docs: builder-first IA reorganization of the English docs

[ouiliame]

What this does

Rebuilds the English docs around the product's real ontology — everything is a block; some blocks are triggers; an integration is one block with Actions and optionally a Trigger — with a builder-first rewrite of the core reference, live spec-driven visuals, and a reworked docs generator that emits one page per integration.

1. IA / ontology

• Sidebar reorganized into topic sections; Core Blocks (16) and Core Triggers (5 native: Start, Schedule, Webhook, RSS, Table) are folder accordions under Workflows, after Deployment.
• The old /blocks and /triggers index pages are folded into the Workflows overview (kept to a real introduction — concepts, block taxonomy, trigger framing — after an editorial trim).
• /tools/* + /triggers/<service> are unified into /integrations/<service>: one generated page per service with the curated intro, ## Actions, and a ## Triggers section when the service has one. No "Tools" terminology. ~205 pages. (Fresh start — no redirects, per maintainer decision.)

2. Hand-rewritten reference (builder voice)

• All 16 core block pages rewritten against the real block schemas: accurate config/outputs tables, pageType frontmatter, FAQs kept, Best Practices kept, every distinct example rendered as a live WorkflowPreview (~36 hand-authored example workflows).
• All 5 native trigger pages rewritten the same way (Wait's async suspend/resume mode, Webhook's auth/dedup behavior, the Table trigger off the auto-gen card, etc.).

3. Live visuals (no screenshots to maintain for block heroes)

• BlockPreview — spec-driven hero rendering each block exactly as the canvas shows it.
• WorkflowPreview — app-styled ReactFlow diagrams, now with container rendering (Loop/Parallel render as real subflow containers with a Start pill and nested blocks) and integration-icon fallback (Gmail/Slack/etc. glyphs in diagrams).

4. Generator (scripts/generate-docs.ts)

• Emits per-service integrations/ pages (block pass writes Actions; trigger pass appends ## Triggers, or writes a standalone page for trigger-only services like IMAP/Circleback; jsm triggers merge into the Jira Service Management page).
• Manual-content preservation hardened (three bug classes fixed): cleanup and writer now share one canonical filter so hand-curated intros are never deleted-then-regenerated away; hand-written pages are guarded from cleanup; manual sections with no insertion anchor append instead of being silently dropped. Double regeneration is churn-free (idempotent) with all MANUAL-CONTENT intact.
• scripts/README.md rewritten to document the pipeline (canonical sources in apps/sim, the golden don't-hand-edit rule, the manual-content escape hatch).

5. Stale-content fixes

Skills page location, Credentials→Secrets, Integrations page, retired Vision block, Copilot→Mothership, dead Mod+Y shortcut, recovered staging's enriched Table doc (filter operators, limits, column types), restored 198 curated integration intros that the relocation would otherwise have dropped.

Verification

• bun run build passes (note: docs build needs DATABASE_URL for the search route — pre-existing; CI provides it).
• fumadocs-mdx clean; 116 image refs resolve; all BlockPreview/WorkflowPreview usages validated against specs/exports.
• Generator run twice back-to-back → zero diff.

Scope / notes

• English (en) only. Other locales unchanged (they keep the old structure; follow-up).
• Branch is merged with current staging — block colors/configs and the new integrations (Sendblue, MillionVerifier, NeverBounce, ZeroBounce) are reflected.
• Videos serve from the asset CDN (NEXT_PUBLIC_BLOB_BASE_URL); remote in local dev, fine in prod.

Known gaps / follow-ups (tracked, not blockers)

• Fill the ~58 {/* VISUAL */} / TODO placeholder slots (diagrams/screenshots); refresh old-UI screenshots.
• a2a / mysql / postgresql were recategorized to category: 'blocks' upstream and currently have no docs home — needs an IA decision.
• FAQ/depth pass on how-it-runs, data-flow, triggers/start, triggers/table.
• Port the IA to other locales; Logs API reference re-home (blocked on the OpenAPI pipeline).

🤖 Generated with Claude Code

[vercel]

@ouiliame is attempting to deploy a commit to the Sim Team on Vercel.

A member of the Team first needs to authorize it.

[cursor]

PR Summary

Low Risk
Documentation and docs-site UI only; no changes to core app auth, data, or execution paths.

Overview
This PR reorganizes the English docs around a builder-first information architecture: new Building agents concept pages, a slimmer Blocks overview, and block reference pages rewritten with pageType frontmatter, task-oriented prose, and links to /workflows/connections instead of the removed /connections section (those MDX pages and meta.json are deleted).

Live workflow visuals replace static block hero screenshots. A new workflow-preview package adds hand-authored BLOCK_DISPLAY_SPECS, BlockPreview (static canvas-style cards), WorkflowPreview (React Flow diagrams with many shared example workflows), plus OutputBundle and block icons including WaitIcon. Block and workflow docs import these components for heroes and inline examples.

Docs chrome changes: MDX pages show a PageTypeBadge (tutorial / guide / reference / concept) when pageType is set, and DocsDescription is no longer rendered under the title on MDX/API pages. The standalone Copilot docs page in this diff is removed.

^{Reviewed by Cursor Bugbot for commit 9ecfebf. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Duplicate React provider keys

Medium Severity

WorkflowPreview keys ReactFlowProvider only from workflow.id, highlightBlock, and highlightEdge. The workflows overview renders two previews with the same CLASSIFY_WORKFLOW and highlightBlock="agent", so React sees duplicate sibling keys and can reuse the wrong internal flow state between diagrams.

 

^{Reviewed by Cursor Bugbot for commit 18cee3d. Configure here.}

[greptile-apps]

Greptile Summary

This PR reorganizes the English docs from a product-category IA into a builder-first topic structure, rewrites key conceptual pages, and introduces two new infrastructure pieces: a pageType Diátaxis badge and a WorkflowPreview/OutputBundle component system that embeds live ReactFlow diagrams in MDX. All moved URLs have permanent redirects in next.config.ts.

• Sidebar restructured: Get Started → Workflows → Tables → Files → Knowledge Bases → Logs → Building agents → Mothership → Workspaces → Platform → Reference. Generated catalogs (blocks/tools/triggers) demoted to a Reference section.
• WorkflowPreview and OutputBundle React components added, backed by ReactFlow 11 + Framer Motion 12; four static example workflows defined in examples.ts with unique IDs, keyed on the ReactFlowProvider to force remount on highlight changes.
• pageType frontmatter field added via a Zod schema extension in source.config.ts, rendered as a small Diátaxis-mode badge in page.tsx; DocsDescription intentionally removed from the page template in favour of first-paragraph prose in each MDX body.

Confidence Score: 5/5

Docs-only change with no runtime logic outside of two new React components and redirect rules; all redirects verified against deleted files, all sidebar page references verified to exist on disk.

The WorkflowPreview/OutputBundle components are client-only and isolated to the docs app. The ReactFlowProvider key correctly includes workflow.id plus the two highlight props, so state resets whenever the diagram content changes. The pageType schema extension is backward-compatible (field is optional). Redirect coverage is complete for every removed path. No application code outside apps/docs is touched.

No files require special attention. The two-hop redirect chains in next.config.ts (capabilities/agents and execution/form) were already flagged in a previous review thread.

Important Files Changed

Filename	Overview
apps/docs/next.config.ts	32 permanent redirects added for moved/removed URLs; two redirect chains (capabilities/agents and execution/form) incur two round-trips but this was already flagged in a previous thread
apps/docs/components/workflow-preview/workflow-preview.tsx	New ReactFlow-based read-only workflow diagram component; ReactFlowProvider keyed on workflow.id+highlight props to force remount on changes; nodes state correctly resets because of the key, but animate prop is not part of the key
apps/docs/components/page-type-badge.tsx	New Diátaxis badge component; uses satisfies Record to enforce exhaustive CONFIG coverage at compile time; runtime null guard is harmless
apps/docs/app/[lang]/[[...slug]]/page.tsx	Adds PageTypeBadge before DocsTitle; removes DocsDescription from visual rendering while keeping it in SEO metadata (StructuredData, generateMetadata); change is intentional for pages rewritten in this PR
apps/docs/source.config.ts	Extends frontmatter schema with optional pageType enum via Zod; backward-compatible since field is optional
apps/docs/content/docs/en/meta.json	Root sidebar restructured; all referenced files verified to exist on disk; individual knowledgebase/mothership pages listed flat rather than as folder groups, consistent with their respective meta.jsons
apps/docs/package.json	Adds reactflow ^11.11.4 and framer-motion ^12.5.0 to docs app dependencies

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph WorkflowPreview["WorkflowPreview (client)"]
        WP["WorkflowPreview\n(wrapper, key = workflow.id + highlights)"]
        RFP["ReactFlowProvider\n(remounts on key change)"]
        PF["PreviewFlow\n(useState nodes/edges)"]
        PBS["PreviewBlockNode\n(framer-motion m.div)"]
        PE["PreviewEdge\n(m.path or path)"]
    end

    subgraph Data["Static data (examples.ts)"]
        CW["CLASSIFY_WORKFLOW"]
        CRW["CLASSIFY_REPLY_WORKFLOW"]
        SKW["SUPPORT_KB_WORKFLOW"]
        TEW["TABLE_ENRICH_WORKFLOW"]
    end

    subgraph Transform["workflow-data.ts"]
        TRF["toReactFlowElements()"]
    end

    subgraph Badge["pageType badge"]
        SC["source.config.ts\n(Zod schema extension)"]
        LS["lib/source.ts\n(DocsPageType type)"]
        PTB["PageTypeBadge component"]
    end

    MDX["MDX page\n(server component)"] -->|imports| WP
    MDX -->|frontmatter pageType| SC
    SC --> LS
    LS --> PTB
    PTB --> PageTsx["page.tsx"]

    Data --> WP
    WP --> RFP
    RFP --> PF
    PF -->|useMemo| TRF
    TRF -->|nodes| PBS
    TRF -->|edges| PE

Loading

_{Reviews (2): Last reviewed commit: "docs: reorganize into topic/ontology IA ..." | Re-trigger Greptile}

[greptile-apps]

Two-hop redirect chains on deprecated URLs

Two redirect chains are introduced here. /capabilities/agents first hits the /building-agents/agents rule (line 23) before bouncing again to /building-agents, and /execution/form first hits /deployment/form (line 25) before going to /deployment. With permanent: true (308), browsers eventually cache both hops, but the first visit still pays two round trips and search-engine crawlers must follow two hops to update index URLs. Both chains can be collapsed to a single hop by pointing the old source directly at the final destination.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 9, 2026 7:15pm

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9ecfebf. Configure here.}

[cursor]

Preview flow ignores prop updates

Medium Severity

PreviewFlow derives React Flow nodes and edges in useMemo, but stores them in useState only on first mount. When animate or other memo inputs change while workflow.id and highlight props stay the same, the provider key does not remount, so the canvas keeps stale nodes and edges instead of updated data or animation flags.

 

^{Reviewed by Cursor Bugbot for commit 9ecfebf. Configure here.}