From a54082141abcee1e0bbb7eceffe37ea1a405aca0 Mon Sep 17 00:00:00 2001
From: welsberr <welsberr@gmail.com>
Date: Fri, 1 May 2026 21:02:33 -0400
Subject: [PATCH] Document GenieHive foundation gateway boundary

---
 docs/README.md                       |   1 +
 docs/architecture.md                 |   5 ++
 docs/geniehive-foundation-gateway.md | 100 +++++++++++++++++++++++++++
 3 files changed, 106 insertions(+)
 create mode 100644 docs/geniehive-foundation-gateway.md

diff --git a/docs/README.md b/docs/README.md
index a6efaf4..159ef65 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,6 +7,7 @@ Primary docs:
 - [quickstart.md](quickstart.md)
 - [assistant-protocol.md](assistant-protocol.md)
 - [architecture.md](architecture.md)
+- [geniehive-foundation-gateway.md](geniehive-foundation-gateway.md)
 - [llmwiki-import.md](llmwiki-import.md)
 - [sync-roadmap.md](sync-roadmap.md)
 
diff --git a/docs/architecture.md b/docs/architecture.md
index 72e24ae..4d1c4db 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -6,6 +6,11 @@
 - `Didactopus`: learner-facing workflows and educational tooling
 - `GenieHive`: model and routing layer where runtime assistant/service resolution is needed
 
+For governed model access, GroundRecall treats the GenieHive Foundation gateway
+profile as an external endpoint and policy boundary. GroundRecall does not own
+GenieHive credentials, request audit logs, provider routing, or budget state.
+See [geniehive-foundation-gateway.md](geniehive-foundation-gateway.md).
+
 ## Core Design
 
 The system is built around one canonical flow:
diff --git a/docs/geniehive-foundation-gateway.md b/docs/geniehive-foundation-gateway.md
new file mode 100644
index 0000000..7d7849e
--- /dev/null
+++ b/docs/geniehive-foundation-gateway.md
@@ -0,0 +1,100 @@
+# GenieHive Foundation Gateway Notes
+
+Last updated: 2026-05-01
+
+This document records how GroundRecall should relate to the optional GenieHive
+Foundation gateway profile.
+
+## Boundary
+
+GroundRecall remains the grounded knowledge substrate. It owns:
+
+- source import and provenance
+- normalized knowledge objects
+- review candidates and promotion records
+- canonical query and export
+- assistant-neutral bundles
+
+GenieHive remains the model and routing control plane. The Foundation gateway
+profile adds governance around model access:
+
+- named, revocable client credentials
+- request audit logging without prompt or completion content
+- model and operation allowlists
+- future provider credential indirection
+- future provider adapters, quotas, and operator tooling
+
+GroundRecall should not duplicate GenieHive's credential, audit, routing, or
+budgeting state.
+
+## Integration Pattern
+
+GroundRecall-powered workflows that need model assistance should treat
+GenieHive as an external OpenAI-compatible endpoint:
+
+```text
+GroundRecall source/query/export -> client workflow -> GenieHive role/model
+```
+
+The client workflow should carry only:
+
+- `GENIEHIVE_BASE_URL`
+- `GENIEHIVE_API_KEY`
+- requested role or model, preferably a role such as `archive_migrator`
+
+Provider root keys must not be stored in GroundRecall source notes, promoted
+objects, exports, assistant bundles, or repo docs.
+
+## What To Record In GroundRecall
+
+Allowed operational facts:
+
+- which GenieHive deployment profile is in use, such as `casual` or
+  `foundation_gateway`
+- non-secret endpoint locations, such as a localhost or ZeroTier base URL
+- role names used by workflows
+- commit IDs for GenieHive capability changes
+- whether request audit logging and allowlist enforcement are enabled
+- test or smoke-test outcomes
+
+Not allowed:
+
+- raw GenieHive API keys
+- provider API keys
+- provider dashboard credentials
+- prompt or completion content copied from audit logs
+- secrets embedded in `.env` files
+
+## Current GenieHive Milestones Reflected Here
+
+As of this note, the local GenieHive roadmap has completed:
+
+- baseline and compatibility guard
+- config profiles and feature flags
+- named client key storage, opt-in named auth, and admin key endpoints
+- opt-in request audit logging
+- named-key model and operation authorization
+
+Remaining GenieHive work that may matter to GroundRecall-assisted workflows:
+
+- archive migration role/profile config
+- provider credential indirection
+- Anthropic Messages adapter
+- budget and quota enforcement
+- admin CLI and operations documentation
+- security review
+
+## GroundRecall Implications
+
+No GroundRecall schema change is needed for these GenieHive milestones.
+
+GroundRecall may eventually benefit from optional metadata fields or source-note
+conventions for:
+
+- `model_gateway`
+- `model_role`
+- `request_id`
+- `workflow_run_id`
+
+Those should remain provenance metadata for generated or assisted artifacts, not
+a copy of GenieHive's audit table.