demo-platform/docs/USER-GUIDE.md

Demo Platform — User Guide

For end users of a deployed instance. Your administrator gives you two things: the platform URL (e.g. https://demo.yourcompany.com) and an API key.

---

1. What this is

One capture of your product becomes three things:

1. An interactive demo — a clickable walkthrough prospects drive themselves, embedded on your site or sent as a link
2. A step-by-step guide — a shareable page/markdown doc with screenshots
3. A narrated video — an MP4 rendered from the same steps

Everything runs on your company's own infrastructure. Viewer data never leaves it.

2. Your API key and what it can do

Keys carry scopes:

Scope	Lets you (or your AI agent)
read	View demos, analytics, leads
author	Create and edit demos — steps, tooltips, hotspots, guides, videos
publish	Make demos publicly viewable
admin	Manage keys and delete lead data

Most people get read,author. Publishing is a deliberately separate permission — drafts are the default state of the world, and a human (or a key a human explicitly trusted) flips things live.

3. Your first demo in ten minutes

Install the capture extension (ask your admin for the extension/ folder): Chrome → chrome://extensions → Developer mode → Load unpacked → select the folder. Click the extension icon, enter the platform URL and your API key.

Record: open your product, pick a capture mode (see §4), click Start recording this tab, then simply click through the flow you want to show — each click becomes a step, with the click position remembered. Click the extension → Finish & upload.

Refine: open https://<platform>/editor, paste your key once, open the new demo. For each step: drag a box over the thing the viewer should click, write a tooltip title and one or two sentences, Save. Reorder with the arrows. Delete noise steps.

Publish & share: hit Publish (needs the publish scope — otherwise ask someone who has it, or have your agent request it and a human approve). You get a share link /p/<token>. Copy embed code gives you an iframe for your site.

4. The two capture modes

Screenshot mode — takes a picture at every click. Works on anything you can see in the tab. Pixels are frozen: editing means re-capturing. Use it for: quick demos, anything visually complex (canvas charts, maps, video).

DOM mode — captures the actual page structure at every click, with your styles and images inlined. Stays crisp at any size, and the platform can re-render it for guides and video. Text in DOM snapshots is real text. Use it for: standard web app UIs. Caveats: exotic CSS, canvas/WebGL content, and some web fonts may not survive perfectly — check the result and fall back to screenshot mode for those flows.

Hiding sensitive data: anything your developers tag with data-dp-mask in the app is automatically masked (•••••) in DOM captures. Password fields are always masked. Do a pass over your capture before publishing regardless — you are the last line of defence.

5. Editor reference

• Hotspot — drag on the snapshot; this is what the viewer clicks to advance
• Tooltip — title + body shown beside the hotspot. Short beats long
• Lead gate — tick the box on a step and viewers must leave name + email before advancing past it. Put it after you've shown value, not on step 1
• Reorder / delete — arrows and × in the step list
• Step guide — auto-generated from your steps at /p/<token>/guide
• Export video — renders an MP4 slideshow of all steps; add narration via your agent (§7, "Narrated video")
• Embed — Copy embed code → paste the iframe anywhere on your site

Sharing with identity: append ?v=<anything> to a share link you send to a specific person (e.g. /p/abc123?v=acme-corp). Their journey shows up in analytics under that token. No token, no identification — the platform stores no IP addresses and does no fingerprinting.

6. Connecting your AI agent

The platform ships an MCP server — it never runs a model itself; you attach whichever AI you already use, and it operates the platform with exactly the permissions of the key you give it.

Endpoint: POST https://<platform>/mcp (Streamable HTTP) Auth: Authorization: Bearer <your-api-key> header

Claude Code:

claude mcp add --transport http demos https://<platform>/mcp \
  --header "Authorization: Bearer dp_yourkey"

Other MCP hosts: any host supporting Streamable HTTP remote servers with a custom auth header works the same way.

What your agent sees depends on the key's scopes. With read,author it can inspect demos and analytics, write and revise every tooltip, place hotspots, reorder, wire branching, set chapters, configure lead gates, export guides and render videos — but it cannot publish. Give it a publish-scoped key only if you genuinely want it shipping things without you.

A note on trust: lead submissions are strangers' free text. The platform wraps them in explicit untrusted-data markers so your agent treats them as data, never as instructions — but as a habit, use a read-only key for any agent whose job is just reading analytics.

7. Prompt cookbook

Copy, adapt, and send these to your connected agent. Reference demos by name — the agent can list them.

Sales walkthrough (prospect-facing):

Look at the demo "Q3 Platform Tour". Rewrite every tooltip so the demo tells a story for a CFO evaluating us: each step should state the benefit first, the action second, max 2 sentences. Keep step 1's tooltip as a hook that promises what they'll see by the end.

Onboarding / training:

Turn the demo "Invoice Approval Flow" into training material: write instructional tooltips in second person imperative ("Click…", "Enter…"), then export the step guide as markdown so I can drop it into our wiki.

Feature announcement:

The demo "New Reporting" shows our new dashboards. Write tooltips aimed at existing customers who know the old version — every step should contrast what's new with what changed. Then add a chapter menu: "What's new", "Deep dive", "Getting started".

Personalized prospect demo:

Duplicate isn't available yet, so: take demo "Generic Tour" and rewrite all tooltips to speak directly to Acme Corp (logistics company, 400 trucks, pain point is manual dispatch). Mention their industry where natural. Give me the personalized share link format with viewer token acme-corp.

Branching demo (choose-your-own path):

On demo "Full Product Tour": add branch hotspots on step 1 — one labeled "For finance teams" jumping to the reporting steps, one labeled "For ops teams" jumping to the workflow steps. Tell me which steps you chose as targets and why.

Lead-gated content:

On demo "ROI Calculator Walkthrough", enable a lead gate after the step where the results first appear — fields: name, work email, company. Explain where you placed it and the drop-off risk.

Analytics-driven iteration:

Pull the analytics for "Homepage Demo". Where do viewers drop off? Propose rewritten tooltips for the two steps before the biggest drop, apply them, and tell me what you changed so I can compare next week's numbers.

Narrated video:

Export the guide for "Platform Tour" and write a 90-second narration script from it — conversational, one short paragraph per step, no jargon. I'll record it and upload the audio; then render the video with 4 seconds per step and my narration attached.

Guide repurposing:

Export the step guide for "Setup Flow" as markdown and rewrite it as a help center article with an intro paragraph, prerequisites list, and a troubleshooting section for the three most likely mistakes.

8. Analytics, leads & privacy

Per-step view/advance/back/complete counts; lead form submissions; identified viewers only when a share link carried a ?v= token. No IPs are stored — the schema has no column for them. No cookies, no fingerprinting. Leads can be deleted permanently by an admin (DELETE /api/leads/<id>), which is your GDPR erasure path.

9. Troubleshooting

• "invalid or missing API key" — key pasted with whitespace, or deleted by an admin. Get a fresh one.
• DOM capture looks wrong — known limits (canvas, some fonts). Re-record that flow in screenshot mode; report the gap to your admin.
• Publish button fails — your key lacks the publish scope. Working as intended; ask an admin.
• Video export is slow — DOM steps are rendered through a real browser the first time; subsequent exports reuse the cache.
• Extension uploads hang on huge captures — DOM snapshots of very heavy pages are large; capture shorter segments per demo.