v0.3.52: docs updates, deployment version tables, workspace-level api keys, knowledgebase improvements

* update infra and remove railway

* feat(api-keys): add workspace-level api keys

* encrypt api keys

* Revert "update infra and remove railway"

This reverts commit b23258a5a1.

* reran migrations

* tested workspace keys

* consolidated code

* more consolidation

* cleanup

* consolidate, remove unused code

* add dummy key for ci

* continue with regular path for self-hosted folks that don't have key set

* fix tests

* fix test

* remove tests

* removed ci additions

.devcontainer/docker-compose.yml

@@ -77,7 +77,7 @@ services:
       - POSTGRES_PASSWORD=postgres
       - POSTGRES_DB=simstudio
     ports:
-      - "5432:5432"
+      - "${POSTGRES_PORT:-5432}:5432"
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U postgres"]
       interval: 5s

.github/workflows/build.yml

@@ -2,8 +2,7 @@ name: Build and Publish Docker Image
 
 on:
   push:
-    branches: [main]
-    tags: ['v*']
+    branches: [main, staging]
 
 jobs:
   build-and-push:
@@ -56,7 +55,7 @@ jobs:
         uses: docker/setup-buildx-action@v3
 
       - name: Log in to the Container registry
-        if: github.event_name != 'pull_request'
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
@@ -70,10 +69,7 @@ jobs:
           images: ${{ matrix.image }}
           tags: |
             type=raw,value=latest-${{ matrix.arch }},enable=${{ github.ref == 'refs/heads/main' }}
-            type=ref,event=pr,suffix=-${{ matrix.arch }}
-            type=semver,pattern={{version}},suffix=-${{ matrix.arch }}
-            type=semver,pattern={{major}}.{{minor}},suffix=-${{ matrix.arch }}
-            type=semver,pattern={{major}}.{{minor}}.{{patch}},suffix=-${{ matrix.arch }}
+            type=raw,value=staging-${{ github.sha }}-${{ matrix.arch }},enable=${{ github.ref == 'refs/heads/staging' }}
             type=sha,format=long,suffix=-${{ matrix.arch }}
 
       - name: Build and push Docker image
@@ -82,7 +78,7 @@ jobs:
           context: .
           file: ${{ matrix.dockerfile }}
           platforms: ${{ matrix.platform }}
-          push: ${{ github.event_name != 'pull_request' }}
+          push: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha,scope=build-v3
@@ -93,7 +89,7 @@ jobs:
   create-manifests:
     runs-on: ubuntu-latest
     needs: build-and-push
-    if: github.event_name != 'pull_request'
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
     strategy:
       matrix:
         include:
@@ -119,10 +115,6 @@ jobs:
           images: ${{ matrix.image }}
           tags: |
             type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
-            type=ref,event=pr
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=semver,pattern={{major}}.{{minor}}.{{patch}}
             type=sha,format=long
 
       - name: Create and push manifest

.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
           node-version: latest
 
       - name: Install dependencies
-        run: bun install
+        run: bun install --frozen-lockfile
 
       - name: Run tests with coverage
         env:

.github/workflows/trigger-deploy.yml

@@ -35,10 +35,10 @@ jobs:
       - name: Deploy to Staging
         if: github.ref == 'refs/heads/staging'
         working-directory: ./apps/sim
-        run: npx --yes trigger.dev@4.0.0 deploy -e staging
+        run: npx --yes trigger.dev@4.0.1 deploy -e staging
 
       - name: Deploy to Production
         if: github.ref == 'refs/heads/main'
         working-directory: ./apps/sim
-        run: npx --yes trigger.dev@4.0.0 deploy
+        run: npx --yes trigger.dev@4.0.1 deploy
 

README.md

@@ -159,8 +159,7 @@ bun run dev:sockets
 Copilot is a Sim-managed service. To use Copilot on a self-hosted instance:
 
 - Go to https://sim.ai → Settings → Copilot and generate a Copilot API key
-- Set `COPILOT_API_KEY` in your self-hosted environment to that value
-- Host Sim on a publicly available DNS and set NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL to that value ([ngrok](https://ngrok.com/))
+- Set `COPILOT_API_KEY` environment variable in your self-hosted apps/sim/.env file to that value
 
 ## Tech Stack
 
@@ -175,6 +174,7 @@ Copilot is a Sim-managed service. To use Copilot on a self-hosted instance:
 - **Monorepo**: [Turborepo](https://turborepo.org/)
 - **Realtime**: [Socket.io](https://socket.io/)
 - **Background Jobs**: [Trigger.dev](https://trigger.dev/)
+- **Remote Code Execution**: [E2B](https://www.e2b.dev/)
 
 ## Contributing
 

apps/docs/app/(docs)/[[...slug]]/page.tsx

@@ -1,6 +1,6 @@
+import defaultMdxComponents from 'fumadocs-ui/mdx'
 import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/page'
 import { notFound } from 'next/navigation'
-import mdxComponents from '@/components/mdx-components'
 import { source } from '@/lib/source'
 
 export const dynamic = 'force-dynamic'
@@ -36,7 +36,7 @@ export default async function Page(props: { params: Promise<{ slug?: string[] }>
       <DocsTitle>{page.data.title}</DocsTitle>
       <DocsDescription>{page.data.description}</DocsDescription>
       <DocsBody>
-        <MDX components={mdxComponents} />
+        <MDX components={defaultMdxComponents} />
       </DocsBody>
     </DocsPage>
   )

apps/docs/app/(docs)/layout.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react'
 import { DocsLayout } from 'fumadocs-ui/layouts/docs'
 import { ExternalLink, GithubIcon } from 'lucide-react'
+import Image from 'next/image'
 import Link from 'next/link'
 import { source } from '@/lib/source'
 
@@ -23,7 +24,17 @@ export default function Layout({ children }: { children: ReactNode }) {
       <DocsLayout
         tree={source.pageTree}
         nav={{
-          title: <div className='flex items-center font-medium'>Sim</div>,
+          title: (
+            <div className='flex items-center'>
+              <Image
+                src='/static/logo.png'
+                alt='Sim'
+                width={60}
+                height={24}
+                className='h-6 w-auto'
+              />
+            </div>
+          ),
         }}
         links={[
           {
@@ -33,9 +44,10 @@ export default function Layout({ children }: { children: ReactNode }) {
           },
         ]}
         sidebar={{
-          defaultOpenLevel: 1,
+          defaultOpenLevel: 0,
           collapsible: true,
           footer: null,
+          banner: null,
         }}
       >
         {children}

apps/docs/app/global.css

@@ -6,6 +6,150 @@
   --color-fd-primary: #802fff; /* Purple from control-bar component */
 }
 
+/* Target any potential border classes */
+* {
+  --fd-border-sidebar: transparent !important;
+}
+
+/* Override any CSS custom properties for borders */
+:root {
+  --fd-border: transparent !important;
+  --fd-border-sidebar: transparent !important;
+}
+
+/* Sidebar improvements for cleaner design */
+[data-sidebar] {
+  --fd-sidebar-width: 280px;
+  background-color: rgb(255 255 255);
+  padding-top: 16px;
+}
+
+/* Clean sidebar container */
+[data-sidebar] > div {
+  padding: 0 16px;
+}
+
+/* Section headers/separators styling */
+[data-sidebar] .text-sm.font-medium.text-muted-foreground,
+[data-sidebar] [data-separator] {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-top: 20px;
+  margin-bottom: 6px;
+  padding-left: 12px;
+  padding-right: 12px;
+  color: rgb(115 115 115);
+  border: none;
+  background: none;
+}
+
+/* First separator should have less top margin */
+[data-sidebar] [data-separator]:first-of-type {
+  margin-top: 12px;
+}
+
+/* Clean sidebar item styling */
+[data-sidebar] a {
+  padding: 8px 12px;
+  margin: 1px 0;
+  border-radius: 6px;
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 1.4;
+  transition: all 0.15s ease;
+  display: block;
+  color: rgb(71 85 105);
+  text-decoration: none;
+}
+
+[data-sidebar] a[data-active="true"] {
+  background-color: rgba(128, 47, 255, 0.08);
+  color: var(--color-fd-primary);
+  font-weight: 500;
+}
+
+[data-sidebar] a:hover:not([data-active="true"]) {
+  background-color: rgb(248 250 252);
+  color: rgb(51 65 85);
+}
+
+/* Improve spacing between sidebar items */
+[data-sidebar] nav > * + * {
+  margin-top: 2px;
+}
+
+/* Section group styling */
+[data-sidebar] [data-folder] {
+  margin-bottom: 4px;
+}
+
+[data-sidebar] [data-folder] > div:first-child {
+  font-weight: 500;
+  font-size: 13px;
+  color: rgb(15 23 42);
+  padding: 6px 12px;
+  margin-bottom: 4px;
+}
+
+/* Clean up folder toggle buttons */
+[data-sidebar] button[data-folder-toggle] {
+  padding: 4px 8px 4px 12px;
+  border-radius: 6px;
+  font-size: 13px;
+  font-weight: 500;
+  color: rgb(51 65 85);
+}
+
+[data-sidebar] button[data-folder-toggle]:hover {
+  background-color: rgb(248 250 252);
+}
+
+/* Nested item indentation */
+[data-sidebar] [data-folder] a {
+  padding-left: 24px;
+  font-size: 14px;
+}
+
+/* Dark mode adjustments */
+@media (prefers-color-scheme: dark) {
+  [data-sidebar] {
+    background-color: rgb(2 8 23);
+  }
+
+  [data-sidebar] a {
+    color: rgb(148 163 184);
+  }
+
+  [data-sidebar] a:hover:not([data-active="true"]) {
+    background-color: rgb(30 41 59);
+    color: rgb(226 232 240);
+  }
+
+  [data-sidebar] a[data-active="true"] {
+    background-color: rgba(128, 47, 255, 0.15);
+    color: var(--color-fd-primary);
+  }
+
+  [data-sidebar] .text-sm.font-medium.text-muted-foreground,
+  [data-sidebar] [data-separator] {
+    color: rgb(148 163 184);
+  }
+
+  [data-sidebar] [data-folder] > div:first-child {
+    color: rgb(226 232 240);
+  }
+
+  [data-sidebar] button[data-folder-toggle] {
+    color: rgb(148 163 184);
+  }
+
+  [data-sidebar] button[data-folder-toggle]:hover {
+    background-color: rgb(30 41 59);
+  }
+}
+
 /* Custom text highlighting styles */
 .text-highlight {
   color: var(--color-fd-primary);
@@ -16,6 +160,23 @@
   color: var(--color-fd-primary);
 }
 
+/* Add bottom spacing to prevent abrupt page endings */
+[data-content] {
+  padding-bottom: 4rem;
+}
+
+/* Alternative fallback for different Fumadocs versions */
+main article,
+.docs-page main {
+  padding-bottom: 4rem;
+}
+
+/* Remove any unwanted borders/outlines from video elements */
+video {
+  outline: none !important;
+  border-style: solid !important;
+}
+
 /* Tailwind v4 content sources */
 @source '../app/**/*.{js,ts,jsx,tsx,mdx}';
 @source '../components/**/*.{js,ts,jsx,tsx,mdx}';

apps/docs/components/mdx-components.tsx

@@ -1,10 +0,0 @@
-import defaultMdxComponents from 'fumadocs-ui/mdx'
-import { ThemeImage } from './ui/theme-image'
-
-// Extend the default MDX components with our custom components
-const mdxComponents = {
-  ...defaultMdxComponents,
-  ThemeImage,
-}
-
-export default mdxComponents

apps/docs/components/ui/block-types.tsx

@@ -1,163 +0,0 @@
-import {
-  AgentIcon,
-  ApiIcon,
-  ChartBarIcon,
-  CodeIcon,
-  ConditionalIcon,
-  ConnectIcon,
-  ResponseIcon,
-} from '@/components/icons'
-import { cn } from '@/lib/utils'
-
-// Custom Feature component specifically for BlockTypes to handle the 6-item layout
-const BlockFeature = ({
-  title,
-  description,
-  icon,
-  href,
-  index,
-  totalItems,
-  itemsPerRow,
-}: {
-  title: string
-  description: string
-  icon: React.ReactNode
-  href?: string
-  index: number
-  totalItems: number
-  itemsPerRow: number
-}) => {
-  const blockColor = {
-    '--block-color':
-      title === 'Agent'
-        ? '#8b5cf6'
-        : title === 'API'
-          ? '#3b82f6'
-          : title === 'Condition'
-            ? '#f59e0b'
-            : title === 'Function'
-              ? '#10b981'
-              : title === 'Router'
-                ? '#6366f1'
-                : title === 'Evaluator'
-                  ? '#ef4444'
-                  : '#8b5cf6',
-  } as React.CSSProperties
-
-  const content = (
-    <>
-      {index < itemsPerRow && (
-        <div className='pointer-events-none absolute inset-0 h-full w-full bg-gradient-to-t from-neutral-100 to-transparent opacity-0 transition duration-200 group-hover/feature:opacity-100 dark:from-neutral-800' />
-      )}
-      {index >= itemsPerRow && (
-        <div className='pointer-events-none absolute inset-0 h-full w-full bg-gradient-to-b from-neutral-100 to-transparent opacity-0 transition duration-200 group-hover/feature:opacity-100 dark:from-neutral-800' />
-      )}
-      <div
-        className='relative z-10 mb-4 px-10 text-neutral-500 transition-colors duration-200 group-hover/feature:text-[color:var(--block-color,#8b5cf6)] dark:text-neutral-400 dark:group-hover/feature:text-[color:var(--block-color,#a78bfa)]'
-        style={blockColor}
-      >
-        {icon}
-      </div>
-      <div className='relative z-10 mb-2 px-10 font-bold text-lg'>
-        <div
-          className='absolute inset-y-0 left-0 h-6 w-1 origin-center rounded-tr-full rounded-br-full bg-neutral-300 transition-all duration-200 group-hover/feature:h-8 group-hover/feature:bg-[color:var(--block-color,#8b5cf6)] dark:bg-neutral-700'
-          style={blockColor}
-        />
-        <span className='inline-block text-neutral-800 transition duration-200 group-hover/feature:translate-x-2 dark:text-neutral-100'>
-          {title}
-        </span>
-      </div>
-      <p className='relative z-10 max-w-xs px-10 text-neutral-600 text-sm dark:text-neutral-300'>
-        {description}
-      </p>
-    </>
-  )
-
-  const containerClasses = cn(
-    'flex flex-col lg:border-r py-5 relative group/feature dark:border-neutral-800',
-    (index === 0 || index === itemsPerRow) && 'lg:border-l dark:border-neutral-800',
-    index < itemsPerRow && 'lg:border-b dark:border-neutral-800',
-    href && 'cursor-pointer hover:bg-neutral-50 dark:hover:bg-neutral-900/50 transition-colors'
-  )
-
-  if (href) {
-    return (
-      <a href={href} className={containerClasses} style={{ textDecoration: 'none' }}>
-        {content}
-      </a>
-    )
-  }
-
-  return <div className={containerClasses}>{content}</div>
-}
-
-export function BlockTypes() {
-  const features = [
-    {
-      title: 'Agent',
-      description:
-        'Create powerful AI agents using any LLM provider with customizable system prompts and tool integrations.',
-      icon: <AgentIcon className='h-6 w-6' />,
-      href: '/blocks/agent',
-    },
-    {
-      title: 'API',
-      description:
-        'Connect to any external API with support for all standard HTTP methods and customizable request parameters.',
-      icon: <ApiIcon className='h-6 w-6' />,
-      href: '/blocks/api',
-    },
-    {
-      title: 'Condition',
-      description:
-        'Add a condition to the workflow to branch the execution path based on a boolean expression.',
-      icon: <ConditionalIcon className='h-6 w-6' />,
-      href: '/blocks/condition',
-    },
-    {
-      title: 'Function',
-      description:
-        'Execute custom JavaScript or TypeScript code within your workflow to transform data or implement complex logic.',
-      icon: <CodeIcon className='h-6 w-6' />,
-      href: '/blocks/function',
-    },
-    {
-      title: 'Router',
-      description:
-        'Intelligently direct workflow execution to different paths based on input analysis.',
-      icon: <ConnectIcon className='h-6 w-6' />,
-      href: '/blocks/router',
-    },
-    {
-      title: 'Evaluator',
-      description:
-        'Assess content using customizable evaluation metrics and scoring criteria across multiple dimensions.',
-      icon: <ChartBarIcon className='h-6 w-6' />,
-      href: '/blocks/evaluator',
-    },
-    {
-      title: 'Response',
-      description:
-        'Send a response back to the caller with customizable data, status, and headers.',
-      icon: <ResponseIcon className='h-6 w-6' />,
-      href: '/blocks/response',
-    },
-  ]
-
-  const totalItems = features.length
-  const itemsPerRow = 3 // For large screens
-
-  return (
-    <div className='relative z-10 mx-auto grid max-w-7xl grid-cols-1 py-10 md:grid-cols-2 lg:grid-cols-3'>
-      {features.map((feature, index) => (
-        <BlockFeature
-          key={feature.title}
-          {...feature}
-          index={index}
-          totalItems={totalItems}
-          itemsPerRow={itemsPerRow}
-        />
-      ))}
-    </div>
-  )
-}

apps/docs/components/ui/features.tsx

@@ -1,102 +0,0 @@
-import {
-  IconAdjustmentsBolt,
-  IconCloud,
-  IconEaseInOut,
-  IconHeart,
-  IconHelp,
-  IconHistory,
-  IconRouteAltLeft,
-  IconTerminal2,
-} from '@tabler/icons-react'
-import { cn } from '@/lib/utils'
-
-export function Features() {
-  const features = [
-    {
-      title: 'Multi-LLM Support',
-      description: 'Connect to any LLM provider including OpenAI, Anthropic, and more',
-      icon: <IconCloud />,
-    },
-    {
-      title: 'API Deployment',
-      description: 'Deploy your workflows as secure, scalable APIs',
-      icon: <IconTerminal2 />,
-    },
-    {
-      title: 'Webhook Integration',
-      description: 'Trigger workflows via webhooks from external services',
-      icon: <IconRouteAltLeft />,
-    },
-    {
-      title: 'Scheduled Execution',
-      description: 'Schedule workflows to run at specific times or intervals',
-      icon: <IconEaseInOut />,
-    },
-    {
-      title: '40+ Integrations',
-      description: 'Connect to hundreds of external services and data sources',
-      icon: <IconAdjustmentsBolt />,
-    },
-    {
-      title: 'Visual Debugging',
-      description: 'Debug workflows visually with detailed execution logs',
-      icon: <IconHelp />,
-    },
-    {
-      title: 'Version Control',
-      description: 'Track changes and roll back to previous versions',
-      icon: <IconHistory />,
-    },
-    {
-      title: 'Team Collaboration',
-      description: 'Collaborate with team members on workflow development',
-      icon: <IconHeart />,
-    },
-  ]
-  return (
-    <div className='relative z-20 mx-auto grid max-w-7xl grid-cols-1 py-10 md:grid-cols-2 lg:grid-cols-4'>
-      {features.map((feature, index) => (
-        <Feature key={feature.title} {...feature} index={index} />
-      ))}
-    </div>
-  )
-}
-
-export const Feature = ({
-  title,
-  description,
-  icon,
-  index,
-}: {
-  title: string
-  description: string
-  icon: React.ReactNode
-  index: number
-}) => {
-  return (
-    <div
-      className={cn(
-        'group/feature relative flex flex-col py-5 lg:border-r dark:border-neutral-800',
-        (index === 0 || index === 4) && 'lg:border-l dark:border-neutral-800',
-        index < 4 && 'lg:border-b dark:border-neutral-800'
-      )}
-    >
-      {index < 4 && (
-        <div className='pointer-events-none absolute inset-0 h-full w-full bg-gradient-to-t from-neutral-100 to-transparent opacity-0 transition duration-200 group-hover/feature:opacity-100 dark:from-neutral-800' />
-      )}
-      {index >= 4 && (
-        <div className='pointer-events-none absolute inset-0 h-full w-full bg-gradient-to-b from-neutral-100 to-transparent opacity-0 transition duration-200 group-hover/feature:opacity-100 dark:from-neutral-800' />
-      )}
-      <div className='relative z-10 mb-4 px-10 text-neutral-600 dark:text-neutral-400'>{icon}</div>
-      <div className='relative z-10 mb-2 px-10 font-bold text-lg'>
-        <div className='absolute inset-y-0 left-0 h-6 w-1 origin-center rounded-tr-full rounded-br-full bg-neutral-300 transition-all duration-200 group-hover/feature:h-8 group-hover/feature:bg-purple-500 dark:bg-neutral-700' />
-        <span className='inline-block text-neutral-800 transition duration-200 group-hover/feature:translate-x-2 dark:text-neutral-100'>
-          {title}
-        </span>
-      </div>
-      <p className='relative z-10 max-w-xs px-10 text-neutral-600 text-sm dark:text-neutral-300'>
-        {description}
-      </p>
-    </div>
-  )
-}

apps/docs/components/ui/image.tsx

@@ -0,0 +1,53 @@
+'use client'
+
+import { useState } from 'react'
+import NextImage, { type ImageProps as NextImageProps } from 'next/image'
+import { cn } from '@/lib/utils'
+import { Lightbox } from './lightbox'
+
+interface ImageProps extends Omit<NextImageProps, 'className'> {
+  className?: string
+  enableLightbox?: boolean
+}
+
+export function Image({
+  className = 'w-full rounded-xl border border-border shadow-sm overflow-hidden',
+  enableLightbox = true,
+  alt = '',
+  src,
+  ...props
+}: ImageProps) {
+  const [isLightboxOpen, setIsLightboxOpen] = useState(false)
+
+  const handleImageClick = () => {
+    if (enableLightbox) {
+      setIsLightboxOpen(true)
+    }
+  }
+
+  return (
+    <>
+      <NextImage
+        className={cn(
+          'object-cover',
+          enableLightbox && 'cursor-pointer transition-opacity hover:opacity-90',
+          className
+        )}
+        alt={alt}
+        src={src}
+        onClick={handleImageClick}
+        {...props}
+      />
+
+      {enableLightbox && (
+        <Lightbox
+          isOpen={isLightboxOpen}
+          onClose={() => setIsLightboxOpen(false)}
+          src={typeof src === 'string' ? src : String(src)}
+          alt={alt}
+          type='image'
+        />
+      )}
+    </>
+  )
+}

apps/docs/components/ui/lightbox.tsx

@@ -0,0 +1,74 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+import { getVideoUrl } from '@/lib/utils'
+
+interface LightboxProps {
+  isOpen: boolean
+  onClose: () => void
+  src: string
+  alt: string
+  type: 'image' | 'video'
+}
+
+export function Lightbox({ isOpen, onClose, src, alt, type }: LightboxProps) {
+  const overlayRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        onClose()
+      }
+    }
+
+    const handleClickOutside = (event: MouseEvent) => {
+      if (overlayRef.current && event.target === overlayRef.current) {
+        onClose()
+      }
+    }
+
+    if (isOpen) {
+      document.addEventListener('keydown', handleKeyDown)
+      document.addEventListener('click', handleClickOutside)
+      document.body.style.overflow = 'hidden'
+    }
+
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown)
+      document.removeEventListener('click', handleClickOutside)
+      document.body.style.overflow = 'unset'
+    }
+  }, [isOpen, onClose])
+
+  if (!isOpen) return null
+
+  return (
+    <div
+      ref={overlayRef}
+      className='fixed inset-0 z-50 flex items-center justify-center bg-black/80 p-12 backdrop-blur-sm'
+      role='dialog'
+      aria-modal='true'
+      aria-label='Media viewer'
+    >
+      <div className='relative max-h-full max-w-full overflow-hidden rounded-xl shadow-2xl'>
+        {type === 'image' ? (
+          <img
+            src={src}
+            alt={alt}
+            className='max-h-[calc(100vh-6rem)] max-w-[calc(100vw-6rem)] rounded-xl object-contain'
+            loading='lazy'
+          />
+        ) : (
+          <video
+            src={getVideoUrl(src)}
+            autoPlay
+            loop
+            muted
+            playsInline
+            className='max-h-[calc(100vh-6rem)] max-w-[calc(100vw-6rem)] rounded-xl outline-none focus:outline-none'
+          />
+        )}
+      </div>
+    </div>
+  )
+}

apps/docs/components/ui/theme-image.tsx

@@ -1,48 +0,0 @@
-'use client'
-
-import { useEffect, useState } from 'react'
-import Image from 'next/image'
-import { useTheme } from 'next-themes'
-
-interface ThemeImageProps {
-  lightSrc: string
-  darkSrc: string
-  alt: string
-  width?: number
-  height?: number
-  className?: string
-}
-
-export function ThemeImage({
-  lightSrc,
-  darkSrc,
-  alt,
-  width = 600,
-  height = 400,
-  className = 'rounded-lg border border-border my-6',
-}: ThemeImageProps) {
-  const { resolvedTheme } = useTheme()
-  const [imageSrc, setImageSrc] = useState(lightSrc)
-  const [mounted, setMounted] = useState(false)
-
-  // Wait until component is mounted to avoid hydration mismatch
-  useEffect(() => {
-    setMounted(true)
-  }, [])
-
-  useEffect(() => {
-    if (mounted) {
-      setImageSrc(resolvedTheme === 'dark' ? darkSrc : lightSrc)
-    }
-  }, [resolvedTheme, lightSrc, darkSrc, mounted])
-
-  if (!mounted) {
-    return null
-  }
-
-  return (
-    <div className='flex justify-center'>
-      <Image src={imageSrc} alt={alt} width={width} height={height} className={className} />
-    </div>
-  )
-}

apps/docs/components/ui/video.tsx

@@ -1,4 +1,8 @@
+'use client'
+
+import { useState } from 'react'
 import { getVideoUrl } from '@/lib/utils'
+import { Lightbox } from './lightbox'
 
 interface VideoProps {
   src: string
@@ -7,24 +11,47 @@ interface VideoProps {
   loop?: boolean
   muted?: boolean
   playsInline?: boolean
+  enableLightbox?: boolean
 }
 
 export function Video({
   src,
-  className = 'w-full -mb-2 rounded-lg',
+  className = 'w-full rounded-xl border border-border shadow-sm overflow-hidden outline-none focus:outline-none',
   autoPlay = true,
   loop = true,
   muted = true,
   playsInline = true,
+  enableLightbox = true,
 }: VideoProps) {
+  const [isLightboxOpen, setIsLightboxOpen] = useState(false)
+
+  const handleVideoClick = () => {
+    if (enableLightbox) {
+      setIsLightboxOpen(true)
+    }
+  }
+
   return (
-    <video
-      autoPlay={autoPlay}
-      loop={loop}
-      muted={muted}
-      playsInline={playsInline}
-      className={className}
-      src={getVideoUrl(src)}
-    />
+    <>
+      <video
+        autoPlay={autoPlay}
+        loop={loop}
+        muted={muted}
+        playsInline={playsInline}
+        className={`${className} ${enableLightbox ? 'cursor-pointer transition-opacity hover:opacity-90' : ''}`}
+        src={getVideoUrl(src)}
+        onClick={handleVideoClick}
+      />
+
+      {enableLightbox && (
+        <Lightbox
+          isOpen={isLightboxOpen}
+          onClose={() => setIsLightboxOpen(false)}
+          src={src}
+          alt={`Video: ${src}`}
+          type='video'
+        />
+      )}
+    </>
   )
 }

apps/docs/content/docs/blocks/agent.mdx

@@ -1,22 +1,24 @@
 ---
 title: Agent
-description: Create powerful AI agents using any LLM provider
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
+import { Video } from '@/components/ui/video'
 
 The Agent block serves as the interface between your workflow and Large Language Models (LLMs). It executes inference requests against various AI providers, processes natural language inputs according to defined instructions, and generates structured or unstructured outputs for downstream consumption.
 
-<ThemeImage
-  lightSrc="/static/light/agent-light.png"
-  darkSrc="/static/dark/agent-dark.png"
-  alt="Agent Block Configuration"
-  width={350}
-  height={175}
-/>
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/agent.png"
+    alt="Agent Block Configuration"
+    width={500}
+    height={400}
+    className="my-6"
+  />
+</div>
 
 ## Overview
 
@@ -68,7 +70,7 @@ The Agent block supports multiple LLM providers through a unified inference inte
 **Local Deployment**: Ollama-compatible models (self-hosted inference)
 
 <div className="mx-auto w-3/5 overflow-hidden rounded-lg">
-  <video autoPlay loop muted playsInline className="w-full -mb-2 rounded-lg" src="/models.mp4"></video>
+  <Video src="models.mp4" width={500} height={350} />
 </div>
 
 ### Temperature
@@ -90,9 +92,9 @@ Control the creativity and randomness of responses:
   </Tab>
 </Tabs>
 
-<p className="mt-4 text-sm text-gray-600 dark:text-gray-400">
+<div className="mt-4 text-sm text-gray-600 dark:text-gray-400">
   The temperature range (0-1 or 0-2) varies depending on the selected model.
-</p>
+</div>
 
 ### API Key
 
@@ -108,7 +110,7 @@ Tools extend the agent's capabilities through external API integrations and serv
 3. Configure authentication parameters and operational constraints
 
 <div className="mx-auto w-3/5 overflow-hidden rounded-lg">
-  <video autoPlay loop muted playsInline className="w-full -mb-2 rounded-lg" src="/tools.mp4"></video>
+  <Video src="tools.mp4" width={500} height={350} />
 </div>
 
 **Available Tool Categories**:
@@ -124,7 +126,7 @@ Tools extend the agent's capabilities through external API integrations and serv
 - **None**: Tool definition available but excluded from model context
 
 <div className="mx-auto w-3/5 overflow-hidden rounded-lg">
-  <video autoPlay loop muted playsInline className="w-full -mb-2 rounded-lg" src="/granular-tool-control.mp4"></video>
+  <Video src="granular-tool-control.mp4" width={500} height={350} />
 </div>
 
 ### Response Format
@@ -165,42 +167,41 @@ After an agent completes, you can access its outputs:
 
 ## Advanced Features
 
-### Memory Integration
+### Memory + Agent: Conversation History
 
-Agents can maintain context across interactions using the memory system:
+Use a `Memory` block with a consistent `id` (for example, `chat`) to persist messages between runs, and include that history in the Agent's prompt.
 
-```javascript
-// In a Function block before the agent
-const memory = {
-  conversation_history: previousMessages,
-  user_preferences: userProfile,
-  session_data: currentSession
-};
+- Add the user's message before the Agent
+- Read the conversation history for context
+- Append the Agent's reply after it runs
+
+```yaml
+# 1) Add latest user message
+- Memory (operation: add)
+  id: chat
+  role: user
+  content: {{input}}
+
+# 2) Load conversation history
+- Memory (operation: get)
+  id: chat
+
+# 3) Run the agent with prior messages available
+- Agent
+  System Prompt: ...
+  User Prompt: |
+    Use the conversation so far:
+    {{memory_get.memories}}
+    Current user message: {{input}}
+
+# 4) Store the agent reply
+- Memory (operation: add)
+  id: chat
+  role: assistant
+  content: {{agent.content}}
 ```
 
-### Structured Output Validation
-
-Use JSON Schema to ensure consistent, machine-readable responses:
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "analysis": {"type": "string"},
-    "confidence": {"type": "number", "minimum": 0, "maximum": 1},
-    "categories": {"type": "array", "items": {"type": "string"}}
-  },
-  "required": ["analysis", "confidence"]
-}
-```
-
-### Error Handling
-
-Agents automatically handle common errors:
-- API rate limits with exponential backoff
-- Invalid tool calls with retry logic
-- Network failures with connection recovery
-- Schema validation errors with fallback responses
+See the `Memory` block reference for details: [/tools/memory](/tools/memory).
 
 ## Inputs and Outputs
 
@@ -265,10 +266,12 @@ Agents automatically handle common errors:
 <div className="mb-4 rounded-md border p-4">
   <h4 className="font-medium">Scenario: Handle customer inquiries with database access</h4>
   <ol className="list-decimal pl-5 text-sm">
-    <li>User submits support ticket via API block</li>
-    <li>Agent processes inquiry with product database tools</li>
-    <li>Agent generates response and creates follow-up ticket</li>
-    <li>Response block sends reply to customer</li>
+    <li>User submits a support ticket via the API block</li>
+    <li>Agent checks orders/subscriptions in Postgres and searches the knowledge base for guidance</li>
+    <li>If escalation is needed, the Agent creates a Linear issue with relevant context</li>
+    <li>Agent drafts a clear email reply</li>
+    <li>Gmail sends the reply to the customer</li>
+    <li>Conversation is saved to Memory to maintain history for future messages</li>
   </ol>
 </div>
 

apps/docs/content/docs/blocks/api.mdx

@@ -1,22 +1,23 @@
 ---
 title: API
-description: Connect to external services through API endpoints
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
 
-The API block enables you to connect your workflow to external services through HTTP requests. It supports various methods like GET, POST, PUT, DELETE, and PATCH, allowing you to interact with virtually any API endpoint.
+The API block enables you to connect your workflow to external services through API endpoints using HTTP requests. It supports various methods like GET, POST, PUT, DELETE, and PATCH, allowing you to interact with virtually any API endpoint.
 
-<ThemeImage
-  lightSrc="/static/light/api-light.png"
-  darkSrc="/static/dark/api-dark.png"
-  alt="API Block"
-  width={350}
-  height={175}
-/>
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/api.png"
+    alt="API Block"
+    width={500}
+    height={400}
+    className="my-6"
+  />
+</div>
 
 ## Overview
 
@@ -37,6 +38,15 @@ The API block enables you to:
   </Step>
 </Steps>
 
+## How It Works
+
+The API block processes HTTP requests through a structured approach:
+
+1. **Configure Request** - Set URL, method, headers, and body parameters
+2. **Execute Request** - Send HTTP request to the specified endpoint
+3. **Process Response** - Handle response data, status codes, and headers
+4. **Error Handling** - Manage timeouts, retries, and error conditions
+
 ## Configuration Options
 
 ### URL
@@ -202,18 +212,6 @@ if (<api.status> === 200) {
   </ol>
 </div>
 
-### Create Support Ticket
-
-<div className="mb-4 rounded-md border p-4">
-  <h4 className="font-medium">Scenario: Submit support request to ticketing system</h4>
-  <ol className="list-decimal pl-5 text-sm">
-    <li>Agent analyzes user issue and generates ticket data</li>
-    <li>API block POSTs ticket to support system</li>
-    <li>Condition block checks if ticket was created successfully</li>
-    <li>Response block confirms ticket creation with ID</li>
-  </ol>
-</div>
-
 ### Payment Processing
 
 <div className="mb-4 rounded-md border p-4">
@@ -222,7 +220,7 @@ if (<api.status> === 200) {
     <li>Function block validates payment data</li>
     <li>API block creates payment intent via Stripe</li>
     <li>Condition block handles payment success/failure</li>
-    <li>Function block updates order status in database</li>
+    <li>Supabase block updates order status in database</li>
   </ol>
 </div>
 

apps/docs/content/docs/blocks/condition.mdx

@@ -1,23 +1,24 @@
 ---
 title: Condition
-description: Create conditional logic and branching in your workflows
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
 
-The Condition block allows you to branch your workflow execution path based on boolean expressions. It evaluates conditions and routes the workflow accordingly, enabling you to create dynamic, responsive workflows with different execution paths.
+The Condition block allows you to branch your workflow execution path based on boolean expressions, enabling you to create dynamic, responsive workflows with different execution paths. It evaluates conditions and routes the workflow accordingly, letting you control execution flow based on data or logic without requiring an LLM.
 
-<ThemeImage
-  lightSrc="/static/light/condition-light.png"
-  darkSrc="/static/dark/condition-dark.png"
-  alt="Condition Block"
-  width={350}
-  height={175}
-/>
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/condition.png"
+    alt="Condition Block"
+    width={500}
+    height={350}
+    className="my-6"
+  />
+</div>
 
 <Callout>
   Condition blocks enable deterministic decision-making without requiring an LLM, making them ideal

apps/docs/content/docs/blocks/evaluator.mdx

@@ -1,31 +1,52 @@
 ---
 title: Evaluator
-description: Assess content quality using customizable evaluation metrics
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
 import { Video } from '@/components/ui/video'
 
-The Evaluator block uses AI to score and assess content quality based on metrics you define. Perfect for quality control, A/B testing, and ensuring your AI outputs meet specific standards.
+The Evaluator block uses AI to score and assess content quality using customizable evaluation metrics that you define. Perfect for quality control, A/B testing, and ensuring your AI outputs meet specific standards.
 
-<ThemeImage
-  lightSrc="/static/light/evaluator-light.png"
-  darkSrc="/static/dark/evaluator-dark.png"
-  alt="Evaluator Block Configuration"
-  width={350}
-  height={175}
-/>
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/evaluator.png"
+    alt="Evaluator Block Configuration"
+    width={500}
+    height={400}
+    className="my-6"
+  />
+</div>
 
-## What You Can Evaluate
+## Overview
 
-**AI-Generated Content**: Score chatbot responses, generated articles, or marketing copy
-**User Input**: Evaluate customer feedback, survey responses, or form submissions  
-**Content Quality**: Assess clarity, accuracy, relevance, and tone
-**Performance Metrics**: Track improvements over time with consistent scoring
-**A/B Testing**: Compare different approaches with objective metrics
+The Evaluator block enables you to:
+
+<Steps>
+  <Step>
+    <strong>Score Content Quality</strong>: Use AI to evaluate content against custom metrics with numeric scores
+  </Step>
+  <Step>
+    <strong>Define Custom Metrics</strong>: Create specific evaluation criteria tailored to your use case  
+  </Step>
+  <Step>
+    <strong>Automate Quality Control</strong>: Build workflows that automatically assess and filter content
+  </Step>
+  <Step>
+    <strong>Track Performance</strong>: Monitor improvements and consistency over time with objective scoring
+  </Step>
+</Steps>
+
+## How It Works
+
+The Evaluator block processes content through AI-powered assessment:
+
+1. **Receive Content** - Takes input content from previous blocks in your workflow
+2. **Apply Metrics** - Evaluates content against your defined custom metrics  
+3. **Generate Scores** - AI model assigns numeric scores for each metric
+4. **Provide Summary** - Returns detailed evaluation with scores and explanations
 
 ## Configuration Options
 
@@ -64,7 +85,7 @@ Choose an AI model to perform the evaluation:
 **Local Models**: Any model running on Ollama
 
 <div className="w-full max-w-2xl mx-auto overflow-hidden rounded-lg">
-  <Video src="models.mp4" />
+  <Video src="models.mp4" width={500} height={350} />
 </div>
 
 **Recommendation**: Use models with strong reasoning capabilities like GPT-4o or Claude 3.7 Sonnet for more accurate evaluations.
@@ -81,46 +102,93 @@ Your API key for the selected LLM provider. This is securely stored and used for
 4. The LLM evaluates the content and returns numeric scores for each metric
 5. The Evaluator block formats these scores as structured output for use in your workflow
 
+## Example Use Cases
+
+### Content Quality Assessment
+
+<div className="mb-4 rounded-md border p-4">
+  <h4 className="font-medium">Scenario: Evaluate blog post quality before publication</h4>
+  <ol className="list-decimal pl-5 text-sm">
+    <li>Agent block generates blog post content</li>
+    <li>Evaluator assesses accuracy, readability, and engagement</li>
+    <li>Condition block checks if scores meet minimum thresholds</li>
+    <li>High scores → Publish, Low scores → Revise and retry</li>
+  </ol>
+</div>
+
+### A/B Testing Content
+
+<div className="mb-4 rounded-md border p-4">
+  <h4 className="font-medium">Scenario: Compare multiple AI-generated responses</h4>
+  <ol className="list-decimal pl-5 text-sm">
+    <li>Parallel block generates multiple response variations</li>
+    <li>Evaluator scores each variation on clarity and relevance</li>
+    <li>Function block selects highest-scoring response</li>
+    <li>Response block returns the best result</li>
+  </ol>
+</div>
+
+### Customer Support Quality Control
+
+<div className="mb-4 rounded-md border p-4">
+  <h4 className="font-medium">Scenario: Ensure support responses meet quality standards</h4>
+  <ol className="list-decimal pl-5 text-sm">
+    <li>Support agent generates response to customer inquiry</li>
+    <li>Evaluator scores helpfulness, empathy, and accuracy</li>
+    <li>Scores logged for training and performance monitoring</li>
+    <li>Low scores trigger human review process</li>
+  </ol>
+</div>
+
 ## Inputs and Outputs
 
-### Inputs
-
-- **Content**: The text or structured data to evaluate
-- **Metrics**: Custom evaluation criteria with scoring ranges
-- **Model Settings**: LLM provider and parameters
-
-### Outputs
-
-- **Content**: A summary of the evaluation
-- **Model**: The model used for evaluation
-- **Tokens**: Usage statistics
-- **Metric Scores**: Numeric scores for each defined metric
-
-## Example Usage
-
-Here's an example of how an Evaluator block might be configured for assessing customer service responses:
-
-```yaml
-# Example Evaluator Configuration
-metrics:
-  - name: Empathy
-    description: How well does the response acknowledge and address the customer's emotional state?
-    range:
-      min: 1
-      max: 5
-  - name: Solution
-    description: How effectively does the response solve the customer's problem?
-    range:
-      min: 1
-      max: 5
-  - name: Clarity
-    description: How clear and easy to understand is the response?
-    range:
-      min: 1
-      max: 5
-
-model: Anthropic/claude-3-opus
-```
+<Tabs items={['Configuration', 'Variables', 'Results']}>
+  <Tab>
+    <ul className="list-disc space-y-2 pl-6">
+      <li>
+        <strong>Content</strong>: The text or structured data to evaluate
+      </li>
+      <li>
+        <strong>Evaluation Metrics</strong>: Custom criteria with scoring ranges
+      </li>
+      <li>
+        <strong>Model</strong>: AI model for evaluation analysis
+      </li>
+      <li>
+        <strong>API Key</strong>: Authentication for selected LLM provider
+      </li>
+    </ul>
+  </Tab>
+  <Tab>
+    <ul className="list-disc space-y-2 pl-6">
+      <li>
+        <strong>evaluator.content</strong>: Summary of the evaluation
+      </li>
+      <li>
+        <strong>evaluator.model</strong>: Model used for evaluation
+      </li>
+      <li>
+        <strong>evaluator.tokens</strong>: Token usage statistics
+      </li>
+      <li>
+        <strong>evaluator.cost</strong>: Cost summary for the evaluation call
+      </li>
+    </ul>
+  </Tab>
+  <Tab>
+    <ul className="list-disc space-y-2 pl-6">
+      <li>
+        <strong>Metric Scores</strong>: Numeric scores for each defined metric
+      </li>
+      <li>
+        <strong>Evaluation Summary</strong>: Detailed assessment with explanations
+      </li>
+      <li>
+        <strong>Access</strong>: Available in blocks after the evaluator
+      </li>
+    </ul>
+  </Tab>
+</Tabs>
 
 ## Best Practices
 

apps/docs/content/docs/blocks/function.mdx

@@ -1,22 +1,23 @@
 ---
 title: Function
-description: Execute custom JavaScript or TypeScript code in your workflows
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
 
-The Function block lets you run custom JavaScript or TypeScript code in your workflow. Use it to transform data, perform calculations, or implement custom logic that isn't available in other blocks.
+The Function block lets you execute custom JavaScript or TypeScript code in your workflows. Use it to transform data, perform calculations, or implement custom logic that isn't available in other blocks.
 
-<ThemeImage
-  lightSrc="/static/light/function-light.png"
-  darkSrc="/static/dark/function-dark.png"
-  alt="Function Block with Code Editor"
-  width={350}
-  height={175}
-/>
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/function.png"
+    alt="Function Block with Code Editor"
+    width={500}
+    height={350}
+    className="my-6"
+  />
+</div>
 
 ## Overview
 
@@ -42,164 +43,25 @@ The Function block enables you to:
 The Function block runs your code in a secure, isolated environment:
 
 1. **Receive Input**: Access data from previous blocks via the `input` object
-2. **Execute Code**: Run your JavaScript/TypeScript code 
+2. **Execute Code**: Run your JavaScript/Python code 
 3. **Return Results**: Use `return` to pass data to the next block
 4. **Handle Errors**: Built-in error handling and logging
 
-## Configuration Options
+## Remote Execution (E2B)
 
-### Code Editor
-
-Write your JavaScript/TypeScript code in a full-featured editor with:
-- Syntax highlighting and error checking
-- Line numbers and bracket matching
-- Support for modern JavaScript features
-- Native support for `fetch` 
-
-### Accessing Input Data
-
-Use the `input` object to access data from previous blocks:
-
-```javascript
-// Access data from connected blocks
-const userData = <agent.userData>;
-const orderData = <agent.orderData>;
-
-// Access specific fields
-const customerName = <agent.customer.name>;
-const total = <agent.order.total>;
-```
-
-### Common Examples
-
-**Data Transformation**:
-```javascript
-// Convert and format data
-const formatted = {
-  name: <agent.user.firstName> + ' ' + <agent.user.lastName>,
-  email: <agent.user.email>.toLowerCase(),
-  joinDate: new Date(<agent.user.created>).toLocaleDateString()
-};
-return formatted;
-```
-
-**Calculations**:
-```javascript
-// Calculate discounts and totals
-const subtotal = <agent.items>.reduce((sum, item) => sum + item.price, 0);
-const discount = subtotal > 100 ? 0.1 : 0;
-const total = subtotal * (1 - discount);
-
-return { subtotal, discount, total };
-```
-
-**Data Validation**:
-```javascript
-// Validate email format
-const email = <agent.email>;
-const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
-
-if (!isValid) {
-  throw new Error('Invalid email format');
-}
-return { email, isValid };
-```
-
-### Accessing Results
-
-After a function executes, you can access its outputs:
-
-- **`<function.result>`**: The value returned from your function
-- **`<function.stdout>`**: Any console.log() output from your code
-
-## Advanced Features
-
-### Async/Await Support
-
-Use async functions for complex operations:
-
-```javascript
-// Async function example
-const processData = async () => {
-  const data = <api.response>;
-  
-  // Process data with async operations
-  const processed = await Promise.all(
-    data.map(async (item) => {
-      return {
-        id: item.id,
-        processed: true,
-        timestamp: new Date().toISOString()
-      };
-    })
-  );
-  
-  return processed;
-};
-
-return await processData();
-```
-
-### Error Handling
-
-Implement robust error handling:
-
-```javascript
-try {
-  const result = <api.data>;
-  
-  if (!result || !result.length) {
-    throw new Error('No data received');
-  }
-  
-  return result.map(item => ({
-    id: item.id,
-    name: item.name.trim(),
-    valid: true
-  }));
-} catch (error) {
-  console.error('Processing failed:', error.message);
-  return { error: error.message, valid: false };
-}
-```
-
-### Performance Optimization
-
-Optimize for large datasets:
-
-```javascript
-// Efficient data processing
-const data = <api.large_dataset>;
-
-// Use efficient array methods
-const processed = data
-  .filter(item => item.status === 'active')
-  .map(item => ({
-    id: item.id,
-    summary: item.description.substring(0, 100)
-  }))
-  .slice(0, 1000); // Limit results
-
-return processed;
-```
-
-## Security and Limitations
-
-<Callout type="warning">
-  Functions run in a secure environment with these restrictions:
-  - **Execution timeout**: 30 seconds maximum to prevent infinite loops
-  - **Memory limits**: Limited memory to prevent resource exhaustion
-  - **No network access**: Cannot make HTTP requests (use API blocks instead)
-  - **Limited APIs**: Only safe JavaScript APIs are available
-</Callout>
+  - **Languages**: Run JavaScript and Python in an isolated E2B sandbox.
+  - **How to enable**: Toggle “Remote Code Execution” in the Function block.
+  - **When to use**: Heavier logic, external libraries, or Python-specific code.
+  - **Performance**: Slower than local JS due to sandbox startup and network overhead.
+  - **Notes**: Requires `E2B_API_KEY` if running locally. For lowest latency, use natively local JS (Fast Mode).
 
 ## Inputs and Outputs
 
-<Tabs items={['Configuration', 'Variables', 'Results']}>
+<Tabs items={['Configuration', 'Variables']}>
   <Tab>
     <ul className="list-disc space-y-2 pl-6">
       <li>
-        <strong>Code</strong>: Your JavaScript/TypeScript code to execute
+        <strong>Code</strong>: Your JavaScript/Python code to execute
       </li>
       <li>
         <strong>Timeout</strong>: Maximum execution time (defaults to 30 seconds)
@@ -217,25 +79,6 @@ return processed;
       <li>
         <strong>function.stdout</strong>: Console.log() output from your code
       </li>
-      <li>
-        <strong>function.error</strong>: Error details if function failed
-      </li>
-      <li>
-        <strong>function.execution_time</strong>: Time taken to execute
-      </li>
-    </ul>
-  </Tab>
-  <Tab>
-    <ul className="list-disc space-y-2 pl-6">
-      <li>
-        <strong>Function Result</strong>: Primary output from your code
-      </li>
-      <li>
-        <strong>Debug Information</strong>: Logs and execution details
-      </li>
-      <li>
-        <strong>Access</strong>: Available in blocks after the function
-      </li>
     </ul>
   </Tab>
 </Tabs>

apps/docs/content/docs/blocks/index.mdx

@@ -6,13 +6,12 @@ description: The building components of your AI workflows
 import { Card, Cards } from 'fumadocs-ui/components/card'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { BlockTypes } from '@/components/ui/block-types'
 import { Video } from '@/components/ui/video'
 
 Blocks are the building components you connect together to create AI workflows. Think of them as specialized modules that each handle a specific task—from chatting with AI models to making API calls or processing data.
 
 <div className="w-full max-w-2xl mx-auto overflow-hidden rounded-lg">
-  <Video src="connections.mp4" />
+  <Video src="connections.mp4" width={700} height={450} />
 </div>
 
 ## Core Block Types
@@ -32,8 +31,6 @@ Sim provides seven core block types that handle the essential functions of AI wo
 ### Output Blocks
 - **[Response](/blocks/response)** - Format and return final results from your workflow
 
-<BlockTypes />
-
 ## How Blocks Work
 
 Each block has three main components:
@@ -63,7 +60,7 @@ You create workflows by connecting blocks together. The output of one block beco
 - **Branching paths**: Some blocks can route to different paths based on conditions
 
 <div className="w-full max-w-2xl mx-auto overflow-hidden rounded-lg">
-  <Video src="connections.mp4" />
+  <Video src="connections.mp4" width={700} height={450} />
 </div>
 
 ## Common Patterns

apps/docs/content/docs/blocks/loop.mdx

@@ -1,22 +1,15 @@
 ---
 title: Loop
-description: Create iterative workflows with loops that execute blocks repeatedly
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
 
-The Loop block is a container block in Sim that allows you to execute a group of blocks repeatedly. Loops enable iterative processing in your workflows.
+The Loop block is a container block in Sim that allows you to create iterative workflows by executing a group of blocks repeatedly. Loops enable iterative processing in your workflows.
 
-<ThemeImage
-  lightSrc="/static/light/loop-light.png"
-  darkSrc="/static/dark/loop-dark.png"
-  alt="Loop Block"
-  width={500}
-  height={300}
-/>
+The Loop block supports two types of iteration:
 
 <Callout type="info">
   Loop blocks are container nodes that can hold other blocks inside them. The blocks inside a loop will execute multiple times based on your configuration.
@@ -33,8 +26,23 @@ The Loop block enables you to:
   <Step>
     <strong>Repeat operations</strong>: Execute blocks a fixed number of times
   </Step>
+  <Step>
+    <strong>Sequential processing</strong>: Handle data transformation in ordered iterations
+  </Step>
+  <Step>
+    <strong>Aggregate results</strong>: Collect outputs from all loop iterations
+  </Step>
 </Steps>
 
+## How It Works
+
+The Loop block executes contained blocks through sequential iteration:
+
+1. **Initialize Loop** - Set up iteration parameters (count or collection)
+2. **Execute Iteration** - Run contained blocks for current iteration
+3. **Collect Results** - Store output from each iteration
+4. **Continue or Complete** - Move to next iteration or finish loop
+
 ## Configuration Options
 
 ### Loop Type
@@ -43,7 +51,19 @@ Choose between two types of loops:
 
 <Tabs items={['For Loop', 'ForEach Loop']}>
   <Tab>
-    A numeric loop that executes a fixed number of times. Use this when you need to repeat an operation a specific number of times.
+    **For Loop (Iterations)** - A numeric loop that executes a fixed number of times:
+    
+    <div className="flex justify-center">
+      <Image
+        src="/static/blocks/loop-1.png"
+        alt="For Loop with iterations"
+        width={500}
+        height={400}
+        className="my-6"
+      />
+    </div>
+    
+    Use this when you need to repeat an operation a specific number of times.
     
     ```
     Example: Run 5 times
@@ -55,7 +75,19 @@ Choose between two types of loops:
     ```
   </Tab>
   <Tab>
-    A collection-based loop that iterates over each item in an array or object. Use this when you need to process a collection of items.
+    **ForEach Loop (Collection)** - A collection-based loop that iterates over each item in an array or object:
+    
+    <div className="flex justify-center">
+      <Image
+        src="/static/blocks/loop-2.png"
+        alt="ForEach Loop with collection"
+        width={500}
+        height={400}
+        className="my-6"
+      />
+    </div>
+    
+    Use this when you need to process a collection of items.
     
     ```
     Example: Process ["apple", "banana", "orange"]

apps/docs/content/docs/blocks/meta.json

@@ -11,5 +11,6 @@
     "response",
     "router",
     "workflow"
-  ]
+  ],
+  "defaultOpen": false
 }

apps/docs/content/docs/blocks/parallel.mdx

@@ -1,22 +1,15 @@
 ---
 title: Parallel
-description: Execute multiple blocks concurrently for faster workflow processing
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
 
-The Parallel block is a container block in Sim that allows you to execute multiple instances of blocks concurrently.
+The Parallel block is a container block in Sim that allows you to execute multiple instances of blocks concurrently for faster workflow processing.
 
-<ThemeImage
-  lightSrc="/static/light/parallel-light.png"
-  darkSrc="/static/dark/parallel-dark.png"
-  alt="Parallel Block"
-  width={500}
-  height={300}
-/>
+The Parallel block supports two types of concurrent execution:
 
 <Callout type="info">
   Parallel blocks are container nodes that execute their contents multiple times simultaneously, unlike loops which execute sequentially.
@@ -49,7 +42,19 @@ Choose between two types of parallel execution:
 
 <Tabs items={['Count-based', 'Collection-based']}>
   <Tab>
-    Execute a fixed number of parallel instances. Use this when you need to run the same operation multiple times concurrently.
+    **Count-based Parallel** - Execute a fixed number of parallel instances:
+    
+    <div className="flex justify-center">
+      <Image
+        src="/static/blocks/parallel-1.png"
+        alt="Count-based parallel execution"
+        width={500}
+        height={400}
+        className="my-6"
+      />
+    </div>
+    
+    Use this when you need to run the same operation multiple times concurrently.
     
     ```
     Example: Run 5 parallel instances
@@ -61,7 +66,19 @@ Choose between two types of parallel execution:
     ```
   </Tab>
   <Tab>
-    Distribute a collection across parallel instances. Each instance processes one item from the collection simultaneously.
+    **Collection-based Parallel** - Distribute a collection across parallel instances:
+    
+    <div className="flex justify-center">
+      <Image
+        src="/static/blocks/parallel-2.png"
+        alt="Collection-based parallel execution"
+        width={500}
+        height={400}
+        className="my-6"
+      />
+    </div>
+    
+    Each instance processes one item from the collection simultaneously.
     
     ```
     Example: Process ["task1", "task2", "task3"] in parallel
@@ -105,8 +122,8 @@ After a parallel block completes, you can access aggregated results:
 <div className="mb-4 rounded-md border p-4">
   <h4 className="font-medium">Scenario: Get responses from multiple AI models</h4>
   <ol className="list-decimal pl-5 text-sm">
-    <li>Count-based parallel set to 3 instances</li>
-    <li>Inside parallel: Agent configured with different model per instance</li>
+    <li>Collection-based parallel over a list of model IDs (e.g., ["gpt-4o", "claude-3.7-sonnet", "gemini-2.5-pro"])</li>
+    <li>Inside parallel: Agent's model is set to the current item from the collection</li>
     <li>After parallel: Compare and select best response</li>
   </ol>
 </div>

apps/docs/content/docs/blocks/response.mdx

@@ -1,33 +1,61 @@
 ---
 title: Response
-description: Send a structured response back to API calls
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
 
-The Response block is the final step in your workflow that formats and returns data to whoever called your workflow. It's like the "return" statement for your entire workflow—it packages up results and sends them back.
+The Response block is the final step in your workflow that formats and sends a structured response back to API calls. It's like the "return" statement for your entire workflow—it packages up results and sends them back.
 
-<ThemeImage
-  lightSrc="/static/light/response-light.png"
-  darkSrc="/static/dark/response-dark.png"
-  alt="Response Block Configuration"
-  width={350}
-  height={175}
-/>
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/response.png"
+    alt="Response Block Configuration"
+    width={500}
+    height={400}
+    className="my-6"
+  />
+</div>
 
 <Callout type="info">
   Response blocks are terminal blocks - they end the workflow execution and cannot connect to other blocks.
 </Callout>
 
+## Overview
+
+The Response block enables you to:
+
+<Steps>
+  <Step>
+    <strong>Format API Responses</strong>: Structure workflow results into proper HTTP responses
+  </Step>
+  <Step>
+    <strong>Set Status Codes</strong>: Configure appropriate HTTP status codes based on workflow outcomes
+  </Step>
+  <Step>
+    <strong>Control Headers</strong>: Add custom headers for API responses and webhooks
+  </Step>
+  <Step>
+    <strong>Transform Data</strong>: Convert workflow variables into client-friendly response formats
+  </Step>
+</Steps>
+
+## How It Works
+
+The Response block finalizes workflow execution:
+
+1. **Collect Data** - Gathers variables and outputs from previous blocks
+2. **Format Response** - Structures data according to your configuration
+3. **Set HTTP Details** - Applies status codes and headers
+4. **Send Response** - Returns the formatted response to the API caller
+
 ## When You Need Response Blocks
 
-**API Endpoints**: When your workflow is called via API, Response blocks format the return data
-**Webhooks**: Return confirmation or data back to the calling system
-**Testing**: See formatted results when testing your workflow
-**Data Export**: Structure data for external systems or reports
+- **API Endpoints**: When your workflow is called via API, Response blocks format the return data
+- **Webhooks**: Return confirmation or data back to the calling system
+- **Testing**: See formatted results when testing your workflow
 
 ## Two Ways to Build Responses
 
@@ -83,9 +111,9 @@ Set the HTTP status code for the response. Common status codes include:
   </Tab>
 </Tabs>
 
-<p className="mt-4 text-sm text-gray-600 dark:text-gray-400">
+<div className="mt-4 text-sm text-gray-600 dark:text-gray-400">
   Default status code is 200 if not specified.
-</p>
+</div>
 
 ### Response Headers
 
@@ -99,27 +127,90 @@ Headers are configured as key-value pairs:
 | Cache-Control | no-cache |
 | X-API-Version | 1.0 |
 
+## Example Use Cases
+
+### API Endpoint Response
+
+<div className="mb-4 rounded-md border p-4">
+  <h4 className="font-medium">Scenario: Return structured data from a search API</h4>
+  <ol className="list-decimal pl-5 text-sm">
+    <li>Workflow processes search query and retrieves results</li>
+    <li>Function block formats and paginates results</li>
+    <li>Response block returns JSON with data, pagination, and metadata</li>
+    <li>Client receives structured response with 200 status</li>
+  </ol>
+</div>
+
+### Webhook Confirmation
+
+<div className="mb-4 rounded-md border p-4">
+  <h4 className="font-medium">Scenario: Acknowledge webhook receipt and processing</h4>
+  <ol className="list-decimal pl-5 text-sm">
+    <li>Webhook trigger receives external system data</li>
+    <li>Workflow processes the incoming data</li>
+    <li>Response block returns confirmation with processing status</li>
+    <li>External system receives acknowledgment</li>
+  </ol>
+</div>
+
+### Error Response Handling
+
+<div className="mb-4 rounded-md border p-4">
+  <h4 className="font-medium">Scenario: Return appropriate error responses</h4>
+  <ol className="list-decimal pl-5 text-sm">
+    <li>Condition block detects validation failure or system error</li>
+    <li>Router directs to error handling path</li>
+    <li>Response block returns 400/500 status with error details</li>
+    <li>Client receives structured error information</li>
+  </ol>
+</div>
+
 ## Inputs and Outputs
 
-<Tabs items={['Inputs', 'Outputs']}>
+<Tabs items={['Configuration', 'Variables', 'Results']}>
   <Tab>
     <ul className="list-disc space-y-2 pl-6">
       <li>
-        <strong>data</strong> (JSON, optional): The JSON data to send in the response body
+        <strong>Response Data</strong>: JSON structure for response body
       </li>
       <li>
-        <strong>status</strong> (number, optional): HTTP status code (default: 200)
+        <strong>Status Code</strong>: HTTP status code (default: 200)
       </li>
       <li>
-        <strong>headers</strong> (JSON, optional): Additional response headers
+        <strong>Headers</strong>: Custom HTTP headers as key-value pairs
+      </li>
+      <li>
+        <strong>Mode</strong>: Builder or Editor mode for response construction
       </li>
     </ul>
   </Tab>
   <Tab>
     <ul className="list-disc space-y-2 pl-6">
-      <li><strong>data</strong>: The response body data</li>
-      <li><strong>status</strong>: HTTP status code</li>
-      <li><strong>headers</strong>: Response headers</li>
+      <li>
+        <strong>response.data</strong>: The structured response body
+      </li>
+      <li>
+        <strong>response.status</strong>: HTTP status code sent
+      </li>
+      <li>
+        <strong>response.headers</strong>: Headers included in response
+      </li>
+      <li>
+        <strong>response.success</strong>: Boolean indicating successful completion
+      </li>
+    </ul>
+  </Tab>
+  <Tab>
+    <ul className="list-disc space-y-2 pl-6">
+      <li>
+        <strong>HTTP Response</strong>: Complete response sent to API caller
+      </li>
+      <li>
+        <strong>Workflow Termination</strong>: Ends workflow execution
+      </li>
+      <li>
+        <strong>Access</strong>: Response blocks are terminal - no subsequent blocks
+      </li>
     </ul>
   </Tab>
 </Tabs>
@@ -146,36 +237,6 @@ Use the `<variable.name>` syntax to dynamically insert workflow variables into y
   Variable names are case-sensitive and must match exactly with the variables available in your workflow.
 </Callout>
 
-## Example Usage
-
-Here's an example of how a Response block might be configured for a user search API:
-
-```yaml
-data: |
-  {
-    "success": true,
-    "data": {
-      "users": "<variable.searchResults>",
-      "pagination": {
-        "page": "<variable.currentPage>",
-        "limit": "<variable.pageSize>",
-        "total": "<variable.totalUsers>"
-      }
-    },
-    "query": {
-      "searchTerm": "<variable.searchTerm>",
-      "filters": "<variable.appliedFilters>"
-    },
-    "timestamp": "<variable.timestamp>"
-  }
-status: 200
-headers:
-  - key: X-Total-Count
-    value: <variable.totalUsers>
-  - key: Cache-Control
-    value: public, max-age=300
-```
-
 ## Best Practices
 
 - **Use meaningful status codes**: Choose appropriate HTTP status codes that accurately reflect the outcome of the workflow

apps/docs/content/docs/blocks/router.mdx

@@ -1,24 +1,25 @@
 ---
 title: Router
-description: Route workflow execution based on specific conditions or logic
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
 import { Video } from '@/components/ui/video'
 
-The Router block uses AI to intelligently decide which path your workflow should take next. Unlike Condition blocks that use simple rules, Router blocks can understand context and make smart routing decisions based on content analysis.
+The Router block uses AI to intelligently decide which path your workflow should take next, routing workflow execution based on specific conditions or logic. Unlike Condition blocks that use simple rules, Router blocks can understand context and make smart routing decisions based on content analysis.
 
-<ThemeImage
-  lightSrc="/static/light/router-light.png"
-  darkSrc="/static/dark/router-dark.png"
-  alt="Router Block with Multiple Paths"
-  width={350}
-  height={175}
-/>
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/router.png"
+    alt="Router Block with Multiple Paths"
+    width={500}
+    height={400}
+    className="my-6"
+  />
+</div>
 
 ## Overview
 
@@ -104,7 +105,7 @@ Choose an AI model to power the routing decision:
 **Local Models**: Any model running on Ollama 
 
 <div className="w-full max-w-2xl mx-auto overflow-hidden rounded-lg">
-  <Video src="router-model-dropdown.mp4" />
+  <Video src="router-model-dropdown.mp4" width={500} height={350} />
 </div>
 
 **Recommendation**: Use models with strong reasoning capabilities like GPT-4o or Claude 3.7 Sonnet for more accurate routing decisions.
@@ -117,9 +118,10 @@ Your API key for the selected LLM provider. This is securely stored and used for
 
 After a router makes a decision, you can access its outputs:
 
-- **`<router.content>`**: Summary of the routing decision made
+- **`<router.prompt>`**: Summary of the routing prompt used
 - **`<router.selected_path>`**: Details of the chosen destination block
 - **`<router.tokens>`**: Token usage statistics from the LLM
+- **`<router.cost>`**: Cost summary for the routing call (input, output, total)
 - **`<router.model>`**: The model used for decision-making
 
 ## Advanced Features
@@ -135,34 +137,9 @@ Target Block 2: "Billing inquiries, subscription changes, payment issues"
 Target Block 3: "General questions, feedback, feature requests"
 ```
 
-### Multi-Model Routing
-
-Use different models for different routing scenarios:
-
-```javascript
-// Fast routing for simple cases
-Model: GPT-4o-mini
-Criteria: Simple, common routing patterns
-
-// Complex routing for nuanced decisions
-Model: Claude 3.7 Sonnet
-Criteria: Complex content analysis required
-```
-
-### Fallback Handling
-
-Implement robust fallback mechanisms:
-
-```javascript
-// Router configuration
-Primary Targets: ["Support", "Sales", "Technical"]
-Fallback Target: "General" // Default when no specific match
-Confidence Threshold: 0.7 // Minimum confidence for routing
-```
-
 ## Inputs and Outputs
 
-<Tabs items={['Configuration', 'Variables', 'Results']}>
+<Tabs items={['Configuration', 'Variables']}>
   <Tab>
     <ul className="list-disc space-y-2 pl-6">
       <li>
@@ -182,7 +159,7 @@ Confidence Threshold: 0.7 // Minimum confidence for routing
   <Tab>
     <ul className="list-disc space-y-2 pl-6">
       <li>
-        <strong>router.content</strong>: Summary of routing decision
+        <strong>router.prompt</strong>: Summary of routing prompt used
       </li>
       <li>
         <strong>router.selected_path</strong>: Details of chosen destination
@@ -190,24 +167,14 @@ Confidence Threshold: 0.7 // Minimum confidence for routing
       <li>
         <strong>router.tokens</strong>: Token usage statistics
       </li>
+      <li>
+        <strong>router.cost</strong>: Cost summary for the routing call (input, output, total)
+      </li>
       <li>
         <strong>router.model</strong>: Model used for decision-making
       </li>
     </ul>
   </Tab>
-  <Tab>
-    <ul className="list-disc space-y-2 pl-6">
-      <li>
-        <strong>Routing Decision</strong>: Primary path selection result
-      </li>
-      <li>
-        <strong>Decision Context</strong>: Analysis summary and reasoning
-      </li>
-      <li>
-        <strong>Access</strong>: Available in blocks after the router
-      </li>
-    </ul>
-  </Tab>
 </Tabs>
 
 ## Example Use Cases

apps/docs/content/docs/blocks/workflow.mdx

@@ -1,22 +1,23 @@
 ---
 title: Workflow
-description: Execute other workflows as reusable components within your current workflow
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
 
-The Workflow block allows you to execute other workflows as reusable components within your current workflow. This powerful feature enables modular design, code reuse, and the creation of complex nested workflows that can be composed from smaller, focused workflows.
+The Workflow block allows you to execute other workflows as reusable components within your current workflow. This enables modular design, code reuse, and the creation of complex nested workflows that can be composed from smaller, focused workflows.
 
-<ThemeImage
-  lightSrc="/static/light/workflow-light.png"
-  darkSrc="/static/dark/workflow-dark.png"
-  alt="Workflow Block"
-  width={300}
-  height={175}
-/>
+<div className="flex justify-center">
+  <Image
+    src="/static/blocks/workflow.png"
+    alt="Workflow Block"
+    width={500}
+    height={350}
+    className="my-6"
+  />
+</div>
 
 <Callout type="info">
   Workflow blocks enable modular design by allowing you to compose complex workflows from smaller, reusable components.
@@ -46,9 +47,9 @@ The Workflow block serves as a bridge between workflows, enabling you to:
 The Workflow block:
 
 1. Takes a reference to another workflow in your workspace
-2. Passes input data from the current workflow to the child workflow
+2. Passes input data from the current workflow to the child workflow (available via start.input)
 3. Executes the child workflow in an isolated context
-4. Returns the results back to the parent workflow for further processing
+4. Returns the result back to the parent workflow for further processing
 
 ## Configuration Options
 
@@ -60,26 +61,6 @@ Choose which workflow to execute from a dropdown list of available workflows in
 - Workflows shared with you by other team members
 - Both enabled and disabled workflows (though only enabled workflows can be executed)
 
-### Input Data
-
-Define the data to pass to the child workflow:
-
-- **Single Variable Input**: Select a variable or block output to pass to the child workflow
-- **Variable References**: Use `<variable.name>` to reference workflow variables
-- **Block References**: Use `<blockName.field>` to reference outputs from previous blocks
-- **Automatic Mapping**: The selected data is automatically available as `start.input` in the child workflow
-- **Optional**: The input field is optional - child workflows can run without input data
-- **Type Preservation**: Variable types (strings, numbers, objects, etc.) are preserved when passed to the child workflow
-
-### Accessing Results
-
-After a workflow executes, you can access its outputs:
-
-- **`<workflow.response>`**: The complete output from the child workflow
-- **`<workflow.name>`**: The name of the executed child workflow
-- **`<workflow.success>`**: Boolean indicating successful completion
-- **`<workflow.error>`**: Error details if the workflow failed
-- **`<workflow.execution_time>`**: Time taken to execute the workflow
 
 ### Execution Context
 
@@ -88,58 +69,12 @@ The child workflow executes with:
 - Its own isolated execution context
 - Access to the same workspace resources (API keys, environment variables)
 - Proper workspace membership and permission checks
-- Independent logging and monitoring
-
-## Safety and Limitations
-
-To prevent infinite recursion and ensure system stability, the Workflow block includes several safety mechanisms:
+- Nested tracespan in the execution log
 
 <Callout type="warning">
   **Cycle Detection**: The system automatically detects and prevents circular dependencies between workflows to avoid infinite loops.
 </Callout>
 
-- **Maximum Depth Limit**: Nested workflows are limited to a maximum depth of 10 levels
-- **Cycle Detection**: Automatic detection and prevention of circular workflow dependencies
-- **Timeout Protection**: Child workflows inherit timeout settings to prevent indefinite execution
-- **Resource Limits**: Memory and execution time limits apply to prevent resource exhaustion
-
-## Advanced Features
-
-### Dynamic Workflow Selection
-
-Select workflows dynamically based on runtime conditions:
-
-```javascript
-// In a Function block before the Workflow block
-const workflowId = <condition.result> ? 'premium-workflow' : 'standard-workflow';
-return { selectedWorkflow: workflowId };
-```
-
-### Error Handling and Fallbacks
-
-Implement robust error handling for child workflows:
-
-```javascript
-// In a Function block after the Workflow block
-if (!<workflow.success>) {
-  console.error('Child workflow failed:', <workflow.error>);
-  // Implement fallback logic
-  return { fallback: true, error: <workflow.error> };
-}
-return <workflow.response>;
-```
-
-### Workflow Chaining
-
-Chain multiple workflows together:
-
-```javascript
-// Pass output from one workflow to another
-Workflow 1 Input: <start.input>
-Workflow 2 Input: <workflow1.response>
-Workflow 3 Input: <workflow2.response>
-```
-
 ## Inputs and Outputs
 
 <Tabs items={['Configuration', 'Variables', 'Results']}>
@@ -158,20 +93,17 @@ Workflow 3 Input: <workflow2.response>
   </Tab>
   <Tab>
     <ul className="list-disc space-y-2 pl-6">
-      <li>
-        <strong>workflow.response</strong>: Complete output from child workflow
-      </li>
-      <li>
-        <strong>workflow.name</strong>: Name of executed child workflow
-      </li>
       <li>
         <strong>workflow.success</strong>: Boolean indicating completion status
       </li>
       <li>
-        <strong>workflow.error</strong>: Error details if workflow failed
+        <strong>workflow.childWorkflowName</strong>: Name of executed child workflow
       </li>
       <li>
-        <strong>workflow.execution_time</strong>: Time taken to execute
+        <strong>workflow.result</strong>: Result returned by the child workflow
+      </li>
+      <li>
+        <strong>workflow.error</strong>: Error details if workflow failed
       </li>
     </ul>
   </Tab>
@@ -228,32 +160,10 @@ Workflow 3 Input: <workflow2.response>
   </ol>
 </div>
 
-### Example: Customer Validation Workflow
-
-```javascript title="validation-workflow.js"
-// Main workflow passes customer data to validation workflow
-const customerData = <start.input>;
-
-// Validation workflow processes the data
-const emailValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(customerData.email);
-const phoneValid = /^\+?[1-9]\d{1,14}$/.test(customerData.phone);
-
-return {
-  customer: customerData,
-  validation: {
-    email: emailValid,
-    phone: phoneValid,
-    overall: emailValid && phoneValid
-  }
-};
-```
-
 ## Best Practices
 
 - **Keep workflows focused**: Design child workflows to handle specific, well-defined tasks with clear inputs and outputs
 - **Minimize nesting depth**: Avoid deeply nested workflow hierarchies for better maintainability and performance
 - **Handle errors gracefully**: Implement proper error handling for child workflow failures and provide fallback mechanisms
-- **Document dependencies**: Clearly document which workflows depend on others and maintain dependency maps
 - **Test independently**: Ensure child workflows can be tested and validated independently from parent workflows
-- **Monitor performance**: Be aware that nested workflows can impact overall execution time and resource usage
 - **Use semantic naming**: Give workflows descriptive names that clearly indicate their purpose and functionality

apps/docs/content/docs/connections/accessing-data.mdx

@@ -1,190 +0,0 @@
----
-title: Accessing Connected Data
-description: Techniques for accessing and manipulating data from connected blocks
----
-
-import { Callout } from 'fumadocs-ui/components/callout'
-import { File, Files, Folder } from 'fumadocs-ui/components/files'
-
-Once blocks are connected, you can access data from source blocks in destination blocks using connection tags and various data access techniques.
-
-## Basic Data Access
-
-The simplest way to access data is through direct references using connection tags:
-
-<Files>
-  <File name="Simple Property" annotation="<block.content>" />
-  <File name="Nested Property" annotation="<block.tokens.total>" />
-  <File name="Array Element" annotation="<block.items[0].name>" />
-  <File name="Complex Path" annotation="<block.data.users[2].profile.email>" />
-</Files>
-
-## Advanced Data Access Techniques
-
-### Array Access
-
-You can access array elements using square bracket notation:
-
-```javascript
-// Access the first item in an array
-<block.items[0]>
-
-// Access a specific property of an array item
-<block.items[2].name>
-
-// Access the last item in an array (in Function blocks)
-const items = input.block.items;
-const lastItem = items[items.length - 1];
-```
-
-### Object Property Access
-
-Access object properties using dot notation:
-
-```javascript
-// Access a simple property
-<block.content>
-
-// Access a nested property
-<block.data.user.profile.name>
-
-// Access a property with special characters (in Function blocks)
-const data = input.block.data;
-const specialProp = data['property-with-dashes'];
-```
-
-### Dynamic References
-
-Connection references are evaluated at runtime, allowing for dynamic data flow through your workflow:
-
-```javascript
-// In a Function block, you can access connected data
-const userName = input.userBlock.name;
-const orderTotal = input.apiBlock.body.order.total;
-
-// Process the data
-const discount = orderTotal > 100 ? 0.1 : 0;
-const finalPrice = orderTotal * (1 - discount);
-
-// Return the result
-return {
-  userName,
-  originalTotal: orderTotal,
-  discount: discount * 100 + '%',
-  finalPrice
-};
-```
-
-## Data Transformation
-
-### Using Function Blocks
-
-Function blocks are the most powerful way to transform data between connections:
-
-```javascript
-// Example: Transform API response data
-const apiResponse = input.apiBlock.data;
-const transformedData = {
-  users: apiResponse.results.map(user => ({
-    id: user.id,
-    fullName: `${user.firstName} ${user.lastName}`,
-    email: user.email.toLowerCase(),
-    isActive: user.status === 'active'
-  })),
-  totalCount: apiResponse.count,
-  timestamp: new Date().toISOString()
-};
-
-return transformedData;
-```
-
-### String Interpolation
-
-You can combine connection tags with static text:
-
-```
-Hello, <userBlock.name>! Your order #<orderBlock.id> has been processed.
-```
-
-### Conditional Content
-
-In Function blocks, you can create conditional content based on connected data:
-
-```javascript
-const user = input.userBlock;
-const orderTotal = input.orderBlock.total;
-
-let message = `Thank you for your order, ${user.name}!`;
-
-if (orderTotal > 100) {
-  message += " You've qualified for free shipping!";
-} else {
-  message += ` Add $${(100 - orderTotal).toFixed(2)} more to qualify for free shipping.`;
-}
-
-return { message };
-```
-
-## Handling Missing Data
-
-It's important to handle cases where connected data might be missing or null:
-
-<Callout type="warning">
-  Always validate connected data before using it, especially when accessing nested properties or
-  array elements.
-</Callout>
-
-### Default Values
-
-In Function blocks, you can provide default values for missing data:
-
-```javascript
-const userName = input.userBlock?.name || 'Guest'
-const items = input.orderBlock?.items || []
-const total = input.orderBlock?.total ?? 0
-```
-
-### Conditional Checks
-
-Check if data exists before accessing nested properties:
-
-```javascript
-let userEmail = 'No email provided'
-if (input.userBlock && input.userBlock.contact && input.userBlock.contact.email) {
-  userEmail = input.userBlock.contact.email
-}
-```
-
-### Optional Chaining
-
-In Function blocks, use optional chaining to safely access nested properties:
-
-```javascript
-const userCity = input.userBlock?.address?.city
-const firstItemName = input.orderBlock?.items?.[0]?.name
-```
-
-## Debugging Connection Data
-
-When troubleshooting connection issues, these techniques can help:
-
-1. **Log Data**: In Function blocks, use `console.log()` to inspect connected data
-2. **Return Full Objects**: Return the full input object to see all available data
-3. **Check Types**: Verify the data types of connected values
-4. **Validate Paths**: Ensure you're using the correct path to access nested data
-
-```javascript
-// Example debugging function
-function debugConnections() {
-  console.log('All inputs:', input)
-  console.log('User data type:', typeof input.userBlock)
-  console.log('Order items:', input.orderBlock?.items)
-
-  return {
-    debug: true,
-    allInputs: input,
-    userExists: !!input.userBlock,
-    orderItemCount: input.orderBlock?.items?.length || 0,
-  }
-}
-```

apps/docs/content/docs/connections/basics.mdx

@@ -1,6 +1,5 @@
 ---
 title: Connection Basics
-description: Learn how connections work in Sim
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
@@ -8,7 +7,7 @@ import { Step, Steps } from 'fumadocs-ui/components/steps'
 
 ## How Connections Work
 
-Connections are the pathways that allow data to flow between blocks in your workflow. When you connect two blocks in Sim, you're establishing a data flow relationship that defines how information passes from one block to another.
+Connections are the pathways that allow data to flow between blocks in your workflow. In Sim, connections define how information passes from one block to another, enabling data flow throughout your workflow.
 
 <Callout type="info">
   Each connection represents a directed relationship where data flows from a source block's output
@@ -28,9 +27,6 @@ Connections are the pathways that allow data to flow between blocks in your work
   <Step>
     <strong>Confirm Connection</strong>: Release to create the connection
   </Step>
-  <Step>
-    <strong>Configure (Optional)</strong>: Some connections may require additional configuration
-  </Step>
 </Steps>
 
 ### Connection Flow
@@ -42,35 +38,7 @@ The flow of data through connections follows these principles:
 3. **Data Transformation**: Data may be transformed as it passes between blocks
 4. **Conditional Paths**: Some blocks (like Router and Condition) can direct flow to different paths
 
-### Connection Visualization
-
-Connections are visually represented in the workflow editor:
-
-- **Solid Lines**: Active connections that will pass data
-- **Animated Flow**: During execution, data flow is visualized along connections
-- **Color Coding**: Different connection types may have different colors
-- **Connection Tags**: Visual indicators showing what data is available
-
-### Managing Connections
-
-You can manage your connections in several ways:
-
-- **Delete**: Click on a connection and press Delete or use the context menu
-- **Reroute**: Drag a connection to change its path
-- **Inspect**: Click on a connection to see details about the data being passed
-- **Disable**: Temporarily disable a connection without deleting it
-
 <Callout type="warning">
   Deleting a connection will immediately stop data flow between the blocks. Make sure this is
   intended before removing connections.
 </Callout>
-
-## Connection Compatibility
-
-Not all blocks can be connected to each other. Compatibility depends on:
-
-1. **Data Type Compatibility**: The output type must be compatible with the input type
-2. **Block Restrictions**: Some blocks may have restrictions on what they can connect to
-3. **Workflow Logic**: Connections must make logical sense in the context of your workflow
-
-The editor will indicate when connections are invalid or incompatible.

apps/docs/content/docs/connections/best-practices.mdx

@@ -1,208 +0,0 @@
----
-title: Connection Best Practices
-description: Recommended patterns for effective connection management
----
-
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Step, Steps } from 'fumadocs-ui/components/steps'
-
-## Workflow Organization
-
-### Organize Your Connections
-
-Keep your workflow clean and understandable by organizing connections logically:
-
-- **Minimize crossing connections** when possible to reduce visual complexity
-- **Group related blocks together** to make data flow more intuitive
-- **Use consistent flow direction** (typically left-to-right or top-to-bottom)
-- **Label complex connections** with descriptive names
-
-<Callout type="info">
-  A well-organized workflow is easier to understand, debug, and maintain. Take time to arrange your
-  blocks and connections in a logical manner.
-</Callout>
-
-### Connection Naming Conventions
-
-When working with multiple connections, consistent naming helps maintain clarity:
-
-<Steps>
-  <Step>
-    <strong>Use descriptive block names</strong>: Name blocks based on their function (e.g.,
-    "UserDataFetcher", "ResponseGenerator")
-  </Step>
-  <Step>
-    <strong>Be specific with connection references</strong>: Use clear variable names when
-    referencing connections in code
-  </Step>
-  <Step>
-    <strong>Document complex connections</strong>: Add comments explaining non-obvious data
-    transformations
-  </Step>
-</Steps>
-
-## Data Validation
-
-### Validate Data Flow
-
-Ensure that the data being passed between blocks is compatible:
-
-- **Check that required fields are available** in the source block
-- **Verify data types match expectations** before using them
-- **Use Function blocks to transform data** when necessary
-- **Handle missing or null values** with default values or conditional logic
-
-```javascript
-// Example: Validating and transforming data in a Function block
-function processUserData() {
-  // Validate required fields
-  if (!input.userBlock || !input.userBlock.id) {
-    return { error: 'Missing user data', valid: false }
-  }
-
-  // Transform and validate data types
-  const userId = String(input.userBlock.id)
-  const userName = input.userBlock.name || 'Unknown User'
-  const userScore = Number(input.userBlock.score) || 0
-
-  return {
-    valid: true,
-    user: {
-      id: userId,
-      name: userName,
-      score: userScore,
-      isHighScore: userScore > 100,
-    },
-  }
-}
-```
-
-## Documentation
-
-### Document Connection Purpose
-
-Add comments or descriptions to clarify the purpose of connections, especially in complex workflows:
-
-- **What data is being passed**: Document the key fields and their purpose
-- **Why this connection exists**: Explain the relationship between blocks
-- **Any transformations or conditions applied**: Note any data processing that occurs
-
-```javascript
-// Example: Documenting connection purpose in a Function block
-/*
- * This function processes user data from the UserFetcher block
- * and order history from the OrderHistory block to generate
- * personalized product recommendations.
- *
- * Input:
- * - userBlock: User profile data (id, preferences, history)
- * - orderBlock: Recent order history (items, dates, amounts)
- *
- * Output:
- * - recommendations: Array of recommended product IDs
- * - userSegment: Calculated user segment for marketing
- * - conversionProbability: Estimated likelihood of purchase
- */
-function generateRecommendations() {
-  // Implementation...
-}
-```
-
-## Testing and Debugging
-
-### Test Connection References
-
-Verify that connection references work as expected:
-
-- **Test with different input values** to ensure robustness
-- **Check edge cases** (empty values, large datasets, special characters)
-- **Ensure error handling for missing or invalid data**
-- **Use console logging in Function blocks** to debug connection issues
-
-```javascript
-// Example: Testing connection references with edge cases
-function testConnections() {
-  console.log('Testing connections...')
-
-  // Log all inputs for debugging
-  console.log('All inputs:', JSON.stringify(input, null, 2))
-
-  // Test for missing data
-  const hasUserData = !!input.userBlock
-  console.log('Has user data:', hasUserData)
-
-  // Test edge cases
-  const items = input.orderBlock?.items || []
-  console.log('Item count:', items.length)
-  console.log('Empty items test:', items.length === 0 ? 'Passed' : 'Failed')
-
-  // Return test results
-  return {
-    tests: {
-      hasUserData,
-      hasItems: items.length > 0,
-      hasLargeOrder: items.length > 10,
-    },
-  }
-}
-```
-
-## Performance Considerations
-
-### Optimize Data Flow
-
-Keep your workflows efficient by optimizing how data flows through connections:
-
-- **Pass only necessary data** between blocks to reduce memory usage
-- **Use Function blocks to filter large datasets** before passing them on
-- **Consider caching results** for expensive operations
-- **Break complex workflows into smaller, reusable components**
-
-```javascript
-// Example: Optimizing data flow by filtering
-function optimizeUserData() {
-  const userData = input.userBlock
-
-  // Only pass necessary fields to downstream blocks
-  return {
-    id: userData.id,
-    name: userData.name,
-    email: userData.email,
-    // Filter out unnecessary profile data, history, etc.
-  }
-}
-```
-
-## Security Best Practices
-
-### Secure Sensitive Data
-
-Protect sensitive information when using connections:
-
-- **Never expose API keys or credentials** in connection data
-- **Sanitize user input** before processing it
-- **Redact sensitive information** when logging connection data
-- **Use secure connections** for external API calls
-
-<Callout type="warning">
-  Be careful when logging connection data that might contain sensitive information. Always redact or
-  mask sensitive fields like passwords, API keys, or personal information.
-</Callout>
-
-## Advanced Patterns
-
-### Conditional Connections
-
-Use Condition blocks to create dynamic workflows:
-
-- **Route data based on content** to different processing paths
-- **Implement fallback paths** for error handling
-- **Create decision trees** for complex business logic
-
-### Feedback Loops
-
-Create more sophisticated workflows with feedback connections:
-
-- **Implement iterative processing** by connecting later blocks back to earlier ones
-- **Use Memory blocks** to store state between iterations
-- **Set termination conditions** to prevent infinite loops

apps/docs/content/docs/connections/data-structure.mdx

@@ -1,12 +1,11 @@
 ---
 title: Connection Data Structure
-description: Understanding the data structure of different block outputs
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 
-When you connect blocks, the output data structure from the source block determines what values are available in the destination block. Each block type produces a specific output structure that you can reference in downstream blocks.
+When you connect blocks, understanding the data structure of different block outputs is important because the output data structure from the source block determines what values are available in the destination block. Each block type produces a specific output structure that you can reference in downstream blocks.
 
 <Callout type="info">
   Understanding these data structures is essential for effectively using connection tags and
@@ -180,7 +179,7 @@ Some blocks may produce custom output structures based on their configuration:
 Many block outputs contain nested data structures. You can access these using dot notation in connection tags:
 
 ```
-<blockId.path.to.nested.data>
+<blockName.path.to.nested.data>
 ```
 
 For example:

apps/docs/content/docs/connections/meta.json

@@ -1,4 +1,5 @@
 {
   "title": "Connections",
-  "pages": ["basics", "tags", "data-structure", "accessing-data", "best-practices"]
+  "pages": ["basics", "tags", "data-structure"],
+  "defaultOpen": false
 }

apps/docs/content/docs/connections/tags.mdx

@@ -1,12 +1,11 @@
 ---
 title: Connection Tags
-description: Using connection tags to reference data between blocks
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Video } from '@/components/ui/video'
 
-Connection tags are visual representations of the data available from connected blocks. They provide an easy way to reference outputs from previous blocks in your workflow.
+Connection tags are visual representations of the data available from connected blocks, providing an easy way to reference data between blocks and outputs from previous blocks in your workflow.
 
 <div className="mx-auto w-full overflow-hidden rounded-lg">
   <Video src="connections.mp4" />
@@ -66,12 +65,12 @@ There are two primary ways to use connection tags in your workflows:
 Connection tags use a simple syntax to reference data:
 
 ```
-<blockId.path.to.data>
+<blockName.path.to.data>
 ```
 
 Where:
 
-- `blockId` is the identifier of the source block
+- `blockName` is the name of the source block
 - `path.to.data` is the path to the specific data field
 
 For example:

apps/docs/content/docs/copilot/index.mdx

@@ -1,15 +1,13 @@
 ---
 title: Copilot
-description: Build and edit workflows with Sim Copilot
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Card, Cards } from 'fumadocs-ui/components/card'
+import { Image } from '@/components/ui/image'
 import { MessageCircle, Package, Zap, Infinity as InfinityIcon, Brain, BrainCircuit } from 'lucide-react'
 
-## What is Copilot
-
-Copilot is your in-editor assistant that helps you build, understand, and improve workflows. It can:
+Copilot is your in-editor assistant that helps you build and edit workflows with Sim Copilot, as well as understand and improve them. It can:
 
 - **Explain**: Answer questions about Sim and your current workflow
 - **Guide**: Suggest edits and best practices
@@ -18,35 +16,57 @@ Copilot is your in-editor assistant that helps you build, understand, and improv
 <Callout type="info">
   Copilot is a Sim-managed service. For self-hosted deployments, generate a Copilot API key in the hosted app (sim.ai → Settings → Copilot)
   1. Go to [sim.ai](https://sim.ai) → Settings → Copilot and generate a Copilot API key
-2. Set `COPILOT_API_KEY` in your self-hosted environment to that value
-3. Host Sim on a publicly available DNS and set `NEXT_PUBLIC_APP_URL` and `BETTER_AUTH_URL` to that value (e.g., using ngrok)
+  2. Set `COPILOT_API_KEY` in your self-hosted environment to that value
 </Callout>
 
+## Context Menu (@)
+
+Use the `@` symbol to reference various resources and give Copilot more context about your workspace:
+
+<Image
+  src="/static/copilot/copilot-menu.png"
+  alt="Copilot context menu showing available reference options"
+  width={600}
+  height={400}
+/>
+
+The `@` menu provides access to:
+- **Chats**: Reference previous copilot conversations
+- **All workflows**: Reference any workflow in your workspace
+- **Workflow Blocks**: Reference specific blocks from workflows
+- **Blocks**: Reference block types and templates
+- **Knowledge**: Reference your uploaded documents and knowledgebase
+- **Docs**: Reference Sim documentation
+- **Templates**: Reference workflow templates
+- **Logs**: Reference execution logs and results
+
+This contextual information helps Copilot provide more accurate and relevant assistance for your specific use case.
+
 ## Modes
 
 <Cards>
-  <Card title="Ask">
-    <div className="flex items-start gap-3">
-      <span className="mt-0.5 inline-flex h-8 w-8 items-center justify-center rounded-md border border-border/50 bg-muted/60">
+  <Card
+    title={
+      <span className="inline-flex items-center gap-2">
         <MessageCircle className="h-4 w-4 text-muted-foreground" />
+        Ask
       </span>
-      <div>
-        <p className="m-0 text-sm">
-          Q&A mode for explanations, guidance, and suggestions without making changes to your workflow.
-        </p>
-      </div>
+    }
+  >
+    <div className="m-0 text-sm">
+      Q&A mode for explanations, guidance, and suggestions without making changes to your workflow.
     </div>
   </Card>
-  <Card title="Agent">
-    <div className="flex items-start gap-3">
-      <span className="mt-0.5 inline-flex h-8 w-8 items-center justify-center rounded-md border border-border/50 bg-muted/60">
+  <Card
+    title={
+      <span className="inline-flex items-center gap-2">
         <Package className="h-4 w-4 text-muted-foreground" />
+        Agent
       </span>
-      <div>
-        <p className="m-0 text-sm">
-          Build-and-edit mode. Copilot proposes specific edits (add blocks, wire variables, tweak settings) and applies them when you approve.
-        </p>
-      </div>
+    }
+  >
+    <div className="m-0 text-sm">
+      Build-and-edit mode. Copilot proposes specific edits (add blocks, wire variables, tweak settings) and applies them when you approve.
     </div>
   </Card>
 </Cards>
@@ -54,44 +74,89 @@ Copilot is your in-editor assistant that helps you build, understand, and improv
 ## Depth Levels
 
 <Cards>
-  <Card title="Fast">
-    <div className="flex items-start gap-3">
-      <span className="mt-0.5 inline-flex h-8 w-8 items-center justify-center rounded-md border border-border/50 bg-muted/60">
+  <Card
+    title={
+      <span className="inline-flex items-center gap-2">
         <Zap className="h-4 w-4 text-muted-foreground" />
+        Fast
       </span>
-      <div>
-        <p className="m-0 text-sm">Quickest and cheapest. Best for small edits, simple workflows, and minor tweaks.</p>
-      </div>
-    </div>
+    }
+  >
+    <div className="m-0 text-sm">Quickest and cheapest. Best for small edits, simple workflows, and minor tweaks.</div>
   </Card>
-  <Card title="Auto">
-    <div className="flex items-start gap-3">
-      <span className="mt-0.5 inline-flex h-8 w-8 items-center justify-center rounded-md border border-border/50 bg-muted/60">
+  <Card
+    title={
+      <span className="inline-flex items-center gap-2">
         <InfinityIcon className="h-4 w-4 text-muted-foreground" />
+        Auto
       </span>
-      <div>
-        <p className="m-0 text-sm">Balanced speed and reasoning. Recommended default for most tasks.</p>
-      </div>
-    </div>
+    }
+  >
+    <div className="m-0 text-sm">Balanced speed and reasoning. Recommended default for most tasks.</div>
   </Card>
-  <Card title="Pro">
-    <div className="flex items-start gap-3">
-      <span className="mt-0.5 inline-flex h-8 w-8 items-center justify-center rounded-md border border-border/50 bg-muted/60">
+  <Card
+    title={
+      <span className="inline-flex items-center gap-2">
         <Brain className="h-4 w-4 text-muted-foreground" />
+        Advanced
       </span>
-      <div>
-        <p className="m-0 text-sm">More reasoning for larger workflows and complex edits while staying performant.</p>
-      </div>
-    </div>
+    }
+  >
+    <div className="m-0 text-sm">More reasoning for larger workflows and complex edits while staying performant.</div>
   </Card>
-  <Card title="Max">
-    <div className="flex items-start gap-3">
-      <span className="mt-0.5 inline-flex h-8 w-8 items-center justify-center rounded-md border border-border/50 bg-muted/60">
+  <Card
+    title={
+      <span className="inline-flex items-center gap-2">
         <BrainCircuit className="h-4 w-4 text-muted-foreground" />
+        Behemoth
       </span>
-      <div>
-        <p className="m-0 text-sm">Maximum reasoning for deep planning, debugging, and complex architectural changes.</p>
-      </div>
-    </div>
+    }
+  >
+    <div className="m-0 text-sm">Maximum reasoning for deep planning, debugging, and complex architectural changes.</div>
   </Card>
-</Cards> 
+</Cards>
+
+### Mode Selection Interface
+
+You can easily switch between different reasoning modes using the mode selector in the Copilot interface:
+
+<Image
+  src="/static/copilot/copilot-models.png"
+  alt="Copilot mode selection showing Advanced mode with MAX toggle"
+  width={600}
+  height={300}
+/>
+
+The interface allows you to:
+- **Select reasoning level**: Choose from Fast, Auto, Advanced, or Behemoth
+- **Enable MAX mode**: Toggle for maximum reasoning capabilities when you need the most thorough analysis
+- **See mode descriptions**: Understand what each mode is optimized for
+
+Choose your mode based on the complexity of your task - use Fast for simple questions and Behemoth for complex architectural changes.
+
+## Billing and Cost Calculation
+
+### How Costs Are Calculated
+
+Copilot usage is billed per token from the underlying LLM:
+
+- **Input tokens**: billed at the provider's base rate (**at-cost**)
+- **Output tokens**: billed at **1.5×** the provider's base output rate
+
+```javascript
+copilotCost = (inputTokens × inputPrice + outputTokens × (outputPrice × 1.5)) / 1,000,000
+```
+
+| Component | Rate Applied         |
+|----------|----------------------|
+| Input    | inputPrice           |
+| Output   | outputPrice × 1.5    |
+
+<Callout type="warning">
+  Pricing shown reflects rates as of September 4, 2025. Check provider documentation for current pricing.
+</Callout>
+
+<Callout type="info">
+  Model prices are per million tokens. The calculation divides by 1,000,000 to get the actual cost. See <a href="/execution/costs">the Cost Calculation page</a> for background and examples.
+</Callout>
+

apps/docs/content/docs/copilot/meta.json

@@ -1,4 +1,5 @@
 {
   "title": "Copilot",
-  "pages": ["index"]
+  "pages": ["index"],
+  "defaultOpen": false
 }

apps/docs/content/docs/execution/advanced.mdx

@@ -1,214 +0,0 @@
----
-title: Logging and Cost Calculation
-description: Understanding workflow logs and how execution costs are calculated in Sim
----
-
-import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
-
-Sim provides comprehensive logging for workflow executions and automatic cost calculation for AI model usage.
-
-## Logging System
-
-Sim offers two complementary logging interfaces:
-
-### Real-Time Console (Manual Executions)
-
-During manual workflow execution, logs appear in real-time in the Console panel on the right side of the workflow editor:
-
-<ThemeImage
-  lightSrc="/static/light/console-panel-light.png"
-  darkSrc="/static/dark/console-panel-dark.png"
-  alt="Real-time Console Panel"
-  width={600}
-  height={400}
-/>
-
-The console shows:
-- Block execution progress with active block highlighting
-- Real-time outputs as blocks complete
-- Execution timing for each block
-- Success/error status indicators
-
-### Logs Page (All Executions)
-
-All workflow executions—whether triggered manually, via API, Chat, Schedule, or Webhook—are logged to the dedicated Logs page:
-
-<ThemeImage
-  lightSrc="/static/light/logs-page-light.png"
-  darkSrc="/static/dark/logs-page-dark.png"
-  alt="Logs Page"
-  width={600}
-  height={400}
-/>
-
-The Logs page provides:
-- Comprehensive filtering by time range, status, trigger type, folder, and workflow
-- Search functionality across all logs
-- Live mode for real-time updates
-- 7-day log retention (upgradeable for longer retention)
-
-## Log Details Sidebar
-
-Clicking on any log entry opens a detailed sidebar view:
-
-<ThemeImage
-  lightSrc="/static/light/logs-sidebar-light.png"
-  darkSrc="/static/dark/logs-sidebar-dark.png"
-  alt="Logs Sidebar Details"
-  width={600}
-  height={400}
-/>
-
-### Block Input/Output
-
-View the complete data flow for each block with tabs to switch between:
-
-<Tabs items={['Output', 'Input']}>
-  <Tab>
-    **Output Tab** shows the block's execution result:
-    - Structured data with JSON formatting
-    - Markdown rendering for AI-generated content
-    - Copy button for easy data extraction
-  </Tab>
-  
-  <Tab>
-    **Input Tab** displays what was passed to the block:
-    - Resolved variable values
-    - Referenced outputs from other blocks
-    - Environment variables used
-    - API keys are automatically redacted for security
-  </Tab>
-</Tabs>
-
-### Execution Timeline
-
-For workflow-level logs, view detailed execution metrics:
-- Start and end timestamps
-- Total workflow duration
-- Individual block execution times
-- Performance bottleneck identification
-
-### Model Breakdown
-
-For workflows using AI blocks, expand the Model Breakdown section to see:
-
-<ThemeImage
-  lightSrc="/static/light/model-breakdown-light.png"
-  darkSrc="/static/dark/model-breakdown-dark.png"
-  alt="Model Breakdown"
-  width={600}
-  height={400}
-/>
-
-- **Token Usage**: Input and output token counts for each model
-- **Cost Breakdown**: Individual costs per model and operation
-- **Model Distribution**: Which models were used and how many times
-- **Total Cost**: Aggregate cost for the entire workflow execution
-
-### Workflow Snapshot
-
-For any logged execution, click "View Snapshot" to see the exact workflow state at execution time:
-
-<ThemeImage
-  lightSrc="/static/light/workflow-snapshot-light.png"
-  darkSrc="/static/dark/workflow-snapshot-dark.png"
-  alt="Workflow Snapshot"
-  width={600}
-  height={400}
-/>
-
-The snapshot provides:
-- Frozen canvas showing the workflow structure
-- Block states and connections as they were during execution
-- Click any block to see its inputs and outputs
-- Useful for debugging workflows that have since been modified
-
-<Callout type="info">
-  Workflow snapshots are only available for executions after the enhanced logging system was introduced. Older migrated logs show a "Logged State Not Found" message.
-</Callout>
-
-## Cost Calculation
-
-Sim automatically calculates costs for all AI model usage:
-
-### How Costs Are Calculated
-
-Every workflow execution includes two cost components:
-
-**Base Execution Charge**: $0.001 per execution
-
-**AI Model Usage**: Variable cost based on token consumption
-```javascript
-modelCost = (inputTokens × inputPrice + outputTokens × outputPrice) / 1,000,000
-totalCost = baseExecutionCharge + modelCost
-```
-
-<Callout type="info">
-  AI model prices are per million tokens. The calculation divides by 1,000,000 to get the actual cost. Workflows without AI blocks only incur the base execution charge.
-</Callout>
-
-### Pricing Options
-
-<Tabs items={['Hosted Models', 'Bring Your Own API Key']}>
-  <Tab>
-    **Hosted Models** - Sim provides API keys with a 2.5x pricing multiplier:
-    
-    | Model | Base Price (Input/Output) | Hosted Price (Input/Output) |
-    |-------|---------------------------|----------------------------|
-    | GPT-4o | $2.50 / $10.00 | $6.25 / $25.00 |
-    | GPT-4.1 | $2.00 / $8.00 | $5.00 / $20.00 |
-    | o1 | $15.00 / $60.00 | $37.50 / $150.00 |
-    | o3 | $2.00 / $8.00 | $5.00 / $20.00 |
-    | Claude 3.5 Sonnet | $3.00 / $15.00 | $7.50 / $37.50 |
-    | Claude Opus 4.0 | $15.00 / $75.00 | $37.50 / $187.50 |
-    
-    *The 2.5x multiplier covers infrastructure and API management costs.*
-  </Tab>
-  
-  <Tab>
-    **Your Own API Keys** - Use any model at base pricing:
-    
-    | Provider | Models | Input / Output |
-    |----------|---------|----------------|
-    | Google | Gemini 2.5 | $0.15 / $0.60 |
-    | Deepseek | V3, R1 | $0.75 / $1.00 |
-    | xAI | Grok 4, Grok 3 | $5.00 / $25.00 |
-    | Groq | Llama 4 Scout | $0.40 / $0.60 |
-    | Cerebras | Llama 3.3 70B | $0.94 / $0.94 |
-    | Ollama | Local models | Free |
-    
-    *Pay providers directly with no markup*
-  </Tab>
-</Tabs>
-
-<Callout type="warning">
-  Pricing shown reflects rates as of July 14, 2025. Check provider documentation for current pricing.
-</Callout>
-
-### Cost Optimization
-
-<Accordions>
-  <Accordion title="Model Selection">
-    Choose models based on task complexity. Simple tasks can use GPT-4.1-nano ($0.10/$0.40) while complex reasoning might need o1 or Claude Opus.
-  </Accordion>
-  
-  <Accordion title="Prompt Engineering">
-    Well-structured, concise prompts reduce token usage without sacrificing quality.
-  </Accordion>
-  
-  <Accordion title="Local Models">
-    Use Ollama for non-critical tasks to eliminate API costs entirely.
-  </Accordion>
-</Accordions>
-
-## Usage Monitoring
-
-Monitor your usage and billing in Settings → Subscription:
-
-- **Current Usage**: Real-time usage and costs for the current period
-- **Usage Limits**: Plan limits with visual progress indicators
-- **Billing Details**: Projected charges and minimum commitments
-- **Plan Management**: Upgrade options and billing history

apps/docs/content/docs/execution/api.mdx

@@ -0,0 +1,536 @@
+---
+title: External API
+---
+
+import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { CodeBlock } from 'fumadocs-ui/components/codeblock'
+import { Video } from '@/components/ui/video'
+
+Sim provides a comprehensive external API for querying workflow execution logs and setting up webhooks for real-time notifications when workflows complete.
+
+## Authentication
+
+All API requests require an API key passed in the `x-api-key` header:
+
+```bash
+curl -H "x-api-key: YOUR_API_KEY" \
+  https://sim.ai/api/v1/logs?workspaceId=YOUR_WORKSPACE_ID
+```
+
+You can generate API keys from your user settings in the Sim dashboard.
+
+## Logs API
+
+All API responses include information about your workflow execution limits and usage:
+
+```json
+"limits": {
+  "workflowExecutionRateLimit": {
+    "sync": {
+      "limit": 60,        // Max sync workflow executions per minute
+      "remaining": 58,    // Remaining sync workflow executions
+      "resetAt": "..."    // When the window resets
+    },
+    "async": {
+      "limit": 60,        // Max async workflow executions per minute
+      "remaining": 59,    // Remaining async workflow executions
+      "resetAt": "..."    // When the window resets
+    }
+  },
+  "usage": {
+    "currentPeriodCost": 1.234,  // Current billing period usage in USD
+    "limit": 10,                  // Usage limit in USD
+    "plan": "pro",                // Current subscription plan
+    "isExceeded": false           // Whether limit is exceeded
+  }
+}
+```
+
+**Note:** The rate limits in the response body are for workflow executions. The rate limits for calling this API endpoint are in the response headers (`X-RateLimit-*`).
+
+### Query Logs
+
+Query workflow execution logs with extensive filtering options.
+
+<Tabs items={['Request', 'Response']}>
+  <Tab value="Request">
+    ```http
+    GET /api/v1/logs
+    ```
+
+    **Required Parameters:**
+    - `workspaceId` - Your workspace ID
+
+    **Optional Filters:**
+    - `workflowIds` - Comma-separated workflow IDs
+    - `folderIds` - Comma-separated folder IDs
+    - `triggers` - Comma-separated trigger types: `api`, `webhook`, `schedule`, `manual`, `chat`
+    - `level` - Filter by level: `info`, `error`
+    - `startDate` - ISO timestamp for date range start
+    - `endDate` - ISO timestamp for date range end
+    - `executionId` - Exact execution ID match
+    - `minDurationMs` - Minimum execution duration in milliseconds
+    - `maxDurationMs` - Maximum execution duration in milliseconds
+    - `minCost` - Minimum execution cost
+    - `maxCost` - Maximum execution cost
+    - `model` - Filter by AI model used
+
+    **Pagination:**
+    - `limit` - Results per page (default: 100)
+    - `cursor` - Cursor for next page
+    - `order` - Sort order: `desc`, `asc` (default: desc)
+
+    **Detail Level:**
+    - `details` - Response detail level: `basic`, `full` (default: basic)
+    - `includeTraceSpans` - Include trace spans (default: false)
+    - `includeFinalOutput` - Include final output (default: false)
+  </Tab>
+  <Tab value="Response">
+    ```json
+    {
+      "data": [
+        {
+          "id": "log_abc123",
+          "workflowId": "wf_xyz789",
+          "executionId": "exec_def456",
+          "level": "info",
+          "trigger": "api",
+          "startedAt": "2025-01-01T12:34:56.789Z",
+          "endedAt": "2025-01-01T12:34:57.123Z",
+          "totalDurationMs": 334,
+          "cost": {
+            "total": 0.00234
+          },
+          "files": null
+        }
+      ],
+      "nextCursor": "eyJzIjoiMjAyNS0wMS0wMVQxMjozNDo1Ni43ODlaIiwiaWQiOiJsb2dfYWJjMTIzIn0",
+      "limits": {
+        "workflowExecutionRateLimit": {
+          "sync": {
+            "limit": 60,
+            "remaining": 58,
+            "resetAt": "2025-01-01T12:35:56.789Z"
+          },
+          "async": {
+            "limit": 60,
+            "remaining": 59,
+            "resetAt": "2025-01-01T12:35:56.789Z"
+          }
+        },
+        "usage": {
+          "currentPeriodCost": 1.234,
+          "limit": 10,
+          "plan": "pro",
+          "isExceeded": false
+        }
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### Get Log Details
+
+Retrieve detailed information about a specific log entry.
+
+<Tabs items={['Request', 'Response']}>
+  <Tab value="Request">
+    ```http
+    GET /api/v1/logs/{id}
+    ```
+  </Tab>
+  <Tab value="Response">
+    ```json
+    {
+      "data": {
+        "id": "log_abc123",
+        "workflowId": "wf_xyz789",
+        "executionId": "exec_def456",
+        "level": "info",
+        "trigger": "api",
+        "startedAt": "2025-01-01T12:34:56.789Z",
+        "endedAt": "2025-01-01T12:34:57.123Z",
+        "totalDurationMs": 334,
+        "workflow": {
+          "id": "wf_xyz789",
+          "name": "My Workflow",
+          "description": "Process customer data"
+        },
+        "executionData": {
+          "traceSpans": [...],
+          "finalOutput": {...}
+        },
+        "cost": {
+          "total": 0.00234,
+          "tokens": {
+            "prompt": 123,
+            "completion": 456,
+            "total": 579
+          },
+          "models": {
+            "gpt-4o": {
+              "input": 0.001,
+              "output": 0.00134,
+              "total": 0.00234,
+              "tokens": {
+                "prompt": 123,
+                "completion": 456,
+                "total": 579
+              }
+            }
+          }
+        },
+        "limits": {
+          "workflowExecutionRateLimit": {
+            "sync": {
+              "limit": 60,
+              "remaining": 58,
+              "resetAt": "2025-01-01T12:35:56.789Z"
+            },
+            "async": {
+              "limit": 60,
+              "remaining": 59,
+              "resetAt": "2025-01-01T12:35:56.789Z"
+            }
+          },
+          "usage": {
+            "currentPeriodCost": 1.234,
+            "limit": 10,
+            "plan": "pro",
+            "isExceeded": false
+          }
+        }
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+### Get Execution Details
+
+Retrieve execution details including the workflow state snapshot.
+
+<Tabs items={['Request', 'Response']}>
+  <Tab value="Request">
+    ```http
+    GET /api/v1/logs/executions/{executionId}
+    ```
+  </Tab>
+  <Tab value="Response">
+    ```json
+    {
+      "executionId": "exec_def456",
+      "workflowId": "wf_xyz789",
+      "workflowState": {
+        "blocks": {...},
+        "edges": [...],
+        "loops": {...},
+        "parallels": {...}
+      },
+      "executionMetadata": {
+        "trigger": "api",
+        "startedAt": "2025-01-01T12:34:56.789Z",
+        "endedAt": "2025-01-01T12:34:57.123Z",
+        "totalDurationMs": 334,
+        "cost": {...}
+      }
+    }
+    ```
+  </Tab>
+</Tabs>
+
+## Webhook Subscriptions
+
+Get real-time notifications when workflow executions complete. Webhooks are configured through the Sim UI in the workflow editor.
+
+### Configuration
+
+Webhooks can be configured for each workflow through the workflow editor UI. Click the webhook icon in the control bar to set up your webhook subscriptions.
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="configure-webhook.mp4" width={700} height={450} />
+</div>
+
+**Available Configuration Options:**
+- `url`: Your webhook endpoint URL
+- `secret`: Optional secret for HMAC signature verification
+- `includeFinalOutput`: Include the workflow's final output in the payload
+- `includeTraceSpans`: Include detailed execution trace spans
+- `includeRateLimits`: Include the workflow owner's rate limit information
+- `includeUsageData`: Include the workflow owner's usage and billing data
+- `levelFilter`: Array of log levels to receive (`info`, `error`)
+- `triggerFilter`: Array of trigger types to receive (`api`, `webhook`, `schedule`, `manual`, `chat`)
+- `active`: Enable/disable the webhook subscription
+
+### Webhook Payload
+
+When a workflow execution completes, Sim sends a POST request to your webhook URL:
+
+```json
+{
+  "id": "evt_123",
+  "type": "workflow.execution.completed",
+  "timestamp": 1735925767890,
+  "data": {
+    "workflowId": "wf_xyz789",
+    "executionId": "exec_def456",
+    "status": "success",
+    "level": "info",
+    "trigger": "api",
+    "startedAt": "2025-01-01T12:34:56.789Z",
+    "endedAt": "2025-01-01T12:34:57.123Z",
+    "totalDurationMs": 334,
+    "cost": {
+      "total": 0.00234,
+      "tokens": {
+        "prompt": 123,
+        "completion": 456,
+        "total": 579
+      },
+      "models": {
+        "gpt-4o": {
+          "input": 0.001,
+          "output": 0.00134,
+          "total": 0.00234,
+          "tokens": {
+            "prompt": 123,
+            "completion": 456,
+            "total": 579
+          }
+        }
+      }
+    },
+    "files": null,
+    "finalOutput": {...},  // Only if includeFinalOutput=true
+    "traceSpans": [...],   // Only if includeTraceSpans=true
+    "rateLimits": {...},   // Only if includeRateLimits=true
+    "usage": {...}         // Only if includeUsageData=true
+  },
+  "links": {
+    "log": "/v1/logs/log_abc123",
+    "execution": "/v1/logs/executions/exec_def456"
+  }
+}
+```
+
+### Webhook Headers
+
+Each webhook request includes these headers:
+
+- `sim-event`: Event type (always `workflow.execution.completed`)
+- `sim-timestamp`: Unix timestamp in milliseconds
+- `sim-delivery-id`: Unique delivery ID for idempotency
+- `sim-signature`: HMAC-SHA256 signature for verification (if secret configured)
+- `Idempotency-Key`: Same as delivery ID for duplicate detection
+
+### Signature Verification
+
+If you configure a webhook secret, verify the signature to ensure the webhook is from Sim:
+
+<Tabs items={['Node.js', 'Python']}>
+  <Tab value="Node.js">
+    ```javascript
+    import crypto from 'crypto';
+
+    function verifyWebhookSignature(body, signature, secret) {
+      const [timestampPart, signaturePart] = signature.split(',');
+      const timestamp = timestampPart.replace('t=', '');
+      const expectedSignature = signaturePart.replace('v1=', '');
+      
+      const signatureBase = `${timestamp}.${body}`;
+      const hmac = crypto.createHmac('sha256', secret);
+      hmac.update(signatureBase);
+      const computedSignature = hmac.digest('hex');
+      
+      return computedSignature === expectedSignature;
+    }
+
+    // In your webhook handler
+    app.post('/webhook', (req, res) => {
+      const signature = req.headers['sim-signature'];
+      const body = JSON.stringify(req.body);
+      
+      if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET)) {
+        return res.status(401).send('Invalid signature');
+      }
+      
+      // Process the webhook...
+    });
+    ```
+  </Tab>
+  <Tab value="Python">
+    ```python
+    import hmac
+    import hashlib
+    import json
+
+    def verify_webhook_signature(body: str, signature: str, secret: str) -> bool:
+        timestamp_part, signature_part = signature.split(',')
+        timestamp = timestamp_part.replace('t=', '')
+        expected_signature = signature_part.replace('v1=', '')
+        
+        signature_base = f"{timestamp}.{body}"
+        computed_signature = hmac.new(
+            secret.encode(),
+            signature_base.encode(),
+            hashlib.sha256
+        ).hexdigest()
+        
+        return hmac.compare_digest(computed_signature, expected_signature)
+
+    # In your webhook handler
+    @app.route('/webhook', methods=['POST'])
+    def webhook():
+        signature = request.headers.get('sim-signature')
+        body = json.dumps(request.json)
+        
+        if not verify_webhook_signature(body, signature, os.environ['WEBHOOK_SECRET']):
+            return 'Invalid signature', 401
+        
+        # Process the webhook...
+    ```
+  </Tab>
+</Tabs>
+
+### Retry Policy
+
+Failed webhook deliveries are retried with exponential backoff and jitter:
+
+- Maximum attempts: 5
+- Retry delays: 5 seconds, 15 seconds, 1 minute, 3 minutes, 10 minutes
+- Jitter: Up to 10% additional delay to prevent thundering herd
+- Only HTTP 5xx and 429 responses trigger retries
+- Deliveries timeout after 30 seconds
+
+<Callout type="info">
+  Webhook deliveries are processed asynchronously and don't affect workflow execution performance.
+</Callout>
+
+## Best Practices
+
+1. **Polling Strategy**: When polling for logs, use cursor-based pagination with `order=asc` and `startDate` to fetch new logs efficiently.
+
+2. **Webhook Security**: Always configure a webhook secret and verify signatures to ensure requests are from Sim.
+
+3. **Idempotency**: Use the `Idempotency-Key` header to detect and handle duplicate webhook deliveries.
+
+4. **Privacy**: By default, `finalOutput` and `traceSpans` are excluded from responses. Only enable these if you need the data and understand the privacy implications.
+
+5. **Rate Limiting**: Implement exponential backoff when you receive 429 responses. Check the `Retry-After` header for the recommended wait time.
+
+## Rate Limiting
+
+The API implements rate limiting to ensure fair usage:
+
+- **Free plan**: 10 requests per minute
+- **Pro plan**: 30 requests per minute
+- **Team plan**: 60 requests per minute
+- **Enterprise plan**: Custom limits
+
+Rate limit information is included in response headers:
+- `X-RateLimit-Limit`: Maximum requests per window
+- `X-RateLimit-Remaining`: Requests remaining in current window
+- `X-RateLimit-Reset`: ISO timestamp when the window resets
+
+## Example: Polling for New Logs
+
+```javascript
+let cursor = null;
+const workspaceId = 'YOUR_WORKSPACE_ID';
+const startDate = new Date().toISOString();
+
+async function pollLogs() {
+  const params = new URLSearchParams({
+    workspaceId,
+    startDate,
+    order: 'asc',
+    limit: '100'
+  });
+  
+  if (cursor) {
+    params.append('cursor', cursor);
+  }
+  
+  const response = await fetch(
+    `https://sim.ai/api/v1/logs?${params}`,
+    {
+      headers: {
+        'x-api-key': 'YOUR_API_KEY'
+      }
+    }
+  );
+  
+  if (response.ok) {
+    const data = await response.json();
+    
+    // Process new logs
+    for (const log of data.data) {
+      console.log(`New execution: ${log.executionId}`);
+    }
+    
+    // Update cursor for next poll
+    if (data.nextCursor) {
+      cursor = data.nextCursor;
+    }
+  }
+}
+
+// Poll every 30 seconds
+setInterval(pollLogs, 30000);
+```
+
+## Example: Processing Webhooks
+
+```javascript
+import express from 'express';
+import crypto from 'crypto';
+
+const app = express();
+app.use(express.json());
+
+app.post('/sim-webhook', (req, res) => {
+  // Verify signature
+  const signature = req.headers['sim-signature'];
+  const body = JSON.stringify(req.body);
+  
+  if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET)) {
+    return res.status(401).send('Invalid signature');
+  }
+  
+  // Check timestamp to prevent replay attacks
+  const timestamp = parseInt(req.headers['sim-timestamp']);
+  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
+  
+  if (timestamp < fiveMinutesAgo) {
+    return res.status(401).send('Timestamp too old');
+  }
+  
+  // Process the webhook
+  const event = req.body;
+  
+  switch (event.type) {
+    case 'workflow.execution.completed':
+      const { workflowId, executionId, status, cost } = event.data;
+      
+      if (status === 'error') {
+        console.error(`Workflow ${workflowId} failed: ${executionId}`);
+        // Handle error...
+      } else {
+        console.log(`Workflow ${workflowId} completed: ${executionId}`);
+        console.log(`Cost: $${cost.total}`);
+        // Process successful execution...
+      }
+      break;
+  }
+  
+  // Return 200 to acknowledge receipt
+  res.status(200).send('OK');
+});
+
+app.listen(3000, () => {
+  console.log('Webhook server listening on port 3000');
+});
+```

apps/docs/content/docs/execution/basics.mdx

@@ -1,243 +1,132 @@
 ---
 title: Execution Basics
-description: Understanding the fundamental execution flow in Sim
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { File, Files, Folder } from 'fumadocs-ui/components/files'
+import { Card, Cards } from 'fumadocs-ui/components/card'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
-import {
-  AgentIcon,
-  ApiIcon,
-  ChartBarIcon,
-  CodeIcon,
-  ConditionalIcon,
-  ConnectIcon,
-  ResponseIcon,
-  StarterIcon,
-  LoopIcon,
-  ParallelIcon,
-} from '@/components/icons'
+import { Image } from '@/components/ui/image'
 import { Video } from '@/components/ui/video'
 
-When you run a workflow in Sim, the execution engine follows a systematic process to ensure blocks are executed in the correct order with proper data flow.
+Understanding how workflows execute in Sim is key to building efficient and reliable automations. The execution engine automatically handles dependencies, concurrency, and data flow to ensure your workflows run smoothly and predictably.
 
-## Execution Flow
+## How Workflows Execute
 
-The execution engine runs workflows in layers, processing blocks based on their dependencies:
+Sim's execution engine processes workflows intelligently by analyzing dependencies and running blocks in the most efficient order possible.
 
-<Steps>
-  <Step>
-    <strong>Validation</strong>: Ensures the workflow has a starter block with no incoming connections and all blocks are properly connected.
-  </Step>
+### Concurrent Execution by Default
 
-  <Step>
-    <strong>Layer-based Execution</strong>: Identifies which blocks can execute next based on completed dependencies and executes them in parallel.
-  </Step>
+Multiple blocks run concurrently when they don't depend on each other. This parallel execution dramatically improves performance without requiring manual configuration.
 
-  <Step>
-    <strong>Path Updates</strong>: Router and Condition blocks update the active execution path, determining which blocks execute next.
-  </Step>
+<Image
+  src="/static/execution/concurrency.png"
+  alt="Multiple blocks running concurrently after the Start block"
+  width={800}
+  height={500}
+/>
 
-  <Step>
-    <strong>Iteration Processing</strong>: Loop and Parallel blocks manage iterations and create virtual instances for concurrent execution.
-  </Step>
+In this example, both the Customer Support and Deep Researcher agent blocks execute simultaneously after the Start block, maximizing efficiency.
 
-  <Step>
-    <strong>Result Collection</strong>: Outputs from the final blocks are collected and returned as the workflow result.
-  </Step>
-</Steps>
+### Automatic Output Combination
 
-## Block Types and Execution
+When blocks have multiple dependencies, the execution engine automatically waits for all dependencies to complete, then provides their combined outputs to the next block. No manual combining required.
 
-Different block types have different execution behaviors:
+<Image
+  src="/static/execution/combination.png"
+  alt="Function block automatically receiving outputs from multiple previous blocks"
+  width={800}
+  height={500}
+/>
 
-<Tabs items={['Orchestration Blocks', 'Processing Blocks', 'Integration Blocks']}>
-  <Tab>
-    <Card>
-      Orchestration blocks control the flow of execution through your workflow.
-      <Files>
-        <File
-          name="Starter Block"
-          icon={<StarterIcon className="h-4 w-4" />}
-          annotation="Initiates workflow execution and provides initial input values. Every workflow must have exactly one starter block."
-        />
-        <File
-          name="Router Block"
-          icon={<ConnectIcon className="h-4 w-4" />}
-          annotation="Directs execution along specific paths based on dynamic decisions. Uses an AI model to select one of multiple possible paths."
-        />
-        <File
-          name="Condition Block"
-          icon={<ConditionalIcon className="h-4 w-4" />}
-          annotation="Executes different paths based on conditional logic. Evaluates JavaScript expressions to determine which path to follow."
-        />
-        <File
-          name="Loop Block"
-          icon={<LoopIcon className="h-4 w-4" />}
-          annotation="Executes blocks repeatedly for a fixed number of iterations or over a collection. Manages iteration state and provides access to current item."
-        />
-        <File
-          name="Parallel Block"
-          icon={<ParallelIcon className="h-4 w-4" />}
-          annotation="Executes blocks concurrently across multiple instances. Distributes work based on count or collection for faster processing."
-        />
-      </Files>
-    </Card>
-  </Tab>
+The Function block receives outputs from both agent blocks as soon as they complete, allowing you to process the combined results.
 
-<Tab>
-  <Card>
-    Processing blocks transform data and generate new outputs.
-    <Files>
-      <File
-        name="Agent Block"
-        icon={<AgentIcon className="h-4 w-4" />}
-        annotation="Interacts with AI models to generate content. Executes prompts against various LLM providers."
-      />
-      <File
-        name="Function Block"
-        icon={<CodeIcon className="h-4 w-4" />}
-        annotation="Executes custom JavaScript/TypeScript code. Runs in a secure sandbox environment with access to connected block outputs."
-      />
-      <File
-        name="Evaluator Block"
-        icon={<ChartBarIcon className="h-4 w-4" />}
-        annotation="Assesses outputs against defined criteria. Uses AI to evaluate content based on custom metrics."
-      />
-      <File
-        name="Workflow Block"
-        icon={<ConnectIcon className="h-4 w-4" />}
-        annotation="Execute nested workflows as a single block. Allows modular workflow design by embedding one workflow inside another."
-      />
-    </Files>
+### Smart Routing
+
+Workflows can branch in multiple directions using routing blocks. The execution engine supports both deterministic routing (with Condition blocks) and AI-powered routing (with Router blocks).
+
+<Image
+  src="/static/execution/routing.png"
+  alt="Workflow showing both conditional and router-based branching"
+  width={800}
+  height={500}
+/>
+
+This workflow demonstrates how execution can follow different paths based on conditions or AI decisions, with each path executing independently.
+
+## Block Types
+
+Sim provides different types of blocks that serve specific purposes in your workflows:
+
+<Cards>
+  <Card title="Triggers" href="/triggers">
+    **Starter blocks** initiate workflows and **Webhook blocks** respond to external events. Every workflow needs a trigger to begin execution.
   </Card>
-</Tab>
+  
+  <Card title="Processing Blocks" href="/blocks">
+    **Agent blocks** interact with AI models, **Function blocks** run custom code, and **API blocks** connect to external services. These blocks transform and process your data.
+  </Card>
+  
+  <Card title="Control Flow" href="/blocks">
+    **Router blocks** use AI to choose paths, **Condition blocks** branch based on logic, and **Loop/Parallel blocks** handle iterations and concurrency.
+  </Card>
+  
+  <Card title="Output & Response" href="/blocks">
+    **Response blocks** format final outputs for APIs and chat interfaces, returning structured results from your workflows.
+  </Card>
+</Cards>
 
-  <Tab>
-    <Card>
-      Integration blocks connect with external systems.
-      <Files>
-        <File
-          name="API Block"
-          icon={<ApiIcon className="h-4 w-4" />}
-          annotation="Makes HTTP requests to external services. Configurable with headers, body, and authentication."
-        />
-        <File
-          name="Knowledge Base Block"
-          icon={
-            <svg className="h-4 w-4" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
-              <path d="M12 2L3 9V20C3 20.55 3.45 21 4 21H9V14H15V21H20C20.55 21 21 20.55 21 20V9L12 2Z" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"/>
-              <circle cx="12" cy="10" r="2" stroke="currentColor" strokeWidth="2"/>
-            </svg>
-          }
-          annotation="Search and interact with knowledge bases. Performs semantic search, retrieves documents, and manages knowledge data."
-        />
-        <File
-          name="Response Block"
-          icon={<ResponseIcon className="h-4 w-4" />}
-          annotation="Format and return responses from workflows. Configure response data, status codes, and headers."
-        />
-        <File
-          name="Tool Blocks"
-          icon={<CodeIcon className="h-4 w-4" />}
-          annotation="Specialized blocks for specific services (Gmail, Slack, GitHub, etc.). Each has its own execution logic for the specific service."
-        />
-      </Files>
-    </Card>
-  </Tab>
-</Tabs>
+All blocks execute automatically based on their dependencies - you don't need to manually manage execution order or timing.
 
-## Execution Methods
+## Execution Triggers
 
-Sim offers multiple ways to trigger workflow execution:
+Workflows can be triggered in several ways, depending on your use case:
 
-### Manual Execution
+### Manual Testing
+Click "Run" in the workflow editor to test your workflow during development. Perfect for debugging and validation.
 
-Run workflows on-demand through the Sim interface by clicking the "Run" button. This is perfect for:
+### Scheduled Execution  
+Set up recurring executions using cron expressions. Great for regular data processing, reports, or maintenance tasks.
 
-- Testing during development
-- One-off tasks
-- Workflows that need human supervision
+### API Deployment
+Deploy workflows as HTTP endpoints that can be called programmatically from your applications.
 
-<div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="input-format.mp4" />
-</div>
+### Webhook Integration
+Respond to events from external services like GitHub, Stripe, or custom systems in real-time.
 
-### Scheduled Execution
-
-Configure workflows to run automatically on a specified schedule:
-
-- Set up recurring executions using cron expressions
-- Define start times and frequency
-- Configure timezone settings
-- Set minimum and maximum execution intervals
-
-<div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="configure-schedule.mp4" />
-</div>
-
-### API Endpoints
-
-Each workflow can be exposed as an API endpoint:
-
-- Get a unique URL for your workflow
-- Configure authentication requirements
-- Send custom inputs via POST requests
-- Receive execution results as JSON responses
-
-<div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="api-deployment.mp4" />
-</div>
-
-#### Viewing Deployed APIs
-
-Monitor your deployed workflow APIs and their current state:
-
-<div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="api-redeployment.mp4" />
-</div>
-
-This shows how to view the deployed state and compare with the original deployed API configuration.
-
-### Webhooks
-
-Configure workflows to execute in response to external events:
-
-- Set up webhook triggers from third-party services
-- Process incoming webhook data as workflow input
-- Configure webhook security settings
-- Support for specialized webhooks (GitHub, Stripe, etc.)
-
-<div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="webhooks.mp4" />
-</div>
+### Chat Interface
+Create conversational interfaces hosted on custom subdomains for user-facing AI applications.
 
 <Callout type="info">
-  The execution method you choose depends on your workflow's purpose. Manual execution is great for
-  development, while scheduled execution, API endpoints, and webhooks are better for production use
-  cases.
+  Learn more about each trigger type in the [Triggers section](/triggers) of the documentation.
 </Callout>
 
-## Execution Context
+## Execution Monitoring
 
-Each workflow execution maintains a context that tracks:
+When workflows run, Sim provides real-time visibility into the execution process:
 
-- **Block States**: Outputs and execution status of each block
-- **Execution Path**: Active blocks based on routing decisions
-- **Loop/Parallel State**: Current iterations and distribution items
-- **Environment Variables**: Configuration values available during execution
-- **Execution Logs**: Detailed records of each block's execution
+- **Live Block States**: See which blocks are currently executing, completed, or failed
+- **Execution Logs**: Detailed logs appear in real-time showing inputs, outputs, and any errors
+- **Performance Metrics**: Track execution time and costs for each block
+- **Path Visualization**: Understand which execution paths were taken through your workflow
 
-## Real-Time Monitoring
+<Callout type="info">
+  All execution details are captured and available for review even after workflows complete, helping with debugging and optimization.
+</Callout>
 
-Monitor your workflow execution in real-time:
+## Key Execution Principles
 
-- **Active Block Highlighting**: Currently executing blocks pulse with animation
-- **Live Logs**: Execution logs appear instantly in the logs panel
-- **Block States**: Visual indicators show success, error, or pending states
-- **Performance Metrics**: Execution time for each block
+Understanding these core principles will help you build better workflows:
 
-These monitoring features help you understand workflow behavior and quickly identify any issues.
+1. **Dependency-Based Execution**: Blocks only run when all their dependencies have completed
+2. **Automatic Parallelization**: Independent blocks run concurrently without configuration
+3. **Smart Data Flow**: Outputs flow automatically to connected blocks
+4. **Error Handling**: Failed blocks stop their execution path but don't affect independent paths
+5. **State Persistence**: All block outputs and execution details are preserved for debugging
+
+## Next Steps
+
+Now that you understand execution basics, explore:
+- **[Block Types](/blocks)** - Learn about specific block capabilities
+- **[Logging](/execution/logging)** - Monitor workflow executions and debug issues
+- **[Cost Calculation](/execution/costs)** - Understand and optimize workflow costs
+- **[Triggers](/triggers)** - Set up different ways to run your workflows

apps/docs/content/docs/execution/costs.mdx

@@ -0,0 +1,182 @@
+---
+title: Cost Calculation
+---
+
+import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Image } from '@/components/ui/image'
+
+Sim automatically calculates costs for all workflow executions, providing transparent pricing based on AI model usage and execution charges. Understanding these costs helps you optimize workflows and manage your budget effectively.
+
+## How Costs Are Calculated
+
+Every workflow execution includes two cost components:
+
+**Base Execution Charge**: $0.001 per execution
+
+**AI Model Usage**: Variable cost based on token consumption
+```javascript
+modelCost = (inputTokens × inputPrice + outputTokens × outputPrice) / 1,000,000
+totalCost = baseExecutionCharge + modelCost
+```
+
+<Callout type="info">
+  AI model prices are per million tokens. The calculation divides by 1,000,000 to get the actual cost. Workflows without AI blocks only incur the base execution charge.
+</Callout>
+
+## Model Breakdown in Logs
+
+For workflows using AI blocks, you can view detailed cost information in the logs:
+
+<div className="flex justify-center">
+  <Image
+    src="/static/logs/logs-cost.png"
+    alt="Model Breakdown"
+    width={600}
+    height={400}
+    className="my-6"
+  />
+</div>
+
+The model breakdown shows:
+- **Token Usage**: Input and output token counts for each model
+- **Cost Breakdown**: Individual costs per model and operation
+- **Model Distribution**: Which models were used and how many times
+- **Total Cost**: Aggregate cost for the entire workflow execution
+
+## Pricing Options
+
+<Tabs items={['Hosted Models', 'Bring Your Own API Key']}>
+  <Tab>
+    **Hosted Models** - Sim provides API keys with a 2.5x pricing multiplier:
+    
+    | Model | Base Price (Input/Output) | Hosted Price (Input/Output) |
+    |-------|---------------------------|----------------------------|
+    | GPT-4o | $2.50 / $10.00 | $6.25 / $25.00 |
+    | GPT-4.1 | $2.00 / $8.00 | $5.00 / $20.00 |
+    | o1 | $15.00 / $60.00 | $37.50 / $150.00 |
+    | o3 | $2.00 / $8.00 | $5.00 / $20.00 |
+    | Claude 3.5 Sonnet | $3.00 / $15.00 | $7.50 / $37.50 |
+    | Claude Opus 4.0 | $15.00 / $75.00 | $37.50 / $187.50 |
+    
+    *The 2.5x multiplier covers infrastructure and API management costs.*
+  </Tab>
+  
+  <Tab>
+    **Your Own API Keys** - Use any model at base pricing:
+    
+    | Provider | Models | Input / Output |
+    |----------|---------|----------------|
+    | Google | Gemini 2.5 | $0.15 / $0.60 |
+    | Deepseek | V3, R1 | $0.75 / $1.00 |
+    | xAI | Grok 4, Grok 3 | $5.00 / $25.00 |
+    | Groq | Llama 4 Scout | $0.40 / $0.60 |
+    | Cerebras | Llama 3.3 70B | $0.94 / $0.94 |
+    | Ollama | Local models | Free |
+    
+    *Pay providers directly with no markup*
+  </Tab>
+</Tabs>
+
+<Callout type="warning">
+  Pricing shown reflects rates as of September 10, 2025. Check provider documentation for current pricing.
+</Callout>
+
+## Cost Optimization Strategies
+
+<Accordions>
+  <Accordion title="Model Selection">
+    Choose models based on task complexity. Simple tasks can use GPT-4.1-nano ($0.10/$0.40) while complex reasoning might need o1 or Claude Opus.
+  </Accordion>
+  
+  <Accordion title="Prompt Engineering">
+    Well-structured, concise prompts reduce token usage without sacrificing quality.
+  </Accordion>
+  
+  <Accordion title="Local Models">
+    Use Ollama for non-critical tasks to eliminate API costs entirely.
+  </Accordion>
+  
+  <Accordion title="Caching and Reuse">
+    Store frequently used results in variables or files to avoid repeated AI model calls.
+  </Accordion>
+  
+  <Accordion title="Batch Processing">
+    Process multiple items in a single AI request rather than making individual calls.
+  </Accordion>
+</Accordions>
+
+## Usage Monitoring
+
+Monitor your usage and billing in Settings → Subscription:
+
+- **Current Usage**: Real-time usage and costs for the current period
+- **Usage Limits**: Plan limits with visual progress indicators
+- **Billing Details**: Projected charges and minimum commitments
+- **Plan Management**: Upgrade options and billing history
+
+### Programmatic Usage Tracking
+
+You can query your current usage and limits programmatically using the API:
+
+**Endpoint:**
+```text
+GET /api/users/me/usage-limits
+```
+
+**Authentication:**
+- Include your API key in the `X-API-Key` header
+
+**Example Request:**
+```bash
+curl -X GET -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" https://sim.ai/api/users/me/usage-limits
+```
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "rateLimit": {
+    "sync": { "isLimited": false, "limit": 10, "remaining": 10, "resetAt": "2025-09-08T22:51:55.999Z" },
+    "async": { "isLimited": false, "limit": 50, "remaining": 50, "resetAt": "2025-09-08T22:51:56.155Z" },
+    "authType": "api"
+  },
+  "usage": {
+    "currentPeriodCost": 12.34,
+    "limit": 100,
+    "plan": "pro"
+  }
+}
+```
+
+**Response Fields:**
+- `currentPeriodCost` reflects usage in the current billing period
+- `limit` is derived from individual limits (Free/Pro) or pooled organization limits (Team/Enterprise)
+- `plan` is the highest-priority active plan associated with your user
+
+## Plan Limits
+
+Different subscription plans have different usage limits:
+
+| Plan | Monthly Usage Limit | Rate Limits (per minute) |
+|------|-------------------|-------------------------|
+| **Free** | $10 | 5 sync, 10 async |
+| **Pro** | $100 | 10 sync, 50 async |
+| **Team** | $500 (pooled) | 50 sync, 100 async |
+| **Enterprise** | Custom | Custom |
+
+## Cost Management Best Practices
+
+1. **Monitor Regularly**: Check your usage dashboard frequently to avoid surprises
+2. **Set Budgets**: Use plan limits as guardrails for your spending
+3. **Optimize Workflows**: Review high-cost executions and optimize prompts or model selection
+4. **Use Appropriate Models**: Match model complexity to task requirements
+5. **Batch Similar Tasks**: Combine multiple requests when possible to reduce overhead
+
+## Next Steps
+
+- Review your current usage in [Settings → Subscription](https://sim.ai/settings/subscription)
+- Learn about [Logging](/execution/logging) to track execution details
+- Explore the [External API](/execution/api) for programmatic cost monitoring
+- Check out [workflow optimization techniques](/blocks) to reduce costs

apps/docs/content/docs/execution/index.mdx

@@ -1,12 +1,11 @@
 ---
 title: Execution
-description: Understand how workflows are executed in Sim
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Card, Cards } from 'fumadocs-ui/components/card'
 
-Sim's execution engine brings your workflows to life by processing blocks in the correct order, managing data flow, and handling errors gracefully.
+Sim's execution engine brings your workflows to life by processing blocks in the correct order, managing data flow, and handling errors gracefully, so you can understand exactly how workflows are executed in Sim.
 
 <Callout type="info">
   Every workflow execution follows a deterministic path based on your block connections and logic, ensuring predictable and reliable results.
@@ -20,8 +19,16 @@ Sim's execution engine brings your workflows to life by processing blocks in the
     workflow
   </Card>
 
-  <Card title="Logging and Cost Calculation" href="/execution/advanced">
-    Understand workflow logs and how execution costs are calculated in Sim
+  <Card title="Logging" href="/execution/logging">
+    Monitor workflow executions with comprehensive logging and real-time visibility
+  </Card>
+  
+  <Card title="Cost Calculation" href="/execution/costs">
+    Understand how workflow execution costs are calculated and optimized
+  </Card>
+  
+  <Card title="External API" href="/execution/api">
+    Access execution logs and set up webhooks programmatically via REST API
   </Card>
 </Cards>
 
@@ -125,4 +132,4 @@ const result = await client.executeWorkflow('workflow-id', {
 
 ## What's Next?
 
-Start with [Execution Basics](/execution/basics) to understand how workflows run, then explore [Logging and Cost Calculation](/execution/advanced) to monitor and optimize your executions.
+Start with [Execution Basics](/execution/basics) to understand how workflows run, then explore [Logging](/execution/logging) to monitor your executions and [Cost Calculation](/execution/costs) to optimize your spending.

apps/docs/content/docs/execution/logging.mdx

@@ -0,0 +1,150 @@
+---
+title: Logging
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Image } from '@/components/ui/image'
+
+Sim provides comprehensive logging for all workflow executions, giving you complete visibility into how your workflows run, what data flows through them, and where issues might occur.
+
+## Logging System
+
+Sim offers two complementary logging interfaces to match different workflows and use cases:
+
+### Real-Time Console
+
+During manual or chat workflow execution, logs appear in real-time in the Console panel on the right side of the workflow editor:
+
+<div className="flex justify-center">
+  <Image
+    src="/static/logs/console.png"
+    alt="Real-time Console Panel"
+    width={400}
+    height={300}
+    className="my-6"
+  />
+</div>
+
+The console shows:
+- Block execution progress with active block highlighting
+- Real-time outputs as blocks complete
+- Execution timing for each block
+- Success/error status indicators
+
+### Logs Page
+
+All workflow executions—whether triggered manually, via API, Chat, Schedule, or Webhook—are logged to the dedicated Logs page:
+
+<div className="flex justify-center">
+  <Image
+    src="/static/logs/logs.png"
+    alt="Logs Page"
+    width={600}
+    height={400}
+    className="my-6"
+  />
+</div>
+
+The Logs page provides:
+- Comprehensive filtering by time range, status, trigger type, folder, and workflow
+- Search functionality across all logs
+- Live mode for real-time updates
+- 7-day log retention (upgradeable for longer retention)
+
+## Log Details Sidebar
+
+Clicking on any log entry opens a detailed sidebar view:
+
+<div className="flex justify-center">
+  <Image
+    src="/static/logs/logs-sidebar.png"
+    alt="Logs Sidebar Details"
+    width={600}
+    height={400}
+    className="my-6"
+  />
+</div>
+
+### Block Input/Output
+
+View the complete data flow for each block with tabs to switch between:
+
+<Tabs items={['Output', 'Input']}>
+  <Tab>
+    **Output Tab** shows the block's execution result:
+    - Structured data with JSON formatting
+    - Markdown rendering for AI-generated content
+    - Copy button for easy data extraction
+  </Tab>
+  
+  <Tab>
+    **Input Tab** displays what was passed to the block:
+    - Resolved variable values
+    - Referenced outputs from other blocks
+    - Environment variables used
+    - API keys are automatically redacted for security
+  </Tab>
+</Tabs>
+
+### Execution Timeline
+
+For workflow-level logs, view detailed execution metrics:
+- Start and end timestamps
+- Total workflow duration
+- Individual block execution times
+- Performance bottleneck identification
+
+## Workflow Snapshots
+
+For any logged execution, click "View Snapshot" to see the exact workflow state at execution time:
+
+<div className="flex justify-center">
+  <Image
+    src="/static/logs/logs-frozen-canvas.png"
+    alt="Workflow Snapshot"
+    width={600}
+    height={400}
+    className="my-6"
+  />
+</div>
+
+The snapshot provides:
+- Frozen canvas showing the workflow structure
+- Block states and connections as they were during execution
+- Click any block to see its inputs and outputs
+- Useful for debugging workflows that have since been modified
+
+<Callout type="info">
+  Workflow snapshots are only available for executions after the enhanced logging system was introduced. Older migrated logs show a "Logged State Not Found" message.
+</Callout>
+
+## Log Retention
+
+- **Free Plan**: 7 days of log retention
+- **Pro Plan**: 30 days of log retention
+- **Team Plan**: 90 days of log retention
+- **Enterprise Plan**: Custom retention periods available
+
+## Best Practices
+
+### For Development
+- Use the real-time console for immediate feedback during testing
+- Check block inputs and outputs to verify data flow
+- Use workflow snapshots to compare working vs. broken versions
+
+### For Production
+- Monitor the Logs page regularly for errors or performance issues
+- Set up filters to focus on specific workflows or time periods
+- Use live mode during critical deployments to watch executions in real-time
+
+### For Debugging
+- Always check the execution timeline to identify slow blocks
+- Compare inputs between working and failing executions
+- Use workflow snapshots to see the exact state when issues occurred
+
+## Next Steps
+
+- Learn about [Cost Calculation](/execution/costs) to understand workflow pricing
+- Explore the [External API](/execution/api) for programmatic log access
+- Set up [Webhook notifications](/execution/api#webhook-subscriptions) for real-time alerts

apps/docs/content/docs/execution/meta.json

@@ -1,4 +1,5 @@
 {
   "title": "Execution",
-  "pages": ["basics", "advanced"]
+  "pages": ["basics", "logging", "costs", "api"],
+  "defaultOpen": false
 }

apps/docs/content/docs/getting-started/index.mdx

@@ -1,6 +1,5 @@
 ---
 title: Getting Started
-description: Build your first AI workflow in 5 minutes
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
@@ -8,7 +7,6 @@ import { Card, Cards } from 'fumadocs-ui/components/card'
 import { File, Files, Folder } from 'fumadocs-ui/components/files'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
 import {
   AgentIcon,
   ApiIcon,
@@ -24,6 +22,7 @@ import {
   SlackIcon,
 } from '@/components/icons'
 import { Video } from '@/components/ui/video'
+import { Image } from '@/components/ui/image'
 
 This tutorial will guide you through building your first AI workflow in Sim. We'll create a people research agent that can find information about individuals using state-of-the-art LLM-Search tools.
 
@@ -40,9 +39,8 @@ A people research agent that:
 4. Extracts structured information using a response format
 5. Returns comprehensive data about the person
 
-<ThemeImage
-  lightSrc="/static/examples/started/started-1.png"
-  darkSrc="/static/examples/started/started-1.png"
+<Image
+  src="/static/getting-started/started-1.png"
   alt="Getting Started Example"
   width={800}
   height={500}
@@ -64,7 +62,7 @@ A people research agent that:
     - **User Prompt**: Drag the connection from the Start block's output into this field (this connects `<start.input>` to the user prompt)
     
     <div className="mx-auto w-full overflow-hidden rounded-lg">
-      <Video src="examples/started-2.mp4" />
+      <Video src="getting-started/started-2.mp4" width={700} height={450} />
     </div>
   </Step>
   
@@ -78,7 +76,7 @@ A people research agent that:
     - Add your API keys for both tools (this allows the agent to search the web and access additional information)
     
     <div className="mx-auto w-3/5 overflow-hidden rounded-lg">
-      <Video src="examples/started-3.mp4" />
+      <Video src="getting-started/started-3.mp4" width={700} height={450} />
     </div>
   </Step>
   
@@ -93,7 +91,7 @@ A people research agent that:
     You should see the agent's response analyzing the person described in your text.
     
     <div className="mx-auto w-full overflow-hidden rounded-lg">
-      <Video src="examples/started-4.mp4" />
+      <Video src="getting-started/started-4.mp4" width={700} height={450} />
     </div>
   </Step>
   
@@ -106,7 +104,7 @@ A people research agent that:
     - The AI will generate a JSON schema for you automatically
     
     <div className="mx-auto w-full overflow-hidden rounded-lg">
-      <Video src="examples/started-5.mp4" />
+      <Video src="getting-started/started-5.mp4" width={700} height={450} />
     </div>
   </Step>
   
@@ -121,7 +119,7 @@ A people research agent that:
     You should now see structured JSON output with the person's information organized into location, profession, and education fields.
     
     <div className="mx-auto w-full overflow-hidden rounded-lg">
-      <Video src="examples/started-6.mp4" />
+      <Video src="getting-started/started-6.mp4" width={700} height={450} />
     </div>
   </Step>
 </Steps>

apps/docs/content/docs/introduction/index.mdx

@@ -1,94 +1,85 @@
 ---
 title: Introduction
-description: Build AI workflows visually without code
 ---
 
 import { Card, Cards } from 'fumadocs-ui/components/card'
-import { File, Files, Folder } from 'fumadocs-ui/components/files'
-import { Features } from '@/components/ui/features'
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Image } from '@/components/ui/image'
 
-Sim is a visual workflow editor that enables you to build AI-powered applications by connecting blocks on a canvas. Drag and drop components to create chatbots, automation workflows, and data processing pipelines without writing code.
+Sim is a visual workflow builder for AI applications that lets you build AI agent workflows visually. Create powerful AI agents, automation workflows, and data processing pipelines by connecting blocks on a canvas—no coding required.
 
-## What Makes Sim Powerful
+<div className="flex justify-center">
+  <Image
+    src="/static/introduction.png"
+    alt="Sim visual workflow canvas"
+    width={700}
+    height={450}
+    className="my-6"
+  />
+</div>
 
-**Multi-Model AI Support** - Connect to OpenAI, Anthropic, Google, Groq, Cerebras, and local models through Ollama. Switch providers without rebuilding workflows.
+## What You Can Build
 
-**60+ Pre-Built Tools** - Gmail, Slack, Notion, Google Sheets, Airtable, Supabase, Pinecone, and more. Extensible architecture allows custom tool integration.
+**AI Assistants & Chatbots**
+Create intelligent agents that can search the web, access your calendar, send emails, and interact with your business tools.
 
-**Flexible Execution** - Run workflows via chat interface, REST API, webhooks, scheduled jobs, or trigger from external systems.
+**Business Process Automation**
+Automate repetitive tasks like data entry, report generation, customer support responses, and content creation.
 
-**Production Deployment** - Deploy as APIs, integrate with existing systems using our SDK, or embed as plugins. Built-in monitoring, logging, and error handling.
+**Data Processing & Analysis**
+Extract insights from documents, analyze datasets, generate reports, and sync data between systems.
 
-**Real-time Collaboration** - Work simultaneously with team members on the same workflow, like Google Docs for AI development.
+**API Integration Workflows**
+Connect multiple services into unified endpoints, orchestrate complex business logic, and handle event-driven automation.
 
-Connect multiple AI models, integrate with 60+ services, and deploy production-ready applications through an intuitive visual interface designed specifically for AI development.
+## How It Works
 
-## Core Building Blocks
+**Visual Canvas**
+Drag and drop blocks to build workflows. Connect AI models, databases, APIs, and business tools with simple point-and-click connections.
 
-**Processing Blocks**
+**Smart Blocks**
+Choose from processing blocks (AI agents, APIs, functions), logic blocks (conditions, loops, routers), and output blocks (responses, evaluators).
 
-- **Agent** - Execute AI model inference with any LLM provider
-- **API** - Connect to REST endpoints and external services  
-- **Function** - Run custom JavaScript for data processing
+**Multiple Triggers**
+Start workflows via chat interface, REST API, webhooks, scheduled jobs, or external events from services like Slack and GitHub.
 
-**Logic Blocks**
-
-- **Condition** - Create branching logic based on data evaluation
-- **Router** - Route execution paths using AI-powered decision making
-- **Loop** - Iterate over collections sequentially
-- **Parallel** - Execute multiple operations concurrently
-
-**Output Blocks**
-
-- **Response** - Format and return final workflow results
-- **Evaluator** - Validate outputs against defined criteria
+**Team Collaboration**
+Work simultaneously with team members on the same workflow with real-time editing and permissions management.
 
 ## Built-in Integrations
 
-**AI Models**: OpenAI, Anthropic, Google, Groq, Cerebras, Ollama
+Sim connects to 80+ services out of the box:
 
-**Communication**: Gmail, Slack, Telegram, WhatsApp, Microsoft Teams
+- **AI Models**: OpenAI, Anthropic, Google, Groq, Cerebras, local Ollama models
+- **Communication**: Gmail, Slack, Teams, Telegram, WhatsApp  
+- **Productivity**: Notion, Google Sheets, Airtable, Monday.com
+- **Development**: GitHub, Jira, Linear, browser automation
+- **Search & Web**: Google Search, Perplexity, Firecrawl, Exa AI
+- **Databases**: PostgreSQL, MySQL, Supabase, Pinecone, Qdrant
 
-**Data Sources**: Notion, Google Sheets, Airtable, Supabase, Pinecone
+Need something custom? Use our [MCP integration](/mcp) to connect any external service.
 
-**Web Services**: Firecrawl, Google Search, Exa AI, Perplexity
+## Deployment Options
 
-**Development**: GitHub, Jira, Linear, browser automation
+**Cloud-hosted**: Get started instantly at [sim.ai](https://sim.ai) with managed infrastructure, automatic scaling, and built-in monitoring.
 
-## Use Cases
+**Self-hosted**: Deploy on your own infrastructure using Docker, with support for local AI models via Ollama for complete data privacy.
 
-**AI Assistants** - Build chatbots with web search, calendar access, and email capabilities
+## Next Steps
 
-**Content Generation** - Create blog posts, social media content, and marketing materials
-
-**Data Processing** - Extract insights from documents, analyze datasets, and generate reports
-
-**Process Automation** - Automate business workflows with event-driven triggers
-
-**API Orchestration** - Combine multiple services into unified endpoints
-
-## Key Features
-
-**Multi-Provider AI Support** - Switch between OpenAI, Anthropic, Google, and local models without rebuilding workflows
-
-**Real-time Collaboration** - Work simultaneously with team members on the same workflow
-
-**Production-Ready** - Built-in error handling, logging, and monitoring for production deployments
-
-**Local Development** - Test with Ollama locally, then deploy with cloud providers
-
-## Getting Started
-
-Ready to build your first workflow? Our [Getting Started guide](/getting-started) will walk you through creating a customer support assistant in under 10 minutes.
+Ready to build your first AI workflow?
 
 <Cards>
-  <Card title="Getting Started" href="/getting-started">
-    Build your first workflow
+  <Card title="Getting Started" href="/docs/getting-started">
+    Create your first workflow in 10 minutes
   </Card>
-  <Card title="Blocks" href="/blocks">
-    Learn about workflow components
+  <Card title="Workflow Blocks" href="/docs/blocks">
+    Learn about the building blocks
   </Card>
-  <Card title="Tools" href="/tools">
-    Explore integrations
+  <Card title="Tools & Integrations" href="/docs/tools">
+    Explore 60+ built-in integrations
+  </Card>
+  <Card title="Team Permissions" href="/docs/permissions">
+    Set up workspace roles and permissions
   </Card>
 </Cards>

apps/docs/content/docs/knowledgebase/index.mdx

@@ -0,0 +1,113 @@
+---
+title: Knowledgebase
+---
+
+import { Video } from '@/components/ui/video'
+import { Image } from '@/components/ui/image'
+
+The knowledgebase allows you to upload, process, and search through your documents with intelligent vector search and chunking. Documents of various types are automatically processed, embedded, and made searchable. Your documents are intelligently chunked, and you can view, edit, and search through them using natural language queries.
+
+## Upload and Processing
+
+Simply upload your documents to get started. Sim automatically processes them in the background, extracting text, creating embeddings, and breaking them into searchable chunks.
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="knowledgebase-1.mp4" width={700} height={450} />
+</div>
+
+The system handles the entire processing pipeline for you:
+
+1. **Text Extraction**: Content is extracted from your documents using specialized parsers for each file type
+2. **Intelligent Chunking**: Documents are broken into meaningful chunks with configurable size and overlap
+3. **Embedding Generation**: Vector embeddings are created for semantic search capabilities
+4. **Processing Status**: Track the progress as your documents are processed
+
+## Supported File Types
+
+Sim supports PDF, Word (DOC/DOCX), plain text (TXT), Markdown (MD), HTML, Excel (XLS/XLSX), PowerPoint (PPT/PPTX), and CSV files. Files can be up to 100MB each, with optimal performance for files under 50MB. You can upload multiple documents simultaneously, and PDF files include OCR processing for scanned documents.
+
+## Viewing and Editing Chunks
+
+Once your documents are processed, you can view and edit the individual chunks. This gives you full control over how your content is organized and searched.
+
+<Image src="/static/knowledgebase.png" alt="Document chunks view showing processed content" width={800} height={500} />
+
+### Chunk Configuration
+- **Default chunk size**: 1,024 characters
+- **Configurable range**: 100-4,000 characters per chunk
+- **Smart overlap**: 200 characters by default for context preservation
+- **Hierarchical splitting**: Respects document structure (sections, paragraphs, sentences)
+
+### Editing Capabilities
+- **Edit chunk content**: Modify the text content of individual chunks
+- **Adjust chunk boundaries**: Merge or split chunks as needed
+- **Add metadata**: Enhance chunks with additional context
+- **Bulk operations**: Manage multiple chunks efficiently
+
+## Advanced PDF Processing
+
+For PDF documents, Sim offers enhanced processing capabilities:
+
+### OCR Support
+When configured with Azure or [Mistral OCR](https://docs.mistral.ai/ocr/):
+- **Scanned document processing**: Extract text from image-based PDFs
+- **Mixed content handling**: Process PDFs with both text and images
+- **High accuracy**: Advanced AI models ensure accurate text extraction
+
+## Using The Knowledge Block in Workflows
+
+Once your documents are processed, you can use them in your AI workflows through the Knowledge block. This enables Retrieval-Augmented Generation (RAG), allowing your AI agents to access and reason over your document content to provide more accurate, contextual responses.
+
+<Image src="/static/knowledgebase-2.png" alt="Using Knowledge Block in Workflows" width={800} height={500} />
+
+### Knowledge Block Features
+- **Semantic search**: Find relevant content using natural language queries
+- **Context integration**: Automatically include relevant chunks in agent prompts
+- **Dynamic retrieval**: Search happens in real-time during workflow execution
+- **Relevance scoring**: Results ranked by semantic similarity
+
+### Integration Options
+- **System prompts**: Provide context to your AI agents
+- **Dynamic context**: Search and include relevant information during conversations
+- **Multi-document search**: Query across your entire knowledgebase
+- **Filtered search**: Combine with tags for precise content retrieval
+
+## Vector Search Technology
+
+Sim uses vector search powered by [pgvector](https://github.com/pgvector/pgvector) to understand the meaning and context of your content:
+
+### Semantic Understanding
+- **Contextual search**: Finds relevant content even when exact keywords don't match
+- **Concept-based retrieval**: Understands relationships between ideas
+- **Multi-language support**: Works across different languages
+- **Synonym recognition**: Finds related terms and concepts
+
+### Search Capabilities
+- **Natural language queries**: Ask questions in plain English
+- **Similarity search**: Find conceptually similar content
+- **Hybrid search**: Combines vector and traditional keyword search
+- **Configurable results**: Control the number and relevance threshold of results
+
+## Document Management
+
+### Organization Features
+- **Bulk upload**: Upload multiple files at once via the asynchronous API
+- **Processing status**: Real-time updates on document processing
+- **Search and filter**: Find documents quickly in large collections
+- **Metadata tracking**: Automatic capture of file information and processing details
+
+### Security and Privacy
+- **Secure storage**: Documents stored with enterprise-grade security
+- **Access control**: Workspace-based permissions
+- **Processing isolation**: Each workspace has isolated document processing
+- **Data retention**: Configure document retention policies
+
+## Getting Started
+
+1. **Navigate to your knowledgebase**: Access from your workspace sidebar
+2. **Upload documents**: Drag and drop or select files to upload
+3. **Monitor processing**: Watch as documents are processed and chunked
+4. **Explore chunks**: View and edit the processed content
+5. **Add to workflows**: Use the Knowledge block to integrate with your AI agents
+
+The knowledgebase transforms your static documents into an intelligent, searchable resource that your AI workflows can leverage for more informed and contextual responses.

apps/docs/content/docs/knowledgebase/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Knowledgebase",
+  "pages": ["index", "tags"],
+  "defaultOpen": false
+}

apps/docs/content/docs/knowledgebase/tags.mdx

@@ -0,0 +1,108 @@
+---
+title: Tags and Filtering
+---
+
+import { Video } from '@/components/ui/video'
+
+Tags provide a powerful way to organize your documents and create precise filtering for your vector searches. By combining tag-based filtering with semantic search, you can retrieve exactly the content you need from your knowledgebase.
+
+## Adding Tags to Documents
+
+You can add custom tags to any document in your knowledgebase to organize and categorize your content for easier retrieval.
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="knowledgebase-tag.mp4" width={700} height={450} />
+</div>
+
+### Tag Management
+- **Custom tags**: Create your own tag system that fits your workflow
+- **Multiple tags per document**: Apply as many tags as needed to each document, there are 7 tag slots available per knowledgebase that are shared by all documents in the knowledgebase
+- **Tag organization**: Group related documents with consistent tagging
+
+### Tag Best Practices
+- **Consistent naming**: Use standardized tag names across your documents
+- **Descriptive tags**: Use clear, meaningful tag names
+- **Regular cleanup**: Remove unused or outdated tags periodically
+
+## Using Tags in Knowledge Blocks
+
+Tags become powerful when combined with the Knowledge block in your workflows. You can filter your searches to specific tagged content, ensuring your AI agents get the most relevant information.
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="knowledgebase-tag2.mp4" width={700} height={450} />
+</div>
+
+## Search Modes
+
+The Knowledge block supports three different search modes depending on what you provide:
+
+### 1. Tag-Only Search
+When you **only provide tags** (no search query):
+- **Direct retrieval**: Fetches all documents that have the specified tags
+- **No vector search**: Results are based purely on tag matching
+- **Fast performance**: Quick retrieval without semantic processing
+- **Exact matching**: Only documents with all specified tags are returned
+
+**Use case**: When you need all documents from a specific category or project
+
+### 2. Vector Search Only
+When you **only provide a search query** (no tags):
+- **Semantic search**: Finds content based on meaning and context
+- **Full knowledgebase**: Searches across all documents
+- **Relevance ranking**: Results ordered by semantic similarity
+- **Natural language**: Use questions or phrases to find relevant content
+
+**Use case**: When you need the most relevant content regardless of organization
+
+### 3. Combined Tag Filtering + Vector Search
+When you **provide both tags and a search query**:
+1. **First**: Filter documents to only those with the specified tags
+2. **Then**: Perform vector search within that filtered subset
+3. **Result**: Semantically relevant content from your tagged documents only
+
+**Use case**: When you need relevant content from a specific category or project
+
+### Search Configuration
+
+#### Tag Filtering
+- **Multiple tags**: Use multiple tags for OR logic (document must have one or more of the tags)
+- **Tag combinations**: Mix different tag types for precise filtering
+- **Case sensitivity**: Tag matching is case-insensitive
+- **Partial matching**: Exact tag name matching required
+
+#### Vector Search Parameters
+- **Query complexity**: Natural language questions work best
+- **Result limits**: Configure how many chunks to retrieve
+- **Relevance threshold**: Set minimum similarity scores
+- **Context window**: Adjust chunk size for your use case
+
+## Integration with Workflows
+
+### Knowledge Block Configuration
+1. **Select knowledgebase**: Choose which knowledgebase to search
+2. **Add tags**: Specify filtering tags (optional)
+3. **Enter query**: Add your search query (optional)
+4. **Configure results**: Set number of chunks to retrieve
+5. **Test search**: Preview results before using in workflow
+
+### Dynamic Tag Usage
+- **Variable tags**: Use workflow variables as tag values
+- **Conditional filtering**: Apply different tags based on workflow logic
+- **Context-aware search**: Adjust tags based on conversation context
+- **Multi-step filtering**: Refine searches through workflow steps
+
+### Performance Optimization
+- **Efficient filtering**: Tag filtering happens before vector search for better performance
+- **Caching**: Frequently used tag combinations are cached for speed
+- **Parallel processing**: Multiple tag searches can run simultaneously
+- **Resource management**: Automatic optimization of search resources
+
+## Getting Started with Tags
+
+1. **Plan your tag structure**: Decide on consistent naming conventions
+2. **Start tagging**: Add relevant tags to your existing documents
+3. **Test combinations**: Experiment with tag + search query combinations
+4. **Integrate into workflows**: Use the Knowledge block with your tagging strategy
+5. **Refine over time**: Adjust your tagging approach based on search results
+
+Tags transform your knowledgebase from a simple document store into a precisely organized, searchable intelligence system that your AI workflows can navigate with surgical precision.

apps/docs/content/docs/mcp/index.mdx

@@ -0,0 +1,140 @@
+---
+title: MCP (Model Context Protocol)
+---
+
+import { Video } from '@/components/ui/video'
+import { Callout } from 'fumadocs-ui/components/callout'
+
+The Model Context Protocol ([MCP](https://modelcontextprotocol.com/)) allows you to connect external tools and services using a standardized protocol, enabling you to integrate APIs and services directly into your workflows. With MCP, you can extend Sim's capabilities by adding custom integrations that work seamlessly with your agents and workflows.
+
+## What is MCP?
+
+MCP is an open standard that enables AI assistants to securely connect to external data sources and tools. It provides a standardized way to:
+
+- Connect to databases, APIs, and file systems
+- Access real-time data from external services
+- Execute custom tools and scripts
+- Maintain secure, controlled access to external resources
+
+## Adding MCP Servers
+
+MCP servers provide collections of tools that your agents can use. You can add MCP servers in two ways:
+
+### From Workspace Settings
+
+Configure MCP servers at the workspace level so all team members can use them:
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="mcp-1.mp4" width={700} height={450} />
+</div>
+
+1. Navigate to your workspace settings
+2. Go to the **MCP Servers** section
+3. Click **Add MCP Server**
+4. Enter the server configuration details
+5. Save the configuration
+
+<Callout type="info">
+MCP servers configured in workspace settings are available to all workspace members based on their permission levels.
+</Callout>
+
+### From Agent Configuration
+
+You can also add and configure MCP servers directly from within an agent block:
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="mcp-2.mp4" width={700} height={450} />
+</div>
+
+This is useful when you need to quickly set up a specific integration for a particular workflow.
+
+## Using MCP Tools in Agents
+
+Once MCP servers are configured, their tools become available within your agent blocks:
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="mcp-3.mp4" width={700} height={450} />
+</div>
+
+1. Open an **Agent** block
+2. In the **Tools** section, you'll see available MCP tools
+3. Select the tools you want the agent to use
+4. The agent can now access these tools during execution
+
+## Standalone MCP Tool Block
+
+For more granular control, you can use the dedicated MCP Tool block to execute specific MCP tools:
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="mcp-4.mp4" width={700} height={450} />
+</div>
+
+The MCP Tool block allows you to:
+- Execute any configured MCP tool directly
+- Pass specific parameters to the tool
+- Use the tool's output in subsequent workflow steps
+- Chain multiple MCP tools together
+
+### When to Use MCP Tool vs Agent
+
+**Use Agent with MCP tools when:**
+- You want the AI to decide which tools to use
+- You need complex reasoning about when and how to use tools
+- You want natural language interaction with the tools
+
+**Use MCP Tool block when:**
+- You need deterministic tool execution
+- You want to execute a specific tool with known parameters
+- You're building structured workflows with predictable steps
+
+## Permission Requirements
+
+MCP functionality requires specific workspace permissions:
+
+| Action | Required Permission |
+|--------|-------------------|
+| Configure MCP servers in settings | **Admin** |
+| Use MCP tools in agents | **Write** or **Admin** |
+| View available MCP tools | **Read**, **Write**, or **Admin** |
+| Execute MCP Tool blocks | **Write** or **Admin** |
+
+## Common Use Cases
+
+### Database Integration
+Connect to databases to query, insert, or update data within your workflows.
+
+### API Integrations
+Access external APIs and web services that don't have built-in Sim integrations.
+
+### File System Access
+Read, write, and manipulate files on local or remote file systems.
+
+### Custom Business Logic
+Execute custom scripts or tools specific to your organization's needs.
+
+### Real-time Data Access
+Fetch live data from external systems during workflow execution.
+
+## Security Considerations
+
+- MCP servers run with the permissions of the user who configured them
+- Always verify MCP server sources before installation
+- Use environment variables for sensitive configuration data
+- Review MCP server capabilities before granting access to agents
+
+## Troubleshooting
+
+### MCP Server Not Appearing
+- Verify the server configuration is correct
+- Check that you have the required permissions
+- Ensure the MCP server is running and accessible
+
+### Tool Execution Failures
+- Verify tool parameters are correctly formatted
+- Check MCP server logs for error messages
+- Ensure required authentication is configured
+
+### Permission Errors
+- Confirm your workspace permission level
+- Check if the MCP server requires additional authentication
+- Verify the server is properly configured for your workspace

apps/docs/content/docs/mcp/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "MCP",
+  "pages": ["index"],
+  "defaultOpen": false
+}

apps/docs/content/docs/meta.json

@@ -1,25 +1,25 @@
 {
   "title": "Sim Documentation",
   "pages": [
-    "---Introduction---",
     "./introduction/index",
     "./getting-started/index",
-    "---Create---",
+    "---Building Workflows---",
     "triggers",
     "blocks",
     "tools",
-    "---Connections---",
     "connections",
+    "mcp",
+    "copilot",
+    "knowledgebase",
+    "---Configuration---",
+    "variables",
     "---Execution---",
     "execution",
-    "---Copilot---",
-    "copilot",
     "---Advanced---",
-    "./variables/index",
+    "permissions",
     "yaml",
     "---SDKs---",
-    "./sdks/python",
-    "./sdks/typescript"
+    "sdks"
   ],
-  "defaultOpen": true
+  "defaultOpen": false
 }

apps/docs/content/docs/permissions/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Permissions",
+  "pages": ["roles-and-permissions"],
+  "defaultOpen": false
+}

apps/docs/content/docs/permissions/roles-and-permissions.mdx

@@ -0,0 +1,161 @@
+---
+title: "Roles and Permissions"
+---
+
+import { Video } from '@/components/ui/video'
+
+When you invite team members to your organization or workspace, you'll need to choose what level of access to give them. This guide explains what each permission level allows users to do, helping you understand team roles and what access each permission level provides.
+
+## How to Invite Someone to a Workspace
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="invitations.mp4" width={700} height={450} />
+</div>
+
+## Workspace Permission Levels
+
+When inviting someone to a workspace, you can assign one of three permission levels:
+
+| Permission | What They Can Do |
+|------------|------------------|
+| **Read** | View workflows, see execution results, but cannot make any changes |
+| **Write** | Create and edit workflows, run workflows, manage environment variables |
+| **Admin** | Everything Write can do, plus invite/remove users and manage workspace settings |
+
+## What Each Permission Level Can Do
+
+Here's a detailed breakdown of what users can do with each permission level:
+
+### Read Permission
+**Perfect for:** Stakeholders, observers, or team members who need visibility but shouldn't make changes
+
+**What they can do:**
+- View all workflows in the workspace
+- See workflow execution results and logs
+- Browse workflow configurations and settings
+- View environment variables (but not edit them)
+
+**What they cannot do:**
+- Create, edit, or delete workflows
+- Run or deploy workflows
+- Change any workspace settings
+- Invite other users
+
+### Write Permission  
+**Perfect for:** Developers, content creators, or team members actively working on automation
+
+**What they can do:**
+- Everything Read users can do, plus:
+- Create, edit, and delete workflows
+- Run and deploy workflows
+- Add, edit, and delete workspace environment variables
+- Use all available tools and integrations
+- Collaborate in real-time on workflow editing
+
+**What they cannot do:**
+- Invite or remove users from the workspace
+- Change workspace settings
+- Delete the workspace
+
+### Admin Permission
+**Perfect for:** Team leads, project managers, or technical leads who need to manage the workspace
+
+**What they can do:**
+- Everything Write users can do, plus:
+- Invite new users to the workspace with any permission level
+- Remove users from the workspace
+- Manage workspace settings and integrations
+- Configure external tool connections
+- Delete workflows created by other users
+
+**What they cannot do:**
+- Delete the workspace (only the workspace owner can do this)
+- Remove the workspace owner from the workspace
+
+---
+
+## Workspace Owner vs Admin
+
+Every workspace has one **Owner** (the person who created it) plus any number of **Admins**.
+
+### Workspace Owner
+- Has all Admin permissions
+- Can delete the workspace
+- Cannot be removed from the workspace
+- Can transfer ownership to another user
+
+### Workspace Admin  
+- Can do everything except delete the workspace or remove the owner
+- Can be removed from the workspace by the owner or other admins
+
+---
+
+## Common Scenarios
+
+### Adding a New Developer to Your Team
+1. **Organization level**: Invite them as an **Organization Member**
+2. **Workspace level**: Give them **Write** permission so they can create and edit workflows
+
+### Adding a Project Manager
+1. **Organization level**: Invite them as an **Organization Member** 
+2. **Workspace level**: Give them **Admin** permission so they can manage the team and see everything
+
+### Adding a Stakeholder or Client
+1. **Organization level**: Invite them as an **Organization Member**
+2. **Workspace level**: Give them **Read** permission so they can see progress but not make changes
+
+---
+
+## Environment Variables
+
+Users can create two types of environment variables:
+
+### Personal Environment Variables
+- Only visible to the individual user
+- Available in all workflows they run
+- Managed in user settings
+
+### Workspace Environment Variables
+- **Read permission**: Can see variable names and values
+- **Write/Admin permission**: Can add, edit, and delete variables
+- Available to all workspace members
+- If a personal variable has the same name as a workspace variable, the personal one takes priority
+
+---
+
+## Best Practices
+
+### Start with Minimal Permissions
+Give users the lowest permission level they need to do their job. You can always increase permissions later.
+
+### Use Organization Structure Wisely
+- Make trusted team leads **Organization Admins**
+- Most team members should be **Organization Members**
+- Reserve workspace **Admin** permissions for people who need to manage users
+
+### Review Permissions Regularly
+Periodically review who has access to what, especially when team members change roles or leave the company.
+
+### Environment Variable Security
+- Use personal environment variables for sensitive API keys
+- Use workspace environment variables for shared configuration
+- Regularly audit who has access to sensitive variables
+
+---
+
+## Organization Roles
+
+When inviting someone to your organization, you can assign one of two roles:
+
+### Organization Admin
+**What they can do:**
+- Invite and remove team members from the organization
+- Create new workspaces
+- Manage billing and subscription settings
+- Access all workspaces within the organization
+
+### Organization Member  
+**What they can do:**
+- Access workspaces they've been specifically invited to
+- View the list of organization members
+- Cannot invite new people or manage organization settings

apps/docs/content/docs/sdks/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "SDKs",
+  "pages": ["python", "typescript"]
+}

apps/docs/content/docs/sdks/python.mdx

@@ -1,6 +1,5 @@
 ---
 title: Python SDK
-description: The official Python SDK for Sim
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
@@ -8,7 +7,7 @@ import { Card, Cards } from 'fumadocs-ui/components/card'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 
-The official Python SDK for Sim allows you to execute workflows programmatically from your Python applications.
+The official Python SDK for Sim allows you to execute workflows programmatically from your Python applications using the official Python SDK.
 
 <Callout type="info">
   The Python SDK supports Python 3.8+ and provides synchronous workflow execution. All workflow executions are currently synchronous.

apps/docs/content/docs/sdks/typescript.mdx

@@ -1,6 +1,5 @@
 ---
 title: TypeScript/JavaScript SDK
-description: The official TypeScript/JavaScript SDK for Sim
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
@@ -8,7 +7,7 @@ import { Card, Cards } from 'fumadocs-ui/components/card'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 
-The official TypeScript/JavaScript SDK for Sim allows you to execute workflows programmatically from your Node.js applications, web applications, and other JavaScript environments.
+The official TypeScript/JavaScript SDK for Sim provides full type safety and supports both Node.js and browser environments, allowing you to execute workflows programmatically from your Node.js applications, web applications, and other JavaScript environments. All workflow executions are currently synchronous.
 
 <Callout type="info">
   The TypeScript SDK provides full type safety and supports both Node.js and browser environments. All workflow executions are currently synchronous.

apps/docs/content/docs/tools/jira.mdx

@@ -58,7 +58,7 @@ Retrieve detailed information about a specific Jira issue
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `domain` | string | Yes | Your Jira domain \(e.g., yourcompany.atlassian.net\) |
-| `projectId` | string | No | Jira project ID to retrieve issues from. If not provided, all issues will be retrieved. |
+| `projectId` | string | No | Jira project ID \(optional; not required to retrieve a single issue\). |
 | `issueKey` | string | Yes | Jira issue key to retrieve \(e.g., PROJ-123\) |
 | `cloudId` | string | No | Jira Cloud ID for the instance. If not provided, it will be fetched using the domain. |
 

apps/docs/content/docs/tools/meta.json

@@ -33,12 +33,16 @@
     "microsoft_planner",
     "microsoft_teams",
     "mistral_parse",
+    "mongodb",
+    "mysql",
     "notion",
     "onedrive",
     "openai",
     "outlook",
+    "parallel_ai",
     "perplexity",
     "pinecone",
+    "postgresql",
     "qdrant",
     "reddit",
     "s3",
@@ -62,5 +66,6 @@
     "wikipedia",
     "x",
     "youtube"
-  ]
+  ],
+  "defaultOpen": false
 }

apps/docs/content/docs/tools/microsoft_excel.mdx

@@ -109,7 +109,7 @@ Read data from a Microsoft Excel spreadsheet
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `spreadsheetId` | string | Yes | The ID of the spreadsheet to read from |
-| `range` | string | No | The range of cells to read from |
+| `range` | string | No | The range of cells to read from. Accepts "SheetName!A1:B2" for explicit ranges or just "SheetName" to read the used range of that sheet. If omitted, reads the used range of the first sheet. |
 
 #### Output
 

apps/docs/content/docs/tools/mongodb.mdx

@@ -0,0 +1,264 @@
+---
+title: MongoDB
+description: Connect to MongoDB database
+---
+
+import { BlockInfoCard } from "@/components/ui/block-info-card"
+
+<BlockInfoCard 
+  type="mongodb"
+  color="#E0E0E0"
+  icon={true}
+  iconSvg={`<svg className="block-icon"  xmlns='http://www.w3.org/2000/svg' viewBox='0 0 128 128'>
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='currentColor'
+        d='M88.038 42.812c1.605 4.643 2.761 9.383 3.141 14.296.472 6.095.256 12.147-1.029 18.142-.035.165-.109.32-.164.48-.403.001-.814-.049-1.208.012-3.329.523-6.655 1.065-9.981 1.604-3.438.557-6.881 1.092-10.313 1.687-1.216.21-2.721-.041-3.212 1.641-.014.046-.154.054-.235.08l.166-10.051-.169-24.252 1.602-.275c2.62-.429 5.24-.864 7.862-1.281 3.129-.497 6.261-.98 9.392-1.465 1.381-.215 2.764-.412 4.148-.618z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#45A538'
+        d='M61.729 110.054c-1.69-1.453-3.439-2.842-5.059-4.37-8.717-8.222-15.093-17.899-18.233-29.566-.865-3.211-1.442-6.474-1.627-9.792-.13-2.322-.318-4.665-.154-6.975.437-6.144 1.325-12.229 3.127-18.147l.099-.138c.175.233.427.439.516.702 1.759 5.18 3.505 10.364 5.242 15.551 5.458 16.3 10.909 32.604 16.376 48.9.107.318.384.579.583.866l-.87 2.969z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#46A037'
+        d='M88.038 42.812c-1.384.206-2.768.403-4.149.616-3.131.485-6.263.968-9.392 1.465-2.622.417-5.242.852-7.862 1.281l-1.602.275-.012-1.045c-.053-.859-.144-1.717-.154-2.576-.069-5.478-.112-10.956-.18-16.434-.042-3.429-.105-6.857-.175-10.285-.043-2.13-.089-4.261-.185-6.388-.052-1.143-.236-2.28-.311-3.423-.042-.657.016-1.319.029-1.979.817 1.583 1.616 3.178 2.456 4.749 1.327 2.484 3.441 4.314 5.344 6.311 7.523 7.892 12.864 17.068 16.193 27.433z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#409433'
+        d='M65.036 80.753c.081-.026.222-.034.235-.08.491-1.682 1.996-1.431 3.212-1.641 3.432-.594 6.875-1.13 10.313-1.687 3.326-.539 6.652-1.081 9.981-1.604.394-.062.805-.011 1.208-.012-.622 2.22-1.112 4.488-1.901 6.647-.896 2.449-1.98 4.839-3.131 7.182a49.142 49.142 0 01-6.353 9.763c-1.919 2.308-4.058 4.441-6.202 6.548-1.185 1.165-2.582 2.114-3.882 3.161l-.337-.23-1.214-1.038-1.256-2.753a41.402 41.402 0 01-1.394-9.838l.023-.561.171-2.426c.057-.828.133-1.655.168-2.485.129-2.982.241-5.964.359-8.946z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#4FAA41'
+        d='M65.036 80.753c-.118 2.982-.23 5.964-.357 8.947-.035.83-.111 1.657-.168 2.485l-.765.289c-1.699-5.002-3.399-9.951-5.062-14.913-2.75-8.209-5.467-16.431-8.213-24.642a4498.887 4498.887 0 00-6.7-19.867c-.105-.31-.407-.552-.617-.826l4.896-9.002c.168.292.39.565.496.879a6167.476 6167.476 0 016.768 20.118c2.916 8.73 5.814 17.467 8.728 26.198.116.349.308.671.491 1.062l.67-.78-.167 10.052z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#4AA73C'
+        d='M43.155 32.227c.21.274.511.516.617.826a4498.887 4498.887 0 016.7 19.867c2.746 8.211 5.463 16.433 8.213 24.642 1.662 4.961 3.362 9.911 5.062 14.913l.765-.289-.171 2.426-.155.559c-.266 2.656-.49 5.318-.814 7.968-.163 1.328-.509 2.632-.772 3.947-.198-.287-.476-.548-.583-.866-5.467-16.297-10.918-32.6-16.376-48.9a3888.972 3888.972 0 00-5.242-15.551c-.089-.263-.34-.469-.516-.702l3.272-8.84z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#57AE47'
+        d='M65.202 70.702l-.67.78c-.183-.391-.375-.714-.491-1.062-2.913-8.731-5.812-17.468-8.728-26.198a6167.476 6167.476 0 00-6.768-20.118c-.105-.314-.327-.588-.496-.879l6.055-7.965c.191.255.463.482.562.769 1.681 4.921 3.347 9.848 5.003 14.778 1.547 4.604 3.071 9.215 4.636 13.813.105.308.47.526.714.786l.012 1.045c.058 8.082.115 16.167.171 24.251z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#60B24F'
+        d='M65.021 45.404c-.244-.26-.609-.478-.714-.786-1.565-4.598-3.089-9.209-4.636-13.813-1.656-4.93-3.322-9.856-5.003-14.778-.099-.287-.371-.514-.562-.769 1.969-1.928 3.877-3.925 5.925-5.764 1.821-1.634 3.285-3.386 3.352-5.968.003-.107.059-.214.145-.514l.519 1.306c-.013.661-.072 1.322-.029 1.979.075 1.143.259 2.28.311 3.423.096 2.127.142 4.258.185 6.388.069 3.428.132 6.856.175 10.285.067 5.478.111 10.956.18 16.434.008.861.098 1.718.152 2.577z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#A9AA88'
+        d='M62.598 107.085c.263-1.315.609-2.62.772-3.947.325-2.649.548-5.312.814-7.968l.066-.01.066.011a41.402 41.402 0 001.394 9.838c-.176.232-.425.439-.518.701-.727 2.05-1.412 4.116-2.143 6.166-.1.28-.378.498-.574.744l-.747-2.566.87-2.969z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#B6B598'
+        d='M62.476 112.621c.196-.246.475-.464.574-.744.731-2.05 1.417-4.115 2.143-6.166.093-.262.341-.469.518-.701l1.255 2.754c-.248.352-.59.669-.728 1.061l-2.404 7.059c-.099.283-.437.483-.663.722l-.695-3.985z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#C2C1A7'
+        d='M63.171 116.605c.227-.238.564-.439.663-.722l2.404-7.059c.137-.391.48-.709.728-1.061l1.215 1.037c-.587.58-.913 1.25-.717 2.097l-.369 1.208c-.168.207-.411.387-.494.624-.839 2.403-1.64 4.819-2.485 7.222-.107.305-.404.544-.614.812-.109-1.387-.22-2.771-.331-4.158z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#CECDB7'
+        d='M63.503 120.763c.209-.269.506-.508.614-.812.845-2.402 1.646-4.818 2.485-7.222.083-.236.325-.417.494-.624l-.509 5.545c-.136.157-.333.294-.398.477-.575 1.614-1.117 3.24-1.694 4.854-.119.333-.347.627-.525.938-.158-.207-.441-.407-.454-.623-.051-.841-.016-1.688-.013-2.533z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#DBDAC7'
+        d='M63.969 123.919c.178-.312.406-.606.525-.938.578-1.613 1.119-3.239 1.694-4.854.065-.183.263-.319.398-.477l.012 3.64-1.218 3.124-1.411-.495z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#EBE9DC'
+        d='M65.38 124.415l1.218-3.124.251 3.696-1.469-.572z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#CECDB7'
+        d='M67.464 110.898c-.196-.847.129-1.518.717-2.097l.337.23-1.054 1.867z'
+      />
+      <path
+        fillRule='evenodd'
+        clipRule='evenodd'
+        fill='#4FAA41'
+        d='M64.316 95.172l-.066-.011-.066.01.155-.559-.023.56z'
+      />
+    </svg>`}
+/>
+
+## Usage Instructions
+
+Connect to any MongoDB database to execute queries, manage data, and perform database operations. Supports find, insert, update, delete, and aggregation operations with secure connection handling.
+
+
+
+## Tools
+
+### `mongodb_query`
+
+Execute find operation on MongoDB collection
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | MongoDB server hostname or IP address |
+| `port` | number | Yes | MongoDB server port \(default: 27017\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | No | MongoDB username |
+| `password` | string | No | MongoDB password |
+| `authSource` | string | No | Authentication database |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `collection` | string | Yes | Collection name to query |
+| `query` | string | No | MongoDB query filter as JSON string |
+| `limit` | number | No | Maximum number of documents to return |
+| `sort` | string | No | Sort criteria as JSON string |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `documents` | array | Array of documents returned from the query |
+| `documentCount` | number | Number of documents returned |
+
+### `mongodb_insert`
+
+Insert documents into MongoDB collection
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | MongoDB server hostname or IP address |
+| `port` | number | Yes | MongoDB server port \(default: 27017\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | No | MongoDB username |
+| `password` | string | No | MongoDB password |
+| `authSource` | string | No | Authentication database |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `collection` | string | Yes | Collection name to insert into |
+| `documents` | array | Yes | Array of documents to insert |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `documentCount` | number | Number of documents inserted |
+| `insertedId` | string | ID of inserted document \(single insert\) |
+| `insertedIds` | array | Array of inserted document IDs \(multiple insert\) |
+
+### `mongodb_update`
+
+Update documents in MongoDB collection
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | MongoDB server hostname or IP address |
+| `port` | number | Yes | MongoDB server port \(default: 27017\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | No | MongoDB username |
+| `password` | string | No | MongoDB password |
+| `authSource` | string | No | Authentication database |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `collection` | string | Yes | Collection name to update |
+| `filter` | string | Yes | Filter criteria as JSON string |
+| `update` | string | Yes | Update operations as JSON string |
+| `upsert` | boolean | No | Create document if not found |
+| `multi` | boolean | No | Update multiple documents |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `matchedCount` | number | Number of documents matched by filter |
+| `modifiedCount` | number | Number of documents modified |
+| `documentCount` | number | Total number of documents affected |
+| `insertedId` | string | ID of inserted document \(if upsert\) |
+
+### `mongodb_delete`
+
+Delete documents from MongoDB collection
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | MongoDB server hostname or IP address |
+| `port` | number | Yes | MongoDB server port \(default: 27017\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | No | MongoDB username |
+| `password` | string | No | MongoDB password |
+| `authSource` | string | No | Authentication database |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `collection` | string | Yes | Collection name to delete from |
+| `filter` | string | Yes | Filter criteria as JSON string |
+| `multi` | boolean | No | Delete multiple documents |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `deletedCount` | number | Number of documents deleted |
+| `documentCount` | number | Total number of documents affected |
+
+### `mongodb_execute`
+
+Execute MongoDB aggregation pipeline
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | MongoDB server hostname or IP address |
+| `port` | number | Yes | MongoDB server port \(default: 27017\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | No | MongoDB username |
+| `password` | string | No | MongoDB password |
+| `authSource` | string | No | Authentication database |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `collection` | string | Yes | Collection name to execute pipeline on |
+| `pipeline` | string | Yes | Aggregation pipeline as JSON string |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `documents` | array | Array of documents returned from aggregation |
+| `documentCount` | number | Number of documents returned |
+
+
+
+## Notes
+
+- Category: `tools`
+- Type: `mongodb`

apps/docs/content/docs/tools/mysql.mdx

@@ -0,0 +1,180 @@
+---
+title: MySQL
+description: Connect to MySQL database
+---
+
+import { BlockInfoCard } from "@/components/ui/block-info-card"
+
+<BlockInfoCard 
+  type="mysql"
+  color="#E0E0E0"
+  icon={true}
+  iconSvg={`<svg className="block-icon"
+      
+      xmlns='http://www.w3.org/2000/svg'
+      
+      
+      viewBox='0 0 25.6 25.6'
+    >
+      <path
+        d='M179.076 94.886c-3.568-.1-6.336.268-8.656 1.25-.668.27-1.74.27-1.828 1.116.357.355.4.936.713 1.428.535.893 1.473 2.096 2.32 2.72l2.855 2.053c1.74 1.07 3.703 1.695 5.398 2.766.982.625 1.963 1.428 2.945 2.098.5.357.803.938 1.428 1.16v-.135c-.312-.4-.402-.98-.713-1.428l-1.34-1.293c-1.293-1.74-2.9-3.258-4.64-4.506-1.428-.982-4.55-2.32-5.13-3.97l-.088-.1c.98-.1 2.14-.447 3.078-.715 1.518-.4 2.9-.312 4.46-.713l2.143-.625v-.4c-.803-.803-1.383-1.874-2.23-2.632-2.275-1.963-4.775-3.882-7.363-5.488-1.383-.892-3.168-1.473-4.64-2.23-.537-.268-1.428-.402-1.74-.848-.805-.98-1.25-2.275-1.83-3.436l-3.658-7.763c-.803-1.74-1.295-3.48-2.275-5.086-4.596-7.585-9.594-12.18-17.268-16.687-1.65-.937-3.613-1.34-5.7-1.83l-3.346-.18c-.715-.312-1.428-1.16-2.053-1.562-2.543-1.606-9.102-5.086-10.977-.5-1.205 2.9 1.785 5.755 2.8 7.228.76 1.026 1.74 2.186 2.277 3.346.3.758.4 1.562.713 2.365.713 1.963 1.383 4.15 2.32 5.98.5.937 1.025 1.92 1.65 2.767.357.5.982.714 1.115 1.517-.625.893-.668 2.23-1.025 3.347-1.607 5.042-.982 11.288 1.293 15 .715 1.115 2.4 3.57 4.686 2.632 2.008-.803 1.56-3.346 2.14-5.577.135-.535.045-.892.312-1.25v.1l1.83 3.703c1.383 2.186 3.793 4.462 5.8 5.98 1.07.803 1.918 2.187 3.256 2.677v-.135h-.088c-.268-.4-.67-.58-1.027-.892-.803-.803-1.695-1.785-2.32-2.677-1.873-2.498-3.523-5.265-4.996-8.12-.715-1.383-1.34-2.9-1.918-4.283-.27-.536-.27-1.34-.715-1.606-.67.98-1.65 1.83-2.143 3.034-.848 1.918-.936 4.283-1.248 6.737-.18.045-.1 0-.18.1-1.426-.356-1.918-1.83-2.453-3.078-1.338-3.168-1.562-8.254-.402-11.913.312-.937 1.652-3.882 1.117-4.774-.27-.848-1.16-1.338-1.652-2.008-.58-.848-1.203-1.918-1.605-2.855-1.07-2.5-1.605-5.265-2.766-7.764-.537-1.16-1.473-2.365-2.232-3.435-.848-1.205-1.783-2.053-2.453-3.48-.223-.5-.535-1.294-.178-1.83.088-.357.268-.5.623-.58.58-.5 2.232.134 2.812.4 1.65.67 3.033 1.294 4.416 2.23.625.446 1.295 1.294 2.098 1.518h.938c1.428.312 3.033.1 4.37.5 2.365.76 4.506 1.874 6.426 3.08 5.844 3.703 10.664 8.968 13.92 15.26.535 1.026.758 1.963 1.25 3.034.938 2.187 2.098 4.417 3.033 6.56.938 2.097 1.83 4.24 3.168 5.98.67.937 3.346 1.427 4.55 1.918.893.4 2.275.76 3.08 1.25 1.516.937 3.033 2.008 4.46 3.034.713.534 2.945 1.65 3.078 2.54zm-45.5-38.772a7.09 7.09 0 0 0-1.828.223v.1h.088c.357.714.982 1.205 1.428 1.83l1.027 2.142.088-.1c.625-.446.938-1.16.938-2.23-.268-.312-.312-.625-.535-.937-.268-.446-.848-.67-1.206-1.026z'
+        transform='matrix(.390229 0 0 .38781 -46.300037 -16.856717)'
+        fillRule='evenodd'
+        fill='#00678c'
+      />
+    </svg>`}
+/>
+
+{/* MANUAL-CONTENT-START:intro */}
+The [MySQL](https://www.mysql.com/) tool enables you to connect to any MySQL database and perform a wide range of database operations directly within your agentic workflows. With secure connection handling and flexible configuration, you can easily manage and interact with your data.
+
+With the MySQL tool, you can:
+
+- **Query data**: Execute SELECT queries to retrieve data from your MySQL tables using the `mysql_query` operation.
+- **Insert records**: Add new rows to your tables with the `mysql_insert` operation by specifying the table and data to insert.
+- **Update records**: Modify existing data in your tables using the `mysql_update` operation, providing the table, new data, and WHERE conditions.
+- **Delete records**: Remove rows from your tables with the `mysql_delete` operation, specifying the table and WHERE conditions.
+- **Execute raw SQL**: Run any custom SQL command using the `mysql_execute` operation for advanced use cases.
+
+The MySQL tool is ideal for scenarios where your agents need to interact with structured data—such as automating reporting, syncing data between systems, or powering data-driven workflows. It streamlines database access, making it easy to read, write, and manage your MySQL data programmatically.
+{/* MANUAL-CONTENT-END */}
+
+
+## Usage Instructions
+
+Connect to any MySQL database to execute queries, manage data, and perform database operations. Supports SELECT, INSERT, UPDATE, DELETE operations with secure connection handling.
+
+
+
+## Tools
+
+### `mysql_query`
+
+Execute SELECT query on MySQL database
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | MySQL server hostname or IP address |
+| `port` | number | Yes | MySQL server port \(default: 3306\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | Yes | Database username |
+| `password` | string | Yes | Database password |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `query` | string | Yes | SQL SELECT query to execute |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `rows` | array | Array of rows returned from the query |
+| `rowCount` | number | Number of rows returned |
+
+### `mysql_insert`
+
+Insert new record into MySQL database
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | MySQL server hostname or IP address |
+| `port` | number | Yes | MySQL server port \(default: 3306\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | Yes | Database username |
+| `password` | string | Yes | Database password |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `table` | string | Yes | Table name to insert into |
+| `data` | object | Yes | Data to insert as key-value pairs |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `rows` | array | Array of inserted rows |
+| `rowCount` | number | Number of rows inserted |
+
+### `mysql_update`
+
+Update existing records in MySQL database
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | MySQL server hostname or IP address |
+| `port` | number | Yes | MySQL server port \(default: 3306\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | Yes | Database username |
+| `password` | string | Yes | Database password |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `table` | string | Yes | Table name to update |
+| `data` | object | Yes | Data to update as key-value pairs |
+| `where` | string | Yes | WHERE clause condition \(without WHERE keyword\) |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `rows` | array | Array of updated rows |
+| `rowCount` | number | Number of rows updated |
+
+### `mysql_delete`
+
+Delete records from MySQL database
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | MySQL server hostname or IP address |
+| `port` | number | Yes | MySQL server port \(default: 3306\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | Yes | Database username |
+| `password` | string | Yes | Database password |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `table` | string | Yes | Table name to delete from |
+| `where` | string | Yes | WHERE clause condition \(without WHERE keyword\) |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `rows` | array | Array of deleted rows |
+| `rowCount` | number | Number of rows deleted |
+
+### `mysql_execute`
+
+Execute raw SQL query on MySQL database
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | MySQL server hostname or IP address |
+| `port` | number | Yes | MySQL server port \(default: 3306\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | Yes | Database username |
+| `password` | string | Yes | Database password |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `query` | string | Yes | Raw SQL query to execute |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `rows` | array | Array of rows returned from the query |
+| `rowCount` | number | Number of rows affected |
+
+
+
+## Notes
+
+- Category: `tools`
+- Type: `mysql`

apps/docs/content/docs/tools/onedrive.mdx

@@ -68,7 +68,7 @@ Upload a file to OneDrive
 | `fileName` | string | Yes | The name of the file to upload |
 | `content` | string | Yes | The content of the file to upload |
 | `folderSelector` | string | No | Select the folder to upload the file to |
-| `folderId` | string | No | The ID of the folder to upload the file to \(internal use\) |
+| `manualFolderId` | string | No | Manually entered folder ID \(advanced mode\) |
 
 #### Output
 
@@ -87,7 +87,7 @@ Create a new folder in OneDrive
 | --------- | ---- | -------- | ----------- |
 | `folderName` | string | Yes | Name of the folder to create |
 | `folderSelector` | string | No | Select the parent folder to create the folder in |
-| `folderId` | string | No | ID of the parent folder \(internal use\) |
+| `manualFolderId` | string | No | Manually entered parent folder ID \(advanced mode\) |
 
 #### Output
 
@@ -105,7 +105,7 @@ List files and folders in OneDrive
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `folderSelector` | string | No | Select the folder to list files from |
-| `folderId` | string | No | The ID of the folder to list files from \(internal use\) |
+| `manualFolderId` | string | No | The manually entered folder ID \(advanced mode\) |
 | `query` | string | No | A query to filter the files |
 | `pageSize` | number | No | The number of files to return |
 

apps/docs/content/docs/tools/outlook.mdx

@@ -211,10 +211,27 @@ Read emails from Outlook
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
-| `success` | boolean | Email read operation success status |
-| `messageCount` | number | Number of emails retrieved |
-| `messages` | array | Array of email message objects |
 | `message` | string | Success or status message |
+| `results` | array | Array of email message objects |
+
+### `outlook_forward`
+
+Forward an existing Outlook message to specified recipients
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `messageId` | string | Yes | The ID of the message to forward |
+| `to` | string | Yes | Recipient email address\(es\), comma-separated |
+| `comment` | string | No | Optional comment to include with the forwarded message |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Success or error message |
+| `results` | object | Delivery result details |
 
 
 

apps/docs/content/docs/tools/parallel_ai.mdx

@@ -0,0 +1,106 @@
+---
+title: Parallel AI
+description: Search with Parallel AI
+---
+
+import { BlockInfoCard } from "@/components/ui/block-info-card"
+
+<BlockInfoCard 
+  type="parallel_ai"
+  color="#E0E0E0"
+  icon={true}
+  iconSvg={`<svg className="block-icon"
+      
+      fill='currentColor'
+      
+      
+      viewBox='0 0 271 270'
+      xmlns='http://www.w3.org/2000/svg'
+    >
+      <path
+        d='M267.804 105.65H193.828C194.026 106.814 194.187 107.996 194.349 109.178H76.6703C76.4546 110.736 76.2388 112.312 76.0591 113.87H1.63342C1.27387 116.198 0.950289 118.543 0.698608 120.925H75.3759C75.2501 122.483 75.1602 124.059 75.0703 125.617H195.949C196.003 126.781 196.057 127.962 196.093 129.144H270.68V125.384C270.195 118.651 269.242 112.061 267.804 105.65Z'
+        fill='#1D1C1A'
+      />
+      <path
+        d='M195.949 144.401H75.0703C75.1422 145.977 75.2501 147.535 75.3759 149.093H0.698608C0.950289 151.457 1.2559 153.802 1.63342 156.148H76.0591C76.2388 157.724 76.4366 159.282 76.6703 160.84H194.349C194.187 162.022 194.008 163.186 193.828 164.367H267.804C269.242 157.957 270.195 151.367 270.68 144.634V140.874H196.093C196.057 142.055 196.003 143.219 195.949 144.401Z'
+        fill='#1D1C1A'
+      />
+      <path
+        d='M190.628 179.642H80.3559C80.7514 181.218 81.1828 182.776 81.6143 184.334H9.30994C10.2448 186.715 11.2515 189.061 12.3121 191.389H83.7536C84.2749 192.965 84.7962 194.523 85.3535 196.08H185.594C185.163 197.262 184.732 198.426 184.282 199.608H254.519C258.6 192.177 261.98 184.316 264.604 176.114H191.455C191.185 177.296 190.898 178.46 190.61 179.642H190.628Z'
+        fill='#1D1C1A'
+      />
+      <path
+        d='M177.666 214.883H93.3352C94.1082 216.458 94.9172 218.034 95.7441 219.574H29.8756C31.8351 221.992 33.8666 224.337 35.9699 226.63H99.6632C100.598 228.205 101.551 229.781 102.522 231.321H168.498C167.761 232.503 167.006 233.685 166.233 234.849H226.762C234.474 227.847 241.36 219.95 247.292 211.355H179.356C178.799 212.537 178.26 213.719 177.684 214.883H177.666Z'
+        fill='#1D1C1A'
+      />
+      <path
+        d='M154.943 250.106H116.058C117.371 251.699 118.701 253.257 120.067 254.797H73.021C91.6094 264.431 112.715 269.946 135.096 270C135.24 270 135.366 270 135.492 270C135.618 270 135.761 270 135.887 270C164.04 269.911 190.178 261.28 211.805 246.56H157.748C156.813 247.742 155.878 248.924 154.925 250.088L154.943 250.106Z'
+        fill='#1D1C1A'
+      />
+      <path
+        d='M116.059 19.9124H154.943C155.896 21.0764 156.831 22.2582 157.766 23.4401H211.823C190.179 8.72065 164.058 0.0895344 135.906 0C135.762 0 135.636 0 135.51 0C135.384 0 135.24 0 135.115 0C112.715 0.0716275 91.6277 5.56904 73.0393 15.2029H120.086C118.719 16.7429 117.389 18.3187 116.077 19.8945L116.059 19.9124Z'
+        fill='#1D1C1A'
+      />
+      <path
+        d='M93.3356 55.1532H177.667C178.242 56.3171 178.799 57.499 179.339 58.6808H247.274C241.342 50.0855 234.457 42.1886 226.744 35.187H166.215C166.988 36.351 167.743 37.5328 168.48 38.7147H102.504C101.533 40.2726 100.58 41.8305 99.6456 43.4063H35.9523C33.831 45.6804 31.7996 48.0262 29.858 50.4616H95.7265C94.8996 52.0195 94.1086 53.5774 93.3176 55.1532H93.3356Z'
+        fill='#1D1C1A'
+      />
+      <path
+        d='M80.3736 90.3758H190.646C190.933 91.5398 191.221 92.7216 191.491 93.9035H264.64C262.015 85.7021 258.636 77.841 254.555 70.4097H184.318C184.767 71.5736 185.199 72.7555 185.63 73.9373H85.3893C84.832 75.4952 84.2927 77.0531 83.7893 78.6289H12.3479C11.2872 80.9389 10.2805 83.2847 9.3457 85.6842H81.65C81.2186 87.2421 80.7871 88.8 80.3916 90.3758H80.3736Z'
+        fill='#1D1C1A'
+      />
+    </svg>`}
+/>
+
+{/* MANUAL-CONTENT-START:intro */}
+[Parallel AI](https://parallel.ai/) is an advanced web search and content extraction platform designed to deliver comprehensive, high-quality results for any query. By leveraging intelligent processing and large-scale data extraction, Parallel AI enables users and agents to access, analyze, and synthesize information from across the web with speed and accuracy.
+
+With Parallel AI, you can:
+
+- **Search the web intelligently**: Retrieve relevant, up-to-date information from a wide range of sources  
+- **Extract and summarize content**: Get concise, meaningful excerpts from web pages and documents  
+- **Customize search objectives**: Tailor queries to specific needs or questions for targeted results  
+- **Process results at scale**: Handle large volumes of search results with advanced processing options  
+- **Integrate with workflows**: Use Parallel AI within Sim to automate research, content gathering, and knowledge extraction  
+- **Control output granularity**: Specify the number of results and the amount of content per result  
+- **Secure API access**: Protect your searches and data with API key authentication
+
+In Sim, the Parallel AI integration empowers your agents to perform web searches and extract content programmatically. This enables powerful automation scenarios such as real-time research, competitive analysis, content monitoring, and knowledge base creation. By connecting Sim with Parallel AI, you unlock the ability for agents to gather, process, and utilize web data as part of your automated workflows.
+{/* MANUAL-CONTENT-END */}
+
+
+## Usage Instructions
+
+Search the web using Parallel AI's advanced search capabilities. Get comprehensive results with intelligent processing and content extraction.
+
+
+
+## Tools
+
+### `parallel_search`
+
+Search the web using Parallel AI. Provides comprehensive search results with intelligent processing and content extraction.
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `objective` | string | Yes | The search objective or question to answer |
+| `search_queries` | string | No | Optional comma-separated list of search queries to execute |
+| `processor` | string | No | Processing method: base or pro \(default: base\) |
+| `max_results` | number | No | Maximum number of results to return \(default: 5\) |
+| `max_chars_per_result` | number | No | Maximum characters per result \(default: 1500\) |
+| `apiKey` | string | Yes | Parallel AI API Key |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `results` | array | Search results with excerpts from relevant pages |
+
+
+
+## Notes
+
+- Category: `tools`
+- Type: `parallel_ai`

apps/docs/content/docs/tools/postgresql.mdx

@@ -0,0 +1,188 @@
+---
+title: PostgreSQL
+description: Connect to PostgreSQL database
+---
+
+import { BlockInfoCard } from "@/components/ui/block-info-card"
+
+<BlockInfoCard 
+  type="postgresql"
+  color="#336791"
+  icon={true}
+  iconSvg={`<svg className="block-icon"
+      
+      
+      
+      viewBox='-4 0 264 264'
+      xmlns='http://www.w3.org/2000/svg'
+      preserveAspectRatio='xMinYMin meet'
+    >
+      <path d='M255.008 158.086c-1.535-4.649-5.556-7.887-10.756-8.664-2.452-.366-5.26-.21-8.583.475-5.792 1.195-10.089 1.65-13.225 1.738 11.837-19.985 21.462-42.775 27.003-64.228 8.96-34.689 4.172-50.492-1.423-57.64C233.217 10.847 211.614.683 185.552.372c-13.903-.17-26.108 2.575-32.475 4.549-5.928-1.046-12.302-1.63-18.99-1.738-12.537-.2-23.614 2.533-33.079 8.15-5.24-1.772-13.65-4.27-23.362-5.864-22.842-3.75-41.252-.828-54.718 8.685C6.622 25.672-.937 45.684.461 73.634c.444 8.874 5.408 35.874 13.224 61.48 4.492 14.718 9.282 26.94 14.237 36.33 7.027 13.315 14.546 21.156 22.987 23.972 4.731 1.576 13.327 2.68 22.368-4.85 1.146 1.388 2.675 2.767 4.704 4.048 2.577 1.625 5.728 2.953 8.875 3.74 11.341 2.835 21.964 2.126 31.027-1.848.056 1.612.099 3.152.135 4.482.06 2.157.12 4.272.199 6.25.537 13.374 1.447 23.773 4.143 31.049.148.4.347 1.01.557 1.657 1.345 4.118 3.594 11.012 9.316 16.411 5.925 5.593 13.092 7.308 19.656 7.308 3.292 0 6.433-.432 9.188-1.022 9.82-2.105 20.973-5.311 29.041-16.799 7.628-10.86 11.336-27.217 12.007-52.99.087-.729.167-1.425.244-2.088l.16-1.362 1.797.158.463.031c10.002.456 22.232-1.665 29.743-5.154 5.935-2.754 24.954-12.795 20.476-26.351' />
+      <path
+        d='M237.906 160.722c-29.74 6.135-31.785-3.934-31.785-3.934 31.4-46.593 44.527-105.736 33.2-120.211-30.904-39.485-84.399-20.811-85.292-20.327l-.287.052c-5.876-1.22-12.451-1.946-19.842-2.067-13.456-.22-23.664 3.528-31.41 9.402 0 0-95.43-39.314-90.991 49.444.944 18.882 27.064 142.873 58.218 105.422 11.387-13.695 22.39-25.274 22.39-25.274 5.464 3.63 12.006 5.482 18.864 4.817l.533-.452c-.166 1.7-.09 3.363.213 5.332-8.026 8.967-5.667 10.541-21.711 13.844-16.235 3.346-6.698 9.302-.471 10.86 7.549 1.887 25.013 4.561 36.813-11.958l-.47 1.885c3.144 2.519 5.352 16.383 4.982 28.952-.37 12.568-.617 21.197 1.86 27.937 2.479 6.74 4.948 21.905 26.04 17.386 17.623-3.777 26.756-13.564 28.027-29.89.901-11.606 2.942-9.89 3.07-20.267l1.637-4.912c1.887-15.733.3-20.809 11.157-18.448l2.64.232c7.99.363 18.45-1.286 24.589-4.139 13.218-6.134 21.058-16.377 8.024-13.686h.002'
+        fill='#336791'
+      />
+      <path
+        d='M108.076 81.525c-2.68-.373-5.107-.028-6.335.902-.69.523-.904 1.129-.962 1.546-.154 1.105.62 2.327 1.096 2.957 1.346 1.784 3.312 3.01 5.258 3.28.282.04.563.058.842.058 3.245 0 6.196-2.527 6.456-4.392.325-2.336-3.066-3.893-6.355-4.35M196.86 81.599c-.256-1.831-3.514-2.353-6.606-1.923-3.088.43-6.082 1.824-5.832 3.659.2 1.427 2.777 3.863 5.827 3.863.258 0 .518-.017.78-.054 2.036-.282 3.53-1.575 4.24-2.32 1.08-1.136 1.706-2.402 1.591-3.225'
+        fill='#FFF'
+      />
+      <path
+        d='M247.802 160.025c-1.134-3.429-4.784-4.532-10.848-3.28-18.005 3.716-24.453 1.142-26.57-.417 13.995-21.32 25.508-47.092 31.719-71.137 2.942-11.39 4.567-21.968 4.7-30.59.147-9.463-1.465-16.417-4.789-20.665-13.402-17.125-33.072-26.311-56.882-26.563-16.369-.184-30.199 4.005-32.88 5.183-5.646-1.404-11.801-2.266-18.502-2.376-12.288-.199-22.91 2.743-31.704 8.74-3.82-1.422-13.692-4.811-25.765-6.756-20.872-3.36-37.458-.814-49.294 7.571-14.123 10.006-20.643 27.892-19.38 53.16.425 8.501 5.269 34.653 12.913 59.698 10.062 32.964 21 51.625 32.508 55.464 1.347.449 2.9.763 4.613.763 4.198 0 9.345-1.892 14.7-8.33a529.832 529.832 0 0 1 20.261-22.926c4.524 2.428 9.494 3.784 14.577 3.92.01.133.023.266.035.398a117.66 117.66 0 0 0-2.57 3.175c-3.522 4.471-4.255 5.402-15.592 7.736-3.225.666-11.79 2.431-11.916 8.435-.136 6.56 10.125 9.315 11.294 9.607 4.074 1.02 7.999 1.523 11.742 1.523 9.103 0 17.114-2.992 23.516-8.781-.197 23.386.778 46.43 3.586 53.451 2.3 5.748 7.918 19.795 25.664 19.794 2.604 0 5.47-.303 8.623-.979 18.521-3.97 26.564-12.156 29.675-30.203 1.665-9.645 4.522-32.676 5.866-45.03 2.836.885 6.487 1.29 10.434 1.289 8.232 0 17.731-1.749 23.688-4.514 6.692-3.108 18.768-10.734 16.578-17.36zm-44.106-83.48c-.061 3.647-.563 6.958-1.095 10.414-.573 3.717-1.165 7.56-1.314 12.225-.147 4.54.42 9.26.968 13.825 1.108 9.22 2.245 18.712-2.156 28.078a36.508 36.508 0 0 1-1.95-4.009c-.547-1.326-1.735-3.456-3.38-6.404-6.399-11.476-21.384-38.35-13.713-49.316 2.285-3.264 8.084-6.62 22.64-4.813zm-17.644-61.787c21.334.471 38.21 8.452 50.158 23.72 9.164 11.711-.927 64.998-30.14 110.969a171.33 171.33 0 0 0-.886-1.117l-.37-.462c7.549-12.467 6.073-24.802 4.759-35.738-.54-4.488-1.05-8.727-.92-12.709.134-4.22.692-7.84 1.232-11.34.663-4.313 1.338-8.776 1.152-14.037.139-.552.195-1.204.122-1.978-.475-5.045-6.235-20.144-17.975-33.81-6.422-7.475-15.787-15.84-28.574-21.482 5.5-1.14 13.021-2.203 21.442-2.016zM66.674 175.778c-5.9 7.094-9.974 5.734-11.314 5.288-8.73-2.912-18.86-21.364-27.791-50.624-7.728-25.318-12.244-50.777-12.602-57.916-1.128-22.578 4.345-38.313 16.268-46.769 19.404-13.76 51.306-5.524 64.125-1.347-.184.182-.376.352-.558.537-21.036 21.244-20.537 57.54-20.485 59.759-.002.856.07 2.068.168 3.735.362 6.105 1.036 17.467-.764 30.334-1.672 11.957 2.014 23.66 10.111 32.109a36.275 36.275 0 0 0 2.617 2.468c-3.604 3.86-11.437 12.396-19.775 22.426zm22.479-29.993c-6.526-6.81-9.49-16.282-8.133-25.99 1.9-13.592 1.199-25.43.822-31.79-.053-.89-.1-1.67-.127-2.285 3.073-2.725 17.314-10.355 27.47-8.028 4.634 1.061 7.458 4.217 8.632 9.645 6.076 28.103.804 39.816-3.432 49.229-.873 1.939-1.698 3.772-2.402 5.668l-.546 1.466c-1.382 3.706-2.668 7.152-3.465 10.424-6.938-.02-13.687-2.984-18.819-8.34zm1.065 37.9c-2.026-.506-3.848-1.385-4.917-2.114.893-.42 2.482-.992 5.238-1.56 13.337-2.745 15.397-4.683 19.895-10.394 1.031-1.31 2.2-2.794 3.819-4.602l.002-.002c2.411-2.7 3.514-2.242 5.514-1.412 1.621.67 3.2 2.702 3.84 4.938.303 1.056.643 3.06-.47 4.62-9.396 13.156-23.088 12.987-32.921 10.526zm69.799 64.952c-16.316 3.496-22.093-4.829-25.9-14.346-2.457-6.144-3.665-33.85-2.808-64.447.011-.407-.047-.8-.159-1.17a15.444 15.444 0 0 0-.456-2.162c-1.274-4.452-4.379-8.176-8.104-9.72-1.48-.613-4.196-1.738-7.46-.903.696-2.868 1.903-6.107 3.212-9.614l.549-1.475c.618-1.663 1.394-3.386 2.214-5.21 4.433-9.848 10.504-23.337 3.915-53.81-2.468-11.414-10.71-16.988-23.204-15.693-7.49.775-14.343 3.797-17.761 5.53-.735.372-1.407.732-2.035 1.082.954-11.5 4.558-32.992 18.04-46.59 8.489-8.56 19.794-12.788 33.568-12.56 27.14.444 44.544 14.372 54.366 25.979 8.464 10.001 13.047 20.076 14.876 25.51-13.755-1.399-23.11 1.316-27.852 8.096-10.317 14.748 5.644 43.372 13.315 57.129 1.407 2.521 2.621 4.7 3.003 5.626 2.498 6.054 5.732 10.096 8.093 13.046.724.904 1.426 1.781 1.96 2.547-4.166 1.201-11.649 3.976-10.967 17.847-.55 6.96-4.461 39.546-6.448 51.059-2.623 15.21-8.22 20.875-23.957 24.25zm68.104-77.936c-4.26 1.977-11.389 3.46-18.161 3.779-7.48.35-11.288-.838-12.184-1.569-.42-8.644 2.797-9.547 6.202-10.503.535-.15 1.057-.297 1.561-.473.313.255.656.508 1.032.756 6.012 3.968 16.735 4.396 31.874 1.271l.166-.033c-2.042 1.909-5.536 4.471-10.49 6.772z'
+        fill='#FFF'
+      />
+    </svg>`}
+/>
+
+{/* MANUAL-CONTENT-START:intro */}
+The [PostgreSQL](https://www.postgresql.org/) tool enables you to connect to any PostgreSQL database and perform a wide range of database operations directly within your agentic workflows. With secure connection handling and flexible configuration, you can easily manage and interact with your data.
+
+With the PostgreSQL tool, you can:
+
+- **Query data**: Execute SELECT queries to retrieve data from your PostgreSQL tables using the `postgresql_query` operation.
+- **Insert records**: Add new rows to your tables with the `postgresql_insert` operation by specifying the table and data to insert.
+- **Update records**: Modify existing data in your tables using the `postgresql_update` operation, providing the table, new data, and WHERE conditions.
+- **Delete records**: Remove rows from your tables with the `postgresql_delete` operation, specifying the table and WHERE conditions.
+- **Execute raw SQL**: Run any custom SQL command using the `postgresql_execute` operation for advanced use cases.
+
+The PostgreSQL tool is ideal for scenarios where your agents need to interact with structured data—such as automating reporting, syncing data between systems, or powering data-driven workflows. It streamlines database access, making it easy to read, write, and manage your PostgreSQL data programmatically.
+{/* MANUAL-CONTENT-END */}
+
+
+## Usage Instructions
+
+Connect to any PostgreSQL database to execute queries, manage data, and perform database operations. Supports SELECT, INSERT, UPDATE, DELETE operations with secure connection handling.
+
+
+
+## Tools
+
+### `postgresql_query`
+
+Execute a SELECT query on PostgreSQL database
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | PostgreSQL server hostname or IP address |
+| `port` | number | Yes | PostgreSQL server port \(default: 5432\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | Yes | Database username |
+| `password` | string | Yes | Database password |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `query` | string | Yes | SQL SELECT query to execute |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `rows` | array | Array of rows returned from the query |
+| `rowCount` | number | Number of rows returned |
+
+### `postgresql_insert`
+
+Insert data into PostgreSQL database
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | PostgreSQL server hostname or IP address |
+| `port` | number | Yes | PostgreSQL server port \(default: 5432\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | Yes | Database username |
+| `password` | string | Yes | Database password |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `table` | string | Yes | Table name to insert data into |
+| `data` | object | Yes | Data object to insert \(key-value pairs\) |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `rows` | array | Inserted data \(if RETURNING clause used\) |
+| `rowCount` | number | Number of rows inserted |
+
+### `postgresql_update`
+
+Update data in PostgreSQL database
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | PostgreSQL server hostname or IP address |
+| `port` | number | Yes | PostgreSQL server port \(default: 5432\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | Yes | Database username |
+| `password` | string | Yes | Database password |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `table` | string | Yes | Table name to update data in |
+| `data` | object | Yes | Data object with fields to update \(key-value pairs\) |
+| `where` | string | Yes | WHERE clause condition \(without WHERE keyword\) |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `rows` | array | Updated data \(if RETURNING clause used\) |
+| `rowCount` | number | Number of rows updated |
+
+### `postgresql_delete`
+
+Delete data from PostgreSQL database
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | PostgreSQL server hostname or IP address |
+| `port` | number | Yes | PostgreSQL server port \(default: 5432\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | Yes | Database username |
+| `password` | string | Yes | Database password |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `table` | string | Yes | Table name to delete data from |
+| `where` | string | Yes | WHERE clause condition \(without WHERE keyword\) |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `rows` | array | Deleted data \(if RETURNING clause used\) |
+| `rowCount` | number | Number of rows deleted |
+
+### `postgresql_execute`
+
+Execute raw SQL query on PostgreSQL database
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `host` | string | Yes | PostgreSQL server hostname or IP address |
+| `port` | number | Yes | PostgreSQL server port \(default: 5432\) |
+| `database` | string | Yes | Database name to connect to |
+| `username` | string | Yes | Database username |
+| `password` | string | Yes | Database password |
+| `ssl` | string | No | SSL connection mode \(disabled, required, preferred\) |
+| `query` | string | Yes | Raw SQL query to execute |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `message` | string | Operation status message |
+| `rows` | array | Array of rows returned from the query |
+| `rowCount` | number | Number of rows affected |
+
+
+
+## Notes
+
+- Category: `tools`
+- Type: `postgresql`

apps/docs/content/docs/triggers/meta.json

@@ -1,4 +1,5 @@
 {
   "title": "Triggers",
-  "pages": ["starter", "schedule", "webhook"]
+  "pages": ["starter", "schedule", "webhook"],
+  "defaultOpen": false
 }

apps/docs/content/docs/triggers/schedule.mdx

@@ -1,21 +1,23 @@
 ---
 title: Schedule
-description: Automatically trigger workflows on a recurring schedule
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
+import { Video } from '@/components/ui/video'
 
-The Schedule block automatically triggers workflow execution at specified intervals or times.
+The Schedule block automatically triggers workflows on a recurring schedule at specified intervals or times.
 
-<ThemeImage
-  lightSrc="/static/light/schedule-light.png"
-  darkSrc="/static/dark/schedule-dark.png"
-  alt="Schedule Block"
-  width={350}
-  height={175}
-/>
+<div className="flex justify-center">
+  <Image
+    src="/static/schedule.png"
+    alt="Schedule Block"
+    width={500}
+    height={400}
+    className="my-6"
+  />
+</div>
 
 ## Schedule Options
 
@@ -44,7 +46,7 @@ Configure when your workflow runs using the dropdown options:
 ## Configuring Schedules
 
 <div className="mx-auto w-full overflow-hidden rounded-lg">
-  <video autoPlay loop muted playsInline className="w-full -mb-2 rounded-lg" src="/configure-schedule.mp4"></video>
+  <Video src="configure-schedule.mp4" width={700} height={450} />
 </div>
 
 When a workflow is scheduled:
@@ -54,13 +56,15 @@ When a workflow is scheduled:
 
 ## Disabled Schedules
 
-<ThemeImage
-  lightSrc="/static/light/schedule-disabled-light.png"
-  darkSrc="/static/dark/schedule-disabled-dark.png"
-  alt="Disabled Schedule"
-  width={500}
-  height={200}
-/>
+<div className="flex justify-center">
+  <Image
+    src="/static/schedule-disabled.png"
+    alt="Disabled Schedule"
+    width={500}
+    height={350}
+    className="my-6"
+  />
+</div>
 
 Disabled schedules show when they were last active and can be re-enabled at any time.
 

apps/docs/content/docs/triggers/starter.mdx

@@ -1,21 +1,23 @@
 ---
 title: Starter
-description: Manually initiate workflow execution with input parameters
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
+import { Image } from '@/components/ui/image'
+import { Video } from '@/components/ui/video'
 
-The Starter block allows manual workflow execution with two input modes: structured parameters or conversational chat.
+The Starter block allows you to manually initiate workflow execution with input parameters, offering two input modes: structured parameters or conversational chat.
 
-<ThemeImage
-  lightSrc="/static/light/starter-light.png"
-  darkSrc="/static/dark/starter-dark.png"
-  alt="Starter Block with Manual and Chat Mode Options"
-  width={350}
-  height={175}
-/>
+<div className="flex justify-center">
+  <Image
+    src="/static/starter.png"
+    alt="Starter Block with Manual and Chat Mode Options"
+    width={500}
+    height={400}
+    className="my-6"
+  />
+</div>
 
 ## Execution Modes
 
@@ -25,13 +27,12 @@ Choose your input method from the dropdown:
   <Tab>
     <div className="space-y-4">
       <ul className="list-disc space-y-1 pl-6">
-        <li><strong>Structured inputs</strong>: Define specific parameters (text, number, boolean, JSON, file, date)</li>
-        <li><strong>Form interface</strong>: Users fill out a form with predefined fields</li>
-        <li><strong>API friendly</strong>: Perfect for programmatic execution</li>
+        <li><strong>API Friendly Structured inputs</strong>: Define specific parameters (text, number, boolean, JSON, file, date)</li>
+        <li><strong>Testing while Building Your Workflow</strong>: Quick iteration while debugging workflows</li>
       </ul>
       
       <div className="mx-auto w-full overflow-hidden rounded-lg">
-        <video autoPlay loop muted playsInline className="w-full -mb-2 rounded-lg" src="/input-format.mp4"></video>
+        <Video src="input-format.mp4" width={700} height={450} />
       </div>
       
       <p className="text-sm text-gray-600">Configure input parameters that will be available when deploying as an API endpoint.</p>
@@ -41,13 +42,11 @@ Choose your input method from the dropdown:
     <div className="space-y-4">
       <ul className="list-disc space-y-1 pl-6">
         <li><strong>Natural language</strong>: Users type questions or requests</li>
-        <li><strong>start.input variable</strong>: Captures all user input as `<start.input>`</li>
-        <li><strong>start.conversationId</strong>: Access conversation ID as `<start.conversationId>`</li>
         <li><strong>Conversational</strong>: Ideal for AI-powered workflows</li>
       </ul>
       
       <div className="mx-auto w-full overflow-hidden rounded-lg">
-        <video autoPlay loop muted playsInline className="w-full -mb-2 rounded-lg" src="/chat-input.mp4"></video>
+        <Video src="chat-input.mp4" width={700} height={450} />
       </div>
       
       <p className="text-sm text-gray-600">Chat with your workflow and access input text, conversation ID, and uploaded files for context-aware responses.</p>
@@ -59,36 +58,6 @@ Choose your input method from the dropdown:
 
 In Chat mode, access user input and conversation context through special variables:
 
-```yaml
-# Reference the chat input, conversation ID, and files in your workflow
-user_message: "<start.input>"
-conversation_id: "<start.conversationId>"
-uploaded_files: "<start.files>"
-```
-
 - **`<start.input>`** - Contains the user's message text
 - **`<start.conversationId>`** - Unique identifier for the conversation thread
-- **`<start.files>`** - Array of files uploaded by the user (if any)
-
-## API Execution
-
-<Tabs items={['Manual Mode', 'Chat Mode']}>
-  <Tab>
-    ```bash
-    curl -X POST "https://api.sim.dev/v1/workflows/{id}/start" \
-      -H "Authorization: Bearer {api-key}" \
-      -d '{"parameters": {"userId": "123", "action": "process"}}'
-    ```
-  </Tab>
-  <Tab>
-    ```bash
-    curl -X POST "https://api.sim.dev/v1/workflows/{id}/start" \
-      -H "Authorization: Bearer {api-key}" \
-      -d '{"input": "Analyze Q4 sales data"}'
-    ```
-  </Tab>
-</Tabs>
-
-<Callout>
-Starter blocks are ideal for testing workflows and user-initiated tasks. For automated execution, use Schedule or Webhook triggers.
-</Callout>
+- **`<start.files>`** - Array of files uploaded by the user (if any)

apps/docs/content/docs/triggers/webhook.mdx

@@ -1,54 +1,126 @@
 ---
 title: Webhooks  
-description: Trigger workflow execution from external webhooks
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
 import { Video } from '@/components/ui/video'
 
-The Webhook block allows external services to automatically trigger your workflow execution through HTTP webhooks.
+Webhooks allow external services to trigger workflow execution from external webhooks by sending HTTP requests to your workflow. Sim supports two approaches for webhook-based triggers.
+
+## Generic Webhook Trigger
+
+The Generic Webhook block creates a flexible endpoint that can receive any payload and trigger your workflow:
 
 <div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="webhooks.mp4" />
+  <Video src="webhooks-1.mp4" width={700} height={450} />
 </div>
 
-## Supported Providers
+### How It Works
 
-Choose from the dropdown to configure your webhook source:
+1. **Add Generic Webhook Block** - Drag the Generic Webhook block to start your workflow
+2. **Configure Payload** - Set up the expected payload structure (optional)
+3. **Get Webhook URL** - Copy the automatically generated unique endpoint
+4. **External Integration** - Configure your external service to send POST requests to this URL
+5. **Workflow Execution** - Every request to the webhook URL triggers the workflow
 
-<Tabs items={['Popular Services', 'Generic']}>
-  <Tab>
-    <ul className="grid grid-cols-2 gap-1 text-sm">
-      <li>**Slack** - Bot events and messages</li>
-      <li>**Gmail** - Email notifications</li>
-      <li>**GitHub** - Repository events</li>
-      <li>**Discord** - Server events</li>
-      <li>**Airtable** - Database changes</li>
-      <li>**Telegram** - Bot messages</li>
-      <li>**WhatsApp** - Messaging events</li>
-      <li>**Stripe** - Payment events</li>
-    </ul>
-  </Tab>
-  <Tab>
-    <p>For custom integrations:</p>
-    <ul className="list-disc space-y-1 pl-6 text-sm">
-      <li><strong>HTTP POST</strong>: Accepts requests from any client</li>
-      <li><strong>Authentication</strong>: Bearer token or custom headers</li>
-      <li><strong>Security</strong>: IP restrictions and rate limiting</li>
-      <li><strong>Deduplication</strong>: Prevents duplicate requests</li>
-    </ul>
-  </Tab>
-</Tabs>
+### Features
 
-## How It Works
+- **Flexible Payload**: Accepts any JSON payload structure
+- **Automatic Parsing**: Webhook data is automatically parsed and available to subsequent blocks
+- **Authentication**: Optional bearer token or custom header authentication
+- **Rate Limiting**: Built-in protection against abuse
+- **Deduplication**: Prevents duplicate executions from repeated requests
 
-1. **Configure Provider** - Select from dropdown and set up authentication
-2. **Get Webhook URL** - Automatically generated unique endpoint  
-3. **External Service** - Sends HTTP POST to your webhook URL
-4. **Workflow Triggers** - Automatically starts when webhook is received
+<Callout type="info">
+The Generic Webhook trigger fires every time the webhook URL receives a request, making it perfect for real-time integrations.
+</Callout>
 
-<Callout>
-Webhooks cannot receive incoming connections and serve as pure workflow triggers.
-</Callout>
+## Trigger Mode for Service Blocks
+
+Alternatively, you can use specific service blocks (like Slack, GitHub, etc.) in "trigger mode" to create more specialized webhook endpoints:
+
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="slack-trigger.mp4" width={700} height={450} />
+</div>
+
+### Setting Up Trigger Mode
+
+1. **Add Service Block** - Choose a service block (e.g., Slack, GitHub, Airtable)
+2. **Enable Trigger Mode** - Toggle "Use as Trigger" in the block settings
+3. **Configure Service** - Set up authentication and event filters specific to that service
+4. **Webhook Registration** - The service automatically registers the webhook with the external platform
+5. **Event-Based Execution** - Workflow triggers only for specific events from that service
+
+### When to Use Each Approach
+
+**Use Generic Webhook when:**
+- Integrating with custom applications or services
+- You need maximum flexibility in payload structure
+- Working with services that don't have dedicated blocks
+- Building internal integrations
+
+**Use Trigger Mode when:**
+- Working with supported services (Slack, GitHub, etc.)
+- You want service-specific event filtering
+- You need automatic webhook registration
+- You want structured data handling for that service
+
+## Supported Services for Trigger Mode
+
+The following service blocks support trigger mode:
+
+- **Slack** - Messages, mentions, reactions
+- **GitHub** - Push, PR, issue events  
+- **Airtable** - Record changes
+- **Telegram** - Bot messages and commands
+- **Gmail** - Email notifications
+- **WhatsApp** - Messaging events
+- **Jira** - Issue updates, comments
+- **Linear** - Issue state changes
+- **Notion** - Page updates
+
+## Security and Best Practices
+
+### Authentication Options
+
+- **Bearer Tokens**: Include `Authorization: Bearer <token>` header
+- **Custom Headers**: Define custom authentication headers
+
+### Payload Handling
+
+- **Validation**: Validate incoming payloads to prevent malformed data
+- **Size Limits**: Webhooks have payload size limits for security
+- **Error Handling**: Configure error responses for invalid requests
+
+### Testing Webhooks
+
+1. Use tools like Postman or curl to test your webhook endpoints
+2. Check workflow execution logs for debugging
+3. Verify payload structure matches your expectations
+4. Test authentication and error scenarios
+
+<Callout type="warning">
+Always validate and sanitize incoming webhook data before processing it in your workflows.
+</Callout>
+
+## Common Use Cases
+
+### Real-time Notifications
+- Slack messages triggering automated responses
+- Email notifications for critical events
+
+### CI/CD Integration  
+- GitHub pushes triggering deployment workflows
+- Build status updates
+- Automated testing pipelines
+
+### Data Synchronization
+- Airtable changes updating other systems
+- Form submissions triggering follow-up actions
+- E-commerce order processing
+
+### Customer Support
+- Support ticket creation workflows
+- Automated escalation processes
+- Multi-channel communication routing

apps/docs/content/docs/variables/environment-variables.mdx

@@ -0,0 +1,96 @@
+---
+title: Environment Variables
+---
+
+import { Callout } from 'fumadocs-ui/components/callout'
+import { Image } from '@/components/ui/image'
+
+Environment variables provide a secure way to manage configuration values and secrets across your workflows, including API keys and other sensitive data that your workflows need to access. They keep secrets out of your workflow definitions while making them available during execution.
+
+## Variable Types
+
+Environment variables in Sim work at two levels:
+
+- **Personal Environment Variables**: Private to your account, only you can see and use them
+- **Workspace Environment Variables**: Shared across the entire workspace, available to all team members
+
+<Callout type="info">
+Workspace environment variables take precedence over personal ones when there's a naming conflict.
+</Callout>
+
+## Setting up Environment Variables
+
+Navigate to Settings to configure your environment variables:
+
+<Image
+  src="/static/environment/environment-1.png"
+  alt="Environment variables modal for creating new variables"
+  width={500}
+  height={350}
+/>
+
+From your workspace settings, you can create and manage both personal and workspace-level environment variables. Personal variables are private to your account, while workspace variables are shared with all team members.
+
+### Making Variables Workspace-Scoped
+
+Use the workspace scope toggle to make variables available to your entire team:
+
+<Image
+  src="/static/environment/environment-2.png"
+  alt="Toggle workspace scope for environment variables"
+  width={500}
+  height={350}
+/>
+
+When you enable workspace scope, the variable becomes available to all workspace members and can be used in any workflow within that workspace.
+
+### Workspace Variables View
+
+Once you have workspace-scoped variables, they appear in your environment variables list:
+
+<Image
+  src="/static/environment/environment-3.png"
+  alt="Workspace-scoped variables in the environment variables list"
+  width={500}
+  height={350}
+/>
+
+## Using Variables in Workflows
+
+To reference environment variables in your workflows, use the `{{}}` notation. When you type `{{` in any input field, a dropdown will appear showing both your personal and workspace-level environment variables. Simply select the variable you want to use.
+
+<Image
+  src="/static/environment/environment-4.png"
+  alt="Using environment variables with double brace notation"
+  width={500}
+  height={350}
+/>
+
+## Variable Precedence
+
+When you have both personal and workspace variables with the same name:
+
+1. **Workspace variables take precedence** over personal variables
+2. This prevents naming conflicts and ensures consistent behavior across team workflows
+3. If a workspace variable exists, the personal variable with the same name is ignored
+
+<Callout type="warning">
+Choose variable names carefully to avoid unintended overrides. Consider prefixing personal variables with your initials or workspace variables with the project name.
+</Callout>
+
+## Security Best Practices
+
+### For Sensitive Data
+- Store API keys, tokens, and passwords as environment variables instead of hardcoding them
+- Use workspace variables for shared resources that multiple team members need
+- Keep personal credentials in personal variables
+
+### Variable Naming
+- Use descriptive names: `DATABASE_URL` instead of `DB`
+- Follow consistent naming conventions across your team
+- Consider prefixes to avoid conflicts: `PROD_API_KEY`, `DEV_API_KEY`
+
+### Access Control
+- Workspace environment variables respect workspace permissions
+- Only users with write access or higher can create/modify workspace variables
+- Personal variables are always private to the individual user

apps/docs/content/docs/variables/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Variables",
-  "pages": ["index"]
+  "pages": ["workflow-variables", "environment-variables"]
 }

apps/docs/content/docs/variables/workflow-variables.mdx

@@ -1,15 +1,13 @@
 ---
-title: Variables
-description: Store and share data across your workflow with global variables
+title: Workflow Variables
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { ThemeImage } from '@/components/ui/theme-image'
 import { Video } from '@/components/ui/video'
 
-Variables in Sim act as a global store for data that can be accessed and modified by any block in your workflow. They provide a powerful way to share information between different parts of your workflow, maintain state, and create more dynamic applications.
+Variables in Sim act as a global store for data that can be accessed and modified by any block in your workflow, allowing you to store and share data across your workflow with global variables. They provide a powerful way to share information between different parts of your workflow, maintain state, and create more dynamic applications.
 
 <div className="mx-auto w-full overflow-hidden rounded-lg">
   <Video src="variables.mp4" />
@@ -120,7 +118,6 @@ When you access a variable from a block, you can:
 Variables in Sim have global scope, meaning:
 
 - They are accessible from any block in your workflow
-- Any block can modify them
 - Changes to variables persist throughout workflow execution
 - Variables maintain their values between runs, unless explicitly reset
 

apps/docs/content/docs/yaml/meta.json

@@ -1,4 +1,5 @@
 {
   "title": "YAML Reference",
-  "pages": ["index", "block-reference", "blocks", "examples"]
+  "pages": ["index", "block-reference", "blocks", "examples"],
+  "defaultOpen": false
 }