improvement(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 rewritten core reference, executor-verified semantics, live app-styled visuals, a reworked docs generator, and URLs that mirror the sidebar. 109 commits, kept current with staging throughout (8 merges absorbed, including the Sim trigger, Enrichment/Logs blocks, and every integration added along the way).

1. IA — sections own their pages, URLs match

/workflows/{overview, how-it-runs, data-flow, connections, variables}
/workflows/deployment/* · /workflows/triggers/{start,schedule,webhook,rss,table,sim} · /workflows/blocks/{agent…workflow}
/agents/{overview, choosing, custom-tools, mcp, skills}
/tables · /files · /knowledgebase · /logs-debugging · /mothership (+ mailer)
/platform/{workspaces, organization, permissions, credentials, costs, self-hosting/*, enterprise/*}
/integrations/<service>   ← one page per service (was /tools/* + /triggers/<service>)

Every previously-live URL 308-redirects to its new home (/tools/*, /blocks/*, /triggers/* incl. native-vs-service disambiguation, /mcp, /skills, /costs, /credentials, /permissions/*, /mailer, /self-hosting/*, /enterprise/*, /deployment/*, /capabilities/*, /execution/*, /connections/*, /variables/*, /copilot) — chains verified single-hop.

2. Hand-rewritten reference, verified against code

• 16 core block pages + 6 native trigger pages rewritten against the real schemas; every distinct example is a live WorkflowPreview (~40 hand-authored workflows). FAQs and Best Practices kept.
• Execution semantics audited against the executor — several old claims were wrong and are fixed: failure behavior (an unhandled error stops the run; only a connected error port continues it), join semantics (waits only for feeders that will run), reference resolution order + unmatched-tag behavior, run time limits (5 min free / 50 min paid sync, 90 min async — from execution-limits).
• Variables vs connection tags untangled ("one syntax, named sources"; variable is a literal prefix); workflow-as-tool corrected to agent-decided (workflow_executor).

3. Live visuals (theme-aware, no screenshot rot for block chrome)

• BlockPreview heroes, WorkflowPreview canvases with Loop/Parallel containers, per-branch condition/router handles matching the app's real handle ids (condition-<id>, router-<routeId>), tool chips, click-to-inspect lightbox with a read-only block inspector, and a run-inspector OutputBundle — all driven by --wp-* tokens mirroring the app's light/dark globals.
• ~20 current-UI screenshots placed (tables workflow-columns, logs, integrations/skills flows, error paths); the remaining capture list lives in apps/docs/.plans/visuals-manifest.md, priority-ordered by platform usage data.

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

• Emits per-service integrations/<service>.mdx (Actions + Triggers on one page; provider→page mappings like jsm→Jira Service Management; native resources table/knowledge/memory/enrichment/logs included; the native Sim trigger excluded).
• Manual-content preservation hardened through three bug classes — cleanup/writer share one canonical filter, hand-written pages are guarded, anchor-less manual sections append instead of dropping. Double regeneration is provably idempotent. Pipeline documented in scripts/README.md.
• The agent skills (add-integration, add-block, validate-integration) now teach the new layout, so integration PRs mint /integrations/ docsLinks the moment this merges — which also ends the recurring fork-PR conflicts (staging's old generator writing into the deleted tools/).

5. Accuracy & data-driven content

• Stale-content sweep: model rosters → current defaults, wrong tokens shapes fixed, Settings-era flows updated to the sidebar UI (Integrations, Skills + new import flow), retired Vision block, HubSpot Marketplace setup guide added.
• Platform-metrics read (sim-internals) drove targeted additions, each with an inline {/* why */} provenance comment: run-timeout docs (the Workflow Zoom #1 provable error class), a first-green-run callout on getting-started (92%→49% funnel cliff), error-port guidance guarded (<1% adoption).

Verification

• Production build passes; fumadocs-mdx clean; full-tree link sweep: 0 broken internal links; all preview usages validated against specs/exports; generator double-run → zero diff.
• Information-loss audit (4-agent, full diff): zero substantive facts/limits/procedures lost — every deletion is relocated (verified), covered elsewhere, or a listed deliberate cut (stale facts, re-teach padding, prose catalogs, UI hand-holding).

Known follow-ups (tracked, not blockers)

• Decision: in-editor Copilot still exists in the app but its docs page was removed in favor of Mothership (/copilot redirects there). Confirm direction or add a page post-merge.
• Screenshot/video re-capture pass (.plans/visuals-manifest.md, usage-prioritized; getting-started videos first) + remaining {/* VISUAL */} slots.
• Port the IA to de/es/fr/ja/zh; Academy tab; @sim/workflow-preview shared-renderer package (RFC on feat/docs-workflow-preview).

🤖 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

Medium Risk
Large, public-facing documentation and URL migration—broken redirects or stale generator output would affect discoverability, but runtime product code paths are largely unchanged.

Overview
Reorganizes English docs around builder-first IA: workflows, agents, platform, and one page per service at /integrations/<service> (replacing split /tools + /triggers paths), with legacy URLs 308-redirected and agent skills updated so new blocks use docsLink: …/integrations/{service}.

Adds a workflow-preview stack in the docs app—WorkflowPreview (React Flow canvases with loop/parallel containers, branch handles, lightbox + read-only inspector), BlockPreview heroes, OutputBundle, and --wp-* theme tokens aligned to the product UI—plus dozens of hand-authored example workflows wired into rewritten agent/concept pages.

Docs UX: front matter pageType drives a new PageTypeBadge; page templates drop the default DocsDescription subtitle. Generator (generate-docs.ts) emits merged Actions+Triggers integration MDX with hardened manual-content preservation; old per-block pages under content/docs/en/blocks/ are removed in favor of the new tree (content relocated per the PR audit).

Content updates: new guides (agents/choosing, custom-tools, expanded overview), trimmed MCP/skills copy (Skills UI on Integrations tab, import flows), and .gitignore for .plans/.

^{Reviewed by Cursor Bugbot for commit 649b01c. 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 11, 2026 1:39am

[gitguardian]

⚠️ GitGuardian has uncovered 1 secret following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

Since your pull request originates from a forked repository, GitGuardian is not able to associate the secrets uncovered with secret incidents on your GitGuardian dashboard.
Skipping this check run and merging your pull request will create secret incidents on your GitGuardian dashboard.

🔎 Detected hardcoded secret in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
33881454	Triggered	Generic Password	aae00a9	apps/sim/app/api/chat/utils.test.ts	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secret safely. Learn here the best practices.
3. Revoke and rotate this secret.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

[waleedlatif1]

@ouiliame we should probably remove this

[cursor]

Malformed gitignore entry

Low Severity

The Fumadocs ignore line combines /.source/ and .plans/ into one pattern with a space. Git treats that as a single path, so .plans/ under apps/docs is not ignored as intended.

 

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

[cursor]

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

There are 4 total unresolved issues (including 3 from previous reviews).

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

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

[cursor]

Parallel preview wrong handle

Medium Severity

Parallel workflow previews use the Loop inner-start handle id loop-start-source, but the builder uses parallel-start-source on Parallel containers. Docs claim handle ids match the app, so readers may wire the wrong handle in real workflows.

Additional Locations (1)

• apps/docs/components/workflow-preview/examples.ts#L1583-L1584

 

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