docs: end-user guide — setup, capture modes, MCP agent connection, prompt cookbook
This commit is contained in:
parent
928628f49a
commit
4333cd23ef
1 changed files with 192 additions and 0 deletions
192
docs/USER-GUIDE.md
Normal file
192
docs/USER-GUIDE.md
Normal file
|
|
@ -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://<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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue