From 2e6f15bf8afb2b5738cbc552f9990f4cf63251ad Mon Sep 17 00:00:00 2001
From: Matthew Paver <30728931+MatthewPaver@users.noreply.github.com>
Date: Fri, 23 Oct 2026 11:12:18 +0100
Subject: [PATCH] Add guided review using the real ProjectLens workflow

---
 Processing/tests/browser_walkthrough.py | 168 ++++++++++++++++++++
 README.md                               |  10 +-
 docs/change-assurance.html              |   7 +
 docs/change-assurance.js                |  49 +++++-
 docs/walkthrough.css                    |  94 ++++++++++++
 docs/walkthrough.js                     | 195 ++++++++++++++++++++++++
 scripts/run_browser_tests.py            |   1 +
 7 files changed, 516 insertions(+), 8 deletions(-)
 create mode 100644 Processing/tests/browser_walkthrough.py
 create mode 100644 docs/walkthrough.css
 create mode 100644 docs/walkthrough.js

diff --git a/Processing/tests/browser_walkthrough.py b/Processing/tests/browser_walkthrough.py
new file mode 100644
index 0000000..e647891
--- /dev/null
+++ b/Processing/tests/browser_walkthrough.py
@@ -0,0 +1,168 @@
+"""Exercise the guide against the real review/record engine, with isolated examples."""
+from pathlib import Path
+import json
+import os
+from playwright.sync_api import sync_playwright, expect
+
+BASE = os.environ.get("PROJECTLENS_BROWSER_BASE_URL", "http://127.0.0.1:8765/change-assurance.html")
+CAPTURES = Path(os.environ.get("PROJECTLENS_SCREENSHOT_DIR", "/tmp/projectlens-browser"))
+CAPTURES.mkdir(parents=True, exist_ok=True)
+
+
+def next_step(page, label):
+    page.get_by_role("button", name=f"Next: {label}", exact=True).click()
+
+
+def snapshot(page):
+    return page.evaluate("window.ProjectLensWalkthrough.snapshot()")
+
+
+def ready(page):
+    page.goto(f"{BASE}?walkthrough=1")
+    expect(page.locator("#tourMovement")).to_contain_text("73 days")
+
+
+def run_journey(browser):
+    context = browser.new_context(viewport={"width": 1440, "height": 1000}, reduced_motion="reduce")
+    page = context.new_page()
+    page.goto(BASE)
+    # Existing work must survive the demonstration, its saves and its restart.
+    preserved = page.evaluate("""() => {
+      const record = {id:'existing-work',project:'Real work sentinel',owner:'Keep me',rationale:'Preserve this record',decision:'Return for revision',createdAt:'2026-10-01T00:00:00Z',evidenceVersion:'existing-source'};
+      const values = {'projectlens:change-decisions:v1':JSON.stringify([record]),'projectlens:change-conditions:v1':'[]','projectlens:evidence-requests:v1':'[]','projectlens:review-draft:v1':JSON.stringify({marker:'existing draft'})};
+      Object.entries(values).forEach(([key,value])=>localStorage.setItem(key,value)); return values;
+    }""")
+    requests, errors = [], []
+    page.on("request", lambda request: requests.append((request.method, request.url)))
+    page.on("pageerror", lambda error: errors.append(str(error)))
+    ready(page)
+    assert snapshot(page)["decisions"] == []
+    expect(page.locator("#tourPlay")).to_be_disabled()
+    assert page.evaluate("getComputedStyle(document.querySelector('.tour-bar.current')).animationName") == "none"
+    # The expected findings are recomputed by the publicly exposed product engine.
+    assert page.evaluate("""() => {
+      const {review,narrative}=ProjectLensWalkthrough.snapshot(), api=ProjectLensChangeAssurance;
+      const actual=api.analyseReview(api.parseXer(review.previous.sourceText,review.previous.fileName),api.parseXer(review.current.sourceText,review.current.fileName),narrative);
+      return JSON.stringify(actual.blockers)===JSON.stringify(review.blockers)&&actual.finishMovement===review.finishMovement;
+    }""")
+    page.screenshot(path=str(CAPTURES / "walkthrough-desktop.png"), full_page=True)
+    next_step(page, "inspect the conflict")
+    expect(page.locator("#tourTitle")).to_be_focused()
+    expect(page.locator("#blockerList .blocker")).to_have_count(3)
+    page.locator('[data-finding="1"]').click()
+    expect(page.locator("#findingEvidence")).to_contain_text("constraint")
+    next_step(page, "change the claim")
+    original = snapshot(page)
+    page.locator("#tourNarrative").fill("A new narrative awaiting checks.")
+    expect(page.locator("#tourNext")).to_be_disabled()
+    page.get_by_role("button", name="Try an acknowledged finish change", exact=True).click()
+    expect(page.locator("#tourCheckStatus")).to_contain_text("4 findings in the original pack; 3 now")
+    changed = snapshot(page)
+    assert changed["review"]["inputIdentity"] != original["review"]["inputIdentity"]
+    assert changed["review"]["previous"] == original["review"]["previous"]
+    assert changed["review"]["current"] == original["review"]["current"]
+    assert not any(finding["type"] == "Contradiction" for finding in changed["review"]["blockers"])
+    next_step(page, "make a decision")
+    expect(page.locator("#tourNext")).to_be_disabled()
+    assert snapshot(page)["decisions"] == []
+    page.get_by_label("Approve with conditions", exact=True).check()
+    page.locator("#decisionCondition").fill("Confirm the schedule basis")
+    page.get_by_role("button", name="Save decision record", exact=False).click()
+    expect(page.locator("#workspaceError")).to_contain_text("owner and a due date")
+    expect(page.locator("#tourPosition")).to_contain_text("Step 4")
+    page.locator("#conditionOwner").fill("Example planning lead")
+    page.locator("#conditionDue").fill("2027-12-01")
+    page.get_by_role("button", name="Save decision record", exact=False).click()
+    expect(page.locator("#tourPosition")).to_contain_text("Step 5")
+    with page.expect_download() as event:
+        page.get_by_role("button", name="Download walkthrough record", exact=True).click()
+    record = json.loads(Path(event.value.path()).read_text())
+    assert record["demonstration"] is True and record["storage"] == "memory-only"
+    assert record["decisions"][0]["findings"] == changed["review"]["blockers"]
+    assert record["decisions"][0]["narrative"] == changed["narrative"]
+    assert record["decisions"][0]["inputIdentity"] == changed["review"]["inputIdentity"]
+    assert len(record["decisions"][0]["precedentsNotReviewed"]) == 3
+    assert record["conditions"][0]["decisionId"] == record["decisions"][0]["id"]
+    next_step(page, "track the follow-up")
+    expect(page.locator("#tourNext")).to_have_text("Follow-up still open")
+    page.get_by_role("button", name="Mark closed", exact=True).click()
+    expect(page.locator("#tourComplete")).to_contain_text("Condition closed")
+    expect(page.locator("#tourNext")).to_have_text("Walkthrough complete")
+    with page.expect_download() as event:
+        page.get_by_role("button", name="Download walkthrough record", exact=True).click()
+    assert json.loads(Path(event.value.path()).read_text())["conditions"][0]["closed"] is True
+    assert page.evaluate("values => Object.entries(values).every(([key,value])=>localStorage.getItem(key)===value)", preserved)
+    page.get_by_role("button", name="Restart", exact=True).click()
+    expect(page.locator("#tourMovement")).to_contain_text("73 days")
+    assert snapshot(page)["decisions"] == []
+    assert snapshot(page)["conditions"] == []
+    assert page.evaluate("values => Object.entries(values).every(([key,value])=>localStorage.getItem(key)===value)", preserved)
+    assert all(method == "GET" for method, _ in requests), requests
+    assert not any(":8787" in url for _, url in requests)
+    assert not errors, errors
+    context.close()
+
+
+def run_phone(browser):
+    context = browser.new_context(viewport={"width":390,"height":844}, reduced_motion="reduce")
+    page = context.new_page()
+    ready(page)
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth+1")
+    page.screenshot(path=str(CAPTURES / "walkthrough-mobile.png"), full_page=True)
+    for label in ["inspect the conflict", "change the claim", "make a decision"]:
+        next_step(page, label)
+        assert page.evaluate("document.documentElement.scrollWidth<=innerWidth+1")
+    page.get_by_label("Return for revision", exact=True).check()
+    page.get_by_role("button", name="Save decision record", exact=False).click()
+    next_step(page, "track the follow-up")
+    expect(page.locator("#tourComplete")).to_contain_text("without conditions")
+    assert snapshot(page)["conditions"] == []
+    context.close()
+
+
+def run_playback_and_recovery(browser):
+    context = browser.new_context(viewport={"width":1280,"height":900})
+    page = context.new_page()
+    page.clock.install()
+    ready(page)
+    page.get_by_role("button", name="Play walkthrough", exact=True).click()
+    page.clock.fast_forward(10000)
+    expect(page.locator("#tourPosition")).to_contain_text("Step 2")
+    page.get_by_role("button", name="Pause walkthrough", exact=True).click()
+    page.clock.fast_forward(20000)
+    expect(page.locator("#tourPosition")).to_contain_text("Step 2")
+    page.get_by_role("button", name="Play walkthrough", exact=True).click()
+    page.clock.fast_forward(10000)
+    expect(page.locator("#tourPosition")).to_contain_text("Step 3")
+    page.locator("#tourNarrative").focus()
+    page.clock.fast_forward(20000)
+    expect(page.locator("#tourPosition")).to_contain_text("Step 3")
+    page.get_by_role("button", name="Play walkthrough", exact=True).click()
+    page.clock.fast_forward(10000)
+    expect(page.locator("#tourPosition")).to_contain_text("Step 4")
+    expect(page.locator("#tourPlay")).to_be_disabled()
+    page.clock.fast_forward(30000)
+    assert snapshot(page)["decisions"] == []
+    context.close()
+    context = browser.new_context()
+    page = context.new_page()
+    page.route("**/demo/northstar-previous.xer", lambda route: route.abort())
+    page.goto(f"{BASE}?walkthrough=1")
+    expect(page.locator("#tourError")).to_be_visible()
+    expect(page.locator("#tourNext")).to_be_disabled()
+    page.unroute("**/demo/northstar-previous.xer")
+    page.get_by_role("button", name="Retry loading the example", exact=True).click()
+    expect(page.locator("#tourMovement")).to_contain_text("73 days")
+    expect(page.locator("#tourError")).to_be_hidden()
+    expect(page.locator("#workspaceError")).to_be_hidden()
+    context.close()
+
+
+if __name__ == "__main__":
+    with sync_playwright() as playwright:
+        browser = playwright.chromium.launch()
+        run_journey(browser)
+        run_phone(browser)
+        run_playback_and_recovery(browser)
+        browser.close()
+    print("Walkthrough passed: real checks, changed inputs, decision validation, export, closure, isolation, phone, playback and retry.")
diff --git a/README.md b/README.md
index 991a81f..4f75bb9 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ For the project controls reviewer who has to tell a board whether a change pack
 
 ![ProjectLens change assurance workspace comparing a change pack narrative against its schedule evidence](docs/assets/change-assurance-overview.png)
 
-**Live demo (no install, no account):** [review a change pack](https://matthewpaver.github.io/ProjectLens/change-assurance.html) · [XER schedule review](https://matthewpaver.github.io/ProjectLens/schedule-review.html) · [board review](https://matthewpaver.github.io/ProjectLens/board-readiness.html) · [public GMPP evidence](https://matthewpaver.github.io/ProjectLens/) · [2-minute walkthrough (MP4)](docs/assets/projectlens-evidence-demo.mp4)
+**Live demo (no install, no account):** [interactive guided review](https://matthewpaver.github.io/ProjectLens/change-assurance.html?walkthrough=1) · [review a change pack](https://matthewpaver.github.io/ProjectLens/change-assurance.html) · [XER schedule review](https://matthewpaver.github.io/ProjectLens/schedule-review.html) · [board review](https://matthewpaver.github.io/ProjectLens/board-readiness.html) · [public GMPP evidence](https://matthewpaver.github.io/ProjectLens/) · [2-minute walkthrough (MP4)](docs/assets/projectlens-evidence-demo.mp4)
 
 On the change-assurance page, select **Try the Northstar example**. It is a synthetic pack, and the result is one readiness verdict with three blockers and the questions to send the team before the meeting.
 
@@ -36,6 +36,14 @@ Expected result: the evidence desk shows three findings, including the 73-day fi
 
 **Your own schedules.** Export two single-project XER files from Primavera P6 (**File → Export → Primavera XER**): the comparison point and the latest submission. Select **Use my own XER files**, choose both files and paste the narrative. Files are parsed in the browser and never uploaded. If you have no XER to hand, use the synthetic [Northstar](https://matthewpaver.github.io/ProjectLens/demo/northstar-previous.xer) ([current](https://matthewpaver.github.io/ProjectLens/demo/northstar-current.xer)) or [Riverside](https://matthewpaver.github.io/ProjectLens/demo/riverside-previous.xer) ([current](https://matthewpaver.github.io/ProjectLens/demo/riverside-current.xer), [narrative](https://matthewpaver.github.io/ProjectLens/demo/riverside-narrative.txt)) pairs.
 
+## Guided review
+
+[Take the Northstar walkthrough](https://matthewpaver.github.io/ProjectLens/change-assurance.html?walkthrough=1) to inspect the two bundled XER exports, edit the narrative and rerun the actual checks. Choose a human decision, download the source-linked record and close an owned condition. The guide uses the same parser, checks, form validation and registers as the full application.
+
+Playback starts only when selected and pauses for the human decision, editing or a hidden tab. Reduced-motion visitors use Next. Walkthrough records are held in memory only, separate from saved work; reload or Restart discards them. The downloaded JSON is labelled as a demonstration. The walkthrough makes no causation or approval claim.
+
+The walkthrough journey, isolation, playback, phone layout and failed-load recovery run with `make browser-test` (the focused suite is `Processing/tests/browser_walkthrough.py`).
+
 ## How it works
 
 ```mermaid
diff --git a/docs/change-assurance.html b/docs/change-assurance.html
index d9e74d5..835cf12 100644
--- a/docs/change-assurance.html
+++ b/docs/change-assurance.html
@@ -17,6 +17,7 @@
   <link href="https://fonts.googleapis.com/css2?family=Archivo+Black&family=Libre+Franklin:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
   <link rel="stylesheet" href="styles.css">
   <link rel="stylesheet" href="change-assurance.css">
+  <link rel="stylesheet" href="walkthrough.css">
 </head>
 <body class="assurance-body">
   <a class="skip-link" href="#workspace">Skip to review workspace</a>
@@ -38,6 +39,9 @@
     </div>
   </header>
 
+  <p id="walkthroughSession" class="tour-session" hidden>Synthetic walkthrough · records exist only in this tab until reload. <a href="change-assurance.html">Exit to full ProjectLens</a></p>
+  <div class="tour-layout">
+  <aside id="walkthroughGuide" class="tour-guide" hidden aria-label="Walkthrough guide"></aside>
   <main id="workspace">
     <div id="workspaceError" class="workspace-notice" role="alert" hidden></div>
     <div id="draftNotice" class="workspace-notice" hidden>
@@ -54,6 +58,7 @@ <h1>Check the change pack<br><em>before you decide.</em></h1>
             <button class="assurance-primary" id="loadAssuranceDemo" type="button">Try the Northstar example <span>→</span></button>
             <button class="assurance-secondary" id="showOwnPack" type="button">Use my own XER files</button>
           </div>
+          <p class="walkthrough-entry"><a href="?walkthrough=1">Take the guided walkthrough</a> · about one minute, at your pace</p>
           <p class="trust-line">Your files stay in this browser. Fixed rules compare the dates, and a person makes the decision.</p>
         </div>
         <aside class="decision-preview assurance-reveal delay-1" aria-label="Example readiness result">
@@ -212,10 +217,12 @@ <h3>Similar cases from public records</h3>
       <div id="conditionRegister" class="register-list"></div>
     </section>
   </main>
+  </div>
 
   <footer class="site-footer">Built by Matthew Paver · <a href="https://matthewpaver.github.io/store/apps/projectlens/">product notes</a> · <a href="https://github.com/MatthewPaver/ProjectLens">source</a> · <a href="https://www.linkedin.com/in/matthew-paver-534262166/">LinkedIn</a> · <a href="https://matthewpaver.github.io/">matthewpaver.github.io</a></footer>
 
   <div class="assurance-toast" id="assuranceToast" role="status" aria-live="polite"></div>
   <script src="change-assurance.js"></script>
+  <script src="walkthrough.js"></script>
 </body>
 </html>
diff --git a/docs/change-assurance.js b/docs/change-assurance.js
index 4a86162..2573633 100644
--- a/docs/change-assurance.js
+++ b/docs/change-assurance.js
@@ -1,3 +1,18 @@
+// Walkthrough records are disposable and never share the real-work store.
+const IS_WALKTHROUGH = new URLSearchParams(window.location.search).get("walkthrough") === "1";
+const walkthroughRecords = new Map();
+function recordStore() {
+  return IS_WALKTHROUGH ? {
+    getItem: key => walkthroughRecords.get(key) ?? null,
+    setItem: (key, value) => walkthroughRecords.set(key, value),
+    removeItem: key => walkthroughRecords.delete(key),
+  } : localStorage;
+}
+if (IS_WALKTHROUGH) {
+  document.body.classList.add("walkthrough-session");
+  document.querySelector("#walkthroughSession").hidden = false;
+}
+
 const assuranceState = {
   files: { previous: null, current: null },
   review: null,
@@ -256,14 +271,14 @@ function showToast(message) {
 
 function storage(key) {
   try {
-    const value = JSON.parse(localStorage.getItem(key) || "[]");
+    const value = JSON.parse(recordStore().getItem(key) || "[]");
     return key === storageKeys.draft ? value : Array.isArray(value) ? value : [];
   } catch { return []; }
 }
 
 function saveStorage(key, value) {
   try {
-    localStorage.setItem(key, JSON.stringify(value));
+    recordStore().setItem(key, JSON.stringify(value));
     return true;
   } catch {
     showError("This browser could not save the record. Free device storage or allow site storage, then try again. Keep this tab open.");
@@ -680,6 +695,7 @@ function renderConditionRegister() {
     if (condition) condition.closed = !condition.closed;
     saveStorage(storageKeys.conditions, all);
     renderConditionRegister();
+    document.dispatchEvent(new Event("projectlens:condition-changed"));
   }));
 }
 
@@ -825,12 +841,13 @@ function saveDecision(event) {
   if (!saveRecordGroup(updates)) return;
   $("#workspaceError").hidden = true;
   if (storage(storageKeys.draft)?.inputIdentity === review.inputIdentity) {
-    try { localStorage.removeItem(storageKeys.draft); $("#draftNotice").hidden = true; } catch { /* A saved decision remains valid if the old draft cannot be removed. */ }
+    try { recordStore().removeItem(storageKeys.draft); $("#draftNotice").hidden = true; } catch { /* A saved decision remains valid if the old draft cannot be removed. */ }
   }
   renderConditionRegister();
   window.location.hash = "decisions";
   showToast("Decision record saved with its evidence version.");
   event.currentTarget.reset();
+  document.dispatchEvent(new Event("projectlens:decision-saved"));
 }
 
 function resetReview() {
@@ -891,7 +908,7 @@ function bindEvents() {
   $("#resumeDraft").addEventListener("click", resumeDraft);
   $("#discardDraft").addEventListener("click", () => {
     if (!window.confirm("Delete the saved draft from this device? The current open review stays in this tab.")) return;
-    try { localStorage.removeItem(storageKeys.draft); $("#draftNotice").hidden = true; }
+    try { recordStore().removeItem(storageKeys.draft); $("#draftNotice").hidden = true; }
     catch { showError("The saved draft could not be deleted. Check browser storage permissions."); }
   });
   $("#saveEvidenceRequest").addEventListener("click", saveEvidenceRequest);
@@ -950,12 +967,12 @@ function renderSelectedFinding(index) {
 function saveRecordGroup(updates) {
   const previous = {};
   try {
-    for (const key of Object.keys(updates)) previous[key] = localStorage.getItem(key);
-    for (const [key, value] of Object.entries(updates)) localStorage.setItem(key, JSON.stringify(value));
+    for (const key of Object.keys(updates)) previous[key] = recordStore().getItem(key);
+    for (const [key, value] of Object.entries(updates)) recordStore().setItem(key, JSON.stringify(value));
     return true;
   } catch {
     for (const [key, value] of Object.entries(previous)) {
-      try { if (value === null) localStorage.removeItem(key); else localStorage.setItem(key, value); } catch { /* Keep the open form available for recovery. */ }
+      try { if (value === null) recordStore().removeItem(key); else recordStore().setItem(key, value); } catch { /* Keep the open form available for recovery. */ }
     }
     showError("The decision could not be saved. Keep this tab open, allow site storage or free device space, then retry.");
     return false;
@@ -999,3 +1016,21 @@ showView(window.location.hash.slice(1) || "reviews");
 const bootStatus = $("#precedentStatus");
 if (bootStatus) bootStatus.textContent = `Run a review to retrieve precedents. ${precedentSidecarHint()}`;
 window.ProjectLensChangeAssurance = { parseXer, analyseReview };
+
+// A narrow bridge lets the guide use the product's real actions and records.
+if (IS_WALKTHROUGH) window.ProjectLensWalkthrough = {
+  async load() {
+    $("#workspaceError").hidden = true;
+    await loadDemo();
+    if (!assuranceState.review) throw new Error("The example could not load. Retry the walkthrough.");
+  },
+  async recheck(narrative) {
+    $("#assuranceNarrative").value = narrative;
+    await runReview();
+    if (!$("#workspaceError").hidden) throw new Error($("#workspaceError").textContent);
+  },
+  snapshot() {
+    return structuredClone({ review: assuranceState.review, narrative: $("#assuranceNarrative").value,
+      decisions: storage(storageKeys.decisions), conditions: storage(storageKeys.conditions) });
+  },
+};
diff --git a/docs/walkthrough.css b/docs/walkthrough.css
new file mode 100644
index 0000000..688848d
--- /dev/null
+++ b/docs/walkthrough.css
@@ -0,0 +1,94 @@
+.walkthrough-entry { margin-top: 1rem; font-size: .875rem; }
+.walkthrough-entry a { color: inherit; text-underline-offset: 4px; }
+.tour-session { margin: 0; padding: 12px 32px; background: #dce7e8; color: #18383b; font-size: 13px; line-height: 1.6; }
+.tour-session a { color: inherit; margin-left: 12px; text-underline-offset: 3px; }
+.walkthrough-session .tour-layout { max-width: 1600px; margin: auto; display: grid; grid-template-columns: 300px minmax(0, 1fr); }
+.tour-guide { padding: 32px 24px; align-self: start; position: sticky; top: 74px; }
+.tour-guide h1 { margin: 0 0 16px; font: 600 24px/1.2 'Libre Franklin', sans-serif; letter-spacing: -.025em; }
+.tour-intro { margin-bottom: 24px; font-size: 14px; line-height: 1.65; }
+.tour-steps { list-style: none; padding: 0; margin: 0 0 24px; }
+.tour-steps li + li { border-top: 1px solid #c4c3b9; }
+.tour-guide button { font: 500 13px/1.4 'Libre Franklin', sans-serif; cursor: pointer; color: #071a1b; }
+.tour-steps button { width: 100%; display: flex; gap: 12px; text-align: left; border: 0; background: transparent; padding: 12px 0; }
+.tour-steps span { font-variant-numeric: tabular-nums; }
+.tour-steps button[aria-current] { font-weight: 700; color: #8f3c27; }
+.tour-guide button:disabled { cursor: default; opacity: .52; }
+.tour-controls, .tour-navigation { display: flex; flex-wrap: wrap; gap: 8px; }
+.tour-controls button, .tour-navigation button, .tour-stage button { border: 1px solid #8b9690; padding: 11px 14px; background: #fffdf6; border-radius: 0; min-height: 44px; }
+.tour-navigation { margin-top: 20px; }
+.tour-navigation #tourNext { flex: 1; color: #fffdf6; background: #071a1b; border-color: #071a1b; }
+.tour-fine { font-size: 12px; line-height: 1.65; color: #455b56; margin: 14px 0; }
+.tour-exit { display: inline-block; margin-top: 8px; color: #18383b; font-size: 13px; text-underline-offset: 4px; }
+.walkthrough-session #workspace { min-width: 0; padding: 32px; background: #fffdf6; border-left: 1px solid #c4c3b9; }
+.tour-stage { scroll-margin-top: 96px; }
+.tour-stage-heading { margin-bottom: 28px; max-width: 70ch; }
+#tourPosition { margin: 0 0 12px; font-size: 13px; font-variant-numeric: tabular-nums; }
+.tour-stage h2 { font: 600 clamp(24px, 2.4vw, 36px)/1.2 'Libre Franklin', sans-serif; letter-spacing: -.025em; margin: 0 0 16px; }
+#tourDescription { font-size: 15px; line-height: 1.7; }
+.tour-timeline { padding: 24px; background: #f1ecdf; margin-bottom: 24px; }
+.tour-schedule { display: grid; grid-template-columns: 1fr auto; gap: 8px 16px; font-size: 13px; }
+.tour-schedule + .tour-schedule { margin-top: 28px; }
+.tour-schedule strong { font-variant-numeric: tabular-nums; }
+.tour-track { grid-column: 1 / -1; height: 24px; background: #e1e2d7; overflow: hidden; }
+.tour-bar { height: 100%; width: 100%; transform: scaleX(var(--finish-scale, 0)); transform-origin: left; background: #455e57; }
+.tour-bar.current { background: #a94d35; animation: reveal-finish 750ms cubic-bezier(.16,1,.3,1); }
+@keyframes reveal-finish { from { clip-path: inset(0 100% 0 0); } to { clip-path: inset(0 0 0 0); } }
+.tour-schedule code { grid-column: 1 / -1; overflow-wrap: anywhere; font: 12px/1.5 'JetBrains Mono', monospace; }
+#tourMovement { margin: 24px 0 0; font-weight: 600; font-size: 16px; line-height: 1.5; }
+#tourOriginalClaim { margin: 0; padding: 24px; background: #071a1b; color: #fffdf6; font-size: 16px; line-height: 1.7; white-space: pre-line; }
+#tourExperiment { margin-bottom: 28px; }
+#tourExperiment label { display: block; margin-bottom: 10px; font-size: 14px; font-weight: 600; }
+#tourNarrative { display: block; width: 100%; resize: vertical; padding: 16px; border: 1px solid #8b9690; background: #fffdf6; color: #071a1b; font: 14px/1.65 'Libre Franklin', sans-serif; caret-color: #a94d35; }
+.tour-experiment-actions { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 12px; }
+.tour-stage button { font: 500 13px/1.5 'Libre Franklin', sans-serif; cursor: pointer; color: #071a1b; }
+.tour-stage button:disabled { opacity: .52; cursor: wait; }
+.tour-guide button:hover:not(:disabled), .tour-stage button:hover:not(:disabled) { background: #dce7e8; color: #071a1b; }
+.tour-guide :focus-visible, .tour-stage :focus-visible { outline: 3px solid #406d84; outline-offset: 3px; }
+#tourCheckStatus, #tourRecordSummary, #tourDownloadStatus, .tour-form-hint, .tour-complete { font-size: 14px; line-height: 1.65; }
+.tour-form-hint, .tour-complete { padding: 16px; background: #dce7e8; color: #18383b; }
+.tour-error { padding: 16px; margin-bottom: 24px; background: #fae8df; color: #72321f; }
+.walkthrough-session .assurance-hero, .walkthrough-session .simple-flow, .walkthrough-session #packIntake,
+.walkthrough-session .review-tools, .walkthrough-session #supportingEvidence,
+.walkthrough-session .readiness-actions, .walkthrough-session #requestPanel, .walkthrough-session #draftNotice { display: none !important; }
+.walkthrough-session[data-tour-stage='0'] #readinessWorkspace { display: none; }
+.walkthrough-session[data-tour-stage='3'] #readinessCard { display: none; }
+.walkthrough-session .readiness-workspace { padding: 0 0 24px; }
+.walkthrough-session .review-context { margin-top: 24px; }
+.walkthrough-session .register-heading h1 { font: 600 26px/1.25 "Libre Franklin", sans-serif; letter-spacing: -.025em; }
+.walkthrough-session .register-row.closed { opacity: 1; }
+.walkthrough-session .assurance-toast:not(.show) { visibility: hidden; }
+.walkthrough-session .register-view { min-height: 0; padding: 24px 0; }
+.walkthrough-session .decision-panel { margin-top: 0; }
+.walkthrough-session .site-footer { padding: 24px 32px; }
+.walkthrough-session .header-meta a { display: none; }
+.walkthrough-session ::selection { background: #d6e4e7; color: #071a1b; }
+@media (max-width: 1100px) {
+  .walkthrough-session .tour-layout { grid-template-columns: 245px minmax(0, 1fr); }
+  .tour-guide { padding: 24px 16px; }
+  .walkthrough-session #workspace { padding: 24px; }
+  .walkthrough-session .evidence-desk { grid-template-columns: 1fr; }
+}
+@media (max-width: 760px) {
+  .walkthrough-session .tour-layout { display: block; }
+  .tour-guide { position: static; padding: 24px 16px; }
+  .tour-guide h1 { font-size: 24px; }
+  .tour-intro, .tour-steps { display: none; }
+  .tour-steps { display: none; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 0 12px; margin-bottom: 16px; }
+  .tour-steps li, .tour-steps li + li { border-top: 1px solid #c4c3b9; }
+  .tour-steps button { font-size: 12px; gap: 6px; }
+  .tour-guide .tour-fine:last-of-type, .tour-exit { display: none; }
+  .tour-session { padding: 12px 16px; font-size: 12px; }
+  .tour-session a { display: block; margin-left: 0; }
+  .walkthrough-session #workspace { border-left: 0; border-top: 1px solid #c4c3b9; padding: 24px 16px 80px; }
+  .tour-stage { scroll-margin-top: 80px; }
+  .tour-timeline { padding: 16px; }
+  .tour-schedule { grid-template-columns: 1fr; }
+  .walkthrough-session .assurance-header nav { display: none; }
+  .walkthrough-session .header-meta { display: block; }
+  .walkthrough-session .assurance-header { grid-template-columns: 1fr auto; }
+  .walkthrough-session .evidence-desk.evidence-open > div { display: block; }
+  .walkthrough-session .evidence-desk .finding-evidence { display: block; }
+  .walkthrough-session #backToFindings { display: none; }
+  .tour-navigation { position: fixed; inset: auto 0 0; padding: 12px 16px; background: #f1ecdf; border-top: 1px solid #8b9690; z-index: 60; margin: 0; }
+}
+@media (prefers-reduced-motion: reduce) { .tour-bar.current { animation: none; } }
diff --git a/docs/walkthrough.js b/docs/walkthrough.js
new file mode 100644
index 0000000..11f9ec4
--- /dev/null
+++ b/docs/walkthrough.js
@@ -0,0 +1,195 @@
+/* A guide around the existing product. All checks and records use its engine. */
+(() => {
+  const engine = window.ProjectLensWalkthrough;
+  if (!engine) return;
+  const byId = id => document.getElementById(id);
+  const reduced = matchMedia('(prefers-reduced-motion: reduce)');
+  const steps = [
+    ['Read the pack', 'The update says “unchanged”. What do the two schedules actually show?', 'These are the bundled Northstar XER files. The dates below come from the same parser used by the full application.'],
+    ['Inspect the conflict', 'The finish moved. The narrative did not.', 'Select a finding in the real evidence desk. Inspect the original activity fields and the narrative beside them. All detected findings remain available.'],
+    ['Change the claim', 'Same schedules. A different narrative.', 'Edit the text, then rerun the real checks. Acknowledging movement can remove a keyword conflict; it does not repair the schedule or prove the explanation.'],
+    ['Make a decision', 'The next step belongs to a person.', 'Choose an outcome and complete the real form. “Approve with conditions” also needs a condition, owner and due date. Unresolved findings stay in the record.'],
+    ['Export the record', 'The decision keeps its evidence.', 'Download the engine-generated record, including the exact narrative, findings, source identity and any condition. This walkthrough stores nothing in your saved-work register.'],
+    ['Track the follow-up', 'An owned condition stays visible.', 'If you added a condition, mark it closed in the real register. Closure changes its status; it does not erase the decision or its original findings.'],
+  ];
+  let step = 0, playing = false, timer, busy = false, loaded = false, dirty = false, original = '', originalCount = 0;
+  let downloaded = false;
+  const guide = byId('walkthroughGuide');
+  guide.innerHTML = `<h1>See a change review through.</h1><p class="tour-intro">A short guided example, with the working application. Play the introduction or explore at your pace.</p>
+    <ol class="tour-steps">${steps.map(([label], i) => `<li><button type="button" data-tour-step="${i}" disabled><span>${i + 1}</span>${label}</button></li>`).join('')}</ol>
+    <div class="tour-controls"><button type="button" id="tourPlay" disabled>Play walkthrough</button><button type="button" id="tourRestart">Restart</button></div>
+    <p id="tourPlayback" class="tour-fine" role="status">Loading the original evidence…</p>
+    <div class="tour-navigation"><button type="button" id="tourBack" disabled>Back</button><button type="button" id="tourNext" disabled>Next: inspect the conflict</button></div>
+    <p class="tour-fine">About one minute plus your decision. No upload or AI call. Reloading discards the example records.</p>
+    <a class="tour-exit" href="change-assurance.html">Try with your own change pack</a>`;
+  guide.hidden = false;
+  guide.insertBefore(guide.querySelector(".tour-navigation"), guide.querySelector(".tour-steps"));
+  const stage = document.createElement('section');
+  stage.className = 'tour-stage';
+  stage.setAttribute('aria-labelledby', 'tourTitle');
+  stage.innerHTML = `<div class="tour-stage-heading"><p id="tourPosition">Step 1 of 6</p><h2 id="tourTitle" tabindex="-1"></h2><p id="tourDescription"></p></div>
+    <div id="tourError" class="tour-error" role="alert" hidden><p></p><button type="button" id="tourRetry">Retry loading the example</button></div>
+    <section id="tourPack" aria-label="Parsed schedule comparison"><div class="tour-timeline">
+      <div class="tour-schedule"><span>Previous scheduled finish</span><strong id="tourPreviousDate">Loading…</strong><div class="tour-track"><div class="tour-bar previous"></div></div><code>northstar-previous.xer</code></div>
+      <div class="tour-schedule"><span>Current scheduled finish</span><strong id="tourCurrentDate">Loading…</strong><div class="tour-track"><div class="tour-bar current"></div></div><code>northstar-current.xer</code></div>
+      <p id="tourMovement"></p><p class="tour-fine">Finish-date comparison, not a critical-path calculation. Both bars share a date scale starting at the previous data date.</p></div>
+      <blockquote id="tourOriginalClaim"></blockquote><p id="tourInputDetails" class="tour-fine"></p></section>
+    <section id="tourExperiment" hidden><label for="tourNarrative">Narrative to check against these same two schedules</label><textarea id="tourNarrative" rows="7" spellcheck="false"></textarea>
+      <div class="tour-experiment-actions"><button type="button" id="tourRerun">Rerun checks</button><button type="button" id="tourAcknowledge">Try an acknowledged finish change</button><button type="button" id="tourOriginal">Restore original narrative</button></div>
+      <p id="tourCheckStatus" role="status"></p><p class="tour-fine">These are keyword checks. A smaller finding count does not establish that the narrative is correct.</p></section>
+    <section id="tourRecord" hidden><p id="tourRecordSummary"></p><button type="button" id="tourDownload">Download walkthrough record</button><p id="tourDownloadStatus" role="status"></p></section>
+    <p id="tourDecisionHint" class="tour-form-hint" hidden>Example only. The owner and rationale are editable. Choose your own outcome; nothing is saved outside this tab.</p>
+    <p id="tourComplete" class="tour-complete" role="status" hidden></p>`;
+  byId('workspace').prepend(stage);
+  const date = value => new Intl.DateTimeFormat('en-GB', { day: 'numeric', month: 'short', year: 'numeric', timeZone: 'UTC' }).format(new Date(value));
+  const currentDecision = snapshot => snapshot.decisions.find(record => record.inputIdentity === snapshot.review?.inputIdentity);
+  function stop(message) {
+    playing = false; clearTimeout(timer);
+    byId('tourPlay').textContent = 'Play walkthrough';
+    byId('tourPlay').setAttribute('aria-pressed', 'false');
+    if (message) byId('tourPlayback').textContent = message;
+  }
+  function schedule() {
+    clearTimeout(timer);
+    if (playing && step < 3 && !busy && !dirty) timer = setTimeout(() => go(step + 1, false), 10000);
+  }
+  function updateControls() {
+    const snapshot = engine.snapshot(), decision = currentDecision(snapshot);
+    const locked = busy || !loaded;
+    byId('tourBack').disabled = locked || step === 0 || (step === 2 && dirty);
+    byId('tourNext').disabled = locked || (step === 2 && dirty) || (step === 3 && !decision) || step === 5;
+    const openConditions = snapshot.conditions.some(condition => condition.decisionId === decision?.id && !condition.closed);
+    byId('tourNext').textContent = step === 5 ? (openConditions ? 'Follow-up still open' : 'Walkthrough complete') : `Next: ${steps[step + 1][0].toLowerCase()}`;
+    byId('tourPlay').disabled = locked || step >= 3 || reduced.matches || dirty;
+    guide.querySelectorAll('[data-tour-step]').forEach(button => {
+      const index = Number(button.dataset.tourStep);
+      button.disabled = locked || index > step || (step === 2 && dirty && index !== step);
+      if (index === step) button.setAttribute('aria-current', 'step'); else button.removeAttribute('aria-current');
+    });
+    ['tourRerun', 'tourAcknowledge', 'tourOriginal'].forEach(id => { byId(id).disabled = locked; });
+  }
+  function recordSummary() {
+    const snapshot = engine.snapshot(), decision = currentDecision(snapshot);
+    if (!decision) return;
+    const conditions = snapshot.conditions.filter(condition => condition.decisionId === decision.id);
+    byId('tourRecordSummary').textContent = `${decision.decision}. ${decision.unresolved} unresolved findings preserved. Source identity: ${decision.inputIdentity.slice(0, 12)}. ${conditions.length} condition${conditions.length === 1 ? '' : 's'} attached.`;
+    byId('tourDownloadStatus').textContent = downloaded ? 'Record downloaded. Continue to the follow-up register.' : 'Download is optional and starts only when you choose it.';
+    byId('tourComplete').hidden = step !== 5;
+    byId('tourComplete').textContent = conditions.length
+      ? conditions.every(condition => condition.closed) ? 'Condition closed. The original decision and evidence remain in the record. You have completed the review journey.' : 'Your decision is recorded. Close the example condition below to complete the follow-up.'
+      : 'You recorded a decision without conditions. There is no condition to close. You have completed the review journey.';
+  }
+  function go(index, focus = true) {
+    if (busy || !loaded || index < 0 || index > 5) return;
+    if (step === 2 && dirty && index !== 2) { stop('Rerun the edited narrative before continuing.'); return; }
+    if (index > 3 && !currentDecision(engine.snapshot())) return;
+    step = index;
+    document.body.dataset.tourStage = String(step);
+    byId('tourPosition').textContent = `Step ${step + 1} of 6 · ${steps[step][0]}`;
+    byId('tourTitle').textContent = steps[step][1];
+    byId('tourDescription').textContent = steps[step][2];
+    byId('tourPack').hidden = step !== 0;
+    byId('tourExperiment').hidden = step !== 2;
+    byId('tourDecisionHint').hidden = step !== 3;
+    byId('tourRecord').hidden = step < 4;
+    byId('decisionPanel').hidden = step !== 3;
+    byId('tourComplete').hidden = step !== 5;
+    // These are the application's views, not replicas of their content.
+    const view = step < 4 ? 'reviews' : step === 4 ? 'decisions' : 'follow-up';
+    location.hash = view;
+    document.querySelectorAll('[data-view]').forEach(element => { element.hidden = element.dataset.view !== view; });
+    if (step === 3) {
+      stop('Playback paused. Choose the human decision, then save the example record.');
+      if (!byId('decisionOwner').value) byId('decisionOwner').value = 'Example review chair';
+      if (!byId('decisionRationale').value) byId('decisionRationale').value = 'Example: preserve the unresolved findings and require the schedule basis to be confirmed.';
+    } else if (!playing) byId('tourPlayback').textContent = reduced.matches ? 'Reduced motion is on. Use Next to explore at your own pace.' : 'Use Next, or play the introduction. You control every decision and download.';
+    recordSummary(); updateControls(); schedule();
+    if (focus) {
+      byId('tourTitle').focus({ preventScroll: true });
+      stage.scrollIntoView({ block: 'start', behavior: 'instant' });
+    }
+  }
+  async function recheck(value) {
+    stop('Rechecking the narrative with the existing engine…');
+    busy = true; updateControls();
+    try {
+      await engine.recheck(value);
+      byId('tourNarrative').value = engine.snapshot().narrative;
+      dirty = false; downloaded = false;
+      const review = engine.snapshot().review;
+      byId('tourCheckStatus').textContent = `${originalCount} findings in the original pack; ${review.blockers.length} now. The scheduled finish still moved ${review.finishMovement} days. Check the findings below.`;
+      byId('tourError').hidden = true;
+      byId('tourPlayback').textContent = 'Checks rerun. Inspect the result or continue to the decision.';
+    } catch (error) { showError(error.message); }
+    finally { busy = false; updateControls(); }
+  }
+  function showError(message) {
+    stop('The example is paused. Your saved-work register has not changed.');
+    byId('tourError').hidden = false;
+    byId('tourError').querySelector('p').textContent = message;
+    byId('tourRetry').hidden = loaded;
+  }
+  async function load() {
+    busy = true; loaded = false; updateControls();
+    byId('tourError').hidden = true;
+    try {
+      await engine.load();
+      const snapshot = engine.snapshot(), review = snapshot.review;
+      original = snapshot.narrative; originalCount = review.blockers.length;
+      byId('tourPreviousDate').textContent = date(review.previous.project.scheduledFinish);
+      byId('tourCurrentDate').textContent = date(review.current.project.scheduledFinish);
+      const start = new Date(review.previous.project.dataDate).getTime();
+      const previous = new Date(review.previous.project.scheduledFinish).getTime() - start;
+      const current = new Date(review.current.project.scheduledFinish).getTime() - start;
+      document.querySelector('.tour-bar.previous').style.setProperty('--finish-scale', String(Math.max(0, previous) / Math.max(1, current, previous)));
+      document.querySelector('.tour-bar.current').style.setProperty('--finish-scale', String(Math.max(0, current) / Math.max(1, current, previous)));
+      byId('tourMovement').textContent = `${review.finishMovement} days later. ${review.blockers.length} findings from the current checks.`;
+      byId('tourOriginalClaim').textContent = original.split(/\n\s*\n/).find(part => /unchanged|on track/i.test(part)) || original;
+      byId('tourInputDetails').textContent = `Parsed ${review.previous.tasks.length} previous and ${review.current.tasks.length} current activities. Nothing was uploaded.`;
+      byId('tourNarrative').value = original;
+      loaded = true;
+    } catch (error) { showError(error.message); }
+    finally { busy = false; if (loaded) { go(0, false); window.scrollTo({ top: 0, behavior: 'instant' }); } else updateControls(); }
+  }
+  byId('tourPlay').addEventListener('click', () => {
+    if (playing) { stop('Playback paused. Continue at your pace.'); return; }
+    playing = true;
+    byId('tourPlay').textContent = 'Pause walkthrough'; byId('tourPlay').setAttribute('aria-pressed', 'true');
+    byId('tourPlayback').textContent = 'Playing the introduction. Each step stays visible for ten seconds; the decision always pauses playback.';
+    schedule();
+  });
+  byId('tourNext').addEventListener('click', () => { stop(); go(step + 1); });
+  byId('tourBack').addEventListener('click', () => { stop(); go(step - 1); });
+  guide.querySelectorAll('[data-tour-step]').forEach(button => button.addEventListener('click', () => { stop(); go(Number(button.dataset.tourStep)); }));
+  byId('tourRestart').addEventListener('click', () => location.reload());
+  byId('tourRetry').addEventListener('click', load);
+  byId('tourNarrative').addEventListener('input', () => { dirty = true; stop('Narrative changed. Rerun the checks before continuing.'); updateControls(); });
+  byId('tourNarrative').addEventListener('focus', () => stop('Playback paused while you edit.'));
+  byId('tourRerun').addEventListener('click', () => recheck(byId('tourNarrative').value));
+  byId('tourOriginal').addEventListener('click', () => recheck(original));
+  byId('tourAcknowledge').addEventListener('click', () => {
+    const review = engine.snapshot().review;
+    recheck(`The scheduled finish moves from ${date(review.previous.project.scheduledFinish)} to ${date(review.current.project.scheduledFinish)}, ${review.finishMovement} days later.\n\nGovernance action is under review.`);
+  });
+  document.addEventListener('projectlens:decision-saved', () => { stop(); downloaded = false; go(4); });
+  document.addEventListener('projectlens:condition-changed', () => { recordSummary(); updateControls(); });
+  document.addEventListener('visibilitychange', () => { if (document.hidden) stop('Playback paused while this tab is hidden.'); });
+  reduced.addEventListener('change', () => { if (reduced.matches) stop('Reduced motion is on. Use Next to explore.'); updateControls(); });
+  document.querySelectorAll('[data-view-link]').forEach(link => link.addEventListener('click', event => {
+    event.preventDefault(); stop();
+    go(link.dataset.viewLink === 'reviews' ? 1 : link.dataset.viewLink === 'decisions' ? 4 : 5);
+  }));
+  document.querySelectorAll('#blockerList, #decisionForm, #findingEvidence').forEach(element => ['pointerdown', 'focusin'].forEach(event => element.addEventListener(event, () => stop('Playback paused while you explore the application.'))));
+  byId('tourDownload').addEventListener('click', () => {
+    const snapshot = engine.snapshot(), decision = currentDecision(snapshot);
+    if (!decision) return;
+    const record = { schemaVersion: 1, demonstration: true, storage: 'memory-only', decisions: [decision], conditions: snapshot.conditions.filter(condition => condition.decisionId === decision.id) };
+    const url = URL.createObjectURL(new Blob([JSON.stringify(record, null, 2)], { type: 'application/json' }));
+    const link = document.createElement('a'); link.href = url; link.download = 'projectlens-walkthrough-record.json'; link.click();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+    downloaded = true; recordSummary();
+  });
+  document.title = 'ProjectLens | Guided change-review walkthrough';
+  go(0, false);
+  load();
+})();
diff --git a/scripts/run_browser_tests.py b/scripts/run_browser_tests.py
index 803471a..d623a42 100644
--- a/scripts/run_browser_tests.py
+++ b/scripts/run_browser_tests.py
@@ -14,6 +14,7 @@
     "browser_smoke.py",
     "browser_board_readiness.py",
     "browser_change_assurance.py",
+    "browser_walkthrough.py",
     "browser_xer_review.py",
     "browser_parser_compatibility.py",
 )