diff --git a/.gitignore b/.gitignore
index 8fe2a9d1..cfb5aab2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -220,6 +220,12 @@ frontend/playwright-report/
frontend/test-results/
frontend/e2e/.auth/
+# Superpowers brainstorming mockups
+.superpowers/
+
+# Test results (root level)
+test-results/
+
# Railway CLI (local tooling)
node_modules/
package.json
diff --git a/backend/Dockerfile b/backend/Dockerfile
index 0bccd57a..1cbc6ea6 100644
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@ -6,6 +6,10 @@ WORKDIR /app
RUN apt-get update && apt-get install -y \
gcc \
libpq-dev \
+ libpango1.0-dev \
+ libcairo2-dev \
+ libgdk-pixbuf-2.0-dev \
+ libffi-dev \
&& rm -rf /var/lib/apt/lists/*
# Install Python dependencies
diff --git a/backend/alembic/versions/21ddb46ddd05_add_onboarding_and_branding_columns.py b/backend/alembic/versions/21ddb46ddd05_add_onboarding_and_branding_columns.py
new file mode 100644
index 00000000..4627141a
--- /dev/null
+++ b/backend/alembic/versions/21ddb46ddd05_add_onboarding_and_branding_columns.py
@@ -0,0 +1,41 @@
+"""add onboarding and branding columns
+
+Revision ID: 21ddb46ddd05
+Revises: 061
+Create Date: 2026-03-16 23:30:48.910485
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '21ddb46ddd05'
+down_revision: Union[str, None] = '061'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ # Users: onboarding + branding columns
+ op.add_column('users', sa.Column('onboarding_dismissed', sa.Boolean(), server_default='false', nullable=False))
+ op.add_column('users', sa.Column('logo_data', sa.Text(), nullable=True))
+ op.add_column('users', sa.Column('logo_content_type', sa.String(length=50), nullable=True))
+ op.add_column('users', sa.Column('company_display_name', sa.String(length=255), nullable=True))
+
+ # Teams: branding columns
+ op.add_column('teams', sa.Column('logo_data', sa.Text(), nullable=True))
+ op.add_column('teams', sa.Column('logo_content_type', sa.String(length=50), nullable=True))
+ op.add_column('teams', sa.Column('company_display_name', sa.String(length=255), nullable=True))
+
+
+def downgrade() -> None:
+ op.drop_column('teams', 'company_display_name')
+ op.drop_column('teams', 'logo_content_type')
+ op.drop_column('teams', 'logo_data')
+ op.drop_column('users', 'company_display_name')
+ op.drop_column('users', 'logo_content_type')
+ op.drop_column('users', 'logo_data')
+ op.drop_column('users', 'onboarding_dismissed')
diff --git a/backend/alembic/versions/ee98013dd18c_add_session_supporting_data_table.py b/backend/alembic/versions/ee98013dd18c_add_session_supporting_data_table.py
new file mode 100644
index 00000000..9a4ecdef
--- /dev/null
+++ b/backend/alembic/versions/ee98013dd18c_add_session_supporting_data_table.py
@@ -0,0 +1,41 @@
+"""add session_supporting_data table
+
+Revision ID: ee98013dd18c
+Revises: 21ddb46ddd05
+Create Date: 2026-03-16 23:31:43.483511
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'ee98013dd18c'
+down_revision: Union[str, None] = '21ddb46ddd05'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ op.create_table('session_supporting_data',
+ sa.Column('id', sa.UUID(), nullable=False),
+ sa.Column('session_id', sa.UUID(), nullable=False),
+ sa.Column('label', sa.String(length=255), nullable=False),
+ sa.Column('data_type', sa.Enum('text_snippet', 'screenshot', name='supporting_data_type'), nullable=False),
+ sa.Column('content', sa.Text(), nullable=False),
+ sa.Column('content_type', sa.String(length=50), nullable=True),
+ sa.Column('sort_order', sa.Integer(), nullable=False),
+ sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
+ sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
+ sa.ForeignKeyConstraint(['session_id'], ['sessions.id'], ondelete='CASCADE'),
+ sa.PrimaryKeyConstraint('id'),
+ )
+ op.create_index(op.f('ix_session_supporting_data_session_id'), 'session_supporting_data', ['session_id'], unique=False)
+
+
+def downgrade() -> None:
+ op.drop_index(op.f('ix_session_supporting_data_session_id'), table_name='session_supporting_data')
+ op.drop_table('session_supporting_data')
+ op.execute("DROP TYPE IF EXISTS supporting_data_type")
diff --git a/backend/app/api/endpoints/branding.py b/backend/app/api/endpoints/branding.py
new file mode 100644
index 00000000..7e22b2f7
--- /dev/null
+++ b/backend/app/api/endpoints/branding.py
@@ -0,0 +1,130 @@
+"""Team branding endpoints — logo upload and company display name."""
+
+import base64
+from typing import Annotated, Optional
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_current_active_user, get_db
+from app.models.team import Team
+from app.models.user import User
+from app.schemas.branding import BrandingResponse
+
+router = APIRouter(prefix="/teams", tags=["branding"])
+
+ALLOWED_CONTENT_TYPES = {"image/png", "image/jpeg", "image/svg+xml"}
+MAX_LOGO_SIZE = 2 * 1024 * 1024 # 2MB
+
+
+def _require_team_member(user: User, team_id: UUID) -> None:
+ """Ensure the user belongs to the given team (or is super admin)."""
+ if user.is_super_admin:
+ return
+ if user.team_id != team_id:
+ raise HTTPException(status_code=403, detail="Not a member of this team")
+
+
+def _require_team_admin(user: User, team_id: UUID) -> None:
+ """Ensure the user is a team admin for the given team (or is super admin)."""
+ if user.is_super_admin:
+ return
+ if not user.is_team_admin or user.team_id != team_id:
+ raise HTTPException(status_code=403, detail="Team admin required")
+
+
+@router.get("/{team_id}/branding", response_model=BrandingResponse)
+async def get_branding(
+ team_id: UUID,
+ db: Annotated[AsyncSession, Depends(get_db)],
+ current_user: Annotated[User, Depends(get_current_active_user)],
+) -> BrandingResponse:
+ """Retrieve branding info for a team. Any team member can read."""
+ _require_team_member(current_user, team_id)
+
+ result = await db.execute(select(Team).where(Team.id == team_id))
+ team = result.scalar_one_or_none()
+ if not team:
+ raise HTTPException(status_code=404, detail="Team not found")
+
+ return BrandingResponse(
+ company_display_name=team.company_display_name,
+ logo_content_type=team.logo_content_type,
+ has_logo=team.logo_data is not None,
+ )
+
+
+@router.patch("/{team_id}/branding", response_model=BrandingResponse)
+async def update_branding(
+ team_id: UUID,
+ db: Annotated[AsyncSession, Depends(get_db)],
+ current_user: Annotated[User, Depends(get_current_active_user)],
+ logo: Annotated[Optional[UploadFile], File()] = None,
+ company_display_name: Annotated[Optional[str], Form()] = None,
+) -> BrandingResponse:
+ """Upload logo and/or update company display name. Team admin only."""
+ _require_team_admin(current_user, team_id)
+
+ result = await db.execute(select(Team).where(Team.id == team_id))
+ team = result.scalar_one_or_none()
+ if not team:
+ raise HTTPException(status_code=404, detail="Team not found")
+
+ # Handle logo upload
+ if logo is not None:
+ if logo.content_type not in ALLOWED_CONTENT_TYPES:
+ raise HTTPException(
+ status_code=400,
+ detail=f"Invalid content type '{logo.content_type}'. Allowed: {', '.join(sorted(ALLOWED_CONTENT_TYPES))}",
+ )
+
+ raw_bytes = await logo.read()
+ if len(raw_bytes) > MAX_LOGO_SIZE:
+ raise HTTPException(
+ status_code=400,
+ detail=f"Logo exceeds maximum size of {MAX_LOGO_SIZE // (1024 * 1024)}MB",
+ )
+
+ team.logo_data = base64.b64encode(raw_bytes).decode("utf-8")
+ team.logo_content_type = logo.content_type
+
+ # Handle display name update
+ if company_display_name is not None:
+ team.company_display_name = company_display_name
+
+ await db.commit()
+ await db.refresh(team)
+
+ return BrandingResponse(
+ company_display_name=team.company_display_name,
+ logo_content_type=team.logo_content_type,
+ has_logo=team.logo_data is not None,
+ )
+
+
+@router.delete("/{team_id}/branding/logo", status_code=200, response_model=BrandingResponse)
+async def delete_logo(
+ team_id: UUID,
+ db: Annotated[AsyncSession, Depends(get_db)],
+ current_user: Annotated[User, Depends(get_current_active_user)],
+) -> BrandingResponse:
+ """Remove the team logo. Team admin only."""
+ _require_team_admin(current_user, team_id)
+
+ result = await db.execute(select(Team).where(Team.id == team_id))
+ team = result.scalar_one_or_none()
+ if not team:
+ raise HTTPException(status_code=404, detail="Team not found")
+
+ team.logo_data = None
+ team.logo_content_type = None
+ await db.commit()
+ await db.refresh(team)
+
+ return BrandingResponse(
+ company_display_name=team.company_display_name,
+ logo_content_type=team.logo_content_type,
+ has_logo=False,
+ )
diff --git a/backend/app/api/endpoints/onboarding.py b/backend/app/api/endpoints/onboarding.py
new file mode 100644
index 00000000..fdb07cd8
--- /dev/null
+++ b/backend/app/api/endpoints/onboarding.py
@@ -0,0 +1,110 @@
+"""Onboarding status endpoints — track new-user checklist progress."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_current_active_user
+from app.core.database import get_db
+from app.models.assistant_chat import AssistantChat
+from app.models.psa_connection import PsaConnection
+from app.models.session import Session
+from app.models.tree import Tree
+from app.models.user import User
+from app.schemas.onboarding import OnboardingStatus
+
+router = APIRouter(prefix="/users", tags=["onboarding"])
+
+
+@router.get("/onboarding-status", response_model=OnboardingStatus)
+async def get_onboarding_status(
+ db: Annotated[AsyncSession, Depends(get_db)],
+ current_user: Annotated[User, Depends(get_current_active_user)],
+) -> OnboardingStatus:
+ """Return onboarding checklist completion status for the current user."""
+
+ # created_flow — user owns at least 1 tree
+ created_flow_q = await db.execute(
+ select(func.count()).select_from(Tree).where(Tree.author_id == current_user.id).limit(1)
+ )
+ created_flow = (created_flow_q.scalar() or 0) > 0
+
+ # ran_session — user has at least 1 session
+ ran_session_q = await db.execute(
+ select(func.count()).select_from(Session).where(Session.user_id == current_user.id).limit(1)
+ )
+ ran_session = (ran_session_q.scalar() or 0) > 0
+
+ # exported_session — user has at least 1 session with exported=True
+ exported_q = await db.execute(
+ select(func.count())
+ .select_from(Session)
+ .where(Session.user_id == current_user.id, Session.exported == True) # noqa: E712
+ .limit(1)
+ )
+ exported_session = (exported_q.scalar() or 0) > 0
+
+ # tried_ai_assistant — user has at least 1 assistant chat
+ ai_q = await db.execute(
+ select(func.count())
+ .select_from(AssistantChat)
+ .where(AssistantChat.user_id == current_user.id)
+ .limit(1)
+ )
+ tried_ai_assistant = (ai_q.scalar() or 0) > 0
+
+ # Team-dependent checks
+ is_team_user = current_user.team_id is not None
+
+ invited_teammate = False
+ connected_psa = False
+
+ if is_team_user:
+ # invited_teammate — team/account has more than 1 member
+ if current_user.account_id:
+ teammate_q = await db.execute(
+ select(func.count())
+ .select_from(User)
+ .where(
+ User.account_id == current_user.account_id,
+ User.deleted_at.is_(None),
+ )
+ )
+ invited_teammate = (teammate_q.scalar() or 0) > 1
+
+ # connected_psa — account has at least 1 PSA connection
+ if current_user.account_id:
+ psa_q = await db.execute(
+ select(func.count())
+ .select_from(PsaConnection)
+ .where(PsaConnection.account_id == current_user.account_id)
+ .limit(1)
+ )
+ connected_psa = (psa_q.scalar() or 0) > 0
+
+ return OnboardingStatus(
+ created_flow=created_flow,
+ ran_session=ran_session,
+ exported_session=exported_session,
+ tried_ai_assistant=tried_ai_assistant,
+ invited_teammate=invited_teammate,
+ connected_psa=connected_psa,
+ is_team_user=is_team_user,
+ dismissed=current_user.onboarding_dismissed,
+ )
+
+
+@router.post("/onboarding-status/dismiss", response_model=OnboardingStatus)
+async def dismiss_onboarding(
+ db: Annotated[AsyncSession, Depends(get_db)],
+ current_user: Annotated[User, Depends(get_current_active_user)],
+) -> OnboardingStatus:
+ """Dismiss the onboarding checklist for the current user."""
+ current_user.onboarding_dismissed = True
+ await db.commit()
+ await db.refresh(current_user)
+
+ # Return updated status (reuse the GET logic)
+ return await get_onboarding_status(db=db, current_user=current_user)
diff --git a/backend/app/api/endpoints/sessions.py b/backend/app/api/endpoints/sessions.py
index e0e303a2..ea4375f1 100644
--- a/backend/app/api/endpoints/sessions.py
+++ b/backend/app/api/endpoints/sessions.py
@@ -391,18 +391,51 @@ async def export_session(
detail="You don't have access to this session"
)
+ # PDF export — separate path with binary response
+ if export_options.format == "pdf":
+ from app.services.export_service import generate_pdf_export
+ from fastapi.responses import Response
+ pdf_bytes = await generate_pdf_export(session, export_options, db)
+
+ if session.completed_at:
+ session.exported = True
+ await db.commit()
+
+ return Response(
+ content=pdf_bytes,
+ media_type="application/pdf",
+ headers={"Content-Disposition": f'attachment; filename="session-export-{session_id}.pdf"'},
+ )
+
+ # Query supporting data for non-PDF formats
+ from app.models.supporting_data import SessionSupportingData
+ sd_result = await db.execute(
+ select(SessionSupportingData)
+ .where(SessionSupportingData.session_id == session_id)
+ .order_by(SessionSupportingData.sort_order)
+ )
+ supporting_data_items = [
+ {
+ "label": sd.label,
+ "data_type": sd.data_type,
+ "content": sd.content,
+ "content_type": sd.content_type,
+ }
+ for sd in sd_result.scalars().all()
+ ]
+
# Generate export based on format
if export_options.format == "markdown":
- content = generate_markdown_export(session, export_options)
+ content = generate_markdown_export(session, export_options, supporting_data=supporting_data_items)
media_type = "text/markdown"
elif export_options.format == "html":
- content = generate_html_export(session, export_options)
+ content = generate_html_export(session, export_options, supporting_data=supporting_data_items)
media_type = "text/html"
elif export_options.format == "psa":
- content = generate_psa_export(session, export_options)
+ content = generate_psa_export(session, export_options, supporting_data=supporting_data_items)
media_type = "text/plain"
else: # text
- content = generate_text_export(session, export_options)
+ content = generate_text_export(session, export_options, supporting_data=supporting_data_items)
media_type = "text/plain"
# Resolve variables in export output
diff --git a/backend/app/api/endpoints/supporting_data.py b/backend/app/api/endpoints/supporting_data.py
new file mode 100644
index 00000000..b7d0a33a
--- /dev/null
+++ b/backend/app/api/endpoints/supporting_data.py
@@ -0,0 +1,201 @@
+import base64
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select, func
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.database import get_db
+from app.api.deps import get_current_active_user
+from app.models import User
+from app.models.session import Session
+from app.models.supporting_data import SessionSupportingData
+from app.schemas.supporting_data import (
+ SupportingDataCreate,
+ SupportingDataUpdate,
+ SupportingDataResponse,
+)
+
+router = APIRouter(prefix="/sessions", tags=["supporting-data"])
+
+MAX_ITEMS_PER_SESSION = 20
+MAX_TEXT_SNIPPET_CHARS = 50_000
+MAX_SCREENSHOT_RAW_BYTES = 2 * 1024 * 1024 # 2MB
+
+
+async def _check_session_access(user: User, session: Session, db: AsyncSession) -> None:
+ """Verify user has access to the session (owner, team admin, or super admin)."""
+ if user.is_super_admin:
+ return
+ if session.user_id == user.id:
+ return
+ # Team admins can only access sessions from their own team members
+ if user.is_team_admin and user.team_id is not None:
+ session_owner = await db.get(User, session.user_id)
+ if session_owner and session_owner.team_id == user.team_id:
+ return
+ raise HTTPException(status_code=403, detail="Access denied")
+
+
+async def _get_session_or_404(session_id: UUID, db: AsyncSession) -> Session:
+ """Fetch session by ID or raise 404."""
+ result = await db.execute(select(Session).where(Session.id == session_id))
+ session = result.scalar_one_or_none()
+ if not session:
+ raise HTTPException(status_code=404, detail="Session not found")
+ return session
+
+
+@router.post(
+ "/{session_id}/supporting-data",
+ response_model=SupportingDataResponse,
+ status_code=status.HTTP_201_CREATED,
+)
+async def create_supporting_data(
+ session_id: UUID,
+ data: SupportingDataCreate,
+ db: AsyncSession = Depends(get_db),
+ current_user: User = Depends(get_current_active_user),
+):
+ """Add a supporting data item (text snippet or screenshot) to a session."""
+ session = await _get_session_or_404(session_id, db)
+ await _check_session_access(current_user, session, db)
+
+ # Check item limit
+ count_result = await db.execute(
+ select(func.count()).select_from(SessionSupportingData).where(
+ SessionSupportingData.session_id == session_id
+ )
+ )
+ current_count = count_result.scalar() or 0
+ if current_count >= MAX_ITEMS_PER_SESSION:
+ raise HTTPException(
+ status_code=400,
+ detail=f"Maximum {MAX_ITEMS_PER_SESSION} supporting data items per session",
+ )
+
+ # Validate content size based on type
+ if data.data_type == "text_snippet":
+ if len(data.content) > MAX_TEXT_SNIPPET_CHARS:
+ raise HTTPException(
+ status_code=400,
+ detail=f"Text snippet exceeds maximum {MAX_TEXT_SNIPPET_CHARS} characters",
+ )
+ elif data.data_type == "screenshot":
+ try:
+ raw_bytes = base64.b64decode(data.content)
+ except Exception:
+ raise HTTPException(status_code=400, detail="Invalid base64 content for screenshot")
+ if len(raw_bytes) > MAX_SCREENSHOT_RAW_BYTES:
+ raise HTTPException(
+ status_code=400,
+ detail=f"Screenshot exceeds maximum {MAX_SCREENSHOT_RAW_BYTES // (1024 * 1024)}MB raw size",
+ )
+
+ # Auto-increment sort_order
+ max_order_result = await db.execute(
+ select(func.max(SessionSupportingData.sort_order)).where(
+ SessionSupportingData.session_id == session_id
+ )
+ )
+ max_order = max_order_result.scalar()
+ next_order = (max_order or 0) + 1
+
+ item = SessionSupportingData(
+ session_id=session_id,
+ label=data.label,
+ data_type=data.data_type,
+ content=data.content,
+ content_type=data.content_type,
+ sort_order=next_order,
+ )
+ db.add(item)
+ await db.commit()
+ await db.refresh(item)
+
+ return item
+
+
+@router.get(
+ "/{session_id}/supporting-data",
+ response_model=list[SupportingDataResponse],
+)
+async def list_supporting_data(
+ session_id: UUID,
+ db: AsyncSession = Depends(get_db),
+ current_user: User = Depends(get_current_active_user),
+):
+ """List all supporting data items for a session, ordered by sort_order."""
+ session = await _get_session_or_404(session_id, db)
+ await _check_session_access(current_user, session, db)
+
+ result = await db.execute(
+ select(SessionSupportingData)
+ .where(SessionSupportingData.session_id == session_id)
+ .order_by(SessionSupportingData.sort_order)
+ )
+ return result.scalars().all()
+
+
+@router.patch(
+ "/{session_id}/supporting-data/{item_id}",
+ response_model=SupportingDataResponse,
+)
+async def update_supporting_data(
+ session_id: UUID,
+ item_id: UUID,
+ data: SupportingDataUpdate,
+ db: AsyncSession = Depends(get_db),
+ current_user: User = Depends(get_current_active_user),
+):
+ """Update a supporting data item's label or content."""
+ session = await _get_session_or_404(session_id, db)
+ await _check_session_access(current_user, session, db)
+
+ result = await db.execute(
+ select(SessionSupportingData).where(
+ SessionSupportingData.id == item_id,
+ SessionSupportingData.session_id == session_id,
+ )
+ )
+ item = result.scalar_one_or_none()
+ if not item:
+ raise HTTPException(status_code=404, detail="Supporting data item not found")
+
+ if data.label is not None:
+ item.label = data.label
+ if data.content is not None:
+ item.content = data.content
+
+ await db.commit()
+ await db.refresh(item)
+
+ return item
+
+
+@router.delete(
+ "/{session_id}/supporting-data/{item_id}",
+ status_code=status.HTTP_204_NO_CONTENT,
+)
+async def delete_supporting_data(
+ session_id: UUID,
+ item_id: UUID,
+ db: AsyncSession = Depends(get_db),
+ current_user: User = Depends(get_current_active_user),
+):
+ """Remove a supporting data item from a session."""
+ session = await _get_session_or_404(session_id, db)
+ await _check_session_access(current_user, session, db)
+
+ result = await db.execute(
+ select(SessionSupportingData).where(
+ SessionSupportingData.id == item_id,
+ SessionSupportingData.session_id == session_id,
+ )
+ )
+ item = result.scalar_one_or_none()
+ if not item:
+ raise HTTPException(status_code=404, detail="Supporting data item not found")
+
+ await db.delete(item)
+ await db.commit()
diff --git a/backend/app/api/router.py b/backend/app/api/router.py
index 3bc9afde..e857bd20 100644
--- a/backend/app/api/router.py
+++ b/backend/app/api/router.py
@@ -18,6 +18,9 @@ from app.api.endpoints import kb_accelerator
from app.api.endpoints import beta_signup
from app.api.endpoints import scripts
from app.api.endpoints import integrations
+from app.api.endpoints import onboarding
+from app.api.endpoints import branding
+from app.api.endpoints import supporting_data
api_router = APIRouter()
@@ -61,3 +64,6 @@ api_router.include_router(kb_accelerator.router)
api_router.include_router(beta_signup.router)
api_router.include_router(scripts.router)
api_router.include_router(integrations.router)
+api_router.include_router(onboarding.router)
+api_router.include_router(branding.router)
+api_router.include_router(supporting_data.router)
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index 1938cdf0..b7854b0b 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -39,6 +39,7 @@ from .script_template import ScriptCategory, ScriptTemplate, ScriptGeneration
from .psa_connection import PsaConnection
from .psa_post_log import PsaPostLog
from .psa_member_mapping import PsaMemberMapping
+from .supporting_data import SessionSupportingData
__all__ = [
"User",
@@ -92,4 +93,5 @@ __all__ = [
"PsaConnection",
"PsaPostLog",
"PsaMemberMapping",
+ "SessionSupportingData",
]
diff --git a/backend/app/models/session.py b/backend/app/models/session.py
index bbab74cf..c191572b 100644
--- a/backend/app/models/session.py
+++ b/backend/app/models/session.py
@@ -82,6 +82,7 @@ class Session(Base):
assigned_to: Mapped[Optional["User"]] = relationship("User", foreign_keys=[assigned_to_id])
attachments: Mapped[list["Attachment"]] = relationship("Attachment", back_populates="session")
shares: Mapped[list["SessionShare"]] = relationship("SessionShare", back_populates="session", cascade="all, delete-orphan")
+ supporting_data = relationship("SessionSupportingData", back_populates="session", cascade="all, delete-orphan", order_by="SessionSupportingData.sort_order")
# PSA ticket link
psa_ticket_id: Mapped[Optional[str]] = mapped_column(String(100), nullable=True)
diff --git a/backend/app/models/supporting_data.py b/backend/app/models/supporting_data.py
new file mode 100644
index 00000000..ea04cd91
--- /dev/null
+++ b/backend/app/models/supporting_data.py
@@ -0,0 +1,25 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+from sqlalchemy import DateTime, Enum, ForeignKey, Integer, String, Text
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.core.database import Base
+
+
+class SessionSupportingData(Base):
+ __tablename__ = "session_supporting_data"
+
+ id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+ session_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("sessions.id", ondelete="CASCADE"), nullable=False, index=True)
+ label: Mapped[str] = mapped_column(String(255), nullable=False)
+ data_type: Mapped[str] = mapped_column(Enum("text_snippet", "screenshot", name="supporting_data_type"), nullable=False)
+ content: Mapped[str] = mapped_column(Text, nullable=False)
+ content_type: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)
+ sort_order: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+ created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False)
+ updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), onupdate=lambda: datetime.now(timezone.utc), nullable=False)
+
+ session = relationship("Session", back_populates="supporting_data")
diff --git a/backend/app/models/team.py b/backend/app/models/team.py
index 299c9cb9..098444dd 100644
--- a/backend/app/models/team.py
+++ b/backend/app/models/team.py
@@ -1,7 +1,7 @@
import uuid
from datetime import datetime, timezone
-from typing import TYPE_CHECKING
-from sqlalchemy import String, DateTime
+from typing import Optional, TYPE_CHECKING
+from sqlalchemy import String, DateTime, Text
from sqlalchemy.orm import Mapped, mapped_column, relationship
from sqlalchemy.dialects.postgresql import UUID
from app.core.database import Base
@@ -23,6 +23,12 @@ class Team(Base):
default=uuid.uuid4
)
name: Mapped[str] = mapped_column(String(255), nullable=False)
+
+ # Branding
+ logo_data: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+ logo_content_type: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)
+ company_display_name: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
+
created_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True),
default=lambda: datetime.now(timezone.utc)
diff --git a/backend/app/models/user.py b/backend/app/models/user.py
index f0c3f3f6..c7d566d7 100644
--- a/backend/app/models/user.py
+++ b/backend/app/models/user.py
@@ -1,7 +1,7 @@
import uuid
from datetime import datetime, timezone
from typing import Optional, TYPE_CHECKING
-from sqlalchemy import String, DateTime, ForeignKey, Boolean, CheckConstraint
+from sqlalchemy import String, DateTime, ForeignKey, Boolean, CheckConstraint, Text
from sqlalchemy.orm import Mapped, mapped_column, relationship
from sqlalchemy.dialects.postgresql import UUID
from app.core.database import Base
@@ -73,6 +73,15 @@ class User(Base):
job_title: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
timezone: Mapped[str] = mapped_column(String(100), nullable=False, default="UTC", server_default="UTC")
avatar_url: Mapped[Optional[str]] = mapped_column(String(500), nullable=True)
+
+ # Onboarding
+ onboarding_dismissed: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False, server_default="false")
+
+ # Branding (solo pros without a team)
+ logo_data: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+ logo_content_type: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)
+ company_display_name: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
+
email_verified_at: Mapped[Optional[datetime]] = mapped_column(
DateTime(timezone=True), nullable=True
)
diff --git a/backend/app/schemas/branding.py b/backend/app/schemas/branding.py
new file mode 100644
index 00000000..bd6baeaf
--- /dev/null
+++ b/backend/app/schemas/branding.py
@@ -0,0 +1,14 @@
+from typing import Optional
+from pydantic import BaseModel
+
+
+class BrandingResponse(BaseModel):
+ company_display_name: Optional[str] = None
+ logo_content_type: Optional[str] = None
+ has_logo: bool = False
+
+
+class BrandingLogoResponse(BaseModel):
+ company_display_name: Optional[str] = None
+ logo_data: Optional[str] = None
+ logo_content_type: Optional[str] = None
diff --git a/backend/app/schemas/onboarding.py b/backend/app/schemas/onboarding.py
new file mode 100644
index 00000000..d21647b5
--- /dev/null
+++ b/backend/app/schemas/onboarding.py
@@ -0,0 +1,12 @@
+from pydantic import BaseModel
+
+
+class OnboardingStatus(BaseModel):
+ created_flow: bool
+ ran_session: bool
+ exported_session: bool
+ tried_ai_assistant: bool
+ invited_teammate: bool
+ connected_psa: bool
+ is_team_user: bool
+ dismissed: bool
diff --git a/backend/app/schemas/session.py b/backend/app/schemas/session.py
index 58f4e2df..2a764711 100644
--- a/backend/app/schemas/session.py
+++ b/backend/app/schemas/session.py
@@ -106,7 +106,7 @@ class SessionResponse(BaseModel):
class SessionExport(BaseModel):
- format: str = Field(default="markdown", pattern="^(text|markdown|html|psa)$")
+ format: str = Field(default="markdown", pattern="^(text|markdown|html|psa|pdf)$")
include_timestamps: bool = True
include_tree_info: bool = True
# Phase A
diff --git a/backend/app/schemas/supporting_data.py b/backend/app/schemas/supporting_data.py
new file mode 100644
index 00000000..7469fab8
--- /dev/null
+++ b/backend/app/schemas/supporting_data.py
@@ -0,0 +1,30 @@
+from datetime import datetime
+from typing import Literal, Optional
+from uuid import UUID
+from pydantic import BaseModel, Field
+
+
+class SupportingDataCreate(BaseModel):
+ label: str = Field(..., min_length=1, max_length=255)
+ data_type: Literal["text_snippet", "screenshot"]
+ content: str = Field(..., min_length=1, max_length=5_000_000)
+ content_type: Optional[str] = Field(None, max_length=50)
+
+
+class SupportingDataUpdate(BaseModel):
+ label: Optional[str] = Field(None, min_length=1, max_length=255)
+ content: Optional[str] = Field(None, min_length=1)
+
+
+class SupportingDataResponse(BaseModel):
+ id: UUID
+ session_id: UUID
+ label: str
+ data_type: str
+ content: str
+ content_type: Optional[str]
+ sort_order: int
+ created_at: datetime
+ updated_at: datetime
+
+ model_config = {"from_attributes": True}
diff --git a/backend/app/schemas/user.py b/backend/app/schemas/user.py
index 496c46e9..a48df65b 100644
--- a/backend/app/schemas/user.py
+++ b/backend/app/schemas/user.py
@@ -46,6 +46,7 @@ class UserResponse(UserBase):
role: str = "engineer"
account_id: Optional[UUID] = None
account_role: Optional[str] = None
+ team_id: Optional[UUID] = None
is_super_admin: bool = False
is_active: bool = True
must_change_password: bool = False
diff --git a/backend/app/services/export_service.py b/backend/app/services/export_service.py
index 8654eb89..7d3d8091 100644
--- a/backend/app/services/export_service.py
+++ b/backend/app/services/export_service.py
@@ -1,11 +1,13 @@
"""
Session export generators for ResolutionFlow.
-Provides markdown, plain text, HTML, and PSA/ticket note export formatters
+Provides markdown, plain text, HTML, PDF, and PSA/ticket note export formatters
for troubleshooting sessions.
"""
import html
+import os
from datetime import datetime
+from pathlib import Path
from typing import Any
from app.models.session import Session
@@ -169,7 +171,7 @@ def _escape_markdown_table(value: str) -> str:
return value.replace("|", "\\|").replace("\n", " ")
-def generate_markdown_export(session: Session, options: SessionExport) -> str:
+def generate_markdown_export(session: Session, options: SessionExport, supporting_data: list[dict] | None = None) -> str:
"""Generate markdown export."""
if _is_procedural_session(session):
return _generate_procedural_markdown(session, options)
@@ -259,6 +261,22 @@ def generate_markdown_export(session: Session, options: SessionExport) -> str:
lines.append(f"*{decision['timestamp']}*")
lines.append("")
+ # Supporting Data
+ if supporting_data:
+ lines.append("---")
+ lines.append("")
+ lines.append("## Supporting Data")
+ lines.append("")
+ for sd in supporting_data:
+ lines.append(f"### {sd['label']}")
+ if sd["data_type"] == "text_snippet":
+ lines.append("```")
+ lines.append(sd["content"])
+ lines.append("```")
+ else:
+ lines.append(f"[Screenshot: {sd['label']}]")
+ lines.append("")
+
# Resolution / Outcome Notes
_raw_notes = getattr(session, 'outcome_notes', None)
outcome_notes = _raw_notes if isinstance(_raw_notes, str) else ''
@@ -284,7 +302,7 @@ def generate_markdown_export(session: Session, options: SessionExport) -> str:
return "\n".join(lines)
-def generate_text_export(session: Session, options: SessionExport) -> str:
+def generate_text_export(session: Session, options: SessionExport, supporting_data: list[dict] | None = None) -> str:
"""Generate plain text export."""
if _is_procedural_session(session):
return _generate_procedural_text(session, options)
@@ -359,6 +377,19 @@ def generate_text_export(session: Session, options: SessionExport) -> str:
if duration_seconds is not None:
lines.append(f" Duration: {_format_step_duration(duration_seconds)}")
+ # Supporting Data
+ if supporting_data:
+ lines.append("")
+ lines.append("SUPPORTING DATA")
+ lines.append("-" * 20)
+ for sd in supporting_data:
+ lines.append(f"\n {sd['label']}:")
+ if sd["data_type"] == "text_snippet":
+ for content_line in sd["content"].splitlines():
+ lines.append(f" {content_line}")
+ else:
+ lines.append(f" [Screenshot: {sd['label']}]")
+
# Resolution
_raw_notes = getattr(session, 'outcome_notes', None)
outcome_notes = _raw_notes if isinstance(_raw_notes, str) else ''
@@ -380,7 +411,7 @@ def generate_text_export(session: Session, options: SessionExport) -> str:
return "\n".join(lines)
-def generate_html_export(session: Session, options: SessionExport) -> str:
+def generate_html_export(session: Session, options: SessionExport, supporting_data: list[dict] | None = None) -> str:
"""Generate HTML export."""
if _is_procedural_session(session):
return _generate_procedural_html(session, options)
@@ -470,6 +501,15 @@ def generate_html_export(session: Session, options: SessionExport) -> str:
html_parts.append(f'{html.escape(str(decision["timestamp"]))}
')
html_parts.append('')
+ # Supporting Data
+ if supporting_data:
+ html_parts.append('Supporting Data ')
+ for sd in supporting_data:
+ if sd["data_type"] == "text_snippet":
+ html_parts.append(f'{html.escape(sd["label"])} {html.escape(sd["content"])} {html.escape(sd["label"])}
+
Summary
+
{{ summary }}
+
+
Troubleshooting Path
+ {% for step in steps %}
+
+
+
{{ loop.index }}. {{ step.title }}
+ {% if step.decision %}
+
{{ step.decision }}
+ {% endif %}
+ {% if step.notes %}
+
{{ step.notes }}
+ {% endif %}
+ {% if step.duration %}
+
{{ step.duration }}
+ {% endif %}
+
+
+ {% endfor %}
+
+
Supporting Data
+ {% for item in supporting_data %}
+
+
{{ item.label }}
+
+ {% if item.data_type == "screenshot" %}
+
+ {% else %}
+
{{ item.content }}
+ {% endif %}
+
+
+ {% endfor %}
+
Summary
+{{ summary }}
+{% endif %}
+
+
+{% if steps %}
+Troubleshooting Path
+
+ {% for step in steps %}
+
+
+
{{ loop.index }}. {{ step.title }}
+ {% if step.decision %}
+
Decision: {{ step.decision }}
+ {% endif %}
+
+ {% endfor %}
+
+
Supporting Data
+ {% for item in supporting_data %}
+
+
{{ item.label }}
+ {% if item.data_type == "text_snippet" %}
+
{{ item.content }}
+ {% elif item.data_type == "screenshot" %}
+
+ {% endif %}
+
+ {% endfor %}
+
` blocks with labels
+- Screenshots: `
+ {illustration && (
+
+ {illustration}
+
+ )}
+ {!illustration && icon && (
+
{icon}
+ )}
+
{title}
+ {description && (
+
{description}
+ )}
+ {action &&
{action}
}
+ {learnMoreLink && (
+
+ {learnMoreText} →
+
+ )}
+
+
+ )
+}
+
+export function AnalyticsIllustration() {
+ return (
+
+
+ )
+}
+
+export function SessionIllustration() {
+ return (
+
+
+ )
+}
+
+export function IntegrationIllustration() {
+ return (
+
+
+ )
+}
+
+export function StepLibraryIllustration() {
+ return (
+
+
+ )
+}
+
+export function ScriptIllustration() {
+ return (
+
+ >
+
+ )
+}
+
+export function ShareIllustration() {
+ return (
+
+
+ )
+}
+```
+
+- [ ] **Step 3: Verify frontend build**
+
+Run: `cd frontend && npm run build`
+Expected: Build succeeds.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add frontend/src/components/common/EmptyState.tsx frontend/src/components/common/EmptyStateIllustrations.tsx
+git commit -m "feat: upgrade EmptyState component with illustration and learn more support"
+```
+
+---
+
+### Task 12: Roll Out Empty States Across Pages
+
+**Files:** 8 page files (see file structure above)
+
+- [ ] **Step 1: Update each page's empty state**
+
+For each page, update the empty state usage to include the new props (illustration, description, CTA, learnMoreLink). The specific edits depend on how each page currently renders its empty state — read each file and update the `` usage.
+
+**Pattern for each page:**
+
+```tsx
+import { FlowIllustration } from '@/components/common/EmptyStateIllustrations'
+
+// In the render:
+Create a Flow }
+ learnMoreLink="/guides/creating-flows"
+/>
+```
+
+Apply the correct illustration, title, description, CTA, and guide link from the spec table for each of the 8 pages.
+
+- [ ] **Step 2: Add empty states to pages that don't have them**
+
+For StepLibraryPage, ScriptLibraryPage, and the integrations page — add the `EmptyState` component where no data exists. Read each file first to understand the current rendering logic.
+
+- [ ] **Step 3: Verify frontend build**
+
+Run: `cd frontend && npm run build`
+Expected: Build succeeds with no TypeScript errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add frontend/src/pages/
+git commit -m "feat: roll out illustrative empty states across 8 pages"
+```
+
+---
+
+### Task 13: Create Guide Pages & Route
+
+**Files:**
+- Create: 7 guide component files in `frontend/src/pages/guides/`
+- Create: `frontend/src/pages/guides/GuidePage.tsx`
+- Modify: `frontend/src/router.tsx`
+
+- [ ] **Step 1: Create guide page wrapper**
+
+Create `frontend/src/pages/guides/GuidePage.tsx`:
+
+```tsx
+import { useParams, Link } from 'react-router-dom'
+import { ChevronRight } from 'lucide-react'
+import { EmptyState } from '@/components/common/EmptyState'
+import CreatingFlowsGuide from './CreatingFlowsGuide'
+import UnderstandingAnalyticsGuide from './UnderstandingAnalyticsGuide'
+import RunningSessionsGuide from './RunningSessionsGuide'
+import PsaSetupGuide from './PsaSetupGuide'
+import StepLibraryGuide from './StepLibraryGuide'
+import ScriptTemplatesGuide from './ScriptTemplatesGuide'
+import SharingSessionsGuide from './SharingSessionsGuide'
+
+const guides: Record = {
+ 'creating-flows': { title: 'Creating Flows', component: CreatingFlowsGuide },
+ 'understanding-analytics': { title: 'Understanding Analytics', component: UnderstandingAnalyticsGuide },
+ 'running-sessions': { title: 'Running Sessions', component: RunningSessionsGuide },
+ 'psa-setup': { title: 'Connecting Your PSA', component: PsaSetupGuide },
+ 'step-library': { title: 'Using the Step Library', component: StepLibraryGuide },
+ 'script-templates': { title: 'Script Templates', component: ScriptTemplatesGuide },
+ 'sharing-sessions': { title: 'Sharing Sessions', component: SharingSessionsGuide },
+}
+
+export default function GuidePage() {
+ const { slug } = useParams<{ slug: string }>()
+ const guide = slug ? guides[slug] : undefined
+
+ if (!guide) {
+ return (
+
+ Back to Dashboard
+
+ }
+ />
+ )
+ }
+
+ const GuideContent = guide.component
+
+ return (
+
+
+ {guide.title}
+
+
+
+
+ Creating Flows
+
+ Flows are the core of ResolutionFlow — structured troubleshooting paths that guide your team
+ through proven resolution steps.
+
+
+ Flow Types
+
+ Troubleshooting — Decision trees that branch based on what the engineer finds at each step.Projects — Step-by-step procedural guides for installations, migrations, and setups.Maintenance — Recurring check sequences you can schedule and run in batches.
+
+ Creating a Flow Manually
+
+ Click "Create a Flow" from the Flow Library, choose your flow type, and start building
+ in the visual editor. Add decision nodes, connect paths, and define outcomes.
+
+
+ Using AI to Generate Flows
+
+ Describe your troubleshooting scenario in plain language and the AI assistant will generate
+ a complete flow structure. You can then refine it in the editor.
+
+
+
+
+
+ )
+}
+```
+
+Create the remaining 6 guides following the same pattern, tailored to their topic per the spec table. Keep each 300-600 words.
+
+- [ ] **Step 3: Add route to router.tsx**
+
+In `frontend/src/router.tsx`, add the guide route inside the protected children:
+
+```tsx
+{ path: 'guides/:slug', element: page(GuidePage) }
+```
+
+Add the lazy import at the top:
+```tsx
+const GuidePage = lazy(() => import('./pages/guides/GuidePage'))
+```
+
+- [ ] **Step 4: Verify frontend build**
+
+Run: `cd frontend && npm run build`
+Expected: Build succeeds.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/src/pages/guides/ frontend/src/router.tsx
+git commit -m "feat: add 7 in-app user guides with /guides/:slug route"
+```
+
+---
+
+### Task 14: EmptyState Vitest Tests
+
+**Files:**
+- Create: `frontend/src/components/common/__tests__/EmptyState.test.tsx`
+
+- [ ] **Step 1: Write tests**
+
+Create `frontend/src/components/common/__tests__/EmptyState.test.tsx`:
+
+```tsx
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { BrowserRouter } from 'react-router-dom'
+import { EmptyState } from '../EmptyState'
+import { FlowIllustration } from '../EmptyStateIllustrations'
+
+const wrapper = ({ children }: { children: React.ReactNode }) => (
+ {children}
+)
+
+describe('EmptyState', () => {
+ it('renders title and description', () => {
+ render(
+ Do Thing} />,
+ { wrapper }
+ )
+ expect(screen.getByText('Do Thing')).toBeInTheDocument()
+ })
+
+ it('renders learn more link', () => {
+ render(
+ {
+ const response = await apiClient.get('/users/onboarding-status')
+ return response.data
+}
+
+export async function dismissOnboarding(): Promise {
+ await apiClient.post('/users/onboarding-status/dismiss')
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add frontend/src/api/onboarding.ts
+git commit -m "feat: add onboarding status API client"
+```
+
+---
+
+### Task 17: OnboardingChecklist Component
+
+**Files:**
+- Create: `frontend/src/components/dashboard/OnboardingChecklist.tsx`
+
+- [ ] **Step 1: Create the component**
+
+Create `frontend/src/components/dashboard/OnboardingChecklist.tsx`:
+
+```tsx
+import { useEffect, useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { Check, X, ChevronRight } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { getOnboardingStatus, dismissOnboarding, OnboardingStatus } from '@/api/onboarding'
+
+interface ChecklistItem {
+ key: keyof OnboardingStatus
+ label: string
+ path: string
+}
+
+const SOLO_ITEMS: ChecklistItem[] = [
+ { key: 'created_flow', label: 'Create your first flow', path: '/trees' },
+ { key: 'ran_session', label: 'Run your first session', path: '/trees' },
+ { key: 'exported_session', label: 'Export a session', path: '/sessions' },
+ { key: 'tried_ai_assistant', label: 'Try the AI assistant', path: '/assistant' },
+]
+
+const TEAM_ITEMS: ChecklistItem[] = [
+ { key: 'created_flow', label: 'Create your first flow', path: '/trees' },
+ { key: 'invited_teammate', label: 'Invite a team member', path: '/account' },
+ { key: 'ran_session', label: 'Run your first session', path: '/trees' },
+ { key: 'connected_psa', label: 'Connect a PSA integration', path: '/account/integrations' },
+ { key: 'exported_session', label: 'Export a session', path: '/sessions' },
+]
+
+export function OnboardingChecklist() {
+ const [status, setStatus] = useState(null)
+ const [dismissed, setDismissed] = useState(false)
+ const [allComplete, setAllComplete] = useState(false)
+ const navigate = useNavigate()
+
+ useEffect(() => {
+ getOnboardingStatus()
+ .then(setStatus)
+ .catch(() => {})
+ }, [])
+
+ if (!status || status.dismissed || dismissed) return null
+
+ const items = status.is_team_user ? TEAM_ITEMS : SOLO_ITEMS
+ const completedCount = items.filter((item) => status[item.key]).length
+ const totalCount = items.length
+ const isAllDone = completedCount === totalCount
+
+ // Show "all set" briefly then auto-hide after 2 seconds
+ useEffect(() => {
+ if (isAllDone) {
+ const timer = setTimeout(() => setAllComplete(true), 2000)
+ return () => clearTimeout(timer)
+ }
+ }, [isAllDone])
+
+ if (allComplete) return null
+
+ const handleDismiss = async () => {
+ setDismissed(true)
+ await dismissOnboarding().catch(() => {})
+ }
+
+ return (
+
+ {/* Progress bar */}
+
+
+
+
+
+ Getting Started
+
+
+ {isAllDone ? "You're all set!" : `${completedCount} of ${totalCount} complete`}
+
+
+
+
+
+
+
+ {items.map((item) => {
+ const isComplete = status[item.key]
+ return (
+
!isComplete && navigate(item.path)}
+ className={cn(
+ 'flex w-full items-center gap-3 rounded-lg px-3 py-2 text-left text-sm transition-colors',
+ isComplete
+ ? 'text-muted-foreground cursor-default'
+ : 'text-foreground hover:bg-[rgba(255,255,255,0.04)]'
+ )}
+ >
+
+ {isComplete &&
+ {item.label}
+ {!isComplete && (
+
+ )
+ })}
+
+
{
+ const response = await apiClient.get(`/sessions/${sessionId}/supporting-data`)
+ return response.data
+}
+
+export async function createSupportingData(
+ sessionId: string,
+ data: { label: string; data_type: string; content: string; content_type?: string }
+): Promise {
+ const response = await apiClient.post(`/sessions/${sessionId}/supporting-data`, data)
+ return response.data
+}
+
+export async function updateSupportingData(
+ sessionId: string,
+ itemId: string,
+ data: { label?: string; content?: string }
+): Promise {
+ const response = await apiClient.patch(`/sessions/${sessionId}/supporting-data/${itemId}`, data)
+ return response.data
+}
+
+export async function deleteSupportingData(sessionId: string, itemId: string): Promise {
+ await apiClient.delete(`/sessions/${sessionId}/supporting-data/${itemId}`)
+}
+```
+
+- [ ] **Step 2: Create branding API client**
+
+Create `frontend/src/api/branding.ts`:
+
+```typescript
+import { apiClient } from './client'
+
+export interface BrandingInfo {
+ company_display_name: string | null
+ logo_content_type: string | null
+ has_logo: boolean
+}
+
+export async function getBranding(teamId: string): Promise {
+ const response = await apiClient.get(`/teams/${teamId}/branding`)
+ return response.data
+}
+
+export async function updateBranding(
+ teamId: string,
+ formData: FormData
+): Promise {
+ const response = await apiClient.patch(`/teams/${teamId}/branding`, formData, {
+ headers: { 'Content-Type': 'multipart/form-data' },
+ })
+ return response.data
+}
+
+export async function deleteLogo(teamId: string): Promise {
+ await apiClient.delete(`/teams/${teamId}/branding/logo`)
+}
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/src/api/supportingData.ts frontend/src/api/branding.ts
+git commit -m "feat: add supporting data and branding API clients"
+```
+
+---
+
+### Task 20: Supporting Data UI Components
+
+**Files:**
+- Create: `frontend/src/components/session/AddSupportingDataModal.tsx`
+- Create: `frontend/src/components/session/SupportingDataPanel.tsx`
+
+- [ ] **Step 1: Create the add modal**
+
+Create `frontend/src/components/session/AddSupportingDataModal.tsx` with:
+- Two tabs: "Text Snippet" and "Screenshot"
+- Text tab: label input + multiline textarea
+- Screenshot tab: label input + drag-and-drop zone + file picker + paste support
+- Submit button that calls `createSupportingData`
+- 2MB file size validation for screenshots
+- Uses glass-card modal styling per design system
+
+- [ ] **Step 2: Create the panel**
+
+Create `frontend/src/components/session/SupportingDataPanel.tsx` with:
+- Collapsible section showing supporting data items
+- Each item: type icon (Code2 for text, Image for screenshot) + label + preview + delete button
+- "Add Supporting Data" button that opens the modal
+- Fetches items via `getSupportingData` on mount
+- Uses the design system's glass card and muted foreground styles
+
+- [ ] **Step 3: Integrate into session runner pages**
+
+Read the troubleshooting session runner (`TreeNavigationPage`) and procedural session runner (`ProceduralNavigationPage`) to find the notes/scratchpad area. Add the `SupportingDataPanel` component near the existing notes input in both pages.
+
+- [ ] **Step 4: Verify frontend build**
+
+Run: `cd frontend && npm run build`
+Expected: Build succeeds.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/src/components/session/AddSupportingDataModal.tsx frontend/src/components/session/SupportingDataPanel.tsx frontend/src/pages/
+git commit -m "feat: add supporting data capture UI to session runners"
+```
+
+---
+
+### Task 21: PDF Export in ExportPreviewModal
+
+**Files:**
+- Modify: `frontend/src/components/session/ExportPreviewModal.tsx`
+- Modify: `frontend/src/pages/SessionDetailPage.tsx`
+
+- [ ] **Step 1: Update ExportPreviewModal**
+
+Read `frontend/src/components/session/ExportPreviewModal.tsx` and modify:
+
+1. Update format type to include `'pdf'`:
+```typescript
+format: 'markdown' | 'text' | 'html' | 'psa' | 'pdf'
+```
+
+2. Add a `onDownloadPdf` callback prop for triggering the PDF download.
+
+3. When `format === 'pdf'`, hide the textarea and show a download-only UI:
+```tsx
+{format === 'pdf' ? (
+
+
PDF exports are generated server-side with your team's branding.
+
+ {loading ? 'Generating PDF...' : 'Download PDF'}
+
+
` blocks with labels | ` {
+ const response = await apiClient.get(`/teams/${teamId}/branding`)
+ return response.data
+}
+
+export async function updateBranding(teamId: string, formData: FormData): Promise {
+ const response = await apiClient.patch(`/teams/${teamId}/branding`, formData, {
+ headers: { 'Content-Type': 'multipart/form-data' },
+ })
+ return response.data
+}
+
+export async function deleteLogo(teamId: string): Promise {
+ await apiClient.delete(`/teams/${teamId}/branding/logo`)
+}
diff --git a/frontend/src/api/onboarding.ts b/frontend/src/api/onboarding.ts
new file mode 100644
index 00000000..4f54e687
--- /dev/null
+++ b/frontend/src/api/onboarding.ts
@@ -0,0 +1,21 @@
+import { apiClient } from './client'
+
+export interface OnboardingStatus {
+ created_flow: boolean
+ ran_session: boolean
+ exported_session: boolean
+ tried_ai_assistant: boolean
+ invited_teammate: boolean
+ connected_psa: boolean
+ is_team_user: boolean
+ dismissed: boolean
+}
+
+export async function getOnboardingStatus(): Promise {
+ const response = await apiClient.get('/users/onboarding-status')
+ return response.data
+}
+
+export async function dismissOnboarding(): Promise {
+ await apiClient.post('/users/onboarding-status/dismiss')
+}
diff --git a/frontend/src/api/supportingData.ts b/frontend/src/api/supportingData.ts
new file mode 100644
index 00000000..0dc36546
--- /dev/null
+++ b/frontend/src/api/supportingData.ts
@@ -0,0 +1,39 @@
+import { apiClient } from './client'
+
+export interface SupportingDataItem {
+ id: string
+ session_id: string
+ label: string
+ data_type: 'text_snippet' | 'screenshot'
+ content: string
+ content_type: string | null
+ sort_order: number
+ created_at: string
+ updated_at: string
+}
+
+export async function getSupportingData(sessionId: string): Promise {
+ const response = await apiClient.get(`/sessions/${sessionId}/supporting-data`)
+ return response.data
+}
+
+export async function createSupportingData(
+ sessionId: string,
+ data: { label: string; data_type: string; content: string; content_type?: string }
+): Promise {
+ const response = await apiClient.post(`/sessions/${sessionId}/supporting-data`, data)
+ return response.data
+}
+
+export async function updateSupportingData(
+ sessionId: string,
+ itemId: string,
+ data: { label?: string; content?: string }
+): Promise {
+ const response = await apiClient.patch(`/sessions/${sessionId}/supporting-data/${itemId}`, data)
+ return response.data
+}
+
+export async function deleteSupportingData(sessionId: string, itemId: string): Promise {
+ await apiClient.delete(`/sessions/${sessionId}/supporting-data/${itemId}`)
+}
diff --git a/frontend/src/components/common/EmptyState.tsx b/frontend/src/components/common/EmptyState.tsx
index 22e4a266..b917eb6b 100644
--- a/frontend/src/components/common/EmptyState.tsx
+++ b/frontend/src/components/common/EmptyState.tsx
@@ -1,23 +1,51 @@
import type { ReactNode } from 'react'
+import { Link } from 'react-router-dom'
import { cn } from '@/lib/utils'
interface EmptyStateProps {
icon?: ReactNode
+ illustration?: ReactNode
title: string
description?: string
action?: ReactNode
+ learnMoreLink?: string
+ learnMoreText?: string
className?: string
}
-export function EmptyState({ icon, title, description, action, className }: EmptyStateProps) {
+export function EmptyState({
+ icon,
+ illustration,
+ title,
+ description,
+ action,
+ learnMoreLink,
+ learnMoreText = 'Learn more',
+ className,
+}: EmptyStateProps) {
return (
- {icon &&
{icon}
}
+ {illustration && (
+
+ {illustration}
+
+ )}
+ {!illustration && icon && (
+
{icon}
+ )}
{title}
{description && (
-
{description}
+
{description}
)}
{action &&
{action}
}
+ {learnMoreLink && (
+
+ {learnMoreText} →
+
+ )}
+ {/* Root node */}
+
+ )
+}
+
+export function AnalyticsIllustration() {
+ return (
+
+ {/* Bars */}
+
+ )
+}
+
+export function SessionIllustration() {
+ return (
+
+ {/* Card 1 */}
+
+ )
+}
+
+export function IntegrationIllustration() {
+ return (
+
+ {/* Left box */}
+
+ )
+}
+
+export function StepLibraryIllustration() {
+ return (
+
+ {/* List items */}
+
+ )
+}
+
+export function ScriptIllustration() {
+ return (
+
+ {/* Terminal window */}
+
+ )
+}
+
+export function ShareIllustration() {
+ return (
+
+ {/* Center node */}
+
+ )
+}
diff --git a/frontend/src/components/common/__tests__/EmptyState.test.tsx b/frontend/src/components/common/__tests__/EmptyState.test.tsx
new file mode 100644
index 00000000..83b81a3c
--- /dev/null
+++ b/frontend/src/components/common/__tests__/EmptyState.test.tsx
@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { BrowserRouter } from 'react-router-dom'
+import { EmptyState } from '../EmptyState'
+import { FlowIllustration } from '../EmptyStateIllustrations'
+
+function renderWithRouter(ui: React.ReactElement) {
+ return render({ui} )
+}
+
+describe('EmptyState', () => {
+ it('renders title and description', () => {
+ renderWithRouter(
+ Create New}
+ />
+ )
+
+ expect(screen.getByRole('button', { name: 'Create New' })).toBeInTheDocument()
+ })
+
+ it('renders learn more link with correct href', () => {
+ renderWithRouter(
+ icon}
+ illustration={(null)
+ const [dismissed, setDismissed] = useState(false)
+ const [allComplete, setAllComplete] = useState(false)
+
+ useEffect(() => {
+ getOnboardingStatus()
+ .then(setStatus)
+ .catch(() => {
+ // Silently fail — don't show checklist if endpoint unavailable
+ })
+ }, [])
+
+ const items = status?.is_team_user ? TEAM_ITEMS : SOLO_ITEMS
+ const completedCount = status
+ ? items.filter((item) => status[item.key]).length
+ : 0
+ const totalCount = items.length
+ const isAllDone = completedCount === totalCount && status !== null
+
+ useEffect(() => {
+ if (isAllDone) {
+ const timer = setTimeout(() => setAllComplete(true), 2000)
+ return () => clearTimeout(timer)
+ }
+ }, [isAllDone])
+
+ // Don't render if dismissed, fully complete, or not loaded yet
+ if (!status || status.dismissed || dismissed || allComplete) return null
+
+ const progressPercent = totalCount > 0 ? (completedCount / totalCount) * 100 : 0
+
+ const handleDismiss = async () => {
+ setDismissed(true)
+ try {
+ await dismissOnboarding()
+ } catch {
+ // Already hidden locally
+ }
+ }
+
+ return (
+
+ {/* Progress bar */}
+
+
+
+ {/* Header */}
+
+
+
+ Getting Started
+
+
+ {isAllDone ? (
+ You're all set!
+ ) : (
+
+ {completedCount}
+ {' '}of {totalCount} complete
+
+ )}
+
+
+
+
+
+
+ {/* Checklist items */}
+
+ {items.map((item) => {
+ const done = status[item.key]
+ return (
+
+ !done && navigate(item.path)}
+ disabled={done}
+ className={cn(
+ 'w-full flex items-center gap-3 rounded-lg px-3 py-2 text-sm transition-colors text-left',
+ done
+ ? 'cursor-default'
+ : 'hover:bg-[rgba(255,255,255,0.04)]'
+ )}
+ >
+ {/* Checkbox */}
+
+ {done &&
+
+ {/* Label */}
+
+ {item.label}
+
+
+ {/* Arrow for incomplete items */}
+ {!done && (
+
+
+ )
+ })}
+
+
+
('text_snippet')
+ const [label, setLabel] = useState('')
+ const [textContent, setTextContent] = useState('')
+ const [imageBase64, setImageBase64] = useState(null)
+ const [imageContentType, setImageContentType] = useState(null)
+ const [imageFileName, setImageFileName] = useState(null)
+ const [isSubmitting, setIsSubmitting] = useState(false)
+ const [error, setError] = useState(null)
+ const fileInputRef = useRef(null)
+
+ const resetForm = () => {
+ setLabel('')
+ setTextContent('')
+ setImageBase64(null)
+ setImageContentType(null)
+ setImageFileName(null)
+ setError(null)
+ setActiveTab('text_snippet')
+ }
+
+ const handleClose = () => {
+ resetForm()
+ onClose()
+ }
+
+ const processFile = useCallback((file: File) => {
+ if (file.size > MAX_FILE_SIZE) {
+ setError('File must be under 2MB')
+ return
+ }
+ if (!['image/png', 'image/jpeg', 'image/svg+xml'].includes(file.type)) {
+ setError('Only PNG, JPEG, and SVG files are supported')
+ return
+ }
+ setError(null)
+ setImageFileName(file.name)
+ setImageContentType(file.type)
+
+ const reader = new FileReader()
+ reader.onload = () => {
+ const result = reader.result as string
+ // Strip the data:... prefix to get raw base64
+ const base64 = result.includes(',') ? result.split(',')[1] : result
+ setImageBase64(base64)
+ }
+ reader.readAsDataURL(file)
+ }, [])
+
+ const handleFileChange = (e: React.ChangeEvent) => {
+ const file = e.target.files?.[0]
+ if (file) processFile(file)
+ }
+
+ const handlePaste = useCallback((e: React.ClipboardEvent) => {
+ const items = e.clipboardData?.items
+ if (!items) return
+ for (const item of items) {
+ if (item.type.startsWith('image/')) {
+ e.preventDefault()
+ const file = item.getAsFile()
+ if (file) processFile(file)
+ return
+ }
+ }
+ }, [processFile])
+
+ const handleSubmit = async () => {
+ if (!label.trim()) {
+ setError('Label is required')
+ return
+ }
+
+ if (activeTab === 'text_snippet' && !textContent.trim()) {
+ setError('Content is required')
+ return
+ }
+
+ if (activeTab === 'screenshot' && !imageBase64) {
+ setError('Please select or paste an image')
+ return
+ }
+
+ setIsSubmitting(true)
+ setError(null)
+ try {
+ await createSupportingData(sessionId, {
+ label: label.trim(),
+ data_type: activeTab,
+ content: activeTab === 'text_snippet' ? textContent : imageBase64!,
+ content_type: activeTab === 'screenshot' ? (imageContentType ?? undefined) : undefined,
+ })
+ toast.success('Supporting data added')
+ onAdded()
+ handleClose()
+ } catch (err) {
+ console.error('Failed to add supporting data:', err)
+ setError('Failed to save. Please try again.')
+ } finally {
+ setIsSubmitting(false)
+ }
+ }
+
+ return (
+
+ {/* Tabs */}
+
+ setActiveTab('text_snippet')}
+ className={cn(
+ 'flex flex-1 items-center justify-center gap-2 rounded-md px-3 py-2 text-sm font-medium transition-colors',
+ activeTab === 'text_snippet'
+ ? 'bg-card text-foreground shadow-sm'
+ : 'text-muted-foreground hover:text-foreground'
+ )}
+ >
+
+ setActiveTab('screenshot')}
+ className={cn(
+ 'flex flex-1 items-center justify-center gap-2 rounded-md px-3 py-2 text-sm font-medium transition-colors',
+ activeTab === 'screenshot'
+ ? 'bg-card text-foreground shadow-sm'
+ : 'text-muted-foreground hover:text-foreground'
+ )}
+ >
+
+
+
+ {/* Label */}
+
+
+ Label
+
+
+
+ {/* Text Snippet Tab Content */}
+ {activeTab === 'text_snippet' && (
+
+
+ Content
+
+