From 953fc8c911281451d35999979135ab869a8cb2fe Mon Sep 17 00:00:00 2001
From: welsberr <welsberr@gmail.com>
Date: Mon, 27 Apr 2026 14:31:02 -0400
Subject: [PATCH] Document Didactopus bridge from GroundRecall

---
 README.md                 | 25 ++++++++++++
 docs/didactopus-bridge.md | 84 +++++++++++++++++++++++++++++++++++++++
 docs/quickstart.md        | 29 ++++++++++++++
 3 files changed, 138 insertions(+)
 create mode 100644 docs/didactopus-bridge.md

diff --git a/README.md b/README.md
index 41850e2..3c56ebd 100644
--- a/README.md
+++ b/README.md
@@ -6,3 +6,28 @@ GroundRecall is a human-reviewable/AI usable knowledge layer with capabilities t
 source material began as legacy office documents and you want a provenance-aware
 knowledge import without going through a learner pack first. See
 `docs/quickstart.md` for the minimal `doclift -> GroundRecall` flow.
+
+`GroundRecall` can now also export a pack-ready
+`groundrecall_query_bundle.json` for a reviewed concept so `Didactopus` can
+carry that concept context into a learner-facing pack:
+
+```bash
+python -m groundrecall.export /path/to/groundrecall-store /tmp/groundrecall-export \
+  --pack-ready-concept channel-capacity
+```
+
+The matching `Didactopus` bridge flow is:
+
+```bash
+didactopus doclift-bundle-groundrecall \
+  /path/to/groundrecall-store \
+  channel-capacity \
+  /tmp/doclift-bundle \
+  /tmp/didactopus-pack \
+  --course-title "Example Course"
+```
+
+See:
+
+- `docs/quickstart.md`
+- `docs/didactopus-bridge.md`
diff --git a/docs/didactopus-bridge.md b/docs/didactopus-bridge.md
new file mode 100644
index 0000000..839c762
--- /dev/null
+++ b/docs/didactopus-bridge.md
@@ -0,0 +1,84 @@
+# Didactopus Bridge
+
+This documents the `GroundRecall` side of the bridge into a learner-facing
+`Didactopus` pack.
+
+## Purpose
+
+Use this when:
+
+- you already have a reviewed concept in a canonical `GroundRecall` store
+- your source material also exists as a normalized `doclift` bundle
+- you want `Didactopus` to generate a learner-facing pack that carries the
+  reviewed concept context along with the ordinary pack artifacts
+
+`GroundRecall` remains the canonical reviewed knowledge layer.
+`Didactopus` remains the learner-facing pack and workbench layer.
+
+## Minimal Export
+
+Export a pack-ready query bundle directly from the `GroundRecall` store:
+
+```bash
+groundrecall export /path/to/groundrecall-store /tmp/groundrecall-export \
+  --pack-ready-concept channel-capacity
+```
+
+That writes:
+
+- `/tmp/groundrecall-export/groundrecall_query_bundle.json`
+
+It also records the path in `export_manifest.json`.
+
+## End-To-End Bridge
+
+The shortest full bridge path is:
+
+```bash
+doclift convert-dir /path/to/legacy-course /tmp/doclift-bundle --asset-root /path/to/legacy-course
+
+didactopus doclift-bundle-groundrecall \
+  /path/to/groundrecall-store \
+  channel-capacity \
+  /tmp/doclift-bundle \
+  /tmp/didactopus-pack \
+  --course-title "Example Course"
+```
+
+That command:
+
+1. exports `groundrecall_query_bundle.json` for the selected concept
+2. passes that file into the `Didactopus` `doclift` bundle demo workflow
+3. writes a generated pack that includes the GroundRecall bundle as a declared
+   supporting artifact
+
+## Outputs
+
+On the `GroundRecall` side:
+
+- canonical store remains unchanged
+- export directory contains `groundrecall_query_bundle.json`
+
+On the `Didactopus` side:
+
+- generated pack contains `groundrecall_query_bundle.json`
+- the pack summary records that the GroundRecall bundle was included
+- learner-workbench flows can consume the review and graph context from that
+  bundle
+
+## Why This Boundary Matters
+
+This keeps responsibilities clean:
+
+- `doclift` normalizes document corpora
+- `GroundRecall` owns canonical reviewed concept/query context
+- `Didactopus` owns learner-facing packs, workbenches, and pedagogy workflows
+
+The bridge exists so those systems can cooperate without collapsing into one
+repository boundary or one data model.
+
+## Related Documentation
+
+- [quickstart.md](quickstart.md)
+- [architecture.md](architecture.md)
+- `Didactopus`: `docs/groundrecall-bridge.md`
diff --git a/docs/quickstart.md b/docs/quickstart.md
index b9a997a..9b17884 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -84,6 +84,12 @@ Export assistant-neutral artifacts:
 groundrecall export store/ exports/groundrecall --concept channel-capacity
 ```
 
+Export a pack-ready `groundrecall_query_bundle.json` for `Didactopus`:
+
+```bash
+groundrecall export store/ exports/groundrecall --pack-ready-concept channel-capacity
+```
+
 Export assistant-targeted bundles:
 
 ```bash
@@ -91,6 +97,28 @@ groundrecall assistant-export store/ codex exports/codex --concept channel-capac
 groundrecall assistant-export store/ claude_code exports/claude --concept channel-capacity
 ```
 
+## Bridge To Didactopus
+
+If you want a `Didactopus` learner pack that carries reviewed GroundRecall
+concept context, the shortest bridge flow is:
+
+```bash
+doclift convert-dir /path/to/legacy-course /tmp/doclift-bundle --asset-root /path/to/legacy-course
+didactopus doclift-bundle-groundrecall \
+  store/ \
+  channel-capacity \
+  /tmp/doclift-bundle \
+  /tmp/didactopus-pack \
+  --course-title "Example Course"
+```
+
+That command:
+
+- exports a pack-ready `groundrecall_query_bundle.json` from `GroundRecall`
+- feeds it into the `Didactopus` `doclift` bundle flow
+- writes a pack with the GroundRecall query bundle included as a declared
+  supporting artifact
+
 ## Default Working Layout
 
 A simple local layout is:
@@ -108,5 +136,6 @@ The current alpha does not require this exact layout, but it is a sensible start
 ## Next Reading
 
 - [architecture.md](architecture.md)
+- [didactopus-bridge.md](didactopus-bridge.md)
 - [llmwiki-import.md](llmwiki-import.md)
 - [sync-roadmap.md](sync-roadmap.md)