autoplay walkthrough in README, embed in docs landing

Use the GitHub user-attachments URL for both README and docs so the
video plays inline without bundling the 15MB binary into the gh-pages
build. README gets autoplay/muted/loop; docs landing uses controls.

Author: awbx

README.md

@@ -6,7 +6,7 @@ Build FHIR REST queries with compile-time type safety for resources, search para
 
 **[Documentation](https://awbx.github.io/fhir-dsl/)** | **[Quick Start](https://awbx.github.io/fhir-dsl/docs/getting-started/quick-start)** | **[CLI Usage](https://awbx.github.io/fhir-dsl/docs/cli/usage)** | **[Roadmap](https://awbx.github.io/fhir-dsl/docs/roadmap)**
 
-<video src="https://github.com/user-attachments/assets/64947e51-cdd0-41fc-b7e0-01d68009ffc8" controls width="100%"></video>
+<video src="https://github.com/user-attachments/assets/64947e51-cdd0-41fc-b7e0-01d68009ffc8" autoplay muted loop playsinline controls width="100%"></video>
 
 
 ## Why fhir-dsl?

apps/docs/src/pages/index.js

@@ -5,6 +5,9 @@ import { Highlight, themes } from 'prism-react-renderer';
 import { useState } from 'react';
 import styles from './index.module.css';
 
+const WALKTHROUGH_VIDEO_URL =
+  'https://github.com/user-attachments/assets/64947e51-cdd0-41fc-b7e0-01d68009ffc8';
+
 const EXAMPLES = [
   {
     id: 'search',
@@ -399,6 +402,32 @@ function Hero({ title, tagline, version }) {
   );
 }
 
+function Walkthrough() {
+  return (
+    <section className={styles.section}>
+      <div className={styles.sectionHeader}>
+        <span className={styles.eyebrow}>Walkthrough</span>
+        <h2 className={styles.sectionTitle}>See it in action</h2>
+        <p className={styles.sectionLead}>
+          A short narrated tour of the query builder, generator, and CLI.
+        </p>
+      </div>
+
+      <div className={styles.videoFrame}>
+        <video
+          className={styles.video}
+          src={WALKTHROUGH_VIDEO_URL}
+          controls
+          preload="metadata"
+          playsInline
+        >
+          <track kind="captions" />
+        </video>
+      </div>
+    </section>
+  );
+}
+
 function Playground() {
   const [activeId, setActiveId] = useState(EXAMPLES[0].id);
   const active = EXAMPLES.find((e) => e.id === activeId) ?? EXAMPLES[0];
@@ -509,6 +538,7 @@ export default function Home() {
           tagline={siteConfig.tagline}
           version={siteConfig.customFields?.version}
         />
+        <Walkthrough />
         <Playground />
         <Features />
         <CTA />

apps/docs/src/pages/index.module.css

@@ -244,6 +244,25 @@
   margin: 0;
 }
 
+/* ───── Walkthrough video ───── */
+
+.videoFrame {
+  border: 1px solid var(--surface-border);
+  border-radius: 14px;
+  background: var(--code-bg);
+  overflow: hidden;
+  box-shadow: 0 24px 60px -30px rgba(15, 23, 42, 0.5);
+  aspect-ratio: 16 / 9;
+}
+
+.video {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  background: var(--code-bg);
+}
+
 /* ───── Tabs / code playground ───── */
 
 .playground {