[lightnoor890]

Closes #121

What changed and why

New patients landed on an empty care hub and new doctors on a dashboard with no idea what was missing. This adds a first-run onboarding section to both dashboards, built in src/features/onboarding/:

• Role-specific checklist with progress
  • Patient: finish profile → fill in health profile → find a pharmacy or lab (the “first search” step).
  • Doctor: submit verification documents → list specialties → publish availability.
  • Each item shows a text Done/To do pill (not colour alone), remaining items link to the screen that does the work where one exists, and a role="progressbar" with aria-valuenow/aria-valuetext says “2 of 3 steps complete”.
• Completion comes from the server, never the browser. A new src/services/onboarding-service.ts calls the assumed GET /patients/me/onboarding / GET /doctors/me/onboarding summaries; hooks use typed onboardingKeys factories. There is no localStorage/sessionStorage completion flag and no “dismissed” flag, so a new device shows the same state.
• Optional guided tour. A three-step inline tour (no dialog, no aria-modal, no focus trap, no backdrop) appears only while setup is unfinished. It is a labelled region with normal buttons, aria-live="polite" step announcements, Back/Next/Done and Skip tour, and Escape closes it. The page remains fully usable underneath.
• Never blocks access. If the summary fails to load, a non-blocking role="status" notice appears and the rest of the dashboard works unchanged. Once the server reports every step complete, the checklist and tour disappear.

Doctor documents/specialties/availability have no self-serve screen in this repo yet, so those checklist items track and explain the state but do not link; this is documented rather than faking destinations.

API shapes are assumed (docforum-core has no onboarding endpoint yet) and recorded in ARCHITECTURE_ESSENTIALS.md → “Known assumptions — First-run onboarding”. Mock handlers/fixtures were added so npm run dev:mock shows the feature for both roles.

PRD flow: implements the first-run step of the patient and doctor onboarding flows (PRD §4 account setup → health profile → first search for patients; verification → specialties → availability for doctors). No backend contract change.

Tests

npm run typecheck   # tsc -b --noEmit — clean
npm test            # Test Files  69 passed (69)
                    # Tests      574 passed (574)
npm run build       # ✓ built
npm run check:dist  # ✓ no mock code in production bundle
npm run check:stellar-boundary  # ✓

New tests: server-driven progress on both roles, Done/To do text and links for remaining work, checklist hidden when complete, tour Next/Back/Skip/Done and Escape, non-modal (no dialog role / aria-modal) assertions, non-blocking error notice, “no request without a session”, mock handler coverage, and query-key factory coverage. The patient dashboard test also asserts the hub stays usable while onboarding is unfinished.

Screenshots (desktop 1280×900, mobile 390×844)

• screenshots/onboarding-patient-desktop.png
• screenshots/onboarding-patient-mobile.png
• screenshots/onboarding-doctor-desktop.png
• screenshots/onboarding-doctor-mobile.png

(These are full-page mock-mode captures; the pre-existing dev panel was hidden. The patient care-hub “could not be loaded” banner in the patient shots is a pre-existing mock coverage gap — GET /appointments/mine has no handler — unrelated to this change.)

[drips-wave]

@lightnoor890 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[drips-wave]

@lightnoor890 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[drips-wave]

@lightnoor890 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[github-actions]

@lightnoor890 This PR now has merge conflicts with main, most likely because #162 (feat(admin): closure calendar management for holidays and clinic closures) was just merged, so it can't be merged until it's rebased:

git fetch upstream            # upstream = https://github.com/DocForum/docforum-web.git
git rebase upstream/main
# resolve the conflicts, re-run the tests, then:
git push --force-with-lease

The usual culprits are shared files like ROADMAP.md and ARCHITECTURE*.md. CI re-runs when you push, and the needs-rebase label is removed automatically once the conflicts are resolved.

_{Automated message. It won't repeat unless the PR conflicts again after your next push.}

[github-actions]

@lightnoor890 This PR now has merge conflicts with main, most likely because #207 (feat(facility): API keys and webhooks management for facility system integrations (#55)) was just merged, so it can't be merged until it's rebased:

git fetch upstream            # upstream = https://github.com/DocForum/docforum-web.git
git rebase upstream/main
# resolve the conflicts, re-run the tests, then:
git push --force-with-lease

The usual culprits are shared docs like ROADMAP.md and ARCHITECTURE*.md. If the conflict is in the ROADMAP.md changelog, move your entry into a new file under changelog.d/ (see changelog.d/README.md) rather than resolving it in place, so it can't conflict again. CI re-runs when you push, and the needs-rebase label is removed automatically once the conflicts are resolved.

_{Automated message. It won't repeat unless the PR conflicts again after your next push.}

[afeezorobsco-cyber]

@lightnoor890 CI is failing on this branch against the latest main, so it can't be merged yet. The errors from the latest run:

Frontend (typecheck + test + build)

src/mocks/handlers.test.ts(28,13): error TS6133: 'onboardingService' is declared but its value is never read.

Remove the unused onboardingService import in src/mocks/handlers.test.ts:28.

This PR also conflicts with main again, so please rebase first, then fix the above.