docs: builder-first IA reorganization of the English docs

apps/docs/.plans/integrations-ia.md

@@ -0,0 +1,85 @@
+# Spec: integration pages as per-service block indexes
+
+Status: approved, in progress. Owner: docs reorg (`feat/docs-reorg`).
+
+## Ontology (the thing we're encoding)
+
+Everything in a workflow is a **block**. A workflow is **blocks + connections**. Some
+blocks are **triggers** — they take no input and start the run. This is literal in the
+code: `BlockCategory = 'blocks' | 'tools' | 'triggers'`, and integration blocks
+(`gmail`, `github`, …) additionally carry a `triggers: {}` capability — the same block
+does actions *and* can start a workflow. There is no separate "trigger" species, and we
+stop using the word **"Tools"** in user-facing docs.
+
+Encoding: a small **Trigger** badge on any block that starts a workflow (driven by
+`category: 'triggers'` or a `triggers:{}` capability). Native trigger blocks and an
+integration's trigger use the same badge.
+
+## Target IA
+
+- **`/integrations/<service>`** (generated, one page per service) — a **block index for
+  that service**: its capabilities listed, trigger capability(ies) badged **Trigger**.
+  This single page is the per-integration unified reference. Replaces `/tools/<service>`
+  **and** `/triggers/<service>`.
+- **Blocks reference** (hand-written: core blocks + the ~10 trigger blocks) — same
+  pattern: a block index with triggers badged. Folds today's *Core Blocks* + *Core
+  Triggers* into one "blocks, some are triggers" surface.
+- **Retire** `/tools/*`, `/triggers/<service>`, and the interim `integration-triggers/`
+  folder → all become `/integrations/<service>`.
+
+## Resolved decisions
+
+- **A. Native trigger blocks** live in the **Blocks** reference, badged **Trigger**, kept
+  in a scannable "Triggers" sub-grouping within it. (Done as the final step, after the
+  generator work.)
+- **B. Navbar / section label = "Integrations".** Users search by service; the ontology
+  ("it's a block") is taught in prose, not the nav label.
+- **C. Redirects added.** Initially decided as a fresh start, revised before merge:
+  `/tools/*` are live, indexed URLs referenced by deployed app docsLink fields and
+  marketplace listings, so next.config now 308s them (and the old
+  `/triggers/<service>` pages) to `/integrations/<service>`.
+- **D. Integration page = one page per service** listing the service's operations + its
+  trigger(s), triggers badged. Not Tools/Triggers tabs; a single badged block index.
+
+## Generator (`scripts/generate-docs.ts`)
+
+Today: `generateAllBlockDocs()` → writes `tools/<service>.mdx` (per `category:'tools'`
+block) + `generateAllTriggerDocs()` writes `triggers/<service>.mdx` from
+`apps/sim/triggers/<provider>/` + rewrites `triggers/meta.json` + emits
+icons/icon-mapping/landing `integrations.json`. **One integration = two pages today.**
+
+Changes:
+1. New output root `content/docs/en/integrations/`; stop writing `tools/` and integration
+   `triggers/`.
+2. **Join by service:** for each integration gather (a) the block's operations/actions and
+   (b) the trigger config from `apps/sim/triggers/<provider>/` if present.
+3. Emit `integrations/<service>.mdx`: header (icon + name) + block index, trigger entries
+   badged. Generate `integrations/meta.json`.
+4. Repoint landing/icon `docsUrl` (`/tools/<x>` → `/integrations/<x>`); keep the landing
+   `integrations.json` shape intact.
+5. Keep hand-written core blocks + native triggers (`HANDWRITTEN_*` / `SKIP_*`). Remove
+   the old `tools`/`triggers` meta writers.
+
+## Redirects (`apps/docs/next.config.ts`)
+
+- `/tools` -> `/integrations`; `/tools/:slug` -> `/integrations/:slug` (custom-tools -> building-agents)
+- `/triggers/<service>` -> `/integrations/<service>` (enumerated; provider-slug mappings for jsm/google-*/microsoft-teams)
+- `/blocks` -> `/workflows#blocks`; `/triggers` -> `/workflows#triggers`
+- Native trigger pages (`/triggers/start|schedule|webhook|rss|table`) unaffected.
+
+## Migration order
+
+1. Trigger badge component + the integration-page template.
+2. Rewrite the generator to emit `/integrations/<service>`; regenerate; delete old
+   `tools/` + integration `triggers/` + `integration-triggers/`.
+3. Redirects; rename the navbar surface to Integrations; update `meta.json`.
+4. Fold native triggers into the Blocks reference (badged); retire the separate Core
+   Triggers framing.
+5. Build + link-check.
+
+## Notes / risk
+
+- The generator also feeds the **landing page** via `integrations.json` — changes must not
+  break its shape, only repoint doc URLs.
+- The interim `integration-triggers/` folder and the *Core Triggers* accordion are
+  scaffolding that this supersedes.

apps/docs/app/[lang]/[[...slug]]/page.tsx

@@ -5,11 +5,12 @@ import type { ApiPageProps } from 'fumadocs-openapi/ui'
 import { createAPIPage } from 'fumadocs-openapi/ui'
 import { Pre } from 'fumadocs-ui/components/codeblock'
 import defaultMdxComponents from 'fumadocs-ui/mdx'
-import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/page'
+import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/page'
 import { notFound } from 'next/navigation'
 import { PageFooter } from '@/components/docs-layout/page-footer'
 import { PageNavigationArrows } from '@/components/docs-layout/page-navigation-arrows'
 import { LLMCopyButton } from '@/components/page-actions'
+import { PageTypeBadge } from '@/components/page-type-badge'
 import { StructuredData } from '@/components/structured-data'
 import { CodeBlock } from '@/components/ui/code-block'
 import { Heading } from '@/components/ui/heading'
@@ -173,7 +174,6 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
               <PageNavigationArrows previous={neighbours?.previous} next={neighbours?.next} />
             </div>
             <DocsTitle className='mb-2'>{data.title}</DocsTitle>
-            <DocsDescription>{data.description}</DocsDescription>
           </div>
           <DocsBody>
             <APIPage {...apiProps} />
@@ -222,8 +222,8 @@ export default async function Page(props: { params: Promise<{ slug?: string[]; l
             </div>
             <PageNavigationArrows previous={neighbours?.previous} next={neighbours?.next} />
           </div>
+          {data.pageType && <PageTypeBadge type={data.pageType} className='mb-3' />}
           <DocsTitle className='mb-2'>{data.title}</DocsTitle>
-          <DocsDescription>{data.description}</DocsDescription>
         </div>
         <DocsBody>
           <MDX

apps/docs/components/page-type-badge.tsx

@@ -0,0 +1,44 @@
+import type { DocsPageType } from '@/lib/source'
+import { cn } from '@/lib/utils'
+
+const CONFIG = {
+  tutorial: { label: 'Tutorial', className: 'text-[#33c482] border-[#33c482]/30 bg-[#33c482]/10' },
+  guide: {
+    label: 'Guide',
+    className: 'text-blue-600 border-blue-500/30 bg-blue-500/10 dark:text-blue-400',
+  },
+  reference: {
+    label: 'Reference',
+    className: 'text-violet-600 border-violet-500/30 bg-violet-500/10 dark:text-violet-400',
+  },
+  concept: {
+    label: 'Concept',
+    className: 'text-amber-600 border-amber-500/30 bg-amber-500/10 dark:text-amber-400',
+  },
+} as const satisfies Record<DocsPageType, { label: string; className: string }>
+
+interface PageTypeBadgeProps {
+  type: DocsPageType
+  className?: string
+}
+
+/**
+ * Small label that tells the reader which Diátaxis mode a page is — learning,
+ * task, lookup, or understanding. Rendered only when a page declares `type`.
+ */
+export function PageTypeBadge({ type, className }: PageTypeBadgeProps) {
+  const config = CONFIG[type]
+  if (!config) return null
+
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center rounded-full border px-2 py-0.5 font-medium text-[11px] uppercase tracking-[0.04em]',
+        config.className,
+        className
+      )}
+    >
+      {config.label}
+    </span>
+  )
+}

apps/docs/components/workflow-preview/block-display-specs.ts

@@ -0,0 +1,220 @@
+/**
+ * A hand-authored block, described as what the builder canvas displays.
+ *
+ * - `rows` are the visible sub-block rows; use `'-'` for an empty/unset field (the canvas
+ *   shows a dash), or a representative value where the field has a default.
+ * - `branches` render one output handle per entry (Condition's if/else-if/else, Router's
+ *   routes); when set, also set `hideSourceHandle: true` so the single output is replaced.
+ * - `showError: true` adds the bottom `Error` row + red handle (action blocks, not triggers).
+ * - `hideTargetHandle: true` for triggers (entry points — no input).
+ * - `bgColor` is the resolved hex; the Agent uses Sim green `#33C482` (`var(--brand)`).
+ */
+export interface BlockDisplaySpec {
+  name: string
+  /** Block type — drives the header icon (see `BLOCK_ICONS`). */
+  type: string
+  /** Resolved brand color (hex). */
+  bgColor: string
+  rows: Array<{ title: string; value: string }>
+  branches?: string[]
+  showError?: boolean
+  hideTargetHandle?: boolean
+  hideSourceHandle?: boolean
+}
+
+/**
+ * Display specs for the block reference previews — one per block, edited to match exactly
+ * what the builder canvas shows. Source of truth for the `<BlockPreview>` heroes.
+ */
+
+export const BLOCK_DISPLAY_SPECS: Record<string, BlockDisplaySpec> = {
+  agent: {
+    name: 'Agent',
+    type: 'agent',
+    bgColor: '#33C482',
+    showError: true,
+    rows: [
+      { title: 'Messages', value: '-' },
+      { title: 'Model', value: 'claude-sonnet-4-6' },
+      { title: 'Files', value: '-' },
+      { title: 'Tools', value: '-' },
+      { title: 'Skills', value: '-' },
+      { title: 'Memory', value: 'None' },
+      { title: 'Response Format', value: '-' },
+    ],
+  },
+  api: {
+    name: 'API',
+    type: 'api',
+    bgColor: '#2F55FF',
+    showError: true,
+    rows: [
+      { title: 'URL', value: '-' },
+      { title: 'Method', value: 'GET' },
+      { title: 'Query Params', value: '-' },
+      { title: 'Headers', value: '-' },
+      { title: 'Body', value: '-' },
+    ],
+  },
+  condition: {
+    name: 'Condition',
+    type: 'condition',
+    bgColor: '#FF752F',
+    showError: true,
+    hideSourceHandle: true,
+    rows: [],
+    branches: ['if', 'else if', 'else'],
+  },
+  credential: {
+    name: 'Credential',
+    type: 'credential',
+    bgColor: '#6366F1',
+    showError: true,
+    rows: [
+      { title: 'Operation', value: 'Select Credential' },
+      { title: 'Credential', value: '-' },
+    ],
+  },
+  evaluator: {
+    name: 'Evaluator',
+    type: 'evaluator',
+    bgColor: '#4D5FFF',
+    showError: true,
+    rows: [
+      { title: 'Evaluation Metrics', value: '-' },
+      { title: 'Content', value: '-' },
+      { title: 'Model', value: 'claude-sonnet-4-6' },
+    ],
+  },
+  function: {
+    name: 'Function',
+    type: 'function',
+    bgColor: '#FF402F',
+    showError: true,
+    rows: [
+      { title: 'Language', value: 'JavaScript' },
+      { title: 'Code', value: '-' },
+    ],
+  },
+  guardrails: {
+    name: 'Guardrails',
+    type: 'guardrails',
+    bgColor: '#3D642D',
+    showError: true,
+    rows: [
+      { title: 'Content to Validate', value: '-' },
+      { title: 'Validation Type', value: 'Valid JSON' },
+    ],
+  },
+  response: {
+    name: 'Response',
+    type: 'response',
+    bgColor: '#2F55FF',
+    showError: true,
+    hideSourceHandle: true,
+    rows: [
+      { title: 'Response Data Mode', value: 'Builder' },
+      { title: 'Response Structure', value: '-' },
+      { title: 'Status Code', value: '-' },
+      { title: 'Response Headers', value: '-' },
+    ],
+  },
+  router: {
+    name: 'Router',
+    type: 'router',
+    bgColor: '#28C43F',
+    showError: true,
+    hideSourceHandle: true,
+    rows: [{ title: 'Context', value: '-' }],
+    branches: ['route 1'],
+  },
+  variables: {
+    name: 'Variables',
+    type: 'variables',
+    bgColor: '#8B5CF6',
+    showError: true,
+    rows: [{ title: 'Variable Assignments', value: '-' }],
+  },
+  wait: {
+    name: 'Wait',
+    type: 'wait',
+    bgColor: '#F59E0B',
+    showError: true,
+    rows: [
+      { title: 'Wait Amount', value: '-' },
+      { title: 'Unit', value: 'Seconds' },
+    ],
+  },
+  webhook: {
+    name: 'Webhook',
+    type: 'webhook',
+    bgColor: '#10B981',
+    showError: true,
+    rows: [
+      { title: 'Webhook URL', value: '-' },
+      { title: 'Payload', value: '-' },
+      { title: 'Signing Secret', value: '-' },
+      { title: 'Additional Headers', value: '-' },
+    ],
+  },
+  workflow: {
+    name: 'Workflow',
+    type: 'workflow',
+    bgColor: '#6366F1',
+    showError: true,
+    rows: [
+      { title: 'Select Workflow', value: '-' },
+      { title: 'Input Variable', value: '-' },
+    ],
+  },
+  human_in_the_loop: {
+    name: 'Human in the Loop',
+    type: 'human_in_the_loop',
+    bgColor: '#10B981',
+    showError: true,
+    rows: [
+      { title: 'Display Data', value: '-' },
+      { title: 'Notification', value: '-' },
+      { title: 'Resume Form', value: '-' },
+    ],
+  },
+  schedule: {
+    name: 'Schedule',
+    type: 'schedule',
+    bgColor: '#6366F1',
+    hideTargetHandle: true,
+    rows: [
+      { title: 'Run frequency', value: 'Every X Minutes' },
+      { title: 'Interval (minutes)', value: '-' },
+    ],
+  },
+  rss: {
+    name: 'RSS Feed',
+    type: 'rss',
+    bgColor: '#F97316',
+    hideTargetHandle: true,
+    rows: [{ title: 'Feed URL', value: '-' }],
+  },
+  webhook_trigger: {
+    name: 'Webhook',
+    type: 'webhook',
+    bgColor: '#10B981',
+    hideTargetHandle: true,
+    rows: [
+      { title: 'Webhook URL', value: '-' },
+      { title: 'Require Authentication', value: '-' },
+      { title: 'Input Format', value: '-' },
+    ],
+  },
+  table: {
+    name: 'Table',
+    type: 'table',
+    bgColor: '#10B981',
+    hideTargetHandle: true,
+    rows: [
+      { title: 'Table', value: '-' },
+      { title: 'Event type', value: 'Row updated' },
+      { title: 'Watch columns', value: '-' },
+    ],
+  },
+}