From bc55fc3b50933cbdc46844b0c8207a99ec4e6b31 Mon Sep 17 00:00:00 2001 From: Will Chen Date: Wed, 10 Jun 2026 18:39:57 -0700 Subject: [PATCH] improvement(docs): builder-first IA reorganization of the English docs (#4896) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: reorganize into topic/ontology IA with a builder-first rewrite Restructure the English docs from internal product categories into a topic-based information architecture, and rewrite the conceptual pages to install a mental model first rather than enumerate features. Structure & navigation - Reorder the sidebar to follow how someone builds: Get Started -> Workflows -> Tables -> Files -> Knowledge Bases -> Logs -> Building agents -> Mothership -> Workspaces -> Platform -> Reference. - Demote the generated blocks/tools/triggers catalogs to a Reference section at the bottom. - Break up the monolithic execution/ folder into deployment/ and logs-debugging/; collapse connections/* and variables/* into single pages under workflows/. - Rename capabilities/ to building-agents/; relabel the integration catalog as "Integrations". Remove deprecated copilot and form deployment. Redirects added in next.config.ts for every moved URL. Conceptual rewrites - Workflows core (index, how-it-runs, data-flow, connections, variables): one mental model, one running example, terser prose. - New building-agents overview distinguishes an agent (a workflow you build) from an Agent block (one reasoning step), plus a "choosing what to use" guide. - Concept-trim passes on Knowledge Base, Tables, Blocks, Triggers overviews; new task pages for KB, Tables, and Files. - New code-verified Alerts page. Infrastructure - pageType frontmatter (concept/guide/reference) + badge render. - WorkflowPreview / OutputBundle components to embed real, app-styled workflow diagrams (adds framer-motion + reactflow to apps/docs). Co-Authored-By: Claude Opus 4.8 (1M context) * feat(docs): spec-driven BlockPreview for block reference heroes Replace the static screenshot hero on each block reference page with a that renders the block exactly as the builder canvas shows it — header icon, sub-block rows, and branch/error handles — from a hand-authored display spec. Static and non-interactive (no ReactFlow), so it can't be panned or dragged, and self-updating to edit. - block-display-specs.ts: one editable spec per block (rows, branches, handles) - block-preview.tsx: static scaled card renderer with decorative handles - block-icons.tsx: brand glyphs for the core block types; icons.tsx adds WaitIcon - 14 block + 3 trigger pages swapped from to Co-Authored-By: Claude Opus 4.8 (1M context) * fix(docs): correct stale navigation and removed-feature references Audited the docs against the product changelog (GitHub releases / staging git history) for content that misleads readers — features that moved, were renamed, or removed — rather than cosmetic drift. Fixes: - Skills: no longer a Settings tab. It was promoted to its own workspace page (#4354), so "Settings → Skills under the Tools section" sent readers to a tab that no longer exists. (skills/index.mdx) - Env vars: the workspace tab is "Secrets", not "Environment Variables" (credentials→secrets rename, #4364). (quick-reference/index.mdx) - Mothership FAQ pointed to "Settings → Credentials" for integration connections; integrations moved to their own page and there is no Credentials tab. (mothership/tasks.mdx) - Vision block was retired (#4684); a tip still named it. Reworded to "an Agent using a vision-capable model". (files/passing-files.mdx) - Getting-started FAQ told new users to "use the Copilot feature" to build in natural language — that surface is Mothership. (getting-started) - Removed the dead "Mod+Y → Go to templates" shortcut; the templates gallery was removed (#4354). (keyboard-shortcuts) Note: MCP "tools" (Settings → Tools, for consuming) and MCP "servers" (Settings → System, for exposing) are distinct surfaces — both doc references are correct and were intentionally left as-is. Co-Authored-By: Claude Opus 4.8 (1M context) * fix(docs): repair broken /docs-prefixed enterprise links The enterprise overview linked to /docs/enterprise/* (access-control, sso, whitelabeling, audit-logs, data-retention, data-drains), but the docs site is served at root — those 6 links 404'd. Now root-relative /enterprise/*. Co-Authored-By: Claude Opus 4.8 (1M context) * fix(docs): refresh stale workflow-preview example blocks The /workflows diagram blocks are hand-authored (separate from the spec-driven BlockPreview heroes) and had drifted from the real UI: - Agent color purple #6f3dfa -> green #33C482 (the var(--brand) rebrand) - Model gpt-4o -> claude-sonnet-4-6 (current default) - "Prompt" row -> "Messages" (the actual agent sub-block) - Start color #34B5FF -> #2FB3FF (real starter bgColor) Co-Authored-By: Claude Opus 4.8 (1M context) * fix(docs): align BlockPreview input/output handles to the card edge The header (input/output) handles are positioned relative to the card and used a -16px offset, so they floated 8px past the edge. Row/error handles are -16px relative to a row that's already inset 8px by content padding, so they sit correctly. Header handles are now -8px, so every handle sticks out the same 8px and hugs the block edge. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): rewrite Agent reference to match the current block The page documented the old UI (System/User Prompt, no Files or Skills, Memory taught as a separate block — contradicting its own FAQ). Rewritten to the real sub-blocks (Messages, Model, Files, Tools, Skills, Memory, Response Format) in the builder voice of the workflows exemplars: oriented opening, agent vs Agent-block callout, outputs table, a live WorkflowPreview example, FAQ kept and corrected (tool control "Force", not "Required"). pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): rewrite API reference to match the current block Tightened to the builder voice and the real config (URL, Method, Query Params, Headers, Body + Advanced timeout/retries/backoff). Dropped the off-topic "Dynamic URL Construction" / "Response Validation" sections (those are Function-block techniques, not API config). Outputs table, FAQ kept. The example is now a live WorkflowPreview (new API_FETCH_WORKFLOW in examples.ts, exported via the barrel). pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): rewrite Condition reference to match the current block Tightened to the builder voice: oriented opening (branches on boolean expressions, no model call, vs Router), the real branch model (if / else if / else, checked top to bottom), connection-tag expression examples, an error-path callout, outputs table, and a live branching WorkflowPreview example (CONDITION_ROUTE_WORKFLOW). FAQ kept. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): restore Best Practices + multi-example workflows on Condition Recalibration: reference pages keep genuine substance (Best Practices, every distinct example), cutting only redundancy and verbose register. Restores the Best Practices section and turns the three use cases into three rendered WorkflowPreview examples (route by priority, moderate content, branch onboarding). Adds CONDITION_MODERATE_WORKFLOW and CONDITION_ONBOARD_WORKFLOW. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): restore Best Practices on Agent reference Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): restore Best Practices on API reference Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): rewrite Function reference to match the current block Fixed the verbose register and dropped the duplicated outputs section + the stale Python screenshot/TODO, while keeping the real substance: JS vs Python (local vs E2B sandbox), the large-inputs sim.files/sim.values helpers, the worked loyalty-score example, and Best Practices. The use cases are now two rendered WorkflowPreview examples (reshape an API response, validate input). Adds FUNCTION_RESHAPE_WORKFLOW and FUNCTION_VALIDATE_WORKFLOW. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): rewrite Router reference to match the current block Cleaned the register, generalized the drifting model list, and folded the Router-vs-Condition guidance into a callout. Kept the substance (routes as output ports, NO_MATCH error path, all seven outputs, Best Practices, FAQ). The three same-shape use cases collapse to one rendered triage WorkflowPreview (ROUTER_TRIAGE_WORKFLOW), which the prose notes stands for the pattern. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): restore the classify and lead-qual examples on Router I wrongly folded two distinct Router scenarios into a note. Restored all three as their own rendered WorkflowPreview examples: triage a support ticket, classify feedback (to child workflows), qualify a lead (sales vs self-serve). Adds ROUTER_CLASSIFY_WORKFLOW and ROUTER_LEAD_WORKFLOW. (Also exports RESPONSE_API_WORKFLOW for the next page.) Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): rewrite Response reference to match the current block Cleaned the register and broadened "Variable References" to connection tags (any output, not just workflow variables). Kept the substance: exit-point semantics, Builder/Editor mode, status codes, headers, the parallel-branch warning, Best Practices, FAQ. All three use cases are now rendered WorkflowPreview examples (API endpoint, webhook ack, status-per-branch). Adds RESPONSE_API/WEBHOOK/ERROR_WORKFLOW. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): rewrite Variables reference to match the current block Cleaned the register, corrected the outputs (each assignment is also exposed as , not "no outputs"), and kept the substance: assignments reference earlier outputs and current values, global access, Best Practices, FAQ. Two use cases now render as WorkflowPreview examples (count retries, hold config). Adds VARIABLES_RETRY_WORKFLOW and VARIABLES_CONFIG_WORKFLOW. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): rewrite Wait reference to match the current block Corrected a real staleness: the block now has an Async mode that suspends the run for minutes/hours/days (not a hard 10-minute cap), plus a resumeAt output. Documents Wait Amount / Unit / Async, the sync-vs-async distinction, all three outputs, Best Practices, and updated FAQ. Two rendered WorkflowPreview examples (space out API calls, delayed follow-up). Adds WAIT_RATELIMIT_WORKFLOW and WAIT_FOLLOWUP_WORKFLOW. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): polish Credential reference (frontmatter, fold redundant tabs) The page was already accurate to the block (Select/List operations, the outputs tabs, the wiring steps). Light touch only: added description + pageType, made the header consistent, and folded the two identical Gmail/Slack "how to wire" tabs into one line. Examples stay as labeled flows + the List/ForEach screenshot, since they use integration blocks and a Loop the WorkflowPreview can't render. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): render the shared-credential example + icon fallback for integrations Addressing the gap: WorkflowPreview block nodes now fall back to the integration icon map, so diagrams can show Gmail/Drive/Slack/etc. with their real glyphs, not just core blocks. Renders the Credential "share one account across blocks" example as a WorkflowPreview (CREDENTIAL_SHARE_WORKFLOW). The multi-account and List+ForEach examples stay as labeled flows + screenshot (the latter uses a Loop container the preview can't render). Also exports EVALUATOR_GATE_WORKFLOW for the next page. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): rewrite Evaluator reference to match the current block Cleaned the register, generalized the drifting model list, and documented the per-metric outputs (), which the page omitted. Kept the substance (metrics with name/description/range, structured-output guarantee, Best Practices, FAQ). The quality-gate example renders as a WorkflowPreview; the same shape covers the parallel-variations and support-QC patterns, noted in prose. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): render the Credential route-by-logic example too The icon fallback unblocked it: the "route to a different account by logic" example now renders as a WorkflowPreview (CREDENTIAL_ROUTE_WORKFLOW), a Condition selecting a production vs staging credential. The List + ForEach example stays a screenshot because it nests blocks in a Loop container the flat WorkflowPreview can't represent. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): render Guardrails examples + light accuracy pass Kept the full substance (four validation types, PII entity/language detail, the PII screenshot and video, outputs, Best Practices, FAQ). Light fixes: frontmatter, and generalized the drifting model names (GPT-4o / Claude 3.7) to "a strong reasoning model" with the current default. The three use cases now render as WorkflowPreview examples (validate JSON, check grounding, block PII). Adds GUARDRAILS_JSON/HALLUCINATION/PII_WORKFLOW. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): render Human-in-the-Loop examples + frontmatter Kept all the substance (Display Data, Notification, Resume Form, the Approval Methods and API Execute Behavior tabs, outputs, the paused/resume example). Added frontmatter and rendered the use cases as WorkflowPreview examples (approve before publish, two-stage approval, verify extracted data); Quality Control folds into the approval note as the same approve-then-act shape. Adds HITL_APPROVAL/MULTISTAGE/VALIDATE_WORKFLOW. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): render Webhook examples + frontmatter The page was already accurate (Webhook URL/Payload/Signing Secret/Headers, the automatic-headers table, HMAC details, outputs, POST-only callout, FAQ). Added frontmatter and rendered the two use cases as WorkflowPreview examples (notify a service, fire on a check). Adds WEBHOOK_NOTIFY_WORKFLOW and WEBHOOK_TRIGGER_WORKFLOW. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): add example + pageType to Workflow block reference The page was already accurate and well-structured (Configure It, outputs, deployment-status badge, execution notes, FAQ). Added pageType: reference and a rendered WorkflowPreview example showing a parent calling the child workflow enrich-lead and reading its result. Adds WORKFLOW_CALL_WORKFLOW. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): container rendering for Loop/Parallel + render the Loop example Adds subflow/container support to WorkflowPreview, modeled on the app's subflow-node.tsx: a solid-bordered box with a header (icon + name), an internal "Start" pill whose handle feeds the first nested block, and target/source handles at the vertical center. PreviewBlock gains size/parentId; edges gain an optional sourceHandle; nodes render nested children via React Flow parentNode. Renders the Loop reference's ForEach example (LOOP_WORKFLOW) and keeps the four loop-type sections + inside/outside referencing + caps. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): fix the Loop container's Start-pill connector The Start pill -> first-block edge wasn't rendering: it was a React Flow parent->child edge (unreliable), and the opaque container body hid it. Nested blocks now render as absolute-positioned top-level nodes (container below at zIndex 0, blocks above at zIndex 1), so the connector is an ordinary edge, and the container body is see-through so it's visible. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): render the Parallel example + frontmatter (last core block) Reuses the container rendering for the Parallel reference. Kept all substance (count/collection types, inside/outside referencing, batch size of 20, instance isolation, the Parallel-vs-Loop table, Best Practices, FAQ). Added frontmatter and a rendered container WorkflowPreview (PARALLEL_WORKFLOW: distribute tasks, call concurrently, aggregate ); the two use cases stay as labeled flows. Adds PARALLEL_WORKFLOW. pageType: reference. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): prose glow-up for Guardrails to match the agent/condition voice Rewrote the listy register (**Use Cases:** / **How It Works:** / **Configuration:** scaffolding, "Use this when you need to..." filler) into the plain builder voice, matching the depth of the Agent/Condition/Function rewrites. Kept every validation type, option, range, the full PII entity/region list, the screenshot and video, the outputs table, the rendered examples, Best Practices, and FAQ. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): prose glow-up for Loop to match the agent/condition voice Rewrote into the plain builder voice and cut the filler: dropped the "Use this when you need to..." lines and the ASCII "Example: Iteration 1, 2, 3" pseudo-code, and folded the duplicated Inputs/Outputs tabs into Configuration + Referencing sections. Kept all four loop types with their screenshots, the inside/outside reference rules, the 1,000-iteration cap, sequential-vs-parallel guidance, the rendered example, and FAQ. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): prose glow-up for Parallel to match the agent/condition voice Same treatment as Loop: plain builder voice, dropped the ASCII pseudo-code and the duplicated Inputs/Outputs tabs, folded the verbose Advanced Features into tight Configuration + Referencing sections. Kept both types with screenshots, the batch-size-of-20 cap, instance isolation, large-result indexing, the Parallel-vs-Loop table, the rendered example, and FAQ. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): prose glow-up for Human-in-the-Loop Tightened the register: folded the pause sentence into the intro, made the section headers consistent (Configuration, Outputs), converted the bold-list Block Outputs into a table, condensed the Notification channel bullets to a line, and renamed the second "Example" so it no longer collides with the rendered Examples. Kept all the substance — Display Data / Notification / Resume Form, the Approval Methods and API Execute Behavior tabs, the portal video, and FAQ. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): re-enrich Loop prose (fuller, explanatory — not terse) The first glow-up overcorrected into terse fragments. Restored proper docs-quality prose at the Agent/Condition level: each loop type now explains what it does, when to use it, and the relevant reference; Configuration, Referencing, nesting, and Best Practices give context and the "why," not just bullets. Same substance, readable depth. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): re-balance Parallel prose to the Agent/Condition register Calibrated to the level signed off on elsewhere: each concept explained in a couple of clear sentences with a concrete detail — informative, not terse, not padded. Kept both types with screenshots, batch-size cap, isolation, large-result indexing, the Parallel-vs-Loop table, the rendered example, and FAQ. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): restore the Notification channel detail on HITL The glow-up over-compressed: it flattened the five notification channels (each with what they do) into one sentence. Restored them as a list in plain voice — tightening register shouldn't drop genuinely useful reference detail. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(blocks): builder-voice polish on the Credential intro Light touch only — the page was already well-structured and explanatory, so just led the intro with what the block does (and bolded the name) to match the other references. No content changed elsewhere. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(triggers): rewrite Start trigger in the builder voice Tightened the register, swapped the <> noise for backticks, added pageType + an outputs table, and kept all substance: Input Format types, chat-only outputs (input/conversationId/files), the editor/API/chat tabs, and best practices. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(triggers): rewrite Schedule trigger in the builder voice Plain voice and clean markdown (dropped the raw