Add session trace reports and GitHub Pages docs site

Author: apartsin

.github/workflows/pages.yml

@@ -0,0 +1,53 @@
+name: Publish Docs Site
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install site generator dependency
+        run: python -m pip install markdown
+
+      - name: Build HTML site
+        run: python scripts/build_pages_site.py
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

INSTALL.md

@@ -85,6 +85,7 @@ Useful runtime pages:
 
 - `http://127.0.0.1:8000/`
 - `http://127.0.0.1:8000/diagnostics/view`
+- `http://127.0.0.1:8000/sessions/{session_id}/trace-report`
 
 ## Run the Tests
 
@@ -117,4 +118,7 @@ npm run test:e2e:real
 
 - The normal app runtime is GPU-only and uses the real Diffusers backend.
 - The mock generator is reserved for tests and explicit test harnesses only.
+- Round generation and feedback submission run as async jobs with visible progress in the UI.
 - Trace logs are written under `data/traces/`.
+- Per-session trace bundles and readable `report.html` files are written under `data/traces/sessions/<session_id>/`.
+- You can generate a complete real GPU example bundle with `python scripts/create_real_e2e_example.py`.

README.md

@@ -49,6 +49,7 @@ This repository now contains:
 - a real GPU-backed Diffusers generation workflow
 - a deterministic mock generation path reserved for tests
 - rich backend logging and persisted trace events
+- per-session HTML trace reports that capture proposed images, user actions, and preference outcomes
 - frontend trace capture and visible trace panels
 - automated API, lifecycle, and browser tests including replay export smoke coverage
 
@@ -125,19 +126,32 @@ back to mock automatically. The mock generator is reserved for explicit test
 harnesses only.
 
 Trace logs are persisted under `data/traces/`.
+Per-session reports are written under `data/traces/sessions/<session_id>/report.html` and are also available in the app at `/sessions/{session_id}/trace-report`.
 
 Run a one-off real-model smoke test:
 
 ```bash
 python scripts/smoke_real_diffusers.py
 ```
 
+Create a full real GPU-backed example run with a readable HTML walkthrough:
+
+```bash
+python scripts/create_real_e2e_example.py
+```
+
 Build an optional release zip:
 
 ```bash
 powershell -ExecutionPolicy Bypass -File scripts/build_release_zip.ps1 -Version v0.1.0
 ```
 
+Build the static HTML documentation site locally:
+
+```bash
+python scripts/build_pages_site.py
+```
+
 ## Legacy Source
 
 The original combined specification is preserved as:
@@ -146,7 +160,7 @@ The original combined specification is preserved as:
 
 ## Next Suggested Steps
 
-- add a diagnostics endpoint for backend, CUDA, and model readiness
-- introduce a database-backed repository
 - expand browser coverage for pairwise and top-k feedback flows
-- add release packaging and bootstrap/install scripts
+- add export packaging for session trace bundles
+- surface richer GPU diagnostics like adapter name and VRAM in the UI
+- add CI automation for the release packaging flow

RELEASE.md

@@ -10,6 +10,7 @@ A release should include:
 - release notes
 - installation instructions
 - optional packaged zip artifact
+- updated user/developer docs for async jobs, trace reports, and example bundles
 
 Current release notes:
 
@@ -24,14 +25,16 @@ Current release notes:
    `npm run test:e2e:chrome`
 4. If releasing from a CUDA-capable machine, optionally run:
    `python scripts/smoke_real_diffusers.py`
-5. Review:
+5. If releasing from a CUDA-capable machine, optionally refresh the real example bundle:
+   `python scripts/create_real_e2e_example.py`
+6. Review:
    - [INSTALL.md](E:\Projects\StableSteering\INSTALL.md)
    - [README.md](E:\Projects\StableSteering\README.md)
    - [RELEASE_NOTES_v0.1.0.md](E:\Projects\StableSteering\RELEASE_NOTES_v0.1.0.md)
-6. Build a source zip if needed:
+7. Build a source zip if needed:
    `powershell -ExecutionPolicy Bypass -File scripts/build_release_zip.ps1 -Version v0.1.0`
-7. Create the Git tag.
-8. Push the tag and upload the zip if desired.
+8. Create the Git tag.
+9. Push the tag and upload the zip if desired.
 
 ## Suggested Tagging Flow
 

RELEASE_NOTES_v0.1.0.md

@@ -10,9 +10,11 @@ Initial runnable MVP release of StableSteering.
 - browser UI for setup, interactive sessions, replay, diagnostics, and trace visibility
 - rich backend logging and persisted frontend/backend trace events
 - async round generation and feedback submission with visible progress indicators
+- per-session HTML trace reports saved by the backend
 - replay exports with schema and app version metadata
 - Playwright browser coverage, including replay export smoke and diagnostics checks
 - opt-in real-backend browser smoke path for CUDA-capable environments
+- reusable real GPU-backed end-to-end example bundle generation
 
 ## Included Documentation
 

app/README.md

@@ -5,7 +5,7 @@ This folder contains the running StableSteering application.
 ## Structure
 
 - `main.py`
-  FastAPI entry point. Builds app state, exposes HTML pages and JSON APIs, accepts frontend trace events, and serves runtime diagnostics.
+  FastAPI entry point. Builds app state, exposes HTML pages and JSON APIs, accepts frontend trace events, serves runtime diagnostics, and renders saved session trace reports.
 
 - `frontend_trace.py`
   Shared schema for browser-submitted trace events.
@@ -40,4 +40,4 @@ This folder contains the running StableSteering application.
 2. `engine/orchestrator.py` coordinates experiment, session, round, and feedback lifecycle.
 3. `engine/generation.py` resolves the active generation backend.
 4. `storage/repository.py` persists experiments, sessions, rounds, artifacts, and trace data references.
-5. `frontend/` renders the UI and posts browser events back to the backend.
+5. `frontend/` renders the UI, submits async jobs, shows progress, and posts browser events back to the backend.