Guided demo: The one you own in your repo

Why does a guided demo feel easy to ship and painful to keep current? Because the artifact lives in someone else's editor. The moment your guided demo sits inside a proprietary SaaS, every UI change becomes a manual update inside a tool you do not control. That is the ownership problem. A guided demo in your repo does not have it.

What a guided demo is, and why ownership matters

The buyer's job the demo has to do

A guided demo is a buyer-facing walkthrough that shows someone a specific path through your product. Not the whole app. Not a sandbox to poke around in. Just the flow that answers their question fast. It works as a leave-behind after a sales call, an embed on a landing page, or a self-serve explainer that runs without a human on the other end.

That only works long term if the demo stays accurate. Accuracy is a maintenance problem, not a design problem.

Why a demo inside a SaaS editor becomes someone else's problem

When the demo lives in a hosted editor — Supademo, Arcade, Storylane — updating it after a product change means opening their UI, finding the affected screens, and editing or recapturing them one by one. Your product moves on a Tuesday; the demo catches up whenever you get around to it. The artifact and the source of truth are in different places, so they drift. A guided demo in your repo does not drift. It changes the same way your product does, through the same tools, in the same workflow.

That folder lives next to `/src`. When the product ships, the demo ships.

How a guided demo differs from sandbox demos, video demos, and product tours

Where each format works without hand-waving

Four formats, four jobs:

• Video demo — passive viewing. The buyer watches. No interaction, no branching. Right for top-of-funnel awareness where you control the narrative completely.
• Sandbox demo — the buyer tries the product in a safe clone. Right for high-intent prospects who want to explore before buying. Expensive to build and maintain.
• Product tour — in-app guidance for users who already have access. Tooltips, modals, checklists. Built for activation, not acquisition.
• Guided demo — a curated path through the product, interactive but directed. The buyer clicks through a specific flow you designed. Right for sales walkthroughs, website embeds, and leave-behinds.

The moment the formats stop being interchangeable

The decision point is what the buyer does next. A video demo ends the interaction. A sandbox demo invites the buyer to wander, which is useful only if they are ready to evaluate, not just learn. A product tour assumes the buyer is already inside the product.

A guided demo is for the gap: the buyer is not ready to try the product but needs more than a video. That is most of the sales funnel. Using the wrong format here — a video when the buyer wants to click, a sandbox when they want a path — adds friction that does not show up in your analytics until conversion drops. According to PostHog's guide on giving S-tier demos, picking one main point and building the demo around it is the difference between a demo that lands and one that wanders. Format choice comes first.

Why SaaS-only guided demo editors break when your product ships fast

The first version looks fine, then the UI moves

You ship a guided demo on a Monday. It covers your onboarding flow: three screens, two clicks, one outcome. On Thursday, the product team restructures the nav. The sidebar label changes. A step moves. The guided demo now shows the old UI to every buyer who opens it.

Inside a SaaS editor, fixing this means opening the tool, locating the affected screens, and either editing them inline, if the tool supports it, or recapturing them from scratch. On screenshot-based tools, there is no inline layout edit. A structural UI change means recapturing every affected screen. That is not a one-time cost. It is a cost you pay every time the product moves.

What recapture really means in practice

Recapture is not just taking a new screenshot. It means rebuilding the annotation layer on top of it — the hotspots, the tooltip copy, the click targets. Then you retest the flow end to end to make sure nothing broke. On a five-screen guided demo with two branching paths, a single nav change can touch every screen.

The work adds up. A team shipping weekly pays that cost weekly. The demo that was a two-hour build becomes a two-hour maintenance task that keeps coming back, competing with everything else on the roadmap. Supademo's own help documentation describes recapture as the path for structural UI changes, which is at least honest about the cost.

Build a guided demo in code, not in a hosted editor

The simplest repo structure that still makes sense

A code-native guided demo does not need a complex setup. The folder structure above is the whole thing. Steps own the walkthrough logic — what screen comes after what action. Assets hold the captures, whether screenshots or HTML. Copy lives separately so you can update text without touching the flow. Config holds the variables that change per customer: company name, logo, sandbox data.

That separation matters. When the product ships a UI change, you update assets. When the sales team wants a new customer's name in the demo, you update config. Neither change touches the other. The demo stays in your repo, versioned with git, visible in the same PR history as the product.

How the product and the demo stay in sync

The workflow is a loop: product change lands in a branch, demo code updates in the same branch, both ship together. Your agent — Cursor, Claude, Codex — can handle the demo update the same way it handles any code change. You describe what moved, the agent updates the relevant steps and assets, you review the diff. No separate tool to open, no SaaS editor to navigate, no recapture queue to work through.

This is what Mintlify did for documentation: made the artifact code that lives next to the product instead of a separate SaaS. The same model applies to demos. The demo is the new deck, and it should live where the deck's source of truth lives: in your repo.

Use your coding agent to update the guided demo without manual cleanup

What the prompt has to say, and what it should not do

When the product UI changes, the agent prompt has one job: update the affected demo steps to match the new UI. A good prompt names the specific change, like "the Settings nav item moved from the sidebar to the top bar", points at the relevant files (`/steps/onboarding.js`, `/assets/step-3.png`), and asks for a targeted update, not a full rewrite.

What the prompt should not do is rewrite the whole flow because the agent decided to improve it. Scope the change. "Update step 3 to reflect the new nav position. Don't touch steps 1, 2, or 4." The agent's job is re-authoring code, not editing a brittle recording. That distinction is what makes the workflow fast.

Guardrails that keep the agent from wandering

Three checks before you merge an agent-generated demo update:

• Review the diff against the stated change. If the agent touched files outside the scope you named, understand why before approving.
• Keep copy consistent. The agent will sometimes rewrite tooltip text while updating layout. If the copy was not in scope, revert it.
• Avoid full-flow regeneration for partial changes. One screen changed; one screen should update. A prompt that says "regenerate the demo to match the current product" will produce something technically correct and tonally off. It loses the intentional framing you built into the original flow.

The agent is fast at the mechanical parts. The judgment about what the demo should say is still yours.

Add personalization and analytics without turning the guided demo into a mess

Tokens and company names belong in the right layer

Personalization breaks guided demos when it is baked into the flow logic instead of isolated in a config layer. If a company name appears in six different steps and it is hardcoded into each one, updating it for a new customer means editing six files. If it is a token in `/config.json` and every step references the token, updating it means changing one value.

The same principle applies to logos, sandbox data, and any field that varies by customer. Keep the demo path stable. Keep the variables in config. The agent can produce a new customer variant by re-prompting against the config layer: same flow, fresh branding, one pass.

Tracking engagement without coupling the demo to the dashboard

Analytics should sit alongside the demo, not inside the step logic. A view event fires when the demo loads. A completion event fires when the last step renders. Those two hooks are enough to measure engagement without coupling the demo to any specific analytics tool.

When you are ready to connect something like PostHog, the integration is a few lines next to the demo code, not a feature you have to unlock inside a SaaS editor. The demo does not know or care which analytics tool receives the events. That flexibility is only possible because the demo is code you own.

Where Inkly comes in

The problem the article just walked through is not a demo-format problem. It is an artifact-location problem. The guided demo breaks on maintenance because it lives inside a vendor's SaaS, where your product changes cannot reach it without manual rework. The fix is not a better editor. It is a demo that lives where the product lives.

Inkly is built on that premise. You capture the demo with a Chrome extension, and the output is code you own — HTML, in your repo, next to the product. When the UI changes, you re-prompt your agent against the existing demo code. No recapture, no annotation rebuild, no SaaS editor to navigate. When a new customer needs a tailored version, you re-prompt for a branded variant off the same base. The tradeoff is straightforward: Inkly requires a coding agent (Cursor, Claude, Codex) and a repo workflow. If your team does not operate that way yet, the bring-your-own-agent path adds setup. But if you are already prompting your way through the product, the demo becomes code you maintain the same way you maintain everything else.

FAQ

Q: What is a guided demo, and how is it different from a sandbox demo, video demo, or product tour?

A guided demo is a curated, interactive walkthrough of a specific product flow. The buyer clicks through a path you designed, rather than exploring freely or watching passively. A video demo is passive viewing with no interaction. A sandbox demo gives the buyer a live or cloned environment to explore on their own. A product tour is in-app guidance for users who already have access. The guided demo fills the gap between "I watched a video" and "I tried the product". It is the format for the middle of the funnel.

Q: How can I create a guided demo quickly without locking it inside a proprietary editor?

Capture the flow with a Chrome extension or screenshot tool to get the assets fast, then output the demo as code into your own repo. The folder structure is simple: steps, assets, copy, and config. From there, your coding agent can maintain and update it without you ever opening a SaaS editor. The first demo takes roughly the same time as a Supademo capture; every subsequent update is a prompt instead of a recapture.

Q: How do I keep a guided demo current every time the product UI changes?

Keep the demo in the same repo as the product. When a UI change lands, update the relevant demo assets and steps in the same branch. If you are using a coding agent, prompt it to update the specific files affected by the change. Scope the prompt to the change, review the diff, and ship. The demo stays in sync because it lives next to the source of truth.

Q: What is the simplest workflow for a founder or indie hacker who wants to ship one fast?

One repo, one agent, one demo flow. Capture the key screens, drop them into a `/demo` folder, write the step logic in plain JSON or JS, and keep all variable content in a config file. Prompt your agent to wire it together. You do not need a demo platform. You need a folder structure and twenty minutes.

Q: How can a product engineer own demo updates in code or version control?

The demo lives in the repo like any other artifact. Changes go through PRs, show up in git history, and can be reviewed alongside the product changes that prompted them. When the product ships a UI change, the demo update ships in the same PR. No separate tool, no out-of-band update, no "someone needs to update the demo" ticket that sits in the backlog for two weeks.

Conclusion

If the guided demo is going to stay useful, it has to live where the product lives. A demo in a SaaS editor is a snapshot that starts going stale the moment you close the tab. A demo in your repo is a maintained artifact — one that your agent can update, personalize, and keep current without manual rework. Put one guided demo in your repo this week. Push a UI change. Update it with a single agent prompt. That is the whole test.