# Open Patient Record Protocol Website Documentation Plan

Create a dedicated OPRP section on www.convey.care with substantial documentation for patients, implementers, Host operators, and credential authorities. Publish from the same versioned sources used to build and test the software so documentation stays aligned with actual behavior.

The requested public origin is `https://oprp.convey.care`. The website is a Next.js App Router project under `website/`, with Tailwind CSS and official shadcn/ui components. `npm run build:website` prepares canonical documentation/source content and builds its static Next.js export; `npm run check:website` verifies the exported routes and assets. The independent website project can also be built directly by Vercel with Root Directory `protocol/website`. It uses Convey's existing logo assets, Cairo typography and violet/cyan styling. CSS follows the system light/dark preference on initial render and when it changes, with the matching Convey logo and radial-gradient palette. The homepage adapts Convey's particle-network animation and content fades; reduced-motion preferences disable continuous animation and fades, and background rendering pauses when hidden or outside the viewport. Documentation and code surfaces use the same light/dark palette. Git publication, audience, deployment and custom-domain state are recorded in the publication report; a built site is not proof of a connected domain.

Repository publication sources include the [quickstart](quickstart.md), [wire profile](wire-profile.md), [threat model](threat-model.md), [Host guide](reference-host.md), [refresh recovery](refresh-recovery.md), [synchronization](synchronization.md), [credential lifecycle](credential-lifecycle.md), [portable backup/restore](portability.md), [Host migration](host-migration.md), [migration conformance/recovery](migration-conformance.md), [cryptographic evaluation](cryptography-evaluation.md), [implementation evidence](implementation-status.md), and [changelog](changelog.md), [clinical validation](clinical-validation.md) and [pagination/mirrors](pagination-mirrors.md), alongside the agreed requirements and planning documents. These are ready for website adaptation as draft material; the generated documentation is now published at the current public Site URL; the requested custom domain and public SDK repository still require the publication steps.

## Reader paths

| Reader | What the documentation should help them do |
| --- | --- |
| Patient or representative | Understand custody, standing consent, delegated authority, hosting choice, outage behavior, backup recovery, and migration. |
| Application developer | Implement one authorized workflow using an SDK, then handle failures and synchronization. |
| Host implementer | Implement every required operation and demonstrate conformance. |
| Host operator | Deploy, protect, monitor, recover, and administer a Host. |
| Credential authority | Understand verification requirements, issuance, trust admission, and revocation. |
| Security reviewer | Reproduce cryptographic vectors, inspect trust boundaries, and assess claims. |

## Proposed public sections

| Path | Documents |
| --- | --- |
| `/` | Overview, project status, core promises, limitations, and reader navigation. |
| `/patients/` | Addresses, Host selection, standing permissions, emergency preauthorization, representatives, backups, moves, recovery, and frequently asked questions. |
| `/architecture/` | Actors, identifier model, discovery, trust, storage boundaries, and sequence diagrams. |
| `/specification/` | Versioned normative core, terminology, capabilities, messages, authorization, records, and error handling. |
| `/specification/authorization/` | Requested and approved access periods, short-lived JWTs, refresh, decision outcomes, optional interaction discovery, representative context, and revocation. |
| `/specification/security/` | Required algorithms, credential profiles, key lifecycle, replay protection, downgrade prevention, and metadata exposure. |
| `/specification/synchronization/` | Queues, operation receipts, conditional updates, transactions, conflicts, feeds, and deletion behavior. |
| `/specification/visibility/` | Label and field policy, incomplete representations, protected writes, cache generations and offline limits. |
| `/specification/portability/` | Archive format, export, import, backup, restore, transfer, cutover, and recovery. |
| `/specification/subscriptions/` | Topics, filtering, callbacks, event format, acknowledgements, delivery failure, and catch-up. |
| `/guides/clinical-validation/` | Offline dependency installation, local terminology coverage, durable Host jobs and migration recovery; [source guide](durable-clinical-validation.md). |
| `/profiles/us/` | Versioned R4 base profiles, selected US Core 9 validation targets, terminology limitations, consent policy mapping and deployment considerations. |
| `/quickstart/` | Run the synthetic demonstration and complete consent, record exchange, and migration. |
| `/sdk/` | Installation, tutorials, generated API references, platform key storage, and compatibility tables. |
| `/hosts/` | Build a Host, configurable authorization and approval examples, representative-evidence guidance, storage adapters, installation, administration, backups, monitoring, and assessment criteria. |
| `/authorities/` | Verification policy, credential issuance, root trust, revocation, audits, and incident handling. |
| `/conformance/` | Requirement catalogue, executable tests, cross-language vectors, and published implementation evidence. |
| `/security/` | Threat model, review status, disclosure process, incident response, and known limitations. |
| `/governance/` | Licenses, patent policy, contribution process, compatibility, versioning, and independent operation. |
| `/releases/` | Drafts, changelogs, pinned dependencies, downloadable specifications, packages, and migration notes. |

## Documentation deliverables during development

Each milestone updates the specification, architecture decisions, runnable tutorial, relevant SDK reference, operational guide, and conformance evidence. Publish complete worked scenarios, including failure recovery, rather than only API lists.

The first tutorial discovers a patient, verifies an application, requests a token from the Host, and demonstrates both automatic issuance under standing permission and conditional approval for new access. It writes a lab observation, retrieves it, obtains a replacement token without patient interaction, and demonstrates a denied operation. Early authorization tutorials also cover limited emergency preauthorization, a parent with scoped control, and a conditional power-of-attorney representative. Working tutorials now include independent encrypted recovery after source disappearance duplicate-safe destination retries, and coordinated live migration with pending queue recovery. The [subscription tutorial](subscriptions.md) now covers protected callback activation, durable hints, lost acknowledgments and authorized catch-up; its [conformance guide](subscription-conformance.md) records recovery cases. Later tutorials expand offline conflict resolution and general FHIR/incremental portability.

Show hospital and lab examples with different approved access periods and short-lived tokens. Explain refresh without repeated patient login, the distinction between refresh and extending authorization, application-instance credentials, revocation, and recovery from a failed refresh response.

Diagrams explain discovery, authority trust, token requests and optional approval, encrypted exchange, event delivery, and migration. Machine-readable schemas and generated API references accompany prose. Separate required protocol behavior, Host-specific policy, and reference implementation examples. Explain proposed OPRP choices separately from requirements inherited from FHIR and other standards.

## Publication checks

Validate internal links, stable version URLs, example code, downloadable artifacts, schema references, navigation, search, accessibility, and mobile layouts. Use synthetic data throughout. Build tutorial snippets in CI and fail the documentation build when a public API changes without its examples.

Display draft status and implementation coverage prominently. Separate protocol conformance, Host assessment, independent security review, and jurisdiction-specific considerations. Do not imply an unpublished or unimplemented capability is available.

Make copies of the specification and schemas usable offline. Independent implementations must not need a Convey account or fetch a Convey endpoint to validate every request. Namespace publication and site hosting do not imply exclusive authority over runtime trust.

## Packaged SDK and clinical documentation sources

The [FHIR coverage guide](fhir-coverage.md) and [backend SDK guide](sdks.md) now provide developer-section content for scoped clinical types, histories/deletion, local package installation, runtime/provider choices and conformance evidence. Versioned local tarball/wheel/NuGet artifacts and checksums are generated under `protocol/releases/`. Versioned SDK/profile files can be served by the generated site; Apache 2.0 is applied; public Git and DNS setup remain explicit publication steps. Local packaging never publishes to a package registry.

## Visibility profile update

The Host advertises `visibility_profile: "oprp-visibility-1"`. [Visibility and cache invalidation](visibility.md) defines trusted grant policy, exact security labels, `SUBSETTED` field projections, write/export protection and required baseline/change `visibility_epoch`. Changed visibility invalidates prior cursors and clears SDK mirrors before a new baseline; disconnected clients cannot learn unknown permission changes. [Negative conformance](negative-conformance.md) records authenticated rejection tests. Host policy and approval delivery remain local integration choices.

## External clinical validation update

The [external clinical validation guide](external-clinical-validation.md) supplies six versioned R4 profiles and selected US Core 9.0.0 targets. The [durable validation guide](durable-clinical-validation.md) adds full offline dependency locking, finite local terminology and restartable intake/migration jobs. Setup requires Java and a verified dependency-cache copy. Structural-only mode advertises disabled terminology; local mode rejects unavailable systems and does not include broad licensed clinical vocabularies. Host authorization and conditional patient approval remain separate.