HealthProbe Documentation Index

Canonical documentation root: HealthProbe/Doc/

This directory is the only place for substantive HealthProbe documentation. Root-level AGENTS.md and CLAUDE.md are bootstrap pointers only, kept so agent tools can find this index.

Current Product Direction

HealthProbe is a single-device, local Health DB Time Machine: - capture selected HealthKit-accessible observations over time; - reconstruct how the local Health database looked at a chosen observation date; - explain local changes with consolidation-aware labels; - preserve recovery-compatible archives and exports; - keep the iOS app read-only with respect to HealthKit and iOS backups.

Target storage architecture: - SQLite archive/analysis database is the source of truth; - observations are stored differentially, not as recurring complete snapshots; - Core Data is the rebuildable UI/report cache for expensive counts and summaries; - SwiftData is legacy/prototype only and should not be expanded; - existing prototype/test databases are disposable and may be reset for archive v2.

How To Point Agents

Use the chapter map below. Send agents to the narrowest document that matches their task.

If the task is about...	Send the agent to...
Overall product scope, non-goals, future parking lot	`01-product/Product-Specification.md`
MVP behavior and out-of-scope boundaries	`01-product/MVP-Specification.md`
Database design, archive schema, differential storage, SQL analysis	`02-architecture/Database-Design.md`
Core Data cache schema and invalidation	`02-architecture/Core-Data-Cache-Design.md`
Export formats, manifests, streaming contract	`02-architecture/Export-Specification.md`
Implementation workflow, HealthKit capture, exports, tests	`02-architecture/Implementation-Guide.md`
Forensic limits, export meaning, recovery compatibility	`01-product/Forensics-Limitations.md`
General agent ownership and handoff rules	`00-agent-guides/AGENTS.md`
SwiftUI/UI work	`00-agent-guides/CLAUDE.md`
Refactoring milestones and sequencing	`04-project/Refactoring-Plan.md`
Project status and refactoring priorities	`04-project/IMPLEMENTATION_STATUS.md`
SwiftData retirement inventory	`04-project/SwiftData-Retirement-Inventory.md`
Historical UI notes only	`99-archive/`

Chapters

00 Agent Guides

00-agent-guides/AGENTS.md Multi-agent development guide, ownership boundaries, protocol contracts, and current architecture decisions.
00-agent-guides/CLAUDE.md UI/SwiftUI-specific instructions aligned with the current Time Machine objective.

01 Product

01-product/Product-Specification.md Full current product specification, motivations, architecture decision record, and non-goals.
01-product/MVP-Specification.md MVP scope for the iOS app, including read-only behavior, differential storage expectations, exports, and out-of-scope restore/republication.
01-product/Forensics-Limitations.md What the app can and cannot prove, how to interpret changes, and what recovery-compatible exports should preserve.

02 Architecture

02-architecture/Database-Design.md Canonical database design. Start here for SQLite archive v2, Core Data cache boundaries, differential storage, point-in-time reconstruction, SQL diffs, recovery-compatible exports, reset policy, future migrations, and DB tests.
02-architecture/Core-Data-Cache-Design.md Target Core Data cache schema, invalidation rules, rebuild order, and legacy-device cache behavior.
02-architecture/Export-Specification.md JSON/CSV export envelope, canonical manifest hashing, item hashing, streaming/cancellation behavior, and provenance warnings.
02-architecture/Implementation-Guide.md Technical implementation guide for HealthKit capture flow, change explanation, exports, context logging, UI integration, and testing. It references the canonical database design instead of redefining it.

03 UI

03-ui/README.md Entry point for active UI guidance and links to archived UI notes.

04 Project

04-project/Refactoring-Plan.md Checkable milestone plan for the database-led refactor from prototype architecture to SQLite archive v2 + Core Data cache.
04-project/IMPLEMENTATION_STATUS.md Current implementation status and refactoring priorities.
04-project/SwiftData-Retirement-Inventory.md Current SwiftData dependency inventory and retirement slices.

99 Archive

Files in 99-archive/ are historical implementation notes. They are kept for context only and are not product requirements.

Removed / Replaced Objectives

These are not current objectives: - HealthProbe CloudKit/iCloud sync; - cross-device record-by-record comparison; - count-drop-as-data-loss alerting; - notification-led monitoring; - community reporting or open-source publication commitments; - macOS companion as committed product scope; - in-app backup transplant, restore, or HealthKit re-publication; - SwiftData as target persistence foundation; - backward compatibility with prototype/test databases; - recurring complete snapshots for large HealthKit datasets.

Document Maintenance Rules

Add new substantive docs only under HealthProbe/Doc/.
Update this index whenever a document is added, renamed, archived, or removed.
If a document becomes stale but may still be useful, move it to 99-archive/ and add a warning header.
Do not leave old copies in the repository root.
Product scope changes must update product docs first, then implementation docs, then code.

HealthProbe: local HealthKit observation history, recovery-compatible archives, no in-app restore.