Other export surfaces

Several Health.md features trigger or present the same production exports without defining a new health-data schema.

Export Preview

Preview executes the configured exporter against the selected day and displays the resulting files before writing. Preview content follows the same JSON, CSV, Markdown, and Bases contracts documented in this reference.

A preview is not proof that every HealthKit query will remain available during a later export. Check the final file’s capture status and diagnostics.

Daily Note Injection

Daily Note Injection merges selected flat summary/frontmatter values into an existing Obsidian daily note. It draws from the same ExportDataSnapshot, metric mapping, frontmatter key customization, units, and schema-v8 diagnostics used by Markdown/Bases.

It does not inject the complete canonical archive. With normal export mode, use the companion JSON/CSV file for exact source records. With Daily Notes Only, no companion archive, data dictionary, roll-up, individual-entry, or provider-sidecar file is written; the injected summary is intentionally the sole destination output.

Daily Notes Only applies to filesystem destinations and is rejected for API Endpoint exports. Connected Mac peers negotiate explicit support so an older Mac cannot ignore the mode and unexpectedly write aggregate files.

User renames affect the written key; the data dictionary retains canonicalKey for cross-vault integrations.

Morning ends daily-note preparation remains internal and does not enable production injection. Its independently versioned annotation uses healthmd_injection_kind: daily_capture_v1 plus healthmd_daily_injection_v1, a quoted JSON envelope with kind: healthmd_daily_capture, version: 1, and the exact accepted Apple-v11 record_json string. This record describes only the newly injected, selected capture; it does not assign a schema or attribution to the surrounding personal note or its retained historical properties. Readers consume that scoped record rather than combining it with older fields.

A later Night begins injection replaces the scoped record with the newly selected Apple-v8 capture and its frozen calendar. When section injection is enabled, the record also retains the selected current detail available in that capture; frontmatter-only injection retains summaries. Neither mode embeds the canonical source archive. Retained Morning fields and sections remain outside that capture, including when section injection is disabled or the metric selection changes. Ordinary historical notes without an annotation keep their existing output. Early unqualified notes with both annotation fields set to null attest no capture; readers reject those notes instead of interpreting retained values under a different attribution rule. Export the note again to obtain a scoped capture.

Preparation projects selected frontmatter properties from the accepted renderer, preserves personal preambles and unrelated sections, and optionally supplies the accepted Markdown sections. The scoped record never contains the canonical source archive. These annotation names are reserved for capture authority and cannot be selected metric aliases. The shared core projects and merges these scoped patches for both native adapters, preserving personal YAML and body content. A file declaring a complete Health.md daily-export or roll-up schema is a different artifact role and rejects partial injection; choose a personal daily note or use the complete-export workflow for that file. Apple local composition carries immutable prepared note text with the accepted renderer pin, operation identity, date, path, clock and injection settings. It validates the combined output paths and merges every note before the first write. At note commit, it prepares final bytes from the latest personal text and checks that predecessor again immediately before replacement. An exact installed result can replay; an intervening edit rejects instead of being overwritten. Fresh and restored local operations use their captured settings even after live mode or timezone changes. Preview prepares the same accepted note payload, reads under the captured vault identity without following symlinks, and bounds only the displayed text. Existing notes over 8 MiB reject before they are loaded for preview or merging. Daily Notes Only produces no aggregate, dictionary, roll-up, ZIP, individual-entry or provider-sidecar output, including when those preferences remain saved or no aggregate format is selected. Missing notes follow create-or-skip; skipped notes are terminal no-health-data outcomes for that date. Note updates/skips remain separate from generated-file counts. Normal ZIP exports package the accepted generated files and update daily notes separately in the vault. The ZIP destination and note paths are checked together, and every note merge is validated before publication; notes are never placed inside the archive. Note updates/skips are reported separately from the one generated ZIP. As with ordinary multi-file export, a later write failure can leave already committed companions. Direct companions, connected archive/individual-entry composition, scheduled recovery and runtime qualification remain pending before production enablement.

Connected Mac loose/range exports and Daily Notes Only persist note content in the protected receiver spool before writing the destination. A version-2 received plan binds each note’s captured owner, path, predecessor digest and final-content digest to the same operation, and keeps a separate acknowledgement frontier. Notes and generated files share the existing 33 MiB spool budget. Resume verifies exact installed notes or commits against the captured predecessor without rerendering or querying the source; changed personal text, unsafe paths, corrupt spools and inconsistent frontiers reject. Missing-note skips stay terminal and note counts remain separate from generated-file counts. Plans without effective note work retain their version-1 encoding. Summary Only suppresses the saved note preference; Daily Notes Only takes precedence over saved summary/archive options. If an unavailable range summary falls back to daily files, note mode follows that effective operation. The iPhone requires an explicit compatible Morning ends pin before starting the connected transfer.

Android local folder exports and previews compose an accepted aggregate plan with the same scoped capture before writing. They freeze selection and presentation before destination lookup, reject portable path collisions, and require a readable, unambiguous note. Before replacing an existing note, they recheck its document identity and content, and revalidate the selected folder. A changed or unreadable note fails rather than being treated as missing. Missing notes follow the existing create-or-skip setting. SAF does not provide an atomic multi-file transaction or compare-and-swap; concurrent changes after the final check remain an OS storage limitation. Durable note journals, direct/gateway companions and runtime qualification remain pending under Issue #104 before Morning ends production enablement. Android’s record retains its own android-sleep-v6 profile and native sleep identities; the annotation does not convert either platform’s record into the other’s profile. A later Android Night update of an already scoped note uses daily_capture_v2 and healthmd_daily_injection_v2: an exact native v4/v5 record plus the explicitly captured local timezone in an outer envelope. The frozen record receives no new schema, clock or meaning. Selected current detail follows the section setting; retained Morning fields and tables remain outside the active capture. Local export and preview use the same scoped merge, and the bound note write bypasses the historical flat-YAML merger even when aggregate files use Append or Update. Unknown capture kinds or an unavailable clock fail before writes. Fresh historical notes keep their ordinary output.

Apple Shortcuts and App Intents

Shortcut export intents invoke Health.md’s ordinary export orchestration for a date, yesterday, last N days, or a date range. They honor the resolved profile’s API or local-folder destination and do not define a separate daily file schema. Last N Days ends yesterday by default; Include Today shifts the same N-day window to end today.

Shortcut status/summary results are automation convenience values. Any files produced still follow the selected production format contracts. A shortcut reporting that an action completed does not replace per-day archive/query diagnostics.

Scheduled exports

Scheduled exports use the same selected metrics, formats, schema versions, and lossless setting. Scheduling adds lifecycle/retry state, not a different health-data shape.

When HealthKit is protected or the device cannot complete work, pending dates are retained for retry. A later successful action should still be evaluated per daily capture status.

Export Preview and serialization errors

Preview-friendly convenience methods can render an explicit serialization-error object/string when canonical encoding fails. Production writers use throwing paths and fail the affected date rather than silently dropping an unencodable record.

Do not ingest a health-data-serialization-error fallback as a normal daily record.

Mac Destination and Manual IP

Nearby Mac Destination and paired Manual IP/Tailscale deliver the same captured job through different encrypted transports. Both use the connected request/result contracts and Mac-side shared exporters.

Transport choice does not change daily JSON/CSV/Markdown/Bases semantics.

Provider sidecars

Enabled third-party integrations can add provider-specific external records to an API envelope or file job. Apple v8 embeds reviewed typed provider sections while retaining provider-native sidecars under their own schema/version. Neither layer mutates healthmd.healthkit_records v1.

Consumers should branch on provider identity/schema and retain unknown provider records separately from Apple Health source records.

Export history

Export history records operational outcomes such as dates, target, files, failures, and retry state. It is app state, not a health-data export contract. Do not use history success as a substitute for reading final capture diagnostics.

Archives and containers

Compression or connected-transfer spooling changes packaging, not the objects inside. Validate the inner declared schema after extraction/reassembly.

Contract reuse summary

Surface	Unique health-data schema?	Authoritative output
Manual export	No	Selected daily/roll-up formats.
Export Preview	No	Preview of the selected production exporter.
Daily Note Injection	No	Flat summary/frontmatter projection.
Apple Shortcuts export intents	No	Selected production files.
Scheduled exports	No	Selected production files plus operational retry state.
Mac Destination	No	Shared Mac-written production files.
Manual IP/Tailscale	No	Same connected job over paired transport.
API Endpoint	Yes, envelope only	healthmd.api_export wrapping daily records.
Mac CLI strict raw	Yes, result envelope only	healthmd.raw_result wrapping daily records.
Provider integration	Provider-specific sidecar	Independently versioned external records.
Roll-ups	Yes	healthmd.rollup_summary.