Skip to main content
Synced from the repo — do not edit here

Canonical source: docs/claude/atlas-consumer-handoff.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.

Atlas / Health Assistant — Session Handoff (2026-07-11)

Resume point for the consumer "Health Assistant" (client-facing name for Atlas) redesign work. All code is committed to wt/hybrid. The vision foundation is deployed to production (atlas_consumer). This doc preserves the expensive backend maps so a fresh context can continue without re-investigating.

SHIPPED this session (committed; vision also deployed)​

  • Real Atlas chat = redesign Health Assistant: full-screen pushed RouteChatV2(assistantOnly:true) (back button, no bottom nav pill), warm token bubbles (terracotta sent / surfaceRaised received, chat_message.dart WidgetChatMessageContent), _ChatHeaderV2 title="Health Assistant" (assistantOnly, no subtitle). Streaming + tool calls verified.
  • Vision foundation DEPLOYED: attach image/PDF → Claude vision. 4 seams: route_chat.dart:~1326 (pass pre-upload attachments) + :1225 (allow image-only) → service_atlas_consumer.dart:runAtlasConsumer(media) (base64) → functions_atlas_consumer.py ConsumerRequest.media → functions_ai_agent.py:~7031 run_claude_agent(media=…) builds Claude image/document blocks (mirrors functions_stedi.py:~705). sonnet-4-6 = vision. VERIFY with a real lab/meal photo on a physical device.
  • Quick-add + sheet: wide icon-badge buttons + "Message Atlas…" input at bottom (functional — type → opens chat with msg auto-sent via openRpChat(initialQuery) → RouteChatV2.initialQuery → WidgetChatContent.initialQuery, existing dedup). rp_quickadd.dart.
  • Chat attach sheet rebuilt modern (modal_add_media.dart _RedesignAttachTile, redesign variant).
  • Health + → real add-metric picker (rp_live.dart _openAddMetric → showBasisModalAddPickerModern over addable BasisHealthType). Health search now covers metrics (day.insights) not just labs.

SIM DEV LOOP (to resume verification)​

  • Persistent flutter run on sim 9B345F76-958C-4F22-928B-6A7EBD383896, stdin from FIFO /tmp/rp_flutter_fifo (a sleep 86400 > fifo holder must be alive or the read-open blocks). echo r > FIFO = reload, R = restart.
  • Auth token: node basis-functions/tools/_mint_redesign.cjs (writes /tmp/redesign_token.txt, prints MINT_OK — do NOT redirect stdout). Launch: flutter run -d <sim> --dart-define=kFeatureRedesignedHome=true --dart-define=DBG_FB_TOKEN=$(cat /tmp/redesign_token.txt) --dart-define=DBG_CLINIC=axuk-khwf-prkr < /tmp/rp_flutter_fifo. Signs into PROD Firebase as George (uid GoOU3d2QcyRZMD83IhbQeIclpwh2).
  • Screenshot: xcrun simctl io <sim> screenshot. Tap: idb ui tap --udid <sim> x y (device points; screenshot px 923-wide → point = px393/923, py852/2000). Type: idb ui text.
  • If build fails with Flutter.framework/Flutter does not exist, cannot thin after a killed run: flutter precache --ios --force + rm -rf build/ios .dart_tool/flutter_build ~/Library/Developer/Xcode/DerivedData/Runner-*.

DEFERRED WORK — exact anchors (from 3 explore agents)​

A. Vision capability tools (next layer on the shipped foundation)​

  • Labs → add to record: extraction reuse = callable analyze_document_summary_v2 (in functions_ai_documents.py, Gemini OCR over PDF) or analyze_lab_report (functions_lab_analysis.py:62). Write to users/{uid}/labs/{labId}; trigger sync_user_lab_to_clinic (functions_labs_mirror.py:102) auto-mirrors to clinicsv2/{clinic}/clinic_users/{uid}/labs. Add an Atlas tool that, on a recognized lab image, offers to write the doc.
  • Report → share with care team: post a message to chats/{uid} (schema: messages[] of {time, content, author:{id,role:'coach'|'user'}, media:[]}, real write at functions_workflows.py:169).
  • Meal Q&A: largely covered by the shipped vision (Atlas sees the photo); optionally a nutrition tool.

B. Approval cards = copilot_drafts pattern (NOT basis/* media — those are dead on the AI path)​

  • Tools: functions_ai_agent.py:55 TOOLS list; proposal tools prepare_update_protocol (:276), prepare_book_appointment (:259). Dispatch execute_tool (:1207). Draft writer example _exec_prepare_update_protocol (:3823) writes clinicsv2/{clinic}/clinic_users/{uid}/copilot_drafts/{id} {type:'proposed_action', status:'draft', data:{action, request_type, title, summary, params}, session_id, request_id} (_draft_meta :37 pins card to msg).
  • Consumer Atlas already gets full TOOLS (atlas_consumer calls run_claude_agent with no override) but passes NO draft_session_id/request_id and the consumer app doesn't read copilot_drafts + there's no consumer accept endpoint. MUST BUILD: (1) surface drafts to the Ready app (add a media/cards array to the backend-owned assistant-message write at functions_atlas_consumer.py:~244, or a users/{uid}/atlas_drafts collection); (2) consumer propose_* tools passing user context; (3) a user-facing accept endpoint (execute_copilot_action :8163 is staff-only — needs a user-owns-draft variant); (4) protocol self-apply carve-out (assign_protocol functions_clinic.py:1014 requires EDIT_HABITS; build a server-side executor under PermissionAuthorSystem, pattern _call_clinic_handler :4339). Booking is self-service already (book_appointment :7885, []-perm) — the Booking card can call it as the user today.
  • Model = Anthropic Claude (run_claude_agent :6936, sonnet-4-6 for consumer). Frontend attach/accept widgets: chat_attachments.dart (WidgetChatAttachment :337, WidgetAttachmentAcceptWrapper :202 — single Accept button, 5 mutation mimes, local-DB apply).

C. Voice input (net-new) — recommend interactive two-way (live waveform + realtime STT + optional TTS). Mic is a no-op today (route_chat.dart _buildCompact mic TODO; rp_atlas.dart fake waveform). Design its own task.​

D. Small polish​

  • Dark-theme the add-metric picker (showBasisModalAddPickerModern renders light — pass a theme like the attach sheet did).
  • Chat history is ONE continuous chatDocCoachAI doc — separate past-chats/sessions is a deliberate add.

CONSTRAINTS​

  • Backend = basis-functions in THIS worktree; deploy ONLY via .github/scripts/ship.sh --approved-by-george wt/hybrid <fns> (merges wt/hybrid→master, deploys from master). Never firebase deploy from the worktree. George approves each deploy in-conversation.
  • NEVER fake an Approve/apply action — verify the real handler exists first (see [[project_consumer_atlas_capabilities]], [[feedback_redesign_acceptance_bar]]).