From 118f265862f810195877f0bdcc43d72a8f7fb8cd Mon Sep 17 00:00:00 2001
From: gramps <gramps@llamachile.shop>
Date: Sun, 12 Apr 2026 08:24:12 -0700
Subject: [PATCH] docs: add HIPAA-ready positioning for architecture and pitch

- clarify BEDS is compliance-friendly architecture, not certification
- add healthcare/regulated deployment framing to visual brief
- document controls BEDS provides vs contract implementation responsibilities
- update wiki index description for regulated-deployment positioning
---
 wiki/02-architecture.md                   | 24 +++++++++++++++
 wiki/11-beds-architecture-visual-brief.md | 36 +++++++++++++++++++++++
 wiki/Home.md                              |  2 +-
 3 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/wiki/02-architecture.md b/wiki/02-architecture.md
index a98618e..73c40fb 100644
--- a/wiki/02-architecture.md
+++ b/wiki/02-architecture.md
@@ -158,3 +158,27 @@ BEDS has no node types in code. All nodes run the same binary. The configuration
 - Whether this node is in production mode (fatal IPL failures) or development mode (non-fatal)
 
 Changing a node's role means changing its config file and restarting. No code changes. No redeployment.
+
+## Compliance-Oriented Deployment Pattern
+
+BEDS can be used as the architecture baseline for regulated workloads (including healthcare contracts) because it enforces transport and execution boundaries by design.
+
+Important framing:
+
+- BEDS is not a compliance certification
+- BEDS is a control-friendly runtime architecture
+- Final compliance posture depends on infrastructure, policy, and operational practice
+
+Why this architecture helps:
+
+- AMQP-first messaging centralizes request flow and transport governance
+- Template-driven dispatch limits ad hoc query behavior in application code
+- Class -> Schema -> Base I/O layering keeps business logic separate from storage concerns
+- Event lineage enables request-chain reconstruction for audits and incident review
+
+What must be added in deployment for HIPAA-class programs:
+
+- At-rest encryption and key lifecycle controls
+- Strong service identity and TLS policy in production
+- Access governance, least privilege, and operator accountability
+- Log retention, backup/restore validation, and incident response processes
diff --git a/wiki/11-beds-architecture-visual-brief.md b/wiki/11-beds-architecture-visual-brief.md
index 6b8b89a..b5e50c7 100644
--- a/wiki/11-beds-architecture-visual-brief.md
+++ b/wiki/11-beds-architecture-visual-brief.md
@@ -111,6 +111,42 @@ This pattern supports both:
 - Better compliance posture from centralized message handling
 - Strong foundation for future AI-assisted data object generation
 
+## HIPAA Contract Positioning
+
+Use this framing in proposals and executive briefings:
+
+- BEDS is not marketed as "HIPAA certified software"
+- BEDS is an architecture baseline that makes HIPAA-ready implementations practical
+- Compliance outcomes come from deployment controls, policy, and operations on top of BEDS
+
+### Why BEDS Helps HIPAA Programs
+
+- AMQP-first transport centralizes ingress, routing, and logging controls
+- Template/class boundaries isolate domain data paths and reduce ad hoc access patterns
+- Event lineage supports investigation and audit workflows with traceable parent/child chains
+- Config-driven node roles support separation of duties and segmented runtime deployment
+
+### What BEDS Provides vs What the Contract Team Must Provide
+
+BEDS provides:
+
+- Controlled transport path for data in transit
+- Deterministic routing and broker-level operational guardrails
+- Structured telemetry and lineage-ready diagnostics
+- Layer boundaries that reduce accidental direct data access
+
+Contract implementation must provide:
+
+- Encryption at rest and key management practices
+- TLS and identity policy enforcement in production
+- Least-privilege access model and workforce controls
+- Retention, backup, incident response, and evidence collection procedures
+- BAA/legal governance and organizational compliance program artifacts
+
+### One-Line Sales Statement
+
+"BEDS gives healthcare and regulated teams a compliance-friendly architecture spine; HIPAA compliance is achieved by deploying that spine with required security and operational controls."
+
 ## Visual Blueprint (for Diagram or Image Generation)
 
 Use this structure when creating architecture visuals:
diff --git a/wiki/Home.md b/wiki/Home.md
index 29bf77b..180f17f 100644
--- a/wiki/Home.md
+++ b/wiki/Home.md
@@ -18,7 +18,7 @@ If you are reading this as a new contributor, start here and read in order. The
 - [IPL — Initial Program Load](04-ipl.md) — The bootstrap sequence, step by step, and why order matters
 - [Configuration System](05-configuration.md) — Layered TOML, environment files, topology options
 - [Modernization Roadmap](10-modernization-roadmap.md) — POC-first execution sequence and modernization requirements
-- [Architecture Visual Brief](11-beds-architecture-visual-brief.md) — Leadership-facing architecture narrative and diagram prompts
+- [Architecture Visual Brief](11-beds-architecture-visual-brief.md) — Leadership-facing architecture narrative, diagram prompts, and regulated-deployment positioning
 
 ### Messaging
 - [Queue Topology](06-queue-topology.md) — AMQP exchanges, queues, routing keys, and the broker model