🧭 Tandem showcase guide

Purpose

This is the durable handoff for guided tours. QuizWizz remains the live showcase and evidence source, but the product under study is now the tandem interaction itself: browser control, visual grounding, pacing, narration, feedback capture, recovery, and scale across a long tour.

Locked owner direction

• Use the owner’s already-visible, user-created Ego Lite task space as the sole working surface during a showcase.
• Do not open Brave, Chrome, an isolated or headless browser, or a duplicate tab.
• Do not use terminal commands, bench queries, source inspection, wiki editing, or background implementation while the tour is active.
• One stop is one complete visible interaction loop. Never chain ahead behind narration.
• The visible Ego Lite surface—not source code, a database result, or an isolated DOM—is authoritative for “you can see.”
• Record feedback silently and durably. Do not make the owner search for precise UX terminology; preserve their wording, then translate it into a crisp issue, idea, decision, or task without changing the intent.
• The owner may stop, redirect, or say next at any time. A stop is a stop, not permission to finish a hidden sequence.

Control is the punctuation, not the overhead

Measured on 2026-08-18. The visible task space is strictly turn-based: exactly one side holds control, and only the holder can act. While control is delegated to the owner the agent is fully blind — it can still list task spaces and read the ownership state, but every page operation fails with Task space not selected. It cannot read the URL, the DOM, or the scroll position.

The reverse is just as absolute and was violated once: while the agent holds control the owner has visual feedback only and zero input — no scrolling, no clicking, no typing. Any sentence of the form “you can scroll to…” is false unless control has actually been handed over and the handoff returned done.

Retracted claim

The owner was told he could scroll a long mockup while the agent held the claim. He could not. Visibility was inferred from hit-testing at the viewport centre and stated as fact. Rule: never describe what the owner can do on a surface the agent is holding.

Because the two sides can never observe simultaneously, handing control back and forth is not friction to be minimised — it is the beat that separates one stop from the next.

Action	Cost measured	When
Hand control to the owner	~0.5 s, one call	End of every stop that invites reaction
Owner confirms, agent resumes	~0.5 s, one call	Only after an explicit “continue”
Full round trip per stop	~1 s	Negligible beside settle-and-read time

A round trip costs about a second, which is far less than the time the owner spends looking at the screen. So the default is: yield control at every stop, not only when a login or captcha forces it.

Turn-taking rules

• End a stop by handing control over, then say in one sentence what is now possible and what to say to continue.
• Resuming depends on why the other side holds control, and the two cases are opposite. This is the working browser, and a space sitting idle is not a reason to stall.
  • Reclaim without asking when the space is idle, unassigned, left over from a previous session, or was handed back only so a file could be opened — in short, whenever nobody is actively driving. Stalling here is the failure; the owner’s standing direction is that Ego Lite is the agent’s browser to claim.
  • Never seize while the owner is actively driving: after a handoff that invited them to interact, after they took over through the GUI mid-flow, or when they have asked to look around. Then wait for an explicit continue, because the take-over primitive performs no ownership check and would snatch the browser away mid-gesture.
  • When it is genuinely unclear, one short question costs less than either mistake.
• A “user is controlling” error raised while the owner is mid-interaction is a hard stop, never an obstacle to route around; it usually means the current approach is going wrong. The same error on an idle or unassigned space is not a stop — reclaim and carry on.
• Before handing over, restore the page: undo every temporary inspection hack — injected outlines, hidden siblings, zoom changes, hoisted panels — and return to normal zoom at a sensible scroll position. The owner must receive the real artifact, not a debugging state.
• Blindness during the owner’s turn is expected. Do not poll, guess, or narrate what is on screen; ask what they saw.
• An agent-initiated wait may block for the owner’s return inside the same round, but it must never take control.

Tab hygiene

Superseded artifacts must be closed as they are replaced, not left to pile up. Four tabs accumulated during one session — two abandoned diagram drafts, the living mockup, and the live settings screen — because each new artifact was opened with a reuse-or-open call while nothing was ever closed. Keep only the tabs worth showing: the current artifact and, where useful, the live screen it is compared against.

Highlighting

The browser layer provides an action-labelled highlight animation on click, hover and drag. Prefer it over hand-injected CSS outlines: it is visible, reversible, and it does not mutate the product’s own markup.

Known capture limitation

Screenshots of a page scrolled past the top return an identical blank frame; this was reproduced on an untouched live page, so it is a capture limitation rather than a page defect. Scrolling itself works. Inspect below-fold content by hoisting the target or hiding its siblings — then restore before handing over. The capture helper returns a file path, and it rejects an options object, so there is no full-page variant to fall back on.

The one-stop loop

Step	Required behaviour	Proof before continuing
1. Name	State one intended browser action in one short sentence.	The action is singular and visible.
2. Act	Perform one click, navigation, scroll, or field interaction in Ego Lite.	No second interaction is chained.
3. Settle	Wait deliberately for loading, animation, and visual orientation.	The destination has stopped changing.
4. Verify	Check the resulting URL or title and one named visible element.	The intended destination is actually on screen.
5. Highlight	Put a visible outline, tint, badge, or pointer on the exact focus.	The owner does not need to guess which element is being discussed.
6. Explain	Describe only what is currently visible in two or three short prose sentences.	No below-fold, unopened, or source-derived claims.
7. Yield	Stop completely for inspection, correction, feedback, or next.	No work continues behind narration.

Narration is part of the interaction

Anything that must be heard belongs in short prose. Tables and code blocks are not reliable narration. During the tour, narration must use a playback path that survives continued model activity; otherwise the next tool action can cut speech off mid-sentence and destroy the shared rhythm.

What failed, and what it teaches

Failure observed	Why it broke the tandem	Required correction
An isolated browser was narrated as though it were on the owner’s desktop.	The agent and owner were not looking at the same surface.	Adopt the existing user-owned Ego Lite task space before making any visual claim.
Brave was opened after the owner explicitly requested Ego Lite.	The chosen tool contradicted the interaction contract.	Treat “Ego Lite only” as a hard surface boundary.
Terminal-mediated browser work continued during the showcase.	It was invisible, cognitively out of sync, and impossible for the owner to supervise.	Keep all non-browser work outside the active tour.
Several actions ran while narration was playing.	By the time the explanation finished, the screen or agent state had moved on.	One action, deliberate wait, verification, explanation, then full yield.
Database or source truth was substituted for visible truth.	Stored state cannot prove what the owner can presently see.	Verify the actual visible page and highlight the named element.
A long final summary replaced interactive stops.	It produced information, not a guided experience.	Keep summaries secondary; the tour itself must carry the explanation.
Native speech stopped when model work continued.	The owner heard fragments while the agent silently advanced.	Use durable narration and never work behind it.
Deep-link navigation changed the URL without bringing the target panel on screen.	URL state and visual state diverged.	Verify viewport presence; scroll visibly when needed; report the mismatch as a defect.

Demonstrated working pattern

The shared loop was proven on the live QuizWizz question editor:

1. The existing user-created Ego Lite task space was selected.
2. The active question-editor tab was reused rather than duplicated.
3. The page was visibly scrolled until the answer choice Sitar entered the viewport.
4. Sitar was visibly highlighted.
5. The URL/title and highlighted text were verified before explanation.
6. The next stop highlighted the Explanation field and yielded.

A later settings stop exposed a real interaction defect: the #qw-advanced deep link updated the URL but initially left Advanced outside the viewport. One visible wheel-scroll brought the panel onscreen. This is both a QuizWizz navigation issue and a useful test case for the tandem verifier: URL equality alone is never enough.

Evidence captured

Artifact	Measurement	Meaning
Live walk entries	86	Durable event stream for the tour
Decisions	8	Owner direction that should not be silently overwritten
Issues	26	Observed defects or interaction failures
Ideas	10	Candidate improvements, not yet commitments
Todos	2	Explicit follow-up work
Navigation events	12	Movement across the visible product
Context notes	28	Explanations and observations needed for later interpretation
Highlighted captures	52	Visual evidence tied to individual stops

The complete local walk artifact remains the high-detail evidence record. This public page intentionally excludes workstation paths, credentials, internal host details, and secret-adjacent operational specifics.

Feedback capture contract

• Capture the owner’s spoken or typed feedback without interrogation. Accidental speech-to-text fragments, ambient conversation, and unrelated utterances are not product feedback and must not be promoted into decisions, tasks, or wiki content.
• Preserve ambiguity verbatim when intent is not yet locked.
• Translate vague reactions such as “cluttered,” “unintuitive,” “too much text,” or “duplicates” into measured defects only after inspecting the live page.
• Attach each note to the current URL and a durable visible target: role, name, text, selector, or bounding box—not an ephemeral accessibility-tree reference.
• Store corrections and retractions as new events. Never rewrite history to make the agent look consistent.
• When a decision is locked, future conflicting feedback must be surfaced as a conflict rather than silently replacing it.
• Regenerate the human-readable report from the append-only event log; the event log remains authoritative.

Scale requirements for a long tandem tour

Browser control

• Reliable adoption of the existing user-owned task space.
• Stable tab identity across navigation and rerenders.
• Viewport-aware verification, not URL-only verification.
• Highlight primitives that are visible, reversible, and do not mutate product state.
• Recovery after stale references, closed tabs, login expiry, dialogs, and unexpected navigation.
• An explicit visible indicator that the agent currently has control.

Interaction rhythm

• A stop-state machine: name → act → settle → verify → highlight → explain → yield.
• Hard prevention of a second action before yield.
• User interruption must cancel queued narration and browser actions immediately.
• Narration completion must be observable; silence cannot be interpreted as success.
• Compact prose by default: one screen, one idea, two or three sentences.

Evidence and memory

• Append-only notes with type, timestamp, URL, durable target, and optional capture.
• Locked decisions and explicit retractions.
• Checkpoint/resume that restores the last verified visible state, not merely the last URL.
• Automatic reconciliation between event log, generated report, wiki tasks, and completed log.
• Deduplication that links repeated observations without erasing repetition as evidence of friction.

Safety and privacy

• A tour-start declaration of the sole visible surface and forbidden background tools.
• No secret, credential, operator path, or private infrastructure detail in published artifacts.
• No hidden form submission, destructive action, or external publish without a visibly explained stop.
• Separate local evidence from public synthesis.

QuizWizz showcase route

QuizWizz remains the live proving ground because it contains dense navigation, long settings, forms, filtered lists, editors, player flows, and print output. The tour should continue from the currently verified Advanced settings panel and use product defects to test tandem capabilities rather than allowing product implementation to take over the session.

Recommended route:

1. Finish the Advanced panel one visible control at a time.
2. Revisit the settings deep-link/viewport mismatch and document the exact user-visible failure.
3. Exercise search and progressive disclosure without letting the page become a 201-control lecture.
4. Walk the filtered Questions and Subjects states, including an escape route from empty results.
5. Open one quiz, explain its draft/visibility state, then run the player end to end.
6. Open print/PDF as a distinct visible job.
7. End on the dashboard and show how the completed journey changes—or fails to change—the stats.

The product direction remains: a clean dashboard as the front door; only common/default settings visible; the long tail in labelled accordions or focused panes; icon plus short label with hover, focus, and touch-accessible detail; and no hover-only meaning.

Next-agent handoff

Primary mission

Improve and prove the Ego Lite tandem guide system. QuizWizz is the showcase, not the main implementation target during the tour.

Start by adopting the already-visible user-owned Ego Lite task space and verifying the current settings page. Continue at Advanced only if the panel is visibly onscreen; otherwise perform one visible scroll, verify, highlight, explain, and yield. Do not inspect source or fix QuizWizz while showcase mode is active.

For every new stop, answer these questions through visible behaviour:

1. Did the owner see the exact action?
2. Did the agent wait long enough to remain synchronized?
3. Was the destination verified in the viewport?
4. Was the focus unmistakably highlighted?
5. Was the explanation short, audible, and limited to the visible screen?
6. Did the system stop cleanly for the owner?
7. Was the resulting feedback captured without interrupting the flow?

When the tour ends explicitly, distil surviving findings into the open work ledger, record finished work with its evidence — the historical completed rows live in the task log completed record — and update Now only if current project state changed.

Acceptance criteria

The tandem guide is working when a ten-stop showcase can be completed with:

• ten singular visible actions and ten explicit yields;
• no browser or tool outside the adopted Ego Lite task space;
• no unverified “you can see” statement;
• every focus visibly highlighted;
• no narration cut off by continued work;
• interruption cancelling all queued activity;
• every owner comment durably captured and traceable to its visible context;
• a checkpoint that resumes at the last verified element;
• a public summary containing no private workstation or infrastructure detail.