Operations Wizard

Trials and pilots will run with little or no onboarding team. Peterson put it as "That makes the wizard all the more important, because we won't have the sort of white glove… guidance". The product has to carry the onboarding itself.

The session described a journey that takes weeks: people and endpoints, deploy, visibility, a recommended baseline at Observe, frameworks, a pilot through an exception, then expand. A checklist alone can't explain why each step comes next, or what the thing on screen means once you get there. Mark's answer is to make the UI explain itself.

• Hover anything in help mode to learn what it is and how to use it.
• Drop numbered markers on a screen to walk someone through it.
• Step through a task across pages, with the relevant part of the screen highlighted.
• Let an AI harness give the tour: "fire up our dashboard and your favorite harness".

Written once, the same explanations serve every mode, the docs and the agent.

Done looks like this, on the design site first:

1. One annotation model and one attach protocol. Any element can carry a help id. Each id has a title, a body, optional "how to use", a docs link and related ids. The internals stay free, but the protocol is small enough that attaching help never touches the component's own props (modularity = purpose + protocol).
2. Help mode. A toggle and a fixed help panel, as in Ableton's Info View. Hovering an annotated element fills the panel. Nothing pops over the content you're trying to read.
3. Marker overlay. Brightly coloured numbered circles with a white outline and a subtle drop shadow, pinned to parts of the screen, with a legend that explains each one. Usable live and in captures, so a screenshot can explain itself too.
4. The linear wizard, brought forward. app.qpoint.io's WizardSteps + Sequin kit is replicated first, then optimized (the layer's rule for extraction), and becomes the step container that tours and in-page tasks share. A task like "track a framework" or "stage the recommended baseline" is a short linear wizard. A tour is a wizard whose steps can live on different pages.
5. Tours. Ordered steps that navigate between pages, highlight a target, show text and wait for a condition ("first signal arrived") when a step needs one. Progress comes from real state rather than ticked boxes, and it survives leaving and coming back.
6. The operations journey as the first tour. J1–J7 from the brief, with Observe before Enforce as the easy path, not a lock. It runs on the lab's fixture worlds (c113 first-run@*, c121 adoption → established).
7. An AI tour guide over MCP. An MCP server any harness can connect to. It lists tours, reads a page's annotations, starts a tour, moves to a step, highlights a target and explains it. The dashboard on screen follows along. It is demoed end to end with Claude Code against the design site.
8. Every mode demoed on one lab page (likely /pages/phase4/mock/policies) with empty, minimal, typical, overflow and error cases, before anything is extracted to the layer or ported to qdash.

In:

• replicating app.qpoint.io's wizard kit (WizardSteps, EduHarness, PingListener, FinalStep, Sequin) on the design site as the starting point for linear tasks and tour steps; its layer extraction comes after the demo holds;
• a prior-art survey: Ableton Info View; product-tour libraries (Shepherd, Driver.js, Intro.js) and adoption tools (Pendo, Appcues); annotation and redline tools; c30 /tour; the qdash and app.qpoint.io checklists; c121 07; c81's adoptionSteps;
• the annotation registry and its content, written in the same voice as phase4/governance-model.vue, which is the doc each journey step links to;
• the attach protocol (a directive, a data attribute or a wrapper, decided in Phase 1);
• help mode, the marker overlay and the tour runner on the design site, composed from the layer's UxPopover, UxHelpText, UxHoverBox and UxStickyBand before anything new is made;
• the tour MCP server and the page channel it drives;
• the operations-journey tour content (J1–J7) and its progress model.

Out:

• the qdash port and layer extraction. They follow once the demo holds and get their own cycle or thread.
• the tray-only (self-install, no central UI) journey beyond a pointer. Brief open question 5.
• Peterson's journey/wizard intent. We draw against it when it lands, not ahead of it. Until then the brief's J1–J7 is the working order.
• frameworks and policy page content. c123 and c126 own those pages; this cycle only annotates them.

Rough phases:

• 0. Kick-off. Before captures of the pages the first tour touches, and the prior-art survey.
• 1. The model. The annotation model, the attach protocol and the registry. The app.qpoint.io wizard kit is replicated on the design site.
• 2. The three on-screen modes, built on one lab page.
• 3. The operations tour. J1–J7 across lab pages and fixture worlds.
• 4. The MCP tour guide, driving the same page.
• 5. Review, then plan the extraction and port.

• kick-off (2026-10-27): Stage 1 and Stage 2 written together from Mark's direction and the market-analyst brief, alongside c123 (frameworks) and c126 (policies). Nothing built yet.
• prior art located (2026-10-27): Mark named app.qpoint.io's simple linear wizard as the prior art and thought it might be in q-nuxt-layer. It isn't: the kit is still app-local in app.qpoint.io/app/components/wizard/ with utils/sequin.js, unchanged since c23 classed it app-local. Objective 4 and Phase 1 now replicate it first.
• before captures (2026-10-27): thread c125-before: c125-before-home-adoption, -endpoints-adoption, -policies-adoption and -governance-model in public/cycles/design/. Program scripts/shot-programs/c125-before.json. They show the lab in adoption with no help, markers or tour: the pages the journey would start on. The app.qpoint.io wizard kit isn't shot yet, because its dev server isn't running and the project is stale.
• rulings (2026-10-27): Mark answered two kick-off questions. (1) The MCP tour guide drives the design-site lab first; qdash comes after. That settles Phase 4's target, though the transport question (open question 1) stays open. (2) The app.qpoint.io wizard kit is documented first (its own dev server, captures, a prior-art note), then copied onto the design site.
• wizard kit, documented then copied (2026-10-27): app.qpoint.io ran on :3301, since its content watcher holds :3300. Thread c125-wizard-kit shot the A–D demo in tab mode, the only /dev/wizards page that still resolves. prior-art-wizard-kit.md records the anatomy (Sequin, per-step overrides, the form, listener and end modes), the seven flows it shipped in, what it hands c125, and what was found while copying. The kit is replicated verbatim except for named changes in app/components/replicas/wizard/ (ReplicasWizard*, plus the app-local LinkBack) and app/utils/sequin.js. It's demoed at /pages/phase4/wizard-kit (tab, centred and linear modes, the listener → end install shape, the pieces alone), and thread c125-wizard-replica holds five shots of it working.
• the richer radar (2026-10-27): Mark's old branch was app.qpoint.io origin/mask-image (d82388d and 0bfe673, 2024-06-05, never merged). The twelve radar assets are lifted into app/assets/images/wizard/mask-image/. Its Radar.vue is now ReplicasWizardRadar, a black disc with line and sweep layers turning at 12 s and 6 s, and it's grafted into the replica PingListener as the branch had it. See prior-art-wizard-kit.md § The richer radar. Checked on :3000: both layers load and turn, and the console shows no errors.
• radar sizes (2026-10-27): ReplicasWizardRadar takes size (px, default 38, as on the branch), and both layers fill the disc. The wizard-kit page's pieces section shows it at 38, 96, 160 and 280 px. The SVG layers stay crisp at 280.
• radar line colour (2026-10-27): ReplicasWizardRadar takes lineColor (white, leaf, grape, grape-400 (added on request) or grey-500; default white, as on the branch). The two SVG layers are now inlined via ?raw, with #fff → currentColor and their cls-* classes prefixed per layer, because inline SVG <style> is document-global and the two files' classes collide. The grey rings (#545454) stay grey. There's a select for it on the wizard-kit radar card. On leaf and grape, a hairline seam sometimes shows at the sweep's edge. It's in the branch artwork, and white hides it.
• the tour layer, prototyped from c123 (2026-10-27): c123's addressable OWASP® tour needed a tour runtime before this cycle's Phase 1, so a working prototype is in the lab. Pages carry data-qp-id (and an optional data-qp-key for rows) and nothing else. <TourHost /> is mounted once in a layout. The panel floats in its own dark-grape material, the ring and callouts follow targets by ID, and Examples float real components with example props over their live counterparts. Drills send a simulated violation through the alert path and are kept in the delivery log, never in findings. Content is data, and an adapter is the one seam to the app. tour-layer.md has the protocol, the materials, the drill rules and six work packages (W1–W6), each with where to pick it up and what done looks like. It answers Objective 1's attach protocol in favour of a data attribute; Phase 1 should confirm that or replace it.
• mcp-guide, written up (2026-10-29): thread mcp-guide (prompt, plan), raised from c123's session: tours a person's own agent can drive over MCP. The plan proposes an answer to OQ1, with three rules: actions stay with the person, the person's clicks win, and no dashboard changes. Its test ladder runs on the design site before anything reaches qdash: a demo page, a Playwright walk of every step, an MCP contract script, error and safety cases, Claude Code end to end, then the same script against qdash. Added as W7 in tour-layer.md. Nothing built: the panel-iterations thread (tour-panel-iterations-prompt.md) is in the tour files the same day, so the build waits for them to be quiet.
• mcp-guide, built (2026-10-29): the same day, once the tour files had been quiet for about 12 minutes. window.qpTour (useTourApi), <TourAgent /> beside <TourHost />, a dev-only relay (server/api/tour/*, server/utils/tourRelay.ts) and the MCP endpoint /api/tour/mcp, with 11 tools and no verb for a step's action. TourHost and useTour are unchanged; the panel-iterations thread had them open. The demo page is /pages/phase4/tour-mcp. scripts/tour-drive-check.mjs passes 62 checks across rungs 1–4. In rung 5, Claude Code walked stop 2 on the embedded lab and left Stage and Simulate violation to the person (transcript). The plan's § Built lists what's left: a recorded capture, a second harness, the no-tab case, and nuxt generate with the new SDK dependency. Committed in f351ccdf7c.
• mcp-guide, the unscripted guide written up (2026-10-29): Mark asked whether an agent could answer "Where do I go to add a Slack integration?" with no tour, using the callout. It can. The plan's § The unscripted guide adds three tools: find-in-app (searches an app map on the server), open-page (any page) and point (a ring plus a TourCallout with one sentence). It also adds IDs on the rail and the Connect button. The app map is Objective 1's annotation registry, started from the agent's side. One rule changes: point puts a short label on screen, and the explanation stays in chat. The plan has rungs U0–U4, and U4 asks the exact question in Claude Code. Not built.
• mcp-guide, the unscripted guide built (2026-10-29): app/data/app-map.ts, which covers 29 pages and 66 regions and is checked against the pages by U1. Four tools: find-in-app, read-page, open-page (rings the rail, then goes) and point (a ring and v4's callout). Rail IDs, plus Connect and connector IDs. scripts/tour-guide-ask.mjs asks a real harness any question. 166 checks pass. In Claude Code, three questions asked exactly as written each found the page, rang the way and read the region before answering; none pressed anything. For Slack it said "already connected; config changes it" (answers and captures). The map followed c123's port of qdash's pages, which landed mid-build. Committed in f351ccdf7c.
• lab knob ?draft=empty (2026-10-29): Mark asked to clear the seed's proposed changes from every page (and noted that demo mode, Shift+D, already hides the tray and the theme editor). useGovernanceMock gains ?draft=empty: the stage's world with no lines in the shared draft and no saves in the log that made them. ?draft=seeded brings the twelve back. It's kept in lab links like ?stage, and it's sticky: a link without it leaves the draft as it is. The query is now watched, so a page that doesn't call useGovernanceMock itself still reseeds on a stage or draft change. Committed in f351ccdf7c.
• tour runtime, from c123's tours (2026-10-29): c123's five tours (c123 CYCLE.md § tours) added to TourHost and the v5 panel, with the panel thread's go-ahead. Follow the page: the person's own click onto the next step's page advances the tour. Clickable stop markers. Spots: buttons in the panel, each ringing one area. A safe area that stacks pinned chrome. The glide is ease-in-out quint. A step's short names it on the Next button, in place of its beat. Committed with this cycle's panel and mcp-guide work on 2026-10-29.
• mcp-guide knows the dashboard (2026-10-29): guide-knowledge.ts makes the policy catalog (19 policies) and the frameworks (5, with 44 requirements) searchable in a customer's words, through rows on policies.row and compliance.framework. It adds a hand-written word list per policy, 17 concepts, and an explain tool. open-page takes { policyId }. New IDs on the Control Center's rows and eight on the policy page's sections. The server is renamed qpoint-guide. 189 checks pass. In Claude Code, SSH keys went to the P-FILES row, and DeepSeek went to P-PROVIDERS' Mode with its live state.
• focus only what's specific (2026-10-29): Mark: "I don't know that we gain anything by highlighting the whole page." A cloud session's b3ebf9106f: a step rings the one region that answers its question, and Dim and Fade fall back to the ring past about half the viewport (effectiveFocus in TourHost). It was written against an older Host.vue and reapplied by hand in f351ccdf7c. Rule in tour-layer.md.
• mcp-guide, committed and deployed (2026-10-29): the c123 tours session's commit needed these files to build, so Mark approved including them: f351ccdf7c on c123/owasp-agentic-tour, pushed and deployed. nuxt generate passed with the MCP SDK and needed no prerender exclusions. The live _deploy.json showed f351ccdf with 0 uncommitted. The guide only drives a page on the dev server; deployed, the relay isn't there.
• in-app chat, split off (2026-10-29): Mark asked how a chat window in the web app would work, then asked for a new cycle with initial thoughts and no plan: c127 Guide Chat.

1. How does a harness drive the page on screen? MCP tools on one side and the browser on the other: a local channel (SSE or WebSocket) from the MCP server to the open dashboard, the dashboard hosting the MCP endpoint itself, or the harness driving a browser it controls. This decides the architecture, so Phase 4 starts with a spike. Proposed 2026-10-29 (mcp-guide-plan.md): both, in order. First a page API (window.qpTour), which any agent with a browser can drive. Then the dashboard hosts the MCP endpoint and relays to the open tab over SSE. Not yet ruled.
2. Where does the journey live? A persistent progress element in the shell, a Home panel, its own page, inline nudges, or a mix (brief OQ2).
3. Is "recommended baseline" the same artifact as Rob's minimum built-in set and the "standard" starter config? This is shared with c126 O2/O7.
4. What counts as done for each stage? This matters most for J6 → J7, which is problem:safe-to-enforce (brief OQ4).
5. How big is the beta version? A checklist plus annotated pages may be enough for the pilot (brief OQ1).
6. Do markers belong in the capture system too, so /capture can shoot an annotated screen for docs and briefs?