Technical reference. For task-based help, see the corresponding user guide.

Documentation status: reviewed against implementation · Reviewed: 2026-07-21 · Primary users: new family and coach users · Surfaces: mobile web, coach portal and platform API

Getting-started guides provide one published PDF for each audience. They can be opened deliberately from navigation/announcements and can appear once as a lightweight onboarding prompt for a recently created account.

Only a guide with publishedAt is returned. A missing/unpublished audience record produces guide: null, not an unauthorized file URL.

1. Client requests GET /getting-started/guide?audience=family|coach.
2. The platform checks actor/audience permission and looks up the single published record.
3. The object must live in getting-started-guides. The platform creates a 15-minute signed download URL and returns title, description, file name/type, publication/update dates and URL expiry.

1. The full screen shows the publication date and a role-specific back control.
2. PDF.js renders each page to a canvas, limiting render scale to 2 and disabling range/stream fetches for predictable signed-file loading.
3. Loading, API error, PDF load/render error and unpublished empty states are distinct.

1. The panel defaults to the coach audience but lets a coach switch to the family guide for client-support context.
2. A published PDF is shown in an embedded viewer with publication metadata; an unpublished audience shows an explicit unavailable state.

1. Prompt evaluation runs only on the family or coach home route (including the root route resolved by default role).
2. The actor must have been created within the previous six weeks.
3. After a 700 ms delay, the dialog loads the route's audience guide.
4. Dismissal stores a per-user, per-audience seen marker in local storage; coach and family prompts stay separate for dual-role users.
5. Configured test/pilot emails may always repeat the prompt. Development may force it with showGettingStartedGuide=1; automated end-to-end runs can suppress it with their dedicated storage flag.

Publishing/upload is an owner operational workflow. Guide objects are PDF-only under the guides/ storage prefix; coaches can read both audiences but cannot publish from the coach portal.

• Audience checks happen before the signed URL is issued.
• The file route re-checks that the requested object belongs to a published guide and that the actor can read its audience.
• Signed URLs are temporary bearer links. Do not store them as durable content links or expose them in analytics/logs.
• Prompt state is device-local convenience; it is not a server authorization or publication record.

The client does not continually refresh a signed URL inside an already-open PDF viewer. If a guide sits open beyond its URL lifetime and later needs the network, close/reopen it to request a new authorized URL.

1. [ ] Families can read only family; coaches and super-admin can read both.
2. [ ] Unpublished records return null and never a signed object URL.
3. [ ] Both viewers show publication metadata and distinct load/error/unavailable states.
4. [ ] Prompt is home-only, recent-account-only, delayed and once per user/audience.
5. [ ] Dismissal remains usable when browser storage throws.
6. [ ] Signed guide URL is 15 minutes, bucket/prefix checked and refreshed by reopening.
7. [ ] Coach portal audience switch does not imply publishing authority.

• Mobile web: mobile-web/src/routes/GettingStartedGuideScreen.tsx, mobile-web/src/components/GettingStartedPromptHost.tsx, mobile-web/src/components/PdfGuideCanvasViewer.tsx
• Coach portal: admin-web/src/routes/GettingStartedPanel.tsx
• Platform: platform/packages/shared/src/getting-started-guides.ts, platform/apps/api/src/routes/getting-started-guide-routes.ts, platform/apps/api/src/services/getting-started-guide-service.ts, platform/apps/api/src/routes/file-routes.ts

• 27 — Announcements and notification banners
• 28 — FAQs, feedback and support
• 30 — Signed files and profile media