docs: add demo guided tour design spec

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-06-10 08:05:14 +02:00 · 2026-05-11 14:34:07 -07:00 · 2026-05-11 14:34:07 -07:00 · 6e2a6b7611
commit 6e2a6b7611
parent 155613c794
1 changed files with 252 additions and 0 deletions
--- a/docs/superpowers/specs/2026-05-11-demo-guided-tour-design.md
+++ 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.