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
- **Branch hotspots** — switch Draw mode to "Branch", drag a region, pick the
  target step. Branches render dashed in the player and let viewers choose
  their own path
- **Chapters** — the Chapters panel in the sidebar builds the jump menu shown
  in the player bar
- **Duplicate / delete demos** — ⧉ and × on the demo list. Duplicate before
  personalizing for a prospect; the copy is always a private draft
- **Personalized link** — one click generates a share link with a viewer token
  baked in
- **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 the demo "Generic Tour", then rewrite all tooltips in the copy to
> speak directly to Acme Corp (logistics company, 400 trucks, pain point is
> manual dispatch). Mention their industry where natural. Rename the copy
> "Acme Corp Tour" and tell me when it's ready to publish — I'll send it 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.