openshellorg · AMDphreak · Sep 28, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -5,12 +5,18 @@ on:
     branches: [main, master]
     paths:
       - "docs/**"
+      - "lib/**"
+      - "scripts/**"
+      - "CONTRIBUTING.md"
+      - "test/**"
       - "supplemental-ui/**"
       - "antora-playbook.yml"
       - "antora-playbook-local.yml"
       - "package.json"
       - "pnpm-lock.yaml"
       - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [main, master]
   workflow_dispatch:
   repository_dispatch:
     types: [docs-rebuild]
@@ -27,9 +33,37 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  diagram-audit:
+    name: Themed SVG and diagram checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "pnpm"
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Sync themed-svg browser runtime
+        run: pnpm run diagrams:sync
+
+      - name: Run diagram and dark-mode audits
+        # Static only: no mermaid-cli / Puppeteer. See CONTRIBUTING.md and scripts/DIAGRAM-AUDITS.md.
+        run: pnpm run diagrams:check:all
+
   build:
     name: Build Antora docs
     runs-on: ubuntu-latest
+    needs: diagram-audit
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -47,6 +81,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Sync themed-svg browser runtime
+        run: pnpm run diagrams:sync
+
       - name: Build Antora docs
         id: antora
         uses: antora-supplemental/antora-build-action@v2
@@ -69,6 +106,7 @@ jobs:
     name: Deploy to GitHub Pages
     runs-on: ubuntu-latest
     needs: build
+    if: github.event_name != 'pull_request'
     environment:
       name: github-pages
       url: ${{ steps.deploy.outputs.page_url }}

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
@@ -1,5 +1,13 @@
 = Changelog
 
+== 2026-09-27 -- Facto stack for docs.opensh.org
+
+* Adopt `@antora-supplemental/facto-stack` wiring: `indexify` URLs, site-nav-tree curated sidebar roots, nav-typology (+ Diátaxis), page-context/edit, link-validator, linkinator, extension-lister, orphan-finder, build-stack footer, client Mermaid + diagram lightbox, Kroki bake for non-Mermaid diagrams.
+* Playbook content source: `openshellorg/actor-shell` → `Desktop-Tooling/grammaton-ui-shell` (component `grammaton-ui-shell`).
+* Supplemental UI: nav-tree / typology partials and helpers from the Facto compose pattern (DevCentr reference).
+* Diagram **rendering engines** (Facto): `@antora-supplemental/mermaid-client` + `@antora-supplemental/diagram-lightbox` from antora-diagram-engines for `[source,mermaid]`; `asciidoctor-kroki` for PlantUML/other Kroki types; no alternate AsciiDoc renderers.
+* Hub diagram CI: themed-svg runtime sync, static dark-text audit, verifier tests, and Antora `verify-themed-svg-dark-mode` — does **not** clone upstream to re-run `diagrams:check` / mermaid-cli (bake freshness stays in product repos). Documented in [CONTRIBUTING.md](CONTRIBUTING.md) and [scripts/DIAGRAM-AUDITS.md](scripts/DIAGRAM-AUDITS.md).
+
 == 2026-09-26 -- Config Key Sanitation renamed to Config Lifecycle Management
 
 * The protocol page is now xref:standard-config-lifecycle-management.adoc[Config Lifecycle Management]; the old `standard-config-key-sanitation` URL redirects to it.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,38 @@
+# Contributing to OpenShellOrg Docs
+
+## Hub CI scope
+
+This repository builds https://docs.opensh.org with Antora and the [facto-stack](https://github.com/antora-supplemental/facto-stack) compose. GitHub Actions runs:
+
+- **Themed SVG runtime sync** — `pnpm diagrams:check` (vendored `@dev-centr/themed-svg` browser bundle)
+- **Static dark-mode text audit** — reads committed adaptive SVGs from upstream repos (no browser)
+- **Verifier unit tests** — `pnpm test:dark-text`
+- **Antora site generation** — includes `verify-themed-svg-dark-mode` warnings on catalog SVGs
+
+## Mermaid → SVG bake (not run in this hub)
+
+The docs hub **does not** run `pnpm diagrams:check`, mermaid-cli, or Puppeteer/Chromium in CI. We intentionally do **not** clone product repos to re-render `.mmd` sources against committed `*.svg` / `*.host.svg` pairs.
+
+If you change Mermaid sources or theme manifests in a **product repo** (especially [shell-architecture](https://github.com/openshellorg/shell-architecture)), validate on a developer machine **before merge**:
+
+```bash
+cd shell-architecture   # or your product checkout
+pnpm install
+pnpm diagrams           # regenerate baked SVG pairs
+pnpm diagrams:check     # staleness gate
+pnpm test               # shell-architecture: diagrams + PlayTime artifact checks
+```
+
+Authoritative contributor notes for shell-architecture diagrams: [diagrams/README.adoc](https://github.com/openshellorg/shell-architecture/blob/main/diagrams/README.adoc).
+
+This hub still publishes those committed SVGs via Antora content sources; freshness is owned by the product repo and human review, not hub Actions.
+
+## Local hub checks
+
+```bash
+pnpm install
+pnpm diagrams:check:all   # hub static audits only
+pnpm docs                 # or pnpm docs:local with sibling checkouts
+```
+
+See also [scripts/DIAGRAM-AUDITS.md](scripts/DIAGRAM-AUDITS.md).
diff --git a/README.md b/README.md
@@ -27,13 +27,14 @@
     <li><a href="#about-the-project">About The Project</a></li>
     <li><a href="#installation">Installation</a></li>
     <li><a href="#usage">Usage</a></li>
+    <li><a href="CONTRIBUTING.md">Contributing</a></li>
     <li><a href="#contact">Contact</a></li>
   </ol>
 </details>
 
 ## About The Project
 
-Documentation hub for [OpenShellOrg](https://github.com/openshellorg) — Antora site aggregating org projects, plus SOS certification packages in this monorepo.
+Documentation hub for [OpenShellOrg](https://github.com/openshellorg) — Antora site aggregating org projects, plus SOS certification packages in this monorepo. The published site follows the [facto-stack](https://github.com/antora-supplemental/facto-stack) Antora compose pack (Valentus + Lunr + page-context + site-nav-tree + maint extensions), aligned with [DevCentr docs](https://docs.devcentr.org/).
 
 ### Mission
 
@@ -79,6 +80,23 @@ docs/                      # this repo (openshellorg/docs)
 | `@sos/grammar` | Grammar definitions for parsing SOS syntax |
 | `@sos/validator-core` | Core validation logic for SOS compliance |
 
+### Diagram rendering engines (Facto)
+
+This hub uses the [antora-diagram-engines](https://github.com/antora-supplemental/antora-diagram-engines) packages Facto documents — not custom renderers:
+
+| Diagram source | Renderer | Package / extension |
+|----------------|----------|---------------------|
+| AsciiDoc `[source,mermaid]` (and `.mermaid-client` roles) | Client Mermaid in the browser | `@antora-supplemental/mermaid-client` |
+| PlantUML and other Kroki diagram types in AsciiDoc | Build-time bake via Kroki | `asciidoctor-kroki` (`kroki-server-url`, `kroki-fetch-diagram`) |
+| Baked SVG + client Mermaid hosts | Lightbox / zoom UI | `@antora-supplemental/diagram-lightbox` |
+| `image::…[.themed-svg]` committed figures (e.g. shell-architecture) | Pre-generated adaptive/host SVGs in the product repo (`mermaid-cli` + `@dev-centr/mermaid-svg-css-vars`); runtime recolor via `@dev-centr/themed-svg` | Bake freshness: [shell-architecture](https://github.com/openshellorg/shell-architecture) `pnpm diagrams:check` / `pnpm test` (not re-run from this hub) |
+
+Playbook attrs: `mermaid-client: ''`, `mermaid-client-mode: client`. Supplemental UI loads `mermaid-client-*` and `diagram-lightbox-*` partials after SoftNav (Facto stack demo pattern).
+
+**Hub diagram CI** (`pnpm diagrams:check:all`): sync/check vendored themed-svg runtime, static dark-mode text audit on committed adaptive SVGs (no mermaid-cli / Puppeteer), and verifier unit tests. Antora build runs `verify-themed-svg-dark-mode` as warnings on catalog SVGs.
+
+**Mermaid → SVG bake is not validated here.** Hub Actions do not run mermaid-cli or Puppeteer. If you change `.mmd` or theme manifests in a product repo, run that repo’s `pnpm diagrams` / `pnpm diagrams:check` on a developer machine before merge ([shell-architecture diagrams guide](https://github.com/openshellorg/shell-architecture/blob/main/diagrams/README.adoc)). See [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Installation
 
 ### Prerequisites
@@ -103,6 +121,9 @@ pnpm build
 pnpm docs
 # or local sibling checkouts:
 pnpm docs:local
+
+# Themed SVG / diagram audits (hub static checks only; no upstream mermaid-cli)
+pnpm diagrams:check:all
 ```
 
 Published docs: https://docs.opensh.org/

diff --git a/antora-playbook-local.yml b/antora-playbook-local.yml
@@ -1,3 +1,4 @@
+# Local sibling checkouts — same Facto extensions as antora-playbook.yml
 site:
   title: OpenShellOrg Docs
   url: https://docs.opensh.org
@@ -7,12 +8,52 @@ site:
     site_home_url: https://opensh.org
     site_home_label: OpenShellOrg home
     header_doc_title: OpenShellOrg Docs
+    nav_typology_diataxis: 'true'
+
+urls:
+  html_extension_style: indexify
 
 antora:
   extensions:
     - '@antora/lunr-extension'
     - require: '@antora-supplemental/unversioned-component-urls'
+    - require: '@antora-supplemental/site-nav-tree'
+      include:
+        - open-shell-org
+        - shell-architecture
+        - about
+        - nu-require
+        - nu-emit
+        - project-map
+      order:
+        - open-shell-org
+        - shell-architecture
+        - about
+        - nu-require
+        - nu-emit
+        - project-map
+    - require: '@antora-supplemental/nav-typology'
+    - require: '@antora-supplemental/nav-typology-diataxis'
     - '@antora-supplemental/build-stack'
+    - ./lib/verify-themed-svg-dark-mode.js
+    - '@antora-supplemental/page-edit'
+    - require: '@antora-supplemental/link-validator'
+      reportEmail: openshell@devcentr.org
+      softFail403: true
+      failLevel: none
+    - require: '@antora-supplemental/linkinator'
+      statusDefault: unchecked
+    - require: '@antora-supplemental/extension-lister'
+      layouts: [footer]
+    - require: '@antora-supplemental/orphan-finder/extension'
+      reportEmail: openshell@devcentr.org
+      failOnUnresolved: false
+    - require: '@antora-supplemental/page-context/antora'
+      component: open-shell-org
+      path: keywords
+    # Diagram rendering engines — same mapping as antora-playbook.yml (Facto / antora-diagram-engines + Kroki).
+    - require: '@antora-supplemental/mermaid-client/antora'
+    - require: '@antora-supplemental/diagram-lightbox'
 
 content:
   sources:
@@ -43,7 +84,7 @@ content:
     - url: ../project-map
       branches: HEAD
       start_path: docs
-    - url: ../actor-shell
+    - url: ../grammaton-ui-shell
       branches: HEAD
       start_path: docs
     - url: ../terminal-gui-prompts
@@ -57,12 +98,21 @@ ui:
   supplemental_files: ./supplemental-ui
 
 asciidoc:
+  extensions:
+    - asciidoctor-kroki
+    - '@antora-supplemental/page-context'
   attributes:
     stem: latexmath
     experimental: ""
     idprefix: ""
     idseparator: "-"
     page-pagination: ""
+    kroki-server-url: https://kroki.io
+    kroki-fetch-diagram: true
+    mermaid-client: ''
+    mermaid-client-mode: client
+    page-context-active: ''
+    page-context-keyword-base: '/open-shell-org/keywords'
 
 output:
   dir: build/site
diff --git a/antora-playbook.yml b/antora-playbook.yml
@@ -1,3 +1,4 @@
+# OpenShellOrg Docs — CI/production (Facto stack + OSO hub sources)
 site:
   title: OpenShellOrg Docs
   url: https://docs.opensh.org
@@ -11,13 +12,57 @@ site:
     site_home_url: https://opensh.org
     site_home_label: OpenShellOrg home
     header_doc_title: OpenShellOrg Docs
+    nav_typology_diataxis: 'true'
+
+urls:
+  html_extension_style: indexify
 
 antora:
   extensions:
     - '@antora/lunr-extension'
     - require: '@antora-supplemental/unversioned-component-urls'
-    - '@antora-supplemental/page-edit'
+    - require: '@antora-supplemental/site-nav-tree'
+      include:
+        - open-shell-org
+        - shell-architecture
+        - about
+        - nu-require
+        - nu-emit
+        - project-map
+      order:
+        - open-shell-org
+        - shell-architecture
+        - about
+        - nu-require
+        - nu-emit
+        - project-map
+    - require: '@antora-supplemental/nav-typology'
+    - require: '@antora-supplemental/nav-typology-diataxis'
     - '@antora-supplemental/build-stack'
+    - ./lib/verify-themed-svg-dark-mode.js
+    - '@antora-supplemental/page-edit'
+    - require: '@antora-supplemental/link-validator'
+      reportEmail: openshell@devcentr.org
+      softFail403: true
+      failLevel: none
+    - require: '@antora-supplemental/linkinator'
+      statusDefault: unchecked
+    - require: '@antora-supplemental/extension-lister'
+      layouts: [footer]
+    - require: '@antora-supplemental/orphan-finder/extension'
+      reportEmail: openshell@devcentr.org
+      failOnUnresolved: false
+    - require: '@antora-supplemental/page-context/antora'
+      component: open-shell-org
+      path: keywords
+    # Diagram rendering engines (Facto / antora-diagram-engines + Kroki — no alternate renderers):
+    # | Format | Engine |
+    # | [source,mermaid] listings | @antora-supplemental/mermaid-client (client runtime) |
+    # | plantuml, ditaa, … | asciidoctor-kroki → kroki-server-url |
+    # | zoom / lightbox chrome | @antora-supplemental/diagram-lightbox |
+    # | [.themed-svg] image::… committed SVGs | upstream mermaid-cli + mermaid-svg-css-vars; @dev-centr/themed-svg at site runtime (not AsciiDoc listing renderers) |
+    - require: '@antora-supplemental/mermaid-client/antora'
+    - require: '@antora-supplemental/diagram-lightbox'
 
 content:
   sources:
@@ -48,7 +93,8 @@ content:
     - url: https://github.com/openshellorg/project-map.git
       branches: [main]
       start_path: docs
-    - url: https://github.com/openshellorg/actor-shell.git
+    # Grammaton UI Shell moved from openshellorg/actor-shell to Desktop-Tooling/grammaton-ui-shell
+    - url: https://github.com/Desktop-Tooling/grammaton-ui-shell.git
       branches: [main]
       start_path: docs
     - url: https://github.com/openshellorg/terminal-gui-prompts.git
@@ -62,12 +108,22 @@ ui:
   supplemental_files: ./supplemental-ui
 
 asciidoc:
+  extensions:
+    # Kroki bakes PlantUML and other non-Mermaid diagram types; mermaid-client skips [source,mermaid].
+    - asciidoctor-kroki
+    - '@antora-supplemental/page-context'
   attributes:
     stem: latexmath
     experimental: ""
     idprefix: ""
     idseparator: "-"
     page-pagination: ""
+    kroki-server-url: https://kroki.io
+    kroki-fetch-diagram: true
+    mermaid-client: ''
+    mermaid-client-mode: client
+    page-context-active: ''
+    page-context-keyword-base: '/open-shell-org/keywords'
 
 output:
   dir: build/site
diff --git a/docs/modules/ROOT/pages/ecosystem.adoc b/docs/modules/ROOT/pages/ecosystem.adoc
@@ -33,7 +33,7 @@ link:https://github.com/AMDphreak/connectome-fs[connectome-fs] owns node/edition
 Spec and ownership live in shell-architecture:
 
 * xref:shell-architecture::shell-host-and-env-refresh.adoc[env-refresh + terminal fork] — Nu-first `env-refresh` CLI (planned) and https://github.com/openshellorg/terminal[`openshellorg/terminal`] (fork of Windows Terminal) with per-tab env health + Fix/Insert desync bar; DevCentr prefers these when installed
-* xref:actor-shell::index.adoc[actor-shell] — non-frustrating Windows/Linux UI shell on an Erlang-style actor runtime (D); Phase 1 `libbeam_d` landed
+* xref:grammaton-ui-shell::index.adoc[Grammaton UI Shell] — non-frustrating Windows/Linux UI shell on an Erlang-style actor runtime (D); Phase 1 `libbeam_d` landed (formerly actor-shell; now `Desktop-Tooling/grammaton-ui-shell`)
 
 == Orientation and help