[Feature] Make first-run Apple Health setup and backfill progress explicit

[HercoGC]

Problem

For a first-time Apple Health setup, the web onboarding screen presents Apple Health as a source but does not make it clear that the connection must be completed later in the native iOS app.

After connecting HealthLoger, the initial HealthKit backfill also lacks an obvious overall history range, oldest date reached, remaining count or last-progress time. When server throttling is reached, the sync can appear to have stopped even though it may be waiting and retrying.

This makes it difficult for a non-technical user to distinguish expected first-run behaviour from a broken setup.

Proposed solution

Treat Apple Health setup and initial backfill as one guided first-run flow:

1. On the web onboarding source card, state: Complete Apple Health setup in HealthLoger on your iPhone after onboarding.
2. Provide a link to the iOS/TestFlight instructions and a clear Continue or Set up later action.
3. In HealthLoger, show:
   • current data type or phase;
   • records accepted;
   • oldest date reached;
   • last successful activity time;
   • rate-limited / waiting / retrying state;
   • approximate remaining work or ETA when it can be calculated honestly.
4. Preserve a clear completed state and last-sync summary after the first backfill.

Workarounds used

• Complete web onboarding without selecting Apple Health, then install HealthLoger through TestFlight and connect Apple Health from the iPhone.
• Keep HealthLoger open during the first sync and periodically check the HealthLog dashboard for progressively older readings.
• For a complete historical backfill, export Apple Health's export.zip and import it through the web app. For this archive, the Docker memory workaround documented in [Bug] Apple Health ZIP parser exceeds the default 1 GB Docker memory limit #775 was also required.

These workarounds complete the setup but do not provide a trustworthy native progress view.

Possible implementation

• Give Apple Health a distinct onboarding state such as Requires iPhone app, rather than presenting it like a selectable web connector.
• Return a compact server-authoritative sync status containing phase, accepted count, oldest source timestamp, last activity, throttle/retry state and completion state.
• Let iOS display honest indeterminate progress when a total is unknown and an ETA only when coverage supports it.
• Preserve the last successful sync summary so users can distinguish a completed backfill from an inactive or interrupted one.
• Link the web and iOS first-run screens to the same current setup documentation.

Alternatives considered

The current workaround is to watch the web dashboard for older readings and wait without knowing whether the phone is still working. Opening the app again can also trigger activity, but this does not explain progress or whether throttling is being handled.

Issue #586 concerns background HealthKit delivery after initial setup. This request is narrower: it concerns first-run setup guidance and visibility into the initial historical backfill.

Affected surface

Web (PWA), iOS app (v1.5+), API

Additional context

Observed with HealthLog v1.37.11 and HealthLoger 0.17.0 on iOS 27. No health readings, account details or private server address are included.

Pre-flight checks

• I confirmed this is not a duplicate of an existing feature request.
• I'm proposing a feature, not asking a usage question.

[MBombeck]

This shipped in v1.37.20. Onboarding now says plainly that Apple Health data arrives through the iPhone app, and the Apple Health card reports the backfill progress the server actually sees: accepted counts per import, how far back the oldest reading goes, and how recently data last arrived. One honest note on scope: the server does not track an ETA or the phone-side throttle state, so the card shows what the server can vouch for rather than an estimate it cannot back. Would be glad to hear whether this covers what you had in mind on your instance. Refs #778