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. Old URLs 308-redirect: /tools/:slug and the old /triggers/<service> pages → /integrations/:slug, /blocks//triggers → the workflows overview anchors.

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 ~55 {/* 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
Changes are confined to the docs app, generated MDX, and URL redirects; no runtime product or auth paths. Redirect and generator URL updates need correct deployment so existing /tools links and integrations.json consumers keep working.

Overview
Reorganizes English docs around a blocks-first ontology: integrations become one generated page per service under /integrations/<service> (actions + triggers), with 308 redirects from /tools/* and service /triggers/* URLs.

Adds a workflow-preview MDX toolkit—BlockPreview (canvas-accurate block heroes), WorkflowPreview / OutputBundle / BlockInspector (ReactFlow diagrams and run-inspector facsimiles), plus a large library of hand-authored example workflows—used across rewritten core block reference pages (screenshots replaced, pageType: reference, tighter builder voice).

Docs chrome now shows an optional Diátaxis PageTypeBadge from frontmatter and drops the default DocsDescription under the title. Planning artifacts track integration IA and stale screenshot/video recapture.

^{Reviewed by Cursor Bugbot for commit b90b3db. Bugbot is set up for automated code reviews on this repo. 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 11:22pm

[cursor]

Light icons on light swatches

Low Severity

Integration blocks in workflow diagrams use light header colors (for example #FFFFFF for Gmail) but block nodes always render header icons with text-white. On those swatches the glyph disappears or is nearly invisible, unlike PreviewContainerNode, which already picks icon color from background luminance.

Additional Locations (2)

• apps/docs/components/workflow-preview/block-preview.tsx#L36-L41
• apps/docs/components/workflow-preview/block-inspector.tsx#L186-L191

 

^{Reviewed by Cursor Bugbot for commit 54e9c4e. Configure here.}

[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 f081750. Configure here.}

[cursor]

Page subtitle no longer renders

Medium Severity

The layout no longer renders DocsDescription, so frontmatter description values added on rewritten reference pages never appear in the page body. Metadata and structured data still use data.description, but readers only see the title and optional page-type badge.

Additional Locations (1)

• apps/docs/app/[lang]/[[...slug]]/page.tsx#L175-L176

 

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