# 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`](01-product/Product-Specification.md) |
| MVP behavior and out-of-scope boundaries | [`01-product/MVP-Specification.md`](01-product/MVP-Specification.md) |
| Database design, archive schema, differential storage, SQL analysis | [`02-architecture/Database-Design.md`](02-architecture/Database-Design.md) |
| Core Data cache schema and invalidation | [`02-architecture/Core-Data-Cache-Design.md`](02-architecture/Core-Data-Cache-Design.md) |
| Export formats, manifests, streaming contract | [`02-architecture/Export-Specification.md`](02-architecture/Export-Specification.md) |
| Implementation workflow, HealthKit capture, exports, tests | [`02-architecture/Implementation-Guide.md`](02-architecture/Implementation-Guide.md) |
| Forensic limits, export meaning, recovery compatibility | [`01-product/Forensics-Limitations.md`](01-product/Forensics-Limitations.md) |
| General agent ownership and handoff rules | [`00-agent-guides/AGENTS.md`](00-agent-guides/AGENTS.md) |
| SwiftUI/UI work | [`00-agent-guides/CLAUDE.md`](00-agent-guides/CLAUDE.md) |
| Refactoring milestones and sequencing | [`04-project/Refactoring-Plan.md`](04-project/Refactoring-Plan.md) |
| Import performance iterations and real-device timing comparisons | [`04-project/Import-Optimization-Log.md`](04-project/Import-Optimization-Log.md) |
| Project status and refactoring priorities | [`04-project/IMPLEMENTATION_STATUS.md`](04-project/IMPLEMENTATION_STATUS.md) |
| SwiftData retirement inventory | [`04-project/SwiftData-Retirement-Inventory.md`](04-project/SwiftData-Retirement-Inventory.md) |
| Historical UI notes only | [`99-archive/`](99-archive/) |

## Chapters

### 00 Agent Guides

- [`00-agent-guides/AGENTS.md`](00-agent-guides/AGENTS.md)
  Multi-agent development guide, ownership boundaries, protocol contracts, and current architecture decisions.

- [`00-agent-guides/CLAUDE.md`](00-agent-guides/CLAUDE.md)
  UI/SwiftUI-specific instructions aligned with the current Time Machine objective.

### 01 Product

- [`01-product/Product-Specification.md`](01-product/Product-Specification.md)
  Full current product specification, motivations, architecture decision record, and non-goals.

- [`01-product/MVP-Specification.md`](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`](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`](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`](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`](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`](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`](03-ui/README.md)
  Entry point for active UI guidance and links to archived UI notes.

### 04 Project

- [`04-project/Refactoring-Plan.md`](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/Import-Optimization-Log.md`](04-project/Import-Optimization-Log.md)
  Living log for first-import optimization work, measured real-device reports, bottleneck diagnosis, and next experiments.

- [`04-project/IMPLEMENTATION_STATUS.md`](04-project/IMPLEMENTATION_STATUS.md)
  Current implementation status and refactoring priorities.

- [`04-project/SwiftData-Retirement-Inventory.md`](04-project/SwiftData-Retirement-Inventory.md)
  Current SwiftData dependency inventory and retirement slices.

### 99 Archive

Files in [`99-archive/`](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

1. Add new substantive docs only under `HealthProbe/Doc/`.
2. Update this index whenever a document is added, renamed, archived, or removed.
3. If a document becomes stale but may still be useful, move it to `99-archive/` and add a warning header.
4. Do not leave old copies in the repository root.
5. 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.*
