heyrafiki · moengadaniel · Aug 14, 2026 · Aug 13, 2026 · Aug 14, 2026
@@ -1,3 +1,4 @@
 node_modules/
 .mintlify/
+.playwright-cli/
 .DS_Store
@@ -1,6 +1,7 @@
 ---
 title: "Authentication"
 description: "Authenticate Heyrafiki API requests with a secret key."
+keywords: ["API authentication", "Bearer token", "Heyrafiki API key"]
 ---
 
 Authenticate with a secret key sent as a Bearer token.

@@ -1,6 +1,7 @@
 ---
 title: "Benefits"
 description: "Check Cover and reserve an approved Session."
+keywords: ["health insurance eligibility API", "pre-authorization API", "mental health Benefits"]
 ---
 
 The Benefit flow has two resources:

@@ -1,11 +1,24 @@
 ---
 title: "API changelog"
 description: "Released changes to the Heyrafiki API."
+keywords: ["Heyrafiki API changelog", "API releases", "OpenAPI changes"]
 rss: true
 ---
 
 Released API changes appear here. Product and website changes are on the [Heyrafiki changelog](https://heyrafiki.space/changelog).
 
+<Update label="14 August 2026" description="API surface map" tags={["Documented", "Reference"]}>
+**Documented** the complete [API overview](/resources) as eight resource areas and 31 released operations. The generated endpoint reference and public contract remain the operation-level authorities.
+</Update>
+
+<Update label="14 August 2026" description="Research evidence paths" tags={["Added", "Evidence"]}>
+**Added** a [research and evidence guide](/research/evidence) connecting public statements to the OpenAPI contract, Assurance Graph, synthetic fixtures, deterministic runners and stated limitations.
+
+**Added** the Stage 1 Assurance Graph protocol manuscript, prior-art search record and independent reviewer packet. The candidate is evaluated against five progressively stronger baselines before results are published.
+
+**Documented** First Light v2 as reproducible synthetic conformance evidence. It does not establish clinical validity or population effectiveness.
+</Update>
+
 <Update label="9 August 2026" description="MCP 2026-07-28" tags={["Changed", "Sandbox"]}>
 **Changed** the remote MCP server to the `2026-07-28` protocol contract, including stateless discovery, per-request capability metadata, transport header validation and structured completion results.
 

@@ -1,6 +1,7 @@
 ---
 title: "Claims and remittance"
 description: "Submit, review and reconcile covered Care."
+keywords: ["health Claims API", "Claim adjudication", "remittance reconciliation"]
 ---
 
 Claims start from delivered Care, an eligible Benefit and approved service evidence. Amounts use the currency's minor unit.

@@ -1,6 +1,7 @@
 ---
 title: "Platform capabilities"
 description: "The resource families and contracts that make up the Heyrafiki Platform."
+keywords: ["platform capabilities", "typed capabilities", "healthcare API architecture"]
 ---
 
 The public contract grows by capability. Generated endpoint pages remain the authority for callable operations.

@@ -1,21 +1,22 @@
 ---
 title: "Institutional integrations"
 description: "Connect Care, Cover, Claims and audit through governed contracts."
+keywords: ["institutional healthcare integration", "payer API", "health data governance", "research integration"]
 ---
 
 Institutional integrations use versioned resources for Practitioner discovery, Bookings, Benefits, Claims and remittance.
 
 <Columns cols={2}>
-  <Card title="Insurers and payers" icon="shield-check" href="/insurance/integration-guide">
+  <Card title="Insurers and payers" icon="file-invoice-dollar" href="/insurance/integration-guide">
     Connect Coverage, eligibility, pre-authorization, Claims, remittance and reconciliation.
   </Card>
-  <Card title="Government and regulators" icon="landmark" href="#government-and-regulatory-readiness">
+  <Card title="Government and regulators" icon="building-shield" href="#government-and-regulatory-integration">
     Review authority, data minimization, audit evidence and controlled exchange boundaries.
   </Card>
-  <Card title="Health Organizations" icon="hospital" href="#health-organizations">
+  <Card title="Health Organizations" icon="heart-pulse" href="#health-organizations">
     Coordinate Care through purpose-bound Practitioner, Booking and Session capabilities.
   </Card>
-  <Card title="Research and open ecosystems" icon="flask" href="#research">
+  <Card title="Research and open ecosystems" icon="diagram-project" href="#research">
     Use approved protocols, synthetic environments and versioned public contracts.
   </Card>
 </Columns>
@@ -50,19 +51,19 @@ Credential issuers remain authoritative for professional status. Payers remain a
 ## Five-role acceptance model
 
 <Tabs>
-  <Tab title="Payer engineering" icon="code">
+  <Tab title="Engineering" icon="terminal">
     Verify Coverage ingestion, eligibility, pre-authorization, Claim adjudication, remittance, Webhooks, retries and cross-tenant denial against the versioned contract.
   </Tab>
-  <Tab title="Actuarial and finance" icon="calculator">
+  <Tab title="Finance" icon="chart-line">
     Recompute line and Claim identities, reconcile advice to independent settlement evidence, and preserve service, submission, adjudication and payment dates for governed analysis.
   </Tab>
-  <Tab title="Care operations" icon="stethoscope">
+  <Tab title="Care" icon="clipboard-check">
     Confirm that service evidence connects delivered Care to the covered workflow while Clinical Notes, Messages and private Session content remain outside the payer contract.
   </Tab>
-  <Tab title="Security and privacy" icon="lock">
+  <Tab title="Privacy" icon="fingerprint">
     Exercise Organization isolation, least-privilege scopes, synthetic-only test data, signature validation, stale-event rejection and minimum-necessary response fields.
   </Tab>
-  <Tab title="Governance and audit" icon="scale-balanced">
+  <Tab title="Governance" icon="file-shield">
     Retain the contract commit, owner map, request identifiers, idempotency evidence, negative-test results, policy versions, reconciliation evidence and activation decision.
   </Tab>
 </Tabs>

@@ -1,6 +1,7 @@
 ---
 title: "Platform workflow"
 description: "How public resources connect Care, Cover, Claims and remittance."
+keywords: ["healthcare platform workflow", "Care and Claims", "API workflow"]
 ---
 
 Heyrafiki connects Care and payment operations through shared resource identifiers and versioned contracts.

@@ -2,7 +2,7 @@
   "$schema": "https://mintlify.com/docs.json",
   "theme": "mint",
   "name": "Heyrafiki",
-  "description": "The Heyrafiki API: authentication, errors and live resources.",
+  "description": "Reference and integration guidance for the Heyrafiki API, Sandbox, insurance and institutional workflows.",
   "styling": {
     "eyebrows": "breadcrumbs",
     "codeblocks": "dark"
@@ -18,7 +18,7 @@
   },
   "colors": {
     "primary": "#184A34",
-    "light": "#2F9E68",
+    "light": "#56C995",
     "dark": "#3D7B5C"
   },
   "appearance": {
@@ -72,7 +72,11 @@
     "prompt": "Search Heyrafiki Docs"
   },
   "seo": {
-    "indexing": "navigable"
+    "indexing": "navigable",
+    "metatags": {
+      "canonical": "https://docs.heyrafiki.space",
+      "og:locale": "en_KE"
+    }
   },
   "metadata": {
     "timestamp": true
@@ -139,6 +143,10 @@
           {
             "group": "Security and data governance",
             "pages": ["security/overview", "security/data-boundaries"]
+          },
+          {
+            "group": "Research and evidence",
+            "pages": ["research/evidence"]
           }
         ]
       },

@@ -1,6 +1,7 @@
 ---
 title: "Environments"
 description: "Separate sandbox development from regulated production use."
+keywords: ["API environments", "Sandbox", "production access"]
 ---
 
 Heyrafiki keys are bound to one environment.

@@ -1,6 +1,7 @@
 ---
 title: "Errors"
 description: "HTTP status codes and the Heyrafiki error envelope."
+keywords: ["API errors", "HTTP status codes", "error envelope"]
 ---
 
 Every API error returns the same envelope.

@@ -17,17 +17,26 @@ https://api.heyrafiki.space/v1
   Sandbox keys are issued to approved projects. Sandbox records are isolated from production and cannot be used for Care delivery, Benefits decisions or Claims.
 </Note>
 
-## Choose a path
+## Choose your path
 
 <CardGroup cols={3}>
-  <Card title="Developers" icon="code" href="/quickstart">
-    Authenticate, make a request and work through the sandbox.
+  <Card title="Developers" icon="terminal" href="/quickstart">
+    Make the first request, handle errors and build against the Sandbox.
   </Card>
-  <Card title="Insurers and Organizations" icon="building" href="/insurance/integration-guide">
-    Review integration ownership, financial controls and the synthetic acceptance plan.
+  <Card title="Payer teams" icon="file-invoice-dollar" href="/insurance/integration-guide">
+    Map Coverage, Benefits, Claims, remittance, controls and acceptance evidence.
   </Card>
-  <Card title="Public and research integrations" icon="landmark" href="/concepts/institutions#regulators-and-public-systems">
-    Review authority boundaries, testing and protocol-bound access.
+  <Card title="Care operations" icon="clipboard-check" href="/concepts/platform">
+    Follow the operational path from discovery and Booking through covered Care.
+  </Card>
+  <Card title="Security and privacy" icon="fingerprint" href="/security/overview">
+    Review identity, purpose, Consent, scopes, data boundaries and audit behavior.
+  </Card>
+  <Card title="Public institutions" icon="building-shield" href="/concepts/institutions">
+    Review authority mappings, controlled exchange and synthetic pilot gates.
+  </Card>
+  <Card title="Researchers" icon="diagram-project" href="/research/evidence">
+    Inspect reproducible evidence, prior-art boundaries and research limitations.
   </Card>
 </CardGroup>
 
@@ -40,8 +49,8 @@ https://api.heyrafiki.space/v1
   <Card title="Errors" icon="triangle-exclamation" href="/errors">
     Status codes and the error envelope.
   </Card>
-  <Card title="Resources" icon="cube" href="/resources">
-    Practitioners, Bookings, Benefits, Sessions, Claims, remittance and Webhooks.
+  <Card title="API overview" icon="diagram-project" href="/resources">
+    Map all 31 released operations before opening the endpoint reference.
   </Card>
   <Card title="Sandbox" icon="flask" href="/sandbox">
     Test records, failure cases and the request runner.

@@ -13,19 +13,19 @@ Use one isolated Sandbox project and synthetic records for the full payer pilot.
 ## Pilot control room
 
 <Tabs>
-  <Tab title="Engineering" icon="code">
+  <Tab title="Engineering" icon="terminal">
     Own the contract commit, environment mapping, retry policy, idempotency keys, Webhook consumer and integration logs.
   </Tab>
-  <Tab title="Actuarial and finance" icon="calculator">
+  <Tab title="Finance" icon="chart-line">
     Own independent amount recomputation, Benefit interpretation, valuation assumptions, remittance allocation and settlement variance review.
   </Tab>
-  <Tab title="Care operations" icon="stethoscope">
+  <Tab title="Care" icon="clipboard-check">
     Own service-code mapping, Practitioner workflow, delivered-service evidence and escalation when operational evidence is incomplete.
   </Tab>
-  <Tab title="Security and privacy" icon="lock">
+  <Tab title="Privacy" icon="fingerprint">
     Own scopes, tenant isolation, synthetic-data controls, secret handling, signature verification and data-minimization review.
   </Tab>
-  <Tab title="Governance" icon="scale-balanced">
+  <Tab title="Governance" icon="file-shield">
     Own policy references, decision authority, audit retrieval, incident contacts, activation approval and rollback authority.
   </Tab>
 </Tabs>

@@ -54,16 +54,16 @@ outstanding = payer_liability - observed_settlement
 Remittance remains payer advice. Settlement remains independent evidence of money movement. The timeline does not mark a Claim settled from an advice file alone.
 
 <Tabs>
-  <Tab title="Actuarial" icon="calculator">
+  <Tab title="Actuarial" icon="chart-line">
     Reconstruct reported Claim development by service, report, decision and settlement dates. Preserve zero-Claim exposure and define the cohort, valuation basis and treatment of reopened or reversed Claims before calculating a portfolio measure.
   </Tab>
-  <Tab title="Finance" icon="scale-balanced">
+  <Tab title="Finance" icon="money-bill-transfer">
     Reconcile payer liability to advice, observed movement, ledger evidence and the remaining outstanding amount without netting unrelated balances.
   </Tab>
-  <Tab title="Regulatory review" icon="landmark">
+  <Tab title="Oversight" icon="file-shield">
     Trace the Claim from effective policy version through coded decision, communication event, remittance and settlement observation. Each transition retains its source authority and recorded time.
   </Tab>
-  <Tab title="Engineering" icon="code">
+  <Tab title="Engineering" icon="terminal">
     Validate gapless event sequence, unique event identifiers, nondecreasing knowledge time, integer amounts and balanced adjudication in CI.
   </Tab>
 </Tabs>

@@ -1,6 +1,7 @@
 ---
 title: "Quickstart"
 description: "Make the first authenticated request to the Heyrafiki sandbox."
+keywords: ["Heyrafiki quickstart", "Sandbox API", "mental healthcare API tutorial"]
 ---
 
 ## 1. Create a sandbox key
@@ -71,3 +72,20 @@ curl https://api.heyrafiki.space/v1/bookings \
 <Note>
 Sandbox requests use fictitious records. Do not send names, contacts, clinical content or payment credentials in test requests.
 </Note>
+
+## Continue the integration
+
+<CardGroup cols={2}>
+  <Card title="Test failures and retries" icon="rotate" href="/testing">
+    Exercise authorization, idempotency, rate limits and recovery before adding a workflow.
+  </Card>
+  <Card title="Add covered Care" icon="file-invoice-dollar" href="/benefits">
+    Check eligibility and complete the pre-authorization sequence.
+  </Card>
+  <Card title="Receive changes" icon="satellite-dish" href="/webhooks">
+    Register an endpoint, verify signatures and handle duplicate deliveries.
+  </Card>
+  <Card title="Open the API map" icon="diagram-project" href="/resources">
+    Browse the 31 released operations by resource area.
+  </Card>
+</CardGroup>
@@ -1,6 +1,7 @@
 ---
 title: "Rate limits"
 description: "Read limits from every response and retry predictably."
+keywords: ["API rate limits", "retry backoff", "HTTP 429"]
 ---
 
 Limits are assigned per key and project. Do not hard-code a plan-wide number.

@@ -1,6 +1,7 @@
 ---
 title: "Requests"
 description: "Headers, identifiers, timestamps and money."
+keywords: ["API request format", "idempotency key", "request ID"]
 ---
 
 Send and receive JSON over HTTPS.