Fooftilly · cursor · Sep 21, 2026 · Sep 20, 2026 · Sep 21, 2026 · Sep 21, 2026
diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md
@@ -2,6 +2,20 @@
 
 PRKS is a local-first research application with a Python backend, SQLite persistence, managed files on disk, and a vanilla-JavaScript single-page frontend.
 
+```mermaid
+flowchart LR
+    U[Browser / PWA] -->|HTTP / API| S[PRKS threaded HTTP server]
+    S --> G[LibraryAccessGate]
+    G --> DB[(SQLite library)]
+    G --> F[Managed files]
+    G --> I[Derived indexes / caches]
+    U --> LS[(Browser local store)]
+    LS <-->|durable ops + reconciliation| S
+```
+
+The diagram separates canonical server storage from browser-local durable intent and from rebuildable derived indexes.
+
+
 ## Runtime shape
 
 At a high level:

diff --git a/docs/wiki/Getting-Started.md b/docs/wiki/Getting-Started.md
@@ -2,6 +2,9 @@
 
 PRKS is designed to run locally. The normal installation uses Python and SQLite directly; Docker is optional.
 
+![PRKS public-domain demo library](https://raw.githubusercontent.com/Fooftilly/PRKS/master/docs/screenshots/folders.png)
+
+
 ## Requirements
 
 PRKS currently requires Python 3.12 or newer and the exact Python package versions pinned in `requirements.txt`. The application validates the Python environment before it performs database recovery, migrations, storage binding, or server startup.

diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md
@@ -4,6 +4,15 @@ PRKS (Personal Research Knowledge System) is a local research library for organi
 
 The wiki is the orientation layer for users and contributors. It explains how the major parts fit together without replacing the repository's detailed implementation documents.
 
+## PRKS at a glance
+
+| Library | Work / PDF | People |
+| --- | --- | --- |
+| ![PRKS folder showing public-domain research works](https://raw.githubusercontent.com/Fooftilly/PRKS/master/docs/screenshots/folders.png) | ![PRKS Work view with Origin of Species open in the PDF reader](https://raw.githubusercontent.com/Fooftilly/PRKS/master/docs/screenshots/work.png) | ![PRKS People library](https://raw.githubusercontent.com/Fooftilly/PRKS/master/docs/screenshots/people.png) |
+
+These screenshots are generated from the repository's synthetic/public-domain demo library rather than a real personal research collection.
+
+
 ## Start here
 
 - [Getting Started](Getting-Started.md) — install, run, Docker, testing mode, and storage basics.

diff --git a/docs/wiki/Offline-and-Sync.md b/docs/wiki/Offline-and-Sync.md
@@ -2,6 +2,28 @@
 
 PRKS is progressively becoming local-first. The core rule is that durable user intent and offline read caching are separate systems.
 
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant UI as PRKS UI
+    participant L as Durable local store
+    participant S as PRKS server
+    participant DB as Canonical SQLite state
+
+    U->>UI: Edit supported data
+    UI->>L: Persist operation first
+    L-->>UI: Project pending intent
+    UI-->>U: Show saved/pending state
+    L->>S: Sync when reachable
+    S->>DB: Validate + apply
+    DB-->>S: Canonical revision
+    S-->>L: Acknowledge / reconcile
+    L-->>UI: Project canonical result
+```
+
+A disposable offline read projection is separate from this durable mutation path.
+
+
 ## Three different mechanisms
 
 ### Disposable read cache/projection

diff --git a/docs/wiki/README.md b/docs/wiki/README.md
@@ -24,3 +24,16 @@ When a wiki page summarizes one of those areas, link to the authoritative docume
 `.github/workflows/publish-wiki.yml` mirrors this directory to the GitHub Wiki after changes land on `master`. `README.md` itself is source-maintenance guidance and is not published as a Wiki page.
 
 GitHub creates the backing `PRKS.wiki.git` repository only after the Wiki has been initialized once. If it does not exist yet, create an initial Home page in the repository's Wiki UI, then run the **Publish Wiki** workflow manually. After that, merges that touch `docs/wiki/**` publish automatically.
+
+
+## Visual documentation
+
+Use visuals when they explain a workflow or architecture faster than prose:
+
+- repository demo screenshots must come from synthetic/public-domain test data;
+- screenshots should be referenced from stable repository URLs so they render in both `docs/wiki/` and the published GitHub Wiki;
+- prefer Mermaid for architecture/data-flow diagrams that benefit from version-controlled text diffs;
+- keep diagrams small and conceptual rather than mirroring implementation line-by-line;
+- do not publish screenshots from a real personal research library.
+
+The canonical promotional screenshot pipeline lives under `scripts/seed_demo_library.py`, `scripts/capture_demo_screenshots.py`, and `docs/screenshots/`.
diff --git a/docs/wiki/Research-Network.md b/docs/wiki/Research-Network.md
@@ -2,6 +2,23 @@
 
 PRKS includes structured research entities in addition to ordinary library metadata.
 
+```mermaid
+flowchart LR
+    W[Works / sources] -->|research-note mentions| A[Arguments / Stances]
+    A -->|evidence / source| W
+    W -->|research-note mentions| C[Concepts]
+    C -->|parent of| C2[Child Concepts]
+    A -->|supports / opposes / qualifies / holds| P[Positions]
+    A -->|responds to| A2[Other Arguments]
+    P --> G[Research Graph]
+    A --> G
+    C --> G
+    W --> G
+```
+
+The graph is a projection of canonical research relationships; it is not a separate graph database.
+
+
 ## Concepts
 
 Concepts represent research ideas/categories and can participate in hierarchical/related structures. Concept list/detail pages can be used alongside Works in the workspace.

diff --git a/docs/wiki/User-Guide.md b/docs/wiki/User-Guide.md
@@ -2,6 +2,11 @@
 
 PRKS organizes research around Works and the entities connected to them. The interface is deliberately closer to a research workspace than to a file manager: a PDF or video can carry bibliographic metadata, research notes, people/roles, tags, progress, annotations, and links into the research network.
 
+![PRKS Work detail with managed PDF](https://raw.githubusercontent.com/Fooftilly/PRKS/master/docs/screenshots/work.png)
+
+The screenshots in this guide use the public-domain demo library maintained by the repository.
+
+
 ## Works
 
 A Work is the central research item. A Work may represent a managed PDF, an online/video source, or another supported research item.

diff --git a/docs/wiki/Workspace-Tabs-and-Split-View.md b/docs/wiki/Workspace-Tabs-and-Split-View.md
@@ -2,6 +2,23 @@
 
 PRKS keeps a strip of in-app tabs under the top ribbon. Stacked mode shows one page at a time. Split view shows Main on the left and a Secondary area on the right that can itself be split further, up to 4 panes on screen at once (Main plus 3 Secondary). PRKS remembers your open tabs and split layout between sessions on this browser/device. That memory is local to the browser profile; there is no server-side workspace synchronization in this version.
 
+```mermaid
+flowchart TB
+    Tabs[Open PRKS tabs] --> Main[Main pane<br/>owns browser URL]
+    Tabs --> Secondary[Secondary tree<br/>recursive splits]
+    Tabs --> Parked[Parked tabs<br/>not currently mounted]
+    Secondary --> S1[Secondary pane]
+    Secondary --> S2[Secondary pane]
+    S1 --> S3[Optional nested split]
+
+    Main -. per-tab .-> C1[TabContext]
+    S1 -. per-tab .-> C2[TabContext]
+    S2 -. per-tab .-> C3[TabContext]
+```
+
+Each visible pane has its own TabContext; parked tabs remain open without necessarily keeping their page resources mounted. Main is a permanent root pane beside the Secondary tree — nested splits live only under Secondary.
+
+
 ## Workspace tabs
 
 Opening supported destinations creates or reuses PRKS tabs. Tabs can be switched, reordered, closed, or parked.