From 6e2a6b76116e54a7e2374c65697aaf7cfce5e527 Mon Sep 17 00:00:00 2001 From: Luca Martial Date: Mon, 11 May 2026 14:34:07 -0700 Subject: [PATCH] docs: add demo guided tour design spec Co-Authored-By: Claude Opus 4.6 (1M context) --- .../2026-05-11-demo-guided-tour-design.md | 252 ++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-11-demo-guided-tour-design.md diff --git a/docs/superpowers/specs/2026-05-11-demo-guided-tour-design.md b/docs/superpowers/specs/2026-05-11-demo-guided-tour-design.md new file mode 100644 index 00000000..34585743 --- /dev/null +++ b/docs/superpowers/specs/2026-05-11-demo-guided-tour-design.md @@ -0,0 +1,252 @@ +# Demo Guided Tour — Design Spec + +## Problem + +The "Try KTX with packaged demo data" option in `ktx setup` is completely +disconnected from the real setup wizard. It bypasses all wizard steps, plays +an animated replay in a temp directory, and exits with no bridge to actually +using KTX. Users don't learn the real setup flow and hit a dead end. + +## Solution + +Redesign the demo option as a **guided tour** that walks the user through the +same setup wizard steps with pre-filled, read-only selections. The tour ends +with a real interactive agents step so the user can immediately use the demo +project with their coding agent. + +## Design Decisions + +| Decision | Choice | Rationale | +|----------|--------|-----------| +| Implementation strategy | Demo mode flag on existing wizard steps | Maximum code reuse; wizard changes automatically apply to demo | +| LLM/embeddings steps | Skipped | Not relevant to pre-packaged demo data | +| Database selection | PostgreSQL (read-only card) | Pre-filled, matches demo dataset | +| Context sources | dbt, Metabase, Notion (read-only card) | Pre-filled, matches demo dataset | +| Context build | Replay through real progress visualization | Same spinners, progress bars, status icons as real build | +| Agents step | Real interactive step | User actually connects their agent | +| Project location | Temp directory (`/tmp/ktx-demo-{hex}`) | Frictionless, no directory prompt | +| Navigation | Enter to advance, Escape to go back | Consistent with rest of wizard | + +## Flow + +``` +Entry menu: "Try KTX with packaged demo data" + │ + ▼ +Create demo project in /tmp/ktx-demo-{hex} +Copy pre-packaged assets (demo DB, replay, context artifacts) + │ + ▼ +┌────────────────────────────────────────────────────────────────┐ +│ Demo banner (persistent, shown on every step) │ +│ │ +│ Demo mode — data has been pre-processed and KTX context is │ +│ already built. This walkthrough illustrates the setup steps. │ +│ Selections are pre-filled and read-only. │ +└────────────────────────────────────────────────────────────────┘ + │ + ▼ +Read-only card: Database connection + ▸ PostgreSQL (demo warehouse) + [Enter → next, Escape → back to entry menu] + │ + ▼ +Read-only card: Context sources + ▸ dbt + ▸ Metabase + ▸ Notion + [Enter → next, Escape → back to database card] + │ + ▼ +Context build replay + Same renderContextBuildView() / repainter as real wizard + Sources: demo-warehouse, dbt, metabase, notion + Replay at slightly faster-than-real pace + Completion summary: business areas, query definitions, knowledge pages + [Enter → next, Escape → back to sources card] + │ + ▼ +Transition message: + "Demo project is ready — let's connect your agent" + │ + ▼ +Interactive agents step (real runKtxSetupAgentsStep()) + User selects agent target, scope, install mode + [Normal interactive navigation; Escape goes back to replay summary] + │ + ▼ +Final summary: + ★ KTX demo is ready + Agent connected, project path shown + ⚠ Temp directory warning + Pointer to `ktx setup` for real data +``` + +## Step Details + +### Demo Banner + +Shown at the top of every read-only step. Uses clack box-drawing style: + +``` +┌ Demo mode — data has been pre-processed and KTX context is already built. +│ This walkthrough illustrates the setup steps. Selections are pre-filled and read-only. +``` + +### Read-Only Step Cards + +Rendered by a shared `renderDemoCard()` helper: + +```typescript +async function renderDemoCard( + title: string, + selections: string[], + io: KtxCliIo, +): Promise<'forward' | 'back'> +``` + +- Renders a clack-style box with title, bullet list of pre-filled selections, + and navigation hint ("Press Enter to continue, Escape to go back") +- Listens for raw keypresses: Enter → `'forward'`, Escape → `'back'` +- Uses same box-drawing characters and colors as `@clack/prompts` + +Card format: + +``` +┌ {title} +│ +│ ▸ {selection 1} +│ ▸ {selection 2} +│ ... +│ +│ Press Enter to continue, Escape to go back +└ +``` + +### Demo Step Sequence + +The demo reuses the main wizard's step loop with these steps: + +```typescript +const demoSteps = ['databases', 'sources', 'context', 'agents']; +``` + +Steps `databases` and `sources` dispatch to `renderDemoCard()` instead of +their real interactive functions when demo mode is active. Step `context` +dispatches to the replay visualization. Step `agents` runs the real +`runKtxSetupAgentsStep()`. + +Back navigation reuses `previousNavigableStepIndex()`. Escaping from the +first step (databases) returns to the entry menu. + +### Context Build Replay + +Uses the same rendering pipeline as the real context build: + +- `renderContextBuildView()` for the progress display +- `createRepainter()` for terminal repainting +- Same spinner frames, progress bars (`████░░░░`), status icons (`✓`, `⠹`, `○`) +- Same source grouping (Primary sources / Context sources) + +Sources shown: + +``` +Primary sources: + ✓ demo-warehouse completed · Xs + +Context sources: + ✓ dbt completed · Xs + ✓ metabase completed · Xs + ✓ notion completed · Xs +``` + +Replay timing: events from the pre-packaged replay file are played back at +a slightly faster pace than real-time (compressed to feel brisk but not +instant). + +Completion summary uses the existing format: + +``` +★ KTX finished ingesting your data + + ✓ Analyzed X business areas + ✓ Reconciled — 0 conflicts + + KTX created: + 📊 X query definitions + 📝 X knowledge pages + + Press Enter to continue, Escape to go back +``` + +The exact counts and artifact names come from the pre-packaged demo results +(to be provided by the user as improved demo data). + +### Agents Step Transition + +A brief message bridges from the read-only tour to the interactive step: + +``` +┌ Demo project is ready — let's connect your agent +│ +│ Your KTX context has been built with demo data. +│ Select an agent to start using it. +└ +``` + +Then `runKtxSetupAgentsStep()` runs with the demo project directory, +normal interactive prompts enabled. + +### Final Summary + +``` +★ KTX demo is ready + + Your agent is connected to a demo KTX project. + + ⚠ This project is in a temporary directory and will be + cleaned up by your system. To set up KTX with your own + data, run: ktx setup + + Project: /tmp/ktx-demo-a1b2c3 +``` + +If the user skips the agents step, replace the first line with manual +agent connection instructions (`ktx setup --agents --project-dir /tmp/...`). + +## Implementation Approach + +Thread a `demoMode` flag through the main setup loop in `setup.ts`. When +active: + +1. Skip `models` and `embeddings` steps entirely +2. Replace `databases` and `sources` step dispatch with `renderDemoCard()` +3. Replace `context` step dispatch with replay visualization +4. Run `agents` step normally +5. Show demo-specific completion summary instead of ready menu + +The `renderDemoCard()` helper is a new function in a new file +(e.g. `setup-demo-cards.ts`) that handles read-only card rendering and +keypress listening. + +The context build replay reuses existing `renderContextBuildView()` and +`createRepainter()` from `context-build-view.ts`, fed with events from +the pre-packaged replay file at an accelerated playback rate. + +## Files Changed + +| File | Change | +|------|--------| +| `packages/cli/src/setup.ts` | Add `demoMode` flag to setup loop; skip models/embeddings; dispatch to demo cards for databases/sources; show demo banner; demo completion summary | +| `packages/cli/src/setup-demo-cards.ts` | New file: `renderDemoCard()` helper, demo banner renderer, demo step definitions | +| `packages/cli/src/setup-context.ts` | Support replay mode for demo: feed pre-packaged events at accelerated pace through existing progress view | +| `packages/cli/src/demo.ts` | Remove or simplify `runKtxSetupDemoFromEntryMenu()` — now dispatches to the main setup loop with `demoMode: true` | +| `packages/cli/src/demo-assets.ts` | Update asset list if new demo data is provided; ensure demo project setup writes valid `ktx.yaml` for agent use | + +## Open Items + +- **Demo data**: User will provide improved pre-packaged results (Postgres, + dbt, Metabase, Notion). Current demo assets may need updating. +- **Replay speed**: Exact acceleration factor TBD — should feel brisk but + give users time to read source names and status transitions. Start with + ~2x real-time and adjust.