diff --git a/apps/api/src/tutorials.ts b/apps/api/src/tutorials.ts
new file mode 100644
index 00000000..f86f3a5e
--- /dev/null
+++ b/apps/api/src/tutorials.ts
@@ -0,0 +1,182 @@
+import prisma from '@briefer/database'
+import {
+  OnboardingTutorialStep,
+  StepStates,
+  TutorialState,
+} from '@briefer/types'
+import { logger } from './logger.js'
+
+const ONBOARDING_STEP_ORDER: OnboardingTutorialStep[] = [
+  'connectDataSource',
+  'runQuery',
+  'runPython',
+  'createVisualization',
+  'publishDashboard',
+  'inviteTeamMembers',
+]
+
+export const stepStatesFromStep = (
+  stepIds: OnboardingTutorialStep[],
+  currentStep: OnboardingTutorialStep,
+  isComplete: boolean
+): StepStates => {
+  const currentStepIndex = stepIds.indexOf(currentStep)
+
+  return stepIds.reduce<StepStates>((acc, stepId, index) => {
+    if (isComplete) {
+      return { ...acc, [stepId]: 'completed' }
+    }
+
+    if (index < currentStepIndex) {
+      return { ...acc, [stepId]: 'completed' }
+    } else if (index === currentStepIndex) {
+      return { ...acc, [stepId]: 'current' }
+    } else {
+      return { ...acc, [stepId]: 'upcoming' }
+    }
+  }, {} as StepStates)
+}
+
+export const getTutorialState = async (
+  workspaceId: string,
+  _tutorialType: 'onboarding'
+): Promise<TutorialState | null> => {
+  const tutorial = await prisma().onboardingTutorial.findUnique({
+    where: {
+      workspaceId,
+    },
+  })
+
+  if (!tutorial) {
+    return null
+  }
+
+  const stepStates = stepStatesFromStep(
+    ONBOARDING_STEP_ORDER,
+    tutorial.currentStep,
+    tutorial.isComplete
+  )
+
+  return {
+    id: tutorial.id,
+    isCompleted: tutorial.isComplete,
+    isDismissed: tutorial.isDismissed,
+    stepStates,
+  }
+}
+
+export const advanceTutorial = async (
+  workspaceId: string,
+  tutorialType: 'onboarding',
+  // TODO don't allow null here - this is just for testing
+  ifCurrentStep: OnboardingTutorialStep | null
+): Promise<TutorialState | null> => {
+  const tutorial = await prisma().onboardingTutorial.findUnique({
+    where: {
+      workspaceId,
+    },
+  })
+
+  if (!tutorial) {
+    logger().error(
+      { workspaceId, tutorialType },
+      'Trying to advance tutorial that does not exist'
+    )
+    return null
+  }
+
+  if (
+    ifCurrentStep &&
+    (tutorial.isComplete || tutorial.currentStep !== ifCurrentStep)
+  ) {
+    return {
+      id: tutorial.id,
+      isCompleted: tutorial.isComplete,
+      isDismissed: tutorial.isDismissed,
+      stepStates: stepStatesFromStep(
+        ONBOARDING_STEP_ORDER,
+        tutorial.currentStep,
+        tutorial.isComplete
+      ),
+    }
+  }
+
+  const currentIndex = ONBOARDING_STEP_ORDER.indexOf(tutorial.currentStep)
+  const nextStepIndex = currentIndex + 1
+  const nextStep = ONBOARDING_STEP_ORDER[nextStepIndex]
+
+  if (nextStepIndex === ONBOARDING_STEP_ORDER.length) {
+    await prisma().onboardingTutorial.update({
+      where: {
+        workspaceId,
+      },
+      data: {
+        isComplete: true,
+      },
+    })
+
+    return {
+      id: tutorial.id,
+      isCompleted: true,
+      isDismissed: tutorial.isDismissed,
+      stepStates: stepStatesFromStep(
+        ONBOARDING_STEP_ORDER,
+        tutorial.currentStep,
+        true
+      ),
+    }
+  }
+
+  if (!nextStep) {
+    logger().error(
+      { workspaceId, tutorialType },
+      'Trying to advance tutorial to a step that does not exist'
+    )
+    return null
+  }
+
+  await prisma().onboardingTutorial.update({
+    where: {
+      workspaceId,
+    },
+    data: {
+      currentStep: nextStep,
+    },
+  })
+
+  return {
+    id: tutorial.id,
+    isCompleted: tutorial.isComplete,
+    isDismissed: tutorial.isDismissed,
+    stepStates: stepStatesFromStep(
+      ONBOARDING_STEP_ORDER,
+      nextStep,
+      tutorial.isComplete
+    ),
+  }
+}
+
+export const dismissTutorial = async (
+  workspaceId: string,
+  _tutorialType: 'onboarding'
+): Promise<TutorialState | null> => {
+  const tutorial = await prisma().onboardingTutorial.update({
+    where: {
+      workspaceId,
+    },
+    data: {
+      isDismissed: true,
+    },
+  })
+
+  return {
+    id: tutorial.id,
+    isCompleted: true,
+    isDismissed: tutorial.isDismissed,
+    stepStates: stepStatesFromStep(
+      ONBOARDING_STEP_ORDER,
+      tutorial.currentStep,
+      tutorial.isComplete
+    ),
+  }
+}
diff --git a/apps/api/src/v1/workspaces/workspace/data-sources/index.ts b/apps/api/src/v1/workspaces/workspace/data-sources/index.ts
index 2bf4a94e..dbb056ea 100644
--- a/apps/api/src/v1/workspaces/workspace/data-sources/index.ts
+++ b/apps/api/src/v1/workspaces/workspace/data-sources/index.ts
@@ -24,6 +24,8 @@ import { fetchDataSourceStructure } from '../../../../datasources/structure.js'
 import { canUpdateWorkspace } from '../../../../auth/token.js'
 import { captureDatasourceCreated } from '../../../../events/posthog.js'
 import { IOServer } from '../../../../websocket/index.js'
+import { advanceTutorial } from '../../../../tutorials.js'
+import { broadcastTutorialStepStates } from '../../../../websocket/workspace/tutorial.js'
 
 const dataSourcePayload = z.union([
   z.object({
@@ -393,6 +395,9 @@ const dataSourcesRouter = (socketServer: IOServer) => {
       })
 
       res.status(201).json(datasource)
+
+      await advanceTutorial(workspaceId, 'onboarding', 'connectDataSource')
+      broadcastTutorialStepStates(socketServer, workspaceId, 'onboarding')
     } catch (err) {
       req.log.error(
         {
diff --git a/apps/api/src/v1/workspaces/workspace/documents/document/publish.ts b/apps/api/src/v1/workspaces/workspace/documents/document/publish.ts
index 1feedbe6..d608fb70 100644
--- a/apps/api/src/v1/workspaces/workspace/documents/document/publish.ts
+++ b/apps/api/src/v1/workspaces/workspace/documents/document/publish.ts
@@ -9,6 +9,8 @@ import { DocumentPersistor } from '../../../../../yjs/v2/persistors.js'
 import { getYDocWithoutHistory } from '../../../../../yjs/v2/documents.js'
 import { getDocId, getYDocForUpdate } from '../../../../../yjs/v2/index.js'
 import { broadcastDocument } from '../../../../../websocket/workspace/documents.js'
+import { advanceTutorial } from '../../../../../tutorials.js'
+import { broadcastTutorialStepStates } from '../../../../../websocket/workspace/tutorial.js'
 
 export default function publishRouter(socketServer: IOServer) {
   const publishRouter = Router({ mergeParams: true })
@@ -22,6 +24,7 @@ export default function publishRouter(socketServer: IOServer) {
       return
     }
 
+    let hasDashboard = false
     try {
       await prisma().$transaction(
         async (tx) => {
@@ -41,13 +44,14 @@ export default function publishRouter(socketServer: IOServer) {
             doc.id,
             doc.workspaceId,
             async (yDoc) => {
+              hasDashboard = yDoc.dashboard.size > 0
               await tx.yjsAppDocument.create({
                 data: {
                   documentId,
                   state: Buffer.from(
                     Y.encodeStateAsUpdate(getYDocWithoutHistory(yDoc))
                   ),
-                  hasDashboard: yDoc.dashboard.size > 0,
+                  hasDashboard,
                 },
               })
               setPristine(yDoc.ydoc)
@@ -65,6 +69,9 @@ export default function publishRouter(socketServer: IOServer) {
       await broadcastDocument(socketServer, workspaceId, documentId)
 
       res.sendStatus(204)
+
+      await advanceTutorial(workspaceId, 'onboarding', 'publishDashboard')
+      broadcastTutorialStepStates(socketServer, workspaceId, 'onboarding')
     } catch (err) {
       req.log.error(
         {
diff --git a/apps/api/src/v1/workspaces/workspace/index.ts b/apps/api/src/v1/workspaces/workspace/index.ts
index d23b83e7..0d4f691a 100644
--- a/apps/api/src/v1/workspaces/workspace/index.ts
+++ b/apps/api/src/v1/workspaces/workspace/index.ts
@@ -9,7 +9,6 @@ import { IOServer } from '../../../websocket/index.js'
 import { getParam } from '../../../utils/express.js'
 import { broadcastDocuments } from '../../../websocket/workspace/documents.js'
 import { UserWorkspaceRole, updateWorkspace } from '@briefer/database'
-import onboardingRouter from './onboarding.js'
 import filesRouter from './files.js'
 import componentsRouter from './components.js'
 import { canUpdateWorkspace, hasWorkspaceRoles } from '../../../auth/token.js'
@@ -17,6 +16,7 @@ import { WorkspaceEditFormValues } from '@briefer/types'
 import { encrypt } from '@briefer/database'
 import { config } from '../../../config/index.js'
 import { isWorkspaceNameValid } from '../../../utils/validation.js'
+import tutorialsRouter from './tutorials.js'
 
 const isAdmin = hasWorkspaceRoles([UserWorkspaceRole.admin])
 
@@ -84,10 +84,10 @@ export default function workspaceRouter(socketServer: IOServer) {
     res.status(200).json(updatedWorkspace)
   })
 
-  router.use('/onboarding', onboardingRouter)
+  router.use('/tutorials', tutorialsRouter(socketServer))
   router.use('/data-sources', dataSourcesRouter(socketServer))
   router.use('/documents', documentsRouter(socketServer))
-  router.use('/users', usersRouter)
+  router.use('/users', usersRouter(socketServer))
   router.use('/favorites', favoritesRouter)
   router.use(
     '/environment-variables',
diff --git a/apps/api/src/v1/workspaces/workspace/onboarding.ts b/apps/api/src/v1/workspaces/workspace/onboarding.ts
deleted file mode 100644
index 61ba6bd1..00000000
--- a/apps/api/src/v1/workspaces/workspace/onboarding.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import { Router } from 'express'
-import { getParam } from '../../../utils/express.js'
-import z from 'zod'
-import { OnboardingStep } from '@briefer/types'
-import { updateOnboardingStep } from '@briefer/database'
-
-const onboardingRouter = Router({ mergeParams: true })
-
-const onboardingPayload = z.object({
-  onboardingStep: OnboardingStep,
-})
-
-onboardingRouter.put('/', async (req, res) => {
-  const workspaceId = getParam(req, 'workspaceId')
-  const payload = onboardingPayload.safeParse(req.body)
-  if (!payload.success) {
-    res.status(400).end()
-    return
-  }
-
-  const workspace = updateOnboardingStep(
-    workspaceId,
-    payload.data.onboardingStep
-  )
-
-  res.json(workspace)
-})
-
-export default onboardingRouter
diff --git a/apps/api/src/v1/workspaces/workspace/tutorials.ts b/apps/api/src/v1/workspaces/workspace/tutorials.ts
new file mode 100644
index 00000000..05f19eaa
--- /dev/null
+++ b/apps/api/src/v1/workspaces/workspace/tutorials.ts
@@ -0,0 +1,118 @@
+import { Router } from 'express'
+import { IOServer } from '../../../websocket'
+import { getParam } from '../../../utils/express.js'
+import {
+  advanceTutorial,
+  dismissTutorial,
+  getTutorialState,
+} from '../../../tutorials.js'
+import { broadcastTutorialStepStates } from '../../../websocket/workspace/tutorial.js'
+import { logger } from '../../../logger.js'
+import prisma from '@briefer/database'
+
+export default function tutorialsRouter(socketServer: IOServer) {
+  const router = Router({ mergeParams: true })
+
+  router.get('/:tutorialType', async (req, res) => {
+    const workspaceId = getParam(req, 'workspaceId')
+    const tutorialType = getParam(req, 'tutorialType')
+
+    if (tutorialType !== 'onboarding') {
+      res.sendStatus(400)
+      return
+    }
+
+    try {
+      const tutorialState = await getTutorialState(workspaceId, tutorialType)
+
+      if (!tutorialState) {
+        res.status(404).end()
+        return
+      }
+
+      res.json(tutorialState)
+    } catch (err) {
+      logger().error(
+        { err, workspaceId, tutorialType },
+        'Failed to get tutorial state'
+      )
+      res.status(500).end()
+    }
+  })
+
+  router.post('/:tutorialType', async (req, res) => {
+    const workspaceId = getParam(req, 'workspaceId')
+    const tutorialType = getParam(req, 'tutorialType')
+
+    if (tutorialType !== 'onboarding') {
+      res.sendStatus(400)
+      return
+    }
+
+    try {
+      const tutorialState = await advanceTutorial(
+        workspaceId,
+        tutorialType,
+        null
+      )
+
+      if (!tutorialState) {
+        res.status(404).end()
+        return
+      }
+
+      res.json(tutorialState)
+      broadcastTutorialStepStates(socketServer, workspaceId, tutorialType)
+    } catch (err) {
+      logger().error(
+        { err, workspaceId, tutorialType },
+        'Failed to dismiss tutorial'
+      )
+      res.status(500).end()
+    }
+  })
+
+  router.post('/:tutorialType/dismiss', async (req, res) => {
+    const workspaceId = getParam(req, 'workspaceId')
+    const tutorialType = getParam(req, 'tutorialType')
+
+    if (tutorialType !== 'onboarding') {
+      res.sendStatus(400)
+      return
+    }
+
+    const tutorial = await prisma().onboardingTutorial.findUnique({
+      where: {
+        workspaceId,
+      },
+    })
+
+    if (!tutorial) {
+      return res.sendStatus(404)
+    }
+
+    if (!tutorial.isComplete) {
+      return res.sendStatus(400)
+    }
+
+    try {
+      const tutorialState = await dismissTutorial(workspaceId, tutorialType)
+
+      if (!tutorialState) {
+        res.status(404).end()
+        return
+      }
+
+      res.json(tutorialState)
+      broadcastTutorialStepStates(socketServer, workspaceId, tutorialType)
+    } catch (err) {
+      logger().error(
+        { err, workspaceId, tutorialType },
+        'Failed to dismiss tutorial'
+      )
+      res.status(500).end()
+    }
+  })
+
+  return router
+}
diff --git a/apps/api/src/v1/workspaces/workspace/users/index.ts b/apps/api/src/v1/workspaces/workspace/users/index.ts
index 1c9d7d07..3bd309f1 100644
--- a/apps/api/src/v1/workspaces/workspace/users/index.ts
+++ b/apps/api/src/v1/workspaces/workspace/users/index.ts
@@ -15,8 +15,9 @@ import { generatePassword, hashPassword } from '../../../../password.js'
 import { hasWorkspaceRoles } from '../../../../auth/token.js'
 import { isUserNameValid } from '../../../../utils/validation.js'
 import * as posthog from '../../../../events/posthog.js'
-
-const usersRouter = Router({ mergeParams: true })
+import { advanceTutorial } from '../../../../tutorials.js'
+import { broadcastTutorialStepStates } from '../../../../websocket/workspace/tutorial.js'
+import { IOServer } from '../../../../websocket/index.js'
 
 const userSchema = z.object({
   name: z.string(),
@@ -28,94 +29,103 @@ const userSchema = z.object({
   ]),
 })
 
-usersRouter.get('/', async (req, res) => {
-  const workspaceId = getParam(req, 'workspaceId')
-  res.json(await listWorkspaceUsers(workspaceId))
-})
+const usersRouter = (socketServer: IOServer) => {
+  const router = Router({ mergeParams: true })
+
+  router.get('/', async (req, res) => {
+    const workspaceId = getParam(req, 'workspaceId')
+    res.json(await listWorkspaceUsers(workspaceId))
+  })
+
+  const isAdmin = hasWorkspaceRoles([UserWorkspaceRole.admin])
+
+  router.post('/', isAdmin, async (req, res) => {
+    const workspaceId = getParam(req, 'workspaceId')
+    try {
+      const result = userSchema.safeParse(req.body)
+      if (!result.success) {
+        res.status(400).end()
+        return
+      }
+
+      const email = result.data.email.trim()
+
+      if (!isUserNameValid(result.data.name)) {
+        res.status(400).end()
+        return
+      }
+
+      const workspace = await getWorkspaceById(workspaceId)
+      if (!workspace) {
+        res.status(404).end()
+        return
+      }
+
+      const password = generatePassword(24)
+      let invitee = await getUserByEmail(email)
+      if (!invitee) {
+        const passwordDigest = await hashPassword(password)
+        invitee = await createUser(email, result.data.name, passwordDigest)
+      }
+
+      await addUserToWorkspace(invitee.id, workspaceId, result.data.role)
+      posthog.captureUserCreated(invitee, workspace.id)
+
+      res.json({
+        ...invitee,
+        password,
+      })
+
+      await advanceTutorial(workspaceId, 'onboarding', 'inviteTeamMembers')
+      broadcastTutorialStepStates(socketServer, workspaceId, 'onboarding')
+    } catch (err) {
+      req.log.error({ err, workspaceId }, 'Error creating user')
+      res.sendStatus(500)
+    }
+  })
 
-const isAdmin = hasWorkspaceRoles([UserWorkspaceRole.admin])
+  async function belongsToWorkspace(
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ) {
+    const workspaceId = getParam(req, 'workspaceId')
+    const userId = getParam(req, 'userId')
 
-usersRouter.post('/', isAdmin, async (req, res) => {
-  const workspaceId = getParam(req, 'workspaceId')
-  try {
-    const result = userSchema.safeParse(req.body)
-    if (!result.success) {
+    if (!validate(userId) || !validate(workspaceId)) {
       res.status(400).end()
       return
     }
 
-    const email = result.data.email.trim()
-
-    if (!isUserNameValid(result.data.name)) {
-      res.status(400).end()
+    const uw = req.session.userWorkspaces[workspaceId]
+    if (!uw) {
+      res.status(403).end()
       return
     }
 
-    const workspace = await getWorkspaceById(workspaceId)
-    if (!workspace) {
-      res.status(404).end()
+    next()
+  }
+
+  function isAdminOrSelf(req: Request, res: Response, next: NextFunction) {
+    const workspaceId = getParam(req, 'workspaceId')
+    const role = req.session.userWorkspaces[workspaceId]?.role
+    if (role === 'admin') {
+      next()
       return
     }
 
-    const password = generatePassword(24)
-    let invitee = await getUserByEmail(email)
-    if (!invitee) {
-      const passwordDigest = await hashPassword(password)
-      invitee = await createUser(email, result.data.name, passwordDigest)
+    const userId = getParam(req, 'userId')
+    if (userId === req.session.user.id) {
+      next()
+      return
     }
 
-    await addUserToWorkspace(invitee.id, workspaceId, result.data.role)
-    posthog.captureUserCreated(invitee, workspace.id)
-
-    res.json({
-      ...invitee,
-      password,
-    })
-  } catch (err) {
-    req.log.error({ err, workspaceId }, 'Error creating user')
-    res.sendStatus(500)
-  }
-})
-
-async function belongsToWorkspace(
-  req: Request,
-  res: Response,
-  next: NextFunction
-) {
-  const workspaceId = getParam(req, 'workspaceId')
-  const userId = getParam(req, 'userId')
-
-  if (!validate(userId) || !validate(workspaceId)) {
-    res.status(400).end()
-    return
-  }
-
-  const uw = req.session.userWorkspaces[workspaceId]
-  if (!uw) {
     res.status(403).end()
-    return
   }
 
-  next()
-}
+  router.use('/:userId', isAdminOrSelf, belongsToWorkspace, userRouter)
 
-function isAdminOrSelf(req: Request, res: Response, next: NextFunction) {
-  const workspaceId = getParam(req, 'workspaceId')
-  const role = req.session.userWorkspaces[workspaceId]?.role
-  if (role === 'admin') {
-    next()
-    return
-  }
-
-  const userId = getParam(req, 'userId')
-  if (userId === req.session.user.id) {
-    next()
-    return
-  }
-
-  res.status(403).end()
+  return router
 }
 
-usersRouter.use('/:userId', isAdminOrSelf, belongsToWorkspace, userRouter)
-
 export default usersRouter
diff --git a/apps/api/src/websocket/index.ts b/apps/api/src/websocket/index.ts
index 12be33c3..d18e4696 100644
--- a/apps/api/src/websocket/index.ts
+++ b/apps/api/src/websocket/index.ts
@@ -15,6 +15,7 @@ import {
   Comment,
   DataSourceTable,
   PythonSuggestionsResult,
+  TutorialState,
 } from '@briefer/types'
 import { v4 as uuidv4 } from 'uuid'
 import { logger } from '../logger.js'
@@ -96,6 +97,11 @@ interface EmitEvents {
     documentId: string
     commentId: string
   }) => void
+  'workspace-tutorial-update': (msg: {
+    workspaceId: string
+    tutorialType: 'onboarding'
+    tutorialState: TutorialState
+  }) => void
 }
 
 export interface Socket extends BaseSocket<any, EmitEvents> {
diff --git a/apps/api/src/websocket/workspace/tutorial.ts b/apps/api/src/websocket/workspace/tutorial.ts
new file mode 100644
index 00000000..073fefbc
--- /dev/null
+++ b/apps/api/src/websocket/workspace/tutorial.ts
@@ -0,0 +1,20 @@
+import { getTutorialState } from '../../tutorials.js'
+import { IOServer } from '../index.js'
+
+export async function broadcastTutorialStepStates(
+  socket: IOServer,
+  workspaceId: string,
+  tutorialType: 'onboarding'
+) {
+  const tutorialState = await getTutorialState(workspaceId, tutorialType)
+
+  if (!tutorialState) {
+    return
+  }
+
+  socket.to(workspaceId).emit('workspace-tutorial-update', {
+    workspaceId,
+    tutorialType,
+    tutorialState,
+  })
+}
diff --git a/apps/api/src/workspace/index.ts b/apps/api/src/workspace/index.ts
index 4e2f5bc5..92a449a4 100644
--- a/apps/api/src/workspace/index.ts
+++ b/apps/api/src/workspace/index.ts
@@ -5,6 +5,7 @@ import {
   UserWorkspaceRole,
   ApiWorkspace,
   createWorkspace as prismaCreateWorkspace,
+  createDocument,
 } from '@briefer/database'
 import { IOServer } from '../websocket/index.js'
 import { WorkspaceCreateInput } from '@briefer/types'
@@ -71,6 +72,14 @@ export class WorkspaceCreator implements IWorkspaceCreator {
         skipDuplicates: true,
       })
 
+      await tx.onboardingTutorial.create({
+        data: {
+          workspaceId: workspace.id,
+          currentStep: 'connectDataSource',
+          isComplete: false,
+        },
+      })
+
       return { workspace, invitedUsers: guestUsers }
     }
 
diff --git a/apps/api/src/yjs/v2/executor/python.ts b/apps/api/src/yjs/v2/executor/python.ts
index 18e93102..3bf95655 100644
--- a/apps/api/src/yjs/v2/executor/python.ts
+++ b/apps/api/src/yjs/v2/executor/python.ts
@@ -13,10 +13,17 @@ import { updateDataframes } from './index.js'
 import { DataFrame } from '@briefer/types'
 import { PythonEvents } from '../../../events/index.js'
 import { WSSharedDocV2 } from '../index.js'
+import { advanceTutorial } from '../../../tutorials.js'
+import { broadcastTutorialStepStates } from '../../../websocket/workspace/tutorial.js'
 
 export type PythonEffects = {
   executePython: typeof executePython
   listDataFrames: typeof listDataFrames
+  advanceTutorial: typeof advanceTutorial
+  broadcastTutorialStepStates: (
+    workspaceId: string,
+    tutorialType: 'onboarding'
+  ) => Promise<void>
 }
 
 export interface IPythonExecutor {
@@ -112,6 +119,13 @@ export class PythonExecutor implements IPythonExecutor {
         'python block executed'
       )
       executionItem.setCompleted(errored ? 'error' : 'success')
+
+      await this.effects.advanceTutorial(
+        this.workspaceId,
+        'onboarding',
+        'runPython'
+      )
+      this.effects.broadcastTutorialStepStates(this.workspaceId, 'onboarding')
     } catch (err) {
       logger().error(
         {
@@ -148,6 +162,17 @@ export class PythonExecutor implements IPythonExecutor {
       {
         executePython,
         listDataFrames,
+        advanceTutorial,
+        broadcastTutorialStepStates: (
+          workspaceId: string,
+          tutorialType: 'onboarding'
+        ) => {
+          return broadcastTutorialStepStates(
+            doc.socketServer,
+            workspaceId,
+            tutorialType
+          )
+        },
       }
     )
   }
diff --git a/apps/api/src/yjs/v2/executor/sql.ts b/apps/api/src/yjs/v2/executor/sql.ts
index a1ff9a58..46fc0b6a 100644
--- a/apps/api/src/yjs/v2/executor/sql.ts
+++ b/apps/api/src/yjs/v2/executor/sql.ts
@@ -14,10 +14,17 @@ import {
   renameDataFrame,
 } from '../../../python/query/index.js'
 import { logger } from '../../../logger.js'
-import { DataFrame, RunQueryResult } from '@briefer/types'
+import {
+  DataFrame,
+  OnboardingTutorialStep,
+  RunQueryResult,
+} from '@briefer/types'
 import { SQLEvents } from '../../../events/index.js'
 import { WSSharedDocV2 } from '../index.js'
 import { updateDataframes } from './index.js'
+import { advanceTutorial } from '../../../tutorials.js'
+import { IOServer } from '../../../websocket/index.js'
+import { broadcastTutorialStepStates } from '../../../websocket/workspace/tutorial.js'
 
 export type SQLEffects = {
   makeSQLQuery: typeof makeSQLQuery
@@ -25,6 +32,11 @@ export type SQLEffects = {
   renameDataFrame: typeof renameDataFrame
   listDataFrames: typeof listDataFrames
   documentHasRunSQLSelectionEnabled: (id: string) => Promise<boolean>
+  advanceTutorial: typeof advanceTutorial
+  broadcastTutorialStepStates: (
+    workspaceId: string,
+    tutorialType: 'onboarding'
+  ) => Promise<void>
 }
 
 export interface ISQLExecutor {
@@ -239,6 +251,13 @@ export class SQLExecutor implements ISQLExecutor {
         },
         'sql block executed'
       )
+
+      await this.effects.advanceTutorial(
+        this.workspaceId,
+        'onboarding',
+        'runQuery'
+      )
+      this.effects.broadcastTutorialStepStates(this.workspaceId, 'onboarding')
     } catch (err) {
       logger().error(
         {
@@ -347,6 +366,17 @@ export class SQLExecutor implements ISQLExecutor {
         listDataSources,
         renameDataFrame,
         listDataFrames,
+        advanceTutorial,
+        broadcastTutorialStepStates: (
+          workspaceId: string,
+          tutorialType: 'onboarding'
+        ) => {
+          return broadcastTutorialStepStates(
+            doc.socketServer,
+            workspaceId,
+            tutorialType
+          )
+        },
         documentHasRunSQLSelectionEnabled: (id: string) =>
           prisma()
             .document.findFirst({
diff --git a/apps/api/src/yjs/v2/executor/visualization.ts b/apps/api/src/yjs/v2/executor/visualization.ts
index f6b08f9d..b1f1487d 100644
--- a/apps/api/src/yjs/v2/executor/visualization.ts
+++ b/apps/api/src/yjs/v2/executor/visualization.ts
@@ -15,9 +15,16 @@ import { createVisualization } from '../../../python/visualizations.js'
 import { z } from 'zod'
 import { VisEvents } from '../../../events/index.js'
 import { WSSharedDocV2 } from '../index.js'
+import { advanceTutorial } from '../../../tutorials.js'
+import { broadcastTutorialStepStates } from '../../../websocket/workspace/tutorial.js'
 
 export type VisualizationEffects = {
   createVisualization: typeof createVisualization
+  advanceTutorial: typeof advanceTutorial
+  broadcastTutorialStepStates: (
+    workspaceId: string,
+    tutorialType: 'onboarding'
+  ) => Promise<void>
 }
 
 export interface IVisualizationExecutor {
@@ -186,6 +193,13 @@ export class VisualizationExecutor implements IVisualizationExecutor {
         },
         'visualization block run completed'
       )
+
+      await this.effects.advanceTutorial(
+        this.workspaceId,
+        'onboarding',
+        'createVisualization'
+      )
+      this.effects.broadcastTutorialStepStates(this.workspaceId, 'onboarding')
     } catch (err) {
       logger().error(
         {
@@ -210,7 +224,20 @@ export class VisualizationExecutor implements IVisualizationExecutor {
       doc.workspaceId,
       doc.documentId,
       doc.dataframes,
-      { createVisualization }
+      {
+        createVisualization,
+        advanceTutorial,
+        broadcastTutorialStepStates: (
+          workspaceId: string,
+          tutorialType: 'onboarding'
+        ) => {
+          return broadcastTutorialStepStates(
+            doc.socketServer,
+            workspaceId,
+            tutorialType
+          )
+        },
+      }
     )
   }
 }
diff --git a/apps/api/src/yjs/v2/index.ts b/apps/api/src/yjs/v2/index.ts
index 33f8fb4c..8e955fdf 100644
--- a/apps/api/src/yjs/v2/index.ts
+++ b/apps/api/src/yjs/v2/index.ts
@@ -408,7 +408,8 @@ export class WSSharedDocV2 {
   public updating: number = 0
   public clock: number = 0
 
-  private socketServer: IOServer
+  public socketServer: IOServer
+
   private title: string = ''
   private executor: Executor
   private aiExecutor: AIExecutor
diff --git a/apps/web/src/components/DashboarNotebookGroupButton.tsx b/apps/web/src/components/DashboarNotebookGroupButton.tsx
index bb55bf07..10b82238 100644
--- a/apps/web/src/components/DashboarNotebookGroupButton.tsx
+++ b/apps/web/src/components/DashboarNotebookGroupButton.tsx
@@ -44,6 +44,7 @@ function DashboardNotebookGroupButton(props: Props) {
         active={isDashboardButtonDisabled}
       >
         <button
+          id="dashboard-view-button"
           className={clsx(
             'flex gap-x-1.5 items-center rounded-r-sm px-3 py-1 text-sm disabled:cursor-not-allowed disabled:opacity-50 ring-1 ring-inset ring-gray-300 hover:bg-ceramic-50',
             props.current === 'dashboard'
diff --git a/apps/web/src/components/Dashboard/index.tsx b/apps/web/src/components/Dashboard/index.tsx
index fab31c50..ac3537b4 100644
--- a/apps/web/src/components/Dashboard/index.tsx
+++ b/apps/web/src/components/Dashboard/index.tsx
@@ -187,7 +187,8 @@ export default function Dashboard(props: Props) {
               tooltipClassname="w-40"
             >
               <button
-                className="flex items-center rounded-sm px-3 py-1 text-sm bg-primary-200 hover:bg-primary-300 disabled:cursor-not-allowed disabled:opacity-50 gap-x-1.5 group"
+                id="dashboard-publish-button"
+                className="flex items-center rounded-sm px-3 py-1 text-sm bg-primary-200 hover:bg-primary-300 border border-transparent disabled:border-gray-200 disabled:bg-gray-100 disabled:cursor-not-allowed gap-x-1.5 group relative disabled:text-gray-500"
                 onClick={onPublish}
                 disabled={props.publishing}
               >
diff --git a/apps/web/src/components/DataSourceIcons.tsx b/apps/web/src/components/DataSourceIcons.tsx
deleted file mode 100644
index 9b191207..00000000
--- a/apps/web/src/components/DataSourceIcons.tsx
+++ /dev/null
@@ -1,79 +0,0 @@
-import Link from 'next/link'
-
-type DataSourceBlockProps = {
-  name: string
-  icon: string
-  href: string
-}
-
-const DataSourceBlock = ({ name, icon, href }: DataSourceBlockProps) => {
-  return (
-    <Link
-      href={href}
-      className="h-32 w-32 p-2 border border-gray-200 rounded-md flex flex-col items-center justify-around bg-gray-50 hover:bg-ceramic-50 hover:border-gray-300"
-    >
-      <img src={icon} alt="" className="h-12 w-12" />
-      <span className="text-sm">{name}</span>
-    </Link>
-  )
-}
-
-export const DataSourceIcons = ({
-  workspaceId,
-  onCSV,
-}: {
-  workspaceId: string
-  onCSV: () => void
-}) => {
-  return (
-    <div className="w-full flex gap-x-4 gap-y-4 flex-wrap">
-      <DataSourceBlock
-        icon="/icons/sqlserver.png"
-        name="SQLServer"
-        href={`/workspaces/${workspaceId}/data-sources/new/sqlserver`}
-      />
-      <DataSourceBlock
-        icon="/icons/athena.png"
-        name="Athena"
-        href={`/workspaces/${workspaceId}/data-sources/new/athena`}
-      />
-      <DataSourceBlock
-        icon="/icons/bigquery.png"
-        name="BigQuery"
-        href={`/workspaces/${workspaceId}/data-sources/new/bigquery`}
-      />
-      <DataSourceBlock
-        icon="/icons/postgres.png"
-        name="PostgreSQL"
-        href={`/workspaces/${workspaceId}/data-sources/new/postgresql`}
-      />
-      <DataSourceBlock
-        icon="/icons/redshift.png"
-        name="Redshift"
-        href={`/workspaces/${workspaceId}/data-sources/new/redshift`}
-      />
-      <DataSourceBlock
-        icon="/icons/oracle.png"
-        name="Oracle"
-        href={`/workspaces/${workspaceId}/data-sources/new/oracle`}
-      />
-      <DataSourceBlock
-        icon="/icons/snowflake.png"
-        name="Snowflake"
-        href={`/workspaces/${workspaceId}/data-sources/new/snowflake`}
-      />
-      <DataSourceBlock
-        icon="/icons/databrickssql.png"
-        name="Databricks SQL"
-        href={`/workspaces/${workspaceId}/data-sources/new/databrickssql`}
-      />
-      <button
-        onClick={onCSV}
-        className="h-32 w-32 py-3 px-6 border border-gray-200 rounded-md flex flex-col items-center justify-around bg-gray-50 hover:bg-ceramic-50 hover:border-gray-300"
-      >
-        <img src="/icons/csv.png" alt="" className="h-12 w-12" />
-        <span className="text-sm">Files</span>
-      </button>
-    </div>
-  )
-}
diff --git a/apps/web/src/components/Layout.tsx b/apps/web/src/components/Layout.tsx
index cb382c5a..514f1f25 100644
--- a/apps/web/src/components/Layout.tsx
+++ b/apps/web/src/components/Layout.tsx
@@ -64,7 +64,7 @@ type ConfigItem = {
 
 const configs = (workspaceId: string): ConfigItem[] => [
   {
-    id: 'environments',
+    id: 'environments-sidebar-item',
     name: 'Environments',
     href: `/workspaces/${workspaceId}/environments`,
     hidden: true,
@@ -72,35 +72,35 @@ const configs = (workspaceId: string): ConfigItem[] => [
     allowedRoles: new Set<UserWorkspaceRole>(['admin']),
   },
   {
-    id: 'data-sources',
+    id: 'data-sources-sidebar-item',
     name: 'Data sources',
     href: `/workspaces/${workspaceId}/data-sources`,
     icon: CircleStackIcon,
     allowedRoles: new Set<UserWorkspaceRole>(['admin', 'editor']),
   },
   {
-    id: 'users',
+    id: 'users-sidebar-item',
     name: 'Users',
     href: `/workspaces/${workspaceId}/users`,
     icon: UsersIcon,
     allowedRoles: new Set<UserWorkspaceRole>(['admin', 'editor', 'viewer']),
   },
   {
-    id: 'integrations',
+    id: 'integrations-sidebar-item',
     name: 'Integrations',
     href: `/workspaces/${workspaceId}/integrations`,
     icon: PuzzlePieceIcon,
     allowedRoles: new Set<UserWorkspaceRole>(['admin', 'editor']),
   },
   {
-    id: 'settings',
+    id: 'settings-sidebar-item',
     name: 'Settings',
     href: `/workspaces/${workspaceId}/settings`,
     icon: AdjustmentsHorizontalIcon,
     allowedRoles: new Set<UserWorkspaceRole>(['admin']),
   },
   {
-    id: 'thrash',
+    id: 'thrash-sidebar-item',
     name: 'Trash',
     href: `/workspaces/${workspaceId}/trash`,
     icon: TrashIcon,
@@ -389,6 +389,7 @@ export default function Layout({
 
                   {user.roles[workspaceId] !== 'viewer' && (
                     <button
+                      id="create-workspace-doc"
                       onClick={onCreateDocumentHandler}
                       className="p-1 hover:text-ceramic-500 hover:bg-ceramic-100/70 rounded-md hover:cursor-pointer"
                     >
@@ -430,12 +431,15 @@ export default function Layout({
               {configs(workspaceId)
                 .filter(showConfigItem)
                 .map((item) => (
-                  <li key={item.name}>
+                  <li id={item.id} key={item.name}>
                     <ConfigurationsMenuLink
                       href={item.href}
                       text={item.name}
                       icon={item.icon}
-                      blink={item.id === 'data-sources' && !hasUserDataSource}
+                      blink={
+                        item.id === 'data-sources-sidebar-item' &&
+                        !hasUserDataSource
+                      }
                     />
                   </li>
                 ))}
diff --git a/apps/web/src/components/TourHighlight.tsx b/apps/web/src/components/TourHighlight.tsx
new file mode 100644
index 00000000..4ac5b249
--- /dev/null
+++ b/apps/web/src/components/TourHighlight.tsx
@@ -0,0 +1,82 @@
+import React, { useEffect, useState } from 'react'
+import ReactDOM from 'react-dom'
+import { useTourHighlight } from './TourHighlightProvider'
+
+interface Position {
+  top: number
+  left: number
+  width: number
+  height: number
+}
+
+const TourHighlight: React.FC = () => {
+  const [{ selector, isTourActive }, { setTourActive }] = useTourHighlight()
+  const [position, setPosition] = useState<Position | null>(null)
+
+  useEffect(() => {
+    if (selector) {
+      const element = document.querySelector(selector) as HTMLElement | null
+      if (element) {
+        const rect = element.getBoundingClientRect()
+        setPosition({
+          top: rect.top + window.scrollY,
+          left: rect.left + window.scrollX,
+          width: rect.width,
+          height: rect.height,
+        })
+      } else {
+        console.warn(`No element found for selector: "${selector}"`)
+        setPosition(null)
+      }
+    }
+  }, [selector, isTourActive])
+
+  const posStyle = position
+    ? {
+        top: position.top - 2,
+        left: position.left - 2,
+        width: position.width + 4,
+        height: position.height + 4,
+      }
+    : {}
+
+  useEffect(() => {
+    // dismiss tour on any clicks or key presses or after 5 seconds
+    const dismiss = () => {
+      setTourActive(false)
+    }
+
+    document.addEventListener('click', dismiss)
+    document.addEventListener('keydown', dismiss)
+
+    const timeout = setTimeout(() => {
+      setTourActive(false)
+    }, 5000)
+
+    return () => {
+      document.removeEventListener('click', dismiss)
+      document.removeEventListener('keydown', dismiss)
+      clearTimeout(timeout)
+    }
+  })
+
+  return ReactDOM.createPortal(
+    <div
+      id="tour-highlight"
+      style={{
+        position: 'absolute',
+        boxShadow: '0 0 0 9999px rgba(0, 0, 0, 0.5)',
+        border: '1px solid #76ad03',
+        borderRadius: '4px',
+        zIndex: 9999,
+        pointerEvents: 'none',
+        opacity: isTourActive && position ? 1 : 0,
+        transition: 'opacity 0.3s',
+        ...posStyle,
+      }}
+    ></div>,
+    document.body
+  )
+}
+
+export default TourHighlight
diff --git a/apps/web/src/components/TourHighlightProvider.tsx b/apps/web/src/components/TourHighlightProvider.tsx
new file mode 100644
index 00000000..66492fc7
--- /dev/null
+++ b/apps/web/src/components/TourHighlightProvider.tsx
@@ -0,0 +1,60 @@
+import React, { createContext, useContext, useState, ReactNode } from 'react'
+import TourHighlight from './TourHighlight'
+
+interface TourHighlightContextType {
+  selector: string | null
+  setSelector: (selector: string | null) => void
+  isTourActive: boolean
+  setTourActive: (active: boolean) => void
+}
+
+const TourHighlightContext = createContext<
+  TourHighlightContextType | undefined
+>(undefined)
+
+export const TourHighlightProvider: React.FC<{ children: ReactNode }> = ({
+  children,
+}) => {
+  const [selector, setSelector] = useState<string | null>(null)
+  const [isTourActive, setTourActive] = useState(false)
+
+  return (
+    <TourHighlightContext.Provider
+      value={{ selector, setSelector, isTourActive, setTourActive }}
+    >
+      <TourHighlight />
+      {children}
+    </TourHighlightContext.Provider>
+  )
+}
+
+type UseTourHighlightState = {
+  selector: string | null
+  isTourActive: boolean
+}
+
+type UseTourHighlightAPI = {
+  setSelector: (selector: string | null) => void
+  setTourActive: (active: boolean) => void
+}
+
+export const useTourHighlight: () => [
+  UseTourHighlightState,
+  UseTourHighlightAPI
+] = () => {
+  const context = useContext(TourHighlightContext)
+  if (!context) {
+    console.warn('useTourHighlight must be used within a TourHighlightProvider')
+    return [
+      { selector: null, isTourActive: false },
+      { setSelector: () => {}, setTourActive: () => {} },
+    ]
+  }
+  return [
+    { selector: context.selector, isTourActive: context.isTourActive },
+    {
+      setSelector: context.setSelector,
+      setTourActive: context.setTourActive,
+    },
+  ]
+}
diff --git a/apps/web/src/components/Tutorial.tsx b/apps/web/src/components/Tutorial.tsx
new file mode 100644
index 00000000..1dc323ab
--- /dev/null
+++ b/apps/web/src/components/Tutorial.tsx
@@ -0,0 +1,554 @@
+import useTutorial from '@/hooks/useTutorial'
+import {
+  OnboardingTutorialStep,
+  StepStates,
+  TutorialStepStatus,
+} from '@briefer/types'
+import {
+  ArrowRightIcon,
+  CheckCircleIcon,
+  ChevronDownIcon,
+  ChevronUpIcon,
+  ForwardIcon,
+} from '@heroicons/react/24/solid'
+import clsx from 'clsx'
+import { useRouter } from 'next/router'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import React from 'react'
+import { useTourHighlight } from './TourHighlightProvider'
+import { useStringQuery } from '@/hooks/useQueryArgs'
+
+const defaultStepStates: StepStates = {
+  connectDataSource: 'current',
+  runQuery: 'upcoming',
+  runPython: 'upcoming',
+  createVisualization: 'upcoming',
+  publishDashboard: 'upcoming',
+  inviteTeamMembers: 'upcoming',
+}
+
+// TODO https://regexlicensing.org/ - can we do something else?
+const isDocumentPath = (path: string) => {
+  return /\/documents\/[^\/]+\/(notebook|dashboard)(\/[^\/]*)?$/.test(path)
+}
+
+export const OnboardingTutorial = () => {
+  const router = useRouter()
+  const workspaceId = useStringQuery('workspaceId')
+  const [, { setSelector, setTourActive }] = useTourHighlight()
+
+  const [{ tutorialState }, { advanceTutorial, dismissTutorial }] = useTutorial(
+    workspaceId,
+    'onboarding',
+    defaultStepStates
+  )
+
+  const [expandedStep, setExpandedStep] = React.useState<
+    Map<OnboardingTutorialStep, boolean>
+  >(new Map())
+
+  const toggleExpanded = useCallback((step: OnboardingTutorialStep) => {
+    setExpandedStep((prev) => {
+      const next = new Map(prev)
+      next.set(step, !prev.get(step))
+      return next
+    })
+  }, [])
+
+  const isWithinDocumentPage = useMemo(() => {
+    return isDocumentPath(router.pathname)
+  }, [router.pathname])
+
+  if (!workspaceId || tutorialState.isDismissed) {
+    return null
+  }
+
+  const completeButton = (
+    <button
+      disabled={!tutorialState.isCompleted}
+      onClick={() => dismissTutorial()}
+      className={
+        'text-sm w-full flex gap-x-1.5 items-center justify-center font-medium py-1.5 px-2 rounded-sm disabled:opacity-50 bg-primary-200 hover:bg-primary-300 text-primary-800 border border-primary-400 disabled:cursor-not-allowed disabled:bg-gray-300 disabled:text-gray-800 disabled:border-gray-400'
+      }
+    >
+      <CheckCircleIcon className="h-4 w-4" />
+      <span>Finish</span>
+    </button>
+  )
+
+  const dismissButton = (
+    <button
+      className="text-sm w-full flex gap-x-1.5 items-center justify-center font-medium px-2 py-1.5 rounded-sm bg-white hover:bg-gray-50 text-gray-600 border border-gray-200 disabled:cursor-not-allowed disabled:bg-gray-50 disabled:text-gray-400 disabled:border-gray-200"
+      disabled={tutorialState.isCompleted}
+      onClick={() => {
+        advanceTutorial()
+      }}
+    >
+      <ForwardIcon className="h-4 w-4" />
+      <span>Skip step</span>
+    </button>
+  )
+
+  return (
+    <Tutorial
+      name={'Welcome to Briefer'}
+      onAdvanceTutorial={advanceTutorial}
+      totalSteps={Object.values(tutorialState.stepStates).length}
+      completedSteps={
+        Object.values(tutorialState.stepStates).filter((s) => s === 'completed')
+          .length
+      }
+      actionButtons={
+        <>
+          {dismissButton}
+          {completeButton}
+        </>
+      }
+    >
+      <TutorialStep
+        name={'Connect a data source'}
+        description={
+          <>
+            <p>
+              {
+                "You can connect a database in the 'data sources' page at the bottom left corner."
+              }
+            </p>
+            <p>
+              {
+                'When adding a data source, pick your database type, and enter the connection details.'
+              }
+            </p>
+          </>
+        }
+        status={tutorialState.stepStates['connectDataSource']}
+        isExpanded={expandedStep.get('connectDataSource') ?? false}
+        onExpand={() => toggleExpanded('connectDataSource')}
+      >
+        <TutorialStepAction
+          label="Add a data source"
+          onClick={() => {
+            router.push(`/workspaces/${workspaceId}/data-sources/new`)
+          }}
+        />
+        {/* TODO: Deactivated on open-source
+        <TutorialStepAction
+          label="I'll use the demo data source"
+          onClick={() => {}}
+        />
+        */}
+      </TutorialStep>
+
+      <TutorialStep
+        name={'Run a query'}
+        description={
+          <>
+            <p>
+              {
+                "Add a query block to a page, select the data source you've just connected, and write your query."
+              }
+            </p>
+            <p>Then, press the run button to see the results.</p>
+          </>
+        }
+        status={tutorialState.stepStates['runQuery']}
+        isExpanded={expandedStep.get('runQuery') ?? false}
+        onExpand={() => toggleExpanded('runQuery')}
+      >
+        <TutorialStepAction
+          label="Add a query block"
+          onClick={() => {
+            // TODO we need a setTimeout here because otherwise the listener
+            // within the tour highlight provider will trigger before the
+            // element is rendered and will dismiss the tour
+            setTimeout(() => {
+              setTourActive(true)
+              setSelector('#last-plus-button')
+            }, 0)
+          }}
+          hidden={!isWithinDocumentPage}
+        />
+      </TutorialStep>
+
+      <TutorialStep
+        name={'Run some Python code'}
+        description={
+          <>
+            <p>
+              Add a Python block, write some code, and press the run button.
+            </p>
+            {
+              "Tip: you can manipulate query results with Python. Briefer puts every query's result into variable containing a Pandas Data Frame."
+            }
+          </>
+        }
+        status={tutorialState.stepStates['runPython']}
+        isExpanded={expandedStep.get('runPython') ?? false}
+        onExpand={() => toggleExpanded('runPython')}
+      >
+        <TutorialStepAction
+          label="Add a Python block"
+          onClick={() => {
+            // TODO we need a setTimeout here because otherwise the listener
+            // within the tour highlight provider will trigger before the
+            // element is rendered and will dismiss the tour
+            setTimeout(() => {
+              setTourActive(true)
+              setSelector('#last-plus-button')
+            }, 0)
+          }}
+          hidden={!isWithinDocumentPage}
+        />
+      </TutorialStep>
+
+      <TutorialStep
+        name={'Create a visualization'}
+        description={
+          <>
+            <p>
+              Add a visualization block to your page, select the data frame from
+              your query, and choose the visualization type.
+            </p>
+            <p>Then pick what goes on the x and y axis to see a graph.</p>
+          </>
+        }
+        status={tutorialState.stepStates['createVisualization']}
+        isExpanded={expandedStep.get('createVisualization') ?? false}
+        onExpand={() => toggleExpanded('createVisualization')}
+      >
+        <TutorialStepAction
+          label="Add a visualization block"
+          onClick={() => {
+            // TODO we need a setTimeout here because otherwise the listener
+            // within the tour highlight provider will trigger before the
+            // element is rendered and will dismiss the tour
+            setTimeout(() => {
+              setTourActive(true)
+              setSelector('#last-plus-button')
+            }, 0)
+          }}
+        />
+      </TutorialStep>
+
+      <TutorialStep
+        name={'Publish a dashboard'}
+        description={
+          <>
+            <p>
+              {
+                'Switch to the dashboard view using the button at the top right corner.'
+              }
+            </p>
+            <p>
+              {
+                "Then, drag and drop your notebook's blocks to create a dashboard."
+              }
+            </p>
+            <p>
+              {
+                " When you're done, click the 'publish' button to save your dashboard."
+              }
+            </p>
+          </>
+        }
+        status={tutorialState.stepStates['publishDashboard']}
+        isExpanded={expandedStep.get('publishDashboard') ?? false}
+        onExpand={() => toggleExpanded('publishDashboard')}
+      >
+        <TutorialStepAction
+          label="Switch to dashboard view"
+          onClick={() => {
+            // TODO we need a setTimeout here because otherwise the listener
+            // within the tour highlight provider will trigger before the
+            // element is rendered and will dismiss the tour
+            setTimeout(() => {
+              setTourActive(true)
+              setSelector('#dashboard-view-button')
+            }, 0)
+          }}
+        />
+        <TutorialStepAction
+          hidden={!router.pathname.endsWith('/dashboard/edit')}
+          label="Publish the dashboard"
+          onClick={() => {
+            // TODO we need a setTimeout here because otherwise the listener
+            // within the tour highlight provider will trigger before the
+            // element is rendered and will dismiss the tour
+            setTimeout(() => {
+              setTourActive(true)
+              setSelector('#dashboard-publish-button')
+            }, 0)
+          }}
+        />
+      </TutorialStep>
+
+      <TutorialStep
+        name={'Invite team members'}
+        description={
+          <>
+            <p>
+              {
+                "Add users by accessing the users page and clicking the 'add user' button on the top right corner."
+              }
+            </p>
+            <p>
+              {
+                "Every time you add a user, we'll generate a random password for them. Once they log in, they can change it."
+              }
+            </p>
+          </>
+        }
+        status={tutorialState.stepStates['inviteTeamMembers']}
+        isExpanded={expandedStep.get('inviteTeamMembers') ?? false}
+        onExpand={() => toggleExpanded('inviteTeamMembers')}
+      >
+        <TutorialStepAction
+          label="Add a new user"
+          hidden={router.pathname.endsWith('/users/new')}
+          onClick={() => {
+            // TODO we need a setTimeout here because otherwise the listener
+            // within the tour highlight provider will trigger before the
+            // element is rendered and will dismiss the tour
+            setTimeout(() => {
+              setTourActive(true)
+
+              if (router.pathname.endsWith('/users')) {
+                setSelector('#add-user-button')
+              } else {
+                setSelector('#users-sidebar-item')
+              }
+            }, 0)
+          }}
+        />
+        {/* TODO on cloud we must also have an action item for "allowAllFromDomain" */}
+      </TutorialStep>
+    </Tutorial>
+  )
+}
+
+type TutorialProps = {
+  name: string
+  children:
+    | React.ReactElement<TutorialStepProps>
+    | React.ReactElement<TutorialStepProps>[]
+  onAdvanceTutorial: () => void
+  totalSteps: number
+  completedSteps: number
+  actionButtons?: React.ReactNode
+}
+
+export const Tutorial = (props: TutorialProps) => {
+  const router = useRouter()
+  const [isCollapsed, setIsCollapsed] = useState(false)
+
+  const ChevronIcon = isCollapsed ? ChevronUpIcon : ChevronDownIcon
+
+  const isWithinDocumentPage = useMemo(() => {
+    return isDocumentPath(router.pathname)
+  }, [router.pathname])
+
+  return (
+    <div
+      className={clsx(
+        'absolute bottom-0 right-4 bg-white rounded-lg w-80 z-30 border border-gray-200 font-sans overflow-hidden shadow-sm transition-transform duration-300',
+        isWithinDocumentPage ? '-translate-y-14' : '-translate-y-4'
+      )}
+    >
+      <div
+        className={clsx(
+          'bg-gray-50 rounded-t-lg h-12 w-full border-gray-200 p-4 flex items-center justify-between',
+          isCollapsed ? '' : 'border-b'
+        )}
+      >
+        <div className="text-sm flex gap-x-2 items-center">
+          <span className="text-gray-600 font-medium ">Welcome to Briefer</span>
+          <button
+            className="text-gray-400 text-xs font-medium inline-block"
+            onClick={props.onAdvanceTutorial}
+          >
+            ({props.completedSteps}/{props.totalSteps})
+          </button>
+        </div>
+        <button
+          className="text-gray-400 hover:text-gray-800"
+          onClick={() => setIsCollapsed((prev) => !prev)}
+        >
+          <ChevronIcon className="h-3.5 w-3.5" />
+        </button>
+      </div>
+      <div
+        className={clsx(
+          'transition-max-height duration-300',
+          isCollapsed ? 'max-h-0' : 'max-h-96'
+        )}
+      >
+        <div className={clsx('h-72 overflow-auto')}>
+          <div className="flex flex-col gap-y-4 p-4">
+            {React.Children.map(props.children, (child, index) => {
+              return React.cloneElement(child, {
+                isLast: index === React.Children.count(props.children) - 1,
+              })
+            })}
+          </div>
+        </div>
+        <div className="w-full bg-gray-50 p-2 flex items-center justify-center gap-x-2 border-t border-gray-200">
+          {props.actionButtons}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+const TutorialStepStatusIndicator = (props: {
+  status: TutorialStepStatus
+  isLast: boolean
+}) => {
+  const statusBall = useMemo(() => {
+    if (props.status === 'current') {
+      return (
+        <>
+          <div className="absolute size-2.5 rounded-full bg-yellow-300 ring-1 ring-yellow-300 animate-ping" />
+          <div className="size-2.5 rounded-full bg-yellow-300 ring-1 ring-yellow-400" />
+        </>
+      )
+    }
+
+    if (props.status === 'completed') {
+      return <CheckCircleIcon className="h-4 w-4 text-green-700" />
+    }
+
+    return (
+      <div className="size-2.5 rounded-full bg-gray-100 ring-1 ring-gray-300" />
+    )
+  }, [props.status])
+
+  return (
+    <>
+      <div
+        className={clsx(
+          'absolute left-0 top-1 flex w-6 justify-center -bottom-6',
+          props.isLast ? 'hidden' : 'block'
+        )}
+      >
+        <div
+          className={clsx(
+            'w-px',
+            props.status === 'completed' ? 'bg-green-600/40' : 'bg-gray-200'
+          )}
+        ></div>
+      </div>
+
+      <div className="relative flex size-6 flex-none items-center justify-center bg-white">
+        {statusBall}
+      </div>
+    </>
+  )
+}
+
+type TutorialStepActionProps = {
+  label: string
+  hidden?: boolean
+  onClick: () => void
+}
+
+const TutorialStepAction = (props: TutorialStepActionProps) => {
+  if (props.hidden) {
+    return null
+  }
+
+  return (
+    <button
+      className="text-blue-600 text-xs w-full flex gap-x-1 items-center font-medium hover:text-blue-800"
+      onClick={props.onClick}
+    >
+      <ArrowRightIcon className="h-3 w-3" />
+      <span>{props.label}</span>
+    </button>
+  )
+}
+
+type TutorialStepProps = {
+  name: string
+  description: string | React.ReactNode
+  status: TutorialStepStatus
+  isExpanded: boolean
+  onExpand: () => void
+  isLast?: boolean
+  children?:
+    | React.ReactElement<TutorialStepActionProps>
+    | React.ReactElement<TutorialStepActionProps>[]
+}
+
+const TutorialStep = (props: TutorialStepProps) => {
+  const stepRef = useRef<HTMLLIElement>(null)
+
+  // focus on the current step when it changes
+  useEffect(() => {
+    if (props.status === 'current') {
+      const stepElement = stepRef.current
+      const clock = setTimeout(
+        () =>
+          stepElement?.scrollIntoView({
+            behavior: 'smooth',
+            block: 'center',
+            inline: 'center',
+          }),
+        1200
+      )
+
+      return () => {
+        clearTimeout(clock)
+      }
+    }
+  }, [props.status])
+
+  return (
+    <li className="relative flex gap-x-2" ref={stepRef}>
+      <TutorialStepStatusIndicator
+        status={props.status}
+        isLast={props.isLast ?? false}
+      />
+
+      <div className="flex flex-col py-0.5 text-sm w-full flex gap-y-1">
+        <button
+          disabled={props.status === 'current'}
+          onClick={stepRef.current ? props.onExpand : () => {}}
+          className={clsx(
+            'block text-left font-medium',
+            props.status === 'current'
+              ? 'text-gray-800 hover:text-gray-900'
+              : props.status === 'completed'
+              ? 'text-green-700 hover:text-green-800'
+              : 'text-gray-400 hover:text-gray-500'
+          )}
+        >
+          {props.name}
+        </button>
+        <div
+          className={clsx(
+            'flex flex-col gap-y-3 transition-max-height duration-500 overflow-hidden',
+            props.status !== 'current' && !props.isExpanded
+              ? 'max-h-0'
+              : 'max-h-72',
+            props.status === 'current' ? 'delay-[1000ms]' : 'delay-[200ms]'
+          )}
+        >
+          <div className="text-xs text-gray-500 flex flex-col gap-y-1.5">
+            {props.description}
+          </div>
+
+          {props.children && (
+            <div
+              className={clsx(
+                'text-blue-600 text-xs w-full flex flex-col gap-y-1',
+                props.status === 'current' ? 'block' : 'hidden'
+              )}
+            >
+              {props.children}
+            </div>
+          )}
+        </div>
+      </div>
+    </li>
+  )
+}
diff --git a/apps/web/src/components/onboarding/index.tsx b/apps/web/src/components/onboarding/index.tsx
deleted file mode 100644
index cec32001..00000000
--- a/apps/web/src/components/onboarding/index.tsx
+++ /dev/null
@@ -1,142 +0,0 @@
-import { Fragment, useCallback, useState } from 'react'
-import { Dialog, Transition } from '@headlessui/react'
-import OnboardingSteps, {
-  ONBOARDING_STEP_CHAIN,
-  useOnboardingSteps,
-} from './onboardingSteps'
-import { ArrowRightIcon, CheckIcon } from '@heroicons/react/24/solid'
-import {
-  ActivateTrialStep,
-  DataSourceStep,
-  JoinSlackStep,
-  WelcomeStep,
-} from './steps'
-import { OnboardingStep } from '@briefer/types'
-
-const getCurrentStepContent = (
-  currentStepId: OnboardingStep | undefined
-): React.FC<{
-  currentStepId: OnboardingStep
-  goToStep: (stepId: OnboardingStep) => void
-}> | null => {
-  if (!currentStepId) {
-    return WelcomeStep
-  }
-
-  switch (currentStepId) {
-    case 'intro':
-      return WelcomeStep
-    case 'connectDataSource':
-      return DataSourceStep
-    case 'activateTrial':
-      return ActivateTrialStep
-    case 'joinSlack':
-    case 'done':
-      return JoinSlackStep
-    default:
-      return null
-  }
-}
-
-function Onboarding() {
-  const [open, setOpen] = useState(true)
-
-  const { currentStepId, isLoading, goToStep, nextStep, prevStep } =
-    useOnboardingSteps()
-
-  const StepContent = getCurrentStepContent(currentStepId)
-
-  const isFirstStep = ONBOARDING_STEP_CHAIN[0].id === currentStepId
-  const isLastStep =
-    ONBOARDING_STEP_CHAIN[ONBOARDING_STEP_CHAIN.length - 1].id === currentStepId
-
-  const onNextStep = useCallback(() => {
-    if (isLastStep) {
-      setOpen(false)
-    }
-
-    nextStep()
-  }, [isLastStep, nextStep])
-
-  return (
-    <Transition.Root
-      show={open && !isLoading && currentStepId !== 'done'}
-      as={Fragment}
-    >
-      <Dialog className="relative z-[1000]" onClose={() => null}>
-        <Transition.Child
-          as={Fragment}
-          enter="ease-out duration-300"
-          enterFrom="opacity-0"
-          enterTo="opacity-100"
-          leave="ease-in duration-200"
-          leaveFrom="opacity-100"
-          leaveTo="opacity-0"
-        >
-          <div className="fixed inset-0 bg-gray-500 bg-opacity-75 transition-opacity" />
-        </Transition.Child>
-
-        <div className="fixed inset-0 z-10 w-screen overflow-y-auto">
-          <div className="flex min-h-full items-end justify-center p-4 text-center sm:items-center sm:p-0">
-            <Transition.Child
-              as={Fragment}
-              enter="ease-out duration-300"
-              enterFrom="opacity-0 translate-y-4 sm:translate-y-0 sm:scale-95"
-              enterTo="opacity-100 translate-y-0 sm:scale-100"
-              leave="ease-in duration-200"
-              leaveFrom="opacity-100 translate-y-0 sm:scale-100"
-              leaveTo="opacity-0 translate-y-4 sm:translate-y-0 sm:scale-95"
-            >
-              <Dialog.Panel className="relative transform overflow-hidden rounded-lg bg-white text-left shadow-xl transition-all max-w-2xl">
-                <div className="flex items-start h-full divide-x divide-gray-200">
-                  <div className="p-6 min-w-40">
-                    <OnboardingSteps
-                      currentStepId={currentStepId ?? 'intro'}
-                      goToStep={goToStep}
-                    />
-                  </div>
-
-                  <div className="flex flex-col justify-between h-full py-6 px-8 w-[96rem] overflow-auto">
-                    {StepContent && (
-                      <StepContent
-                        currentStepId={currentStepId ?? 'intro'}
-                        goToStep={goToStep}
-                      />
-                    )}
-
-                    <div className="flex flex-row-reverse gap-x-3 pt-6">
-                      <button
-                        type="button"
-                        data-autofocus
-                        className="inline-flex items-center gap-x-3 w-full justify-center rounded-sm bg-primary-200 px-4 py-2 text-sm shadow-sm hover:bg-primary-300 sm:w-auto"
-                        onClick={onNextStep}
-                      >
-                        {isLastStep ? 'Finish' : 'Next'}
-                        {isLastStep ? (
-                          <CheckIcon className="w-3 h-3" />
-                        ) : (
-                          <ArrowRightIcon className="w-3 h-3" />
-                        )}
-                      </button>
-                      {!isFirstStep && (
-                        <button
-                          type="button"
-                          className="inline-flex w-full justify-center rounded-sm bg-white px-4 py-2 text-sm text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 hover:bg-gray-50 sm:w-auto"
-                          onClick={prevStep}
-                        >
-                          Back
-                        </button>
-                      )}
-                    </div>
-                  </div>
-                </div>
-              </Dialog.Panel>
-            </Transition.Child>
-          </div>
-        </div>
-      </Dialog>
-    </Transition.Root>
-  )
-}
-
-export default Onboarding
diff --git a/apps/web/src/components/onboarding/onboardingSteps.tsx b/apps/web/src/components/onboarding/onboardingSteps.tsx
deleted file mode 100644
index 7d19ccef..00000000
--- a/apps/web/src/components/onboarding/onboardingSteps.tsx
+++ /dev/null
@@ -1,161 +0,0 @@
-import { useStringQuery } from '@/hooks/useQueryArgs'
-import { useWorkspaces } from '@/hooks/useWorkspaces'
-import { OnboardingStep } from '@briefer/types'
-import { CheckCircleIcon } from '@heroicons/react/20/solid'
-import { useCallback, useMemo, useState } from 'react'
-
-type StepChainItem = {
-  id: OnboardingStep
-  name: string
-}
-
-export const ONBOARDING_STEP_CHAIN: StepChainItem[] = [
-  {
-    id: 'intro',
-    name: 'Introduction',
-  },
-  {
-    id: 'connectDataSource',
-    name: 'Connect a data source',
-  },
-  {
-    id: 'joinSlack',
-    name: 'Community and support',
-  },
-]
-
-function OnboardingSteps({
-  currentStepId,
-  goToStep,
-}: {
-  currentStepId: OnboardingStep
-  goToStep: (stepId: OnboardingStep) => void
-}) {
-  const currentStepIndex = useMemo(
-    () => ONBOARDING_STEP_CHAIN.findIndex((step) => step.id === currentStepId),
-    [currentStepId]
-  )
-
-  return (
-    <nav className="text-xs pt-1 pb-8 h-full" aria-label="Progress">
-      <ol role="list" className="space-y-6 flex flex-col justify-center">
-        {ONBOARDING_STEP_CHAIN.map((step, i) => (
-          <li key={step.name}>
-            {i < currentStepIndex ? (
-              <button onClick={() => goToStep(step.id)} className="group">
-                <span className="flex items-start">
-                  <span className="relative flex h-5 w-5 flex-shrink-0 items-center justify-center">
-                    <CheckCircleIcon
-                      className="h-full w-full text-primary-600 group-hover:text-primary-800"
-                      aria-hidden="true"
-                    />
-                  </span>
-                  <span className="ml-1.5 font-medium text-gray-500 group-hover:text-gray-900 text-left">
-                    {step.name}
-                  </span>
-                </span>
-              </button>
-            ) : i === currentStepIndex ? (
-              <button
-                onClick={() => goToStep(step.id)}
-                className="flex items-start"
-                aria-current="step"
-              >
-                <span
-                  className="relative flex h-5 w-5 flex-shrink-0 items-center justify-center"
-                  aria-hidden="true"
-                >
-                  <span className="absolute h-4 w-4 rounded-full bg-primary-200" />
-                  <span className="relative block h-2 w-2 rounded-full bg-primary-600" />
-                </span>
-                <span className="ml-1.5 font-bold text-primary-600 text-left">
-                  {step.name}
-                </span>
-              </button>
-            ) : (
-              <button onClick={() => goToStep(step.id)} className="group">
-                <div className="flex items-start">
-                  <div
-                    className="relative flex h-5 w-5 flex-shrink-0 items-center justify-center"
-                    aria-hidden="true"
-                  >
-                    <div className="h-2 w-2 rounded-full bg-gray-300 group-hover:bg-gray-400" />
-                  </div>
-                  <p className="ml-1.5 font-medium text-gray-500 group-hover:text-gray-900 text-left">
-                    {step.name}
-                  </p>
-                </div>
-              </button>
-            )}
-          </li>
-        ))}
-      </ol>
-    </nav>
-  )
-}
-
-export const useOnboardingSteps = () => {
-  const workspaceId = useStringQuery('workspaceId')
-  const [workspaces, { updateOnboarding }] = useWorkspaces()
-  const isLoading = workspaces.isLoading
-
-  const currentWorkspace = workspaces.data.find(
-    (workspace) => workspace.id === workspaceId
-  )
-
-  const goToStep = useCallback(
-    (stepId: OnboardingStep) => {
-      if (!currentWorkspace) {
-        return
-      }
-
-      updateOnboarding(currentWorkspace.id, stepId)
-    },
-    [currentWorkspace, updateOnboarding]
-  )
-
-  const nextStep = useCallback(() => {
-    if (!currentWorkspace) {
-      return
-    }
-
-    const currentStepIndex = ONBOARDING_STEP_CHAIN.findIndex(
-      (step) => step.id === currentWorkspace.onboardingStep
-    )
-
-    if (currentStepIndex === ONBOARDING_STEP_CHAIN.length - 1) {
-      updateOnboarding(workspaceId, 'done')
-      return
-    }
-
-    const nextStep = ONBOARDING_STEP_CHAIN[currentStepIndex + 1]
-    updateOnboarding(currentWorkspace.id, nextStep.id)
-  }, [currentWorkspace, updateOnboarding])
-
-  const prevStep = useCallback(() => {
-    if (!currentWorkspace) {
-      return
-    }
-
-    const currentStepIndex = ONBOARDING_STEP_CHAIN.findIndex(
-      (step) => step.id === currentWorkspace.onboardingStep
-    )
-
-    if (currentStepIndex === 0) {
-      return
-    }
-
-    const prevStep = ONBOARDING_STEP_CHAIN[currentStepIndex - 1]
-    updateOnboarding(currentWorkspace.id, prevStep.id)
-  }, [currentWorkspace, updateOnboarding])
-
-  return {
-    isLoading,
-    currentStepId: currentWorkspace?.onboardingStep,
-    goToStep,
-    nextStep,
-    prevStep,
-  }
-}
-
-export default OnboardingSteps
diff --git a/apps/web/src/components/onboarding/steps.tsx b/apps/web/src/components/onboarding/steps.tsx
deleted file mode 100644
index dadec9d1..00000000
--- a/apps/web/src/components/onboarding/steps.tsx
+++ /dev/null
@@ -1,242 +0,0 @@
-import { Dialog } from '@headlessui/react'
-import { DataSourceIcons } from '../DataSourceIcons'
-import { useStringQuery } from '@/hooks/useQueryArgs'
-import { useDataSources } from '@/hooks/useDatasources'
-import { InlineWidget } from 'react-calendly'
-import { useSession } from '@/hooks/useAuth'
-import { useState } from 'react'
-
-export const WelcomeStep = () => {
-  return (
-    <div className="flex flex-col gap-y-2">
-      <Dialog.Title
-        as="h2"
-        className="text-lg font-semibold leading-6 text-gray-900"
-      >
-        Welcome to Briefer!
-      </Dialog.Title>
-      <Dialog.Description className="flex flex-col gap-y-2 text-sm text-gray-500">
-        <p>
-          Hey there! I&apos;m Lucas, founder of Briefer, and I&apos;m excited to
-          have you on board.
-        </p>
-        <p>
-          Here&apos;s a quick video to help you get started with Briefer.
-          I&apos;d highly recommend watching it before you dive in.
-        </p>
-
-        <div
-          className="mt-4"
-          style={{
-            position: 'relative',
-            paddingBottom: '62.5%',
-            height: 0,
-          }}
-        >
-          <iframe
-            src="https://www.loom.com/embed/b8387e51fab1463d85d7ca6efd78bbaa?sid=c058f20f-5487-48d3-a2c3-c3cf837ddc1c&hideEmbedTopBar=true&hide_share=true&hide_owner=true"
-            frameBorder="0"
-            allowFullScreen
-            style={{
-              position: 'absolute',
-              top: 0,
-              left: 0,
-              width: '100%',
-              height: '100%',
-            }}
-          ></iframe>
-        </div>
-      </Dialog.Description>
-    </div>
-  )
-}
-
-export const DataSourceStep = () => {
-  const workspaceId = useStringQuery('workspaceId') ?? ''
-  const [isUsingCsv, setIsUsingCsv] = useState(false)
-
-  const [{ datasources: dataSources }] = useDataSources(workspaceId)
-
-  if (dataSources.size > 0) {
-    return (
-      <div className="flex flex-col gap-y-2">
-        <Dialog.Title
-          as="h2"
-          className="text-lg font-semibold leading-6 text-gray-900"
-        >
-          Your data source is connected
-        </Dialog.Title>
-        <Dialog.Description className="flex flex-col gap-y-2 text-sm text-gray-500">
-          <p>You&apos;ve connected a data source to Briefer. Great job!</p>
-          <p>
-            You will be able to query this data source using Briefer&apos;s
-            query blocks.
-          </p>
-
-          <div
-            className="mt-4"
-            style={{
-              position: 'relative',
-              paddingBottom: '62.5%',
-              height: 0,
-            }}
-          >
-            <iframe
-              src="https://www.loom.com/embed/c1c16fa926c546f3b9e416843f6d4e10?sid=2909a383-bb98-4e35-892e-2f0e01560ea8&hideEmbedTopBar=true&hide_share=true&hide_owner=true"
-              frameBorder="0"
-              allowFullScreen
-              style={{
-                position: 'absolute',
-                top: 0,
-                left: 0,
-                width: '100%',
-                height: '100%',
-              }}
-            ></iframe>
-          </div>
-        </Dialog.Description>
-      </div>
-    )
-  }
-
-  if (isUsingCsv) {
-    return (
-      <div className="flex flex-col gap-y-2">
-        <Dialog.Title
-          as="h2"
-          className="text-lg font-semibold leading-6 text-gray-900"
-        >
-          Here is how to use CSV files
-        </Dialog.Title>
-        <Dialog.Description className="flex flex-col gap-y-2 text-sm text-gray-500">
-          <p>
-            You can upload files directly into your pages by using the file
-            upload block.
-          </p>
-          <p>Here&apos;s a quick video on how to use files in your pages.</p>
-
-          <div
-            className="mt-4"
-            style={{
-              position: 'relative',
-              paddingBottom: '62.5%',
-              height: 0,
-            }}
-          >
-            <iframe
-              src="https://www.loom.com/embed/db98b8c3b43641478bf2a90816274bf7?sid=29188922-78b1-4d4a-b232-f5575edc19ed&hideEmbedTopBar=true&hide_share=true&hide_owner=true"
-              frameBorder="0"
-              allowFullScreen
-              style={{
-                position: 'absolute',
-                top: 0,
-                left: 0,
-                width: '100%',
-                height: '100%',
-              }}
-            ></iframe>
-          </div>
-        </Dialog.Description>
-      </div>
-    )
-  }
-
-  return (
-    <div className="flex flex-col gap-y-2">
-      <Dialog.Title
-        as="h2"
-        className="text-lg font-semibold leading-6 text-gray-900"
-      >
-        Let&apos;s connect to a data source
-      </Dialog.Title>
-      <Dialog.Description className="flex flex-col gap-y-2 text-sm text-gray-500">
-        <p>
-          Briefer works better when it&apos;s connected to your data sources.
-        </p>
-        <p>Which of these data sources would you like to connect first?</p>
-
-        <div className="mt-4 flex items-center justify-center">
-          <DataSourceIcons
-            workspaceId={workspaceId}
-            onCSV={() => setIsUsingCsv(true)}
-          />
-        </div>
-      </Dialog.Description>
-    </div>
-  )
-}
-
-export const ActivateTrialStep = () => {
-  const session = useSession({ redirectToLogin: true })
-  const email = session.data?.email
-
-  return (
-    <div className="flex flex-col gap-y-2">
-      <Dialog.Title
-        as="h2"
-        className="text-lg font-semibold leading-6 text-gray-900"
-      >
-        Now, let&apos;s get you some extra features
-      </Dialog.Title>
-      <Dialog.Description className="flex flex-col gap-y-2 text-sm text-gray-500">
-        <p>
-          Let&apos;s be honest, you&apos;re probably tired of these onboarding
-          screens and just want to get to the good stuff, but hear me out.
-        </p>
-        <p>
-          If you hop on a 15-minute call with me, I&apos;ll give you a free
-          trial of our professional plan for 30 days.
-        </p>
-        <div className="mt-4 flex items-center justify-center">
-          <InlineWidget
-            url="https://calendly.com/lucasfcosta/briefer-intro-call?hide_event_type_details=1"
-            styles={{ width: '100%', height: '500px' }}
-            prefill={{ email }}
-          />
-        </div>
-        <p>
-          I&apos;m doing this is because I want to hear about your use cases and
-          help you get the most out of Briefer.
-        </p>
-      </Dialog.Description>
-    </div>
-  )
-}
-
-export const JoinSlackStep = () => {
-  return (
-    <div className="flex flex-col gap-y-2">
-      <Dialog.Title
-        as="h2"
-        className="text-lg font-semibold leading-6 text-gray-900"
-      >
-        Join Slack
-      </Dialog.Title>
-      <Dialog.Description className="flex flex-col gap-y-2 text-sm text-gray-500">
-        <p>
-          Briefer&apos;s Slack community is the perfect place to get help, share
-          feedback, and connect with other people in the data community.
-        </p>
-        <p>
-          If you hop in and say hi, I&apos;ll be there to welcome you
-          personally, and you can ask me anything you want.
-        </p>
-        <div className="py-6 flex items-center justify-center">
-          <a
-            href="https://briefercommunity.slack.com/join/shared_invite/zt-2geo5vlh2-RxEOwCRrVEz6JDkrPHuf0g#/shared-invite/email"
-            target="_blank"
-            rel="noreferrer"
-            className="bg-primary-200 text-gray-900 px-5 py-3 rounded-md text-md font-semibold shadow-sm flex gap-x-3 items-center"
-          >
-            <img src="/icons/slack.png" alt="Slack Logo" className="w-6 h-6" />
-            Join Briefer&apos;s Slack Community
-          </a>
-        </div>
-        <p>
-          I&apos;m doing this is because I want to hear about your use cases and
-          help you get the most out of Briefer.
-        </p>
-      </Dialog.Description>
-    </div>
-  )
-}
diff --git a/apps/web/src/components/v2Editor/PlusButton.tsx b/apps/web/src/components/v2Editor/PlusButton.tsx
index 2c5c5334..b483cbc9 100644
--- a/apps/web/src/components/v2Editor/PlusButton.tsx
+++ b/apps/web/src/components/v2Editor/PlusButton.tsx
@@ -38,11 +38,13 @@ const useClickOutside = (
 }
 
 interface Props {
-  alwaysVisible: boolean
+  alwaysOpen: boolean
   onAddBlock: (type: BlockType) => void
   isEditable: boolean
   writebackEnabled: boolean
+  isLast: boolean
 }
+
 function PlusButton(props: Props) {
   const wrapperRef = useRef<HTMLDivElement>(null)
   const [showOptions, setShowOptions] = useState(false)
@@ -63,13 +65,21 @@ function PlusButton(props: Props) {
     [props.onAddBlock]
   )
 
+  const btnDivProps = props.isLast ? { id: 'last-plus-button' } : {}
+
   return (
-    <div className="w-full group relative py-2" ref={wrapperRef}>
+    <div
+      {...btnDivProps}
+      className="w-full group relative py-2"
+      ref={wrapperRef}
+    >
       <button
         className={clsx(
           'flex items-center justify-center gap-x-2 group-hover:opacity-100 transition-opacity duration-200 w-full h-6',
           !props.isEditable && 'invisible',
-          props.alwaysVisible || showOptions ? 'opacity-100' : 'opacity-0'
+          props.alwaysOpen || showOptions || props.isLast
+            ? 'opacity-100'
+            : 'opacity-0'
         )}
         onClick={toggleOptions}
       >
@@ -81,7 +91,7 @@ function PlusButton(props: Props) {
         <div className="w-full h-[1px] bg-gray-200" />
       </button>
 
-      {props.isEditable && (showOptions || props.alwaysVisible) && (
+      {props.isEditable && (showOptions || props.alwaysOpen) && (
         <BlockList
           onAddBlock={addBlockHandler}
           writebackEnabled={props.writebackEnabled}
@@ -137,32 +147,38 @@ function BlockList(props: BlockListProps) {
       </div>
       <div className="w-full bg-white py-1 rounded-md border border-gray-200 flex items-center justify-center divide-x divide-gray-200 shadow-lg">
         <BlockSuggestion
+          id="add-block-text"
           icon={<Bars3CenterLeftIcon className="w-4 h-4" />}
           onAdd={onAddText}
           text="Text"
         />
         <BlockSuggestion
+          id="add-block-query"
           icon={<CircleStackIcon className="w-4 h-4" />}
           onAdd={onAddSQL}
           text="Query"
         />
         <BlockSuggestion
+          id="add-block-python"
           icon={<CodeBracketIcon className="w-4 h-4" />}
           onAdd={onAddPython}
           text="Python"
         />
         <BlockSuggestion
+          id="add-block-visualization"
           icon={<ChartBarIcon className="w-4 h-4" />}
           onAdd={onAddVisualization}
           text="Visualization"
         />
         <BlockSuggestion
+          id="add-block-pivot"
           icon={<Table2Icon className="w-4 h-4" />}
           onAdd={onAddPivotTable}
           text="Pivot"
         />
         {props.writebackEnabled && (
           <BlockSuggestion
+            id="add-block-writeback"
             icon={<ArrowUpTrayIcon className="w-4 h-4" />}
             onAdd={onAddWriteback}
             text="Writeback"
@@ -196,6 +212,7 @@ function BlockList(props: BlockListProps) {
 }
 
 type BlockSuggestionProps = {
+  id: string
   icon: JSX.Element
   text: string
   onAdd: () => void
@@ -207,7 +224,7 @@ function BlockSuggestion(props: BlockSuggestionProps) {
   }, [props.onAdd])
 
   return (
-    <div className="w-full text-sm px-1 relative z-30">
+    <div id={props.id} className="w-full text-sm px-1 relative z-30">
       <button
         className="w-full transition-colors transition-100 flex items-center justify-center gap-x-2 p-2 rounded-md text-gray-400 bg-white hover:bg-gray-100 hover:text-gray-700"
         onClick={onClick}
diff --git a/apps/web/src/components/v2Editor/index.tsx b/apps/web/src/components/v2Editor/index.tsx
index c8559514..1b72b307 100644
--- a/apps/web/src/components/v2Editor/index.tsx
+++ b/apps/web/src/components/v2Editor/index.tsx
@@ -109,6 +109,7 @@ const dataframesGetter = (yDoc: Y.Doc) => yDoc.getMap<DataFrame>('dataframes')
 
 const Dropzone = ({
   index,
+  isLast,
   isEditable,
   onDropItem,
   onCheckCanDrop,
@@ -116,6 +117,7 @@ const Dropzone = ({
   writebackEnabled,
 }: {
   index: number
+  isLast: boolean
   isEditable: boolean
   onDropItem: (
     blockGroupId: string,
@@ -163,7 +165,8 @@ const Dropzone = ({
       className={clsx('w-full', isOver && canDrop ? 'bg-ceramic-300' : '')}
     >
       <PlusButton
-        alwaysVisible={false}
+        isLast={isLast}
+        alwaysOpen={false}
         onAddBlock={addBlockHandler}
         isEditable={isEditable}
         writebackEnabled={writebackEnabled}
@@ -901,6 +904,7 @@ file`
 
 const V2EditorRow = (props: {
   index: number
+  totalBlocks: number
   document: ApiDocument
   yDoc: Y.Doc
   blockId: string
@@ -946,11 +950,13 @@ const V2EditorRow = (props: {
   executionQueue: ExecutionQueue
   aiTasks: AITasks
 }) => {
+  const isLast = props.index === props.totalBlocks - 1
   return (
     <div>
       {props.index === 0 && (
         <Dropzone
           index={props.index}
+          isLast={false}
           isEditable={props.isEditable && !props.isApp}
           onAddBlock={props.onAddBlock}
           onDropItem={props.onDropItem}
@@ -981,14 +987,17 @@ const V2EditorRow = (props: {
         executionQueue={props.executionQueue}
         aiTasks={props.aiTasks}
       />
-      <Dropzone
-        index={props.index + 1}
-        isEditable={props.isEditable && !props.isApp}
-        onAddBlock={props.onAddBlock}
-        onDropItem={props.onDropItem}
-        onCheckCanDrop={props.onCheckCanDrop}
-        writebackEnabled={props.writebackEnabled}
-      />
+      <div className={clsx(isLast ? 'pt-2' : '')}>
+        <Dropzone
+          index={props.index + 1}
+          isLast={isLast}
+          isEditable={props.isEditable && !props.isApp}
+          onAddBlock={props.onAddBlock}
+          onDropItem={props.onDropItem}
+          onCheckCanDrop={props.onCheckCanDrop}
+          writebackEnabled={props.writebackEnabled}
+        />
+      </div>
     </div>
   )
 }
@@ -1392,6 +1401,7 @@ const Editor = (props: Props) => {
           key={i}
           blockId={blockId}
           index={i}
+          totalBlocks={layout.value.length}
           isEditable={props.isEditable}
           isApp={props.isApp}
           onAddBlock={onAddBlock}
@@ -1507,7 +1517,8 @@ const Editor = (props: Props) => {
                 {domBlocks.length === 0 && (
                   <div className="w-full">
                     <PlusButton
-                      alwaysVisible
+                      isLast
+                      alwaysOpen
                       onAddBlock={addBlockToBottom}
                       isEditable={props.isEditable}
                       writebackEnabled={hasWriteback}
diff --git a/apps/web/src/hooks/useTutorial.ts b/apps/web/src/hooks/useTutorial.ts
new file mode 100644
index 00000000..908e9217
--- /dev/null
+++ b/apps/web/src/hooks/useTutorial.ts
@@ -0,0 +1,110 @@
+import { NEXT_PUBLIC_API_URL } from '@/utils/env'
+import fetcher from '@/utils/fetcher'
+import { StepStates, TutorialState } from '@briefer/types'
+import { useCallback, useEffect, useMemo } from 'react'
+import useSWR from 'swr'
+import useWebsocket from './useWebsocket'
+
+type UseTutorialState = {
+  tutorialState: TutorialState
+  isLoading: boolean
+}
+
+type UseTutorialAPI = {
+  advanceTutorial: () => void
+  dismissTutorial: () => void
+}
+
+const useTutorial = (
+  workspaceId: string,
+  tutorialType: string,
+  defaultStepStates: StepStates
+): [UseTutorialState, UseTutorialAPI] => {
+  const socket = useWebsocket()
+  const { data, isLoading, error, mutate } = useSWR<TutorialState>(
+    `${NEXT_PUBLIC_API_URL()}/v1/workspaces/${workspaceId}/tutorials/${tutorialType}`,
+    fetcher
+  )
+
+  const defaultData = useMemo(
+    () => ({
+      id: '',
+      isCompleted: false,
+      // This is true so that workspaces without tutorial don't show the tutorial
+      isDismissed: true,
+      stepStates: defaultStepStates,
+    }),
+    [defaultStepStates]
+  )
+
+  useEffect(() => {
+    if (!socket) {
+      return
+    }
+
+    const onTutorialUpdate = (msg: { tutorialState: TutorialState }) => {
+      mutate(msg.tutorialState)
+    }
+
+    socket.on('workspace-tutorial-update', onTutorialUpdate)
+
+    return () => {
+      socket.off('workspace-tutorial-update', onTutorialUpdate)
+    }
+  }, [socket, mutate])
+
+  const advanceTutorial = useCallback(async () => {
+    try {
+      const tutorialRes = await fetch(
+        `${NEXT_PUBLIC_API_URL()}/v1/workspaces/${workspaceId}/tutorials/${tutorialType}`,
+        {
+          credentials: 'include',
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        }
+      )
+
+      return tutorialRes.json()
+    } catch (err) {
+      alert('Something went wrong')
+      return null
+    }
+  }, [workspaceId, tutorialType])
+
+  const dismissTutorial = useCallback(async () => {
+    mutate(
+      async () => {
+        try {
+          const tutorialRes = await fetch(
+            `${NEXT_PUBLIC_API_URL()}/v1/workspaces/${workspaceId}/tutorials/${tutorialType}/dismiss`,
+            {
+              credentials: 'include',
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+              },
+            }
+          )
+
+          return tutorialRes.json()
+        } catch (err) {
+          alert('Something went wrong')
+          return null
+        }
+      },
+      { optimisticData: { ...defaultData, isDismissed: true } }
+    )
+  }, [workspaceId, tutorialType, defaultData, mutate])
+
+  return [
+    {
+      tutorialState: data ?? defaultData,
+      isLoading: isLoading || (!data && !error),
+    },
+    { advanceTutorial, dismissTutorial },
+  ]
+}
+
+export default useTutorial
diff --git a/apps/web/src/hooks/useWorkspaces.ts b/apps/web/src/hooks/useWorkspaces.ts
index d4955a1a..231cdd48 100644
--- a/apps/web/src/hooks/useWorkspaces.ts
+++ b/apps/web/src/hooks/useWorkspaces.ts
@@ -2,7 +2,6 @@ import fetcher from '@/utils/fetcher'
 import type { ApiWorkspace } from '@briefer/database'
 import { useCallback, useMemo } from 'react'
 import useSWR from 'swr'
-import { OnboardingStep } from '@briefer/types'
 import { WorkspaceEditFormValues } from '@briefer/types'
 import { NEXT_PUBLIC_API_URL } from '@/utils/env'
 
@@ -11,10 +10,6 @@ type API = {
     workspaceId: string,
     data: WorkspaceEditFormValues
   ) => Promise<ApiWorkspace>
-  updateOnboarding: (
-    workspaceId: string,
-    onboardingStep: OnboardingStep
-  ) => Promise<void>
 }
 type UseWorkspaces = [{ data: ApiWorkspace[]; isLoading: boolean }, API]
 export const useWorkspaces = (): UseWorkspaces => {
@@ -45,47 +40,13 @@ export const useWorkspaces = (): UseWorkspaces => {
     [swrRes]
   )
 
-  const updateOnboarding = useCallback(
-    async (workspaceId: string, onboardingStep: OnboardingStep) => {
-      await swrRes.mutate(
-        async () => {
-          const res = await fetch(
-            `${NEXT_PUBLIC_API_URL()}/v1/workspaces/${workspaceId}/onboarding`,
-            {
-              credentials: 'include',
-              method: 'PUT',
-              headers: { 'Content-Type': 'application/json' },
-              body: JSON.stringify({ onboardingStep }),
-            }
-          )
-
-          const workspace: ApiWorkspace = await res.json()
-          return (swrRes.data ?? []).map((w) =>
-            w.id === workspace.id ? workspace : w
-          )
-        },
-        {
-          revalidate: true,
-          optimisticData: swrRes.data?.map((w) => {
-            if (w.id === workspaceId) {
-              return { ...w, onboardingStep }
-            }
-            return w
-          }),
-        }
-      )
-    },
-    [swrRes]
-  )
-
   return useMemo(
     () => [
       { data: swrRes.data ?? [], isLoading: swrRes.isLoading },
       {
         updateSettings,
-        updateOnboarding,
       },
     ],
-    [swrRes, updateSettings, updateOnboarding]
+    [swrRes, updateSettings]
   )
 }
diff --git a/apps/web/src/pages/_app.tsx b/apps/web/src/pages/_app.tsx
index d31d5175..6a359d30 100644
--- a/apps/web/src/pages/_app.tsx
+++ b/apps/web/src/pages/_app.tsx
@@ -21,6 +21,8 @@ import Telemetry from '@/components/Telemetry'
 import { DataSourcesProvider } from '@/hooks/useDatasources'
 import { ReusableComponentsProvider } from '@/hooks/useReusableComponents'
 import { CommentsProvider } from '@/hooks/useComments'
+import { OnboardingTutorial } from '@/components/Tutorial'
+import { TourHighlightProvider } from '@/components/TourHighlightProvider'
 
 type Page<P = {}> = NextPage<P> & {
   layout?: ComponentType
@@ -48,9 +50,12 @@ function App({ Component, pageProps: { session, ...pageProps } }: Props) {
                 <DataSourcesProvider>
                   <ReusableComponentsProvider>
                     <SideBarProvider>
-                      <Layout>
-                        <Component {...pageProps} />
-                      </Layout>
+                      <TourHighlightProvider>
+                        <OnboardingTutorial />
+                        <Layout>
+                          <Component {...pageProps} />
+                        </Layout>
+                      </TourHighlightProvider>
                     </SideBarProvider>
                   </ReusableComponentsProvider>
                 </DataSourcesProvider>
diff --git a/apps/web/src/pages/workspaces/[workspaceId]/users/index.tsx b/apps/web/src/pages/workspaces/[workspaceId]/users/index.tsx
index ee64095b..9432510a 100644
--- a/apps/web/src/pages/workspaces/[workspaceId]/users/index.tsx
+++ b/apps/web/src/pages/workspaces/[workspaceId]/users/index.tsx
@@ -86,6 +86,7 @@ export default function UsersPage() {
               active={false}
             >
               <button
+                id="add-user-button"
                 onClick={() => {
                   router.push(`/workspaces/${workspaceId}/users/new`)
                 }}
diff --git a/packages/database/prisma/migrations/20250106134253_add_onboarding_v2/migration.sql b/packages/database/prisma/migrations/20250106134253_add_onboarding_v2/migration.sql
new file mode 100644
index 00000000..7b9e39f6
--- /dev/null
+++ b/packages/database/prisma/migrations/20250106134253_add_onboarding_v2/migration.sql
@@ -0,0 +1,33 @@
+/*
+  Warnings:
+
+  - You are about to drop the column `onboardingStep` on the `Workspace` table. All the data in the column will be lost.
+
+*/
+-- CreateEnum
+CREATE TYPE "OnboardingTutorialStep" AS ENUM ('connectDataSource', 'runQuery', 'runPython', 'createVisualization', 'publishDashboard', 'inviteTeamMembers');
+
+-- AlterTable
+ALTER TABLE "Workspace" DROP COLUMN "onboardingStep";
+
+-- DropEnum
+DROP TYPE "OnboardingStep";
+
+-- CreateTable
+CREATE TABLE "OnboardingTutorial" (
+    "id" UUID NOT NULL DEFAULT gen_random_uuid(),
+    "workspaceId" UUID NOT NULL,
+    "currentStep" "OnboardingTutorialStep" NOT NULL DEFAULT 'connectDataSource',
+    "isComplete" BOOLEAN NOT NULL DEFAULT false,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "isDismissed" BOOLEAN NOT NULL DEFAULT false,
+
+    CONSTRAINT "OnboardingTutorial_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "OnboardingTutorial_workspaceId_key" ON "OnboardingTutorial"("workspaceId");
+
+-- AddForeignKey
+ALTER TABLE "OnboardingTutorial" ADD CONSTRAINT "OnboardingTutorial_workspaceId_fkey" FOREIGN KEY ("workspaceId") REFERENCES "Workspace"("id") ON DELETE CASCADE ON UPDATE CASCADE;
diff --git a/packages/database/prisma/schema.prisma b/packages/database/prisma/schema.prisma
index 2b858fc8..3e541fa0 100644
--- a/packages/database/prisma/schema.prisma
+++ b/packages/database/prisma/schema.prisma
@@ -29,12 +29,12 @@ model Document {
   parent      Document?  @relation("DocumentParent", fields: [parentId], references: [id], onDelete: Cascade)
   children    Document[] @relation("DocumentParent")
 
-  yjsDocument        YjsDocument?
-  yjsAppDocuments    YjsAppDocument[]
-  comments           Comment[]
-  Favorite           Favorite[]
-  executionSchedules ExecutionSchedule[]
-  reusableComponents ReusableComponent[]
+  yjsDocument                YjsDocument?
+  yjsAppDocuments            YjsAppDocument[]
+  comments                   Comment[]
+  Favorite                   Favorite[]
+  executionSchedules         ExecutionSchedule[]
+  reusableComponents         ReusableComponent[]
   reusableComponentInstances ReusableComponentInstance[]
 
   runUnexecutedBlocks Boolean @default(false)
@@ -49,7 +49,7 @@ model YjsDocument {
   createdAt  DateTime @default(now())
   updatedAt  DateTime @default(now()) @updatedAt
 
-  document Document @relation(fields: [documentId], references: [id], onDelete: Cascade)
+  document   Document    @relation(fields: [documentId], references: [id], onDelete: Cascade)
   yjsUpdates YjsUpdate[]
 }
 
@@ -409,16 +409,16 @@ model User {
   createdAt      DateTime @default(now())
   updatedAt      DateTime @default(now()) @updatedAt
 
-  workspacesInvitees   UserWorkspace[] @relation("UserWorkspaceInviter")
-  workspaces           UserWorkspace[] @relation("UserWorkspaceUser")
-  ownedWorkspaces      Workspace[]
-  confirmedAt          DateTime?
-  lastVisitedWorkspaceId String? @db.Uuid
+  workspacesInvitees     UserWorkspace[] @relation("UserWorkspaceInviter")
+  workspaces             UserWorkspace[] @relation("UserWorkspaceUser")
+  ownedWorkspaces        Workspace[]
+  confirmedAt            DateTime?
+  lastVisitedWorkspaceId String?         @db.Uuid
 
-  lastVisitedWorkspace Workspace? @relation(fields: [lastVisitedWorkspaceId], references: [id], name: "lastVisitedWorkspace", onDelete: SetNull)
-  comments           Comment[]
-  Favorite           Favorite[]
-  UserYjsAppDocument UserYjsAppDocument[]
+  lastVisitedWorkspace Workspace?           @relation(fields: [lastVisitedWorkspaceId], references: [id], name: "lastVisitedWorkspace", onDelete: SetNull)
+  comments             Comment[]
+  Favorite             Favorite[]
+  UserYjsAppDocument   UserYjsAppDocument[]
 }
 
 model Comment {
@@ -477,25 +477,16 @@ enum Plan {
   professional
 }
 
-enum OnboardingStep {
-  intro
-  connectDataSource
-  activateTrial
-  joinSlack
-  done
-}
-
 model Workspace {
-  id             String         @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
+  id             String   @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
   name           String
   source         String?
-  useCases       String[]       @default([])
+  useCases       String[] @default([])
   useContext     String?
-  plan           Plan           @default(free)
-  ownerId        String         @db.Uuid
-  secretsId      String?        @unique @db.Uuid
-  onboardingStep OnboardingStep @default(intro)
-  assistantModel String         @default("gpt-4o")
+  plan           Plan     @default(free)
+  ownerId        String   @db.Uuid
+  secretsId      String?  @unique @db.Uuid
+  assistantModel String   @default("gpt-4o")
 
   createdAt DateTime @default(now())
   updatedAt DateTime @default(now()) @updatedAt
@@ -515,7 +506,8 @@ model Workspace {
   snowflakeDataSources     SnowflakeDataSource[]
   databricksSQLDataSources DatabricksSQLDataSource[]
   environmentVariables     EnvironmentVariable[]
-  lastVisitors             User[] @relation("lastVisitedWorkspace")
+  lastVisitors             User[]                    @relation("lastVisitedWorkspace")
+  onboardingTutorial       OnboardingTutorial?
 }
 
 enum UserWorkspaceRole {
@@ -597,61 +589,84 @@ enum ReusableComponentType {
 model ReusableComponent {
   id String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
 
-  state      Bytes
-  type       ReusableComponentType
-  title      String
-  blockId    String                @unique @db.Uuid
-  documentId String                @db.Uuid
-  createdAt  DateTime              @default(now())
-  updatedAt  DateTime              @default(now()) @updatedAt
-  instancesCreated Boolean         @default(true)
-
-  document Document @relation(fields: [documentId], references: [id], onDelete: Cascade)
+  state            Bytes
+  type             ReusableComponentType
+  title            String
+  blockId          String                @unique @db.Uuid
+  documentId       String                @db.Uuid
+  createdAt        DateTime              @default(now())
+  updatedAt        DateTime              @default(now()) @updatedAt
+  instancesCreated Boolean               @default(true)
+
+  document                   Document                    @relation(fields: [documentId], references: [id], onDelete: Cascade)
   reusableComponentInstances ReusableComponentInstance[]
 }
 
 model ReusableComponentInstance {
-  id                  String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
-  blockId             String @unique @db.Uuid
-  reusableComponentId String @db.Uuid
-  documentId          String @db.Uuid
+  id                  String   @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
+  blockId             String   @unique @db.Uuid
+  reusableComponentId String   @db.Uuid
+  documentId          String   @db.Uuid
   createdAt           DateTime @default(now())
   updatedAt           DateTime @default(now()) @updatedAt
 
-  reusableComponent   ReusableComponent @relation(fields: [reusableComponentId], references: [id], onDelete: Cascade)
-  document            Document          @relation(fields: [documentId], references: [id], onDelete: Cascade)
+  reusableComponent ReusableComponent @relation(fields: [reusableComponentId], references: [id], onDelete: Cascade)
+  document          Document          @relation(fields: [documentId], references: [id], onDelete: Cascade)
 }
 
-
 model YjsUpdate {
-  id         String   @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
-  update     Bytes
-  clock      Int
+  id     String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
+  update Bytes
+  clock  Int
 
-  createdAt  DateTime @default(now())
-  updatedAt  DateTime @default(now()) @updatedAt
+  createdAt DateTime @default(now())
+  updatedAt DateTime @default(now()) @updatedAt
 
-  yjsDocumentId String?   @db.Uuid
+  yjsDocumentId String?      @db.Uuid
   yjsDocument   YjsDocument? @relation(fields: [yjsDocumentId], references: [id], onDelete: Cascade)
 
-  yjsAppDocumentId String?   @db.Uuid
+  yjsAppDocumentId String?         @db.Uuid
   yjsAppDocument   YjsAppDocument? @relation(fields: [yjsAppDocumentId], references: [id], onDelete: Cascade)
 
-  userYjsAppDocumentYjsAppDocumentId String? @db.Uuid
-  userYjsAppDocumentUserId           String? @db.Uuid
-  userYjsAppDocument UserYjsAppDocument? @relation(fields: [userYjsAppDocumentYjsAppDocumentId, userYjsAppDocumentUserId], references: [yjsAppDocumentId, userId], onDelete: Cascade)
+  userYjsAppDocumentYjsAppDocumentId String?             @db.Uuid
+  userYjsAppDocumentUserId           String?             @db.Uuid
+  userYjsAppDocument                 UserYjsAppDocument? @relation(fields: [userYjsAppDocumentYjsAppDocumentId, userYjsAppDocumentUserId], references: [yjsAppDocumentId, userId], onDelete: Cascade)
 }
 
 model PubSubPayload {
-  id         String   @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
-  payload    Bytes
-  createdAt  DateTime @default(now())
+  id        String   @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
+  payload   Bytes
+  createdAt DateTime @default(now())
 }
 
 // socket.io pg adapter is case insensitive, so we can't
 // follow our naming convention here
 model socket_io_attachments {
-  id         BigInt    @default(autoincrement()) @unique
-  createdAt  DateTime  @default(now()) @map("created_at")
-  payload    Bytes
+  id        BigInt   @unique @default(autoincrement())
+  createdAt DateTime @default(now()) @map("created_at")
+  payload   Bytes
+}
+
+enum OnboardingTutorialStep {
+  connectDataSource
+  runQuery
+  runPython
+  createVisualization
+  publishDashboard
+  inviteTeamMembers
+}
+
+model OnboardingTutorial {
+  id String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
+
+  workspaceId String    @db.Uuid
+  workspace   Workspace @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
+
+  currentStep OnboardingTutorialStep @default(connectDataSource)
+  isComplete  Boolean                @default(false)
+  createdAt   DateTime               @default(now())
+  updatedAt   DateTime               @default(now()) @updatedAt
+  isDismissed Boolean                @default(false)
+
+  @@unique([workspaceId])
 }
diff --git a/packages/database/src/documents.ts b/packages/database/src/documents.ts
index e90c4bdb..2f7ad916 100644
--- a/packages/database/src/documents.ts
+++ b/packages/database/src/documents.ts
@@ -179,6 +179,7 @@ export async function createDocument(
   data: {
     id?: string
     title?: string
+    icon?: string
     parentId?: string | null
     version?: number
     orderIndex: number
@@ -203,6 +204,7 @@ export async function createDocument(
       title: data.title ?? '',
       orderIndex: data.orderIndex,
       version: data.version,
+      icon: data.icon,
     },
   })
 }
diff --git a/packages/database/src/index.ts b/packages/database/src/index.ts
index 49a49c1a..3de31d92 100644
--- a/packages/database/src/index.ts
+++ b/packages/database/src/index.ts
@@ -13,6 +13,7 @@ export type {
   UserYjsAppDocument,
   YjsUpdate,
   ReusableComponentInstance,
+  OnboardingTutorial,
 } from '@prisma/client'
 
 export { UserWorkspaceRole } from '@prisma/client'
diff --git a/packages/database/src/workspaces.ts b/packages/database/src/workspaces.ts
index 7522c225..8bf785b7 100644
--- a/packages/database/src/workspaces.ts
+++ b/packages/database/src/workspaces.ts
@@ -1,10 +1,6 @@
 import prisma, { PrismaTransaction } from './index.js'
 import { Workspace } from '@prisma/client'
-import {
-  OnboardingStep,
-  WorkspaceCreateInput,
-  WorkspaceEditFormValues,
-} from '@briefer/types'
+import { WorkspaceCreateInput, WorkspaceEditFormValues } from '@briefer/types'
 
 type WorkspaceWithSecrets = Workspace & {
   secrets: {
@@ -123,19 +119,6 @@ export async function updateWorkspace(
   return transformSecrets(w)
 }
 
-export async function updateOnboardingStep(
-  workspaceId: string,
-  onboardingStep: OnboardingStep
-) {
-  const w = await prisma().workspace.update({
-    where: { id: workspaceId },
-    data: { onboardingStep },
-    include: { secrets: true },
-  })
-
-  return transformSecrets(w)
-}
-
 export async function createWorkspace(
   wData: WorkspaceCreateInput,
   ownerId: string,
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index 45190338..353b2671 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -760,16 +760,6 @@ export function isInvalidVisualizationFilter(
   )
 }
 
-export const OnboardingStep = z.union([
-  z.literal('intro'),
-  z.literal('connectDataSource'),
-  z.literal('activateTrial'),
-  z.literal('joinSlack'),
-  z.literal('done'),
-])
-
-export type OnboardingStep = z.infer<typeof OnboardingStep>
-
 export const DataSourceColumn = z.object({
   name: z.string(),
   type: z.string(),
@@ -1199,3 +1189,27 @@ export enum ElementType {
   Block = 'BLOCK',
   BlockGroup = 'BLOCK_GROUP',
 }
+
+export type TutorialStepStatus = 'current' | 'completed' | 'upcoming'
+export const OnboardingTutorialStep = z.enum([
+  'connectDataSource',
+  'runQuery',
+  'runPython',
+  'createVisualization',
+  'publishDashboard',
+  'inviteTeamMembers',
+])
+
+export type OnboardingTutorialStep = z.infer<typeof OnboardingTutorialStep>
+
+export const TutorialStepStatus = z.enum(['current', 'completed', 'upcoming'])
+export type TutorialStepStatus = z.infer<typeof TutorialStepStatus>
+
+export type StepStates = Record<OnboardingTutorialStep, TutorialStepStatus>
+
+export type TutorialState = {
+  id: string
+  isCompleted: boolean
+  isDismissed: boolean
+  stepStates: StepStates
+}