diff --git a/cmd/internal/flags/types.go b/cmd/internal/flags/types.go
index bdbdf350..e0170bd5 100644
--- a/cmd/internal/flags/types.go
+++ b/cmd/internal/flags/types.go
@@ -295,7 +295,7 @@ var TemplateOutputPathFlag = &Metadata{
 var TemplateFlag = &Metadata{
 	Name:      "template",
 	Shorthand: "t",
-	Usage:     "Registered template name. Templates can be registered in the flow configuration file or with `flow set template`.",
+	Usage:     "Registered template name. Templates can be registered in the flow configuration file or with 'flow template add'.",
 	Default:   "",
 	Required:  false,
 }
@@ -338,7 +338,7 @@ var RunningFlag = &Metadata{
 var CmdFlag = &Metadata{
 	Name: "cmd",
 	Usage: "Run an ad-hoc shell command through flow instead of a named executable. " +
-		"The command runs with the current workspace's environment and is recorded in `flow logs`. " +
+		"The command runs with the current workspace's environment and is recorded in flow logs. " +
 		"Repeat --cmd to run multiple commands in one invocation (see --mode).",
 	Default:  []string{},
 	Required: false,
@@ -386,7 +386,7 @@ var SpecFlag = &Metadata{
 	Name: "spec",
 	Usage: "Run a transient executable from an inline definition (any type: exec, serial, parallel, request, " +
 		"render, launch). Accepts inline YAML/JSON, '@path' to read a file, or '-' to read stdin. " +
-		"The executable is not saved to disk but is recorded in `flow logs`.",
+		"The executable is not saved to disk but is recorded in flow logs.",
 	Default:  "",
 	Required: false,
 }
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index b22cd9c4..93cd88aa 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -3,26 +3,95 @@ import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
 import flowfileGrammar from './flowfile.tmLanguage.json'
 
 // https://vitepress.dev/reference/site-config
+const SITE = 'https://flowexec.io'
+const SITE_NAME = 'flow'
+const SITE_DESCRIPTION =
+  'Write your workflows down, then run them from any project on your machine — with the right secrets, the right environment, and a record of what happened.'
+const OG_IMAGE = `${SITE}/og-default.png`
+
 export default defineConfig({
-  title: "flow",
-  description: "Local developer automation platform that flows with you.",
+  title: SITE_NAME,
+  description: SITE_DESCRIPTION,
   base: '/',
   outDir: './dist',
+  lang: 'en-US',
+
+  // Cloudflare Pages redirects /foo.html to /foo, so without this the sitemap
+  // advertises URLs that immediately redirect and the site links to a different
+  // form than it declares canonical.
+  cleanUrls: true,
 
   sitemap: {
-    hostname: 'https://flowexec.io'
+    hostname: SITE
   },
 
   head: [
-    ['link', { rel: 'icon', href: '/favicon.ico' }],
-    ['link', { rel: 'alternate', type: 'text/plain', title: 'llms.txt', href: 'https://flowexec.io/llms.txt' }]
+    ['link', { rel: 'icon', href: '/favicon.ico', sizes: '48x48' }],
+    ['link', { rel: 'icon', type: 'image/png', href: '/icon.png' }],
+    ['link', { rel: 'apple-touch-icon', href: '/apple-touch-icon.png' }],
+    ['meta', { name: 'theme-color', content: '#2D353B' }],
+    ['meta', { name: 'author', content: 'Dockery Labs' }],
+    ['link', { rel: 'alternate', type: 'text/plain', title: 'llms.txt', href: `${SITE}/llms.txt` }],
+
+    // Per-page og:title / og:description / og:url and the canonical link are
+    // added in transformPageData below; these are the values that never vary.
+    ['meta', { property: 'og:site_name', content: SITE_NAME }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:locale', content: 'en_US' }],
+    ['meta', { property: 'og:image', content: OG_IMAGE }],
+    ['meta', { property: 'og:image:width', content: '1200' }],
+    ['meta', { property: 'og:image:height', content: '630' }],
+    ['meta', { property: 'og:image:alt', content: 'flow' }],
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+    ['meta', { name: 'twitter:image', content: OG_IMAGE }],
+
+    ['script', { type: 'application/ld+json' }, JSON.stringify({
+      '@context': 'https://schema.org',
+      '@type': 'SoftwareApplication',
+      name: SITE_NAME,
+      description: SITE_DESCRIPTION,
+      url: SITE,
+      applicationCategory: 'DeveloperApplication',
+      operatingSystem: 'macOS, Linux, Windows',
+      license: 'https://github.com/flowexec/flow/blob/main/LICENSE',
+      offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
+      author: { '@type': 'Organization', name: 'Dockery Labs', url: 'https://jahvon.dev' },
+      sameAs: ['https://github.com/flowexec/flow', 'https://discord.gg/CtByNKNMxM']
+    })]
   ],
 
+  transformPageData(pageData) {
+    const path = pageData.relativePath
+      .replace(/(^|\/)index\.md$/, '$1')
+      .replace(/\.md$/, '')
+    const canonical = `${SITE}/${path}`
+    const title = pageData.frontmatter.title
+      ? `${pageData.frontmatter.title} | ${SITE_NAME}`
+      : SITE_NAME
+    const description = pageData.frontmatter.description || SITE_DESCRIPTION
+
+    pageData.frontmatter.head ??= []
+    pageData.frontmatter.head.push(
+      ['link', { rel: 'canonical', href: canonical }],
+      ['meta', { property: 'og:url', content: canonical }],
+      ['meta', { property: 'og:title', content: title }],
+      ['meta', { property: 'og:description', content: description }],
+      ['meta', { name: 'twitter:title', content: title }],
+      ['meta', { name: 'twitter:description', content: description }]
+    )
+  },
+
   markdown: {
     config(md) {
       md.use(tabsMarkdownPlugin)
     },
     languages: [flowfileGrammar as never],
+    // Shiki bundles both, so code blocks land on the same palette as the rest
+    // of the site instead of GitHub's default blues.
+    theme: {
+      light: 'everforest-light',
+      dark: 'everforest-dark',
+    },
   },
 
   themeConfig: {
@@ -33,12 +102,22 @@ export default defineConfig({
 
     siteTitle: false,
 
+    // Three items, not five. The logo already goes home, and the two reference
+    // sections are destinations you arrive at from a guide rather than things
+    // you browse cold — so they collapse into one menu and give the search and
+    // Ask controls room to breathe.
     nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Guides', link: '/guides/', activeMatch: '/guides/'},
+      { text: 'Guides', link: '/guides/', activeMatch: '/guides/' },
       { text: 'Examples', link: '/examples', activeMatch: '/examples' },
-      { text: 'CLI Reference', link: '/cli/', activeMatch: '/cli/' },
-      { text: 'Config Reference', link: '/types/', activeMatch: '/types/' }
+      {
+        text: 'Reference',
+        activeMatch: '/(cli|types)/',
+        items: [
+          { text: 'CLI Reference', link: '/cli/' },
+          { text: 'Configuration Reference', link: '/types/' },
+          { text: 'Contributing', link: '/development' }
+        ]
+      }
     ],
 
     sidebar: {
@@ -69,12 +148,17 @@ export default defineConfig({
                 { text: 'Templates & Workflow Generation', link: '/guides/templating' },
               ]
             },
-            { text: 'Integrations & Tools',
+            { text: 'Interfaces',
               items: [
                 { text: 'Interactive UI', link: '/guides/interactive' },
-                { text: 'AI Tools', link: '/guides/ai-tools' },
                 { text: 'Run Provenance', link: '/guides/run-provenance' },
-                { text: 'Integrations', link: '/guides/integrations' },
+              ]
+            },
+            { text: 'Integrations',
+              items: [
+                { text: 'AI Tools & MCP', link: '/guides/ai-tools' },
+                { text: 'Containers', link: '/guides/containers' },
+                { text: 'GitHub Actions', link: '/guides/github-actions' },
               ]
             },
           ]
@@ -242,6 +326,15 @@ export default defineConfig({
       provider: 'local'
     },
 
+    footer: {
+      message: 'Released under the <a href="https://github.com/flowexec/flow/blob/main/LICENSE">Apache 2.0 License</a>.',
+      copyright: [
+        `&copy; ${new Date().getFullYear()} <a href="https://jahvon.dev">Dockery Labs</a>`,
+        '<a href="https://jahvon.dev/architecture/flow/">Architecture</a>',
+        '<a href="https://mochiexec.io">Mochi</a>',
+      ].join(' &middot; ')
+    },
+
     outline: {
       level: [2, 3]
     }
diff --git a/docs/.vitepress/theme/AskBridge.vue b/docs/.vitepress/theme/AskBridge.vue
new file mode 100644
index 00000000..f9b03300
--- /dev/null
+++ b/docs/.vitepress/theme/AskBridge.vue
@@ -0,0 +1,130 @@
+<script setup lang="ts">
+import { nextTick, onMounted, onUnmounted, ref } from 'vue'
+import Icon from './Icon.vue'
+import { openAsk } from './askState'
+
+/**
+ * A row inside VitePress's own search modal that hands the current query over
+ * to the Ask panel — the "no page matched, ask the codebase" path.
+ *
+ * VitePress teleports its search box to <body> and exposes no slot, so the
+ * only way in is to observe the DOM. That means depending on three internal
+ * selectors, so every one of them is checked before the row renders: if a
+ * VitePress upgrade renames any of them the bridge quietly disappears and the
+ * standalone Ask button carries on working.
+ */
+const SELECTORS = {
+  box: '.VPLocalSearchBox',
+  shell: '.VPLocalSearchBox .shell',
+  input: '#localsearch-input',
+  backdrop: '.VPLocalSearchBox .backdrop',
+}
+
+const ready = ref(false)
+const query = ref('')
+
+let observer: MutationObserver | null = null
+let input: HTMLInputElement | null = null
+
+function syncQuery() {
+  query.value = input?.value.trim() ?? ''
+}
+
+function attach() {
+  if (ready.value) return
+  const shell = document.querySelector(SELECTORS.shell)
+  const found = document.querySelector<HTMLInputElement>(SELECTORS.input)
+  if (!shell || !found) return
+
+  input = found
+  input.addEventListener('input', syncQuery)
+  syncQuery()
+  ready.value = true
+}
+
+function detach() {
+  input?.removeEventListener('input', syncQuery)
+  input = null
+  ready.value = false
+  query.value = ''
+}
+
+function onMutation() {
+  if (document.querySelector(SELECTORS.box)) attach()
+  else if (ready.value) detach()
+}
+
+async function handoff() {
+  const q = query.value
+  // Drop the teleport before VitePress removes the node it renders into.
+  ready.value = false
+  await nextTick()
+  document.querySelector<HTMLElement>(SELECTORS.backdrop)?.click()
+  openAsk(q)
+}
+
+onMounted(() => {
+  observer = new MutationObserver(onMutation)
+  observer.observe(document.body, { childList: true, subtree: true })
+})
+
+onUnmounted(() => {
+  observer?.disconnect()
+  observer = null
+  detach()
+})
+</script>
+
+<template>
+  <Teleport v-if="ready" :to="SELECTORS.shell">
+    <button class="ask-bridge" type="button" @click="handoff">
+      <Icon name="sparkle" />
+      <span class="ask-bridge__text">
+        <template v-if="query">Ask the codebase about “{{ query }}”</template>
+        <template v-else>Ask the codebase a question</template>
+      </span>
+      <Icon name="arrowRight" />
+    </button>
+  </Teleport>
+</template>
+
+<style scoped>
+.ask-bridge {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 12px 16px;
+  border: 0;
+  border-top: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-soft);
+  color: var(--vp-c-text-2);
+  font-size: 13.5px;
+  text-align: left;
+  cursor: pointer;
+  transition: color 0.18s ease, background-color 0.18s ease;
+}
+
+.ask-bridge:hover {
+  background: var(--vp-c-default-soft);
+  color: var(--vp-c-text-1);
+}
+
+.ask-bridge__text {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ask-bridge :deep(.ui-icon) {
+  width: 14px;
+  height: 14px;
+}
+
+.ask-bridge :deep(.ui-icon:first-child) {
+  color: var(--vp-c-brand-1);
+  opacity: 1;
+}
+</style>
diff --git a/docs/.vitepress/theme/AskDeepWiki.vue b/docs/.vitepress/theme/AskDeepWiki.vue
new file mode 100644
index 00000000..4e51f896
--- /dev/null
+++ b/docs/.vitepress/theme/AskDeepWiki.vue
@@ -0,0 +1,524 @@
+<script setup lang="ts">
+import { computed, nextTick, onMounted, onUnmounted, ref } from 'vue'
+import MarkdownIt from 'markdown-it'
+import Icon from './Icon.vue'
+import { askDeepWiki, DeepWikiError, DEEPWIKI_URL, REPO } from './deepwiki'
+import { askOpen, askQuery } from './askState'
+
+const SUGGESTIONS = [
+  'How does flow resolve an executable reference?',
+  'What happens when a parallel executable fails?',
+  'How are secrets injected into a running executable?',
+]
+
+// `html: false` is the sanitisation boundary — model output never reaches the
+// DOM as markup, only as text markdown-it itself escaped.
+const md = new MarkdownIt({ html: false, linkify: true, breaks: false })
+
+const input = ref<HTMLInputElement | null>(null)
+const question = ref('')
+const answer = ref('')
+const error = ref('')
+const loading = ref(false)
+const elapsed = ref(0)
+const asked = ref('')
+
+let controller: AbortController | null = null
+
+const rendered = computed(() => (answer.value ? md.render(answer.value) : ''))
+
+function cancel() {
+  controller?.abort()
+  controller = null
+  loading.value = false
+}
+
+function close() {
+  cancel()
+  askOpen.value = false
+}
+
+function reset() {
+  answer.value = ''
+  error.value = ''
+  elapsed.value = 0
+  asked.value = ''
+}
+
+async function submit() {
+  const q = question.value.trim()
+  if (!q || loading.value) return
+
+  reset()
+  loading.value = true
+  asked.value = q
+  controller = new AbortController()
+
+  try {
+    answer.value = await askDeepWiki(q, {
+      signal: controller.signal,
+      onProgress: (seconds) => {
+        elapsed.value = seconds
+      },
+    })
+  } catch (err) {
+    if (controller?.signal.aborted) return
+    error.value =
+      err instanceof DeepWikiError
+        ? err.message
+        : 'Could not reach DeepWiki. It may be rate limited or temporarily down.'
+  } finally {
+    loading.value = false
+    controller = null
+  }
+}
+
+function ask(suggestion: string) {
+  question.value = suggestion
+  submit()
+}
+
+function onKeydown(e: KeyboardEvent) {
+  if (e.key === 'Escape' && askOpen.value) {
+    e.preventDefault()
+    close()
+  }
+}
+
+// Layout mounts this component only while the panel is open, so the component
+// lifetime *is* the open state — a watcher on askOpen would register too late
+// to ever see the transition that created it.
+onMounted(async () => {
+  document.addEventListener('keydown', onKeydown)
+  document.body.style.overflow = 'hidden'
+
+  // A query handed over from the search modal arrives here.
+  if (askQuery.value) {
+    question.value = askQuery.value
+    askQuery.value = ''
+  }
+
+  await nextTick()
+  input.value?.focus()
+  input.value?.select()
+})
+onUnmounted(() => {
+  document.removeEventListener('keydown', onKeydown)
+  document.body.style.overflow = ''
+  controller?.abort()
+})
+</script>
+
+<template>
+  <Teleport to="body">
+    <div v-if="askOpen" class="ask" role="dialog" aria-modal="true" aria-label="Ask the flow codebase">
+      <div class="ask__backdrop" @click="close" />
+
+      <div class="ask__shell">
+        <form class="ask__bar" @submit.prevent="submit">
+          <Icon name="sparkle" />
+          <input
+            ref="input"
+            v-model="question"
+            class="ask__input"
+            type="search"
+            placeholder="Ask anything about the flow codebase…"
+            autocomplete="off"
+            spellcheck="false"
+          />
+          <button
+            v-if="!loading"
+            class="ask__btn"
+            type="submit"
+            title="Ask"
+            :disabled="!question.trim()"
+          >
+            <Icon name="enter" />
+          </button>
+          <button
+            v-else
+            class="ask__btn"
+            type="button"
+            title="Stop"
+            @click="cancel"
+          >
+            <span class="ask__stop" />
+          </button>
+
+          <button class="ask__btn ask__close" type="button" title="Close" @click="close">
+            <Icon name="close" />
+          </button>
+        </form>
+
+        <div class="ask__body">
+          <!-- Idle -->
+          <div v-if="!loading && !answer && !error" class="ask__idle">
+            <p class="ask__idle-lede">
+              Answers are grounded in the <code>{{ REPO }}</code> source, not just these docs.
+              Expect about 15 seconds.
+            </p>
+            <ul class="ask__suggestions">
+              <li v-for="s in SUGGESTIONS" :key="s">
+                <button type="button" @click="ask(s)">
+                  {{ s }}
+                  <Icon name="arrowRight" />
+                </button>
+              </li>
+            </ul>
+          </div>
+
+          <!-- Working -->
+          <div v-else-if="loading" class="ask__loading">
+            <p class="ask__status">
+              <span class="ask__pulse" />
+              Reading the flow codebase<span v-if="elapsed" class="tabular"> · {{ elapsed }}s</span>
+            </p>
+            <div class="ask__skeleton">
+              <span v-for="n in 5" :key="n" :style="{ width: `${[96, 88, 72, 91, 54][n - 1]}%` }" />
+            </div>
+          </div>
+
+          <!-- Failed -->
+          <div v-else-if="error" class="ask__error">
+            <p><Icon name="alert" /> {{ error }}</p>
+            <a :href="DEEPWIKI_URL" target="_blank" rel="noopener noreferrer">
+              Ask on DeepWiki instead <Icon name="external" />
+            </a>
+          </div>
+
+          <!-- Answered -->
+          <div v-else class="ask__answer">
+            <p class="ask__asked">{{ asked }}</p>
+            <div class="vp-doc" v-html="rendered" />
+          </div>
+        </div>
+
+        <div class="ask__foot">
+          <span>
+            Generated by
+            <a :href="DEEPWIKI_URL" target="_blank" rel="noopener noreferrer">DeepWiki</a>
+            from the flow source · may be inaccurate
+          </span>
+          <span class="ask__foot-keys"><kbd>esc</kbd> close</span>
+        </div>
+      </div>
+    </div>
+  </Teleport>
+</template>
+
+<style scoped>
+.ask {
+  position: fixed;
+  inset: 0;
+  z-index: 100;
+  display: flex;
+  justify-content: center;
+  padding: 64px 16px 16px;
+}
+
+.ask__backdrop {
+  position: absolute;
+  inset: 0;
+  background: var(--vp-backdrop-bg-color);
+  backdrop-filter: blur(4px);
+}
+
+.ask__shell {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  max-width: 720px;
+  max-height: 100%;
+  overflow: hidden;
+  background: var(--vp-c-bg-elv);
+  border: 1px solid var(--vp-c-border);
+  border-radius: var(--radius);
+}
+
+.ask__bar {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 14px 16px;
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+.ask__bar > :deep(.ui-icon) {
+  width: 17px;
+  height: 17px;
+  color: var(--vp-c-brand-1);
+  opacity: 1;
+}
+
+.ask__input {
+  flex: 1 1 auto;
+  min-width: 0;
+  border: 0;
+  background: transparent;
+  color: var(--vp-c-text-1);
+  font-size: 16px;
+  outline: none;
+}
+
+.ask__input::placeholder {
+  color: var(--vp-c-text-3);
+}
+
+.ask__input::-webkit-search-cancel-button {
+  display: none;
+}
+
+.ask__btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  flex: 0 0 auto;
+  border: 1px solid var(--vp-c-border);
+  border-radius: 7px;
+  background: transparent;
+  color: var(--vp-c-text-2);
+  cursor: pointer;
+  transition: border-color 0.18s ease, color 0.18s ease;
+}
+
+.ask__btn:hover:not(:disabled) {
+  border-color: var(--vp-c-text-3);
+  color: var(--vp-c-text-1);
+}
+
+.ask__btn:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+.ask__btn :deep(.ui-icon) {
+  width: 14px;
+  height: 14px;
+}
+
+.ask__close {
+  border-color: transparent;
+}
+
+.ask__stop {
+  width: 9px;
+  height: 9px;
+  border-radius: 2px;
+  background: currentColor;
+}
+
+.ask__body {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  padding: 18px 20px;
+}
+
+/* --- idle ---------------------------------------------------------------- */
+
+.ask__idle-lede {
+  margin: 0 0 16px;
+  font-size: 13.5px;
+  line-height: 1.62;
+  color: var(--vp-c-text-2);
+}
+
+.ask__idle-lede code {
+  font-family: var(--vp-font-family-mono);
+  font-size: 0.9em;
+}
+
+.ask__suggestions {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.ask__suggestions li + li {
+  border-top: 1px solid var(--vp-c-divider);
+}
+
+.ask__suggestions button {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  width: 100%;
+  padding: 11px 2px;
+  border: 0;
+  background: none;
+  color: var(--vp-c-text-1);
+  font-size: 14px;
+  text-align: left;
+  cursor: pointer;
+  transition: color 0.18s ease;
+}
+
+.ask__suggestions button:hover {
+  color: var(--vp-c-brand-1);
+}
+
+.ask__suggestions :deep(.ui-icon) {
+  width: 14px;
+  height: 14px;
+}
+
+/* --- working ------------------------------------------------------------- */
+
+.ask__status {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  margin: 0 0 16px;
+  font-size: 12.5px;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  color: var(--vp-c-text-2);
+}
+
+.ask__pulse {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--vp-c-brand-1);
+  animation: ask-pulse 1.4s ease-in-out infinite;
+}
+
+@keyframes ask-pulse {
+  0%,
+  100% {
+    opacity: 0.25;
+    transform: scale(0.8);
+  }
+  50% {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.ask__skeleton {
+  display: flex;
+  flex-direction: column;
+  gap: 11px;
+}
+
+.ask__skeleton span {
+  height: 9px;
+  border-radius: 5px;
+  background: var(--vp-c-default-soft);
+  animation: ask-shimmer 1.6s ease-in-out infinite;
+}
+
+.ask__skeleton span:nth-child(2) { animation-delay: 0.1s; }
+.ask__skeleton span:nth-child(3) { animation-delay: 0.2s; }
+.ask__skeleton span:nth-child(4) { animation-delay: 0.3s; }
+.ask__skeleton span:nth-child(5) { animation-delay: 0.4s; }
+
+@keyframes ask-shimmer {
+  0%,
+  100% { opacity: 0.45; }
+  50% { opacity: 1; }
+}
+
+/* --- failed -------------------------------------------------------------- */
+
+.ask__error p {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0 0 12px;
+  font-size: 14px;
+  color: var(--vp-c-text-1);
+}
+
+.ask__error a {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 13.5px;
+  font-weight: 500;
+  color: var(--vp-c-brand-1);
+  text-decoration: none;
+}
+
+.ask__error :deep(.ui-icon) {
+  width: 15px;
+  height: 15px;
+}
+
+/* --- answered ------------------------------------------------------------ */
+
+.ask__asked {
+  margin: 0 0 14px;
+  padding-bottom: 12px;
+  border-bottom: 1px solid var(--vp-c-divider);
+  font-size: 13px;
+  letter-spacing: 0.02em;
+  color: var(--vp-c-text-2);
+}
+
+.ask__answer :deep(.vp-doc) {
+  font-size: 14.5px;
+}
+
+.ask__answer :deep(.vp-doc > *:first-child) {
+  margin-top: 0;
+}
+
+.ask__answer :deep(pre) {
+  padding: 14px 16px;
+  overflow-x: auto;
+  background: var(--vp-code-block-bg);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  font-family: var(--vp-font-family-mono);
+  font-size: 12.5px;
+  line-height: 1.6;
+}
+
+.ask__answer :deep(h2),
+.ask__answer :deep(h3) {
+  margin: 1.6em 0 0.6em;
+  padding: 0;
+  border: 0;
+  font-size: 15px;
+  font-weight: 600;
+}
+
+/* --- foot ---------------------------------------------------------------- */
+
+.ask__foot {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 10px 16px;
+  border-top: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-soft);
+  font-size: 11.5px;
+  color: var(--vp-c-text-3);
+}
+
+.ask__foot a {
+  color: var(--vp-c-text-2);
+}
+
+.ask__foot kbd {
+  padding: 1px 5px;
+  border: 1px solid var(--vp-c-border);
+  border-radius: 4px;
+  font-family: var(--vp-font-family-mono);
+  font-size: 10px;
+}
+
+@media (max-width: 640px) {
+  .ask {
+    padding: 12px;
+  }
+  .ask__foot-keys {
+    display: none;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/AskTrigger.vue b/docs/.vitepress/theme/AskTrigger.vue
new file mode 100644
index 00000000..c383f084
--- /dev/null
+++ b/docs/.vitepress/theme/AskTrigger.vue
@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import Icon from './Icon.vue'
+import { openAsk } from './askState'
+</script>
+
+<template>
+  <button class="ask-trigger" title="Ask about the flow codebase (⌘I)" @click="openAsk()">
+    <Icon name="sparkle" />
+    <span class="ask-trigger__text">Ask AI</span>
+  </button>
+</template>
+
+<style scoped>
+.ask-trigger {
+  display: inline-flex;
+  flex: 0 0 auto;
+  margin-left: 8px;
+  align-items: center;
+  gap: 6px;
+  padding: 0 10px;
+  height: 30px;
+  border: 1px solid var(--vp-c-border);
+  border-radius: 8px;
+  background: transparent;
+  color: var(--vp-c-text-2);
+  font-size: 13px;
+  font-weight: 500;
+  white-space: nowrap;
+  cursor: pointer;
+  transition: border-color 0.18s ease, color 0.18s ease;
+}
+
+.ask-trigger:hover {
+  border-color: var(--vp-c-text-3);
+  color: var(--vp-c-text-1);
+}
+
+.ask-trigger :deep(.ui-icon) {
+  width: 14px;
+  height: 14px;
+  color: var(--vp-c-brand-1);
+  opacity: 1;
+}
+
+/* In the mobile nav screen the trigger is a full-width row, not a pill. */
+.VPNavScreen .ask-trigger {
+  width: 100%;
+  height: 38px;
+  justify-content: center;
+}
+</style>
diff --git a/docs/.vitepress/theme/Card.vue b/docs/.vitepress/theme/Card.vue
new file mode 100644
index 00000000..57fec19a
--- /dev/null
+++ b/docs/.vitepress/theme/Card.vue
@@ -0,0 +1,145 @@
+<script setup lang="ts">
+import Icon from './Icon.vue'
+
+defineProps<{
+  icon: string
+  title: string
+  badge?: string
+  stack?: string[]
+  href?: string
+  hrefText?: string
+  altHref?: string
+  altHrefText?: string
+}>()
+</script>
+
+<template>
+  <article class="card">
+    <div class="card__head">
+      <span class="card__icon"><Icon :name="icon" /></span>
+      <div class="card__heading">
+        <h3 class="card__title">{{ title }}</h3>
+        <span v-if="badge" class="card__badge">{{ badge }}</span>
+      </div>
+    </div>
+
+    <p class="card__body"><slot /></p>
+
+    <p v-if="stack?.length" class="card__stack">
+      <template v-for="(item, i) in stack" :key="item">
+        <span v-if="i > 0" class="sep">·</span>{{ item }}
+      </template>
+    </p>
+
+    <p v-if="href" class="card__links">
+      <a :href="href">{{ hrefText ?? 'Guide' }}</a>
+      <a v-if="altHref" :href="altHref">{{ altHrefText ?? 'Reference' }}</a>
+    </p>
+  </article>
+</template>
+
+<style scoped>
+.card {
+  display: flex;
+  flex-direction: column;
+  padding: 22px;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-border);
+  border-radius: var(--radius);
+  transition: border-color 0.18s ease;
+}
+
+.card:hover {
+  border-color: var(--vp-c-text-3);
+}
+
+.card__head {
+  display: flex;
+  align-items: center;
+  gap: 11px;
+  margin-bottom: 10px;
+}
+
+.card__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 30px;
+  height: 30px;
+  flex: 0 0 auto;
+  border: 1px solid var(--vp-c-border);
+  border-radius: 8px;
+  font-size: 15px;
+  color: var(--vp-c-brand-1);
+}
+
+.card__heading {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+  min-width: 0;
+}
+
+.card__title {
+  margin: 0;
+  padding: 0;
+  border: 0;
+  font-size: 17px;
+  font-weight: 600;
+  line-height: 1.3;
+  letter-spacing: -0.01em;
+  color: var(--vp-c-text-1);
+}
+
+.card__badge {
+  padding: 2px 8px;
+  border-radius: 6px;
+  background: var(--vp-c-default-soft);
+  font-size: 11px;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--vp-c-text-2);
+}
+
+.card__body {
+  flex: 1 1 auto;
+  margin: 0 0 14px;
+  font-size: 14px;
+  line-height: 1.62;
+  color: var(--vp-c-text-2);
+}
+
+.card__stack {
+  margin: 0 0 14px;
+  font-size: 12.5px;
+  letter-spacing: 0.02em;
+  color: var(--vp-c-text-3);
+}
+
+.card__stack .sep {
+  margin: 0 7px;
+  opacity: 0.5;
+}
+
+.card__links {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 14px;
+  margin: 0;
+  font-size: 13.5px;
+}
+
+.card__links a {
+  color: var(--vp-c-brand-1);
+  font-weight: 500;
+  text-decoration: none;
+  box-shadow: 0 1px 0 var(--vp-c-brand-1);
+  transition: opacity 0.18s ease;
+}
+
+.card__links a:hover {
+  opacity: 0.75;
+}
+</style>
diff --git a/docs/.vitepress/theme/CardGrid.vue b/docs/.vitepress/theme/CardGrid.vue
new file mode 100644
index 00000000..c57e88d7
--- /dev/null
+++ b/docs/.vitepress/theme/CardGrid.vue
@@ -0,0 +1,17 @@
+<template>
+  <div class="card-grid"><slot /></div>
+</template>
+
+<style scoped>
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 16px;
+}
+
+@media (max-width: 600px) {
+  .card-grid {
+    grid-template-columns: 1fr;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/ExamplesGallery.vue b/docs/.vitepress/theme/ExamplesGallery.vue
index f93832a3..179e3aa2 100644
--- a/docs/.vitepress/theme/ExamplesGallery.vue
+++ b/docs/.vitepress/theme/ExamplesGallery.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { ref, computed, onMounted, onUnmounted } from 'vue'
+import Icon from './Icon.vue'
 
 const copied = ref(false)
 async function copySource(text: string) {
@@ -85,18 +86,7 @@ onUnmounted(() => {
             class="github-link"
             title="View on GitHub"
           >
-            <svg
-              xmlns="http://www.w3.org/2000/svg"
-              width="15"
-              height="15"
-              viewBox="0 0 24 24"
-              fill="currentColor"
-              aria-hidden="true"
-            >
-              <path
-                d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12z"
-              />
-            </svg>
+            <Icon name="github" />
           </a>
         </div>
 
@@ -145,18 +135,7 @@ onUnmounted(() => {
               class="modal-github-link"
               title="View on GitHub"
             >
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                width="16"
-                height="16"
-                viewBox="0 0 24 24"
-                fill="currentColor"
-                aria-hidden="true"
-              >
-                <path
-                  d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12z"
-                />
-              </svg>
+            <Icon name="github" />
               GitHub
             </a>
             <button class="modal-close" @click="closeModal" aria-label="Close">✕</button>
@@ -182,7 +161,7 @@ onUnmounted(() => {
 
 .filter-btn {
   padding: 0.3rem 0.9rem;
-  border-radius: 20px;
+  border-radius: 999px;
   border: 1px solid var(--vp-c-border);
   background: var(--vp-c-bg-soft);
   color: var(--vp-c-text-2);
@@ -200,7 +179,7 @@ onUnmounted(() => {
 .filter-btn.active {
   background: var(--vp-c-brand-1);
   border-color: var(--vp-c-brand-1);
-  color: #fff;
+  color: var(--vp-c-bg);
 }
 
 .examples-grid {
@@ -211,7 +190,8 @@ onUnmounted(() => {
 
 .example-card {
   border: 1px solid var(--vp-c-border);
-  border-radius: 10px;
+  border-radius: var(--radius);
+  transition: border-color 0.18s ease;
   padding: 1rem 1.1rem;
   background: var(--vp-c-bg-soft);
   display: flex;
@@ -219,6 +199,10 @@ onUnmounted(() => {
   gap: 0.6rem;
 }
 
+.example-card:hover {
+  border-color: var(--vp-c-text-3);
+}
+
 .card-header {
   display: flex;
   justify-content: space-between;
@@ -231,15 +215,16 @@ onUnmounted(() => {
   letter-spacing: 0.03em;
   text-transform: uppercase;
   padding: 0.15rem 0.6rem;
-  border-radius: 20px;
+  border-radius: 999px;
   background: var(--vp-c-brand-1);
-  color: #fff;
+  color: var(--vp-c-bg);
 }
 
 .github-link {
   color: var(--vp-c-text-3);
   display: flex;
   align-items: center;
+  font-size: 15px;
   transition: color 0.15s;
 }
 
@@ -293,7 +278,7 @@ onUnmounted(() => {
   padding: 0.15rem 0.5rem;
   border-radius: 4px;
   background: var(--vp-c-brand-2);
-  color: #fff;
+  color: var(--vp-c-bg);
   cursor: default;
 }
 
@@ -331,7 +316,7 @@ onUnmounted(() => {
 .modal {
   background: var(--vp-c-bg);
   border: 1px solid var(--vp-c-border);
-  border-radius: 12px;
+  border-radius: var(--radius);
   width: 100%;
   max-width: 780px;
   max-height: 85vh;
@@ -373,9 +358,9 @@ onUnmounted(() => {
   letter-spacing: 0.03em;
   text-transform: uppercase;
   padding: 0.15rem 0.55rem;
-  border-radius: 20px;
+  border-radius: 999px;
   background: var(--vp-c-brand-1);
-  color: #fff;
+  color: var(--vp-c-bg);
   flex-shrink: 0;
 }
 
@@ -403,6 +388,11 @@ onUnmounted(() => {
   color: var(--vp-c-brand-1);
 }
 
+.modal-github-link :deep(.ui-icon) {
+  width: 16px;
+  height: 16px;
+}
+
 .modal-github-link {
   display: flex;
   align-items: center;
diff --git a/docs/.vitepress/theme/HomeBackdrop.vue b/docs/.vitepress/theme/HomeBackdrop.vue
new file mode 100644
index 00000000..edb5061c
--- /dev/null
+++ b/docs/.vitepress/theme/HomeBackdrop.vue
@@ -0,0 +1,269 @@
+<script setup lang="ts">
+import { onMounted, onUnmounted, ref } from 'vue'
+
+/**
+ * Ambient backdrop for the home page.
+ *
+ * A drifting node field — the same family as the one on jahvon.dev — but the
+ * edges here carry pulses that travel from node to node and pop when they
+ * land. It reads as work moving through a graph, which is what flow does.
+ *
+ * Vanilla canvas, no library. Colours are read from the theme's CSS variables
+ * so it follows dark/light without a second palette, and it holds a single
+ * static frame when the visitor asks for reduced motion.
+ */
+
+const canvas = ref<HTMLCanvasElement | null>(null)
+
+interface Node {
+  x: number
+  y: number
+  vx: number
+  vy: number
+  r: number
+}
+
+interface Pulse {
+  from: number
+  to: number
+  /** 0 → 1 along the edge, then a short pop while > 1. */
+  t: number
+  speed: number
+}
+
+const LINK_DISTANCE = 150
+const MAX_PULSES = 5
+
+onMounted(() => {
+  const el = canvas.value
+  if (!el) return
+  const ctx = el.getContext('2d')
+  if (!ctx) return
+
+  const reduced = matchMedia('(prefers-reduced-motion: reduce)').matches
+  const dpr = Math.min(window.devicePixelRatio || 1, 2)
+
+  let width = 0
+  let height = 0
+  let nodes: Node[] = []
+  let pulses: Pulse[] = []
+  let frame: number | null = null
+  let running = false
+  let phase = 0
+
+  let cEdge = ''
+  let cNode = ''
+  let cPulse = ''
+
+  function readColors() {
+    const style = getComputedStyle(document.documentElement)
+    cEdge = style.getPropertyValue('--vp-c-divider').trim() || '#ddd'
+    cNode = style.getPropertyValue('--vp-c-text-3').trim() || '#999'
+    cPulse = style.getPropertyValue('--vp-c-brand-1').trim() || '#7FBBB3'
+  }
+
+  function resize() {
+    width = el!.clientWidth
+    height = el!.clientHeight
+    el!.width = width * dpr
+    el!.height = height * dpr
+    ctx!.setTransform(dpr, 0, 0, dpr, 0, 0)
+  }
+
+  function seed() {
+    const count = Math.max(10, Math.min(28, Math.round((width * height) / 46000)))
+    nodes = Array.from({ length: count }, () => ({
+      x: Math.random() * width,
+      y: Math.random() * height,
+      vx: (Math.random() - 0.5) * 0.13,
+      vy: (Math.random() - 0.5) * 0.13,
+      r: 1.3 + Math.random() * 1.3,
+    }))
+    pulses = []
+  }
+
+  function distance(a: Node, b: Node) {
+    return Math.hypot(a.x - b.x, a.y - b.y)
+  }
+
+  /** Send a pulse down some edge that currently exists. */
+  function spawnPulse() {
+    if (nodes.length < 2) return
+    const from = Math.floor(Math.random() * nodes.length)
+    const candidates: number[] = []
+    for (let i = 0; i < nodes.length; i++) {
+      if (i !== from && distance(nodes[from], nodes[i]) < LINK_DISTANCE) candidates.push(i)
+    }
+    if (!candidates.length) return
+    pulses.push({
+      from,
+      to: candidates[Math.floor(Math.random() * candidates.length)],
+      t: 0,
+      speed: 0.0035 + Math.random() * 0.004,
+    })
+  }
+
+  function draw() {
+    ctx!.clearRect(0, 0, width, height)
+
+    // Edges
+    ctx!.strokeStyle = cEdge
+    ctx!.lineWidth = 1
+    for (let i = 0; i < nodes.length; i++) {
+      for (let j = i + 1; j < nodes.length; j++) {
+        const d = distance(nodes[i], nodes[j])
+        if (d >= LINK_DISTANCE) continue
+        ctx!.globalAlpha = (1 - d / LINK_DISTANCE) * 0.45
+        ctx!.beginPath()
+        ctx!.moveTo(nodes[i].x, nodes[i].y)
+        ctx!.lineTo(nodes[j].x, nodes[j].y)
+        ctx!.stroke()
+      }
+    }
+
+    // Nodes
+    ctx!.fillStyle = cNode
+    for (const n of nodes) {
+      ctx!.globalAlpha = 0.55
+      ctx!.beginPath()
+      ctx!.arc(n.x, n.y, n.r, 0, Math.PI * 2)
+      ctx!.fill()
+    }
+
+    // Pulses in transit, and the pop where one lands
+    for (const p of pulses) {
+      const a = nodes[p.from]
+      const b = nodes[p.to]
+      if (!a || !b) continue
+
+      if (p.t <= 1) {
+        const x = a.x + (b.x - a.x) * p.t
+        const y = a.y + (b.y - a.y) * p.t
+        // Fade in and out so pulses never blink on at full strength.
+        ctx!.globalAlpha = Math.sin(p.t * Math.PI) * 0.85
+        ctx!.fillStyle = cPulse
+        ctx!.beginPath()
+        ctx!.arc(x, y, 2.1, 0, Math.PI * 2)
+        ctx!.fill()
+      } else {
+        const pop = (p.t - 1) / 0.35
+        ctx!.globalAlpha = (1 - pop) * 0.5
+        ctx!.strokeStyle = cPulse
+        ctx!.lineWidth = 1.2
+        ctx!.beginPath()
+        ctx!.arc(b.x, b.y, 2 + pop * 7, 0, Math.PI * 2)
+        ctx!.stroke()
+      }
+    }
+
+    ctx!.globalAlpha = 1
+  }
+
+  function step() {
+    for (const n of nodes) {
+      n.x += n.vx + Math.sin(phase + n.y * 0.008) * 0.045
+      n.y += n.vy + Math.cos(phase + n.x * 0.008) * 0.045
+      if (n.x < -20) n.x = width + 20
+      else if (n.x > width + 20) n.x = -20
+      if (n.y < -20) n.y = height + 20
+      else if (n.y > height + 20) n.y = -20
+    }
+    phase += 0.004
+
+    for (const p of pulses) p.t += p.speed
+    pulses = pulses.filter(
+      (p) => p.t < 1.35 && distance(nodes[p.from], nodes[p.to]) < LINK_DISTANCE * 1.25
+    )
+    if (pulses.length < MAX_PULSES && Math.random() < 0.018) spawnPulse()
+  }
+
+  function loop() {
+    if (!running) return
+    step()
+    draw()
+    frame = requestAnimationFrame(loop)
+  }
+
+  function start() {
+    if (running || reduced) return
+    running = true
+    loop()
+  }
+
+  function stop() {
+    running = false
+    if (frame !== null) cancelAnimationFrame(frame)
+    frame = null
+  }
+
+  function onVisibility() {
+    if (document.hidden) stop()
+    else start()
+  }
+
+  let resizeTimer: number | undefined
+  function onResize() {
+    window.clearTimeout(resizeTimer)
+    resizeTimer = window.setTimeout(() => {
+      resize()
+      seed()
+      draw()
+    }, 180)
+  }
+
+  const themeWatcher = new MutationObserver(() => {
+    readColors()
+    draw()
+  })
+
+  readColors()
+  resize()
+  seed()
+  draw()
+  start()
+
+  document.addEventListener('visibilitychange', onVisibility)
+  window.addEventListener('resize', onResize)
+  themeWatcher.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ['class'],
+  })
+
+  onUnmounted(() => {
+    stop()
+    document.removeEventListener('visibilitychange', onVisibility)
+    window.removeEventListener('resize', onResize)
+    themeWatcher.disconnect()
+    window.clearTimeout(resizeTimer)
+  })
+})
+</script>
+
+<template>
+  <canvas ref="canvas" class="home-backdrop" aria-hidden="true" />
+</template>
+
+<style scoped>
+.home-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 0;
+  display: block;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+  opacity: 0.55;
+}
+
+@media (max-width: 700px) {
+  .home-backdrop {
+    opacity: 0.34;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .home-backdrop {
+    opacity: 0.28;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/Icon.vue b/docs/.vitepress/theme/Icon.vue
new file mode 100644
index 00000000..09bacbff
--- /dev/null
+++ b/docs/.vitepress/theme/Icon.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { ICONS, FILLED } from './icons'
+
+const props = defineProps<{ name: string }>()
+
+const markup = computed(() => ICONS[props.name] ?? '')
+const filled = computed(() => FILLED.has(props.name))
+</script>
+
+<template>
+  <svg
+    class="ui-icon"
+    viewBox="0 0 24 24"
+    :fill="filled ? 'currentColor' : 'none'"
+    :stroke="filled ? 'none' : 'currentColor'"
+    stroke-width="1.6"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+    focusable="false"
+    v-html="markup"
+  />
+</template>
+
+<style scoped>
+.ui-icon {
+  width: 1em;
+  height: 1em;
+  flex: 0 0 auto;
+  opacity: 0.75;
+}
+</style>
diff --git a/docs/.vitepress/theme/Layout.vue b/docs/.vitepress/theme/Layout.vue
new file mode 100644
index 00000000..eb829184
--- /dev/null
+++ b/docs/.vitepress/theme/Layout.vue
@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import { computed, defineAsyncComponent, onMounted, onUnmounted } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import { useData } from 'vitepress'
+import AskTrigger from './AskTrigger.vue'
+import AskBridge from './AskBridge.vue'
+import { askOpen, openAsk } from './askState'
+
+const { Layout } = DefaultTheme
+const { frontmatter } = useData()
+
+// Both of these pull in weight the rest of the site never needs — markdown-it
+// for the answer, a canvas loop for the backdrop — so neither is in the main
+// chunk.
+const AskDeepWiki = defineAsyncComponent(() => import('./AskDeepWiki.vue'))
+const HomeBackdrop = defineAsyncComponent(() => import('./HomeBackdrop.vue'))
+
+const isHome = computed(() => frontmatter.value.layout === 'home')
+
+function isEditingContent(event: KeyboardEvent) {
+  const el = event.target as HTMLElement | null
+  return (
+    !!el &&
+    (el.isContentEditable ||
+      el.tagName === 'INPUT' ||
+      el.tagName === 'SELECT' ||
+      el.tagName === 'TEXTAREA')
+  )
+}
+
+// VitePress already owns ⌘K and `/` for local search.
+function onKeydown(event: KeyboardEvent) {
+  if (event.key.toLowerCase() !== 'i' || !(event.metaKey || event.ctrlKey)) return
+  if (isEditingContent(event)) return
+  event.preventDefault()
+  openAsk()
+}
+
+onMounted(() => window.addEventListener('keydown', onKeydown))
+onUnmounted(() => window.removeEventListener('keydown', onKeydown))
+</script>
+
+<template>
+  <Layout>
+    <!-- Before the menu, so the two ways to look something up sit together
+         instead of at opposite ends of the bar. -->
+    <template #nav-bar-content-before>
+      <AskTrigger />
+    </template>
+    <template #nav-screen-content-after>
+      <AskTrigger />
+    </template>
+  </Layout>
+
+  <HomeBackdrop v-if="isHome" />
+  <AskBridge />
+  <AskDeepWiki v-if="askOpen" />
+</template>
diff --git a/docs/.vitepress/theme/NowStrip.vue b/docs/.vitepress/theme/NowStrip.vue
new file mode 100644
index 00000000..3ff6c9bc
--- /dev/null
+++ b/docs/.vitepress/theme/NowStrip.vue
@@ -0,0 +1,153 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import Icon from './Icon.vue'
+import { data as release } from '../../release.data.js'
+
+const INSTALL_CMD = 'curl -sSL https://install.flowexec.io | bash'
+
+const copied = ref(false)
+async function copyInstall() {
+  await navigator.clipboard.writeText(INSTALL_CMD)
+  copied.value = true
+  setTimeout(() => {
+    copied.value = false
+  }, 2000)
+}
+</script>
+
+<template>
+  <ul class="now-strip">
+    <li class="now-item">
+      <Icon name="terminal" />
+      <div class="now-item__body">
+        <span class="now-item__label">Install</span>
+        <button
+          class="now-item__cmd"
+          :title="copied ? 'Copied' : 'Copy to clipboard'"
+          @click="copyInstall"
+        >
+          <code>{{ INSTALL_CMD }}</code>
+          <Icon :name="copied ? 'check' : 'copy'" />
+        </button>
+      </div>
+    </li>
+
+    <li class="now-item">
+      <Icon name="layers" />
+      <div class="now-item__body">
+        <span class="now-item__label">Latest</span>
+        <span class="now-item__value tabular">
+          <a :href="release.url">{{ release.tag || 'Releases' }}</a>
+        </span>
+      </div>
+    </li>
+
+    <li class="now-item">
+      <Icon name="monitor" />
+      <div class="now-item__body">
+        <span class="now-item__label">Runs on</span>
+        <span class="now-item__value">macOS · Linux · Windows</span>
+      </div>
+    </li>
+  </ul>
+</template>
+
+<style scoped>
+/* The 2px gap over a border-coloured ground *is* the hairline divider — one
+   rule instead of per-cell borders that double up at the seams. */
+.now-strip {
+  display: grid;
+  grid-template-columns: minmax(0, 1.6fr) repeat(auto-fit, minmax(150px, 1fr));
+  gap: 1px;
+  margin: 0 0 calc(var(--gap) * 1.2);
+  padding: 0;
+  list-style: none;
+  background: var(--vp-c-border);
+  border: 1px solid var(--vp-c-border);
+  border-radius: var(--radius);
+  overflow: hidden;
+}
+
+.now-item {
+  display: flex;
+  align-items: flex-start;
+  gap: 11px;
+  margin: 0;
+  padding: 15px 17px;
+  background: var(--vp-c-bg);
+  font-size: 14px;
+}
+
+.now-item > :deep(.ui-icon) {
+  width: 15px;
+  height: 15px;
+  margin-top: 3px;
+  color: var(--vp-c-text-2);
+}
+
+.now-item__body {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  min-width: 0;
+}
+
+.now-item__label {
+  font-size: 10.5px;
+  line-height: 1.4;
+  letter-spacing: 0.09em;
+  text-transform: uppercase;
+  color: var(--vp-c-text-2);
+}
+
+.now-item__value {
+  line-height: 1.45;
+  color: var(--vp-c-text-1);
+}
+
+.now-item__value a {
+  color: var(--vp-c-brand-1);
+  text-decoration: none;
+  box-shadow: 0 1px 0 var(--vp-c-brand-1);
+}
+
+.now-item__cmd {
+  display: inline-flex;
+  align-items: center;
+  gap: 9px;
+  min-width: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--vp-c-text-1);
+  cursor: pointer;
+  text-align: left;
+}
+
+.now-item__cmd code {
+  overflow: hidden;
+  font-family: var(--vp-font-family-mono);
+  font-size: 12.5px;
+  line-height: 1.5;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.now-item__cmd :deep(.ui-icon) {
+  width: 14px;
+  height: 14px;
+  color: var(--vp-c-text-3);
+  transition: color 0.18s ease;
+}
+
+.now-item__cmd:hover :deep(.ui-icon) {
+  color: var(--vp-c-brand-1);
+  opacity: 1;
+}
+
+@media (max-width: 700px) {
+  .now-strip {
+    grid-template-columns: 1fr;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/NumberedSection.vue b/docs/.vitepress/theme/NumberedSection.vue
new file mode 100644
index 00000000..3ab0ea09
--- /dev/null
+++ b/docs/.vitepress/theme/NumberedSection.vue
@@ -0,0 +1,107 @@
+<script setup lang="ts">
+defineProps<{
+  index: string
+  label: string
+  claim: string
+  /** The "not another X — Y" line that heads off the obvious misreading. */
+  aside?: string
+}>()
+</script>
+
+<template>
+  <section class="numbered">
+    <div class="numbered__rail">
+      <span class="numbered__index tabular">{{ index }}</span>
+      <span class="numbered__label">{{ label }}</span>
+    </div>
+    <div class="numbered__body">
+      <p class="numbered__claim">{{ claim }}</p>
+      <p class="numbered__text"><slot /></p>
+      <p v-if="aside" class="numbered__aside">{{ aside }}</p>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.numbered {
+  display: grid;
+  grid-template-columns: 6.5rem minmax(0, 1fr);
+  gap: 0 24px;
+  padding: 26px 0;
+  border-top: 1px solid var(--vp-c-divider);
+}
+
+.numbered__rail {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding-top: 3px;
+}
+
+.numbered__index {
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  color: var(--vp-c-text-3);
+}
+
+.numbered__label {
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--vp-c-brand-1);
+}
+
+.numbered__claim {
+  max-width: 36ch;
+  margin: 0 0 10px;
+  font-size: 19px;
+  font-weight: 600;
+  line-height: 1.42;
+  letter-spacing: -0.014em;
+  color: var(--vp-c-text-1);
+}
+
+.numbered__text :deep(code) {
+  padding: 2px 5px;
+  border-radius: 4px;
+  background: var(--vp-c-default-soft);
+  font-family: var(--vp-font-family-mono);
+  font-size: 0.88em;
+}
+
+.numbered__text {
+  max-width: 68ch;
+  margin: 0;
+  font-size: 15px;
+  line-height: 1.7;
+  color: var(--vp-c-text-2);
+}
+
+.numbered__aside {
+  max-width: 66ch;
+  margin: 14px 0 0;
+  padding-left: 13px;
+  border-left: 2px solid var(--vp-c-border);
+  font-size: 13.5px;
+  line-height: 1.62;
+  color: var(--vp-c-text-3);
+}
+
+@media (max-width: 600px) {
+  .numbered {
+    grid-template-columns: 1fr;
+    gap: 10px;
+  }
+  .numbered__rail {
+    flex-direction: row;
+    align-items: baseline;
+    gap: 10px;
+    padding-top: 0;
+  }
+  .numbered__claim {
+    font-size: 17px;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/SectionHead.vue b/docs/.vitepress/theme/SectionHead.vue
new file mode 100644
index 00000000..47060697
--- /dev/null
+++ b/docs/.vitepress/theme/SectionHead.vue
@@ -0,0 +1,78 @@
+<script setup lang="ts">
+import Icon from './Icon.vue'
+
+defineProps<{
+  icon: string
+  label: string
+  moreText?: string
+  moreLink?: string
+}>()
+</script>
+
+<template>
+  <h2 class="home-section__title">
+    <span class="home-section__label">
+      <Icon :name="icon" />
+      {{ label }}
+    </span>
+    <a v-if="moreLink" class="home-section__more" :href="moreLink">
+      {{ moreText ?? 'More' }}
+      <Icon name="arrowRight" />
+    </a>
+  </h2>
+</template>
+
+<style scoped>
+h2.home-section__title {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  margin: calc(var(--gap) * 1.6) 0 calc(var(--gap) * 0.8);
+  padding-bottom: 10px;
+  border: 0;
+  border-bottom: 1px solid var(--vp-c-border);
+  font-size: 15px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--vp-c-text-2);
+}
+
+.home-section__label {
+  display: inline-flex;
+  align-items: center;
+  gap: 9px;
+}
+
+.home-section__label :deep(.ui-icon) {
+  width: 1.05em;
+  height: 1.05em;
+}
+
+.home-section__more {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 13px;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+  text-transform: none;
+  white-space: nowrap;
+  color: var(--vp-c-text-2);
+  text-decoration: none;
+  transition: color 0.18s ease;
+}
+
+.home-section__more:hover {
+  color: var(--vp-c-brand-1);
+}
+
+@media (max-width: 600px) {
+  h2.home-section__title {
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 4px;
+  }
+}
+</style>
diff --git a/docs/.vitepress/theme/askState.ts b/docs/.vitepress/theme/askState.ts
new file mode 100644
index 00000000..a57a75da
--- /dev/null
+++ b/docs/.vitepress/theme/askState.ts
@@ -0,0 +1,14 @@
+import { ref } from 'vue'
+
+/**
+ * Shared state for the Ask panel. The trigger renders in two places (desktop
+ * nav and mobile nav screen) but the modal is mounted once by Layout.vue, so
+ * the open flag has to live outside both.
+ */
+export const askOpen = ref(false)
+export const askQuery = ref('')
+
+export function openAsk(query = '') {
+  if (query) askQuery.value = query
+  askOpen.value = true
+}
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
index 2ef06381..a1706729 100644
--- a/docs/.vitepress/theme/custom.css
+++ b/docs/.vitepress/theme/custom.css
@@ -1,58 +1,3 @@
-:root {
-  --vp-c-brand-1: #7FBBB3;
-  --vp-c-brand-2: #83C092;
-  --vp-c-brand-3: #D699B6;
-  --vp-home-hero-name-color: #7FBBB3;
-  --vp-button-brand-bg: #7FBBB3;
-  --vp-button-brand-hover-bg: #6BAAA2;
-  --vp-button-brand-active-bg: #7FBBB3;
-
-  --vp-custom-block-tip-border: #7FBBB3;
-  --vp-custom-block-tip-text: var(--vp-c-text-1);
-  --vp-custom-block-tip-bg: rgba(127, 187, 179, 0.1);
-  --vp-custom-block-tip-code-bg: rgba(127, 187, 179, 0.15);
-}
-
-/* Hero layout */
-.VPHero {
-  padding-top: 140px !important;
-  padding-bottom: 80px !important;
-}
-
-/* Hero image */
-.VPHero .image-src {
-  max-width: 220px !important;
-  max-height: 220px !important;
-  filter: drop-shadow(5px 5px 100px #D699B6);
-}
-
-.VPHero .name {
-  font-size: 1.8em !important;
-  line-height: 1.8em !important;
-}
-
-.VPHero .text {
-  font-size: 3.2em !important;
-  line-height: 1.2em !important;
-}
-
-.VPHero .tagline {
-  font-size: 1.4em !important;
-  line-height: 1.8em !important;
-}
-
-@media (max-width: 639px) {
-  .VPHero {
-    padding-top: 72px !important;
-    padding-bottom: 48px !important;
-    overflow-x: hidden;
-  }
-
-  .VPHero .text {
-    font-size: 2em !important;
-  }
-
-  .VPHero .tagline {
-    font-size: 1.1em !important;
-  }
-}
\ No newline at end of file
+@import './styles/tokens.css';
+@import './styles/rhythm.css';
+@import './styles/overrides.css';
diff --git a/docs/.vitepress/theme/deepwiki.ts b/docs/.vitepress/theme/deepwiki.ts
new file mode 100644
index 00000000..0b8d6732
--- /dev/null
+++ b/docs/.vitepress/theme/deepwiki.ts
@@ -0,0 +1,170 @@
+/**
+ * DeepWiki client.
+ *
+ * DeepWiki indexes flowexec/flow and exposes an `ask_question` tool over a
+ * public, unauthenticated MCP endpoint. The endpoint is stateless — no
+ * `initialize` handshake and no session id — so a single POST is the whole
+ * protocol, and it answers `Access-Control-Allow-Origin: *`, which is what
+ * makes calling it straight from the page possible.
+ *
+ * It replies with an SSE stream: progress notifications while the model works
+ * (~15-20s is normal), then one frame carrying the answer.
+ *
+ * None of this is versioned or documented by DeepWiki. Callers must handle
+ * failure by pointing people at deepwiki.com rather than showing a dead UI.
+ */
+
+const ENDPOINT = 'https://mcp.deepwiki.com/mcp'
+export const REPO = 'flowexec/flow'
+export const DEEPWIKI_URL = `https://deepwiki.com/${REPO}`
+
+/** Generous ceiling: observed round trips are ~16s. */
+const TIMEOUT_MS = 90_000
+
+export interface AskOptions {
+  /** Seconds elapsed, as reported by DeepWiki's own progress notifications. */
+  onProgress?: (elapsedSeconds: number) => void
+  signal?: AbortSignal
+}
+
+export class DeepWikiError extends Error {}
+
+export async function askDeepWiki(
+  question: string,
+  { onProgress, signal }: AskOptions = {}
+): Promise<string> {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS)
+  const relay = () => controller.abort()
+  signal?.addEventListener('abort', relay)
+
+  try {
+    const res = await fetch(ENDPOINT, {
+      method: 'POST',
+      // Only `content-type` is in the endpoint's Access-Control-Allow-Headers;
+      // `accept` rides along because it is a CORS-safelisted request header.
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: {
+          name: 'ask_question',
+          arguments: { repoName: REPO, question },
+        },
+      }),
+      signal: controller.signal,
+    })
+
+    if (!res.ok || !res.body) {
+      throw new DeepWikiError(`DeepWiki returned ${res.status}`)
+    }
+
+    const answer = await readStream(res.body, onProgress)
+    if (!answer) {
+      throw new DeepWikiError('DeepWiki closed the stream without an answer')
+    }
+    return tidy(answer)
+  } finally {
+    clearTimeout(timeout)
+    signal?.removeEventListener('abort', relay)
+  }
+}
+
+async function readStream(
+  body: ReadableStream<Uint8Array>,
+  onProgress?: (seconds: number) => void
+): Promise<string | null> {
+  const reader = body.pipeThrough(new TextDecoderStream()).getReader()
+  let buffer = ''
+  let answer: string | null = null
+
+  const handle = (frame: string) => {
+    const payload = parseFrame(frame)
+    if (!payload) return
+
+    if (payload.error) {
+      throw new DeepWikiError(payload.error.message ?? 'DeepWiki error')
+    }
+
+    if (payload.method === 'notifications/message') {
+      const msg = payload.params?.data?.msg
+      const seconds = typeof msg === 'string' ? elapsedFrom(msg) : null
+      if (seconds !== null) onProgress?.(seconds)
+      return
+    }
+
+    const text = payload.result?.content?.[0]?.text
+    if (typeof text === 'string') answer = text
+  }
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) break
+      buffer += value
+
+      // DeepWiki terminates frames with CRLFCRLF, not the bare LFLF that most
+      // SSE examples show. Hold the trailing partial back for the next chunk.
+      const frames = buffer.split(/\r?\n\r?\n/)
+      buffer = frames.pop() ?? ''
+      frames.forEach(handle)
+    }
+    // The answer is the last thing sent and may arrive without a closing blank
+    // line, so whatever is left when the stream ends still has to be read.
+    if (buffer.trim()) handle(buffer)
+  } finally {
+    reader.cancel().catch(() => {})
+  }
+
+  return answer
+}
+
+interface Frame {
+  method?: string
+  params?: { data?: { msg?: string } }
+  result?: { content?: Array<{ type?: string; text?: string }> }
+  error?: { message?: string }
+}
+
+function parseFrame(frame: string): Frame | null {
+  for (const line of frame.split('\n')) {
+    // `:` lines are keep-alive comments.
+    if (!line.startsWith('data:')) continue
+    try {
+      return JSON.parse(line.slice(5).trim()) as Frame
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+function elapsedFrom(msg: string): number | null {
+  const match = /\((\d+)s elapsed\)/.exec(msg)
+  return match ? Number(match[1]) : null
+}
+
+/**
+ * DeepWiki strips its inline citation markers on the way out and leaves the
+ * whitespace behind, so answers arrive with runs of spaces and orphaned gaps
+ * before punctuation. Fenced code is left exactly as sent.
+ */
+function tidy(markdown: string): string {
+  return markdown
+    .split(/(```[\s\S]*?```)/g)
+    .map((segment, i) =>
+      i % 2 === 1
+        ? segment
+        : segment
+            .replace(/[ \t]+([.,;:!?)])/g, '$1')
+            .replace(/[ \t]{2,}/g, ' ')
+            .replace(/[ \t]+$/gm, '')
+            .replace(/\]\(\/(wiki|search)\//g, '](https://deepwiki.com/$1/')
+    )
+    .join('')
+    .trim()
+}
diff --git a/docs/.vitepress/theme/icons.ts b/docs/.vitepress/theme/icons.ts
new file mode 100644
index 00000000..1f5bea2a
--- /dev/null
+++ b/docs/.vitepress/theme/icons.ts
@@ -0,0 +1,42 @@
+/**
+ * Inline icon set — feather-style, 24x24, stroked at 1.6.
+ *
+ * Values are the inner markup of the <svg>; Icon.vue supplies the wrapper so
+ * viewBox, stroke width, and joins stay identical everywhere. Everything here
+ * is an authored constant, never user input, which is what makes rendering it
+ * with v-html safe.
+ */
+
+export const ICONS: Record<string, string> = {
+  terminal: '<path d="m4 17 6-5-6-5"/><path d="M12 19h8"/>',
+  layers: '<path d="m12 2 9 5-9 5-9-5z"/><path d="m3 12 9 5 9-5"/><path d="m3 17 9 5 9-5"/>',
+  box: '<path d="M12 2 3 7v10l9 5 9-5V7z"/><path d="m3 7 9 5 9-5"/><path d="M12 12v10"/>',
+  book: '<path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20"/><path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z"/>',
+  folder:
+    '<path d="M4 20h16a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2z"/>',
+  lock: '<rect x="3" y="11" width="18" height="11" rx="2"/><path d="M7 11V7a5 5 0 0 1 10 0v4"/>',
+  zap: '<path d="m13 2-10 12h9l-1 8 10-12h-9l1-8z"/>',
+  file: '<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/><path d="M16 13H8"/><path d="M16 17H8"/>',
+  monitor:
+    '<rect x="2" y="3" width="20" height="14" rx="2"/><path d="M8 21h8"/><path d="M12 17v4"/>',
+  plug: '<path d="M12 22v-5"/><path d="M9 8V2"/><path d="M15 8V2"/><path d="M18 8v5a4 4 0 0 1-4 4h-4a4 4 0 0 1-4-4V8z"/>',
+  sparkle:
+    '<path d="m12 3 1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9z"/><path d="m19 15 .7 1.9 1.9.7-1.9.7-.7 1.9-.7-1.9-1.9-.7 1.9-.7z"/>',
+  search: '<circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/>',
+  download: '<path d="M12 3v12"/><path d="m7 12 5 5 5-5"/><path d="M5 21h14"/>',
+  copy: '<rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>',
+  check: '<path d="m5 13 4 4L19 7"/>',
+  arrowRight: '<path d="M5 12h14"/><path d="m12 5 7 7-7 7"/>',
+  enter: '<path d="m9 10-5 5 5 5"/><path d="M20 4v7a4 4 0 0 1-4 4H4"/>',
+  clock: '<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/>',
+  pin: '<path d="M20 10c0 6-8 12-8 12s-8-6-8-12a8 8 0 0 1 16 0z"/><circle cx="12" cy="10" r="3"/>',
+  alert: '<circle cx="12" cy="12" r="9"/><path d="M12 8v5"/><path d="M12 16h.01"/>',
+  close: '<path d="M18 6 6 18"/><path d="m6 6 12 12"/>',
+  external:
+    '<path d="M15 3h6v6"/><path d="M10 14 21 3"/><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h6"/>',
+  github:
+    '<path d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385.6.105.825-.255.825-.57 0-.285-.015-1.23-.015-2.235-3.015.555-3.795-.735-4.035-1.41-.135-.345-.72-1.41-1.23-1.695-.42-.225-1.02-.78-.015-.795.945-.015 1.62.87 1.845 1.23 1.08 1.815 2.805 1.305 3.495.99.105-.78.42-1.305.765-1.605-2.67-.3-5.46-1.335-5.46-5.925 0-1.305.465-2.385 1.23-3.225-.12-.3-.54-1.53.12-3.18 0 0 1.005-.315 3.3 1.23.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23.66 1.65.24 2.88.12 3.18.765.84 1.23 1.905 1.23 3.225 0 4.605-2.805 5.625-5.475 5.925.435.375.81 1.095.81 2.22 0 1.605-.015 2.895-.015 3.3 0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12z"/>',
+}
+
+/** Icons drawn as solid shapes rather than strokes. */
+export const FILLED = new Set(['github'])
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 3551350b..53f7fed3 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -1,13 +1,27 @@
 import type { Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
 import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
+import Layout from './Layout.vue'
 import ExamplesGallery from './ExamplesGallery.vue'
+import Icon from './Icon.vue'
+import SectionHead from './SectionHead.vue'
+import NumberedSection from './NumberedSection.vue'
+import CardGrid from './CardGrid.vue'
+import Card from './Card.vue'
+import NowStrip from './NowStrip.vue'
 import './custom.css'
 
 export default {
     extends: DefaultTheme,
+    Layout,
     enhanceApp({ app }) {
         enhanceAppWithTabs(app)
         app.component('ExamplesGallery', ExamplesGallery)
+        app.component('Icon', Icon)
+        app.component('SectionHead', SectionHead)
+        app.component('NumberedSection', NumberedSection)
+        app.component('CardGrid', CardGrid)
+        app.component('Card', Card)
+        app.component('NowStrip', NowStrip)
     },
-} satisfies Theme
\ No newline at end of file
+} satisfies Theme
diff --git a/docs/.vitepress/theme/styles/overrides.css b/docs/.vitepress/theme/styles/overrides.css
new file mode 100644
index 00000000..7934d3fd
--- /dev/null
+++ b/docs/.vitepress/theme/styles/overrides.css
@@ -0,0 +1,296 @@
+/* ---------------------------------------------------------------------------
+   Default-theme chrome, retuned to the same language as the components.
+
+   VitePress ships these rules as scoped styles, so their selectors carry an
+   extra `[data-v-*]` attribute and outrank a plain class here. Where a rule
+   below is marked, `!important` is the only way to reach it without forking
+   the component.
+   --------------------------------------------------------------------------- */
+
+/* --- Nav ------------------------------------------------------------------ */
+
+.VPNavBar {
+  border-bottom: 1px solid transparent;
+}
+
+.VPNavBar.has-sidebar .curtain {
+  display: none;
+}
+
+.VPNavBarMenuLink,
+.VPNavBarMenuGroup .VPMenuLink {
+  font-weight: 500;
+  letter-spacing: 0.005em;
+}
+
+/* --- Sidebar -------------------------------------------------------------- */
+
+.VPSidebarItem.level-0 > .item > .text {
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--vp-c-text-2);
+}
+
+.VPSidebarItem.is-link > .item > .link:hover .text {
+  color: var(--vp-c-brand-1);
+}
+
+.VPSidebarItem.level-1 .indicator,
+.VPSidebarItem.level-2 .indicator,
+.VPSidebarItem.level-3 .indicator {
+  border-radius: 1px;
+}
+
+/* --- Aside / outline ------------------------------------------------------ */
+
+.VPDocAsideOutline .outline-title {
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--vp-c-text-2);
+}
+
+.VPDocAsideOutline .content {
+  border-left-color: var(--vp-c-divider);
+}
+
+/* --- Doc footer ----------------------------------------------------------- */
+
+.VPDocFooter .prev-next {
+  border-top: 1px solid var(--vp-c-divider);
+}
+
+.VPDocFooter .pager-link {
+  border-radius: var(--radius);
+  border-color: var(--vp-c-border);
+  transition: border-color 0.18s ease;
+}
+
+.VPDocFooter .pager-link:hover {
+  border-color: var(--vp-c-text-3);
+}
+
+.VPDocFooter .desc {
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--vp-c-text-3);
+}
+
+/* --- Local search --------------------------------------------------------
+   The Ask panel is styled as this modal's sibling, so the two have to agree on
+   radius, edge, and footer treatment.
+   ------------------------------------------------------------------------- */
+
+.VPLocalSearchBox .shell {
+  border-radius: var(--radius) !important; /* scoped rule sets 6px */
+  border: 1px solid var(--vp-c-border);
+}
+
+.VPLocalSearchBox .search-bar {
+  border-radius: 8px;
+  border-color: var(--vp-c-border);
+}
+
+.VPLocalSearchBox .result {
+  border-radius: 8px;
+}
+
+/* --- Nav search button ---------------------------------------------------- */
+
+.DocSearch-Button,
+.VPNavBarSearchButton {
+  border-radius: 8px;
+}
+
+/* --- Home hero -----------------------------------------------------------
+   Sizing is VitePress's own; the only thing this design removes is the glow
+   plate behind the mark (killed via --vp-home-hero-image-* in tokens.css).
+   ------------------------------------------------------------------------- */
+
+.VPHero .VPImage {
+  border-radius: 0;
+}
+
+.VPHero .tagline {
+  max-width: 46ch;
+  color: var(--vp-c-text-2);
+}
+
+.VPHome {
+  margin-bottom: 72px;
+}
+
+/* The custom home sections carry their own rhythm; VitePress's doc spacing
+   would double it up. */
+.VPHome .vp-doc > div > .home-section:first-child {
+  margin-top: 0;
+}
+
+/* --- Home backdrop -------------------------------------------------------
+   The ambient canvas is fixed at z-index 0 and the page ground paints behind
+   it, so the app shell has to establish a stacking context above it.
+   ------------------------------------------------------------------------- */
+
+.Layout {
+  position: relative;
+  z-index: 1;
+}
+
+.VPNav,
+.VPLocalNav {
+  background-color: var(--vp-c-bg);
+}
+
+/* --- Home hero eyebrow ---------------------------------------------------
+   `hero.name` is the only slot above the headline, and VitePress renders it at
+   headline size. Both rules below fight the component's own scoped styles,
+   which carry an extra [data-v-*] and cannot be outranked from here.
+   ------------------------------------------------------------------------- */
+
+.VPHero .name {
+  font-size: 12px !important;
+  line-height: 1.4 !important;
+  font-weight: 600;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+  margin-bottom: 14px;
+}
+
+.VPHero .text {
+  max-width: 18ch;
+  font-size: 42px !important;
+  line-height: 1.16 !important;
+  letter-spacing: -0.03em;
+}
+
+.VPHero .tagline {
+  font-size: 15.5px !important;
+  line-height: 1.68 !important;
+}
+
+@media (max-width: 959px) {
+  .VPHero .text {
+    max-width: none;
+    font-size: 34px !important;
+  }
+}
+
+@media (max-width: 639px) {
+  .VPHero .text {
+    font-size: 28px !important;
+  }
+}
+
+/* --- Home closer ---------------------------------------------------------- */
+
+.home-closer {
+  margin: calc(var(--gap) * 2) 0 0;
+  padding-top: calc(var(--gap) * 0.8);
+  border-top: 1px solid var(--vp-c-divider);
+  font-size: 14px;
+  letter-spacing: 0.02em;
+  text-align: center;
+  color: var(--vp-c-text-3);
+}
+
+/* --- Search + Ask, as one group ------------------------------------------
+   The slot renders before VPNavBarSearch, which flex-grows to fill the bar and
+   would strand the Ask button at the far left. Reordering the two and moving
+   the growth onto Ask keeps them adjacent and pushes the menu right.
+   ------------------------------------------------------------------------- */
+
+/* Search moves ahead of the slot; Ask keeps the default order so it lands
+   first among the remaining children by DOM position, and its auto margin
+   pushes the menu and icons to the right. */
+.VPNavBar .content-body > .search {
+  order: -1;
+  flex-grow: 0;
+}
+
+.VPNavBar .content-body > .ask-trigger {
+  margin-right: auto;
+}
+
+/* Below the hamburger breakpoint the nav screen carries its own Ask row. */
+@media (max-width: 767px) {
+  .VPNavBar .content-body > .ask-trigger {
+    display: none;
+  }
+}
+
+.VPNavScreen .ask-trigger {
+  margin: 0 0 16px;
+}
+
+/* --- Badge rows ----------------------------------------------------------
+   Markdown emits shield badges as adjacent inline links with no separator, so
+   they butt together; and the doc-wide image radius is sized for screenshots,
+   not for a 20px-tall badge.
+   ------------------------------------------------------------------------- */
+
+.vp-doc .badge-row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  margin: 0 0 1.6em;
+}
+
+.vp-doc .badge-row a {
+  display: inline-flex;
+  line-height: 0;
+}
+
+.vp-doc .badge-row img {
+  height: 20px;
+  width: auto;
+  border-radius: 4px;
+}
+
+/* --- Hero mark -----------------------------------------------------------
+   VitePress sizes the mark at 320px on desktop with a glow plate of exactly
+   the same size, so the halo sits *behind* the logo instead of around it and
+   the pair dominates the hero. This scales the mark back and lets the plate
+   run wider than it, which reads as a wash rather than a disc.
+
+   The three-class selectors are deliberate: the component's own rules are
+   `.image-src[data-v-*]` and `.image-bg[data-v-*]`, which tie with a
+   two-class override and would win on source order.
+   ------------------------------------------------------------------------- */
+
+.VPHero .image-container .image-src {
+  max-width: 124px;
+  max-height: 124px;
+}
+
+.VPHero .image-container .image-bg {
+  width: 168px;
+  height: 168px;
+}
+
+@media (min-width: 640px) {
+  .VPHero .image-container .image-src {
+    max-width: 152px;
+    max-height: 152px;
+  }
+  .VPHero .image-container .image-bg {
+    width: 208px;
+    height: 208px;
+  }
+}
+
+@media (min-width: 960px) {
+  .VPHero .image-container .image-src {
+    max-width: 188px;
+    max-height: 188px;
+  }
+  .VPHero .image-container .image-bg {
+    width: 252px;
+    height: 252px;
+  }
+}
diff --git a/docs/.vitepress/theme/styles/rhythm.css b/docs/.vitepress/theme/styles/rhythm.css
new file mode 100644
index 00000000..17c7dfcb
--- /dev/null
+++ b/docs/.vitepress/theme/styles/rhythm.css
@@ -0,0 +1,168 @@
+/* ---------------------------------------------------------------------------
+   Rhythm.
+
+   Generous measure, a comfortable ruled pitch, soft rules instead of hard
+   borders, and nothing that raises its voice. Loaded after tokens so it can
+   retune the default theme's type and spacing.
+   --------------------------------------------------------------------------- */
+
+body {
+  line-height: 1.72;
+}
+
+.vp-doc p,
+.vp-doc li {
+  line-height: 1.78;
+}
+
+/* Headings: present, not loud. Lighter weight, tighter tracking, more air. */
+.vp-doc h1,
+.vp-doc h2,
+.vp-doc h3,
+.vp-doc h4 {
+  font-weight: 600;
+  letter-spacing: -0.011em;
+}
+
+.vp-doc h1 {
+  font-weight: 650;
+  letter-spacing: -0.022em;
+  font-size: 2.1rem;
+  line-height: 1.25;
+}
+
+.vp-doc h2 {
+  margin: 2.4em 0 0.9em;
+  padding-bottom: 0.34em;
+  border-top: 0;
+  border-bottom: 1px solid var(--vp-c-border);
+  font-size: 1.45rem;
+  letter-spacing: -0.014em;
+}
+
+.vp-doc h3 {
+  margin: 2em 0 0.7em;
+  font-size: 1.15rem;
+}
+
+.vp-doc h4 {
+  margin: 1.6em 0 0.6em;
+}
+
+/* Links: an underline you can read through, not a colour-only cue. */
+.vp-doc a {
+  font-weight: inherit;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 3px;
+  transition: color 0.18s ease;
+}
+
+/* Tables, code blocks, images: paper, not chrome. */
+.vp-doc table {
+  display: table;
+  width: 100%;
+  border-collapse: collapse;
+  overflow-x: auto;
+}
+
+/* Hairline rules carry the row separation, so the default zebra striping is
+   redundant. Its selector is `.vp-doc tr:nth-child(2n)`, which outranks a plain
+   `tr` rule — it has to be matched, not just overridden. */
+.vp-doc tr,
+.vp-doc tr:nth-child(2n) {
+  background: transparent;
+  border-top: 1px solid var(--vp-c-divider);
+}
+
+/* Reference tables put the prose in the last column; without this the fixed
+   columns claim the width and the description wraps into a narrow gutter. */
+.vp-doc table td:last-child,
+.vp-doc table th:last-child {
+  width: 100%;
+}
+
+.vp-doc table code {
+  white-space: nowrap;
+}
+
+.vp-doc th,
+.vp-doc td {
+  border: 0;
+  border-bottom: 1px solid var(--vp-c-divider);
+  padding: 11px 14px 11px 0;
+}
+
+.vp-doc th {
+  background: transparent;
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--vp-c-text-2);
+}
+
+.vp-doc div[class*='language-'],
+.vp-doc .vp-code-group,
+.vp-doc img {
+  border-radius: var(--radius);
+}
+
+.vp-doc div[class*='language-'] {
+  border: 1px solid var(--vp-c-divider);
+}
+
+.vp-doc blockquote {
+  border-left: 2px solid var(--vp-c-border);
+  color: var(--vp-c-text-2);
+}
+
+.vp-doc .custom-block {
+  border-radius: var(--radius);
+  border-width: 1px;
+  border-left-width: 3px;
+}
+
+/* Anything numeric lines up in a column: versions, dates, counts. */
+time,
+.vp-doc kbd,
+.tabular {
+  font-variant-numeric: tabular-nums;
+}
+
+.vp-doc kbd {
+  display: inline-block;
+  padding: 1px 6px;
+  border: 1px solid var(--vp-c-border);
+  border-radius: 5px;
+  background: var(--vp-c-bg-soft);
+  font-family: var(--vp-font-family-mono);
+  font-size: 0.85em;
+  line-height: 1.5;
+}
+
+/* Cards change their edge on hover, never their size. */
+.VPFeature,
+.VPTeamMembersItem {
+  border-radius: var(--radius);
+  border-color: var(--vp-c-border);
+  transition: border-color 0.18s ease, background-color 0.18s ease;
+}
+
+.VPFeature:hover {
+  border-color: var(--vp-c-text-3);
+  transform: none;
+}
+
+.VPButton {
+  border-radius: 8px;
+  font-weight: 500;
+  transition: border-color 0.18s ease, background-color 0.18s ease,
+    color 0.18s ease;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  * {
+    transition-duration: 0.01ms !important;
+    animation-duration: 0.01ms !important;
+  }
+}
diff --git a/docs/.vitepress/theme/styles/tokens.css b/docs/.vitepress/theme/styles/tokens.css
new file mode 100644
index 00000000..07f59606
--- /dev/null
+++ b/docs/.vitepress/theme/styles/tokens.css
@@ -0,0 +1,266 @@
+/* ---------------------------------------------------------------------------
+   Everforest, mapped onto VitePress's variable contract.
+
+   VitePress derives almost everything from the primitive scales (gray-*,
+   red-*, …) and the background/text/border trio, so overriding those is enough
+   to retheme the whole default theme without touching its components.
+
+   Accents are Everforest medium. The light-mode accents are darkened from the
+   published palette: Everforest light is a deliberately low-contrast theme, and
+   the stock values land near 2.8:1 on cream, under the 4.5:1 needed for link
+   text. Every value below is checked against its own background.
+   --------------------------------------------------------------------------- */
+
+:root {
+  /* Everforest light — bg0/bg1/bg2/bg3, fg, greys */
+  --ef-bg0: #FDF6E3;
+  --ef-bg1: #F4F0D9;
+  --ef-bg2: #EFEBD4;
+  --ef-bg3: #E6E2CC;
+  --ef-bg-dim: #F2EFDF;
+  --ef-fg: #5C6A72;
+
+  /* Structure, lifted from jahvon.dev's rhythm layer */
+  --radius: 12px;
+  --gap: 30px;
+}
+
+.dark {
+  /* Everforest dark (medium) */
+  --ef-bg0: #2D353B;
+  --ef-bg1: #343F44;
+  --ef-bg2: #3D484D;
+  --ef-bg3: #475258;
+  --ef-bg-dim: #232A2E;
+  --ef-fg: #D3C6AA;
+}
+
+/* --- Primitive scales ---------------------------------------------------- */
+
+:root {
+  --vp-c-gray-1: #DFD9C2;
+  --vp-c-gray-2: #E6E2CC;
+  --vp-c-gray-3: #EFEBD4;
+  --vp-c-gray-soft: rgba(147, 159, 145, 0.16);
+
+  --vp-c-red-1: #C43E3B;
+  --vp-c-red-2: #D6504C;
+  --vp-c-red-3: #E06663;
+  --vp-c-red-soft: rgba(248, 85, 82, 0.12);
+
+  --vp-c-yellow-1: #8A6100;
+  --vp-c-yellow-2: #A07200;
+  --vp-c-yellow-3: #B98500;
+  --vp-c-yellow-soft: rgba(223, 160, 0, 0.14);
+
+  --vp-c-green-1: #5C6E00;
+  --vp-c-green-2: #6E8300;
+  --vp-c-green-3: #8DA101;
+  --vp-c-green-soft: rgba(141, 161, 1, 0.14);
+
+  --vp-c-purple-1: #A83D86;
+  --vp-c-purple-2: #C04D9B;
+  --vp-c-purple-3: #DF69BA;
+  --vp-c-purple-soft: rgba(223, 105, 186, 0.12);
+}
+
+.dark {
+  --vp-c-gray-1: #4F585E;
+  --vp-c-gray-2: #475258;
+  --vp-c-gray-3: #3D484D;
+  --vp-c-gray-soft: rgba(157, 169, 160, 0.16);
+
+  --vp-c-red-1: #E67E80;
+  --vp-c-red-2: #D96C6E;
+  --vp-c-red-3: #B85B5D;
+  --vp-c-red-soft: rgba(230, 126, 128, 0.16);
+
+  --vp-c-yellow-1: #DBBC7F;
+  --vp-c-yellow-2: #C9A96C;
+  --vp-c-yellow-3: #A98F5A;
+  --vp-c-yellow-soft: rgba(219, 188, 127, 0.16);
+
+  --vp-c-green-1: #A7C080;
+  --vp-c-green-2: #94AC70;
+  --vp-c-green-3: #7B915C;
+  --vp-c-green-soft: rgba(167, 192, 128, 0.16);
+
+  --vp-c-purple-1: #D699B6;
+  --vp-c-purple-2: #C288A5;
+  --vp-c-purple-3: #A5718B;
+  --vp-c-purple-soft: rgba(214, 153, 182, 0.16);
+}
+
+/* --- Brand ---------------------------------------------------------------
+   flow's mark is Everforest blue #7FBBB3 / aqua #83C092. That pair works on
+   the dark ground as-is (5.7:1 and 5.9:1). On cream it is 2:1, so light mode
+   uses a deepened aqua that keeps the hue and clears 4.9:1.
+   ------------------------------------------------------------------------- */
+
+:root {
+  --vp-c-brand-1: #1F7A5A;
+  --vp-c-brand-2: #2A8A67;
+  --vp-c-brand-3: #35A77C;
+  --vp-c-brand-soft: rgba(53, 167, 124, 0.12);
+  --vp-c-brand: var(--vp-c-brand-1);
+}
+
+.dark {
+  --vp-c-brand-1: #7FBBB3;
+  --vp-c-brand-2: #83C092;
+  --vp-c-brand-3: #6BAAA2;
+  --vp-c-brand-soft: rgba(127, 187, 179, 0.16);
+}
+
+/* --- Background ----------------------------------------------------------- */
+
+:root {
+  --vp-c-bg: var(--ef-bg0);
+  --vp-c-bg-alt: var(--ef-bg1);
+  --vp-c-bg-elv: #FFFCF1;
+  --vp-c-bg-soft: var(--ef-bg1);
+}
+
+.dark {
+  --vp-c-bg: var(--ef-bg0);
+  --vp-c-bg-alt: var(--ef-bg-dim);
+  --vp-c-bg-elv: var(--ef-bg1);
+  --vp-c-bg-soft: var(--ef-bg1);
+}
+
+/* --- Borders -------------------------------------------------------------
+   The whole design leans on hairlines instead of shadow, so `border` has to
+   stay visible while `divider` stays quiet.
+   ------------------------------------------------------------------------- */
+
+:root {
+  --vp-c-border: #DBD5BC;
+  --vp-c-divider: #E9E4CE;
+  --vp-c-gutter: #E9E4CE;
+}
+
+.dark {
+  --vp-c-border: #475258;
+  --vp-c-divider: #3D484D;
+  --vp-c-gutter: #232A2E;
+}
+
+/* --- Text ---------------------------------------------------------------- */
+
+:root {
+  --vp-c-text-1: var(--ef-fg);   /* 5.2:1 on bg0 */
+  --vp-c-text-2: #66746C;        /* 4.6:1 — darkened from Everforest grey1 */
+  --vp-c-text-3: #839289;        /* 3.0:1, non-essential only */
+}
+
+.dark {
+  --vp-c-text-1: var(--ef-fg);   /* 7.4:1 */
+  --vp-c-text-2: #9DA9A0;        /* 5.1:1 */
+  --vp-c-text-3: #7A8478;        /* 3.2:1 */
+}
+
+/* --- Code ---------------------------------------------------------------- */
+
+:root {
+  --vp-code-block-bg: #F2EDD8;
+  --vp-code-bg: var(--vp-c-gray-soft);
+  --vp-code-copy-code-bg: var(--ef-bg2);
+  --vp-code-copy-code-hover-bg: var(--ef-bg3);
+  --vp-code-tab-bg: var(--vp-code-block-bg);
+}
+
+.dark {
+  --vp-code-block-bg: var(--ef-bg-dim);
+  --vp-code-copy-code-bg: var(--ef-bg2);
+  --vp-code-copy-code-hover-bg: var(--ef-bg3);
+}
+
+/* --- Buttons -------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-bg: var(--vp-c-brand-1);
+  --vp-button-brand-border: var(--vp-c-brand-1);
+  --vp-button-brand-text: #FDF6E3;
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-hover-border: var(--vp-c-brand-2);
+  --vp-button-brand-hover-text: #FDF6E3;
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+  --vp-button-brand-active-border: var(--vp-c-brand-1);
+
+  --vp-button-alt-bg: transparent;
+  --vp-button-alt-border: var(--vp-c-border);
+  --vp-button-alt-text: var(--vp-c-text-1);
+  --vp-button-alt-hover-bg: transparent;
+  --vp-button-alt-hover-border: var(--vp-c-text-3);
+  --vp-button-alt-hover-text: var(--vp-c-text-1);
+  --vp-button-alt-active-bg: transparent;
+  --vp-button-alt-active-border: var(--vp-c-text-3);
+}
+
+.dark {
+  --vp-button-brand-text: #2D353B;
+  --vp-button-brand-hover-text: #2D353B;
+}
+
+/* --- Inputs, search, nav -------------------------------------------------- */
+
+:root {
+  --vp-input-bg-color: var(--vp-c-bg);
+  --vp-input-border-color: var(--vp-c-border);
+  --vp-nav-bg-color: var(--vp-c-bg);
+  --vp-sidebar-bg-color: var(--vp-c-bg);
+  --vp-nav-screen-bg-color: var(--vp-c-bg);
+  --vp-local-nav-bg-color: var(--vp-c-bg);
+  --vp-local-search-bg: var(--vp-c-bg-elv);
+  --vp-local-search-result-border: var(--vp-c-divider);
+  --vp-local-search-result-selected-border: var(--vp-c-brand-1);
+  --vp-backdrop-bg-color: rgba(45, 53, 59, 0.55);
+}
+
+/* --- Hero ----------------------------------------------------------------
+   The mark keeps a glow, but as VitePress's blurred plate behind it rather
+   than the old `drop-shadow(5px 5px 100px #D699B6)` on the PNG itself — a
+   diffuse wash instead of a hard offset shadow, and it picks up both brand
+   hues instead of only the purple.
+   ------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: var(--vp-c-brand-1);
+  --vp-home-hero-name-background: transparent;
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    rgba(214, 153, 182, 0.34) 30%,
+    rgba(127, 187, 179, 0.34)
+  );
+  --vp-home-hero-image-filter: blur(38px);
+}
+
+.dark {
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    rgba(214, 153, 182, 0.34) 30%,
+    rgba(127, 187, 179, 0.34)
+  );
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(46px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+/* --- Shadows: none -------------------------------------------------------- */
+
+:root {
+  --vp-shadow-1: none;
+  --vp-shadow-2: none;
+  --vp-shadow-3: 0 0 0 1px var(--vp-c-border);
+  --vp-shadow-4: 0 0 0 1px var(--vp-c-border);
+  --vp-shadow-5: 0 0 0 1px var(--vp-c-border);
+}
diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md
index 5d63dd98..e368feb6 100644
--- a/docs/breaking-changes.md
+++ b/docs/breaking-changes.md
@@ -1,5 +1,6 @@
 ---
 title: Breaking Changes
+description: "Breaking changes between flow releases, and what to do about each one when upgrading."
 ---
 
 # Breaking Changes
diff --git a/docs/cli/flow.md b/docs/cli/flow.md
index c8083994..b5484a4c 100644
--- a/docs/cli/flow.md
+++ b/docs/cli/flow.md
@@ -1,34 +1,38 @@
-## flow
+---
+title: flow
+description: "flow is a command line interface designed to make managing and running development workflows easier."
+---
+
+# flow
 
 flow is a command line interface designed to make managing and running development workflows easier.
 
-### Synopsis
+## Synopsis
 
 flow is a command line interface designed to make managing and running development workflows easier.It's driven by executables organized across workspaces and namespaces defined in a workspace.
 
 See https://flowexec.io for more information.
 
-### Options
-
-```
-  -h, --help               help for flow
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
-
-### SEE ALSO
-
-* [flow browse](flow_browse.md)	 - Discover and explore available executables.
-* [flow cache](flow_cache.md)	 - Manage temporary key-value data.
-* [flow cli](flow_cli.md)	 - Manage the flow CLI itself.
-* [flow config](flow_config.md)	 - View and update global flow configuration.
-* [flow exec](flow_exec.md)	 - Execute any executable by reference.
-* [flow logs](flow_logs.md)	 - View execution history and logs.
-* [flow mcp](flow_mcp.md)	 - Start Model Context Provider (MCP) server for AI assistant integration
-* [flow schema](flow_schema.md)	 - Validate flowfiles and workspace configs against their schemas.
-* [flow secret](flow_secret.md)	 - Manage secrets stored in a vault.
-* [flow sync](flow_sync.md)	 - Refresh workspace cache and discover new executables.
-* [flow template](flow_template.md)	 - Manage flowfile templates.
-* [flow vault](flow_vault.md)	 - Manage sensitive secret stores.
-* [flow workspace](flow_workspace.md)	 - Manage development workspaces.
-
+## Options
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for flow |
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
+
+## See also
+
+- [flow browse](flow_browse.md) — Discover and explore available executables.
+- [flow cache](flow_cache.md) — Manage temporary key-value data.
+- [flow cli](flow_cli.md) — Manage the flow CLI itself.
+- [flow config](flow_config.md) — View and update global flow configuration.
+- [flow exec](flow_exec.md) — Execute any executable by reference.
+- [flow logs](flow_logs.md) — View execution history and logs.
+- [flow mcp](flow_mcp.md) — Start Model Context Provider (MCP) server for AI assistant integration
+- [flow schema](flow_schema.md) — Validate flowfiles and workspace configs against their schemas.
+- [flow secret](flow_secret.md) — Manage secrets stored in a vault.
+- [flow sync](flow_sync.md) — Refresh workspace cache and discover new executables.
+- [flow template](flow_template.md) — Manage flowfile templates.
+- [flow vault](flow_vault.md) — Manage sensitive secret stores.
+- [flow workspace](flow_workspace.md) — Manage development workspaces.
diff --git a/docs/cli/flow_browse.md b/docs/cli/flow_browse.md
index 672d489f..0a3090a6 100644
--- a/docs/cli/flow_browse.md
+++ b/docs/cli/flow_browse.md
@@ -1,8 +1,13 @@
-## flow browse
+---
+title: flow browse
+description: "Discover and explore available executables."
+---
+
+# flow browse
 
 Discover and explore available executables.
 
-### Synopsis
+## Synopsis
 
 Browse executables across workspaces.
 
@@ -13,45 +18,42 @@ Browse executables across workspaces.
 See https://flowexec.io/types/flowfile#executableverb for more information on executable verbs and
 https://flowexec.io/types/flowfile#executableref for more information on executable references.
 
-```
+```shell
 flow browse [EXECUTABLE-REFERENCE] [flags]
 ```
 
-### Examples
-
-```
-
-  flow browse                              # interactive multi-pane browser
-  flow browse --list                       # flat list of all executables
-  flow browse --verb run                   # list only 'run' executables
-  flow browse --namespace myproject        # filter by namespace
+## Examples
 
+```shell
+flow browse                              # interactive multi-pane browser
+flow browse --list                       # flat list of all executables
+flow browse --verb run                   # list only 'run' executables
+flow browse --namespace myproject        # filter by namespace
 ```
 
-### Options
+## Options
 
-```
-  -a, --all                      List from all namespaces.
-      --annotation stringArray   Filter by annotations. Format: 'key=value' for exact value match, or 'key' for presence regardless of value. Repeat the flag for multiple selectors; all selectors must match (AND).
-  -f, --filter string            Filter executable by reference substring.
-  -h, --help                     help for browse
-  -l, --list                     Show a simple list view of executables instead of interactive discovery.
-  -n, --namespace string         Filter executables by namespace.
-  -o, --output string            Output format. One of: yaml, json, or tui.
-  -t, --tag stringArray          Filter by tags.
-  -v, --verb string              Filter executables by verb.
-      --visibility string        Filter by visibility level (hierarchical). Valid: public, private, internal, hidden. Default: private
-  -w, --workspace string         Filter executables by workspace.
-```
-
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-a, --all` |  | List from all namespaces. |
+| `--annotation` | `stringArray` | Filter by annotations. Format: 'key=value' for exact value match, or 'key' for presence regardless of value. Repeat the flag for multiple selectors; all selectors must match (AND). |
+| `-f, --filter` | `string` | Filter executable by reference substring. |
+| `-h, --help` |  | help for browse |
+| `-l, --list` |  | Show a simple list view of executables instead of interactive discovery. |
+| `-n, --namespace` | `string` | Filter executables by namespace. |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-t, --tag` | `stringArray` | Filter by tags. |
+| `-v, --verb` | `string` | Filter executables by verb. |
+| `--visibility` | `string` | Filter by visibility level (hierarchical). Valid: public, private, internal, hidden. Default: private |
+| `-w, --workspace` | `string` | Filter executables by workspace. |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
diff --git a/docs/cli/flow_cache.md b/docs/cli/flow_cache.md
index 9a1c40af..2598cf2e 100644
--- a/docs/cli/flow_cache.md
+++ b/docs/cli/flow_cache.md
@@ -1,30 +1,34 @@
-## flow cache
+---
+title: flow cache
+description: "Manage temporary key-value data."
+---
+
+# flow cache
 
 Manage temporary key-value data.
 
-### Synopsis
+## Synopsis
 
 Manage temporary key-value data. Values set outside executables runs persist globally, while values set within executables persist only for that execution scope.
 
-### Options
-
-```
-  -h, --help   help for cache
-```
+## Options
 
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for cache |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
-* [flow cache clear](flow_cache_clear.md)	 - Clear cache data. Use --all to remove data across all scopes.
-* [flow cache get](flow_cache_get.md)	 - Get cached data by key.
-* [flow cache list](flow_cache_list.md)	 - List all keys in the store.
-* [flow cache remove](flow_cache_remove.md)	 - Remove a key from the cached data store.
-* [flow cache set](flow_cache_set.md)	 - Set cached data by key.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
+- [flow cache clear](flow_cache_clear.md) — Clear cache data. Use --all to remove data across all scopes.
+- [flow cache get](flow_cache_get.md) — Get cached data by key.
+- [flow cache list](flow_cache_list.md) — List all keys in the store.
+- [flow cache remove](flow_cache_remove.md) — Remove a key from the cached data store.
+- [flow cache set](flow_cache_set.md) — Set cached data by key.
diff --git a/docs/cli/flow_cache_clear.md b/docs/cli/flow_cache_clear.md
index c15f9632..2b96b9e7 100644
--- a/docs/cli/flow_cache_clear.md
+++ b/docs/cli/flow_cache_clear.md
@@ -1,33 +1,37 @@
-## flow cache clear
+---
+title: flow cache clear
+description: "Clear cache data. Use --all to remove data across all scopes."
+---
+
+# flow cache clear
 
 Clear cache data. Use --all to remove data across all scopes.
 
-### Synopsis
+## Synopsis
 
 The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes. Use the --global flag to force use of the global cache scope, even when called from within an executable.
 
 This will remove all keys and values from the data store.
 
-```
+```shell
 flow cache clear [flags]
 ```
 
-### Options
+## Options
 
-```
-      --all             Force clear all stored data
-  -h, --help            help for clear
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `--all` |  | Force clear all stored data |
+| `-h, --help` |  | help for clear |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow cache](flow_cache.md)	 - Manage temporary key-value data.
+## See also
 
+- [flow cache](flow_cache.md) — Manage temporary key-value data.
diff --git a/docs/cli/flow_cache_get.md b/docs/cli/flow_cache_get.md
index b5684b47..b942a494 100644
--- a/docs/cli/flow_cache_get.md
+++ b/docs/cli/flow_cache_get.md
@@ -1,33 +1,37 @@
-## flow cache get
+---
+title: flow cache get
+description: "Get cached data by key."
+---
+
+# flow cache get
 
 Get cached data by key.
 
-### Synopsis
+## Synopsis
 
 The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes. Use the --global flag to force use of the global cache scope, even when called from within an executable.
 
 This will retrieve the value for the given key.
 
-```
+```shell
 flow cache get KEY [flags]
 ```
 
-### Options
+## Options
 
-```
-  -g, --global          Force use of the global cache scope, even when called from within an executable
-  -h, --help            help for get
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-g, --global` |  | Force use of the global cache scope, even when called from within an executable |
+| `-h, --help` |  | help for get |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow cache](flow_cache.md)	 - Manage temporary key-value data.
+## See also
 
+- [flow cache](flow_cache.md) — Manage temporary key-value data.
diff --git a/docs/cli/flow_cache_list.md b/docs/cli/flow_cache_list.md
index 399c3397..b6bbfef9 100644
--- a/docs/cli/flow_cache_list.md
+++ b/docs/cli/flow_cache_list.md
@@ -1,32 +1,36 @@
-## flow cache list
+---
+title: flow cache list
+description: "List all keys in the store."
+---
+
+# flow cache list
 
 List all keys in the store.
 
-### Synopsis
+## Synopsis
 
 The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes. Use the --global flag to force use of the global cache scope, even when called from within an executable.
 
 This will list all keys currently stored in the data store.
 
-```
+```shell
 flow cache list [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for list
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for list |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow cache](flow_cache.md)	 - Manage temporary key-value data.
+## See also
 
+- [flow cache](flow_cache.md) — Manage temporary key-value data.
diff --git a/docs/cli/flow_cache_remove.md b/docs/cli/flow_cache_remove.md
index c68872bf..7256b41c 100644
--- a/docs/cli/flow_cache_remove.md
+++ b/docs/cli/flow_cache_remove.md
@@ -1,33 +1,37 @@
-## flow cache remove
+---
+title: flow cache remove
+description: "Remove a key from the cached data store."
+---
+
+# flow cache remove
 
 Remove a key from the cached data store.
 
-### Synopsis
+## Synopsis
 
 The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes. Use the --global flag to force use of the global cache scope, even when called from within an executable.
 
 This will remove the specified key and its value from the data store.
 
-```
+```shell
 flow cache remove KEY [flags]
 ```
 
-### Options
+## Options
 
-```
-  -g, --global          Force use of the global cache scope, even when called from within an executable
-  -h, --help            help for remove
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-g, --global` |  | Force use of the global cache scope, even when called from within an executable |
+| `-h, --help` |  | help for remove |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow cache](flow_cache.md)	 - Manage temporary key-value data.
+## See also
 
+- [flow cache](flow_cache.md) — Manage temporary key-value data.
diff --git a/docs/cli/flow_cache_set.md b/docs/cli/flow_cache_set.md
index 07e66f37..95ab85a5 100644
--- a/docs/cli/flow_cache_set.md
+++ b/docs/cli/flow_cache_set.md
@@ -1,33 +1,37 @@
-## flow cache set
+---
+title: flow cache set
+description: "Set cached data by key."
+---
+
+# flow cache set
 
 Set cached data by key.
 
-### Synopsis
+## Synopsis
 
 The data store is a key-value store that can be used to persist data across executions. Values that are set outside of an executable will persist across all executions until they are cleared. When set within an executable, the data will only persist across serial or parallel sub-executables but all values will be cleared when the parent executable completes. Use the --global flag to force use of the global cache scope, even when called from within an executable.
 
 This will overwrite any existing value for the key.
 
-```
+```shell
 flow cache set KEY [VALUE] [flags]
 ```
 
-### Options
+## Options
 
-```
-  -g, --global          Force use of the global cache scope, even when called from within an executable
-  -h, --help            help for set
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-g, --global` |  | Force use of the global cache scope, even when called from within an executable |
+| `-h, --help` |  | help for set |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow cache](flow_cache.md)	 - Manage temporary key-value data.
+## See also
 
+- [flow cache](flow_cache.md) — Manage temporary key-value data.
diff --git a/docs/cli/flow_cli.md b/docs/cli/flow_cli.md
index 59a5b405..007f7d37 100644
--- a/docs/cli/flow_cli.md
+++ b/docs/cli/flow_cli.md
@@ -1,26 +1,30 @@
-## flow cli
+---
+title: flow cli
+description: "Manage the flow CLI itself."
+---
+
+# flow cli
 
 Manage the flow CLI itself.
 
-### Synopsis
+## Synopsis
 
 Commands for managing the flow CLI tool (updates, version info, etc.).
 
-### Options
-
-```
-  -h, --help   help for cli
-```
+## Options
 
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for cli |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
-* [flow cli update](flow_cli_update.md)	 - Update flow to the latest version.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
+- [flow cli update](flow_cli_update.md) — Update flow to the latest version.
diff --git a/docs/cli/flow_cli_update.md b/docs/cli/flow_cli_update.md
index 12572853..cc0c5efe 100644
--- a/docs/cli/flow_cli_update.md
+++ b/docs/cli/flow_cli_update.md
@@ -1,42 +1,44 @@
-## flow cli update
+---
+title: flow cli update
+description: "Update flow to the latest version."
+---
+
+# flow cli update
 
 Update flow to the latest version.
 
-### Synopsis
+## Synopsis
 
 Check GitHub for a newer version of flow and install it if available.
 
-```
+```shell
 flow cli update [flags]
 ```
 
-### Examples
-
-```
-
-  flow cli update                    # check for an update and prompt before installing
-  flow cli update --yes              # install the latest version without confirmation
-  flow cli update --version v2.1.0   # install a specific version
+## Examples
 
+```shell
+flow cli update                    # check for an update and prompt before installing
+flow cli update --yes              # install the latest version without confirmation
+flow cli update --version v2.1.0   # install a specific version
 ```
 
-### Options
+## Options
 
-```
-  -h, --help             help for update
-  -o, --output string    Output format. One of: yaml, json, or tui.
-      --version string   Target version to install (e.g. v2.1.0). Defaults to the latest release.
-  -y, --yes              Skip confirmation prompts
-```
-
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for update |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `--version` | `string` | Target version to install (e.g. v2.1.0). Defaults to the latest release. |
+| `-y, --yes` |  | Skip confirmation prompts |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow cli](flow_cli.md)	 - Manage the flow CLI itself.
+## See also
 
+- [flow cli](flow_cli.md) — Manage the flow CLI itself.
diff --git a/docs/cli/flow_config.md b/docs/cli/flow_config.md
index 20caa56e..d667a3a5 100644
--- a/docs/cli/flow_config.md
+++ b/docs/cli/flow_config.md
@@ -1,31 +1,35 @@
-## flow config
+---
+title: flow config
+description: "View and update global flow configuration."
+---
+
+# flow config
 
 View and update global flow configuration.
 
-### Synopsis
+## Synopsis
 
 Manage global flow configuration. Settings are stored in the flow config file and apply
 across all workspaces unless overridden.
 
 Use 'config get' to view current values and 'config set &lt;setting&gt;' subcommands to change them.
 
-### Options
-
-```
-  -h, --help   help for config
-```
+## Options
 
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for config |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
-* [flow config get](flow_config_get.md)	 - Get the current global configuration values.
-* [flow config reset](flow_config_reset.md)	 - Restore the default flow configuration values. This will overwrite the current configuration.
-* [flow config set](flow_config_set.md)	 - Set a global configuration value.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
+- [flow config get](flow_config_get.md) — Get the current global configuration values.
+- [flow config reset](flow_config_reset.md) — Restore the default flow configuration values. This will overwrite the current configuration.
+- [flow config set](flow_config_set.md) — Set a global configuration value.
diff --git a/docs/cli/flow_config_get.md b/docs/cli/flow_config_get.md
index 35ce0cfb..eb07cdf5 100644
--- a/docs/cli/flow_config_get.md
+++ b/docs/cli/flow_config_get.md
@@ -1,26 +1,30 @@
-## flow config get
+---
+title: flow config get
+description: "Get the current global configuration values."
+---
+
+# flow config get
 
 Get the current global configuration values.
 
-```
+```shell
 flow config get [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for get
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for get |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow config](flow_config.md)	 - View and update global flow configuration.
+## See also
 
+- [flow config](flow_config.md) — View and update global flow configuration.
diff --git a/docs/cli/flow_config_reset.md b/docs/cli/flow_config_reset.md
index cd6d2759..7cd6738f 100644
--- a/docs/cli/flow_config_reset.md
+++ b/docs/cli/flow_config_reset.md
@@ -1,26 +1,30 @@
-## flow config reset
+---
+title: flow config reset
+description: "Restore the default flow configuration values. This will overwrite the current configuration."
+---
+
+# flow config reset
 
 Restore the default flow configuration values. This will overwrite the current configuration.
 
-```
+```shell
 flow config reset [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for reset
-  -y, --yes    Skip confirmation prompts
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for reset |
+| `-y, --yes` |  | Skip confirmation prompts |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow config](flow_config.md)	 - View and update global flow configuration.
+## See also
 
+- [flow config](flow_config.md) — View and update global flow configuration.
diff --git a/docs/cli/flow_config_set.md b/docs/cli/flow_config_set.md
index 326b39c7..85079f1f 100644
--- a/docs/cli/flow_config_set.md
+++ b/docs/cli/flow_config_set.md
@@ -1,29 +1,33 @@
-## flow config set
+---
+title: flow config set
+description: "Set a global configuration value."
+---
 
-Set a global configuration value.
+# flow config set
 
-### Options
+Set a global configuration value.
 
-```
-  -h, --help   help for set
-```
+## Options
 
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for set |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow config](flow_config.md)	 - View and update global flow configuration.
-* [flow config set log-mode](flow_config_set_log-mode.md)	 - Set the default log mode.
-* [flow config set namespace](flow_config_set_namespace.md)	 - Change the current namespace.
-* [flow config set notifications](flow_config_set_notifications.md)	 - Enable or disable notifications.
-* [flow config set theme](flow_config_set_theme.md)	 - Set the theme for the TUI views
-* [flow config set timeout](flow_config_set_timeout.md)	 - Set the default timeout for executables.
-* [flow config set tui](flow_config_set_tui.md)	 - Enable or disable the interactive terminal UI experience.
-* [flow config set update-check](flow_config_set_update-check.md)	 - Enable or disable background CLI update checks.
-* [flow config set workspace-mode](flow_config_set_workspace-mode.md)	 - Switch between fixed and dynamic workspace modes.
+## See also
 
+- [flow config](flow_config.md) — View and update global flow configuration.
+- [flow config set log-mode](flow_config_set_log-mode.md) — Set the default log mode.
+- [flow config set namespace](flow_config_set_namespace.md) — Change the current namespace.
+- [flow config set notifications](flow_config_set_notifications.md) — Enable or disable notifications.
+- [flow config set theme](flow_config_set_theme.md) — Set the theme for the TUI views
+- [flow config set timeout](flow_config_set_timeout.md) — Set the default timeout for executables.
+- [flow config set tui](flow_config_set_tui.md) — Enable or disable the interactive terminal UI experience.
+- [flow config set update-check](flow_config_set_update-check.md) — Enable or disable background CLI update checks.
+- [flow config set workspace-mode](flow_config_set_workspace-mode.md) — Switch between fixed and dynamic workspace modes.
diff --git a/docs/cli/flow_config_set_log-mode.md b/docs/cli/flow_config_set_log-mode.md
index 76040e43..7457fe56 100644
--- a/docs/cli/flow_config_set_log-mode.md
+++ b/docs/cli/flow_config_set_log-mode.md
@@ -1,25 +1,29 @@
-## flow config set log-mode
+---
+title: flow config set log-mode
+description: "Set the default log mode."
+---
+
+# flow config set log-mode
 
 Set the default log mode.
 
-```
+```shell
 flow config set log-mode [logfmt|json|text|hidden] [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for log-mode
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for log-mode |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow config set](flow_config_set.md)	 - Set a global configuration value.
+## See also
 
+- [flow config set](flow_config_set.md) — Set a global configuration value.
diff --git a/docs/cli/flow_config_set_namespace.md b/docs/cli/flow_config_set_namespace.md
index fe307a81..ec049c03 100644
--- a/docs/cli/flow_config_set_namespace.md
+++ b/docs/cli/flow_config_set_namespace.md
@@ -1,34 +1,36 @@
-## flow config set namespace
+---
+title: flow config set namespace
+description: "Change the current namespace."
+---
+
+# flow config set namespace
 
 Change the current namespace.
 
-```
+```shell
 flow config set namespace NAME [flags]
 ```
 
-### Examples
-
-```
-
-  flow config set namespace myproject
-  flow config set namespace default
+## Examples
 
+```shell
+flow config set namespace myproject
+flow config set namespace default
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for namespace
-```
-
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for namespace |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow config set](flow_config_set.md)	 - Set a global configuration value.
+## See also
 
+- [flow config set](flow_config_set.md) — Set a global configuration value.
diff --git a/docs/cli/flow_config_set_notifications.md b/docs/cli/flow_config_set_notifications.md
index 8fc1407f..635cea94 100644
--- a/docs/cli/flow_config_set_notifications.md
+++ b/docs/cli/flow_config_set_notifications.md
@@ -1,26 +1,30 @@
-## flow config set notifications
+---
+title: flow config set notifications
+description: "Enable or disable notifications."
+---
+
+# flow config set notifications
 
 Enable or disable notifications.
 
-```
+```shell
 flow config set notifications [true|false] [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help    help for notifications
-      --sound   Update completion sound notification setting
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for notifications |
+| `--sound` |  | Update completion sound notification setting |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow config set](flow_config_set.md)	 - Set a global configuration value.
+## See also
 
+- [flow config set](flow_config_set.md) — Set a global configuration value.
diff --git a/docs/cli/flow_config_set_theme.md b/docs/cli/flow_config_set_theme.md
index a61ec323..e1fd8c93 100644
--- a/docs/cli/flow_config_set_theme.md
+++ b/docs/cli/flow_config_set_theme.md
@@ -1,25 +1,29 @@
-## flow config set theme
+---
+title: flow config set theme
+description: "Set the theme for the TUI views"
+---
+
+# flow config set theme
 
 Set the theme for the TUI views
 
-```
+```shell
 flow config set theme [default|dark|light|dracula|tokyo-night] [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for theme
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for theme |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow config set](flow_config_set.md)	 - Set a global configuration value.
+## See also
 
+- [flow config set](flow_config_set.md) — Set a global configuration value.
diff --git a/docs/cli/flow_config_set_timeout.md b/docs/cli/flow_config_set_timeout.md
index daedb8d1..9a6a64d2 100644
--- a/docs/cli/flow_config_set_timeout.md
+++ b/docs/cli/flow_config_set_timeout.md
@@ -1,25 +1,29 @@
-## flow config set timeout
+---
+title: flow config set timeout
+description: "Set the default timeout for executables."
+---
+
+# flow config set timeout
 
 Set the default timeout for executables.
 
-```
+```shell
 flow config set timeout DURATION [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for timeout
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for timeout |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow config set](flow_config_set.md)	 - Set a global configuration value.
+## See also
 
+- [flow config set](flow_config_set.md) — Set a global configuration value.
diff --git a/docs/cli/flow_config_set_tui.md b/docs/cli/flow_config_set_tui.md
index 543a8f51..78058ebc 100644
--- a/docs/cli/flow_config_set_tui.md
+++ b/docs/cli/flow_config_set_tui.md
@@ -1,25 +1,29 @@
-## flow config set tui
+---
+title: flow config set tui
+description: "Enable or disable the interactive terminal UI experience."
+---
+
+# flow config set tui
 
 Enable or disable the interactive terminal UI experience.
 
-```
+```shell
 flow config set tui [true|false] [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for tui
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for tui |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow config set](flow_config_set.md)	 - Set a global configuration value.
+## See also
 
+- [flow config set](flow_config_set.md) — Set a global configuration value.
diff --git a/docs/cli/flow_config_set_update-check.md b/docs/cli/flow_config_set_update-check.md
index a206b275..0f5c8022 100644
--- a/docs/cli/flow_config_set_update-check.md
+++ b/docs/cli/flow_config_set_update-check.md
@@ -1,25 +1,29 @@
-## flow config set update-check
+---
+title: flow config set update-check
+description: "Enable or disable background CLI update checks."
+---
+
+# flow config set update-check
 
 Enable or disable background CLI update checks.
 
-```
+```shell
 flow config set update-check [true|false] [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for update-check
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for update-check |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow config set](flow_config_set.md)	 - Set a global configuration value.
+## See also
 
+- [flow config set](flow_config_set.md) — Set a global configuration value.
diff --git a/docs/cli/flow_config_set_workspace-mode.md b/docs/cli/flow_config_set_workspace-mode.md
index 9b76e7d3..dbfcbccf 100644
--- a/docs/cli/flow_config_set_workspace-mode.md
+++ b/docs/cli/flow_config_set_workspace-mode.md
@@ -1,25 +1,29 @@
-## flow config set workspace-mode
+---
+title: flow config set workspace-mode
+description: "Switch between fixed and dynamic workspace modes."
+---
+
+# flow config set workspace-mode
 
 Switch between fixed and dynamic workspace modes.
 
-```
+```shell
 flow config set workspace-mode [fixed|dynamic] [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for workspace-mode
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for workspace-mode |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow config set](flow_config_set.md)	 - Set a global configuration value.
+## See also
 
+- [flow config set](flow_config_set.md) — Set a global configuration value.
diff --git a/docs/cli/flow_config_set_workspace.md b/docs/cli/flow_config_set_workspace.md
index 30bb0700..3b9ab809 100644
--- a/docs/cli/flow_config_set_workspace.md
+++ b/docs/cli/flow_config_set_workspace.md
@@ -1,31 +1,8 @@
 ---
-title: Flow Config Set Workspace
+title: See also
+description: "- [flow config set](flow_config_set.md) — Update flow configuration values."
 ---
 
-## flow config set workspace
-
-Change the current workspace.
-
-```
-flow config set workspace NAME [flags]
-```
-
-### Options
-
-```
-  -f, --fixed   Set the workspace mode to fixed
-  -h, --help    help for workspace
-```
-
-### Options inherited from parent commands
-
-```
-  -x, --non-interactive   Disable displaying flow output via terminal UI rendering. This is only needed if the interactive output is enabled by default in flow's configuration.
-      --sync              Sync flow cache and workspaces
-      --verbosity int     Log verbosity level (-1 to 1)
-```
-
-### SEE ALSO
-
-* [flow config set](flow_config_set.md)	 - Update flow configuration values.
+# See also
 
+- [flow config set](flow_config_set.md) — Update flow configuration values.
diff --git a/docs/cli/flow_exec.md b/docs/cli/flow_exec.md
index 0b7a7812..7f21592f 100644
--- a/docs/cli/flow_exec.md
+++ b/docs/cli/flow_exec.md
@@ -1,8 +1,13 @@
-## flow exec
+---
+title: flow exec
+description: "Execute any executable by reference."
+---
+
+# flow exec
 
 Execute any executable by reference.
 
-### Synopsis
+## Synopsis
 
 Execute an executable where EXECUTABLE_ID is the target executable's ID in the form of 'ws/ns:name'.
 The flow subcommand used should match the target executable's verb or one of its aliases.
@@ -14,59 +19,56 @@ Positional arguments are specified as values without any prefix.
 See https://flowexec.io/types/flowfile#executableverb for more information on executable verbs.
 See https://flowexec.io/types/flowfile#executableref for more information on executable IDs.
 
-```
+```shell
 flow exec EXECUTABLE_ID [-- args...] [flags]
 ```
 
-### Examples
-
-```
-
-  # Execute a nameless flow in the current workspace with the 'install' verb
-  flow install
+## Examples
 
-  # Execute a nameless flow in the 'ws' workspace with the 'test' verb
-  flow test ws/
+```shell
+# Execute a nameless flow in the current workspace with the 'install' verb
+flow install
 
-  # Execute the 'build' flow in the current workspace and namespace
-  flow exec build
-  flow run build   # 'run' is an alias for the 'exec' verb
+# Execute a nameless flow in the 'ws' workspace with the 'test' verb
+flow test ws/
 
-  # Execute the 'docs' flow with the 'show' verb
-  flow show docs
+# Execute the 'build' flow in the current workspace and namespace
+flow exec build
+flow run build   # 'run' is an alias for the 'exec' verb
 
-  # Execute in a specific workspace and namespace
-  flow exec ws/ns:build
+# Execute the 'docs' flow with the 'show' verb
+flow show docs
 
-  # Pass flag and positional arguments to the executable
-  flow exec ws/ns:build -- --flag1=value1 --flag2=value2 value3 value4
+# Execute in a specific workspace and namespace
+flow exec ws/ns:build
 
+# Pass flag and positional arguments to the executable
+flow exec ws/ns:build -- --flag1=value1 --flag2=value2 value3 value4
 ```
 
-### Options
+## Options
 
-```
-  -b, --background           Run the executable in the background and return a run ID immediately.
-      --cmd flow logs        Run an ad-hoc shell command through flow instead of a named executable. The command runs with the current workspace's environment and is recorded in flow logs. Repeat --cmd to run multiple commands in one invocation (see --mode).
-      --dir string           Working directory for an ad-hoc command (defaults to the current directory). Only valid with --cmd.
-  -h, --help                 help for exec
-      --interpreter string   The interpreter to run ad-hoc --cmd commands with: 'sh' (default) or 'python'. Applies to every --cmd in the invocation.
-      --label string         A short, human-readable label for an ad-hoc command (used in history). Only valid with --cmd.
-  -m, --log-mode string      Log mode (text, logfmt, json, hidden)
-      --mode string          How to run multiple --cmd commands: 'serial' (default) or 'parallel'. (default "serial")
-  -p, --param stringArray    Set a parameter value by env key. (i.e. KEY=value) Use multiple times to set multiple parameters. This will override any existing parameter values defined for the executable.
-      --spec flow logs       Run a transient executable from an inline definition (any type: exec, serial, parallel, request, render, launch). Accepts inline YAML/JSON, '@path' to read a file, or '-' to read stdin. The executable is not saved to disk but is recorded in flow logs.
-      --workspace string     Workspace whose environment the ad-hoc/transient run should use (only with --cmd or --spec). Defaults to the workspace containing the run directory, then the current workspace. Does not change the global current workspace.
-```
-
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-b, --background` |  | Run the executable in the background and return a run ID immediately. |
+| `--cmd` | `stringArray` | Run an ad-hoc shell command through flow instead of a named executable. The command runs with the current workspace's environment and is recorded in flow logs. Repeat --cmd to run multiple commands in one invocation (see --mode). |
+| `--dir` | `string` | Working directory for an ad-hoc command (defaults to the current directory). Only valid with --cmd. |
+| `-h, --help` |  | help for exec |
+| `--interpreter` | `string` | The interpreter to run ad-hoc --cmd commands with: 'sh' (default) or 'python'. Applies to every --cmd in the invocation. |
+| `--label` | `string` | A short, human-readable label for an ad-hoc command (used in history). Only valid with --cmd. |
+| `-m, --log-mode` | `string` | Log mode (text, logfmt, json, hidden) |
+| `--mode` | `string` | How to run multiple --cmd commands: 'serial' (default) or 'parallel'. (default "serial") |
+| `-p, --param` | `stringArray` | Set a parameter value by env key. (i.e. KEY=value) Use multiple times to set multiple parameters. This will override any existing parameter values defined for the executable. |
+| `--spec` | `string` | Run a transient executable from an inline definition (any type: exec, serial, parallel, request, render, launch). Accepts inline YAML/JSON, '@path' to read a file, or '-' to read stdin. The executable is not saved to disk but is recorded in flow logs. |
+| `--workspace` | `string` | Workspace whose environment the ad-hoc/transient run should use (only with --cmd or --spec). Defaults to the workspace containing the run directory, then the current workspace. Does not change the global current workspace. |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
diff --git a/docs/cli/flow_logs.md b/docs/cli/flow_logs.md
index 222d2cdf..da273270 100644
--- a/docs/cli/flow_logs.md
+++ b/docs/cli/flow_logs.md
@@ -1,63 +1,65 @@
-## flow logs
+---
+title: flow logs
+description: "View execution history and logs."
+---
+
+# flow logs
 
 View execution history and logs.
 
-### Synopsis
+## Synopsis
 
 View execution history recorded in the data store, with associated log output. Optionally filter by executable reference.
 
-```
+```shell
 flow logs [ref] [flags]
 ```
 
-### Examples
-
-```
-
-  flow logs                          # all history
-  flow logs --last                   # most recent entry with full output
-  flow logs --status failed          # only failed runs
-  flow logs --status running         # only in-progress runs
-  flow logs --source mcp             # only runs launched by an AI/MCP client
-  flow logs --session <id>           # everything one agent session ran
-  flow logs run build                # history for 'run build' executable
-  flow logs --running                # list active background processes
-  flow logs -o json --tail 50        # include the last 50 lines of each run's output
-  flow logs --last --grep ERROR      # last run, only lines matching /ERROR/
+## Examples
 
+```shell
+flow logs                          # all history
+flow logs --last                   # most recent entry with full output
+flow logs --status failed          # only failed runs
+flow logs --status running         # only in-progress runs
+flow logs --source mcp             # only runs launched by an AI/MCP client
+flow logs --session <id>           # everything one agent session ran
+flow logs run build                # history for 'run build' executable
+flow logs --running                # list active background processes
+flow logs -o json --tail 50        # include the last 50 lines of each run's output
+flow logs --last --grep ERROR      # last run, only lines matching /ERROR/
 ```
 
-### Options
+## Options
 
-```
-      --client string      Filter history by the client that launched the run (e.g. 'claude', 'cursor').
-      --content            Include each record's log output (json/yaml only; already shown for --last text output).
-      --grep string        Include only log lines matching this regular expression (implies --content).
-  -h, --help               help for logs
-      --last               Print the last execution's logs
-      --limit int          Maximum number of records to display.
-      --max-bytes int      Cap included log output to the last N bytes, keeping the tail (implies --content).
-  -o, --output string      Output format. One of: yaml, json, or tui.
-      --running            Show only active background processes.
-      --session string     Filter history to a single provenance session ID (e.g. an AI agent session).
-      --since string       Filter history to entries after a duration (e.g. 1h, 30m, 7d).
-      --source string      Filter history by run origin, e.g. 'cli', 'desktop' or 'mcp'.
-      --status string      Filter history by status (running, completed, or failed; success/failure accepted as aliases).
-      --tail int           Include only the last N lines of log output (implies --content).
-  -w, --workspace string   Filter history by workspace name.
-```
-
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `--client` | `string` | Filter history by the client that launched the run (e.g. 'claude', 'cursor'). |
+| `--content` |  | Include each record's log output (json/yaml only; already shown for --last text output). |
+| `--grep` | `string` | Include only log lines matching this regular expression (implies --content). |
+| `-h, --help` |  | help for logs |
+| `--last` |  | Print the last execution's logs |
+| `--limit` | `int` | Maximum number of records to display. |
+| `--max-bytes` | `int` | Cap included log output to the last N bytes, keeping the tail (implies --content). |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `--running` |  | Show only active background processes. |
+| `--session` | `string` | Filter history to a single provenance session ID (e.g. an AI agent session). |
+| `--since` | `string` | Filter history to entries after a duration (e.g. 1h, 30m, 7d). |
+| `--source` | `string` | Filter history by run origin, e.g. 'cli', 'desktop' or 'mcp'. |
+| `--status` | `string` | Filter history by status (running, completed, or failed; success/failure accepted as aliases). |
+| `--tail` | `int` | Include only the last N lines of log output (implies --content). |
+| `-w, --workspace` | `string` | Filter history by workspace name. |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
-* [flow logs attach](flow_logs_attach.md)	 - Stream log output from a running background process by run ID.
-* [flow logs clear](flow_logs_clear.md)	 - Clear execution history and logs.
-* [flow logs kill](flow_logs_kill.md)	 - Terminate a running background process by run ID.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
+- [flow logs attach](flow_logs_attach.md) — Stream log output from a running background process by run ID.
+- [flow logs clear](flow_logs_clear.md) — Clear execution history and logs.
+- [flow logs kill](flow_logs_kill.md) — Terminate a running background process by run ID.
diff --git a/docs/cli/flow_logs_attach.md b/docs/cli/flow_logs_attach.md
index 1688fcf3..2e6eb4ba 100644
--- a/docs/cli/flow_logs_attach.md
+++ b/docs/cli/flow_logs_attach.md
@@ -1,29 +1,33 @@
-## flow logs attach
+---
+title: flow logs attach
+description: "Stream log output from a running background process by run ID."
+---
+
+# flow logs attach
 
 Stream log output from a running background process by run ID.
 
-### Synopsis
+## Synopsis
 
 Stream the log output of a background process identified by its run ID.
 
-```
+```shell
 flow logs attach RUN_ID [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for attach
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for attach |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow logs](flow_logs.md)	 - View execution history and logs.
+## See also
 
+- [flow logs](flow_logs.md) — View execution history and logs.
diff --git a/docs/cli/flow_logs_clear.md b/docs/cli/flow_logs_clear.md
index 8ea8a944..656bc0ff 100644
--- a/docs/cli/flow_logs_clear.md
+++ b/docs/cli/flow_logs_clear.md
@@ -1,29 +1,33 @@
-## flow logs clear
+---
+title: flow logs clear
+description: "Clear execution history and logs."
+---
+
+# flow logs clear
 
 Clear execution history and logs.
 
-### Synopsis
+## Synopsis
 
 Remove execution history records and associated log files. If a ref is provided, only that executable's data is cleared.
 
-```
+```shell
 flow logs clear [ref] [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for clear
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for clear |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow logs](flow_logs.md)	 - View execution history and logs.
+## See also
 
+- [flow logs](flow_logs.md) — View execution history and logs.
diff --git a/docs/cli/flow_logs_kill.md b/docs/cli/flow_logs_kill.md
index dd36406f..7ab09965 100644
--- a/docs/cli/flow_logs_kill.md
+++ b/docs/cli/flow_logs_kill.md
@@ -1,29 +1,33 @@
-## flow logs kill
+---
+title: flow logs kill
+description: "Terminate a running background process by run ID."
+---
+
+# flow logs kill
 
 Terminate a running background process by run ID.
 
-### Synopsis
+## Synopsis
 
 Send a termination signal to a running background process identified by its run ID.
 
-```
+```shell
 flow logs kill RUN_ID [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for kill
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for kill |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow logs](flow_logs.md)	 - View execution history and logs.
+## See also
 
+- [flow logs](flow_logs.md) — View execution history and logs.
diff --git a/docs/cli/flow_mcp.md b/docs/cli/flow_mcp.md
index 4f6e372f..daf88252 100644
--- a/docs/cli/flow_mcp.md
+++ b/docs/cli/flow_mcp.md
@@ -1,31 +1,35 @@
-## flow mcp
+---
+title: flow mcp
+description: "Start Model Context Provider (MCP) server for AI assistant integration"
+---
+
+# flow mcp
 
 Start Model Context Provider (MCP) server for AI assistant integration
 
-### Synopsis
+## Synopsis
 
 Start a Model Context Protocol server that enables AI assistants to interact with your flow executables, workspaces, and configurations through natural language. AI assistants can discover, validate, and execute flow workflows, making your automation platform accessible through conversational interfaces/clients.
 
 This server used stdio for transport. For more information on MCP, see https://modelcontextprotocol.io
 
-```
+```shell
 flow mcp [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help   help for mcp
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for mcp |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
diff --git a/docs/cli/flow_schema.md b/docs/cli/flow_schema.md
index 9a124fec..73e822dd 100644
--- a/docs/cli/flow_schema.md
+++ b/docs/cli/flow_schema.md
@@ -1,27 +1,31 @@
-## flow schema
+---
+title: flow schema
+description: "Validate flowfiles and workspace configs against their schemas."
+---
+
+# flow schema
 
 Validate flowfiles and workspace configs against their schemas.
 
-### Synopsis
+## Synopsis
 
 Utilities for working with flow YAML schemas. Use these commands to validate flowfiles
 and workspace configs against their JSON schemas — useful in CI pipelines and pre-commit hooks.
 
-### Options
-
-```
-  -h, --help   help for schema
-```
+## Options
 
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for schema |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
-* [flow schema validate](flow_schema_validate.md)	 - Validate flow files and workspace configs against their schemas.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
+- [flow schema validate](flow_schema_validate.md) — Validate flow files and workspace configs against their schemas.
diff --git a/docs/cli/flow_schema_validate.md b/docs/cli/flow_schema_validate.md
index 83f117c3..968beb34 100644
--- a/docs/cli/flow_schema_validate.md
+++ b/docs/cli/flow_schema_validate.md
@@ -1,32 +1,36 @@
-## flow schema validate
+---
+title: flow schema validate
+description: "Validate flow files and workspace configs against their schemas."
+---
+
+# flow schema validate
 
 Validate flow files and workspace configs against their schemas.
 
-### Synopsis
+## Synopsis
 
 Validate one or more flow files or workspace configuration files against their JSON schemas. File type is auto-detected from the filename (*.flow for flow files, flow.yaml for workspace configs). Use --type to override auto-detection. Use --strict to also check for unknown keys.
 
-```
+```shell
 flow schema validate FILE... [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for validate
-  -o, --output string   Output format. One of: yaml, json, or tui.
-      --strict          Also check for unknown keys not defined in the schema
-      --type string     File type to validate as (flowfile, workspace, config, template). Auto-detected if omitted.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for validate |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `--strict` |  | Also check for unknown keys not defined in the schema |
+| `--type` | `string` | File type to validate as (flowfile, workspace, config, template). Auto-detected if omitted. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow schema](flow_schema.md)	 - Validate flowfiles and workspace configs against their schemas.
+## See also
 
+- [flow schema](flow_schema.md) — Validate flowfiles and workspace configs against their schemas.
diff --git a/docs/cli/flow_secret.md b/docs/cli/flow_secret.md
index f0f18b08..1c462e62 100644
--- a/docs/cli/flow_secret.md
+++ b/docs/cli/flow_secret.md
@@ -1,8 +1,13 @@
-## flow secret
+---
+title: flow secret
+description: "Manage secrets stored in a vault."
+---
+
+# flow secret
 
 Manage secrets stored in a vault.
 
-### Synopsis
+## Synopsis
 
 Manage secrets stored in the active vault. Secrets are encrypted key-value pairs that
 can be referenced inside flowfiles using the secret reference syntax (e.g. ${secret:MY_KEY}).
@@ -10,26 +15,25 @@ can be referenced inside flowfiles using the secret reference syntax (e.g. ${sec
 The active vault is used by default; pass --vault to target a different one. Use
 'vault' subcommands to create and manage vaults.
 
-### Options
-
-```
-  -h, --help   help for secret
-```
+## Options
 
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for secret |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
-* [flow secret get](flow_secret_get.md)	 - Get the value of a secret in the current vault.
-* [flow secret link](flow_secret_link.md)	 - Link a name in the current vault to a secret in an external provider.
-* [flow secret list](flow_secret_list.md)	 - List secrets stored in the current vault.
-* [flow secret remove](flow_secret_remove.md)	 - Remove a secret from the vault.
-* [flow secret set](flow_secret_set.md)	 - Set a secret in the current vault. If no value is provided, you will be prompted to enter one.
-* [flow secret unlink](flow_secret_unlink.md)	 - Remove a link from the current vault, leaving the secret itself untouched.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
+- [flow secret get](flow_secret_get.md) — Get the value of a secret in the current vault.
+- [flow secret link](flow_secret_link.md) — Link a name in the current vault to a secret in an external provider.
+- [flow secret list](flow_secret_list.md) — List secrets stored in the current vault.
+- [flow secret remove](flow_secret_remove.md) — Remove a secret from the vault.
+- [flow secret set](flow_secret_set.md) — Set a secret in the current vault. If no value is provided, you will be prompted to enter one.
+- [flow secret unlink](flow_secret_unlink.md) — Remove a link from the current vault, leaving the secret itself untouched.
diff --git a/docs/cli/flow_secret_get.md b/docs/cli/flow_secret_get.md
index c13ac4d1..523525d9 100644
--- a/docs/cli/flow_secret_get.md
+++ b/docs/cli/flow_secret_get.md
@@ -1,39 +1,41 @@
-## flow secret get
+---
+title: flow secret get
+description: "Get the value of a secret in the current vault."
+---
+
+# flow secret get
 
 Get the value of a secret in the current vault.
 
-```
+```shell
 flow secret get REFERENCE [flags]
 ```
 
-### Examples
-
-```
-
-  flow secret get MY_TOKEN
-  flow secret get MY_TOKEN --as-plain-text
-  flow secret get MY_TOKEN --copy
+## Examples
 
+```shell
+flow secret get MY_TOKEN
+flow secret get MY_TOKEN --as-plain-text
+flow secret get MY_TOKEN --copy
 ```
 
-### Options
+## Options
 
-```
-      --copy            Copy the secret value to the clipboard
-  -h, --help            help for get
-  -o, --output string   Output format. One of: yaml, json, or tui.
-  -p, --plaintext       Output the secret value as plain text instead of an obfuscated string
-  -V, --vault string    Vault name to use instead of the current vault.
-```
-
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `--copy` |  | Copy the secret value to the clipboard |
+| `-h, --help` |  | help for get |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-p, --plaintext` |  | Output the secret value as plain text instead of an obfuscated string |
+| `-V, --vault` | `string` | Vault name to use instead of the current vault. |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow secret](flow_secret.md)	 - Manage secrets stored in a vault.
+## See also
 
+- [flow secret](flow_secret.md) — Manage secrets stored in a vault.
diff --git a/docs/cli/flow_secret_link.md b/docs/cli/flow_secret_link.md
index 64febcf7..e8c6999e 100644
--- a/docs/cli/flow_secret_link.md
+++ b/docs/cli/flow_secret_link.md
@@ -1,8 +1,13 @@
-## flow secret link
+---
+title: flow secret link
+description: "Link a name in the current vault to a secret in an external provider."
+---
+
+# flow secret link
 
 Link a name in the current vault to a secret in an external provider.
 
-### Synopsis
+## Synopsis
 
 Point NAME at REFERENCE, a path the vault's provider understands -- an
 op:// URI, a pass entry path, an SSM parameter name. Reading NAME reads
@@ -10,36 +15,33 @@ through to that secret; nothing is copied and nothing is written back.
 
 Only external vaults hold links.
 
-```
+```shell
 flow secret link NAME REFERENCE [flags]
 ```
 
-### Examples
-
-```
-
-  flow secret link aws-access-key 'op://Team/AWS/access_key_id'
-  flow secret link db-password 'team/db/password'
-  flow secret link api-token '/prod/service-a/api-token'
+## Examples
 
+```shell
+flow secret link aws-access-key 'op://Team/AWS/access_key_id'
+flow secret link db-password 'team/db/password'
+flow secret link api-token '/prod/service-a/api-token'
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for link
-  -o, --output string   Output format. One of: yaml, json, or tui.
-  -V, --vault string    Vault name to use instead of the current vault.
-```
-
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for link |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-V, --vault` | `string` | Vault name to use instead of the current vault. |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow secret](flow_secret.md)	 - Manage secrets stored in a vault.
+## See also
 
+- [flow secret](flow_secret.md) — Manage secrets stored in a vault.
diff --git a/docs/cli/flow_secret_list.md b/docs/cli/flow_secret_list.md
index ac01c606..3410fc36 100644
--- a/docs/cli/flow_secret_list.md
+++ b/docs/cli/flow_secret_list.md
@@ -1,28 +1,32 @@
-## flow secret list
+---
+title: flow secret list
+description: "List secrets stored in the current vault."
+---
+
+# flow secret list
 
 List secrets stored in the current vault.
 
-```
+```shell
 flow secret list [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for list
-  -o, --output string   Output format. One of: yaml, json, or tui.
-  -p, --plaintext       Output the secret value as plain text instead of an obfuscated string
-  -V, --vault string    Vault name to use instead of the current vault.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for list |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-p, --plaintext` |  | Output the secret value as plain text instead of an obfuscated string |
+| `-V, --vault` | `string` | Vault name to use instead of the current vault. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow secret](flow_secret.md)	 - Manage secrets stored in a vault.
+## See also
 
+- [flow secret](flow_secret.md) — Manage secrets stored in a vault.
diff --git a/docs/cli/flow_secret_remove.md b/docs/cli/flow_secret_remove.md
index 2d13bd4d..89164873 100644
--- a/docs/cli/flow_secret_remove.md
+++ b/docs/cli/flow_secret_remove.md
@@ -1,28 +1,32 @@
-## flow secret remove
+---
+title: flow secret remove
+description: "Remove a secret from the vault."
+---
+
+# flow secret remove
 
 Remove a secret from the vault.
 
-```
+```shell
 flow secret remove NAME [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for remove
-  -o, --output string   Output format. One of: yaml, json, or tui.
-  -V, --vault string    Vault name to use instead of the current vault.
-  -y, --yes             Skip confirmation prompts
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for remove |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-V, --vault` | `string` | Vault name to use instead of the current vault. |
+| `-y, --yes` |  | Skip confirmation prompts |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow secret](flow_secret.md)	 - Manage secrets stored in a vault.
+## See also
 
+- [flow secret](flow_secret.md) — Manage secrets stored in a vault.
diff --git a/docs/cli/flow_secret_set.md b/docs/cli/flow_secret_set.md
index 2c3e6b71..5b27df43 100644
--- a/docs/cli/flow_secret_set.md
+++ b/docs/cli/flow_secret_set.md
@@ -1,38 +1,40 @@
-## flow secret set
+---
+title: flow secret set
+description: "Set a secret in the current vault. If no value is provided, you will be prompted to enter one."
+---
+
+# flow secret set
 
 Set a secret in the current vault. If no value is provided, you will be prompted to enter one.
 
-```
+```shell
 flow secret set NAME [VALUE] [flags]
 ```
 
-### Examples
-
-```
-
-  flow secret set MY_TOKEN              # prompted securely
-  flow secret set MY_TOKEN s3cr3t       # inline value
-  flow secret set MY_TOKEN --from-file ./token.txt
+## Examples
 
+```shell
+flow secret set MY_TOKEN              # prompted securely
+flow secret set MY_TOKEN s3cr3t       # inline value
+flow secret set MY_TOKEN --from-file ./token.txt
 ```
 
-### Options
+## Options
 
-```
-      --file string     File to read the secret's value from
-  -h, --help            help for set
-  -o, --output string   Output format. One of: yaml, json, or tui.
-  -V, --vault string    Vault name to use instead of the current vault.
-```
-
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `--file` | `string` | File to read the secret's value from |
+| `-h, --help` |  | help for set |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-V, --vault` | `string` | Vault name to use instead of the current vault. |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow secret](flow_secret.md)	 - Manage secrets stored in a vault.
+## See also
 
+- [flow secret](flow_secret.md) — Manage secrets stored in a vault.
diff --git a/docs/cli/flow_secret_unlink.md b/docs/cli/flow_secret_unlink.md
index 187ff761..e33ef19f 100644
--- a/docs/cli/flow_secret_unlink.md
+++ b/docs/cli/flow_secret_unlink.md
@@ -1,27 +1,31 @@
-## flow secret unlink
+---
+title: flow secret unlink
+description: "Remove a link from the current vault, leaving the secret itself untouched."
+---
+
+# flow secret unlink
 
 Remove a link from the current vault, leaving the secret itself untouched.
 
-```
+```shell
 flow secret unlink NAME [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for unlink
-  -o, --output string   Output format. One of: yaml, json, or tui.
-  -V, --vault string    Vault name to use instead of the current vault.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for unlink |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-V, --vault` | `string` | Vault name to use instead of the current vault. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow secret](flow_secret.md)	 - Manage secrets stored in a vault.
+## See also
 
+- [flow secret](flow_secret.md) — Manage secrets stored in a vault.
diff --git a/docs/cli/flow_sync.md b/docs/cli/flow_sync.md
index 115d86b4..86a56fb9 100644
--- a/docs/cli/flow_sync.md
+++ b/docs/cli/flow_sync.md
@@ -1,42 +1,44 @@
-## flow sync
+---
+title: flow sync
+description: "Refresh workspace cache and discover new executables."
+---
+
+# flow sync
 
 Refresh workspace cache and discover new executables.
 
-### Synopsis
+## Synopsis
 
 Refresh the workspace cache and discover new executables. Use --git to also pull latest changes for all git-sourced workspaces before syncing. Use --force with --git to discard local changes and hard reset to the remote.
 
-```
+```shell
 flow sync [flags]
 ```
 
-### Examples
-
-```
-
-  flow sync               # rescan all workspaces for new executables
-  flow sync --git         # pull all git-sourced workspaces, then rescan
-  flow sync --git --force # hard-reset git workspaces before rescan
+## Examples
 
+```shell
+flow sync               # rescan all workspaces for new executables
+flow sync --git         # pull all git-sourced workspaces, then rescan
+flow sync --git --force # hard-reset git workspaces before rescan
 ```
 
-### Options
+## Options
 
-```
-      --force           Force update by discarding local changes (hard reset to remote)
-  -g, --git             Pull latest changes for all git-sourced workspaces before syncing
-  -h, --help            help for sync
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
-
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `--force` |  | Force update by discarding local changes (hard reset to remote) |
+| `-g, --git` |  | Pull latest changes for all git-sourced workspaces before syncing |
+| `-h, --help` |  | help for sync |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
diff --git a/docs/cli/flow_template.md b/docs/cli/flow_template.md
index b9b24eaf..cb05b27f 100644
--- a/docs/cli/flow_template.md
+++ b/docs/cli/flow_template.md
@@ -1,8 +1,13 @@
-## flow template
+---
+title: flow template
+description: "Manage flowfile templates."
+---
+
+# flow template
 
 Manage flowfile templates.
 
-### Synopsis
+## Synopsis
 
 Manage flowfile templates. A template is a reusable flowfile scaffold that can generate
 executables, directory structures, and configuration files via 'template generate'.
@@ -15,25 +20,24 @@ Templates (*.flow.tmpl files) are also auto-discovered within your workspaces du
 Registered templates take precedence over discovered ones when names collide; use a
 'workspace/name' reference to target a specific discovered template.
 
-### Options
-
-```
-  -h, --help   help for template
-```
+## Options
 
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for template |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
-* [flow template add](flow_template_add.md)	 - Register a flowfile template by name.
-* [flow template generate](flow_template_generate.md)	 - Generate workspace executables and scaffolding from a flowfile template.
-* [flow template get](flow_template_get.md)	 - Get a flowfile template's details. Either it's registered name or file path can be used.
-* [flow template list](flow_template_list.md)	 - List registered and workspace-discovered flowfile templates.
-* [flow template remove](flow_template_remove.md)	 - Unregister a flowfile template by name.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
+- [flow template add](flow_template_add.md) — Register a flowfile template by name.
+- [flow template generate](flow_template_generate.md) — Generate workspace executables and scaffolding from a flowfile template.
+- [flow template get](flow_template_get.md) — Get a flowfile template's details. Either it's registered name or file path can be used.
+- [flow template list](flow_template_list.md) — List registered and workspace-discovered flowfile templates.
+- [flow template remove](flow_template_remove.md) — Unregister a flowfile template by name.
diff --git a/docs/cli/flow_template_add.md b/docs/cli/flow_template_add.md
index ba2787ed..29e805e5 100644
--- a/docs/cli/flow_template_add.md
+++ b/docs/cli/flow_template_add.md
@@ -1,26 +1,30 @@
-## flow template add
+---
+title: flow template add
+description: "Register a flowfile template by name."
+---
+
+# flow template add
 
 Register a flowfile template by name.
 
-```
+```shell
 flow template add NAME DEFINITION_TEMPLATE_PATH [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for add
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for add |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow template](flow_template.md)	 - Manage flowfile templates.
+## See also
 
+- [flow template](flow_template.md) — Manage flowfile templates.
diff --git a/docs/cli/flow_template_generate.md b/docs/cli/flow_template_generate.md
index eb341441..46a832c6 100644
--- a/docs/cli/flow_template_generate.md
+++ b/docs/cli/flow_template_generate.md
@@ -1,8 +1,13 @@
-## flow template generate
+---
+title: flow template generate
+description: "Generate workspace executables and scaffolding from a flowfile template."
+---
+
+# flow template generate
 
 Generate workspace executables and scaffolding from a flowfile template.
 
-### Synopsis
+## Synopsis
 
 Add rendered executables from a flowfile template to a workspace.
 
@@ -13,30 +18,29 @@ One of -f or -t must be provided and must point to a valid flowfile template.
 The -d flag can be used to specify an output directory within the workspace to create
 the flowfile and its artifacts in.
 
-```
+```shell
 flow template generate FLOWFILE_NAME [-w WORKSPACE ] [-d OUTPUT_DIR] [-f FILE | -t TEMPLATE] [flags]
 ```
 
-### Options
+## Options
 
-```
-  -d, --dir string                   Output directory (within the workspace) to create the flow file and its artifacts. If the directory does not exist, it will be created.
-  -f, --file string                  Path to the template file. It must be a valid flow file template.
-  -h, --help                         help for generate
-  -o, --output string                Output format. One of: yaml, json, or tui.
-  -s, --set stringArray              Set a form field value by key (KEY=value). Repeat for multiple fields. Fields with a matching key will skip the interactive prompt.
-  -t, --template flow set template   Registered template name. Templates can be registered in the flow configuration file or with flow set template.
-  -w, --workspace string             Workspace to create the flow file and its artifacts. Defaults to the current workspace.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-d, --dir` | `string` | Output directory (within the workspace) to create the flow file and its artifacts. If the directory does not exist, it will be created. |
+| `-f, --file` | `string` | Path to the template file. It must be a valid flow file template. |
+| `-h, --help` |  | help for generate |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-s, --set` | `stringArray` | Set a form field value by key (KEY=value). Repeat for multiple fields. Fields with a matching key will skip the interactive prompt. |
+| `-t, --template` | `string` | Registered template name. Templates can be registered in the flow configuration file or with 'flow template add'. |
+| `-w, --workspace` | `string` | Workspace to create the flow file and its artifacts. Defaults to the current workspace. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow template](flow_template.md)	 - Manage flowfile templates.
+## See also
 
+- [flow template](flow_template.md) — Manage flowfile templates.
diff --git a/docs/cli/flow_template_get.md b/docs/cli/flow_template_get.md
index 12a138d0..dbe6f1fe 100644
--- a/docs/cli/flow_template_get.md
+++ b/docs/cli/flow_template_get.md
@@ -1,28 +1,32 @@
-## flow template get
+---
+title: flow template get
+description: "Get a flowfile template's details. Either it's registered name or file path can be used."
+---
+
+# flow template get
 
 Get a flowfile template's details. Either it's registered name or file path can be used.
 
-```
+```shell
 flow template get [flags]
 ```
 
-### Options
+## Options
 
-```
-  -f, --file string                  Path to the template file. It must be a valid flow file template.
-  -h, --help                         help for get
-  -o, --output string                Output format. One of: yaml, json, or tui.
-  -t, --template flow set template   Registered template name. Templates can be registered in the flow configuration file or with flow set template.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-f, --file` | `string` | Path to the template file. It must be a valid flow file template. |
+| `-h, --help` |  | help for get |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-t, --template` | `string` | Registered template name. Templates can be registered in the flow configuration file or with 'flow template add'. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow template](flow_template.md)	 - Manage flowfile templates.
+## See also
 
+- [flow template](flow_template.md) — Manage flowfile templates.
diff --git a/docs/cli/flow_template_list.md b/docs/cli/flow_template_list.md
index 7b748903..6585ea7e 100644
--- a/docs/cli/flow_template_list.md
+++ b/docs/cli/flow_template_list.md
@@ -1,26 +1,30 @@
-## flow template list
+---
+title: flow template list
+description: "List registered and workspace-discovered flowfile templates."
+---
+
+# flow template list
 
 List registered and workspace-discovered flowfile templates.
 
-```
+```shell
 flow template list [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for list
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for list |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow template](flow_template.md)	 - Manage flowfile templates.
+## See also
 
+- [flow template](flow_template.md) — Manage flowfile templates.
diff --git a/docs/cli/flow_template_remove.md b/docs/cli/flow_template_remove.md
index 3c3d13fd..d4b66315 100644
--- a/docs/cli/flow_template_remove.md
+++ b/docs/cli/flow_template_remove.md
@@ -1,26 +1,30 @@
-## flow template remove
+---
+title: flow template remove
+description: "Unregister a flowfile template by name."
+---
+
+# flow template remove
 
 Unregister a flowfile template by name.
 
-```
+```shell
 flow template remove NAME [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for remove
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for remove |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow template](flow_template.md)	 - Manage flowfile templates.
+## See also
 
+- [flow template](flow_template.md) — Manage flowfile templates.
diff --git a/docs/cli/flow_vault.md b/docs/cli/flow_vault.md
index f420d6c3..03e9e808 100644
--- a/docs/cli/flow_vault.md
+++ b/docs/cli/flow_vault.md
@@ -1,8 +1,13 @@
-## flow vault
+---
+title: flow vault
+description: "Manage sensitive secret stores."
+---
+
+# flow vault
 
 Manage sensitive secret stores.
 
-### Synopsis
+## Synopsis
 
 Manage secret stores (vaults). A vault is an encrypted key-value store that holds secrets
 referenced by your executables. Multiple vault types are supported (e.g. age encryption,
@@ -11,26 +16,25 @@ AES-256, system keyring, or environment-variable passthrough).
 One vault is active at a time; use 'vault switch' to change the active vault. Secrets
 within a vault are managed with the 'secret' subcommands.
 
-### Options
-
-```
-  -h, --help   help for vault
-```
+## Options
 
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for vault |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
-* [flow vault create](flow_vault_create.md)	 - Create a new vault.
-* [flow vault edit](flow_vault_edit.md)	 - Edit the configuration of an existing vault.
-* [flow vault get](flow_vault_get.md)	 - Get the details of a vault.
-* [flow vault list](flow_vault_list.md)	 - List all available vaults.
-* [flow vault remove](flow_vault_remove.md)	 - Remove an existing vault.
-* [flow vault switch](flow_vault_switch.md)	 - Switch the active vault.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
+- [flow vault create](flow_vault_create.md) — Create a new vault.
+- [flow vault edit](flow_vault_edit.md) — Edit the configuration of an existing vault.
+- [flow vault get](flow_vault_get.md) — Get the details of a vault.
+- [flow vault list](flow_vault_list.md) — List all available vaults.
+- [flow vault remove](flow_vault_remove.md) — Remove an existing vault.
+- [flow vault switch](flow_vault_switch.md) — Switch the active vault.
diff --git a/docs/cli/flow_vault_create.md b/docs/cli/flow_vault_create.md
index e6947732..a87ddf3d 100644
--- a/docs/cli/flow_vault_create.md
+++ b/docs/cli/flow_vault_create.md
@@ -1,45 +1,47 @@
-## flow vault create
+---
+title: flow vault create
+description: "Create a new vault."
+---
+
+# flow vault create
 
 Create a new vault.
 
-```
+```shell
 flow vault create NAME [flags]
 ```
 
-### Examples
-
-```
-
-  flow vault create myvault --type age --set
-  flow vault create myvault --type aes256 --key-env VAULT_KEY
-  flow vault create myvault --type keyring
+## Examples
 
+```shell
+flow vault create myvault --type age --set
+flow vault create myvault --type aes256 --key-env VAULT_KEY
+flow vault create myvault --type keyring
 ```
 
-### Options
+## Options
 
-```
-  -c, --config string          File path to read the external vault's configuration from. The file must be a valid vault configuration file.
-  -h, --help                   help for create
-      --identity-env string    Environment variable name for the Age vault identity. Only used for Age vaults.
-      --identity-file string   File path for the Age vault identity. An absolute path is recommended. Only used for Age vaults.
-      --key-env string         Environment variable name for the vault encryption key. Only used for AES256 vaults.
-      --key-file string        File path for the vault encryption key. An absolute path is recommended. Only used for AES256 vaults.
-  -o, --output string          Output format. One of: yaml, json, or tui.
-  -p, --path string            Directory that the vault will use to store its data. If not set, the vault will be stored in the flow cache directory.
-      --recipients string      Comma-separated list of recipient keys for the vault. Only used for Age vaults.
-  -s, --set                    Set the newly created vault as the current vault
-  -t, --type string            Vault type. Either unencrypted, age, aes256, keyring, or external (default "aes256")
-```
-
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-c, --config` | `string` | File path to read the external vault's configuration from. The file must be a valid vault configuration file. |
+| `-h, --help` |  | help for create |
+| `--identity-env` | `string` | Environment variable name for the Age vault identity. Only used for Age vaults. |
+| `--identity-file` | `string` | File path for the Age vault identity. An absolute path is recommended. Only used for Age vaults. |
+| `--key-env` | `string` | Environment variable name for the vault encryption key. Only used for AES256 vaults. |
+| `--key-file` | `string` | File path for the vault encryption key. An absolute path is recommended. Only used for AES256 vaults. |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-p, --path` | `string` | Directory that the vault will use to store its data. If not set, the vault will be stored in the flow cache directory. |
+| `--recipients` | `string` | Comma-separated list of recipient keys for the vault. Only used for Age vaults. |
+| `-s, --set` |  | Set the newly created vault as the current vault |
+| `-t, --type` | `string` | Vault type. Either unencrypted, age, aes256, keyring, or external (default "aes256") |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow vault](flow_vault.md)	 - Manage sensitive secret stores.
+## See also
 
+- [flow vault](flow_vault.md) — Manage sensitive secret stores.
diff --git a/docs/cli/flow_vault_edit.md b/docs/cli/flow_vault_edit.md
index 70e2edde..97cd2763 100644
--- a/docs/cli/flow_vault_edit.md
+++ b/docs/cli/flow_vault_edit.md
@@ -1,36 +1,40 @@
-## flow vault edit
+---
+title: flow vault edit
+description: "Edit the configuration of an existing vault."
+---
+
+# flow vault edit
 
 Edit the configuration of an existing vault.
 
-### Synopsis
+## Synopsis
 
 Edit the configuration of an existing vault. Note: You cannot change the vault type after creation.
 
-```
+```shell
 flow vault edit NAME [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help                   help for edit
-      --identity-env string    Environment variable name for the Age vault identity. Only used for Age vaults.
-      --identity-file string   File path for the Age vault identity. An absolute path is recommended. Only used for Age vaults.
-      --key-env string         Environment variable name for the vault encryption key. Only used for AES256 vaults.
-      --key-file string        File path for the vault encryption key. An absolute path is recommended. Only used for AES256 vaults.
-  -o, --output string          Output format. One of: yaml, json, or tui.
-  -p, --path string            Directory that the vault will use to store its data. If not set, the vault will be stored in the flow cache directory.
-      --recipients string      Comma-separated list of recipient keys for the vault. Only used for Age vaults.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for edit |
+| `--identity-env` | `string` | Environment variable name for the Age vault identity. Only used for Age vaults. |
+| `--identity-file` | `string` | File path for the Age vault identity. An absolute path is recommended. Only used for Age vaults. |
+| `--key-env` | `string` | Environment variable name for the vault encryption key. Only used for AES256 vaults. |
+| `--key-file` | `string` | File path for the vault encryption key. An absolute path is recommended. Only used for AES256 vaults. |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-p, --path` | `string` | Directory that the vault will use to store its data. If not set, the vault will be stored in the flow cache directory. |
+| `--recipients` | `string` | Comma-separated list of recipient keys for the vault. Only used for Age vaults. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow vault](flow_vault.md)	 - Manage sensitive secret stores.
+## See also
 
+- [flow vault](flow_vault.md) — Manage sensitive secret stores.
diff --git a/docs/cli/flow_vault_get.md b/docs/cli/flow_vault_get.md
index aa4e8f35..a19f7d51 100644
--- a/docs/cli/flow_vault_get.md
+++ b/docs/cli/flow_vault_get.md
@@ -1,26 +1,30 @@
-## flow vault get
+---
+title: flow vault get
+description: "Get the details of a vault."
+---
+
+# flow vault get
 
 Get the details of a vault.
 
-```
+```shell
 flow vault get NAME [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for get
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for get |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow vault](flow_vault.md)	 - Manage sensitive secret stores.
+## See also
 
+- [flow vault](flow_vault.md) — Manage sensitive secret stores.
diff --git a/docs/cli/flow_vault_list.md b/docs/cli/flow_vault_list.md
index 283238b3..3775f8b5 100644
--- a/docs/cli/flow_vault_list.md
+++ b/docs/cli/flow_vault_list.md
@@ -1,26 +1,30 @@
-## flow vault list
+---
+title: flow vault list
+description: "List all available vaults."
+---
+
+# flow vault list
 
 List all available vaults.
 
-```
+```shell
 flow vault list [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for list
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for list |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow vault](flow_vault.md)	 - Manage sensitive secret stores.
+## See also
 
+- [flow vault](flow_vault.md) — Manage sensitive secret stores.
diff --git a/docs/cli/flow_vault_remove.md b/docs/cli/flow_vault_remove.md
index c73d344f..fd63016c 100644
--- a/docs/cli/flow_vault_remove.md
+++ b/docs/cli/flow_vault_remove.md
@@ -1,32 +1,36 @@
-## flow vault remove
+---
+title: flow vault remove
+description: "Remove an existing vault."
+---
+
+# flow vault remove
 
 Remove an existing vault.
 
-### Synopsis
+## Synopsis
 
 Remove an existing vault by its name. The vault's encrypted secret data remains on disk at its storage path, but its configuration is deleted so flow no longer tracks it.
 Note: You cannot remove the current vault.
 
-```
+```shell
 flow vault remove NAME [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for remove
-  -o, --output string   Output format. One of: yaml, json, or tui.
-  -y, --yes             Skip confirmation prompts
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for remove |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-y, --yes` |  | Skip confirmation prompts |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow vault](flow_vault.md)	 - Manage sensitive secret stores.
+## See also
 
+- [flow vault](flow_vault.md) — Manage sensitive secret stores.
diff --git a/docs/cli/flow_vault_switch.md b/docs/cli/flow_vault_switch.md
index bdfe77c6..f5c852d9 100644
--- a/docs/cli/flow_vault_switch.md
+++ b/docs/cli/flow_vault_switch.md
@@ -1,26 +1,30 @@
-## flow vault switch
+---
+title: flow vault switch
+description: "Switch the active vault."
+---
+
+# flow vault switch
 
 Switch the active vault.
 
-```
+```shell
 flow vault switch NAME [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for switch
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for switch |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow vault](flow_vault.md)	 - Manage sensitive secret stores.
+## See also
 
+- [flow vault](flow_vault.md) — Manage sensitive secret stores.
diff --git a/docs/cli/flow_workspace.md b/docs/cli/flow_workspace.md
index 44bd1b9c..8137ee05 100644
--- a/docs/cli/flow_workspace.md
+++ b/docs/cli/flow_workspace.md
@@ -1,8 +1,13 @@
-## flow workspace
+---
+title: flow workspace
+description: "Manage development workspaces."
+---
+
+# flow workspace
 
 Manage development workspaces.
 
-### Synopsis
+## Synopsis
 
 Manage flow workspaces. A workspace is a directory (local or git-sourced) that contains
 flow files defining your executables. One workspace is active at a time.
@@ -11,26 +16,25 @@ Workspaces are registered globally so flow can find executables across projects.
 Use 'workspace add' to register a new workspace, 'workspace switch' to change the
 active workspace, and 'workspace update' to pull the latest changes from a remote source.
 
-### Options
-
-```
-  -h, --help   help for workspace
-```
+## Options
 
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for workspace |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
-* [flow workspace add](flow_workspace_add.md)	 - Initialize a new workspace from a local path or Git URL.
-* [flow workspace get](flow_workspace_get.md)	 - Get workspace details. If the name is omitted, the current workspace is used.
-* [flow workspace list](flow_workspace_list.md)	 - List all registered workspaces.
-* [flow workspace remove](flow_workspace_remove.md)	 - Remove an existing workspace.
-* [flow workspace switch](flow_workspace_switch.md)	 - Switch the current workspace.
-* [flow workspace update](flow_workspace_update.md)	 - Pull latest changes for a git-sourced workspace.
+## See also
 
+- [flow](flow.md) — flow is a command line interface designed to make managing and running development workflows easier.
+- [flow workspace add](flow_workspace_add.md) — Initialize a new workspace from a local path or Git URL.
+- [flow workspace get](flow_workspace_get.md) — Get workspace details. If the name is omitted, the current workspace is used.
+- [flow workspace list](flow_workspace_list.md) — List all registered workspaces.
+- [flow workspace remove](flow_workspace_remove.md) — Remove an existing workspace.
+- [flow workspace switch](flow_workspace_switch.md) — Switch the current workspace.
+- [flow workspace update](flow_workspace_update.md) — Pull latest changes for a git-sourced workspace.
diff --git a/docs/cli/flow_workspace_add.md b/docs/cli/flow_workspace_add.md
index f3a27354..0f4618b8 100644
--- a/docs/cli/flow_workspace_add.md
+++ b/docs/cli/flow_workspace_add.md
@@ -1,8 +1,13 @@
-## flow workspace add
+---
+title: flow workspace add
+description: "Initialize a new workspace from a local path or Git URL."
+---
+
+# flow workspace add
 
 Initialize a new workspace from a local path or Git URL.
 
-### Synopsis
+## Synopsis
 
 Initialize a new workspace. PATH_OR_GIT_URL can be a local directory path or a Git repository URL (HTTPS or SSH). When a Git URL is provided, the repository is cloned to the flow cache directory and registered as a workspace.
 
@@ -12,29 +17,28 @@ Examples:
   flow workspace add tools git@github.com:org/tools.git --branch main
   flow workspace add stable https://github.com/org/flows.git --tag v1.0.0
 
-```
+```shell
 flow workspace add NAME PATH_OR_GIT_URL [flags]
 ```
 
-### Options
+## Options
 
-```
-  -b, --branch string   Git branch to checkout when cloning a git workspace
-      --depth int       Git clone depth (0 for full history)
-  -h, --help            help for add
-  -o, --output string   Output format. One of: yaml, json, or tui.
-  -s, --set             Set the newly created workspace as the current workspace
-      --tag string      Git tag to checkout when cloning a git workspace
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-b, --branch` | `string` | Git branch to checkout when cloning a git workspace |
+| `--depth` | `int` | Git clone depth (0 for full history) |
+| `-h, --help` |  | help for add |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-s, --set` |  | Set the newly created workspace as the current workspace |
+| `--tag` | `string` | Git tag to checkout when cloning a git workspace |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow workspace](flow_workspace.md)	 - Manage development workspaces.
+## See also
 
+- [flow workspace](flow_workspace.md) — Manage development workspaces.
diff --git a/docs/cli/flow_workspace_get.md b/docs/cli/flow_workspace_get.md
index a1240e52..73ec1f29 100644
--- a/docs/cli/flow_workspace_get.md
+++ b/docs/cli/flow_workspace_get.md
@@ -1,26 +1,30 @@
-## flow workspace get
+---
+title: flow workspace get
+description: "Get workspace details. If the name is omitted, the current workspace is used."
+---
+
+# flow workspace get
 
 Get workspace details. If the name is omitted, the current workspace is used.
 
-```
+```shell
 flow workspace get NAME [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for get
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for get |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow workspace](flow_workspace.md)	 - Manage development workspaces.
+## See also
 
+- [flow workspace](flow_workspace.md) — Manage development workspaces.
diff --git a/docs/cli/flow_workspace_list.md b/docs/cli/flow_workspace_list.md
index 152d84ec..ab783f05 100644
--- a/docs/cli/flow_workspace_list.md
+++ b/docs/cli/flow_workspace_list.md
@@ -1,28 +1,32 @@
-## flow workspace list
+---
+title: flow workspace list
+description: "List all registered workspaces."
+---
+
+# flow workspace list
 
 List all registered workspaces.
 
-```
+```shell
 flow workspace list [flags]
 ```
 
-### Options
+## Options
 
-```
-      --annotation stringArray   Filter by annotations. Format: 'key=value' for exact value match, or 'key' for presence regardless of value. Repeat the flag for multiple selectors; all selectors must match (AND).
-  -h, --help                     help for list
-  -o, --output string            Output format. One of: yaml, json, or tui.
-  -t, --tag stringArray          Filter by tags.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `--annotation` | `stringArray` | Filter by annotations. Format: 'key=value' for exact value match, or 'key' for presence regardless of value. Repeat the flag for multiple selectors; all selectors must match (AND). |
+| `-h, --help` |  | help for list |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-t, --tag` | `stringArray` | Filter by tags. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow workspace](flow_workspace.md)	 - Manage development workspaces.
+## See also
 
+- [flow workspace](flow_workspace.md) — Manage development workspaces.
diff --git a/docs/cli/flow_workspace_remove.md b/docs/cli/flow_workspace_remove.md
index 678296d8..8681430e 100644
--- a/docs/cli/flow_workspace_remove.md
+++ b/docs/cli/flow_workspace_remove.md
@@ -1,32 +1,36 @@
-## flow workspace remove
+---
+title: flow workspace remove
+description: "Remove an existing workspace."
+---
+
+# flow workspace remove
 
 Remove an existing workspace.
 
-### Synopsis
+## Synopsis
 
 Remove an existing workspace. File contents will remain in the corresponding directory but the workspace will be unlinked from the flow global configurations.
 Note: You cannot remove the current workspace.
 
-```
+```shell
 flow workspace remove NAME [flags]
 ```
 
-### Options
+## Options
 
-```
-  -h, --help            help for remove
-  -o, --output string   Output format. One of: yaml, json, or tui.
-  -y, --yes             Skip confirmation prompts
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `-h, --help` |  | help for remove |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
+| `-y, --yes` |  | Skip confirmation prompts |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow workspace](flow_workspace.md)	 - Manage development workspaces.
+## See also
 
+- [flow workspace](flow_workspace.md) — Manage development workspaces.
diff --git a/docs/cli/flow_workspace_switch.md b/docs/cli/flow_workspace_switch.md
index 1b8244bf..1ed5a38f 100644
--- a/docs/cli/flow_workspace_switch.md
+++ b/docs/cli/flow_workspace_switch.md
@@ -1,36 +1,38 @@
-## flow workspace switch
+---
+title: flow workspace switch
+description: "Switch the current workspace."
+---
+
+# flow workspace switch
 
 Switch the current workspace.
 
-```
+```shell
 flow workspace switch NAME [flags]
 ```
 
-### Examples
-
-```
-
-  flow workspace switch myproject
-  flow workspace switch myproject --fixed
+## Examples
 
+```shell
+flow workspace switch myproject
+flow workspace switch myproject --fixed
 ```
 
-### Options
+## Options
 
-```
-  -f, --fixed           Set the workspace mode to fixed
-  -h, --help            help for switch
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
-
-### Options inherited from parent commands
+| Flag | Type | Description |
+|------|------|-------------|
+| `-f, --fixed` |  | Set the workspace mode to fixed |
+| `-h, --help` |  | help for switch |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow workspace](flow_workspace.md)	 - Manage development workspaces.
+## See also
 
+- [flow workspace](flow_workspace.md) — Manage development workspaces.
diff --git a/docs/cli/flow_workspace_update.md b/docs/cli/flow_workspace_update.md
index 32cbbd99..a8bb9d36 100644
--- a/docs/cli/flow_workspace_update.md
+++ b/docs/cli/flow_workspace_update.md
@@ -1,34 +1,38 @@
-## flow workspace update
+---
+title: flow workspace update
+description: "Pull latest changes for a git-sourced workspace."
+---
+
+# flow workspace update
 
 Pull latest changes for a git-sourced workspace.
 
-### Synopsis
+## Synopsis
 
 Pull the latest changes from the git remote for a workspace that was added from a Git URL. If NAME is omitted, the current workspace is used.
 
 This respects the branch or tag that was originally specified when the workspace was added.
 Use --force to discard local changes and hard reset to the remote.
 
-```
+```shell
 flow workspace update [NAME] [flags]
 ```
 
-### Options
+## Options
 
-```
-      --force           Force update by discarding local changes (hard reset to remote)
-  -h, --help            help for update
-  -o, --output string   Output format. One of: yaml, json, or tui.
-```
+| Flag | Type | Description |
+|------|------|-------------|
+| `--force` |  | Force update by discarding local changes (hard reset to remote) |
+| `-h, --help` |  | help for update |
+| `-o, --output` | `string` | Output format. One of: yaml, json, or tui. |
 
-### Options inherited from parent commands
-
-```
-  -L, --log-level string   Log verbosity level (debug, info, fatal) (default "info")
-      --sync               Sync flow cache and workspaces
-```
+## Options inherited from parent commands
 
-### SEE ALSO
+| Flag | Type | Description |
+|------|------|-------------|
+| `-L, --log-level` | `string` | Log verbosity level (debug, info, fatal) (default "info") |
+| `--sync` |  | Sync flow cache and workspaces |
 
-* [flow workspace](flow_workspace.md)	 - Manage development workspaces.
+## See also
 
+- [flow workspace](flow_workspace.md) — Manage development workspaces.
diff --git a/docs/cli/flow_workspace_view.md b/docs/cli/flow_workspace_view.md
index d1ba5340..f5a8f7d1 100644
--- a/docs/cli/flow_workspace_view.md
+++ b/docs/cli/flow_workspace_view.md
@@ -1,31 +1,8 @@
 ---
-title: Flow Workspace View
+title: See also
+description: "- [flow workspace](flow_workspace.md) — Manage flow workspaces."
 ---
 
-## flow workspace view
-
-View the documentation for a workspace. If the name is omitted, the current workspace is used.
-
-```
-flow workspace view NAME [flags]
-```
-
-### Options
-
-```
-  -h, --help            help for view
-  -o, --output string   Output format. One of: yaml, json, doc, or list.
-```
-
-### Options inherited from parent commands
-
-```
-  -x, --non-interactive   Disable displaying flow output via terminal UI rendering. This is only needed if the interactive output is enabled by default in flow's configuration.
-      --sync              Sync flow cache and workspaces
-      --verbosity int     Log verbosity level (-1 to 1)
-```
-
-### SEE ALSO
-
-* [flow workspace](flow_workspace.md)	 - Manage flow workspaces.
+# See also
 
+- [flow workspace](flow_workspace.md) — Manage flow workspaces.
diff --git a/docs/development.md b/docs/development.md
index f4110de0..df6f816d 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -1,16 +1,25 @@
 ---
 title: Contributing to flow
+description: "How to contribute to flow: set up a development environment, understand the project layout, run the test suites, and work with generated code."
 ---
 
 # Contributing to flow
 
-[![Go Report Card](https://goreportcard.com/badge/github.com/flowexec/flow)](https://goreportcard.com/report/github.com/flowexec/flow)
-[![Go Reference](https://pkg.go.dev/badge/github.com/flowexec/flow.svg)](https://pkg.go.dev/github.com/flowexec/flow)
-[![GitHub branch check runs](https://img.shields.io/github/check-runs/flowexec/flow/main)](https://github.com/flowexec/flow/actions?query=branch%3Amain)
-[![Codecov](https://img.shields.io/codecov/c/github/flowexec/flow)](https://app.codecov.io/gh/flowexec/flow)
+<p class="badge-row">
+  <a href="https://deepwiki.com/flowexec/flow"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
+  <a href="https://pkg.go.dev/github.com/flowexec/flow"><img src="https://pkg.go.dev/badge/github.com/flowexec/flow.svg" alt="Go Reference"></a>
+  <a href="https://github.com/flowexec/flow/actions?query=branch%3Amain"><img src="https://img.shields.io/github/check-runs/flowexec/flow/main" alt="GitHub branch check runs"></a>
+  <a href="https://app.codecov.io/gh/flowexec/flow"><img src="https://img.shields.io/codecov/c/github/flowexec/flow" alt="Codecov"></a>
+</p>
 
 This document provides an overview of how to contribute to the flow project, including setting up your development environment, understanding the project structure, and running tests.
 
+> [!TIP]
+> Getting oriented in an unfamiliar codebase is the slow part.
+> [DeepWiki](https://deepwiki.com/flowexec/flow) indexes this repository and answers questions
+> against the source — use the **Ask AI** button in the nav on any page of this site, or read the
+> generated wiki directly. It is a fast way to find the right file before you start reading.
+
 Before getting started, please read our [Code of Conduct](https://github.com/flowexec/flow/blob/main/.github/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/flowexec/flow/blob/main/.github/CONTRIBUTING.md).
 
 **Ways to Contribute**
diff --git a/docs/examples.md b/docs/examples.md
index 2fca41a1..58b7c74e 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -1,5 +1,6 @@
 ---
 title: Examples
+description: "Real-world flow files from the flow-examples repository, covering Go projects, Docker, Kubernetes, Git automation, and HTTP APIs."
 ---
 
 # Examples
diff --git a/docs/guides/advanced.md b/docs/guides/advanced.md
index 376769f0..085a01c0 100644
--- a/docs/guides/advanced.md
+++ b/docs/guides/advanced.md
@@ -1,5 +1,6 @@
 ---
 title: Advanced Workflows
+description: "Advanced flow automation: conditional execution, shared state, composition across workspaces, and long-running background jobs."
 ---
 
 # Advanced Workflows
diff --git a/docs/guides/ai-tools.md b/docs/guides/ai-tools.md
index f9a6f4c8..f614a7d0 100644
--- a/docs/guides/ai-tools.md
+++ b/docs/guides/ai-tools.md
@@ -1,35 +1,21 @@
 ---
 title: AI Tools
+description: "Expose your workflows to Claude Code, Cursor, and any MCP client with flow's MCP server, plus llms.txt, JSON schemas, and a committed skill file."
 ---
 
 # AI Tools
 
-flow exposes your automation to AI coding tools through the [Model Context Protocol](https://modelcontextprotocol.io). Your assistant can discover, run, and write executables the same way you do — with full access to workspace context, secrets handling, and execution history.
+`flow mcp` exposes your automation over the [Model Context Protocol](https://modelcontextprotocol.io).
+A connected assistant discovers, runs, and writes executables through the same engine you use by
+hand — with the workspace's environment, secrets injected at run time, and every run recorded in
+flow's history.
 
-Beyond your named executables, flow can also act as your assistant's **shell**: it wraps arbitrary commands as transient, self-documenting runs so everything the assistant does executes with the right environment and lands in a single, attributable history — instead of scattered, untracked shell calls.
+flow provides the tools and stops there. It makes no model calls of its own and holds no vendor
+keys; the assistant is yours, and flow stays a deterministic task runner underneath it.
 
-## MCP Server
+## Setup
 
-### Setup
-
-Add this to your MCP client configuration (Claude Code, Cursor, Cline, or any MCP-compatible client):
-
-```json
-{
-  "mcpServers": {
-    "flow": {
-      "command": "flow",
-      "args": ["mcp"]
-    }
-  }
-}
-```
-
-The server runs over stdio. That's the entire setup.
-
-**Commit it to your repo.** Claude Code and Cursor both read a `.mcp.json` at the repository root,
-so checking that file in means every teammate — and every fresh clone — gets flow's tools without
-per-person setup. Put the snippet above in `.mcp.json` and commit it:
+Put this in `.mcp.json` at the root of your repository and commit it:
 
 ```json title=".mcp.json"
 {
@@ -43,11 +29,19 @@ per-person setup. Put the snippet above in `.mcp.json` and commit it:
 }
 ```
 
-Each user still approves the server on first use, so committing it grants no access on its own —
-it just removes the setup step. Pair it with the skill in [Wiring It Up](#wiring-it-up-for-your-project)
-below: the `.mcp.json` supplies the tools, the skill tells the assistant to reach for them.
+That is the entire setup. Claude Code and Cursor both read `.mcp.json` from the repository root, so
+committing it means every teammate and every fresh clone gets flow's tools with no per-person
+configuration. Each user still approves the server on first use, so the file grants no access on its
+own — it only removes the setup step. Other MCP clients take the same object under their own config
+path.
+
+This repo does exactly that: see
+[`.mcp.json`](https://github.com/flowexec/flow/blob/main/.mcp.json) in the flow source.
 
-### What's available
+Connecting the server gives your assistant the tools; it does not make it *reach* for them.
+[Teach it to prefer flow](#teaching-your-assistant-to-use-it) with a committed instruction file.
+
+## What the server exposes
 
 **Tools**
 
@@ -92,11 +86,13 @@ Structured prompts the assistant can invoke for common tasks:
 | `migrate_automation` | Convert existing Makefile, npm scripts, or shell scripts to flow |
 | `explain_flow` | Explain flow concepts and configuration |
 
-## Wiring It Up for Your Project
+## Teaching your assistant to use it
 
-Connecting flow via MCP gives your assistant the tools — but it won't automatically reach for them over plain shell commands. If you ask it to run tests, it might just run `go test ./...` instead of your `test` executable.
+Ask an assistant to run the tests and it will happily type `go test ./...` instead of calling your
+`test` executable — the tools being available is not the same as the tools being used.
 
-The solution is a small instruction file committed to your repo. Claude Code calls these [background skills](https://agentskills.io): they load into context on every session without any manual invocation.
+The fix is a small instruction file committed alongside the `.mcp.json`. Claude Code calls these
+[background skills](https://agentskills.io): they load on every session with no manual invocation.
 
 Create `.claude/skills/flow-context/SKILL.md`:
 
@@ -107,31 +103,48 @@ description: This project uses flow for automation. When asked to build, test, r
 user-invocable: false
 ---
 
-This repository uses flow for automation. The `mcp__flow__*` MCP tools are available —
-prefer them over raw Bash for anything runnable.
+This repository uses **flow** for all development automation. The `mcp__flow__*` MCP tools are
+available — prefer them over raw `Bash` for anything runnable, so it executes with the workspace's
+environment and secrets and is captured in flow's execution history.
 
 ## Running work — pick the closest tool
 
-1. **Named task?** (build, test, lint, deploy, …) → `mcp__flow__list_executables` to find it,
-   then `mcp__flow__execute` with its verb + name. Don't hand-roll a shell command a flow
-   executable already covers.
+1. **Named task?** (build, test, lint, validate, generate, deploy, …) → `mcp__flow__list_executables`
+   to find it, then `mcp__flow__execute` with its verb + name. Don't hand-roll a shell command a
+   flow executable already covers.
 2. **Arbitrary one-off command?** (a `git ...`, a script) → `mcp__flow__run_command` with the
-   command and a short `label`. Runs with workspace env/secrets and lands in `flow logs`.
-   Pass `commands` (array) + `mode` (`serial`/`parallel`) to run several in one call.
-3. **One-off is Python?** → `mcp__flow__run_python` with `code` and a short `label`, rather
-   than `python -c` or a scratch `.py` file. flow resolves the workspace's virtualenv, so
-   imports see the project's dependencies, and tracebacks report real line numbers.
+   command and a short `label`. It runs with workspace env/secrets and lands in `flow logs` with
+   provenance. Pass `commands` (array) + `mode` (`serial`/`parallel`) to run several in one call.
+3. **One-off is Python?** → `mcp__flow__run_python` with `code` and a short `label`, rather than
+   `python -c` or a scratch `.py` file. flow resolves the workspace's virtualenv, so imports see
+   the project's dependencies and tracebacks report real line numbers.
 4. **Something richer than one command?** (a serial/parallel batch, an HTTP `request`) →
    `mcp__flow__run_executable` with an inline `spec`.
-5. Only fall back to Bash for things that genuinely shouldn't be recorded or that flow isn't
-   suited to (e.g. interactive/TTY programs).
+5. Only fall back to `Bash` when a command genuinely shouldn't be recorded or flow isn't the right
+   tool (e.g. interactive/TTY programs).
+
+## Key executables in this repo
 
-Call `mcp__flow__get_info` at the start of a session, or when you need schema URLs to author
-.flow files. To review what you've run this session, call `mcp__flow__get_execution_logs`
-with `mine: true`.
+Common refs: `test unit`, `lint`, `build app`. Use `mcp__flow__list_executables` to discover
+current names — don't assume them.
+
+## Context & authoring
+
+- Call `mcp__flow__get_info` at the start of a session, or when you need schema URLs to author
+  `.flow` files.
+- Author or edit flow files with `mcp__flow__write_flowfile` (validated server-side) rather than
+  writing YAML by hand.
+- To review what you've run this session, call `mcp__flow__get_execution_logs` with `mine: true`;
+  `source`/`session`/`status` filter history more broadly.
 ```
 
-`user-invocable: false` keeps it out of the `/` command menu — it's not something you invoke, it's just always there. Update the body with the specific executables your project uses.
+`user-invocable: false` keeps it out of the `/` command menu — it is not something you invoke, it is
+just always in context.
+
+The **Key executables** section is the part worth tailoring: name the handful of refs your project
+actually uses, and tell the assistant to discover the rest rather than guess. flow's own copy lives
+at [`.claude/skills/flow-context/SKILL.md`](https://github.com/flowexec/flow/blob/main/.claude/skills/flow-context/SKILL.md)
+if you want a working reference.
 
 ## Observability
 
@@ -182,3 +195,49 @@ executables:
 | `flow.yaml` (workspace) | [workspace_schema.json](https://flowexec.io/schemas/workspace_schema.json) |
 | `*.flow.tmpl` (template) | [template_schema.json](https://flowexec.io/schemas/template_schema.json) |
 | User config | [config_schema.json](https://flowexec.io/schemas/config_schema.json) |
+
+## Understanding flow itself
+
+Everything above is about running *your* automation. A different question — how flow itself works,
+why a reference resolves the way it does, what the runner does on a failed step — is answered by the
+Go source rather than by these guides.
+
+[DeepWiki](https://deepwiki.com/flowexec/flow) indexes the `flowexec/flow` repository and answers
+questions against it.
+
+### From this site
+
+Every page here has an **Ask AI** button in the nav. It sends your question to DeepWiki and renders
+the answer inline; expect roughly fifteen seconds.
+
+### From your assistant
+
+DeepWiki runs a public MCP server. Adding it alongside flow's own server lets an assistant read how
+flow works *and* run your workflows in the same session:
+
+```json title=".mcp.json"
+{
+  "mcpServers": {
+    "flow": {
+      "type": "stdio",
+      "command": "flow",
+      "args": ["mcp"]
+    },
+    "deepwiki": {
+      "type": "http",
+      "url": "https://mcp.deepwiki.com/mcp"
+    }
+  }
+}
+```
+
+It exposes three tools — `ask_question`, `read_wiki_structure`, and `read_wiki_contents` — and takes
+any `owner/repo` it has indexed, so the same entry answers for your own dependencies too.
+
+This one is genuinely optional. It is a third-party service, it needs network access, and unlike
+flow's server it does put a model in the loop. Leave it out if either of those is a problem.
+
+> [!NOTE]
+> DeepWiki's answers are model-generated. They are grounded in real source, but they can be wrong or
+> lag behind `main`. Treat them as a fast way to find the right file, and confirm anything
+> load-bearing against the code or these guides.
diff --git a/docs/guides/concepts.md b/docs/guides/concepts.md
index 7f2b8f10..201f8477 100644
--- a/docs/guides/concepts.md
+++ b/docs/guides/concepts.md
@@ -1,5 +1,6 @@
 ---
 title: Core Concepts
+description: "The three things flow is built on: workspaces that group automation by project, executables that define what runs, and vaults that hold secrets."
 ---
 
 # Core Concepts
diff --git a/docs/guides/containers.md b/docs/guides/containers.md
new file mode 100644
index 00000000..0d68cc09
--- /dev/null
+++ b/docs/guides/containers.md
@@ -0,0 +1,185 @@
+---
+title: Containers
+description: "Run a single flow executable inside a container image with exec.container, or run the whole CLI from ghcr.io/flowexec/flow in a CI pipeline."
+---
+
+# Containers
+
+There are two separate things you might mean by "run flow in a container", and they solve different
+problems:
+
+- **[A step runs in a container](#running-a-step-in-a-container)** — flow runs on your machine and
+  puts one executable inside an image. Use this when a task needs a toolchain you would rather not
+  install.
+- **[flow runs in a container](#running-flow-in-a-container)** — the whole CLI runs inside an image.
+  Use this for CI platforms with no first-party integration, or for fully isolated execution.
+
+## Running a step in a container
+
+Any `exec` executable can declare a `container`. flow resolves parameters, arguments, and secrets on
+the host as usual, then runs the command inside the image with the workspace mounted:
+
+```yaml
+executables:
+  - verb: build
+    name: app
+    exec:
+      container:
+        image: golang:1.26-bookworm
+      cmd: go build -o bin/app ./cmd/app
+```
+
+The workspace root is mounted at `/workspace` and the executable's directory becomes the working
+directory inside it, so `cmd` reads exactly as it would on the host. Nothing else about the
+executable changes — it still composes, still takes parameters, still appears in `flow browse`.
+
+### Options
+
+| Field | Default | What it does |
+|-------|---------|--------------|
+| `image` | *required* | Image to run in, e.g. `golang:1.26-alpine` |
+| `runtime` | `auto` | `docker` or `podman`; `auto` prefers Docker and falls back to Podman |
+| `workdir` | the executable's `dir` | Working directory inside the container |
+| `mountWorkspace` | `/workspace` | Where the workspace root is mounted |
+| `volumes` | `[]` | Extra bind mounts, `host:container` or `host:container:options` |
+| `inheritEnv` | `true` | Pass flow's resolved environment in |
+| `entrypoint` | matches the interpreter | `sh` for a shell command, `python3` for a Python one; set empty to use the image's own `ENTRYPOINT` |
+| `user` | current host user on Linux | `uid`, `uid:gid`, or a name |
+| `network` | runtime default | e.g. `host`, `none`, or a named network |
+
+### What crosses the boundary
+
+Two defaults are worth knowing, because they are what make containerised steps behave predictably:
+
+**Environment.** `inheritEnv` passes flow's *resolved* environment — parameters, arguments, and
+`FLOW_*` variables — into the container. The host process environment is **never** forwarded,
+whatever you set it to. A container step therefore sees the values the executable declares and
+nothing it happened to inherit from your shell, which is the same isolation CI gives you.
+
+Host interpreter discovery stops at the container boundary too: `VIRTUAL_ENV`, `PYTHONPATH`,
+`PYTHONHOME`, and `FLOW_PYTHON_BIN` are dropped regardless of `inheritEnv`. Those paths either do
+not exist inside the image or, worse, resolve to an unrelated mounted directory.
+
+**File ownership.** On Linux, `user` defaults to the current host user, so files the container
+writes into the mounted workspace are not owned by `root`. Set `user: root` to opt out if the image
+needs it.
+
+### A fuller example
+
+```yaml
+executables:
+  - verb: test
+    name: integration
+    exec:
+      params:
+        - envKey: DATABASE_URL
+          secretRef: test-db-url
+      container:
+        image: golang:1.26-bookworm
+        network: host
+        volumes:
+          - /var/run/docker.sock:/var/run/docker.sock
+        workdir: /workspace/tests
+      cmd: go test -tags=integration ./...
+```
+
+`DATABASE_URL` is decrypted from the vault on the host and handed to the container as an
+environment variable. The secret never touches the image or the mounted files.
+
+### A pinned Python toolchain
+
+`interpreter: python` composes with `container`, which is the tidiest way to run Python against an
+exact version without installing it locally:
+
+```yaml
+executables:
+  - verb: run
+    name: report
+    exec:
+      interpreter: python
+      container:
+        image: python:3.13-alpine
+      cmd: |
+        import sys
+        print(sys.version)
+```
+
+flow writes the inline code to a script and bind-mounts it read only rather than passing it with
+`-c`, so tracebacks report real line numbers and the code never lands in the process table. The
+entrypoint defaults to `python3`, resolved on the image's `PATH` — which is what lets any Python
+image work with no further configuration.
+
+Setting `entrypoint: ""` hands execution to the image's own `ENTRYPOINT`; with Python that only
+works if the image's entrypoint is itself an interpreter.
+
+> [!TIP]
+> Reach for a container when the *toolchain* is the problem — a pinned compiler, a linter you do not
+> want globally installed. For steps that only need what is already on the machine, plain `exec` is
+> faster and simpler.
+
+## Running flow in a container
+
+The published image at `ghcr.io/flowexec/flow` carries the CLI and enough scaffolding to register a
+workspace on startup.
+
+```shell
+# Drop into the default workspace
+docker run -it --rm ghcr.io/flowexec/flow
+
+# Run one executable
+docker run -it --rm ghcr.io/flowexec/flow validate
+```
+
+The entrypoint reads three environment variables:
+
+| Variable | What it does |
+|----------|--------------|
+| `REPO` | Repository URL to clone (defaults to flow's own repo) |
+| `BRANCH` | Branch to check out |
+| `WORKSPACE` | Name to register the workspace under (defaults to `flow`) |
+
+### Workspace from git
+
+```shell
+docker run -it --rm \
+  -e REPO=https://github.com/your-org/your-workspace \
+  -e BRANCH=main \
+  -e WORKSPACE=my-workspace \
+  ghcr.io/flowexec/flow exec "deploy app"
+```
+
+### Workspace from your machine
+
+```shell
+docker run -it --rm \
+  -v $(pwd):/workspaces/my-workspace \
+  -w /workspaces/my-workspace \
+  -e WORKSPACE=my-workspace \
+  ghcr.io/flowexec/flow exec "build app"
+```
+
+## In CI/CD pipelines
+
+Any platform that can run a container can run flow. The shape is always the same:
+
+1. Use `ghcr.io/flowexec/flow` as the job image.
+2. Set `REPO`, `BRANCH`, and `WORKSPACE`, or mount the checkout directly.
+3. Call `flow exec "your executable"`.
+
+```yaml
+# GitLab CI
+test:
+  image: ghcr.io/flowexec/flow
+  variables:
+    WORKSPACE: my-project
+  script:
+    - flow exec "test unit"
+```
+
+On GitHub Actions, prefer the [first-party action](github-actions.md) — it handles vaults, multiple
+workspaces, and structured error codes for you.
+
+> [!NOTE]
+> The container image is less exercised than the CLI and the GitHub Action. It should work on any
+> Docker-capable platform, but if you run flow somewhere new we would like to hear how it went —
+> open an issue or say so in [Discord](https://discord.gg/CtByNKNMxM).
diff --git a/docs/guides/executables.md b/docs/guides/executables.md
index 822004d0..a1383a8c 100644
--- a/docs/guides/executables.md
+++ b/docs/guides/executables.md
@@ -1,5 +1,6 @@
 ---
 title: Executables
+description: "Every flow executable type and configuration option: exec, serial, parallel, request, render, and launch, with parameters, arguments, and conditionals."
 ---
 
 # Executables
diff --git a/docs/guides/execution-history.md b/docs/guides/execution-history.md
index bf244161..40a4481b 100644
--- a/docs/guides/execution-history.md
+++ b/docs/guides/execution-history.md
@@ -1,5 +1,6 @@
 ---
 title: Execution History & Logs
+description: "View, filter, and manage flow's execution history and logs, including runs launched by AI assistants."
 ---
 
 # Execution History & Logs
@@ -149,4 +150,4 @@ flow logs clear verb ws/ns:name
 ## What's Next?
 
 - **Customize your interface** → [Interactive UI](interactive.md)
-- **Integrate with external tools** → [Integrations](integrations.md)
+- **Run flow in CI** → [GitHub Actions](github-actions.md) or [Containers](containers.md)
diff --git a/docs/guides/expressions.md b/docs/guides/expressions.md
index 501b4473..0be04257 100644
--- a/docs/guides/expressions.md
+++ b/docs/guides/expressions.md
@@ -1,5 +1,6 @@
 ---
 title: Expression Language
+description: "The Expr-based expression language flow uses for conditionals and dynamic values in flow files."
 ---
 
 # Expression Language
diff --git a/docs/guides/first-workflow.md b/docs/guides/first-workflow.md
index ebe150d4..6f89d733 100644
--- a/docs/guides/first-workflow.md
+++ b/docs/guides/first-workflow.md
@@ -1,5 +1,6 @@
 ---
 title: Your First Workflow
+description: "Build a complete flow workflow from scratch: create a workspace, write a flow file, and run it."
 ---
 
 # Your First Workflow
diff --git a/docs/guides/generated-config.md b/docs/guides/generated-config.md
index eae77293..cb70f733 100644
--- a/docs/guides/generated-config.md
+++ b/docs/guides/generated-config.md
@@ -1,5 +1,6 @@
 ---
 title: Imported Executables Config Reference
+description: "Import existing Makefiles, npm scripts, and other automation into flow as generated executables."
 ---
 
 # Imported Executables Config Reference
diff --git a/docs/guides/github-actions.md b/docs/guides/github-actions.md
new file mode 100644
index 00000000..26252f22
--- /dev/null
+++ b/docs/guides/github-actions.md
@@ -0,0 +1,155 @@
+---
+title: GitHub Actions
+description: "Run your flow executables in GitHub Actions with flowexec/action: inputs, outputs, vault secrets, multi-workspace setups, and matrix builds."
+---
+
+# GitHub Actions
+
+The [`flowexec/action`](https://github.com/marketplace/actions/flow-execute) action installs the
+flow CLI, registers your repository as a workspace, and runs one executable. Anything you can run
+locally runs the same way in CI — same flow file, same reference, same environment resolution.
+
+## Quickstart
+
+```yaml
+name: CI
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: flowexec/action@v1
+        with:
+          executable: 'build app'
+```
+
+`executable` takes the same `VERB NAME` reference you would type after `flow exec`. This is the
+whole point of running flow in CI: the pipeline stops being a second copy of your build logic and
+becomes a one-line call into the automation you already maintain.
+
+flow's own pipelines work this way — see
+[`.github/workflows`](https://github.com/flowexec/flow/tree/main/.github/workflows) in this repo.
+
+## Inputs
+
+### Choosing what runs
+
+| Input | Default | What it does |
+|-------|---------|--------------|
+| `executable` | *required* | The executable reference to run, e.g. `test unit` |
+| `workspace` | `.` | Workspace to run in, as a path or a registered name |
+| `workspace-name` | auto | Name to register the workspace under |
+| `workspaces` | — | A YAML/JSON map of several workspaces, local or git-sourced |
+| `working-directory` | `.` | Directory to run flow from |
+| `flow-version` | `latest` | Pin the CLI version |
+
+### Passing values in
+
+| Input | Default | What it does |
+|-------|---------|--------------|
+| `params` | — | `KEY=VALUE` pairs bound to the executable's parameters |
+| `env` | — | `KEY=VALUE` pairs exported for the run |
+| `secrets` | — | `KEY=VALUE` pairs written into a vault before the run |
+| `vault-key` | — | Encryption key for an existing vault |
+
+### Controlling the run
+
+| Input | Default | What it does |
+|-------|---------|--------------|
+| `timeout` | `30m` | Abort the executable after this long |
+| `upload` | `false` | Upload flow's logs as a workflow artifact |
+| `continue-on-error` | `false` | Keep the job green when the executable fails |
+| `clone-token` | — | Token used to clone private git workspaces |
+| `clone-depth` | `1` | Clone depth for git workspaces; `0` for full history |
+
+## Secrets
+
+Secrets go into a flow vault for the duration of the job, then are injected into the executable
+exactly as they would be on your machine — so the executable does not need a CI-specific branch.
+
+```yaml
+      - uses: flowexec/action@v1
+        with:
+          executable: 'deploy app'
+          params: |
+            ENVIRONMENT=production
+          secrets: |
+            API_KEY=${{ secrets.API_KEY }}
+            DB_PASSWORD=${{ secrets.DB_PASSWORD }}
+```
+
+If you do not pass `vault-key`, the action generates one and returns it as an output, so a later
+step in the same job can reuse the vault.
+
+> [!IMPORTANT]
+> Pass secrets through the `secrets` input rather than `env`. Values arriving through `secrets` are
+> stored in the vault and referenced by name, which keeps them out of the executable's rendered
+> command line.
+
+## Multiple workspaces
+
+Composed automation often spans repositories. `workspaces` registers several at once, including
+ones cloned from git:
+
+```yaml
+      - uses: flowexec/action@v1
+        with:
+          executable: 'deploy platform'
+          workspaces: |
+            app: .
+            infra: https://github.com/your-org/infra.git
+          clone-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Cross-workspace references (`infra/k8s:apply`) then resolve the same way they do locally. See
+[Workspaces](workspaces.md) for how references are addressed.
+
+## Outputs
+
+| Output | What it carries |
+|--------|-----------------|
+| `exit-code` | Exit code of the executable |
+| `output` | Captured stdout |
+| `error-code` | Machine-readable failure code, e.g. `EXECUTION_FAILED`, `TIMEOUT`, `NOT_FOUND` |
+| `vault-key` | The generated vault key, when secrets were configured without one |
+
+`error-code` is the same stable code the CLI reports in its
+[error envelope](/guides/execution-history), so a job can branch on *why* something failed rather
+than parsing log text:
+
+```yaml
+      - uses: flowexec/action@v1
+        id: run
+        with:
+          executable: 'test e2e'
+          continue-on-error: 'true'
+      - if: steps.run.outputs.error-code == 'TIMEOUT'
+        run: echo "::warning::e2e timed out; retrying nightly"
+```
+
+## Matrix builds
+
+The action runs on Linux, macOS, and Windows runners, so one matrix covers every platform your
+workflow supports:
+
+```yaml
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: flowexec/action@v1
+        with:
+          executable: 'test unit'
+          upload: 'true'
+```
+
+## Other CI platforms
+
+There is no first-party action for GitLab CI, CircleCI, or Jenkins. Run flow through its container
+image instead — see [Containers](containers.md#in-ci-cd-pipelines).
diff --git a/docs/guides/index.md b/docs/guides/index.md
index d499a773..7dbd7e7f 100644
--- a/docs/guides/index.md
+++ b/docs/guides/index.md
@@ -1,5 +1,6 @@
 ---
 title: User Guides
+description: "Guides for flow, from core concepts and your first workflow through secrets, templates, expressions, and integrations."
 ---
 
 # User Guides
@@ -26,10 +27,21 @@ Master the core features of flow:
 
 Take your automation to the next level:
 
-- **[Templates & Code Generation](templating.md)** - Generate workflows and project scaffolding
+- **[Expression Language](expressions.md)** - Conditionals and dynamic values in flow files
 - **[Advanced Workflows](advanced.md)** - Complex automation with conditionals, state, and composition
+- **[Imported Executables](generated-config.md)** - Pull in Makefiles, npm scripts, and other existing automation
+- **[Templates & Code Generation](templating.md)** - Generate workflows and project scaffolding
+
+## Interfaces
+
 - **[Interactive UI](interactive.md)** - Customize and use the terminal interface
-- **[Integrations](integrations.md)** - Run flow in MCP clients, GitHub Actions, and containerized environments
+- **[Run Provenance](run-provenance.md)** - Trace who or what launched every run
+
+## Integrations
+
+- **[AI Tools & MCP](ai-tools.md)** - Give a coding assistant your workflows over MCP
+- **[Containers](containers.md)** - Run a single step in an image, or the whole CLI in one
+- **[GitHub Actions](github-actions.md)** - Call your executables from a CI pipeline
 
 ## Other Resources
 
diff --git a/docs/guides/integrations.md b/docs/guides/integrations.md
deleted file mode 100644
index 7fc5f3ef..00000000
--- a/docs/guides/integrations.md
+++ /dev/null
@@ -1,147 +0,0 @@
----
-title: Integrations
----
-
-# Integrations
-
-flow integrates with popular CI/CD platforms, AI assistants, and containerized environments to bring your automation anywhere.
-
-
-## AI Assistant Integration
-
-> For a full guide covering MCP, llms.txt, JSON schemas, and Claude Code integration, see [AI Tools](/guides/ai-tools).
-
-### Model Context Protocol (MCP)
-
-Connect flow to AI assistants through the local Model Context Protocol server for natural language workflow management.
-The flow MCP server enables AI assistants to discover, understand, and execute your flow workflows through conversational interfaces.
-
-#### Basic Usage
-
-Add the MCP server command to your favorite MCP client:
-
-```json
-{
-  "mcpServers": {
-    "flow": {
-      "command": "flow",
-      "args": ["mcp"]
-    }
-  }
-}
-```
-
-The server uses stdio transport and provides AI assistants with:
-
-**Available Tools:**
-- `get_info` - Get flow information, schemas, and current context
-- `execute` - Run a named executable by ref
-- `run_command` - Run arbitrary shell command(s) through flow, captured in history
-- `run_executable` - Run a transient executable of any type from an inline spec
-- `list_workspaces` - List all registered workspaces
-- `get_workspace` - Get details about a specific workspace
-- `get_workspace_config` - Get the full configuration for a specific workspace
-- `switch_workspace` - Change the current workspace
-- `list_executables` - List and filter executables across workspaces
-- `get_executable` - Get detailed information about an executable
-- `get_execution_logs` - Retrieve recent execution logs, with provenance filters
-- `sync_executables` - Sync workspace and executable state
-- `write_flowfile` - Create or update a flow file in a workspace
-
-**Available Resources:**
-- `flow://workspace/{name}` - Workspace metadata and configuration as JSON
-- `flow://executable/{workspace}/{namespace}/{name}` - Executable definition and metadata as JSON
-- `flow://flowfile/{path}` - Raw flowfile YAML content
-- `flow://logs/{run_id}` - Output of a specific execution run as plain text
-
-**Available Prompts:**
-- `generate_executable` - Generate flow executable configurations
-- `generate_project_executables` - Generate complete project automation sets
-- `debug_executable` - Debug failing executables
-- `migrate_automation` - Convert existing automation to flow
-- `explain_flow` - Explain flow concepts and usage
-
-> [!NOTE]
-> **Learn more about MCP**: Visit the [Model Context Protocol](https://modelcontextprotocol.io) documentation for client setup and integration details.
-
-## CI/CD & Deployment
-
-### GitHub Actions
-
-Execute flow workflows directly in your GitHub Actions pipelines with the official action.
-
-```yaml
-name: CI
-on: [push]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: flowexec/action@v1
-        with:
-          executable: 'build app'
-          params: |
-            ENVIRONMENT=production
-          secrets: |
-            API_KEY=${{ secrets.API_KEY }}
-```
-
-The action installs the flow CLI, registers your repository as a workspace, and runs the specified executable. It supports Linux, macOS, and Windows runners, multi-workspace setups with git-sourced workspaces, vault secret injection, and structured error codes as outputs.
-
-> **Complete documentation**: Visit the [Flow Execute Action](https://github.com/marketplace/actions/flow-execute) on GitHub Marketplace.
-
-### Docker
-
-Run flow in containerized environments for CI/CD pipelines or isolated execution.
-
-### Basic Usage
-
-```shell
-# Run with default workspace
-docker run -it --rm ghcr.io/flowexec/flow
-
-# Execute specific executable
-docker run -it --rm ghcr.io/flowexec/flow validate
-```
-
-**Environment Variables**
-- `REPO`: Repository URL to clone (defaults to flow's repo)
-- `BRANCH`: Git branch to checkout (optional)
-- `WORKSPACE`: Workspace name to use (defaults to "flow")
-
-
-### Workspace from Git
-
-Automatically clone and configure a workspace:
-
-```shell
-docker run -it --rm \
-  -e REPO=https://github.com/your-org/your-workspace \
-  -e BRANCH=main \
-  -e WORKSPACE=my-workspace \
-  ghcr.io/flowexec/flow exec "deploy app"
-```
-
-### Local Workspace
-
-Mount your local workspace:
-
-```shell
-docker run -it --rm \
-  -v $(pwd):/workspaces/my-workspace \
-  -w /workspaces/my-workspace \
-  -e WORKSPACE=my-workspace \
-  ghcr.io/flowexec/flow exec "build app"
-```
-
-### In CI/CD Pipelines
-
-Any CI/CD platform that supports Docker can run flow. The key is:
-
-1. **Use the Docker image**: `ghcr.io/flowexec/flow`
-2. **Set environment variables**: `REPO`, `WORKSPACE`, `BRANCH` as needed
-3. **Execute your flow commands**: `flow exec "your-executable"`
-
-> **Note**: While this should work, the Docker integration hasn't been extensively tested. If you try flow with other CI/CD platforms, we'd love to hear about your experience!
diff --git a/docs/guides/interactive.md b/docs/guides/interactive.md
index 5c95db96..3fa30036 100644
--- a/docs/guides/interactive.md
+++ b/docs/guides/interactive.md
@@ -1,5 +1,6 @@
 ---
 title: Interactive UI
+description: "Browse, search, filter, and run every workflow across every workspace from flow's terminal interface."
 ---
 
 # Interactive UI
diff --git a/docs/guides/run-provenance.md b/docs/guides/run-provenance.md
index 2e767f22..291626eb 100644
--- a/docs/guides/run-provenance.md
+++ b/docs/guides/run-provenance.md
@@ -1,5 +1,6 @@
 ---
 title: Run Provenance
+description: "Trace who or what launched every flow run — the CLI, an MCP client, or a specific agent session."
 ---
 
 # Run Provenance
diff --git a/docs/guides/secrets.md b/docs/guides/secrets.md
index 0c58f4d4..760c7f05 100644
--- a/docs/guides/secrets.md
+++ b/docs/guides/secrets.md
@@ -1,5 +1,6 @@
 ---
 title: Working with Secrets
+description: "Store secrets in encrypted local vaults with AES-256, age, keyring, or environment backends, and inject them into runs without committing anything."
 ---
 
 # Working with Secrets
diff --git a/docs/guides/templating.md b/docs/guides/templating.md
index 74a33bba..6cb3775e 100644
--- a/docs/guides/templating.md
+++ b/docs/guides/templating.md
@@ -1,5 +1,6 @@
 ---
 title: Templates & Workflow Generation
+description: "Generate flow files and project scaffolding from templates, with interactive forms, copied artifacts, and pre/post-run hooks."
 ---
 
 # Templates & Workflow Generation
diff --git a/docs/guides/workspaces.md b/docs/guides/workspaces.md
index cc365abb..9ea6473d 100644
--- a/docs/guides/workspaces.md
+++ b/docs/guides/workspaces.md
@@ -1,5 +1,6 @@
 ---
 title: Workspaces
+description: "Organize automation across projects with flow workspaces, including git-sourced workspaces and cross-workspace executable references."
 ---
 
 # Workspaces
diff --git a/docs/index.md b/docs/index.md
index fc649110..1fdcf383 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -2,9 +2,9 @@
 layout: home
 
 hero:
-  name: ""
-  text: "Built to flow with you."
-  tagline: "One place for all your scripts, secrets, and automation."
+  name: "flow · open source"
+  text: "Write your workflows down."
+  tagline: "Then run them from any project on your machine — with the right secrets, the right environment, and a record of what happened."
   image:
     src: /icon.png
     alt: flow
@@ -18,33 +18,60 @@ hero:
     - theme: alt
       text: View on GitHub
       link: https://github.com/flowexec/flow
-
-features:
-  - icon: 📁
-    title: Works Across All Your Projects
-    details: Register any repo as a workspace and run its workflows from anywhere on your machine
-  - icon: 🖥️
-    title: Find Anything Instantly
-    details: Browse, search, and filter all workflows across all projects from one TUI
-  - icon: 🔒
-    title: Secrets as First-Class Citizens
-    details: Encrypted local vaults with multiple backends — secrets inject at runtime, never hardcoded
-  - icon: ⚙️
-    title: Any Execution Pattern
-    details: Serial, parallel, conditional, HTTP requests, interactive prompts, and background jobs
-  - icon: 📄
-    title: Reusable Templates
-    details: Bootstrap new projects with flow-ready scaffolding from your own templates
-  - icon: 🤖
-    title: Works with AI Tools
-    details: Connect Claude Code, Cursor, or any MCP client and your assistant can discover, run, and write your workflows
+description: "Write your workflows down as flow files, then run them from any project on your machine — with encrypted secrets, execution history, and an MCP server for coding agents."
 ---
 
+<NowStrip />
+
 <p align="center"><video autoplay loop muted playsinline style="width: 100%; max-width: 900px; display: block; margin: 0 auto;"><source src="/demo/hero.mp4" type="video/mp4"><img src="/demo/hero.gif" style="width: 100%; max-width: 900px;"></video></p>
 
-Browse real-world workflows in the [Examples gallery](/examples) or explore the [flow project's own executables](https://github.com/flowexec/flow/tree/main/.execs).
+<NumberedSection index="01" label="Write" claim="Workflows are YAML you keep next to the code they run." aside="Not another YAML dialect — every flow file validates against a published JSON schema, so your editor autocompletes it before flow ever sees it.">
+A flow file declares what a task does, what it needs, and how it runs: in order, in parallel, behind a condition, as an HTTP request, or as a background job. Check it in and the automation travels with the repo.
+</NumberedSection>
+
+<NumberedSection index="02" label="Run" claim="One binary, every project on your machine." aside="Not a task runner you have to cd into — flow knows where every workspace lives, so the command reads the same from any directory.">
+Register a repo as a workspace and its workflows are reachable from anywhere — by name from your shell, or by browsing them in the terminal UI. Secrets come out of an encrypted local vault at the moment they are needed, never out of a file you committed.
+</NumberedSection>
+
+<NumberedSection index="03" label="Connect" claim="The same workflows, from your terminal or your coding agent." aside="Not an AI product — flow ships the tools and stops there. No vendor keys and no model calls in the critical path of a task runner.">
+<code>flow mcp</code> exposes every executable over the Model Context Protocol, so an assistant can discover what a project is able to do, run it, and read the logs back — through the same engine you use by hand.
+</NumberedSection>
+
+<SectionHead icon="box" label="What's inside" moreText="All guides" moreLink="/guides/" />
 
-::: tip Mochi: Your workflows, neatly wrapped
-Want a desktop UI, workflow auto-discovery, and AI enrichment on top of Flow?
+<CardGrid>
+  <Card icon="folder" title="Workspaces" :stack="['registry', 'git', 'discovery']" href="/guides/workspaces" alt-href="/types/workspace" alt-href-text="Schema">
+    Register any repo once. Its executables are then addressable from anywhere, with that project's environment applied.
+  </Card>
+  <Card icon="zap" title="Executables" :stack="['serial', 'parallel', 'request', 'render', 'launch']" href="/guides/executables" alt-href="/types/flowfile" alt-href-text="Schema">
+    Six execution types, conditionals, retries, arguments, and prompts — composed from other executables by reference.
+  </Card>
+  <Card icon="lock" title="Vaults" :stack="['AES-256', 'age', 'keyring', 'env']" href="/guides/secrets" alt-href="/cli/flow_vault" alt-href-text="CLI">
+    Encrypted local secret storage with pluggable backends. Values are injected into the process at run time and never written to disk.
+  </Card>
+  <Card icon="file" title="Templates" :stack="['scaffolding', 'generation']" href="/guides/templating" alt-href="/types/template" alt-href-text="Schema">
+    Bootstrap new projects and new workflows from templates you author, with prompts and generated files.
+  </Card>
+  <Card icon="monitor" title="Interactive UI" :stack="['browse', 'search', 'logs']" href="/guides/interactive" alt-href="/cli/flow_browse" alt-href-text="CLI">
+    Browse, filter, and run every workflow across every workspace from one terminal interface — then watch the logs stream.
+  </Card>
+  <Card icon="plug" title="AI tools" badge="MCP" :stack="['Claude Code', 'Cursor', 'any MCP client']" href="/guides/ai-tools" alt-href="/cli/flow_mcp" alt-href-text="CLI">
+    A deterministic tool surface for assistants: discover, run, and author workflows, with full provenance on every run.
+  </Card>
+</CardGrid>
+
+<SectionHead icon="book" label="Start here" moreText="Examples gallery" moreLink="/examples" />
+
+- **[Install flow](/installation)** — one line on macOS, Linux, or Windows
+- **[Quickstart](/quickstart)** — a working workflow in about five minutes
+- **[Core concepts](/guides/concepts)** — workspaces, executables, and vaults, and how they fit together
+- **[Examples](/examples)** — real flow files for Go, Docker, Kubernetes, Git, and HTTP APIs
+- **[flow's own automation](https://github.com/flowexec/flow/tree/main/.execs)** — this project builds, tests, and releases itself with flow
+- **[How flow is built](https://jahvon.dev/architecture/flow/)** — an architecture deep dive from Dockery Labs, the workshop behind flow
+
+::: tip Mochi: your workflows, neatly wrapped
+Want a desktop dashboard, workflow auto-discovery, and AI enrichment on top of flow?
 [Sign up for early access →](https://mochiexec.io)
-:::
\ No newline at end of file
+:::
+
+<p class="home-closer">A short path to everything you run.</p>
diff --git a/docs/installation.md b/docs/installation.md
index 005681bf..1a612770 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,5 +1,6 @@
 ---
 title: Installation
+description: "Install the flow CLI on macOS, Linux, or Windows with a one-line script, Homebrew, go install, or a release binary."
 ---
 
 # Installation
@@ -116,4 +117,4 @@ Ready to start automating? → [Quick start guide](quickstart.md)
 
 ## CI/CD & Containers
 
-For GitHub Actions, Docker, and other integrations, see the [integrations guide](guides/integrations.md).
\ No newline at end of file
+To run flow in CI, see [GitHub Actions](guides/github-actions.md) or [Containers](guides/containers.md).
\ No newline at end of file
diff --git a/docs/package-lock.json b/docs/package-lock.json
index aff6c07b..460566b1 100644
--- a/docs/package-lock.json
+++ b/docs/package-lock.json
@@ -9,8 +9,10 @@
       "version": "0.1.0",
       "devDependencies": {
         "@types/js-yaml": "^4.0.9",
+        "@types/markdown-it": "^14.1.2",
         "@types/node": "^25.6.0",
         "js-yaml": "^4.3.1",
+        "markdown-it": "^14.1.0",
         "vitepress": "^1.6.4",
         "vitepress-plugin-tabs": "0.7.1",
         "vue": "^3.5.13",
@@ -178,6 +180,7 @@
       "integrity": "sha512-Mw6pAUF121MfngQtcUb5quZVqMC68pSYYjCRZkSITC085S3zdk+h/g7i6FxnVdbSU6OztxikSDMh1r7Z+4iPlA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@algolia/client-common": "5.40.1",
         "@algolia/requester-browser-xhr": "5.40.1",
@@ -1088,9 +1091,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1108,9 +1108,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1128,9 +1125,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1148,9 +1142,6 @@
         "riscv64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1168,9 +1159,6 @@
         "s390x"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1188,9 +1176,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1208,9 +1193,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1228,9 +1210,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -1248,9 +1227,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1274,9 +1250,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1300,9 +1273,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1326,9 +1296,6 @@
         "riscv64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1352,9 +1319,6 @@
         "s390x"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1378,9 +1342,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1404,9 +1365,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1430,9 +1388,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -2124,6 +2079,7 @@
       "integrity": "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~7.19.0"
       }
@@ -2420,6 +2376,7 @@
       "integrity": "sha512-iUNxcXUNg9085TJx0HJLjqtDE0r1RZ0GOGrt8KNQqQT5ugu8lZsHuMUYW/e0lHhq6xBvmktU9Bw4CXP9VQeKrg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@algolia/abtesting": "1.6.1",
         "@algolia/client-abtesting": "5.40.1",
@@ -2661,6 +2618,7 @@
       "integrity": "sha512-7Ke1jyybbbPZyZXFxEftUtxFGLMpE2n6A+z//m4CRDlj0hW+o3iYSmh8nFlYMurOiJVDmJRilUQtJr08KfIxlg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "tabbable": "^6.2.0"
       }
@@ -2782,6 +2740,26 @@
         "node": ">=6"
       }
     },
+    "node_modules/linkify-it": {
+      "version": "5.0.2",
+      "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.2.tgz",
+      "integrity": "sha512-ONTm2jCMAVZjgQa/Fy1kScXsuOoF5NPTsoFBdE1KVIZ2vAh/r9+Bqo+0jINCBYnavTPQZz38QzFTme79ENoN3Q==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/markdown-it"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "uc.micro": "^2.0.0"
+      }
+    },
     "node_modules/magic-string": {
       "version": "0.30.19",
       "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.19.tgz",
@@ -2799,6 +2777,34 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/markdown-it": {
+      "version": "14.3.0",
+      "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.3.0.tgz",
+      "integrity": "sha512-RCEsPjR+sr0x+AuYp601tKTkgFG4YEPLCzHST3cQ/fhlJkqAkz1L2/Qbp1j9qw5SBwQHFBoW8+hoN5xssOF0Tw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/markdown-it"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1",
+        "entities": "^4.5.0",
+        "linkify-it": "^5.0.2",
+        "mdurl": "^2.0.0",
+        "punycode.js": "^2.3.1",
+        "uc.micro": "^2.1.0"
+      },
+      "bin": {
+        "markdown-it": "bin/markdown-it.mjs"
+      }
+    },
     "node_modules/mdast-util-to-hast": {
       "version": "13.2.1",
       "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.1.tgz",
@@ -2821,6 +2827,13 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/mdurl": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.1.0.tgz",
+      "integrity": "sha512-1+HBaOx0zi/dQWht8rNv9MYf9qqpqL/kxI0hXImU6Y547zM6Sni8BQibt7ifgMcYtQg41ao3Ivd6cnSM86inpg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/micromark-util-character": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz",
@@ -3057,6 +3070,16 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/punycode.js": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
+      "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/regex": {
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/regex/-/regex-6.0.1.tgz",
@@ -3317,6 +3340,13 @@
       "license": "0BSD",
       "optional": true
     },
+    "node_modules/uc.micro": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
+      "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/undici": {
       "version": "7.29.0",
       "resolved": "https://registry.npmjs.org/undici/-/undici-7.29.0.tgz",
@@ -3340,6 +3370,7 @@
       "integrity": "sha512-i7qRCmY42zmCwnYlh9H2SvLEypEFGye5iRmEMKjcGi7zk9UquigRjFtTLz0TYqr0ZGLZhaMHl/foy1bZR+Cwlw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "pathe": "^2.0.3"
       }
@@ -3453,6 +3484,7 @@
       "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",
@@ -3513,6 +3545,7 @@
       "integrity": "sha512-+2ym1/+0VVrbhNyRoFFesVvBvHAVMZMK0rw60E3X/5349M1GuVdKeazuksqopEdvkKwKGs21Q729jX81/bkBJg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@docsearch/css": "3.8.2",
         "@docsearch/js": "3.8.2",
@@ -3566,6 +3599,7 @@
       "integrity": "sha512-toaZjQ3a/G/mYaLSbV+QsQhIdMo9x5rrqIpYRObsJ6T/J+RyCSFwN2LHNVH9v8uIcljDNa3QzPVdv3Y6b9hAJQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@vue/compiler-dom": "3.5.22",
         "@vue/compiler-sfc": "3.5.22",
@@ -3589,6 +3623,7 @@
       "dev": true,
       "hasInstallScript": true,
       "license": "Apache-2.0",
+      "peer": true,
       "bin": {
         "workerd": "bin/workerd"
       },
diff --git a/docs/package.json b/docs/package.json
index c33eae5c..4a04f4dc 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -10,8 +10,10 @@
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
+    "@types/markdown-it": "^14.1.2",
     "@types/node": "^25.6.0",
     "js-yaml": "^4.3.1",
+    "markdown-it": "^14.1.0",
     "vitepress": "^1.6.4",
     "vitepress-plugin-tabs": "0.7.1",
     "vue": "^3.5.13",
diff --git a/docs/public/apple-touch-icon.png b/docs/public/apple-touch-icon.png
new file mode 100644
index 00000000..9a2a5278
Binary files /dev/null and b/docs/public/apple-touch-icon.png differ
diff --git a/docs/public/demo.gif b/docs/public/demo.gif
deleted file mode 100644
index 4f53a019..00000000
Binary files a/docs/public/demo.gif and /dev/null differ
diff --git a/docs/public/llms.txt b/docs/public/llms.txt
index d32bcf9d..48182676 100644
--- a/docs/public/llms.txt
+++ b/docs/public/llms.txt
@@ -26,7 +26,8 @@ Flow organizes automation into **workspaces** (projects/domains), each rooted at
 - [Templates & Workflow Generation](https://flowexec.io/guides/templating): Generate executables from templates with interactive forms
 - [Advanced Workflows](https://flowexec.io/guides/advanced): Serial/parallel pipelines, retries, conditional execution, arguments/params
 - [Interactive UI](https://flowexec.io/guides/interactive): TUI customization and keybindings
-- [Integrations](https://flowexec.io/guides/integrations): MCP server, GitHub Actions, Docker, CI pipelines
+- [GitHub Actions](https://flowexec.io/guides/github-actions): the flowexec/action inputs and outputs, vault secrets in CI, multi-workspace and matrix builds
+- [Containers](https://flowexec.io/guides/containers): running a single executable inside an image via `exec.container`, and running the flow CLI itself from ghcr.io/flowexec/flow
 - [AI Tools](https://flowexec.io/guides/ai-tools): MCP setup and tools (including running arbitrary commands through flow), execution observability/provenance, llms.txt, JSON schemas, Claude Code skills and settings
 
 ## Configuration Reference
diff --git a/docs/public/og-default.png b/docs/public/og-default.png
new file mode 100644
index 00000000..8f0cceed
Binary files /dev/null and b/docs/public/og-default.png differ
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 3a9f6f21..0f388c49 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,5 +1,6 @@
 ---
 title: Quick Start
+description: "Write and run your first flow workflow in about five minutes: register a workspace, define an executable, and run it from anywhere."
 ---
 
 # Quick Start
diff --git a/docs/release.data.ts b/docs/release.data.ts
new file mode 100644
index 00000000..68cd8f52
--- /dev/null
+++ b/docs/release.data.ts
@@ -0,0 +1,51 @@
+import { defineLoader } from 'vitepress'
+
+const REPO = 'flowexec/flow'
+const GITHUB_API = 'https://api.github.com'
+
+export interface ReleaseData {
+  /** Latest release tag, e.g. "v1.4.2". Empty when the lookup failed. */
+  tag: string
+  url: string
+}
+
+declare const data: ReleaseData
+export { data }
+
+function githubHeaders(): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+  }
+  if (process.env.GITHUB_TOKEN) {
+    headers['Authorization'] = `Bearer ${process.env.GITHUB_TOKEN}`
+  }
+  return headers
+}
+
+const RELEASES_URL = `https://github.com/${REPO}/releases`
+
+export default defineLoader({
+  async load(): Promise<ReleaseData> {
+    // Unlike examples.data.ts this never throws: the version is decoration, and
+    // an unauthenticated CI build that trips GitHub's rate limit should still
+    // produce a site.
+    try {
+      const res = await fetch(`${GITHUB_API}/repos/${REPO}/releases/latest`, {
+        headers: githubHeaders(),
+      })
+      if (!res.ok) {
+        console.warn(`[release.data] GitHub API ${res.status}; omitting version`)
+        return { tag: '', url: RELEASES_URL }
+      }
+      const release = (await res.json()) as { tag_name?: string; html_url?: string }
+      return {
+        tag: release.tag_name ?? '',
+        url: release.html_url ?? RELEASES_URL,
+      }
+    } catch (err) {
+      console.warn(`[release.data] lookup failed; omitting version:`, err)
+      return { tag: '', url: RELEASES_URL }
+    }
+  },
+})
diff --git a/docs/tuikit.md b/docs/tuikit.md
index 76831ab2..8cb5b9d7 100644
--- a/docs/tuikit.md
+++ b/docs/tuikit.md
@@ -1,5 +1,6 @@
 ---
 title: Tuikit
+description: "tuikit is the terminal UI toolkit behind flow's interactive interface."
 ---
 
 > [!NOTE]
diff --git a/docs/types/config.md b/docs/types/config.md
index a851d6bf..9c403248 100644
--- a/docs/types/config.md
+++ b/docs/types/config.md
@@ -1,5 +1,6 @@
 ---
 title: Config
+description: "User Configuration for the Flow CLI. Includes configurations for workspaces, templates, I/O, and other settings for the CLI. It is read from the user's flow config directory: -…"
 ---
 
 <!-- (Documentation autogenerated by docsgen. Do not edit directly.) -->
@@ -19,28 +20,21 @@ Alternatively, a custom path can be set using the `FLOW_CONFIG_PATH` environment
 
 ## Properties
 
-**Required:**
-- `workspaces`
-- `currentWorkspace`
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `colorOverride` | Override the default color palette for the interactive UI. This can be used to customize the colors of the UI.  | [ColorPalette](#colorpalette) |  |  |
-| `currentNamespace` | The name of the current namespace.  Namespaces are used to reference executables in the CLI using the format `workspace:namespace/name`. If the namespace is not set, only executables defined without a namespace will be discovered.  | `string` |  |  |
-| `currentVault` | The name of the currently active vault. | `string` |  |  |
-| `currentWorkspace` | The name of the current workspace. This should match a key in the `workspaces` or `remoteWorkspaces` map. | `string` |  |  |
-| `defaultLogMode` | The default log mode to use when running executables. This can either be `hidden`, `json`, `logfmt` or `text`  `hidden` will not display any logs. `json` will display logs in JSON format. `logfmt` will display logs with a log level, timestamp, and message. `text` will just display the log message.  | `string` | logfmt |  |
-| `defaultTimeout` | The default timeout to use when running executables. This should be a valid duration string.  | `string` | 30m |  |
-| `interactive` |  | [Interactive](#interactive) |  |  |
-| `templates` | A map of flowfile template names to their paths. | `map` (`string` -> `string`) | map[] |  |
-| `theme` | The theme of the interactive UI. | `string` | default |  |
-| `updateCheck` | Whether to check for CLI updates in the background. When enabled, flow will periodically check GitHub for a newer version and display a notice if one is available after each command. Set `FLOW_NO_UPDATE_CHECK=1` to suppress checks regardless of this setting.  | `boolean` | false |  |
-| `vaults` | A legacy map of vault names to their storage paths, retained for backwards compatibility. The authoritative list of vaults is discovered from the vault configuration directory managed by flow; this map is no longer required to reference or switch vaults.  | `map` (`string` -> `string`) |  |  |
-| `workspaceMode` | The mode of the workspace. This can be either `fixed` or `dynamic`. In `fixed` mode, the current workspace used at runtime is always the one set in the currentWorkspace config field. In `dynamic` mode, the current workspace used at runtime is determined by the current directory. If the current directory is within a workspace, that workspace is used.  | `string` | dynamic |  |
-| `workspaces` | Map of workspace names to their paths. The path should be a valid absolute path to the workspace directory.  | `map` (`string` -> `string`) |  |  |
-
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `colorOverride` | [ColorPalette](#colorpalette) |  |  | Override the default color palette for the interactive UI. This can be used to customize the colors of the UI.  |
+| `currentNamespace` | `string` |  |  | The name of the current namespace.  Namespaces are used to reference executables in the CLI using the format `workspace:namespace/name`. If the namespace is not set, only executables defined without a namespace will be discovered.  |
+| `currentVault` | `string` |  |  | The name of the currently active vault. |
+| `currentWorkspace` | `string` |  |  | The name of the current workspace. This should match a key in the `workspaces` or `remoteWorkspaces` map. |
+| `defaultLogMode` | `string` | logfmt |  | The default log mode to use when running executables. This can either be `hidden`, `json`, `logfmt` or `text`  `hidden` will not display any logs. `json` will display logs in JSON format. `logfmt` will display logs with a log level, timestamp, and message. `text` will just display the log message.  |
+| `defaultTimeout` | `string` | 30m |  | The default timeout to use when running executables. This should be a valid duration string.  |
+| `interactive` | [Interactive](#interactive) |  |  |  |
+| `templates` | `map` (`string` -> `string`) | map[] |  | A map of flowfile template names to their paths. |
+| `theme` | `string` | default |  | The theme of the interactive UI. |
+| `updateCheck` | `boolean` | false |  | Whether to check for CLI updates in the background. When enabled, flow will periodically check GitHub for a newer version and display a notice if one is available after each command. Set `FLOW_NO_UPDATE_CHECK=1` to suppress checks regardless of this setting.  |
+| `vaults` | `map` (`string` -> `string`) |  |  | A legacy map of vault names to their storage paths, retained for backwards compatibility. The authoritative list of vaults is discovered from the vault configuration directory managed by flow; this map is no longer required to reference or switch vaults.  |
+| `workspaceMode` | `string` | dynamic |  | The mode of the workspace. This can be either `fixed` or `dynamic`. In `fixed` mode, the current workspace used at runtime is always the one set in the currentWorkspace config field. In `dynamic` mode, the current workspace used at runtime is determined by the current directory. If the current directory is within a workspace, that workspace is used.  |
+| `workspaces` | `map` (`string` -> `string`) |  | Yes | Map of workspace names to their paths. The path should be a valid absolute path to the workspace directory.  |
 
 ## Definitions
 
@@ -50,44 +44,33 @@ The color palette for the interactive UI.
 The colors can be either an ANSI 16, ANSI 256, or TrueColor (hex) value.
 If unset, the default color for the current theme will be used.
 
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `black` |  | `string` |  |  |
-| `body` |  | `string` |  |  |
-| `border` |  | `string` |  |  |
-| `codeStyle` | The style of the code block. For example, `monokai`, `dracula`, `github`, etc. See [chroma styles](https://github.com/alecthomas/chroma/tree/master/styles) for available style names.  | `string` |  |  |
-| `emphasis` |  | `string` |  |  |
-| `error` |  | `string` |  |  |
-| `gray` |  | `string` |  |  |
-| `info` |  | `string` |  |  |
-| `primary` |  | `string` |  |  |
-| `secondary` |  | `string` |  |  |
-| `success` |  | `string` |  |  |
-| `tertiary` |  | `string` |  |  |
-| `warning` |  | `string` |  |  |
-| `white` |  | `string` |  |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `black` | `string` |  |  |  |
+| `body` | `string` |  |  |  |
+| `border` | `string` |  |  |  |
+| `codeStyle` | `string` |  |  | The style of the code block. For example, `monokai`, `dracula`, `github`, etc. See [chroma styles](https://github.com/alecthomas/chroma/tree/master/styles) for available style names.  |
+| `emphasis` | `string` |  |  |  |
+| `error` | `string` |  |  |  |
+| `gray` | `string` |  |  |  |
+| `info` | `string` |  |  |  |
+| `primary` | `string` |  |  |  |
+| `secondary` | `string` |  |  |  |
+| `success` | `string` |  |  |  |
+| `tertiary` | `string` |  |  |  |
+| `warning` | `string` |  |  |  |
+| `white` | `string` |  |  |  |
 
 ### Interactive
 
 Configurations for the interactive UI.
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `enabled` |  | `boolean` |  | ✘ |
-| `notifyOnCompletion` | Whether to send a desktop notification when a command completes. | `boolean` |  |  |
-| `soundOnCompletion` | Whether to play a sound when a command completes. | `boolean` |  |  |
-
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `enabled` | `boolean` |  | Yes |  |
+| `notifyOnCompletion` | `boolean` |  |  | Whether to send a desktop notification when a command completes. |
+| `soundOnCompletion` | `boolean` |  |  | Whether to play a sound when a command completes. |
 
diff --git a/docs/types/flowfile.md b/docs/types/flowfile.md
index 7d282faa..70baf640 100644
--- a/docs/types/flowfile.md
+++ b/docs/types/flowfile.md
@@ -1,5 +1,6 @@
 ---
 title: FlowFile
+description: "Configuration for a group of Flow CLI executables. The file must have the extension `.flow`, `.flow.yaml`, or `.flow.yml` in order to be discovered by the CLI. It's configuration…"
 ---
 
 <!-- (Documentation autogenerated by docsgen. Do not edit directly.) -->
@@ -13,32 +14,24 @@ in order to be discovered by the CLI. It's configuration is used to define a gro
 
 ## Properties
 
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `annotations` |  | [CommonAnnotations](#commonannotations) | map[] |  |
-| `description` | A description of the executables defined within the flow file. This description will used as a shared description for all executables in the flow file.  | `string` |  |  |
-| `descriptionFile` | A path to a markdown file that contains the description of the executables defined within the flow file. | `string` |  |  |
-| `executables` |  | `array` ([Executable](#executable)) | [] |  |
-| `imports` |  | [Imports](#imports) | [] |  |
-| `namespace` | The namespace to be given to all executables in the flow file. If not set, the executables in the file will be grouped into the root (*) namespace. Namespaces can be reused across multiple flow files.  Namespaces are used to reference executables in the CLI using the format `workspace:namespace/name`.  | `string` |  |  |
-| `tags` | Tags to be applied to all executables defined within the flow file. | `array` (`string`) | [] |  |
-| `visibility` |  | [CommonVisibility](#commonvisibility) |  |  |
-
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `annotations` | [CommonAnnotations](#commonannotations) | map[] |  |  |
+| `description` | `string` |  |  | A description of the executables defined within the flow file. This description will used as a shared description for all executables in the flow file.  |
+| `descriptionFile` | `string` |  |  | A path to a markdown file that contains the description of the executables defined within the flow file. |
+| `executables` | `array` ([Executable](#executable)) | [] |  |  |
+| `imports` | [Imports](#imports) | [] |  |  |
+| `namespace` | `string` |  |  | The namespace to be given to all executables in the flow file. If not set, the executables in the file will be grouped into the root (*) namespace. Namespaces can be reused across multiple flow files.  Namespaces are used to reference executables in the CLI using the format `workspace:namespace/name`.  |
+| `tags` | `array` (`string`) | [] |  | Tags to be applied to all executables defined within the flow file. |
+| `visibility` | [CommonVisibility](#commonvisibility) |  |  |  |
 
 ## Definitions
 
 ### CommonAliases
 
 Alternate names that can be used to reference the executable in the CLI.
-
 **Type:** `array` (`string`)
 
-
-
-
 ### CommonAnnotations
 
 A map of arbitrary string key/value metadata attached to the object.
@@ -48,23 +41,15 @@ filtering or display in the Flow UI - treat them as opaque state.
 Keys should be namespaced (e.g. `my-tool.example.com/state`) to avoid
 collisions between tools.
 
-
 **Type:** `map` (`string` -> `string`)
 
-
-
-
 ### CommonTags
 
 A list of tags.
 Tags can be used with list commands to filter returned data.
 
-
 **Type:** `array` (`string`)
 
-
-
-
 ### CommonVisibility
 
 The visibility of the executables to Flow.
@@ -75,85 +60,55 @@ If not set, the visibility will default to `public`.
 `internal` executables can be executed within their own workspace but are not listed.
 `hidden` executables cannot be executed or listed.
 
-
-**Type:** `string`
-**Default:** `public`
-**Valid values:**
-- `public`
-- `private`
-- `internal`
-- `hidden`
-
-
+**Type:** `string` &middot; **Default:** `public`
+**Valid values:** `public`, `private`, `internal`, `hidden`
 
 ### ExecContainerVolume
 
 
-
-
-
-
-
-
 ### Executable
 
 The executable schema defines the structure of an executable in the Flow CLI.
 Executables are the building blocks of workflows and are used to define the actions that can be performed in a workspace.
 
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `aliases` |  | [CommonAliases](#commonaliases) | [] |  |
-| `annotations` |  | [CommonAnnotations](#commonannotations) | map[] |  |
-| `description` | A description of the executable. This description is rendered as markdown in the interactive UI.  | `string` |  |  |
-| `exec` |  | [ExecutableExecExecutableType](#executableexecexecutabletype) |  |  |
-| `launch` |  | [ExecutableLaunchExecutableType](#executablelaunchexecutabletype) |  |  |
-| `name` | An optional name for the executable.  Name is used to reference the executable in the CLI using the format `workspace/namespace:name`. [Verb group + Name] must be unique within the namespace of the workspace.  | `string` |  |  |
-| `parallel` |  | [ExecutableParallelExecutableType](#executableparallelexecutabletype) |  |  |
-| `render` |  | [ExecutableRenderExecutableType](#executablerenderexecutabletype) |  |  |
-| `request` |  | [ExecutableRequestExecutableType](#executablerequestexecutabletype) |  |  |
-| `serial` |  | [ExecutableSerialExecutableType](#executableserialexecutabletype) |  |  |
-| `tags` |  | [CommonTags](#commontags) | [] |  |
-| `timeout` | The maximum amount of time the executable is allowed to run before being terminated. The timeout is specified in Go duration format (e.g. 30s, 5m, 1h).  | `string` |  |  |
-| `verb` |  | [ExecutableVerb](#executableverb) | exec | ✘ |
-| `verbAliases` | A list of aliases for the verb. This allows the executable to be referenced with multiple verbs. | `array` ([Verb](#verb)) | [] |  |
-| `visibility` |  | [CommonVisibility](#commonvisibility) |  |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `aliases` | [CommonAliases](#commonaliases) | [] |  |  |
+| `annotations` | [CommonAnnotations](#commonannotations) | map[] |  |  |
+| `description` | `string` |  |  | A description of the executable. This description is rendered as markdown in the interactive UI.  |
+| `exec` | [ExecutableExecExecutableType](#executableexecexecutabletype) |  |  |  |
+| `launch` | [ExecutableLaunchExecutableType](#executablelaunchexecutabletype) |  |  |  |
+| `name` | `string` |  |  | An optional name for the executable.  Name is used to reference the executable in the CLI using the format `workspace/namespace:name`. [Verb group + Name] must be unique within the namespace of the workspace.  |
+| `parallel` | [ExecutableParallelExecutableType](#executableparallelexecutabletype) |  |  |  |
+| `render` | [ExecutableRenderExecutableType](#executablerenderexecutabletype) |  |  |  |
+| `request` | [ExecutableRequestExecutableType](#executablerequestexecutabletype) |  |  |  |
+| `serial` | [ExecutableSerialExecutableType](#executableserialexecutabletype) |  |  |  |
+| `tags` | [CommonTags](#commontags) | [] |  |  |
+| `timeout` | `string` |  |  | The maximum amount of time the executable is allowed to run before being terminated. The timeout is specified in Go duration format (e.g. 30s, 5m, 1h).  |
+| `verb` | [ExecutableVerb](#executableverb) | exec | Yes |  |
+| `verbAliases` | `array` ([Verb](#verb)) | [] |  | A list of aliases for the verb. This allows the executable to be referenced with multiple verbs. |
+| `visibility` | [CommonVisibility](#commonvisibility) |  |  |  |
 
 ### ExecutableArgument
 
-
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `default` | The default value to use if the argument is not provided. If the argument is required and no default is provided, the executable will fail.  | `string` |  |  |
-| `envKey` | The name of the environment variable that will be assigned the value. | `string` |  |  |
-| `flag` | The flag to use when setting the argument from the command line. Either `flag` or `pos` must be set, but not both.  | `string` |  |  |
-| `outputFile` | A path where the argument value will be temporarily written to disk. The file will be created before execution and cleaned up afterwards.  | `string` |  |  |
-| `pos` | The position of the argument in the command line ArgumentList. Values start at 1. Either `flag` or `pos` must be set, but not both.  | `integer` |  |  |
-| `required` | If the argument is required, the executable will fail if the argument is not provided. If the argument is not required, the default value will be used if the argument is not provided.  | `boolean` | false |  |
-| `type` | The type of the argument. This is used to determine how to parse the value of the argument. | `string` | string |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `default` | `string` |  |  | The default value to use if the argument is not provided. If the argument is required and no default is provided, the executable will fail.  |
+| `envKey` | `string` |  |  | The name of the environment variable that will be assigned the value. |
+| `flag` | `string` |  |  | The flag to use when setting the argument from the command line. Either `flag` or `pos` must be set, but not both.  |
+| `outputFile` | `string` |  |  | A path where the argument value will be temporarily written to disk. The file will be created before execution and cleaned up afterwards.  |
+| `pos` | `integer` |  |  | The position of the argument in the command line ArgumentList. Values start at 1. Either `flag` or `pos` must be set, but not both.  |
+| `required` | `boolean` | false |  | If the argument is required, the executable will fail if the argument is not provided. If the argument is not required, the default value will be used if the argument is not provided.  |
+| `type` | `string` | string |  | The type of the argument. This is used to determine how to parse the value of the argument. |
 
 ### ExecutableArgumentList
 
-
-
 **Type:** `array` ([ExecutableArgument](#executableargument))
 
-
-
-
 ### ExecutableDirectory
 
 The directory to execute the command in.
@@ -163,56 +118,42 @@ If prefixed with `./`, the path will be relative to the current working director
 If prefixed with `//`, the path will be relative to the workspace root.
 Environment variables in the path will be expended at runtime.
 
-
 **Type:** `string`
 
-
-
-
 ### ExecutableExecContainer
 
 Run the command or file inside a container instead of on the host.
 Requires `docker` or `podman` on the PATH.
 
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `entrypoint` | The container entrypoint. Defaults to `sh` so that `cmd` behaves as a shell command regardless of the image's own ENTRYPOINT. Set to an empty string to use the image's ENTRYPOINT instead.  | `string` |  |  |
-| `image` | The container image to run in (e.g. `golang:1.21-alpine`). | `string` |  | ✘ |
-| `inheritEnv` | Pass the flow-resolved environment (parameters, arguments, and `FLOW_*` variables) into the container. Defaults to `true`. The host process environment is never forwarded regardless of this setting.  | `boolean` |  |  |
-| `mountWorkspace` | The path inside the container where the workspace root is mounted. | `string` | /workspace |  |
-| `network` | The container network to attach to (e.g. `host`, `none`, or a named network). If unset, the runtime default is used.  | `string` |  |  |
-| `runtime` | The container runtime to use. `auto` prefers `docker` and falls back to `podman` if `docker` is not on the PATH.  | `string` | auto |  |
-| `user` | The user to run as inside the container, in `uid`, `uid:gid`, or `name` form. On Linux, defaults to the current host user so that files written to mounted volumes are not owned by root. Set to `root` to opt out.  | `string` |  |  |
-| `volumes` | Additional bind mounts to add to the container. | `array` ([ExecContainerVolume](#execcontainervolume)) | [] |  |
-| `workdir` | The working directory inside the container. If unset, the executable's resolved `dir` is translated to its path inside the workspace mount.  | `string` |  |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `entrypoint` | `string` |  |  | The container entrypoint. Defaults to `sh` so that `cmd` behaves as a shell command regardless of the image's own ENTRYPOINT. Set to an empty string to use the image's ENTRYPOINT instead.  |
+| `image` | `string` |  | Yes | The container image to run in (e.g. `golang:1.21-alpine`). |
+| `inheritEnv` | `boolean` |  |  | Pass the flow-resolved environment (parameters, arguments, and `FLOW_*` variables) into the container. Defaults to `true`. The host process environment is never forwarded regardless of this setting.  |
+| `mountWorkspace` | `string` | /workspace |  | The path inside the container where the workspace root is mounted. |
+| `network` | `string` |  |  | The container network to attach to (e.g. `host`, `none`, or a named network). If unset, the runtime default is used.  |
+| `runtime` | `string` | auto |  | The container runtime to use. `auto` prefers `docker` and falls back to `podman` if `docker` is not on the PATH.  |
+| `user` | `string` |  |  | The user to run as inside the container, in `uid`, `uid:gid`, or `name` form. On Linux, defaults to the current host user so that files written to mounted volumes are not owned by root. Set to `root` to opt out.  |
+| `volumes` | `array` ([ExecContainerVolume](#execcontainervolume)) | [] |  | Additional bind mounts to add to the container. |
+| `workdir` | `string` |  |  | The working directory inside the container. If unset, the executable's resolved `dir` is translated to its path inside the workspace mount.  |
 
 ### ExecutableExecExecutableType
 
 Standard executable type. Runs a command/file in a subprocess.
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `args` |  | [ExecutableArgumentList](#executableargumentlist) |  |  |
-| `cmd` | The command to execute. Only one of `cmd` or `file` must be set.  | `string` |  |  |
-| `container` |  | [ExecutableExecContainer](#executableexeccontainer) |  |  |
-| `dir` |  | [ExecutableDirectory](#executabledirectory) |  |  |
-| `file` | The file to execute (`.sh`, `.bat`, `.cmd`, `.ps1`, `.py`). Only one of `cmd` or `file` must be set.  | `string` |  |  |
-| `interpreter` | The interpreter used to run `cmd`. Defaults to `sh`, flow's built-in POSIX shell interpreter; `python` runs `cmd` as a Python script.  When set, this also overrides the interpreter inferred from a `file` extension. When unset, `file` is run by the interpreter matching its extension, so `file: script.py` runs under Python without setting this.  | [ExecutableExecInterpreter](#executableexecinterpreter) |  |  |
-| `logMode` | The log mode to use when running the executable. This can either be `hidden`, `json`, `logfmt` or `text`  | `string` | logfmt |  |
-| `params` |  | [ExecutableParameterList](#executableparameterlist) |  |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `args` | [ExecutableArgumentList](#executableargumentlist) |  |  |  |
+| `cmd` | `string` |  |  | The command to execute. Only one of `cmd` or `file` must be set.  |
+| `container` | [ExecutableExecContainer](#executableexeccontainer) |  |  |  |
+| `dir` | [ExecutableDirectory](#executabledirectory) |  |  |  |
+| `file` | `string` |  |  | The file to execute (`.sh`, `.bat`, `.cmd`, `.ps1`, `.py`). Only one of `cmd` or `file` must be set.  |
+| `interpreter` | [ExecutableExecInterpreter](#executableexecinterpreter) |  |  | The interpreter used to run `cmd`. Defaults to `sh`, flow's built-in POSIX shell interpreter; `python` runs `cmd` as a Python script.  When set, this also overrides the interpreter inferred from a `file` extension. When unset, `file` is run by the interpreter matching its extension, so `file: script.py` runs under Python without setting this.  |
+| `logMode` | `string` | logfmt |  | The log mode to use when running the executable. This can either be `hidden`, `json`, `logfmt` or `text`  |
+| `params` | [ExecutableParameterList](#executableparameterlist) |  |  |  |
 
 ### ExecutableExecInterpreter
 
@@ -220,111 +161,75 @@ The interpreter used to run a command.
 `sh` uses flow's built-in POSIX shell interpreter; `python` runs the command
 as a Python script.
 
-
 **Type:** `string`
-
-**Valid values:**
-- `sh`
-- `python`
-
-
+**Valid values:** `sh`, `python`
 
 ### ExecutableLaunchExecutableType
 
 Launches an application or opens a URI.
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `app` | The application to launch the URI with. | `string` |  |  |
-| `args` |  | [ExecutableArgumentList](#executableargumentlist) |  |  |
-| `params` |  | [ExecutableParameterList](#executableparameterlist) |  |  |
-| `uri` | The URI to launch. This can be a file path or a web URL. | `string` |  | ✘ |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `app` | `string` |  |  | The application to launch the URI with. |
+| `args` | [ExecutableArgumentList](#executableargumentlist) |  |  |  |
+| `params` | [ExecutableParameterList](#executableparameterlist) |  |  |  |
+| `uri` | `string` |  | Yes | The URI to launch. This can be a file path or a web URL. |
 
 ### ExecutableParallelExecutableType
 
-
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `args` |  | [ExecutableArgumentList](#executableargumentlist) |  |  |
-| `dir` |  | [ExecutableDirectory](#executabledirectory) |  |  |
-| `execs` | A list of executables to run in parallel. Each executable can be a command or a reference to another executable.  | [ExecutableParallelRefConfigList](#executableparallelrefconfiglist) |  | ✘ |
-| `failFast` | End the parallel execution as soon as an exec exits with a non-zero status. This is the default behavior. When set to false, all execs will be run regardless of the exit status of parallel execs.  | `boolean` |  |  |
-| `maxThreads` | The maximum number of threads to use when executing the parallel executables. | `integer` | 5 |  |
-| `params` |  | [ExecutableParameterList](#executableparameterlist) |  |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `args` | [ExecutableArgumentList](#executableargumentlist) |  |  |  |
+| `dir` | [ExecutableDirectory](#executabledirectory) |  |  |  |
+| `execs` | [ExecutableParallelRefConfigList](#executableparallelrefconfiglist) |  | Yes | A list of executables to run in parallel. Each executable can be a command or a reference to another executable.  |
+| `failFast` | `boolean` |  |  | End the parallel execution as soon as an exec exits with a non-zero status. This is the default behavior. When set to false, all execs will be run regardless of the exit status of parallel execs.  |
+| `maxThreads` | `integer` | 5 |  | The maximum number of threads to use when executing the parallel executables. |
+| `params` | [ExecutableParameterList](#executableparameterlist) |  |  |  |
 
 ### ExecutableParallelRefConfig
 
 Configuration for a parallel executable.
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `args` | Arguments to pass to the executable. | `array` (`string`) | [] |  |
-| `cmd` | The command to execute. One of `cmd` or `ref` must be set.  | `string` |  |  |
-| `if` | An expression that determines whether the executable should run, using the Expr language syntax. The expression is evaluated at runtime and must resolve to a boolean value.  The expression has access to OS/architecture information (os, arch), environment variables (env), stored data (store), and context information (ctx) like workspace and paths.  For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists in the store, and `env["CI"] == "true"` will run in CI environments. See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.  | `string` |  |  |
-| `interpreter` | The interpreter used to run `cmd` for this step. Defaults to `sh`. Only applies to `cmd`; a `ref` uses the referenced executable's own interpreter.  | [ExecutableExecInterpreter](#executableexecinterpreter) |  |  |
-| `name` | A human-readable label for this step, used for display purposes. | `string` |  |  |
-| `ref` | A reference to another executable to run in serial. One of `cmd` or `ref` must be set.  | [ExecutableRef](#executableref) |  |  |
-| `retries` | The number of times to retry the executable if it fails. | `integer` | 0 |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `args` | `array` (`string`) | [] |  | Arguments to pass to the executable. |
+| `cmd` | `string` |  |  | The command to execute. One of `cmd` or `ref` must be set.  |
+| `if` | `string` |  |  | An expression that determines whether the executable should run, using the Expr language syntax. The expression is evaluated at runtime and must resolve to a boolean value.  The expression has access to OS/architecture information (os, arch), environment variables (env), stored data (store), and context information (ctx) like workspace and paths.  For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists in the store, and `env["CI"] == "true"` will run in CI environments. See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.  |
+| `interpreter` | [ExecutableExecInterpreter](#executableexecinterpreter) |  |  | The interpreter used to run `cmd` for this step. Defaults to `sh`. Only applies to `cmd`; a `ref` uses the referenced executable's own interpreter.  |
+| `name` | `string` |  |  | A human-readable label for this step, used for display purposes. |
+| `ref` | [ExecutableRef](#executableref) |  |  | A reference to another executable to run in serial. One of `cmd` or `ref` must be set.  |
+| `retries` | `integer` | 0 |  | The number of times to retry the executable if it fails. |
 
 ### ExecutableParallelRefConfigList
 
 A list of executables to run in parallel. The executables can be defined by it's exec `cmd` or `ref`.
 
-
 **Type:** `array` ([ExecutableParallelRefConfig](#executableparallelrefconfig))
 
-
-
-
 ### ExecutableParameter
 
 A parameter is a value that can be passed to an executable and all of its sub-executables.
 Only one of `text`, `secretRef`, `prompt`, or `file` must be set. Specifying more than one will result in an error.
 
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `envFile` | A path to a file containing environment variables to be passed to the executable. The file should contain one variable per line in the format `KEY=VALUE`.  | `string` |  |  |
-| `envKey` | The name of the environment variable that will be assigned the value.  When specified with `envFile`, only the environment variable with this name will be set.  | `string` |  |  |
-| `outputFile` | A path where the parameter value will be temporarily written to disk. The file will be created before execution and cleaned up afterwards.  | `string` |  |  |
-| `prompt` | A prompt to be displayed to the user when collecting an input value. | `string` |  |  |
-| `secretRef` | A reference to a secret to be passed to the executable. | `string` |  |  |
-| `text` | A static value to be passed to the executable. | `string` |  |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `envFile` | `string` |  |  | A path to a file containing environment variables to be passed to the executable. The file should contain one variable per line in the format `KEY=VALUE`.  |
+| `envKey` | `string` |  |  | The name of the environment variable that will be assigned the value.  When specified with `envFile`, only the environment variable with this name will be set.  |
+| `outputFile` | `string` |  |  | A path where the parameter value will be temporarily written to disk. The file will be created before execution and cleaned up afterwards.  |
+| `prompt` | `string` |  |  | A prompt to be displayed to the user when collecting an input value. |
+| `secretRef` | `string` |  |  | A reference to a secret to be passed to the executable. |
+| `text` | `string` |  |  | A static value to be passed to the executable. |
 
 ### ExecutableParameterList
 
-
-
 **Type:** `array` ([ExecutableParameter](#executableparameter))
 
-
-
-
 ### ExecutableRef
 
 A reference to an executable.
@@ -335,119 +240,86 @@ For example, `exec ws/ns:my-workflow`.
 - If the namespace is not specified, the current namespace will be used.
 - Excluding the name will reference the executable with a matching verb but an unspecified name and namespace (e.g. `exec ws` or simply `exec`).
 
-
 **Type:** `string`
 
-
-
-
 ### ExecutableRenderExecutableType
 
 Renders a markdown template file with data.
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `args` |  | [ExecutableArgumentList](#executableargumentlist) |  |  |
-| `dir` |  | [ExecutableDirectory](#executabledirectory) |  |  |
-| `params` |  | [ExecutableParameterList](#executableparameterlist) |  |  |
-| `templateDataFile` | The path to the JSON or YAML file containing the template data. | `string` |  |  |
-| `templateFile` | The path to the markdown template file to render. | `string` |  |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `args` | [ExecutableArgumentList](#executableargumentlist) |  |  |  |
+| `dir` | [ExecutableDirectory](#executabledirectory) |  |  |  |
+| `params` | [ExecutableParameterList](#executableparameterlist) |  |  |  |
+| `templateDataFile` | `string` |  |  | The path to the JSON or YAML file containing the template data. |
+| `templateFile` | `string` |  |  | The path to the markdown template file to render. |
 
 ### ExecutableRequestExecutableType
 
 Makes an HTTP request.
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `args` |  | [ExecutableArgumentList](#executableargumentlist) |  |  |
-| `body` | The body of the request. | `string` |  |  |
-| `headers` | A map of headers to include in the request. | `map` (`string` -> `string`) | map[] |  |
-| `logResponse` | If set to true, the response will be logged as program output. | `boolean` | false |  |
-| `method` | The HTTP method to use when making the request. | `string` | GET |  |
-| `params` |  | [ExecutableParameterList](#executableparameterlist) |  |  |
-| `responseFile` |  | [ExecutableRequestResponseFile](#executablerequestresponsefile) |  |  |
-| `timeout` | The timeout for the request in Go duration format (e.g. 30s, 5m, 1h). | `string` | 30m0s |  |
-| `transformResponse` | [Expr](https://expr-lang.org/docs/language-definition) expression used to transform the response before saving it to a file or outputting it.  The following variables are available in the expression:   - `status`: The response status string.   - `code`: The response status code.   - `body`: The response body.   - `headers`: The response headers.  For example, to capitalize a JSON body field's value, you can use `upper(fromJSON(body)["field"])`.  | `string` |  |  |
-| `url` | The URL to make the request to. | `string` |  | ✘ |
-| `validStatusCodes` | A list of valid status codes. If the response status code is not in this list, the executable will fail. If not set, the response status code will not be checked.  | `array` (`integer`) | [] |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `args` | [ExecutableArgumentList](#executableargumentlist) |  |  |  |
+| `body` | `string` |  |  | The body of the request. |
+| `headers` | `map` (`string` -> `string`) | map[] |  | A map of headers to include in the request. |
+| `logResponse` | `boolean` | false |  | If set to true, the response will be logged as program output. |
+| `method` | `string` | GET |  | The HTTP method to use when making the request. |
+| `params` | [ExecutableParameterList](#executableparameterlist) |  |  |  |
+| `responseFile` | [ExecutableRequestResponseFile](#executablerequestresponsefile) |  |  |  |
+| `timeout` | `string` | 30m0s |  | The timeout for the request in Go duration format (e.g. 30s, 5m, 1h). |
+| `transformResponse` | `string` |  |  | [Expr](https://expr-lang.org/docs/language-definition) expression used to transform the response before saving it to a file or outputting it.  The following variables are available in the expression:   - `status`: The response status string.   - `code`: The response status code.   - `body`: The response body.   - `headers`: The response headers.  For example, to capitalize a JSON body field's value, you can use `upper(fromJSON(body)["field"])`.  |
+| `url` | `string` |  | Yes | The URL to make the request to. |
+| `validStatusCodes` | `array` (`integer`) | [] |  | A list of valid status codes. If the response status code is not in this list, the executable will fail. If not set, the response status code will not be checked.  |
 
 ### ExecutableRequestResponseFile
 
 Configuration for saving the response of a request to a file.
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `dir` |  | [ExecutableDirectory](#executabledirectory) |  |  |
-| `filename` | The name of the file to save the response to. | `string` |  | ✘ |
-| `saveAs` | The format to save the response as. | `string` | raw |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `dir` | [ExecutableDirectory](#executabledirectory) |  |  |  |
+| `filename` | `string` |  | Yes | The name of the file to save the response to. |
+| `saveAs` | `string` | raw |  | The format to save the response as. |
 
 ### ExecutableSerialExecutableType
 
 Executes a list of executables in serial.
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `args` |  | [ExecutableArgumentList](#executableargumentlist) |  |  |
-| `dir` |  | [ExecutableDirectory](#executabledirectory) |  |  |
-| `execs` | A list of executables to run in serial. Each executable can be a command or a reference to another executable.  | [ExecutableSerialRefConfigList](#executableserialrefconfiglist) |  | ✘ |
-| `failFast` | End the serial execution as soon as an exec exits with a non-zero status. This is the default behavior. When set to false, all execs will be run regardless of the exit status of the previous exec.  | `boolean` |  |  |
-| `params` |  | [ExecutableParameterList](#executableparameterlist) |  |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `args` | [ExecutableArgumentList](#executableargumentlist) |  |  |  |
+| `dir` | [ExecutableDirectory](#executabledirectory) |  |  |  |
+| `execs` | [ExecutableSerialRefConfigList](#executableserialrefconfiglist) |  | Yes | A list of executables to run in serial. Each executable can be a command or a reference to another executable.  |
+| `failFast` | `boolean` |  |  | End the serial execution as soon as an exec exits with a non-zero status. This is the default behavior. When set to false, all execs will be run regardless of the exit status of the previous exec.  |
+| `params` | [ExecutableParameterList](#executableparameterlist) |  |  |  |
 
 ### ExecutableSerialRefConfig
 
 Configuration for a serial executable.
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `args` | Arguments to pass to the executable. | `array` (`string`) | [] |  |
-| `cmd` | The command to execute. One of `cmd` or `ref` must be set.  | `string` |  |  |
-| `if` | An expression that determines whether the executable should run, using the Expr language syntax. The expression is evaluated at runtime and must resolve to a boolean value.  The expression has access to OS/architecture information (os, arch), environment variables (env), stored data (store), and context information (ctx) like workspace and paths.  For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists in the store, and `env["CI"] == "true"` will run in CI environments. See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.  | `string` |  |  |
-| `interpreter` | The interpreter used to run `cmd` for this step. Defaults to `sh`. Only applies to `cmd`; a `ref` uses the referenced executable's own interpreter.  | [ExecutableExecInterpreter](#executableexecinterpreter) |  |  |
-| `name` | A human-readable label for this step, used for display purposes. | `string` |  |  |
-| `ref` | A reference to another executable to run in serial. One of `cmd` or `ref` must be set.  | [ExecutableRef](#executableref) |  |  |
-| `retries` | The number of times to retry the executable if it fails. | `integer` | 0 |  |
-| `reviewRequired` | If set to true, the user will be prompted to review the output of the executable before continuing. | `boolean` | false |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `args` | `array` (`string`) | [] |  | Arguments to pass to the executable. |
+| `cmd` | `string` |  |  | The command to execute. One of `cmd` or `ref` must be set.  |
+| `if` | `string` |  |  | An expression that determines whether the executable should run, using the Expr language syntax. The expression is evaluated at runtime and must resolve to a boolean value.  The expression has access to OS/architecture information (os, arch), environment variables (env), stored data (store), and context information (ctx) like workspace and paths.  For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists in the store, and `env["CI"] == "true"` will run in CI environments. See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.  |
+| `interpreter` | [ExecutableExecInterpreter](#executableexecinterpreter) |  |  | The interpreter used to run `cmd` for this step. Defaults to `sh`. Only applies to `cmd`; a `ref` uses the referenced executable's own interpreter.  |
+| `name` | `string` |  |  | A human-readable label for this step, used for display purposes. |
+| `ref` | [ExecutableRef](#executableref) |  |  | A reference to another executable to run in serial. One of `cmd` or `ref` must be set.  |
+| `retries` | `integer` | 0 |  | The number of times to retry the executable if it fails. |
+| `reviewRequired` | `boolean` | false |  | If set to true, the user will be prompted to review the output of the executable before continuing. |
 
 ### ExecutableSerialRefConfigList
 
 A list of executables to run in serial. The executables can be defined by it's exec `cmd` or `ref`.
 
-
 **Type:** `array` ([ExecutableSerialRefConfig](#executableserialrefconfig))
 
-
-
-
 ### ExecutableVerb
 
 Keywords that describe the action an executable performs. Executables are configured with a single verb,
@@ -478,164 +350,17 @@ to use the verb that best describes the action they are performing.
 By providing minimal aliasing with comprehensive verb coverage, flow enables natural language operations
 while maintaining simplicity and flexibility for diverse development and operations workflows.
 
-
-**Type:** `string`
-**Default:** `exec`
-**Valid values:**
-- `abort`
-- `activate`
-- `add`
-- `analyze`
-- `apply`
-- `archive`
-- `audit`
-- `backup`
-- `benchmark`
-- `build`
-- `bundle`
-- `check`
-- `clean`
-- `clear`
-- `commit`
-- `compile`
-- `compress`
-- `configure`
-- `connect`
-- `copy`
-- `create`
-- `deactivate`
-- `debug`
-- `decompress`
-- `decrypt`
-- `delete`
-- `deploy`
-- `destroy`
-- `disable`
-- `disconnect`
-- `edit`
-- `enable`
-- `encrypt`
-- `erase`
-- `exec`
-- `execute`
-- `export`
-- `expose`
-- `fetch`
-- `fix`
-- `flush`
-- `format`
-- `generate`
-- `get`
-- `import`
-- `index`
-- `init`
-- `inspect`
-- `install`
-- `join`
-- `kill`
-- `launch`
-- `lint`
-- `list`
-- `load`
-- `lock`
-- `login`
-- `logout`
-- `manage`
-- `merge`
-- `migrate`
-- `modify`
-- `monitor`
-- `mount`
-- `new`
-- `notify`
-- `open`
-- `package`
-- `partition`
-- `patch`
-- `pause`
-- `ping`
-- `preload`
-- `prefetch`
-- `profile`
-- `provision`
-- `publish`
-- `purge`
-- `push`
-- `queue`
-- `reboot`
-- `recover`
-- `refresh`
-- `release`
-- `reload`
-- `remove`
-- `request`
-- `reset`
-- `restart`
-- `restore`
-- `retrieve`
-- `rollback`
-- `run`
-- `save`
-- `scale`
-- `scan`
-- `schedule`
-- `seed`
-- `send`
-- `serve`
-- `set`
-- `setup`
-- `show`
-- `snapshot`
-- `start`
-- `stash`
-- `stop`
-- `tag`
-- `teardown`
-- `terminate`
-- `test`
-- `tidy`
-- `trace`
-- `transform`
-- `trigger`
-- `tunnel`
-- `undeploy`
-- `uninstall`
-- `unmount`
-- `unset`
-- `update`
-- `upgrade`
-- `validate`
-- `verify`
-- `view`
-- `watch`
-
-
+**Type:** `string` &middot; **Default:** `exec`
+**Valid values:** `abort`, `activate`, `add`, `analyze`, `apply`, `archive`, `audit`, `backup`, `benchmark`, `build`, `bundle`, `check`, `clean`, `clear`, `commit`, `compile`, `compress`, `configure`, `connect`, `copy`, `create`, `deactivate`, `debug`, `decompress`, `decrypt`, `delete`, `deploy`, `destroy`, `disable`, `disconnect`, `edit`, `enable`, `encrypt`, `erase`, `exec`, `execute`, `export`, `expose`, `fetch`, `fix`, `flush`, `format`, `generate`, `get`, `import`, `index`, `init`, `inspect`, `install`, `join`, `kill`, `launch`, `lint`, `list`, `load`, `lock`, `login`, `logout`, `manage`, `merge`, `migrate`, `modify`, `monitor`, `mount`, `new`, `notify`, `open`, `package`, `partition`, `patch`, `pause`, `ping`, `preload`, `prefetch`, `profile`, `provision`, `publish`, `purge`, `push`, `queue`, `reboot`, `recover`, `refresh`, `release`, `reload`, `remove`, `request`, `reset`, `restart`, `restore`, `retrieve`, `rollback`, `run`, `save`, `scale`, `scan`, `schedule`, `seed`, `send`, `serve`, `set`, `setup`, `show`, `snapshot`, `start`, `stash`, `stop`, `tag`, `teardown`, `terminate`, `test`, `tidy`, `trace`, `transform`, `trigger`, `tunnel`, `undeploy`, `uninstall`, `unmount`, `unset`, `update`, `upgrade`, `validate`, `verify`, `view`, `watch`
 
 ### Imports
 
 A list of script files (`.sh`, `.bat`, `.cmd`, `.ps1`) to convert into generated executables in the file's executable group.
-
 **Type:** `array` (`string`)
 
-
-
-
 ### Ref
 
 
-
-
-
-
-
-
 ### Verb
 
 
-
-
-
-
-
-
-
diff --git a/docs/types/index.md b/docs/types/index.md
index c5c36b69..65c3ce1d 100644
--- a/docs/types/index.md
+++ b/docs/types/index.md
@@ -1,21 +1,32 @@
 ---
-title: flow YAML Configurations
+title: Configuration Reference
 ---
 
-# flow YAML Configurations
+# Configuration Reference
 
-- [FlowFile](flowfile.md)
-- [Template](template.md)
-- [Workspace](workspace.md)
-- [Config](config.md)
+flow reads four kinds of YAML file. Every one of them has a published JSON schema, so your editor
+can validate and autocomplete it as you type — see [Editor setup](#editor-setup) below.
 
-## IDE Integration <!-- {docsify-ignore} -->
+<CardGrid>
+  <Card icon="file" title="Flow File" :stack="['*.flow', '*.flow.yaml', '*.flow.yml']" href="/types/flowfile" href-text="Reference" alt-href="/guides/executables" alt-href-text="Guide">
+    A group of executables with shared metadata. This is the file you write most often — a workspace can hold as many as you like, anywhere in its tree.
+  </Card>
+  <Card icon="folder" title="Workspace" :stack="['flow.yaml']" href="/types/workspace" href-text="Reference" alt-href="/guides/workspaces" alt-href-text="Guide">
+    Marks a directory as a workspace and sets what applies across it: display name, tags, environment files, and which paths are searched for executables.
+  </Card>
+  <Card icon="box" title="Template" :stack="['*.flow.tmpl']" href="/types/template" href-text="Reference" alt-href="/guides/templating" alt-href-text="Guide">
+    A form plus a flow file to render from it, with files to copy and executables to run before and after generating.
+  </Card>
+  <Card icon="terminal" title="Config" :stack="['~/.flow/config.yaml']" href="/types/config" href-text="Reference" alt-href="/cli/flow_config" alt-href-text="CLI">
+    Your machine-level settings: the current workspace and namespace, registered workspaces, theme, log mode, and timeouts.
+  </Card>
+</CardGrid>
 
-All flow configuration files have YAML schemas available for intelligent suggestions and validation in your IDE.
+## Editor setup
 
-### Enable Schema Validation <!-- {docsify-ignore} -->
-
-Add this comment to the top of your flow files:
+Point a schema-aware editor at the published schema with a `yaml-language-server` comment on the
+first line, and you get completion, hover docs, and inline validation with no plugin beyond a YAML
+extension:
 
 ```yaml
 # yaml-language-server: $schema=https://flowexec.io/schemas/flowfile_schema.json
@@ -27,16 +38,16 @@ executables:
       cmd: echo "Hello, world!"
 ```
 
-### Available Schemas <!-- {docsify-ignore} -->
-
-- **FlowFile**: `https://flowexec.io/schemas/flowfile_schema.json`
-- **Template**: `https://flowexec.io/schemas/template_schema.json`
-- **Workspace**: `https://flowexec.io/schemas/workspace_schema.json`
-- **Config**: `https://flowexec.io/schemas/config_schema.json`
+| File | Schema |
+|------|--------|
+| `*.flow`, `*.flow.yaml`, `*.flow.yml` | [flowfile_schema.json](https://flowexec.io/schemas/flowfile_schema.json) |
+| `flow.yaml` | [workspace_schema.json](https://flowexec.io/schemas/workspace_schema.json) |
+| `*.flow.tmpl` | [template_schema.json](https://flowexec.io/schemas/template_schema.json) |
+| `config.yaml` | [config_schema.json](https://flowexec.io/schemas/config_schema.json) |
 
-### IDE Setup <!-- {docsify-ignore} -->
+### Associating the file extensions
 
-**VS Code**: Install the YAML extension and configure file associations:
+`*.flow` files are YAML, but editors do not know that from the extension alone. In VS Code:
 
 ```json
 // settings.json
@@ -49,4 +60,8 @@ executables:
 }
 ```
 
-**Other IDEs**: Configure your IDE to treat `*.flow`, `*.flow.yaml`, and `*.flow.yml` files as YAML files.
+Other editors need the equivalent mapping of `*.flow`, `*.flow.yaml`, and `*.flow.yml` to YAML.
+
+> [!TIP]
+> `flow schema validate` checks files from the command line, so the same validation runs in CI
+> without an editor. See [flow schema](/cli/flow_schema).
diff --git a/docs/types/template.md b/docs/types/template.md
index 2d00956f..9742f4cc 100644
--- a/docs/types/template.md
+++ b/docs/types/template.md
@@ -1,5 +1,6 @@
 ---
 title: Template
+description: "Configuration for a flowfile template; templates can be used to generate flow files."
 ---
 
 <!-- (Documentation autogenerated by docsgen. Do not edit directly.) -->
@@ -10,21 +11,15 @@ Configuration for a flowfile template; templates can be used to generate flow fi
 
 ## Properties
 
-**Required:**
-- `template`
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `annotations` |  | [CommonAnnotations](#commonannotations) | map[] |  |
-| `artifacts` | A list of artifacts to be copied after generating the flow file. | `array` ([Artifact](#artifact)) |  |  |
-| `description` | A description of the template. This is used to describe what the template generates and when to reach for it, and is shown when browsing templates.  | `string` |  |  |
-| `form` | Form fields to be displayed to the user when generating a flow file from a template.  The form will be rendered first, and the user's input can be used to render the template.  | `array` ([Field](#field)) | [] |  |
-| `postRun` | A list of exec executables to run after generating the flow file. | `array` ([TemplateRefConfig](#templaterefconfig)) |  |  |
-| `preRun` | A list of exec executables to run before generating the flow file. | `array` ([TemplateRefConfig](#templaterefconfig)) |  |  |
-| `template` | The flow file template to generate. The template must be a valid flow file after rendering. | `string` |  |  |
-
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `annotations` | [CommonAnnotations](#commonannotations) | map[] |  |  |
+| `artifacts` | `array` ([Artifact](#artifact)) |  |  | A list of artifacts to be copied after generating the flow file. |
+| `description` | `string` |  |  | A description of the template. This is used to describe what the template generates and when to reach for it, and is shown when browsing templates.  |
+| `form` | `array` ([Field](#field)) | [] |  | Form fields to be displayed to the user when generating a flow file from a template.  The form will be rendered first, and the user's input can be used to render the template.  |
+| `postRun` | `array` ([TemplateRefConfig](#templaterefconfig)) |  |  | A list of exec executables to run after generating the flow file. |
+| `preRun` | `array` ([TemplateRefConfig](#templaterefconfig)) |  |  | A list of exec executables to run before generating the flow file. |
+| `template` | `string` |  | Yes | The flow file template to generate. The template must be a valid flow file after rendering. |
 
 ## Definitions
 
@@ -33,21 +28,16 @@ Configuration for a flowfile template; templates can be used to generate flow fi
 File source and destination configuration.
 Go templating from form data is supported in all fields.
 
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `asTemplate` | If true, the artifact will be copied as a template file. The file will be rendered using Go templating from  the form data. [Expr language functions](https://expr-lang.org/docs/language-definition) are available for use in the template.  | `boolean` | false |  |
-| `dstDir` | The directory to copy the file to. If not set, the file will be copied to the root of the flow file directory. The directory will be created if it does not exist.  | `string` |  |  |
-| `dstName` | The name of the file to copy to. If not set, the file will be copied with the same name. | `string` |  |  |
-| `if` | An expression that determines whether the the artifact should be copied, using the Expr language syntax.  The expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met,  the artifact will not be copied.  The expression has access to OS/architecture information (os, arch), environment variables (env), form input  (form), and context information (name, workspace, directory, etc.).  See the [flow documentation](https://flowexec.io/guide/templating) for more information.  | `string` |  |  |
-| `srcDir` | The directory to copy the file from.  If not set, the file will be copied from the directory of the template file.  | `string` |  |  |
-| `srcName` | The name of the file to copy. | `string` |  |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `asTemplate` | `boolean` | false |  | If true, the artifact will be copied as a template file. The file will be rendered using Go templating from  the form data. [Expr language functions](https://expr-lang.org/docs/language-definition) are available for use in the template.  |
+| `dstDir` | `string` |  |  | The directory to copy the file to. If not set, the file will be copied to the root of the flow file directory. The directory will be created if it does not exist.  |
+| `dstName` | `string` |  |  | The name of the file to copy to. If not set, the file will be copied with the same name. |
+| `if` | `string` |  |  | An expression that determines whether the the artifact should be copied, using the Expr language syntax.  The expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met,  the artifact will not be copied.  The expression has access to OS/architecture information (os, arch), environment variables (env), form input  (form), and context information (name, workspace, directory, etc.).  See the [flow documentation](https://flowexec.io/guide/templating) for more information.  |
+| `srcDir` | `string` |  |  | The directory to copy the file from.  If not set, the file will be copied from the directory of the template file.  |
+| `srcName` | `string` |  |  | The name of the file to copy. |
 
 ### CommonAnnotations
 
@@ -58,12 +48,8 @@ filtering or display in the Flow UI - treat them as opaque state.
 Keys should be namespaced (e.g. `my-tool.example.com/state`) to avoid
 collisions between tools.
 
-
 **Type:** `map` (`string` -> `string`)
 
-
-
-
 ### ExecutableRef
 
 A reference to an executable.
@@ -74,48 +60,33 @@ For example, `exec ws/ns:my-workflow`.
 - If the namespace is not specified, the current namespace will be used.
 - Excluding the name will reference the executable with a matching verb but an unspecified name and namespace (e.g. `exec ws` or simply `exec`).
 
-
 **Type:** `string`
 
-
-
-
 ### Field
 
 A field to be displayed to the user when generating a flow file from a template.
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `default` | The default value to use if a value is not set. | `string` |  |  |
-| `description` | A description of the field. | `string` |  |  |
-| `group` | The group to display the field in. Fields with the same group will be displayed together. | `integer` | 0 |  |
-| `key` | The key to associate the data with. This is used as the key in the template data map. | `string` |  | ✘ |
-| `prompt` | A prompt to be displayed to the user when collecting an input value. | `string` |  | ✘ |
-| `required` | If true, a value must be set. If false, the default value will be used if a value is not set. | `boolean` | false |  |
-| `type` | The type of input field to display. | `string` | text |  |
-| `validate` | A regular expression to validate the input value against. | `string` |  |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `default` | `string` |  |  | The default value to use if a value is not set. |
+| `description` | `string` |  |  | A description of the field. |
+| `group` | `integer` | 0 |  | The group to display the field in. Fields with the same group will be displayed together. |
+| `key` | `string` |  | Yes | The key to associate the data with. This is used as the key in the template data map. |
+| `prompt` | `string` |  | Yes | A prompt to be displayed to the user when collecting an input value. |
+| `required` | `boolean` | false |  | If true, a value must be set. If false, the default value will be used if a value is not set. |
+| `type` | `string` | text |  | The type of input field to display. |
+| `validate` | `string` |  |  | A regular expression to validate the input value against. |
 
 ### TemplateRefConfig
 
 Configuration for a template executable.
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `args` | Arguments to pass to the executable. | `array` (`string`) | [] |  |
-| `cmd` | The command to execute. One of `cmd` or `ref` must be set.  | `string` |  |  |
-| `if` | An expression that determines whether the executable should be run, using the Expr language syntax.  The expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met,  the executable will be skipped.  The expression has access to OS/architecture information (os, arch), environment variables (env), form input  (form), and context information (name, workspace, directory, etc.).  See the [flow documentation](https://flowexec.io/guide/templating) for more information.  | `string` |  |  |
-| `ref` | A reference to another executable to run in serial. One of `cmd` or `ref` must be set.  | [ExecutableRef](#executableref) |  |  |
-
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `args` | `array` (`string`) | [] |  | Arguments to pass to the executable. |
+| `cmd` | `string` |  |  | The command to execute. One of `cmd` or `ref` must be set.  |
+| `if` | `string` |  |  | An expression that determines whether the executable should be run, using the Expr language syntax.  The expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met,  the executable will be skipped.  The expression has access to OS/architecture information (os, arch), environment variables (env), form input  (form), and context information (name, workspace, directory, etc.).  See the [flow documentation](https://flowexec.io/guide/templating) for more information.  |
+| `ref` | [ExecutableRef](#executableref) |  |  | A reference to another executable to run in serial. One of `cmd` or `ref` must be set.  |
 
diff --git a/docs/types/workspace.md b/docs/types/workspace.md
index 6c30a4bc..1f9a2736 100644
--- a/docs/types/workspace.md
+++ b/docs/types/workspace.md
@@ -1,5 +1,6 @@
 ---
 title: Workspace
+description: "Configuration for a workspace in the Flow CLI. This configuration is used to define the settings for a workspace. Every workspace has a workspace config file named `flow.yaml` in…"
 ---
 
 <!-- (Documentation autogenerated by docsgen. Do not edit directly.) -->
@@ -13,24 +14,20 @@ Every workspace has a workspace config file named `flow.yaml` in the root of the
 
 ## Properties
 
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `annotations` |  | [CommonAnnotations](#commonannotations) | map[] |  |
-| `description` | A description of the workspace. This description is rendered as markdown in the interactive UI. | `string` |  |  |
-| `descriptionFile` | A path to a markdown file that contains the description of the workspace. | `string` |  |  |
-| `displayName` | The display name of the workspace. This is used in the interactive UI. | `string` |  |  |
-| `envFiles` | A list of environment variable files to load for the workspace. These files should contain key-value pairs of environment variables. By default, the `.env` file in the workspace root is loaded if it exists.  | `array` (`string`) | [] |  |
-| `executables` |  | [ExecutableFilter](#executablefilter) |  |  |
-| `gitRef` | The git ref (branch or tag name) that was specified when the workspace was added from a git URL. Used by `flow workspace update` to checkout the correct ref after pulling.  | `string` |  |  |
-| `gitRefType` | The type of git ref specified when the workspace was added. Either "branch" or "tag". Empty if no ref was specified.  | `string` |  |  |
-| `gitRemote` | The git remote URL for the workspace. This is set automatically when a workspace is added from a git URL. Used by `flow workspace update` to pull the latest changes.  | `string` |  |  |
-| `tags` |  | [CommonTags](#commontags) | [] |  |
-| `templates` | Filters controlling which flowfile template files (*.flow.tmpl) are auto-discovered within the workspace during `flow sync`. Uses the same include/exclude semantics as the executables filter. When unset, the entire workspace is scanned (minus the default exclusions like node_modules/, vendor/, and .git/).  | [ExecutableFilter](#executablefilter) |  |  |
-| `verbAliases` |  | [VerbAliases](#verbaliases) |  |  |
-
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `annotations` | [CommonAnnotations](#commonannotations) | map[] |  |  |
+| `description` | `string` |  |  | A description of the workspace. This description is rendered as markdown in the interactive UI. |
+| `descriptionFile` | `string` |  |  | A path to a markdown file that contains the description of the workspace. |
+| `displayName` | `string` |  |  | The display name of the workspace. This is used in the interactive UI. |
+| `envFiles` | `array` (`string`) | [] |  | A list of environment variable files to load for the workspace. These files should contain key-value pairs of environment variables. By default, the `.env` file in the workspace root is loaded if it exists.  |
+| `executables` | [ExecutableFilter](#executablefilter) |  |  |  |
+| `gitRef` | `string` |  |  | The git ref (branch or tag name) that was specified when the workspace was added from a git URL. Used by `flow workspace update` to checkout the correct ref after pulling.  |
+| `gitRefType` | `string` |  |  | The type of git ref specified when the workspace was added. Either "branch" or "tag". Empty if no ref was specified.  |
+| `gitRemote` | `string` |  |  | The git remote URL for the workspace. This is set automatically when a workspace is added from a git URL. Used by `flow workspace update` to pull the latest changes.  |
+| `tags` | [CommonTags](#commontags) | [] |  |  |
+| `templates` | [ExecutableFilter](#executablefilter) |  |  | Filters controlling which flowfile template files (*.flow.tmpl) are auto-discovered within the workspace during `flow sync`. Uses the same include/exclude semantics as the executables filter. When unset, the entire workspace is scanned (minus the default exclusions like node_modules/, vendor/, and .git/).  |
+| `verbAliases` | [VerbAliases](#verbaliases) |  |  |  |
 
 ## Definitions
 
@@ -43,37 +40,23 @@ filtering or display in the Flow UI - treat them as opaque state.
 Keys should be namespaced (e.g. `my-tool.example.com/state`) to avoid
 collisions between tools.
 
-
 **Type:** `map` (`string` -> `string`)
 
-
-
-
 ### CommonTags
 
 A list of tags.
 Tags can be used with list commands to filter returned data.
 
-
 **Type:** `array` (`string`)
 
-
-
-
 ### ExecutableFilter
 
-
-
 **Type:** `object`
 
-
-
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
-| `excluded` | A list of directories or file patterns to exclude from the executable search. Supports directory paths (e.g., "node_modules/", "vendor/") and glob patterns for filenames (e.g., "*.js.flow", "*temp*"). Common exclusions like node_modules/, vendor/, third_party/, external/, and *.js.flow are excluded by default.  | `array` (`string`) | [] |  |
-| `included` | A list of directories or file patterns to include in the executable search. Supports directory paths (e.g., "src/", "scripts/") and glob patterns for filenames (e.g., "*.test.flow", "example*").  | `array` (`string`) | [] |  |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
+| `excluded` | `array` (`string`) | [] |  | A list of directories or file patterns to exclude from the executable search. Supports directory paths (e.g., "node_modules/", "vendor/") and glob patterns for filenames (e.g., "*.js.flow", "*temp*"). Common exclusions like node_modules/, vendor/, third_party/, external/, and *.js.flow are excluded by default.  |
+| `included` | `array` (`string`) | [] |  | A list of directories or file patterns to include in the executable search. Supports directory paths (e.g., "src/", "scripts/") and glob patterns for filenames (e.g., "*.test.flow", "example*").  |
 
 ### VerbAliases
 
@@ -82,10 +65,5 @@ Setting this will override all of the default flow command aliases. The verbs an
 
 If set to an empty object, verb aliases will be disabled.
 
-
 **Type:** `map` (`string` -> `array` (`string`))
 
-
-
-
-
diff --git a/tools/docsgen/cli.go b/tools/docsgen/cli.go
new file mode 100644
index 00000000..4685aed7
--- /dev/null
+++ b/tools/docsgen/cli.go
@@ -0,0 +1,274 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// Cobra's markdown is a flat dump: the command name is an h2 rather than a page
+// title, every fenced block is untagged so nothing highlights, and the flag
+// listings are fixed-width columns that overflow the site's content column and
+// clip their own descriptions. polishCLIDocs rewrites the generated files into
+// the same shape as the hand-written guides.
+//
+// It is deliberately conservative — anything it cannot parse is left as a code
+// block rather than mangled into a broken table.
+
+var (
+	// Matches the leading `-x, --name` (or just `--name`) of a flag usage line.
+	// Everything after it is the value placeholder and the description.
+	flagHeadRe = regexp.MustCompile(`^\s+(?:-([a-zA-Z]), )?--([a-zA-Z0-9-]+)`)
+	// Cobra aligns descriptions into a column, so two or more spaces separate
+	// the placeholder from the description. A single space cannot be used: a
+	// placeholder taken from backticks in the usage string may itself contain
+	// one (e.g. `--spec flow logs`).
+	columnGapRe = regexp.MustCompile(`\s{2,}`)
+)
+
+type flagDoc struct {
+	short string
+	name  string
+	value string
+	desc  string
+}
+
+func polishCLIDocs(dir string) error {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return err
+	}
+	for _, entry := range entries {
+		if entry.IsDir() || filepath.Ext(entry.Name()) != ".md" {
+			continue
+		}
+		// index.md is hand-maintained, not emitted by GenMarkdownTree.
+		if entry.Name() == "index.md" {
+			continue
+		}
+		path := filepath.Join(dir, entry.Name())
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		polished, ok := polishCLIDoc(string(raw))
+		if !ok {
+			continue
+		}
+		if err := os.WriteFile(path, []byte(polished), 0o600); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func polishCLIDoc(src string) (string, bool) {
+	lines := strings.Split(strings.ReplaceAll(src, "\r\n", "\n"), "\n")
+
+	var (
+		out     []string
+		title   string
+		section string
+		i       int
+	)
+
+	for ; i < len(lines); i++ {
+		if rest, ok := strings.CutPrefix(lines[i], "## "); ok {
+			title = strings.TrimSpace(rest)
+			i++
+			break
+		}
+	}
+	if title == "" {
+		// Not a file this generator produced; leave it alone.
+		return "", false
+	}
+
+	out = append(out, "---", "title: "+title)
+	// Cobra puts the command's one-line summary directly under the heading; it
+	// doubles as the page's meta description.
+	if summary := leadParagraph(lines[i:]); summary != "" {
+		out = append(out, "description: "+yamlString(summary))
+	}
+	out = append(out, "---", "", "# "+title)
+
+	for ; i < len(lines); i++ {
+		line := lines[i]
+
+		switch {
+		case strings.HasPrefix(line, "### "):
+			section = strings.TrimSpace(line[len("### "):])
+			out = append(out, "## "+sectionHeading(section))
+
+		case strings.HasPrefix(strings.TrimSpace(line), "```"):
+			var body []string
+			for i++; i < len(lines) && strings.TrimSpace(lines[i]) != "```"; i++ {
+				body = append(body, lines[i])
+			}
+			out = append(out, renderBlock(section, body)...)
+
+		case section == "SEE ALSO" && strings.HasPrefix(line, "* "):
+			out = append(out, seeAlsoItem(line))
+
+		default:
+			out = append(out, line)
+		}
+	}
+
+	return strings.TrimRight(strings.Join(out, "\n"), "\n") + "\n", true
+}
+
+// leadParagraph returns the first line of prose before any heading or code
+// block, which for a Cobra page is the command's short description.
+func leadParagraph(lines []string) string {
+	for _, line := range lines {
+		t := strings.TrimSpace(line)
+		if t == "" {
+			continue
+		}
+		if strings.HasPrefix(t, "#") || strings.HasPrefix(t, "```") {
+			return ""
+		}
+		return t
+	}
+	return ""
+}
+
+func sectionHeading(section string) string {
+	if section == "SEE ALSO" {
+		return "See also"
+	}
+	return section
+}
+
+func isFlagSection(section string) bool {
+	return strings.HasPrefix(section, "Options")
+}
+
+func renderBlock(section string, body []string) []string {
+	if isFlagSection(section) {
+		if flags, ok := parseFlagBlock(body); ok {
+			return renderFlagTable(flags)
+		}
+	}
+	return fence("shell", dedent(trimBlankEdges(body)))
+}
+
+func fence(lang string, body []string) []string {
+	out := make([]string, 0, len(body)+2)
+	out = append(out, "```"+lang)
+	out = append(out, body...)
+	return append(out, "```")
+}
+
+func renderFlagTable(flags []flagDoc) []string {
+	out := []string{"| Flag | Type | Description |", "|------|------|-------------|"}
+	for _, f := range flags {
+		name := "--" + f.name
+		if f.short != "" {
+			name = "-" + f.short + ", " + name
+		}
+		value := ""
+		if f.value != "" {
+			value = "`" + f.value + "`"
+		}
+		out = append(out, "| `"+name+"` | "+value+" | "+escapeCell(f.desc)+" |")
+	}
+	return out
+}
+
+// parseFlagBlock turns Cobra's aligned flag usage listing into structured rows.
+// It reports false if any line fails to parse, so the caller can fall back to
+// rendering the block verbatim.
+func parseFlagBlock(body []string) ([]flagDoc, bool) {
+	var flags []flagDoc
+	for _, raw := range body {
+		line := strings.TrimRight(raw, " \t")
+		if strings.TrimSpace(line) == "" {
+			continue
+		}
+
+		m := flagHeadRe.FindStringSubmatchIndex(line)
+		if m == nil {
+			// A wrapped description continues the previous row.
+			if len(flags) == 0 {
+				return nil, false
+			}
+			flags[len(flags)-1].desc += " " + strings.TrimSpace(line)
+			continue
+		}
+
+		rest := line[m[1]:]
+		var value, desc string
+		if gap := columnGapRe.FindStringIndex(rest); gap != nil {
+			value = strings.TrimSpace(rest[:gap[0]])
+			desc = strings.TrimSpace(rest[gap[1]:])
+		} else {
+			value = strings.TrimSpace(rest)
+		}
+
+		flags = append(flags, flagDoc{
+			short: submatch(line, m, 1),
+			name:  submatch(line, m, 2),
+			value: value,
+			desc:  desc,
+		})
+	}
+	return flags, len(flags) > 0
+}
+
+func submatch(s string, m []int, group int) string {
+	lo, hi := m[2*group], m[2*group+1]
+	if lo < 0 {
+		return ""
+	}
+	return s[lo:hi]
+}
+
+func escapeCell(s string) string {
+	return strings.ReplaceAll(s, "|", `\|`)
+}
+
+// seeAlsoItem rewrites `* [flow](flow.md)\t - description` into a normal list
+// item; the tab is a Cobra artifact and renders as a stray gap.
+func seeAlsoItem(line string) string {
+	s := strings.Join(strings.Fields(strings.TrimPrefix(line, "* ")), " ")
+	return "- " + strings.Replace(s, ") - ", ") — ", 1)
+}
+
+func trimBlankEdges(body []string) []string {
+	start, end := 0, len(body)
+	for start < end && strings.TrimSpace(body[start]) == "" {
+		start++
+	}
+	for end > start && strings.TrimSpace(body[end-1]) == "" {
+		end--
+	}
+	return body[start:end]
+}
+
+func dedent(body []string) []string {
+	indent := -1
+	for _, line := range body {
+		if strings.TrimSpace(line) == "" {
+			continue
+		}
+		n := len(line) - len(strings.TrimLeft(line, " "))
+		if indent < 0 || n < indent {
+			indent = n
+		}
+	}
+	if indent <= 0 {
+		return body
+	}
+	out := make([]string, len(body))
+	for i, line := range body {
+		if len(line) >= indent {
+			out[i] = line[indent:]
+		} else {
+			out[i] = strings.TrimLeft(line, " ")
+		}
+	}
+	return out
+}
diff --git a/tools/docsgen/main.go b/tools/docsgen/main.go
index 60bc2f5f..995edd3b 100644
--- a/tools/docsgen/main.go
+++ b/tools/docsgen/main.go
@@ -27,7 +27,11 @@ func main() {
 	rootCmd := cli.BuildRootCommand(ctx)
 	cli.RegisterAllCommands(ctx, rootCmd)
 	rootCmd.DisableAutoGenTag = true
-	if err := doc.GenMarkdownTree(rootCmd, filepath.Join(rootDir(), DocsDir, cliDir)); err != nil {
+	cliOut := filepath.Join(rootDir(), DocsDir, cliDir)
+	if err := doc.GenMarkdownTree(rootCmd, cliOut); err != nil {
+		panic(err)
+	}
+	if err := polishCLIDocs(cliOut); err != nil {
 		panic(err)
 	}
 
diff --git a/tools/docsgen/markdown.go b/tools/docsgen/markdown.go
index 55c580ca..e2736e25 100644
--- a/tools/docsgen/markdown.go
+++ b/tools/docsgen/markdown.go
@@ -57,6 +57,7 @@ func generateMarkdownDocs() {
 					"OneLine":    removeNewlines,
 					"IsRequired": requiredStr,
 					"DefaultStr": defaultStr,
+					"YAMLStr":    yamlString,
 				}).
 				Parse(typeTemplate)
 			if err != nil {
@@ -152,7 +153,8 @@ func typeStr(s *schema.JSONSchema) string {
 func requiredStr(list []string, key schema.FieldKey) string {
 	for _, k := range list {
 		if strings.ToLower(k) == key.Lower() {
-			return "✘"
+			// A cross reads as "not required" to most people; say it plainly.
+			return "Yes"
 		}
 	}
 	return ""
@@ -162,6 +164,24 @@ func removeNewlines(s string) string {
 	return strings.ReplaceAll(s, "\n", " ")
 }
 
+// yamlString renders a double-quoted YAML scalar for use in frontmatter, capped
+// at roughly what a search result will show.
+func yamlString(s string) string {
+	s = strings.Join(strings.Fields(s), " ")
+	const maxLen = 180
+	if len(s) > maxLen {
+		if cut := strings.LastIndex(s[:maxLen], " "); cut > 0 {
+			s = s[:cut]
+		} else {
+			s = s[:maxLen]
+		}
+		s = strings.TrimRight(s, " .,;:") + "…"
+	}
+	s = strings.ReplaceAll(s, `\`, `\\`)
+	s = strings.ReplaceAll(s, `"`, `\"`)
+	return `"` + s + `"`
+}
+
 func defaultStr(val interface{}) string {
 	if val == nil {
 		return ""
diff --git a/tools/docsgen/type.md.tmpl b/tools/docsgen/type.md.tmpl
index 5b5239ab..742b99c3 100644
--- a/tools/docsgen/type.md.tmpl
+++ b/tools/docsgen/type.md.tmpl
@@ -1,5 +1,6 @@
 ---
 title: {{ .Title }}
+description: {{ YAMLStr .Description }}
 ---
 
 <!-- (Documentation autogenerated by docsgen. Do not edit directly.) -->
@@ -11,46 +12,30 @@ title: {{ .Title }}
 {{ if .Properties -}}
 ## Properties
 
-{{if .Required -}}
-**Required:**
-{{range .Required -}}
-- `{{ . }}`
-{{end}}
-{{- end}}
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
 {{ range $key, $prop := .Properties -}}
-| `{{$key.Lower}}` | {{OneLine $prop.Description}} | {{TypeStr $prop}} | {{DefaultStr $prop.Default}} | {{IsRequired .Required $key}} |
+| `{{$key.Lower}}` | {{TypeStr $prop}} | {{DefaultStr $prop.Default}} | {{IsRequired $.Required $key}} | {{OneLine $prop.Description}} |
 {{ end -}}
 {{end}}
-
 {{ if .Definitions -}}
 ## Definitions
 
 {{ range $key, $def := .Definitions -}}
 ### {{$key.Title}}
 
-{{ if $def.Description -}}{{$def.Description}}{{- end }}
-
-{{ if $def.Type -}}**Type:** {{ TypeStr $def }}{{ end }}
-{{ if $def.Default -}}**Default:** `{{DefaultStr $def.Default}}`{{ end }}
-{{if $def.Enum -}}
-**Valid values:**
-{{ range $def.Enum -}}
-- `{{ . }}`
-{{ end -}}
-{{- end}}
-
-{{ if and (eq .Type "object") .Properties -}}
-**Properties:**
-
-| Field | Description | Type | Default | Required |
-| ----- | ----------- | ---- | ------- | :--------: |
+{{ if $def.Description }}{{$def.Description}}
+{{ end }}
+{{- if $def.Type }}**Type:** {{ TypeStr $def }}{{ if $def.Default }} &middot; **Default:** `{{DefaultStr $def.Default}}`{{ end }}
+{{ end }}
+{{- if $def.Enum }}**Valid values:** {{ range $i, $e := $def.Enum }}{{ if $i }}, {{ end }}`{{ $e }}`{{ end }}
+{{ end }}
+{{- if and (eq .Type "object") .Properties }}
+| Field | Type | Default | Required | Description |
+| ----- | ---- | ------- | :------: | ----------- |
 {{ range $propKey, $prop := .Properties -}}
-| `{{$propKey.Lower}}` | {{OneLine $prop.Description}} | {{TypeStr $prop}} | {{DefaultStr $prop.Default}} | {{IsRequired $def.Required $propKey}} |
+| `{{$propKey.Lower}}` | {{TypeStr $prop}} | {{DefaultStr $prop.Default}} | {{IsRequired $def.Required $propKey}} | {{OneLine $prop.Description}} |
+{{ end }}
+{{- end }}
 {{ end -}}
-{{end}}
-{{end}}
 {{end -}}