From 4333cd23ef053ed9545ef9088361a1c202cbf6af Mon Sep 17 00:00:00 2001 From: scot Date: Sat, 18 Jul 2026 05:43:40 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20end-user=20guide=20=E2=80=94=20setup,?= =?UTF-8?q?=20capture=20modes,=20MCP=20agent=20connection,=20prompt=20cook?= =?UTF-8?q?book?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/USER-GUIDE.md | 192 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 docs/USER-GUIDE.md diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md new file mode 100644 index 0000000..fbed131 --- /dev/null +++ b/docs/USER-GUIDE.md @@ -0,0 +1,192 @@ +# 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:///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/`. *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//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=` 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:///mcp` (Streamable HTTP) +**Auth:** `Authorization: Bearer ` header + +**Claude Code:** +``` +claude mcp add --transport http demos https:///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/`), 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.