Add: docs/HLD.md, the high-level design, with its diagrams on Pages

.github/workflows/pages.yml

@@ -9,6 +9,10 @@ name: Pages
 # where corvidlabs.xyz reads them from for a repo marked `governed` in its
 # project catalog (scripts/refresh-coverage.ts).
 #
+# And the high-level design, docs/HLD.md, at /architecture/, with its Mermaid
+# diagrams drawn. That page is not the demo and is not built by hi: it is the
+# markdown rendered into docs/site/architecture.html.
+#
 # Pages must be enabled once in the repository settings
 # (Settings -> Pages -> Source: GitHub Actions); this workflow does not enable it.
 
@@ -20,6 +24,8 @@ on:
       - "INTENT.md"      # the page title and its lead prose
       - "src/**"         # how the page is rendered
       - "specs/**"       # the atlas coverage badges track these
+      - "docs/HLD.md"    # the architecture page
+      - "docs/site/**"   # and its template
       - ".github/workflows/pages.yml"
   workflow_dispatch:
 
@@ -72,6 +78,24 @@ jobs:
           output-dir: site/badges
           components: "coverage langmix treemap sunburst calendar"
 
+      # GitHub renders the Mermaid fences in docs/HLD.md natively; this page
+      # does the same by loading Mermaid from jsdelivr in the reader's browser.
+      # That is why it is a separate page from the one above, which fetches
+      # nothing (hi: VIEW-2). marked is pinned so the markup cannot move under
+      # the template.
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Render the architecture page
+        run: |
+          mkdir -p site/architecture
+          bunx marked@18.0.14 --gfm -i docs/HLD.md -o "$RUNNER_TEMP/hld.html"
+          awk -v body="$RUNNER_TEMP/hld.html" '
+            $0 == "<!-- HLD -->" { while ((getline line < body) > 0) print line; found = 1; next }
+            { print }
+            END { if (!found) { print "docs/site/architecture.html has no <!-- HLD --> line" > "/dev/stderr"; exit 1 } }
+          ' docs/site/architecture.html > site/architecture/index.html
+          grep -q 'language-mermaid' site/architecture/index.html
+
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:

README.md

@@ -284,6 +284,32 @@ usually the whole reason two criteria disagree. Use the subject the sentence act
 `an operator`. `admin` is a permission bit; an operator is someone with a job to do, and the job is
 what the criterion is about.
 
+## Architecture
+
+One binary and plain files. The verbs that write hold a lock on `hi/` for the whole
+read-modify-write, and the two that write criteria read the result back before they save it; the
+verbs that read never lock. Nothing leaves the repository except the ticket `hi issue --create`
+hands to `gh`.
+
+```mermaid
+flowchart LR
+    accTitle: hi at a glance
+    accDescr: A person or an agent runs hi. Capture, retire, index and seed write the files in hi/ and INTENT.md under a lock. Check, ls, export, issue and view only read them, and hand JSON to an agent, a ticket to gh, and a page to a browser.
+
+    who(["person or agent"]) --> write["capture · retire · index · seed<br/>one writer at a time"]
+    who --> read["check · ls · export · issue · view<br/>read only"]
+    write --> files[("hi/*.md<br/>INTENT.md")]
+    files --> read
+    read -->|"hi export"| json["JSON for an agent<br/>then a spec-sync spec"]
+    read -->|"hi issue --create"| gh["a GitHub issue, via gh"]
+    read -->|"hi view"| page["one self-contained page"]
+```
+
+[docs/HLD.md](docs/HLD.md) is the high-level design: the modules, the capture, retire and export
+flows, how HI/1 is parsed, the id rules, how `INTENT.md`'s list is regenerated, the fledge plugin
+and its hooks, and what breaks and how. It is also published with its diagrams at
+[corvidlabs.github.io/hi/architecture](https://corvidlabs.github.io/hi/architecture/).
+
 ## What it deliberately does not do
 
 `hi` stores **no state**, tracks **no lifecycle**, binds **no evidence**, and **never fails a build