academy: self-hosted video player, sectioned IA, lesson videos + related docs

- VideoPlaceholder plays self-hosted MP4 (Vercel Blob via getAssetUrl) instead
  of YouTube; resolves absolute URLs, /static paths, and bare asset names
- Restructure foundations into sections: Get Started, Workflows (intro,
  branching, loops, subworkflows), Agents, Tables, Files, Knowledge Bases —
  each topic a folder with an intro page; eyebrows match their section
- Wire all uploaded lesson videos; scaffold the three Workflows sub-lessons
- Add a "Related documentation" section to every lesson linking the reference
  docs; fix in-body cross-links broken by the folder move

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ouiliame

apps/docs/components/ui/video-placeholder.tsx

@@ -1,7 +1,7 @@
 'use client'
 
 import { useState } from 'react'
-import { cn } from '@/lib/utils'
+import { cn, getAssetUrl } from '@/lib/utils'
 
 interface VideoPlaceholderProps {
   /** Large title shown on the hero. */
@@ -10,17 +10,19 @@ interface VideoPlaceholderProps {
   eyebrow?: string
   /** Pill in the top-right corner. Defaults to "Coming soon" (shown only until a video is set). */
   label?: string
-  /** YouTube video id or URL. When set, the play button loads the video; otherwise the card is "coming soon". */
-  youtube?: string
+  /**
+   * Self-hosted video source. Accepts an absolute URL, a root-relative path
+   * (`/static/...`), or a bare asset name resolved through the Blob CDN. When
+   * set, the play button loads the video; otherwise the card is "coming soon".
+   */
+  src?: string
   className?: string
 }
 
-/** Pull an 11-char YouTube id out of an id or any common YouTube URL. */
-function parseYouTubeId(input?: string): string | null {
-  if (!input) return null
-  if (/^[\w-]{11}$/.test(input)) return input
-  const match = input.match(/(?:youtu\.be\/|[?&]v=|\/embed\/|\/shorts\/)([\w-]{11})/)
-  return match ? match[1] : null
+/** Resolve a video source: pass absolute/root-relative through, send bare names to the Blob CDN. */
+function resolveVideoSrc(src: string): string {
+  if (/^https?:\/\//.test(src) || src.startsWith('/')) return src
+  return getAssetUrl(src)
 }
 
 /** The sim logotype, drawn with currentColor so the theme can tint it. */
@@ -37,33 +39,35 @@ function SimWordmark({ className }: { className?: string }) {
 
 /**
  * A 16:9 lesson hero used across the Academy. Always shows the design-system
- * video card (title, blueprint grid, theme-aware dark/light). When a `youtube`
- * id/URL is provided the play button loads the video inline; otherwise the card
- * reads "Coming soon" and the play button is muted.
+ * video card (title, blueprint grid, theme-aware dark/light). When a `src` is
+ * provided the play button loads the self-hosted video inline; otherwise the
+ * card reads "Coming soon" and the play button is muted.
  */
 export function VideoPlaceholder({
   title,
   eyebrow,
   label = 'Coming soon',
-  youtube,
+  src,
   className,
 }: VideoPlaceholderProps) {
-  const videoId = parseYouTubeId(youtube)
+  const hasVideo = Boolean(src)
   const [playing, setPlaying] = useState(false)
 
-  if (playing && videoId) {
+  if (playing && src) {
     return (
       <div
         className={cn(
           'not-prose my-6 aspect-video w-full overflow-hidden rounded-[20px] bg-black',
           className
         )}
       >
-        <iframe
-          src={`https://www.youtube-nocookie.com/embed/${videoId}?autoplay=1&rel=0`}
+        {/* biome-ignore lint/a11y/useMediaCaption: lesson videos have no caption track yet */}
+        <video
+          src={resolveVideoSrc(src)}
           title={title ?? 'Lesson video'}
-          allow='autoplay; encrypted-media; picture-in-picture; fullscreen'
-          allowFullScreen
+          controls
+          autoPlay
+          playsInline
           className='h-full w-full border-0'
         />
       </div>
@@ -100,7 +104,7 @@ export function VideoPlaceholder({
       ))}
 
       {/* Top-right status pill — only until a video is wired up */}
-      {!videoId && (
+      {!hasVideo && (
         <span className='absolute top-6 right-6 z-10 inline-flex items-center gap-2 rounded-full border border-[#E6E6E6] bg-white px-4 py-2 font-medium text-[12px] text-[#5F5F5F] uppercase tracking-[0.14em] md:top-8 md:right-8 dark:border-white/12 dark:bg-[#1A1A1A] dark:text-[#E6E6E6]'>
           <span className='size-1.5 rounded-full bg-[#1F8A5B]' />
           {label}
@@ -128,7 +132,7 @@ export function VideoPlaceholder({
 
       {/* Centered play button — active when a video is wired, muted otherwise */}
       <div className='absolute inset-0 z-10 grid place-items-center'>
-        {videoId ? (
+        {hasVideo ? (
           <button
             type='button'
             onClick={() => setPlaying(true)}

…/docs/content/docs/en/academy/agents.mdx …content/docs/en/academy/agents/intro.mdxapps/docs/content/docs/en/academy/agents.mdx renamed to apps/docs/content/docs/en/academy/agents/intro.mdx apps/docs/content/docs/en/academy/agents.mdx renamed to apps/docs/content/docs/en/academy/agents/intro.mdx

@@ -7,7 +7,7 @@ import { VideoPlaceholder } from '@/components/ui/video-placeholder'
 import { WhatYouWillLearn } from '@/components/ui/what-you-will-learn'
 import { VideoChapters } from '@/components/ui/video-chapters'
 
-<VideoPlaceholder eyebrow="Foundations" title="Agents" className="mt-2" />
+<VideoPlaceholder eyebrow="Agents" title="Agents" src="https://nnjgp7vypgx4myuq.public.blob.vercel-storage.com/academy-preview/agents-intro-light-with-intro.mp4" className="mt-2" />
 
 <div className="mt-8 grid grid-cols-1 items-start gap-10 lg:grid-cols-[1fr_300px]">
 <div>
@@ -47,7 +47,7 @@ In Sim, you build AI agents as **workflows that use the Agent block**. There's n
 
 ## An agent is a workflow
 
-This is the one idea to hold onto: **an AI agent is a workflow** — one built around the Agent block. Everything you learned about [workflows](/academy/workflows) applies. You don't leave the model; you add reasoning to it.
+This is the one idea to hold onto: **an AI agent is a workflow** — one built around the Agent block. Everything you learned about [workflows](/academy/workflows/intro) applies. You don't leave the model; you add reasoning to it.
 
 ## Inside the Agent block
 
@@ -71,3 +71,11 @@ The clearest way to see an agent isn't to build one from nothing — it's to tak
 Your ability to compose workflows that make **multiple agent calls** is central to designing intelligent processes. And every agentic workflow you build becomes a building block — your workspace's library of agents composes into larger AI systems.
 
 Start with one Agent block; the platform scales as your ambition does. The most sophisticated systems are just more of these, composed — more agent blocks swapping in, more reasoning, more reach, all from the same model you learned here.
+
+## Related documentation
+
+- [Agents overview](/agents)
+- [Choosing a model](/agents/choosing)
+- [Custom tools](/agents/custom-tools)
+- [MCP](/agents/mcp)
+- [Skills](/agents/skills)

…s/docs/content/docs/en/academy/files.mdx …/content/docs/en/academy/files/intro.mdxapps/docs/content/docs/en/academy/files.mdx renamed to apps/docs/content/docs/en/academy/files/intro.mdx apps/docs/content/docs/en/academy/files.mdx renamed to apps/docs/content/docs/en/academy/files/intro.mdx

@@ -7,7 +7,7 @@ import { VideoPlaceholder } from '@/components/ui/video-placeholder'
 import { WhatYouWillLearn } from '@/components/ui/what-you-will-learn'
 import { VideoChapters } from '@/components/ui/video-chapters'
 
-<VideoPlaceholder eyebrow="Foundations" title="Files" className="mt-2" />
+<VideoPlaceholder eyebrow="Files" title="Files" src="https://nnjgp7vypgx4myuq.public.blob.vercel-storage.com/academy-preview/files-light-with-intro.mp4" className="mt-2" />
 
 <div className="mt-8 grid grid-cols-1 items-start gap-10 lg:grid-cols-[1fr_300px]">
 <div>
@@ -58,3 +58,9 @@ The point isn't a new concept to learn — it's recognizing that the file-based
 - Produce a rendered document, chart, or audio file as a workflow's output.
 
 If you're thinking "could I automate the thing that involves *that* document?" — the answer is almost always yes. Files are how Sim handles the real assets your processes already run on.
+
+## Related documentation
+
+- [Files overview](/files)
+- [Using files in workflows](/files/using-in-workflows)
+- [Generating files](/files/generating)

apps/docs/content/docs/en/academy/index.mdx

@@ -6,7 +6,7 @@ description: Sim is a unified workspace for building and operating AI systems 
 import { VideoPlaceholder } from '@/components/ui/video-placeholder'
 import { WhatYouWillLearn } from '@/components/ui/what-you-will-learn'
 
-<VideoPlaceholder eyebrow="Foundations" title="What is Sim?" className="mt-2" />
+<VideoPlaceholder eyebrow="Get Started" title="What is Sim?" src="https://nnjgp7vypgx4myuq.public.blob.vercel-storage.com/academy-preview/what-is-sim-light-with-intro.mp4" className="mt-2" />
 
 Sim is a unified workspace for **building and operating AI systems**. Everything you make lives in one place, and everything connects.
 
@@ -27,7 +27,7 @@ Sim is a unified workspace for **building and operating AI systems**. Everything
 
 A **workspace** is a collection of shared resources and the workflows that use them.
 
-- **Resources** are your data: [tables](/academy/tables) (structured records), [knowledge bases](/academy/knowledge-bases) (searchable memory), and [files](/academy/files) (documents and media).
+- **Resources** are your data: [tables](/academy/tables/intro) (structured records), [knowledge bases](/academy/knowledge-bases/intro) (searchable memory), and [files](/academy/files/intro) (documents and media).
 - **Workflows** are your processes — the agents and automations that read those resources, act, and write results back.
 
 Everything in a workspace can see everything else in it. A workflow reads a table, searches a knowledge base, produces a file — and the next workflow picks up where it left off.
@@ -37,3 +37,8 @@ Everything in a workspace can see everything else in it. A workflow reads a tabl
 **Integrations** are plugins. They let your resources and workflows reach services beyond Sim — send a Slack message, read a Gmail inbox, write a row to a CRM, call any API. You connect an account once, and any workflow can use it.
 
 So the whole picture is small: a workspace is **data + processes**, integrations plug it into **everything else**, and the rest of this course is just learning each piece and watching them compose.
+
+## Related documentation
+
+- [Introduction](/introduction)
+- [Getting started](/getting-started)

…tent/docs/en/academy/knowledge-bases.mdx …ocs/en/academy/knowledge-bases/intro.mdxapps/docs/content/docs/en/academy/knowledge-bases.mdx renamed to apps/docs/content/docs/en/academy/knowledge-bases/intro.mdx apps/docs/content/docs/en/academy/knowledge-bases.mdx renamed to apps/docs/content/docs/en/academy/knowledge-bases/intro.mdx

@@ -7,7 +7,7 @@ import { VideoPlaceholder } from '@/components/ui/video-placeholder'
 import { WhatYouWillLearn } from '@/components/ui/what-you-will-learn'
 import { VideoChapters } from '@/components/ui/video-chapters'
 
-<VideoPlaceholder eyebrow="Foundations" title="Knowledge Bases" className="mt-2" />
+<VideoPlaceholder eyebrow="Knowledge Bases" title="Knowledge Bases" src="https://nnjgp7vypgx4myuq.public.blob.vercel-storage.com/academy-preview/knowledge-bases-light-with-intro.mp4" className="mt-2" />
 
 <div className="mt-8 grid grid-cols-1 items-start gap-10 lg:grid-cols-[1fr_300px]">
 <div>
@@ -61,6 +61,12 @@ Use a Knowledge block with a query and it returns the most relevant chunks, each
 
 ## Grounding an answer
 
-On its own, that's retrieval. The power comes one step later: feed those chunks into an [Agent](/academy/agents) block's context, and the model answers from your actual documents — accurate, up to date, and able to **cite** where each fact came from. That's grounding plus retrieval.
+On its own, that's retrieval. The power comes one step later: feed those chunks into an [Agent](/academy/agents/intro) block's context, and the model answers from your actual documents — accurate, up to date, and able to **cite** where each fact came from. That's grounding plus retrieval.
 
 Knowledge bases power systems that need to give agents accurate, current context — and they're where you store what your systems learn over time.
+
+## Related documentation
+
+- [Knowledge Bases overview](/knowledgebase)
+- [Using a knowledge base in workflows](/knowledgebase/using-in-workflows)
+- [Connectors](/knowledgebase/connectors)

apps/docs/content/docs/en/academy/meta.json

@@ -4,12 +4,19 @@
   "pages": [
     "---Get Started---",
     "index",
-    "---Foundations---",
-    "workflows",
-    "agents",
-    "knowledge-bases",
-    "tables",
-    "files",
+    "---Workflows---",
+    "workflows/intro",
+    "workflows/branching",
+    "workflows/loops",
+    "workflows/subworkflows",
+    "---Agents---",
+    "agents/intro",
+    "---Tables---",
+    "tables/intro",
+    "---Files---",
+    "files/intro",
+    "---Knowledge Bases---",
+    "knowledge-bases/intro",
     "---Use Cases---",
     "use-cases/slack-it-triage",
     "use-cases/document-extraction",

…/docs/content/docs/en/academy/tables.mdx …content/docs/en/academy/tables/intro.mdxapps/docs/content/docs/en/academy/tables.mdx renamed to apps/docs/content/docs/en/academy/tables/intro.mdx apps/docs/content/docs/en/academy/tables.mdx renamed to apps/docs/content/docs/en/academy/tables/intro.mdx

@@ -7,7 +7,7 @@ import { VideoPlaceholder } from '@/components/ui/video-placeholder'
 import { WhatYouWillLearn } from '@/components/ui/what-you-will-learn'
 import { VideoChapters } from '@/components/ui/video-chapters'
 
-<VideoPlaceholder eyebrow="Foundations" title="Tables" className="mt-2" />
+<VideoPlaceholder eyebrow="Tables" title="Tables" src="https://nnjgp7vypgx4myuq.public.blob.vercel-storage.com/academy-preview/tables-light-with-intro.mp4" className="mt-2" />
 
 <div className="mt-8 grid grid-cols-1 items-start gap-10 lg:grid-cols-[1fr_300px]">
 <div>
@@ -63,3 +63,9 @@ Once you see a use case that way, building it in Sim is mostly wiring those oper
 Tables aren't only storage — they're a working surface for your AI systems. **Workflow columns** let you run an operation across every row at once, in parallel, so a table becomes the place you launch and track work in bulk.
 
 That makes a table a powerful interface for automation — the place you manage and operate agentic processes at scale.
+
+## Related documentation
+
+- [Tables overview](/tables)
+- [Using tables in workflows](/tables/using-in-workflows)
+- [Workflow columns](/tables/workflow-columns)

apps/docs/content/docs/en/academy/use-cases/document-extraction.mdx

@@ -38,6 +38,6 @@ Turn a pile of unstructured documents — invoices, contracts, forms — into st
 
 ## What you'll build
 
-A **file** comes in, an **Agent** block extracts the fields into a [structured output](/academy/agents) so the shape is predictable, and a **Table** block writes the row. Run it across a batch and a folder of documents becomes a queryable table.
+A **file** comes in, an **Agent** block extracts the fields into a [structured output](/academy/agents/intro) so the shape is predictable, and a **Table** block writes the row. Run it across a batch and a folder of documents becomes a queryable table.
 
-This composes [files](/academy/files), [agents](/academy/agents), and [tables](/academy/tables).
+This composes [files](/academy/files/intro), [agents](/academy/agents/intro), and [tables](/academy/tables/intro).

apps/docs/content/docs/en/academy/use-cases/monitoring-research.mdx

@@ -38,6 +38,6 @@ Build a system that runs on a schedule, checks the sources you care about, resea
 
 ## What you'll build
 
-A **Schedule trigger** kicks the workflow off. An **Agent** block with search tools gathers and reads sources, synthesizes what changed, and a final step delivers it — a Slack message, or a saved report [file](/academy/files).
+A **Schedule trigger** kicks the workflow off. An **Agent** block with search tools gathers and reads sources, synthesizes what changed, and a final step delivers it — a Slack message, or a saved report [file](/academy/files/intro).
 
-This composes [workflows](/academy/workflows), [agents](/academy/agents), and [files](/academy/files).
+This composes [workflows](/academy/workflows/intro), [agents](/academy/agents/intro), and [files](/academy/files/intro).

apps/docs/content/docs/en/academy/use-cases/sales-data-enrichment.mdx

@@ -40,4 +40,4 @@ Run your sales pipeline as data. Start with thin lead records in a table, enrich
 
 Leads live in a **table**. A **workflow column** runs per row: it enriches the record, an **Agent** block scores the fit, and the results are written straight back into the table. The table becomes both the queue and the record.
 
-This is [tables](/academy/tables) and [agents](/academy/agents) composed into a pipeline that operates at scale.
+This is [tables](/academy/tables/intro) and [agents](/academy/agents/intro) composed into a pipeline that operates at scale.