Jorvis Documentation, RAG, and Hermes Knowledge Pipeline

Architecture View Only

Public supporting references live in Runtime Overview, Agent Workflow Overview, and Operations Overview.

This visual covers: documentation source flow, publish flow, KB/RAG ingest, validation points, and Hermes knowledge loops.
This visual does not cover: OpenClaw control plane, Open WebUI client injection details, or general model-routing policy.
Design reference: ADR-0022 (Documentation and RAG Stack).

1. Documentation Pipeline Overview

Current

flowchart LR A["docs/ sources"] --> B["sanitize / normalize"] B --> C["MkDocs build"] C --> D["GitHub Pages"] C --> K["Prod Nginx (jorvis.app)"] B --> E["KB sync script"] E --> F["OpenWebUI Knowledge Base"] F --> G["RAG retrieval responses"] B --> H["CI validation"] H --> I["Link checker"] H --> J["SSOT conflict checks"]

The pipeline has two distribution tracks: static publishing (GitHub Pages + prod Nginx) and KB/RAG ingest (OpenWebUI Knowledge Base). Both are sourced from the same docs/ tree, and Hermes turns repeated knowledge work into reusable capability while those streams remain bounded.

2. Source and Transform Layer

Current

Primary source: repo-managed Markdown docs under docs/ plus the public-safe reference wrappers under docs-public/.
Upstream mirror: Open WebUI docs synced weekly via scripts/kb/sync-openwebui-docs.sh into docs/knowledge-base/open-webui/upstream/.
Transform step: sanitize tokens, normalize content shape, and prepare static and KB-facing outputs.
Hermes layer: repeated docs work becomes reusable knowledge work, not just one-off retrieval.
Static build: mkdocs.yml produces the full site/ artifact, while mkdocs-public.yml produces the public-safe site-public/ reference build.
Key property: the documentation pipeline must not silently redefine runtime truth; it points back to canonical runtime docs.

3. Dual Distribution Paths

Current

Path A: Static documentation

The full MkDocs build still produces site/, while the public-safe reference build produces site-public/ for the /reference/ surface on jorvis.app. Architecture HTML visuals remain served directly by prod Nginx.

Path B: KB / RAG ingest

scripts/sync_docs_to_openwebui.py uploads selected docs to the OpenWebUI Knowledge Base on jorvis.app. Gated by OPENWEBUI_API_KEY secret and optional OPENWEBUI_KB_SYNC_ON_PUSH flag.

4. CI Validation Gates

Current

flowchart TD D["Docs change (push/PR)"] --> L["Documentation Link Checker"] D --> B["MkDocs Build (hard gate)"] D --> S["SSOT snapshot checks"] B --> SM["Build Summary"] L --> SM D --> K["KB Sync (main only, gated)"] D --> U["Upstream docs mirror (weekly)"]

CI Workflow	Trigger	Gate Type
docs.yml	push (main/develop) on `docs/`, `docs-public/`, `requirements-docs.txt`, `mkdocs-public.yml`, `.github/workflows/docs.yml`; PR on main; manual dispatch	Full MkDocs build, public reference build, Pages deploy (main push only), and KB sync (gated main push or manual dispatch)
docs-link-check.yml	push/PR on `docs/*/.md` and `docs-public/*/.md` + weekly	Link validation (hard block)
sync-openwebui-docs.yml	weekly + manual dispatch	Upstream mirror sync

5. Boundaries and Non-Goals

Current

This visual is not the model-policy source of truth.
This visual is not the OpenClaw control-plane visual.
This visual is not the Hermes execution-loop spec, either.
This visual does not pin transient KB UUIDs, doc counts, or host-specific fallback endpoints.
This visual should not act as a release ledger or task history board.
KB sync is opt-in on push (controlled by OPENWEBUI_KB_SYNC_ON_PUSH); manual dispatch is always available.

6. Key Scripts and Paths

Current

Script / Path	Purpose
scripts/sync_docs_to_openwebui.py	Uploads selected docs to OpenWebUI KB on `jorvis.app`
scripts/kb/sync-openwebui-docs.sh	Syncs Open WebUI upstream docs into repo mirror
scripts/check-links.sh	Local link validation for docs
requirements-docs.txt	MkDocs and doc build dependencies
mkdocs-public.yml	Builds the curated public-safe reference surface to `site-public/`
docs/architecture/visuals/*.html	Architecture HTML visuals (served on prod Nginx)

7. Related Canonical Docs

Current

Current Architecture

Main platform shape and request paths.

OpenClaw Runtime Operations

Operational OpenClaw truth lives separately.

Operations Overview

Public-safe summary of smoke checks, observability, and bridge-sync operations.

ADR-0022

Documentation and RAG stack decision that anchors the build and publish model.

Jorvis Architecture Visual

System topology, request paths, and subsystem boundaries.

OpenClaw Control Plane Visual

Assistant, memory lanes, and planned control-plane expansion.

Agent Ops Architecture Visual

Human-role model, SSOT flow, and memory guardrails.

Jorvis Product Overview

Enterprise capabilities, safety gates, and engineering metrics.