From 35d8caba2a6efec366a8f7419b06c8d9507c08ec Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Fri, 9 Oct 2026 00:02:09 +1100
Subject: [PATCH 1/4] feat(home): lead with demos and simplify demo handoff

---
 COPY.md                                       |   2 +
 app/components/DemoStage.vue                  |  19 +-
 app/components/_DemoActions.vue               |  67 +++++
 app/composables/useDemoEngagement.ts          |  36 +++
 app/pages/_HomeDemoCarousel.vue               |  70 ++++++
 app/pages/index.vue                           | 229 +++++++++++++-----
 app/utils/random-order.ts                     |   9 +
 docs/runbooks/demo-measurement.md             |  63 +++++
 .../marketing/app/components/BoardShell.vue   |  26 +-
 .../app/pages/skills/demos/[...demo].vue      |   2 +-
 layers/marketing/content/pages/privacy.md     |   8 +-
 server/api/events/demo.post.ts                |  16 ++
 server/presenters/demo-engagement.ts          |   3 +
 server/schemas/demo-engagement.ts             |  13 +
 shared/demo-engagement.ts                     |  35 +++
 test/a11y.nuxt.spec.ts                        |   9 +
 test/unit/demo-engagement.test.ts             |  34 +++
 test/unit/random-order.test.ts                |  17 ++
 18 files changed, 590 insertions(+), 68 deletions(-)
 create mode 100644 app/components/_DemoActions.vue
 create mode 100644 app/composables/useDemoEngagement.ts
 create mode 100644 app/pages/_HomeDemoCarousel.vue
 create mode 100644 app/utils/random-order.ts
 create mode 100644 docs/runbooks/demo-measurement.md
 create mode 100644 server/api/events/demo.post.ts
 create mode 100644 server/presenters/demo-engagement.ts
 create mode 100644 server/schemas/demo-engagement.ts
 create mode 100644 shared/demo-engagement.ts
 create mode 100644 test/unit/demo-engagement.test.ts
 create mode 100644 test/unit/random-order.test.ts

diff --git a/COPY.md b/COPY.md
index 6029172c..ff303fcd 100644
--- a/COPY.md
+++ b/COPY.md
@@ -44,7 +44,9 @@ These exact strings. Do not paraphrase them per page.
 | Demos page | See what skills make · Each demo is one recorded run: the prompt, and what the Agent built with the Skill. Pick a prompt to see the output, or open it live. | guidance only: the `/skills/demos` H1 and line. The meta title is "Claude skill examples: see what each one makes" for the admitted query |
 | Demo page | What /{name} made · One recorded run: the prompt, and what the Agent built with the Skill. | guidance only: the H1 and line of a demo page, `/skills/demos/<owner>/<repo>/<name>`. The meta title is "{name} skill example: {noun}" for the query "<skill> skill example", with `noun` from `DEMO_GROUPS`. The meta description is "{agent} made this {noun} with the /{name} skill from one prompt: “{prompt}”", cut at a word to 160 characters |
 | Demo groups | Films and launch videos · Landing pages · UI components · Diagrams and explainers | guidance only: `DEMO_GROUPS` in `shared/demo-groups.ts`: the `/skills/demos` group headings and their lines |
+| Demo actions | Run it yourself · Agent prompt · Terminal · Copy Agent prompt · Copy command · Copied · Copy demo link · Copied demo link | guidance only: demo stages. The Agent prompt includes the recorded task. The terminal option loads the Skill. Run is hidden on phones. |
 | Demo stage | Open the demo | guidance only: the demo stage link. On the homepage it opens the demo page; on a demo page it opens the Skill page Demo panel |
+| Home demo carousel | Previous demo · Next demo · {n} of {total} | guidance only: the manual homepage demo controls. The position is live text for screen readers. |
 | Demo panel | Demo · Prompt · Open live demo · Open in a new tab · Run it yourself · All demos | guidance only: the Skill page Demo panel. "Show screenshots" replaces "Open live demo" while the live output shows. "All demos" opens the demo page. It hides for a Skill page only demo, and while the Skill holds a run check flag |
 | Demo provenance | {Agent logo} {model}, {effort} effort | guidance only: the recording line on the Skill page panel and the homepage stage. Screen readers and the title get "Recorded with {agent}, {model}, {effort} effort". Omit effort when the recording has no evidence for it. No date and no GitHub link: the Skill page is where visitors inspect a Skill |
 | Demo outdated | Recorded on an older version of this Skill. | guidance only: under the Demo panel when the Skill moved past the recorded commit |
diff --git a/app/components/DemoStage.vue b/app/components/DemoStage.vue
index d3273713..1cf8abbc 100644
--- a/app/components/DemoStage.vue
+++ b/app/components/DemoStage.vue
@@ -2,6 +2,7 @@
 import type { HomeDemoItem } from '~/utils/home-demos'
 import { demoPagePath } from '#shared/demo-pages'
 import { demoCardSkill, demoHasPhoneFrame, demoHref, demoPhoneRatio } from '~/utils/home-demos'
+import DemoActions from './_DemoActions.vue'
 import DemoMedia from './home-demos/_DemoMedia.vue'
 import DemoRecording from './home-demos/_DemoRecording.vue'
 import SkillCard from './SkillCard.vue'
@@ -27,6 +28,8 @@ const { demo, surface = 'demos', eager = false, showPrompt = false, live = false
 }>()
 
 /** The output page itself, when this stage shows it live. A film always plays as video. */
+const stage = useTemplateRef<HTMLElement>('stage')
+const { record } = useDemoEngagement(() => `${demo.owner}/${demo.repo}/${demo.name}`, surface, stage)
 const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
 </script>
 
@@ -44,6 +47,7 @@ const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
     </p>
     <!-- The whole page, in a window one screen tall. A film fills the window and plays on view. -->
     <div
+      ref="stage"
       class="demo-stage__window"
       :data-phone="demoHasPhoneFrame(demo) ? '' : undefined"
       :style="demo.video
@@ -71,9 +75,10 @@ const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
         layout="row"
         metric="none"
         :description="false"
-        :actions="['run']"
+        :actions="[]"
         :surface
       />
+      <DemoActions :demo :surface @action="record" />
     </div>
   </div>
 </template>
@@ -152,6 +157,14 @@ const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
     block-size: auto;
     aspect-ratio: var(--phone-ratio, 4 / 5);
   }
+
+  .demo-stage__id :deep(.skill-card--row) {
+    padding-block: 0.5rem;
+  }
+
+  .demo-stage__id :deep(.skill-card__row-end) {
+    display: none;
+  }
 }
 
 /* The live page scrolls inside its own frame. */
@@ -174,6 +187,10 @@ const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
 
 /* The Skill row's hover fill follows the rounded corners of everything around it. */
 .demo-stage__id {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 0.5rem;
   margin-block-start: 0.25rem;
   overflow: hidden;
   border-radius: var(--ui-radius);
diff --git a/app/components/_DemoActions.vue b/app/components/_DemoActions.vue
new file mode 100644
index 00000000..204c9979
--- /dev/null
+++ b/app/components/_DemoActions.vue
@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import type { HomeDemoItem } from '~/utils/home-demos'
+import { demoPagePath } from '#shared/demo-pages'
+import { skillPageUrl, skillRunCmd, skillRunPrompt } from '#shared/skill-commands'
+
+const { demo, surface } = defineProps<{ demo: HomeDemoItem, surface: string }>()
+const emit = defineEmits<{ action: [action: { event: 'share' } | { event: 'copy', format: 'agent' | 'terminal' }] }>()
+const format = ref<'agent' | 'terminal'>('agent')
+const text = computed(() => format.value === 'agent'
+  ? `${skillRunPrompt(skillPageUrl(demo.owner, demo.repo, demo.name))}\n\n${demo.prompt}`
+  : skillRunCmd(demo.owner, demo.repo, demo.name))
+const target = computed(() => ({ kind: 'skill' as const, owner: demo.owner, name: demo.name }))
+const { copy, copied } = useInstallCopy(text, surface, 'run', target)
+const error = ref('')
+const shareUrl = computed(() => `https://skilld.dev${demoPagePath(demo)}`)
+const { copy: copyLink, copied: linkCopied, isSupported: linkSupported } = useClipboard({ source: shareUrl, legacy: true })
+
+async function copyPrompt() {
+  error.value = ''
+  const copiedFormat = format.value
+  const result = await copy()
+  if (result._tag === 'error')
+    error.value = result.message
+  else
+    emit('action', { event: 'copy', format: copiedFormat })
+}
+async function share() {
+  error.value = ''
+  if (!linkSupported.value) {
+    error.value = 'Could not copy. Select the link and copy it manually.'
+    return
+  }
+  await copyLink().then(() => emit('action', { event: 'share' })).catch((cause) => {
+    console.warn('[demo-share] Could not copy demo link:', cause)
+    error.value = 'Could not copy. Select the link and copy it manually.'
+  })
+}
+</script>
+
+<template>
+  <div class="demo-actions">
+    <UPopover class="demo-actions__run">
+      <UButton label="Run it yourself" color="neutral" variant="outline" class="min-h-11" />
+      <template #content>
+        <div class="w-[min(28rem,calc(100vw-2rem))] space-y-3 p-4 demo-actions__panel">
+          <div class="flex gap-2">
+            <UButton label="Agent prompt" :aria-pressed="format === 'agent'" color="neutral" variant="outline" class="demo-actions__format min-h-11" @click="format = 'agent'" />
+            <UButton label="Terminal" :aria-pressed="format === 'terminal'" color="neutral" variant="outline" class="demo-actions__format min-h-11" @click="format = 'terminal'" />
+          </div>
+          <pre class="max-h-64 overflow-auto whitespace-pre-wrap break-words rounded border border-default p-3 text-xs">{{ text }}</pre>
+          <UButton :label="copied ? 'Copied' : format === 'agent' ? 'Copy Agent prompt' : 'Copy command'" color="neutral" variant="outline" class="min-h-11" @click="copyPrompt" />
+        </div>
+      </template>
+    </UPopover>
+    <UButton :icon="linkCopied ? 'i-lucide-check' : 'i-lucide-link'" :aria-label="linkCopied ? 'Copied demo link' : 'Copy demo link'" color="neutral" variant="ghost" class="min-h-11 min-w-11 justify-center" @click="share" />
+    <span class="sr-only" role="status">{{ linkCopied ? 'Copied demo link' : copied ? 'Copied' : '' }}</span>
+    <p v-if="error" role="alert" class="basis-full text-xs text-error">
+      {{ error }} <a :href="shareUrl" class="underline">{{ shareUrl }}</a>
+    </p>
+  </div>
+</template>
+
+<style scoped>
+.demo-actions__format[aria-pressed='true'] { background: var(--ui-bg-accented); color: var(--ui-text-highlighted); }
+.demo-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 0.5rem; }
+@media (max-width: 39.99rem) { .demo-actions__run { display: none; } }
+</style>
diff --git a/app/composables/useDemoEngagement.ts b/app/composables/useDemoEngagement.ts
new file mode 100644
index 00000000..aae83356
--- /dev/null
+++ b/app/composables/useDemoEngagement.ts
@@ -0,0 +1,36 @@
+import type { MaybeRefOrGetter, Ref } from 'vue'
+import type { DemoCampaign, DemoEngagement } from '#shared/demo-engagement'
+import { demoElapsedBucket, demoFrameIsVisible } from '#shared/demo-engagement'
+
+export function useDemoEngagement(slug: MaybeRefOrGetter<string>, surface: string, stage: Readonly<Ref<HTMLElement | null>>) {
+  const route = useRoute()
+  const exposed = new Set<string>()
+  const firstSeen = new Map<string, number>()
+  const visible = ref(false)
+  const campaign = computed<DemoCampaign>(() => {
+    const value = route.query.campaign
+    return value === 'demo-component' || value === 'demo-page' || value === 'demo-motion' ? value : 'direct'
+  })
+  function record(action: { event: 'exposure' } | { event: 'share' } | { event: 'copy', format: 'agent' | 'terminal' }) {
+    const key = toValue(slug)
+    const since = firstSeen.get(key)
+    const context = { slug: key, surface, campaign: campaign.value }
+    const body: DemoEngagement = action.event === 'exposure'
+      ? { ...context, ...action }
+      : { ...context, ...action, elapsed: demoElapsedBucket(since === undefined ? null : performance.now() - since) }
+    void $fetch('/api/events/demo', { method: 'POST', body }).catch((error) => {
+      console.warn('[demo-engagement] Could not record demo event:', error)
+    })
+  }
+  useIntersectionObserver(stage, ([entry]) => {
+    visible.value = demoFrameIsVisible(entry)
+  }, { threshold: 0.5 })
+  watch([() => toValue(slug), visible], ([key, isVisible]) => {
+    if (!isVisible || exposed.has(key))
+      return
+    exposed.add(key)
+    firstSeen.set(key, performance.now())
+    record({ event: 'exposure' })
+  })
+  return { record }
+}
diff --git a/app/pages/_HomeDemoCarousel.vue b/app/pages/_HomeDemoCarousel.vue
new file mode 100644
index 00000000..237b1ad1
--- /dev/null
+++ b/app/pages/_HomeDemoCarousel.vue
@@ -0,0 +1,70 @@
+<script setup lang="ts">
+import type { HomeDemoItem } from '../utils/home-demos'
+import DemoStage from '../components/DemoStage.vue'
+import { shuffled } from '../utils/random-order'
+
+const { demos } = defineProps<{ demos: readonly HomeDemoItem[] }>()
+const order = shallowRef<readonly HomeDemoItem[]>(demos)
+const picked = ref(0)
+const current = computed(() => order.value[picked.value])
+const stageId = useId()
+
+// Hydrate the cached page before choosing a fresh order for this visit.
+onMounted(() => {
+  order.value = shuffled(demos, Math.random)
+})
+
+function move(direction: -1 | 1): void {
+  picked.value = (picked.value + direction + order.value.length) % order.value.length
+}
+</script>
+
+<template>
+  <div v-if="current" class="home-demo-carousel">
+    <div :id="stageId">
+      <DemoStage :demo="current" eager show-prompt surface="home-hero-demo" />
+    </div>
+    <div v-if="order.length > 1" class="home-demo-carousel__controls">
+      <UButton
+        icon="i-lucide-arrow-left"
+        color="neutral"
+        variant="ghost"
+        aria-label="Previous demo"
+        :aria-controls="stageId"
+        class="min-h-11 min-w-11 justify-center"
+        @click="move(-1)"
+      />
+      <span class="font-mono text-xs text-muted" aria-live="polite" aria-atomic="true">{{ picked + 1 }} of {{ order.length }}</span>
+      <UButton
+        icon="i-lucide-arrow-right"
+        color="neutral"
+        variant="ghost"
+        aria-label="Next demo"
+        :aria-controls="stageId"
+        class="min-h-11 min-w-11 justify-center"
+        @click="move(1)"
+      />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.home-demo-carousel {
+  container-type: inline-size;
+}
+
+/* Each pick gets the same frame, including demos with a shorter phone shot. */
+.home-demo-carousel :deep(.demo-stage__window) {
+  block-size: clamp(16rem, 62.5cqi, 24rem);
+  aspect-ratio: auto;
+  inline-size: 100%;
+}
+
+.home-demo-carousel__controls {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 0.5rem;
+  margin-block-start: 0.5rem;
+}
+</style>
diff --git a/app/pages/index.vue b/app/pages/index.vue
index 4cad92f0..e0a3d219 100644
--- a/app/pages/index.vue
+++ b/app/pages/index.vue
@@ -11,6 +11,8 @@ import OutcomeClusterGrid from '../components/OutcomeClusterGrid.vue'
 import { AGENT_LOGOS } from '../utils/agent-logos'
 import { MORE_AGENT_COUNT } from '../utils/agent-reach'
 import { homeDemoFeed } from '../utils/home-demos'
+import { shuffled } from '../utils/random-order'
+import HomeDemoCarousel from './_HomeDemoCarousel.vue'
 
 const setupPrompt = agentSetupPrompt()
 const heroAgentsLabel = `Works with ${AGENT_LOGOS.map(agent => agent.label).join(', ')}, and ${MORE_AGENT_COUNT} more Agents`
@@ -106,10 +108,16 @@ if (import.meta.server) {
   serverTimingHeader.value = homeDataTimings.join(', ')
 }
 
-// Lazy: the section sits under the hero, and its images load lazily anyway.
-const { data: demosData } = useLazyFetch('/api/skill-demos', {
-  key: 'home-skill-demos-v2',
-  transform: homeDemoFeed,
+// The lead demo belongs in the server-rendered opening screen.
+const { data: demosData } = await useFetch('/api/skill-demos', {
+  key: 'home-skill-demos-v3',
+  transform: (feed) => {
+    const home = homeDemoFeed(feed)
+    const hero = feed.items.find(demo => demo.owner === 'vojtaholik' && demo.repo === 'good-css' && demo.name === 'good-css') ?? null
+    const candidates = feed.items.filter(demo => demo.makes === 'ui-component' || demo.makes === 'landing-page')
+    const heroDemos = hero ? [hero, ...candidates.filter(demo => demo !== hero)].slice(0, 6) : candidates.slice(0, 6)
+    return { ...home, heroDemos, items: home.items.filter(demo => demo !== hero) }
+  },
 })
 
 // Lazy too: the Why band sits below the fold, and the feed is cached for a day.
@@ -126,6 +134,17 @@ function onAvatarError(owner: string) {
 const trendingBoard = computed(() =>
   (trendingData.value?.board ?? []).filter(row => !missingAvatars.value.has(row.owner)),
 )
+const trendingOrder = ref<string[]>([])
+onMounted(() => {
+  trendingOrder.value = shuffled(trendingBoard.value.map(row => row.key), Math.random)
+})
+const homeTrendingRows = computed(() => {
+  const rows = (trendingData.value?.board ?? [])
+    .map((row, index) => ({ row, rank: index + 1 }))
+    .filter(({ row }) => !missingAvatars.value.has(row.owner))
+  const positions = new Map(trendingOrder.value.map((key, index) => [key, index]))
+  return rows.toSorted((a, b) => (positions.get(a.row.key) ?? a.rank) - (positions.get(b.row.key) ?? b.rank))
+})
 
 /**
  * The section is hidden entirely when the board comes up short. A trending
@@ -223,7 +242,7 @@ function recentRepoDescription(item: RecentRepoUpdate): string {
 
 <template>
   <div class="home-page overflow-clip">
-    <section class="home-hero" aria-labelledby="hero-heading">
+    <section class="home-hero" :class="{ 'home-hero--demo': demosData?.heroDemos.length }" aria-labelledby="hero-heading">
       <!-- The signature, at low strength. Stone only: the H1 full stop is the
            band's one rose dot, so the texture's pick draws in stone. The mask
            keeps a clear column behind the copy. -->
@@ -231,55 +250,66 @@ function recentRepoDescription(item: RecentRepoUpdate): string {
         <TextureBrailleNames :names="heroTextureNames" />
       </div>
 
-      <div class="home-hero__content mx-auto max-w-4xl px-4 text-center sm:px-6">
-        <!-- The rose dot is the full stop. Screen readers get a typed one. -->
-        <h1 id="hero-heading" class="home-hero-title font-semibold tracking-[-0.045em] text-highlighted text-balance">
-          Agent skills for you<br class="hidden sm:inline">
-          and your agent<span class="sr-only">.</span><span class="home-hero-dot" aria-hidden="true" />
-        </h1>
-        <!-- What sets skilld apart, so the caption assumes the reader knows
+      <div
+        class="home-hero__content mx-auto px-4 text-center sm:px-6"
+        :class="demosData?.heroDemos.length ? 'home-hero__content--demo max-w-6xl' : 'max-w-4xl'"
+      >
+        <div class="home-hero__intro">
+          <!-- The rose dot is the full stop. Screen readers get a typed one. -->
+          <h1 id="hero-heading" class="home-hero-title font-semibold tracking-[-0.045em] text-highlighted text-balance">
+            Agent skills for you<br class="hidden sm:inline">
+            and your agent<span class="sr-only">.</span><span class="home-hero-dot" aria-hidden="true" />
+          </h1>
+          <!-- What sets skilld apart, so the caption assumes the reader knows
              what a Skill is. Run comes before install, and the skilld Skill
              behind the promo below lets the agent search on its own. The
              lifecycle band under the hero maps the CLI's verbs. -->
-        <p class="home-hero__caption mx-auto mt-5 text-base leading-relaxed text-muted text-balance">
-          Try any skill before you install it. Your agent can search for its own.
-        </p>
-
-        <HomeSearch class="mx-auto mt-7 max-w-xl text-left" />
-
-        <ul class="home-hero__claims home-hero-claims data-label mx-auto mt-5 list-none p-0" aria-label="About skilld">
-          <li>
-            <a href="https://github.com/skilld-dev/skilld" target="_blank" rel="noopener">Open-source CLI, no telemetry</a>
-          </li>
-          <li>
-            <NuxtLink to="/vs/skills-sh">
-              A skills.sh alternative
-            </NuxtLink>
-          </li>
-          <li>
-            <UPopover :content="{ side: 'bottom', align: 'center', sideOffset: 8 }">
-              <button type="button" class="home-hero__promo">
-                Teach your agent skilld
-                <UIcon name="i-lucide-chevron-down" class="size-3 shrink-0" aria-hidden="true" />
-              </button>
-              <template #content>
-                <div class="home-hero__promo-panel space-y-3 p-3">
-                  <SkilldInstallChip surface="home-hero-promo" />
-                  <p class="text-xs leading-relaxed text-muted">
-                    No terminal? Paste this into your agent.
-                  </p>
-                  <CopyText :text="setupPrompt" label="setup prompt" />
-                </div>
-              </template>
-            </UPopover>
-          </li>
-        </ul>
-
-        <!-- Quiet proof under the claims line. The section it links to names each Agent and the way in. -->
-        <NuxtLink to="#agents" class="home-hero__agents mx-auto mt-5" :aria-label="heroAgentsLabel">
-          <UIcon v-for="agent in AGENT_LOGOS" :key="agent.id" :name="agent.icon" class="size-4 shrink-0" aria-hidden="true" />
-          <span class="data-label" aria-hidden="true">+{{ MORE_AGENT_COUNT }}</span>
-        </NuxtLink>
+          <p class="home-hero__caption mx-auto mt-5 text-base leading-relaxed text-muted text-balance">
+            Try any skill before you install it. Your agent can search for its own.
+          </p>
+
+          <HomeSearch class="mx-auto mt-7 max-w-xl text-left" />
+        </div>
+
+        <div v-if="demosData?.heroDemos.length" class="home-hero__demo text-left">
+          <HomeDemoCarousel :demos="demosData.heroDemos" />
+        </div>
+
+        <div class="home-hero__support">
+          <ul class="home-hero__claims home-hero-claims data-label mx-auto mt-5 list-none p-0" aria-label="About skilld">
+            <li>
+              <a href="https://github.com/skilld-dev/skilld" target="_blank" rel="noopener">Open-source CLI, no telemetry</a>
+            </li>
+            <li>
+              <NuxtLink to="/vs/skills-sh">
+                A skills.sh alternative
+              </NuxtLink>
+            </li>
+            <li>
+              <UPopover :content="{ side: 'bottom', align: 'center', sideOffset: 8 }">
+                <button type="button" class="home-hero__promo">
+                  Teach your agent skilld
+                  <UIcon name="i-lucide-chevron-down" class="size-3 shrink-0" aria-hidden="true" />
+                </button>
+                <template #content>
+                  <div class="home-hero__promo-panel space-y-3 p-3">
+                    <SkilldInstallChip surface="home-hero-promo" />
+                    <p class="text-xs leading-relaxed text-muted">
+                      No terminal? Paste this into your agent.
+                    </p>
+                    <CopyText :text="setupPrompt" label="setup prompt" />
+                  </div>
+                </template>
+              </UPopover>
+            </li>
+          </ul>
+
+          <!-- Quiet proof under the claims line. The section it links to names each Agent and the way in. -->
+          <NuxtLink to="#agents" class="home-hero__agents mx-auto mt-5" :aria-label="heroAgentsLabel">
+            <UIcon v-for="agent in AGENT_LOGOS" :key="agent.id" :name="agent.icon" class="size-4 shrink-0" aria-hidden="true" />
+            <span class="data-label" aria-hidden="true">+{{ MORE_AGENT_COUNT }}</span>
+          </NuxtLink>
+        </div>
       </div>
     </section>
 
@@ -290,9 +320,6 @@ function recentRepoDescription(item: RecentRepoUpdate): string {
       scroll into view, so their code stays out of the scripts the first paint
       waits on.
     -->
-    <!-- The first content section: what Skills make, before any list of them. -->
-    <LazyHomeDemos hydrate-on-visible :demos="demosData?.items ?? []" :total="demosData?.total ?? 0" />
-
     <section
       v-if="showTrending || trendingStatus === 'pending'"
       id="trending"
@@ -316,7 +343,11 @@ function recentRepoDescription(item: RecentRepoUpdate): string {
 
         <template v-else>
           <div class="mt-8">
-            <LazyBoardRankedList hydrate-on-visible :rows="trendingBoard" surface="home-trending-row" @avatar-error="onAvatarError" />
+            <ol class="editorial-ledger list-none p-0">
+              <li v-for="{ row, rank } in homeTrendingRows" :key="row.key">
+                <LazyTrendingBoardItem hydrate-on-visible :row :rank surface="home-trending-row" @avatar-error="onAvatarError" />
+              </li>
+            </ol>
           </div>
           <UButton
             :to="weekBoardPath"
@@ -331,6 +362,8 @@ function recentRepoDescription(item: RecentRepoUpdate): string {
       </div>
     </section>
 
+    <LazyHomeDemos hydrate-on-visible :demos="demosData?.items ?? []" :total="demosData?.total ?? 0" />
+
     <LazyHomeWhy hydrate-on-visible :trending-row="whyTrendingRow" :demos="demosData?.previews ?? []" :pulls="pullsData?.items ?? []" />
 
     <LazyHomeAgents hydrate-on-visible />
@@ -732,6 +765,38 @@ function recentRepoDescription(item: RecentRepoUpdate): string {
   padding-bottom: 4.5rem;
 }
 
+.home-hero__content--demo {
+  display: grid;
+  grid-template-areas: 'intro' 'demo' 'support';
+  gap: 1.5rem;
+}
+
+.home-hero__intro {
+  grid-area: intro;
+  min-inline-size: 0;
+}
+
+.home-hero__demo {
+  grid-area: demo;
+  min-inline-size: 0;
+}
+
+.home-hero__demo :deep(.demo-stage__prompt) {
+  display: -webkit-box;
+  overflow: hidden;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
+}
+
+.home-hero__support {
+  grid-area: support;
+  min-inline-size: 0;
+}
+
 /* Phones and tablets: a strip under the copy, clear of every line of text. */
 .home-hero__texture {
   --brand-dot: var(--ui-text-muted);
@@ -770,6 +835,49 @@ function recentRepoDescription(item: RecentRepoUpdate): string {
       linear-gradient(to bottom, transparent, #000 18%, #000 82%, transparent);
     mask-composite: intersect;
   }
+
+  .home-hero__content--demo {
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+    grid-template-rows: 1fr min-content min-content 1fr;
+    grid-template-areas: '. demo' 'intro demo' 'support demo' '. demo';
+    gap: 1rem 3rem;
+    padding-block: 3rem;
+    align-items: start;
+    text-align: start;
+  }
+
+  .home-hero--demo .home-hero__texture {
+    mask-image:
+      linear-gradient(
+        to right,
+        #000 0,
+        #000 calc(50% - 40rem),
+        transparent calc(50% - 36rem),
+        transparent calc(50% + 36rem),
+        #000 calc(50% + 40rem),
+        #000 100%
+      ),
+      linear-gradient(to bottom, transparent, #000 18%, #000 82%, transparent);
+  }
+
+  .home-hero__content--demo .home-hero-title {
+    font-size: clamp(2.75rem, 4vw, 3.5rem);
+  }
+
+  .home-hero__content--demo .home-hero__caption,
+  .home-hero__content--demo .home-hero__agents {
+    margin-inline: 0;
+  }
+
+  .home-hero__demo :deep(.skill-card--row) {
+    grid-template-columns: minmax(0, 1fr) auto;
+    grid-template-areas: 'id end';
+    column-gap: 1rem;
+  }
+
+  .home-hero__demo :deep(.skill-card__row-end) {
+    margin-block-start: 0;
+  }
 }
 
 /* Inline-block drops the space the template formatter leaves inside a link,
@@ -816,6 +924,17 @@ function recentRepoDescription(item: RecentRepoUpdate): string {
     padding-inline: 0.6em;
     color: var(--ui-text-dimmed);
   }
+
+  .home-hero__content--demo .home-hero__claims {
+    flex-wrap: wrap;
+    justify-content: start;
+    gap: 0.25rem 1rem;
+    margin-top: 0;
+  }
+
+  .home-hero__content--demo .home-hero__claims > li + li::before {
+    content: none;
+  }
 }
 
 .home-hero__agents {
diff --git a/app/utils/random-order.ts b/app/utils/random-order.ts
new file mode 100644
index 00000000..85722b8d
--- /dev/null
+++ b/app/utils/random-order.ts
@@ -0,0 +1,9 @@
+/** Change presentation order while leaving the source data intact. */
+export function shuffled<T>(items: readonly T[], random: () => number): T[] {
+  const result = [...items]
+  for (let index = result.length - 1; index > 0; index--) {
+    const target = Math.floor(random() * (index + 1))
+    ;[result[index], result[target]] = [result[target]!, result[index]!]
+  }
+  return result
+}
diff --git a/docs/runbooks/demo-measurement.md b/docs/runbooks/demo-measurement.md
new file mode 100644
index 00000000..90d2300b
--- /dev/null
+++ b/docs/runbooks/demo-measurement.md
@@ -0,0 +1,63 @@
+# Demo measurement
+
+The anonymous discovery loop measures actions, not identified visitors.
+A copy shows intent. It does not prove that an Agent ran a Skill.
+
+## Events
+
+`POST /api/events/demo` accepts only fixed event shapes.
+It rejects identity fields, task text, unknown fields, and arbitrary campaign names.
+
+An exposure means at least half the output frame entered view.
+Each stage counts each demo once during that page visit.
+A carousel return does not count another exposure.
+Separate stages and reloads count separately.
+
+Agent and terminal copies count only after the clipboard succeeds.
+The Agent prompt includes the recorded task.
+A share count means the demo link was copied, not opened or posted.
+
+Elapsed time uses five buckets: unseen, under 10 seconds, 10 to 29 seconds,
+30 to 119 seconds, and 120 seconds or more.
+The clock starts at the first exposure and includes time away from the tab.
+It measures time before the action, not attention.
+
+Campaign labels are `demo-component`, `demo-page`, and `demo-motion`.
+Any other query value becomes `direct`.
+Links use `?campaign=<label>`. Ordinary share links omit campaign data.
+
+## Analytics Engine layout
+
+The binding is `SKILLD_WEB_ANALYTICS`.
+The first five blob positions retain the existing meanings.
+
+| Position | Demo meaning |
+| --- | --- |
+| blob1 | Surface |
+| blob2 | Empty, no command grammar |
+| blob3 | `demo` |
+| blob4 | `owner/repo/name` |
+| blob5 | Country or `XX` |
+| blob6 | `exposure`, `copy`, or `share` |
+| blob7 | `agent`, `terminal`, or empty |
+| blob8 | Elapsed bucket, empty for exposure |
+| blob9 | Campaign label |
+| double1 | Zero, preserves the existing command copy total |
+| double2 | One demo action |
+
+Existing `/api/events/install` still records the run copy.
+Never add its copy counts to demo copy counts. They describe the same action.
+Use the Analytics Engine sample weight when summing counts.
+
+## Seven-day comparison
+
+After deployment, collect seven full UTC days before comparing changes.
+Group exposure, copy, and share counts by surface, demo, and campaign.
+Report copies per 100 exposures and link copies per 100 exposures.
+These are action rates and may exceed 100 with repeat copying.
+
+Keep the production ranking weights fixed during the comparison.
+Homepage display order may vary, but each row keeps its original rank.
+Record deployment times beside the aggregate export.
+Change one surface per comparison, then collect another seven full days.
+A local preview cannot establish conversion lift or campaign performance.
diff --git a/layers/marketing/app/components/BoardShell.vue b/layers/marketing/app/components/BoardShell.vue
index cdcded59..659626a0 100644
--- a/layers/marketing/app/components/BoardShell.vue
+++ b/layers/marketing/app/components/BoardShell.vue
@@ -12,7 +12,7 @@ import TrendingWeeklyCta from './TrendingWeeklyCta.vue'
  * invitation, and the install chip under it. The board places the narrow
  * screen's copy of the invitation itself; see `BoardRankedList`.
  */
-const { headingId, surface, showWeeklyCta, ctaPending } = defineProps<{
+const { headingId, surface, showWeeklyCta, ctaPending, contentFirst = false } = defineProps<{
   /** The page's `<h1>` id, which names the header and the board. */
   headingId: string
   /** Analytics prefix for the install chip, such as `trending`. */
@@ -21,6 +21,8 @@ const { headingId, surface, showWeeklyCta, ctaPending } = defineProps<{
   showWeeklyCta: boolean
   /** The session has not loaded, so the invitation holds its space unseen. */
   ctaPending: boolean
+  /** Lead with a selected result before navigation on narrow screens. */
+  contentFirst?: boolean
 }>()
 </script>
 
@@ -30,7 +32,7 @@ const { headingId, surface, showWeeklyCta, ctaPending } = defineProps<{
       <header :aria-labelledby="headingId" class="mx-auto mb-7 max-w-7xl lg:ml-56 lg:mr-0">
         <slot name="header" />
         <!-- Narrow screens have no sidebar, so the install sits under the heading. -->
-        <div class="mt-5 lg:hidden">
+        <div v-if="!contentFirst" class="mt-5 lg:hidden">
           <div class="board-teach">
             <p class="font-mono text-xs text-muted">
               Teach your agent skilld
@@ -41,7 +43,11 @@ const { headingId, surface, showWeeklyCta, ctaPending } = defineProps<{
       </header>
 
       <div class="board-layout relative grid items-start gap-6 lg:grid-cols-[14rem_minmax(0,1fr)] lg:gap-8">
-        <div class="board-sidebar">
+        <section v-if="contentFirst" class="min-w-0 lg:col-start-2 lg:row-start-1 lg:pt-6" :aria-labelledby="headingId">
+          <slot />
+        </section>
+
+        <div class="board-sidebar lg:col-start-1 lg:row-start-1">
           <slot name="sidebar" />
 
           <!--
@@ -52,7 +58,7 @@ const { headingId, surface, showWeeklyCta, ctaPending } = defineProps<{
             so it carries no `aria-hidden`, which HTML validation rejects over
             a link.
           -->
-          <div class="board-sidebar__foot">
+          <div class="board-sidebar__foot" :class="{ 'board-sidebar__foot--visible': contentFirst }">
             <div v-if="showWeeklyCta" :class="{ invisible: ctaPending }">
               <TrendingWeeklyCta variant="rail" />
             </div>
@@ -72,7 +78,7 @@ const { headingId, surface, showWeeklyCta, ctaPending } = defineProps<{
           <slot name="sidebar-end" />
         </div>
 
-        <section class="min-w-0 lg:pt-6" :aria-labelledby="headingId">
+        <section v-if="!contentFirst" class="min-w-0 lg:pt-6" :aria-labelledby="headingId">
           <slot />
         </section>
       </div>
@@ -100,6 +106,13 @@ const { headingId, surface, showWeeklyCta, ctaPending } = defineProps<{
 
 .board-sidebar__foot {
   display: none;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 1.5rem;
+  margin-block-start: 2rem;
+}
+
+.board-sidebar__foot--visible {
+  display: grid;
 }
 
 .board-teach {
@@ -128,9 +141,6 @@ const { headingId, surface, showWeeklyCta, ctaPending } = defineProps<{
 
   .board-sidebar__foot {
     display: grid;
-    grid-template-columns: minmax(0, 1fr);
-    gap: 1.5rem;
-    margin-block-start: 2rem;
   }
 }
 </style>
diff --git a/layers/marketing/app/pages/skills/demos/[...demo].vue b/layers/marketing/app/pages/skills/demos/[...demo].vue
index 0ec770cd..321d785e 100644
--- a/layers/marketing/app/pages/skills/demos/[...demo].vue
+++ b/layers/marketing/app/pages/skills/demos/[...demo].vue
@@ -128,7 +128,7 @@ else {
 </script>
 
 <template>
-  <BoardShell heading-id="demos-heading" surface="demos" :show-weekly-cta="false" :cta-pending="false">
+  <BoardShell heading-id="demos-heading" surface="demos" :show-weekly-cta="false" :cta-pending="false" :content-first="!!pageDemo">
     <template #header>
       <h1 id="demos-heading" class="text-3xl font-semibold tracking-tight text-balance">
         {{ pageDemo ? `What /${pageDemo.name} made` : 'See what skills make' }}
diff --git a/layers/marketing/content/pages/privacy.md b/layers/marketing/content/pages/privacy.md
index bede13e4..271c5d42 100644
--- a/layers/marketing/content/pages/privacy.md
+++ b/layers/marketing/content/pages/privacy.md
@@ -1,14 +1,14 @@
 ---
 title: Privacy
 description: What skilld.dev stores, why it needs the data, how long it keeps it, and how you delete your account.
-label: Last updated 7 October 2026
-updatedAt: 2026-10-07
+label: Last updated 8 October 2026
+updatedAt: 2026-10-08
 ---
 
 ## In short
 
 - You can browse skilld.dev and run Skills without an account.
-- skilld.dev counts page views and command copies. The counts hold no name, IP address, or cookie. It loads no advertising scripts.
+- skilld.dev counts page views, demo views, command copies, and demo link copies. The counts hold no name, IP address, or cookie. It loads no advertising scripts.
 - An account is optional. You sign in with [GitHub](https://github.com) to like Skills, watch Repositories, get email, or connect the skilld CLI.
 - You can delete your account from your dashboard at any time.
 - The skilld CLI sends no telemetry.
@@ -46,6 +46,8 @@ When you copy a printed command, your browser tells skilld.dev. skilld stores on
 
 That count goes to [Cloudflare Analytics Engine](https://developers.cloudflare.com/analytics/analytics-engine/), which keeps it for 90 days. It holds no IP address, no cookie, and no account ID, so a count cannot be traced to you or joined to your account. skilld keeps no record of an individual copy.
 
+Demo counts also record the displayed demo, the surface, and whether you copied an Agent prompt, a terminal command, or a demo link. A view counts when at least half the output frame is visible. Each demo counts once per stage during that page visit. Copy counts include a coarse time bucket since the frame first became visible, and one of three fixed campaign labels when the page link supplies it. They hold no task text, full query string, visitor identifier, or exact elapsed time. These counts use the same 90-day Analytics Engine storage.
+
 The skilld CLI sends no telemetry. skilld.dev accepts an anonymous run count from a CLI at the same address, under the same rules, and drops any account ID the request carries.
 
 ### Cookies
diff --git a/server/api/events/demo.post.ts b/server/api/events/demo.post.ts
new file mode 100644
index 00000000..544b7f64
--- /dev/null
+++ b/server/api/events/demo.post.ts
@@ -0,0 +1,16 @@
+import { presentDemoEngagement } from '~~/server/presenters/demo-engagement'
+import { DemoEngagementInput } from '~~/server/schemas/demo-engagement'
+import { analyticsCountry } from '#shared/analytics'
+import { demoEngagementDataPoint } from '#shared/demo-engagement'
+import { defineApiHandler } from '#shared/server/handler'
+
+export default defineApiHandler({
+  schema: DemoEngagementInput,
+  handler: async ({ event, body, platform }) => {
+    const dataset = platform.env.SKILLD_WEB_ANALYTICS
+    if (!dataset)
+      throw createError({ statusCode: 500, message: 'Analytics Engine binding missing' })
+    dataset.writeDataPoint(demoEngagementDataPoint(body, analyticsCountry(getHeader(event, 'cf-ipcountry'))))
+  },
+  presenter: presentDemoEngagement,
+})
diff --git a/server/presenters/demo-engagement.ts b/server/presenters/demo-engagement.ts
new file mode 100644
index 00000000..2c59bd47
--- /dev/null
+++ b/server/presenters/demo-engagement.ts
@@ -0,0 +1,3 @@
+export function presentDemoEngagement() {
+  return { ok: true as const }
+}
diff --git a/server/schemas/demo-engagement.ts b/server/schemas/demo-engagement.ts
new file mode 100644
index 00000000..f0c4435d
--- /dev/null
+++ b/server/schemas/demo-engagement.ts
@@ -0,0 +1,13 @@
+import { z } from 'zod'
+
+const context = {
+  surface: z.enum(['home-hero-demo', 'home-demos', 'demos', 'demos-page']),
+  slug: z.string().max(384).regex(/^[\w.-]+\/[\w.-]+\/[\w.-]+$/),
+  campaign: z.enum(['direct', 'demo-component', 'demo-page', 'demo-motion']),
+}
+const elapsed = z.enum(['unseen', 'under-10s', '10-29s', '30-119s', '120s-plus'])
+export const DemoEngagementInput = z.discriminatedUnion('event', [
+  z.object({ ...context, event: z.literal('exposure') }).strict(),
+  z.object({ ...context, event: z.literal('share'), elapsed }).strict(),
+  z.object({ ...context, event: z.literal('copy'), format: z.enum(['agent', 'terminal']), elapsed }).strict(),
+])
diff --git a/shared/demo-engagement.ts b/shared/demo-engagement.ts
new file mode 100644
index 00000000..089bf22c
--- /dev/null
+++ b/shared/demo-engagement.ts
@@ -0,0 +1,35 @@
+import type { AnalyticsDataPoint } from './analytics'
+import { analyticsIndex } from './analytics'
+
+export type DemoCampaign = 'direct' | 'demo-component' | 'demo-page' | 'demo-motion'
+export type DemoElapsed = 'unseen' | 'under-10s' | '10-29s' | '30-119s' | '120s-plus'
+interface DemoContext { surface: string, slug: string, campaign: DemoCampaign }
+export type DemoEngagement = DemoContext & (
+  | { event: 'exposure' }
+  | { event: 'share', elapsed: DemoElapsed }
+  | { event: 'copy', format: 'agent' | 'terminal', elapsed: DemoElapsed }
+)
+
+export function demoElapsedBucket(milliseconds: number | null): DemoElapsed {
+  if (milliseconds === null)
+    return 'unseen'
+  if (milliseconds < 10000)
+    return 'under-10s'
+  if (milliseconds < 30000)
+    return '10-29s'
+  return milliseconds < 120000 ? '30-119s' : '120s-plus'
+}
+
+/** Preserve the five existing blob meanings and double 1, the command copy count. */
+export function demoEngagementDataPoint(event: DemoEngagement, country: string): AnalyticsDataPoint {
+  return {
+    blobs: [event.surface, '', 'demo', event.slug, country, event.event, event.event === 'copy' ? event.format : '', event.event === 'exposure' ? '' : event.elapsed, event.campaign],
+    doubles: [0, 1],
+    indexes: [analyticsIndex(event.slug)],
+  }
+}
+
+/** An observer also reports initial entries below its threshold. */
+export function demoFrameIsVisible(entry: { isIntersecting: boolean, intersectionRatio: number } | undefined): boolean {
+  return !!entry?.isIntersecting && entry.intersectionRatio >= 0.5
+}
diff --git a/test/a11y.nuxt.spec.ts b/test/a11y.nuxt.spec.ts
index f4ad24e6..ae03eba3 100644
--- a/test/a11y.nuxt.spec.ts
+++ b/test/a11y.nuxt.spec.ts
@@ -653,6 +653,14 @@ describe('accessibility: components', () => {
     expect(picks[1]?.getAttribute('aria-pressed')).toBe('true')
     expect(stage()).toBe('/skills/demos/anthropics/skills/two')
     expect(container.querySelector('a[href="/skills/demos"]')?.textContent).toContain('All 42 demos')
+    const run = container.querySelector<HTMLButtonElement>('.demo-actions__run')!
+    run.click()
+    await nextTick()
+    await new Promise(done => setTimeout(done, 400))
+    const panel = document.querySelector<HTMLElement>('.demo-actions__panel')!
+    expect(panel).not.toBeNull()
+    const panelResults = await runAxe(panel)
+    expect(panelResults.violations, formatViolations(panelResults)).toHaveLength(0)
     wrapper.unmount()
   })
 
@@ -993,6 +1001,7 @@ describe('accessibility: component coverage', () => {
     'StatsLeaderboard', // Tested at page level
     'UiTooltip', // Wrapper around UTooltip, exercised by parent components
     '_ChipSwitch', // The switch above RunChip and CliInstallChip, axe-scanned and clicked through both
+    '_DemoActions', // DemoStage actions, scanned inside HomeDemos and DemoIndex; the open popover is checked in the browser
     'DemoStage', // The stage DemoIndex and /skills/demos render, scanned inside the HomeDemos and DemoIndex tests
     'home-demos/_DemoMedia', // A part of HomeDemos, scanned inside the HomeDemos tests
     'home-demos/_DemoPicture', // A part of HomeDemos, scanned inside the HomeDemos tests
diff --git a/test/unit/demo-engagement.test.ts b/test/unit/demo-engagement.test.ts
new file mode 100644
index 00000000..ff48c73b
--- /dev/null
+++ b/test/unit/demo-engagement.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { DemoEngagementInput } from '../../server/schemas/demo-engagement'
+import { demoElapsedBucket, demoEngagementDataPoint, demoFrameIsVisible } from '../../shared/demo-engagement'
+
+describe('anonymous demo engagement', () => {
+  const base = { surface: 'home-hero-demo', slug: 'heyimjames/skills/good-css', campaign: 'direct' as const }
+  it('keeps demo counts separate from existing command copy counts', () => {
+    expect(demoEngagementDataPoint({ ...base, event: 'copy', format: 'agent', elapsed: '10-29s' }, 'AU')).toEqual({
+      blobs: ['home-hero-demo', '', 'demo', base.slug, 'AU', 'copy', 'agent', '10-29s', 'direct'],
+      doubles: [0, 1],
+      indexes: [base.slug],
+    })
+  })
+  it('rejects identity, prompt text, arbitrary campaigns, and invalid copy formats', () => {
+    const point = { ...base, event: 'exposure' }
+    expect(DemoEngagementInput.safeParse(point).success).toBe(true)
+    for (const extra of [{ userId: '12' }, { prompt: 'private task' }, { campaign: 'private-user' }, { format: 'agent' }])
+      expect(DemoEngagementInput.safeParse({ ...point, ...extra }).success).toBe(false)
+    expect(DemoEngagementInput.safeParse({ ...base, event: 'copy', format: 'unknown', elapsed: 'under-10s' }).success).toBe(false)
+    expect(DemoEngagementInput.safeParse({ ...point, slug: '' }).success).toBe(false)
+  })
+  it('stores only coarse time buckets, including actions before exposure', () => {
+    expect([null, 0, 9999, 10000, 30000, 120000].map(demoElapsedBucket)).toEqual(['unseen', 'under-10s', 'under-10s', '10-29s', '30-119s', '120s-plus'])
+  })
+})
+
+describe('demo exposure boundary', () => {
+  it('requires half the frame in view before counting an exposure', () => {
+    expect(demoFrameIsVisible({ isIntersecting: true, intersectionRatio: 0.1 })).toBe(false)
+    expect(demoFrameIsVisible({ isIntersecting: true, intersectionRatio: 0.5 })).toBe(true)
+    expect(demoFrameIsVisible({ isIntersecting: false, intersectionRatio: 1 })).toBe(false)
+    expect(demoFrameIsVisible(undefined)).toBe(false)
+  })
+})
diff --git a/test/unit/random-order.test.ts b/test/unit/random-order.test.ts
new file mode 100644
index 00000000..2c8e8bc2
--- /dev/null
+++ b/test/unit/random-order.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest'
+import { shuffled } from '../../app/utils/random-order'
+
+describe('shuffled', () => {
+  it('changes display order without changing ranks or the source list', () => {
+    const rows = [{ name: 'a', rank: 1 }, { name: 'b', rank: 2 }, { name: 'c', rank: 3 }]
+    expect(shuffled(rows, () => 0)).toEqual([rows[1], rows[2], rows[0]])
+    expect(rows).toEqual([{ name: 'a', rank: 1 }, { name: 'b', rank: 2 }, { name: 'c', rank: 3 }])
+  })
+
+  it('keeps every entry exactly once across different random sequences', () => {
+    for (const value of [0, 0.25, 0.5, 0.999])
+      expect(shuffled(['a', 'b', 'c', 'd'], () => value).sort()).toEqual(['a', 'b', 'c', 'd'])
+    expect(shuffled([], () => 0)).toEqual([])
+    expect(shuffled(['a'], () => 0)).toEqual(['a'])
+  })
+})

From 23e267fd2a7a20f7351f8ad755d7dd00ce5d59f2 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Fri, 9 Oct 2026 00:20:36 +1100
Subject: [PATCH 2/4] style(home): simplify hero and shorten demo pages

---
 COPY.md                                       |  3 +-
 app/components/DemoStage.vue                  | 51 +++++++++++++++++--
 app/pages/_HomeDemoCarousel.vue               |  2 +-
 app/pages/index.vue                           | 13 +----
 .../app/pages/skills/demos/[...demo].vue      |  2 +-
 5 files changed, 51 insertions(+), 20 deletions(-)

diff --git a/COPY.md b/COPY.md
index ff303fcd..a9a3e9fd 100644
--- a/COPY.md
+++ b/COPY.md
@@ -45,8 +45,9 @@ These exact strings. Do not paraphrase them per page.
 | Demo page | What /{name} made · One recorded run: the prompt, and what the Agent built with the Skill. | guidance only: the H1 and line of a demo page, `/skills/demos/<owner>/<repo>/<name>`. The meta title is "{name} skill example: {noun}" for the query "<skill> skill example", with `noun` from `DEMO_GROUPS`. The meta description is "{agent} made this {noun} with the /{name} skill from one prompt: “{prompt}”", cut at a word to 160 characters |
 | Demo groups | Films and launch videos · Landing pages · UI components · Diagrams and explainers | guidance only: `DEMO_GROUPS` in `shared/demo-groups.ts`: the `/skills/demos` group headings and their lines |
 | Demo actions | Run it yourself · Agent prompt · Terminal · Copy Agent prompt · Copy command · Copied · Copy demo link · Copied demo link | guidance only: demo stages. The Agent prompt includes the recorded task. The terminal option loads the Skill. Run is hidden on phones. |
-| Demo stage | Open the demo | guidance only: the demo stage link. On the homepage it opens the demo page; on a demo page it opens the Skill page Demo panel |
+| Demo stage | Open the demo | guidance only: the demo stage link. The hero shows the output, author row, and this link only. On the homepage it opens the demo page; on a demo page it opens the Skill page Demo panel |
 | Home demo carousel | Previous demo · Next demo · {n} of {total} | guidance only: the manual homepage demo controls. The position is live text for screen readers. |
+| Demo page prompt | Prompt | guidance only: the selected demo page keeps its recorded task in an expandable disclosure above the shorter output frame. |
 | Demo panel | Demo · Prompt · Open live demo · Open in a new tab · Run it yourself · All demos | guidance only: the Skill page Demo panel. "Show screenshots" replaces "Open live demo" while the live output shows. "All demos" opens the demo page. It hides for a Skill page only demo, and while the Skill holds a run check flag |
 | Demo provenance | {Agent logo} {model}, {effort} effort | guidance only: the recording line on the Skill page panel and the homepage stage. Screen readers and the title get "Recorded with {agent}, {model}, {effort} effort". Omit effort when the recording has no evidence for it. No date and no GitHub link: the Skill page is where visitors inspect a Skill |
 | Demo outdated | Recorded on an older version of this Skill. | guidance only: under the Demo panel when the Skill moved past the recorded commit |
diff --git a/app/components/DemoStage.vue b/app/components/DemoStage.vue
index 1cf8abbc..a09af87a 100644
--- a/app/components/DemoStage.vue
+++ b/app/components/DemoStage.vue
@@ -17,8 +17,9 @@ import SkillCard from './SkillCard.vue'
  * "Open the demo" goes: the demo's own page, or, on that page, the Skill
  * page's Demo panel.
  */
-const { demo, surface = 'demos', eager = false, showPrompt = false, live = false, opens = 'demo-page' } = defineProps<{
+const { demo, surface = 'demos', eager = false, showPrompt = false, live = false, opens = 'demo-page', presentation = 'full' } = defineProps<{
   demo: HomeDemoItem
+  presentation?: 'full' | 'hero' | 'compact'
   /** The analytics surface for the run chip, such as `home-demos`. */
   surface?: string
   eager?: boolean
@@ -34,15 +35,23 @@ const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
 </script>
 
 <template>
-  <div class="demo-stage">
-    <div class="demo-stage__head">
+  <div class="demo-stage" :class="{ 'demo-stage--compact': presentation === 'compact' }">
+    <div v-if="presentation !== 'hero'" class="demo-stage__head">
       <DemoRecording :demo />
       <NuxtLink :to="opens === 'skill-page' ? demoHref(demo) : demoPagePath(demo)" class="demo-stage__open">
         Open the demo<span class="sr-only"> of /{{ demo.name }}</span>
         <UIcon name="i-lucide-arrow-right" class="size-3.5 shrink-0" aria-hidden="true" />
       </NuxtLink>
     </div>
-    <p v-if="showPrompt" class="demo-stage__prompt">
+    <details v-if="showPrompt && presentation === 'compact'" class="demo-stage__task">
+      <summary class="data-label">
+        Prompt
+      </summary>
+      <p class="demo-stage__prompt">
+        {{ demo.prompt }}
+      </p>
+    </details>
+    <p v-else-if="showPrompt && presentation !== 'hero'" class="demo-stage__prompt">
       <span class="data-label mr-2">Prompt</span>{{ demo.prompt }}
     </p>
     <!-- The whole page, in a window one screen tall. A film fills the window and plays on view. -->
@@ -78,7 +87,11 @@ const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
         :actions="[]"
         :surface
       />
-      <DemoActions :demo :surface @action="record" />
+      <NuxtLink v-if="presentation === 'hero'" :to="demoPagePath(demo)" class="demo-stage__open" :aria-label="`Open the demo of /${demo.name}`">
+        Open the demo
+        <UIcon name="i-lucide-arrow-right" class="size-3.5 shrink-0" aria-hidden="true" />
+      </NuxtLink>
+      <DemoActions v-else :demo :surface @action="record" />
     </div>
   </div>
 </template>
@@ -167,6 +180,34 @@ const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
   }
 }
 
+/* Selected demo pages leave room for the author and actions below the output. */
+.demo-stage--compact .demo-stage__window {
+  block-size: clamp(14rem, 40svh, 26rem);
+  aspect-ratio: auto;
+}
+
+.demo-stage--compact .demo-stage__window[data-film] {
+  block-size: auto;
+  aspect-ratio: var(--video-w) / var(--video-h);
+  inline-size: min(100%, calc(40svh * var(--video-w) / var(--video-h)));
+}
+
+.demo-stage__task {
+  margin-block-end: 0.75rem;
+}
+
+.demo-stage__task summary {
+  display: list-item;
+  min-block-size: 2.75rem;
+  padding-block: 0.75rem;
+  cursor: pointer;
+}
+
+.demo-stage__task summary:focus-visible {
+  outline: 2px solid var(--ui-border-accented);
+  outline-offset: 2px;
+}
+
 /* The live page scrolls inside its own frame. */
 .demo-stage__window[data-live] {
   overflow: hidden;
diff --git a/app/pages/_HomeDemoCarousel.vue b/app/pages/_HomeDemoCarousel.vue
index 237b1ad1..7361c8ff 100644
--- a/app/pages/_HomeDemoCarousel.vue
+++ b/app/pages/_HomeDemoCarousel.vue
@@ -22,7 +22,7 @@ function move(direction: -1 | 1): void {
 <template>
   <div v-if="current" class="home-demo-carousel">
     <div :id="stageId">
-      <DemoStage :demo="current" eager show-prompt surface="home-hero-demo" />
+      <DemoStage :demo="current" eager presentation="hero" surface="home-hero-demo" />
     </div>
     <div v-if="order.length > 1" class="home-demo-carousel__controls">
       <UButton
diff --git a/app/pages/index.vue b/app/pages/index.vue
index e0a3d219..bc2ba1af 100644
--- a/app/pages/index.vue
+++ b/app/pages/index.vue
@@ -781,17 +781,6 @@ function recentRepoDescription(item: RecentRepoUpdate): string {
   min-inline-size: 0;
 }
 
-.home-hero__demo :deep(.demo-stage__prompt) {
-  display: -webkit-box;
-  overflow: hidden;
-  padding: 0;
-  border: 0;
-  background: transparent;
-  -webkit-box-orient: vertical;
-  -webkit-line-clamp: 2;
-  line-clamp: 2;
-}
-
 .home-hero__support {
   grid-area: support;
   min-inline-size: 0;
@@ -840,7 +829,7 @@ function recentRepoDescription(item: RecentRepoUpdate): string {
     grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
     grid-template-rows: 1fr min-content min-content 1fr;
     grid-template-areas: '. demo' 'intro demo' 'support demo' '. demo';
-    gap: 1rem 3rem;
+    gap: 1rem 4rem;
     padding-block: 3rem;
     align-items: start;
     text-align: start;
diff --git a/layers/marketing/app/pages/skills/demos/[...demo].vue b/layers/marketing/app/pages/skills/demos/[...demo].vue
index 321d785e..03ceb191 100644
--- a/layers/marketing/app/pages/skills/demos/[...demo].vue
+++ b/layers/marketing/app/pages/skills/demos/[...demo].vue
@@ -175,7 +175,7 @@ else {
 
     <div id="demos-stage" ref="stage" class="demos-stage scroll-mt-24">
       <Transition name="demos-swap" mode="out-in">
-        <DemoStage v-if="current" :key="currentKey" :demo="current" show-prompt live eager opens="skill-page" surface="demos-page" />
+        <DemoStage v-if="current" :key="currentKey" :demo="current" :presentation="pageDemo ? 'compact' : 'full'" show-prompt live eager opens="skill-page" surface="demos-page" />
       </Transition>
       <p v-if="!current" class="text-sm text-muted">
         No demos are published yet.

From 8aefadd613ede80344137c845d35ffd18090eda4 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Fri, 9 Oct 2026 00:55:24 +1100
Subject: [PATCH 3/4] style(demos): grow frames and keep actions in reach

---
 app/components/DemoStage.vue | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/app/components/DemoStage.vue b/app/components/DemoStage.vue
index a09af87a..3f319a74 100644
--- a/app/components/DemoStage.vue
+++ b/app/components/DemoStage.vue
@@ -180,16 +180,25 @@ const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
   }
 }
 
-/* Selected demo pages leave room for the author and actions below the output. */
+/* Give interactive pages most of the screen, while keeping their actions in reach. */
 .demo-stage--compact .demo-stage__window {
-  block-size: clamp(14rem, 40svh, 26rem);
+  block-size: clamp(24rem, 68svh, 52rem);
   aspect-ratio: auto;
 }
 
 .demo-stage--compact .demo-stage__window[data-film] {
   block-size: auto;
   aspect-ratio: var(--video-w) / var(--video-h);
-  inline-size: min(100%, calc(40svh * var(--video-w) / var(--video-h)));
+  inline-size: min(100%, calc(68svh * var(--video-w) / var(--video-h)));
+}
+
+.demo-stage--compact .demo-stage__id {
+  position: sticky;
+  inset-block-end: 0;
+  z-index: 2;
+  border-block-start: 1px solid var(--ui-border);
+  background: var(--ui-bg);
+  padding-block-end: env(safe-area-inset-bottom, 0px);
 }
 
 .demo-stage__task {

From 84a3745d52cf595e087d9c66851cc934f725062e Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Fri, 9 Oct 2026 01:42:49 +1100
Subject: [PATCH 4/4] feat(demos): compact prompt and show recorded token usage

---
 COPY.md                                      |  3 +-
 app/components/DemoStage.vue                 | 60 +++++++++++++++----
 app/components/home-demos/_DemoRecording.vue | 14 ++++-
 app/utils/home-demos.ts                      | 22 +++++--
 docs/runbooks/demo-measurement.md            | 11 ++++
 layers/registry/server/data/skill-demos.json | 63 +++++++++++++++++---
 layers/registry/server/utils/skill-demos.ts  |  5 ++
 scripts/record-skill-demo.ts                 |  4 ++
 shared/demo-usage.ts                         | 31 ++++++++++
 test/unit/demo-usage.test.ts                 | 19 ++++++
 test/unit/home-demos.test.ts                 | 17 ++++++
 test/unit/skill-demos.test.ts                |  8 +++
 12 files changed, 227 insertions(+), 30 deletions(-)
 create mode 100644 shared/demo-usage.ts
 create mode 100644 test/unit/demo-usage.test.ts

diff --git a/COPY.md b/COPY.md
index a9a3e9fd..2223ddd1 100644
--- a/COPY.md
+++ b/COPY.md
@@ -47,8 +47,9 @@ These exact strings. Do not paraphrase them per page.
 | Demo actions | Run it yourself · Agent prompt · Terminal · Copy Agent prompt · Copy command · Copied · Copy demo link · Copied demo link | guidance only: demo stages. The Agent prompt includes the recorded task. The terminal option loads the Skill. Run is hidden on phones. |
 | Demo stage | Open the demo | guidance only: the demo stage link. The hero shows the output, author row, and this link only. On the homepage it opens the demo page; on a demo page it opens the Skill page Demo panel |
 | Home demo carousel | Previous demo · Next demo · {n} of {total} | guidance only: the manual homepage demo controls. The position is live text for screen readers. |
-| Demo page prompt | Prompt | guidance only: the selected demo page keeps its recorded task in an expandable disclosure above the shorter output frame. |
+| Demo page prompt | Prompt | guidance only: the selected demo page keeps its recorded task in an expandable disclosure beside the model and effort, above the output frame. |
 | Demo panel | Demo · Prompt · Open live demo · Open in a new tab · Run it yourself · All demos | guidance only: the Skill page Demo panel. "Show screenshots" replaces "Open live demo" while the live output shows. "All demos" opens the demo page. It hides for a Skill page only demo, and while the Skill holds a run check flag |
+| Demo token usage | {n} tokens · Input: {input}; cached input: {cached}; output: {output} | guidance only: recording metadata. Counts come from recorded usage. Cached input is included in input. Omit unavailable counts. |
 | Demo provenance | {Agent logo} {model}, {effort} effort | guidance only: the recording line on the Skill page panel and the homepage stage. Screen readers and the title get "Recorded with {agent}, {model}, {effort} effort". Omit effort when the recording has no evidence for it. No date and no GitHub link: the Skill page is where visitors inspect a Skill |
 | Demo outdated | Recorded on an older version of this Skill. | guidance only: under the Demo panel when the Skill moved past the recorded commit |
 | Home section: changes | Keep up with skill changes. | guidance only: the homepage section heading for watching and the digest |
diff --git a/app/components/DemoStage.vue b/app/components/DemoStage.vue
index 3f319a74..6ac74fb3 100644
--- a/app/components/DemoStage.vue
+++ b/app/components/DemoStage.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import type { HomeDemoItem } from '~/utils/home-demos'
 import { demoPagePath } from '#shared/demo-pages'
-import { demoCardSkill, demoHasPhoneFrame, demoHref, demoPhoneRatio } from '~/utils/home-demos'
+import { demoCardSkill, demoHasPhoneFrame, demoHref, demoPhoneRatio, demoRecording } from '~/utils/home-demos'
 import DemoActions from './_DemoActions.vue'
 import DemoMedia from './home-demos/_DemoMedia.vue'
 import DemoRecording from './home-demos/_DemoRecording.vue'
@@ -31,27 +31,32 @@ const { demo, surface = 'demos', eager = false, showPrompt = false, live = false
 /** The output page itself, when this stage shows it live. A film always plays as video. */
 const stage = useTemplateRef<HTMLElement>('stage')
 const { record } = useDemoEngagement(() => `${demo.owner}/${demo.repo}/${demo.name}`, surface, stage)
+const recording = computed(() => demoRecording(demo))
 const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
 </script>
 
 <template>
   <div class="demo-stage" :class="{ 'demo-stage--compact': presentation === 'compact' }">
     <div v-if="presentation !== 'hero'" class="demo-stage__head">
-      <DemoRecording :demo />
+      <details v-if="showPrompt && presentation === 'compact'" class="demo-stage__task">
+        <summary class="data-label">
+          <span>Prompt</span>
+          <DemoRecording :demo />
+        </summary>
+        <p v-if="recording.usage" class="data-label demo-stage__usage">
+          {{ recording.usage.sentence }}
+        </p>
+        <p class="demo-stage__prompt">
+          {{ demo.prompt }}
+        </p>
+      </details>
+      <DemoRecording v-else :demo />
       <NuxtLink :to="opens === 'skill-page' ? demoHref(demo) : demoPagePath(demo)" class="demo-stage__open">
         Open the demo<span class="sr-only"> of /{{ demo.name }}</span>
         <UIcon name="i-lucide-arrow-right" class="size-3.5 shrink-0" aria-hidden="true" />
       </NuxtLink>
     </div>
-    <details v-if="showPrompt && presentation === 'compact'" class="demo-stage__task">
-      <summary class="data-label">
-        Prompt
-      </summary>
-      <p class="demo-stage__prompt">
-        {{ demo.prompt }}
-      </p>
-    </details>
-    <p v-else-if="showPrompt && presentation !== 'hero'" class="demo-stage__prompt">
+    <p v-if="showPrompt && presentation === 'full'" class="demo-stage__prompt">
       <span class="data-label mr-2">Prompt</span>{{ demo.prompt }}
     </p>
     <!-- The whole page, in a window one screen tall. A film fills the window and plays on view. -->
@@ -201,17 +206,46 @@ const liveUrl = computed(() => live && !demo.video ? demo.liveUrl : null)
   padding-block-end: env(safe-area-inset-bottom, 0px);
 }
 
+.demo-stage--compact .demo-stage__head {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: start;
+}
+
+.demo-stage--compact .demo-stage__open {
+  grid-area: 1 / 2;
+}
+
 .demo-stage__task {
-  margin-block-end: 0.75rem;
+  grid-area: 1 / 1 / auto / -1;
 }
 
 .demo-stage__task summary {
-  display: list-item;
+  display: flex;
+  align-items: baseline;
+  gap: 0.75rem;
+  padding-inline-end: 8rem;
   min-block-size: 2.75rem;
   padding-block: 0.75rem;
   cursor: pointer;
 }
 
+.demo-stage__usage {
+  margin-block: 0.5rem;
+}
+
+.demo-stage__task summary::before {
+  content: '▸';
+}
+
+.demo-stage__task[open] summary::before {
+  content: '▾';
+}
+
+.demo-stage__task :deep(.demo-recording__part) {
+  white-space: normal;
+}
+
 .demo-stage__task summary:focus-visible {
   outline: 2px solid var(--ui-border-accented);
   outline-offset: 2px;
diff --git a/app/components/home-demos/_DemoRecording.vue b/app/components/home-demos/_DemoRecording.vue
index 64516235..02785d69 100644
--- a/app/components/home-demos/_DemoRecording.vue
+++ b/app/components/home-demos/_DemoRecording.vue
@@ -13,9 +13,15 @@ const recording = computed(() => demoRecording(demo))
 
 <template>
   <span class="demo-recording" :title="recording.sentence">
-    <UIcon :name="recording.icon" class="demo-recording__icon" aria-hidden="true" />
-    <span class="demo-recording__part" aria-hidden="true">{{ recording.model }}</span>
+    <span class="demo-recording__part" aria-hidden="true">
+      <UIcon :name="recording.icon" class="demo-recording__icon" aria-hidden="true" />
+      {{ recording.model }}
+    </span>
     <span class="sr-only">{{ recording.sentence }}</span>
+    <span v-if="recording.usage" class="demo-recording__usage" :title="recording.usage.sentence">
+      <span aria-hidden="true">{{ recording.usage.label }}</span>
+      <span class="sr-only">{{ recording.usage.label }}. {{ recording.usage.sentence }}</span>
+    </span>
   </span>
 </template>
 
@@ -38,7 +44,9 @@ const recording = computed(() => demoRecording(demo))
 }
 
 .demo-recording__icon {
-  flex: none;
+  display: inline-block;
+  vertical-align: -0.125rem;
+  margin-inline-end: 0.375rem;
   inline-size: 0.875rem;
   block-size: 0.875rem;
 }
diff --git a/app/utils/home-demos.ts b/app/utils/home-demos.ts
index 0ad18da6..0e2839d7 100644
--- a/app/utils/home-demos.ts
+++ b/app/utils/home-demos.ts
@@ -1,7 +1,9 @@
 import type { DemoMakes } from '#shared/demo-groups'
+import type { DemoEffort } from '#shared/demo-recording'
+import type { DemoTokenUsage } from '#shared/demo-usage'
 import type { SkillCardSkill } from '~/types/skill-card'
 import { DEMO_GROUPS } from '#shared/demo-groups'
-import { demoAgentIcon, demoModelLabel } from '#shared/demo-recording'
+import { demoAgentIcon, demoRecordingLabel } from '#shared/demo-recording'
 
 /**
  * The fields the homepage reads from `/api/skill-demos`. Declared here, not
@@ -21,6 +23,8 @@ export interface HomeDemoItem {
   /** How the demo was recorded (GLOSSARY "demo"). The endpoint already sends these. */
   agent: string
   model: string
+  effort?: DemoEffort | null
+  tokenUsage?: DemoTokenUsage | null
   /** `YYYY-MM-DD`. */
   recordedAt: string
   shots: HomeDemoShot[]
@@ -170,13 +174,23 @@ export interface DemoRecordingView {
   model: string
   /** The COPY.md provenance line, for screen readers and the title. */
   sentence: string
+  usage?: { label: string, sentence: string }
 }
 
 /** How a demo was recorded, short enough for a card. */
-export function demoRecording(demo: Pick<HomeDemoItem, 'agent' | 'model'>): DemoRecordingView {
+export function demoRecording(demo: Pick<HomeDemoItem, 'agent' | 'model' | 'effort' | 'tokenUsage'>): DemoRecordingView {
+  const model = demoRecordingLabel(demo.model, demo.effort ?? null)
+  const usage = demo.tokenUsage
+  const count = (value: number) => value.toLocaleString('en-US')
   return {
     icon: demoAgentIcon(demo.agent),
-    model: demoModelLabel(demo.model),
-    sentence: `Recorded with ${demo.agent}, ${demoModelLabel(demo.model)}`,
+    model,
+    sentence: `Recorded with ${demo.agent}, ${model}`,
+    ...(usage
+      ? { usage: {
+          label: `${(usage.inputTokens + usage.outputTokens).toLocaleString('en-US', { notation: 'compact', maximumSignificantDigits: 3 })} tokens`,
+          sentence: `Input: ${count(usage.inputTokens)}; cached input: ${count(usage.cachedInputTokens)}; output: ${count(usage.outputTokens)}`,
+        } }
+      : {}),
   }
 }
diff --git a/docs/runbooks/demo-measurement.md b/docs/runbooks/demo-measurement.md
index 90d2300b..5fdb9142 100644
--- a/docs/runbooks/demo-measurement.md
+++ b/docs/runbooks/demo-measurement.md
@@ -61,3 +61,14 @@ Homepage display order may vary, but each row keeps its original rank.
 Record deployment times beside the aggregate export.
 Change one surface per comparison, then collect another seven full days.
 A local preview cannot establish conversion lift or campaign performance.
+
+## Recorded token usage
+
+Recording metadata is separate from anonymous demo engagement counts.
+The recorder saves Codex usage from completed turns.
+Input includes cached input. Total tokens equal input plus output.
+The page shows input, cached input, and output when Prompt opens.
+Missing usage stays absent. The page does not estimate dollar costs.
+
+Nine existing Codex demos carry usage from their matching completed recording events.
+The backfill matched each Skill ref, source commit, prompt, and model against its recording log.
diff --git a/layers/registry/server/data/skill-demos.json b/layers/registry/server/data/skill-demos.json
index 70577bd6..0cc60b74 100644
--- a/layers/registry/server/data/skill-demos.json
+++ b/layers/registry/server/data/skill-demos.json
@@ -38,7 +38,12 @@
             "height": 844
           }
         }
-      ]
+      ],
+      "tokenUsage": {
+        "inputTokens": 624256,
+        "cachedInputTokens": 577664,
+        "outputTokens": 9780
+      }
     },
     {
       "owner": "anthropics",
@@ -145,7 +150,12 @@
             "height": 844
           }
         }
-      ]
+      ],
+      "tokenUsage": {
+        "inputTokens": 1038004,
+        "cachedInputTokens": 983936,
+        "outputTokens": 18479
+      }
     },
     {
       "owner": "cloudai-x",
@@ -216,7 +226,12 @@
             "height": 844
           }
         }
-      ]
+      ],
+      "tokenUsage": {
+        "inputTokens": 870630,
+        "cachedInputTokens": 816000,
+        "outputTokens": 17671
+      }
     },
     {
       "owner": "conardli",
@@ -256,7 +271,12 @@
             "height": 844
           }
         }
-      ]
+      ],
+      "tokenUsage": {
+        "inputTokens": 1091572,
+        "cachedInputTokens": 1000576,
+        "outputTokens": 16312
+      }
     },
     {
       "owner": "echris6",
@@ -607,7 +627,12 @@
             "height": 900
           }
         }
-      ]
+      ],
+      "tokenUsage": {
+        "inputTokens": 712577,
+        "cachedInputTokens": 655616,
+        "outputTokens": 11710
+      }
     },
     {
       "owner": "justinwetch",
@@ -812,7 +837,12 @@
             "height": 844
           }
         }
-      ]
+      ],
+      "tokenUsage": {
+        "inputTokens": 1043345,
+        "cachedInputTokens": 982528,
+        "outputTokens": 14970
+      }
     },
     {
       "owner": "leonxlnx",
@@ -852,7 +882,12 @@
             "height": 844
           }
         }
-      ]
+      ],
+      "tokenUsage": {
+        "inputTokens": 622760,
+        "cachedInputTokens": 569600,
+        "outputTokens": 20715
+      }
     },
     {
       "owner": "leonxlnx",
@@ -893,7 +928,12 @@
             "height": 844
           }
         }
-      ]
+      ],
+      "tokenUsage": {
+        "inputTokens": 1021578,
+        "cachedInputTokens": 959744,
+        "outputTokens": 18617
+      }
     },
     {
       "owner": "leonxlnx",
@@ -1467,7 +1507,12 @@
             "height": 844
           }
         }
-      ]
+      ],
+      "tokenUsage": {
+        "inputTokens": 852569,
+        "cachedInputTokens": 782464,
+        "outputTokens": 20092
+      }
     },
     {
       "owner": "zarazhangrui",
diff --git a/layers/registry/server/utils/skill-demos.ts b/layers/registry/server/utils/skill-demos.ts
index 09ecc3c9..3a6e6cfb 100644
--- a/layers/registry/server/utils/skill-demos.ts
+++ b/layers/registry/server/utils/skill-demos.ts
@@ -1,9 +1,11 @@
 import type { DemoMakes } from '#shared/demo-groups'
 import type { DemoEffort } from '#shared/demo-recording'
+import type { DemoTokenUsage } from '#shared/demo-usage'
 import { z } from 'zod'
 import { DEMO_MAKES } from '#shared/demo-groups'
 import { demoPagePath, DEMOS_PATH, MIN_INDEXABLE_DEMOS } from '#shared/demo-pages'
 import { DEMO_EFFORTS } from '#shared/demo-recording'
+import { demoTokenUsageSchema } from '#shared/demo-usage'
 import { runCheckFlagKey } from '#shared/run-check-flags'
 import { repoSkillPath } from '#shared/skill-routes'
 import manifest from '../data/skill-demos.json'
@@ -74,6 +76,7 @@ const demoSchema = z.object({
   agentVersion: z.string().min(1),
   model: z.string().min(1),
   effort: z.enum(DEMO_EFFORTS).optional(),
+  tokenUsage: demoTokenUsageSchema.optional(),
   /** The Skill's source commit when the demo was recorded. */
   skillCommit: z.string().regex(/^[0-9a-f]{40}$/),
   recordedAt: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
@@ -180,6 +183,7 @@ export interface SkillDemoView {
   agent: string
   model: string
   effort: DemoEffort | null
+  tokenUsage: DemoTokenUsage | null
   skillCommit: string
   recordedAt: string
   /** True when the Skill moved past the commit the demo recorded. */
@@ -209,6 +213,7 @@ export function presentSkillDemo(demo: SkillDemoRecord, currentCommit: string |
     agent: demo.agent,
     model: demo.model,
     effort: demo.effort ?? null,
+    tokenUsage: demo.tokenUsage ?? null,
     skillCommit: demo.skillCommit,
     recordedAt: demo.recordedAt,
     outdated: currentCommit !== null && currentCommit !== demo.skillCommit,
diff --git a/scripts/record-skill-demo.ts b/scripts/record-skill-demo.ts
index e6602926..3db69dc4 100644
--- a/scripts/record-skill-demo.ts
+++ b/scripts/record-skill-demo.ts
@@ -53,6 +53,7 @@
 
 import type { DemoMakes } from '../shared/demo-groups'
 import type { DemoEffort } from '../shared/demo-recording'
+import type { DemoTokenUsage } from '../shared/demo-usage'
 import { execFile } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { existsSync, readdirSync } from 'node:fs'
@@ -65,6 +66,7 @@ import { parseArgs, promisify } from 'node:util'
 import { chromium } from '@playwright/test'
 import { DEMO_MAKES } from '../shared/demo-groups'
 import { DEMO_EFFORTS } from '../shared/demo-recording'
+import { codexDemoTokenUsage } from '../shared/demo-usage'
 import { runDemoAgent } from './lib/demo-agent'
 
 const run = promisify(execFile)
@@ -178,6 +180,7 @@ interface DemoEntry {
   agentVersion: string
   model: string
   effort?: DemoEffort
+  tokenUsage?: DemoTokenUsage
   skillCommit: string
   recordedAt: string
   pin?: number
@@ -667,6 +670,7 @@ async function main(): Promise<void> {
     agentVersion: agent.version,
     model: agent.model,
     ...(input.effort ? { effort: input.effort } : {}),
+    ...(input.agent === 'codex' ? { tokenUsage: codexDemoTokenUsage(await readFile(join(cwd, 'codex-events.jsonl'), 'utf8')) ?? undefined } : {}),
     skillCommit: pinned.commit,
     recordedAt: new Date().toISOString().slice(0, 10),
     ...media,
diff --git a/shared/demo-usage.ts b/shared/demo-usage.ts
new file mode 100644
index 00000000..d5f92f52
--- /dev/null
+++ b/shared/demo-usage.ts
@@ -0,0 +1,31 @@
+import { z } from 'zod'
+
+export const demoTokenUsageSchema = z.object({
+  inputTokens: z.number().int().nonnegative(),
+  cachedInputTokens: z.number().int().nonnegative(),
+  outputTokens: z.number().int().nonnegative(),
+}).refine(usage => usage.cachedInputTokens <= usage.inputTokens, {
+  message: 'Cached input cannot exceed total input.',
+})
+
+export type DemoTokenUsage = z.infer<typeof demoTokenUsageSchema>
+
+const completedTurnSchema = z.object({
+  usage: z.object({
+    input_tokens: z.number().int().nonnegative(),
+    cached_input_tokens: z.number().int().nonnegative(),
+    output_tokens: z.number().int().nonnegative(),
+  }),
+})
+
+/** Input already includes cached tokens. Sum completed turns without counting the cache twice. */
+export function codexDemoTokenUsage(events: string): DemoTokenUsage | null {
+  const turns = events.trim().split('\n').filter(Boolean).map(line => JSON.parse(line) as unknown).filter(event => z.object({ type: z.string() }).parse(event).type === 'turn.completed').map(event => completedTurnSchema.parse(event).usage)
+  if (!turns.length)
+    return null
+  return demoTokenUsageSchema.parse(turns.reduce((total, usage) => ({
+    inputTokens: total.inputTokens + usage.input_tokens,
+    cachedInputTokens: total.cachedInputTokens + usage.cached_input_tokens,
+    outputTokens: total.outputTokens + usage.output_tokens,
+  }), { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0 }))
+}
diff --git a/test/unit/demo-usage.test.ts b/test/unit/demo-usage.test.ts
new file mode 100644
index 00000000..1863727a
--- /dev/null
+++ b/test/unit/demo-usage.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import { codexDemoTokenUsage } from '../../shared/demo-usage'
+
+describe('codexDemoTokenUsage', () => {
+  it('sums completed turns and keeps cached input inside total input', () => {
+    const events = [
+      { type: 'item.completed' },
+      { type: 'turn.completed', usage: { input_tokens: 100, cached_input_tokens: 80, output_tokens: 20 } },
+      { type: 'turn.completed', usage: { input_tokens: 50, cached_input_tokens: 30, output_tokens: 10 } },
+    ].map(event => JSON.stringify(event)).join('\n')
+    expect(codexDemoTokenUsage(events)).toEqual({ inputTokens: 150, cachedInputTokens: 110, outputTokens: 30 })
+  })
+  it('leaves recordings without completed usage unknown', () => {
+    expect(codexDemoTokenUsage('{"type":"turn.started"}\n')).toBeNull()
+  })
+  it('rejects impossible cached counts', () => {
+    expect(() => codexDemoTokenUsage('{"type":"turn.completed","usage":{"input_tokens":10,"cached_input_tokens":20,"output_tokens":1}}')).toThrow()
+  })
+})
diff --git a/test/unit/home-demos.test.ts b/test/unit/home-demos.test.ts
index efd0b612..19a17f12 100644
--- a/test/unit/home-demos.test.ts
+++ b/test/unit/home-demos.test.ts
@@ -114,3 +114,20 @@ describe('demoSocialPicture', () => {
     expect(demoSocialPicture(demo({ shots: [{ src: '/m.jpg', width: 390, height: 844, alt: 'Phone', viewport: 'mobile', poster: null }] }))).toBeUndefined()
   })
 })
+
+describe('recorded run details', () => {
+  it('includes recorded effort in the model label and accessible sentence', () => {
+    const result = demoRecording({ ...demo(), effort: 'medium' as const })
+    expect(result.model).toBe('Opus 5.5, medium effort')
+    expect(result.sentence).toBe('Recorded with Claude Code, Opus 5.5, medium effort')
+  })
+})
+
+describe('token usage display', () => {
+  it('counts input and output once and preserves exact cache counts in the breakdown', () => {
+    expect(demoRecording({ ...demo(), tokenUsage: { inputTokens: 1043345, cachedInputTokens: 982528, outputTokens: 14970 } }).usage).toEqual({
+      label: '1.06M tokens',
+      sentence: 'Input: 1,043,345; cached input: 982,528; output: 14,970',
+    })
+  })
+})
diff --git a/test/unit/skill-demos.test.ts b/test/unit/skill-demos.test.ts
index de261a13..e3a08168 100644
--- a/test/unit/skill-demos.test.ts
+++ b/test/unit/skill-demos.test.ts
@@ -125,3 +125,11 @@ describe('listDemoSitemapEntries', () => {
     expect(listDemoSitemapEntries(new Set(), [{ ...first!, skillPageOnly: true }, ...rest])).toEqual([])
   })
 })
+
+describe('recorded token usage', () => {
+  it('preserves the recorded breakdown and leaves missing usage unknown', () => {
+    const tokenUsage = { inputTokens: 150, cachedInputTokens: 110, outputTokens: 30 }
+    expect(presentSkillDemo(demo({ tokenUsage }), null).tokenUsage).toEqual(tokenUsage)
+    expect(presentSkillDemo(demo(), null).tokenUsage).toBeNull()
+  })
+})