Product and principles

Part of the Site Guide. Requirements are product direction, not capability receipts.

The promise

Health is a private longitudinal context, evidence and research workspace for an individual understanding their health and, where useful, helping people around them. It includes sleep, food, energy, movement, body changes, recovery, routines, known conditions, doctor visits and years of unresolved questions. A sparse record with unknown fields is useful. No one has to complete a medical intake or choose a disease before saving a note.

The durable value is the story: what the person noticed, measured, ate, did, was told, researched, decided and experienced later. A future AI should be able to inspect the story rather than inherit an old diagnosis as unquestioned truth. The person may save clinician diagnoses and AI opinions with their origin; Health does not make or endorse either.

You, your AI, and this site

• You choose the purpose, AI, health approach, private context, permissions, conclusions and all actions in the world.
• Your AI researches, compares, interprets, explains and drafts. Its capabilities and its own policies belong to that relationship.
• Health stores, connects, versions, searches, displays, retrieves and exports the work. It never diagnoses, prescribes, triages, treats or speaks as a caregiver.

Health's governing wording remains “Never diagnose — research and organize only.” AI research is clearly credited to its author. The person can ask their own AI for advice; the site does not answer the request or claim control over that external AI's behavior.

Context and trust

Every personal record starts private. A connection between records is not permission to disclose the connected graph. Selecting a Question must not silently include everything known about a Person. A brief shows the exact selected records, dates, file access, redactions and saved instructions. Changes in scope remain understandable and revocable.

Observation, imported source statement, AI interpretation, person's conclusion, proposed action, action taken and outcome stay distinguishable. An AI proposal never becomes a person's decision through an edit or resave. Corrections preserve earlier versions. A date range with no record means missing evidence, not no symptom or no activity.

Health is not an emergency service. Queue waits for the person's chosen AI. Keep this fact concise in Queue/help; do not make ordinary health logging look like an alarm screen.

Personal guidance

Three instruction purposes remain visible under Instructions & prompts:

The person may write these with their AI. AI-proposed revisions stay proposals until the person accepts them. A profile cannot alter access, suppress a capability refusal, or change what Health claims.

Dated adoption, 4 October 2026

Scott's request authorizes a Site Guide, cross-repository research, complete pages and an online site. It specifically emphasizes retaining all health context for later better AI review, public-domain/open-license outside research, individually added sources, tools/sites/resources, media, Queue, MCP, admin, Pro and stats.

Routine implementation choices in this guide: Topics and Questions use the corrected September model; Resources and Lists are first-class destinations; sources and personal research remain separate; shared sources begin with verified metadata and links; Pro is admin-assigned during soft launch, with no invented pricing or quota. These are technical/product-shaping decisions made within the request, not falsely attributed verbatim owner rulings.

Current Core §4 supersedes four-state Queue and old archive tools. Current Core §5 supersedes a second settings approval gate. Media v1.7.0 supersedes stripping private originals and defaults paid photo interpretation off. Existing Health text remains readable history; this guide records the correction rather than rewriting that history.

Records and relationships

Part of the Site Guide.

Initial building-block inventory

The dated owner clarification below refines this original inventory. In particular, Activity replaces the combined Food / Activity / Routine label, Visits and Tests are Activity categories, and Measurement includes recorded events and intervals.

Custom fields and Other kinds are allowed from the start. Prefer a useful common type over a table for every possible vital or condition. Store extra structure without requiring a premature universal medical ontology.

Building-block clarification — 4 October 2026

Scott confirmed Instructions for saved guidance and prompts: “It's ‘hey, use this instruction again.’” An Instruction is reusable content the person's AI can retrieve. A Queue request is a particular handoff, which may link an Instruction and ask the AI to use it. Instructions remain in the Library after any particular request is answered.

Measurement covers a recorded value, event or interval: body weight, sleep duration, sleep start/end, a cycle start date, a reported lab result, or a person's rating on a stated scale. Vitals is a category within Measurements. A date does not turn a narrative into a Measurement: “I felt unusually tired this afternoon” remains an Observation even with an exact timestamp. Both types retain when they happened. A cycle event records what the person actually reported; inferred dates or durations must be separate, attributed derivations rather than invented source facts.

Activity keeps what the person ate, did or took, with categories such as Food, Movement, Medication, Self-care, Routine, Visit, Test and Procedure. Planned activities remain distinct from completed ones. A visit/test Activity stores the event and its context, a Source holds the original report or recording, and Measurements hold extracted results linked back to that Source. The older Action record remains readable as an actual action; it is not a second place where new routine intake must be entered. A medicine in the household is a Resource; a reported dose is an Activity, linked to it when useful. Quantities, dates and the person's wording are kept without generating dosage advice.

Categories are lightweight, editable subtypes, with these starting suggestions rather than a mandatory medical classification:

Topic names, categories and tags remain person-controlled. Category describes what a record is; connections describe which Person, Topic or Question it concerns. An Activity may have several connections without being copied into several collections.

Resources, past ownership and care team — 4 October 2026

Resources distinguish Owned now · Previously owned · Considering · Reference. Previously owned preserves useful history about equipment, devices or products that were sold, returned, finished or otherwise stopped being owned. An ownership change never erases past Activities, Measurements, attachments or Research. Specific start/end dates and the reason for the change are optional context. Access and ownership are different: a borrowed device or a gym treadmill can be usable without being owned.

A dentist, primary-care doctor, pediatrician, women's-health provider or clinic is a Resource, categorized Care provider or Clinic. Keep the person's stated name, organization, role, contact details and links to the People they care for. The relationship can name a role such as Dentist or Pediatrician. One provider may connect to several People; the provider's general specialty and their role for a particular Person need not be identical. Former providers remain findable, with dated visits and reports attached. Creating a care-team contact never creates an account, grants access or sends anything to them.

Dated series and real intake — 4 October 2026

Body weight is one Measurement per actual weigh-in, connected to the Person. Each entry keeps the original amount, unit, date/time precision, method/device, source if supplied and notes. A later weigh-in adds a record; it does not overwrite the earlier weight on the Person. Correcting an existing reading preserves its revision history. A latest-weight display can be derived from the dated records; missing dates, units or readings stay visibly missing. Sleep and cycle histories follow the same rule: preserve source events and values before deriving comparisons.

Scott chose real personal use and withdrew the proposed fictional family member. A new private workspace starts empty. No fictional people are seeded into personal accounts, and real names, family relationships or health facts are never copied into public examples, fixtures, screenshots or the Site Guide. Marked synthetic development data remains a separate test corpus. Real intake waits for the dedicated private identity/database/media setup and its synthetic proof; the public preview is not a place to collect it.

Common envelope

Every private record has server-derived owner/workspace identity, stable opaque ID, record kind, title, body or structured fields, created/updated time, effective observation date/time and timezone where known, attribution, source/import context, provenance, version and archive state. A camera date, document date, person-stated date, upload date and inferred date are different facts.

Research adds AI/client identity when known, result date, purpose, selected input record IDs and versions, cited Sources and passage/page locators, assumptions, uncertainties and unresolved questions. Do not require invented model identity when the client does not provide it.

A Measurement retains original value/unit, method, device, whether reported or measured, and any reference range exactly as the report states it. Show original and converted units separately if conversion is supported. Charts separate incompatible methods and show missing periods. The site must not assign diagnostic color bands from its own medical judgment.

Connections

One record may connect to several Topics, Questions, People, Resources or Lists. Use typed reciprocal edges: about, evidence for, produced from, response to, possibly related, supersedes, and included in. Connection pickers search existing records, preview selections and allow removal. Counts navigate to the actual related set.

Do not copy Research into every Topic. Do not infer that two similar names are one Person or merge conflicting reports. Linking a source does not move its private content into a public catalogue.

Typed Activity and continuity

Detail pages show typed dated Activity: Observation, Measurement, Food, Activity, Test, Research, Request, Decision and Outcome. Keep ordinary metadata changes available under History rather than filling the main timeline.

A continuity brief includes the purpose, person-saved guidance, selected chronology, original sources, competing interpretations, decisions/actions actually recorded, changes since the previous review and remaining gaps. Second opinions are separately attributed documents connected to the same Question. Comparison shows agreement, disagreement and different assumptions without selecting a medical winner.

Corrections use version checks and save a readable history. Save batches return per-item applied, unchanged, conflict or refused outcomes. Retrying the same operation must not create duplicates or transfer AI authorship to the person.

Pages and collection controls

Part of the Site Guide. This is the complete page contract; route presence is not proof that the named workflow works.

Page inventory

Never add a public /tracker. Internal tracker readers remain repository artifacts. Personal paths use opaque IDs, never names or health content. Rename a route with a redirect/alias so saved links survive.

Naming clarification — 4 October 2026. Measurements is the umbrella collection (/measurements), including Sleep and Cycle categories; Vitals remains a compatible route/category. Activity is the building-block name, with Food, Movement, Medication, Visit and Test as categories. Tests and Visits is a view of Activity linked to original Sources and extracted Measurements, rather than an Encounter record kind. Resources also covers care providers/clinics and distinguishes owned now, previously owned, considering and reference. The initial route inventory above is preserved as its history; these labels win when building or revising the collections. The current /tests alias opens Activity; a dedicated combined Visit/Test filter remains a view refinement rather than an implemented separate page.

Navigation and readable detail

Desktop follows the newer Health prototype: Home, Topics, People, Resources, Lists, Library, Queue. Questions and all capture/log/research views are reachable from linked records and Menu. Search, capture and Queue stay easy to reach. The account menu groups Learn (Ideas, Connect, For your AI, Updates), You (account, Your Context, stats), appearance, Admin when authorized, and sign-out.

Phone bottom bar: Topics · People · Queue · Library · Menu. Queue is raised at the center. Menu holds Home, Questions, Observations, Vitals, Food & Activity, Tests & Visits, Timeline, Resources, Lists, Research, Sources, Instructions, Summaries and account/help. All jobs work on a phone. Use two or three meaningful columns and open remaining values on the row, with scroll contained inside a table when unavoidable.

Navigation refinement — 5 October 2026. The 30-scenario organization plan keeps working destinations in one header row, moving Library and People into the profile menu first as space contracts. Home, Topics, Questions and Queue remain easy to reach; add other destinations when they fit. Activity offers direct views of Observations, Measurements, Activities and Tests & Visits, while their direct routes remain available. The older desktop/bottom-bar descriptions above are design history; actual responsive behavior is verified against the implementation and dated release receipts.

Detail first screen shows the record title, person/context, latest relevant date, clear primary action and content. Expandable sections hold evidence, Activity, Questions, Research, Sources, Connections and History. Long research gets an internal contents list, readable line lengths, citations that open sources and preserved full content. Avoid large explanatory panels competing with the records.

Detail tabs — 5 October 2026. Separate major content types consistently: main content, Context & data, Connections, Photos & files and History. Add type-specific tabs such as Inventory, Measurements, Items, Sharing and AI response. Research input versions and citations belong in Context & data; they stay distinct from later connected records. Use disclosure sections inside these tabs for smaller details. Preserve drafts and selected files when switching tabs; opening another record starts with its primary tab.

Shared collection contract

Every large collection, Library shelf and detail's Activity/Research set supports Table, List and Grid, search, sort and the family two-line filter. Table is first visit's default on wider screens; phones (under 580px) open as List, with Table and Grid one tap away (design pass, 24 October 2026). Compact view icons have accessible labels, tooltips and clear selected state; remembered per-page choice wins at every breakpoint.

First line contains filter families. Selecting a family opens its options on the second line. OR within a family, AND between families. Opening another family keeps current selections. Selecting an active option toggles it off. All active options appear as removable chips with Clear all. Boolean choices such as Show archived need no second line.

Search and filters compose before pagination. Sort meaningful column headers; second tap reverses direction. List/Grid expose the same sort field and flip control. Do not drop filters when switching views or returning from a detail. Browser-local preferences are per account/page and cleared at sign-out; a named saved view is a separate durable record, not silently promised.

Display exact filtered counts only when the server computed them; otherwise show page range or “more results.” A drill-down count must open that exact set. Keep loading separate from empty and error, and a failed save separate from saved. Empty results provide Clear filters. Use stable sort tie-breaks, cursor pagination, indexed server filters and bounded reads for real collections. The MCP find tools accept these same filter families, enum values, sort fields and cursors.

Health visual direction

Use the current Claude Design project as a stepping stone: plum ink, dusty rose, pale cool grounds, restrained green status accents, serif headings and clear sans-serif data. The older philosophy's plum direction is compatible; brand assets supply the logo. Use a compact quiet shell, thin rules, consistent spacing and deliberate table columns. Photos are evidence and grids earn their space where images help.

Light and dark modes are intentional, with readable documents and media in both. Charts show units, observation dates, method changes and gaps. Use keyboard-operable controls, visible focus, reduced motion, legible contrast and useful touch targets. No invented health score, decorative dashboard numbers, robot/sparkle AI icons or generated medical judgment.

Collection refinements — 5 October 2026

The account name opens the combined profile and page menu. People moves into that menu on narrow screens; the phone bar uses Topics, Lists, Queue, Library and Menu. Activity remains available from Menu. Account management and sign-out remain identity-provider actions, and Admin is shown only to authorized administrators.

Table mode offers a Columns chooser. Its display preference is remembered per account and collection in the browser. Recorded by and Occurred are optional rather than default columns. People defaults to Name, Category, Relationship and Updated; its single record kind does not need a Type column or filter. The actual relationship label (for example, Brother) remains separate from the broader category (Sibling). Categories group the main kind or area of a record; optional tags connect records across those groups. Topics use concise titles while preserving full context and version history.

Exact system timestamps display elapsed seconds, minutes, hours or days through 30 days. Older timestamps display the date. Hover, focus or click reveals the complete date and time. A source's approximate or date-only occurrence retains its recorded precision rather than being turned into an exact instant.

Phone filter families scroll in a single strip rather than consuming several rows. Search, sort and selected filters remain visible. Collection actions wrap, editor fields stack on small phones, and selected tabs have a visible state. The UI system map identifies shared tokens, component owners and loading conventions for future changes.

Capture and workflows

Part of the Site Guide.

Many ways to begin

One question, a feeling, a report, a photo, a recording, a measurement or a saved AI answer can begin a record. Require only what the chosen kind needs. Context is an optional tap: Person, Topic, Question, date, files and reusable instructions. Choosing nothing must not discard the content. Preserve unsaved work during navigation and make failures recoverable.

The Home composer separates Save a note (the person's words, stored now) from For my AI (a preserved instruction in Queue). Vitals and structured activity are quick capture choices, not another mandatory workflow. A clearly chosen Person stays visible while logging. Never silently attach another household member.

File capture accepts camera/library photos, documents and audio. Audio recording shows start/stop, duration, playback, re-record and clear keep/remove controls; it is a recording only after real bytes exist. A photo or recording may be the whole request. Pending uploads remain visibly pending and recoverable. No “saved” success until the storage result confirms it.

Queue

Queue is the durable handoff to the person's chosen AI. It does not launch an AI or run a background research worker.

The composer needs a directive only. Context/attachments are optional. “Add this photo,” “save what I ate” and “keep this doctor's original report” are valid work; do not force research fields.

A request shows original words, who added it, context, attachments, created date, priority set by the person, status/flag and an outcome. Detail shows what was done, which records changed, summaries first, full research one tap deeper, files, and remaining questions. A response can be partial. Set Answered when a useful response is stored, not because an AI made a call or a file was attached. AI working should not falsely imply a currently running process when the client disappeared.

A connected AI may add requests captured from what the person asked for or agreed to, and related follow-ups from that conversation, attributed added by your AI with conversation provenance where available. New unsolicited proposals go to AI Suggestions. Accepting a Suggestion creates a real Queue request with chosen context/depth; suggestions never leak into Queue find results, counts or state tabs. Suggestions show a presence dot, not a badge count.

Manual handoff always works: preview and copy/download a bounded brief, use it with the person's AI, then save/import the attributed result. Connection problems leave the request and its content intact.

Library and long research

Library is a small go-to shelf, with Research · Sources · Instructions & prompts. Resources may be a fourth Health shelf. All Sources and Research remain findable in their collections and on connected records regardless of shelf membership. Shelving is a flag, not a copy. Unshelving never deletes.

The person's AI can add substantial research to the shelf, with attribution; the person can remove it. Instructions distinguish communication, approach and method. Public prompts are optional curated content and never replace a person's profile.

Research readers preserve full documents, structured supporting data, source citations and revisions. The overview helps someone choose what to read; it is not the only stored result. A citation opens the source and its relevant location. A source opens its connected research. Comparing two AI opinions preserves each opinion's author, date, inputs and assumptions.

Longitudinal observations and correlations

Typed logs share a timeline and can be viewed by Person, Topic, Question or date. Meals, exercise, sleep, medications the person reports taking, measurements and feelings stay separate facts that can be compared. Keep quantities, times, timezone, method and missing values visible. The person or their AI may add a suspected association as an attributed hypothesis; the site does not call it a cause or decide treatment from it.

Routine/planned actions stay distinct from completed events. A clinician's prescription or an AI suggestion is not proof the person took a medicine. Preserve the original advice/report as a Source, the person's decision if recorded, the action actually reported, and later outcomes.

First personal intake — 4 October 2026

Begin with actual records the person chooses to share, after their private workspace is activated. Voice can help collect and organize their account; a supplied audio file is preserved as a Source with its original bytes. A conversation transcript does not prove that a separate original audio file was saved.

Collect a small first batch and let it test the building blocks:

1. People: who the records concern and the relationship labels the person wants. Do not create an account or infer permission from a subject record.
2. Topics and Questions: interests, reported known issues and what the person wants their AI to investigate. Preserve the person's phrasing and distinguish reported diagnoses, suspicions and unanswered questions.
3. Care team: providers/clinics, who each cares for, role, current/former context and contact details the person has.
4. Resources: medicines/products, devices, equipment, useful sites and services; owned now, previously owned, considering or reference. A label photograph can remain the original Source for the person's resource description.
5. Dated context: existing weight readings, wearable sleep exports, cycle events, meals, activities and medication intake. Keep original units, dates and source files; the person need not recreate a complete history to begin.
6. Sources and Instructions: original reports/photos/audio and the person's reusable directions for their AI.

Review the extracted records, proposed categories, People and dates with the person before committing real intake. “Unknown,” an approximate date and an exact timestamp are different facts. Missing details become optional follow-up questions or Queue requests; they do not justify making up a measurement. Connecting a wearable Resource does not establish a live wearable import.

Appointment-ready observation summary

Select a Person, purpose, date range and evidence; show the exact included records/files. The person or their AI drafts a concise summary: dated observations in the person's terms; measurement units/methods; original reports; relevant context/actions; changes; missing evidence; questions to discuss. Credit its author and input versions.

The person reviews, corrects and saves it as a versioned artifact. Print/export does not publish or contact a clinician. Share, if implemented, previews the exact artifact and separately chosen attachments and uses revocable narrow access. A future summary never overwrites earlier context or turns a clinician question into a site diagnosis.

Acceptance examples

Use only clearly marked synthetic fixtures for every test and screenshot. Prove one coherent journey with more than a tiny demo: multiple People, Topics, Questions, 30+ dated mixed observations/activities, incompatible measurement methods, several original files, long Research, competing opinions and pending requests. The exact fixture count is a useful corpus choice, not a product-quality target.

Exercise capture → connections → filtered timeline → Queue handoff → attributed result → source reader → corrected summary → reload. Separately exercise an attachment-only request, Needs your input on an Answered item, and a second AI continuing a Question without overwriting the first opinion.

Sources and public catalogue

Part of the Site Guide. Scott's 4 October direction adds a public catalogue of public-domain/open-license outside research. Health curates access and provenance; it does not publish its own medical verdicts.

Three different things

Source is outside evidence: a paper, report, original test, article, book or recording. Research is work the person or their AI writes using sources. Resource is something useful to visit/use, such as a site, app, device, directory or tool. They have connected but separate collections. Listing a Resource does not promise availability, endorsement or an integration.

Users can individually add source metadata, links and their permitted private files. This never grants public redistribution rights. Store who supplied it, what rights are known, when it was accessed and whether the stored item is an original, extraction, link or derived copy. An uncertain license can be kept as a private/link-only reference; never label it public domain by guessing.

Public ingestion contract

Public-readability does not establish permission to republish. PMC's reusable subset has varying license terms, and individual figures may have separate rights. Use the repository's stated dataset/access services rather than systematic scraping of its article website. See PMC Open Access Subset, copyright and retrieval rules, and supported article datasets.

Begin with a small metadata/link catalogue. Full-text and media ingestion are a separate checked lifecycle:

1. Identify the exact article/edition/version and official source.
2. Record title, authors, publisher, DOI/PMCID if present, publication/version dates, retrieval/check date, canonical link and license name/version/link/evidence.
3. Check permission for the actual proposed use, including commercial redistribution, derivatives and any third-party figures/supplements. Unknown, noncommercial, no-derivatives or custom restrictions remain link-only/review-needed until that use is established.
4. Store permitted exact bytes and checksum, source attribution and any required notices; extraction points back to those bytes and page/section. An excerpt is not a stored full article.
5. Publish only explicitly allowlisted public fields and licensed assets through a deliberate admin action. Public entries are sourced independently, never generated from private health workspaces.
6. Preserve ID and version history. Correction/retraction/rights changes can retire or unpublish a record without breaking private citations; show status and last check. Takedown removes public delivery and derivatives while preserving authorized private originals where appropriate.

A public nomination is a separate record containing only the nominated public metadata. It may originate from a person's explicit nomination, but an admin cannot read the private record behind it. Admin review checks the nomination's allowlist, identity/provenance, license/version/date and publication status. A public asset is always a separate cleaned copy, never a private original URL.

Verified starter metadata, 4 October 2026

These are outside articles with publisher license notices checked for a metadata/link starter catalogue. No article body, image, personal participant data or interpretation was ingested during the guide research.

PLOS's terms describe its normal attribution-based publishing terms with exceptions. A journal-wide policy helps discovery, but the exact article/asset notice remains the ingestion gate. This catalogue makes no claim that a paper's findings apply to a user's situation.

Structured starter metadata preserves the verified fields for builders. It is not an ingestion log or deployed catalogue receipt.

Catalogue UI and AI reads

Public Sources shows title, kind, authors/publisher, year, license, available form (external link, full text, files), updated/checked date and correction status. Topic classifications organize discovery without making health judgments. A detail reader keeps attribution and rights visible; link-only records offer Open original, never a false local-reader action.

Library catalogue/checkout tools can return public metadata alongside the person's permitted private shelf. Public reads and private reads remain distinct. A person can save a public reference into a List or connect it to a Question without duplicating the whole article. License, provenance and exact version travel with the reference and any exported content.

Media

Part of the Site Guide. Adopt the binding family Media Storage Standard v1.7.0, freshly read from family main on 4 October 2026. Local family copies inspected were older; build against the canonical file.

Evidence first

Photos, original lab PDFs, voice notes, screenshots and other files are durable bytes. A link, browser preview, base64 caption or pending slot is not an attachment. Preserve the private original byte-for-byte, including its metadata, with original checksum/length/MIME and exact provider version. Generate separate safe display and AI copies. Never silently replace an original with a resized or cleaned copy.

Dates retain provenance: capture date, person-stated date, document date and upload time may disagree or be unknown. Health defaults precise photo location and other sensitive metadata out of AI/share display. Revealing it is a deliberate person-selected disclosure; do not import Buying's location assumption into Health.

Storage and authority

Convex (or the deployed product database) is the authority/control plane: owner, record relationships, grants, sensitivity, visibility, byte manifest, upload lifecycle, rights, idempotency, retention and deletion. B2 is an encrypted byte store, never the authority.

Use separate production-private, production-public, nonproduction-private and nonproduction-public buckets; collision-safe names contain no private content. Enable SSE-B2, exact-origin CORS, narrow bucket/environment server-only keys, exact version/hash manifests and application-owned version cleanup. Fail closed when bindings are missing. Never copy Buying's single shared development/production bucket as family conformance.

Private originals are reached only after application authorization. Trusted view access and original download are distinct. Unlisted sharing resolves a revocable opaque token into a short-lived safe-copy capability. Public content uses a licensed cleaned derivative. Sharing a record does not silently include its files. Provider keys never reach a browser or AI.

Upload and AI transfer

Person uploads show type/size limits before transfer, progress, retry, verified stored state and per-file results. Images are fully decoded, not accepted merely for a JPEG header. Inspect actual bytes and lengths server-side. At upload, make the guaranteed standard AI copy and useful table/grid/detail copies, keeping their exact versions in the cleanup map.

AI uploads use begin → first-party no-redirect relay PUT → verified finish. URL remains on Health's canonical hostname; provider hostnames are not an ordinary setup burden. Bind operation ID, target, checksum/type/length, token hash and expiration. Recheck owner/grant/target at finish, protect committed versions against overlapping finalizers, clean terminal failures, and retry failed lanes with the original operation IDs. A pending device-fill slot stays visibly pending until bytes arrive.

AI evidence reads return bounded protected content blocks with arithmetic reply budgeting and pagination. For large photos, return the standard safe copy instead of refusing for size; report original/served dimensions and bytes. Offer full-resolution regions and saved close-ups for labels. Contact sheets with numbered legends let the person's AI inspect many photos efficiently. Never hand it a permanent public/private storage URL.

Only list assets actually readable under the current grant and lifecycle. Revocation blocks the next read/finish. Deleting assets read as absent on every path: owner render, download/export, shares, trusted viewer, AI batch and capability issuance. Ordinary AI write authority cannot publish, share, reveal originals or change visibility.

Audio and transcription

Record real audio with playback before keeping. Measure volume/silence on the device, show an explicit keep-or-record-again choice for silent clips and never send silence to a transcriber. Preserve recording bytes, duration, capture method, measurement and transcript provenance. A transcript is text derived from the recording and never replaces it.

Scan audio metadata on the server before disclosure; an unscanned/unreadable asset fails closed. Spoken personal details can be sensitive even when container metadata is clean. Apply the recording's sensitivity/context gate to its transcript.

Some clients can read audio and some cannot. Prove that ability for each named client before saying it can hear a recording. Tool output gives text when available and an honest fallback when the client cannot process audio. Never invent what was said.

Pro transcription is a possible bounded convenience under operations; it requires a configured provider, audited Pro flag and deliberate use. Paid photo interpretation stays off by default. Health performs no automatic medical interpretation of media.

Counts, deletion and proof

Count per-account original and all derivative bytes, including close-ups, in the same transaction as store/erase. Counters can be reconciled through bounded read-only scans. No invented free/Pro allotment or quota.

Permanent deletion removes every version of originals and every derived copy, including lazily created variants, after checking other record uses. A file still connected elsewhere is kept and the result explains why. Stop serving immediately, revoke shares and preserve retryable pending cleanup until provider absence is verified. Export includes owned original files, metadata, attribution and permitted derived work. Disclose actual backup retention once verified rather than claiming instant physical absence everywhere.

Proof needs marked synthetic real-byte canaries: upload, validate, render, protected AI read, replay, cross-owner denial, revoke, delete and exact all-version absence. A mocked storage function, provider HEAD response or a working file picker does not prove this lifecycle.

Implementation amendment — October 5, 2026

The Next server now implements bounded 1 MiB first-party parts, byte/hash verification, immutable original and thumbnail/card/display/AI manifests, safe image renditions, protected role-specific viewing and explicit original reads. Both website sessions and verified OAuth calls recheck current record reach; AI upload commits also check the current grant in the database transaction. Original audio container/track metadata is scanned before delivery; recording transcripts remain separate records. Browser recording uses preview and deliberate selection before saving.

Finish reconciles only the current upload's opaque provider prefix. A lost exact-version registration can be recovered from provider metadata and a full byte/hash read. Recovery never deletes pending uncertain versions. Cleanup happens after an immutable ready manifest and verifies absence before forgetting candidates. Person-confirmed deletion inventories all versions of the upload prefix and refuses deletion while another record references the original. Detaching one reference leaves bytes intact.

These are source and local execution-seam capabilities. Hosted bucket configuration, real signed-in playback, authenticated OAuth transfer, exact provider cleanup, and named-client lifecycle are not established by these checks. Contact sheets, full-resolution crop retrieval, paid transcription and unlisted sharing still require their separate implementation and proof; the current role reader does not claim them.

AI contract

Part of the Site Guide. Use Core v1.14.1 §5, the family Bring Your AI MCP/OAuth Standard v1.1.0, current Connector Playbook and Media Standard v1.7.0. Product tool names below are a builder contract; only deployed verified tools appear in live /ai documents.

Useful workflow tools

Keep a compact product-shaped surface over the same services used by the interface, not a parallel database API. Batch is the normal write shape, with per-item results. Tool names may be consolidated when implementation makes these jobs clear.

The 5 October game plan extends this proposed catalogue with paged series reads/imports and precise Queue updates, and specifies source-linked packets, recorder/assertor attribution, selection manifests and current grant enforcement. Neither catalogue is a live-tool claim; the deployed guide remains authoritative for availability.

Find accepts recordKinds, query, personIds, topicIds, questionIds, dateFrom/dateTo, author, archived, scope, record-specific filters, sort, direction, field selection, limit and cursor. Owner/workspace is always server-derived. Unknown or cross-owner IDs get the same refusal. A cursor lives in each request, never connection state.

Normal calls are generous but bounded. Research context is discovered through indexes/search and retrieved in relevant passages/full sections rather than one giant account dump. Library checkout carries the exact item version/license. Defaults do not silently broaden a Person into all their records.

OAuth and grants

One product-native /mcp endpoint serves stateless remote Streamable HTTP. Every request verifies identity and resolves the current durable grant. Records, Queue and grants are durable even though transport state is not.

Anonymous access supplies correct protected-resource metadata and OAuth challenge; authorization-server metadata is discoverable. Only identity scopes appear in OAuth scopes_supported and the 401 challenge. Product capability permissions are stored in the durable grant and checked server-side, never inferred from token scopes or client-provided owner IDs.

CIMD-first is the resource-server direction; validated DCR is a compatibility path when the actual identity provider requires it. Verify current provider/client behavior before advertising protocol or named-client conformance.

OAuth sign-in plus Allow is approval for the site's normal full toolset. On first authenticated call, reads and normal writes work. /settings/ai is for inspecting, narrowing and revoking, never a second enable screen. The person may deliberately opt into an extra manual-review barrier; it ships off. An AI may opt itself out but never back in. A new/wider grant requires the person's action.

This does not grant person-only actions: archive/delete, export, public publication, sharing, invitation/access changes, provider contact, scheduling, purchasing, ordering tests or treatment. Older Health archive_restore planning is superseded by current Core's person-only archive rule. None of the normal tools performs those actions.

Writes and receipts

Use stable per-operation and per-item IDs bound to the intended payload. Expected-version checks protect concurrent edits. One accepted batch gives per-item outcomes and human-readable links/receipts. Validation refusal does not consume the ID needed for a corrected retry; successful, unchanged or proposal outcomes can retain replay receipts.

No hidden change from AI to person authorship through resave. The site checks author/actor and proposal boundaries inside the transaction. Ordinary saves cannot accept a person's conclusion, widen permissions or silently activate instruction revisions. A saved research document does not mark a Question settled.

Public guidance and client proof

Generate /ai, /ai.txt, /llms.txt, tool catalogue and setup copy from one live contract: exact hostname/endpoint, version/protocol claim, tool names, limits, normal read/save path, byte behavior, OAuth/grant model, errors and recovery. Give the next AI enough guidance to succeed without rediscovering the project.

Connection help distinguishes successful OAuth from a client's local-file permission and network-egress policy. First-party relay minimizes the latter to Health's hostname. Specific client menu instructions are dated and sourced. Return terminal versus retryable failures honestly; no endless retry for unavailable provider bindings or corrupt bytes.

The person can use a manual Queue brief immediately. Public connection claims/controls appear when the exact deployed connection has been proved. Named assistants may be examples; support is claimed only for a dated real client lifecycle: discover → consent → brief/evidence → save → inspect/reload → replay/conflict → revoke → reconnect → exact synthetic cleanup. A 401, a listed tool or copied sibling server is not that proof.

Connection correction — October 6, 2026

Use the current family MCP/OAuth v1.3.0 guide and its connector playbook, checked against working Plants and Buying source. The canonical OAuth resource remains https://www.assistwithhealth.com/mcp. Machine entry/discovery and first-party media paths bypass application apex redirects; Vercel’s domain-level redirect must also be removed after this code is deployed. Ordinary apex pages still canonicalize to www.

Clerk OAuth JWTs may omit aud; verify the dedicated issuer, RS256 signature, OAuth access-token type, subject, client identity and expiration, then enforce the current Health grant. Every present audience must name the exact canonical resource. Website/ID tokens, wrong audiences and unapproved registered clients remain refused. Discovery includes the provider’s supported offline_access scope for refresh; Health product permissions remain in its grant.

Claude web discovery was observed reaching the consent screen using its published CIMD identity. Consent, authenticated tools, media and full lifecycle proof remain separate from that discovery result.

Operations and proof

Part of the Site Guide.

Admin

Admin uses the current prototype's four areas: Overview · AI activity · Accounts · Public catalogue. Only server-verified authorized admins can read/mutate these services. UI gating alone is insufficient. Deployment configuration must fail closed when an owner/admin binding is absent. A test/sample Admin page is labelled synthetic and has no privileged backend access.

Overview uses counts and operational aggregates: accounts, observed sessions, storage, Queue traffic, public items and errors. AI activity shows tool name, time, outcome/error code, duration and compact receipt identifiers. Account support shows permission/plan flags, client/build metadata, service errors and resource counts. Admins never inspect private health bodies, attachments, directives, search terms or generated research. Redact logging/support payloads at the source; a health title in an error log is private content too.

Accounts allows authorized admin Pro assignment/removal with who, when and note. Admin-role assignment is a separate creator-authorized security action; Pro is a plan flag, never an admin role. Do not invent support impersonation or grant an AI admin authority.

Public catalogue publishes only independent rights-checked metadata/bytes and explicit safe nominations. Admin checks attribution, rights/license/version, original URL, checked date and retire/correction history. It cannot promote arbitrary personal content by passing a private record ID. Retiring preserves IDs and previously saved reference provenance.

Pro

Scott requested the Pro pattern. Adopt family media v1.7.0's administrator-first plan flag: admins have Pro, admins may assign it with a dated audit record, no checkout, price, upsell or free/paid quota is invented during soft launch.

Pro may hold costly conveniences such as transcription if provider configuration and a concrete opt-in workflow are available. It never adds health reasoning to the site. Background photo interpretation remains off by default; the person's own AI gets efficient copies, regions and contact sheets. Free records, useful uploads and the normal MCP connection remain useful independently of Pro.

Every enabled provider convenience is labelled automatic, keeps original bytes and user/AI words, records model/date/cost and failure state, obeys per-item/day limits and never overwrites a human title/transcript or an AI result. No plan means no data sent. Provider billing, real-data trials or new disclosure are separate consequential boundaries. A plan flag alone is not a working Pro feature.

Your stats

Show what a person has actually built: counts by Health record kind, media original/derived bytes, dated capture/research activity, Queue requested/answered/waiting and observed MCP reads/writes/outcomes. Start with records, stored bytes and calls; add useful weekly/monthly history only where events exist.

Define each metric's date range/timezone, inclusion, archive policy and coverage. One call, one successful batch and several changed records are different counts. History unavailable before instrumentation is unavailable, not zero. Partial periods are visibly partial. Do not invent AI tokens, reasoning effort, health improvement, money saved, avoided diagnoses or clinician outcomes. No streak guilt or health score.

Admin stats use aggregate operational facts, not private content. The person's clinical measurements live in their private timeline; platform stats never infer health state from them.

Data controls

The person can inspect grants/activity, revoke AI access, view any active shares, export durable records and owned files, archive/restore records and request explicit deletion. Archive is reversible and default; permanent delete is a separately confirmed action with exact media cleanup and remaining shared-use/backup facts visible. No ordinary MCP permanent-delete/export action.

Sharing, if available, is narrow, previewed and revocable, with independently selected safe attachments. Unimplemented sharing must remain non-actionable; building a share button does not prove access control. Account deletion is site-specific and includes identities/grants, records, relationships, bytes/derivatives and content-free cleanup evidence without affecting other Assist sites.

Build and release

Preserve the family build order Memory → Bring Your AI → Workspace → Proof. UI/design can proceed in parallel and does not gate the first two stages. Scott's request includes the whole page inventory and an online site; soft launch may expose marked public synthetic previews while protected provider/identity configuration is completed, but previews never become a private-data substitute or a claim that account/MCP/media lifecycle works.

Use existing GitHub, Vercel, Convex and Clerk projects when available; inspect live project bindings without revealing values. B2 follows the current media standard. Verify frontend and backend deployments separately with exact source SHA/version and project/environment; merged source is not a deployed backend.

Keep public claim labels on the family ladder Current / Partial / Later; priority is separate. Unbuilt pages in the requested launch scope stay in scope even when their capability evidence is Later. Public updates carry accurate deployed/local states. Never turn a verified preview into a named-client commitment.

Focused proof and receipts

Run required repository checks and realistic synthetic flows. A coherent set of desktop/tablet/phone scenarios establishes capture, dense collections, details/readers, Queue, activity, source provenance, persisted writes/reload and export. Real storage/action seams, unauthorized second-account access and grant revocation need successful paths as well as refusals. No screenshots or routine acceptance fixtures use real private health data.

Keep evidence separate:

The report puts any genuine Scott dependency first, then says what was implemented, tested, independently reviewed, deployed and observed live, and the exact remaining gap. Stop only for actual consequential boundaries or unavailable configuration/access. A missing provider does not justify stopping unrelated page/workflow construction.

References and adoption record

Part of the Site Guide. Checked 4 October 2026.

Canonical Health direction

• Project Philosophy v1.8.0: responsibility split, durable evidence, extensive research, second opinions, synthetic-first, appointment summary and instruction profiles. Its September correction makes Topics/Questions current direction; earlier Threads/four-state sections remain historical.
• Round-one brief and Ideas and Usage round: working dense-filter design, relationship model, public home and family strip; prototype evidence only.
• Current Claude Design project: newer Health visual/navigation reference inspected by the parent executor during this run; its Home/Topics/People/Resources/Lists/Library/Queue, stats and admin directions guide the app. Prototype pages do not prove provider behavior.
• Tracker Guide and Ready Work Orders: Memory, Bring Your AI, Workspace and Proof approved in August; old terminology must be reconciled to current family Queue/permission rules.

Family standards

Family GitHub main freshly inspected via authenticated read-only API. Main commit at inspection: 71ff0ca998c8b279cb4edd94cff477fdce30a327. Local family checkout was older and dirty; nothing there was changed.

Sibling examples read

• Scriptures Site Guide, edition 9, 3 October: concise index with one topic source each; building blocks and full route table; full Research/Documents; source rights; capture and Queue; principles with admin-assigned Pro and no paid launch promise. Read shell-public-admin, AI contract, capture/workflow, record model and principles topics.
• Plants Site Guide, 29 September: sparse starts, dated observations, separate observation/inference/action, exact private originals, context longevity and no automatic cross-site access. Plants is a family media/MCP implementation reference, not proof of Health support.
• Buying Project Philosophy, local v2.3.0, 13 September: Lists for many purposes, natural notes, distinct Resources/context, profile persistence and meaningful measured stats. The requested Buying Site Guide was not present in the checked local/main tree; this existing product guide and the family standard's dated Buying media amendments supplied the comparable contract. Do not falsely say a missing file was read.

Sites stay independent. The person's authorized AI may move selected context between Assist sites at their request, citing origin; Health performs no silent cross-site sync.

Public rights references

The guide used official PMC subset, PMC copyright, PMC datasets, PLOS terms and exact publisher article notices in Sources and public catalogue. These support the ingestion gate, not a medical recommendation. Refresh policy and exact asset rights at ingestion; they can change.

Thirty uses of Assist With Health

Planning exercise, 5 October 2026. These are workflows, not patient fixtures, clinical instructions or claims of working capabilities. Read alongside the database and MCP game plan and the Site Guide.

For every loop, the person chooses what to capture and what their chosen AI may see. Health stores, connects, versions, retrieves and displays. The chosen AI does the interpretation, research and drafting; the person decides what to do and records what happened. An AI proposal does not become a diagnosis, clinician instruction, completed activity or accepted decision merely because it was saved. A manual selected-context brief supports the same loops when MCP is unavailable.

1. Understand day-to-day energy

• Goal: Make an ongoing investigation of feeling tired or energetic usable across many conversations.
• Capture: Observations in the person's words; optional ratings with a stated scale; sleep, meals, movement, environment and stress context; an Energy Topic and an open Question.
• AI contribution: Retrieve comparable periods, explain missing context and competing hypotheses, and propose a manageable logging approach. Preserve the research and its evidence rather than saving only a conclusion.
• Person and return loop: Choose which observations to record; accept or reject proposed logging; return with new entries and compare against the earlier investigation.
• Storage/MCP edge: Narrative remains Observation even with a date. Ratings are Measurements only with their original scale. Search and time-window retrieval must find linked cross-topic context without turning temporal association into a causal relationship.

2. Explore sleep across wearables and changing schedules

• Goal: Understand sleep changes around shift work, travel, parenting or a different device.
• Capture: Sleep intervals and durations; device Resources; original exports or screenshots as Sources; subjective sleep Observations; dated schedule Activities.
• AI contribution: Compare the selected series, distinguish missing nights from short nights, and explain where device estimates or changed methods limit comparison.
• Person and return loop: Choose a research question or routine to try, log actual changes, then review later data alongside how they felt.
• Storage/MCP edge: Effective date, interval boundaries and timezone differ from upload date. A report transcription is not a raw device export. Series retrieval needs coverage, method and provenance, and imports need duplicate protection.

3. Keep exercise and recovery context

• Goal: Connect activity, equipment, discomfort and recovery over time.
• Capture: Movement Activities with actual versus planned status; duration, distance and exertion when supplied; recovery Observations; selected wearable Measurements; equipment Resources.
• AI contribution: Summarize the recorded pattern, research the person's question and help prepare an appropriately attributed training or clinician discussion document.
• Person and return loop: Decide which plan to follow or discuss, record what was actually done, and add outcomes rather than assuming the planned session occurred.
• Storage/MCP edge: Planned and completed are separate facts. The same treadmill, shoe or brace can connect to many activities; equipment ownership does not prove use. Context retrieval must follow these links without copying the records.

4. Follow body measurements and weight change

• Goal: Keep a meaningful history rather than a single current weight on a profile.
• Capture: One Measurement per reading with original units, method, date precision and measured/reported/estimated distinction; relevant routine and life-change context.
• AI contribution: Describe changes in the selected series and help distinguish observed change from possible explanations.
• Person and return loop: Supply later readings; correct mistaken entries; decide which questions or further context matter.
• Storage/MCP edge: An estimate cannot silently replace a measured reading. Latest value is a view derived from history. Unit conversion must preserve the original. Corrections version an entry; new readings add entries.

5. Investigate food, drink and hydration questions

• Goal: Preserve what was consumed and the context needed for later nutrition or symptom research.
• Capture: Food and drink Activities, quantities if known, original label or meal photos, preparation/context notes, and related Observations or Questions.
• AI contribution: Organize the supplied intake, flag incomplete quantities and investigate questions using the person's selected approach and sources.
• Person and return loop: Choose which questions to pursue; record actual changes and experiences; revisit the original intake with improved information.
• Storage/MCP edge: A photo-based or AI-estimated quantity remains an attributed estimate awaiting confirmation, not an exact meal record. Food in the household is a Resource; consumption is Activity. Batch capture must retain per-item uncertainty.

6. Investigate recurrent headaches or another repeating symptom

• Goal: Carry a long investigation across episodes without locking onto an early explanation.
• Capture: Episode Observations, reported onset/end and severity scale if available, food/drink/sleep/environment context, medicine Activities, originals and prior Research; a persistent Question.
• AI contribution: Compare episodes and counterexamples, identify gaps and competing hypotheses, and draft a clinician-ready chronology.
• Person and return loop: Choose what to log; discuss the summary with a clinician; record the clinician's words and later episodes; revise the investigation without deleting prior theories.
• Storage/MCP edge: An episode can have several observations and measurements without requiring a disease-specific table. A proposed trigger uses a possibly-related edge. Query by occurred time and show unknown episode boundaries rather than inventing durations.

7. Record a new short-term health concern

• Goal: Keep a clear account of a new event so conversations and a possible care visit do not start from memory each time.
• Capture: Original voice/text account, photos if chosen, dated Observations, actual readings, actions taken and the eventual visit/test Sources.
• AI contribution: Retrieve the selected account, help formulate questions and draft a factual summary with missing information clearly visible.
• Person and return loop: Decide what real-world help to seek; record any visit and what happened afterward; return if the concern persists or changes.
• Storage/MCP edge: Health is not a triage engine. No urgency or diagnosis is assigned by the site. A Queue capture request may log context without creating an investigation or a completed visit.

8. Keep ongoing-condition monitoring usable

• Goal: Bring home readings, clinician records and lived experience together for an already documented condition or an unresolved concern.
• Capture: Source-attributed condition history, Measurements with devices/methods, Observations, actual medicine Activities, visits and clinician-provided plans.
• AI contribution: Explain the supplied documents, compare chosen time periods and prepare questions or a review summary; cite ranges only when a source supplies them.
• Person and return loop: Discuss the summary or questions with the care team, add their response as a Source, and continue the actual history.
• Storage/MCP edge: Clinician diagnosis, person suspicion and AI interpretation require different attribution. The site supplies no automatic diagnostic bands. A series query must retain source ranges, units and methods.

9. Track actual medicine use and reported effects

• Goal: Remember which product was actually taken, when, why and what the person noticed.
• Capture: Medicine Resources, bottle/unit details, original labels or prescriptions, reported dose Activities, effects Observations and reusable capture Instructions.
• AI contribution: Retrieve the exact product evidence, organize use history and research or prepare questions using those verified details.
• Person and return loop: Confirm ambiguously identified products, decide what to discuss with a clinician/pharmacist, and record later use and effects.
• Storage/MCP edge: Owning a bottle does not mean taking it. Brand names do not establish formulation. An expiry photo belongs to a particular inventory unit, and an expired stored bottle does not prove that bottle was used. Imports must not manufacture dose events.

10. Preserve allergy, intolerance and adverse-reaction history

• Goal: Keep prior reactions and clinician findings findable without conflating them.
• Capture: Exposure Activities, reaction Observations, test/visit Sources, extracted results, clinician-attributed findings and the person's original recollection.
• AI contribution: Build a source-linked reaction chronology, compare conflicting accounts and prepare questions about uncertainty.
• Person and return loop: Review and correct the chronology; add later professional findings; record actual events without treating an AI hypothesis as confirmed allergy.
• Storage/MCP edge: Person-reported suspicion and documented finding can coexist. Conflicting records need separate authorship and version history. A brief should carry its certainty and source, not flatten everything into one profile checkbox.

11. Compare laboratory and other test results over time

• Goal: Understand a new report alongside prior results while preserving the actual documents.
• Capture: Test Activity, original report Source and protected media; individual extracted Measurements with analyte, unit, report range, method and page locator when available.
• AI contribution: Explain the source, compare compatible results, identify transcription conflicts and create cited Research or visit questions.
• Person and return loop: Check uncertain extractions, choose what to ask the clinician and add their interpretation as a separate attributed record.
• Storage/MCP edge: Ordering, collection, result and upload times differ. Reference ranges belong to the report, not a site-authored rule. Extraction links to the original and must remain reviewable; later corrections cannot erase what a prior AI used.

12. Prepare for and record a procedure

• Goal: Carry the relevant history, preparation documents and recovery account through a procedure and later years.
• Capture: Planned and completed Procedure Activities, clinician instructions as Sources, selected prior history, recovery Observations, actual use of medicines and follow-up visits.
• AI contribution: Organize supplied instructions and questions, produce a selected-context summary and later summarize the recorded recovery for discussion.
• Person and return loop: Decide what to ask or do with the clinician, mark what actually happened, and retain outcome and surgical history for future concerns.
• Storage/MCP edge: Hospital instructions are original Sources, not newly authored AI directions. A canceled or postponed procedure stays distinct from completed surgery. Age-only recollections must not generate invented calendar dates.

13. Follow an injury, mobility concern or rehabilitation

• Goal: Connect pain/function, movement, support equipment and professional assessments.
• Capture: Observations, person-rated function or pain Measurements, Activity with limitations/context, equipment Resources, clinician documents and actual rehabilitation sessions.
• AI contribution: Build a timeline and explain selected materials; compare recorded activity and function with clear uncertainty; prepare follow-up questions.
• Person and return loop: Choose what to discuss or try under the person's real-world care decisions, record actual sessions and outcomes, and return when equipment or activity changes.
• Storage/MCP edge: Body location/laterality may be unknown or change. A custom field can preserve it without a specialized foot/knee/back schema. Reported benefit is an Observation, not an automatically verified effectiveness claim.

14. Compare visible skin or other body changes

• Goal: Preserve photos and descriptions so the original context is available for later review.
• Capture: Protected original photos, person-stated body location, capture time when known, Observations about symptoms and changes, treatments actually used and visit Sources.
• AI contribution: Retrieve selected images and text, describe the reported chronology and draft questions or a comparison artifact without making the site diagnose from images.
• Person and return loop: Choose what to share, add later images or a clinician assessment, and correct location or dates as needed.
• Storage/MCP edge: Lighting, scale and angle limit comparison. Upload time is not capture time. Keep originals separate from thumbnails, OCR and descriptions; captions and resized previews cannot substitute for preserved bytes.

15. Track menstrual cycles and fertility investigations

• Goal: Maintain actual cycle events, tests and care context without treating predictions as observations.
• Capture: Cycle event/interval Measurements, test Activities and result Measurements, original photos/records, reproductive-health visits and selected Questions.
• AI contribution: Explain supplied test information, organize known versus unknown dates and research the person's selected questions using the relevant history.
• Person and return loop: Decide what to log or discuss, add later actual events and provider responses, and revisit hypotheses as the history grows.
• Storage/MCP edge: A predicted cycle start or inferred ovulation remains an attributed derivation. Cross-person context requires an explicit selection; partnership links do not authorize reading another person's records. Test-kit ownership does not prove a test was performed.

16. Preserve pregnancy and postpartum context

• Goal: Keep changing physical, emotional and care information together through a major life transition.
• Capture: Visits/tests with original Sources and extracted Measurements, person Observations, actual routines and medicine Activities, Questions and clinician instructions.
• AI contribution: Organize the supplied chronology and questions, explain selected documents and create a visit summary from the person's chosen evidence.
• Person and return loop: Choose what to ask and share, record care-team responses and actual outcomes, and continue into postpartum context without discarding earlier history.
• Storage/MCP edge: Due-date estimates and their source/version must remain distinct from actual birth events. Do not silently create a child Person from a pregnancy entry. Sensitive subset sharing and selected-date-window retrieval are central.

17. Investigate menopause or other hormonal transitions

• Goal: Keep broad changes and long-term questions together across symptoms, cycles, sleep and care visits.
• Capture: Person-reported Observations, actual cycle Measurements, sleep data, tests and clinician findings, relevant Activities, Research and Questions.
• AI contribution: Compare selected periods and evidence, help the person prepare questions and preserve alternative explanations rather than writing a hormonal cause into every observation.
• Person and return loop: Choose which questions matter, add visit outcomes and later history, and reopen an investigation when new evidence arrives.
• Storage/MCP edge: The same sleep record can inform several topics through links. Stage labels or causal explanations must have attribution; topic tagging alone cannot create a clinical finding.

18. Keep emotional and mental-health context

• Goal: Remember experiences, selected patterns and therapy-related questions while controlling highly sensitive material.
• Capture: Person-authored journal Observations, ratings with stated scales, chosen routine/context Activities, optional therapy Sources and reusable AI communication Instructions.
• AI contribution: Retrieve only the chosen context, help reflect or prepare questions, and save an attributed draft or research result according to the person's instructions.
• Person and return loop: Decide what to retain, disclose or discuss; correct an AI interpretation; add later experiences or a therapist's response separately.
• Storage/MCP edge: A journal may contain third-party information and require a narrower shareable summary. Selected-context access must not automatically expose every linked private note. The site does not infer a mental-health diagnosis or manufacture an interaction profile.

19. Organize sexual, urinary or pelvic-health questions

• Goal: Keep sensitive concerns and related care history usable without unnecessary disclosure.
• Capture: Person-chosen Observations, relevant dated events and test Measurements, care-provider Resources, original reports and Questions.
• AI contribution: Research selected questions and draft a concise clinician discussion document using exactly the authorized context.
• Person and return loop: Choose what to discuss and with whom, save the person's or clinician's response with authorship, and add later context.
• Storage/MCP edge: Sensitivity follows media, originals and derived artifacts as well as the topic. A person relationship is not permission. Removing a record from a share selection must prevent indirect source/attachment leakage through linked retrieval.

20. Maintain dental and oral-health history

• Goal: Carry dental visits, procedures, product use and recurring questions across providers.
• Capture: Dentist/clinic Resources and role relationships, Visit/Procedure Activities, original reports/images, relevant Observations and actual oral-care Activities.
• AI contribution: Summarize supplied history and unresolved questions, explain selected documents and research products or approaches chosen by the person.
• Person and return loop: Review questions with a dentist, record the answer and actual treatment, and retain older provider and procedure context.
• Storage/MCP edge: A care-team provider Resource does not create an account or send a message. Product ownership is separate from use. Location/tooth identifiers can be source-preserving custom fields rather than a compulsory clinical dental ontology.

21. Keep vision and hearing changes usable

• Goal: Connect sensory changes, examinations and assistive devices over time.
• Capture: Person Observations, dated test results with original units/source, optometrist/audiologist Resources, eyewear/hearing-device Resources and actual use/context.
• AI contribution: Explain supplied reports, compare compatible results and prepare questions about device changes or experienced difficulties.
• Person and return loop: Choose which questions to pursue, add provider responses and corrected device details, and compare later findings with the original history.
• Storage/MCP edge: Right/left/both, prescription versus device setting and changed test methods need explicit fields when supplied. Formats and scales must stay native rather than being forced into generic decimal values.

22. Coordinate caregiving for another adult

• Goal: Help a caregiver preserve useful context without confusing their account with the other person's experience.
• Capture: A subject Person, caregiver-attributed Observations, original records, actual care Activities, care-provider Resources and selected Questions/Lists.
• AI contribution: Organize the authorized history, distinguish caregiver report from the person's own report and produce selected handoff or visit summaries.
• Person and return loop: Decide what to share or verify, add the subject's corrections or clinician responses, and record what actually happened.
• Storage/MCP edge: Subject identity, author identity and workspace owner differ. A family relationship grants no access. Mixed-subject sources need careful extraction and disclosure boundaries; recording care context does not silently invite another account.

23. Keep a child's growth and care context

• Goal: Preserve parent/caregiver observations, growth readings, feeding/activity history and pediatric records as the child develops.
• Capture: A person-created subject record, caregiver-attributed Observations, dated Measurements, feeding and other Activities, original visit/test Sources and pediatrician roles.
• AI contribution: Organize selected history and explain supplied documents, keeping the child's actual records separate from generalized research.
• Person and return loop: Choose what to discuss with the pediatrician, add their responses and actual future readings, and correct errors without rewriting history.
• Storage/MCP edge: Age at an event may be known when birth date is not; do not invent either. A children's medicine Resource does not establish that a child exists or received a dose. Future account access is an explicit separate decision.

24. Research family health history

• Goal: Preserve remembered family context and questions about its relevance without inventing diagnoses or inheritance patterns.
• Capture: Subject People and person-stated relationships, separately attributed family-history Observations, supporting Sources when available, uncertainties and a connected Question.
• AI contribution: Distinguish recalled from documented information, research relevant concepts and draft questions for a clinician or a chosen specialist.
• Person and return loop: Decide what to verify or disclose, add corrected names/relationships or source-backed information and revisit earlier research.
• Storage/MCP edge: Unknown relatives can remain unknown; similar names must not auto-merge. Cross-person relationships are data, not permissions. Uncertainty in a family report must survive summaries and later retrieval.

25. Preserve accessibility and communication needs

• Goal: Reduce repeated explanation of how the person wants information and care conversations handled.
• Capture: Person-saved Instructions for AI communication, reported accommodations/needs, assistive Resources, relevant Observations and visit experiences.
• AI contribution: Retrieve the person's exact instructions and help draft an accessible brief or question list, with any suggested changes offered for the person to accept.
• Person and return loop: Edit and version instructions, choose what to share, and record what accommodations actually helped.
• Storage/MCP edge: Health stores and serves the interaction profile; it never authors it automatically. Instructions may have a general scope or a specific purpose. Every context brief should identify which instruction version it included without claiming the external AI obeyed it.

26. Know what health resources are available at home or elsewhere

• Goal: Remember tools, products, supplies, devices and services, including things previously owned or merely considered.
• Capture: Resource descriptions, ownership/access status, bottle/item inventory units, label and expiration Sources, location/quantity when known, research and mixed-type Lists.
• AI contribution: Retrieve what is actually available and its verified details, identify missing labels or uncertainty, and research the person's questions without turning inventory into a recommended treatment plan.
• Person and return loop: Confirm unclear labels, update ownership/quantity or expired units, record actual use separately and add replacement or comparison questions if desired.
• Storage/MCP edge: Product, individual bottle and actual use are separate. Expiration retains raw text, date precision and confidence; unreadable dates stay unknown. A borrowed or gym device can be accessible without owned status. No manufacturer claim becomes site endorsement.

27. Prepare appointments and coordinate a care team

• Goal: Bring a coherent selected account and useful questions to the right provider.
• Capture: Provider/clinic Resources with per-Person roles, planned Visit Activity, a questions List, chosen chronology, previous Sources and a versioned Summary artifact.
• AI contribution: Retrieve selected evidence, draft an appointment-ready observation summary, preserve missing facts and build a question list with attribution.
• Person and return loop: Review what to include, share the chosen artifact, attend the visit, add the clinician's actual response and update ongoing Questions separately.
• Storage/MCP edge: Appointment date/time precision and timezone matter; "later this month" is not a fully confirmed date. A draft summary is not sent, and a planned visit is not completed. Snapshot input record versions so later edits do not misrepresent what the appointment summary contained.

28. Build a substantial personal research library

• Goal: Investigate a topic deeply and return to a growing collection without restarting research.
• Capture: Research Questions, public reference Sources or privately supplied documents, licensing/provenance, original files, passage locators, person-saved research Instructions and attributed Research documents.
• AI contribution: Search prior work, retrieve relevant passages/full documents, investigate gaps and save a layered source-linked result with assumptions, uncertainty and unresolved work.
• Person and return loop: Decide which questions and evidence to pursue, save or reject AI suggestions and request a later review when new sources appear.
• Storage/MCP edge: Public availability is not permission to republish. Public and private source access stay separate. Long documents need paginated discovery, selective passage retrieval and full access when requested, not just short cards or one giant prompt. Sources remain distinct from Research.

29. Compare second opinions and revisit an unresolved case

• Goal: Make a new AI/person review useful when earlier interpretations disagree or new context appears.
• Capture: Original context and source versions, separately attributed Research/opinions, their assumptions and citations, ongoing Questions and actual person decisions/outcomes.
• AI contribution: Retrieve the selected evidence and earlier perspectives, compare their reasoning and gaps, and create another separately attributed analysis rather than overwrite the first.
• Person and return loop: Choose which view to discuss or investigate, add new evidence and outcomes, and reopen or park the question without pretending the site selected a medical winner.
• Storage/MCP edge: Preserve opinion author/client when known and the exact selected input versions. Revocable grants may differ between reviewers. An Answered Queue request does not settle a Question. Conflicting conclusions must remain separately discoverable.

30. Carry selected continuity to another provider, place or life stage

• Goal: Reuse an understandable history during a provider change, move, travel or a later return to the workspace.
• Capture: Person-selected current and historical records, original document references, provider roles, relevant Questions and a versioned continuity/export artifact.
• AI contribution: Prepare a concise history with deeper evidence available, indicate what changed since the prior brief and retain unknowns rather than fill them in.
• Person and return loop: Preview the exact content, choose the recipient or AI access, export/share explicitly, record any response and later amend or revoke access as applicable.
• Storage/MCP edge: Exported bytes cannot be recalled by revoking a link. Selection must be previewable, and protected media retrieval must respect the same authorization as the text. Archived context may remain useful while deleted or excluded context must not leak into a newly generated brief.

Coverage insights for the database and MCP plan

1. A small stable record family spans all thirty uses. Person, Topic, Question, Observation, Measurement, Activity, Resource, Source, Research, Instruction, List, Queue request and Summary/artifact can carry the workflows through editable categories and typed relationships. None requires a table for every condition, body part or procedure.
2. Preserve source facts before deriving summaries. Original bytes, original words, units, source ranges, timing precision and extraction locators anchor everything. Hypotheses, predictions, transcriptions, estimates and clinical findings have visibly different provenance. A later AI must be able to recover the context behind an earlier conclusion.
3. Series and episodes need structure without pretending all data is numeric. Quantities, ratings, date events and intervals all fit Measurement; narrative fits Observation. Episodes are connected records and/or lightweight grouping context. Effective time, coverage and method are more important than a single generic date column.
4. Resources need product versus inventory-unit versus use separation. Provider roles, accessibility, ownership history, multiple bottles, expiry uncertainty and actual medicine intake cannot be collapsed into one resource row. Keep the UI compact but preserve these distinctions underneath it.
5. Every consequential result needs attribution and lineage. A research result or appointment artifact records source and input versions; another opinion remains another record. Corrections version original entries. Decisions and outcomes must be supplied or accepted by the person, not silently inferred from AI text.
6. Privacy is about selections and derivations, not just accounts. Subject Person, record author and owner differ. Family relationships and provider contacts grant no access. Context selection must govern linked originals, media, extracted data and summaries as well as the initially selected row.
7. MCP should expose reusable operations. Discover capabilities, search/filter, fetch records and passages, retrieve compatible series/linked context, capture a batch, upload/read protected media, save versioned research/artifacts, propose suggestions, and operate durable Queue handoffs. Avoid a tool for each symptom or disease and avoid returning an entire life history by default.
8. The person remains in the loop. Queue is selected work for the chosen AI, not an autonomous care engine. Plans differ from happened events; proposals differ from accepted decisions; answering a request differs from settling an investigation. A manual brief must remain usable when MCP is absent.
9. Unknown and conflicting information are normal input. Blank is different from zero; missing nights are different from zero sleep; month-only expiry is different from a day; unknown formulation is different from a guessed brand formula. Save batches need per-item conflict/uncertainty outcomes and retry-safe identities.
10. The useful demonstration is a complete continuity loop. Capture original context → connect/select → AI retrieves/researches → save attributed result → person reviews/acts → add actual outcome/new context → revisit with a better evidence base. Test this on marked synthetic examples, while person-provided real material remains private.

Assist With Health: organization, database and MCP game plan

5 October 2026 · Proposed implementation design, following the 30-use exercise

The recommendation is one connected health workspace with a small set of reusable building blocks. Keep the person's original context, documents and media alongside every attributed interpretation. Different pages are useful views of that same history. A new condition should require a Topic, some categories and perhaps a capture preset—not a new database or tool family.

This plan follows 30 complete user loops, the current Site Guide, inspection of Health's existing services, and a fresh check of the family standards. It is a concrete plan for implementation and iteration; it does not activate private providers, move real intake online, settle the schema permanently or claim working MCP. Person-provided intake remains in the excluded local intake area. The examples here are generic workflow descriptions, not health fixtures.

Health stores, connects, versions, retrieves and displays. The person's chosen AI researches, interprets, compares and drafts. The person decides and acts. The site supplies no diagnosis, treatment recommendation, diagnostic score or autonomous care loop. Its flagship output is an appointment-ready observation summary that the person reviews.

What the 30 loops taught us

The repeating loop is:

flowchart LR
    A[Person supplies context and original evidence] --> B[Health preserves and connects it]
    B --> C[Chosen AI retrieves selected context]
    C --> D[AI researches or drafts an attributed result]
    D --> E[Health saves result, sources and inputs used]
    E --> F[Person reviews and decides]
    F --> G[Actual actions, outcomes and new context]
    G --> C

Six requirements recur across the scenarios:

1. Preserve facts, interpretations and decisions separately. A remembered event, a clinician's finding and an AI hypothesis need different attribution. None overwrites the others.
2. Keep time and uncertainty faithfully. An exact time, a date, a month, an approximate recollection and an unknown date are all legitimate inputs.
3. Make connected history queryable. An AI needs a useful time window and related evidence, not just today's profile or the latest page of records.
4. Separate resource, inventory unit and use. A medicine product, two bottles with different expirations, and a reported dose are three different things.
5. Support both a few entries and dense imports. A weigh-in and months of wearable data share meaning, while their browsing and import shapes differ.
6. Remember what each AI actually used. Future reviews need the original evidence and input versions behind an answer, including gaps and competing opinions.

No scenario requires a separate Headaches, Fertility, Feet or Heart database. The scenario matrix below identifies the few extensions the common model needs.

How the site should be organized

Keep Home, Topics, Questions, Activity, Resources, Lists, Library and Queue as the main working destinations. People is a useful context switch and detail page. On smaller headers, move Library and People into the profile menu first, then less frequently used destinations as needed. Keep one navigation row; preserve direct access to capture and Queue. This refines the Site Guide's older navigation description rather than adding a second competing shell.

These are views, not extra copies. A lab result can appear under its Person, Topic, Test Activity and Measurements while remaining one result with one history. Direct /observations, /measurements, /activity, /tests, /timeline, /research, /sources, /instructions and /summaries links remain available. /vitals stays a compatible alias/category; a date does not make every narrative a Measurement.

Tests & Visits should be a working filtered view of Activity. A Visit or Test Activity stores who/where/when and what happened. Its Source preserves the original report; its Measurements hold extracted values. A separate Encounter building block would duplicate this organization.

A Person page can offer a small persistent history area, but it must link to source-backed records rather than collapse a changing history into an authoritative diagnosis list. Care providers are Resources connected to a Person through a role such as Dentist or Primary care. A provider contact does not create an account, grant access or send anything.

Collections, filters, sort and search

Use the same vocabulary in the UI and MCP. Table is the useful default for dense records; List and Grid share the query. Grid earns its place for resources, photos and source collections.

Common filters are Person, Topic, Question, kind/category, occurred date, source, recorded by, media and archive state. Add metric/method/device/value basis for Measurements; planned/completed/canceled for Activity; ownership/access/category for Resources; readable expiry/expired/unknown for inventory; and state/Needs your input for Queue. Do not force every filter into every collection.

OR within one filter family, AND between families. Search and filters apply before pagination; active chips, sort and the selected view survive a detail visit. Sort by occurred time, updated time, title or relevance where meaningful, always with a stable tie-break. Unknown and approximate dates stay visible. Numeric charts require compatible metrics/units/methods; narrative and event timelines still work without numeric charts.

Search titles, original words, document text, tags and source metadata. Exact IDs and source/series locators are available when the AI already knows what it needs. Start with the existing full-text/indexed stack; add semantic search only if observed retrieval failures justify it. Never rank or count unauthorized content. Show exact filtered counts only when computed; otherwise show the returned range and continuation. The current post-page filtering and capped legacy reads need replacement where they can hide matches.

The database foundation

Retain Convex for structured data and domain transactions, private B2 storage for original bytes and derived files, and the existing Next.js UI. Build on the current record/version/relationship/operation/asset services. A new database engine, medical ontology or provider integration is not necessary to test the product.

Keep two layers: a stable common record identity for navigation and history, and a small number of typed extensions for data that must be validated and queried. Those extensions have one authoritative payload; legacy details fields become compatibility views, not competing copies of the same value.

Common record contract

Every record carries:

• Stable opaque ID, schema version, kind, category, title, original body/structured content, tags and archive state.
• Server-derived owner/workspace boundary; subject Person links are separate from ownership and access.
• Created/updated timestamps and revisions, separate from the time the described thing occurred.
• Source references and locators, who asserted the information, who recorded it, and how it was acquired.
• Original wording/units and explicit uncertainty. Blank means unknown, not zero, false or normal.

Keep the agreed building blocks: Person, Topic, Question, Observation, Measurement, Activity, Resource, Source, Research, Instruction, List, Queue and Summary/artifact. Proposals, interpretations, decisions and outcomes remain explicitly attributed records when useful; AI Suggestions remain separate from real requests. Existing Action records stay readable; new routine intake uses Activity. Typed extensions and editable categories handle variations without proliferating record kinds.

Planned table responsibilities

Names below are implementation targets, not claims that these tables already exist.

Avoid a general collaborator/membership engine in this tranche. A single-owner workspace can contain several subject People without creating co-owners. If separate family accounts later collaborate, add explicit person-approved sharing and membership with independent proof; do not infer it from family relationships. Likewise, save a named collection view as a durable view only when that feature is built; ordinary browser view preferences are already sufficient.

recordSubjects and search/facet summaries are disposable indexes of canonical links/content, maintained inside the same transaction. They are not independently editable health facts. Start with indexes required by the 30 scenarios, not every possible filter combination. Add bounded query plans for combinations rather than fetching the whole workspace to filter in memory.

Who reported it versus who saved it

Separate these axes:

An AI can faithfully file an explicitly supplied report of medicine intake while remaining the saving actor. It cannot turn its own suggestion into a completed dose, accept its own proposal on the person's behalf, or mark a Question settled. A person-reported decision may be recorded as a sourced report; changing the site's acceptance/permission state still requires the person's action. A clinician finding remains attributed to its original Source, rather than becoming a site-authored diagnosis.

Saved AI Interaction Instructions remain person-authored and person-controlled. Faithfully recording the person's exact instruction is different from inventing a profile. AI-proposed wording stays an inactive proposal until the person saves it. The current blanket actor restriction on Activities/actions/outcomes needs refinement, with consequential acceptance boundaries retained.

Time: preserve the precision we actually have

Use a RecordedTime value supporting instant with offset, local date, month, year, local clock with unknown zone, interval, relative/age-only recollection and unknown. Retain original text, timezone/offset when supplied, precision and whether it is exact, approximate or inferred. Separate occurrence, sample/collection, report/result, capture and upload times.

Derived earliest/latest bounds can support sorting and date-window matching, but are index metadata. Do not display an invented January 1 or midnight as the source date. Uncertain intervals may overlap a requested period; results identify that uncertainty. A month-only expiration stays a month, and an unreadable expiration stays unknown or an unconfirmed candidate. When age is supplied without a reliable birth date/year, preserve the age rather than invent a surgery date.

Measurements and wearable imports

Measurements support numeric values with units, coded/ordinal results or ratings with a stated scale, events, intervals and explicitly derived aggregates. Preserve raw text, the numeric lexeme if numeric, original unit, method/device, source reference and extraction locator. A normalizer can derive an additional common-unit value; it must not rewrite the original. Reference ranges and flags are copied from a report with attribution, not medically generated by Health.

Metric definitions need stable keys and lightweight aliases, with optional source/vendor codes. Duration, minimum heart rate and resting heart rate are different metrics. Identical labels from different devices do not establish comparable methods. Derived aggregates record their recipe, source versions, interval, denominator and coverage. A supplied aggregate retains its reported basis; an unknown computation recipe stays unknown. Missing samples remain missing.

For a weigh-in or a cycle event, a normal Measurement record is convenient. Dense wearable series use individually addressable points behind a compact series header; the UI need not display a full card for every sample. These are still logical Measurements with original evidence and revision history, not discarded data. A selected sample can open its detail/source without requiring a copied record. Use one measurement write service so the ordinary record's typed value is a view of its point, not a second authoritative value.

Keep full raw exports in private byte storage with hashes/manifests, then query normalized points in bounded pages. Do not embed months of samples in a Person document. Convex currently limits a document to 1 MiB; splitting series/documents is also useful for selective retrieval, irrespective of that limit. Convex limits.

An import begins with source/subject/mapping preview. Applying pages preserves source row IDs/locators, upstream revision where present, parser/mapping version and per-row results. A retry reuses its operation ID. Prefer upstream namespace + record ID/version + subject for duplicate detection. Without upstream IDs, use source-file hash and row locator to detect an exact repeat; date/value similarity alone is a review candidate, not permission to merge two true readings.

A supplied AI report is its own Source. Extracted values are labelled transcribed from that report, not promoted to a direct device export. Manual edits preserve the original import and correction history. Source revisions and a person's corrections remain distinct. Later direct exports can corroborate or conflict without silently replacing earlier context.

This metadata is compatible with the direction of Health Connect, which distinguishes record IDs, client IDs/versions, data origin, device, recording method and timezone information. Actual Health Connect/Oura integrations remain separate work; the database can preserve these fields without claiming a live connection. Android's data format.

Resources, inventory and activities

A Resource describes a medicine, product, equipment, app, website, service, practitioner or clinic. Owned now, Previously owned, Considering and Reference remain the ownership states. Access is separate: owned, borrowed, available at a gym or other location, unavailable or unknown. Past ownership does not erase historical use.

A resource unit is the particular bottle, package or physical item. Store lot/serial if supplied, formulation/strength as label evidence, opened date, expiry raw text and precision, location, quantity basis and review state. Two units can have different expirations. Package size is not a claim about remaining stock. Never infer ingestion from purchase or availability.

An actual medicine dose, meal, exercise session or use of a device is an Activity. Preserve reported amount, unit, route if stated, time, purpose and original wording, with optional links to the product and unit. Do not infer a brand formulation or dose from an ambiguous name. Planned activities stay planned until their occurrence is reported.

Resource photo imports retain original order/filenames and attach product-label and follow-up expiration images to the relevant candidate unit. Image adjacency helps pairing but does not replace checking the label. Uncertain pairings/dates stay visible for review. Finding an expired label is a source-derived inventory fact; it does not establish which bottle the person took.

Sources, long documents, photos and audio

Original text, files, images and audio remain immutable evidence versions. OCR, transcripts, image descriptions, crops and interpretations are derived artifacts with attribution and links. The site can perform deterministic file handling; the chosen AI supplies transcription/research where needed. Camera metadata can suggest capture time, but its origin is explicit. A file name alone is not a confirmed observation date.

Keep actual original bytes privately, hash them and verify readiness before claiming an attachment saved. Store safe AI renditions, page/region/close-up reads and contact-sheet discovery without losing access to legible original evidence. Audio retains its original, media duration when known, transcript segments/timestamps, speaker labels only when supplied, and an explicit absent/unreadable transcript state. A transcription does not replace the recording.

Long Research and Source documents have versioned bodies, section IDs, stable citations and page/paragraph/table/row/audio-time locators. Small bodies can remain in a record. Larger bodies use an immutable original/text asset plus bounded versioned section chunks; readers reconstruct the full requested document through continuation rather than rejecting it or keeping only its summary. Section search and citations resolve against that document version.

A result's context manifest records exact input versions and asset hashes; a series input also records its interval, source/import revision and sample manifest or bounded snapshot. Later changes must not make an earlier AI appear to have used newer evidence.

Public sources are a separate rights-reviewed catalogue. Store license evidence, attribution, rights for each included asset and the publication revision. Publicly accessible is not automatically redistributable. A private reference can point to a public catalogue version without publishing the person's attached notes or original medical documents. No private-to-public conversion occurs through ordinary AI tools.

Relationships and continuity

Use a small typed relationship vocabulary: about, performed/used, reported-in, extracted-from, cites, based-on, response-to, possibly-related, supersedes and included-in, with explicit metadata where needed. These are relationship design candidates to reconcile with current names, not a second inconsistent taxonomy. Care-provider role and its effective dates belong on the Person↔Resource edge; list order belongs on its membership edge. Planned/actual states and causal hypotheses belong to their records, not inferred from proximity in time.

An episode can be a lightweight grouping/Topic association with linked Observations, Measurements and Activities. It does not need a disease-specific episode table. Preserve unknown onset/end and conflicting recollections. Repeated exact edges reuse their identity; intentional repeated list entries keep separate entry identities.

A Question is the continuing investigation. A Queue request is one piece of work. Research is an attributed result. A Summary is a reusable artifact. Answering a request does not settle the Question, accept an interpretation or establish an outcome. Another opinion creates another result linked to the same evidence.

The MCP system

The UI and MCP must use the same domain services and validators. MCP is a controlled way for the person's chosen AI to find, read and save the person's context. It is not a second database, autonomous researcher or medical tool engine.

Proposed tool catalogue

Retain the Site Guide's product verbs, adding series/import and precise Queue updates. These 18 proposed tools are a build outline; none is advertised as live merely because it appears here.

Ordinary capture can start directly from conversation; it does not require creating a Queue request first. Logging a report, uploading a label, building a provider Resource and drafting an appointment summary use the same result service. Their record validators and provenance distinguish the jobs. The AI's own research tools obtain outside evidence; Health only retrieves its permitted catalogue and preserves supplied results.

Every add/edit family has a batch shape, including Queue requests/updates, Suggestions, Library curation and media begin/finish. Each item carries a stable item/operation ID and expected version where an existing object changes; responses report each item's outcome. Media sessions verify each original separately. A dependent result packet remains atomic as described below; independent uploads or import items may finish separately without falsely reporting the whole batch complete.

Library shelf add/remove is a typed normal operation through health_save_result/health_update, with attribution and a receipt. Removing an item from a shelf preserves its record, original author and evidence; it is not archive or delete. Lists use similarly explicit reference/order/note operations.

Read and selection contract

Requests accept exact record refs, document section selectors or a series/time-window selector, plus field selection, item/byte limits and cursor. Responses include schema version, returned refs/versions, source locators, coverage, next cursor and usable UI links. Metadata discovery is compact; useful source passages and readable media remain available, not just summaries.

Each query applies current permissions before matching, snippets, ranking, counts and facets. A cursor binds the query/sort/filter fingerprint and grant revision. Unknown and inaccessible IDs produce indistinguishable responses. History, connections and Queue lists paginate instead of silently returning the latest small subset.

A Queue's selected context can reference records, exact document sections, assets or series/time windows. A brief preserves that selection and its input versions. Selection describes the request's inputs; the AI grant determines its maximum permitted access. A normal full grant is not silently narrowed to one Queue, and a narrow grant is not broadened by a graph edge. The brief does not automatically attach every linked person record. An explicitly requested follow-up read must still fit current grant reach.

Put applicable person-saved AI Interaction, approach and request-linked Instructions near the top of the brief, with exact text, version and stated scope. Include them in its input manifest. When no applicable guidance is supplied or accessible, report that limitation without revealing hidden metadata or inventing a profile. health_start's index supports discovery; it is not a substitute for delivering the actual guidance with the work.

This avoids treating hundreds of daily readings or dozens of media files as hundreds of manually selected record IDs. Large briefs return an input index and continuation/evidence selectors, with honest coverage, rather than pretending a truncated packet is complete.

One coherent save

The result packet carries:

operationId
basedOn: record/version refs, source locators, asset hashes, series selection snapshot
items: stable local item IDs, kind-specific payloads, subject links and provenance
links: typed edges between local result items or authorized existing refs
citations: source/version + page/section/row/time locator
mediaRefs: already verified attachments, or explicitly pending slots
queue: optional request ID + expected version + answered/continue + needsInput

Resolve local references and validate all dependent records, versions, sources, citations and media states before the domain transaction. A coherent research/summary packet either saves together or refuses; it must not mark Queue answered while losing its evidence graph. Media upload is a separate external operation: a packet may explicitly reference a pending attachment, but cannot claim those bytes are ready. Independent import pages use per-row outcomes and progress; partial batch success is not called an atomic result.

Return applied/unchanged/conflict/refused outcomes, saved IDs/versions and links. Preserve original creator and verified operator separately from the asserted source. Successful retry with the same operation ID and same payload replays its receipt; reuse with different content conflicts. Validation refusal does not consume the corrected operation. An uncertain network failure means the outcome is unknown: retry the exact operation/payload or inspect its receipt through health_update receipt lookup. Never create a new ID simply because the first response was lost.

OAuth, permissions and client compatibility

Use Health's dedicated identity setup and one canonical remote /mcp resource. Verify issuer, signature, audience, expiry and the current server-side client grant for every request. Workspace/operator identity comes from that verification, not a model-provided label or owner ID. Durable grants carry capabilities, reach restrictions, revision, issue/expiry/revocation and last use. Family links and provider contacts are not grants.

Under the family policy, OAuth metadata and the 401 challenge advertise identity scopes only; product permissions live in the grant. Sign-in plus Allow enables the normal read/save/capture tools immediately. Settings inspects, narrows and revokes; it is not a second enable gate. Additional manual review is opt-in. The ordinary AI toolset excludes archive/delete/restore, export, publication, sharing/invites, broader access, provider contact, appointment booking, purchases, tests or treatment actions. Those remain person-controlled UI flows.

CIMD-first registration follows the current family direction; validated compatibility paths depend on the actual provider and client. Official MCP now recommends client metadata documents and retains dynamic registration for compatibility. MCP authorization.

Target the current 2026 Streamable HTTP shape, with explicit request/selection/import handles rather than implicit connection state. Older clients may need a verified dialect adapter. Protocol-version claims and named-client support require actual evidence for that dialect; copying a sibling adapter is only implementation input. MCP transport.

Typed input/output schemas, structured results, readable recovery messages and supported image/audio content make the tools easier to use. The protocol provides those shapes; Health's workflow and access rules are our design, not universal MCP rules. Treat retrieved documents and tool annotations as source data, never authority to change access. MCP tools.

Generate /ai, /ai.txt, /llms.txt, setup help, schemas and live limits from one deployed tool registry. Report terminal unavailability, stale versions, invalid input and retryable/uncertain operations separately. No connected badge, supported-client claim or future tool appears as working before it is proved.

Fit against all 30 scenarios

Every row below corresponds to the fully written capture → AI → person → revisit loop in the scenario document. The toolkit abbreviations are Find/read, Series, Save, Queue, Evidence/media, Library and Import; these refer to the catalogue above.

The exceptions expose concrete work—inventory units, dense series, attribution, precise time, document/context manifests and real grants—rather than a reason to add condition-specific tables.

What exists, and what must change

Source inspected 5 October 2026; this is source evidence, not authenticated deployment proof.

The local real intake is richer than the current database validator. It must go through a mapping/reconciliation preview, not be pushed directly into details or treated as an import-ready fixture. No real content should be copied into tests or public routes to demonstrate these improvements.

Implementation order and visible milestones

Private provider activation remains a separate outstanding authorization, not implied by producing this plan. Work that does not depend on it can continue. Real intake waits for the private persistence/bytes boundary to be proved with synthetic data. External AI permissions and real-world healthcare actions are always separate from implementation mechanics.

Migration is additive and versioned: preserve existing record IDs and manifests, introduce the typed extensions behind compatible readers, backfill indexes/links in bounded pages, and switch writers only after comparing counts, payloads and relationship/asset references. A preview reports unmapped fields, duplicate candidates and rejected rows before applying anything. Keep original intake files and a stable local-ID → server-ID map so a resumed import reconciles rather than duplicates. Revert the reader/writer switch if a tranche fails; do not erase prior evidence as a migration shortcut. No destructive production migration is authorized by this document.

Use a few complete synthetic journeys to verify consequential contracts: conversation capture with unknown dates and person attribution; two units of one product plus actual use; overlapping wearable imports with corrections and missingness; original image/audio plus extracted facts; appointment/second-opinion results with frozen inputs; narrowed grant/revocation and an uncertain-write retry. The 30 scenarios are a design fit review, not an instruction to create 30 rigid test suites.

As the data volume grows, exports need paged records and an actual asset-byte package or explicit unavailable-byte manifest. The current capped manifest export is not a complete longitudinal export. Archive hides normal browsing but retains person-controlled history; erasure uses exact all-version asset cleanup and dependency handling. If source content is erased or excluded, derived text/assets must not silently disclose it through a new brief or share. Already downloaded copies cannot be recalled.

Admin should see operational counts, plan state, provider health and licensing work without browsing private health bodies by default. Pro can control real storage/features through existing plan services; no payment flow is implied. Stats report records, counted bytes, requests and defined-period coverage. Patient trend queries stay in the person's private context and are descriptive, not a generated health score.

Finalize the stable contracts now—identity, ownership, source bytes, attribution, time precision, record/point IDs, versions and replay. Keep categories, forms, charts, navigation details and optional vendor mappings easy to change after use. That gives the database enough structure for reliable continuity without freezing an unsettled product.

Authority and current references

The freshly inspected family main is 71ff0ca998c8b279cb4edd94cff477fdce30a327. This plan uses Core 1.14.1, MCP/OAuth 1.1.0 and Media 1.7.0, alongside Health's stricter responsibility boundary. Plants' protocol/media work and Buying's workflow services are reusable references; their deployments do not prove Health capability. Scriptures supplies useful connected study/library/Queue patterns. See the Site Guide reference register.

Health source references: schema, record model, validation/version/receipt services, records/search, relationships, Queue, MCP transport, live guide contract.