docs: builder-first IA reorganization of the English docs

.agents/skills/add-block/SKILL.md

@@ -41,7 +41,7 @@ export const {ServiceName}Block: BlockConfig = {
   name: '{Service Name}',               // Human readable
   description: 'Brief description',     // One sentence
   longDescription: 'Detailed description for docs',
-  docsLink: 'https://docs.sim.ai/tools/{service}',
+  docsLink: 'https://docs.sim.ai/integrations/{service}',
   category: 'tools',                    // 'tools' | 'blocks' | 'triggers'
   integrationType: IntegrationType.X,   // Primary category (see IntegrationType enum)
   tags: ['oauth', 'api'],              // Cross-cutting tags (see IntegrationTag type)
@@ -732,7 +732,7 @@ export const ServiceBlock: BlockConfig = {
   name: 'Service',
   description: 'Integrate with Service API',
   longDescription: 'Full description for documentation...',
-  docsLink: 'https://docs.sim.ai/tools/service',
+  docsLink: 'https://docs.sim.ai/integrations/service',
   category: 'tools',
   integrationType: IntegrationType.DeveloperTools,
   tags: ['oauth', 'api'],

.agents/skills/add-integration/SKILL.md

@@ -137,7 +137,7 @@ export const {Service}Block: BlockConfig = {
   name: '{Service}',
   description: '...',
   longDescription: '...',
-  docsLink: 'https://docs.sim.ai/tools/{service}',
+  docsLink: 'https://docs.sim.ai/integrations/{service}',
   category: 'tools',
   bgColor: '#HEXCOLOR',
   icon: {Service}Icon,
@@ -425,7 +425,7 @@ Run the documentation generator:
 bun run scripts/generate-docs.ts
 ```
 
-This creates `apps/docs/content/docs/en/tools/{service}.mdx`
+This creates `apps/docs/content/docs/en/integrations/{service}.mdx` — one page per service carrying the block's Actions and, if it has one, its Triggers section. Never hand-edit generated pages; the only editable region is the `{/* MANUAL-CONTENT */}` block (see `scripts/README.md`).
 
 ## V2 Integration Pattern
 

.agents/skills/validate-integration/SKILL.md

@@ -200,7 +200,7 @@ For **each tool** in `tools.access`:
 - [ ] `name` is human-readable (e.g., `'X'`, `'Cloudflare'`)
 - [ ] `description` is a concise one-liner
 - [ ] `longDescription` provides detail for docs
-- [ ] `docsLink` points to `'https://docs.sim.ai/tools/{service}'`
+- [ ] `docsLink` points to `'https://docs.sim.ai/integrations/{service}'`
 - [ ] `category` is `'tools'`
 - [ ] `bgColor` uses the service's brand color hex
 - [ ] `icon` references the correct icon component from `@/components/icons`

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/.plans/visuals-manifest.md

@@ -0,0 +1,169 @@
+# Visuals manifest — screenshots and walkthroughs to recapture
+
+Generated from the live content tree. CURRENT = captured against the new UI
+this cycle; everything else predates the UI changes (Integrations moved out of
+Settings, Agent block Messages field, new sidebar IA, block colors) and should
+be assumed stale until verified.
+
+**Capture priority (per platform usage data, 2026-06):** integration shots in
+adoption order — Google Sheets, Gmail, Telegram, WhatsApp, X, Google Drive,
+Outlook, YouTube, Slack; trigger shots led by Telegram/Gmail/WhatsApp;
+getting-started videos remain #1 overall (first-run funnel cliff).
+
+## Screenshots (120 unique)
+
+- [ ] `/static/api-deployment/api-info.png` — deployment/api.mdx
+- [ ] `/static/api-deployment/api-select-outputs.png` — deployment/api.mdx
+- [ ] `/static/api-deployment/api-tab.png` — deployment/api.mdx
+- [ ] `/static/api-deployment/api-update-button.png` — deployment/api.mdx
+- [ ] `/static/api-deployment/api-versions-menu.png` — deployment/api.mdx
+- [ ] `/static/api-deployment/api-versions.png` — deployment/api.mdx
+- [ ] `/static/blocks/credential-loop.png` — blocks/credential.mdx
+- [ ] `/static/blocks/guardrails-2.png` — blocks/guardrails.mdx
+- [ ] `/static/blocks/hitl-2.png` — blocks/human-in-the-loop.mdx
+- [ ] `/static/blocks/loop-1.png` — blocks/loop.mdx
+- [ ] `/static/blocks/loop-2.png` — blocks/loop.mdx
+- [ ] `/static/blocks/loop-3.png` — blocks/loop.mdx
+- [ ] `/static/blocks/loop-4.png` — blocks/loop.mdx
+- [ ] `/static/blocks/mcp-add-modal.png` — mcp/index.mdx
+- [ ] `/static/blocks/mcp-agent-dropdown.png` — mcp/index.mdx
+- [ ] `/static/blocks/mcp-agent-tools.png` — mcp/index.mdx
+- [ ] `/static/blocks/mcp-client-config.png` — deployment/mcp.mdx
+- [ ] `/static/blocks/mcp-deploy-modal.png` — deployment/mcp.mdx
+- [ ] `/static/blocks/mcp-server-add-modal.png` — deployment/mcp.mdx
+- [ ] `/static/blocks/mcp-server-details.png` — deployment/mcp.mdx
+- [ ] `/static/blocks/mcp-servers-settings.png` — deployment/mcp.mdx
+- [ ] `/static/blocks/mcp-settings.png` — mcp/index.mdx
+- [ ] `/static/blocks/mcp-tool-block.png` — mcp/index.mdx
+- [ ] `/static/blocks/parallel-1.png` — blocks/parallel.mdx
+- [ ] `/static/blocks/parallel-2.png` — blocks/parallel.mdx
+- [ ] `/static/blocks/schedule-3.png` — triggers/schedule.mdx
+- [ ] `/static/chat/chat-deploy-access-email.png` — deployment/chat.mdx
+- [ ] `/static/chat/chat-deploy-config.png` — deployment/chat.mdx
+- [ ] `/static/chat/chat-deploy-output.png` — deployment/chat.mdx
+- [ ] `/static/chat/chat-live.png` — deployment/chat.mdx
+- [ ] `/static/connectors/connectors-excluded.png` — knowledgebase/connectors.mdx
+- [ ] `/static/connectors/connectors-list.png` — knowledgebase/connectors.mdx
+- [ ] `/static/connectors/connectors-sources.png` — knowledgebase/connectors.mdx
+- [ ] `/static/connectors/connectors-sync-history.png` — knowledgebase/connectors.mdx
+- [ ] `/static/credentials/add-service-account.png` — integrations/google-service-account.mdx
+- [ ] `/static/credentials/atlassian/admin-auth-type-picker.png` — integrations/atlassian-service-account.mdx
+- [ ] `/static/credentials/atlassian/admin-scope-picker.png` — integrations/atlassian-service-account.mdx
+- [ ] `/static/credentials/atlassian/sim-add-modal.png` — integrations/atlassian-service-account.mdx
+- [ ] `/static/credentials/atlassian/sim-jira-block-credential.png` — integrations/atlassian-service-account.mdx
+- [ ] `/static/credentials/gcp-add-client-id.png` — integrations/google-service-account.mdx
+- [ ] `/static/credentials/gcp-create-private-key.png` — integrations/google-service-account.mdx
+- [ ] `/static/credentials/gcp-create-service-account.png` — integrations/google-service-account.mdx
+- [ ] `/static/credentials/integrations-service-account.png` — integrations/google-service-account.mdx
+- [ ] `/static/credentials/oauth-selector.png` — integrations/index.mdx
+- [ ] `/static/credentials/secret-dropdown.png` — credentials/index.mdx
+- [ ] `/static/credentials/secret-resolved.png` — credentials/index.mdx
+- [ ] `/static/credentials/workflow-impersonated-account.png` — integrations/google-service-account.mdx
+- [ ] `/static/enterprise/access-control-blocks.png` — enterprise/access-control.mdx
+- [ ] `/static/enterprise/access-control-groups.png` — enterprise/access-control.mdx
+- [ ] `/static/enterprise/access-control-model-providers.png` — enterprise/access-control.mdx
+- [ ] `/static/enterprise/access-control-platform.png` — enterprise/access-control.mdx
+- [ ] `/static/enterprise/audit-logs.png` — enterprise/audit-logs.mdx
+- [ ] `/static/enterprise/data-drains-list.png` — enterprise/data-drains.mdx
+- [ ] `/static/enterprise/data-drains-new.png` — enterprise/data-drains.mdx
+- [ ] `/static/enterprise/data-retention.png` — enterprise/data-retention.mdx
+- [ ] `/static/enterprise/sso-form.png` — enterprise/sso.mdx
+- [ ] `/static/enterprise/whitelabeling.png` — enterprise/whitelabeling.mdx
+- [ ] `/static/execution/combination.png` — workflows/how-it-runs.mdx
+- [ ] `/static/execution/concurrency.png` — workflows/how-it-runs.mdx
+- [ ] `/static/execution/routing.png` — workflows/how-it-runs.mdx
+- [ ] `/static/getting-started/started-1.png` — getting-started/index.mdx
+- [x] `/static/integrations/hubspot/connect-hubspot-modal.png` — integrations/hubspot-setup.mdx, integrations/index.mdx
+- [x] `/static/integrations/hubspot/hubspot-oauth-signin.png` — integrations/hubspot-setup.mdx
+- [x] `/static/integrations/hubspot/hubspot-page-add-to-sim.png` — integrations/hubspot-setup.mdx, integrations/index.mdx
+- [x] `/static/integrations/hubspot/integrations-page.png` — integrations/hubspot-setup.mdx, integrations/index.mdx
+- [ ] `/static/integrations/manual-credential-id.png` — integrations/index.mdx
+- [ ] `/static/integrations/switch-to-manual-id.png` — integrations/index.mdx
+- [ ] `/static/introduction.png` — introduction/index.mdx
+- [ ] `/static/logs/console.png` — logs-debugging/logging.mdx
+- [ ] `/static/logs/logs-cost.png` — costs.mdx
+- [ ] `/static/logs/logs-frozen-canvas.png` — logs-debugging/logging.mdx
+- [ ] `/static/logs/logs-sidebar.png` — logs-debugging/logging.mdx
+- [ ] `/static/logs/logs.png` — logs-debugging/logging.mdx
+- [ ] `/static/mothership/chart-example.png` — mothership/files.mdx
+- [ ] `/static/mothership/image-example.png` — mothership/files.mdx
+- [ ] `/static/mothership/pptx-example.png` — mothership/files.mdx
+- [ ] `/static/mothership/table-example.png` — mothership/tables.mdx
+- [ ] `/static/quick-reference/add-env-variable.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/clear-chat.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/clear-terminal.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/copy-api.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/copy-log.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/create-workflow.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/delete-block.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/deploy.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/disable-block.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/env-variable-reference.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/filter-block.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/folder-context-menu.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/import-workflow.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/lock-block.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/output-select.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/promote-deployment.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/run-from-block.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/run-until-block.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/run-workflow.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/search-everything.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/stop-workflow.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/terminal-search.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/terminal.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/test-chat.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/toggle-manual-mode.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/update-deployment.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/variable-reference.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/variables.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/view-deployment.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/workflow-context-menu.png` — quick-reference/index.mdx
+- [ ] `/static/quick-reference/workspace-context-menu.png` — quick-reference/index.mdx
+- [ ] `/static/secrets/secret-details.png` — credentials/index.mdx
+- [ ] `/static/secrets/secrets-list.png` — credentials/index.mdx
+- [x] `/static/skills/add-skill-create.png` — skills/index.mdx
+- [x] `/static/skills/add-skill-import.png` — skills/index.mdx
+- [ ] `/static/skills/add-skill.png` — skills/index.mdx
+- [x] `/static/skills/skills-tab.png` — skills/index.mdx
+- [ ] `/static/start.png` — triggers/start.mdx
+- [ ] `/static/tables/tables-overview.png` — tables/index.mdx
+- [ ] `/static/tags/tags-create.png` — knowledgebase/tags.mdx
+- [ ] `/static/tags/tags-document-list.png` — knowledgebase/tags.mdx
+- [ ] `/static/tags/tags-kb-menu.png` — knowledgebase/tags.mdx
+- [ ] `/static/tags/tags-knowledge-block.png` — knowledgebase/tags.mdx
+
+## Walkthrough videos (23 unique, CDN-served)
+
+All predate the current UI. getting-started/* confirmed stale (System/User
+Prompt era). Mothership set may be closest to current — verify before re-recording.
+
+- [ ] `getting-started/started-2.mp4` — getting-started/index.mdx
+- [ ] `getting-started/started-3.mp4` — getting-started/index.mdx
+- [ ] `getting-started/started-4.mp4` — getting-started/index.mdx
+- [ ] `getting-started/started-5.mp4` — getting-started/index.mdx
+- [ ] `getting-started/started-6.mp4` — getting-started/index.mdx
+- [ ] `guardrails.mp4` — blocks/guardrails.mdx
+- [ ] `hitl-resume.mp4` — blocks/human-in-the-loop.mdx
+- [ ] `introduction/build-workflow.mp4` — introduction/index.mdx
+- [ ] `invitations.mp4` — permissions/roles-and-permissions.mdx
+- [ ] `knowledgebase-1.mp4` — knowledgebase/index.mdx
+- [ ] `mcp/mcp-deploy-tool.mp4` — deployment/mcp.mdx
+- [ ] `mcp/mcp-server.mp4` — deployment/mcp.mdx
+- [ ] `mcp/settings-mcp-tools.mp4` — mcp/index.mdx
+- [ ] `mothership/context-menu.mp4` — mothership/index.mdx
+- [ ] `mothership/create-workflow.mp4` — mothership/index.mdx, mothership/workflows.mdx
+- [ ] `mothership/files-pipeline-deals-summarizer.mp4` — mothership/files.mdx
+- [ ] `mothership/job-create.mp4` — mothership/tasks.mdx
+- [ ] `mothership/kb.mp4` — mothership/knowledge.mdx
+- [ ] `mothership/research-agent.mp4` — mothership/research.mdx
+- [ ] `mothership/run-workflow.mp4` — mothership/workflows.mdx
+- [ ] `mothership/split-view.mp4` — mothership/index.mdx
+- [ ] `mothership/toggle-file-view.mp4` — mothership/files.mdx
+- [ ] `slack-trigger.mp4` — triggers/webhook.mdx
+
+## Also missing entirely (no asset yet)
+
+39 `{/* VISUAL */}` placeholder slots + 16 `{/* TODO */}` screenshot markers —
+see `grep -rn 'VISUAL\|TODO' content/docs/en/` for the live list (concentrated
+in tables, mothership, logs-debugging, files, workspaces, deployment).