diff --git a/apps/docs/AGENTS.md b/apps/docs/AGENTS.md
new file mode 100644
index 00000000000..5c3dccfd7d6
--- /dev/null
+++ b/apps/docs/AGENTS.md
@@ -0,0 +1,37 @@
+# Documentation guidelines
+
+Read [EDITORIAL_GUIDE.md](EDITORIAL_GUIDE.md) before editing documentation. It defines the voice, terminology, page types, section order, and component choices. [COPY_AUDIT.md](COPY_AUDIT.md) records the complete audit and material source qualifications; keep new conclusions evidence-based.
+
+## Copy and accuracy
+
+- Read the complete original page before rewriting. Preserve useful prerequisites, syntax, examples, permissions, defaults, limits, failure consequences, and recovery instructions. Move repeated detail only after its canonical owner contains it and the local link works.
+- Verify consequential behavior against its current implementation. Use primary documentation for external procedures. Distinguish repository defaults from deployed settings, Cloud from self-hosting, and accepted operations from completed work.
+- Keep Chat content delivery separate from ordinary UI, API-key, MCP, and workflow access. A saved write can have a withheld result; do not imply that a display failure undoes the write.
+- Use concise, concrete prose and sentence-case headings. Remove repetition and decorative components without making required information sparse. Honor the editing scope; shared components and assets may still serve excluded pages.
+
+## Sources and generation
+
+- Edit generated API and CLI prose at its owner, then use the generation commands in the editorial guide. Do not hand-edit generated specifications, reference pages, or marked generated regions.
+- Preserve page URLs, operation IDs, method/path pairs, command options, authentication, and schema behavior. Validate copyable request bodies against the canonical input contracts.
+- Check inbound heading anchors from the entire docs site and application before renaming them. Use native explicit tab triggers for provider bookmarks, with `aria-controls` matching panel IDs; preserve the reciprocal `aria-labelledby` relationship and avoid duplicate element IDs.
+
+## Layout and components
+
+- Use existing Sim tokens and EMCN chrome. Keep styling local to the component; do not add global CSS overrides or custom colors for one page.
+- Use [the authored tab components](components/ui/tabs.tsx). Mixed prose/code panels retain padding; a single code fence can fill its frame. Preserve native selection, keyboard behavior, and intentional code/table scrolling.
+- Page spacing belongs to the page container. The navbar, TOC, and sidebar must agree on breakpoints and reserved row heights. Use the shared section order and route matching in `lib/navigation.ts`.
+- Inspect mobile, tablet, desktop, and breakpoint boundaries. Check 320px and 390px widths, both sides of 640px, 768px, 1024px, and 1280px, plus a wide desktop. Verify headings clear sticky chrome, drawers remain reachable, touch targets are usable, and prose does not overflow. Restore temporary viewport and theme changes after QA.
+
+## Verification
+
+Compile the affected MDX, check internal links and preserved anchors, run the required repository gates, and inspect the production build. Validate all affected tabs and navigation states, rather than only their default panels. Record exact scope and limitations; a successful build does not prove an external provider setup or live Cloud configuration.
+
+<!-- BEGIN:nextjs-agent-rules -->
+
+## This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->
diff --git a/apps/docs/COPY_AUDIT.md b/apps/docs/COPY_AUDIT.md
new file mode 100644
index 00000000000..527220f1ac6
--- /dev/null
+++ b/apps/docs/COPY_AUDIT.md
@@ -0,0 +1,712 @@
+# Documentation copy audit
+
+Audited from staging snapshot `4d2fa26f5de0532048487a94bbe1afc744500dfe`, beginning 2026-10-13. Rebased onto `origin/staging` at `9058427155` and reviewed the 20 intervening commits before final validation. The [editorial guide](EDITORIAL_GUIDE.md) defines the final voice, terminology, organization, media, and generated-source rules.
+
+## Scope and method
+
+The inventory contains **484 entries**: 153 authored MDX pages, 28 generated CLI references, and 303 generated API operations. One authored entry is the root redirect, leaving 483 readable routes. All 306 integration pages are excluded from copy changes, but their links and shared component/asset dependencies are checked.
+
+Each section received a complete audit before rewriting. Reviewers read the entire assigned copy, retained a per-page ledger, compared consequential claims with the owning implementation, checked examples and limits, inspected local media, and used current primary documentation for external setup. Repeated generated schema prose was read once per unique value while retaining every operation-to-field relationship. This is a documentation accuracy review, not proof of a live hosted configuration or an exhaustive security review.
+
+Useful facts are retained or moved to a linked canonical owner. Changes remove repeated introductions, promotional language, displaced FAQs, speculative visual placeholders, stale UI instructions, and redundant media. API and CLI prose changes occur at their canonical sources and are regenerated; identifiers, paths, permissions, schema behavior, defaults, and command options are preserved.
+
+## Assessment and final standard
+
+The original copy often contained useful technical detail, but placed it behind repeated benefits, broad promises, FAQs, and screenshots of ordinary controls. Pages mixed concepts, setup, reference, and troubleshooting in different orders. The final standard uses a short task-focused opening, sentence-case headings, exact visible labels, and a consistent order for each page type. It preserves detailed references where brevity would hide a requirement or failure consequence.
+
+## Coverage
+
+| Section | Entries | Disposition |
+| --- | ---: | --- |
+| Workflow blocks | 18 | complete |
+| API data operations | 136 | complete |
+| API workflow operations | 59 | complete |
+| API workspace operations | 108 | complete |
+| CLI reference | 28 | complete |
+| Self hosting setup | 10 | complete |
+| Self hosting operations | 12 | complete |
+| Workflow core | 16 | complete |
+| Enterprise governance | 8 | complete |
+| Search | 21 | complete |
+| Platform | 6 | complete |
+| Enterprise identity | 9 | complete |
+| Orientation | 6 | complete |
+| Chat | 8 | complete |
+| API guides | 5 | complete |
+| Knowledgebase | 7 | complete |
+| Agents | 5 | complete |
+| CLI guides | 8 | complete |
+| Files | 5 | complete |
+| Tables | 3 | complete |
+| Logs | 3 | complete |
+| MCP | 3 | complete |
+
+## Main accuracy corrections
+
+| Area | Finding and final treatment | Implementation or canonical owner |
+| --- | --- | --- |
+| Workflow state and branching | Variables assign resolved values rather than calculate; Parallel shares workflow variables and unhandled errors can fail the run. Correct examples use real container names and nested result shapes. Router exposes context/reasoning rather than content; an unconnected selectedPath has an empty blockId rather than null. | `executor/handlers/variables`, `executor/execution`, workflow/block guides and shared previews |
+| Runs and deployment | Draft inspection, deployed execution, sync/async receipts, token streaming, v2 framing and legacy resume differ. v2 streaming runs resume asynchronously. Workflow exports can still contain literal secrets. Thinking and tool events have separate deployment policies. Function All secrets narrows the run’s authorized environment rather than granting new access. | `lib/workflows/application`, `lib/workflows/executor`, workflow deployment guides |
+| Agent and Pi | Structured output is requested, not universally guaranteed; parsed fields are not always an object in content. Cache rules vary by model. Pi includes Plan; SSH shell starts in the repository but has the account’s OS permissions. | Agent/Pi handlers and block references |
+| Tables | Cells nest under row.data. Mappings populate Start fields without restricting full row context. False/empty dependencies wait; edits/output clearing can re-arm work. Completed blank results differ from incomplete runs. Expiration is scheduled deletion. | `lib/table`, workflow-column worker/UI and table guides |
+| Credentials and permissions | Credential Groups grant allowed integration types. Personal secrets have grant-resolution nuances without a current sharing control. Explicit empty SCIM groups govern nobody; empty inheritance groups can broaden scope. Workspace keys differ from human principals. | Credential/permission-group use cases, platform and enterprise guides |
+| Logs and retention | Refresh loads a stable snapshot; search text matches run IDs, not arbitrary run content. Current trace uses stacked sections. Run-backed alert cooldowns differ from the per-workflow No Activity cooldown. Cloud Free defaults to 30 days, paid and billing-disabled modes have no plan default, and configured cleanup is deletion rather than an archive. | Logs UI/filter implementation, cleanup dispatcher and Data retention |
+| Costs | Billing mode is distinct from hosting location. Model-block cost objects and Logs API cost fields use USD while Billing/run-resource endpoints and displayed logs use credits. Unsupported purchase/voice instructions are removed; live Max limit conflicts stay qualified. | Cost contracts, billing configuration and Costs |
+| Search | Supported sources retain their specific access/query/read limits. Drive’s native Sheets reads need Sheets API; OAuth setup has a canonical owner. Confluence overflow relevance pages are partial and have no cursor; native CQL supports continued paging. GitLab legacy search is unavailable; Zoom is deployment-enabled rather than universally present. | Search adapters, provider setup and Search guides |
+| Chat and desktop | Recurring Chat work uses deployed workflow schedules; worker behavior is source evidence, not a live Cloud guarantee. Desktop selected-folder reads, browser uploads, Full file access and OS shell privileges are distinct. Native Mac-app control requires its deployment gate, device opt-in and app approval; Chat Find searches loaded transcript windows. | Current external-worker snapshot, desktop tools/settings and Chat/Desktop guides |
+| Self-hosting | Deployment-wide schedule caps, background job inventory, Node workers, secrets/TLS/origins, storage durability and billing-disabled limits are scoped. Chart 1.11.8 is a verified published example, not a live installation claim. | Compose/Helm, config and operator guides |
+| MCP | JSON operations only; read operations can have POST bodies. Catalog search is bounded without a cursor, offline refresh expires, and a result-size error can follow a committed write. | MCP catalog/dispatch/auth and MCP guides |
+| Generated requests | Original rendered defaults had 17 invalid JSON bodies out of 135. Media-level validated examples and valid fork/push/pull/import examples correct these without changing the input contracts. | OpenAPI generator and owning contracts |
+| CLI | Resource/lifecycle organization keeps comprehensive command lookup, flags, aliases and confirmation consequences. Inline code preserves literal pipes, backslashes and nested ticks. | CLI command metadata and documentation generator |
+| Output and limits QA | Qualified Function timeout/stdout limits, Agent metadata-name collisions, Evaluator fallback/coercion, abbreviated Connections outputs, and fixed table column limits. | Current Function/Agent/Evaluator handlers and Table constants |
+| Final preservation review | Restored five provider-token setup links, Stop all and manual dependency behavior, regional PII identifiers and Presidio reference, named Credential references, exact paused v2 resume lookup, and the direct migration prerequisite before upgrade commands. Workflow preview code and visible labels match their examples. | Current settings, executor, table worker, PII catalog and migration owners |
+| Current source qualifications | Corrected paid retention tiers, GiB storage units, Bun/Node prerequisites, SSO/Integrations labels, drain endpoint policy, reversible encryption-key mismatch, NetworkPolicy any-source default, and Pi absolute provider TTL/account limits. | Billing cleanup, settings UI, outbound profiles, encryption, chart and sandbox adapters |
+| API and CLI final comparison | Truthful full connector example uses current projected fields/scopes and incremental-sync support. CLI help distinguishes credit usage, saved changes, delete scheduling, variable batches and file references. Restoring the search keyword “spent” preserves billing discovery without the false period claim. | Connector metadata/projection, command metadata and existing search ranking tests |
+| Generated output safety | The real resources input exceeds Biome’s default 1 MiB cap, which previously yielded successful empty output. The formatter now explicitly caps input/output at 16 MiB, rejects process failures and nonempty-input/empty-output results, and preserves complete parsed JSON. | `scripts/format-generated-source.ts` and actual generator boundary proof |
+
+## Independent final comparison
+
+A fresh parallel review compared every complete original page with its final version, including examples, prerequisites, useful FAQ answers, and local media. Exact ledger reconciliation covers all **484 entries across 22 sections**, without duplicate or missing assignments. Reviewers judged each entry an improvement in clarity, organization, accuracy, or useful coverage, with **zero remaining identified copy issues** after corrections. This is a documented comparative judgment, not a guarantee that every external setup or deployed policy has been exercised. The final column retains the per-page comparison and preservation conclusions.
+
+The final source pass also reviewed the later Chat content-delivery gate, crawler/Markdown changes, and shared file-ownership foundation from staging. Workspace access, search completeness, sharing, storage and retention wording remain supported. Newly added Project foundations are not described as a released Project Files surface. Integration landing backlinks and per-page Markdown are preserved.
+
+## Components and asset cleanup
+
+Shared navigation and API UI labels follow sentence case while preserving acronyms and product names. Authored tabs use a local wrapper around Fumadocs selection and keyboard behavior: mixed panels keep their inset, single code fences fill the frame, and mobile tab lists scroll with 44px targets. SSO provider anchors use native explicit triggers with `aria-controls` matching their panel IDs; keyboard navigation, selection, and bookmarked activation remain native. The shared tab frame uses the actual header/TOC row offset when scrolling a bookmarked panel into view. The compact drawer uses 30px visible chip faces within 44px mobile touch targets, aligned full-width dividers, and the shared section order. TOC/header rows reserve their actual heights at mobile/tablet breakpoints; prose wraps without changing intentional code/table scrolling. API method badges use existing platform surface and text tokens instead of custom color overrides. Integration MDX content remains unchanged. The final pass removes the unused ActionMedia component and its local styling, three unused workflow-preview definitions/exports, and 111 local media files (15,187,771 bytes). Every removed asset belonged to an originally reviewed page and had no basename consumer in current repository source, including integrations and application code. Shared components and media with other consumers remain. Remote media was removed from pages only; no remote assets were deleted.
+
+FAQ answers were folded into their relevant sections. Callouts decreased from 234 to 117; authored Image/ActionImage and Video/ActionVideo instances decreased from 178 to 23. All 36 editorial placeholders were removed. These counts cover the 153 authored entries and exclude generated reference pages and integrations.
+
+## Page-by-page disposition
+
+Every row below represents a fully reviewed inventory entry. “Rewritten” includes organization/voice changes; “corrected” highlights an accuracy fix; “generated” means the owner was changed and the page regenerated; “retained” means reviewed copy already met its purpose. Shared API changes include sentence-case summaries, authentication labels, nonpaged bounds, response-unit/retention qualifications, neutral domain-error examples, valid request/response rendering, and sentence-case UI headings.
+
+### Workflow blocks (18)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [workflows/blocks/agent.mdx](content/docs/workflows/blocks/agent.mdx) | rewritten | Moved a valid structured-classification example before configuration and shortened the opening/description. Preserved provider discovery, Nebius/Jev, tools/skills, durable memory, retry recovery, fallback constraints, and the generated streaming region. Explained direct structured-output fields, malformed-JSON fallback, provider-specific schema enforcement, and supported forced-tool behavior. Replaced universal cache thresholds/discounts and free automatic-cache claims with model-specific primary documentation; described temperature/reasoning as task-dependent settings. Folded unique FAQ answers into provider/failure details and removed repeated best-practice prose. Named independent Include thinking and Include tool calls deployment policies, each requiring client protocol negotiation. Generated capability region preserved byte-for-byte. Retained estimated-cost qualification and specified USD input/output/total objects and .total reference; distinguished Logs UI/run-resource credits and linked Costs. Pi separately identifies possible sandbox cost. Qualified top-level structured fields: standard model/tokens/toolCalls/providerTiming/cost metadata overwrites same-named schema properties. | Verified improvement. Leads with actual structured classification, removes unconditional shape/forced-tool/cache/factuality guarantees, and qualifies native provider enforcement and malformed JSON. Documents metadata-name collisions and USD cost object versus run credits; independent streamed thinking/tool settings and current provider failure details are clearer. Preserved: All configuration, provider prefixes/discovery, Nebius/BYOK, complete Jev question example/answer shapes/limits, file input, dynamic Permission Mode values, skills, all memory windows, durable tool history/retrieval/summaries/retry recovery, fallback/key constraints and token controls remain. Both complete JSON Schemas, system message and classify preview were reviewed; generated model capability table is unchanged byte-for-byte from the requested baseline. Useful FAQ details moved into Provider and failure details. |
+| [workflows/blocks/api.mdx](content/docs/workflows/blocks/api.mdx) | rewritten | Organized purpose, fetch example, fields, advanced controls, outputs, and failure handling. Corrected non-2xx handling to the error port; normal status branches cover successful responses. Added credential forwarding on cross-origin redirects, body-encoding qualification, and the 10 MiB fetch-time cap. Preserved timeout/retry/backoff defaults, non-idempotent retry consequence, proxy guidance, and secret syntax. | Verified improvement. Replaces failed-status-on-normal-path guidance with error-port handling for non-2xx/network/timeout failures. Adds cross-origin credential redirect control, exact retry defaults/safety, proxy boundary, and fetch-time 10 MiB response cap. Preserved: Retains all HTTP methods/default GET, dynamic URL/query/header/body configuration, automatic header overrides, timeout 300,000/max600,000ms, backoff defaults500/30,000ms, idempotency caution, publicly reachable HTTP proxy tunnel, and successful data/status/headers. Fetch/summarize preview is preserved; Start now says User ID consistent with /users/<start.input>. All prior distinct FAQ details are folded into settings/failures. |
+| [workflows/blocks/condition.mdx](content/docs/workflows/blocks/condition.mdx) | rewritten | Led with ordered first-true routing and a priority example; separated fields, outputs, unmatched input, errors, and a score-gating example. Preserved expression operators, literal environment comparison behavior, safe string binding, else behavior, and selectedPath object shape. Made moderation schema numeric and replaced the undefined blocking helper in its preview with a real throwing Function. Folded model-score/tier examples and unique FAQ guidance into their relevant sections. | Verified improvement. Explains first true rule order, unsupported intent use case, skipped-block output and exact selectedPath/null behavior. Shows an actual priority branch and a structured numeric toxicity gate, with throwing-expression recovery and explicit no-match/end behavior. Preserved: Retains all three JavaScript tag expressions and all three secret literal comparisons, operators/string/array/math/Date support, safe secret binding versus Function string distinction, else/catch-all and optional chaining. Priority and moderation previews remain with correct if/else handles; onboarding-tier example technique remains in prose rather than a third duplicate preview. |
+| [workflows/blocks/credential.mdx](content/docs/workflows/blocks/credential.mdx) | rewritten | Reorganized all six workspace/organization OAuth/MCP operations under one configuration/output reference. Replaced cross-service Google credential reuse with compatible Slack actions; completed production/staging routing with Slack consumers. Preserved invitation email versus provider accountEmail, active-account filtering, exactly-one Find semantics, pagination, allowed-workspace/integration scope, and event delivery/legacy migration. Clarified credential IDs versus tokens and MCP connection IDs versus shared server configuration. Replaced the empty Google Ads loop screenshot with a written List → For Each → compatible action procedure. | Verified improvement. Replaces false cross-service Google-account reuse with compatible Slack references and per-action credential authorization/scopes. Orders a usable example before full OAuth/organization/MCP operations, access prerequisites, pagination, deleted credentials and trigger behavior. Preserved: Retains all six operations, invitation versus provider email, workspace/integration allowlisting, every required/optional field, limit100/max100 and cursor rules, exact-one Find, inactive exclusion, duplicates and all output fields. All three unique patterns remain: shared reference, conditional accounts, and paginated/list Loop. Accounts is explicitly named; managed connection versus shared mcpServerId, Function ID-only behavior, secret/service-account exclusions and legacy trigger replacement remain. |
+| [workflows/blocks/evaluator.mdx](content/docs/workflows/blocks/evaluator.mdx) | rewritten | Led with a quality-gate example, then metrics/content/model/fallbacks, outputs, and related docs. Clarified that unnamed metrics are skipped but missing ranges are not a reliable disable mechanism. Preserved named lowercase outputs, model/key configuration, fallback ordering and one-attempt behavior. Explained that requested ranges guide the model and are not general output clamps; removed generic rubric advice repeated elsewhere. Retained estimated-cost qualification and specified USD input/output/total objects and .total reference; distinguished Logs UI/run-resource credits and linked Costs. Pi separately identifies possible sandbox cost. Documented zero fallback for missing/unparseable scores and unguarded numeric coercion; require finite, in-range scores for consequential decisions. | Verified improvement. Corrects missing-range skip and enforced-in-range promises; distinguishes requested schema from post-response range/finite validation. Makes zero fallback/unparseable response and Number-to-NaN behavior visible, while retaining retries/fallback credentials and correct cost units. Preserved: Retains Accuracy/Clarity/Relevance rubric, 1–5 example, text/structured-data versus image/audio boundary, model/advanced settings, all output names, lowercase scores, comparative-metric consistency and quality-gate preview. All fallback ordering/key inheritance/Auto restrictions remain. Gate checks Accuracy>=4 and preserves alternative review path in task prose; no useful FAQ contract is silently dropped. |
+| [workflows/blocks/function.mdx](content/docs/workflows/blocks/function.mdx) | rewritten | Moved the API transformation example first, followed by runtime choice, code/secret syntax, outputs/files, sandbox lifecycle, Agent-tool secret access, distinct examples, large inputs, and errors. Preserved all JavaScript/Python/Shell return conventions, placeholder string/regex/heredoc rules, package catalog, sandbox dependency rules, build sharing/retry/install behavior, and large-value helpers. Carried the file-path remote-mount exception into the runtime table and local-runtime explanation; documented /tmp/sim/inputs and /tmp/sim/outputs and the special indexed .path reference. Separated outputPath/outputSandboxPath/outputTable as direct Function-tool controls rather than builder fields. Preserved secret-export refusal, masking/Unredacted boundaries, 20-file/50 MiB/11-directory caps, and the actual remaining-workflow timeout budget. Made input normalization and loyalty examples self-contained; converted ordinary runtime/build/helper callouts to prose and qualified Python plot capture. Qualified All secrets by the run resolved environment, identities, workspace access and secret grants; Selected secrets only narrows access, and new secrets require execution access. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. Documented the no-deadline Function fallback timeout, configurable local stdout truncation, and separate remote process-output versus file-export budgets. | Verified improvement. Moves runtime prerequisites ahead of code and separates builder outputs/fields from separate Function tool persistence controls. Adds bounded local stdout/remote combined process output and precise fallback/deadline timeout behavior; fixes loyalty inputs, normalized-write description, and mismatched reshape inspector. Preserved: Every code fence was read: JS/Python/Shell active-ID transform, secret expression/conversions/regex/heredoc, pandas mounted-file export, dependency/system lists, bq, one-off install, both full loyalty implementations and all lazy file-read calls. Retains local/remote/import/path distinctions, default/base package and CLI inventory, workspace sandbox authorization/build/runtime strategies/deletion/retry/restrictions, file20/50MiB/depth11 limits, exact secret/export boundaries, all-versus-selected secret tooling and large-input helper limitations. |
+| [workflows/blocks/guardrails.mdx](content/docs/workflows/blocks/guardrails.mdx) | rewritten | Moved valid-JSON gating first and completed its preview with parser and rejection branches. Corrected Mask PII passed=true behavior while retaining Block Request passed=false and the original-input exposure warning. Preserved one-check-per-block behavior, JSON syntax/schema distinction, grounding thresholds/chunk limits, outputs, language support, and regional/custom PII selection. Added RE2 unsupported lookaround/backreference behavior and distinguished the custom PII pattern engine. Removed duplicate FAQ, screenshot, and remote video explanations; retained distinct grounding/PII patterns. | Verified improvement. Corrects successful Mask semantics and independent output use; adds RE2 unsupported constructs, custom engine distinction, and model-grounding qualification. Preserves and extends regional identifiers in a compact current-catalog table and restores the useful Presidio primary documentation link. Preserved: Retains all four validation types, syntax-only JSON, complete email regex, grounding0–10/default3/no model/default5max20 chunks, synchronous latency, Common/all regional identifiers/language selection, outputs and all three workflow previews. New rows retain original NIF/NIE, Italian IDs, PESEL, NRIC/FIN, ABN/ACN/TFN/Medicare and all Indian IDs while adding current VAT/UEN/Finland. Original input remains distinct from maskedText, and detection-with-no-selected-types is qualified. |
+| [workflows/blocks/human-in-the-loop.mdx](content/docs/workflows/blocks/human-in-the-loop.mdx) | rewritten | Named the visible Human block and led with an actual Approval → Condition → publish/reject gate. Corrected single and two-stage previews so submitted approved=false cannot follow the action path. Used consistent named references, valid display JSON, configured metric names, and before/after submission outputs. Consolidated portal/notification/form instructions and replaced overlapping resume/execute tabs with synchronous and async v2 examples. Corrected v2 originally-streaming resumption to async202 JSON; preserved separate legacy endpoints, job receipts, pause-point lookup, selected-output and legacy SSE behavior. Retained no automatic response timeout, cancellation, multiple-pause and human-data-correction behavior. | Verified improvement. Replaces resume-equals-approval examples with explicit true/false gates in single and two-stage flows. Corrects originally-streaming v2 resume to202 JSON/background behavior, fixes named/display references and adds exact data.output.data._resume/contextId and data.runId access. Preserved: Retains complete Display Data, all notification channels/credentials/URL role, typed boolean/comments form, portal, full resumed run envelope/async receipt, all output fields and multi-stage/corrected-data use cases. Retains no automatic response timeout/cancel, pause-point GET/404, all legacy POST/job polling/SSE compatibility, selected-output auto-inclusion, repeated pauses and separate resume run IDs. Useful paused-envelope access fact is preserved explicitly rather than lost with duplicate tabs. |
+| [workflows/blocks/logs.mdx](content/docs/workflows/blocks/logs.mdx) | rewritten | Added a description and a Query IDs → For Each → Get Run Details minimum procedure. Added explicit output shapes/count, trigger filtering, advanced sorting, limits and cost/duration units. Preserved the protected log-facing projection and clarified retained logs versus every internal runtime value. Corrected Free retention to the scoped30-day default and linked effective workspace/organization policy; preserved billing-disabled self-hosted behavior. Added Logs to explicit blocks navigation metadata and converted normal projection explanation to prose. Final navigation gate: retained the existing Logs integration related-page link and omitted a duplicate Core blocks child; the reviewed reference URL and inbound links remain available. | Verified improvement. Turns operation tabs into a complete named Query→For Each→Get Run Details procedure and adds trigger/sort/count controls. Corrects seven-day retention promise to effective30-day default and protected log-facing projection rather than every internal value. Preserved: Retains workspace-only access, every Query filter/limit100max200, newest-first order, full detail metadata/trace/finalOutput fields, credits/ms units and Sim-event shortcut. Retention policy is linked to an owner that contains override/cleanup rules; run-time result remains distinguished from projected logs. |
+| [workflows/blocks/loop.mdx](content/docs/workflows/blocks/loop.mdx) | rewritten | Led with a named Process Reviews collection example and preserved all four type/setting behaviors. Corrected arithmetic updates to Function → Variables and the1000 value to a saved-execution default rather than a hard cap. Corrected completed-container references to normalized names and showed nested per-iteration output arrays. Preserved current index/item/items scope, missing versus empty collection behavior, unbounded conditional loops, execution budgets, nesting and error handling. Verified object collections yield [key,value] pairs in the collection resolver and documented indexed references. Removed stale full-builder screenshots whose useful scope/type information is now text. | Verified improvement. Corrects generic completed <loop.results>, unconditional1000 cap and unevaluated Variables arithmetic to named container results and Function→Variables. Explains nested result arrays, object key/value items, empty versus missing collection, conditional exit and execution budget. Preserved: Retains all four loop modes/check timing/fixed-count fallback, all item/index/items references, normalization, sequential work, nesting in both directions and every distinct API/variation/polling pattern. Full Process Reviews preview and both code/result examples reviewed; removed screenshots are covered by exact setting/type table, not replaced with unsupported images. |
+| [workflows/blocks/parallel.mdx](content/docs/workflows/blocks/parallel.mdx) | rewritten | Led with named Process Tasks example, bounded batches, and real aggregation code. Corrected isolated-variable and independent-unhandled-error guarantees; preserved own item/index/block outputs and ordered nested results. Preserved1–20/default20 batch control, serial batch behavior, global rate-limit caveat, indexed large-output hydration, nesting, and empty collections. Documented object [key,value] items and retained a concise Parallel/Loop comparison. Removed stale repetitive full-builder screenshots and folded FAQ into state/behavior sections. | Verified improvement. Corrects false variable-isolation and independent-error guarantees to shared variables and run-level unhandled failure. Clarifies batches, per-branch Wait versus global rate limit, nested ordered results and index hydration with a correctly typed API path. Preserved: Retains count/collection modes,1–20/default20 batch bound, serial batches beyond bound, index/item/items scope, input result order versus completion order, nesting/empty collection and model/API use cases. Full Process Tasks preview aggregation code and result references reviewed. Loop comparison remains, while unsupported no-shared-state advice is replaced with actual shared-state caution. |
+| [workflows/blocks/pi.mdx](content/docs/workflows/blocks/pi.mdx) | rewritten | Shortened title/description and added the missing Plan mode plus a registered Pi hero. Preserved mode-specific repository/model/search/BYOK/SSH controls and full Babysit permissions, trusted-data boundaries, pinning, partial outcomes and fixed bounds. Corrected Local Dev confinement: file paths are validated, shell commands run with SSH account permissions beyond the working directory. Extended sandbox key-exposure warnings to Plan/Create PR/Update PR and removed the exclusive Conversation/manual-model context claim. Preserved sandbox sizing/billing/lifetime/failover setup, memory exclusions, fork/protection limitations and reviewer controls; removed repeated generic best-practice/FAQ sections. Retained estimated-cost qualification and specified USD input/output/total objects and .total reference; distinguished Logs UI/run-resource credits and linked Costs. Pi separately identifies possible sandbox cost. | Verified improvement. Adds current Plan mode and minimum procedure, corrects SSH shell confinement and extends sandbox key exposure to every sandbox-model mode. Corrects current provider lifetime behavior (known versus unknown deadlines, override floor before run cap, absolute Daytona TTL/minute rounding) and qualifies independent provider/account bounds. Uses 8 GiB for repository memory allocation, links provider/account limits, and names the 24-hour E2B bound as Sim policy rather than a universal provider guarantee. Preserved: Retains all modes/settings/GitHub permissions, full Babysit pinned/trusted lifecycle, unsafe-data/key boundaries, bounds/partial outcomes/reviewer controls, SSH/tunnel/local constraints, search20 budget/provider key behavior, memory/context exclusion and all outputs. Sandbox template/build/compute/billing/orphan/normal teardown/failover facts remain; cost distinguishes USD total/sandbox costs from run credits; no unconditional Conversation/manual-model-only first-prompt safety guarantee remains. |
+| [workflows/blocks/response.mdx](content/docs/workflows/blocks/response.mdx) | rewritten | Led with a quoted JSON response example, fields, outputs/terminal behavior and branch-specific statuses. Qualified custom HTTP response control by API surface and preserved v2 envelope/HTTP contract distinction. Preserved Builder versus Editor fields, nested references, filtered headers, Content-Type/nosniff defaults, first-Response behavior and competing-branch side effects. Folded useful FAQ and removed duplicated webhook acknowledgement preview. | Verified improvement. Corrects universal HTTP-control claim with explicit v2 result/status/headers envelope boundary. Places first-Response termination and competing side effects prominently, with branch-specific response examples and webhook acknowledgement distinction. Preserved: Retains Builder/Editor modes, full nested tagged JSON, status200 and success/error choices, custom headers/default JSON/nosniff/filtering, first-exit/no downstream behavior and no-Response default result. Both distinct response previews remain; removed third webhook preview repeats the preserved acknowledgement fact. Full body and header examples reviewed. |
+| [workflows/blocks/router.mdx](content/docs/workflows/blocks/router.mdx) | rewritten | Led with semantic triage, then route/model/fallback configuration, outputs and unmatched errors. Preserved selectedPath destination shape, current and legacy fallback behavior and credential inheritance. Explained NO_MATCH raises an error and does not trigger fallback retries. Removed duplicate generic benefits/FAQ and kept a distinct current Workflow Inputs-mapping example. Documented the unconnected selectedPath placeholder with empty blockId, unknown blockType and chosen route title. Retained estimated-cost qualification and specified USD input/output/total objects and .total reference; distinguished Logs UI/run-resource credits and linked Costs. Pi separately identifies possible sandbox cost. | Verified improvement. Leads with intent routing and concrete routes, removes universal stronger-model guarantees, and makes NO_MATCH/error/fallback boundaries explicit. Adds actual unconnected selectedPath placeholder and USD cost fields; child-workflow example now uses current named Inputs block. Preserved: Retains context/title/description/model and local provider controls, all output fields plus token usage, fallback five/order/key/Auto behavior including legacy, no fixed route limit and route-specific connected ports. Triage/feedback previews remain; enterprise lead-routing technique remains in final prose. Unique FAQ matching/no-match facts are in explicit sections. |
+| [workflows/blocks/variables.mdx](content/docs/workflows/blocks/variables.mdx) | rewritten | Replaced unevaluated retry arithmetic with an actual Function increment plus Variables assignment and a While retry example. Preserved typed conversion, pre-resolved row references and assignment order. Clarified run-scoped shared namespace including Parallel branches, block-output references, initial values and normalization collisions. Kept a distinct fetched-configuration example and removed generic duplicate FAQ. | Verified improvement. Replaces arithmetic-in-assignment retry example with complete Function increment and ordered typed assignment. Explains pre-resolved references versus assignment order, shared Parallel namespace, normalized collisions and both variable/block outputs. Preserved: Retains prior initialization/per-run reset/global namespace, literals/references, each type conversion, multiple Variables overwrites, retry and stored-profile patterns. All retry nodes, branches, counter assignments and complete increment code reviewed; successful Attempt sets3 and error path increments until While false. Configuration preview reads <api.data.id/tier>. |
+| [workflows/blocks/wait.mdx](content/docs/workflows/blocks/wait.mdx) | rewritten | Led with request spacing, then units/mode/defaults, outputs and a delayed follow-up. Added the30-day async maximum and preserved5-minute inline maximum/default10. Clarified Async always suspends, scheduler timing is approximate, and self-hosted resumption needs the scheduler. Qualified cancelled status to interrupted inline waits and preserved execution/log duration distinction. | Verified improvement. Adds hard30-day async limit and exact always-suspend/scheduler behavior instead of exact resume-time implication. Qualifies cancellation output to inline waits and distinguishes wall-clock completion from execution/log timings and global rate limits. Preserved: Retains duration positive/default10, all mode-specific units, inline five-minute limit, status/waitDuration/resumeAt outputs and cancellation. Both two-second request-spacing and two-day follow-up previews remain; missing service tool configuration is explicitly required in prose. Self-hosted resume scheduler is linked. |
+| [workflows/blocks/webhook.mdx](content/docs/workflows/blocks/webhook.mdx) | rewritten | Distinguished outbound action from inbound Webhook trigger and led with a real formatting Function/Slack payload preview. Preserved full HMAC body/timestamp signature syntax, all automatic headers, custom override effects, and request-delivery ID scope. Preserved successful outputs and error-port behavior; corrected the conditional preview to the if handle. Kept the distinct conditional-notification pattern and moved method/retry advice near related API use. | Verified improvement. Clearly separates outbound POST from inbound trigger and provides a correctly formatted Slack text example. Explains exact HMAC/header overrides/delivery-ID scope and routes non-2xx failures through error handling; fixes conditional if handle. Preserved: Retains URL/payload/AI wand/signing/header controls, full nested JSON payload, all five automatic headers and exact timestamp.body HMAC syntax, successful data/status/headers, and API alternative for method/retry/proxy. Both notify and conditional external-process previews remain. The fixed Format Function produces Slack-required text and the branch runs only on the matching condition. |
+| [workflows/blocks/workflow.mdx](content/docs/workflows/blocks/workflow.mdx) | rewritten | Renamed the reference title to Workflow and led with a current mapped-input child-call example. Verified current workflow_input Inputs mapping versus hidden legacy workflow Input Variable and legacy tool-only Workflow Inputs; corrected heroes and shared previews to current workflow_input. Preserved same-workspace authorization, child credential context, output shapes, child failure/error ports, draft/deployed version and badge behavior. Preserved child-first deployment/redeployment consequences and25-hop call-chain rejection; removed stale screenshot and repetitive configure/use descriptions. | Verified improvement. Corrects current named Inputs mapping versus legacy Input Variable and prevents false parent-tool inheritance. Makes same-workspace authorization, child failure error port, draft/deployed badge difference, child-first update consequences and25-hop rejection explicit. Preserved: Retains wait-for-child/result/success/error/name/id outputs, same workspace, editor draft versus deployed child snapshot, selector self exclusion, badges/deploy/redeploy procedure and focused reuse. Full enrich-lead preview uses workflow_input, child Start input field and named Inputs mapping; previous screenshot instruction technique remains with current visible labels. |
+
+### API data operations (136)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| `listFiles` — `GET /api/v2/files` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Files → List files; sentence case matches the editorial guide. parameters[5].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[5].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listFiles, GET /api/v2/files, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createFile` — `POST /api/v2/files` | rewritten | Copy standardized; no operation-specific discrepancy found. Review correction: complete inline JSON is capped at 10 MiB; the decoded-file limit remains separate. | Verified improvement. Summary: Create File → Create file; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createFile, POST /api/v2/files, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createFileUpload` — `POST /api/v2/files/uploads` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create File Upload → Create file upload; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createFileUpload, POST /api/v2/files/uploads, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getFileUpload` — `GET /api/v2/files/uploads/{uploadId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get File Upload → Get file upload; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId getFileUpload, GET /api/v2/files/uploads/{uploadId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 2 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `abortFileUpload` — `DELETE /api/v2/files/uploads/{uploadId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Abort File Upload → Abort file upload; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId abortFileUpload, DELETE /api/v2/files/uploads/{uploadId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 2 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createFileUploadPartUrls` — `POST /api/v2/files/uploads/{uploadId}/parts` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create File Upload Part URLs → Create file upload part URLs; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createFileUploadPartUrls, POST /api/v2/files/uploads/{uploadId}/parts, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `completeFileUpload` — `POST /api/v2/files/uploads/{uploadId}/complete` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Complete File Upload → Complete file upload; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId completeFileUpload, POST /api/v2/files/uploads/{uploadId}/complete, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 2 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `readFileText` — `GET /api/v2/files/{fileId}/text` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Read File Text → Read file text; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId readFileText, GET /api/v2/files/{fileId}/text, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listFileVersions` — `GET /api/v2/files/{fileId}/versions` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List File Versions → List file versions; sentence case matches the editorial guide. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listFileVersions, GET /api/v2/files/{fileId}/versions, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getFileVersion` — `GET /api/v2/files/{fileId}/versions/{version}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get File Version → Get file version; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getFileVersion, GET /api/v2/files/{fileId}/versions/{version}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteFileVersion` — `DELETE /api/v2/files/{fileId}/versions/{version}` | corrected | "True when the version was removed. Stored-content deletion may finish through a background retry." Keep permanent history removal and current-version conflict, qualify immediate physical purge. | Verified improvement. Summary: Delete File Version → Delete file version; sentence case matches the editorial guide. description: Permanently delete one earlier version and its stored content, for example to purge a leaked value from history before retention removes it. The current version returns `409`; rev… → Permanently remove an earlier version from history and schedule deletion of its stored content. Storage cleanup may retry in the background. The current version returns `409`; rev… responses.200.content.application/json.schema.properties.data.properties.deleted.description: Always true: the version and its stored content are gone. → True when the version was removed from history. Stored-content deletion may finish through a background retry. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteFileVersion, DELETE /api/v2/files/{fileId}/versions/{version}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `readFileVersionText` — `GET /api/v2/files/{fileId}/versions/{version}/text` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Read File Version Text → Read file version text; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId readFileVersionText, GET /api/v2/files/{fileId}/versions/{version}/text, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `downloadFileVersion` — `GET /api/v2/files/{fileId}/versions/{version}/content` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Download File Version → Download file version; sentence case matches the editorial guide. description: Download the bytes of one version, served exactly as Download File serves the current bytes. Generated documents use compiled artifacts, returning `409` while compiling and `413` … → Download the bytes of one version, served exactly as Download file serves the current bytes. Generated documents use compiled artifacts, returning `409` while compiling and `413` … responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId downloadFileVersion, GET /api/v2/files/{fileId}/versions/{version}/content, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `revertFileVersion` — `POST /api/v2/files/{fileId}/versions/{version}/revert` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Revert File Version → Revert file version; sentence case matches the editorial guide. description: Make the content of a version current again by writing it as a new `revert` version, so the revert can itself be reverted. Open editors receive the change. Reverting to the curren… → Make the content of a version current again by writing it as a new `revert` version, so the revert can itself be reverted. Open editors receive the change. Reverting to the curren… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId revertFileVersion, POST /api/v2/files/{fileId}/versions/{version}/revert, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `bulkDownloadFiles` — `GET /api/v2/files/bulk-download` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Bulk Download Files → Bulk download files; sentence case matches the editorial guide. description: Stream selected files and recursive folder contents as a ZIP archive. Each selection parameter and the resolved set allow 100 entries; unmatched paths or excess entries return `40… → Stream selected files and recursive folder contents as a ZIP archive. Each selection parameter and the resolved set allow 100 entries; unmatched paths or excess entries return `40… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId bulkDownloadFiles, GET /api/v2/files/bulk-download, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `unzipFile` — `POST /api/v2/files/{fileId}/unzip` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Unzip File → Unzip file; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId unzipFile, POST /api/v2/files/{fileId}/unzip, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `downloadFile` — `GET /api/v2/files/{fileId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Download File → Download file; sentence case matches the editorial guide. description: Download current file bytes. Generated documents use compiled artifacts, returning `409` while compiling and `413` above the rendered-size ceiling. Downloading records an audit ev… → Download current file bytes. Generated documents use compiled artifacts, returning `409` while compiling and `413` above the rendered-size ceiling. Downloading records an audit ev… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId downloadFile, GET /api/v2/files/{fileId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteFile` — `DELETE /api/v2/files/{fileId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Delete File → Delete file; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteFile, DELETE /api/v2/files/{fileId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `renameFile` — `PATCH /api/v2/files/{fileId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Rename File → Rename file; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId renameFile, PATCH /api/v2/files/{fileId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `restoreFile` — `POST /api/v2/files/{fileId}/restore` | corrected | "The restored file, with its resulting folderPath and name." Keep the accurate operation-level original-folder/root fallback and collision explanation. | Verified improvement. Summary: Restore File → Restore file; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: The restored workspace file, at the root and under its post-restore name. → The restored file, with its resulting folderPath and name. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId restoreFile, POST /api/v2/files/{fileId}/restore, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getFile` — `GET /api/v2/files/{fileId}/metadata` | corrected | "Current version number. Pass as expectedCurrentVersion to require this version still be current. Use expectedRevision to detect edits folded into the same version." | Verified improvement. Summary: Get File Metadata → Get file metadata; sentence case matches the editorial guide. responses.200.content.application/json.schema.properties.data.properties.currentVersion.description: Version number of the current content. List File Versions returns the history; pass this as `expectedCurrentVersion` to revert only if nothing changed since. → Current version number. List file versions returns the history. Pass this as `expectedCurrentVersion` to require that version to remain current; use `expectedRevision` to detect e… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getFile, GET /api/v2/files/{fileId}/metadata, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listAuditLogs` — `GET /api/v2/audit-logs` | corrected | Override inherited descriptions to "Include audit entries created at or after/before this UTC ISO 8601 timestamp." Preserve UTC/Z and year-zero validation details. | Verified improvement. Summary: List Audit Logs → List audit logs; sentence case matches the editorial guide. parameters[4].description: Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is reje… → Include audit entries created at or after this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `00… parameters[4].schema.description: Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is reje… → Include audit entries created at or after this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `00… parameters[5].description: Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rej… → Include audit entries created at or before this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0… 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listAuditLogs, GET /api/v2/audit-logs, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getAuditLog` — `GET /api/v2/audit-logs/{auditLogId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Audit Log → Get audit log; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getAuditLog, GET /api/v2/audit-logs/{auditLogId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `moveFileItems` — `POST /api/v2/files/move` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Move Files → Move files; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId moveFileItems, POST /api/v2/files/move, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getFileShare` — `GET /api/v2/files/{fileId}/share` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get File Share → Get file share; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getFileShare, GET /api/v2/files/{fileId}/share, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `upsertFileShare` — `PATCH /api/v2/files/{fileId}/share` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Enable or Disable File Share → Enable or disable file share; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId upsertFileShare, PATCH /api/v2/files/{fileId}/share, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `editFileContent` — `PATCH /api/v2/files/{fileId}/content` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Edit File Content → Edit file content; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId editFileContent, PATCH /api/v2/files/{fileId}/content, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateFileContent` — `PUT /api/v2/files/{fileId}/content` | rewritten | Copy standardized; no operation-specific discrepancy found. Review correction: complete replacement JSON is capped at 10 MiB; a small patch can edit a larger stored file. | Verified improvement. Summary: Replace File Content → Replace file content; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateFileContent, PUT /api/v2/files/{fileId}/content, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `searchFileContent` — `GET /api/v2/files/search` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Search File Content → Search file content; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId searchFileContent, GET /api/v2/files/search, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `bulkDeleteFiles` — `POST /api/v2/files/bulk-delete` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Delete Files → Delete files; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId bulkDeleteFiles, POST /api/v2/files/bulk-delete, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listFilesFolders` — `GET /api/v2/files/folders` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Folders → List folders; sentence case matches the editorial guide. description: List workspace file folders with parent-path filtering and sorting. Use `scope=archived` to find paths accepted by Restore Folder. Returns the complete set in one page; `nextCurso… → List workspace file folders with parent-path filtering and sorting. Use `scope=archived` to find paths accepted by Restore folder. Returns one page; `nextCursor` is always null. O… parameters[3].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[3].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Preserved: Compared operationId listFilesFolders, GET /api/v2/files/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createFilesFolder` — `POST /api/v2/files/folders` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Folder → Create folder; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createFilesFolder, POST /api/v2/files/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `relocateFilesFolder` — `PATCH /api/v2/files/folders` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Rename or Move Folder → Rename or move folder; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId relocateFilesFolder, PATCH /api/v2/files/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteFilesFolder` — `DELETE /api/v2/files/folders` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Delete Folder → Delete folder; sentence case matches the editorial guide. parameters[2].description: Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are ca… → Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted. parameters[2].schema.description: Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are ca… → Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteFilesFolder, DELETE /api/v2/files/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `restoreFilesFolder` — `POST /api/v2/files/folders/restore` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Restore Folder → Restore folder; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId restoreFilesFolder, POST /api/v2/files/folders/restore, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listKnowledgeBases` — `GET /api/v2/knowledge` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Knowledge Bases → List knowledge bases; sentence case matches the editorial guide. parameters[4].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[4].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. responses.200.content.application/json.schema.properties.data.items.properties.chunkingConfig.properties.overlap.description: Number of overlapping characters between adjacent chunks. → Requested overlap in tokens between adjacent chunks. Preserved: Compared operationId listKnowledgeBases, GET /api/v2/knowledge, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createKnowledgeBase` — `POST /api/v2/knowledge` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. Root corrected inherited chunk-overlap input unit to tokens, preserving schema/default behavior. | Verified improvement. Summary: Create Knowledge Base → Create knowledge base; sentence case matches the editorial guide. requestBody.content.application/json.schema.properties.chunkingConfig.properties.overlap.description: Number of overlapping characters between adjacent chunks. → Requested overlap in tokens between adjacent chunks. responses.201.content.application/json.schema.properties.data.properties.chunkingConfig.properties.overlap.description: Number of overlapping characters between adjacent chunks. → Requested overlap in tokens between adjacent chunks. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createKnowledgeBase, POST /api/v2/knowledge, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getKnowledgeBase` — `GET /api/v2/knowledge/{knowledgeBaseId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Knowledge Base → Get knowledge base; sentence case matches the editorial guide. responses.200.content.application/json.schema.properties.data.properties.chunkingConfig.properties.overlap.description: Number of overlapping characters between adjacent chunks. → Requested overlap in tokens between adjacent chunks. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId getKnowledgeBase, GET /api/v2/knowledge/{knowledgeBaseId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateKnowledgeBase` — `PATCH /api/v2/knowledge/{knowledgeBaseId}` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. Root corrected inherited chunk-overlap input unit to tokens, preserving schema/default behavior. | Verified improvement. Summary: Update Knowledge Base → Update knowledge base; sentence case matches the editorial guide. requestBody.content.application/json.schema.properties.chunkingConfig.properties.overlap.description: Number of overlapping characters between adjacent chunks. → Requested overlap in tokens between adjacent chunks. responses.200.content.application/json.schema.properties.data.properties.chunkingConfig.properties.overlap.description: Number of overlapping characters between adjacent chunks. → Requested overlap in tokens between adjacent chunks. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateKnowledgeBase, PATCH /api/v2/knowledge/{knowledgeBaseId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteKnowledgeBase` — `DELETE /api/v2/knowledge/{knowledgeBaseId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Delete Knowledge Base → Delete knowledge base; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteKnowledgeBase, DELETE /api/v2/knowledge/{knowledgeBaseId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `exportKnowledgeBase` — `GET /api/v2/knowledge/{knowledgeBaseId}/export` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Export Knowledge Base → Export knowledge base; sentence case matches the editorial guide. description: Stream a knowledge base as a bundle archive: its configuration, tag definitions, each workspace-visible document's file and chunk text, and optionally chunk vectors. Access-contro… → Stream a knowledge base as a bundle archive: its configuration, tag definitions, each workspace-visible document's file and chunk text, and optionally chunk vectors. Access-contro… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId exportKnowledgeBase, GET /api/v2/knowledge/{knowledgeBaseId}/export, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listKnowledgeConnectors` — `GET /api/v2/knowledge/{knowledgeBaseId}/connectors` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Knowledge Connectors → List knowledge connectors; sentence case matches the editorial guide. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listKnowledgeConnectors, GET /api/v2/knowledge/{knowledgeBaseId}/connectors, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createKnowledgeConnector` — `POST /api/v2/knowledge/{knowledgeBaseId}/connectors` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Create Knowledge Connector → Create knowledge connector; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createKnowledgeConnector, POST /api/v2/knowledge/{knowledgeBaseId}/connectors, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getKnowledgeConnector` — `GET /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Knowledge Connector → Get knowledge connector; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getKnowledgeConnector, GET /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateKnowledgeConnector` — `PATCH /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. Review correction: the paused request has a paused response example with separate operation-specific metadata. | Verified improvement. Summary: Update Knowledge Connector → Update knowledge connector; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateKnowledgeConnector, PATCH /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteKnowledgeConnector` — `DELETE /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Delete Knowledge Connector → Delete knowledge connector; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteKnowledgeConnector, DELETE /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `syncKnowledgeConnector` — `POST /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/sync` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Sync Knowledge Connector → Sync knowledge connector; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId syncKnowledgeConnector, POST /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/sync, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listKnowledgeConnectorDocuments` — `GET /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/documents` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Knowledge Connector Documents → List knowledge connector documents; sentence case matches the editorial guide. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listKnowledgeConnectorDocuments, GET /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/documents, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateKnowledgeConnectorDocuments` — `PATCH /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/documents` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Update Knowledge Connector Documents → Update knowledge connector documents; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateKnowledgeConnectorDocuments, PATCH /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/documents, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `searchKnowledge` — `POST /api/v2/knowledge/search` | corrected | "If reranking is unavailable, results keep their retrieval order and have no rerankerScore." Preserve best-effort status and billing details. Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. Add "For a query search, all selected bases must use the same embedding model and dimensions; search incompatible bases separately. Tag-only search does not require this." Describe omitted searchMode as workspace policy; avoid claiming a universal vector default. | Verified improvement. Summary: Search Knowledge → Search knowledge; sentence case matches the editorial guide. requestBody.content.application/json.schema.properties.knowledgeBaseIds.description: One knowledge base identifier or an array of up to 20 identifiers. → One knowledge base ID or an array of up to 20 IDs. Query searches require the same embedding model and dimensions across all selected bases; search incompatible bases separately. … requestBody.content.application/json.schema.properties.rerankerEnabled.description: Re-order retrieved chunks with a reranking model before truncating to `topK`. Ignored for a tag-only search, and billed as an additional search unit. Reranking is best-effort — a … → Reorder retrieved chunks with a reranking model before truncating to `topK`. Ignored for tag-only searches. A completed reranking call adds a search unit. If reranking is unavaila… requestBody.content.application/json.schema.properties.searchMode.description: Retrieval strategy: vector is semantic-only, while hybrid also runs full-text search. → Retrieval strategy: `vector` uses semantic search; `hybrid` also runs full-text search. Omit to use the workspace policy. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId searchKnowledge, POST /api/v2/knowledge/search, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listKnowledgeTags` — `GET /api/v2/knowledge/{knowledgeBaseId}/tags` | corrected | "Slot used by document updates: tag1–tag7, number1–number5, date1–date2, or boolean1–boolean3. Upload creation accepts text slots; use Update Document for other types." Keep display-name/slot distinction. | Verified improvement. Summary: List Tags → List tags; sentence case matches the editorial guide. description: List the knowledge base's tag definitions with display names, write slots, and field types. Filters and document reads use display names; document writes use slots. Returns the co… → List the knowledge base's tag definitions with display names, write slots, and field types. Filters and document reads use display names; document writes use slots. Returns one pa… responses.200.content.application/json.schema.properties.data.items.properties.tagSlot.description: Storage slot the tag occupies. Document writes set tag values by slot (`tag1`..`tag7`). → Slot used by document updates: `tag1`–`tag7`, `number1`–`number5`, `date1`–`date2`, or `boolean1`–`boolean3`. Upload creation accepts text slots; use Update document for other typ… responses.200.content.application/json.schema.properties.nextCursor.description: Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change. → Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits. Preserved: Compared operationId listKnowledgeTags, GET /api/v2/knowledge/{knowledgeBaseId}/tags, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createKnowledgeTag` — `POST /api/v2/knowledge/{knowledgeBaseId}/tags` | corrected | "Slot used by document updates: tag1–tag7, number1–number5, date1–date2, or boolean1–boolean3. Upload creation accepts text slots; use Update Document for other types." Keep display-name/slot distinction. Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Create Tag → Create tag; sentence case matches the editorial guide. responses.201.content.application/json.schema.properties.data.properties.tagSlot.description: Storage slot the tag occupies. Document writes set tag values by slot (`tag1`..`tag7`). → Slot used by document updates: `tag1`–`tag7`, `number1`–`number5`, `date1`–`date2`, or `boolean1`–`boolean3`. Upload creation accepts text slots; use Update document for other typ… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createKnowledgeTag, POST /api/v2/knowledge/{knowledgeBaseId}/tags, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `bulkSaveKnowledgeTagDefinitions` — `PUT /api/v2/knowledge/{knowledgeBaseId}/tags` | corrected | "Slot used by document updates: tag1–tag7, number1–number5, date1–date2, or boolean1–boolean3. Upload creation accepts text slots; use Update Document for other types." Keep display-name/slot distinction. | Verified improvement. Summary: Bulk Save Tag Definitions → Bulk save tag definitions; sentence case matches the editorial guide. responses.200.content.application/json.schema.properties.data.properties.created.items.properties.tagSlot.description: Storage slot the tag occupies. Document writes set tag values by slot (`tag1`..`tag7`). → Slot used by document updates: `tag1`–`tag7`, `number1`–`number5`, `date1`–`date2`, or `boolean1`–`boolean3`. Upload creation accepts text slots; use Update document for other typ… responses.200.content.application/json.schema.properties.data.properties.updated.items.properties.tagSlot.description: Storage slot the tag occupies. Document writes set tag values by slot (`tag1`..`tag7`). → Slot used by document updates: `tag1`–`tag7`, `number1`–`number5`, `date1`–`date2`, or `boolean1`–`boolean3`. Upload creation accepts text slots; use Update document for other typ… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId bulkSaveKnowledgeTagDefinitions, PUT /api/v2/knowledge/{knowledgeBaseId}/tags, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteKnowledgeTagDefinitions` — `DELETE /api/v2/knowledge/{knowledgeBaseId}/tags` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Delete Tag Definitions → Delete tag definitions; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteKnowledgeTagDefinitions, DELETE /api/v2/knowledge/{knowledgeBaseId}/tags, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listKnowledgeDocuments` — `GET /api/v2/knowledge/{knowledgeBaseId}/documents` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Documents → List documents; sentence case matches the editorial guide. parameters[5].description: Field used to sort the result. Sorting by `filename` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `filename`. parameters[5].schema.description: Field used to sort the result. Sorting by `filename` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `filename`. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. Preserved: Compared operationId listKnowledgeDocuments, GET /api/v2/knowledge/{knowledgeBaseId}/documents, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `bulkUpdateKnowledgeDocuments` — `PATCH /api/v2/knowledge/{knowledgeBaseId}/documents` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Bulk Enable or Disable Documents → Bulk enable or disable documents; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId bulkUpdateKnowledgeDocuments, PATCH /api/v2/knowledge/{knowledgeBaseId}/documents, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `uploadKnowledgeDocument` — `POST /api/v2/knowledge/{knowledgeBaseId}/documents` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Upload Document → Upload document; sentence case matches the editorial guide. requestBody.content.multipart/form-data.schema.properties.file.description: Document file to upload; the maximum size is 100 MB. → Document file to upload; the maximum size is 100 MiB. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId uploadKnowledgeDocument, POST /api/v2/knowledge/{knowledgeBaseId}/documents, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createKnowledgeDocumentUpload` — `POST /api/v2/knowledge/{knowledgeBaseId}/documents/uploads` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Document Upload → Create document upload; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createKnowledgeDocumentUpload, POST /api/v2/knowledge/{knowledgeBaseId}/documents/uploads, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `abortKnowledgeDocumentUpload` — `DELETE /api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Abort Document Upload → Abort document upload; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId abortKnowledgeDocumentUpload, DELETE /api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createKnowledgeDocumentUploadPartUrls` — `POST /api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}/parts` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Create Document Upload Part URLs → Create document upload part URLs; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createKnowledgeDocumentUploadPartUrls, POST /api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}/parts, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `completeKnowledgeDocumentUpload` — `POST /api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}/complete` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Complete Document Upload → Complete document upload; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId completeKnowledgeDocumentUpload, POST /api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}/complete, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getKnowledgeDocument` — `GET /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Document → Get document; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId getKnowledgeDocument, GET /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateKnowledgeDocument` — `PATCH /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Update Document → Update document; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateKnowledgeDocument, PATCH /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteKnowledgeDocument` — `DELETE /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Delete Document → Delete document; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteKnowledgeDocument, DELETE /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 2 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listKnowledgeFolders` — `GET /api/v2/knowledge/folders` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Folders → List folders; sentence case matches the editorial guide. description: List folders in the knowledge-base folder tree with filtering and sorting. Returns the complete set in one page; `nextCursor` is always null. Workspace folder trees exceeding 10,0… → List folders in the knowledge-base folder tree with filtering and sorting. Returns one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000 folders return `4… parameters[3].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[3].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Preserved: Compared operationId listKnowledgeFolders, GET /api/v2/knowledge/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createKnowledgeFolder` — `POST /api/v2/knowledge/folders` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Create Folder → Create folder; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createKnowledgeFolder, POST /api/v2/knowledge/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `relocateKnowledgeFolder` — `PATCH /api/v2/knowledge/folders` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Rename or Move Folder → Rename or move folder; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId relocateKnowledgeFolder, PATCH /api/v2/knowledge/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteKnowledgeFolder` — `DELETE /api/v2/knowledge/folders` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Delete Folder → Delete folder; sentence case matches the editorial guide. parameters[2].description: Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are ca… → Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted. parameters[2].schema.description: Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are ca… → Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteKnowledgeFolder, DELETE /api/v2/knowledge/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `restoreKnowledgeBase` — `POST /api/v2/knowledge/{knowledgeBaseId}/restore` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Restore Knowledge Base → Restore knowledge base; sentence case matches the editorial guide. responses.200.content.application/json.schema.properties.data.properties.chunkingConfig.properties.overlap.description: Number of overlapping characters between adjacent chunks. → Requested overlap in tokens between adjacent chunks. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId restoreKnowledgeBase, POST /api/v2/knowledge/{knowledgeBaseId}/restore, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `addWorkspaceFilesToKnowledgeBase` — `POST /api/v2/knowledge/{knowledgeBaseId}/documents/from-workspace-files` | corrected | "Workspace file IDs or file paths to index. Prefer IDs or canonical files/<folder>/<name> paths. Duplicates resolving to one file are indexed once." handbook.pdf example is a valid name reference; an ID example would be less ambiguous. Used MiB for verified power-of-1024 byte limits in scoped prose. | Verified improvement. Summary: Index Workspace Files → Index workspace files; sentence case matches the editorial guide. description: Queue stored workspace files for indexing without re-uploading bytes. Unreadable, unsupported, or over-100 MB files appear in `failed`; valid files are queued. Partial success ret… → Queue stored workspace files for indexing without re-uploading bytes. Unreadable, unsupported, or over-100 MiB files appear in `failed`; valid files are queued. Partial success re… requestBody.content.application/json.schema.properties.fileReferences.description: Workspace file identifiers or storage keys to index. Duplicates resolving to the same file are indexed once. → Workspace file IDs or paths to index. Prefer IDs or canonical `files/<folder>/<name>` paths. Duplicates resolving to the same file are indexed once. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId addWorkspaceFilesToKnowledgeBase, POST /api/v2/knowledge/{knowledgeBaseId}/documents/from-workspace-files, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listKnowledgeChunks` — `GET /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: List Chunks → List chunks; sentence case matches the editorial guide. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId listKnowledgeChunks, GET /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createKnowledgeChunk` — `POST /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks` | corrected | "Embed the chunk before returning. It appears in search when the chunk and its document are enabled and the document has completed processing." Preserve connector-managed read-only restriction. | Verified improvement. Summary: Create Chunk → Create chunk; sentence case matches the editorial guide. description: Append a chunk, embedding it before the response so it is immediately searchable. It inherits the document's tags and next `chunkIndex`. Connector-synced chunks are read-only and … → Append a chunk and embed it before returning. It inherits the document's tags and next `chunkIndex`. Search includes it when the chunk and document are enabled and the document ha… requestBody.content.application/json.schema.properties.content.description: Text to embed. It is embedded on write, so the chunk is searchable immediately. → Text embedded before the response. Search includes it when the chunk and document are enabled and the document has completed processing. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createKnowledgeChunk, POST /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `bulkUpdateKnowledgeChunks` — `PATCH /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Bulk Update Chunks → Bulk update chunks; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId bulkUpdateKnowledgeChunks, PATCH /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getKnowledgeChunk` — `GET /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Get Chunk → Get chunk; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId getKnowledgeChunk, GET /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateKnowledgeChunk` — `PATCH /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Update Chunk → Update chunk; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateKnowledgeChunk, PATCH /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteKnowledgeChunk` — `DELETE /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Delete Chunk → Delete chunk; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteKnowledgeChunk, DELETE /api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateKnowledgeTag` — `PATCH /api/v2/knowledge/{knowledgeBaseId}/tags/{tagId}` | corrected | "Slot used by document updates: tag1–tag7, number1–number5, date1–date2, or boolean1–boolean3. Upload creation accepts text slots; use Update Document for other types." Keep display-name/slot distinction. Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Update Tag → Update tag; sentence case matches the editorial guide. responses.200.content.application/json.schema.properties.data.properties.tagSlot.description: Storage slot the tag occupies. Document writes set tag values by slot (`tag1`..`tag7`). → Slot used by document updates: `tag1`–`tag7`, `number1`–`number5`, `date1`–`date2`, or `boolean1`–`boolean3`. Upload creation accepts text slots; use Update document for other typ… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateKnowledgeTag, PATCH /api/v2/knowledge/{knowledgeBaseId}/tags/{tagId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteKnowledgeTag` — `DELETE /api/v2/knowledge/{knowledgeBaseId}/tags/{tagId}` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Delete Tag → Delete tag; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteKnowledgeTag, DELETE /api/v2/knowledge/{knowledgeBaseId}/tags/{tagId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getNextKnowledgeTagSlot` — `GET /api/v2/knowledge/{knowledgeBaseId}/tags/next-slot` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Next Tag Slot → Get next tag slot; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId getNextKnowledgeTagSlot, GET /api/v2/knowledge/{knowledgeBaseId}/tags/next-slot, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listKnowledgeTagUsage` — `GET /api/v2/knowledge/{knowledgeBaseId}/tags/usage` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Tag Usage → List tag usage; sentence case matches the editorial guide. description: Count the documents and chunks with a value for each defined tag. Returns the complete set in one page; `nextCursor` is always null. Workspace API keys return `403`; use a persona… → Count the documents and chunks with a value for each defined tag. Returns one page; `nextCursor` is always null. Workspace API keys return `403`; use a personal API key or scoped … responses.200.content.application/json.schema.properties.nextCursor.description: Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change. → Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId listKnowledgeTagUsage, GET /api/v2/knowledge/{knowledgeBaseId}/tags/usage, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listLogs` — `GET /api/v2/logs` | corrected | Use USD 0.005 fixed + USD 0.0022 model = USD 0.0072 in the detail example and matching list total. Logs USD response contracts remain unchanged; Billing/run-resource credit units are separate. | Verified improvement. Summary: List Logs → List logs; sentence case matches the editorial guide. description: List logs with filters, selectable detail, sorting, and cursor pagination. `includeJobRuns=true` includes chat and Sim-agent jobs only with `sortBy=startedAt`, because other order… → List logs with filters, selectable detail, sorting, and cursor pagination. `includeJobRuns=true` includes chat and Sim-agent jobs only with `sortBy=startedAt`, because other order… responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listLogs, GET /api/v2/logs, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. Logs remain USD. Illustrative run list/detail totals agree: 0.005 fixed + 0.0022 model = 0.0072 USD. |
+| `getLog` — `GET /api/v2/logs/{runId}` | corrected | Use USD 0.005 fixed + USD 0.0022 model = USD 0.0072 in the detail example and matching list total. Logs USD response contracts remain unchanged; Billing/run-resource credit units are separate. Review correction: list and detail examples agree on the run output file. | Verified improvement. Summary: Get Log → Get log; sentence case matches the editorial guide. description: Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty `traceSpans` array does not prove none were recorded. Expired runs are … → Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty `traceSpans` array does not prove none were recorded. Expired runs are … responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getLog, GET /api/v2/logs/{runId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. Logs remain USD. Illustrative run list/detail totals agree: 0.005 fixed + 0.0022 model = 0.0072 USD. |
+| `getLogStats` — `GET /api/v2/logs/stats` | corrected | Publish the input default as string "false" in OpenAPI metadata, while retaining the runtime boolean default. Do not change accepted inputs or runtime behavior. | Verified improvement. Summary: Get Log Statistics → Get log statistics; sentence case matches the editorial guide. description: Get bucketed run counts, success rate, errors, and mean latency for the workspace and individual workflows. Query fields describe window selection and bucketing. Folder filters co… → Get bucketed run counts, success rate, errors, and mean latency for the workspace and individual workflows. Query fields describe window selection and bucketing. Folder filters co… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getLogStats, GET /api/v2/logs/stats, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. includeEmpty advertises string "false" to match its string vocabulary; canonical runtime transform/default remains false. |
+| `listTables` — `GET /api/v2/tables` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Tables → List tables; sentence case matches the editorial guide. parameters[4].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[4].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. Preserved: Compared operationId listTables, GET /api/v2/tables, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createTable` — `POST /api/v2/tables` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Table → Create table; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createTable, POST /api/v2/tables, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getTable` — `GET /api/v2/tables/{tableId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Table → Get table; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId getTable, GET /api/v2/tables/{tableId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 2 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteTable` — `DELETE /api/v2/tables/{tableId}` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Delete Table → Delete table; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteTable, DELETE /api/v2/tables/{tableId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateTable` — `PATCH /api/v2/tables/{tableId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Update Table → Update table; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateTable, PATCH /api/v2/tables/{tableId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `addTableColumn` — `POST /api/v2/tables/{tableId}/columns` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Add Column → Add column; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId addTableColumn, POST /api/v2/tables/{tableId}/columns, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateTableColumn` — `PATCH /api/v2/tables/{tableId}/columns` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Update Column → Update column; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateTableColumn, PATCH /api/v2/tables/{tableId}/columns, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteTableColumn` — `DELETE /api/v2/tables/{tableId}/columns` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Delete Column → Delete column; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteTableColumn, DELETE /api/v2/tables/{tableId}/columns, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listTableRows` — `GET /api/v2/tables/{tableId}/rows` | corrected | Add PayloadTooLarge to these operations and explain the 2 MiB run-state ceiling on includeRunState / row-group detail. Replace internal "sidecar/blockErrors are unbounded" rationale with the user consequence and retry action. Used MiB for verified power-of-1024 byte limits in scoped prose. | Verified improvement. Summary: List Rows → List rows; sentence case matches the editorial guide. description: List rows in default order with cursor pagination. Pages default to a 5 MB limit and may contain fewer rows than requested; continue until `nextCursor` is null. Use Query Rows for… → List rows in default order with cursor pagination. Pages default to a 5 MiB limit and may contain fewer rows than requested; continue until `nextCursor` is null. Use Query rows fo… parameters[4].description: Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it onl… → Include per-workflow-group run outcomes on every row. Off by default. Caps `limit` at 200. Run state above 2 MiB returns `413`; request fewer rows or omit run state. parameters[4].schema.description: Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it onl… → Include per-workflow-group run outcomes on every row. Off by default. Caps `limit` at 200. Run state above 2 MiB returns `413`; request fewer rows or omit run state. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listTableRows, GET /api/v2/tables/{tableId}/rows, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 19 distinct changed field mappings were inspected for this operation. Only newly documented 413 response differs in operation structure; the existing 2 MiB run-state refusal is documented without route or schema behavior changes. |
+| `createTableRows` — `POST /api/v2/tables/{tableId}/rows` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Create Rows → Create rows; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createTableRows, POST /api/v2/tables/{tableId}/rows, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateTableRows` — `PATCH /api/v2/tables/{tableId}/rows` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Update Rows by Filter → Update rows by filter; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateTableRows, PATCH /api/v2/tables/{tableId}/rows, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteTableRows` — `DELETE /api/v2/tables/{tableId}/rows` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Delete Rows → Delete rows; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteTableRows, DELETE /api/v2/tables/{tableId}/rows, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getTableRow` — `GET /api/v2/tables/{tableId}/rows/{rowId}` | corrected | Add PayloadTooLarge to these operations and explain the 2 MiB run-state ceiling on includeRunState / row-group detail. Replace internal "sidecar/blockErrors are unbounded" rationale with the user consequence and retry action. | Verified improvement. Summary: Get Row → Get row; sentence case matches the editorial guide. parameters[3].description: Include per-workflow-group run state on the returned row. Off by default. → Include per-workflow-group run outcomes on the row. Off by default. Run state above 2 MiB returns `413`; omit this option to read the row without run state. parameters[3].schema.description: Include per-workflow-group run state on the returned row. Off by default. → Include per-workflow-group run outcomes on the row. Off by default. Run state above 2 MiB returns `413`; omit this option to read the row without run state. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getTableRow, GET /api/v2/tables/{tableId}/rows/{rowId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 17 distinct changed field mappings were inspected for this operation. Only newly documented 413 response differs in operation structure; the existing 2 MiB run-state refusal is documented without route or schema behavior changes. |
+| `updateTableRow` — `PATCH /api/v2/tables/{tableId}/rows/{rowId}` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Update Row → Update row; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateTableRow, PATCH /api/v2/tables/{tableId}/rows/{rowId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteTableRow` — `DELETE /api/v2/tables/{tableId}/rows/{rowId}` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Delete Row → Delete row; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteTableRow, DELETE /api/v2/tables/{tableId}/rows/{rowId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `upsertTableRow` — `POST /api/v2/tables/{tableId}/rows/upsert` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Upsert Row → Upsert row; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId upsertTableRow, POST /api/v2/tables/{tableId}/rows/upsert, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `queryTableRows` — `POST /api/v2/tables/{tableId}/query` | corrected | "0 requests all matches, subject to the 5 MiB row-data ceiling; larger results return 400 with TABLE_QUERY_RESULT_TOO_LARGE. Use paged queries or an export." Keep includeRunState incompatibility. Distinguish fixed whole-result ceiling from configurable bounded-page default. Used MiB for verified power-of-1024 byte limits in scoped prose. | Verified improvement. Summary: Query Rows → Query rows; sentence case matches the editorial guide. description: Query rows with typed predicates, sorting, and cursor pagination. Omit the predicate to match all rows. Pages default to a 5 MB limit; continue until `nextCursor` is null. Oversiz… → Query rows with typed predicates, sorting, and cursor pagination. Omit the predicate to match all rows. Pages default to a 5 MiB limit; continue until `nextCursor` is null. Oversi… requestBody.content.application/json.schema.properties.includeRunState.description: Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it onl… → Include per-workflow-group run outcomes on every row. Off by default. Incompatible with `limit: 0`; caps `limit` at 200. Run state above 2 MiB returns `413`; request fewer rows or… requestBody.content.application/json.schema.properties.limit.description: Maximum rows to return; zero requests an unbounded result. → Maximum rows per page. `0` requests all matches, subject to a 5 MiB row-data ceiling; larger results return `400` with `TABLE_QUERY_RESULT_TOO_LARGE`. Use paged queries or an expo… 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId queryTableRows, POST /api/v2/tables/{tableId}/query, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `countTableRows` — `POST /api/v2/tables/{tableId}/query/count` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Count Rows → Count rows; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId countTableRows, POST /api/v2/tables/{tableId}/query/count, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listTableViews` — `GET /api/v2/tables/{tableId}/views` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Views → List views; sentence case matches the editorial guide. description: List saved table views, omitting references to removed columns. Returns the complete set in one page; `nextCursor` is always null. OAuth scope: `api:read`. → List saved table views, omitting references to removed columns. Returns one page; `nextCursor` is always null. OAuth scope: `api:read`. responses.200.content.application/json.schema.properties.nextCursor.description: Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change. → Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId listTableViews, GET /api/v2/tables/{tableId}/views, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createTableView` — `POST /api/v2/tables/{tableId}/views` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create View → Create view; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createTableView, POST /api/v2/tables/{tableId}/views, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getTableView` — `GET /api/v2/tables/{tableId}/views/{viewId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get View → Get view; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId getTableView, GET /api/v2/tables/{tableId}/views/{viewId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 2 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateTableView` — `PATCH /api/v2/tables/{tableId}/views/{viewId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Update View → Update view; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateTableView, PATCH /api/v2/tables/{tableId}/views/{viewId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteTableView` — `DELETE /api/v2/tables/{tableId}/views/{viewId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Delete View → Delete view; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteTableView, DELETE /api/v2/tables/{tableId}/views/{viewId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 2 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listTableWorkflowGroups` — `GET /api/v2/tables/{tableId}/groups` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Workflow Groups → List workflow groups; sentence case matches the editorial guide. description: List the workflow and enrichment groups that can be dispatched for a table. Returns the complete set in one page; `nextCursor` is always null. OAuth scope: `api:read`. → List the workflow and enrichment groups that can be dispatched for a table. Returns one page; `nextCursor` is always null. OAuth scope: `api:read`. responses.200.content.application/json.schema.properties.nextCursor.description: Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change. → Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId listTableWorkflowGroups, GET /api/v2/tables/{tableId}/groups, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `addTableWorkflowGroup` — `POST /api/v2/tables/{tableId}/groups` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Add Workflow Group → Add workflow group; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId addTableWorkflowGroup, POST /api/v2/tables/{tableId}/groups, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateTableWorkflowGroup` — `PATCH /api/v2/tables/{tableId}/groups` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Update Workflow Group → Update workflow group; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateTableWorkflowGroup, PATCH /api/v2/tables/{tableId}/groups, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteTableWorkflowGroup` — `DELETE /api/v2/tables/{tableId}/groups` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Delete Workflow Group → Delete workflow group; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteTableWorkflowGroup, DELETE /api/v2/tables/{tableId}/groups, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createTableDispatch` — `POST /api/v2/tables/{tableId}/dispatches` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Run Dispatch → Create run dispatch; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createTableDispatch, POST /api/v2/tables/{tableId}/dispatches, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listTableDispatches` — `GET /api/v2/tables/{tableId}/dispatches` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Run Dispatches → List run dispatches; sentence case matches the editorial guide. responses.200.content.application/json.schema.properties.nextCursor.description: Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change. → Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId listTableDispatches, GET /api/v2/tables/{tableId}/dispatches, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `runRowEnrichment` — `POST /api/v2/tables/{tableId}/rows/{rowId}/enrichment/{groupId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Run Enrichment For One Row → Run enrichment for one row; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId runRowEnrichment, POST /api/v2/tables/{tableId}/rows/{rowId}/enrichment/{groupId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getRowEnrichment` — `GET /api/v2/tables/{tableId}/rows/{rowId}/enrichment/{groupId}` | corrected | Add PayloadTooLarge to these operations and explain the 2 MiB run-state ceiling on includeRunState / row-group detail. Replace internal "sidecar/blockErrors are unbounded" rationale with the user consequence and retry action. | Verified improvement. Summary: Get Row Group Run → Get row group run; sentence case matches the editorial guide. description: Read a workflow or enrichment group’s outcome for one row: `runState` (as exposed by `includeRunState`), output cells keyed by column name, and enrichment providers in cascade ord… → Read one row’s workflow or enrichment-group outcome: run state, output cells keyed by column name, and providers in cascade order with status, hosted-key cost, duration, and the m… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getRowEnrichment, GET /api/v2/tables/{tableId}/rows/{rowId}/enrichment/{groupId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 16 distinct changed field mappings were inspected for this operation. Only newly documented 413 response differs in operation structure; the existing 2 MiB run-state refusal is documented without route or schema behavior changes. |
+| `searchTableRows` — `POST /api/v2/tables/{tableId}/rows/search` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Search Rows → Search rows; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId searchTableRows, POST /api/v2/tables/{tableId}/rows/search, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createTableImport` — `POST /api/v2/tables/imports` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Create Table Import → Create table import; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createTableImport, POST /api/v2/tables/imports, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getTableImport` — `GET /api/v2/tables/imports/{importId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Table Import → Get table import; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId getTableImport, GET /api/v2/tables/imports/{importId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 2 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `cancelTableImport` — `DELETE /api/v2/tables/imports/{importId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Cancel Table Import → Cancel table import; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId cancelTableImport, DELETE /api/v2/tables/imports/{importId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createTableImportPartUrls` — `POST /api/v2/tables/imports/{importId}/parts` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Table Import Part URLs → Create table import part URLs; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createTableImportPartUrls, POST /api/v2/tables/imports/{importId}/parts, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `completeTableImportUpload` — `POST /api/v2/tables/imports/{importId}/complete` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Complete Table Import Upload → Complete table import upload; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId completeTableImportUpload, POST /api/v2/tables/imports/{importId}/complete, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createTableExport` — `POST /api/v2/tables/{tableId}/exports` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Table Export → Create table export; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createTableExport, POST /api/v2/tables/{tableId}/exports, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getTableExport` — `GET /api/v2/tables/{tableId}/exports/{exportId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Table Export → Get table export; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId getTableExport, GET /api/v2/tables/{tableId}/exports/{exportId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 2 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `cancelTableExport` — `DELETE /api/v2/tables/{tableId}/exports/{exportId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Cancel Table Export → Cancel table export; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId cancelTableExport, DELETE /api/v2/tables/{tableId}/exports/{exportId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `downloadTableExport` — `GET /api/v2/tables/{tableId}/exports/{exportId}/download` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Download Table Export → Download table export; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId downloadTableExport, GET /api/v2/tables/{tableId}/exports/{exportId}/download, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `cancelTableRuns` — `POST /api/v2/tables/{tableId}/cancel-runs` | corrected | "Workspace scope, row or all-table cancellation, and optional row predicate or exclusions." Do not advertise producer-group selection. | Verified improvement. Summary: Cancel Column Runs → Cancel column runs; sentence case matches the editorial guide. requestBody.content.application/json.schema.description: Workspace scope, cancellation scope, and optional predicate or producer groups. → Workspace scope, row or all-table cancellation, and optional row predicate or exclusions. requestBody.description: Workspace scope, cancellation scope, and optional predicate or producer groups. → Workspace scope, row or all-table cancellation, and optional row predicate or exclusions. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId cancelTableRuns, POST /api/v2/tables/{tableId}/cancel-runs, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listTablesFolders` — `GET /api/v2/tables/folders` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Folders → List folders; sentence case matches the editorial guide. description: List table folders, optionally limiting results to direct children of a parent path. Returns the complete set in one page; `nextCursor` is always null. OAuth scope: `api:read`. → List table folders, optionally limiting results to direct children of a parent path. Returns one page; `nextCursor` is always null. OAuth scope: `api:read`. parameters[3].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[3].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Preserved: Compared operationId listTablesFolders, GET /api/v2/tables/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createTablesFolder` — `POST /api/v2/tables/folders` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Folder → Create folder; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createTablesFolder, POST /api/v2/tables/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `relocateTablesFolder` — `PATCH /api/v2/tables/folders` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Rename or Move Folder → Rename or move folder; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId relocateTablesFolder, PATCH /api/v2/tables/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteTablesFolder` — `DELETE /api/v2/tables/folders` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Delete Folder → Delete folder; sentence case matches the editorial guide. parameters[2].description: Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are ca… → Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted. parameters[2].schema.description: Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are ca… → Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId deleteTablesFolder, DELETE /api/v2/tables/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `restoreTablesFolder` — `POST /api/v2/tables/folders/restore` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Restore Folder → Restore folder; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId restoreTablesFolder, POST /api/v2/tables/folders/restore, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `restoreTable` — `POST /api/v2/tables/{tableId}/restore` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Restore Table → Restore table; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId restoreTable, POST /api/v2/tables/{tableId}/restore, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `bulkUpdateTableRows` — `POST /api/v2/tables/{tableId}/rows/bulk-update` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Bulk Update Rows → Bulk update rows; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId bulkUpdateTableRows, POST /api/v2/tables/{tableId}/rows/bulk-update, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getTableDispatch` — `GET /api/v2/tables/{tableId}/dispatches/{dispatchId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Run Dispatch → Get run dispatch; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId getTableDispatch, GET /api/v2/tables/{tableId}/dispatches/{dispatchId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 2 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `cancelTableDispatch` — `DELETE /api/v2/tables/{tableId}/dispatches/{dispatchId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Cancel Run Dispatch → Cancel run dispatch; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId cancelTableDispatch, DELETE /api/v2/tables/{tableId}/dispatches/{dispatchId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `moveTables` — `POST /api/v2/tables/move` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Move Tables and Folders → Move tables and folders; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId moveTables, POST /api/v2/tables/move, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 3 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `bulkDeleteTables` — `POST /api/v2/tables/bulk-delete` | corrected | Use neutral document-wide error examples, or operation-specific examples. Preserve error.details.lock and actionable detail codes. These are illustrative examples, not a claim that every server response uses that message. | Verified improvement. Summary: Bulk Delete Tables and Folders → Bulk delete tables and folders; sentence case matches the editorial guide. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId bulkDeleteTables, POST /api/v2/tables/bulk-delete, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+
+### API workflow operations (59)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| `listWorkflows` — `GET /api/v2/workflows` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Workflows → List workflows; sentence case matches the editorial guide. description: List active workflows in a workspace. Use `scope=archived` to find workflows available for restoration. Supports folder and deployment filters, search, sorting, and cursor paginat… → List active workflows in a workspace with workspace read access. Use `scope=archived` to find workflows available for restoration. Filter by folder, deployment, or name; sort and … parameters[7].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[7].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listWorkflows, GET /api/v2/workflows, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createWorkflowV2` — `POST /api/v2/workflows` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Workflow → Create workflow; sentence case matches the editorial guide. description: Create a workflow at the workspace root or in a workflow folder. The response includes seeded blocks and their IDs for attaching edges. Workspace folder trees exceeding 10,000 fol… → Create an undeployed workflow at the workspace root or in a workflow folder. Requires workspace write access. The response includes the seeded start block and its ID for connectin… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createWorkflowV2, POST /api/v2/workflows, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkflowState` — `GET /api/v2/workflows/{workflowId}/state` | corrected | Kept undeployed-copy, same-workflow source state, trigger shutdown, and pending-rollback consequences close to their actions. | Verified improvement. Summary: Get Workflow State → Get workflow state; sentence case matches the editorial guide. description: Get the editable draft graph, including blocks, edges, loop and parallel containers, and variables. Use this state with Replace Workflow State to preserve workspace bindings; Expo… → Read the saved editable draft, including blocks, edges, loop and parallel containers, and variables. Requires workspace read access. Configured values are included; use this state… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getWorkflowState, GET /api/v2/workflows/{workflowId}/state, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `replaceWorkflowState` — `PUT /api/v2/workflows/{workflowId}/state` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Replace Workflow State → Replace workflow state; sentence case matches the editorial guide. description: Atomically replace the draft graph; row-locked concurrent writes are last-write-wins. Block, edge, or subflow IDs owned by another workflow return `409`. Deployments remain immuta… → Replace the draft graph in one write. Requires workspace write access. Concurrent row-locked writes are last-write-wins; IDs owned by another workflow return `409`. Deployments, s… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId replaceWorkflowState, PUT /api/v2/workflows/{workflowId}/state, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `applyWorkflowOperations` — `POST /api/v2/workflows/{workflowId}/operations` | corrected | Aligned request label, mintedBlockIds key, and lint block UUID in the edit example. | Verified improvement. Summary: Apply Workflow Operations → Apply workflow operations; sentence case matches the editorial guide. description: Edit the draft graph and block enablement in one write. Inspect `skipped` for failures; do not retry `deferred` edges. With `atomic=true`, skipped operations or dropped inputs ret… → Apply draft edits and block enablement changes in one write. Requires workspace write access. The live deployment is unchanged; lint is advisory. Inspect `skipped` and `inputValid… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId applyWorkflowOperations, POST /api/v2/workflows/{workflowId}/operations, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `applyWorkflowVariables` — `PATCH /api/v2/workflows/{workflowId}/variables` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Update Workflow Variables → Update workflow variables; sentence case matches the editorial guide. description: Add, edit, or delete variables by name, applying operations in order. Values are coerced to their declared type when possible; otherwise they are stored as supplied. A batch with … → Add, edit, or delete variables by name with workspace write access. Operations run in order. Values are coerced to their declared type when possible and otherwise stored as suppli… responses.200.content.application/json.schema.properties.data.properties.variableCount.description: Variables the workflow now holds. → Number of variables after the batch. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId applyWorkflowVariables, PATCH /api/v2/workflows/{workflowId}/variables, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `duplicateWorkflow` — `POST /api/v2/workflows/{workflowId}/duplicate` | corrected | Kept undeployed-copy, same-workflow source state, trigger shutdown, and pending-rollback consequences close to their actions. | Verified improvement. Summary: Duplicate Workflow → Duplicate workflow; sentence case matches the editorial guide. description: Copy a workflow's graph and variables into the same workspace. Omit `name` to reuse the source name; name collisions in the destination folder are resolved automatically. Workspac… → Create an undeployed copy of a workflow's graph and variables in the same workspace. Requires workspace write access. The destination folder and name default to the source; name c… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId duplicateWorkflow, POST /api/v2/workflows/{workflowId}/duplicate, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `restoreWorkflow` — `POST /api/v2/workflows/{workflowId}/restore` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Restore Workflow → Restore workflow; sentence case matches the editorial guide. description: Restore an archived workflow and the schedules, webhooks, MCP tools, and chats archived with it. An active workflow returns `409`. If its folder is archived, the workflow returns … → Restore an archived workflow and its archived schedules, webhooks, MCP tools, and hosted chat. Requires workspace write access. An active workflow returns `409`. If its folder is … responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId restoreWorkflow, POST /api/v2/workflows/{workflowId}/restore, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `moveWorkflows` — `POST /api/v2/workflows/move` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Move Workflows → Move workflows; sentence case matches the editorial guide. description: Move up to 100 workflows into one folder. Moves succeed or fail independently; missing, archived, or locked workflows appear in `failed`. Duplicate IDs are ignored. Workspace fold… → Move up to 100 workflows to one folder with workspace write access. Each move succeeds or fails independently; missing, archived, or locked workflows appear in `failed`. Duplicate… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId moveWorkflows, POST /api/v2/workflows/move, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkflow` — `GET /api/v2/workflows/{workflowId}` | corrected | Identified trigger inputs as saved-draft fields, not deployed inputs. | Verified improvement. Summary: Get Workflow → Get workflow; sentence case matches the editorial guide. description: Get a workflow with its variables and deployed API-trigger inputs. Workspace folder trees exceeding 10,000 folders return `413`. OAuth scope: `api:read`. → Get workflow metadata, variables, and trigger input fields from the saved draft. Requires workspace read access. Input fields may differ from the live deployment. Workspace folder… responses.200.content.application/json.schema.properties.data.properties.inputs.description: Input fields exposed by the workflow API trigger. → Input fields from the saved draft's input-definition trigger; they may differ from the live deployment. responses.200.content.application/json.schema.properties.data.properties.inputs.items.description: A deployed API trigger input exposed by a workflow. → An input field from an input-definition trigger in the saved draft. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getWorkflow, GET /api/v2/workflows/{workflowId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateWorkflowV2` — `PATCH /api/v2/workflows/{workflowId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Update Workflow → Update workflow; sentence case matches the editorial guide. description: Update a workflow's name, description, or folder path. Workspace folder trees exceeding 10,000 folders return `413`. OAuth scope: `api:write`. → Update a workflow's name, description, or folder path with workspace write access. Omitted fields remain unchanged; `description: null` clears the description. Workspace folder tr… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateWorkflowV2, PATCH /api/v2/workflows/{workflowId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteWorkflowV2` — `DELETE /api/v2/workflows/{workflowId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Delete Workflow → Delete workflow; sentence case matches the editorial guide. description: Archive a workflow and stop its schedules, webhooks, MCP tools, and chats. Use List Workflows with `scope=archived` to find it and Restore Workflow to recover it and its archived … → Archive a workflow and stop its schedules, webhooks, MCP tools, and hosted chat. Requires workspace write access. Find it with List workflows (`scope=archived`) and recover it wit… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteWorkflowV2, DELETE /api/v2/workflows/{workflowId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listWorkflowVersionsV2` — `GET /api/v2/workflows/{workflowId}/versions` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Workflow Versions → List workflow versions; sentence case matches the editorial guide. description: List immutable deployment versions of a workflow, newest first. OAuth scope: `api:read`. → List saved deployment versions, newest first, with workspace read access. Each version pins an immutable graph; its name and release note can be updated. OAuth scope: `api:read`. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listWorkflowVersionsV2, GET /api/v2/workflows/{workflowId}/versions, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `compareWorkflowVersionsV2` — `GET /api/v2/workflows/{workflowId}/versions/compare` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Compare Workflow Versions → Compare workflow versions; sentence case matches the editorial guide. description: Compare two deployment versions of the same workflow. Reports semantic changes, excluding canvas layout; credential-bearing values are withheld while their changes remain visible.… → Compare two deployment versions of the same workflow with workspace read access. The comparison excludes layout changes and withholds credential-bearing values while reporting the… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId compareWorkflowVersionsV2, GET /api/v2/workflows/{workflowId}/versions/compare, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkflowVersionV2` — `GET /api/v2/workflows/{workflowId}/versions/{version}` | corrected | Qualified known-field credential redaction; preserved ordinary variables and unresolved environment references, with export-review guidance. Kept undeployed-copy, same-workflow source state, trigger shutdown, and pending-rollback consequences close to their actions. | Verified improvement. Summary: Get Workflow Version → Get workflow version; sentence case matches the editorial guide. description: Get an immutable deployment version and its pinned workflow graph snapshot. OAuth scope: `api:read`. → Get a deployment version and its pinned graph with workspace read access. Registered credential fields and opaque table/tool values are cleared. Environment references and ordinar… responses.200.content.application/json.schema.properties.data.properties.state.description: Workflow graph saved with this deployment version. Sensitive values are redacted to null. → Graph pinned by this version, with registered credential fields and opaque table/tool values cleared. Environment references and ordinary workflow variables remain included; inspe… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getWorkflowVersionV2, GET /api/v2/workflows/{workflowId}/versions/{version}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateWorkflowVersionV2` — `PATCH /api/v2/workflows/{workflowId}/versions/{version}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Update Workflow Version → Update workflow version; sentence case matches the editorial guide. description: Update a deployment version's name or release note. Omitted fields remain unchanged; `description: null` clears the note. The graph and live version remain unchanged. Use Activate… → Update a deployment version's name or release note with workspace write access. Omitted fields remain unchanged; `description: null` clears the note. The graph and live version ar… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateWorkflowVersionV2, PATCH /api/v2/workflows/{workflowId}/versions/{version}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `activateWorkflowVersion` — `POST /api/v2/workflows/{workflowId}/versions/{version}/activate` | corrected | Named required workspace Admin role separately from OAuth scope and credential-kind restrictions. | Verified improvement. Summary: Activate Workflow Version → Activate workflow version; sentence case matches the editorial guide. description: Asynchronously activate a specific deployment version, including when the workflow is not currently deployed. The draft remains unchanged. Read Get Workflow Deployment for `isDepl… → Activate a specific deployment version asynchronously. Requires workspace Admin access and works when the workflow is undeployed. The draft is unchanged. Poll Get workflow deploym… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId activateWorkflowVersion, POST /api/v2/workflows/{workflowId}/versions/{version}/activate, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `revertWorkflowVersion` — `POST /api/v2/workflows/{workflowId}/versions/{version}/revert` | corrected | Named required workspace Admin role separately from OAuth scope and credential-kind restrictions. | Verified improvement. Summary: Revert Workflow To Version → Revert workflow to version; sentence case matches the editorial guide. description: Replace the editable draft with a deployment version, discarding current draft edits. Use `active` for the live version. The live deployment remains unchanged; Activate Workflow V… → Overwrite the editable draft with a deployment version, discarding current draft edits. Requires workspace Admin access. Use `active` for the live version. The live deployment is … responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId revertWorkflowVersion, POST /api/v2/workflows/{workflowId}/versions/{version}/revert, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkflowDeployment` — `GET /api/v2/workflows/{workflowId}/deployment` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Workflow Deployment → Get workflow deployment; sentence case matches the editorial guide. description: Read live status, deployment time, latest attempt readiness and failure, draft divergence (`needsRedeployment`), anonymous execution access (`isPublicApi`), and registered webhook… → Read live deployment status, the latest attempt's readiness or failure, and draft divergence (`needsRedeployment`). Requires workspace read access. `isPublicApi` reports anonymous… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getWorkflowDeployment, GET /api/v2/workflows/{workflowId}/deployment, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateWorkflowPublicApi` — `PATCH /api/v2/workflows/{workflowId}/deployment` | corrected | Named required workspace Admin role separately from OAuth scope and credential-kind restrictions. | Verified improvement. Summary: Update Workflow Public API Access → Update workflow public API access; sentence case matches the editorial guide. description: Enable or disable unauthenticated execution of the deployed workflow. Enabling allows anyone with the execution URL to consume billed usage. Organization sharing restrictions retu… → Enable or disable unauthenticated execution of the deployed workflow. Requires workspace Admin access. Enabling lets anyone with the execution URL consume billed usage. Organizati… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateWorkflowPublicApi, PATCH /api/v2/workflows/{workflowId}/deployment, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deployWorkflow` — `POST /api/v2/workflows/{workflowId}/deploy` | corrected | Named required workspace Admin role separately from OAuth scope and credential-kind restrictions. | Verified improvement. Summary: Deploy Workflow → Deploy workflow; sentence case matches the editorial guide. description: Create and asynchronously activate a deployment version. Every call creates a new version; retrying after a timeout can create a duplicate. Read Get Workflow Deployment to check a… → Create a deployment version and activate it asynchronously. Requires workspace Admin access. Each accepted deploy creates a new version; retrying after a timeout can create a dupl… responses.200.content.application/json.schema.properties.data.properties.lint.description: Advisory lint findings for the version this deploy publishes, checked as the deploying user. Findings never block a deploy. Null when the lint could not complete within its time b… → Advisory lint for the admitted version, checked as the deploying member. Findings never block deployment. Null when lint exceeds its time budget or cannot complete; the deployment… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deployWorkflow, POST /api/v2/workflows/{workflowId}/deploy, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `undeployWorkflow` — `DELETE /api/v2/workflows/{workflowId}/deploy` | corrected | Named required workspace Admin role separately from OAuth scope and credential-kind restrictions. Kept undeployed-copy, same-workflow source state, trigger shutdown, and pending-rollback consequences close to their actions. | Verified improvement. Summary: Undeploy Workflow → Undeploy workflow; sentence case matches the editorial guide. description: Deactivate the currently serving workflow version. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:write`. → Deactivate the live workflow version and stop its scheduled and webhook triggers. Requires workspace Admin access and a deployed workflow. Deployed MCP tools become inactive; `arc… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId undeployWorkflow, DELETE /api/v2/workflows/{workflowId}/deploy, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `rollbackWorkflow` — `POST /api/v2/workflows/{workflowId}/rollback` | corrected | Named required workspace Admin role separately from OAuth scope and credential-kind restrictions. | Verified improvement. Summary: Rollback Workflow → Rollback workflow; sentence case matches the editorial guide. description: Asynchronously activate a previous deployment version, defaulting to the preceding active version. Requires a deployed workflow and leaves the draft unchanged. Use Activate Workfl… → Activate a previous deployment version asynchronously, defaulting to the preceding active version. Requires workspace Admin access and a deployed workflow. The draft is unchanged.… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId rollbackWorkflow, POST /api/v2/workflows/{workflowId}/rollback, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `exportWorkflow` — `GET /api/v2/workflows/{workflowId}/export` | corrected | Qualified known-field credential redaction; preserved ordinary variables and unresolved environment references, with export-review guidance. Made binding clearing conditional on default exports and actual missing required fields. | Verified improvement. Summary: Export Workflow → Export workflow; sentence case matches the editorial guide. description: Export a portable, secret-sanitized workflow. Use includeReferences=true for non-secret source identities and field occurrences used by mapped imports. Use includeWorkspaceBinding… → Export the saved draft as portable workflow data with workspace read access. Registered credential fields and opaque table/tool values are cleared; environment references and ordi… parameters[2].description: Whether to keep workspace-scoped bindings — table, knowledge base, document, folder, channel, and other resource selectors — in the exported state. Defaults to false, the sharing-… → Keep non-secret table, knowledge base, document, folder, channel, and other workspace bindings for a same-workspace import. Defaults to false, which clears these IDs. Registered c… parameters[2].schema.description: Whether to keep workspace-scoped bindings — table, knowledge base, document, folder, channel, and other resource selectors — in the exported state. Defaults to false, the sharing-… → Keep non-secret table, knowledge base, document, folder, channel, and other workspace bindings for a same-workspace import. Defaults to false, which clears these IDs. Registered c… 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId exportWorkflow, GET /api/v2/workflows/{workflowId}/export, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `importWorkflow` — `POST /api/v2/workflows/import` | corrected | Made binding clearing conditional on default exports and actual missing required fields. Added syntax-valid root examples; import example also passes the portable-workflow parser. Preview hashes are explicitly illustrative. Restored exact-preview choice matching and identical-request retry behavior on fields and apply intros. | Verified improvement. Summary: Import Workflow → Import workflow; sentence case matches the editorial guide. description: Create an undeployed workflow from a portable export object, bare state, or JSON string. Mapping options require a preview fingerprint and stable request ID; unresolved required c… → Create an undeployed workflow from a portable export object, bare draft state, or JSON string. Requires workspace write access. The empty-state example creates a draft that needs … requestBody.content.application/json.schema.description: Workflow document, destination, and optional reviewed mappings. → Workflow document, destination, and optional reviewed mappings. This example creates an empty draft. requestBody.content.application/json.schema.properties.dependentValues.description: Destination-dependent choices keyed by source workflow, block, and field identities. → Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId importWorkflow, POST /api/v2/workflows/import, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 20 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listChatDeployments` — `GET /api/v2/chat-deployments` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Chat Deployments → List chat deployments; sentence case matches the editorial guide. description: List hosted chats and their public URLs with cursor pagination. Filter by `workflowId` for one workflow's chat. The list requires workspace read access; Get Workflow Chat Deployme… → List hosted chats and their URLs with workspace read access and cursor pagination. Filter by `workflowId` for one workflow's chat. The admin-only detail read also includes visitor… responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listChatDeployments, GET /api/v2/chat-deployments, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkflowChatDeployment` — `GET /api/v2/workflows/{workflowId}/deployments/chat` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Workflow Chat Deployment → Get workflow chat deployment; sentence case matches the editorial guide. description: Get a workflow's hosted chat and visitor access settings. Requires workspace admin access; a missing chat returns `404`. Passwords are never returned; `hasPassword` indicates whet… → Get a workflow's hosted chat and visitor access settings with workspace Admin access. A missing chat returns `404`. Passwords are never returned; `hasPassword` reports whether one… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getWorkflowChatDeployment, GET /api/v2/workflows/{workflowId}/deployments/chat, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `replaceWorkflowChatDeployment` — `PUT /api/v2/workflows/{workflowId}/deployments/chat` | corrected | Documented omitted/empty image and empty welcome-message merge exceptions. Named required workspace Admin role separately from OAuth scope and credential-kind restrictions. | Verified improvement. Summary: Create or Replace Workflow Chat Deployment → Create or replace workflow chat deployment; sentence case matches the editorial guide. description: Create or replace a workflow's hosted chat and deploy its draft. Omitted fields reset to defaults except per-field customizations. Password authentication requires `password`; ema… → Create or replace a workflow's hosted chat and deploy its saved draft. Requires workspace Admin access. Omitted fields use defaults; customization exceptions are described on thei… requestBody.content.application/json.schema.properties.customizations.description: Presentation overrides. Omitted fields take platform defaults. → Presentation overrides. Omitted `primaryColor` and `welcomeMessage` use platform defaults; an omitted or empty `imageUrl` keeps the existing avatar. An empty `welcomeMessage` keep… requestBody.content.application/json.schema.properties.customizations.properties.imageUrl.description: Avatar image shown beside assistant messages. → Avatar image shown beside assistant messages. On replace, omission or an empty string keeps the existing avatar. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId replaceWorkflowChatDeployment, PUT /api/v2/workflows/{workflowId}/deployments/chat, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 10 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteWorkflowChatDeployment` — `DELETE /api/v2/workflows/{workflowId}/deployments/chat` | corrected | Named required workspace Admin role separately from OAuth scope and credential-kind restrictions. | Verified improvement. Summary: Delete Workflow Chat Deployment → Delete workflow chat deployment; sentence case matches the editorial guide. description: Remove a workflow's hosted chat and release its URL identifier. The workflow API deployment remains active; use Undeploy Workflow to stop it. Workspace API keys return `403`; use … → Remove the hosted chat and release its URL identifier with workspace Admin access. The workflow API deployment remains active; use Undeploy workflow to stop it. Workspace API keys… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteWorkflowChatDeployment, DELETE /api/v2/workflows/{workflowId}/deployments/chat, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `executeWorkflowV2` — `POST /api/v2/workflows/{workflowId}/execute` | corrected | Named Accept:application/x-ndjson with synchronous flags, final frame data, separate SSE, and ambiguous enqueue reconciliation. Kept undeployed-copy, same-workflow source state, trigger shutdown, and pending-rollback consequences close to their actions. | Verified improvement. Summary: Execute Workflow → Execute workflow; sentence case matches the editorial guide. description: Execute a deployment or use `run.source: "manual"` for the draft. Manual runs require personal or OAuth write access and reject async. Public deployments allow anonymous sync or s… → Run the active deployment, or set `run.source: "manual"` to run the saved draft. Deployed execution requires workspace read access and OAuth `api:write` scope or an API key; publi… requestBody.content.application/json.schema.properties.async.description: Queue the run and return a 202 receipt when true. Requires an OAuth access token or API key, cannot be combined with `stream`, and rejects all streaming and output-shaping options… → Queue the run and return a 202 receipt. Requires an API key or OAuth access token and a deployed run source. Cannot stream, select outputs, enable thinking/tool events, or include… requestBody.content.application/json.schema.properties.run.oneOf[1].properties.entry.oneOf[1].properties.sourceRunId.description: Run ID supplying upstream block results when starting from a selected block. → Run in this workflow whose persisted execution state supplies upstream block results. Missing or expired state returns 404. 3 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId executeWorkflowV2, POST /api/v2/workflows/{workflowId}/execute, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 10 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listWorkflowRunsV2` — `GET /api/v2/workflows/{workflowId}/runs` | corrected | Documented permission-driven null output/files/cost and independent output selection. Root corrected billing-mode/default retention and protected-pause wording in openapi/shared.ts. Included human and time pauses; root corrected the shared pauseKind/resumeAt waiting-reason description. | Verified improvement. Summary: List Workflow Runs → List workflow runs; sentence case matches the editorial guide. description: List recorded runs of a workflow with filtering and opaque cursor pagination. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro a… → List recorded workflow runs with workspace read access, filters, and cursor pagination. Cost can be hidden by organization permission groups. Expired runs are permanently deleted … responses.200.content.application/json.schema.properties.data.items.properties.cost.description: Credit cost, or null when unavailable. → Credits consumed, or null when unavailable or hidden by organization permission groups. responses.200.content.application/json.schema.properties.data.items.properties.status.description: Current or terminal run status. `redacting` is transient, reported while a finished run's output is being scrubbed. `paused` means the run is waiting to be resumed — either held a… → Current or terminal run status. `redacting` is transient, reported while a finished run's output is being scrubbed. `paused` means the run is waiting at a human or time pause, or … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listWorkflowRunsV2, GET /api/v2/workflows/{workflowId}/runs, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkflowRunV2` — `GET /api/v2/workflows/{workflowId}/runs/{runId}` | corrected | Documented permission-driven null output/files/cost and independent output selection. Included human and time pauses; root corrected the shared pauseKind/resumeAt waiting-reason description. | Verified improvement. Summary: Get Workflow Run → Get workflow run; sentence case matches the editorial guide. description: Get current run state with optional final and block outputs. With `includeOutput`, `files` includes download paths; `includeFileBase64` inlines file bytes and returns `413` with t… → Read current run state with workspace read access. Request final output and files with `includeOutput`, or block outputs with `selectedOutputs`. Organization permission groups can… responses.200.content.application/json.schema.properties.data.properties.blockOutputs.description: Outputs of the blocks named by `selectedOutputs`, or null when none were requested. Gated by `selectedOutputs` alone — `includeOutput` governs `output` only. → Selected block outputs, or null when none were requested or execution data is hidden by organization permission groups. `selectedOutputs` controls these independently of `includeO… responses.200.content.application/json.schema.properties.data.properties.cost.description: Credit cost, or null when unavailable. → Credits consumed, or null when unavailable or hidden by organization permission groups. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getWorkflowRunV2, GET /api/v2/workflows/{workflowId}/runs/{runId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 11 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `downloadWorkflowRunFileV2` — `GET /api/v2/workflows/{workflowId}/runs/{runId}/files/{fileId}` | corrected | Documented permission-driven null output/files/cost and independent output selection. Root corrected billing-mode/default retention and protected-pause wording in openapi/shared.ts. | Verified improvement. Summary: Download Workflow Run File → Download workflow run file; sentence case matches the editorial guide. description: Download one run-produced file by ID. Downloads record an audit event. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team… → Download one run-produced file by its reported ID with workspace read access. Downloads record an audit event. Expired runs are permanently deleted by retention cleanup. Sim Cloud… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId downloadWorkflowRunFileV2, GET /api/v2/workflows/{workflowId}/runs/{runId}/files/{fileId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `resumeWorkflowRunV2` — `POST /api/v2/workflows/{workflowId}/runs/{runId}/resume` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Resume Workflow Run → Resume workflow run; sentence case matches the editorial guide. description: Resume one human-in-the-loop pause. The resumed attempt receives a new run ID and returns either a synchronous result or a queue receipt. OAuth scope: `api:write`. → Resume one human-in-the-loop pause with workspace write access. The resumed attempt receives a new run ID and returns a synchronous result or queue receipt. A run that originally … responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 3 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId resumeWorkflowRunV2, POST /api/v2/workflows/{workflowId}/runs/{runId}/resume, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `cancelRunV2` — `POST /api/v2/workflows/{workflowId}/runs/{runId}/cancel` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Cancel Workflow Run → Cancel workflow run; sentence case matches the editorial guide. description: Request cancellation of a running, queued, or paused workflow run. Cancelling a run already in a terminal state is a `200` no-op answered with `success: false` and an `already_*` … → Request cancellation of a running, queued, or paused workflow run with workspace write access. Cancellation is best effort; inspect the outcome flags and `reason`. A terminal run … responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId cancelRunV2, POST /api/v2/workflows/{workflowId}/runs/{runId}/cancel, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listWorkflowsFolders` — `GET /api/v2/workflows/folders` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Workflow Folders → List workflow folders; sentence case matches the editorial guide. description: List workflow folders in a workspace. Returns the complete set in one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000 folders return `413`. OAuth scope:… → List workflow folders with workspace read access, optional parent/name filters, and sorting. Returns one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000… parameters[3].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[3].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listWorkflowsFolders, GET /api/v2/workflows/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createWorkflowsFolder` — `POST /api/v2/workflows/folders` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Workflow Folder → Create workflow folder; sentence case matches the editorial guide. description: Create a workflow folder in a workspace. Workspace folder trees exceeding 10,000 folders return `413`. OAuth scope: `api:write`. → Create a workflow folder at a non-root path with workspace write access. Workspace folder trees exceeding 10,000 folders return `413`. OAuth scope: `api:write`. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createWorkflowsFolder, POST /api/v2/workflows/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `relocateWorkflowsFolder` — `PATCH /api/v2/workflows/folders` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Rename or Move Workflow Folder → Rename or move workflow folder; sentence case matches the editorial guide. description: Rename or move a workflow folder and update all descendant paths. Workspace folder trees exceeding 10,000 folders return `413`. OAuth scope: `api:write`. → Rename or move a workflow folder and update descendant paths with workspace write access. An existing destination receives the folder as a child; otherwise the destination is its … responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId relocateWorkflowsFolder, PATCH /api/v2/workflows/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteWorkflowsFolder` — `DELETE /api/v2/workflows/folders` | corrected | Root corrected recursive folder wording in v2/shared.ts. | Verified improvement. Summary: Delete Workflow Folder → Delete workflow folder; sentence case matches the editorial guide. description: Archive an empty workflow folder, or set `recursive=true` to archive its subfolders and workflows. Use Restore Workflow to recover workflows. OAuth scope: `api:write`. → Archive an empty workflow folder with workspace write access. `recursive=true` also archives its subfolders and workflows, stopping the archived workflows' triggers and hosted sur… parameters[2].description: Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are ca… → Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted. parameters[2].schema.description: Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are ca… → Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteWorkflowsFolder, DELETE /api/v2/workflows/folders, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `previewWorkspaceFork` — `POST /api/v2/workspaces/{workspaceId}/fork/preview` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Restored exact-preview choice matching and identical-request retry behavior on fields and apply intros. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Preview Workspace Fork → Preview workspace fork; sentence case matches the editorial guide. description: Preview the deployed workflows and explicitly selected resources that a new workspace fork would copy. The result is read-only and supplies the fingerprint required by Fork Worksp… → Preview deployed workflows and explicitly selected resources for a new child workspace. Requires source workspace Admin access and permission to create a workspace in its organiza… requestBody.content.application/json.schema.description: The body for this operation. → Optional child name and explicitly selected resource copies. requestBody.description: The body for this operation. → Optional child name and explicitly selected resource copies. Preserved: Compared operationId previewWorkspaceFork, POST /api/v2/workspaces/{workspaceId}/fork/preview, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `forkWorkspace` — `POST /api/v2/workspaces/{workspaceId}/fork` | corrected | Added syntax-valid root examples; import example also passes the portable-workflow parser. Preview hashes are explicitly illustrative. Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Restored exact-preview choice matching and identical-request retry behavior on fields and apply intros. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. Root added and rendered a validated response example with the correct workspace operation kind rather than the shared import enum default. | Verified improvement. Summary: Fork Workspace → Fork workspace; sentence case matches the editorial guide. description: Create a child workspace with undeployed workflow drafts. Requires the reviewed preview fingerprint and a stable request ID. Identical retries return the same operation; reuse wit… → Create a child workspace with undeployed drafts of the source's deployed workflows. Requires source workspace Admin access and permission to create a workspace in its organization… requestBody.content.application/json.schema.description: The body for this operation. → Child name and copy choices, with the actual preview fingerprint and a stable request ID. requestBody.content.application/json.schema.properties.previewFingerprint.description: Fingerprint of the reviewed preview and its choices. → Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value. 4 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId forkWorkspace, POST /api/v2/workspaces/{workspaceId}/fork, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 21 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `previewWorkspacePush` — `POST /api/v2/workspaces/{workspaceId}/fork/push/preview` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Named create/replace/archive actions, draft overwrite and deleted-source archival, preserving undeployed-source targets. Restored exact-preview choice matching and identical-request retry behavior on fields and apply intros. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Preview Workspace Push → Preview workspace push; sentence case matches the editorial guide. description: Preview deployed source workflows replacing mapped targets along a direct fork edge. Push sends the current workspace to the other; pull brings the other into the current workspac… → Preview changes from this workspace into the other workspace along a direct fork edge. Requires Admin access to both workspaces. The plan lists workflows to create, replace, or ar… requestBody.content.application/json.schema.description: The body for this operation. → Other workspace and proposed source-to-target sync choices. requestBody.content.application/json.schema.properties.dependentValues.description: Destination-dependent choices keyed by source workflow, block, and field identities. → Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them. Preserved: Compared operationId previewWorkspacePush, POST /api/v2/workspaces/{workspaceId}/fork/push/preview, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 12 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `pushWorkspace` — `POST /api/v2/workspaces/{workspaceId}/fork/push` | corrected | Added syntax-valid root examples; import example also passes the portable-workflow parser. Preview hashes are explicitly illustrative. Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Named create/replace/archive actions, draft overwrite and deleted-source archival, preserving undeployed-source targets. Restored exact-preview choice matching and identical-request retry behavior on fields and apply intros. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Push Workspace → Push workspace; sentence case matches the editorial guide. description: Apply a reviewed push or pull with inline mappings in one transaction. Requires confirmation, the preview fingerprint, and a stable request ID. Unresolved or changed plans return … → Apply a reviewed sync from this workspace into the other workspace along a direct fork edge. Requires Admin access to both workspaces. Creates unmatched deployed workflows, overwr… requestBody.content.application/json.schema.description: The body for this operation. → Confirmed current-to-other choices, actual preview fingerprint, and stable request ID. requestBody.content.application/json.schema.properties.confirm.description: Explicit acknowledgement that sync replaces target workflows. → Confirm replacement of mapped target drafts and archival of mapped targets whose sources were deleted or archived. 4 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId pushWorkspace, POST /api/v2/workspaces/{workspaceId}/fork/push, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 24 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `previewWorkspacePull` — `POST /api/v2/workspaces/{workspaceId}/fork/pull/preview` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Named create/replace/archive actions, draft overwrite and deleted-source archival, preserving undeployed-source targets. Restored exact-preview choice matching and identical-request retry behavior on fields and apply intros. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Preview Workspace Pull → Preview workspace pull; sentence case matches the editorial guide. description: Preview deployed source workflows replacing mapped targets along a direct fork edge. Push sends the current workspace to the other; pull brings the other into the current workspac… → Preview changes from the other workspace into this workspace along a direct fork edge. Requires Admin access to both workspaces. The plan lists workflows to create, replace, or ar… requestBody.content.application/json.schema.description: The body for this operation. → Other workspace and proposed source-to-target sync choices. requestBody.content.application/json.schema.properties.dependentValues.description: Destination-dependent choices keyed by source workflow, block, and field identities. → Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them. Preserved: Compared operationId previewWorkspacePull, POST /api/v2/workspaces/{workspaceId}/fork/pull/preview, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 12 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `pullWorkspace` — `POST /api/v2/workspaces/{workspaceId}/fork/pull` | corrected | Added syntax-valid root examples; import example also passes the portable-workflow parser. Preview hashes are explicitly illustrative. Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Named create/replace/archive actions, draft overwrite and deleted-source archival, preserving undeployed-source targets. Restored exact-preview choice matching and identical-request retry behavior on fields and apply intros. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Pull Workspace → Pull workspace; sentence case matches the editorial guide. description: Apply a reviewed push or pull with inline mappings in one transaction. Requires confirmation, the preview fingerprint, and a stable request ID. Unresolved or changed plans return … → Apply a reviewed sync from the other workspace into this workspace along a direct fork edge. Requires Admin access to both workspaces. Creates unmatched deployed workflows, overwr… requestBody.content.application/json.schema.description: The body for this operation. → Confirmed other-to-current choices, actual preview fingerprint, and stable request ID. requestBody.content.application/json.schema.properties.confirm.description: Explicit acknowledgement that sync replaces target workflows. → Confirm replacement of mapped target drafts and archival of mapped targets whose sources were deleted or archived. 4 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId pullWorkspace, POST /api/v2/workspaces/{workspaceId}/fork/pull, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 24 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkspaceForkAvailability` — `GET /api/v2/workspaces/{workspaceId}/fork/availability` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Get Workspace Fork Availability → Get workspace fork availability; sentence case matches the editorial guide. description: Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on bot… → Check whether workspace forking is enabled for this deployment and workspace plan. Requires workspace Admin access. Returns `available: false` when the feature gate is unmet. Bill… responses.200.content.application/json.schema.description: The response for this operation. → Whether forking is enabled for this deployment and workspace plan. responses.200.description: The workspace operation result. → Whether forking is enabled for this deployment and workspace plan. Preserved: Compared operationId getWorkspaceForkAvailability, GET /api/v2/workspaces/{workspaceId}/fork/availability, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkspaceForkLineage` — `GET /api/v2/workspaces/{workspaceId}/fork/lineage` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Get Workspace Fork Lineage → Get workspace fork lineage; sentence case matches the editorial guide. description: Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on bot… → Read this workspace and its direct parent, or `parent: null` when it has no active parent. Requires workspace Admin access. The relationship does not grant access to the parent. B… responses.200.content.application/json.schema.description: The response for this operation. → Current workspace and its active direct parent, when present. responses.200.description: The workspace operation result. → Current workspace and its active direct parent, when present. Preserved: Compared operationId getWorkspaceForkLineage, GET /api/v2/workspaces/{workspaceId}/fork/lineage, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listWorkspaceForkChildren` — `GET /api/v2/workspaces/{workspaceId}/fork/children` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: List Workspace Fork Children → List workspace fork children; sentence case matches the editorial guide. description: Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on bot… → List this workspace's active direct children, newest first, with cursor pagination. Requires workspace Admin access. A fork relationship does not grant access to a child workspace… responses.200.content.application/json.schema.description: The response for this operation. → A page of active direct child workspaces. responses.200.content.application/json.schema.properties.data.items.description: The ListWorkspaceForkChildrenResult result. → An active direct child workspace. Preserved: Compared operationId listWorkspaceForkChildren, GET /api/v2/workspaces/{workspaceId}/fork/children, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listWorkspaceForkResources` — `GET /api/v2/workspaces/{workspaceId}/fork/resources` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: List Workspace Fork Resources → List workspace fork resources; sentence case matches the editorial guide. description: Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on bot… → List copyable resources of one kind in this workspace with cursor pagination. Requires workspace Admin access. Fork creation uses file IDs; sync copy choices use file storage keys… parameters[3].description: Resource or operation kind. → Kind of source resource to list for copy selection. parameters[3].schema.description: Resource or operation kind. → Kind of source resource to list for copy selection. Preserved: Compared operationId listWorkspaceForkResources, GET /api/v2/workspaces/{workspaceId}/fork/resources, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 10 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkspaceForkMappings` — `GET /api/v2/workspaces/{workspaceId}/fork/mappings` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Get Workspace Fork Mappings → Get workspace fork mappings; sentence case matches the editorial guide. description: Read persisted mappings in the requested source-to-target direction. Candidate discovery uses the destination resource and selector listing operations. Workspace API keys return `… → Read persisted resource mappings in the requested source-to-target direction along a direct fork edge. Requires Admin access to both workspaces. Discover candidates with destinati… responses.200.content.application/json.schema.description: The response for this operation. → A page of persisted source-to-target mapping entries. responses.200.content.application/json.schema.properties.data.items.description: The GetWorkspaceForkMappingsResult result. → A saved directional mapping entry. Preserved: Compared operationId getWorkspaceForkMappings, GET /api/v2/workspaces/{workspaceId}/fork/mappings, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateWorkspaceForkMappings` — `PUT /api/v2/workspaces/{workspaceId}/fork/mappings` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Update Workspace Fork Mappings → Update workspace fork mappings; sentence case matches the editorial guide. description: Update edge mappings after validating destination resource membership and credential provider compatibility. Push addresses current-to-other mappings; pull addresses other-to-curr… → Update mappings along a direct fork edge with Admin access to both workspaces. Destination resource membership and credential provider compatibility are validated. Push maps curre… requestBody.content.application/json.schema.description: The body for this operation. → Other workspace, direction, and mapping entries to update. requestBody.content.application/json.schema.properties.mappings.description: Mappings keyed by resource type and source identifier. → Mapping entries addressed by resource type and `sourceId`. `targetId: null` clears a mapping. Preserved: Compared operationId updateWorkspaceForkMappings, PUT /api/v2/workspaces/{workspaceId}/fork/mappings, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `rollbackWorkspaceFork` — `POST /api/v2/workspaces/{workspaceId}/fork/rollback` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. Kept undeployed-copy, same-workflow source state, trigger shutdown, and pending-rollback consequences close to their actions. | Verified improvement. Summary: Rollback Workspace Fork → Rollback workspace fork; sentence case matches the editorial guide. description: Restore the latest sync into this workspace using its prior deployed versions. Requires target admin. It does not restore arbitrary drafts or remove every copied resource. Pending… → Restore the latest sync into this workspace from the named other workspace using prior deployed versions. Requires target workspace Admin access. A newer sync from another fork ed… requestBody.content.application/json.schema.description: The body for this operation. → Other workspace whose latest inbound sync should be undone. requestBody.description: The body for this operation. → Other workspace whose latest inbound sync should be undone. Preserved: Compared operationId rollbackWorkspaceFork, POST /api/v2/workspaces/{workspaceId}/fork/rollback, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `unlinkWorkspaceFork` — `POST /api/v2/workspaces/{workspaceId}/fork/unlink` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Unlink Workspace Fork → Unlink workspace fork; sentence case matches the editorial guide. description: Remove the direct fork relationship and its mappings. Requires admin on the acting workspace. Existing workflow and resource content remains available. Workspace API keys return `… → Remove the direct fork relationship and its mappings with Admin access to the acting workspace. Existing workflows and resources remain available. Billing-enabled deployments requ… requestBody.content.application/json.schema.description: The body for this operation. → Other workspace on the direct fork edge to remove. requestBody.description: The body for this operation. → Other workspace on the direct fork edge to remove. Preserved: Compared operationId unlinkWorkspaceFork, POST /api/v2/workspaces/{workspaceId}/fork/unlink, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateWorkspaceForkExclusions` — `PUT /api/v2/workspaces/{workspaceId}/fork/exclusions` | corrected | Named current/source/both-side/target Admin access and qualified feature gate by billing mode rather than hosting location. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Update Workspace Fork Exclusions → Update workspace fork exclusions; sentence case matches the editorial guide. description: Include or exclude selected workflows from fork sync. Excluded workflows are skipped as sources and targets. Missing, archived, and unchanged workflow IDs are skipped. Workspace A… → Include or exclude selected workflows from fork sync with workspace Admin access. Excluded workflows are skipped as sources and targets. Missing, archived, and unchanged workflow … requestBody.content.application/json.schema.description: The body for this operation. → Workflow IDs and whether to exclude them from sync. requestBody.description: The body for this operation. → Workflow IDs and whether to exclude them from sync. Preserved: Compared operationId updateWorkspaceForkExclusions, PUT /api/v2/workspaces/{workspaceId}/fork/exclusions, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `previewWorkflowImport` — `POST /api/v2/workflows/import/preview` | corrected | Restored exact-preview choice matching and identical-request retry behavior on fields and apply intros. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Preview Workflow Import → Preview workflow import; sentence case matches the editorial guide. description: Validate destination mappings and dependent choices without creating a workflow. Returns unresolved fields, discovery instructions, and a fingerprint required by mapped import. No… → Validate destination mappings and configuration with workspace write access, without creating a workflow. The result reports readiness, unresolved fields, discovery instructions, … requestBody.content.application/json.schema.properties.dependentValues.description: Destination-dependent choices keyed by source workflow, block, and field identities. → Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated. requestBody.content.application/json.schema.properties.mappings.description: Mappings keyed by resource type and source identifier. → Mapping entries addressed by resource kind and source identifier. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId previewWorkflowImport, POST /api/v2/workflows/import/preview, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 11 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listSelector` — `POST /api/v2/selectors/list` | corrected | Documented selector cursor scope/restart, data:null, truncation and bounded verification. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: List Selector Options → List selector options; sentence case matches the editorial guide. description: List workspace-scoped configuration choices using the selector key and dependencies from an import or sync preview. Missing OAuth connections require human authorization before pr… → List authorized workspace configuration choices using the selector key and context from an import or sync preview. Requires workspace read access. Missing OAuth connections requir… requestBody.content.application/json.schema.description: The body for this operation. → Workspace, registered selector key, context, and optional search/cursor. requestBody.content.application/json.schema.properties.cursor.description: Opaque continuation cursor returned by the preceding page. → Cursor returned by the preceding page. Keep `workspaceId`, `selectorKey`, `context`, and `search` unchanged; only `limit` may change. Restart without a cursor after a changed-page… Preserved: Compared operationId listSelector, POST /api/v2/selectors/list, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 13 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getSelector` — `POST /api/v2/selectors/get` | corrected | Documented selector cursor scope/restart, data:null, truncation and bounded verification. Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Get Selector Option → Get selector option; sentence case matches the editorial guide. description: Resolve a workspace configuration option by its provider identifier and declared dependencies. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth… → Get an authorized configuration choice by provider ID and declared context with workspace read access. Returns `data: null` when the option is absent from complete results. Trunca… requestBody.content.application/json.schema.description: The body for this operation. → Workspace, registered selector key, context, and provider option ID. requestBody.content.application/json.schema.properties.id.description: Resource identifier. → Provider option ID to resolve with the same selector and declared context. Preserved: Compared operationId getSelector, POST /api/v2/selectors/get, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 10 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkspaceOperation` — `GET /api/v2/workspaces/{workspaceId}/operations/{operationId}` | rewritten | Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: Get Workspace Operation → Get workspace operation; sentence case matches the editorial guide. description: Read a committed operation, copy progress, exact deployment readiness, and structured issues. A failed follow-up does not mean the business transaction was rolled back. OAuth scop… → Read a committed operation and refresh its copy progress, exact admitted deployment readiness, and structured issues with workspace read access. `applied: true` means the transact… responses.200.content.application/json.schema.description: The response for this operation. → Refreshed commit, copy progress, and exact deployment readiness. responses.200.content.application/json.schema.properties.data.properties.copyProgress.properties.status.description: Current operation or deployment outcome. → Background resource-copy status. Preserved: Compared operationId getWorkspaceOperation, GET /api/v2/workspaces/{workspaceId}/operations/{operationId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 13 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listWorkspaceOperations` — `GET /api/v2/workspaces/{workspaceId}/operations` | rewritten | Replaced mechanical body/result text with operation-specific descriptions and human schema titles, preserving stable IDs. | Verified improvement. Summary: List Workspace Operations → List workspace operations; sentence case matches the editorial guide. description: Page committed operations newest first. Filter by the original request ID to reconcile an uncertain mutation response. OAuth scope: `api:read`. → List stored operation receipts newest first with workspace read access. Filter by the original `requestId` to reconcile an uncertain mutation response. Read an individual operatio… parameters[3].description: Stable client request ID for reconciliation and identical retries. → Find an uncertain mutation by the original client request ID; keep the same filter while paging. parameters[3].schema.description: Stable client request ID for reconciliation and identical retries. → Find an uncertain mutation by the original client request ID; keep the same filter while paging. Preserved: Compared operationId listWorkspaceOperations, GET /api/v2/workspaces/{workspaceId}/operations, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 17 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+
+### API workspace operations (108)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| `getBillingStatus` — `GET /api/v2/billing/status` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Billing Status → Get billing status; sentence case matches the editorial guide. parameters[0].description: Workspace whose payer should be resolved. A workspace API key is pinned to its own workspace: any other id answers `404 Workspace not found`, which is also what an id that does no… → Workspace whose payer to report. A workspace API key is bound to its own workspace; a different or unknown ID returns `404 Workspace not found`. Omit for account billing when usin… parameters[0].schema.description: Workspace whose payer should be resolved. A workspace API key is pinned to its own workspace: any other id answers `404 Workspace not found`, which is also what an id that does no… → Workspace whose payer to report. A workspace API key is bound to its own workspace; a different or unknown ID returns `404 Workspace not found`. Omit for account billing when usin… responses.200.content.application/json.schema.properties.data.properties.credits.anyOf[0].properties.used.description: Credits consumed so far. The counter is reset by Stripe invoice webhooks, so on a paid plan it covers the current billing period; on the free plan nothing resets it and the value … → Credits consumed during the current billing period on a paid plan, or over the account’s lifetime on Free. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getBillingStatus, GET /api/v2/billing/status, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listBillingLogs` — `GET /api/v2/billing/logs` | rewritten | Copy standardized; no operation-specific discrepancy found. Review correction: mothership_block remains the distinct Agent-block source. | Verified improvement. Summary: List Billing Logs → List billing logs; sentence case matches the editorial guide. parameters[3].description: Only include usage events recorded at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. Requires `period=custom`. A date without a time, or a timestamp carrying a… → Include events at or after this UTC ISO 8601 timestamp, for example `2026-08-06T00:00:00Z`. Required with `period=custom`. Date-only values, UTC offsets instead of `Z`, and year `… parameters[3].schema.description: Only include usage events recorded at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. Requires `period=custom`. A date without a time, or a timestamp carrying a… → Include events at or after this UTC ISO 8601 timestamp, for example `2026-08-06T00:00:00Z`. Required with `period=custom`. Date-only values, UTC offsets instead of `Z`, and year `… parameters[4].description: Only include usage events recorded at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. Requires `period=custom`, and defaults to now when omitted. A date withou… → Include events at or before this UTC ISO 8601 timestamp, for example `2026-08-06T00:00:00Z`. Allowed only with `period=custom`; omission defaults to now. Date-only values, UTC off… 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listBillingLogs, GET /api/v2/billing/logs, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listWorkspaces` — `GET /api/v2/workspaces` | corrected | Active credential-filtered 25-item default; fix sort rationale. Shared name-sort rationale corrected by root; local sort fields/defaults preserved. | Verified improvement. Summary: List Workspaces → List workspaces; sentence case matches the editorial guide. description: List active workspaces available to the calling credential with opaque cursor pagination. A personal API key or OAuth token sees accessible workspaces that permit user-held API cr… → List active workspaces available to the calling credential. Personal API keys and OAuth tokens see accessible workspaces that permit user-held API credentials; a workspace API key… parameters[0].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[0].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listWorkspaces, GET /api/v2/workspaces, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkspace` — `GET /api/v2/workspaces/{workspaceId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Workspace → Get workspace; sentence case matches the editorial guide. description: Get metadata for an accessible workspace. OAuth scope: `api:read`. → Get metadata for a workspace the calling credential can access. Requires workspace read access. OAuth scope: `api:read`. responses.200.content.application/json.schema.description: Public metadata for one workspace. → Metadata for one workspace. responses.200.description: Public workspace metadata. → Workspace metadata. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getWorkspace, GET /api/v2/workspaces/{workspaceId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listWorkspaceMembers` — `GET /api/v2/workspaces/{workspaceId}/members` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Workspace Members → List workspace members; sentence case matches the editorial guide. description: List workspace members by email, including explicit grants and inherited organization admin access. Each member includes a stable user ID for member administration. OAuth scope: `… → List effective workspace members, ordered by email, including explicit grants and inherited organization Admin access. Use each member’s `userId` for member administration. Requir… responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listWorkspaceMembers, GET /api/v2/workspaces/{workspaceId}/members, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listMcpServers` — `GET /api/v2/mcp-servers` | rewritten | Copy standardized; no operation-specific discrepancy found. Review correction: re-registration resets connection state only when connection inputs change. | Verified improvement. Summary: List MCP Servers → List MCP servers; sentence case matches the editorial guide. description: List MCP servers registered in a workspace, excluding request-header values and OAuth secrets. Connection metadata remains at registration defaults until List MCP Server Tools per… → List external MCP servers registered in the workspace. Request-header values and OAuth secrets are omitted. Connection metadata remains at registration defaults until List MCP ser… parameters[2].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[2].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listMcpServers, GET /api/v2/mcp-servers, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createMcpServer` — `POST /api/v2/mcp-servers` | rewritten | Copy standardized; no operation-specific discrepancy found. Review correction: probe outcomes include OAuth, unauthenticated success and header fallback. | Verified improvement. Summary: Create MCP Server → Create MCP server; sentence case matches the editorial guide. description: Register an external MCP server without connecting to it. A duplicate URL returns `409`; use Update MCP Server to change the existing registration. The server remains disconnected… → Register an external MCP server without establishing a tool connection; registration may probe its authentication method. A duplicate URL returns `409`; use Update MCP server to c… requestBody.content.application/json.schema.properties.authType.description: Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server … → Authentication method. If omitted without `headers`, registration probes once for OAuth protected-resource metadata (RFC 9728), otherwise falling back to `headers`. Set this field… responses.201.content.application/json.schema.properties.data.properties.connectionStatus.description: Result of the most recent connection attempt. Registration and re-registration establish no connection — the auth-type probe they may send does not count as one — so a server begi… → Result of the most recent tool connection attempt. Registration and re-registration set `disconnected`; their authentication probes do not establish a tool connection. Tool discov… 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createMcpServer, POST /api/v2/mcp-servers, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getMcpServer` — `GET /api/v2/mcp-servers/{mcpServerId}` | rewritten | Copy standardized; no operation-specific discrepancy found. Review correction: re-registration resets connection state only when connection inputs change. | Verified improvement. Summary: Get MCP Server → Get MCP server; sentence case matches the editorial guide. description: Get one MCP server by identifier. Request-header values and OAuth client secrets are never returned. OAuth scope: `api:read`. → Get a registered external MCP server. Request-header values and OAuth client secrets are omitted. Requires workspace read access. OAuth scope: `api:read`. responses.200.content.application/json.schema.properties.data.properties.connectionStatus.description: Result of the most recent connection attempt. Registration and re-registration establish no connection — the auth-type probe they may send does not count as one — so a server begi… → Result of the most recent tool connection attempt. Registration and re-registration set `disconnected`; their authentication probes do not establish a tool connection. Tool discov… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getMcpServer, GET /api/v2/mcp-servers/{mcpServerId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateMcpServer` — `PATCH /api/v2/mcp-servers/{mcpServerId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Update MCP Server → Update MCP server; sentence case matches the editorial guide. description: Update an MCP server's supplied fields. Omitted fields remain unchanged unless the field specifies otherwise. Authentication changes revoke the stored OAuth grant and reset connec… → Update an external MCP server. Omitted fields remain unchanged unless a field specifies otherwise. Authentication changes revoke its stored OAuth grant and reset connection metada… requestBody.content.application/json.schema.properties.authType.description: Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server … → Authentication method. If omitted without `headers`, registration probes once for OAuth protected-resource metadata (RFC 9728), otherwise falling back to `headers`. Set this field… responses.200.content.application/json.schema.properties.data.properties.connectionStatus.description: Result of the most recent connection attempt. Registration and re-registration establish no connection — the auth-type probe they may send does not count as one — so a server begi… → Result of the most recent tool connection attempt. Registration and re-registration set `disconnected`; their authentication probes do not establish a tool connection. Tool discov… 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateMcpServer, PATCH /api/v2/mcp-servers/{mcpServerId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteMcpServer` — `DELETE /api/v2/mcp-servers/{mcpServerId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Delete MCP Server → Delete MCP server; sentence case matches the editorial guide. description: Remove an MCP server and revoke its OAuth tokens. Workflows retain blocks that referenced the server's tools, but those tools can no longer be called. OAuth scope: `api:write`. → Remove an external MCP server and revoke its OAuth tokens. Workflow blocks retain references to its tools, but those tools can no longer be called. Requires workspace write access… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteMcpServer, DELETE /api/v2/mcp-servers/{mcpServerId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listMcpServerTools` — `GET /api/v2/mcp-servers/{mcpServerId}/tools` | corrected | Partial inventory, disabled/managed states need explicit qualifications. | Verified improvement. Summary: List MCP Server Tools → List MCP server tools; sentence case matches the editorial guide. description: Discover up to 1,000 tools within 5 MB, connect to the server, and update connection metadata. Results are unpaginated. Invalid OAuth returns `409` with `MCP_SERVER_REAUTHORIZATIO… → Discover tools on an enabled external MCP server and update connection metadata. Discovery is bounded by 1,000 tools, 5 MiB, 50 upstream pages, and 60 seconds; limits or later-pag… responses.200.content.application/json.schema.description: Tools exposed by the MCP server. → Tools discovered so far. Limits or later-page failures can leave the inventory incomplete; the response has no truncation indicator or pagination. responses.200.content.application/json.schema.properties.nextCursor.description: Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change. → Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listMcpServerTools, GET /api/v2/mcp-servers/{mcpServerId}/tools, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listSkills` — `GET /api/v2/skills` | corrected | Bodies omitted/built-ins IDs/epochs verified; fix sort rationale. Shared name-sort rationale corrected by root; local sort fields/defaults preserved. | Verified improvement. Summary: List Skills → List skills; sentence case matches the editorial guide. description: List workspace and built-in skills with cursor pagination. Built-in skills are read-only. The list omits skill bodies; use Get Skill to read content. OAuth scope: `api:read`. → List workspace and built-in skills with cursor pagination. Built-in skills are read-only. Skill bodies are omitted; use Get skill to read content. Requires workspace read access. … parameters[2].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[2].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listSkills, GET /api/v2/skills, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createSkill` — `POST /api/v2/skills` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Skill → Create skill; sentence case matches the editorial guide. description: Create one skill in a workspace. Its kebab-case name must be unique and cannot be reserved by a built-in skill. Workspace API keys return `403`; use a personal API key or scoped O… → Create a workspace skill with a unique kebab-case name that is not reserved by a built-in skill. Requires workspace write access. Workspace API keys return `403`; use a personal A… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createSkill, POST /api/v2/skills, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getSkill` — `GET /api/v2/skills/{skillId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Skill → Get skill; sentence case matches the editorial guide. description: Get one workspace or built-in skill, including its full content. Built-in skills are marked read-only. OAuth scope: `api:read`. → Get a workspace or built-in skill, including its full instructions. Built-in skills are read-only. Requires workspace read access. OAuth scope: `api:read`. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getSkill, GET /api/v2/skills/{skillId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateSkill` — `PATCH /api/v2/skills/{skillId}` | corrected | Omission correct; missing editor requirement. | Verified improvement. Summary: Update Skill → Update skill; sentence case matches the editorial guide. description: Update a workspace skill. Omitted fields remain unchanged. Built-in skills are read-only. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scop… → Update a workspace skill. Omitted fields remain unchanged. Requires skill editor or workspace Admin access; workspace write access alone does not grant editor access. Built-in ski… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateSkill, PATCH /api/v2/skills/{skillId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteSkill` — `DELETE /api/v2/skills/{skillId}` | corrected | Built-in refusal verified; missing editor requirement. | Verified improvement. Summary: Delete Skill → Delete skill; sentence case matches the editorial guide. description: Delete a workspace skill. Built-in skills are read-only and cannot be deleted. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:wri… → Delete a workspace skill. Requires skill editor or workspace Admin access. Built-in skills cannot be deleted. Workspace API keys return `403`; use a personal API key or scoped OAu… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteSkill, DELETE /api/v2/skills/{skillId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listSkillEditors` — `GET /api/v2/skills/{skillId}/editors` | corrected | Built-in empty result and in-memory ordering need explicit copy. Shared name-sort rationale corrected by root; local sort fields/defaults preserved. | Verified improvement. Summary: List Skill Editors → List skill editors; sentence case matches the editorial guide. description: List skill editors and workspace administrators with cursor pagination. OAuth scope: `api:read`. → List explicit skill editors and workspace Admins with cursor pagination. Built-in skills return an empty list. Requires workspace read access. OAuth scope: `api:read`. parameters[2].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[2].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listSkillEditors, GET /api/v2/skills/{skillId}/editors, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `grantSkillEditor` — `POST /api/v2/skills/{skillId}/editors` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Grant Skill Editor → Grant skill editor; sentence case matches the editorial guide. description: Grant skill editor access to a workspace member by email. Requires an existing editor or workspace admin; admins already have access and cannot receive explicit grants. Existing g… → Grant skill editor access to a current workspace member by email. Requires an existing skill editor or workspace Admin. Workspace Admins already have derived access and cannot rec… responses.200.content.application/json.schema.description: Public identity fields for the editor. → Identity fields for the editor. responses.201.content.application/json.schema.description: Public identity fields for the editor. → Identity fields for the editor. 3 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId grantSkillEditor, POST /api/v2/skills/{skillId}/editors, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `revokeSkillEditor` — `DELETE /api/v2/skills/{skillId}/editors` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Revoke Skill Editor → Revoke skill editor; sentence case matches the editorial guide. description: Revoke an explicit editor grant by email. The caller must already be a skill editor or workspace administrator. Workspace administrators have derived access that cannot be revoked… → Revoke an explicit skill editor grant by email. Requires an existing skill editor or workspace Admin. Workspace Admins have derived access that cannot be revoked. Workspace API ke… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId revokeSkillEditor, DELETE /api/v2/skills/{skillId}/editors, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listCustomTools` — `GET /api/v2/custom-tools` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Custom Tools → List custom tools; sentence case matches the editorial guide. description: List code-backed custom tools in a workspace with cursor pagination. OAuth scope: `api:read`. → List code-backed custom tools in the workspace with cursor pagination. Each entry includes its declaration and implementation. Requires workspace read access. OAuth scope: `api:re… responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listCustomTools, GET /api/v2/custom-tools, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createCustomTool` — `POST /api/v2/custom-tools` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Custom Tool → Create custom tool; sentence case matches the editorial guide. description: Create a code-backed custom tool in a workspace. Its title must be unique because tools resolve by title at call time. OAuth scope: `api:write`. → Create a code-backed custom tool. Its title must be unique within the workspace because tools resolve by title at call time. Requires workspace write access. OAuth scope: `api:wri… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createCustomTool, POST /api/v2/custom-tools, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getCustomTool` — `GET /api/v2/custom-tools/{customToolId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Custom Tool → Get custom tool; sentence case matches the editorial guide. description: Get one custom tool by identifier, scoped to its workspace. OAuth scope: `api:read`. → Get a custom tool’s declaration and code by identifier, scoped to its workspace. Requires workspace read access. OAuth scope: `api:read`. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getCustomTool, GET /api/v2/custom-tools/{customToolId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateCustomTool` — `PATCH /api/v2/custom-tools/{customToolId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Update Custom Tool → Update custom tool; sentence case matches the editorial guide. description: Update a custom tool. Omitted fields remain unchanged; titles must remain unique within the workspace. OAuth scope: `api:write`. → Update a custom tool. Omitted fields remain unchanged; supplied schemas and code replace the stored versions. Titles must remain unique within the workspace. Requires workspace wr… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateCustomTool, PATCH /api/v2/custom-tools/{customToolId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteCustomTool` — `DELETE /api/v2/custom-tools/{customToolId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Delete Custom Tool → Delete custom tool; sentence case matches the editorial guide. description: Delete a custom tool. Agent blocks retain their configuration but can no longer call the deleted tool. OAuth scope: `api:write`. → Delete a custom tool. Agent blocks retain their configuration but can no longer call the deleted tool. Requires workspace write access. OAuth scope: `api:write`. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteCustomTool, DELETE /api/v2/custom-tools/{customToolId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listSandboxes` — `GET /api/v2/sandboxes` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Sandboxes → List sandboxes; sentence case matches the editorial guide. description: List reusable dependency environments for Function blocks, including language packages, managed CLIs, and system packages. Sandboxes remain visible after a plan downgrade. OAuth s… → List reusable dependency environments for Function blocks, including language packages, managed CLIs, and system packages. Requires workspace read access. Existing sandboxes remai… parameters[2].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[2].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listSandboxes, GET /api/v2/sandboxes, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createSandbox` — `POST /api/v2/sandboxes` | corrected | Build state/rate budget correct; deployment entitlement qualification. | Verified improvement. Summary: Create Sandbox → Create sandbox; sentence case matches the editorial guide. description: Create a uniquely named dependency environment. If a build is needed, track readiness with `buildStatus`; null means no build is required. Invalid dependencies return `400` with f… → Create a uniquely named dependency environment. Requires workspace Admin access and a configured remote Function runtime. With billing enabled, Max or Enterprise is required unles… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createSandbox, POST /api/v2/sandboxes, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getSandbox` — `GET /api/v2/sandboxes/{sandboxId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Get Sandbox → Get sandbox; sentence case matches the editorial guide. description: Get one sandbox by identifier, scoped to its workspace, including its current build state and any build failure. OAuth scope: `api:read`. → Get a sandbox’s dependency configuration, current build state, and any build failure. Requires workspace read access. OAuth scope: `api:read`. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getSandbox, GET /api/v2/sandboxes/{sandboxId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateSandbox` — `PATCH /api/v2/sandboxes/{sandboxId}` | corrected | List replacement/spec retry/build state correct; deployment qualification. | Verified improvement. Summary: Update Sandbox → Update sandbox; sentence case matches the editorial guide. description: Update a sandbox, preserving omitted fields and replacing supplied lists. Dependency changes may start a build; resending a failed specification retries its build. `buildStatus: n… → Update a sandbox; omitted fields stay unchanged and supplied lists replace their contents. Dependency changes may start a build; resending a failed specification retries it. `buil… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateSandbox, PATCH /api/v2/sandboxes/{sandboxId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteSandbox` — `DELETE /api/v2/sandboxes/{sandboxId}` | corrected | Dependent Function failure correct; deployment qualification. | Verified improvement. Summary: Delete Sandbox → Delete sandbox; sentence case matches the editorial guide. description: Delete a sandbox. Function blocks using it fail until reconfigured. Requires workspace admin access on Max or Enterprise. Workspace API keys return `403`; use a personal API key o… → Delete a sandbox. Function blocks using it fail until reconfigured. Requires workspace Admin access and sandbox entitlement: with billing enabled, Max or Enterprise is required un… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteSandbox, DELETE /api/v2/sandboxes/{sandboxId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listCredentials` — `GET /api/v2/credentials` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Credentials → List credentials; sentence case matches the editorial guide. description: List OAuth and service-account connections visible to the caller. Secret material is never returned. OAuth scope: `api:read`. → List OAuth and service-account connections visible to the caller. Requires workspace read access. Stored tokens, keys, and service-account payloads are omitted. OAuth scope: `api:… responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listCredentials, GET /api/v2/credentials, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createServiceAccountCredential` — `POST /api/v2/credentials` | corrected | Provider verification/dedup status correct; emitted default body invalid. Existing valid encoded service-account body retained; root owns publishing metadata examples in shared generator. | Verified improvement. Summary: Create Service-Account Credential → Create service-account credential; sentence case matches the editorial guide. description: Verify and store a service-account credential using the fields from List Credential Providers, encoded as a JSON object string in `credentials`. Secrets are never returned. A matc… → Verify and store a service-account credential. Use the fields from List credential providers, encoded as a JSON object string in `credentials`. Requires workspace write access. A … responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 3 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createServiceAccountCredential, POST /api/v2/credentials, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listCredentialProviders` — `GET /api/v2/credentials/providers` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Credential Providers → List credential providers; sentence case matches the editorial guide. description: List OAuth and service-account connection methods and their availability. OAuth options provide provider IDs for browser connections; service-account methods declare required fiel… → List OAuth and service-account connection methods and their availability. OAuth options provide provider IDs for browser connections; service-account methods declare required fiel… responses.200.content.application/json.schema.properties.nextCursor.description: Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change. → Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listCredentialProviders, GET /api/v2/credentials/providers, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createCredentialConnection` — `POST /api/v2/credentials/connections` | corrected | Correct acting-user browser flow; body intro contradicts QuickBooks/scope. Required workspaceId and QuickBooks oauthClientConfig documented; valid new, reconnect, and QuickBooks body examples supplied. | Verified improvement. Summary: Create Credential Connection → Create credential connection; sentence case matches the editorial guide. description: Create a short-lived browser URL for connecting an OAuth provider or reconnecting an existing OAuth credential. Open the URL, sign in as the authenticated user, complete provider … → Create a short-lived browser URL to connect an OAuth provider or reconnect a credential. Requires workspace write access; reconnecting also requires credential Admin access. Open … requestBody.content.application/json.schema.description: For a new connection, provide providerId and displayName. For a reconnect, provide only credentialId; the existing display name is preserved. → Provide workspaceId for every flow. For a new connection, send providerId and displayName; for a reconnect, send credentialId and retain the existing name. QuickBooks also require… requestBody.description: For a new connection, provide providerId and displayName. For a reconnect, provide only credentialId; the existing display name is preserved. → Provide workspaceId for every flow. For a new connection, send providerId and displayName; for a reconnect, send credentialId and retain the existing name. QuickBooks also require… 3 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createCredentialConnection, POST /api/v2/credentials/connections, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteCredential` — `DELETE /api/v2/credentials/{credentialId}` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Disconnect Credential → Disconnect credential; sentence case matches the editorial guide. description: Disconnect an OAuth or service-account credential and clear its stored workflow, deployment, paused-run, knowledge-connector, and webhook references. Credential admin access is re… → Disconnect an OAuth or service-account credential and clear its stored workflow, deployment, paused-run, knowledge-connector, and webhook references. Requires credential Admin acc… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteCredential, DELETE /api/v2/credentials/{credentialId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateCredential` — `PATCH /api/v2/credentials/{credentialId}` | corrected | Metadata supports OAuth; secret replacement/required fields contradict copy. Partial metadata distinguished from provider-secret replacement; metadata-only and complete Zoom rotation examples supplied. | Verified improvement. Summary: Update Credential → Update credential; sentence case matches the editorial guide. description: Rename a service-account credential or rotate its secret fields, preserving omitted values and the credential ID. Requires credential admin access. Provider rejection preserves th… → Rename an OAuth or service-account credential, change its description, or rotate a service-account secret. Omitted metadata remains unchanged. Rotation requires the provider’s req… requestBody.content.application/json.schema.description: Replacement display metadata and the write-only fields declared by provider discovery. → Metadata fields to change, or the complete required fields for a service-account secret rotation. Use List credential providers for the selected provider’s fields. requestBody.description: Replacement display metadata and the write-only fields declared by provider discovery. → Metadata fields to change, or the complete required fields for a service-account secret rotation. Use List credential providers for the selected provider’s fields. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateCredential, PATCH /api/v2/credentials/{credentialId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listSecrets` — `GET /api/v2/secrets` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: List Secrets → List secrets; sentence case matches the editorial guide. description: List workspace and caller-owned personal secrets with cursor pagination. Only workspace secrets marked `unredacted` include values; all other entries contain metadata only. Worksp… → List workspace secrets visible to the caller and caller-owned personal secrets. Only workspace secrets marked `unredacted` can include values; every other entry contains metadata … parameters[3].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[3].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listSecrets, GET /api/v2/secrets, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `setSecret` — `PUT /api/v2/secrets/{name}` | corrected | Value-less existing workspace metadata/201 creation correct; missing resource authority. | Verified improvement. Summary: Set Secret → Set secret; sentence case matches the editorial guide. description: Create or replace a workspace or personal secret without returning its value. For existing workspace secrets, omit `value` to update metadata only; this returns `404` if absent. P… → Create or replace a workspace or caller-owned personal secret. New workspace secrets require workspace write access; existing ones require workspace Admin or secret Admin access. … requestBody.content.application/json.schema.properties.value.description: Write-only secret value. It is never returned. Omit it on a workspace secret to change description or unredacted alone, leaving the stored value untouched; the secret must already… → Secret value, omitted from the Set secret response. For an existing workspace secret, omit it to change only `description` or `unredacted`. Personal secrets always require a value… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 3 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId setSecret, PUT /api/v2/secrets/{name}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteSecret` — `DELETE /api/v2/secrets/{name}` | corrected | User-global deletion scope correct; missing resource authority. | Verified improvement. Summary: Delete Secret → Delete secret; sentence case matches the editorial guide. description: Delete a workspace or caller-owned personal secret without reading or returning its stored value. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OA… → Delete a workspace or caller-owned personal secret without returning its value. Workspace secrets require workspace Admin or secret Admin access. Deleting a personal secret remove… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteSecret, DELETE /api/v2/secrets/{name}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getApiMeta` — `GET /api/v2/meta` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Get API Capabilities → Get API status; sentence case matches the editorial guide. description: Get whether v2 is available, what kind of API credential is calling, and when it expires. Requires a valid API key or OAuth access token. OAuth scope: `api:read`. → Get the calling credential’s type and expiry. Requires a valid API key or OAuth access token. `v2Enabled` is true whenever this endpoint is served; the response does not enumerate… responses.200.content.application/json.schema.properties.data.properties.keyType.description: Whether the calling credential is a personal API key carrying the full authority of its owner across their workspaces, a key scoped to one workspace, or an OAuth access token acti… → Calling credential kind: a personal API key acting for its owner, a key bound to one workspace, or an OAuth access token acting for its user within granted scopes. Resource permis… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getApiMeta, GET /api/v2/meta, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listWorkflowMcpServers` — `GET /api/v2/workflow-mcp-servers` | corrected | 2,000-name cap also undercounts toolCount. | Verified improvement. Summary: List Workflow MCP Servers → List workflow MCP servers; sentence case matches the editorial guide. description: List MCP servers that expose deployed workflows to external clients. Use List MCP Servers for external servers Sim calls. Tool names share a 2,000-name page limit; inspect `toolNa… → List MCP servers that expose deployed workflows to external clients. Use List MCP servers for external servers Sim calls. Requires workspace read access. Tool names share a 2,000-… parameters[0].description: Workspace whose published MCP servers to list. → Workspace whose workflow MCP servers to list. parameters[0].schema.description: Workspace whose published MCP servers to list. → Workspace whose workflow MCP servers to list. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listWorkflowMcpServers, GET /api/v2/workflow-mcp-servers, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 16 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createWorkflowMcpServer` — `POST /api/v2/workflow-mcp-servers` | corrected | Public execution consequence/deployed inputs correct; add admin role. | Verified improvement. Summary: Create Workflow MCP Server → Create workflow MCP server; sentence case matches the editorial guide. description: Create an MCP server that exposes deployed workflows as tools. Every supplied workflow must already be deployed. With `isPublic: true`, anyone with the server URL can execute its … → Create an MCP server exposing deployed workflows as tools. Every supplied workflow must already be deployed. With `isPublic: true`, anyone holding the server URL can execute its w… requestBody.content.application/json.schema.description: A new workspace-published MCP server and the workflows it exposes. → A new workflow MCP server and deployed workflows to expose as tools. requestBody.content.application/json.schema.properties.isPublic.description: Whether the server answers MCP clients without a Sim API key. Defaults to false — a public server executes the workflows it publishes for anyone holding its URL. → Whether the server accepts MCP clients without a Sim API key. Defaults to false; a public server lets anyone holding its URL execute the workflows it exposes. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createWorkflowMcpServer, POST /api/v2/workflow-mcp-servers, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 13 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkflowMcpServer` — `GET /api/v2/workflow-mcp-servers/{serverId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Get Workflow MCP Server → Get workflow MCP server; sentence case matches the editorial guide. description: Get a published workflow MCP server's metadata and client endpoint. Use List Workflow MCP Tools for its tool inventory. Workspace API keys return `403`; use a personal API key or … → Get a workflow MCP server’s metadata and client endpoint. Use List workflow MCP tools for its inventory. Requires workspace read access. Workspace API keys return `403`; use a per… responses.200.content.application/json.schema.description: A single published MCP server. → One workflow MCP server and its client endpoint. responses.200.content.application/json.schema.properties.data.properties.mcpServerUrl.description: Endpoint an MCP client connects to. Published here so callers never build it. → MCP client endpoint. Use this returned URL instead of constructing one. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getWorkflowMcpServer, GET /api/v2/workflow-mcp-servers/{serverId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateWorkflowMcpServer` — `PATCH /api/v2/workflow-mcp-servers/{serverId}` | corrected | Partial fields/null/public effect correct; admin role and patch label. | Verified improvement. Summary: Update Workflow MCP Server → Update workflow MCP server; sentence case matches the editorial guide. description: Update a workflow MCP server's name, description, or public access. Omitted fields remain unchanged; `description: null` clears the description. Publish or unpublish tools separat… → Update a workflow MCP server’s name, description, or public access. Omitted fields stay unchanged; `description: null` clears the description. With `isPublic: true`, anyone holdin… requestBody.content.application/json.schema.description: Merge-patch body for a published MCP server. → Server fields to change. Omitted fields remain unchanged; `description: null` clears the description. requestBody.description: Merge-patch body for a published MCP server. → Server fields to change. Omitted fields remain unchanged; `description: null` clears the description. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateWorkflowMcpServer, PATCH /api/v2/workflow-mcp-servers/{serverId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteWorkflowMcpServer` — `DELETE /api/v2/workflow-mcp-servers/{serverId}` | corrected | Underlying workflow API remains deployed; add admin role/Deploy terminology. | Verified improvement. Summary: Delete Workflow MCP Server → Delete workflow MCP server; sentence case matches the editorial guide. description: Delete a workflow MCP server and stop serving its tools. The underlying workflows remain deployed and executable through the workflow API. Workspace API keys return `403`; use a p… → Delete a workflow MCP server and stop serving its tools. Its workflows remain deployed and executable through the workflow API. Requires workspace Admin access. Workspace API keys… responses.200.content.application/json.schema.description: Acknowledgement that the MCP server was unpublished. → Acknowledgement that the workflow MCP server was deleted. responses.200.content.application/json.schema.properties.data.properties.deleted.description: Whether the server was unpublished. → Whether the workflow MCP server was deleted. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deleteWorkflowMcpServer, DELETE /api/v2/workflow-mcp-servers/{serverId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listWorkflowMcpTools` — `GET /api/v2/workflow-mcp-servers/{serverId}/tools` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: List Workflow MCP Tools → List workflow MCP tools; sentence case matches the editorial guide. description: List published tools ordered by name, including the `workflowId` used to delete each registration. Undeploying a workflow makes its registrations `inactive`; redeploying reactivat… → List tool registrations ordered by name, including the `workflowId` used to remove each registration. Undeploying a workflow makes its registrations `inactive`; redeploying reacti… responses.200.content.application/json.schema.description: The tools a published MCP server exposes. → A bounded inventory of tool registrations on the workflow MCP server. responses.200.content.application/json.schema.properties.data.items.description: A tool a server publishes, as returned by a read. Archived registrations are included with `status: "inactive"`. → A tool registration on a workflow MCP server. Archived registrations are included with `status: "inactive"`. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listWorkflowMcpTools, GET /api/v2/workflow-mcp-servers/{serverId}/tools, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 11 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deployWorkflowMcpTool` — `POST /api/v2/workflow-mcp-servers/{serverId}/tools` | corrected | Per-workflow replacement, deployed schema, overrides and 200/updated verified; admin role. | Verified improvement. Summary: Publish Workflow As MCP Tool → Deploy workflow as MCP tool; sentence case matches the editorial guide. description: Publish a deployed workflow as an MCP tool using its deployed input schema. Each server has at most one tool per workflow; repeating the call replaces that tool and returns `200` … → Deploy a workflow as an MCP tool using its deployed input schema. The workflow must already be deployed. Each server has at most one tool per workflow; repeating the call replaces… requestBody.content.application/json.schema.description: The workflow to publish and the tool metadata MCP clients see. → The deployed workflow and tool metadata presented to MCP clients. requestBody.content.application/json.schema.properties.workflowId.description: Deployed workflow to publish. The workflow must already be deployed. → Workflow to expose as an MCP tool. It must already be deployed. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deployWorkflowMcpTool, POST /api/v2/workflow-mcp-servers/{serverId}/tools, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 12 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `undeployWorkflowMcpTool` — `DELETE /api/v2/workflow-mcp-servers/{serverId}/tools/{workflowId}` | corrected | Workflow API remains active; add admin role/Undeploy terminology. | Verified improvement. Summary: Unpublish Workflow MCP Tool → Undeploy workflow MCP tool; sentence case matches the editorial guide. description: Unpublish an MCP tool by its workflow ID. The workflow's API deployment remains active. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope:… → Remove an MCP tool registration by its workflow ID. The workflow’s API deployment remains active. Requires workspace Admin access. Workspace API keys return `403`; use a personal … parameters[1].description: Workflow published as a tool on this server. → Workflow registered as an MCP tool on this server. parameters[1].schema.description: Workflow published as a tool on this server. → Workflow registered as an MCP tool on this server. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId undeployWorkflowMcpTool, DELETE /api/v2/workflow-mcp-servers/{serverId}/tools/{workflowId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listBlocks` — `GET /api/v2/blocks` | corrected | Visible registry/source/preview/sunset/capability rules verified; sort rationale. Shared name-sort rationale corrected by root; local sort fields/defaults preserved. | Verified improvement. Summary: List Blocks → List blocks; sentence case matches the editorial guide. parameters[6].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[6].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listBlocks, GET /api/v2/blocks, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getBlock` — `GET /api/v2/blocks/{blockId}` | corrected | Resolved visible version/hidden 404/field projection verified; direct-input context. | Verified improvement. Summary: Get Block → Get block; sentence case matches the editorial guide. parameters[0].description: Block type identifier. An unversioned base type resolves to the newest version, and the response echoes the resolved id. → Block type identifier. An unversioned base type resolves to the newest visible version. The response echoes the resolved ID. parameters[0].schema.description: Block type identifier. An unversioned base type resolves to the newest version, and the response echoes the resolved id. → Block type identifier. An unversioned base type resolves to the newest visible version. The response echoes the resolved ID. responses.200.content.application/json.schema.properties.data.properties.operations.additionalProperties.properties.inputs.additionalProperties.properties.visibility.description: Who may supply the value: `user-or-llm`, `user-only`, `llm-only`, or `hidden`. → Source of the value in a workflow or Agent block: `user-or-llm`, `user-only`, `llm-only`, or `hidden`. A direct Run tool caller may supply non-hidden parameters; Sim supplies hidd… 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getBlock, GET /api/v2/blocks/{blockId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 40 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. Optional reactiveCondition fields are upstream source changes already present in origin/staging; their requiredType/watchFields shape is preserved. |
+| `listTools` — `GET /api/v2/tools` | corrected | Visible block-exposed built-ins/hosting/filter rules verified; sort rationale. Shared name-sort rationale corrected by root; local sort fields/defaults preserved. | Verified improvement. Summary: List Tools → List tools; sentence case matches the editorial guide. parameters[4].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[4].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. responses.200.content.application/json.schema.properties.data.items.properties.hostedApiKey.description: Whether Sim supplies the API key on THIS deployment: `always`, `conditional` (only for some parameter combinations), or `none` (bring your own). Self-hosted deployments supply no … → API-key hosting on this deployment: `always`, `conditional` for some parameter combinations, or `none` when the caller must supply a key. Self-hosted deployments report `none` for… 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listTools, GET /api/v2/tools, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getTool` — `GET /api/v2/tools/{toolId}` | corrected | Exact visible ID vs newest visible resolution needs correction. | Verified improvement. Summary: Get Tool → Get tool; sentence case matches the editorial guide. description: Get a built-in tool's parameters and outputs. Registered IDs resolve exactly; other names resolve to the newest family version. The returned `id` identifies the resolved tool. Hid… → Get a built-in tool’s parameters and outputs. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The returned `id` identifies that… parameters[0].description: Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id. → Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID. parameters[0].schema.description: Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id. → Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getTool, GET /api/v2/tools/{toolId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `executeTool` — `POST /api/v2/tools/{toolId}/execute` | corrected | 200 failed outcome/hosted billing correct; direct-input/credential caveats. | Verified improvement. Summary: Run Tool → Run tool; sentence case matches the editorial guide. description: Run a built-in tool using published parameter IDs. Sim resolves `credentialId`, hosted keys, and whole-value `{{VAR_NAME}}` references for `user-only` parameters; other values pas… → Run a built-in tool using published parameter IDs. Requires workspace read access. Sim resolves `credentialId`, hosted keys, and whole-value `{{VAR_NAME}}` references in `user-onl… parameters[0].description: Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id. → Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID. parameters[0].schema.description: Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id. → Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId executeTool, POST /api/v2/tools/{toolId}/execute, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 12 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listConnectorTypes` — `GET /api/v2/connector-types` | corrected | Projection/25 default/canonical keys correct; workspace filter statement false. | Verified improvement. Summary: List Connector Types → List connector types; sentence case matches the editorial guide. description: List knowledge-base connector types with opaque cursors, defaulting to 25 summaries per page: identifier, name, description, and auth mode. `detail=full` adds accepted source conf… → List connector types from the deployment’s knowledge-base connector registry. Requires workspace read access and Knowledge Base access; workspace integration allowlists and reveal… parameters[0].description: Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains. → Workspace used to authorize Knowledge Base access to the deployment’s connector-type registry. Workspace integration allowlists and revealed preview blocks do not filter this cata… parameters[0].schema.description: Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains. → Workspace used to authorize Knowledge Base access to the deployment’s connector-type registry. Workspace integration allowlists and revealed preview blocks do not filter this cata… 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Complete Google Drive summary/full examples now match current canonical meta and exact public projection: auth/drive, seven fields, google.drive picker, folderId manual input, typed tags, false incremental-sync flag, and exact UI labels. Preserved: Compared operationId listConnectorTypes, GET /api/v2/connector-types, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. Generated full media example equals final-connector-example.json exactly; public response envelope/schema unchanged. |
+| `listPermissionGroups` — `GET /api/v2/organizations/{organizationId}/permission-groups` | corrected | Schema, operation policy and current response verified; clarify generic labels. | Verified improvement. Summary: List Permission Groups → List permission groups; sentence case matches the editorial guide. parameters[2].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[2].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. responses.200.content.application/json.schema.description: List Permission Groups result. → A page of permission groups with resolved settings. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listPermissionGroups, GET /api/v2/organizations/{organizationId}/permission-groups, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 13 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createPermissionGroup` — `POST /api/v2/organizations/{organizationId}/permission-groups` | corrected | Schema, operation policy and current response verified; clarify generic labels. | Verified improvement. Summary: Create Permission Group → Create permission group; sentence case matches the editorial guide. requestBody.content.application/json.schema.description: Create Permission Group inputs. → Group name, initial restrictions, and default or workspace-specific scope. requestBody.content.application/json.schema.properties.config.properties.hideDeployChatbot.description: Prevent publishing a workflow as a chat. → Prevent deploying a workflow as a chat. requestBody.description: Create Permission Group inputs. → Group name, initial restrictions, and default or workspace-specific scope. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createPermissionGroup, POST /api/v2/organizations/{organizationId}/permission-groups, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 13 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getPermissionGroup` — `GET /api/v2/organizations/{organizationId}/permission-groups/{groupId}` | corrected | Schema, operation policy and current response verified; clarify generic labels. | Verified improvement. Summary: Get Permission Group → Get permission group; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: Get Permission Group result. → The group, its resolved settings, and workspace scope. responses.200.content.application/json.schema.properties.data.properties.config.properties.hideDeployChatbot.description: Prevent publishing a workflow as a chat. → Prevent deploying a workflow as a chat. responses.200.content.application/json.schema.properties.data.properties.isDefault.description: Whether this is the organization default, which applies to everyone across all its workspaces regardless of member assignments. → Whether this is the organization fallback group. It governs a human caller with no applicable workspace-specific group; its own membership assignments do not limit its audience. O… 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getPermissionGroup, GET /api/v2/organizations/{organizationId}/permission-groups/{groupId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updatePermissionGroup` — `PATCH /api/v2/organizations/{organizationId}/permission-groups/{groupId}` | corrected | Schema, operation policy and current response verified; clarify generic labels. | Verified improvement. Summary: Update Permission Group → Update permission group; sentence case matches the editorial guide. requestBody.content.application/json.schema.description: Update Permission Group inputs. → Group fields and restriction keys to change; supplied lists replace their contents. requestBody.content.application/json.schema.properties.config.properties.hideDeployChatbot.description: Prevent publishing a workflow as a chat. → Prevent deploying a workflow as a chat. requestBody.description: Update Permission Group inputs. → Group fields and restriction keys to change; supplied lists replace their contents. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updatePermissionGroup, PATCH /api/v2/organizations/{organizationId}/permission-groups/{groupId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 13 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deletePermissionGroup` — `DELETE /api/v2/organizations/{organizationId}/permission-groups/{groupId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Delete Permission Group → Delete permission group; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: Delete Permission Group result. → Acknowledgement that the group and its assignments were deleted. responses.200.description: Delete Permission Group result. → Acknowledgement that the group and its assignments were deleted. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId deletePermissionGroup, DELETE /api/v2/organizations/{organizationId}/permission-groups/{groupId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listPermissionGroupMembers` — `GET /api/v2/organizations/{organizationId}/permission-groups/{groupId}/members` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: List Permission Group Members → List permission group members; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: List Permission Group Members result. → A page of explicit group membership assignments. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.200.description: List Permission Group Members result. → A page of explicit group membership assignments. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listPermissionGroupMembers, GET /api/v2/organizations/{organizationId}/permission-groups/{groupId}/members, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `addPermissionGroupMember` — `POST /api/v2/organizations/{organizationId}/permission-groups/{groupId}/members` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Add Permission Group Member → Add permission group member; sentence case matches the editorial guide. requestBody.content.application/json.schema.description: Add Permission Group Member inputs. → The organization member to assign to this group. requestBody.description: Add Permission Group Member inputs. → The organization member to assign to this group. responses.201.content.application/json.schema.description: Add Permission Group Member result. → The new explicit membership assignment. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId addPermissionGroupMember, POST /api/v2/organizations/{organizationId}/permission-groups/{groupId}/members, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `removePermissionGroupMember` — `DELETE /api/v2/organizations/{organizationId}/permission-groups/{groupId}/members/{userId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Remove Permission Group Member → Remove permission group member; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: Remove Permission Group Member result. → Acknowledgement that the explicit assignment was removed. responses.200.description: Remove Permission Group Member result. → Acknowledgement that the explicit assignment was removed. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId removePermissionGroupMember, DELETE /api/v2/organizations/{organizationId}/permission-groups/{groupId}/members/{userId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `bulkAddPermissionGroupMembers` — `POST /api/v2/organizations/{organizationId}/permission-groups/{groupId}/members/bulk` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Bulk Add Permission Group Members → Bulk add permission group members; sentence case matches the editorial guide. requestBody.content.application/json.schema.description: Bulk Add Permission Group Members inputs. → Selected organization members or the entire current organization roster. requestBody.description: Bulk Add Permission Group Members inputs. → Selected organization members or the entire current organization roster. responses.200.content.application/json.schema.description: Bulk Add Permission Group Members result. → Counts of added members and existing assignments skipped. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId bulkAddPermissionGroupMembers, POST /api/v2/organizations/{organizationId}/permission-groups/{groupId}/members/bulk, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listOrganizations` — `GET /api/v2/organizations` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: List Organizations → List organizations; sentence case matches the editorial guide. parameters[1].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[1].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. responses.200.content.application/json.schema.description: List Organizations result. → A page of organizations and the acting user’s role in each. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listOrganizations, GET /api/v2/organizations, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getOrganization` — `GET /api/v2/organizations/{organizationId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: Get Organization → Get organization; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: Get Organization result. → Organization metadata and the acting user’s role. responses.200.description: Get Organization result. → Organization metadata and the acting user’s role. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getOrganization, GET /api/v2/organizations/{organizationId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listOrganizationWorkspaces` — `GET /api/v2/organizations/{organizationId}/workspaces` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: List Organization Workspaces → List organization workspaces; sentence case matches the editorial guide. description: List active workspaces owned by the organization. Requires organization administrator access; does not require Access Control. Workspace API keys return `403`; use a personal API … → List active workspaces owned by the organization. Requires organization Admin access; does not require Access Control. Workspace API keys return `403`; use a personal API key or s… parameters[2].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[2].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listOrganizationWorkspaces, GET /api/v2/organizations/{organizationId}/workspaces, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listOrganizationMembers` — `GET /api/v2/organizations/{organizationId}/members` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: List Organization Members → List organization members; sentence case matches the editorial guide. parameters[2].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[2].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. responses.200.content.application/json.schema.description: List Organization Members result. → A page of organization members and their organization roles. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listOrganizationMembers, GET /api/v2/organizations/{organizationId}/members, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateOrganizationMember` — `PATCH /api/v2/organizations/{organizationId}/members/{userId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Update Organization Member → Update organization member; sentence case matches the editorial guide. description: Change a member’s organization role. Requires organization administrator access. The owner’s role and memberships managed by an identity provider cannot be changed here. Workspace… → Change a member’s organization role. Requires organization Admin access. The owner’s role and memberships managed by an identity provider cannot be changed here. Workspace API key… requestBody.content.application/json.schema.description: Update Organization Member input. → The new organization role for this member. requestBody.description: Update Organization Member input. → The new organization role for this member. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateOrganizationMember, PATCH /api/v2/organizations/{organizationId}/members/{userId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `removeOrganizationMember` — `DELETE /api/v2/organizations/{organizationId}/members/{userId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Remove Organization Member → Remove organization member; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: Remove Organization Member result. → Acknowledgement that organization access was removed. responses.200.description: Remove Organization Member result. → Acknowledgement that organization access was removed. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId removeOrganizationMember, DELETE /api/v2/organizations/{organizationId}/members/{userId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listOrganizationInvitations` — `GET /api/v2/organizations/{organizationId}/invitations` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: List Organization Invitations → List organization invitations; sentence case matches the editorial guide. description: List invitations owned by the organization, including invitations with workspace grants. Requires organization administrator access. Expired invitations are reported without modif… → List invitations owned by the organization, including invitations with workspace grants. Requires organization Admin access. Expired invitations are reported without modifying the… responses.200.content.application/json.schema.description: List Organization Invitations result. → A page of invitations, including their current status. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listOrganizationInvitations, GET /api/v2/organizations/{organizationId}/invitations, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createOrganizationInvitation` — `POST /api/v2/organizations/{organizationId}/invitations` | corrected | Billing qualification and already-in-an-organization conflicts missing. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: Create Organization Invitation → Create organization invitation; sentence case matches the editorial guide. description: Email an invitation to join the organization as a member or administrator. Requires organization administrator access, invitations enabled, and an available seat on an eligible pl… → Email an invitation to join the organization as a member or Admin. Requires organization Admin access and invitations enabled; an eligible plan and available seat are required whe… requestBody.content.application/json.schema.description: Create Organization Invitation input. → Invitee email and organization role to offer. requestBody.description: Create Organization Invitation input. → Invitee email and organization role to offer. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createOrganizationInvitation, POST /api/v2/organizations/{organizationId}/invitations, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getOrganizationInvitation` — `GET /api/v2/organizations/{organizationId}/invitations/{invitationId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Get Organization Invitation → Get organization invitation; sentence case matches the editorial guide. description: Get an invitation owned by the organization. Requires organization administrator access. Use List Organization Invitation Workspaces to inspect its workspace grants. The response … → Get an invitation owned by the organization. Requires organization Admin access. Use List organization invitation workspaces to inspect its workspace grants. The response excludes… responses.200.content.application/json.schema.description: Get Organization Invitation result. → Invitation metadata without its acceptance token. responses.200.description: Get Organization Invitation result. → Invitation metadata without its acceptance token. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getOrganizationInvitation, GET /api/v2/organizations/{organizationId}/invitations/{invitationId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `revokeOrganizationInvitation` — `DELETE /api/v2/organizations/{organizationId}/invitations/{invitationId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Revoke Organization Invitation → Revoke organization invitation; sentence case matches the editorial guide. description: Cancel an unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization administrator access. This does not remove a person who … → Cancel an unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization Admin access. This does not remove a person who already … responses.200.content.application/json.schema.description: Revoke Organization Invitation result. → Acknowledgement that the pending invitation was cancelled. responses.200.description: Revoke Organization Invitation result. → Acknowledgement that the pending invitation was cancelled. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId revokeOrganizationInvitation, DELETE /api/v2/organizations/{organizationId}/invitations/{invitationId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listOrganizationInvitationWorkspaces` — `GET /api/v2/organizations/{organizationId}/invitations/{invitationId}/workspaces` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: List Organization Invitation Workspaces → List organization invitation workspaces; sentence case matches the editorial guide. description: List workspace grants attached to an invitation of any status. Includes archived workspaces still owned by the organization; workspaces moved to another organization are omitted. … → List workspace grants attached to an invitation of any status. Includes archived workspaces still owned by the organization; workspaces moved to another organization are omitted. … parameters[3].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[3].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listOrganizationInvitationWorkspaces, GET /api/v2/organizations/{organizationId}/invitations/{invitationId}/workspaces, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `resendOrganizationInvitation` — `POST /api/v2/organizations/{organizationId}/invitations/{invitationId}/resend` | rewritten | Reviewed; accurate details retained under the shared reference standard. | Verified improvement. Summary: Resend Organization Invitation → Resend organization invitation; sentence case matches the editorial guide. description: Email an unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization administrator access and current invitation eligibil… → Email an unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization Admin access and current invitation eligibility. Ret… requestBody.content.application/json.schema.description: Resend Organization Invitation input. → An empty JSON object; the pending invitation supplies the recipient and role. requestBody.description: Resend Organization Invitation input. → An empty JSON object; the pending invitation supplies the recipient and role. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId resendOrganizationInvitation, POST /api/v2/organizations/{organizationId}/invitations/{invitationId}/resend, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listSsoProviders` — `GET /api/v2/organizations/{organizationId}/sso/providers` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says Sorting and pagination controls. | Verified improvement. Summary: List SSO Providers → List SSO providers; sentence case matches the editorial guide. description: List identity providers owned by the organization. Requires organization administrator access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API ke… → List identity providers owned by the organization. Requires organization Admin access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API keys retur… responses.200.content.application/json.schema.description: List SSO Providers result. → A page of identity providers with redacted configuration. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. Preserved: Compared operationId listSsoProviders, GET /api/v2/organizations/{organizationId}/sso/providers, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `saveSsoProvider` — `POST /api/v2/organizations/{organizationId}/sso/providers` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. Review correction: save returns provider ID, protocol and creation state, not configuration. | Verified improvement. Summary: Save SSO Provider → Save SSO provider; sentence case matches the editorial guide. description: Create or update an organization identity provider’s configuration on a verified domain. Requires organization administrator access and SSO entitlement. Existing providers return … → Create or update an organization identity provider’s configuration on a verified domain. Requires organization Admin access and SSO entitlement. Existing providers return 200; cre… requestBody.content.application/json.schema.description: Configuration accepted by Save SSO Provider. → Provider protocol, verified domain, and identity-provider configuration. Omission behavior is field-specific. requestBody.description: Configuration accepted by Save SSO Provider. → Provider protocol, verified domain, and identity-provider configuration. Omission behavior is field-specific. Preserved: Compared operationId saveSsoProvider, POST /api/v2/organizations/{organizationId}/sso/providers, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getSsoProvider` — `GET /api/v2/organizations/{organizationId}/sso/providers/{providerId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Get SSO Provider → Get SSO provider; sentence case matches the editorial guide. description: Get an identity provider owned by the organization. Requires organization administrator access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API k… → Get an identity provider owned by the organization. Requires organization Admin access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API keys retu… responses.200.content.application/json.schema.description: Get SSO Provider result. → The identity provider with redacted configuration. responses.200.description: Get SSO Provider result. → The identity provider with redacted configuration. Preserved: Compared operationId getSsoProvider, GET /api/v2/organizations/{organizationId}/sso/providers/{providerId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `deleteSsoProvider` — `DELETE /api/v2/organizations/{organizationId}/sso/providers/{providerId}` | corrected | No membership/session deletion; qualify fallback if provider remains. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Delete SSO Provider → Delete SSO provider; sentence case matches the editorial guide. description: Remove an identity provider and clear its primary selection. Requires organization administrator access. Existing accounts, memberships, and sessions remain; sign-in falls back to… → Remove an identity provider and clear its primary selection. Requires organization Admin access. Existing accounts, memberships, and sessions remain. Domain sign-in falls back to … responses.200.content.application/json.schema.description: Delete SSO Provider result. → Acknowledgement that the identity provider was removed. responses.200.description: Delete SSO Provider result. → Acknowledgement that the identity provider was removed. Preserved: Compared operationId deleteSsoProvider, DELETE /api/v2/organizations/{organizationId}/sso/providers/{providerId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `setPrimarySsoProvider` — `POST /api/v2/organizations/{organizationId}/sso/providers/{providerId}/primary` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Set Primary SSO Provider → Set primary SSO provider; sentence case matches the editorial guide. description: Make a verified organization provider handle sign-in for its domain. Requires organization administrator access. Other providers remain available for testing and later switching. … → Make a verified organization provider handle sign-in for its domain. Requires organization Admin access. Other providers remain available for testing and later switching. Workspac… requestBody.content.application/json.schema.description: Configuration accepted by Set Primary SSO Provider. → An empty JSON object; the path identifies the provider to make primary. requestBody.description: Configuration accepted by Set Primary SSO Provider. → An empty JSON object; the path identifies the provider to make primary. Preserved: Compared operationId setPrimarySsoProvider, POST /api/v2/organizations/{organizationId}/sso/providers/{providerId}/primary, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getSsoPolicy` — `GET /api/v2/organizations/{organizationId}/sso/policy` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Get SSO Policy → Get SSO policy; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: Get SSO Policy result. → The stored SSO requirement and its effective enforcement state. responses.200.description: Get SSO Policy result. → The stored SSO requirement and its effective enforcement state. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … Preserved: Compared operationId getSsoPolicy, GET /api/v2/organizations/{organizationId}/sso/policy, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateSsoPolicy` — `PATCH /api/v2/organizations/{organizationId}/sso/policy` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Update SSO Policy → Update SSO policy; sentence case matches the editorial guide. description: Require or stop requiring SSO on future sign-ins. Requires organization administrator access. Enabling requires SSO entitlement and a verified provider; disabling remains availabl… → Require or stop requiring SSO on future sign-ins. Requires organization Admin access. Enabling requires SSO entitlement and a verified provider; disabling remains available after … requestBody.content.application/json.schema.description: Configuration accepted by Update SSO Policy. → Whether future sign-ins must use SSO. requestBody.description: Configuration accepted by Update SSO Policy. → Whether future sign-ins must use SSO. Preserved: Compared operationId updateSsoPolicy, PATCH /api/v2/organizations/{organizationId}/sso/policy, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listOrganizationDomains` — `GET /api/v2/organizations/{organizationId}/domains` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says Sorting and pagination controls. | Verified improvement. Summary: List Organization Domains → List organization domains; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: List Organization Domains result. → A page of domain claims; pending challenges are limited to Admins. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.200.description: List Organization Domains result. → A page of domain claims; pending challenges are limited to Admins. Preserved: Compared operationId listOrganizationDomains, GET /api/v2/organizations/{organizationId}/domains, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `addOrganizationDomain` — `POST /api/v2/organizations/{organizationId}/domains` | corrected | Existing claim 200/new 201/cross-org conflict correct; missing 25 cap. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Add Organization Domain → Add organization domain; sentence case matches the editorial guide. description: Claim a domain and receive its DNS TXT challenge. Requires organization administrator access and Enterprise domain entitlement. An existing claim returns 200; a new claim returns … → Claim a domain and receive its DNS TXT challenge. Requires organization Admin access and, when billing is enabled, Enterprise domain entitlement. An organization can claim at most… requestBody.content.application/json.schema.description: Configuration accepted by Add Organization Domain. → The domain to claim and verify. requestBody.description: Configuration accepted by Add Organization Domain. → The domain to claim and verify. Preserved: Compared operationId addOrganizationDomain, POST /api/v2/organizations/{organizationId}/domains, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `verifyOrganizationDomain` — `POST /api/v2/organizations/{organizationId}/domains/{domainId}/verify` | corrected | Already-verified unchanged/domain trust correct; deployment qualification. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Verify Organization Domain → Verify organization domain; sentence case matches the editorial guide. description: Verify domain ownership through the published DNS TXT challenge and grant domain trust to matching organization providers. Requires organization administrator access and Enterpris… → Verify domain ownership through its DNS TXT challenge and grant domain trust to matching organization providers. Requires organization Admin access and, when billing is enabled, E… requestBody.content.application/json.schema.description: Configuration accepted by Verify Organization Domain. → An empty JSON object; verification uses the claim’s current DNS challenge. requestBody.description: Configuration accepted by Verify Organization Domain. → An empty JSON object; verification uses the claim’s current DNS challenge. Preserved: Compared operationId verifyOrganizationDomain, POST /api/v2/organizations/{organizationId}/domains/{domainId}/verify, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `removeOrganizationDomain` — `DELETE /api/v2/organizations/{organizationId}/domains/{domainId}` | corrected | Domain trust revoked/accounts retained correct; deployment qualification. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Remove Organization Domain → Remove organization domain; sentence case matches the editorial guide. description: Remove a domain claim and revoke verified sign-in authority from matching organization providers. Requires organization administrator access and Enterprise domain entitlement. Exi… → Remove a domain claim and revoke verified sign-in authority from matching organization providers. Requires organization Admin access and, when billing is enabled, Enterprise domai… responses.200.content.application/json.schema.description: Remove Organization Domain result. → Acknowledgement that the domain claim was removed. responses.200.description: Remove Organization Domain result. → Acknowledgement that the domain claim was removed. Preserved: Compared operationId removeOrganizationDomain, DELETE /api/v2/organizations/{organizationId}/domains/{domainId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listCredentialMembers` — `GET /api/v2/credentials/{credentialId}/members` | corrected | Grant states/inherited admins correct; remove irrelevant session behavior. Review correction: caller authentication differs from target credential type; integrations.manage is named explicitly. | Verified improvement. Summary: List Credential Members → List credential members; sentence case matches the editorial guide. description: List explicit credential grants, including revoked grants, and inherited workspace administrator access. Requires workspace read access and the integrations.manage capability. Per… → List explicit credential grants, including revoked grants, and inherited workspace Admin access. This endpoint supports OAuth and service-account credentials. Requires workspace r… parameters[4].description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. parameters[4].schema.description: Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. → Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Preserved: Compared operationId listCredentialMembers, GET /api/v2/credentials/{credentialId}/members, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 8 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `upsertCredentialMember` — `POST /api/v2/credentials/{credentialId}/members` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: integrations.manage is named explicitly. | Verified improvement. Summary: Upsert Credential Member → Upsert credential member; sentence case matches the editorial guide. description: Grant or change an existing workspace member’s credential role. Requires credential administrator access and the integrations.manage capability. Revoked grants become active again… → Grant or change a current workspace member’s credential role. Requires credential Admin access and permission to manage integration connections. Revoked grants become active again… requestBody.content.application/json.schema.description: Configuration accepted by Upsert Credential Member. → The current workspace member and credential role to grant. requestBody.description: Configuration accepted by Upsert Credential Member. → The current workspace member and credential role to grant. Preserved: Compared operationId upsertCredentialMember, POST /api/v2/credentials/{credentialId}/members, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `removeCredentialMember` — `DELETE /api/v2/credentials/{credentialId}/members/{userId}` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: integrations.manage is named explicitly. | Verified improvement. Summary: Remove Credential Member → Remove credential member; sentence case matches the editorial guide. description: Revoke an active explicit credential grant. Requires credential administrator access and the integrations.manage capability. Inherited workspace administrators cannot be removed; … → Revoke an active explicit credential grant. Requires credential Admin access and permission to manage integration connections. Inherited workspace Admins cannot be removed; an abs… responses.200.content.application/json.schema.description: Remove Credential Member result. → Acknowledgement that the explicit credential grant was revoked. responses.200.description: Remove Credential Member result. → Acknowledgement that the explicit credential grant was revoked. Preserved: Compared operationId removeCredentialMember, DELETE /api/v2/credentials/{credentialId}/members/{userId}, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getWorkspacePermissionConfig` — `GET /api/v2/workspaces/{workspaceId}/permission-config` | rewritten | Registry-generated hideDeployChatbot publishing wording is outside owned contract sources; source registry left untouched. | Verified improvement. Summary: Get Workspace Permission Config → Get workspace permission config; sentence case matches the editorial guide. responses.200.content.application/json.schema.properties.data.properties.config.anyOf[0].properties.hideDeployChatbot.description: Prevent publishing a workflow as a chat. → Prevent deploying a workflow as a chat. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getWorkspacePermissionConfig, GET /api/v2/workspaces/{workspaceId}/permission-config, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 4 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createWorkspaceInvitations` — `POST /api/v2/workspaces/{workspaceId}/invitations` | rewritten | Copy standardized; no operation-specific discrepancy found. | Verified improvement. Summary: Create Workspace Invitations → Create workspace invitations; sentence case matches the editorial guide. description: Invite people to a workspace or grant access immediately to existing organization members. Requires workspace administrator access and current invitation eligibility; organization… → Invite people to a workspace or grant access immediately to existing organization members. Requires workspace Admin access and current invitation eligibility; invitations offering… responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createWorkspaceInvitations, POST /api/v2/workspaces/{workspaceId}/invitations, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getOrganizationMemberUsageLimit` — `GET /api/v2/organizations/{organizationId}/members/{userId}/usage-limit` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Get Organization Member Credit Limit → Get organization member credit limit; sentence case matches the editorial guide. description: Read a person’s credit cap and credits consumed in the organization billing period. Hosted only. The userId identifies an organization member or external collaborator with workspa… → Read a person’s credit cap and credits consumed in the organization billing period. Hosted deployments only. The `userId` identifies an organization member or external collaborato… responses.200.content.application/json.schema.description: Get Organization Member Credit Limit result. → The person’s current credit cap and billing-period consumption. responses.200.description: Get Organization Member Credit Limit result. → The person’s current credit cap and billing-period consumption. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getOrganizationMemberUsageLimit, GET /api/v2/organizations/{organizationId}/members/{userId}/usage-limit, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateOrganizationMemberUsageLimit` — `PATCH /api/v2/organizations/{organizationId}/members/{userId}/usage-limit` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Update Organization Member Credit Limit → Update organization member credit limit; sentence case matches the editorial guide. description: Set or clear a person’s credit cap. Hosted only. The userId must identify an organization member or external collaborator with workspace access in this organization. The cap is a … → Set or clear a person’s credit cap. Hosted deployments only. The `userId` must identify an organization member or external collaborator with workspace access in this organization.… responses.200.content.application/json.schema.description: Update Organization Member Credit Limit result. → The saved credit cap, or null when the cap was cleared. responses.200.description: Update Organization Member Credit Limit result. → The saved credit cap, or null when the cap was cleared. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateOrganizationMemberUsageLimit, PATCH /api/v2/organizations/{organizationId}/members/{userId}/usage-limit, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getOrganizationUsageSummary` — `GET /api/v2/organizations/{organizationId}/usage/summary` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says Reporting window and optional workspace filter. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: Get Organization Usage Summary → Get organization usage summary; sentence case matches the editorial guide. description: Read pooled credits, a usage series, and an exact previous-period comparison when available. Requires organization administrator access and Usage Monitoring (Enterprise on hosted;… → Read pooled credits, a usage series, and an exact previous-period comparison when available. Requires organization Admin access and Usage Monitoring: Enterprise when billing is en… responses.200.content.application/json.schema.description: Get Organization Usage Summary result. → Reporting bounds, pooled credits, and chronological usage buckets. responses.200.description: Get Organization Usage Summary result. → Reporting bounds, pooled credits, and chronological usage buckets. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getOrganizationUsageSummary, GET /api/v2/organizations/{organizationId}/usage/summary, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getOrganizationUsageBreakdown` — `GET /api/v2/organizations/{organizationId}/usage/breakdown` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says Reporting window, optional workspace filter, grouping dimension, and result limit. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: Get Organization Usage Breakdown → Get organization usage breakdown; sentence case matches the editorial guide. description: Read ranked organization usage by member, workspace, workflow, model, BYOK provider, or source. Requires organization administrator access and Usage Monitoring. Omitted usage is s… → Read ranked usage by member, workspace, workflow, model, BYOK provider, or source. Requires organization Admin access and Usage Monitoring. `other` summarizes groups omitted by th… responses.200.content.application/json.schema.description: Get Organization Usage Breakdown result. → Ranked usage groups and the combined remainder. responses.200.description: Get Organization Usage Breakdown result. → Ranked usage groups and the combined remainder. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getOrganizationUsageBreakdown, GET /api/v2/organizations/{organizationId}/usage/breakdown, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listOrganizationUsageEvents` — `GET /api/v2/organizations/{organizationId}/usage/events` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says Reporting window, source filter, sorting, and pagination. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: List Organization Usage Events → List organization usage events; sentence case matches the editorial guide. description: Page through usage events, including zero-cost reporting. Requires organization administrator access and Usage Monitoring. Defaults to 30 days. Cursors retain the initial reportin… → List usage events, including zero-cost activity. Requires organization Admin access and Usage Monitoring. Defaults to 30 days. Cursors retain the initial reporting window; keep fi… responses.200.content.application/json.schema.description: List Organization Usage Events result. → A page of usage events, including zero-cost activity. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listOrganizationUsageEvents, GET /api/v2/organizations/{organizationId}/usage/events, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `discoverWorkspaceAccessRequests` — `GET /api/v2/workspaces/{workspaceId}/access-requests/discovery` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: params metadata now says Workspace identifier. | Verified improvement. Summary: Discover Workspace Access Requests → Discover workspace access requests; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: Discover Workspace Access Requests result. → A page of access targets and the acting user’s current access state. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.200.description: Discover Workspace Access Requests result. → A page of access targets and the acting user’s current access state. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId discoverWorkspaceAccessRequests, GET /api/v2/workspaces/{workspaceId}/access-requests/discovery, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listMyWorkspaceAccessRequests` — `GET /api/v2/workspaces/{workspaceId}/access-requests` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: params metadata now says Workspace identifier. | Verified improvement. Summary: List My Workspace Access Requests → List my workspace access requests; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: List My Workspace Access Requests result. → A page of the acting user’s workspace and member-credit requests. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.200.description: List My Workspace Access Requests result. → A page of the acting user’s workspace and member-credit requests. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listMyWorkspaceAccessRequests, GET /api/v2/workspaces/{workspaceId}/access-requests, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createWorkspaceAccessRequest` — `POST /api/v2/workspaces/{workspaceId}/access-requests` | corrected | Pending reuse/closed/group-wide effect correct; missing org/enablement/caps. Review correction: query metadata now says No query parameters. Review correction: params metadata now says Workspace identifier. | Verified improvement. Summary: Create Workspace Access Request → Create workspace access request; sentence case matches the editorial guide. description: Request access for the acting user using a target from discovery. Returns an existing matching pending request when applicable; the result may be closed if access is already avail… → Request access using a target from Discover workspace access requests. Requires access to an organization-owned workspace with requests enabled; external collaborators use their w… requestBody.content.application/json.schema.description: Inputs for this operation. → A discovered access target and an optional reason for the request. requestBody.description: Inputs for this operation. → A discovered access target and an optional reason for the request. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createWorkspaceAccessRequest, POST /api/v2/workspaces/{workspaceId}/access-requests, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `cancelWorkspaceAccessRequest` — `POST /api/v2/workspaces/{workspaceId}/access-requests/{requestId}/cancel` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Cancel Workspace Access Request → Cancel workspace access request; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: Cancel Workspace Access Request result. → The cancelled request, or the unchanged request if already resolved. responses.200.description: Cancel Workspace Access Request result. → The cancelled request, or the unchanged request if already resolved. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId cancelWorkspaceAccessRequest, POST /api/v2/workspaces/{workspaceId}/access-requests/{requestId}/cancel, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `discoverOrganizationAccessRequests` — `GET /api/v2/organizations/{organizationId}/access-requests/discovery` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: Discover Organization Access Requests → Discover organization access requests; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: Discover Organization Access Requests result. → A page of access targets and the acting user’s current access state. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.200.description: Discover Organization Access Requests result. → A page of access targets and the acting user’s current access state. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId discoverOrganizationAccessRequests, GET /api/v2/organizations/{organizationId}/access-requests/discovery, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listMyOrganizationAccessRequests` — `GET /api/v2/organizations/{organizationId}/access-requests/mine` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: List My Organization Access Requests → List my organization access requests; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: List My Organization Access Requests result. → A page of the acting user’s organization and member-credit requests. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. responses.200.description: List My Organization Access Requests result. → A page of the acting user’s organization and member-credit requests. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listMyOrganizationAccessRequests, GET /api/v2/organizations/{organizationId}/access-requests/mine, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `createOrganizationAccessRequest` — `POST /api/v2/organizations/{organizationId}/access-requests` | corrected | Pending reuse/group effect correct; missing enablement/submission caps. Review correction: query metadata now says No query parameters. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: Create Organization Access Request → Create organization access request; sentence case matches the editorial guide. description: Request access for the acting user using a target from discovery. Returns an existing matching pending request when applicable; the result may be closed if access is already avail… → Request access using a target from Discover organization access requests. Requires organization membership and requests enabled. Each requester can have 100 pending requests and s… requestBody.content.application/json.schema.description: Inputs for this operation. → A discovered access target and an optional reason for the request. requestBody.description: Inputs for this operation. → A discovered access target and an optional reason for the request. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId createOrganizationAccessRequest, POST /api/v2/organizations/{organizationId}/access-requests, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `listOrganizationAccessRequests` — `GET /api/v2/organizations/{organizationId}/access-requests` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: List Organization Access Requests → List organization access requests; sentence case matches the editorial guide. description: List requests across the organization for administrator review. Includes requests from organization members and external workspace collaborators; history remains available while r… → List requests across the organization for administrator review. Includes requests from organization members and external workspace collaborators; history remains available while r… responses.200.content.application/json.schema.description: List Organization Access Requests result. → A page of requests across the organization for Admin review. responses.200.content.application/json.schema.properties.nextCursor.description: Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself. → Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId listOrganizationAccessRequests, GET /api/v2/organizations/{organizationId}/access-requests, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 7 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `cancelOrganizationAccessRequest` — `POST /api/v2/organizations/{organizationId}/access-requests/{requestId}/cancel` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Cancel Organization Access Request → Cancel organization access request; sentence case matches the editorial guide. responses.200.content.application/json.schema.description: Cancel Organization Access Request result. → The cancelled request, or the unchanged request if already resolved. responses.200.description: Cancel Organization Access Request result. → The cancelled request, or the unchanged request if already resolved. responses.503.description: A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `A… → A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before … 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId cancelOrganizationAccessRequest, POST /api/v2/organizations/{organizationId}/access-requests/{requestId}/cancel, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 5 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `previewOrganizationAccessRequest` — `GET /api/v2/organizations/{organizationId}/access-requests/{requestId}/preview` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Preview Organization Access Request → Preview organization access request; sentence case matches the editorial guide. description: Preview the current permission changes, affected group and audience, or member credit cap. Review canApply, changes, impact, and fingerprint before resolving. Permission changes a… → Preview the current permission changes, affected group and audience, or member credit cap. Review `canApply`, `changes`, `impact`, and `fingerprint` before resolving. Permission c… responses.200.content.application/json.schema.description: Preview Organization Access Request result. → The proposed group or credit-cap change, affected audience, and fingerprint. responses.200.description: Preview Organization Access Request result. → The proposed group or credit-cap change, affected audience, and fingerprint. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId previewOrganizationAccessRequest, GET /api/v2/organizations/{organizationId}/access-requests/{requestId}/preview, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `resolveOrganizationAccessRequest` — `POST /api/v2/organizations/{organizationId}/access-requests/{requestId}/resolve` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. | Verified improvement. Summary: Resolve Organization Access Request → Resolve organization access request; sentence case matches the editorial guide. description: Apply a reviewed request or decline it with a reason. Applying requires the preview fingerprint; changed policy or membership returns a conflict. Credit requests also require a hi… → Apply a reviewed request or decline it with a reason. Applying requires the preview fingerprint; changed policy or membership returns a conflict. Credit requests also require a hi… requestBody.content.application/json.schema.description: Inputs for this operation. → Apply the reviewed fingerprint, with a higher credit cap when applicable, or decline with a reason. requestBody.description: Inputs for this operation. → Apply the reviewed fingerprint, with a higher credit cap when applicable, or decline with a reason. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId resolveOrganizationAccessRequest, POST /api/v2/organizations/{organizationId}/access-requests/{requestId}/resolve, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `getOrganizationAccessRequestSettings` — `GET /api/v2/organizations/{organizationId}/access-requests/settings` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: Get Organization Access Request Settings → Get organization access request settings; sentence case matches the editorial guide. description: Get whether the organization allows new access requests and approvals. This preference does not enable features unavailable in the deployment or subscription. Requires organizatio… → Get whether the organization allows new access requests and approvals. This preference does not enable features unavailable in the deployment or subscription. Requires organizatio… responses.200.content.application/json.schema.description: Get Organization Access Request Settings result. → Whether new requests and approvals are allowed. responses.200.description: Get Organization Access Request Settings result. → Whether new requests and approvals are allowed. 1 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId getOrganizationAccessRequestSettings, GET /api/v2/organizations/{organizationId}/access-requests/settings, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 6 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+| `updateOrganizationAccessRequestSettings` — `PATCH /api/v2/organizations/{organizationId}/access-requests/settings` | rewritten | Reviewed; accurate details retained under the shared reference standard. Review correction: query metadata now says No query parameters. Review correction: params metadata now says Organization identifier. | Verified improvement. Summary: Update Organization Access Request Settings → Update organization access request settings; sentence case matches the editorial guide. description: Allow or pause new access requests and approvals. Pausing preserves history, cancellation, and decline, and does not revoke previously granted access. Requires organization admini… → Allow or pause new access requests and approvals. Pausing preserves history, cancellation, and decline, and does not revoke previously granted access. Requires organization Admin … requestBody.content.application/json.schema.description: Inputs for this operation. → Whether new requests and approvals are allowed. requestBody.description: Inputs for this operation. → Whether new requests and approvals are allowed. 2 request/response media example set(s) now expose the owner's existing examples to the API renderer. Preserved: Compared operationId updateOrganizationAccessRequestSettings, PATCH /api/v2/organizations/{organizationId}/access-requests/settings, security and x-sim-operation with baseline; identifiers, route and credential schemes match. Recursive prose/default/example mappings retained in final-review-api-comparison.json; 9 distinct changed field mappings were inspected for this operation. Operation-level request/response structure, parameters, required fields, defaults and status declarations are identical after removing prose/examples; referenced component changes were reviewed separately. |
+
+### CLI reference (28)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [cli/audit-logs.mdx](content/docs/cli/audit-logs.mdx) | generated | Corrected organization selection wording and inherited audit-action date bounds Added organization Admin/owner and enterprise eligibility before commands Put list before get and linked authentication/permission guidance | Verified improvement. Page purpose: Manage audit logs — every subcommand, argument, and flag → Read organization audit actions and filter by actor, resource, workspace, or time.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 2 baseline and 2 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/billing.mdx](content/docs/cli/billing.mdx) | generated | Replaced Copilot prose with Sim agent/Chat while preserving source enums Kept credential-dependent usage visibility and linked Costs Surfaced server defaults and API schemas | Verified improvement. Page purpose: Manage billing — every subcommand, argument, and flag → Read billing status, credit usage, and storage usage.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Fresh residual source-copy findings corrected by parent and present in current generated page: FR-CLI-02. Preserved: Compared 2 baseline and 2 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/blocks.mdx](content/docs/cli/blocks.mdx) | generated | Replaced Manage metadata with workspace catalog purpose Put list before get and kept visibility/version/sunset constraints Surfaced sort defaults and API schemas | Verified improvement. Page purpose: Manage blocks — every subcommand, argument, and flag → Inspect workflow blocks, integration blocks, and triggers available to the workspace.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Preserved: Compared 2 baseline and 2 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/chat-deployments.mdx](content/docs/cli/chat-deployments.mdx) | generated | Clarified read-only collection purpose Linked creation/update to workflow chat section Surfaced sort defaults and API schemas | Verified improvement. Page purpose: Manage chat deployments — every subcommand, argument, and flag → List workflow chat deployments in the workspace.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 1 baseline and 1 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/cli.mdx](content/docs/cli/cli.mdx) | generated | Renamed page to Command search without changing route Included local query privacy, five-result cap, and terminal-help examples Preserved original command heading anchor | Verified improvement. Page purpose: Discover commands in this CLI — every subcommand, argument, and flag → Find a command by describing the task you want to perform.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 1 baseline and 1 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/commands.mdx](content/docs/cli/commands.mdx) | generated | Replaced universal resource-syntax claim with resource-specific syntax Clarified global-option applicability, telemetry text, export format, help/version Rewrote group summaries and added Chat stream/output/conversation examples Preserved global-options anchor and all root commands | Verified improvement. Page purpose: Global options, and every sim command group → Find command groups, global options, and login, configuration, and Chat commands.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Fresh residual source-copy findings corrected by parent and present in current generated page: FR-CLI-01. Preserved: Compared 7 baseline and 7 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/connector-types.mdx](content/docs/cli/connector-types.mdx) | generated | Explained connector/auth/source-schema discovery Linked full-detail inspection to connector creation Kept complete projection, cursor and default detail behavior | Verified improvement. Page purpose: Manage connector types — every subcommand, argument, and flag → Discover knowledge connectors and their authentication and source-configuration schemas.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 1 baseline and 1 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/credentials.mdx](content/docs/cli/credentials.mdx) | generated | Grouped discovery/connections, member grants, and disconnect lifecycle Added provider schema discovery and human OAuth-link authorization Kept all provider fields, required IDs, write-only/null limitations, and grants Linked each published operation to its API request and response schemas | Verified improvement. Page purpose: Manage credentials — every subcommand, argument, and flag → Discover providers, connect accounts, and manage credential access.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 10 baseline and 10 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/custom-tools.mdx](content/docs/cli/custom-tools.mdx) | generated | Added concrete code-backed tool purpose and CRUD lifecycle order Preserved complete function-schema examples and sandbox fact Linked canonical request/response schemas | Verified improvement. Page purpose: Manage custom tools — every subcommand, argument, and flag → Create and manage code-backed tools that agents can call.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 5 baseline and 5 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/files.mdx](content/docs/cli/files.mdx) | generated | Grouped browsing, content, editing, sharing, versions, archive/restore, and folders Fixed VFS/secret-reference inline code rendering and preserved revision/version guards Changed oversized-content guidance to sim files upload Surfaced archive/version/delete consequences and whole-sharing configuration rules Review correction: inline content help preserves the separate request and decoded-file limits. | Verified improvement. Page purpose: Manage files — every subcommand, argument, and flag → Browse workspace files, read or write content, manage versions, and configure sharing.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Fresh residual source-copy findings corrected by parent and present in current generated page: FR-CLI-03. Preserved: Compared 30 baseline and 30 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/knowledge.mdx](content/docs/cli/knowledge.mdx) | generated | Grouped knowledge bases before search/export, documents, chunks, tags, connectors and folders Fixed tag-filter/secret-reference code rendering Kept typed slots, reranking billing/fallback, search modes, sync states and upload tags Linked JSON flags to canonical API schemas | Verified improvement. Page purpose: Manage knowledge — every subcommand, argument, and flag → Manage knowledge bases, indexed documents, search, tags, and connector syncs.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Fresh residual source-copy findings corrected by parent and present in current generated page: FR-CLI-07. Preserved: Compared 44 baseline and 44 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/logs.mdx](content/docs/cli/logs.mdx) | generated | Added run-diagnostics purpose and browse-before-detail order Included follow JSONL/YAML streaming, stderr, first-seen status and examples Preserved filter limits, severity/status distinctions, job restrictions and bucket behavior | Verified improvement. Page purpose: Manage logs — every subcommand, argument, and flag → Read run diagnostics, follow new runs, and summarize failures and latency.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 4 baseline and 4 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/mcp-servers.mdx](content/docs/cli/mcp-servers.mdx) | generated | Defined external MCP connection direction and linked reverse workflow-serving surface Fixed secret-reference inline code and sentence-case acronym title Grouped connections, tool discovery, and removal Kept immutable URL, auth autodetection, header replacement, refresh and OAuth invalidation | Verified improvement. Page purpose: Manage mcp servers — every subcommand, argument, and flag → Connect external Model Context Protocol (MCP) servers so workflows can use their tools.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 6 baseline and 6 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/meta.mdx](content/docs/cli/meta.mdx) | generated | Renamed title to API capabilities with concrete metadata purpose Removed unused CommandTable import Kept sim meta status unchanged and linked authentication | Verified improvement. Page purpose: Manage meta — every subcommand, argument, and flag → Inspect API availability and the calling credential’s type and expiry.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Fresh residual source-copy findings corrected by parent and present in current generated page: FR-CLI-01. Preserved: Compared 1 baseline and 1 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/organizations.mdx](content/docs/cli/organizations.mdx) | generated | Grouped organization reads, membership/caps, invitations, usage, access requests, domains and SSO Surfaced conditional required fields and OIDC/SAML requirements Kept previews/fingerprints, window bounds, credit units, verified domains and session caveats Added canonical API schema links instead of a second config schema | Verified improvement. Page purpose: Manage organizations — every subcommand, argument, and flag → Manage organization membership, invitations, usage, access requests, and SSO.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 37 baseline and 37 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. No→Conditional labels clarify existing conditional requirements; command usage and option syntax remain identical. |
+| [cli/permission-groups.mdx](content/docs/cli/permission-groups.mdx) | generated | Grouped configuration before member assignments and deletion Explained replacement arrays and supported config-schema lookup Kept default/non-default group, inactive workspace lists, and conditional requirements | Verified improvement. Page purpose: Manage permission groups — every subcommand, argument, and flag → Manage organization permission groups, their configuration, and member assignments.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 9 baseline and 9 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. No→Conditional labels clarify existing conditional requirements; command usage and option syntax remain identical. |
+| [cli/profiles.mdx](content/docs/cli/profiles.mdx) | generated | Explained shared stored login and noninteractive workspace requirement Kept both profiles/profile spellings and command syntax Linked configuration/authentication | Verified improvement. Page purpose: List profiles or add a workspace profile that shares a stored login — every subcommand, argument, and flag → List profiles and add a workspace profile that shares a stored login.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 2 baseline and 2 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/reference.mdx](content/docs/cli/reference.mdx) | generated | Retained all 318 exact command headings, signatures, flags, arguments and aliases Included group purpose/access notes, confirmation consequences and command help Fixed inline code and preserved pipe/backslash round trips Added defaults, API schema links and self-contained output/help/version rules Kept the complete single-fetch machine reference rather than replacing it with guides Rebase delta: scoped raw .mdx availability to authored guides and CLI pages; generated API operations expose OpenAPI JSON. Review correction: inline content help preserves the separate request and decoded-file limits. | Verified improvement. Page purpose: Every sim command, argument, and flag on a single page → Every sim command, argument, and flag on a single page. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Fresh residual source-copy findings corrected by parent and present in current generated page: FR-CLI-01, FR-CLI-02, FR-CLI-03, FR-CLI-04, FR-CLI-05, FR-CLI-06, FR-CLI-07, FR-CLI-08, FR-CLI-09. Preserved: Compared 318 baseline and 318 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. No→Conditional labels clarify existing conditional requirements; command usage and option syntax remain identical. |
+| [cli/sandboxes.mdx](content/docs/cli/sandboxes.mdx) | generated | Added Function-dependency purpose and CRUD lifecycle order Surfaced deletion consequence and schema links Kept manifest parsing, language revalidation, list replacement, package/CLI bounds | Verified improvement. Page purpose: Manage sandboxes — every subcommand, argument, and flag → Manage reusable dependency sets for Function blocks.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 5 baseline and 5 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/secrets.mdx](content/docs/cli/secrets.mdx) | generated | Explained personal/workspace ownership and actual visible-value list behavior Included private terminal input versus metadata-only workspace edits and unattended value input Kept redaction/plaintext consequences and exact file/stdin/newline semantics | Verified improvement. Page purpose: Manage secrets — every subcommand, argument, and flag → Set and manage workspace or personal secrets.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 3 baseline and 3 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/selectors.mdx](content/docs/cli/selectors.mdx) | generated | Defined option-source purpose and declared-dependency OAuth boundary Put list before get and linked published schema lookup Retained the exhaustive selector-key enum in both command entries for complete lookup | Verified improvement. Page purpose: Manage selectors — every subcommand, argument, and flag → Discover destination options for registered fields, such as calendars, channels, and tables.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Preserved: Compared 2 baseline and 2 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/skills.mdx](content/docs/cli/skills.mdx) | generated | Grouped instruction resources, editor grants, and deletion Kept built-in identifiers, reserved/kebab names, current-member constraints and literal content flags Linked agent skill guide and operation schemas | Verified improvement. Page purpose: Manage skills — every subcommand, argument, and flag → Create reusable agent instructions and manage their editors.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 8 baseline and 8 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/tables.mdx](content/docs/cli/tables.mdx) | generated | Grouped tables before rows/query, columns, views, producers/runs, imports/exports and folders Surfaced dispatch-versus-import cancellation and destructive replace timing Fixed local/workspace source exclusivity and workspace-file name requirement Preserved all filter/schema/producer/upsert examples, row caps and run-state limits Linked canonical request and response schemas | Verified improvement. Page purpose: Manage tables — every subcommand, argument, and flag → Manage tables, rows, schemas, views, enrichment runs, imports, and exports.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Fresh residual source-copy findings corrected by parent and present in current generated page: FR-CLI-04, FR-CLI-08. Preserved: Compared 54 baseline and 54 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. No→Conditional labels clarify existing conditional requirements; command usage and option syntax remain identical. |
+| [cli/telemetry.mdx](content/docs/cli/telemetry.mdx) | generated | Qualified enable as a saved preference subject to environment/build gates Documented fixed text output and linked usage-data details Preserved previous status/enable anchors and removed unused table import | Verified improvement. Page purpose: Control anonymous usage reporting — every subcommand, argument, and flag → Inspect and change this machine’s anonymous usage-reporting preference.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 3 baseline and 3 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/tools.mdx](content/docs/cli/tools.mdx) | generated | Added parameter-inspection purpose and list/get/execute order Fixed literal toolId inline code rendering Kept OAuth credential requirements, hosted-key filters and full result schema lookup | Verified improvement. Page purpose: Manage tools — every subcommand, argument, and flag → Find built-in tools, inspect their parameters, and run them.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Preserved: Compared 3 baseline and 3 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/workflow-mcp-servers.mdx](content/docs/cli/workflow-mcp-servers.mdx) | generated | Defined serving Sim workflows versus connecting external tools Grouped server lifecycle, workflow tools, and deletion Kept public defaults, URL exposure, deployed workflow requirement and name normalization Preserved publish/unpublish heading anchors while inheriting deployment terminology | Verified improvement. Page purpose: Manage workflow mcp servers — every subcommand, argument, and flag → Serve deployed workflows as tools for Model Context Protocol (MCP) clients.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 8 baseline and 8 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+| [cli/workflows.mdx](content/docs/cli/workflows.mdx) | generated | Grouped resource lifecycle, drafts, deployments/versions, runs, Chat, import/export and folders Surfaced complete chat replacement and default-public access before invocation Corrected human-pause wait behavior and explicit exit codes Included export literal-secret inspection and successful paused-cancel recovery limits Preserved operations, selected output, manual/deployed state, one-shot run IDs, stream and file caps Kept changed wait/chat anchors and all exact command spellings | Verified improvement. Page purpose: Manage workflows — every subcommand, argument, and flag → Build, deploy, run, and inspect workflows from the terminal.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Fresh residual source-copy findings corrected by parent and present in current generated page: FR-CLI-05, FR-CLI-06, FR-CLI-09. Preserved: Compared 42 baseline and 42 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. No→Conditional labels clarify existing conditional requirements; command usage and option syntax remain identical. |
+| [cli/workspaces.mdx](content/docs/cli/workspaces.mdx) | generated | Grouped access, requests, fork review/lineage, mappings, push/pull previews, operation status and recovery Shortened wait heading while preserving original anchor and exit/reconciliation facts Kept explicit copy choices, stable retry IDs/fingerprints, trigger mappings and invitation partial results Linked workflow-sync guide and canonical operation schemas | Verified improvement. Page purpose: Manage workspaces — every subcommand, argument, and flag → Read workspace access and manage reviewed fork, push, and pull operations.. Commands are grouped in resource/lifecycle order, retain generated options and examples, and link applicable canonical API requests/responses. Onward references and compatible heading anchors support direct lookup without changing invocation syntax. Preserved: Compared 27 baseline and 27 current command invocations; no command, argument, option syntax, alias, or required flag was removed. Command confirmations and field descriptions were read alongside current source; conditional labels match existing schema/confirmation requirements. |
+
+### Self hosting setup (10)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [platform/self-hosting/authentication.mdx](content/docs/platform/self-hosting/authentication.mdx) | rewritten | Ordered origins, login methods, registration controls, SSO, proxy trust, OAuth server, and verification. Corrected effective email verification, email OTP allowlists, domain bans, public MCP registration/scope families, native callback boundary, and anonymous-session wording. Preserved client registration command, fixed token lifetimes, revocation, permission-group scope, shared secret requirements, and inbound anchors. | Verified improvement. Corrects verification with missing provider and emailOTP gates; distinguishes human OAuth authorization from provider integrations and current public registration support. Verified late fix: SSO setup now names Settings → Organization → Single sign-on while preserving both feature flags, organization-scoped and unscoped provider registration, and organization setup links. Preserved: All login callbacks/flags/sharedsecrets, signupblock/allow/MXcontrols, trustproxy, disabledauth consequences, OAuth1h/30day/rotation/revocation, registration/client/redirect/PKCE scripts and upgrade sequencing retained. |
+| [platform/self-hosting/desktop.mdx](content/docs/platform/self-hosting/desktop.mdx) | rewritten | Moved server/TLS prerequisites and install/connect before update/feed internals. Corrected ability to repoint Local builds while preserving baked identity and update eligibility. Preserved URL validation, state clearing/refusal, recovery, channels/feed fallback, CLI probe semantics, packaging/signing/notarization variables. | Verified improvement. Puts exactorigin/TLS requirements before install; corrects Local identity staying fixed rather than inability to repoint and scopes update fallback. Preserved: Both endpoints/statuses/channels/repositories5mincache/GitHubquotas, install/CLIprobes/discovery, stateclearing/recovery, allbuild/sign/notarization/env/filepath options and update eligibility retained. |
+| [platform/self-hosting/docker.mdx](content/docs/platform/self-hosting/docker.mdx) | rewritten | Added Compose 2.24+/Node compatibility prerequisites and manual checkout path. Kept the complete new-install secret/password script, key retention, credential interpolation, cron behavior, and image pinning. Added local-upload durability at the production step and host/container proxy distinctions. Moved FAQ material into backup, scheduler, Redis, credentials, and lifecycle sections; retained every sim-setup mode/command consequence. Corrected Caddy buffering explanation and documented host-gateway use for external Ollama. Review correction: Caddy allowance does not raise the Next.js proxy buffer. | Verified improvement. Adds runtime/Compose prerequisites, durable local upload warning, recreation semantics, provider reachability and streamedproxy qualification. Preserved: Complete6service/defaultports/memory, full5secret+DBenvcreation, URLsafecredentials/persistedPostgres, Caddyexample, OllamaCPU/GPUsetup, LMStudioauth, every CLIaction/destruction scope, backup/restore-T and update instructions remain. |
+| [platform/self-hosting/email.mdx](content/docs/platform/self-hosting/email.mdx) | rewritten | Preserved five providers and fallback order while making apply/recreate and delivery checks explicit. Corrected inline, existing-Secret, and ESO credential paths. Added Gmail API/delegation prerequisites, qualified paid/trial sending limits, and placed INFO logging prerequisites with verification. Kept SMTP TLS/EHLO, SES region/sandbox, sender aliases, and troubleshooting; removed unsupported provider preferences. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Adds provider delivery checks, effective verification boundary, exact secretmode injection and actual uppercaseINFO logging prerequisite. Preserved: All5providerenv/config/authsettings/fallbackorder, SMTPportsEHLO, GoogleRelayvsDWDfullsetup, SESsandbox, Azurelinkedidentity, senderaliases/quotas, alltroubleshooting preserved with a concise provider-first flow. |
+| [platform/self-hosting/environment-variables.mdx](content/docs/platform/self-hosting/environment-variables.mdx) | rewritten | Reordered the reference by deployment settings, model/knowledge configuration, optional capabilities, limits, and observability. Preserved field names, defaults, egress exclusions, sandbox readiness, numbered keys, vector pairings, and inherited Helm null-removal instructions. Corrected deployment-wide database schedule cap, billing-disabled plan-counter scope, opt-in retention, worker isolation, API-key plaintext compatibility, Gemini 3-or-later eligibility, and model-specific width fallback. Qualified Azure API-version selection and separated app/source-checkout .env from Compose-derived values. Review correction: configured body defaults differ from effective request caps. | Verified improvement. Groups actual deployment config, corrections for independent limits/timeouts, worker execution, storage durability, feature overrides and effective embedding default. Verified late fix: The literal FREE_STORAGE_LIMIT_GB key and suggested value5 are preserved; its human-readable quota unit is corrected from GB to GiB. Preserved: All required/optionalkeys, AI/model/provider/OCR, codeexecutionbroker/remoteimage settings, Chat/PII, storage7providerparameters, networklimits, allfreeoptins/nullremoval/Helmreuserecovery and full.env example remain. Removed provenance note is not a configuration variable and remains in canonical Security guide. |
+| [platform/self-hosting/index.mdx](content/docs/platform/self-hosting/index.mdx) | rewritten | Replaced the drifting manual quick-start script with the setup wizard and Docker owner. Separated resource examples from enforced requirements and operational defaults. Placed key/file durability, public origin, email, scheduler, and verification before optional dependencies. Qualified enterprise behavior by billing mode and retained local embedding/remote image prerequisites. | Verified improvement. Reorders deployment choice, supported wizard, production hazards and dependencies; sizing becomes examples rather than user-count guarantees. Verified late fix: Quick start now places Bun and Node.js20 or newer before bunx sim-setup, alongside the preserved Docker and Compose2.24.0 prerequisites. Wizard output, manual setup links and production safeguards remain. Preserved: All deployment choices, resource examples, enterprise/org prerequisites, model/embedding/Chat/OAuth/remote dependencies and next steps retained. Removed raw5secret quickstart replaced by wizard plus full Docker manual setup. |
+| [platform/self-hosting/integrations-oauth.mdx](content/docs/platform/self-hosting/integrations-oauth.mdx) | rewritten | Created canonical Google, Microsoft, and Atlassian console setup sections for Search crosslinks. Preserved full Google Search member scopes/callbacks, all Microsoft resource scopes, full Confluence/Jira member scopes, API permissions/consent/distribution and reconnection distinctions. Added Intune, Ramp, and QuickBooks per-connection configuration; kept all prior provider exceptions/flows and hosted-only key constraints. Kept the complete GitHub App setup at its inbound anchor and removed both screenshots, retaining the correct six-permission table. Folded duplicate FAQ into setup/provider/troubleshooting sections and corrected Kubernetes secret modes. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Adds complete Google/Microsoft/Atlassian member grants and distinction from Search service accounts; corrects secret-store deployment setup and scope-update/reconnect procedure. Verified late fix: GitHub App replacement now uses Credential Groups → Integrations → Update configurations. The migration affects existing provider options, preserves option IDs and retains all reconnect and secret handling consequences. Preserved: All original provider IDs/envcredentials/callbacks, GitHubAppsettings/readpermissions5variablesPEMrefresh/privateboundaries, Bitbucketexactpermissions,7providerextras, alternateInstagram/Shopify/Trelloflows, hostedkeycatalog/limits and nativeSlack requirements retained; current Ramp/Intune/QuickBooks added. Screenshots removed with full GitHub fields intact. |
+| [platform/self-hosting/kubernetes.mdx](content/docs/platform/self-hosting/kubernetes.mdx) | rewritten | Pinned published chart 1.11.8/appVersion v0.9.17 without claiming a live installation test or latest status. Replaced partial public-origin snippet with complete same-host/split-host routing, allowed origin and TLS Secret instructions. Separated inline, existing-Secret and ESO branches; documented env versus envDefaults and retained all core credentials. Labeled legacy ingress-nginx defaults and annotations honestly; did not choose/provision a controller or invent Gateway API support. Pinned cloud example source v0.9.17 and required review of certificate/IAM/storage/project placeholders; preserved database-name and key-loss upgrade caveats. Corrected cosign reference syntax and qualified registry mirroring of verification artifacts. | Verified improvement. Provides full3secretmode setup, working dual port-forward/public socket/TLS examples, same-releasepinnings, verification and safe retained-secret upgrades; scopes ingress retirement. Preserved: Every original OCI/classicrepo/cosign/attestation/cloud6domainoverride/ExternalDB/redis/migrations/cron/backupconversion/PVC consequence retained; code snippets now complete and pinned instead of abstract v1.2.3. |
+| [platform/self-hosting/platforms.mdx](content/docs/platform/self-hosting/platforms.mdx) | rewritten | Converted unsupported Railway template guarantees into concrete verification steps and exposed five-minute cron limits. Replaced the production convenience-script recommendation with official Docker installation and plugin prerequisites. Clarified provider-specific cloud placeholders and extension availability/activation. Labeled external DATABASE_URL scope and explained production Compose overrides. | Verified improvement. Removes unsupported live-template assumptions and adds minute-scheduler gap, maintained ingress requirement and externalDSN Compose limitation. Preserved: Railway/VPS/EKS/AKS/GKE/database providers, pgvector requirement, TLS/ManagedCertificate, resource sizing and externalDatabase setup remain; Railway badge replaced by usable linked template. |
+| [platform/self-hosting/verify.mdx](content/docs/platform/self-hosting/verify.mdx) | rewritten | Preserved all 12 checks and doctor file/journal/live-probe limitations, then separated core and feature checks. Corrected cloud/local multipart thresholds and cross-replica proof claims. Added namespace-consistent commands, avoided printing a Redis credential, and checked actual job success rather than schedules alone. Preserved credential restore checks, uppercase INFO logging/no-op behavior, and upgrade subset. | Verified improvement. Replaces presence-only health guarantees with actual data/recipient/completion results and crosspod requirement; corrects multipart localvscloud thresholds. Preserved: All12checks/failureactions, doctor5groups/repairlimits/journal/skippedprobes, domains, infra/Composecommands, loglevel and postupgrade/postrestore OAuth-key checks retained. |
+
+### Self hosting operations (12)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [platform/self-hosting/architecture.mdx](content/docs/platform/self-hosting/architecture.mdx) | rewritten | Rewrote the service/state/request-path overview and removed the duplicated FAQ. Corrected local JavaScript to Node child workers; kept shared container resources and remote/Trigger.dev distinctions. Preserved ephemeral-upload and secret-loss warnings; distinguished 50 MiB cloud and 8 MiB local PUT thresholds. Added scoped optional Chat-service/database/migration inventory without claiming universal packaging availability. | Verified improvement. Leads with actual services and state; replaces vague stateless labels with the state each service holds, and tables make request paths easier to inspect. Corrects local JavaScript execution to Node child workers sharing the app container memory budget; adds local 8 MiB and cloud 50 MiB transfer thresholds, upload-session persistence, and the separate optional Chat database. Integrates both original FAQ answers at their owners and links the scheduler cleanup gap without repeating the whole job inventory. Preserved: All nine service images, ports, required/optional distinctions, shared Better Auth session setup, realtime Redis prerequisite, migrations lifecycle, PostgreSQL/pgvector requirement, and state backup inventory remain. Local-upload loss and cross-replica visibility warnings, independent ENCRYPTION_KEY backup and recovery, signed browser uploads/CORS, proxied downloads, workflow and cron request paths, and ingress streaming/WebSocket needs remain. Renamed cron heading has no remaining inbound repository reference; existing where-state-lives anchor remains. |
+| [platform/self-hosting/background-jobs.mdx](content/docs/platform/self-hosting/background-jobs.mdx) | rewritten | Moved authentication, deployment setup, customization, and verification before the complete shipped job table. Documented an operator-owned authenticated upload-session cleanup job; runtime/scheduler files unchanged. Corrected published cron customization to a mounted crontab or custom image. Corrected deployment-wide database schedule capacity, inline/external Secret differences, default/job-specific deadlines, and stale schedule vs 401 diagnostics. Preserved all shipped schedules, endpoints, billing/SCIM distinctions and accepted-vs-completed response behavior. | Verified improvement. Puts authenticated setup and verification before the full lookup inventory; separates stale scheduling/controller failures from 401 authentication and accepted-versus-completed work. Replaces ineffective repository-crontab editing with a real mount/custom image procedure and persists CRON_SECRET in the app/scheduler environment. Adds the missing operator-owned cleanup-tasks job and corrects scheduled concurrency to the database queue-wide cap; explains Kubernetes and request retry/deadline budgets in a table. Preserved: Every original shipped job, endpoint, cron expression, polling/subscription distinction, per-job disabling procedure, secret generation/auth syntax, supercronic logging/termination behavior, and two-minute product verification path remain. The original 202 caveat, Trigger.dev-only concurrency settings, Kubernetes history/TTL/default retry limits, outbox deadline exception, and memory headroom consequence remain. Renamed the-jobs heading has no remaining inbound repository reference; #concurrency remains. |
+| [platform/self-hosting/networking.mdx](content/docs/platform/self-hosting/networking.mdx) | rewritten | Moved optional second-ingress/Chat-service routing after core proxy and cloud setup. Added required GKE annotation, cleared unsupported controller field, and qualified certificate provisioning time. Labelled ingress-nginx as retired legacy guidance while keeping standalone Nginx and existing-install annotations. Corrected Azure timeout to 20 seconds and distinguished ALB idle timeout from fixed connection lifetime. Preserved full proxy/transport/NO_PROXY/escape-hatch matrix and reduced large explanatory callouts. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. Review correction: external proxy, Next.js buffer and route body caps are independent layers. | Verified improvement. Corrects GKE ingress class selection, certificate provisioning/verification, Azure backend timeout (20 seconds), and ALB idle timeout semantics; labels retired ingress-nginx configuration as existing-install reference. Preserves complete proxy and egress lookup detail while giving internal NO_PROXY destinations their own section; moves optional ingress/service routing after the main setup. Uses authored tabs and binary request-size units; quotes shell placeholders so readers do not accidentally invoke redirection syntax. Preserved: Both topology variants and all URL/origin keys; full Caddy, Nginx, Traefik, GKE BackendConfig/Service annotation, ManagedCertificate, ALB, and internal ingress examples remain. All request-size keys/defaults, local/cloud upload transport distinction, Bun/Node proxy behavior, per-SDK transport rows, every NO_PROXY example, and the HTTP-only publicly routable per-request proxy restriction remain. Chart-dropped Service annotations, reapplication after Service recreation, TLS/DNS prerequisites, optional copilot host sharing, and WebSocket/SSE timeout/buffering consequences remain. Renamed headings have no remaining inbound repository references. |
+| [platform/self-hosting/object-storage.mdx](content/docs/platform/self-hosting/object-storage.mdx) | rewritten | Moved deployment application steps after all provider setup; corrected backend activation keys. Made the AWS bucket loop handle us-east-1 correctly and preserved all IAM/CORS/bucket fallback details. Added private Azure container creation and a fallback table; kept both credential forms and full CORS headers. Fixed GCS JSON formatting and preserved explicit signed-upload headers, ADC/signBlob permissions and bucket fallbacks. Removed unsupported blanket compatibility/wildcard/MinIO assertions, preserving provider examples and operator verification requirements. Documented missing shipped upload cleanup scheduling and linked the authenticated operator-owned procedure. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Corrects activation predicates, cloud upload/proxied download wording, AWS us-east-1 creation syntax, Azure connection-string shell quoting, and uncertain S3-compatible provider guarantees. Adds the missing Azure container creation procedure and presents fallback behavior in a table. Moves Apply after every provider setup and identifies unscheduled cleanup-tasks with an actual operator procedure link, keeping final-object expiration warnings visible. Preserved: All local path/durability/replica warnings; explicit STORAGE_PROVIDER and precedence/fail-fast behavior; S3, Azure, and GCS purpose-specific bucket/container variables and fallback exceptions remain. All eight AWS/GCS purpose buckets, exact CORS policies and signed metadata/create-only headers, IAM policy/actions, role/IRSA and ADC/inline-key choices, self signBlob permission, provider endpoint/path-style examples and browser reachability/CSP warnings remain. Apply/recreation instructions, preservation of existing local bytes, provider multipart lifecycle/24-hour session/seven-day Azure window, no final-object expiration, and upload/reload/provider-object verification remain. Renamed headings have no current inbound references. |
+| [platform/self-hosting/observability.mdx](content/docs/platform/self-hosting/observability.mdx) | rewritten | Added deployment monitoring/privacy purpose and moved alerts before telemetry setup. Consolidated tracing warnings into the full two-change Helm configuration. Replaced incomplete PII snippet with a scoped policy/network setup link to Security and Data retention. Documented opt-in Chat content capture and distinguished collection, relay, server spans, log records, browser preference and Trigger.dev telemetry. Corrected Redis outage logging and retained health/probe/metrics/OTLP/CloudWatch limits. | Verified improvement. Adds an operator-oriented opening and makes log-redaction policy activation and verification link explicit rather than equating a deployed PII service with masking. Replaces categorical telemetry confidentiality promises with actual default instrumentation and optional message-capture behavior, and states that collection disabling does not disable the relay. Combines the two Helm tracing changes in one complete example; distinguishes successful scheduler requests from completed work and acknowledges Redis connection errors. Preserved: Both health endpoint shapes, liveness-only limitation, full app/realtime probe budgets, LOG_LEVEL commissioning advice, logs commands/request IDs/product Logs distinction, no stock metrics endpoint, CloudWatch self-hosting scope, and every alert remain. Server/browser defaults, privacy preference, three OTLP signals and log metadata, Trigger.dev distinction/all-or-none Grafana variables, endpoint/sampling precedence, mothership service name, Jaeger OTLP port, and collector setup remain. |
+| [platform/self-hosting/redis.mdx](content/docs/platform/self-hosting/redis.mdx) | rewritten | Separated managed-service guidance from Compose/Helm deployment tabs. Qualified managed service clustering compatibility and sizing/failover assumptions; updated Azure retirement advice. Scoped TLS server-name override to app IPv4 and recommended certificate-matching DNS for app/realtime. Kept fallback/persistence/secret/egress details; verification no longer prints credential-bearing URLs. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Replaces universal managed-service/HA sizing assurances with measured estimates and compatible single-endpoint cluster-policy requirements, including Azure retirement guidance. Correctly scopes TLS server-name override to app IPv4 literals and recommends certificate-matching DNS for both app and realtime. Verification checks URL presence without disclosing credentials and separates a bundled redis-cli ping from testing external connectivity/cross-pod behavior. Preserved: All seven fallback matrix entries; pairing-only Redis requirement vs OAuth; cross-pod collaboration/live-event prerequisite; in-flight streaming/cancellation loss vs committed-data preservation remain. Both Redis/TLS URL forms, Compose external override, Helm auto-managed suppression, Secret envFrom precedence, nonpersistent 512 MiB bundle, external egress rule, private endpoint/auth/TLS recommendations, SNI example and cross-replica functional check remain. Managed Redis tab content is promoted to a normal section, preserving the three cloud choices. Renamed verifying heading has no current inbound repository reference. |
+| [platform/self-hosting/reference-architectures.mdx](content/docs/platform/self-hosting/reference-architectures.mdx) | rewritten | Put cloud provisioning and secrets before sizing; retained IaC, identity, network and placeholder-secret prerequisites. Qualified chart minimum vs supported cloud Kubernetes releases and selected StorageClass/provisioner requirements. Labelled legacy AKS ingress-nginx and Azure Cache recommendations without choosing unsupported replacements. Narrowed ALB certificate warning and allowed supported GKE certificate coexistence/migration. Updated chart example to reconciled published 1.11.8/v0.9.17 and explained appVersion vs explicit pins; added Related docs. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Leads with the operator/chart provisioning boundary; removes unsupported Kubernetes support, EKS StorageClass, throughput, and blanket certificate claims. Updates Azure ingress and managed Redis recommendations and clarifies ALB certificate requirements and GKE mixed-certificate migration support. Corrects version pinning: a pinned chart selects its appVersion when image tags are empty, while explicit tags/digests override. Distinguishes published chart metadata from checkout metadata. Preserved: Complete evaluation/production component matrix, local durability, remote Function/Pi image requirements, default database volume, managed-datastore egress warning, per-cloud infrastructure/identity/timeouts, and optional GPU prerequisites remain. All three secret-delivery strategies, complete existing Secret keys and shadowing, ESO mapping failure, requests/limits, full Terraform helm_release example including six sensitive values, placeholder-secret warning, and onward install/security/verification links remain. |
+| [platform/self-hosting/sandboxes.mdx](content/docs/platform/self-hosting/sandboxes.mdx) | rewritten | Rewrote as execution decision, build/verify, deploy, UI readiness, promotion/rollback and separate-image procedure. Preserved E2B-first Daytona parity requirement and all immutable identifiers, scopes, commands and manifest variables. Added checkout/dependency prerequisites, quoted shell placeholders and removed duplicated Daytona build command. Kept 422/503 conditions, billing-disabled entitlement and browser/server distinction; retained shell/Function/document/Pi separation. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Reorders build, verify, configure, enable controls, and promote/rollback so the accepted E2B manifest exists before Daytona consumes it. Quotes shell placeholders and declares checkout/dependency prerequisites, keeps explicit selected-provider verification, and separates public UI assertion from server readiness. Summarizes local/remote execution paths in a table and adds Pi image distinction without overstating local worker isolation. Preserved: Local JavaScript exceptions, selected sandbox 503 and file-path 422 distinctions, Python fail-closed behavior, entitlement/master-switch/browser flags and visible Settings behavior remain. Both full build commands, API-key scopes, immutable image formats, positive monotonic E2B generations, accepted E2B parity manifest capture and Daytona baseline verification, --generation/--base-template, and higher-generation rollback requirement remain. Public Chat run_function/run_code shell image versus workflow function_execute Function image and separate shell/Function/document/Pi contracts remain. Renamed heading anchors have no remaining inbound repository reference. |
+| [platform/self-hosting/scaling.mdx](content/docs/platform/self-hosting/scaling.mdx) | rewritten | Put prerequisites and measurements before scaling settings; removed unsupported observed-memory guarantee. Corrected Node child workers and deployment-wide scheduled-run cap. Added main/subpool ceilings and actual 30-primary app budget; excluded HTTP-only cron pods from independent database counts. Qualified pooling compatibility and linked direct migration DSN; preserved replica overrides/lag and PDB/HPA behavior. Separated billing-disabled plan limits from fixed safety/admission controls and labelled sizing/topology illustrative. | Verified improvement. Puts Redis and shared-storage prerequisites before scale examples and replaces unverified workload benchmarks with measurements/defaults and clearly labelled estimates. Corrects connection budgeting to sum all active main/subpools rather than charging cron pods for direct database pools; preserves per-role read-replica limits and warns about session locks/direct migrator connections. Corrects scheduled concurrency to a shared database cap; qualifies billing-disabled plan limits versus fixed security controls and removes a false 100-user throughput guarantee. Preserved: All component scaling behavior, full replicas/resources and HPA examples, metrics-server requirement, omitted replicas under HPA, PDB/shared-HPA caveat, scale-down interruption warning, and realtime disable example remain. External database two-flag requirement and app.env.DATABASE_URL override caveat; all read-replica keys/fallback/lag; all sizing values; concurrency settings; limit opt-ins/timeouts; full topology/secrets/password/ESO/PDB example remain. |
+| [platform/self-hosting/security.mdx](content/docs/platform/self-hosting/security.mdx) | rewritten | Moved the pre-launch checklist, signup restrictions, and proxy trust before detailed hardening. Folded repeated FAQ answers into their owners, kept all referenced anchors, and preserved key-loss/rotation and Compose password recovery. Corrected API-key storage wording and local Node-worker boundary; removed unsupported provider isolation ranking/universal SSRF guarantee. Added both inbound and outbound app self-call rules plus stored PII Logs policy and verification; kept fail-closed behavior. Kept allowlist/provenance/redirect/metadata/response-cap exceptions and GPU restricted-profile exception; condensed secret modes and validation rules. | Verified improvement. Puts checklist/access/prerequisites first; integrates duplicate FAQ answers; preserves scoped request provenance while removing the false guarantee for arbitrary sandbox network traffic. Corrects local code worker isolation, stored API-key rotation effects, immutable provider readiness errors, restricted-profile GPU exception, and broad egress override semantics. Adds stored log-redaction policy activation, both directions of app self-call NetworkPolicy, and a concrete masking check; labels timing/memory as measured rather than guaranteed. Final recheck: states that the chart default ingress peer permits any source on listed ports when ingress is enabled, and distinguishes original-key restoration from unrecoverable key loss. Preserved: All five secrets, same-session secret requirement, independent encryption backup, all three delivery strategies and shadowing/mapping consequences, ingress/egress rules, metadata-layer distinctions, optional unisolated workloads, restricted-profile exceptions and writable-root choices remain. All six egress provenance classes, exact allowlist examples/validation/limits, loopback/port/HTTP/Cloud distinctions, legacy compatibility cases, redirect statuses/header/body behavior, 100 MiB response limit and unbounded SSE exception remain. Local-worker security warning, all broker ceilings, PII failure marker/internal URL, historical default Compose password/public-port warning, SQL password rotation and loopback/SSH example, and every checklist item remain. Renamed optional-Chat-policy heading has no inbound repository references. |
+| [platform/self-hosting/troubleshooting.mdx](content/docs/platform/self-hosting/troubleshooting.mdx) | rewritten | Reordered all existing symptoms by deployment, auth/network, models/files, scheduler, restore, and source-only Windows lifecycle. Corrected scheduler-vs-auth diagnostics, Redis TLS scope, host alias behavior, private-host allowlist example and proxy owner links. Kept every diagnostic command and embedding/model exception; preserved encryption recovery and TLS-verification warning. Qualified CA-chain guidance and preserved UNABLE_TO_GET_ISSUER_CERT; normalized headings and Bun invocation. | Verified improvement. Reorders every symptom into deployment, login, network, model/storage, scheduler, restore, and source-only recovery order; replaces assumptions with diagnostic interpretation. Corrects shipped Linux host alias, Redis IPv4/app-only SNI scope, stale CronJob diagnosis, TLS chain/bundle caveats and cloud MiB completion threshold. Avoids deleting browser state before collecting errors and replaces printenv Redis credential exposure with presence checks. Preserved: All 23 original symptom families remain, including doctor modes/flags/exit status, database/migrations/pgvector/Kubernetes readiness/image/PVC, realtime/proxy/buffering/disconnects, Redis, TLS trust, private destinations, Ollama/LM Studio auth/prefix/URL/env propagation, CORS, embeddings width/recreation, schedules/polls/Teams, restored credentials, and Windows WSL/LF. Full Compose/Helm command examples, exact settings/env/error/status names, PostgreSQL verification and migration restart, HTTP in-pod secret expansion, original encryption-key recovery, and help links remain. Linux host-IP fallback remains available in the custom-container LM Studio guidance; shipped alias works across hosts. Renamed symptom headings have no current inbound repository references. |
+| [platform/self-hosting/upgrades.mdx](content/docs/platform/self-hosting/upgrades.mdx) | rewritten | Moved the upgrade procedure and rollback before advanced migration mechanics. Updated reconciled published release/chart examples and documented pinned SIM_VERSION behavior before update. Corrected SQL retry budget to 20 minutes; retained 30-minute advisory acquisition, session checks, lock/statement timeouts and connection-error retries. Separated migration DSN delivery modes and kept pooled/direct connection hazards and init-container failure recovery. Preserved all backup/rehearsal/CLI install-kind/pinning/Ollama profile/restore data-loss steps; qualified application-only rollback and password-history inference. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Improves rollback safety: additive migrations alone no longer prove older-app compatibility; puts write-loss and stopped-writer consequences before restore steps. Corrects image/chart pin coupling and actual published version, migration retry budget, pin updates before sim-setup update, shell placeholders, helm-diff prerequisite and persisted-database password diagnosis. Keeps operator procedure concise and moves advanced migration mechanics into a lookup section. Final recheck: restores the concise direct MIGRATION_DATABASE_URL prerequisite before upgrade commands, including Helm/Compose delivery constraints and #migration-environment link. Preserved: All three aligned images and independent cron pin, tag/digest examples, five-step release/backup/rehearsal/apply/verify procedure, snapshots/pg_dump database names, full Helm/Compose/source/Ollama upgrade modes/profile commands, managed-file protection and maintenance downtime remain. Both rollback modes and all writer stopping/restore/old release/secret/verification consequences, all five migration failure diagnoses and do-not-skip-journal warning remain. Complete forward-only SQL/data migration behavior, replica serialization, 30-minute/5-second acquisition, direct DSN/backend PID guard, Helm/Compose propagation, SQLSTATE 55P03/20-minute retries, once-only scripts and 10 transient startup retries remain. Renamed how-migrations-run heading has no current inbound references. |
+
+### Workflow core (16)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [workflows/connections.mdx](content/docs/workflows/connections.mdx) | rewritten | Clarified execution edges versus references, period/whitespace normalization and skipped/missing output behavior Corrected Agent toolCalls list/count and qualified normal API and structured Agent output shapes Replaced nonexistent Router content with context, selectedRoute and reasoning; kept model, tokens and selectedPath. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. Marked output examples as abbreviated; qualified optional Function files, bounded stdout, Agent metadata collisions, and Evaluator fallback scores. | Verified improvement. Separates execution dependencies from value tags and distinguishes unknown names, invalid fields, and known skipped blocks. Corrects Agent toolCalls to list/count, Router fields, and abbreviated optional outputs; adds structured metadata collisions, bounded Function stdout, and Evaluator zero-score qualification. Preserved: Retains normalized names, case-sensitive paths, nested objects, multiple array indices, picker/drag interaction, mixed text and typed Function references, all six complete output examples, and numeric-conversion caution. The existing connections video remains. Its appearance/playback was not assumed verified; no stale-media claim is used. |
+| [workflows/data-flow.mdx](content/docs/workflows/data-flow.mdx) | rewritten | Kept one classify/reply preview and OutputBundle; removed repeated preview Explained last terminal completion, selected blockOutputs projection and v2 Response envelope | Verified improvement. Explains that references select data while edges ensure availability, including active-path joins and skipped-block resolution. Adds completion-order-dependent default workflow output, deliberate final blocks, selectedOutputs projection, and the v2 envelope distinction. Preserved: Retains the complete Classify/Reply workflow and typed OutputBundle; removes only the duplicate highlighted rendering. All six original data kinds, file metadata, per-block output names, reshaping guidance, picker behavior, and Logs navigation remain. Table row nesting and Function result are more explicit. |
+| [workflows/how-it-runs.mdx](content/docs/workflows/how-it-runs.mdx) | rewritten | Preserved four distinct corrected shared previews and dependency/error-port rules Added shared Parallel state and non-2xx API error path; labeled timeout defaults and billing-disabled behavior | Verified improvement. Qualifies handled versus unhandled failures and successful API status outputs instead of implying all failures stop runs. Corrects shared workflow variables inside Parallel and labels execution durations as billing-enabled defaults, with billing-disabled self-hosted configuration and admission/log limitations. Preserved: All four distinct previews remain: independent work, join, routing, and error/success ports. All nodes, displayed settings, and edges were read. Retains dependency readiness, active-path joins, first matching branches, Loop/Parallel nesting, call-chain limit, 5/50/90-minute and Enterprise seven-day limits, timeout consequence, and batching recovery. |
+| [workflows/index.mdx](content/docs/workflows/index.mdx) | rewritten | Reduced five repeated previews to one structured classification example Preserved #blocks/#triggers, trigger taxonomy including Sim events and block/tool distinction Added explicit terminal-result/v2 envelope and draft/live boundaries | Verified improvement. Leads with one actual structured-classification example and concrete trigger/block/tool/connection/output definitions instead of five repetitions of the same preview. Adds Sim Workspace Events to trigger taxonomy and clarifies default terminal output, v2 Response behavior, and draft/live Update semantics. Preserved: Retains the classify use case, block/tool distinction, deterministic rule/code versus model behavior, fan-out answer, all trigger families, data-flow navigation, and stable #blocks/#triggers/#how-it-runs/#next IDs. The remaining preview explicitly requests category/urgency in a complete JSON Schema rather than implying ordinary content magically becomes named fields. |
+| [workflows/variables.mdx](content/docs/workflows/variables.mdx) | rewritten | Replaced isolated Parallel scope with shared run-scoped variables Kept types, initial reset, literal/reference assignment and Function arithmetic distinction Qualified secret grants, personal ownership/current UI nuance, Unredacted and exact protection scope | Verified improvement. Replaces false per-Parallel-variable isolation and universal workspace visibility with shared run state and authorization/grant-aware secret access. Distinguishes reserved reference prefixes, unknown/skipped references, arithmetic versus assignment, and protected versus Unredacted secret projection. Preserved: Retains all five types and initial-value examples, panel procedure, normalized/nested references, per-run reset, same-name workspace precedence, string placeholder coercions, and OAuth/account guidance. The exact execution-log protection owner is linked at the point of use. Settings first-character constraint is explicitly scoped to the Settings UI; broader v2 secret character policy is not falsely narrowed. |
+| [workflows/deployment/agent-events.mdx](content/docs/workflows/deployment/agent-events.mdx) | rewritten | Consolidated negotiation/policy rules and preserved all frame, reset, abort, reconnect and memory distinctions Added separate chat-outputs-v1 capability; replaced unsafe reference parser with body/blockId checks and terminal handling Kept generated Agent table as linked support owner | Verified improvement. Consolidates independent negotiation and exposure policies, correct UI labels, authenticated API example, structured chat-output capability, and terminal/nonterminal distinctions. The full reference parser now guards HTTP/body/block IDs, handles terminal success/error immediately, separates answer/thinking/output buffers, and cancels/releases its reader. Preserved: Retains every frame class, JSON DONE sentinel, chunk resets and interleaving, answer cadence, public tool-metadata limits, stripped reasoning timing, abort/cancel distinctions, live-only reconnect behavior, editor policy, and durable memory boundaries. All Bash and TypeScript examples and all table frames reviewed in full. Detailed provider/model coverage is preserved in the linked generated Agent support region; compact family qualifications remain locally. |
+| [workflows/deployment/api.mdx](content/docs/workflows/deployment/api.mdx) | rewritten | Reorganized authenticated task and sync/SSE/async behavior, preserving language/request/polling examples Corrected token-stream header/reset requirement, v2 Response/error envelope and public/async/manual restrictions Preserved opaque large refs, statuses, retention, retry/reconciliation and key guidance Root standardized the exact Sim API keys settings label and added transient redacting status to polling guidance. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Orders deployment/authentication before requests and explains sync run-resource failure statuses, SSE negotiation, NDJSON heartbeats, async restrictions, manual draft policy, and one-shot run-ID reconciliation. Corrects v2 Response/status/envelope claims, structured capacity errors, transient redacting status, named selectors, and raw-SSE example purpose. Preserved: All cURL/Python/TypeScript sync and stream examples, thinking/tool example, async receipt/polling/completed output, full large-value reference, status table, timeout cap, retention, rate headers, and compromised-key recovery remain. Version/update/rollback/undeploy facts and all three legacy v1 examples are moved to linked Deployment; exact timeout default table is in linked How workflows run; key lifecycle stays linked to Authentication. Public access, description, and output picker procedures remain locally. |
+| [workflows/deployment/chat.mdx](content/docs/workflows/deployment/chat.mdx) | rewritten | Made Agent Memory explicit; latest input/conversationId/files are actual message payload Preserved creation/output/access/share/embed/file/OTP examples and input limit Distinguished hosted OTP resend countdown from server limits and broadened 403 diagnosis Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Corrects automatic full-conversation claims with latest-message/files/conversationId payload and explicit Agent Memory setup. Adds deployment role/capability, live/reset protocol, independent events and structured outputs, working cookie-jar OTP requests, exact encoded-file units, and broader 403 diagnosis. Preserved: Retains all launch fields/default greeting/output choices/access modes/slug rules, password/email/SSO procedure, direct link, complete iframe, cURL/TypeScript submission, file example, OTP flow, input cap, and troubleshooting. The focused allowed-email screenshot remains and was visually inspected. Removed broad launch/output screenshots duplicate the complete written controls; old unsupported voice/full-history language is not treated as a useful current guarantee. |
+| [workflows/deployment/index.mdx](content/docs/workflows/deployment/index.mdx) | rewritten | Made this the canonical Admin/deploy/update/version/compare/load/promote/undeploy owner Moved full v1 deploy/undeploy/rollback examples from API guide here Clarified definition snapshot versus mutable resources and successful live-state verification | Verified improvement. Makes deployment the canonical role/prerequisite/version/task owner and adds actual comparison, draft replacement warning, promotion verification, and undeploy consequences. Moves complete legacy deployment API examples here and qualifies active snapshots versus separately mutable resource contents and explicit manual draft API. Preserved: Retains snapshot/version/live definition, numbering/actor/date, Update toolbar, Rename/description/Promote/Load actions, common active deployment, API/chat/MCP links, and complete v2 input call. All deploy/undeploy/rollback commands from the old API page are present with optional deploy body and specific-version guidance. Update screenshot was inspected and matches the stated control. |
+| [workflows/deployment/mcp.mdx](content/docs/workflows/deployment/mcp.mdx) | rewritten | Corrected Admin-only management and separated invocation auth Preserved server/tool lifecycle, parameter defaults/overrides and live snapshot behavior Replaced old bridge configurations with official Cursor/Codex/Claude Code/VS Code HTTP examples and verified Claude Desktop remote headers flow | Verified improvement. Corrects workflow-MCP management to Admin with no workspace-key access, separating authenticated invocation from management. Replaces outdated bridges/interpolation/CLI flags with direct HTTP Cursor, Codex, Claude Code, Claude connector, and VS Code examples and primary documentation. Preserved: Retains server creation/details/URL/tool lifecycle, public/private headers, optional initial workflows, tool name/description fallbacks, parameter descriptions/overrides/redeployment, client picker/install link, tool/server deletion consequences, and live snapshot behavior. All JSON/TOML/Bash configurations were read in full. Removed screenshots/videos duplicate complete step procedures; remote videos were not declared stale from an uninspected appearance. |
+| [workflows/triggers/rss.mdx](content/docs/workflows/triggers/rss.mdx) | rewritten | Corrected 500 identifiers, subscription creation boundary, per-poll 25/backlog and no-date cases Removed impossible feed.language reference; preserved bounded item/feed outputs and actual failure/backoff behavior Moved FAQ facts into visible behavior sections | Verified improvement. Corrects 500-identifier retention and subscription-creation date boundary, no-date exceptions, 25-per-poll eligible backlog, admission-refusal retries, and limited feed projection. Makes backoff/Retry-After, auto-disable/reset, 10 MiB fetch limit, self-hosted poller, and verification visible outside FAQs. Preserved: Retains feed-only setup/no connected account, RSS/Atom support, normal minute cadence, item/feed/convenience/timestamp outputs, all supported item fields, per-item runs, duplicate prevention, 25 selection order, and 100 failures/recovery. The impossible feed.language example is replaced with feed.description. A concrete release-summary procedure replaces generic lists; monitoring/podcasts use the same preserved per-item mechanism. |
+| [workflows/triggers/schedule.mdx](content/docs/workflows/triggers/schedule.mdx) | rewritten | Used exact settings, valid minute examples, cron alignment and browser timezone/UTC fallback Preserved deployment/registration, multiple blocks, 100-failure and five-minute 429 defer behavior Linked required self-hosted scheduler and removed stale disabled screenshot | Verified improvement. Corrects elapsed-timer/1–1440-minute implication to valid cron minute steps, browser timezone initialization and UTC stored-value fallback. Adds exact controls, next-run/log verification, queued-versus-running distinctions, external scheduler prerequisite, and non-429 admission failures. Preserved: Retains all six modes, hourly minute bounds, all three cron examples, deploy/update/undeploy registration lifecycle, multiple independent schedules, 100 failures/badge reactivation/success reset, and five-minute 429 deferral. Removed disabled screenshot adds no procedure beyond named badge action. Longer intervals are supported through Hourly/Daily/Custom rather than misleading invalid minute steps. |
+| [workflows/triggers/sim.mdx](content/docs/workflows/triggers/sim.mdx) | rewritten | Added actual setup/defaults for all events and run-backed conditions Separated No Activity poller/deployed scope, null payload fields and per-source inactivity cooldown Preserved billing/rate/fire-and-forget/recursion and deployment snapshot constraints | Verified improvement. Adds exact default event/threshold settings and complete wire payload example rather than UI-only event descriptions. Separates No Activity poller, deployed/unarchived scope, never-run behavior, and per-source cooldown from run-backed one-hour subscription cooldown. Preserved: Retains all four plain events and seven rules, workspace filters/self-exclusion, rate minimum five, duration/cost units, truncation, run versus triggeringRun fields, deployment version, fire-and-forget/billing/rate policy, anti-recursion, and redeployment requirement. Adds explicit null-inapplicable fields and self-hosted background-job link. Removed tab/list duplication loses no payload fields. |
+| [workflows/triggers/start.mdx](content/docs/workflows/triggers/start.mdx) | rewritten | Corrected public API nested input and built-in outputs supplied outside Chat Added descriptions and trusted advanced run metadata with reserved field constraints Preserved defaults/coercion/files/editor priority/mock payloads; distinguished v2 explicit entry selection Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Corrects API fields to nested input and chat payload to latest message/files/conversation ID instead of arbitrary launch context or chat-only built-ins. Adds trusted run metadata, reserved fields, valid primitive coercion, and explicit v2 manual entry/mock selection constraints. Preserved: Retains all types/file inputs, defaults for absent/null but not empty string, editor form/upload ordering, normalized references, multiple triggers/editor priority, mock payload testing, and early validation advice. All three surface tabs and the full request example were read. Old screenshot is redundant with complete visible field table; legacy output fields remain described when supplied by other execution surfaces. |
+| [workflows/triggers/table.mdx](content/docs/workflows/triggers/table.mdx) | rewritten | Added deleted-row event; removed nonexistent either option and used exact field labels/defaults Clarified name-keyed rawRow/mapped row, previousRow/deletes, watched columns and direct fire-and-forget behavior | Verified improvement. Adds deleted-row events and correct one-event-per-trigger choice, exact UI fields, default Inserted/header mapping, and same-workspace selection. Corrects rawRow as name-keyed projection and delete previousRow semantics; distinguishes committed mutation from follow-up workflow success. Preserved: Retains all nine references, optional watched-column filtering, table identity/headers/timestamp, mapping toggle, and insert/update use cases. Current hero now uses Event/Watch Columns and a configured Row Updated example. Verification includes a real row event and Logs; missing row fields are qualified. |
+| [workflows/triggers/webhook.mdx](content/docs/workflows/triggers/webhook.mdx) | rewritten | Corrected stable identifier dedup, optional methods and filtered exposed headers with defaults Separated acknowledgement from completed response; preserved deploy/verification/token/port/payload conditions Added authenticated/idempotent curl verification and service-trigger ownership link | Verified improvement. Corrects authentication-on/default Bearer versus exclusive custom header, optional accepted methods, filtered opt-in headers, and scalar stable-ID deduplication. Separates queued receipt/custom acknowledgement from workflow completion and setup verification; provides authenticated, repeatable dedup/auth rejection examples. Preserved: Retains generated URL/deploy requirement, optional named input/file shape, payload references, headers/query/method conditions, configurable response, validation warning, rate limits/no auto-disable, and integration-trigger navigation. Complete curl retains test userId/event and adds a stable key/token. Removed service-specific Slack video is redundant/different-service scope; provider procedure remains linked rather than declared visually stale. |
+
+### Enterprise governance (8)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [platform/enterprise/access-control.mdx](content/docs/platform/enterprise/access-control.mdx) | rewritten | Renamed visible title to Permission groups, retained route, and ordered availability, creation, scope, provider/block/platform references, enforcement, deployment, and related docs. Corrected default fallback versus stacked restrictions, empty SCIM explicit groups, human principal versus workspace-key authority, trace/cost projection, and remembered tool approval. Added Agent default, Knowledge Base Export, Project Issues checklist semantics, current Create group/row/Save navigation, and master/explicit flag precedence. Preserved all platform capabilities, auth/connector allowlists, one-group assignment conflicts, immediate scope/member mutations, external membership scope, start_trigger exemption, existing-workflow failure, and environment allowlist intersection. | Verified improvement. Clarifies one-group fallback rather than intersection, SCIM empty explicit groups, actual actor policies and workspace API-key authority; adds Project Issues and Agent default. Preserved: All permission categories, provider/model and block/tool lists, organization-only rows, conflict behavior, save/immediate scope distinction, external members, instance allowlist and existing-workflow recovery retained. Screenshots replaced by full control/reference tables. |
+| [platform/enterprise/audit-logs.mdx](content/docs/platform/enterprise/audit-logs.mdx) | rewritten | Ordered role/entitlement, viewer, export, versioned API, event semantics, limitations, operator API, and related docs. Corrected historical workspace scope and departed/external-actor defaults; labelled v1 compatibility alongside v2. Preserved v1 fields, response, personal-admin key requirement, workspace-key refusal, cursor/limit, event categories, anonymous/operator attribution, best-effort exception, and tamper limits. Preserved 10,000-row/64 MiB export bounds and truncation, sensitive CSV fields, deployment-admin headers, all-instance scope, offset defaults and max250. Focused source check corrected viewer to resource-type/date filters plus workspace deep-link chip; search also matches actions/actors/resources, not an invented actor picker. | Verified improvement. Separates current/departed actors, CSV/JSON sensitive fields, representative events and best-effort persistence; adds supportedv2 navigation without silently alteringv1 contract. Preserved: Fullv1 request/response/query/rate-pagination example retained including USD limits; all event families, export10000/64MiB caps, admin offset API differences, scopes/keys and tamper limits preserved. Screenshot replaced with named viewer controls and columns. |
+| [platform/enterprise/custom-blocks.mdx](content/docs/platform/enterprise/custom-blocks.mdx) | rewritten | Moved source-admin and organization/feature prerequisites before Workspace settings publication procedure. Added Required input overrides, exact field/output caps and reserved names, current Save, and latest-deployment interface behavior. Corrected Disable/Delete/source-undeploy effects on existing placements; API publication enabled flag is distinguished from disabling a canvas block. Preserved source-owner delegated/personal authority, source-workspace variables/billing, curated output boundary, child logs, default-off consumer tracing, future-only policy changes, opaque failure reference, and fixed source. | Verified improvement. Corrects deletion and disabling to leave broken placements; source access, billing and consumer trace boundaries now precise. Preserved: All input/output/presentation/trace controls, latest deployment, fixed source, required outputs, admin role, source-owner credentials and failure reference retained; useful toolbar screenshot remains. |
+| [platform/enterprise/data-drains.mdx](content/docs/platform/enterprise/data-drains.mdx) | rewritten | Ordered create/test/run procedure, source/schema boundaries, seven destination references, delivery bounds, retention pairing, rotation/deletion, and operator scheduling. Corrected Create drain/New drain/Create actions, Every hour/day labels, detail-page last10 run fields, and API-only destination locators. Corrected BigQuery best-effort deduplication, local Snowflake guard, S3 path-style/public HTTPS and probe cleanup; preserved provider fields/auth/object paths and webhook headers/signature/retries. Preserved source IDs/wire values, all-history backfill, five-minute window, mutable Chat snapshot behavior, exact caps, partial acceptance/replay, stored PII policy, encrypted credential omission/replacement, external lifecycle, and deletion effects. Separated UI recreate from API credential rotation; preserved CRON_SECRET, disabled404/no-op behavior, optional Trigger.dev, and bounded two-job database runner; changed doctor invocation to bunx. Clarified powers-of1024 source bounds and BigQuery 10 MiB request guard from owning source instead of old ambiguous MB wording. | Verified improvement. Introduces concrete verify procedure, exact binary/decimal bounds, incomplete-export and rotation/cursor consequences; avoids CDC and dedup guarantees. Verified late fix: Cloud destinations require public addresses and HTTPS. Self-hosted S3-compatible endpoints may be approved private or named loopback destinations but remain HTTPS-only; self-hosted webhooks may use HTTP only where configuredEndpoint policy allows it. Metadata refusal, pinned address, signed S3 target behavior, authentication, retry, deduplication and source bounds remain. Preserved: All5 source wireIDs,7 destinations with auth/schema/permissions/objectlayout, complete HMAC headers, at-least-once checkpoints, stability window, retry schedule, source/limit caps,20/25min bounds, deletion and retention consequences retained. |
+| [platform/enterprise/data-retention.mdx](content/docs/platform/enterprise/data-retention.mdx) | rewritten | Moved exact Cloud/Enterprise/billing-disabled default table before organization/override configuration. Preserved all UI periods and 24-43,800-hour API bounds, independent field inheritance/null/Forever, whole-policy PII replacement, removal fallback, and irreversible shortening. Corrected file-version coalescing and protected current+9 previous floor, 500 superseded ceiling and Free99 previous cleanup; kept API-only field. Added startedAt log age, active paused-run protection, logical versus physical cleanup, stage-selection prerequisite, failed redaction behavior, and text-only/non-retrospective scope. Preserved resource families, Task age basis, exact entity/language options, output recognizer exclusions, patterns/tokens/max20, and computation warning. Preserved four CRON_SECRET endpoints, missing shipped schedules, explicit/master enablement, optional inline cleanup, PII service Helm naming/manual-value precedence and Compose prerequisite. | Verified improvement. Replaces false no-deletion defaults with scoped plan windows and independently distinguishes age expiry, count caps, active pauses and logical/physical cleanup; adds fail-closed PII behavior. Verified late fix: Current paid default row explicitly covers Pro and Max, including Teams. Execution/job logs and task cleanup have no default age expiry; soft-deleted resources use 90 days and previous file versions use 180 days. Free, Enterprise, self-hosted, override, count-cap and cleanup qualifications are preserved. Preserved: Every retention option/APIhours, override inherit/null semantics,3PIIstages/all language/entity/pattern coverage, restore cautions,4unscheduledcron endpoints,PII deployment methods preserved.2functional screenshots remain. |
+| [platform/enterprise/forks.mdx](content/docs/platform/enterprise/forks.mdx) | rewritten | Replaced repeated per-resource scenarios with direct-edge model, availability/roles, fork and sync procedures, policy, resource reference, recovery, and troubleshooting. Corrected billing-mode entitlement, no extra rollout prerequisite, membership/Project/personal-key snapshot, drafts/background-copy state, and copied chat deployment requirement. Preserved map/copy precedence, saved versus current-review choices, required dependents, full sync and exclusions, source-deleted archive versus undeploy, canonical folder scopes, and literal-secret caveat. Added trigger URL review, target custom-block mapping, exact preview/fingerprint/request-ID retry rules, applied versus completed receipts and deployment readiness. Preserved lineage-wide forward-only default, copy-arrival checked state, resource/OAuth/secret/KB distinctions, public API flag effects, history/key/memory exclusions and archived-chat suppression. Corrected rollback archive/undeploy, prior-deployment reactivation/pending recovery, copied-resource retention, skipped hard-deletions, and permanent one-sided disconnect/Project subtree split. | Verified improvement. Corrects live-chat, native-target/archive and rollback guarantees, adds actual preview/requestId/followup protocol, trigger adoption and memberships. Preserved: Every resource category, directedge/admin matrix, copy/map/dependent scope, unsynced checkboxes, lineage-wide forward-onlydefault, concrete files/example, connector gap/reconnect, background activity and destructive consequences retained.2screenshots locate clearedrefs and dependent field. |
+| [platform/enterprise/usage-tracking.mdx](content/docs/platform/enterprise/usage-tracking.mdx) | rewritten | Ordered owner/admin and entitlement, exact period/credit units, tabs, activity definitions, source attribution/reconciliation, BYOK, export/API and operator configuration. Corrected Export/All events labels, conditional audit-log Open logs link, exact100,000-event cap and four-decimal precision. Resolved legacy mothership_block/visible Agent block attribution to current Sim Chat workflow block; ordinary Agent model calls stay Workflow. Preserved distinct retained Activity metrics/status denominators/first start continuation counting, ownership/history effects, ledger separation, all source rows, nonadditive views, and No workspace attribution. Removed unsupported Chat benchmarking and blanket BYOK non-recording claim; qualified verified workflow-model coverage and separated Logs USD from Billing/run-resource credits. Added organization summary/breakdown/event API links and retained 92-day UI bound, timezone edge bars, current-period consumption versus invoice distinction. | Verified improvement. Corrects ordinaryAgent attribution vs SimChat block label, credits/USD/rounding and invoice distinction; adds actual100000CSVcap and supported org APIs. Preserved: Every metric denominator/duration/retained-history boundary, period/timezone/92days,5tabs/sources/workspace example, own-key exclusion, No workspace, combinedChat surfaces and export columns preserved. |
+| [platform/enterprise/whitelabeling.mdx](content/docs/platform/enterprise/whitelabeling.mdx) | rewritten | Ordered organization scope/entitlement, current Save procedure/fields/verification, fallback, instance variables, Helm asset serving and related docs. Corrected external authorized workspace viewers to host-organization branding and removed instant-all-open-tab propagation guarantee. Preserved logo/wordmark formats/5 MiB/64-char limits, loading fallback, four hex colors, email/URL validation, saved-field precedence, and public-surface differences. Preserved every environment variable, billing-disabled default/explicit off, no-organization instance baseline, favicon/custom CSS/background distinctions, brand-detection variables, and files/binaryFiles mount layout. Removed unverified .sidebar CSS selector and described current same-origin CSS/content-policy requirement. | Verified improvement. Corrects scope for authorized external members, refresh/fallback and shell-safe quoted hex examples; separates instance/public UI exceptions. Preserved: Every identity/color/linkfield/5MiB/64character bound, all instance envkeys, favicon/CSS/background distinctions, brandingConfigMap text/binary examples and same-origin CSP restrictions retained. |
+
+### Search (21)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [search/coda.mdx](content/docs/search/coda.mdx) | rewritten | Ordered connection, queries/reads, service boundary, and troubleshooting. Retained separate personal MCP/REST service credentials, Enterprise org-admin requirement, opened-doc picker/manual IDs, exact-doc checks, REST title-only compatibility/email match, read allowlist, URI compatibility, and limited date coverage. | Verified improvement. Moves shortest personal setup before query/access detail; clearly separates personal MCP grant from REST service boundary. Preserved: Both modes, every-reader connection, Superhuman login, fixed read allowlist, both URI schemes, limited recency coverage, legacy title-only/email-match path, token rotation and Enterprise org-admin prerequisite retained. All six troubleshooting intentions remain; primary API links and separate KB REST owner remain. No media existed. |
+| [search/confluence.mdx](content/docs/search/confluence.mdx) | rewritten | Moved service-token scopes before service setup while preserving #using-a-service-account for three inbound consumers. Retained Cloud-only adapter, member grants, all thirteen service scopes, spaces/type/label OR behavior, missing-space denial, four-site cap, native cursor, attachment/OCR exclusion, and token/app recovery. Linked canonical Atlassian member OAuth console steps/full scopes while retaining callback, variable names, distribution and saved-configuration/reconnect consequences. Rebase delta: retained staging all-terms overflow relevance ranking, partial/no-cursor result, native-CQL pagination and ranking-failure fallback. | Verified improvement. Moves service scopes before central-source instructions; delegates repeated full OAuth setup to verified canonical owner. Adds accurate upstream relevance-page/no-cursor/fallback behavior without treating provider order as exhaustive. Preserved: Cloud-only and personal-plus-service checks, all13 service scopes, explicit spaces/All/manual keys, labels OR, source status/type/readability, four-sites CQL and attachment/OCR exclusion retained. Original exact callback/environment keys, distribution, read:me/offline_access, provider configuration and reconnect requirements remain locally or in linked Atlassian setup. |
+| [search/connect-your-account.mdx](content/docs/search/connect-your-account.mdx) | rewritten | Made connect and verify the first task; grouped provider exceptions and recovery. Retained separate Google grants, personal-vs-service boundary, GitLab identity rules, connection requests not invitations, workflow disconnection consequences, and scope/rate-limit troubleshooting. | Verified improvement. Turns connect into connect-and-verify and names exceptions rather than generic indexing recovery. Preserved: Invitation/SSO/verified identity, popup recovery, not-configured/missing provider, no initial indexing, all seven provider exception rows, separate Google grants, GitLab no-personal connection, reconnect/disconnect shared-workflow consequence and connection-request-not-invitation retained. Generic Secrets Manage secrets label correct; original missing-results checks retained. |
+| [search/fireflies.mdx](content/docs/search/fireflies.mdx) | rewritten | Ordered connect, plain keyword/date queries, transcript evidence, and limits. Retained personal MCP vs KB key, fixed endpoint, 255-character query, exclusive meeting-date bound, absent modification times, 49-result lookahead/cursor, stable tool/JSON/scope behavior, ongoing speech snapshot, generated-summary distinction, truncation and failures. | Verified improvement. Uses Connect→queries/dates→evidence order and reduces repeated permission prose. Preserved: Fixed official endpoint/personal OAuth, separate KB key,255character keyword,scope all,dates/exclusive end/no modification time,49meetings+probe,numeric continuation, speaker/timestamp/summary distinction, ongoing snapshot and visible limits retained. Read-only schema/grant checks, plans/quotas and explicit failures retained; no media existed. |
+| [search/generic-secrets.mdx](content/docs/search/generic-secrets.mdx) | rewritten | Ordered source mode, use, and removal; clarified names-only discovery and code environment mounting. Retained admin/member editor access, Build/Plan-only mount, selected-mode isolation, same-name organization precedence, and deletion of both secret sets. | Verified improvement. Puts destructive source removal in its own section after usage instead of burying it in the setup paragraph. Preserved: Organization and Member modes, admin/member editor paths and view/use split, mode switch, deletion consequence, names-only mounts through run_code/run_function,org-before-workspace precedence and Build/Plan-only boundary retained. Source is explicitly distinct from documents, provider connections and workspace secrets. |
+| [search/github.mdx](content/docs/search/github.mdx) | rewritten | Ordered connection, repository setup, discussion queries, access/changes, and troubleshooting. Retained exact native qualifiers, per-repository App boundary, independent member authorization, default branch/code-only filters, 100-repo discovery, discussion categories/caps/links/review context, provider access freshness, and unsupported hosts. Clarified explicit commits kind; retained #add-a-repository and canonical self-hosted App link. | Verified improvement. Leads with platform/mode boundaries and organizes exact PR query examples before management/troubleshooting. Preserved: Default branch, first100 repositories, explicit scopes, repo-per-App-source, owner approval, personal grant once/org, stable identities/code filters, all four PR query examples, comments/reviews/history caveat,3×50+120000/category and source offsets retained. All seven recovery checks and separate indexed KB link preserved; enterprise hosts excluded and explicit commits kind clarified. |
+| [search/gitlab.mdx](content/docs/search/gitlab.mdx) | corrected | Removed the obsolete restored indexed Search exception. Preserved instance-admin vs non-admin CSV strategies, 17.4 admin requirement, PAT scopes, self-managed host protections, every filter, CSV headers/examples/limits/dedupe/conflicts/inherited membership, confidential restrictions and fail-closed authorization. Grouped request access checks separately from current permission updates and PAT rotation, preserving blank-token retention and invalid/stale-update behavior. | Verified improvement. Puts administrator-versus-CSV decision and server requirements before project setup; compresses duplicates without losing its detailed authorization contract. Preserved: Self-managed17.4admin path,read_api/admin_mode,nonadmin alternative,verified email/no personalgrant,all six resource filters, both exact CSV templates and headerless option,4MiB/100000rows/10MiBrequest,dedupe/conflict/grant semantics, confidential exclusion and rotation retained. All seven failure/recovery rows preserved; legacy restoration mention removed because live backend legacy toggle was removed upstream, ordinary KB remains linked. |
+| [search/gmail.mdx](content/docs/search/gmail.mdx) | corrected | Corrected reads to matching anchor plus up to seven recent independently authorized conversation messages, with final fresh source checks. Added actual per-message/MIME bounds and notices; retained same-mailbox delegation, active Workspace/customer/user checks, label names/OR, rolling dates/query/category restrictions, message-vs-UI matching and attachment exclusion. Moved common Google member OAuth console/scopes to canonical owner while retaining exact callback, API/variables, separate delegation scopes and reconnect instructions. | Verified improvement. Adds source-backed upstream independently authorized conversation context; points repetitive Google app setup/scopes to complete canonical owner. Preserved: All setup/delegation scopes,primary Users/empty restriction, labels OR/names,rollingwindow,query exact candidate, default exclusions,INBOX same-mailbox example, API/UI differences and attachments exclusion retained. Personal callback/google-email,client vars,broad workflow scopes,reconnect/providerconfiguration and union service-account owner link retained. |
+| [search/google-calendar.mdx](content/docs/search/google-calendar.mdx) | rewritten | Ordered connection, service prerequisite/configuration, event details, recovery, and member OAuth. Retained all three service/picker scopes, personal identity and same-member delegation, primary alias/shared-calendar checks, active customer/user restrictions, cancellation/window checks, service ±30-day default, recurrence/timezone/attendee/privacy behavior. Linked common Google member OAuth setup/full scopes; retained callback, API/variables and grant distinction; stated bounded 20-calendar traversal. | Verified improvement. Separates member setup, delegation prerequisites and source-specific restrictions; removes repeated generic OAuth procedure only after canonical owner contains it. Preserved: All three delegation scopes,picker-needs-calendar.readonly,activeDirectory/customer/Users,same-user primaryalias/sharedIDs,30day rolling default,recurrence/timezone/attendees/privateview,attachment/recording exclusion and all five recovery checks retained. Callback/calendar,client vars,broad personal calendar scope and separate grants/reconnect configuration retained. |
+| [search/google-drive.mdx](content/docs/search/google-drive.mdx) | corrected | Corrected supported reads to include bounded downloadable PDF/DOCX text; preserved no OCR and metadata-only unsupported binary formats. Preserved Sheet bounds, parser size/page/expanded limits, comment/reply provenance and caps, source checks, selected folders/descendants, six-user verification and external-reader fallback/partial coverage. Retained full service scope/three-source union and saved Meet document distinctions; linked common Google member console/scopes to canonical owner. Added verified Sheets API enablement for member-grant Sheet reads and targeted recovery; preserved shared-service-account inbound anchor. | Verified improvement. Adds verified upstream complete bounded PDF/DOCX extraction and needed Sheets API prerequisite; groups readable content and discussions before service setup. Preserved: Member/service intersection,Docs/Sheets/Slides,text,20sheets1000rows52cols,comment metadata/replies/3×20/120000partial/offsets, no global comment index,all4service scopes,sixusers/fallbackpartial,folderancestry/type,shared-account scopeunion and Meet saved Docs query retained. Original full member OAuth setup/scopes lives in canonical Google owner; exact local callback/vars/reconnect remain. No useful media lost. |
+| [search/google-meet.mdx](content/docs/search/google-meet.mdx) | rewritten | Led with recent finalized transcript/note-link purpose and separated reader tasks from self-hosted setup. Retained transcript vs smart-note metadata/no body, explicit kinds/space scope, three-conference/five-artifact cap, unsupported query/date fields, complete-or-fail reads, 30-day retention, transcription prerequisite, and no audio reconstruction. Kept Drive/Calendar alternatives and disconnection consequences; moved full member scopes/consent steps to canonical Google guide and retained API/callback/variables/sensitive-scope prerequisite. | Verified improvement. Adds a purpose/decision opening and clear native field table before transcript scope/retention. Preserved: No service account,exact callback and sensitive member scopes,threeconferences/fiveartifacts,transcript versus smart_notesmetadata,space/projectscope,unsupported filters/exclusive start dates,complete-only attributed reads,30dayretention and Drive/Calendaralternatives retained. Disconnect/shared-workflow consequence,reconnect/approval/window recovery,support email and verification guidance retained. |
+| [search/granola.mdx](content/docs/search/granola.mdx) | rewritten | Ordered active-workspace connection, focused query/date behavior, and source evidence/plan limits. Retained official personal endpoint, semantic search, conditional last-30-day/custom listing and UUID scope, no verified continuation, ten-meeting source-note cap, generated answer references, private/summary notes vs transcript quotes, truncation and paid/admin controls. | Verified improvement. Orders setup, query syntax/date options and source evidence cleanly; removes repetition while keeping limits visible. Preserved: Officialendpoint/personalmanagedgrant,activeworkspace,focusedsemanticexamples,presetlast30day/customrange fallback,meetingUUIDcapability,nocontinuation,no inventeddates,10meeting hydration,generatedansweronlyforreferences,notesversustranscripts and plan/admin restrictions retained. Fixed read tools/current schema/grant and explicit formats retained; no media existed. |
+| [search/hubspot.mdx](content/docs/search/hubspot.mdx) | rewritten | Separated connection/query/record reads from self-hosted setup and recovery. Retained four CRM kinds/default property lexical search, returned custom properties, no activities/notes/associations, modification dates/cursor, unsupported ownership/pipeline/lifecycle/custom objects/aggregates and read-only access. Preserved dedicated MCP client env vars, exact callback, fixed regional endpoint handling and grant replacement/reconnect consequence. | Verified improvement. Makes setup and native CRM kinds explicit; places dedicated server app/callback in a concrete operator section. Preserved: Fourkinds/all4default,lexical searchableproperty keywords,custompropertyreads/noactivitiesorassociations,modificationdates/continuation/queryless sort,boundedtotals/ownershippipelineunsupported,permissionplanquotas and read-only action boundary retained. Dedicated vars/server/regionalredirect/exactcallback,reconnectregistration and primary setup retained. |
+| [search/index.mdx](content/docs/search/index.mdx) | corrected | Reordered purpose, first source, modes, provider catalog, access, and related guides. Qualified catalog availability and Zoom enablement; retained member/service/GitHub/GitLab differences, current checks, provider freshness, invitations, privacy, and KB separation. Replaced agent Assistant language with Sim and retired the legacy-index heading. Final navigation gate: the section overview is linked by the folder index; removed its duplicate explicit child entry from meta.json while retaining all routes and child order. | Verified improvement. Turns long live Search overview into shortest verified start, consistent mode/source tables and distinct access/freshness section. Preserved: All17 provider links/modes,GenericSecrets modes and exclusion,source/account distinction,GitLabexception,serviceintersection,GmailINBOXexample,removal,membership/privateconversations,providerfreshness/partialcoverage and access verification steps retained. CredentialGroups separateworkflowgrant and KB indexing remain explicit; obsolete legacy toggle prose removed under upstream live-only change. |
+| [search/jira.mdx](content/docs/search/jira.mdx) | rewritten | Ordered connect, JQL/reads, recovery, and operator setup. Retained Cloud/member-only modes, four-site cap, native site cursor, issue security/app access, bounded comments, no attachment/index path, and broader shared workflow OAuth. Moved complete Atlassian console/scopes to canonical owner while preserving Jira callback/variables, Service Management/Assets scope requirement, distribution and saved-config/reconnect consequences. | Verified improvement. Leads with Cloud-only/personal mode and verification, puts supported JQL/site behavior before recovery. Preserved: Every setup/noindexing/sourcepermission issue,four-sites/nativespecificsitecursor,JQLperquery,commentsbounds/attachmentsexclusion and six troubleshooting rows retained. Exactcallback/vars/fullJiraServiceManagementAssets/read:me/offline_access/Distribution requirements retained in local prerequisite and linked complete owner. |
+| [search/linear.mdx](content/docs/search/linear.mdx) | rewritten | Ordered connection/query examples, project/date/pagination controls, and discussion limits. Retained read scope, full-text/vector and comments/archived flags, project UUID vs team/name, modification dates/default relevance, queryless date listing/cursor, 150-comment/120000-character caps, incomplete coverage, unsupported standalone docs/updates and operation-specific 30/minute quota. | Verified improvement. Adds shortest connect-and-search flow and separates projects/dates/pagination from discussion limits. Preserved: Readscope,issuekey/phraseexamples,nativefulltext+vector,comments/archived,projectUUID,date-only/updated sorting/cursor,150comments/120000notice,standaloneproject exclusion and30requests/min retained. All primary schema/filter/pagination links remain, no media existed. |
+| [search/lucid.mdx](content/docs/search/lucid.mdx) | rewritten | Ordered connection, title/scoped text search, folders, and structured reads. Retained plan/FedRAMP/account boundary, query requirements and 400/200-character caps, no title continuation/ten candidates, modification-date candidate sorting, folder-page/nonrecursive behavior and native product/document scope. Preserved structured graph/revision complete-read behavior, eight-region/512-KiB cap and Sim-specific rendered/OCR/comments/Lucidscale exclusions despite broader provider tools. | Verified improvement. Adds purpose and separates title/document-text/browse/complete graph paths; distinguishes Sim-supported tools from broader provider server tools. Preserved: Readonlyallplans/FedRAMPexception/noappkey,accountboundary,productkinds,UUID/URLliteraltext,400/200chars/nooperators/10candidates/noquerycursor,modificationpageordering,nestedfolderpaging,no recursive scan/shortcuts and8regions512KiBversion-complete read retained. Images/linksasreferences/OCR/comments/Lucidscale unsupported and primarysetup/accessrules remain. |
+| [search/mcp.mdx](content/docs/search/mcp.mdx) | corrected | Added 1–10 batched document reads, independent errors/rate cost, no batch offsets, and individual continuation. Added queryless sort/date listings and explicit browse; retained all schema/response limits, opaque IDs, citations, OAuth/organization access, revocation, and client network prerequisites. Made Codex OAuth login explicit; framed client table as common setups, avoiding an exhaustive list that omitted Devin. Documented four native queries per account and queryIndex-bound cursor continuation from the canonical schema. | Verified improvement. Turns tools/limits into useful tables and adds source-backed batch reads/native multi-query continuation while retaining personal OAuth access. Preserved: Allfiveclientprocedures,scope/opaqueIDs/citationURLs,search/read/chat/privateconversation,topK20/1–50/query2000/readdefault3/cap8/documentID4000/question8192/response1MiB and explicit providererror/partial/retry behavior retained. RevokeAuthorizedapps/existingreturnedcontent,organizationURLscope and separation from workspace/workflow MCP retained; remote client requirements are linked. |
+| [search/notion.mdx](content/docs/search/notion.mdx) | rewritten | Ordered personal connection, conditional tools/queries, sidebar browse, and read coverage. Retained separate MCP vs REST, Notion-only filtering, current schema/plan-dependent AI/keyword/page/date support, ten-page timestamp checks/no invented timestamps, recent-view list meaning, conditional pagination and subtree omissions. Qualified authenticated server capability rather than claiming consolidated/new provider filters already supported by Sim. | Verified improvement. Groups current capability discovery and dates before browse/read sections; avoids promising plan-dependent server tools universally. Preserved: PersonalMCPdistinctworkflowREST/notitlefallback,shortfocusedexamples,AIorfallbackkeywords,Notion-onlyresults,pagescopeifadvertised,10readtimestampverify,localdate/noinventedtime/date-onlylimitations,sidebarprivate/shared/favorites/recentvisits and advertisedpagination retained. Fixedreadallowlist/exactfetchcurrentgrant,incompletesubtrees/refine/OpenNotion and primarysetup/tools remain. |
+| [search/slack.mdx](content/docs/search/slack.mdx) | rewritten | Led with source grant vs bot connection; ordered source setup, retrieval, bot use, deployment, and recovery. Retained member token/current scopes, DMs/channel/file boundaries, semantic/date sort/cursors, thread/preview/retention behavior, personal membership/invitations, private answers/Stop, generated full manifest and three callbacks, event reachability and app eligibility. Qualified slash commands by installed app availability because handlers are present but generated manifest registration was not independently established. | Verified improvement. Leads with personal source versus bot distinction; qualifies slash command availability rather than promising every installed app exposes them. Preserved: Memberonly/realtime/nochannelindex,ownusergrant,allchannel/DM/fileaccess,semanticsversusdatekeyword/cursor,preview-onlyfiles,botDM/mention/query/connect/Home/Stop/privatechannelanswers and separate source/bot disconnect retained. Generatedmanifestnetwork/publicHTTPS/exactthreecallbacks/fullscope-not-subset/scopedreconnect/eligibility and allsevenrecoverychecks retained. |
+| [search/zoom.mdx](content/docs/search/zoom.mdx) | corrected | Added organization/deployment rollout prerequisite, default-off behavior, self-hosted ZOOM_SEARCH and org-targeted AppConfig option; retained non-destructive disable semantics. Ordered connect, occurrence search/reads, dedicated operator OAuth, and disconnect/recovery. Retained UUID vs recurring ID, exclusive meeting dates/cursor/same query, ten-candidate cap, unsupported filters, generated-summary/notes distinction, artifact settings/licenses/processing/access, explicit limits/failures and no recording download/transcription. Kept dedicated General user-managed client/env vars/two scopes/callback/allowlist/endpoint/PKCE/auth method and distribution guidance; attributed 15-minute lifetime to official Meetings API rather than asserting authenticated MCP acceptance. | Verified improvement. Qualifies gated rollout before setup; moves dedicated operator setup after query/evidence behavior and bounds continuation claims to official API evidence. Preserved: Dedicated app/workflowgrant separation,all connection/adminapproval steps,plainquery/actualstart/exclusiveend/UUIDkind,10candidates/noaggregate newest-oldest,transcript/summary/note distinction/noaudioreconstruction,unsupportedfilters and all disconnect/datahandling/recovery steps retained. Readscopes,fixedendpoint/2toolallowlist,PKCE/client_secret_basic,exactcallbackbothfields and internal/external/beta app distribution links remain. |
+
+### Platform (6)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [platform/connected-accounts.mdx](content/docs/platform/connected-accounts.mdx) | rewritten | Reordered availability, Integrations/People/Access setup, runtime references, revocation and troubleshooting. Updated current labels and selected integration-type versus All integrations grants, future integration inclusion, 1,000-workspace bound and migration-review error. Preserved provider prerequisites, verified invitation binding, different provider email, account versus MCP IDs, paging and legacy block replacement. | Verified improvement. Current Integrations/People/Access labels and explicit all-versus-selected integration grants replace obsolete whole-pool allowlist setup. Preserves exposure warning while accurately limiting it to allowed integration types; adds grant ceiling and migration-review recovery. Preserved: Full Slack/Fireflies/Granola/HubSpot/Databricks setup details and Databricks cancellation/secret-preservation/reconnect rules retained. Invitee verification/binding, provider-email distinction, contributor nonmembership, current Chat scope, in-flight consequences, exact Find cardinality, 100-item paging and legacy block migration remain. |
+| [platform/costs.mdx](content/docs/platform/costs.mdx) | rewritten | Renamed to Credits, billing and limits; scoped defaults to Cloud and separated billing-disabled configuration. Retained credit conversion, run/model/tool/sandbox costs, all unusual hosted-tool units, BYOK scopes/inheritance/rotation/lapse, allowances/annual arithmetic, refresh, balances, caps, overage, threshold, concurrency/storage/duration and monitoring. Corrected Parallel search mode and Distance Matrix units; added TypeSafe, Nebius, Kie and TinyFish. Replaced obsolete Model Breakdown with current Overview ledger rows, total and available tokens. Removed fixed 1.1x, unsupported self-service purchase procedure/terms and unverified deployed-voice pricing. Qualified legacy usage helper as account/key-owner USD with storage; linked v2 Billing Status and retained Logs USD versus Billing/run credits. Preserved bring-your-own-key-byok, concurrent-executions and run-time-limits anchors. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Scopes credits to billable Cloud/UI units and distinguishes USD Logs contracts; adds sandbox/base-child-charge policy and separate block/provider limits. Corrects current hosted-tool pricing modes, per-element Distance Matrix pricing, API payer versus workspace account, billing-disabled enforcement and unsupported purchased-credit/deployed-voice procedures. Replaces asserted Max workspace cap with live controls/pricing qualification; strengthens BYOK per-provider exclusive pool/actor scope and organization lapse consequences. Preserved: Every original hosted-tool rate category and BYOK provider catalog retained with new providers; tables replace long one-provider tab set without deleting pricing detail. Preserves monthly/annual rates, weekly refresh arithmetic, seat pooling, on-demand/spend controls, threshold example, concurrency/rate/storage/runtime tables, key encryption/rotation/deletion and Pi exposure warning. Formula retained with correctly named USD/credits components and sandbox term. Legacy usage endpoint/auth/units/rate field meanings remain; recommended v2 monitoring has direct API-owner links. Removed obsolete model-breakdown screenshot and unsupported checkout/deployed-voice claims; retained concrete billing math and threshold examples. |
+| [platform/credentials.mdx](content/docs/platform/credentials.mdx) | rewritten | Reordered scope/grants/management, syntax/runtime identity, Details/Visibility/usage, complete canonical protection algorithm, Chat mounting and headless policies. Preserved every distinct original log/span/model projection boundary, real functional store/response/stream/callback distinction, exact case-sensitive match, scanner forms and false positives/negatives, injected binding non-persistence, transformed/fragmented/network limits, Unredacted public-link/future-log/equal-value conflict, usage and trigger actor rules. Clarified personal ownership/no admin inheritance/current writer restriction versus existing active grant resolution. Retained useful masked editor and corrected picker source/alt; removed obsolete personal details and redundant inserted-reference image. Replaced Copilot and saved-task modal wording with Chat/Sim, current Sim Chat and Inbox policies and deployed schedules. Integrated unique FAQ answers and added source-current Logs-versus-References usage views; retained execution-log-protection anchor. | Verified improvement. Corrects workspace use/reveal grants, personal-secret non-inheritance and existing grant nuance; organizes runtime identity and protection into explicit actor/surface boundaries. Replaces unsupported Scheduled Tasks secret-modal claim with current workflow Schedule setup; adds References versus recorded usage distinction. Preserved: Full .env parser forms, inline save/delete consequences, namespace precedence, all original direct-read languages and recognition exceptions, exact/transformed protection limits, opt-out disclosure and future-run effects remain. Owner departure/suspension and unauthenticated public execution retain explicit personal-namespace consequences. All useful FAQ answers are folded into management/resolution/protection sections. Kept Secrets editor and reference-picker captures; viewed secret-resolved.png independently and current alt accurately names the open picker. Removed duplicate dropdown/detail screenshots without claiming them stale. |
+| [platform/organization.mdx](content/docs/platform/organization.mdx) | rewritten | Removed nonexistent folder colors and five hypothetical visual TODOs. Added concrete named tree and source-current Create folder/Rename/Lock/Delete actions. Retained drag order/reparent, Admin lock authority/inheritance and otherwise authorized execution while locked. Corrected Archive to Delete/Recently deleted and effective retention. Distinguished navigation/naming from workspace access and ownership. | Verified improvement. Replaces unsupported folder archiving/color instructions with current delete/recovery controls, Admin lock access and inherited-lock behavior. Task order uses concrete naming/nesting and drag examples without placeholder visual comments or decorative cards. Preserved: Retains shallow hierarchy, category/action names, ordering, drag-to-nest, lock scope, and folder-versus-workspace choice. Original color instructions are not useful current controls: folder item has no color handler; current menu supplies create/rename/duplicate/export/delete/lock. No real media was removed; original VISUAL comments were placeholders. |
+| [platform/permissions.mdx](content/docs/platform/permissions.mdx) | rewritten | Consolidated repeated role tables/lists/scenarios and11 FAQs into an authority and membership lifecycle guide. Separated Read deployed API execution, Write manual Run/edit/delete and Admin deploy, with per-secret authority. Corrected organization-only membership versus workspace grants and current invitation labels. Preserved seat/eligibility/combined pending invite/scoped revoke/accept preview/owned workspace migration/removal consequences with billing-mode scope. Clarified fixed Owner, inherited organization administrator removal protection and protected billing-account fallback. Documented human permission-group empty inherit versus explicit/SCIM behavior and independent workspace-key operation policy. | Verified improvement. Separates draft Write from deployed API Read role floor; replaces blanket Write secret-management and inherited-personal access statements with resource grant rules. Distinguishes organization-only invitations, workspace grants, billing mode, one-org membership, and explicit/inheritance-mode groups. Preserved: Preserves locked inherited roles, three levels of authority, seats/external eligibility, invitation merging/scoped revocation, archived workspace migration, owner removal fallback, credential access and member-removal consequences. Detailed duplicated role bullets become a role/action matrix; meaningful FAQ consequences are retained under joining/removal/credential/group sections. Remote invitation video was removed because the full labeled procedure now covers it; no stale-media claim. Joining-an-organization and credential-access anchors remain; plan limits moved to linked Costs owner that contains those limits and their live configuration qualification. |
+| [platform/workspaces.mdx](content/docs/platform/workspaces.mdx) | rewritten | Replaced repeated resource subsections with linked resource inventory and workspace decision. Separated integration tools from credential connections/grants and Owner from permission tiers. Corrected authorized workspace switching versus relocation, personal ownership and billing-mode creation rules. Retained draft/deployed/promotion/rollback and explicit sharing boundaries. Removed hypothetical visuals/Scheduled Tasks and unsupported customer handoff ownership claim. Reordered platform/meta.json: workspaces, organization, permissions, credentials, connected-accounts, costs; slugs unchanged. | Verified improvement. Separates workspace roles, credential grants, organization ownership, deployments and explicit sharing. Corrects owner to fixed Admin, personal-secret non-inheritance, archived-workspace joining consequence and billing-disabled scope. Preserved: Retains every resource category, three workspace roles, personal/organization distinction, internal/external joining consequences, and deployment promotion/rollback. Reference links replace decorative cards and placeholder visuals while keeping owners for membership/limits/credentials. |
+
+### Enterprise identity (9)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [platform/enterprise/index.mdx](content/docs/platform/enterprise/index.mdx) | rewritten | Task-oriented feature directory; Cloud and billing-disabled self-hosted scope made explicit. Detailed invitation-disabled setup moved to self-hosted enterprise. | Verified improvement. Separates Cloud subscription from billing-disabled self-hosted flags and organization-owned workspace requirements. Preserved: All enterprise capabilities and shortest navigation retained; administrator-key details moved to linked self-hosted guide, which includes requests and actor requirements. |
+| [platform/enterprise/self-hosted.mdx](content/docs/platform/enterprise/self-hosted.mdx) | rewritten | Operator order: enable flags, choose organization model, verify, schedules and reference. Backfill specifies an existing owner account; Admin API key configured on application and caller. Workspace move includes fresh UUID operationId, same-ID retries, progress read and follow-up inspection. Corrected in-process data drains and direct SCIM cron; added SCIM schedule. Preserved all feature flags/defaults, organization APIs, invitation-disabled behavior, retention opt-in/schedules, Sandbox readiness and local Node worker scope. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Corrects missing application-side admin-secret setup, required idempotent workspace move operationId and follow-up state; backfill owner prerequisites now explicit. Preserved: Every feature flag/browser twin, inherited defaults, organization models, API/SQL/curl examples, deletion consequences, sandbox readiness, inline jobs and separately scheduled retention preserved and corrected. |
+| [platform/enterprise/sso.mdx](content/docs/platform/enterprise/sso.mdx) | rewritten | Removed redundant FAQ component; folded access, linking, owner recovery, offboarding and editing into visible sections. Kept all five protocol/provider guides, exact fields, callback formats, advanced options, flags and scripts. Updated current Okta/Google paths, globally unique provider examples and conditional provider-switch behavior. Added script organization binding/existing-account/DB prerequisites, direct-registration trust and one-provider deregistration ID. Replaced issuer-origin authenticity implication with matching-issuer launch constraint. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. Preserved the five provider anchors on native tab panels; bookmarked provider links select their tab without duplicate headings. | Verified improvement. Places provider setup before verify, then membership/linking and recovery; corrects source registration organization binding and all-provider deletion hazard. Preserved: All5 full provider configurations and URLs retained; global ID, issuer/claim mapping, callback override, discovery, existing account linking, seats/invitations/external grants, owner recovery, unsolicited SAML refusal, primary/test/provider switching and self-hosted scripts retained. OIDC form screenshot removed; every visible field and control remains explained in text/tables. |
+| [platform/enterprise/scim/index.mdx](content/docs/platform/enterprise/scim/index.mdx) | rewritten | Defined SCIM and split prerequisites from normal behavior. Folded all eight FAQ answers into lifecycle, identity matching, seats, managed access, disable/recovery and deployment sections. Kept suspension/removal/session/key/seat ownership distinctions and permanent explicit permission-group membership; empty mapped groups apply to nobody. Reduced duplicated Okta/Entra setup to guide links and exact credential/lifecycle distinctions; retained OneLogin/JumpCloud setup. Corrected scheduler dependency; preserved rollout/rollback and 0325 baseline warning, protocol filters and limits. SCIM metadata title/order reviewed and retained unchanged. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Provides exact decimal byte limit and a direct SCIM cron route independent of Trigger.dev; lifecycle, grants and rollout warnings precede consequences. Preserved: All4 provider configurations, complete protocol/filter/resource/attribute rules, token overlap, member seats/owner conflicts, managed baseline, explicit permission membership, JIT override, disable recovery and migration warning preserved. Provisioning screenshot removed with controls and procedure fully described. |
+| [platform/enterprise/scim/okta.mdx](content/docs/platform/enterprise/scim/okta.mdx) | rewritten | Current creation-experience table and official custom-app route separated from evaluation-only Header Auth Test App recipe. Qualified first-party production policy conflict without claiming OIN publication/certification. Preserved Bearer prefix mismatch, password exclusion, account/group lifecycle tests, assignment-vs-push group distinction, offboarding order, token rotation and troubleshooting. | Verified improvement. Corrects Classic-only OIDC limitation, differentiates newer wizard support, evaluation templates and supported custom production setup. Preserved: All3 meaningful screenshots preserved and freshly visually inspected. Full header syntax, custom field differences, verified-domain usernames, user+group lifecycle tests, separate assignment/push groups, offboarding order,2-token overlap and troubleshooting retained. |
+| [platform/enterprise/scim/entra.mdx](content/docs/platform/enterprise/scim/entra.mdx) | rewritten | Numbered account and group verification procedures; user/group naming kept scoped. Converted soft-delete/permanent-delete/unassignment distinction to lifecycle table. Retained current/legacy UI, Free/P1 licensing, UPN/work-mail fallback, five-member on-demand limit, scheduled-only disable/delete tests, normal cycle timing, watermark resets, token rotation and troubleshooting. | Verified improvement. Separates deactivation from permanent organization removal and orders connection, test assignment, lifecycle, group access and scheduled cycles. Preserved: All3 screenshots retained, scope screenshot freshly inspected. Fields, mappings, Free/P1 distinctions,40-minute cycles,30-day permanent deletion, on-demand5, token rotation, watermark restart and troubleshooting retained. |
+| [platform/enterprise/verified-domains.mdx](content/docs/platform/enterprise/verified-domains.mdx) | rewritten | Moved removal and migration FAQ details into visible sections; removed duplicated prerequisite and FAQ headings. Kept exact TXT host/value, zone suffix pitfall, propagation/persistent verification, one-org/subdomain scope, public DNS endpoints/ports, bypass trust and recovery, image/chart/digest requirements. | Verified improvement. Puts domain authority and bypass trust consequences before DNS/verification actions; limits deletion to future sign-in. Preserved: TXT host/value, subdomain independence, uniqueness, migrated trust, public DNS resolvers, restricted-network bypass, chart image precedence, Cloud exception and all troubleshooting retained. |
+| [platform/enterprise/security.mdx](content/docs/platform/enterprise/security.mdx) | rewritten | Made session-policies page canonical for controls/defaults; retained concise navigation. Converted outbound coverage/exclusions to table without expanding support; kept fail-closed behavior and allowlist-every-address requirement. | Verified improvement. Session, revocation, dedicated egress and PII actions consolidated into task-first rows, with defaults and failures scoped. Preserved: All security policy ranges/defaults and Save/Discard behavior retained in linked Session policies; dedicated HTTPS IPv4 port443 and unsupported egress surfaces remain. |
+| [platform/enterprise/session-policies.mdx](content/docs/platform/enterprise/session-policies.mdx) | rewritten | Moved all FAQ facts into settings, enforcement and revocation sections. Added Save/Discard, integer ranges and distinction between optional limits and default sliding expiry. Qualified policy loosening as no immediate expiry extension; later refresh/new sign-in applies current policy. Clarified current-session exemption and caller’s other-device revocation; kept API/workflow exclusions. Qualified pending-edit claim to already synced changes. | Verified improvement. Clarifies refreshed policy limits, tighter versus looser expiry, and preserved current session. Preserved: 1–8760h max and48–8760h idle,30day/24hour defaults, one-minute policy caching, unsynced work warning and save/discard steps retained. |
+
+### Orientation (6)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [index.mdx](content/docs/index.mdx) | corrected | Replaced duplicate card overview with canonical Introduction/Getting started pointer and redirect stub. Retained routing behavior; root owns source/LLM handling. | Verified improvement. Removes duplicate narrative from a redirect-only URL and sends readers to the actual introduction/tutorial owners. Preserved: Original build modes/models/integrations/resource and permission concepts are retained in Introduction and the linked topic/navigation owners; no operational example existed here. No media/FAQ lost; page path and redirect destination remain. |
+| [introduction/index.mdx](content/docs/introduction/index.mdx) | rewritten | Reorganized into build-method table, workspace-resource table, models/integrations, deployment choices, and related docs. Qualified Chat availability and local-model network requirements; scoped MCP to server-exposed tools. Folded licensing and self-hosting FAQ facts into deployment section; removed promotional repetition and comparison superlatives. | Verified improvement. Organizes methods/resources/models/deployment choices into concise useful tables; removes sidebar-anatomy and fastest/clearest/all-model claims. Qualifies Chat/network/local models and MCP-exposed tools rather than promising offline or arbitrary-service universals. Preserved: Visual/Chat/API methods, mixed authoring, resources and four application domains preserved in method/resource/integration prose. Removed exhaustive provider list delegated to actual integration catalog; installed platform/source license facts and Docker/Kubernetes/local model facts remain. Removed image/video generic builder examples add no unique prerequisite; two FAQs folded into deployment/license section. |
+| [getting-started/index.mdx](content/docs/getting-started/index.mdx) | rewritten | Added workspace/model/tool prerequisites and scoped hosted-vs-own credential explanation. Made seven-step tutorial runnable: create/rename workflow, add/connect Agent, exact System/User messages, configure search tools, locate workflow test chat, inspect run, configure and verify schema. Replaced fictional answer-bearing test profiles with an identifiable research prompt and source inspection. Included complete person JSON schema and updated System prompt; root output references match schema fields. Removed hard-coded model/time claims, prevalence claims, internal metrics comment, and stale Gmail screenshot; kept concrete recovery steps. | Verified improvement. Runnable seven-step guide adds permission/model/tool prerequisites, connection checks, exact Messages, tool setup and genuine research prompt. Adds complete schema, root output references, logs verification and malformed JSON fallback; replaces answer-bearing fictional profiles and unsupported default/time claims. Preserved: Start→Agent people research, Exa/Linkup tools, content test, generated-or-manual structured schema, downstream location/profession/education and missing-key/reference recovery retained. Removed videos/screenshots are replaced by complete named controls and copyable schema/prompt; original warnings have a concrete recovery section. |
+| [desktop/index.mdx](content/docs/desktop/index.mdx) | rewritten | Reordered download/requirements before installation, then capability/privacy guidance, current settings, shortcuts, and updates. Qualified installer cache/version/feed behavior and signing; preserved universal build, macOS 12, Applications eligibility, separate browser/app sessions, certificate rejection, GitHub requirements, notification exclusions, updater modes and fallback. Corrected optional launch at login and enabled Browser/Terminal defaults. Documented Full file access off, prevent-sleep on, Passwords and Google search-suggestion transmission. Scoped read-only to selected-folder filesystem tools; described import/browser staging and separate OS-user shell privileges with conditional approval behavior. Retained #keyboard-shortcuts and added accurate focused-terminal Cmd+R/focused-browser Cmd+L distinctions. Added deployment/device-gated native Mac app control: macOS 14, per-Mac off default, exact legacy UI label, manual Accessibility/Screen Recording setup, per-app grants, and foreground/compatibility limits. Documented conditional Stop shortcut, inability to undo delivered app input, Revoke/Off, sign-out/deployment reset, protected permission surfaces, and possible screenshot/content transmission. | Verified improvement. Moves requirements/server choice before sign-in; qualifies updater selection/caching/signing. Corrects launch-at-login and browser/terminal defaults, local file import/staging/transmission, shell permissions and grants. Accurately adds gated macOS 14 native control alongside macOS 12 general app minimum. Preserved: All original installation/session/download/custom-origin/GitHub/TLS requirements, notifications exclusions, Control Center, shortcuts/settings and updater/manual/fallback behaviors retained. Inspected browser screenshot retained; meaningful Applications/privacy callouts remain; removed always-newest/no-file-staging claims are contradicted by owners. |
+| [quick-reference/index.mdx](content/docs/quick-reference/index.mdx) | rewritten | Replaced eight HTML Preview tables with plain two-column Task/How Markdown tables. Preserved 59 supported prior action intentions; removed only unavailable handle orientation. Corrected import/invite/run/rename/manual-selector/test-chat/Logs-output/version/secret locations and labels. Added admin, partial-run, singleton, draft/live and export-sharing boundaries where needed. Uses browser find for text lookup; no new runtime search component. Removed all ActionMedia usages and imports; root owns shared component/asset cleanup. | Verified improvement. Replaces 3-column media tables with readable Task/How lookup retaining supported operations and correcting labels. Adds Admin/lock/singleton/partial-run/draft-live/export scopes where needed. Preserved: All 59 supported original action intentions retained across workspace/workflow/folders/blocks/connections/panels/run-inspect/deployment/variables. Removed Toggle Handles has no exposed current menu action; retained undo infrastructure does not prove a user control exists. Removed 49 media instances contain no unique action requirement missing from corresponding text; Mod meaning and full shortcuts link remain. |
+| [keyboard-shortcuts/index.mdx](content/docs/keyboard-shortcuts/index.mdx) | rewritten | Reordered workspace navigation before workflow actions/pointer controls and table groups. Corrected add-Agent block scope, Sim change acceptance name, workflow-console scope and editable-field caveats. Preserved existing keyboard/pointer actions and table shortcuts; added current select-all, fill-down and table find controls. Qualified Shift+Enter required-field form, boolean Enter/F2 behavior, row editor, table permissions and locks. Preserved /desktop#keyboard-shortcuts links. | Verified improvement. Groups workspace navigation before builder/table surfaces; distinguishes focused/editable-field scope. Corrects adding Agent block, Sim change terminology and workflow console, and adds real table find/select-all/fill-down/form/boolean behavior. Preserved: Every original keyboard/pointer action intention retained; Desktop #keyboard-shortcuts link preserved. Mod callout folded into opening; tables are compact scoped groups without generic warning repetition. |
+
+### Chat (8)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [chat/files.mdx](content/docs/chat/files.mdx) | rewritten | Separated chat-private attachments, saved workspace Files, and temporary workbench outputs/SIM_OUTPUT_DIR. Corrected Attach file control, supported-reader boundary, ZIP extraction, watched text versus generated binary outputs, and type-dependent viewer modes. Preserved distinct document/CSV/code/digest/postmortem/email, PPTX, image reference, chart/diagram and calculation examples; named binary formats with availability qualification. Preserved deliberate private uploads; qualified stored-file model reads/previews/share links and withheld mounts that prevent code execution. | Verified improvement. Fixes contradictory automatic workspace-save claim; separates private uploads, saved Files, temporary workbench and model preview admission. Keeps generation examples concrete and format support qualified; adds blocked requested mounts without claiming every known-secret byte cannot enter code. Preserved: All four attachment processing examples, six text deliverables, five presentation scenarios, banner/reference/social image examples, three charts, JSON/p95/timestamp/dedup computations retained. Diagram generation/reference variation moved into chart/diagram section; FAQ workflow reuse/types/calculations folded into body. Removed example screenshots/videos contain no unique required parameter or procedure omitted from the written tasks. |
+| [chat/index.mdx](content/docs/chat/index.mdx) | rewritten | Replaced promotional introduction with capabilities, New chat/Build/Search/Plan instructions, scope, resources and progress controls. Added Mailer navigation and corrected recurring work, generic delegation, per-chat queue/Send now, tool approval and configured runtime/usage limits. Qualified Plan by deployment capability and effective platform administrator with Super admin mode; distinguished organization Admin and organization Build workspace-creation permission. Added loaded-message Find controls, progressive older history/failure boundary, 500-match limit, and native activity/Stop link to canonical Desktop procedure. Qualified Chat model delivery separately from access and tool approval: stored content can be masked or withheld. | Verified improvement. Replaces command-center/no-configuration/universal workspace/hour-limit promises with actual start/mode/access steps. Adds scoped Plan, org Build, queue/Send now, Find windows/cap and content gate without promising rollout. Preserved: All original task categories, named workflow/table prompts, four substantial build/research/recurring/contract examples, +/@/drag contexts and resizable/draggable/closeable panel facts retained. FAQ scope/runtime/queue/context information now lives beside relevant tasks; remote videos/TODOs removed with complete text controls. |
+| [chat/knowledge.mdx](content/docs/chat/knowledge.mdx) | rewritten | Organized create, ingest/process, search, sync, workflow retrieval/ingestion, management. Preserved PDF/text/URL/multiple-document requests, source categories and inventory/removal examples. Corrected completed+enabled processing requirement, guarded source removal, explicit retrieval configuration and Knowledge Create/Upsert Document names. Added restricted private knowledge graphs in organization settings, exact New graph/Create and activate/Make active controls, personal organization scope, reserved Default/name limit, and new-chat versus existing-chat bindings. Qualified masked or omitted indexed documents/passages/tag values without changing ordinary workflow retrieval or UI access. | Verified improvement. Corrects immediate availability, universal workflow access and every-run connector deletion assertions. Adds concrete retrieval/write paths, processing verification, current private graph gate and Chat per-item admission. Preserved: Every create/ingest/search/manage example intention and all source categories retained. FAQ supported formats, workflow attachment and programmatic writes folded into processing and workflow section using actual Knowledge Create/Upsert Document names. Remote generic KB video/TODO removed; no unique setup fact lost. |
+| [chat/mailer.mdx](content/docs/chat/mailer.mdx) | rewritten | Moved Cloud Max/Enterprise active billing and workspace Admin prerequisites before setup; qualified self-hosted availability without inventing the hosted email domain. Added member-role/external read-only/raw-secret boundaries, default All secrets and Selected secrets controls, and noninteractive execution. Preserved prefix/address replacement, sender labels, attachments/email examples, 10 MiB hard limit, statuses, failed/complete navigation and thread continuation. Corrected completed-agent-work versus delivered-reply receipt, partial attachment failure, displayed body-preview search and same-workspace live conversation condition. | Verified improvement. Adds Admin/plan/services/member-versus-email-only access prerequisites before enabling inbox. Corrects attachment failure handling, search preview scope, completed-versus-email-delivery and same-workspace continuation. Preserved: Three email examples, generated/custom prefix, address replacement, allowed senders, status lifecycle, continue-in-Chat and 10 MiB attachment fact retained. Only meaningful address-replacement Callout retained; domain FAQ folded into displayed deployment address instruction. |
+| [chat/research.mdx](content/docs/chat/research.mdx) | rewritten | Organized focused questions, saved reports, then source access/freshness. Preserved every distinct company/market/technical/release/authentication/compliance/battle-card scenario while removing exhaustive-completeness promises. Kept public hosted access, Desktop signed-in browser, workspace Files output, current-source dates/citations and connected-source permissions. | Verified improvement. Turns any/every/full-report promises into scoped research, citations/date checks and explicit unknown evidence. Moves complete FAQ access/freshness/saved report facts into source-access and report sections. Preserved: All seven original question domains and five saved-report scenarios preserved, including releases, company hiring, competitive market, auth, compliance and battle card. Saved Files/resource panel/slide reuse and Desktop signed-in browser remain qualified by tool availability; remote decorative video/TODO removed. |
+| [chat/tables.mdx](content/docs/chat/tables.mdx) | rewritten | Organized create/import, query/compute, row mutation/deletion, export, workflow configuration. Preserved schema/CSV/errors/prospects/enrichment, count/range/error-frequency/duplicates/fit/conversion, bulk-update and filtered/full export scenarios. Corrected createdAt system field, table selection requirement, nonpersistent combination of multiple tables, export completion and access/limit distinctions. Qualified admitted row/selection completeness, database totals/cursors, CSV completeness, and committed writes with withheld returned rows. | Verified improvement. Corrects table-name-only workflow configuration claim and system timestamp syntax. Adds per-row admission versus DB totals/cursors, incomplete generated CSV warning and committed write-withheld-result consequence. Preserved: Five table creation, six queries, single/bulk write, delete/full-filtered export, and multi-table combination/plan-limits FAQ facts retained. Original screenshot summary intent remains covered by query/summary prose; no schema/mutation input lost. |
+| [chat/tasks.mdx](content/docs/chat/tasks.mdx) | rewritten | Rewrote obsolete saved-prompt cron Jobs as deployed workflows with Schedule triggers; preserved all daily/weekly/monthly/hourly funding/prospect/error/report use cases and relevant log/manage outcomes. Separated one-time watches/timers from recurring workflows, including 24-hour timer maximum and stop-watch versus workflow cancellation. Preserved Slack/email/GitHub/HubSpot/HTTP actions, account setup/ownership, secrets syntax/scope, MCP server lifecycle and distinct custom-tool scenarios. Added configured approval/results, real external effects, schedule activation/redeployment/timezone, service-specific Google scopes and current Chat server attachment. Added inspect-before-retry consequence when an external action finishes but its returned result is withheld. | Verified improvement. Replaces obsolete saved-prompt Jobs with deployed Schedule workflows while preserving recurring task intentions. Separates timers/watches from recurring work, acting credential scope, service-specific authorization and settled result versus external action. Preserved: All seven daily/weekly/six-hour/monthly/funding/enrichment/error scenarios and log/change/stop tasks preserved through supported schedule model. Five direct service actions, Google/Slack/GitHub connections, all secret names/references, MCP add/update/list/remove and four custom-tool examples retained. FAQ external undo, account inventory and ENV syntax folded into owners; obsolete Jobs video and TODO/callout repetition removed. |
+| [chat/workflows.mdx](content/docs/chat/workflows.mdx) | rewritten | Reordered creation, draft edits/variables, running/logs/debugging, deployment/restoration, and organization/deletion. Preserved all distinct workflow scenarios, exact variable syntax, input examples, logs, API key creation, nested folder moves and deletion consequences. Corrected configured endpoint host, adding an MCP tool to a server, draft versus active state, rollback versus restore, and live/background evidence. | Verified improvement. Clarifies draft versus deployment, explicit run source, access, external-effect testing and successful serving verification. Separates restoring draft from rolling live deployment and corrects MCP workflow tool deployment. Preserved: Five creation, three edit, three run, three log, two debug, variable, API/chat/MCP deploy, rollback, folder/move/rename/delete intentions retained. All three FAQ effects folded into their lifecycle sections; old generic motion embeds/TODOs removed without missing a required control. |
+
+### API guides (5)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [api-reference/authentication.mdx](content/docs/api-reference/authentication.mdx) | rewritten | Separated credential identity/current access from workspace-key management and operation policies; retained workspace payer/member attribution and personal/OAuth restrictions. Retained verified one-time key display/create/revoke instructions and exact Sim API keys label; qualified encryption and modern/legacy prefixes by API_ENCRYPTION_KEY. Kept API-key versus OAuth headers, scope table, method-independent scopes, account grant versus login revocation and API-key logout caveat. Replaced duplicate three-language request with curl and canonical Getting started/SDK links; folded repeated credential-safety text. | Verified improvement. Distinguishes acting identity, current role/policy, operation-specific workspace-key access, and payer instead of the baseline vague permissions table. Corrects API-key Bearer misuse, optional encryption/legacy prefix, OAuth scope/grant and logout behavior; removes duplicate HTTP language samples while linking complete versions. Preserved: Retains key creation/revocation/one-time display, X-API-Key, server-side credentials, modern prefix and OAuth scopes. Complete HTTP examples still exist in Getting started; OAuth/profile detail remains in CLI authentication. |
+| [api-reference/getting-started.mdx](content/docs/api-reference/getting-started.mdx) | rewritten | Separated Cloud/self-host origins, active deployment prerequisites, manual draft access, HTTP result versus in-band run failures, and request versus execution rate policies. Added checked env-backed direct requests, all current wait/terminal/pause states, async mode compatibility and client/server timeout distinction. Preserved one-shot X-Run-Id409 behavior and uncertain-run reconciliation; fixed pagination with required workspaceId and URL-encoded returned cursor. Preserved resource/list/error shapes, strict undeclared-field behavior and validation details while distinguishing OAuth401, usage402, conflict409 and USD/credits. Kept substantial first-call Steps/language Tabs; removed routine status/billing callouts. API navigation moves advanced workflow-sync after SDKs under API guides. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Examples now define environment prerequisites and handle HTTP and in-band run failures; manual draft execution is distinguished from the active deployment. Explains actual status/pause/redaction, async option compatibility, one-shot run-ID recovery, endpoint-specific units, and bound cursor queries. Preserved: Retains origin/OpenAPI URL, API-key creation, ID lookup, deployment, three HTTP languages, async run/status URL, envelopes, strict unknown-field validation, pagination and Retry-After. |
+| [api-reference/python.mdx](content/docs/api-reference/python.mdx) | rewritten | Retained every public method signature/default and complete return-field reference, added forced-sync method and missing retry timeout parameter. Replaced repeated Quick Start/Basic/Steps/env tabs with env-backed context manager; retained sequential multiple-workflow, file-like upload, async polling, retry/status/usage examples. Explained Python failed result versus exception, completed/paused/cancelled states, metadata units and unset logs/traces; preserved 0.2.x migration and mixed legacy/v2 helpers. Fixed usage requestsPerMinute/maxBurst fields and account/key-owner USD scope; Python storage omission explicit; corrected v2 reset milliseconds with legacy-unit caveat. Replaced broken SDK streaming example and done-event parser with raw HTTP SSE inspection and canonical framing/forwarding instructions; preserved Flask backend authentication, event preservation, status/timeout/cleanup concerns. Added redacting to polling and local wait deadline, distinguished client/server timeouts, output selectors, run fields/files/permissions and opaque large-value references. | Verified improvement. Replaces the misleading async/streaming/readiness claims with blocking HTTP, SDK-vs-HTTP streaming limits and failed/paused/cancelled result behavior. Keeps full method and return reference while consolidating repeated examples; corrects retry/reset units and usage shape. Preserved: Retains Python/requests requirements, context management/close, method options/defaults, types, baseURL, file inputs, async polling, retry, usage helpers and Apache-2.0 link. Legacy status/jobs and SDK migration remain explicit; runnable examples replace duplicate/incorrect samples. |
+| [api-reference/typescript.mdx](content/docs/api-reference/typescript.mdx) | rewritten | Retained all public method signatures/options and complete declared/runtime return fields, added forced-sync convenience and LargeValueRef/legacyJob status distinctions. Used Bun install and Node18+ ESM requirement, scoped automatic globalFile conversion to Node20+, fixed Buffer-to-BlobPart typing using Uint8Array. Explained failed-run rejection versus cancelled/paused resolution and exact-state run lookup; async polling waits through runtime redacting without widening SDK types. Fixed legacy USD usage fields/storage, v2 reset-millisecond example, client wait versus server cap, rate-only retries and unsafe-retry recovery. Replaced broken SDK streaming and stale done-frame example with raw HTTP stream, terminal/reset handling, chunk boundaries and canonical protocol client links. Folded duplicate initialization/Steps/environment tabs into one setup, preserved backend helper and Express/Next.js POST/auth/input-size/status responsibilities; retained file formats and actual upload example. | Verified improvement. Corrects Node minimum/global File availability, failed-run rejection, paused success, absent synchronous status, unsupported SDK streaming, and timeout-without-abort. Preserves complete declarations and options while reducing repeated implementations; corrects retries/usage/reset units and shows HTTP framing. Preserved: Retains constructor and methods, options/defaults, types, setter/helpers, file and URL objects, server/backend authorization, async polling, retry, usage, legacy compatibility and license link. |
+| [api-reference/workflow-sync.mdx](content/docs/api-reference/workflow-sync.mdx) | rewritten | Reorganized prerequisites/import/fork/sync/verification/recovery and moved advanced navigation; retained every command/endpoint relationship and scope/role distinction. Made billing-enabled Enterprise versus billing-disabled deployment gate explicit; qualified export sanitization and kept unresolved env values/provenance non-authority. Retained source kind mappings, flat occurrence bindings/encodings/positions, null/required binding rules, dependentValues and selector scope/context/partial/restart bounds. Preserved fork drafts/explicit copies, push/pull direction/direct edge, mapping read/write projection, omitted/replaced/cleared saved choices and trigger URL adoption. Preserved request-ID/fingerprint apply commands, atomic import/idMap/plain-import exception, receipt workspace ownership, committed-follow-up failure and exact deployment readiness. Kept uncertainty reconciliation/stale preview recovery, rollback draft/copy limitations, unlink/exclusions; moved contributor harness details to existing canonical repository README link. | Verified improvement. Puts permissions and deployment gates before mutation steps; separates export/import, fork, direction-relative sync, receipt/recovery, and rollback consequences. Corrects confidentiality guarantees and adds selector bounds, fingerprint/retry safeguards, copy identity differences and exact deployment readiness. Preserved: Retains CLI↔HTTP map, all import/sync payload shapes, source IDs, nested occurrences/encodings, destination selectors, trigger adoption, request IDs, receipts and retry recovery. Contributor harness detail moved to a linked canonical README that contains Bun/Docker/PostgreSQL17/fixtures/migration boundary. |
+
+### Knowledgebase (7)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [knowledgebase/chunking-strategies.mdx](content/docs/knowledgebase/chunking-strategies.mdx) | rewritten | Replaced repeated Advanced warnings and cross-library comparisons with settings, actual Auto routing, strategy behavior, record examples, and troubleshooting. Corrected minimum range to 1–2,000 characters; explained approximate token sizes, per-strategy minimum filtering, overlap behavior, and oversized records. Preserved strict Regex checkbox label, delimiter/segment distinction, normalization, positive lookaround, 500-character pattern limit, unsupported syntax, and no-split behavior. Documented v2 configuration updates including strategy/options, whole-object replacement, defaults on omission, and no automatic rebuild of existing chunks. | Verified improvement. Corrects automatic JSON detection, one-record guarantees, exact token counts and globally enforced minimum sizes; distinguishes each splitter behavior. Adds strict Regex semantics, normalization, unsupported patterns and replacement-versus-merge configuration consequences. Preserved: All six strategies, default sizes/overlap, strategy tradeoffs, JSONL example and Q&A boundary example retained. Original re-create-base advice preserved for UI; API update is distinguished and existing chunks are not falsely said to rebuild. FAQ advice now has explicit record-boundary sections; no unique useful media lost. |
+| [knowledgebase/connectors.mdx](content/docs/knowledgebase/connectors.mdx) | rewritten | Reorganized into connection methods, setup, verification, actions/history, exclusions, sync recovery, Confluence constraints, and catalog. Kept credential kinds/scopes/configuration examples and whole-value secret snapshot/rotation behavior; replaced unverified provider account-menu directions with verified credential requirements. Added Live every 5 minutes and scoped sub-hourly plan gating to hosted billed workspaces; preserved permission refresh and manual-only freshness consequences. Corrected action-menu labels, Pending status, paused/resume behavior, one-minute healthy-sync cooldown, latest-ten history wording, and workspace versus permission-aware removal consequences. Preserved source-retirement cases with their actual default/selected-scope exceptions, incomplete-listing protection, partial failures, backoff, and ten-failure disable behavior. Kept Confluence formats/scope, legacy conversion guidance, image types/floor/GIF behavior, key prerequisites, configurable default image cap, billing/retry/re-enable behavior. Added Otter and Plane; removed a hardcoded connector count. | Verified improvement. Separates indexed KB connections from live Search, source permissions from Workspace access and setup from completed indexing. Adds lifecycle consequences, credential snapshot rotation, one-minute successful manual-sync cooldown and Confluence attachments behavior. Preserved: Original provider credential kinds, GitLab/project requirements, concrete source filters, metadata pool, sync schedule/manual run, Documents/Sync History/Settings actions and keep/remove document choices preserved. Steps retain the genuine sequential setup; unrelated videos/callouts replaced by named controls and scope statements. Five original token-generation locations identified as a preservation gap and sent to root with current primary URLs. |
+| [knowledgebase/debugging-retrieval.mdx](content/docs/knowledgebase/debugging-retrieval.mdx) | rewritten | Organized diagnosis as read output, processing, enabled/access state, filters, stored content, relevance, and duplicates. Removed unsupported universal similarity thresholds and described rank/rankScore/similarity/rerankerScore separately. Preserved raw processing statuses, separate Skipped outcome, Retry and replacement guidance, async wait/poll behavior, connector visibility, and duplicate analysis. Corrected reranker fallback to retain retrieval ordering; preserved completed hosted-key search-unit and BYOK distinction. | Verified improvement. Places completed/enabled/included/readable checks before ranking tweaks, distinguishes accepted upload/sync from finished indexing and isolates source-access failures. Removes misleading similarity cutoff and universal chunk-size advice; keeps returned Hybrid/reranker/recency order and explains cost/fallback. Preserved: No-results, irrelevant passages, duplicates, exact terms, tags, candidate count, reranking, overlap and chunk sizing all retained as diagnosis steps. Original error recovery examples preserved with valid operational qualifications; generic tip/FAQ material is folded into the relevant diagnosis. No unique operational media removed. |
+| [knowledgebase/export-import.mdx](content/docs/knowledgebase/export-import.mdx) | rewritten | Kept Export as the task/title and preserved stable path, ZIP tree, exact HTTP/CLI commands, vectors default, base64 float32 representation, manifest version and fields. Placed role/capability/OAuth/key access and workspace-readable archive scope before download steps. Clarified active/included scope, completed chunk eligibility, omitted empty documents, disabled flags, and all archive exclusions. Preserved 2,000-row preflight/413 and added verified bundle chunk/content format bounds; kept governance/audit and Search-index distinction. | Verified improvement. Puts export access/scope before commands; corrects personal-versus-workspace-readable scope, processing file/chunk inclusion and format ceilings. Adds portability model/dimension caveat, excluded ACL/credentials/provenance and CLI overwrite rule. Preserved: .simkb.zip, vectors default/opt-out, UI/API/CLI paths, manifest/files/chunks tree, float32 base64 encoding and connector-to-plain-document behavior retained. Original import absence remains clear from page purpose; archive source IDs/flags/counts and audit facts retained. Removed callouts/FAQ restated vectors/scope facts now explained at the decision point. |
+| [knowledgebase/index.mdx](content/docs/knowledgebase/index.mdx) | rewritten | Added shortest supported UI path using New base/New documents and explained upload acceptance versus processing completion. Listed actual accepted file extensions and 100 MiB/file, 20-file/action, 500 MiB/action limits. Replaced merge/split/any-document editing promise with current uploaded-document actions and connector read-only behavior. Qualified repository embedding default, kept model/dimension lifetime and query-only multi-base compatibility rule, and retained single-base block scope. Aligned six Related docs Cards with metadata order and added Export. | Verified improvement. Turns overview into create/upload/verify/retrieve flow with actual supported upload formats, limits and OCR prerequisites. Qualifies completion/access and embedding compatibility, keeps separate live Search catalog. Preserved: Original embedding/chunk concept, upload/connectors choice, inspection/editing, Knowledge→Agent composition and related owners retained. Defaults and self-hosted embedding controls preserved with model/dimension compatibility across query searches; tag-only exception added. Decorative media and general FAQ are replaced by complete named controls, format table and processing section. |
+| [knowledgebase/tags.mdx](content/docs/knowledgebase/tags.mdx) | rewritten | Preserved definition/value distinction and all 17 slots (7 Text/5 Number/2 Date/3 Boolean), current UI operators, AND behavior, variable references, date/Boolean/number formats, and connector metadata examples. Added verified Text 512-character and name 100-character bounds with case-insensitive uniqueness/matching. Corrected tag sorting promise to filtering, API rename versus base-modal controls, destructive delete-value consequence, and setup-only metadata choices without automatic slot freeing. Kept tags-only retrieval separate from query retrieval and avoided cheapest/most-precise guarantees. | Verified improvement. Defines metadata definition versus document value, exact typed capacity and destructive deletion before controls. Corrects case-insensitive names/matching, literal operator behavior, AND filters, tag-only no-embedding and connector metadata lifecycle. Preserved: All17 slots and all text/number/date/boolean UI operators retained, including between inclusive bounds and missing-value exclusion. Header Tags location and inspected screenshot retained; Add Tag/Tag Name/Type/Create Tag and document Tags panel remain. Original connector metadata, capacity allocation and filter examples retained; FAQ folded into capacity/operator/query sections. |
+| [knowledgebase/using-in-workflows.mdx](content/docs/knowledgebase/using-in-workflows.mdx) | rewritten | Started with minimum working query/Agent example, followed by query/tag inputs, outputs, advanced modes, and reranking. Corrected Automatic default and workspace policy, query-visible scope, topK default/range, and tag-only mode/cost behavior. Preserved #retrieval-mode, references, citation fields, Hybrid exact identifiers, and no extra keyword model call. Added rank/rankScore/rerankerScore semantics and recency/order guidance; made OutputBundle count match its one displayed result. Preserved reranker model/key prerequisite and added advanced candidate count, four-times default/cap, completed-call billing, and retrieval-order fallback. | Verified improvement. Provides exact Search/Knowledge Base/Search Query→Agent recipe and names output fields/ranking semantics. Adds retrieval modes, recency policy and candidate/fallback/metering behavior without universal similarity-order promises. Preserved: Original refund semantic example, <start.input>/<knowledge.results>, default10/max100, tag-only/query/tag combination and AND filters retained. Shared workflow preview and OutputBundle remain; original source/document/chunk/metadata/query/count fields preserved. Rerank switch/model/self-hosted Cohere key and cost implications retained with actual no-result/tag-only skip behavior. |
+
+### Agents (5)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [agents/index.mdx](content/docs/agents/index.mdx) | rewritten | Scoped definition to workflow agents; replaced repeated feature essays with task setup, capability table and canonical references. Kept corrected shared minimal-agent preview, successful root structured fields, file input, knowledge tool and conversation-ID memory boundaries. Added the overview to owned section navigation without changing slugs. Root retained automatic non-root overview linking rather than duplicating index in metadata; meaningful navigation guard caught the proposed duplicate. | Verified improvement. Replaces conceptual/promotional repetition and hardcoded model default with minimum configuration and capability table. Adds preview structured score binding, files/model/access boundaries and explicit conversation memory. Preserved: Start/Agent/prompt, content output/run details, all four tool sources, rubric, knowledge, memory, structured tier/Condition intention and fixed-vs-model decision preserved. Lead-score workflow preview retained; knowledge/deal-comparison use remains covered by linked knowledge owner and capability purpose. |
+| [agents/choosing.mdx](content/docs/agents/choosing.mdx) | rewritten | Led with who decides execution and an early comparison table; explained custom tools/MCP/workflows as kinds of Agent tools. Qualified Force by model support and execution success, custom API account requirements, and team-owned MCP servers. Preserved one complete lead example, fixed Workflow block versus workflow-as-tool distinction, child draft/deployed context and on-demand skills. | Verified improvement. Moves who-decides decision and six-choice mapping first; distinguishes fixed attempt from successful execution. Corrects Force as model-supported request, not guaranteed call/success; adds API credentials and child draft/deployed context. Preserved: Lead scorer enrichment/reshape/Sheets logging/Search/email/Deep Enrich/rubric examples and all six feature categories preserved. Multiple redundant highlighted previews and callout/VISUAL comments consolidated into one preview and corresponding task prose. |
+| [agents/custom-tools.mdx](content/docs/agents/custom-tools.mdx) | rewritten | Matched Add tool, stacked Schema/Code and Agent picker controls; retained generation capability. Retained canonical function-calling JSON schema, supplied named inputs and params object, safe optional input default, async HTTP/secret example and return semantics. Replaced Node/Buffer/crypto promises with isolated JavaScript, fetch-method, package and filesystem limits; distinguished direct Function tool and block. Corrected deletion role to Write/Admin and warned about saved-definition references; preserved search, secret syntax/visibility/exact-match projection and transformed-value caveats. Folded all three FAQ answers into runtime/secrets/Agent sections and replaced Steps with numbered setup. | Verified improvement. Corrects Schema/Code sections, Add tool control, params/optional bindings and isolated VM capabilities. Weather example now escapes city, handles optional units and HTTP failure; role table matches current Write deletion policy. Preserved: Full function schema and weather return fields retained; async/fetch/secrets reuse and standalone Function distinction remain. Original security/encoded-value limitations, generation controls, search/edit/delete facts and FAQ information folded into runtime/secrets/access sections. |
+| [agents/mcp.mdx](content/docs/agents/mcp.mdx) | rewritten | Matched Add server, save-time test, edit Test connection, Authorize, remote Streamable HTTP and optional OAuth client controls; corrected preliminary audit Connect label using current source. Preserved secret substitution and masking limits, acting/execution-actor OAuth identities, explicitly authorized managed connections and credential grants. Preserved dynamic plain-ID/name configuration, all three access policies, empty-selection semantics, saved legacy normalization, exact case-sensitive names, execution checks and arguments caveat. Preserved standalone List/Run fields, outputs, 1–100/default100 paging, server/managed ID resolution and JSON argument behavior. Added client discovery caps 50pages/1000tools/5MiB/60seconds, partial-versus-complete runtime behavior, five-minute cache/two-minute probe cache, matching draft-only Refresh, current-schema errors and recovery. Corrected registration delete Write/Admin and destination Admin permissions; kept separate external registrations/workflow deployment/Sim workspace/Search MCP directions and self-hosted exact domain-versus-egress/OAuth-origin distinction. | Verified improvement. Adds working OAuth registration sequence, server JSON scope, acting-user/managed identity and independent permissions. Clarifies discovery cache/partial inventory/budgets, draft refresh versus live snapshot, operations access and standalone outputs. Preserved: Every original remote registration field/secret/network boundary, Agent/dynamic/exact-name access mode and standalone list/run/pagination fact retained. Per-workspace registration, disableMcpTools and server-offline FAQ folded into registration/permissions/troubleshoot. Removed generic settings/screenshots/video are replaced with exact named controls; no unique required setup field removed. |
+| [agents/skills.mdx](content/docs/agents/skills.mdx) | rewritten | Led with reusable guidance and Agent on-demand versus Chat-tag behavior; preserved available_skills/load_skill/skill_name details and model compatibility. Preserved Integrations/Skills/Add to Sim, curated suggestions, search, create/edit/share/delete, all name/description/content limits and complete valid SKILL.md example. Specified 5MiB ZIP/shallowest SKILL.md selection and simple frontmatter-only/name-description-body import; explicitly excluded bundled scripts/references/assets/other metadata. Preserved creator/explicit Read-role editor/derived Admin access and sharing, qualified use by organization policy, corrected unconditional execution guarantee. Merged repeated generic best-practice lists and two FAQs into focused authoring and activation verification; retained 500-line recommendation as guidance. | Verified improvement. Moves first use and activation before authoring, clarifies model availability and voluntary load versus explicit Chat tag. Adds exact field/ZIP/import bounds and separates editors from runtime organization restrictions. Preserved: Skill discovery/activation/load_skill runtime, Integrations Skills/editor sharing/Admin rights, curated service skill, direct Chat tag, Markdown structure/testing intentions and under500line guidance preserved. SQL illustration replaced by complete lead-scoring SKILL.md with activation/steps/output/edge conditions; original unsupported universal always-executes guarantee removed. Add-skill screenshot retained; tab screenshot removed after task controls made explicit. |
+
+### CLI guides (8)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [cli/authentication.mdx](content/docs/cli/authentication.mdx) | rewritten | Organized method selection, approval, remote pairing, workspace selection, verification, CI, multi-profile login, self-hosting, storage/refresh, and revocation by task. Retained OAuth-only flags, explicit-method refusal, platform pairing upgrade boundary, callback/container limits, lifetime/refresh locking/replay details, shared-profile restrictions, file permissions, and OAuth versus API-key logout effects. Corrected whoami recovery and current Sim API keys label; added HTTPS and issuer-bound endpoint prerequisites; changed install step in Actions to Bun. | Verified improvement. Orders method choice, approval, remote terminals, workspace selection, verification, CI and revocation by task. Corrects whoami recovery, issuer/HTTPS restrictions and shared-profile/refresh claims; keeps permanent-key/OAuth differences. Preserved: Retains every login option, scopes/callback/remote restrictions, approval-code warnings, 0600 storage, one-hour/fixed30-day lifetimes, refresh locking/replay, CI, profile and logout behavior. |
+| [cli/configuration.mdx](content/docs/cli/configuration.mdx) | rewritten | Reorganized profiles, persistent defaults, independent precedence, files/shared authentication, workspace selection, environment controls, updates, and repair. Retained INI section rules, direct auth_profile restrictions, source precedence, file overrides, picker cap and ephemeral-value refusals, all-workspaces exceptions, update channels/install identity/locks/registry/cache/deadlines, and accurate Node proxy thresholds. Replaced rejected global-output repair with SIM_OUTPUT environment override; made table selection explicit for profile asterisk. | Verified improvement. Clarifies independent precedence, shared authentication restrictions, no global setting persistence, explicit profile existence and environment override repair. Qualifies notice caching and per-request timeout instead of baseline guarantees; retains updater/proxy/registry boundaries. Preserved: Retains profile/config/credential syntax, every variable and setting, workspace picker cap, all-workspaces rules, update managers/channels/ownership/timeouts and registry privacy. |
+| [cli/index.mdx](content/docs/cli/index.mdx) | rewritten | Rebuilt the first-run sequence with Bun installation, explicit workspace selection, verified settings, table listing, and deployed/manual execution. Scoped command shape to resources, retained singular/knowledge aliases and nested help, added task search and complete resource-group discovery. Aligned table transcript with --output table; preserved npm/pnpm compatibility and same-package-manager upgrade facts in prose. | Verified improvement. Makes installation→sign-in→workspace→verification→first workflow a usable numbered sequence and uses Bun installation. Expands the resource map and points to local-vs-Chat scope and command discovery; final meta entry reports status, not nonexistent limits. Preserved: Retains Node20, global/temporary installation, OAuth/pairing, profiles/workspace flags, JSON/table output, deployment/manual run, aliases/help and all original command groups. |
+| [cli/output.mdx](content/docs/cli/output.mdx) | rewritten | Separated raw machine values/envelopes from formatted display output and stdout/stderr. Retained text empty/unclipped/sanitized behavior, trace details, cursor shape, Chat streaming, exports and raw download exceptions. Added fixed-text telemetry and structured save receipt; pinned JSON export and explicitly stated import does not accept YAML; preserved actual command-specific monetary units. | Verified improvement. Explains unwrapped resources versus data/nextCursor list envelopes, raw-vs-display values and stderr exceptions. Corrects telemetry/export/raw-download behavior and pins JSON for round-trip imports instead of implying YAML imports work. Preserved: Retains all four formats, selection/defaults, timestamps/sizes/booleans, clipping/text nulls, trace output, profiles/config/chat/export/file exceptions. |
+| [cli/scripting.mdx](content/docs/cli/scripting.mdx) | rewritten | Reorganized unattended setup, file/list/leading-at inputs, predicates, pagination, command-specific failure tables, async waits, output selection, destructive effects, folders, organization requests/invitations, and nightly automation. Retained all predicate operators/sort syntax, memory/page/cursor controls, caps versus pagination, per-person zero/null credit behavior, permissions impact/fingerprint review, partial invitation commits, folder ref/direct-child behavior, and select-output limits. Added JSON byte bounds and embedded no-stdin boundary; corrected stderr/verification/pagination promises; included operation-wait exits and robust async nightly status handling without executing examples. | Verified improvement. Puts shell prerequisites first; differentiates pagination limit0 from destructive filter caps and separates all outcome-specific exit tables. Retains exact filter/list/folder/sync syntax while correcting run failure/paused handling, stderr format, stdin/embedded boundaries and safe nightly recovery. Preserved: Retains @file/@-/@@ escaping, list syntax, all predicate operators/sort, pagination/cursors/memory, confirmations, organization access/requests/caps/invitations, async waits, selected outputs, folders and end-to-end Bash recipe. |
+| [cli/troubleshooting.mdx](content/docs/cli/troubleshooting.mdx) | rewritten | Kept every original error class with short remedies and canonical links. Corrected output repair and whoami refusal advice; added issuer mismatch, refresh ambiguity, HTTPS/redirect/proxy, truncation versus server caps, output-file receipts/force, uncertain sync reconciliation, and sanitized issue reporting. Used Bun update fallback while retaining existing-manager, prerelease-channel, project-local, npm/pnpm/Yarn Classic compatibility facts. | Verified improvement. Starts with concrete version/profile verification and corrects wrong-workspace/auth-retry guidance. Adds refresh/issuer/redirect/proxy, server truncation, YAML-import and uncertain-operation recovery; fixes old claim docs track every installed release. Preserved: Retains wrong target, 401, connectivity, JSON quoting, table clipping, binary output, settings repair, updates, stderr notice and sanitized issue reporting recovery. |
+| [cli/usage-data.mdx](content/docs/cli/usage-data.mdx) | rewritten | Led with immediate opt-out and exact precedence before the complete event inventory. Retained flags versus values, runtime/CI/agent/endpoint-kind fields, random IDs/session timing, separate sender/no API key, first-notice exclusion, request attribution, and build-controlled self-hosting behavior. Corrected telemetry state deletion to include saved preference reset; stated event exclusions and fixed-text output; qualified downstream account/location/project claims to observable client behavior. | Verified improvement. Qualifies reporting by build destination and excludes nonexecuted/help/first-notice events; separates anonymous event fields from API attribution. Explains setting reset after deleting state, environment priority and network IP-derived location without promising no network data. Preserved: Retains complete event/omission lists, device/session identity, 30-minute grouping, localstate, telemetry opt-outs, firstnotice, self-hosted/build-time destinations and detached delivery. |
+| [cli/workflow-sync.mdx](content/docs/cli/workflow-sync.mdx) | rewritten | Organized access/gates, portable export inspection, resource/field bindings, dependent selector choices, exact preview/apply, fork/sync direction, mapping/copy identities, saved values, trigger URL choices, rollback limits, receipts/waits and uncertain retries. Retained every original concrete mapping/binding/value form, CLI versus HTTP envelope distinction, empty-mapping receipt requirements, source identities, copy opt-in and credential/secret exclusion, source versus destination discovery, direct edge/both-admin scope, exclusions, source deletion versus undeployment, receipt workspaces, list snapshots versus refreshed reads, request-ID replay/conflicts, and commit versus readiness distinction. Scoped fork entitlement to billing mode; pinned JSON export, added payload inspection/literal-value caveat, and moved contributor harness context to the existing API guide's contributor reference while retaining destination-provider validation. | Verified improvement. Organizes prerequisites→exact preview/apply→verification and gives deployment/auth gates, confidentiality qualifications and stable-request recovery. Clarifies source identities vs transient targets, envelope differences, mapping projection, selectors/copy/trigger choices and operation wait outcomes. Preserved: Retains all CLI flags/payloads, same-choices/fingerprint, plain vs mapped import, draft-only fork, direction-relative sync, copies/mappings, deployment readiness, rollback/unlink, requestIDs and contributor harness link. |
+
+### Files (5)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [files/index.mdx](content/docs/files/index.mdx) | rewritten | Added Upload/New file/New folder, viewer capabilities, organization actions, Download, private access, Share/Unshare modes and governance prerequisites. Separated persistent workspace Files, execution artifacts, private Chat attachments and knowledge-base ingestion. Linked archive and retention limits without promising instant physical deletion. | Verified improvement. Turns a sparse conceptual landing page into a usable upload/create/view/organize/share guide with roles and lifecycle. Adds supported viewers, upload ceiling and rendered-download distinction; removes any-workflow/universal-shared-content promises. Preserved: Original contract/report/file-versus-table-versus-KB decisions and workflow read/produce use cases retained. Original onward navigation preserved; private Chat attachment and execution-artifact distinction added. No baseline media or unique FAQ lost. |
+| [files/editor.mdx](content/docs/files/editor.mdx) | rewritten | Preserved formatting marks, heading/quote/divider syntax, lists, shortcuts, tables, code/Mermaid and image editing. Corrected slash-menu trigger, fixed headers, disabled column resizing/merged cells, Markdown normalization and source preservation. Explained 262,144-character rich-edit threshold, source fallback and 50 MiB text-editor ceiling. Documented visible-snapshot export versus saving, and Markdown/image ZIP exports. Review correction: the 50 MiB source preview limit differs from the 10 MiB whole-request save cap. | Verified improvement. Corrects exact-round-trip and universal-rich-edit claims; makes fixed headers, disabled resizing, source fallback and 262,144-character/50 MiB limits explicit. Formatting shortcuts and insertion rules are compact task/reference sections rather than decorative cards/callouts. Preserved: All original text/list/code/Mermaid/link/image functions retained; source preservation and unsupported constructs remain explained. Removed rendered-example screenshot adds no unique control procedure; original formatting/code/table/image facts are in text. Original slash-menu anchor retained as custom ID; links to generation and workflow reuse retained. |
+| [files/generating.mdx](content/docs/files/generating.mdx) | rewritten | Separated generated text, binary UserFile and persisted workspace file. Added complete visible Write recipes, exactly-one-source input, source file copy, folder-scoped suffixing, overwrite and Append. Preserved id/name/size/url and added version/revision precondition distinction. Explained /tmp/sim/outputs automatic workflow exports, per-call Chat SIM_OUTPUT_DIR workspace export and separate hidden Function tool persistence. Replaced direct public URL/never-bytes claims with authenticated workspace/run-file download and optional inline output guidance. | Verified improvement. Adds binary File input, overwrite scope, version versus revision preconditions, execution artifacts versus persistent Files, and authenticated API references. Corrects MIME-label-as-rendering and every-workflow-access guarantees without removing generation use cases. Preserved: Agent summary, Function CSV/text, ElevenLabs audio, images, output-object reuse, deduplicated naming and append all retained. Removed generic callout/card and non-rendered VISUAL comments folded into content/persistence/reference sections; useful MIME and saved-file identity facts remain. Generation/where-file-goes/next stable anchors retained with custom IDs. |
+| [files/passing-files.mdx](content/docs/files/passing-files.mdx) | rewritten | Documented UserFile key/context, optional base64/version, opaque identifiers, display-field omissions and distinct upload/run-file DTOs. Preserved indexed/full-object/property references and scoped compatibility instead of universal conversion claims. Replaced both invalid curls with v2 input wrapper and accepted type/data/name/mime descriptors. Base64 example contains semantically valid text bytes. Added Files/file[] entry prerequisite, deployed-state scope, stored-reference authorization, session serve versus authenticated run/workspace downloads, required workspaceId query, run lifecycle and inline base64 constraints. Folded unique FAQ facts into visible input/limit sections; retained file-capable block/storage examples and concrete separate limits. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Replaces invalid v2 top-level document requests with strict input-wrapper file[] descriptors and valid text base64. Separates UserFile versus API input versus projected run-download shapes and session URL versus X-API-Key download. Replaces automatic-format/base64 universals with receiving-block format limits and a scoped numeric limit table. Preserved: Original arrays/index/name/full-object/content references, Base64/URL alternatives, stored-reference reuse, all integration categories and Start files compatibility preserved. Both FAQ facts (no universal limit and incoming files processing) folded into File limits and API input sections. Original API anchor IDs retained; authored tabs replace direct Fumadocs imports. |
+| [files/using-in-workflows.mdx](content/docs/files/using-in-workflows.mdx) | rewritten | Rebuilt practical report.pdf → Agent → summary.md steps using preview aliases file and agent. Preserved Read/Get Content/Fetch/Write/Append outputs as common paths and linked the complete current operation reference. Corrected unsupported automatic Agent text fallback; named attachment prerequisite and Get Content text path. Preserved optional save/append, dynamic recursive folder selection, authenticated Fetch, extracted-text versus raw-byte Function helpers. Explained /tmp/sim/inputs and /tmp/sim/outputs, special indexed .path mount reference and local JavaScript helper scope. | Verified improvement. Makes a runnable Read→Agent→Write recipe whose named references agree with its shared preview. Corrects File operation count, attachment support, text-only extraction, binary Write, URL persistence, and indexed .path mount semantics. Preserved: PDF summary, email/image attachment, JSON/CSV deterministic Function processing, fetch headers, optional persistence and append use cases preserved. Original five common operations preserved as common paths rather than claiming exhaustive inventory; useful callout/VISUAL intentions are in concrete instructions. All original reading/processing/writing/composing anchors retained as custom IDs. |
+
+### Tables (3)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [tables/index.mdx](content/docs/tables/index.mdx) | rewritten | Moved creation before the type reference; added Expiration and all eight types in picker order, safe conversions and invalid-write distinctions. Preserved Currency relabeling, formula boundary, count/default/byte budgets, atomic row writes and local undo; folded FAQ into behavior. Distinguished configurable 400 KiB row-data default from the fixed 1,000-column ceiling. | Verified improvement. Moves create/edit before the type lookup; adds accurate coercion/API distinction instead of claiming every invalid editor/workflow input errors. Adds current Expiration type and scheduled cleanup/lock consequence; distinguishes individual atomic row writes from multi-step workflow transactions. Preserved: Every original type/example, currency relabel-without-conversion, spreadsheet paste/filter/sort,Table block/group/API choices and all four FAQ facts retained in substantive sections. Original table overview screenshot retained; formulas,undo/API exclusion and plan/deployment ceilings remain visible. JSON any-value and date-time support correct original overly narrow examples; units now match byte constants. |
+| [tables/using-in-workflows.mdx](content/docs/tables/using-in-workflows.mdx) | rewritten | Corrected row.data result and references, quoted JSON writes, first-page totalCount, unique/Conflict Column upsert prerequisites and overlapping-run consequences. Preserved all ten operations, valid shared preview and nested OutputBundle, all/any predicates, projection/sort, batch1000/unlimited filtered updates, cursor termination and surface-specific byte/default limits. | Verified improvement. Makes complete valid-JSON classify loop recipe with real row.data/loop.currentItem references and explicit schema prerequisite. Corrects first-versus-cursor totalCount and numeric coercion, adds unique Conflict Column and unlimited filtered update semantics. Preserves pagination by nextCursor and adds overlap/atomic-claim warning at the point of the queue-like status example. Preserved: All ten original operation intentions,leads fields,shared preview/OutputBundle,all/any nested predicate,order/projection,built-in fields and Insert JSON retained. Original midrun pricing lookup,sequential individual classification,bulk same-patch,unlimited read5MiB/early pages,cursor termination and Logs inspection retained. Original invalidflatrows/unquotedJSJSON examples corrected rather than cut; generic type callout facts folded into current schema/coercion paragraph. |
+| [tables/workflow-columns.mdx](content/docs/tables/workflow-columns.mdx) | rewritten | Moved deployed-workflow prerequisite and setup ahead of behavior; corrected Show additional fields → Workflow inputs current navigation. Corrected full row context, Boolean dependencies, filtered/manual/incomplete controls, auto-run default/re-arm/cancellation, current states and non-guaranteed coordination; preserved output progress, cascade/retry/use-case distinctions. | Verified improvement. Replaces long screenshot-driven narrative with exact current deployed-workflow setup and inputs/output distinction. Corrects mappings-as-access-restriction,false/empty dependencies,attempt-sticky auto behavior,rearm/restartcost,filtered run scopes and atomic-concurrency guarantee. Adds Waiting versus Pending and No output semantics, including downstream no-match waiting. Preserved: Original Enrichments versus Workflow choice,CompanyDomain→CompanyInfo→LeadScore cascade,input/outputconfiguration,manualactions,auto-run/dependencies,statebadges and View execution/Re-run cell recovery preserved. Inspected all six baseline local PNGs independently: new-column-menu,configure-workflow,column-mapping,cell-menu,row-trace,table-groups. Their named setup/trace facts are covered in text; obsolete Add column inputs instruction is corrected to Show additional fields→Workflow inputs. Lost Stop all control found during fresh image review and restored by root. Completed values are retained on cancellation. |
+
+### Logs (3)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [logs-debugging/index.mdx](content/docs/logs-debugging/index.mdx) | rewritten | Separated backward-debugging steps from interface reference; corrected handled-error behavior, trace sections, access qualifications, visible trigger labels and retention. Preserved the six failure cases, resolved references, rerun comparison, and named Troubleshoot in Chat. | Verified improvement. Separates backward failure investigation from interface lookup and corrects handled-error, access/protection, active trace sections, and Chat troubleshooting claims. Replaces false every-run/universal exact-value/archive guarantees with recorded/access-aware logs and effective retention. Preserved: Retains all six investigation steps and all six common failures, named resolved inputs/output/data-flow links, metadata/duration/credits and rerun comparison. Meaningful trace screenshot remains and was visually inspected. Console/snapshot facts moved to the locally linked Run logs reference, and complete secret protections stay in the linked Credentials owner. |
+| [logs-debugging/logging.mdx](content/docs/logs-debugging/logging.mdx) | rewritten | Corrected run-ID search, structured filters, stable snapshot refresh, current trace sections, ledger itemization, access and snapshot availability, and effective retention without an archive promise. Folded unique FAQ fields into the reference; delegated full secret protection detail to Credentials. | Verified improvement. Corrects full-text/live-mode claims to execution-ID search, supported structured filters and stable list refresh controls. Adds current access/itemized ledger and unavailable-snapshot boundaries, effective retention and cleanup versus archive. Preserved: Retains all columns/filters/cost units, console active/timing/tree input-output controls, identifiers/copy/data/file details, snapshot structure/config/connections and migrated Logged State Not Found. Complete status:error workflow:"Support" duration:>5s example and screenshot inspected; useful FAQ protection facts are in linked Credentials, and debugging/task reference separation remains coherent. |
+| [logs-debugging/alerts.mdx](content/docs/logs-debugging/alerts.mdx) | rewritten | Kept verified event, threshold, credit, cooldown, rate minimum and recursion boundaries; added delivery/access prerequisites, verification and troubleshooting. Limited the one-hour rule to run-backed alerts and documented No Activity per-workflow max(one hour, inactivity window) cooldown. | Verified improvement. Adds concrete deployment/delivery/access prerequisites, separate verification and troubleshooting rather than mixing setup with success claims. Corrects No Activity per-workflow max(onehour,inactivity) cooldown while preserving plain versus run-backed rule distinction. Preserved: Retains complete three-consecutive-failures Slack setup, reference message, workspace/source filtering, event/rule choices/credit units/five-run minimum, anti-self/anti-recursion and delivery failure diagnosis. The full text example is unchanged and a named workspaceevent trigger is specified; exact defaults/output details are available in the linked current Sim event reference. |
+
+### MCP (3)
+
+| Page or operation | Result | Changes | Final comparison and preservation |
+| --- | --- | --- | --- |
+| [mcp/authentication.mdx](content/docs/mcp/authentication.mdx) | rewritten | Qualified one-hour access token and fixed 30-day offline refresh grant; removed unsupported renewal and full-access generalizations. Preserved scopes, server audience, revocation consequences, both key forms and examples; distinguished personal/workspace policy and default expiration, exact policy labels and environment interpolation. | Verified improvement. Adds fixed one-hour/30-day OAuth lifetimes and offline_access, actual permission-policy labels and resource-scope boundaries. Qualifies UI-created key default expiry, self-hosted URLs and Cursor environment interpolation. Preserved: Both key client examples, headers/Bearer alternatives, personal/workspace scope, read/write OAuth scopes, audience, revoke/no-undo and organization restrictions retained. Key warning remains concrete; removed most-apps-full-access speculation adds no operational loss. |
+| [mcp/overview.mdx](content/docs/mcp/overview.mdx) | rewritten | Qualified supported JSON API coverage, credential scope and client-controlled approvals; linked canonical request limitations. Moved network prerequisites before connection; preserved all five client tabs and both deployment URLs, corrected Claude navigation and DCR strategy. Used shared authored tabs with padded mixed content, wrapped prose, visible horizontal scrolling, and mobile touch targets. | Verified improvement. Qualifies supported JSON operations rather than promising entire API, scopes connection credential and app-controlled approvals. Puts self-hosted/network prerequisites before client tabs; updates current Claude Customize and automatic registration labels. Preserved: Cloud/self-hosted server URLs, all five complete client examples, read/workflow/failure/table prompts and three separate MCP surfaces retained. Hosted-Claude versus local-client reachability Callout folded into prerequisite prose; authored tabs preserve configuration examples. |
+| [mcp/tools.mdx](content/docs/mcp/tools.mdx) | rewritten | Preserved four tool names, request fields, API result/error formats and binary/multipart/streaming exclusions. Corrected read bodies and method-independent tool classification; added catalog 25/100 bounds, declared-header rules, conditional resource paging, and post-write 1MiB size-error recovery. | Verified improvement. Adds catalog-search defaults/max/no-cursor distinction and permission-based read/write classification. Corrects read JSON body support, forbidden header overrides and post-execution result-size consequences. Preserved: All four tool names and table-row request slots/example, envelope/errors, API parity,1MiB/no-stream/no-binary and async poll guidance retained. Additional queryRows POST/read body example makes previously misleading write-only body row usable. |
+
+## Qualified claims and separate product issues
+
+- A repository default or flag does not prove the deployed Cloud value. Pricing, plan caps and rollout claims remain linked/qualified where live evidence is unavailable. The Max concurrent-run value conflicts with public pricing; the copy does not choose an unverified number.
+- External Chat worker evidence is the read-only staging snapshot `3aec2a03379d175264c26481d25f85647297ee32`. No live worker deployment was authenticated or changed.
+- Provider console procedures and client syntax were checked against primary sources. No provider account, live OAuth grant, infrastructure installation, license entitlement or production data operation was exercised.
+- Uninspected remote media is unverified, not declared stale. Redundant media can be removed when written instructions preserve its purpose.
+- Project file ownership, storage and realtime foundations are present in the latest staging snapshot, but the corresponding Project Files routes/editor callbacks are absent. Future Project docs must distinguish organization retention from workspace overrides. No usable Project Files surface is claimed in this rewrite.
+- Separate implementation observations include missing shipped upload-session cleanup scheduling, permissive schedule validation versus the cron parser, Redis-unavailable row coordination fallback, partial MCP discovery without a completeness flag, and SDK streaming limitations. Copy describes current supported behavior; this pass does not silently change these systems.
+
+## Validation
+
+- **Coverage**: 484/484 entries independently compared across 22 sections, with no missing or duplicate assignments and zero remaining identified copy issues. Scope: 153 authored entries, 28 CLI references, and 303 API operations; 306 integration MDX pages excluded from edits.
+- **Rebase**: Rebased onto origin/staging at 9058427155 after reviewing all 20 intervening commits. The additional export-prefix cleanup does not change documented workspace behavior.
+- **Generation**: Seven OpenAPI documents, 28 CLI reference pages, CLI API, MCP catalog, v2 route table, and Agent streaming region are current. All 303 API operation identities and 318 CLI command/option shapes preserved.
+- **API inputs and examples**: 22 canonical contract files reviewed: 19 editorial-stripped ASTs match staging; three differences are documented description-only helpers. All 135 rendered JSON request bodies validate, and all 135 curl samples pass bash syntax. The baseline’s 17 invalid bodies were reproduced and corrected.
+- **Generator boundary**: The actual 1,057,209-byte resources input reproduced the old successful empty-format result. The formatter now has explicit 16 MiB bounds, preserves complete parsed JSON (1,027,061 formatted bytes), and rejects oversized input; independently inspected.
+- **MDX and links**: All 790 runtime entries compiled/exported. All 1,988 internal links and 97 preserved inbound anchors pass, including excluded integrations and application references.
+- **Repository gates**: Root lint (26 tasks), type-check (26 tasks), check:audits (60 audits), test (20 workspace tasks plus script tests), and applicable block-registry checks against origin/staging passed. Full app run: 3,378 files, 37,636 passed, and 12 skipped. Existing warnings in two unchanged tests remain. The initial docs audit added, edited, or removed no tests; the later picker-selector follow-up is recorded below.
+- **CLI discovery**: Existing tests reproduced a real search regression when the word spent was removed. Help now retains credits spent without the inaccurate this-period claim; all 17 search tests and the complete CLI suite pass.
+- **Production build**: Final apps/docs build passed after the source and layout corrections, generating 1,588 static outputs and full Markdown. A dummy loopback DATABASE_URL was used; no database or authenticated product request was exercised.
+- **HTTP checks**: 1,631/1,631 pass: 789 HTML routes, 789 per-page Markdown routes, 37 local assets, root/missing-route/noindex checks, full Markdown byte equality and API-operation exclusion, CLI.mdx, OpenAPI JSON, negotiated Markdown/Vary Accept, and integration landing backlinks.
+- **Rendered checks**: All 483 readable in-scope routes inspected at 320px with zero prose or root overflow. All 20 authored-tab pages checked across 101 states (81 selections). Mixed panels retain 16px padding, code-only panels fill the frame, and narrow tab targets reach 44px. Intentional code/table/tab-strip scrolling retained.
+- **Responsive navigation**: MCP and generated API checked at 320, 390, 639, 640, 767, 768, 1023, 1024, 1279, 1280, and 1536px. Titles clear actual chrome by 24/32/56px with no empty API TOC row. Drawer faces are 30px, mobile targets 44px, and the aligned 101px header passes at 320/700px. All four section links close the drawer; Escape restores Open Sidebar focus. Native modal keeps other page controls inert; keyboard boundaries may enter browser chrome. A later API tablet header-span defect was reproduced and corrected; fresh checks additionally assert full header width at 768–1023px and right-aligned controls at 768px.
+- **SSO accessibility and bookmarks**: Explicit native controls reciprocally link all five panels. End/ArrowLeft/Home select and scroll tabs correctly. All five bookmarks pass at 320/768/1536px (15 states), selecting the requested provider with tabs 16.8px below sticky chrome. The pre-fix covered bookmark offset was reproduced.
+- **Colors and preview**: All five HTTP method badges checked in light and dark themes; minimum computed contrast is 8.43:1. Inline prose code matches Sim Chat at normal weight, inherited font size and 1px/4px padding in both themes; fenced samples and classed API/schema code keep their own chrome. Dark appearance restored and temporary viewport reset; a verified production API preview remains available.
+- **Cleanup**: 111 newly unused original assets removed (15,187,771 bytes), with repository consumer proof. Unused ActionMedia and three workflow previews removed. Authored callouts 234→117, FAQ 58→0 with useful answers moved, media 178→23, and placeholders 36→0. Shared integration assets retained.
+- **Evidence**: Detailed local evidence in /tmp/sim-docs-copy-audit includes exact final-comparison/rewrite ledgers, source qualifications, rebase reviews, parity proofs, formatter reproduction, HTTP/render reports and screenshots. The committed audit retains every page’s final comparison and preservation findings.
+- **Ship cleanup**: Eight read-only cleanup passes found no React state/effect/memo/callback/query/URL/design issue. Three comment improvements place conditional-write documentation on its owner and shorten redundant reranking/retention notes. That cleanup pass changed no tests. Public hygiene review cleared all 335 regex hits as synthetic examples, documented limits, public references, or repository measurements.
+- **Review corrections**: PR review triage corrected 13 findings and aligned three stale convention findings with sentence case; four findings were disproved against owners and real rendering/help output. A complete 303-operation sweep checked 539 canonical input slices and corrected 33 parameter/query metadata claims plus eight empty-query clarity descriptions. MCP probe/reset, hosting, billing source, credential capability, SSO save result, log/connector examples, numeric preview, and Pi color are corrected at their owners. Related request-cap guides distinguish configured caps, decoded-file limits, and effective request limits.
+- **Review-round validation**: All regenerated references, eight cleanup passes, root lint, 60 audits, 26 type-check tasks, block-registry checks, five sibling test files (36 tests), and the complete 20-workspace test run pass. App: 3,378 files, 37,636 passed, 12 skipped. Production docs build passed; 135 request examples and 135 curl samples validate. All 1,631 HTTP/Markdown/asset checks pass again. API headers fill mobile/tablet widths across 12 breakpoints, MCP clears its TOC at 320/768/1023px, and the temporary viewport is reset. Deployed Vercel preview is login-protected; content verification uses the local production build.
+- **Review-round UI validation**: Both later review findings are corrected: distinct Show/Hide array-item action labels and the canonical Pi canvas sentence with its repository field. Auth labels render without nested code pills, preserve keyboard selection, and keep 30px visible faces with 44px targets. Response headings align with the shared ChipSelect, and its 96px menu aligns to the trigger within 1px at 320/390/768/1023/1280px. Response and request-example pickers retain accessible labels and selection callbacks. Property filters use scoped dependency selectors, including body-portaled schema popovers; focus has no outward ring, narrow inputs fit their frame, and coarse-pointer mobile fields use the shared 44px/16px treatment.
+- **Review-round control coverage**: All 303 response menus preserve all 2,919 status choices in canonical order. All 22 choices across eight multi-example request pages produce distinct, nonempty code samples. Seventeen selected response states across list and execution pages show exactly their matching open schema. Matching and empty-result filtering, nested-schema Enter navigation, and Escape focus restoration pass. Fresh final 320px checks cover all 789 routes, including unchanged integrations, with zero root, prose or visible filter-input overflow; intentional code/table/tab/canvas scrolling is retained. All 1,631 HTTP/Markdown/asset checks pass after the final production build.
+- **Review-round repository gates**: The final UI changes pass eight cleanup passes, root lint (26 tasks), 60 audits, type-check (26 tasks), block-registry checks, all three docs test files (seven tests), and root tests (20 successful workspace tasks plus script tests; 19 unchanged workspace results reused). An earlier run failed on worker startup/termination and a teardown timeout; all eight affected files then passed (68 tests), and the complete rerun with two workers passed 3,378 app files, 37,636 tests, and 12 skips. No tests or timeout configuration were changed to suppress those failures. Final production docs build generates 1,588 outputs.
+- **Accessibility follow-up**: Request-example and response-status trigger names now include the selected value. Browser accessibility trees confirm changed selections announce Request example 3 and status 413 while callbacks, options and styles remain unchanged. Eight cleanup passes are clean. The later tablet TOC warning was independently disproved from compiled CSS: important utilities-layer declarations win over the unlayered important ID rule; fresh 320/768/1023px computations reserve 40px, with tablet headings 32px below the TOC. Full tests and production-build validation for this labels-only follow-up run in CI under the latest user instruction. The earlier all-page and control render proofs still describe the unchanged visual implementation. Normal docs dev startup adds the installed Next.js guidance to AGENTS.md; that standard section is retained alongside the authored editorial instructions.
+- **Open-menu accessibility and hydration**: The shared ChipSelect now exposes single choices as menuitemradio with aria-checked from its existing controlled value, matching the main app reasoning-effort picker. Radix keyboard handling, callbacks, row chrome and the multi-select checkbox branch are unchanged; consumer, role-selector and eight cleanup reviews found no behavioral regression. The pre-fix accessibility tree exposed plain menu items; final keyboard checks show exactly one checked choice, its state follows selection, and Escape restores trigger focus. All 22 request examples pass again at 320px with distinct code and correct checked state; response 200/413/503 checked states, schemas, 96px menu width and alignment pass. Docs pickers are nonmodal to avoid applying aria-hidden to the lazily hydrating search footer: the warning was reproduced, then three fresh-page menu checks passed with no warning or hidden siblings. One synthetic interaction before navigation focus settled was repeated after the page settled; no data action occurred. Full final tests and builds run in CI.
+- **Picker-test compatibility**: CI reproduced eight failures in four existing tests whose single-choice helpers queried the old menuitem role. Parallel test-audit review retained their shell-quoting, explicit integration-grant, scheduling and unsaved-draft assertions and changed only those helpers to menuitemradio. The existing mobile E2E settings-navigation locator received the same one-line adaptation; ordinary action and ChipDropdown locators remain unchanged. No tests, assertions or production seams were added or removed. Final full suites and mobile E2E run in CI; local regeneration, lint, 60 audits, 26 type-check tasks and block-registry checks pass.
diff --git a/apps/docs/EDITORIAL_GUIDE.md b/apps/docs/EDITORIAL_GUIDE.md
new file mode 100644
index 00000000000..50c5b39d3ca
--- /dev/null
+++ b/apps/docs/EDITORIAL_GUIDE.md
@@ -0,0 +1,87 @@
+# Documentation editorial guide
+
+Use this guide with [Sim's product language](../../.claude/rules/constitution.md). Documentation explains how the current product works. Each page should help a reader complete a task, understand a decision, or look up a contract.
+
+## Voice and terminology
+
+- Lead with one or two sentences explaining the task or behavior. Use active voice, short sentences, concrete examples, and imperative steps.
+- Remove promotional adjectives, repeated introductions, generic benefits, and unsupported guarantees. Prefer “Deploy the workflow” to “Unlock the power of automation.”
+- Name the actor when access matters: member, workspace Admin, organization owner, personal API-key caller, or workspace API key. A workspace role, OAuth scope, resource grant, and permission-group restriction are different controls.
+- Use **Sim** for the conversational agent, **Chat** for its surface, and **workflow builder** for the visual editor. Workflow terminology is appropriate when documenting the Workflows module. Preserve literal command names, protocol identifiers, environment keys, and compatibility fields.
+- Use sentence case for titles, descriptions, headings, navigation labels, and API summaries. Preserve product names and acronyms such as API, MCP, OAuth, and SSO. Define unfamiliar terms on introductory pages.
+- Match visible UI labels exactly and format them in **bold**. Format commands, paths, fields, statuses, and literal values as `code`. Keep code examples copyable.
+- Use KiB, MiB, and GiB for limits defined in powers of 1024. Identify whether a number is a default, a hard limit, a configurable setting, or an illustrative example.
+
+## Page organization
+
+Use the order appropriate to the page. These are ordering rules, not a requirement to add empty sections.
+
+| Page type | Order |
+| --- | --- |
+| Overview | Purpose → when to use it and supported capabilities → shortest path to use → important boundaries → related docs |
+| Task guide | Result → actual prerequisites → numbered steps with examples at the relevant step → verify the result → limits or troubleshooting → related docs |
+| Concept | Purpose or decision → behavior and example → boundaries and edge cases → related docs |
+| Block reference | Purpose → minimum working example → settings and inputs → outputs → behavior, limits, and errors → distinct additional examples → related docs |
+| Operator guide | Deployment scope → prerequisites → supported setup → verification → operational and security consequences → troubleshooting or reference → related docs |
+| Command or API reference | Purpose and access → invocation or request example → inputs and defaults → outputs and statuses → consequences, errors, and limits → related references |
+
+Group large references by resource and lifecycle. Keep comprehensive machine references when they serve a separate lookup purpose. Keep prerequisites before the action they govern and destructive consequences before the command or control that triggers them.
+
+Prefer concrete headings such as “Create a connection,” “Outputs,” or “Handle failed requests” over “Overview,” “Advanced features,” and “Best practices.” End onward navigation under **Related docs**, after substantive content.
+
+## Preserve useful information
+
+Shorten by removing repetition and organizing facts. There is no universal word limit.
+
+Keep exact syntax, required fields, permissions, defaults, unsupported cases, resource limits, billing behavior, security boundaries, failure effects, and recovery procedures. Distinguish Cloud from self-hosted deployments and billing-enabled behavior from billing-disabled behavior. Distinguish drafts from deployed versions and an accepted operation from completed background work.
+
+Verify claims against the current owning implementation and visible controls. Use current primary documentation for external services. A repository default does not prove the live hosted configuration. If sources disagree, qualify the statement and record the unresolved conflict in the audit rather than choosing an unsupported guarantee.
+
+Give repeated detail one canonical owner:
+
+| Detail | Canonical owner |
+| --- | --- |
+| Setup requirements and procedures | The relevant task or operator guide |
+| Feature behavior, outputs, and limits | The feature or block reference |
+| Roles, resource grants, and membership | Permissions and the specific resource guide |
+| Permission-group resolution | Enterprise permission groups |
+| Effective retention and cleanup | Enterprise data retention |
+| Credits, metering, and billing distinctions | Costs |
+| API authentication and envelopes | API getting started and authentication |
+| Streaming frames and protocol | Workflow streaming guide |
+| CLI options and command consequences | Generated command reference |
+
+A link replaces repeated detail only after the owner contains it. Keep a concise prerequisite or consequence at the point where the reader needs it.
+
+## Components and media
+
+- Fold useful FAQ answers into the section they explain. Keep a separate FAQ only for questions that cannot be organized coherently elsewhere.
+- Use a callout for a specific prerequisite or a non-obvious security, data-loss, or operational risk that deserves interruption. Use ordinary prose or a table for normal explanation. Keep important limits visible.
+- Use Markdown lists and tables for simple procedures and reference data. Use tabs for distinct configurations and Steps for substantial sequential procedures.
+- Match inline code to Sim Chat: normal-weight monospace text, tight padding, and the existing borderless filled surface tokens. Scope the treatment to prose code; preserve fenced examples, API route bars, schema controls, and selector labels.
+- Use shared `ChipSelect` controls for API response and request-example pickers, with accessible names that include the current value, checked radio semantics for single choices, and menus aligned to their triggers. Keep docs pickers nonmodal so they do not hide lazily hydrating siblings. Keep response headings free of inherited extra margins. Scope dependency filter styling to `data-object-search-input`, including schema popovers portaled to the body; focus stays inside the field, and touch fields retain the shared target and text sizes.
+- Import authored tabs from `@/components/ui/tabs`. Mixed panels retain a content inset; only a single code fence fills the frame. Keep long tab lists horizontally scrollable and long prose references wrapped. For bookmarked panels, use explicit native `TabsList`/`TabsTrigger` controls with `aria-controls` matching each panel ID; changing a panel ID alone leaves the generated control pointing at a nonexistent element.
+- Keep a screenshot when it locates a difficult control or shows a meaningful result. Keep a video when motion explains behavior that text or a static example cannot. Remove decorative, redundant, misleading, or non-rendering media.
+- Inspect media before describing it as stale. Uninspected remote media is unverified; it may still be removed when the written procedure fully covers its purpose. Do not fabricate replacement captures.
+- Remove imports, components, preview definitions, local styling, and assets made unused by an edit after checking all consumers, including integration pages.
+
+## Links and generated sources
+
+Preserve page paths and stable operation IDs. Before renaming a heading, check inbound links from all docs and application code. Preserve a referenced anchor with a custom heading ID such as `## New heading [#existing-anchor]`. Check links from integration pages even when their copy is outside the editing scope.
+
+Edit generated prose at its owner, then regenerate:
+
+| Output | Owner | Command from the repository root |
+| --- | --- | --- |
+| OpenAPI documents and operation pages | `apps/sim/lib/api/contracts/v2/**`, OpenAPI metadata, and `scripts/openapi/generator.ts` | `bun run generate:openapi` |
+| CLI API inputs | Generated OpenAPI and CLI contract overrides | `bun run generate:cli-api` |
+| CLI reference pages and navigation | Command tree, CLI metadata, and `scripts/generate-cli-docs.ts` | `bun run generate:cli-docs` |
+| MCP operation catalog | Authorized operation definitions and generated OpenAPI | `bun run generate:mcp-operations` |
+| v2 route table | Canonical route definitions | `bun run generate:v2-route-table` |
+| Marked Agent streaming table | Streaming protocol metadata and `scripts/sync-agent-stream-docs.ts` | `bun run generate:agent-stream-docs` |
+
+Do not hand-edit generated pages, JSON specifications, or marked generated regions. Preserve all argument, option, schema, authentication, and confirmation detail. CLI descriptions also feed command discovery; run the existing search-ranking checks after changing help copy. Validate rendered request examples against their canonical input contracts; schema validity alone may still leave a semantic error such as an invalid serialized workflow.
+
+## Review checklist
+
+Read the complete page and its examples. Check every useful fact against the original before cutting or moving it. Confirm the opening, order, terminology, headings, and component choices follow this guide. Compile MDX, check internal links and anchors, regenerate affected references, and inspect representative rendered pages on desktop and a narrow viewport. Run the repository's required validation gates for source changes.
diff --git a/apps/docs/README.md b/apps/docs/README.md
index 4bdd01e9e6d..f29f2d48930 100644
--- a/apps/docs/README.md
+++ b/apps/docs/README.md
@@ -1,23 +1,27 @@
-# docs
+# Sim documentation
 
-This is a Next.js application generated with
-[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
+The documentation site uses Next.js and Fumadocs. Read the [editorial guide](EDITORIAL_GUIDE.md) before changing copy or page organization. The [copy audit](COPY_AUDIT.md) records the complete page inventory, accuracy corrections, and validation.
 
-Run development server:
+## Develop
+
+From this directory:
 
 ```bash
 bun run dev
 ```
 
-Open http://localhost:3000 with your browser to see the result.
+Open `http://localhost:3001`. Build the site with `bun run build` and run the built server with `bun run start`.
+
+## Content owners
+
+- Authored pages and navigation: `content/docs/**` and each section's `meta.json`.
+- API operation pages: generated `openapi*.json`, owned by `apps/sim/lib/api/contracts/v2/**` and `scripts/openapi/generator.ts`.
+- CLI reference pages: generated from the command tree by `scripts/generate-cli-docs.ts`.
+- Interactive workflow examples: `components/workflow-preview/**`.
+- Local media: `public/static/**`. Videos resolved through `getAssetUrl` may be hosted remotely.
 
-## Learn More
+Use the owner and generation commands listed in the editorial guide. Do not hand-edit generated reference pages. The build also generates `llms-full.txt` from the current content.
 
-To learn more about Next.js and Fumadocs, take a look at the following
-resources:
+## Validate
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
-  features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-- [Fumadocs](https://fumadocs.vercel.app) - learn about Fumadocs
-- [Bun Documentation](https://bun.sh/docs) - learn about Bun features and API
+From the repository root, run the required lint, type, audit, and test gates in the development guidelines. From this directory, `bun run type-check` compiles MDX and checks the docs workspace, and `bun run build` validates the production site. Inspect affected page types on desktop and a narrow viewport, and check internal links and existing anchors after heading changes.
diff --git a/apps/docs/app/[[...slug]]/page.tsx b/apps/docs/app/[[...slug]]/page.tsx
index 689c7b0a69e..5c31e9a89d8 100644
--- a/apps/docs/app/[[...slug]]/page.tsx
+++ b/apps/docs/app/[[...slug]]/page.tsx
@@ -1,5 +1,12 @@
 import type React from 'react'
 import { Children, cloneElement, isValidElement } from 'react'
+import {
+  chipFieldSurfaceClass,
+  chipFieldTextClass,
+  chipGeometryClass,
+  chipHoverSurfaceClass,
+  cn,
+} from '@sim/emcn'
 import { highlight } from 'fumadocs-core/highlight'
 import { findNeighbour } from 'fumadocs-core/page-tree'
 import type { ApiPageProps } from 'fumadocs-openapi/ui'
@@ -26,7 +33,7 @@ import { DOCS_BASE_URL } from '@/lib/urls'
 const BASE_URL = DOCS_BASE_URL
 
 /**
- * Most pages close with a `## Next` / `## Next steps` grid of onward links.
+ * Pages close with related-documentation links or legacy next-step links.
  * That heading is navigation, not content, so it is kept out of the table of
  * contents — the ToC should say what the page covers, not where to go after it.
  * The heading itself still renders above the cards.
@@ -34,7 +41,15 @@ const BASE_URL = DOCS_BASE_URL
  * Matched on the slug rather than the rendered title because a ToC title is a
  * `ReactNode`; the trailing group tolerates the slugger's dedupe suffix.
  */
-const ONWARD_NAV_SLUG = /^#next(-steps)?(-\d+)?$/i
+const ONWARD_NAV_SLUG = /^#(?:next(?:-steps)?|related-docs)(?:-\d+)?$/i
+
+const AUTH_SCHEME_LABELS: Record<string, string> = {
+  apiKey: 'API key',
+  oauthBearer: 'OAuth access token',
+}
+
+const DOCS_BODY_CLASS_NAME =
+  '[overflow-wrap:anywhere] [&_:not(pre)>code:not([class])]:rounded! [&_:not(pre)>code:not([class])]:px-1! [&_:not(pre)>code:not([class])]:py-px! [&_:not(pre)>code:not([class])]:font-normal! [&_:not(pre)>code:not([class])]:text-[var(--text-primary)]! [&_:not(pre)>code:not([class])]:[font-size:inherit]! [&_:not(pre)>code:not([class])]:bg-[var(--surface-5)]! dark:[&_:not(pre)>code:not([class])]:bg-[var(--surface-4)]!'
 
 function isContentHeading(item: { url: string }): boolean {
   return !ONWARD_NAV_SLUG.test(item.url)
@@ -55,19 +70,42 @@ async function ApiCodeBlock({ lang, code }: { lang: string; code: string }) {
 }
 
 interface ApiSlotElementProps extends React.HTMLAttributes<HTMLElement> {
-  items?: unknown[]
+  items?: Array<{ value: string; label: React.ReactNode }>
 }
 
 /** Labels Fumadocs auth selectors while retaining their selection state and content. */
 function labelAuthSelectors(node: React.ReactNode): React.ReactNode {
+  if (typeof node === 'string') return AUTH_SCHEME_LABELS[node] ?? node
   if (!isValidElement<ApiSlotElementProps>(node)) return node
 
   const props = node.props
   const children =
     props.children === undefined ? undefined : Children.map(props.children, labelAuthSelectors)
 
+  if (node.type === 'code') {
+    return <span className='font-normal text-sm [&>span]:font-normal'>{children}</span>
+  }
+
   if (Array.isArray(props.items)) {
-    return cloneElement(node, { 'aria-label': 'Authentication method' }, children)
+    return cloneElement(
+      node,
+      {
+        'aria-label': 'Authentication method',
+        className: cn(
+          props.className,
+          chipGeometryClass,
+          chipFieldSurfaceClass,
+          chipFieldTextClass,
+          chipHoverSurfaceClass,
+          'relative shrink-0 py-0 focus:ring-0 focus-visible:bg-[var(--surface-hover)] before:absolute before:inset-x-0 before:-inset-y-[7px] before:content-[""]'
+        ),
+        items: props.items.map((item) => ({
+          ...item,
+          label: labelAuthSelectors(item.label),
+        })),
+      },
+      children
+    )
   }
   return children === undefined ? node : cloneElement(node, undefined, children)
 }
@@ -89,22 +127,30 @@ const APIPage = createAPIPage(openapi, {
   content: {
     renderOperationLayout: (slots) => {
       return (
-        <div className='flex @4xl:flex-row flex-col @4xl:items-start gap-x-6 gap-y-4 [--badge-amber-text:#854d0e] [--badge-blue-text:#1e40af] [--badge-error-text:#991b1b] [--badge-orange-text:#9a3412] [--badge-success-text:#166534] dark:[--badge-amber-text:#fcd34d] dark:[--badge-blue-text:#93c5fd] dark:[--badge-error-text:#fca5a5] dark:[--badge-orange-text:#fdba74] dark:[--badge-success-text:#86efac] [&_button[aria-haspopup=dialog]]:min-h-6'>
-          <div className='min-w-0 flex-1'>
+        <div className='grid @4xl:grid-cols-[minmax(0,1fr)_400px] grid-cols-1 @4xl:items-start gap-x-6 gap-y-4 [--badge-amber-text:var(--text-primary)] [--badge-blue-text:var(--text-primary)] [--badge-error-text:var(--text-primary)] [--badge-orange-text:var(--text-primary)] [--badge-success-text:var(--text-primary)] [&_button[aria-haspopup=dialog]]:min-h-6'>
+          <div className='@4xl:col-start-1 @4xl:row-start-1 min-w-0 flex-1'>
             {slots.header}
             {slots.description}
             {slots.apiPlayground}
             {slots.authSchemes && (
-              <div className='api-section-divider'>{labelAuthSelectors(slots.authSchemes)}</div>
+              <div className='api-section-divider [&>div:first-child]:flex-wrap [&>div:first-child]:gap-y-3'>
+                {labelAuthSelectors(slots.authSchemes)}
+                <p className='text-[var(--text-muted)] text-sm'>
+                  Request examples use an API key. For OAuth, replace the <code>X-API-Key</code>{' '}
+                  header with <code>Authorization: Bearer YOUR_ACCESS_TOKEN</code>.
+                </p>
+              </div>
             )}
+          </div>
+          <div className='@4xl:sticky @4xl:top-[calc(var(--fd-docs-row-1,2rem)+1rem)] @4xl:col-start-2 @4xl:row-span-2 @4xl:row-start-1 min-w-0'>
+            {slots.apiExample}
+          </div>
+          <div className='@4xl:col-start-1 @4xl:row-start-2 min-w-0 flex-1'>
             {slots.parameters}
             {slots.body && <div className='api-section-divider'>{slots.body}</div>}
             <ResponseSection>{slots.responses}</ResponseSection>
             {slots.callbacks}
           </div>
-          <div className='@4xl:sticky @4xl:top-[calc(var(--fd-docs-row-1,2rem)+1rem)] @4xl:w-[400px]'>
-            {slots.apiExample}
-          </div>
         </div>
       )
     },
@@ -196,6 +242,7 @@ export default async function Page(props: { params: Promise<{ slug?: string[] }>
           breadcrumb={breadcrumbs}
         />
         <DocsPage
+          className='min-w-0 max-md:col-[main]! max-md:px-4!'
           role='main'
           tabIndex={-1}
           toc={data.toc.filter(isContentHeading)}
@@ -221,7 +268,7 @@ export default async function Page(props: { params: Promise<{ slug?: string[] }>
             </div>
             <PageNavigationArrows previous={neighbours?.previous} next={neighbours?.next} />
           </PageHeader>
-          <DocsBody>
+          <DocsBody className={DOCS_BODY_CLASS_NAME}>
             <APIPage {...apiProps} />
           </DocsBody>
         </DocsPage>
@@ -267,7 +314,7 @@ export default async function Page(props: { params: Promise<{ slug?: string[] }>
           </div>
           <PageNavigationArrows previous={neighbours?.previous} next={neighbours?.next} />
         </PageHeader>
-        <DocsBody>
+        <DocsBody className={DOCS_BODY_CLASS_NAME}>
           {integrationLandingPage && (
             <p>
               {INTEGRATION_LANDING_LABEL}{' '}
diff --git a/apps/docs/app/layout.tsx b/apps/docs/app/layout.tsx
index 121e03e48ed..3fbe2958a6e 100644
--- a/apps/docs/app/layout.tsx
+++ b/apps/docs/app/layout.tsx
@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react'
-import { INTEGRATION_REACH } from '@sim/deployment-config/integration-claims'
+import { defaultTranslations as openApiTranslations } from 'fumadocs-openapi/i18n'
 import { DocsLayout } from 'fumadocs-ui/layouts/docs'
 import { SidebarProvider, SidebarTrigger, useSidebar } from 'fumadocs-ui/layouts/docs/slots/sidebar'
 import { RootProvider } from 'fumadocs-ui/provider/next'
@@ -22,13 +22,46 @@ const inter = Inter({
   display: 'swap',
 })
 
-const DOCS_DESCRIPTION = `Documentation for Sim — the open-source AI workspace where teams build, deploy, and manage AI agents. Connect ${INTEGRATION_REACH} and every major LLM.`
+const DOCUMENTATION_DESCRIPTION =
+  'Guides and API references for Sim, the open-source AI workspace. Learn how to use Chat, build workflows, manage data, and operate your deployment.'
+
+const OPENAPI_TRANSLATIONS = {
+  ...openApiTranslations,
+  titleRequestTabs: 'Request examples',
+  queryParameters: 'Query parameters',
+  pathParameters: 'Path parameters',
+  headerParameters: 'Header parameters',
+  cookieParameters: 'Cookie parameters',
+  titleRequestBody: 'Request body',
+  titleResponseBody: 'Response body',
+  typeScriptDefinitions: 'TypeScript definitions',
+  schemaMultipleOf: 'Multiple of',
+  closeJsonEditor: 'Close JSON editor',
+  openJsonEditor: 'Open JSON editor',
+  accessToken: 'Access token',
+  statusBadRequest: 'Bad request',
+  statusNotFound: 'Not found',
+  statusInternalServerError: 'Internal server error',
+  statusClientError: 'Client error',
+  resourceOwnerPassword: 'Resource owner password flow',
+  clientCredentials: 'Client credentials',
+  deviceAuthorization: 'Device authorization',
+  clientSecret: 'Client secret',
+  serverUrlFieldPlaceholder: 'Enter value',
+  schemaShowArray: 'Show array item',
+  schemaHideArray: 'Hide array item',
+  schemaFilterPropertiesPlaceholder: 'Filter properties',
+  playgroundShowProperty: 'Show property',
+  playgroundPropertyPlaceholder: 'Enter property name',
+  playgroundNewItem: 'New item',
+  playgroundRemoveItem: 'Remove item',
+}
 
 const structuredData = {
   '@context': 'https://schema.org',
   '@type': 'WebSite',
   name: 'Sim Documentation',
-  description: DOCS_DESCRIPTION,
+  description: DOCUMENTATION_DESCRIPTION,
   url: DOCS_BASE_URL,
   publisher: {
     '@type': 'Organization',
@@ -53,14 +86,17 @@ export default function RootLayout({ children }: { children: ReactNode }) {
           dangerouslySetInnerHTML={{ __html: serializeJsonLd(structuredData) }}
         />
       </head>
-      <body className='flex min-h-screen flex-col font-sans'>
+      <body className='flex min-h-screen flex-col font-sans [&_div:has(>input[data-object-search-input])]:h-[30px] [&_div:has(>input[data-object-search-input])]:min-w-0 [&_div:has(>input[data-object-search-input])]:rounded-lg [&_div:has(>input[data-object-search-input])]:border-[var(--border)] [&_div:has(>input[data-object-search-input])]:bg-[var(--surface-5)] [&_div:has(>input[data-object-search-input])]:shadow-none! [&_div:has(>input[data-object-search-input])]:focus-within:bg-[var(--surface-hover)]! [&_div:has(>input[data-object-search-input])]:focus-within:ring-0! max-md:pointer-coarse:[&_div:has(>input[data-object-search-input])]:min-h-11 dark:[&_div:has(>input[data-object-search-input])]:bg-[var(--surface-4)] [&_input[data-object-search-input]]:h-full [&_input[data-object-search-input]]:min-w-0 [&_input[data-object-search-input]]:py-0 [&_input[data-object-search-input]]:text-[var(--text-body)] max-md:pointer-coarse:[&_input[data-object-search-input]]:text-md'>
         <ThemeProvider
           attribute='class'
           defaultTheme='system'
           enableSystem
           disableTransitionOnChange
         >
-          <RootProvider theme={{ enabled: false }}>
+          <RootProvider
+            theme={{ enabled: false }}
+            i18n={{ translations: { openapi: OPENAPI_TRANSLATIONS } }}
+          >
             <a
               href='#nd-page'
               className='sr-only focus:not-sr-only focus:fixed focus:top-3 focus:left-3 focus:z-[100] focus:rounded-lg focus:bg-[var(--bg)] focus:px-4 focus:py-2 focus:text-[var(--text-primary)]'
@@ -96,7 +132,7 @@ export default function RootLayout({ children }: { children: ReactNode }) {
               }}
               containerProps={{
                 className:
-                  '!pt-0 [--text-muted:var(--text-secondary)] [--color-fd-muted-foreground:var(--text-secondary)]',
+                  '!pt-0 max-lg:mt-0! max-lg:[--fd-header-height:56px]! max-lg:[&>#nd-subnav]:flex! md:max-lg:[&>#nd-subnav]:col-[main-start/toc-end]! max-xl:has-[>[data-toc-popover]]:[--fd-toc-popover-height:40px]! max-xl:[&>[data-toc-popover]]:block! [--text-muted:var(--text-secondary)] [--color-fd-muted-foreground:var(--text-secondary)]',
               }}
             >
               {children}
@@ -118,10 +154,10 @@ export const viewport: Viewport = {
 export const metadata = {
   metadataBase: new URL(DOCS_BASE_URL),
   title: {
-    default: 'Sim Documentation — The AI Workspace for Teams',
+    default: 'Sim documentation',
     template: '%s | Sim Docs',
   },
-  description: DOCS_DESCRIPTION,
+  description: DOCUMENTATION_DESCRIPTION,
   applicationName: 'Sim Docs',
   generator: 'Next.js',
   referrer: 'origin-when-cross-origin' as const,
@@ -166,8 +202,8 @@ export const metadata = {
     locale: 'en_US',
     url: DOCS_BASE_URL,
     siteName: 'Sim Documentation',
-    title: 'Sim Documentation — The AI Workspace for Teams',
-    description: DOCS_DESCRIPTION,
+    title: 'Sim documentation',
+    description: DOCUMENTATION_DESCRIPTION,
     images: [
       {
         url: `${DOCS_BASE_URL}/api/og?title=Sim%20Documentation`,
@@ -179,8 +215,8 @@ export const metadata = {
   },
   twitter: {
     card: 'summary_large_image',
-    title: 'Sim Documentation — The AI Workspace for Teams',
-    description: DOCS_DESCRIPTION,
+    title: 'Sim documentation',
+    description: DOCUMENTATION_DESCRIPTION,
     creator: '@simdotai',
     site: '@simdotai',
     images: [`${DOCS_BASE_URL}/api/og?title=Sim%20Documentation`],
diff --git a/apps/docs/components/docs-layout/docs-sidebar.tsx b/apps/docs/components/docs-layout/docs-sidebar.tsx
index 1c8b890b6c7..252cdb604a1 100644
--- a/apps/docs/components/docs-layout/docs-sidebar.tsx
+++ b/apps/docs/components/docs-layout/docs-sidebar.tsx
@@ -13,6 +13,7 @@ import {
   SidebarItem,
   SidebarSeparator,
 } from '@/components/docs-layout/sidebar-components'
+import { DOCS_SECTIONS, getDocsSection } from '@/lib/navigation'
 import { cn } from '@/lib/utils'
 
 interface SidebarTreeProps {
@@ -67,6 +68,7 @@ export function DocsSidebar() {
   const dialogRef = useRef<HTMLDialogElement>(null)
   const { open, setOpen } = useSidebar()
   const mobile = useMediaQuery('(width < 1024px)')
+  const section = getDocsSection(usePathname())
 
   useEffect(() => {
     const dialog = dialogRef.current
@@ -91,25 +93,34 @@ export function DocsSidebar() {
         }}
         className='fixed inset-y-0 right-0 left-auto m-0 h-dvh max-h-none w-[85%] max-w-[380px] border-[var(--border)] border-l bg-[var(--surface-1)] p-0 text-[var(--text-body)] backdrop:bg-black/30 backdrop:backdrop-blur-xs open:flex open:flex-col'
       >
-        <div className='flex shrink-0 items-center justify-between px-4 pt-4 pb-2'>
-          <span className='text-[var(--text-primary)] text-sm'>Documentation</span>
-          <Chip aria-label='Close navigation' leftIcon={X} onClick={() => setOpen(false)} />
+        <div className='shrink-0 border-[var(--border)] border-b'>
+          <div className='flex h-12 items-center justify-between gap-3 px-4'>
+            <span className='text-[var(--text-primary)] text-sm'>Documentation</span>
+            <Chip
+              aria-label='Close navigation'
+              leftIcon={X}
+              mobileCompact
+              onClick={() => setOpen(false)}
+            />
+          </div>
+          <nav
+            aria-label='Documentation sections'
+            className='flex flex-wrap items-center gap-px bg-transparent! px-2 pb-2'
+          >
+            {DOCS_SECTIONS.map((item) => (
+              <ChipLink
+                key={item.slug}
+                href={item.href}
+                active={section === item.slug}
+                aria-current={section === item.slug ? 'page' : undefined}
+                mobileCompact
+                onNavigate={() => setOpen(false)}
+              >
+                {item.compactLabel}
+              </ChipLink>
+            ))}
+          </nav>
         </div>
-        <nav
-          aria-label='Documentation sections'
-          className='flex shrink-0 flex-wrap gap-px px-2 pb-2'
-        >
-          {[
-            ['Docs', '/introduction'],
-            ['API Reference', '/api-reference/getting-started'],
-            ['CLI', '/cli'],
-            ['MCP', '/mcp/overview'],
-          ].map(([label, href]) => (
-            <ChipLink key={href} href={href} onNavigate={() => setOpen(false)}>
-              {label}
-            </ChipLink>
-          ))}
-        </nav>
         {open && <SidebarScrollArea />}
       </dialog>
     )
diff --git a/apps/docs/components/docs-layout/page-header.tsx b/apps/docs/components/docs-layout/page-header.tsx
index 9b3b3b20195..a883bdc1431 100644
--- a/apps/docs/components/docs-layout/page-header.tsx
+++ b/apps/docs/components/docs-layout/page-header.tsx
@@ -10,7 +10,7 @@ interface PageHeaderProps {
 
 export function PageHeader({ title, children, className }: PageHeaderProps) {
   return (
-    <div className={cn('mt-6 flex flex-wrap items-start gap-x-4 gap-y-2 sm:mt-0', className)}>
+    <div className={cn('flex flex-wrap items-start gap-x-4 gap-y-2', className)}>
       <DocsTitle className='mb-2 min-w-0 flex-[1_1_16rem] [overflow-wrap:anywhere]'>
         {title}
       </DocsTitle>
diff --git a/apps/docs/components/footer/footer.tsx b/apps/docs/components/footer/footer.tsx
index 40ada5d217d..73d2d8d490f 100644
--- a/apps/docs/components/footer/footer.tsx
+++ b/apps/docs/components/footer/footer.tsx
@@ -28,7 +28,7 @@ const PRODUCT_LINKS: FooterItem[] = [
   { label: 'Tables', href: '/tables' },
   { label: 'MCP', href: '/agents/mcp' },
   { label: 'API', href: '/api-reference/getting-started' },
-  { label: 'Self Hosting', href: '/platform/self-hosting' },
+  { label: 'Self-hosting', href: '/platform/self-hosting' },
   { label: 'Status', href: 'https://status.sim.ai', external: true },
 ]
 
@@ -42,7 +42,7 @@ const RESOURCES_LINKS: FooterItem[] = [
 
 /** Top model providers — mirrors the landing footer's top 7 catalog providers. */
 const MODEL_LINKS: FooterItem[] = [
-  { label: 'All Models', href: `${SIM_SITE_URL}/models`, external: true },
+  { label: 'All models', href: `${SIM_SITE_URL}/models`, external: true },
   { label: 'OpenAI', href: `${SIM_SITE_URL}/models/openai`, external: true },
   { label: 'Anthropic', href: `${SIM_SITE_URL}/models/anthropic`, external: true },
   { label: 'Google', href: `${SIM_SITE_URL}/models/google`, external: true },
@@ -57,7 +57,7 @@ const BLOCK_LINKS: FooterItem[] = [
   { label: 'Router', href: '/workflows/blocks/router' },
   { label: 'Function', href: '/workflows/blocks/function' },
   { label: 'Condition', href: '/workflows/blocks/condition' },
-  { label: 'API Block', href: '/workflows/blocks/api' },
+  { label: 'API', href: '/workflows/blocks/api' },
   { label: 'Workflow', href: '/workflows/blocks/workflow' },
   { label: 'Parallel', href: '/workflows/blocks/parallel' },
   { label: 'Guardrails', href: '/workflows/blocks/guardrails' },
@@ -66,7 +66,7 @@ const BLOCK_LINKS: FooterItem[] = [
 ]
 
 const INTEGRATION_LINKS: FooterItem[] = [
-  { label: 'All Integrations', href: `${SIM_SITE_URL}/integrations`, external: true },
+  { label: 'All integrations', href: `${SIM_SITE_URL}/integrations`, external: true },
   { label: 'Slack', href: '/integrations/slack' },
   { label: 'GitHub', href: '/integrations/github' },
   { label: 'Gmail', href: '/integrations/gmail' },
@@ -98,8 +98,8 @@ const SOCIAL_LINKS: FooterItem[] = [
 ]
 
 const LEGAL_LINKS: FooterItem[] = [
-  { label: 'Terms of Service', href: `${SIM_SITE_URL}/terms`, external: true },
-  { label: 'Privacy Policy', href: `${SIM_SITE_URL}/privacy`, external: true },
+  { label: 'Terms of service', href: `${SIM_SITE_URL}/terms`, external: true },
+  { label: 'Privacy policy', href: `${SIM_SITE_URL}/privacy`, external: true },
 ]
 
 function FooterColumn({ title, items }: { title: string; items: FooterItem[] }) {
diff --git a/apps/docs/components/navbar/navbar.tsx b/apps/docs/components/navbar/navbar.tsx
index e918b9983ed..c10139356ca 100644
--- a/apps/docs/components/navbar/navbar.tsx
+++ b/apps/docs/components/navbar/navbar.tsx
@@ -6,55 +6,12 @@ import { usePathname } from 'next/navigation'
 import { SearchTrigger } from '@/components/ui/search-trigger'
 import { SimWordmark } from '@/components/ui/sim-logo'
 import { ThemeToggle } from '@/components/ui/theme-toggle'
+import { DOCS_SECTIONS, getDocsSection } from '@/lib/navigation'
 import { SIM_SITE_URL } from '@/lib/urls'
 import { cn } from '@/lib/utils'
 
-/**
- * Sections that own a tab, in reading order: the main docs, then the three
- * reference surfaces. `Documentation` matches by exclusion, so
- * every section listed here is one it must not claim.
- */
-const SECTION_TABS = ['api-reference', 'cli', 'mcp'] as const
-
-/**
- * Whether a pathname is inside a section, matched on its first path segment.
- *
- * A substring or suffix test is wrong: `/integrations/clickup` contains `/cli`,
- * and `/agents/mcp` ends with `/mcp`, and both belong to Documentation.
- */
-function isInSection(pathname: string, section: string): boolean {
-  return pathname === `/${section}` || pathname.startsWith(`/${section}/`)
-}
-
-const NAV_TABS = [
-  {
-    label: 'Documentation',
-    href: '/introduction',
-    match: (p: string) => !SECTION_TABS.some((section) => isInSection(p, section)),
-    external: false,
-  },
-  {
-    label: 'API Reference',
-    href: '/api-reference/getting-started',
-    match: (p: string) => isInSection(p, 'api-reference'),
-    external: false,
-  },
-  {
-    label: 'CLI',
-    href: '/cli',
-    match: (p: string) => isInSection(p, 'cli'),
-    external: false,
-  },
-  {
-    label: 'MCP',
-    href: '/mcp/overview',
-    match: (p: string) => isInSection(p, 'mcp'),
-    external: false,
-  },
-] as const
-
 export function Navbar() {
-  const pathname = usePathname()
+  const section = getDocsSection(usePathname())
 
   return (
     <nav className='sticky top-0 z-50 bg-[var(--bg)]/80 backdrop-blur-md backdrop-saturate-150'>
@@ -90,19 +47,18 @@ export function Navbar() {
             paddingLeft: 'calc(var(--sidebar-offset) + var(--nav-inset))',
           }}
         >
-          {NAV_TABS.map((tab) => {
-            const isActive = !tab.external && tab.match(pathname)
+          {DOCS_SECTIONS.map((tab) => {
+            const isActive = section === tab.slug
             return (
               <Link
                 key={tab.label}
                 href={tab.href}
                 aria-current={isActive ? 'page' : undefined}
-                {...(tab.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
                 className={cn(
                   '-mb-px relative flex items-center border-b text-sm tracking-[-0.01em] transition-colors',
                   isActive
                     ? 'border-[var(--text-muted)] font-medium text-[var(--text-primary)]'
-                    : 'border-transparent font-normal text-[var(--text-secondary)] hover:border-[var(--border-1)] hover:text-[var(--text-primary)]'
+                    : 'border-transparent font-normal text-[var(--text-secondary)] hover:border-[var(--border)] hover:text-[var(--text-primary)]'
                 )}
               >
                 {/* Invisible bold text reserves width to prevent layout shift */}
diff --git a/apps/docs/components/ui/action-media.tsx b/apps/docs/components/ui/action-media.tsx
deleted file mode 100644
index 79d47f5477a..00000000000
--- a/apps/docs/components/ui/action-media.tsx
+++ /dev/null
@@ -1,84 +0,0 @@
-'use client'
-
-import { useRef, useState } from 'react'
-import { Lightbox } from '@sim/emcn'
-import { cn, getAssetUrl } from '@/lib/utils'
-
-interface ActionImageProps {
-  src: string
-  alt: string
-  enableLightbox?: boolean
-}
-
-interface ActionVideoProps {
-  src: string
-  alt: string
-  enableLightbox?: boolean
-}
-
-export function ActionImage({ src, alt, enableLightbox = true }: ActionImageProps) {
-  const image = (
-    <img
-      src={src}
-      alt={alt}
-      className={cn(
-        'inline-block w-full max-w-[200px] rounded-lg border border-[var(--border-1)]',
-        enableLightbox && 'transition-opacity group-hover:opacity-90'
-      )}
-    />
-  )
-
-  if (!enableLightbox) return image
-
-  return (
-    <Lightbox src={src} alt={alt}>
-      <button
-        type='button'
-        aria-label={`Open ${alt} in media viewer`}
-        className='group inline-block cursor-pointer rounded p-0 text-left'
-      >
-        {image}
-      </button>
-    </Lightbox>
-  )
-}
-
-export function ActionVideo({ src, alt, enableLightbox = true }: ActionVideoProps) {
-  const videoRef = useRef<HTMLVideoElement>(null)
-  const [startTime, setStartTime] = useState(0)
-  const resolvedSrc = getAssetUrl(src)
-
-  const openLightbox = () => {
-    setStartTime(videoRef.current?.currentTime ?? 0)
-  }
-
-  const video = (
-    <video
-      ref={videoRef}
-      src={resolvedSrc}
-      autoPlay
-      loop
-      muted
-      playsInline
-      className={cn(
-        'inline-block w-full max-w-[200px] rounded-lg border border-[var(--border-1)]',
-        enableLightbox && 'transition-opacity group-hover:opacity-90'
-      )}
-    />
-  )
-
-  if (!enableLightbox) return video
-
-  return (
-    <Lightbox src={resolvedSrc} alt={alt} type='video' startTime={startTime}>
-      <button
-        type='button'
-        onClick={openLightbox}
-        aria-label={`Open ${alt} in media viewer`}
-        className='group inline-block cursor-pointer rounded p-0 text-left'
-      >
-        {video}
-      </button>
-    </Lightbox>
-  )
-}
diff --git a/apps/docs/components/ui/api-example-selector.tsx b/apps/docs/components/ui/api-example-selector.tsx
index 7f517ceba88..d3c8eb0f52a 100644
--- a/apps/docs/components/ui/api-example-selector.tsx
+++ b/apps/docs/components/ui/api-example-selector.tsx
@@ -1,15 +1,7 @@
 'use client'
 
 import type { ComponentProps } from 'react'
-import { useId } from 'react'
-import {
-  ChipChevronDown,
-  chipFieldSurfaceClass,
-  chipFieldTextClass,
-  chipGeometryClass,
-  chipHoverSurfaceClass,
-  cn,
-} from '@sim/emcn'
+import { ChipSelect } from '@sim/emcn'
 import type { APIPageClientOptions } from 'fumadocs-openapi/ui/client'
 
 type FumadocsAPIExampleSelector = NonNullable<
@@ -19,8 +11,6 @@ type FumadocsAPIExampleSelector = NonNullable<
 interface APIExampleSelectorProps extends ComponentProps<FumadocsAPIExampleSelector> {}
 
 export function APIExampleSelector({ items, value, onValueChange }: APIExampleSelectorProps) {
-  const id = useId()
-
   if (items.length <= 1) return null
 
   const selectedValue = value ?? items[0].id
@@ -28,34 +18,16 @@ export function APIExampleSelector({ items, value, onValueChange }: APIExampleSe
 
   return (
     <div className='not-prose mb-2 flex flex-col gap-1.5'>
-      <label htmlFor={id} className='sr-only'>
-        Request example
-      </label>
-      <div className='relative'>
-        <select
-          id={id}
-          value={selectedValue}
-          onChange={(event) => onValueChange(event.target.value)}
-          /**
-           * Dressed as an emcn chip trigger, but kept a native `select` for the keyboard and
-           * screen-reader behavior a custom listbox would have to rebuild.
-           */
-          className={cn(
-            chipGeometryClass,
-            chipFieldSurfaceClass,
-            chipFieldTextClass,
-            chipHoverSurfaceClass,
-            'w-full appearance-none pe-8'
-          )}
-        >
-          {items.map((item) => (
-            <option key={item.id} value={item.id}>
-              {item.name}
-            </option>
-          ))}
-        </select>
-        <ChipChevronDown className='-translate-y-1/2 pointer-events-none absolute end-2 top-1/2' />
-      </div>
+      <ChipSelect
+        modal={false}
+        aria-label={`Request example: ${selectedItem?.name ?? selectedValue}`}
+        value={selectedValue}
+        onChange={onValueChange}
+        options={items.map((item) => ({ value: item.id, label: item.name }))}
+        fullWidth
+        align='start'
+        dropdownWidth='trigger'
+      />
       {selectedItem?.description && (
         <p className='text-[var(--text-muted)] text-caption'>{selectedItem.description}</p>
       )}
diff --git a/apps/docs/components/ui/response-section.tsx b/apps/docs/components/ui/response-section.tsx
index 9637b27b7a7..43e42e1d9bc 100644
--- a/apps/docs/components/ui/response-section.tsx
+++ b/apps/docs/components/ui/response-section.tsx
@@ -1,21 +1,13 @@
 'use client'
 
-import { useEffect, useId, useRef, useState } from 'react'
-import {
-  ChipChevronDown,
-  chipFieldSurfaceClass,
-  chipFieldTextClass,
-  chipGeometryClass,
-  chipHoverSurfaceClass,
-  cn,
-} from '@sim/emcn'
+import { useEffect, useRef, useState } from 'react'
+import { ChipSelect } from '@sim/emcn'
 
 interface ResponseSectionProps {
   children: React.ReactNode
 }
 
 export function ResponseSection({ children }: ResponseSectionProps) {
-  const id = useId()
   const containerRef = useRef<HTMLDivElement>(null)
   const [statusCodes, setStatusCodes] = useState<string[]>([])
   const [selectedCode, setSelectedCode] = useState<string>('')
@@ -96,33 +88,19 @@ export function ResponseSection({ children }: ResponseSectionProps) {
   return (
     <div ref={containerRef} className='response-section-wrapper'>
       {statusCodes.length > 0 && (
-        <div className='response-section-header'>
-          <h2 className='response-section-title'>Response</h2>
-          <div className='response-section-meta'>
-            <div className='relative'>
-              <label htmlFor={id} className='sr-only'>
-                Response status code
-              </label>
-              <select
-                id={id}
-                value={selectedCode}
-                onChange={(event) => handleSelectCode(event.target.value)}
-                className={cn(
-                  chipGeometryClass,
-                  chipFieldSurfaceClass,
-                  chipFieldTextClass,
-                  chipHoverSurfaceClass,
-                  'appearance-none pe-8'
-                )}
-              >
-                {statusCodes.map((code) => (
-                  <option key={code} value={code}>
-                    {code}
-                  </option>
-                ))}
-              </select>
-              <ChipChevronDown className='-translate-y-1/2 pointer-events-none absolute end-2 top-1/2' />
-            </div>
+        <div className='response-section-header flex-wrap gap-y-3'>
+          <h2 className='response-section-title m-0!'>Response</h2>
+          <div className='response-section-meta flex-wrap gap-y-3'>
+            <ChipSelect
+              modal={false}
+              aria-label={`Response status code: ${selectedCode}`}
+              value={selectedCode}
+              onChange={handleSelectCode}
+              options={statusCodes.map((code) => ({ label: code, value: code }))}
+              align='end'
+              dropdownWidth={96}
+              contentClassName='min-w-0'
+            />
             <span className='response-section-content-type'>application/json</span>
           </div>
         </div>
diff --git a/apps/docs/components/ui/tabs.tsx b/apps/docs/components/ui/tabs.tsx
new file mode 100644
index 00000000000..6f92e1f6c28
--- /dev/null
+++ b/apps/docs/components/ui/tabs.tsx
@@ -0,0 +1,37 @@
+import { cn } from '@sim/emcn'
+import {
+  Tab as FumadocsTab,
+  type TabProps as FumadocsTabProps,
+  Tabs as FumadocsTabs,
+  type TabsProps as FumadocsTabsProps,
+} from 'fumadocs-ui/components/tabs'
+
+interface TabsProps extends FumadocsTabsProps {}
+
+interface TabProps extends FumadocsTabProps {}
+
+/** Keeps the dependency's selection and keyboard behavior with platform tab tokens. */
+export function Tabs({ className, ...props }: TabsProps) {
+  return (
+    <FumadocsTabs
+      {...props}
+      className={cn(
+        'min-w-0 scroll-mt-[calc(var(--fd-docs-row-3,0px)+1rem)] border-[var(--border)] [&>[role=tablist]>button]:font-normal! max-sm:[&>[role=tablist]>button]:min-h-11 [&>[role=tablist]]:min-w-0 [&>[role=tablist]]:[scrollbar-width:thin]! max-sm:[&>[role=tablist]]:min-h-14',
+        className
+      )}
+    />
+  )
+}
+
+/** Only a panel containing a single code fence can omit its content inset. */
+export function Tab({ className, ...props }: TabProps) {
+  return (
+    <FumadocsTab
+      {...props}
+      className={cn(
+        'min-w-0 p-4! [overflow-wrap:anywhere] has-[>figure:only-child]:p-0!',
+        className
+      )}
+    />
+  )
+}
diff --git a/apps/docs/components/workflow-preview/block-display-workflows.ts b/apps/docs/components/workflow-preview/block-display-workflows.ts
index 23e1a609d5a..75898672210 100644
--- a/apps/docs/components/workflow-preview/block-display-workflows.ts
+++ b/apps/docs/components/workflow-preview/block-display-workflows.ts
@@ -34,7 +34,7 @@ export const BLOCK_DISPLAY_WORKFLOWS: Record<string, PreviewWorkflow> = {
         position: { x: 0, y: 0 },
         rows: [
           { title: 'Messages', value: '-' },
-          { title: 'Model', value: 'claude-sonnet-4-6' },
+          { title: 'Model', value: 'claude-sonnet-5-5' },
           { title: 'Files', value: '-' },
           { title: 'Tools', value: '-' },
           { title: 'Skills', value: '-' },
@@ -135,7 +135,7 @@ export const BLOCK_DISPLAY_WORKFLOWS: Record<string, PreviewWorkflow> = {
         rows: [
           { title: 'Evaluation Metrics', value: '-' },
           { title: 'Content', value: '-' },
-          { title: 'Model', value: 'claude-sonnet-4-6' },
+          { title: 'Model', value: 'claude-sonnet-5-5' },
         ],
       },
     ],
@@ -219,7 +219,7 @@ export const BLOCK_DISPLAY_WORKFLOWS: Record<string, PreviewWorkflow> = {
         position: { x: 0, y: 0 },
         rows: [
           { title: 'Context', value: '-' },
-          { title: 'Model', value: 'claude-sonnet-4-6' },
+          { title: 'Model', value: 'claude-sonnet-5-5' },
         ],
         branches: [{ id: 'route 1', label: 'route 1' }],
       },
@@ -302,14 +302,14 @@ export const BLOCK_DISPLAY_WORKFLOWS: Record<string, PreviewWorkflow> = {
       {
         id: 'workflow',
         name: 'Workflow',
-        type: 'workflow',
+        type: 'workflow_input',
         typeLabel: 'Workflow',
         sentence: ['Run', { subBlockId: 'Select Workflow', noun: 'workflow' }],
         bgColor: '#6366F1',
         position: { x: 0, y: 0 },
         rows: [
           { title: 'Select Workflow', value: '-' },
-          { title: 'Input Variable', value: '-' },
+          { title: 'Inputs', value: '-' },
         ],
       },
     ],
@@ -317,12 +317,12 @@ export const BLOCK_DISPLAY_WORKFLOWS: Record<string, PreviewWorkflow> = {
   },
   human_in_the_loop: {
     id: 'human_in_the_loop',
-    name: 'Human in the Loop',
+    name: 'Human',
     blocks: [
       {
         id: 'human_in_the_loop',
-        name: 'Human in the Loop',
-        type: 'human_in_the_loop',
+        name: 'Human',
+        type: 'human_in_the_loop_v2',
         typeLabel: 'Human',
         sentence: ['Pause execution until a human responds'],
         bgColor: '#10B981',
@@ -336,6 +336,51 @@ export const BLOCK_DISPLAY_WORKFLOWS: Record<string, PreviewWorkflow> = {
     ],
     edges: [],
   },
+  pi: {
+    id: 'pi',
+    name: 'Pi Coding Agent',
+    blocks: [
+      {
+        id: 'pi',
+        name: 'Pi coding agent',
+        type: 'pi',
+        typeLabel: 'Pi Coding Agent',
+        bgColor: '#000000',
+        position: {
+          x: 0,
+          y: 0,
+        },
+        rows: [
+          {
+            title: 'Mode',
+            value: 'Plan',
+          },
+          {
+            title: 'Task',
+            value: 'Plan a repository change',
+          },
+          {
+            title: 'Repository Name',
+            value: 'my-repo',
+          },
+          {
+            title: 'Model',
+            value: 'claude-sonnet-4-6',
+          },
+        ],
+        sentence: [
+          'Run',
+          { subBlockId: 'Task', noun: 'task' },
+          'on',
+          { subBlockId: 'Repository Name' },
+          ', in',
+          { subBlockId: 'Mode' },
+          'mode',
+        ],
+      },
+    ],
+    edges: [],
+  },
   schedule: {
     id: 'schedule',
     name: 'Schedule',
@@ -415,7 +460,7 @@ export const BLOCK_DISPLAY_WORKFLOWS: Record<string, PreviewWorkflow> = {
         typeLabel: 'Table',
         sentence: [
           'Run on',
-          { subBlockId: 'Event type', noun: 'event' },
+          { subBlockId: 'Event', noun: 'event' },
           'in',
           { subBlockId: 'Table', noun: 'table' },
         ],
@@ -424,8 +469,8 @@ export const BLOCK_DISPLAY_WORKFLOWS: Record<string, PreviewWorkflow> = {
         hideTargetHandle: true,
         rows: [
           { title: 'Table', value: '-' },
-          { title: 'Event type', value: 'Row updated' },
-          { title: 'Watch columns', value: '-' },
+          { title: 'Event', value: 'Row Updated' },
+          { title: 'Watch Columns', value: '-' },
         ],
       },
     ],
diff --git a/apps/docs/components/workflow-preview/examples.ts b/apps/docs/components/workflow-preview/examples.ts
index 779b470acb7..21864d4b529 100644
--- a/apps/docs/components/workflow-preview/examples.ts
+++ b/apps/docs/components/workflow-preview/examples.ts
@@ -34,8 +34,16 @@ export const CLASSIFY_WORKFLOW: PreviewWorkflow = {
       bgColor: '#33C482',
       position: { x: 340, y: 0 },
       rows: [
-        { title: 'Model', value: 'claude-sonnet-4-6' },
-        { title: 'Messages', value: 'Classify <start.input>' },
+        { title: 'Model', value: 'claude-sonnet-5-5' },
+        {
+          title: 'Messages',
+          value: 'Classify <start.input> into sales, support, or billing and low or high urgency.',
+        },
+        {
+          title: 'Response Format',
+          value:
+            '{"name":"message_classification","schema":{"type":"object","properties":{"category":{"type":"string","enum":["sales","support","billing"]},"urgency":{"type":"string","enum":["low","high"]}},"required":["category","urgency"],"additionalProperties":false}}',
+        },
       ],
     },
   ],
@@ -76,7 +84,7 @@ export const CLASSIFY_REPLY_WORKFLOW: PreviewWorkflow = {
       bgColor: '#33C482',
       position: { x: 330, y: 0 },
       rows: [
-        { title: 'Model', value: 'claude-sonnet-4-6' },
+        { title: 'Model', value: 'claude-sonnet-5-5' },
         { title: 'Messages', value: 'Classify <start.input>' },
       ],
     },
@@ -94,7 +102,7 @@ export const CLASSIFY_REPLY_WORKFLOW: PreviewWorkflow = {
       bgColor: '#33C482',
       position: { x: 660, y: 0 },
       rows: [
-        { title: 'Model', value: 'claude-sonnet-4-6' },
+        { title: 'Model', value: 'claude-sonnet-5-5' },
         { title: 'Messages', value: 'Draft a reply for <classify.content>' },
       ],
     },
@@ -156,7 +164,7 @@ export const SUPPORT_KB_WORKFLOW: PreviewWorkflow = {
       bgColor: '#33C482',
       position: { x: 660, y: 0 },
       rows: [
-        { title: 'Model', value: 'claude-sonnet-4-6' },
+        { title: 'Model', value: 'claude-sonnet-5-5' },
         { title: 'Messages', value: 'Answer from <knowledge.results>' },
       ],
     },
@@ -197,7 +205,7 @@ export const TABLE_ENRICH_WORKFLOW: PreviewWorkflow = {
     },
     {
       id: 'loop',
-      name: 'Loop',
+      name: 'Process leads',
       type: 'loop',
       typeLabel: 'Loop',
       bgColor: '#FAFAF9',
@@ -223,8 +231,12 @@ export const TABLE_ENRICH_WORKFLOW: PreviewWorkflow = {
       position: { x: 70, y: 85 },
       parentId: 'loop',
       rows: [
-        { title: 'Messages', value: 'Classify <loop.currentItem>' },
-        { title: 'Response Format', value: '{ "category": "string", "score": "number" }' },
+        { title: 'Messages', value: 'Classify <loop.currentItem.data>' },
+        {
+          title: 'Response Format',
+          value:
+            '{"name":"lead_classification","schema":{"type":"object","properties":{"category":{"type":"string"},"score":{"type":"number"}},"required":["category","score"],"additionalProperties":false}}',
+        },
       ],
     },
     {
@@ -247,7 +259,7 @@ export const TABLE_ENRICH_WORKFLOW: PreviewWorkflow = {
         {
           title: 'Row Data',
           value:
-            '{ "category": <classify.category>, "score": <classify.score>, "status": "processed" }',
+            '{ "category": "<classify.category>", "score": "<classify.score>", "status": "processed" }',
         },
       ],
     },
@@ -276,7 +288,7 @@ export const API_FETCH_WORKFLOW: PreviewWorkflow = {
       bgColor: '#2FB3FF',
       position: { x: 0, y: 0 },
       hideTargetHandle: true,
-      rows: [{ title: 'Input', value: 'City' }],
+      rows: [{ title: 'Input', value: 'User ID' }],
     },
     {
       id: 'api',
@@ -293,7 +305,7 @@ export const API_FETCH_WORKFLOW: PreviewWorkflow = {
       position: { x: 330, y: 0 },
       rows: [
         { title: 'Method', value: 'GET' },
-        { title: 'URL', value: 'api.weather.com/<start.input>' },
+        { title: 'URL', value: 'https://api.example.com/users/<start.input>' },
       ],
     },
     {
@@ -310,7 +322,7 @@ export const API_FETCH_WORKFLOW: PreviewWorkflow = {
       bgColor: '#33C482',
       position: { x: 660, y: 0 },
       rows: [
-        { title: 'Model', value: 'claude-sonnet-4-6' },
+        { title: 'Model', value: 'claude-sonnet-5-5' },
         { title: 'Messages', value: 'Summarize <api.data>' },
       ],
     },
@@ -414,7 +426,14 @@ export const CONDITION_MODERATE_WORKFLOW: PreviewWorkflow = {
       ],
       bgColor: '#33C482',
       position: { x: 0, y: 60 },
-      rows: [{ title: 'Messages', value: 'Score toxicity of <start.input>' }],
+      rows: [
+        { title: 'Messages', value: 'Score toxicity of <start.input> from 0 to 1.' },
+        {
+          title: 'Response Format',
+          value:
+            '{"name":"moderation","schema":{"type":"object","properties":{"toxicity":{"type":"number","minimum":0,"maximum":1}},"required":["toxicity"],"additionalProperties":false}}',
+        },
+      ],
     },
     {
       id: 'condition',
@@ -437,7 +456,7 @@ export const CONDITION_MODERATE_WORKFLOW: PreviewWorkflow = {
       sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
       bgColor: '#FF402F',
       position: { x: 700, y: 0 },
-      rows: [{ title: 'Code', value: "throw 'blocked'" }],
+      rows: [{ title: 'Code', value: 'throw new Error("Content blocked")' }],
     },
     {
       id: 'publish',
@@ -467,77 +486,6 @@ export const CONDITION_MODERATE_WORKFLOW: PreviewWorkflow = {
   ],
 }
 
-/** Condition example: branch onboarding on the account tier. */
-export const CONDITION_ONBOARD_WORKFLOW: PreviewWorkflow = {
-  id: 'condition-onboard',
-  name: 'Branch onboarding',
-  blocks: [
-    {
-      id: 'plan',
-      name: 'Plan',
-      type: 'function',
-      typeLabel: 'Function',
-      sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
-      bgColor: '#FF402F',
-      position: { x: 0, y: 60 },
-      rows: [{ title: 'Code', value: 'return <start.account>' }],
-    },
-    {
-      id: 'condition',
-      name: 'Condition',
-      type: 'condition',
-      typeLabel: 'Condition',
-      bgColor: '#FF752F',
-      position: { x: 330, y: 60 },
-      rows: [],
-      branches: [
-        { id: 'condition-if', label: 'If', value: "<plan.result.tier> === 'enterprise'" },
-        { id: 'condition-else', label: 'else' },
-      ],
-    },
-    {
-      id: 'guided',
-      name: 'Guided setup',
-      type: 'agent',
-      typeLabel: 'Agent',
-      sentence: [
-        'Prompt',
-        { subBlockId: 'Model', noun: 'model' },
-        'with',
-        { subBlockId: 'Messages' },
-      ],
-      bgColor: '#33C482',
-      position: { x: 700, y: 0 },
-      rows: [{ title: 'Messages', value: 'Walk through SSO and SCIM' }],
-    },
-    {
-      id: 'quickstart',
-      name: 'Quick start',
-      type: 'agent',
-      typeLabel: 'Agent',
-      sentence: [
-        'Prompt',
-        { subBlockId: 'Model', noun: 'model' },
-        'with',
-        { subBlockId: 'Messages' },
-      ],
-      bgColor: '#33C482',
-      position: { x: 700, y: 140 },
-      rows: [{ title: 'Messages', value: 'Send the 2-minute setup' }],
-    },
-  ],
-  edges: [
-    { id: 'plan-condition', source: 'plan', target: 'condition' },
-    { id: 'condition-guided', source: 'condition', target: 'guided', sourceHandle: 'condition-if' },
-    {
-      id: 'condition-quickstart',
-      source: 'condition',
-      target: 'quickstart',
-      sourceHandle: 'condition-else',
-    },
-  ],
-}
-
 /** Function example: reshape an API response into the field a later block needs. */
 export const FUNCTION_RESHAPE_WORKFLOW: PreviewWorkflow = {
   id: 'function-reshape',
@@ -552,7 +500,7 @@ export const FUNCTION_RESHAPE_WORKFLOW: PreviewWorkflow = {
       bgColor: '#2FB3FF',
       position: { x: 0, y: 0 },
       hideTargetHandle: true,
-      rows: [{ title: 'Input', value: 'User ID' }],
+      rows: [{ title: 'Input', value: 'Team ID' }],
     },
     {
       id: 'api',
@@ -569,7 +517,7 @@ export const FUNCTION_RESHAPE_WORKFLOW: PreviewWorkflow = {
       position: { x: 320, y: 0 },
       rows: [
         { title: 'Method', value: 'GET' },
-        { title: 'URL', value: 'api.example.com/users/<start.input>' },
+        { title: 'URL', value: 'https://api.example.com/teams/<start.input>/users' },
       ],
     },
     {
@@ -582,7 +530,11 @@ export const FUNCTION_RESHAPE_WORKFLOW: PreviewWorkflow = {
       position: { x: 640, y: 0 },
       rows: [
         { title: 'Language', value: 'JavaScript' },
-        { title: 'Code', value: 'return <api.data>.profile' },
+        {
+          title: 'Code',
+          value:
+            'const data = <api.data>;\nreturn data.items.filter((item) => item.active).map((item) => item.id);',
+        },
       ],
     },
   ],
@@ -592,10 +544,10 @@ export const FUNCTION_RESHAPE_WORKFLOW: PreviewWorkflow = {
   ],
 }
 
-/** Function example: validate and clean input before writing it. */
+/** Function example: normalize input before writing it. */
 export const FUNCTION_VALIDATE_WORKFLOW: PreviewWorkflow = {
   id: 'function-validate',
-  name: 'Validate before write',
+  name: 'Normalize before write',
   blocks: [
     {
       id: 'start',
@@ -618,7 +570,11 @@ export const FUNCTION_VALIDATE_WORKFLOW: PreviewWorkflow = {
       position: { x: 320, y: 0 },
       rows: [
         { title: 'Language', value: 'JavaScript' },
-        { title: 'Code', value: 'return sanitize(<start.input>)' },
+        {
+          title: 'Code',
+          value:
+            'return { name: String(<start.input.name>).trim(), email: String(<start.input.email>).trim().toLowerCase() };',
+        },
       ],
     },
     {
@@ -638,6 +594,7 @@ export const FUNCTION_VALIDATE_WORKFLOW: PreviewWorkflow = {
       position: { x: 640, y: 0 },
       rows: [
         { title: 'Method', value: 'POST' },
+        { title: 'URL', value: 'https://api.example.com/contacts' },
         { title: 'Body', value: '<clean.result>' },
       ],
     },
@@ -673,7 +630,7 @@ export const ROUTER_TRIAGE_WORKFLOW: PreviewWorkflow = {
       position: { x: 320, y: 95 },
       rows: [
         { title: 'Context', value: '<start.input>' },
-        { title: 'Model', value: 'claude-sonnet-4-6' },
+        { title: 'Model', value: 'claude-sonnet-5-5' },
       ],
       branches: [
         { id: 'router-sales', label: 'Sales' },
@@ -780,7 +737,7 @@ export const RESPONSE_API_WORKFLOW: PreviewWorkflow = {
       bgColor: '#2F55FF',
       position: { x: 640, y: 0 },
       rows: [
-        { title: 'Data', value: '{ "answer": <agent.content> }' },
+        { title: 'Data', value: '{ "answer": "<agent.content>" }' },
         { title: 'Status', value: '200' },
       ],
     },
@@ -823,22 +780,28 @@ export const ROUTER_CLASSIFY_WORKFLOW: PreviewWorkflow = {
     {
       id: 'product',
       name: 'Product',
-      type: 'workflow',
+      type: 'workflow_input',
       typeLabel: 'Workflow',
       sentence: ['Run', { subBlockId: 'Workflow', noun: 'workflow' }],
       bgColor: '#6366F1',
       position: { x: 700, y: 0 },
-      rows: [{ title: 'Workflow', value: 'product-intake' }],
+      rows: [
+        { title: 'Workflow', value: 'product-intake' },
+        { title: 'Inputs', value: 'input = <start.input>' },
+      ],
     },
     {
       id: 'bug',
       name: 'Bug report',
-      type: 'workflow',
+      type: 'workflow_input',
       typeLabel: 'Workflow',
       sentence: ['Run', { subBlockId: 'Workflow', noun: 'workflow' }],
       bgColor: '#6366F1',
       position: { x: 700, y: 140 },
-      rows: [{ title: 'Workflow', value: 'bug-triage' }],
+      rows: [
+        { title: 'Workflow', value: 'bug-triage' },
+        { title: 'Inputs', value: 'input = <start.input>' },
+      ],
     },
   ],
   edges: [
@@ -848,130 +811,6 @@ export const ROUTER_CLASSIFY_WORKFLOW: PreviewWorkflow = {
   ],
 }
 
-/** Router example: qualify a lead into sales or self-serve. */
-export const ROUTER_LEAD_WORKFLOW: PreviewWorkflow = {
-  id: 'router-lead',
-  name: 'Qualify a lead',
-  blocks: [
-    {
-      id: 'start',
-      name: 'Start',
-      type: 'start_trigger',
-      typeLabel: 'Start',
-      sentence: ['Start the workflow', 'with', { subBlockId: 'Input' }],
-      bgColor: '#2FB3FF',
-      position: { x: 0, y: 50 },
-      hideTargetHandle: true,
-      rows: [{ title: 'Input', value: 'Lead' }],
-    },
-    {
-      id: 'router',
-      name: 'Router',
-      type: 'router',
-      typeLabel: 'Router',
-      bgColor: '#28C43F',
-      position: { x: 320, y: 50 },
-      rows: [{ title: 'Context', value: '<start.input>' }],
-      branches: [
-        { id: 'router-enterprise', label: 'Enterprise' },
-        { id: 'router-selfserve', label: 'Self-serve' },
-      ],
-    },
-    {
-      id: 'enterprise',
-      name: 'Enterprise',
-      type: 'agent',
-      typeLabel: 'Agent',
-      sentence: [
-        'Prompt',
-        { subBlockId: 'Model', noun: 'model' },
-        'with',
-        { subBlockId: 'Messages' },
-      ],
-      bgColor: '#33C482',
-      position: { x: 700, y: 0 },
-      rows: [{ title: 'Messages', value: 'Book a sales call' }],
-    },
-    {
-      id: 'selfserve',
-      name: 'Self-serve',
-      type: 'workflow',
-      typeLabel: 'Workflow',
-      sentence: ['Run', { subBlockId: 'Workflow', noun: 'workflow' }],
-      bgColor: '#6366F1',
-      position: { x: 700, y: 140 },
-      rows: [{ title: 'Workflow', value: 'onboarding' }],
-    },
-  ],
-  edges: [
-    { id: 'start-router', source: 'start', target: 'router' },
-    {
-      id: 'router-enterprise',
-      source: 'router',
-      target: 'enterprise',
-      sourceHandle: 'router-enterprise',
-    },
-    {
-      id: 'router-selfserve',
-      source: 'router',
-      target: 'selfserve',
-      sourceHandle: 'router-selfserve',
-    },
-  ],
-}
-
-/** Response example: acknowledge a webhook after processing it. */
-export const RESPONSE_WEBHOOK_WORKFLOW: PreviewWorkflow = {
-  id: 'response-webhook',
-  name: 'Acknowledge a webhook',
-  blocks: [
-    {
-      id: 'webhook',
-      name: 'Webhook',
-      type: 'webhook',
-      typeLabel: 'Webhook',
-      triggerMode: true,
-      sentence: ['Run when an HTTP request arrives'],
-      bgColor: '#10B981',
-      position: { x: 0, y: 0 },
-      hideTargetHandle: true,
-      rows: [{ title: 'Format', value: 'JSON' }],
-    },
-    {
-      id: 'process',
-      name: 'Process',
-      type: 'function',
-      typeLabel: 'Function',
-      sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
-      bgColor: '#FF402F',
-      position: { x: 320, y: 0 },
-      rows: [{ title: 'Code', value: 'save(<webhook.body>)' }],
-    },
-    {
-      id: 'ack',
-      name: 'Response',
-      type: 'response',
-      typeLabel: 'Response',
-      sentence: [
-        'Return',
-        { subBlockId: 'Data', noun: 'response' },
-        'with status',
-        { subBlockId: 'Status' },
-      ],
-      bgColor: '#2F55FF',
-      position: { x: 640, y: 0 },
-      rows: [
-        { title: 'Data', value: '{ "received": true }' },
-        { title: 'Status', value: '200' },
-      ],
-    },
-  ],
-  edges: [
-    { id: 'webhook-process', source: 'webhook', target: 'process' },
-    { id: 'process-ack', source: 'process', target: 'ack' },
-  ],
-}
-
 /** Response example: return a different status on each branch. */
 export const RESPONSE_ERROR_WORKFLOW: PreviewWorkflow = {
   id: 'response-error',
@@ -1003,7 +842,7 @@ export const RESPONSE_ERROR_WORKFLOW: PreviewWorkflow = {
     },
     {
       id: 'ok',
-      name: 'Response',
+      name: 'Success response',
       type: 'response',
       typeLabel: 'Response',
       sentence: [
@@ -1018,7 +857,7 @@ export const RESPONSE_ERROR_WORKFLOW: PreviewWorkflow = {
     },
     {
       id: 'bad',
-      name: 'Response',
+      name: 'Invalid response',
       type: 'response',
       typeLabel: 'Response',
       sentence: [
@@ -1042,50 +881,133 @@ export const RESPONSE_ERROR_WORKFLOW: PreviewWorkflow = {
 /** Variables example: count retries across attempts. */
 export const VARIABLES_RETRY_WORKFLOW: PreviewWorkflow = {
   id: 'variables-retry',
-  name: 'Count retries',
+  name: 'Count retry attempts',
   blocks: [
     {
-      id: 'api',
-      name: 'API',
+      id: 'attempts',
+      name: 'Retry attempts',
+      type: 'loop',
+      typeLabel: 'Loop',
+      bgColor: '#FAFAF9',
+      position: {
+        x: 300,
+        y: 0,
+      },
+      rows: [
+        {
+          title: 'Loop Type',
+          value: 'While Loop',
+        },
+        {
+          title: 'While Condition',
+          value: '<variable.retryCount> < 3',
+        },
+      ],
+      size: {
+        width: 1060,
+        height: 450,
+      },
+    },
+    {
+      id: 'attempt',
+      name: 'Attempt',
       type: 'api',
       typeLabel: 'API',
-      sentence: [
-        'Send',
-        { subBlockId: 'Method', noun: 'method' },
-        'request to',
-        { subBlockId: 'URL', noun: 'URL' },
-      ],
       bgColor: '#2F55FF',
-      position: { x: 0, y: 0 },
-      rows: [{ title: 'Method', value: 'GET' }],
+      position: {
+        x: 70,
+        y: 90,
+      },
+      rows: [
+        {
+          title: 'Method',
+          value: 'GET',
+        },
+        {
+          title: 'URL',
+          value: 'https://api.example.com/job',
+        },
+      ],
+      parentId: 'attempts',
     },
     {
-      id: 'vars',
-      name: 'Variables',
+      id: 'done',
+      name: 'Finish retries',
       type: 'variables',
       typeLabel: 'Variables',
-      sentence: ['Set', { subBlockId: 'Set', noun: 'variables' }],
       bgColor: '#8B5CF6',
-      position: { x: 320, y: 0 },
-      rows: [{ title: 'Set', value: 'retryCount + 1' }],
+      position: {
+        x: 700,
+        y: 30,
+      },
+      rows: [
+        {
+          title: 'Variable Assignments',
+          value: 'retryCount = 3',
+        },
+      ],
+      parentId: 'attempts',
     },
     {
-      id: 'condition',
-      name: 'Condition',
-      type: 'condition',
-      typeLabel: 'Condition',
-      bgColor: '#FF752F',
-      position: { x: 640, y: 0 },
-      rows: [],
-      branches: [
-        { id: 'condition-if', label: 'If', value: '<variable.retryCount> < 3' },
-        { id: 'condition-else', label: 'else' },
+      id: 'increment',
+      name: 'Increment',
+      type: 'function',
+      typeLabel: 'Function',
+      bgColor: '#FF402F',
+      position: {
+        x: 380,
+        y: 230,
+      },
+      rows: [
+        {
+          title: 'Code',
+          value: 'return <variable.retryCount> + 1;',
+        },
+      ],
+      parentId: 'attempts',
+    },
+    {
+      id: 'assign',
+      name: 'Update counter',
+      type: 'variables',
+      typeLabel: 'Variables',
+      bgColor: '#8B5CF6',
+      position: {
+        x: 700,
+        y: 230,
+      },
+      rows: [
+        {
+          title: 'Variable Assignments',
+          value: 'retryCount = <increment.result>',
+        },
       ],
+      parentId: 'attempts',
     },
   ],
   edges: [
-    { id: 'api-vars', source: 'api', target: 'vars' },
-    { id: 'vars-condition', source: 'vars', target: 'condition' },
+    {
+      id: 'attempts-attempt',
+      source: 'attempts',
+      target: 'attempt',
+      sourceHandle: 'loop-start-source',
+    },
+    {
+      id: 'attempt-done',
+      source: 'attempt',
+      target: 'done',
+    },
+    {
+      id: 'attempt-increment',
+      source: 'attempt',
+      target: 'increment',
+      sourceHandle: 'error',
+    },
+    {
+      id: 'increment-assign',
+      source: 'increment',
+      target: 'assign',
+    },
   ],
 }
 
@@ -1107,7 +1029,10 @@ export const VARIABLES_CONFIG_WORKFLOW: PreviewWorkflow = {
       ],
       bgColor: '#2F55FF',
       position: { x: 0, y: 0 },
-      rows: [{ title: 'URL', value: 'api.example.com/profile' }],
+      rows: [
+        { title: 'URL', value: 'https://api.example.com/profile' },
+        { title: 'Method', value: 'GET' },
+      ],
     },
     {
       id: 'vars',
@@ -1117,7 +1042,7 @@ export const VARIABLES_CONFIG_WORKFLOW: PreviewWorkflow = {
       sentence: ['Set', { subBlockId: 'Set', noun: 'variables' }],
       bgColor: '#8B5CF6',
       position: { x: 320, y: 0 },
-      rows: [{ title: 'Set', value: 'userId, userTier' }],
+      rows: [{ title: 'Set', value: 'userId = <api.data.id>, userTier = <api.data.tier>' }],
     },
     {
       id: 'agent',
@@ -1227,6 +1152,7 @@ export const WAIT_FOLLOWUP_WORKFLOW: PreviewWorkflow = {
       rows: [
         { title: 'Amount', value: '2' },
         { title: 'Unit', value: 'Days' },
+        { title: 'Async', value: 'On' },
       ],
     },
     {
@@ -1286,7 +1212,7 @@ export const EVALUATOR_GATE_WORKFLOW: PreviewWorkflow = {
       position: { x: 320, y: 0 },
       rows: [
         { title: 'Metrics', value: 'Accuracy, Clarity' },
-        { title: 'Model', value: 'claude-sonnet-4-6' },
+        { title: 'Model', value: 'claude-sonnet-5-5' },
       ],
     },
     {
@@ -1309,7 +1235,7 @@ export const EVALUATOR_GATE_WORKFLOW: PreviewWorkflow = {
   ],
 }
 
-/** Credential example: select one Google account and reuse it across blocks. */
+/** Credential example: select one Slack account and reuse it across compatible actions. */
 export const CREDENTIAL_SHARE_WORKFLOW: PreviewWorkflow = {
   id: 'credential-share',
   name: 'Share a credential',
@@ -1324,14 +1250,14 @@ export const CREDENTIAL_SHARE_WORKFLOW: PreviewWorkflow = {
       position: { x: 0, y: 100 },
       rows: [
         { title: 'Operation', value: 'Select Credential' },
-        { title: 'Account', value: 'Google' },
+        { title: 'Account', value: 'Slack' },
       ],
     },
     {
-      id: 'gmail',
-      name: 'Gmail',
-      type: 'gmail',
-      typeLabel: 'Gmail',
+      id: 'send',
+      name: 'Send message',
+      type: 'slack',
+      typeLabel: 'Slack',
       isIntegration: true,
       sentence: ['Use account', { subBlockId: 'Account', noun: 'account' }],
       bgColor: '#FFFFFF',
@@ -1339,10 +1265,10 @@ export const CREDENTIAL_SHARE_WORKFLOW: PreviewWorkflow = {
       rows: [{ title: 'Account', value: '<credential.credentialId>' }],
     },
     {
-      id: 'drive',
-      name: 'Drive',
-      type: 'google_drive',
-      typeLabel: 'Google Drive',
+      id: 'read',
+      name: 'Read channel',
+      type: 'slack',
+      typeLabel: 'Slack',
       isIntegration: true,
       sentence: ['Use account', { subBlockId: 'Account', noun: 'account' }],
       bgColor: '#FFFFFF',
@@ -1350,10 +1276,10 @@ export const CREDENTIAL_SHARE_WORKFLOW: PreviewWorkflow = {
       rows: [{ title: 'Account', value: '<credential.credentialId>' }],
     },
     {
-      id: 'calendar',
-      name: 'Calendar',
-      type: 'google_calendar',
-      typeLabel: 'Google Calendar',
+      id: 'reply',
+      name: 'Reply',
+      type: 'slack',
+      typeLabel: 'Slack',
       isIntegration: true,
       sentence: ['Use account', { subBlockId: 'Account', noun: 'account' }],
       bgColor: '#FFFFFF',
@@ -1362,75 +1288,150 @@ export const CREDENTIAL_SHARE_WORKFLOW: PreviewWorkflow = {
     },
   ],
   edges: [
-    { id: 'credential-gmail', source: 'credential', target: 'gmail' },
-    { id: 'credential-drive', source: 'credential', target: 'drive' },
-    { id: 'credential-calendar', source: 'credential', target: 'calendar' },
+    { id: 'credential-gmail', source: 'credential', target: 'send' },
+    { id: 'credential-drive', source: 'credential', target: 'read' },
+    { id: 'credential-calendar', source: 'credential', target: 'reply' },
   ],
 }
 
 /** Credential example: pick a production or staging account at runtime. */
 export const CREDENTIAL_ROUTE_WORKFLOW: PreviewWorkflow = {
   id: 'credential-route',
-  name: 'Route to an account',
+  name: 'Choose a Slack account',
   blocks: [
-    {
-      id: 'pick',
-      name: 'Pick account',
-      type: 'agent',
-      typeLabel: 'Agent',
-      sentence: [
-        'Prompt',
-        { subBlockId: 'Model', noun: 'model' },
-        'with',
-        { subBlockId: 'Messages' },
-      ],
-      bgColor: '#33C482',
-      position: { x: 0, y: 60 },
-      rows: [{ title: 'Messages', value: 'Production or staging?' }],
-    },
     {
       id: 'condition',
-      name: 'Condition',
+      name: 'Choose account',
       type: 'condition',
       typeLabel: 'Condition',
       bgColor: '#FF752F',
-      position: { x: 330, y: 60 },
+      position: {
+        x: 300,
+        y: 60,
+      },
       rows: [],
       branches: [
-        { id: 'condition-if', label: 'If', value: "<variable.env> === 'prod'" },
-        { id: 'condition-else', label: 'else' },
+        {
+          id: 'condition-if',
+          label: 'If',
+          value: "<variable.env> === 'prod'",
+        },
+        {
+          id: 'condition-else',
+          label: 'else',
+        },
       ],
     },
     {
       id: 'prod',
-      name: 'Credential',
+      name: 'Production account',
       type: 'credential',
       typeLabel: 'Credential',
-      sentence: ['Select an OAuth credential', 'for', { subBlockId: 'Account' }],
       bgColor: '#6366F1',
-      position: { x: 700, y: 0 },
-      rows: [{ title: 'Account', value: 'Prod Slack' }],
+      position: {
+        x: 610,
+        y: 0,
+      },
+      rows: [
+        {
+          title: 'Operation',
+          value: 'Select Credential',
+        },
+        {
+          title: 'Credential',
+          value: 'Prod Slack',
+        },
+      ],
     },
     {
       id: 'staging',
-      name: 'Credential',
+      name: 'Staging account',
       type: 'credential',
       typeLabel: 'Credential',
-      sentence: ['Select an OAuth credential', 'for', { subBlockId: 'Account' }],
       bgColor: '#6366F1',
-      position: { x: 700, y: 140 },
-      rows: [{ title: 'Account', value: 'Staging Slack' }],
+      position: {
+        x: 610,
+        y: 180,
+      },
+      rows: [
+        {
+          title: 'Operation',
+          value: 'Select Credential',
+        },
+        {
+          title: 'Credential',
+          value: 'Staging Slack',
+        },
+      ],
+    },
+    {
+      id: 'postprod',
+      name: 'Production message',
+      type: 'slack',
+      typeLabel: 'Slack',
+      bgColor: '#FFFFFF',
+      position: {
+        x: 930,
+        y: 0,
+      },
+      rows: [
+        {
+          title: 'Operation',
+          value: 'Send Message',
+        },
+        {
+          title: 'Credential',
+          value: '<productionaccount.credentialId>',
+        },
+      ],
+      isIntegration: true,
+    },
+    {
+      id: 'poststaging',
+      name: 'Staging message',
+      type: 'slack',
+      typeLabel: 'Slack',
+      bgColor: '#FFFFFF',
+      position: {
+        x: 930,
+        y: 180,
+      },
+      rows: [
+        {
+          title: 'Operation',
+          value: 'Send Message',
+        },
+        {
+          title: 'Credential',
+          value: '<stagingaccount.credentialId>',
+        },
+      ],
+      isIntegration: true,
     },
   ],
   edges: [
-    { id: 'pick-condition', source: 'pick', target: 'condition' },
-    { id: 'condition-prod', source: 'condition', target: 'prod', sourceHandle: 'condition-if' },
+    {
+      id: 'condition-prod',
+      source: 'condition',
+      target: 'prod',
+      sourceHandle: 'condition-if',
+    },
     {
       id: 'condition-staging',
       source: 'condition',
       target: 'staging',
       sourceHandle: 'condition-else',
     },
+    {
+      id: 'prod-postprod',
+      source: 'prod',
+      target: 'postprod',
+    },
+    {
+      id: 'staging-poststaging',
+      source: 'staging',
+      target: 'poststaging',
+    },
   ],
 }
 
@@ -1467,7 +1468,10 @@ export const GUARDRAILS_JSON_WORKFLOW: PreviewWorkflow = {
       sentence: ['Validate content using', { subBlockId: 'Validation', noun: 'validation type' }],
       bgColor: '#3D642D',
       position: { x: 320, y: 0 },
-      rows: [{ title: 'Validation', value: 'Valid JSON' }],
+      rows: [
+        { title: 'Content to Validate', value: '<agent.content>' },
+        { title: 'Validation', value: 'Valid JSON' },
+      ],
     },
     {
       ...GUARDRAILS_GATE,
@@ -1477,10 +1481,37 @@ export const GUARDRAILS_JSON_WORKFLOW: PreviewWorkflow = {
         { id: 'condition-else', label: 'else' },
       ],
     },
+    {
+      id: 'parse',
+      name: 'Parse',
+      type: 'function',
+      typeLabel: 'Function',
+      sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
+      bgColor: '#FF402F',
+      position: { x: 960, y: -60 },
+      rows: [{ title: 'Code', value: 'return JSON.parse(<agent.content>);' }],
+    },
+    {
+      id: 'reject',
+      name: 'Reject',
+      type: 'function',
+      typeLabel: 'Function',
+      sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
+      bgColor: '#FF402F',
+      position: { x: 960, y: 140 },
+      rows: [{ title: 'Code', value: 'return { valid: false, error: <guardrails.error> };' }],
+    },
   ],
   edges: [
     { id: 'start-guardrails', source: 'start', target: 'guardrails' },
     { id: 'guardrails-condition', source: 'guardrails', target: 'condition' },
+    { id: 'condition-parse', source: 'condition', target: 'parse', sourceHandle: 'condition-if' },
+    {
+      id: 'condition-reject',
+      source: 'condition',
+      target: 'reject',
+      sourceHandle: 'condition-else',
+    },
   ],
 }
 
@@ -1504,8 +1535,10 @@ export const GUARDRAILS_HALLUCINATION_WORKFLOW: PreviewWorkflow = {
       bgColor: '#3D642D',
       position: { x: 320, y: 0 },
       rows: [
+        { title: 'Content to Validate', value: '<agent.content>' },
         { title: 'Validation', value: 'Hallucination' },
         { title: 'Knowledge Base', value: 'docs' },
+        { title: 'Model', value: 'claude-sonnet-5-5' },
       ],
     },
     {
@@ -1548,8 +1581,9 @@ export const GUARDRAILS_PII_WORKFLOW: PreviewWorkflow = {
       bgColor: '#3D642D',
       position: { x: 320, y: 0 },
       rows: [
+        { title: 'Content to Validate', value: '<start.input>' },
         { title: 'Validation', value: 'PII Detection' },
-        { title: 'Action', value: 'Block' },
+        { title: 'Action', value: 'Block Request' },
       ],
     },
     {
@@ -1570,34 +1604,67 @@ export const GUARDRAILS_PII_WORKFLOW: PreviewWorkflow = {
 /** HITL example: a human approves AI content before it ships. */
 export const HITL_APPROVAL_WORKFLOW: PreviewWorkflow = {
   id: 'hitl-approval',
-  name: 'Approve before publish',
+  name: 'Approve before publishing',
   blocks: [
     {
       id: 'draft',
       name: 'Draft',
       type: 'agent',
       typeLabel: 'Agent',
-      sentence: [
-        'Prompt',
-        { subBlockId: 'Model', noun: 'model' },
-        'with',
-        { subBlockId: 'Messages' },
-      ],
       bgColor: '#33C482',
-      position: { x: 0, y: 0 },
-      rows: [{ title: 'Messages', value: 'Write the post' }],
+      position: {
+        x: 0,
+        y: 70,
+      },
+      rows: [
+        {
+          title: 'Messages',
+          value: 'Write the post',
+        },
+      ],
     },
     {
       id: 'approve',
-      name: 'Human in the Loop',
-      type: 'human_in_the_loop',
+      name: 'Approval',
+      type: 'human_in_the_loop_v2',
       typeLabel: 'Human',
-      sentence: ['Pause execution until a human responds'],
       bgColor: '#10B981',
-      position: { x: 300, y: 0 },
+      position: {
+        x: 300,
+        y: 70,
+      },
       rows: [
-        { title: 'Display', value: '<draft.content>' },
-        { title: 'Resume', value: 'approved' },
+        {
+          title: 'Display Data',
+          value: '<draft.content>',
+        },
+        {
+          title: 'Resume Form',
+          value: 'approved (boolean)',
+        },
+      ],
+    },
+    {
+      id: 'check',
+      name: 'Check approval',
+      type: 'condition',
+      typeLabel: 'Condition',
+      bgColor: '#FF752F',
+      position: {
+        x: 620,
+        y: 70,
+      },
+      rows: [],
+      branches: [
+        {
+          id: 'condition-if',
+          label: 'If',
+          value: '<approval.approved> === true',
+        },
+        {
+          id: 'condition-else',
+          label: 'else',
+        },
       ],
     },
     {
@@ -1605,20 +1672,63 @@ export const HITL_APPROVAL_WORKFLOW: PreviewWorkflow = {
       name: 'Publish',
       type: 'api',
       typeLabel: 'API',
-      sentence: [
-        'Send',
-        { subBlockId: 'Method', noun: 'method' },
-        'request to',
-        { subBlockId: 'URL', noun: 'URL' },
-      ],
       bgColor: '#2F55FF',
-      position: { x: 640, y: 0 },
-      rows: [{ title: 'Method', value: 'POST' }],
+      position: {
+        x: 950,
+        y: 0,
+      },
+      rows: [
+        {
+          title: 'Method',
+          value: 'POST',
+        },
+        {
+          title: 'Body',
+          value: '{"content":"<draft.content>"}',
+        },
+      ],
+    },
+    {
+      id: 'reject',
+      name: 'Rejected',
+      type: 'function',
+      typeLabel: 'Function',
+      bgColor: '#FF402F',
+      position: {
+        x: 950,
+        y: 180,
+      },
+      rows: [
+        {
+          title: 'Code',
+          value: 'return { approved: false };',
+        },
+      ],
     },
   ],
   edges: [
-    { id: 'draft-approve', source: 'draft', target: 'approve' },
-    { id: 'approve-publish', source: 'approve', target: 'publish' },
+    {
+      id: 'draft-approve',
+      source: 'draft',
+      target: 'approve',
+    },
+    {
+      id: 'approve-check',
+      source: 'approve',
+      target: 'check',
+    },
+    {
+      id: 'check-publish',
+      source: 'check',
+      target: 'publish',
+      sourceHandle: 'condition-if',
+    },
+    {
+      id: 'check-reject',
+      source: 'check',
+      target: 'reject',
+      sourceHandle: 'condition-else',
+    },
   ],
 }
 
@@ -1628,55 +1738,202 @@ export const HITL_MULTISTAGE_WORKFLOW: PreviewWorkflow = {
   name: 'Two-stage approval',
   blocks: [
     {
-      id: 'agent',
-      name: 'Agent',
+      id: 'draft',
+      name: 'Draft',
       type: 'agent',
       typeLabel: 'Agent',
-      sentence: [
-        'Prompt',
-        { subBlockId: 'Model', noun: 'model' },
-        'with',
-        { subBlockId: 'Messages' },
-      ],
       bgColor: '#33C482',
-      position: { x: 0, y: 0 },
-      rows: [{ title: 'Messages', value: 'Draft the change' }],
+      position: {
+        x: 0,
+        y: 70,
+      },
+      rows: [
+        {
+          title: 'Messages',
+          value: 'Write the post',
+        },
+      ],
     },
     {
       id: 'manager',
       name: 'Manager',
-      type: 'human_in_the_loop',
+      type: 'human_in_the_loop_v2',
       typeLabel: 'Human',
-      sentence: ['Pause execution until a human responds'],
       bgColor: '#10B981',
-      position: { x: 280, y: 0 },
-      rows: [{ title: 'Resume', value: 'approved' }],
+      position: {
+        x: 300,
+        y: 90,
+      },
+      rows: [
+        {
+          title: 'Display Data',
+          value: '<draft.content>',
+        },
+        {
+          title: 'Resume Form',
+          value: 'approved (boolean)',
+        },
+      ],
+    },
+    {
+      id: 'managergate',
+      name: 'Check manager',
+      type: 'condition',
+      typeLabel: 'Condition',
+      bgColor: '#FF752F',
+      position: {
+        x: 620,
+        y: 90,
+      },
+      rows: [],
+      branches: [
+        {
+          id: 'condition-if',
+          label: 'If',
+          value: '<manager.approved> === true',
+        },
+        {
+          id: 'condition-else',
+          label: 'else',
+        },
+      ],
     },
     {
       id: 'director',
       name: 'Director',
-      type: 'human_in_the_loop',
+      type: 'human_in_the_loop_v2',
       typeLabel: 'Human',
-      sentence: ['Pause execution until a human responds'],
       bgColor: '#10B981',
-      position: { x: 580, y: 0 },
-      rows: [{ title: 'Resume', value: 'approved' }],
+      position: {
+        x: 950,
+        y: 0,
+      },
+      rows: [
+        {
+          title: 'Display Data',
+          value: '<draft.content>',
+        },
+        {
+          title: 'Resume Form',
+          value: 'approved (boolean)',
+        },
+      ],
+    },
+    {
+      id: 'directorgate',
+      name: 'Check director',
+      type: 'condition',
+      typeLabel: 'Condition',
+      bgColor: '#FF752F',
+      position: {
+        x: 1280,
+        y: 0,
+      },
+      rows: [],
+      branches: [
+        {
+          id: 'condition-if',
+          label: 'If',
+          value: '<director.approved> === true',
+        },
+        {
+          id: 'condition-else',
+          label: 'else',
+        },
+      ],
     },
     {
       id: 'execute',
       name: 'Execute',
       type: 'function',
       typeLabel: 'Function',
-      sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
       bgColor: '#FF402F',
-      position: { x: 880, y: 0 },
-      rows: [{ title: 'Code', value: 'apply()' }],
+      position: {
+        x: 1610,
+        y: -80,
+      },
+      rows: [
+        {
+          title: 'Code',
+          value: 'return { approved: true, content: <draft.content> };',
+        },
+      ],
+    },
+    {
+      id: 'managerreject',
+      name: 'Manager rejected',
+      type: 'function',
+      typeLabel: 'Function',
+      bgColor: '#FF402F',
+      position: {
+        x: 950,
+        y: 230,
+      },
+      rows: [
+        {
+          title: 'Code',
+          value: 'return { approved: false, reviewer: "manager" };',
+        },
+      ],
+    },
+    {
+      id: 'directorreject',
+      name: 'Director rejected',
+      type: 'function',
+      typeLabel: 'Function',
+      bgColor: '#FF402F',
+      position: {
+        x: 1610,
+        y: 100,
+      },
+      rows: [
+        {
+          title: 'Code',
+          value: 'return { approved: false, reviewer: "director" };',
+        },
+      ],
     },
   ],
   edges: [
-    { id: 'agent-manager', source: 'agent', target: 'manager' },
-    { id: 'manager-director', source: 'manager', target: 'director' },
-    { id: 'director-execute', source: 'director', target: 'execute' },
+    {
+      id: 'draft-manager',
+      source: 'draft',
+      target: 'manager',
+    },
+    {
+      id: 'manager-managergate',
+      source: 'manager',
+      target: 'managergate',
+    },
+    {
+      id: 'managergate-director',
+      source: 'managergate',
+      target: 'director',
+      sourceHandle: 'condition-if',
+    },
+    {
+      id: 'managergate-managerreject',
+      source: 'managergate',
+      target: 'managerreject',
+      sourceHandle: 'condition-else',
+    },
+    {
+      id: 'director-directorgate',
+      source: 'director',
+      target: 'directorgate',
+    },
+    {
+      id: 'directorgate-execute',
+      source: 'directorgate',
+      target: 'execute',
+      sourceHandle: 'condition-if',
+    },
+    {
+      id: 'directorgate-directorreject',
+      source: 'directorgate',
+      target: 'directorreject',
+      sourceHandle: 'condition-else',
+    },
   ],
 }
 
@@ -1702,13 +1959,16 @@ export const HITL_VALIDATE_WORKFLOW: PreviewWorkflow = {
     },
     {
       id: 'validate',
-      name: 'Human in the Loop',
-      type: 'human_in_the_loop',
+      name: 'Review data',
+      type: 'human_in_the_loop_v2',
       typeLabel: 'Human',
       sentence: ['Pause execution until a human responds'],
       bgColor: '#10B981',
       position: { x: 300, y: 0 },
-      rows: [{ title: 'Display', value: '<extract.content>' }],
+      rows: [
+        { title: 'Display Data', value: '<extract.content>' },
+        { title: 'Resume Form', value: 'corrected (object)' },
+      ],
     },
     {
       id: 'process',
@@ -1718,7 +1978,7 @@ export const HITL_VALIDATE_WORKFLOW: PreviewWorkflow = {
       sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
       bgColor: '#FF402F',
       position: { x: 640, y: 0 },
-      rows: [{ title: 'Code', value: 'process()' }],
+      rows: [{ title: 'Code', value: 'return <reviewdata.corrected>;' }],
     },
   ],
   edges: [
@@ -1755,7 +2015,7 @@ export const WEBHOOK_NOTIFY_WORKFLOW: PreviewWorkflow = {
       sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
       bgColor: '#FF402F',
       position: { x: 320, y: 0 },
-      rows: [{ title: 'Code', value: 'toSlackBlocks(<agent.content>)' }],
+      rows: [{ title: 'Code', value: 'return { text: <agent.content> };' }],
     },
     {
       id: 'webhook',
@@ -1770,7 +2030,10 @@ export const WEBHOOK_NOTIFY_WORKFLOW: PreviewWorkflow = {
       ],
       bgColor: '#10B981',
       position: { x: 640, y: 0 },
-      rows: [{ title: 'URL', value: 'hooks.slack.com/…' }],
+      rows: [
+        { title: 'URL', value: 'https://hooks.slack.com/services/YOUR/WEBHOOK/SECRET' },
+        { title: 'Payload', value: '<format.result>' },
+      ],
     },
   ],
   edges: [
@@ -1821,12 +2084,17 @@ export const WEBHOOK_TRIGGER_WORKFLOW: PreviewWorkflow = {
       ],
       bgColor: '#10B981',
       position: { x: 640, y: 0 },
-      rows: [{ title: 'URL', value: 'api.partner.com/hook' }],
+      rows: [{ title: 'URL', value: 'https://api.example.com/hook' }],
     },
   ],
   edges: [
     { id: 'start-condition', source: 'start', target: 'condition' },
-    { id: 'condition-webhook', source: 'condition', target: 'webhook' },
+    {
+      id: 'condition-webhook',
+      source: 'condition',
+      target: 'webhook',
+      sourceHandle: 'condition-if',
+    },
   ],
 }
 
@@ -1849,19 +2117,19 @@ export const WORKFLOW_CALL_WORKFLOW: PreviewWorkflow = {
     {
       id: 'child',
       name: 'Workflow',
-      type: 'workflow',
+      type: 'workflow_input',
       typeLabel: 'Workflow',
       sentence: [
         'Run',
         { subBlockId: 'Workflow', noun: 'workflow' },
         ', passing',
-        { subBlockId: 'Input' },
+        { subBlockId: 'Inputs' },
       ],
       bgColor: '#6366F1',
       position: { x: 320, y: 0 },
       rows: [
         { title: 'Workflow', value: 'enrich-lead' },
-        { title: 'Input', value: '<start.input>' },
+        { title: 'Inputs', value: 'input = <start.input>' },
       ],
     },
     {
@@ -1900,17 +2168,20 @@ export const LOOP_WORKFLOW: PreviewWorkflow = {
       bgColor: '#2FB3FF',
       position: { x: 0, y: 95 },
       hideTargetHandle: true,
-      rows: [{ title: 'Input', value: 'Reviews' }],
+      rows: [{ title: 'Input', value: 'reviews (array)' }],
     },
     {
       id: 'loop',
-      name: 'Loop',
+      name: 'Process Reviews',
       type: 'loop',
       typeLabel: 'Loop',
       bgColor: '#FAFAF9',
       position: { x: 340, y: 30 },
       size: { width: 480, height: 300 },
-      rows: [],
+      rows: [
+        { title: 'Loop Type', value: 'For Each' },
+        { title: 'Collection Items', value: '<start.reviews>' },
+      ],
     },
     {
       id: 'score',
@@ -1941,7 +2212,7 @@ export const LOOP_WORKFLOW: PreviewWorkflow = {
       ],
       bgColor: '#33C482',
       position: { x: 910, y: 95 },
-      rows: [{ title: 'Messages', value: 'Summarize <loop.results>' }],
+      rows: [{ title: 'Messages', value: 'Summarize <processreviews.results>' }],
     },
   ],
   edges: [
@@ -1965,17 +2236,21 @@ export const PARALLEL_WORKFLOW: PreviewWorkflow = {
       bgColor: '#2FB3FF',
       position: { x: 0, y: 95 },
       hideTargetHandle: true,
-      rows: [{ title: 'Input', value: 'Tasks' }],
+      rows: [{ title: 'Input', value: 'tasks (array)' }],
     },
     {
       id: 'parallel',
-      name: 'Parallel',
+      name: 'Process Tasks',
       type: 'parallel',
       typeLabel: 'Parallel',
       bgColor: '#1D1C1A',
       position: { x: 340, y: 30 },
       size: { width: 480, height: 300 },
-      rows: [],
+      rows: [
+        { title: 'Parallel Type', value: 'Parallel Each' },
+        { title: 'Parallel Items', value: '<start.tasks>' },
+        { title: 'Parallel Batch Size', value: '20' },
+      ],
     },
     {
       id: 'call',
@@ -1991,7 +2266,7 @@ export const PARALLEL_WORKFLOW: PreviewWorkflow = {
       bgColor: '#2F55FF',
       position: { x: 150, y: 64 },
       parentId: 'parallel',
-      rows: [{ title: 'URL', value: '/tasks/<parallel.currentItem>' }],
+      rows: [{ title: 'URL', value: 'https://api.example.com/tasks/<parallel.currentItem>' }],
     },
     {
       id: 'aggregate',
@@ -2001,7 +2276,12 @@ export const PARALLEL_WORKFLOW: PreviewWorkflow = {
       sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
       bgColor: '#FF402F',
       position: { x: 910, y: 95 },
-      rows: [{ title: 'Code', value: 'merge(<parallel.results>)' }],
+      rows: [
+        {
+          title: 'Code',
+          value: 'return <processtasks.results>.flat().map((output) => output.data);',
+        },
+      ],
     },
   ],
   edges: [
@@ -2034,7 +2314,7 @@ export const BUILD_AGENT_WORKFLOW: PreviewWorkflow = {
     },
     {
       id: 'agent',
-      name: 'Score lead',
+      name: 'Agent',
       type: 'agent',
       typeLabel: 'Agent',
       sentence: [
@@ -2048,8 +2328,13 @@ export const BUILD_AGENT_WORKFLOW: PreviewWorkflow = {
       bgColor: '#33C482',
       position: { x: 320, y: 0 },
       rows: [
-        { title: 'Messages', value: 'Score <start.input>' },
-        { title: 'Model', value: 'claude-sonnet-4-6' },
+        { title: 'Messages', value: 'Score <start.input> from 0 to 100.' },
+        {
+          title: 'Response Format',
+          value:
+            '{"name":"lead_score","schema":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100}},"required":["score"],"additionalProperties":false}}',
+        },
+        { title: 'Model', value: 'claude-sonnet-5-5' },
       ],
       tools: [
         { type: 'knowledge', name: 'Knowledge', bgColor: '#00B0B0' },
@@ -2083,7 +2368,7 @@ export const FILE_SUMMARY_WORKFLOW: PreviewWorkflow = {
       name: 'File',
       type: 'file',
       typeLabel: 'File',
-      sentence: ['Parse', { subBlockId: 'File', noun: 'file' }],
+      sentence: ['Read', { subBlockId: 'File', noun: 'file' }],
       bgColor: '#40916C',
       position: { x: 0, y: 0 },
       rows: [
@@ -2111,7 +2396,7 @@ export const FILE_SUMMARY_WORKFLOW: PreviewWorkflow = {
     },
     {
       id: 'write',
-      name: 'File',
+      name: 'Save summary',
       type: 'file',
       typeLabel: 'File',
       sentence: ['Create', { subBlockId: 'File Name', noun: 'file name' }],
@@ -2120,6 +2405,7 @@ export const FILE_SUMMARY_WORKFLOW: PreviewWorkflow = {
       rows: [
         { title: 'Operation', value: 'Write' },
         { title: 'File Name', value: 'summary.md' },
+        { title: 'Content', value: '<agent.content>' },
       ],
     },
   ],
@@ -2131,8 +2417,8 @@ export const FILE_SUMMARY_WORKFLOW: PreviewWorkflow = {
 
 /**
  * The running example of the choosing guide: a lead scorer combining a
- * workflow-as-tool (enrich), a deterministic Function, an Agent with tools,
- * and a deterministic Google Sheets append.
+ * fixed Workflow step (Enrich), a Function, an Agent with tools,
+ * and a fixed Google Sheets append.
  */
 export const LEAD_SCORER_WORKFLOW: PreviewWorkflow = {
   id: 'lead-scorer',
@@ -2152,12 +2438,15 @@ export const LEAD_SCORER_WORKFLOW: PreviewWorkflow = {
     {
       id: 'enrich',
       name: 'Enrich',
-      type: 'workflow',
+      type: 'workflow_input',
       typeLabel: 'Workflow',
       sentence: ['Run', { subBlockId: 'Workflow', noun: 'workflow' }],
       bgColor: '#6366F1',
       position: { x: 290, y: 0 },
-      rows: [{ title: 'Workflow', value: 'enrich-lead' }],
+      rows: [
+        { title: 'Workflow', value: 'enrich-lead' },
+        { title: 'Inputs', value: 'input = <start.input>' },
+      ],
     },
     {
       id: 'reshape',
@@ -2167,7 +2456,13 @@ export const LEAD_SCORER_WORKFLOW: PreviewWorkflow = {
       sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
       bgColor: '#FF402F',
       position: { x: 580, y: 0 },
-      rows: [{ title: 'Code', value: 'return fields(<enrich.result>)' }],
+      rows: [
+        {
+          title: 'Code',
+          value:
+            'const lead = <enrich.result>; return { company: lead.company, domain: lead.domain };',
+        },
+      ],
     },
     {
       id: 'score',
@@ -2185,14 +2480,19 @@ export const LEAD_SCORER_WORKFLOW: PreviewWorkflow = {
       bgColor: '#33C482',
       position: { x: 870, y: 0 },
       rows: [
-        { title: 'Messages', value: 'Score <reshape.result>' },
-        { title: 'Model', value: 'claude-sonnet-4-6' },
+        { title: 'Messages', value: 'Score <reshape.result> from 0 to 100.' },
+        {
+          title: 'Response Format',
+          value:
+            '{"name":"lead_score","schema":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100}},"required":["score"],"additionalProperties":false}}',
+        },
+        { title: 'Model', value: 'claude-sonnet-5-5' },
       ],
       tools: [
         { type: 'exa', name: 'Search', bgColor: '#1F40ED' },
         { type: 'gmail', name: 'Send Email', bgColor: '#E0E0E0' },
         { type: 'hubspot', name: 'CRM', bgColor: '#FF7A59' },
-        { type: 'workflow', name: 'Deep Enrich', bgColor: '#6366F1' },
+        { type: 'workflow_input', name: 'Deep Enrich', bgColor: '#6366F1' },
       ],
     },
     {
@@ -2242,7 +2542,7 @@ export const CONCURRENCY_WORKFLOW: PreviewWorkflow = {
       sentence: ['Prompt', { subBlockId: 'Model', noun: 'model' }],
       bgColor: '#33C482',
       position: { x: 360, y: 0 },
-      rows: [{ title: 'Model', value: 'claude-sonnet-4-6' }],
+      rows: [{ title: 'Model', value: 'claude-sonnet-5-5' }],
     },
     {
       id: 'research',
@@ -2252,7 +2552,7 @@ export const CONCURRENCY_WORKFLOW: PreviewWorkflow = {
       sentence: ['Prompt', { subBlockId: 'Model', noun: 'model' }],
       bgColor: '#33C482',
       position: { x: 360, y: 150 },
-      rows: [{ title: 'Model', value: 'claude-sonnet-4-6' }],
+      rows: [{ title: 'Model', value: 'claude-sonnet-5-5' }],
     },
   ],
   edges: [
@@ -2288,7 +2588,7 @@ export const COMBINATION_WORKFLOW: PreviewWorkflow = {
       sentence: ['Prompt', { subBlockId: 'Model', noun: 'model' }],
       bgColor: '#33C482',
       position: { x: 360, y: 0 },
-      rows: [{ title: 'Model', value: 'claude-sonnet-4-6' }],
+      rows: [{ title: 'Model', value: 'claude-sonnet-5-5' }],
     },
     {
       id: 'research',
@@ -2298,7 +2598,7 @@ export const COMBINATION_WORKFLOW: PreviewWorkflow = {
       sentence: ['Prompt', { subBlockId: 'Model', noun: 'model' }],
       bgColor: '#33C482',
       position: { x: 360, y: 150 },
-      rows: [{ title: 'Model', value: 'claude-sonnet-4-6' }],
+      rows: [{ title: 'Model', value: 'claude-sonnet-5-5' }],
     },
     {
       id: 'combine',
@@ -2310,7 +2610,11 @@ export const COMBINATION_WORKFLOW: PreviewWorkflow = {
       position: { x: 720, y: 75 },
       rows: [
         { title: 'Language', value: 'JavaScript' },
-        { title: 'Code', value: 'merge(<support.content>, <research.content>)' },
+        {
+          title: 'Code',
+          value:
+            'return { support: <customersupport.content>, research: <deepresearcher.content> };',
+        },
       ],
     },
   ],
@@ -2339,7 +2643,7 @@ export const ROUTING_WORKFLOW: PreviewWorkflow = {
       bgColor: '#2FB3FF',
       position: { x: 0, y: 140 },
       hideTargetHandle: true,
-      rows: [{ title: 'Input', value: 'Message' }],
+      rows: [{ title: 'Input', value: 'message (string), type (string)' }],
     },
     {
       id: 'condition',
@@ -2375,7 +2679,7 @@ export const ROUTING_WORKFLOW: PreviewWorkflow = {
       sentence: ['Prompt', { subBlockId: 'Model', noun: 'model' }],
       bgColor: '#33C482',
       position: { x: 740, y: 280 },
-      rows: [{ title: 'Model', value: 'claude-sonnet-4-6' }],
+      rows: [{ title: 'Model', value: 'claude-sonnet-5-5' }],
     },
     {
       id: 'sales',
@@ -2385,7 +2689,7 @@ export const ROUTING_WORKFLOW: PreviewWorkflow = {
       sentence: ['Prompt', { subBlockId: 'Model', noun: 'model' }],
       bgColor: '#33C482',
       position: { x: 1120, y: -60 },
-      rows: [{ title: 'Model', value: 'claude-sonnet-4-6' }],
+      rows: [{ title: 'Model', value: 'claude-sonnet-5-5' }],
     },
     {
       id: 'support',
@@ -2395,7 +2699,7 @@ export const ROUTING_WORKFLOW: PreviewWorkflow = {
       sentence: ['Prompt', { subBlockId: 'Model', noun: 'model' }],
       bgColor: '#33C482',
       position: { x: 1120, y: 90 },
-      rows: [{ title: 'Model', value: 'claude-sonnet-4-6' }],
+      rows: [{ title: 'Model', value: 'claude-sonnet-5-5' }],
     },
   ],
   edges: [
@@ -2447,7 +2751,7 @@ export const ERROR_PATH_WORKFLOW: PreviewWorkflow = {
       sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
       bgColor: '#FF402F',
       position: { x: 720, y: 0 },
-      rows: [{ title: 'Code', value: 'return ok' }],
+      rows: [{ title: 'Code', value: 'return "ok";' }],
     },
     {
       id: 'handleError',
@@ -2457,7 +2761,7 @@ export const ERROR_PATH_WORKFLOW: PreviewWorkflow = {
       sentence: ['Run', { subBlockId: 'Code', noun: 'code' }],
       bgColor: '#FF402F',
       position: { x: 720, y: 170 },
-      rows: [{ title: 'Code', value: 'return recovered' }],
+      rows: [{ title: 'Code', value: 'return "recovered";' }],
     },
   ],
   edges: [
diff --git a/apps/docs/components/workflow-preview/index.ts b/apps/docs/components/workflow-preview/index.ts
index a5eaac685ea..ad8703d50d4 100644
--- a/apps/docs/components/workflow-preview/index.ts
+++ b/apps/docs/components/workflow-preview/index.ts
@@ -7,7 +7,6 @@ export {
   COMBINATION_WORKFLOW,
   CONCURRENCY_WORKFLOW,
   CONDITION_MODERATE_WORKFLOW,
-  CONDITION_ONBOARD_WORKFLOW,
   CONDITION_ROUTE_WORKFLOW,
   CREDENTIAL_ROUTE_WORKFLOW,
   CREDENTIAL_SHARE_WORKFLOW,
@@ -27,9 +26,7 @@ export {
   PARALLEL_WORKFLOW,
   RESPONSE_API_WORKFLOW,
   RESPONSE_ERROR_WORKFLOW,
-  RESPONSE_WEBHOOK_WORKFLOW,
   ROUTER_CLASSIFY_WORKFLOW,
-  ROUTER_LEAD_WORKFLOW,
   ROUTER_TRIAGE_WORKFLOW,
   ROUTING_WORKFLOW,
   SUPPORT_KB_WORKFLOW,
diff --git a/apps/docs/content/docs/agents/choosing.mdx b/apps/docs/content/docs/agents/choosing.mdx
index 55cb9017ad2..830a03f1879 100644
--- a/apps/docs/content/docs/agents/choosing.mdx
+++ b/apps/docs/content/docs/agents/choosing.mdx
@@ -1,78 +1,81 @@
 ---
 title: Choosing what to use
-description: Pick between a deterministic block, an agent tool, a custom tool, an MCP server, a workflow-as-tool, and a skill.
+description: Choose fixed workflow steps, Agent tools, reusable code, MCP connections, workflows as tools, or skills.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
 import { WorkflowPreview, LEAD_SCORER_WORKFLOW } from '@/components/workflow-preview'
 
-When you build an agent, several features overlap: a deterministic block and an agent tool can run the same integration, and a custom tool, an MCP tool, and a workflow-as-tool can all give an agent the same action. This page lays out the differences so you pick the right one. They vary along three lines: whether the action is **deterministic** (always runs) or **model-decided** (an agent chooses), whether it lives in one workflow or is **reusable** across your workspace, and whether it comes from Sim or an **external** provider.
+Start with who should decide to run an action. Put it on the workflow path when it must be attempted at that point. Give it to an **Agent** block as a tool when the model should decide whether and when to call it.
 
-The running example is a workflow that scores inbound sales leads. It reads a new lead, enriches it, decides on a score, logs the result, and notifies the team. Each option below builds part of it:
+Then choose how to provide the action or instructions:
 
-<WorkflowPreview workflow={LEAD_SCORER_WORKFLOW} height={210} />
+| Choice | Use it for | Configure it in |
+| --- | --- | --- |
+| Fixed workflow block | A required step on a workflow path | The workflow builder |
+| Agent tool | An action the model chooses during a run | The Agent block's **Tools** input |
+| Custom tool | Reusable JavaScript with a parameter schema | Workspace **Custom tools** settings, then the Agent tool list |
+| External MCP server | A toolset provided by a service or your own server | Workspace **MCP tools** settings, then the Agent tool list |
+| Workflow as a tool | A reusable procedure with several steps | A separate workflow, then the Agent tool list |
+| Skill | Reusable instructions for how to do the work | **Integrations → Skills**, then the Agent's **Skills** input or Chat |
 
-{/* VISUAL: decision tree. Always happens? → deterministic block. Else agent chooses? → agent tool. Reuse across workspace? → custom tool. External toolset? → MCP. Whole workflow? → workflow-as-tool. Reusable instructions? → skill. */}
+Custom tools, MCP operations, and workflows as tools are all ways to give an Agent callable actions. A skill supplies instructions for using those capabilities.
 
-## Deterministic block
+## Fixed workflow block
 
-A **block** is a single step that runs at a fixed point on the path, with no model deciding whether to. It always runs when the workflow reaches it. Use one when the action must happen every time: an API call, a data transform, a branch.
+A block runs when the workflow reaches it. Use a fixed step for an API request, transformation, branch, or record that belongs on that path. The step can still fail; fixed execution does not guarantee a successful result.
 
-In the lead scorer, a [Google Sheets](/integrations) block always appends the scored lead to a tracking sheet, and a [Function](/workflows/blocks/function) block always reshapes the enrichment response into the fields the next step expects. The block runs at that point in the graph; an execution error can still stop it.
+This lead-scoring workflow enriches a lead, reshapes the data, scores it, and appends the score to a sheet:
 
-<WorkflowPreview workflow={LEAD_SCORER_WORKFLOW} height={170} highlightBlock="log" />
+<WorkflowPreview workflow={LEAD_SCORER_WORKFLOW} height={210} />
 
-Most steps in a workflow are blocks. Reach for the kinds below only when you want a model to decide, or you want to reuse something.
+The **Workflow** block runs enrichment before scoring. The **Function** block reshapes its result. The **Google Sheets** block records a score whenever execution reaches that step.
 
 ## Agent tool
 
-An **agent tool** is an action you hand to an [Agent](/workflows/blocks/agent) block. The agent reads the task and decides whether and when to call it. The same catalog of [integrations](/integrations) that exist as standalone blocks can also be attached to an agent as tools.
+An Agent tool is an action the model can call while it works. Eligible integrations from the [catalog](/integrations) can run as standalone blocks or as tools attached to an Agent.
 
-In the lead scorer, the Agent has a Search tool and a Send Email tool. For a lead with a thin profile it runs Search to gather context; for a strong lead it calls Send Email. A thin, obvious lead might trigger neither. The agent chooses per run.
+In the lead scorer, the Agent has Search and Send Email tools. It can search when a profile is incomplete or send an email when the task calls for outreach. A run may use either tool, both, or neither.
 
-<WorkflowPreview workflow={LEAD_SCORER_WORKFLOW} height={170} highlightBlock="score" />
+Each tool's **Permission Mode** controls how it is offered:
 
-Each tool carries a `usageControl` setting. **Auto** lets the model decide (the default). **Force** makes the agent call the tool every run, for actions that should never be skipped, like always logging the decision. **None** removes the tool from that agent.
+- **Auto** lets the model decide whether to call it.
+- **Force** requests a call on models that support forced tool use.
+- **None** hides the tool from the model without deleting its configuration.
 
-<Callout type="info">
-A block and an agent tool can be the same underlying integration. The difference is who decides. A block runs because the path reached it. An agent tool runs because the agent chose it.
-</Callout>
+Force does not guarantee success. Use a separate block for an action that must be attempted on the workflow path, such as recording the scoring result. See the [Agent reference](/workflows/blocks/agent) for models and runtime permission modes.
 
 ## Custom tool
 
-A **custom tool** is a tool you define once with an object schema and a JavaScript function body, then reuse across your workspace. It needs no external account. Use one when you have logic that several agents or workflows would otherwise duplicate.
+A [custom tool](/agents/custom-tools) combines an object parameter schema with a JavaScript function body. Save it once in the workspace, then attach it to Agents that need it.
 
-In the lead scorer, a `normalizeCompanyDomain` custom tool cleans a raw website into a canonical domain. The same tool serves the lead scorer, a deduplication workflow, and a reporting agent. Define it in the workspace, then pick it from any Agent block's tool list.
+For example, `normalize_company_domain` can clean a website value before a lead scorer, deduplication agent, or reporting agent uses it. Pure transformations need no external account. Code that calls an API may need that service's credentials.
 
-## MCP server
+Custom tools use the isolated JavaScript runtime. For a fixed code step or code requiring a supported remote sandbox, use [Function](/workflows/blocks/function).
 
-**MCP** (Model Context Protocol) is a standard for connecting an external tool provider. Connect an [MCP server](/agents/mcp) and its tools appear in the agent's tool list as a set. Use it to bring in a complete toolset that Sim does not provide natively, rather than wiring each action by hand.
+## External MCP server
 
-In the lead scorer, your CRM vendor ships an MCP server. After you connect it once, the agent can read accounts and update records through the vendor's own tools. The difference from a custom tool is who maintains it: a custom tool is code you wrote, while an MCP server is a toolbox someone else maintains.
+MCP, the Model Context Protocol, connects an external provider's tools to Sim. Register an [MCP server](/agents/mcp), authorize its connection, and select the operations the Agent may use.
 
-## Workflow-as-tool
+For example, a CRM server can expose account lookup and record updates. The provider maintains those operations, or your team can run its own MCP server. Choose this path when an existing server provides the toolset you need.
 
-A **workflow-as-tool** is a whole workflow handed to an agent as one callable tool. You pick the workflow in the [Agent](/workflows/blocks/agent) block's tool list; the agent decides when to call it and supplies the inputs, which arrive at the child's [Start](/workflows/triggers/start) trigger, and the child's result comes back as the tool's output. Use it when a multi-step procedure should be at the agent's disposal, not on the path.
+## Workflow as a tool
 
-In the lead scorer, the agent has a `Deep Enrich` workflow as a tool — its own five-step procedure. For a thin lead, the agent calls it to fill out the profile before scoring; for a complete lead, it never runs. The agent weighs a whole procedure the same way it weighs a single action.
+Attach another workflow through the Agent's tool list to make a multi-step procedure callable. The Agent supplies inputs to the child's [Start trigger](/workflows/triggers/start) and receives the child's output.
 
-<Callout type="info">
-A workflow can also run as a fixed step: the [Workflow](/workflows/blocks/workflow) block calls a child workflow because the path reached it. Same child workflow, same Start trigger — the difference, as with blocks and agent tools, is who decides. The Enrich step in the diagram is that deterministic case.
-</Callout>
+The lead scorer has a **Deep Enrich** workflow as a tool. The Agent can call that procedure for an incomplete lead and skip it for a complete profile. The separate **Enrich** step in the diagram is the fixed case: a [Workflow block](/workflows/blocks/workflow) calls its child when the path reaches it.
 
-<WorkflowPreview workflow={LEAD_SCORER_WORKFLOW} height={170} highlightBlock="enrich" />
+Child state follows the parent's execution context: draft runs use draft child state; deployed runs use deployed child state. See the Workflow reference for input mapping, permissions, outputs, and errors.
 
 ## Skill
 
-A **skill** is reusable instructions, a written playbook an agent can follow. Each skill has a short name and description that are always visible to the agent, plus a longer body the agent loads only when it decides the skill applies. Use one to capture how something should be done, separate from the tools that do it.
+A [skill](/agents/skills) is reusable Markdown guidance, such as a scoring rubric or writing style guide. A workflow Agent sees the selected skill's name and description, then calls `load_skill` when it decides the full instructions are relevant. In Chat, tagging a skill includes its instructions in the request.
+
+For example, `lead-scoring-rubric` can define score bands and disqualifiers. It tells the agent how to assess a lead; tools still perform searches, updates, and other actions.
 
-In the lead scorer, a `lead-scoring-rubric` skill spells out the bands and disqualifiers. The agent sees the skill's name and description on every run, and when a lead is ambiguous it loads the full rubric and applies it. The distinction is simple: a tool is an action the agent takes, and a skill is guidance the agent reads. Manage skills in your [workspace](/agents/skills).
+## Related docs
 
-| Feature | Who decides it runs | Where it lives | How you author it |
-| --- | --- | --- | --- |
-| **Block** | The path | The workflow | Drag in and configure |
-| **Agent tool** | The agent | On the Agent block | Pick from the integrations |
-| **Custom tool** | The agent | The workspace | Write the code once |
-| **MCP server** | The agent | An external server | Connect it |
-| **Workflow-as-tool** | The agent | Its own workflow | Build it, then pick it in the tool list |
-| **Skill** | The agent | The workspace | Write the instructions |
+- [Agents](/agents)
+- [Agent block reference](/workflows/blocks/agent)
+- [Custom tools](/agents/custom-tools)
+- [Using MCP tools](/agents/mcp)
+- [Agent skills](/agents/skills)
diff --git a/apps/docs/content/docs/agents/custom-tools.mdx b/apps/docs/content/docs/agents/custom-tools.mdx
index b40d49165a6..4f1f010f748 100644
--- a/apps/docs/content/docs/agents/custom-tools.mdx
+++ b/apps/docs/content/docs/agents/custom-tools.mdx
@@ -1,38 +1,28 @@
 ---
-title: Custom Tools
-description: Create your own tools with JavaScript code and use them in Agent blocks
+title: Custom tools
+description: Define reusable JavaScript tools with parameter schemas and attach them to Agent blocks.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Step, Steps } from 'fumadocs-ui/components/steps'
-import { FAQ } from '@/components/ui/faq'
 
-Custom tools let you write your own JavaScript functions and make them available as callable tools in Agent blocks. This is useful when you need functionality that isn't covered by Sim's built-in integrations — for example, calling an internal API, performing a custom calculation, or transforming data in a specific way.
+A custom tool combines a parameter schema with a JavaScript function body. Save the definition in your workspace, then give it to an **Agent** block as an action the model can call.
 
-## How Custom Tools Work
+Use custom tools for calculations, transformations, or API requests that several agents share. Use a [Function block](/workflows/blocks/function) for a fixed code step on a workflow path.
 
-A custom tool has two parts:
+## Create a custom tool
 
-1. **Schema** — A JSON definition describing the tool's name, description, and parameters (using the OpenAI function-calling format). This tells the AI agent what the tool does and what inputs it expects.
-2. **Code** — A JavaScript function body that runs when the agent calls the tool. Parameters defined in the schema are available as variables in your code.
+You need **Write** or **Admin** access to the workspace.
 
-When an Agent block has access to a custom tool, the AI model decides when to call it based on the schema description and the conversation context — just like built-in tools.
+1. Open **Settings → Custom tools** and select **Add tool**.
+2. Enter the function-calling definition in **Schema**.
+3. Write the JavaScript function body in **Code**.
+4. Select **Save**.
 
-## Creating a Custom Tool
-
-<Steps>
-<Step>
-
-### Open Custom Tools settings
-
-Navigate to **Settings → Custom Tools** in your workspace and click **Add**.
-
-</Step>
-<Step>
+Schema and Code are sections on the same page. Each has a generation control that can draft content from a description; review the generated schema and code before saving.
 
 ### Define the schema
 
-In the **Schema** tab, define your tool using JSON in the OpenAI function-calling format:
+The schema tells the model what the tool does and which inputs it accepts. Use the function-calling format below, with `function.parameters.type` set to `object`:
 
 ```json
 {
@@ -45,12 +35,12 @@ In the **Schema** tab, define your tool using JSON in the OpenAI function-callin
       "properties": {
         "city": {
           "type": "string",
-          "description": "The city name"
+          "description": "The city name, optionally including a country code"
         },
         "units": {
           "type": "string",
           "enum": ["celsius", "fahrenheit"],
-          "description": "Temperature units"
+          "description": "Temperature units; defaults to celsius when omitted"
         }
       },
       "required": ["city"]
@@ -59,104 +49,94 @@ In the **Schema** tab, define your tool using JSON in the OpenAI function-callin
 }
 ```
 
-<Callout type="info">
-  You can use the AI wand button to generate a schema from a natural language description of what the tool should do.
-</Callout>
-
-</Step>
-<Step>
+Function names must contain 1–64 letters, digits, underscores, or hyphens. Describe when to call the tool and mark required inputs in the schema.
 
 ### Write the code
 
-Switch to the **Code** tab and write the JavaScript function body. Parameters from your schema are available directly as variables:
+The code runs as an async function body. Supplied parameters with valid JavaScript names are available by name, such as `city`. All inputs are also available through `params`. Read optional inputs through `params`, because an omitted parameter may have no named variable.
+
+This example requires an OpenWeather API key saved as `OPENWEATHER_API_KEY` under **Settings → Secrets**. It handles the optional units input and returns the weather fields the agent needs:
 
 ```javascript
+const apiKey = {{OPENWEATHER_API_KEY}};
+const requestedUnits = params.units ?? 'celsius';
+const apiUnits = requestedUnits === 'celsius' ? 'metric' : 'imperial';
 const response = await fetch(
-  `https://api.openweathermap.org/data/2.5/weather?q=${city}&units=${units === 'celsius' ? 'metric' : 'imperial'}&appid={{OPENWEATHER_API_KEY}}`
+  `https://api.openweathermap.org/data/2.5/weather?q=${encodeURIComponent(city)}&units=${apiUnits}&appid=${apiKey}`
 );
 
-const data = await response.json();
+if (!response.ok) {
+  throw new Error(`Weather request failed: ${response.status}`);
+}
 
+const data = await response.json();
 return {
   temperature: data.main.temp,
+  units: requestedUnits,
   description: data.weather[0].description,
   humidity: data.main.humidity
 };
 ```
 
-For a secret used as a complete JavaScript expression, prefer the unquoted form, such as `const apiKey = {{OPENWEATHER_API_KEY}};`. Quoted and embedded forms remain supported, including the placeholder embedded in the URL above, `"Bearer {{KEY}}"`, template literals, and JavaScript regex literals. The value is bound separately when the tool executes rather than pasted into its source, so its exact string contents are preserved.
+The return value becomes the tool result available to the agent. The [OpenWeather API reference](https://openweathermap.org/api/current) describes its inputs and responses.
 
-<Callout type="info">
-  You can also use the AI wand to generate code from a description. Environment variables are referenced with `&#123;&#123;KEY&#125;&#125;` syntax.
-</Callout>
-
-</Step>
-<Step>
-
-### Save
-
-Click **Save** to create the tool. It's now available to use in any Agent block across your workspace.
-
-</Step>
-</Steps>
+## Attach the tool to an Agent
 
-## Using Custom Tools in Workflows
+1. Open an **Agent** block with a model that supports tools.
+2. In **Tools**, select **Add tool...**.
+3. Find the saved definition under **Custom Tools** and select it.
+4. Run a task that needs the tool and inspect the Agent's tool calls.
 
-Once created, custom tools appear alongside built-in tools when configuring an Agent block:
+The model chooses whether to call it based on its schema and the task, subject to the tool's **Permission Mode**. See [Agent tools](/workflows/blocks/agent) for Auto, Force, and None.
 
-1. Open an Agent block
-2. Click **Add Tools**
-3. Find your custom tool in the tool list
-4. The agent will call the tool when it determines it's relevant to the task
+## JavaScript runtime
 
-## Code Environment
+Custom tools run in an isolated JavaScript VM, including when a workflow has a remote sandbox configured.
 
-### Available Features
+| Capability | Behavior |
+| --- | --- |
+| Async code | Use `await` directly and `return` the result. |
+| Inputs | Read supplied inputs by valid JavaScript name or through `params`; use `params` for optional or non-identifier keys. |
+| HTTP requests | `fetch()` returns status, headers, and `.json()` or `.text()`. Requests must satisfy the deployment's network policy. |
+| Secrets | Use `{{KEY}}` placeholders to bind saved secrets at execution time. |
+| File content | Pass content as an input or use supported scoped `sim.files` helpers to read an authorized file. See the [Function file reference](/workflows/blocks/function#files). |
 
-- **Async/await** — Your code runs in an async context, so you can use `await` directly
-- **fetch()** — Make HTTP requests to external APIs
-- **Node.js built-ins** — Access to `crypto`, `Buffer`, and other standard modules
-- **Environment variables** — Use `{{KEY}}` syntax to bind secrets at execution time without placing plaintext in source code
+Node module loading, external packages, and a sandbox filesystem are unavailable. Do not use `require`, `process`, `Buffer`, Node crypto, or package imports such as axios or lodash. The custom-tool fetch response does not support `.blob()` or `.arrayBuffer()`.
 
-### Limitations
+The separate **Function** tool supports additional runtimes and configured file inputs/outputs. Its controls differ from a saved custom tool and from the standalone Function block; see [Function](/workflows/blocks/function).
 
-- **No npm packages** — External libraries like `axios` or `lodash` are not available. Use built-in APIs instead
-- **Parameters by name** — Schema parameters are available directly as variables (e.g., `city`), not via a `params` object
+## Use secrets
 
-### Returning Results
-
-Return a value from your code to send it back to the agent:
+For a secret used as a complete JavaScript expression, use an unquoted placeholder:
 
 ```javascript
-const result = await fetch(`https://api.example.com/data?q=${query}`);
-const data = await result.json();
-return data;
+const apiKey = {{MY_API_KEY}};
 ```
 
-The returned value becomes the tool output that the agent sees and can use in its response.
+Quoted and embedded forms are also supported, including `"Bearer {{KEY}}"`, template literals, and JavaScript regex literals. Sim binds the value separately from the source, preserving its string contents.
 
-## Managing Custom Tools
+<Callout type="warn">
+Exact recognized secret values are masked in the trace copy and replaced before a tool result reaches the Agent model, unless the secret's visibility setting exempts it. Encoded or transformed values can escape that protection. Runtime operations still receive the real secret. Do not return or print secrets; see [Execution log protection](/platform/credentials#execution-log-protection) for the full scope and limits.
+</Callout>
 
-From **Settings → Custom Tools** you can:
+## Manage tools and access
 
-- **Search** tools by name, function name, or description
-- **Edit** any tool's schema or code
-- **Delete** tools that are no longer needed
+Under **Settings → Custom tools**, search by tool name, function name, or description. Open a definition to edit its schema or code.
 
 <Callout type="warn">
-  Deleting a custom tool removes it from all Agent blocks that reference it. Make sure no active workflows depend on the tool before deleting.
+Deleting a saved tool removes its definition and can break Agents that reference it. Review dependent workflows and remove or replace their bindings before deleting the tool.
 </Callout>
 
-## Permissions
+| Action | Required workspace role |
+| --- | --- |
+| View tools | Read, Write, or Admin |
+| Create, edit, or delete tools | Write or Admin |
+
+Organization permission groups can restrict custom-tool use. See [Permission groups](/platform/enterprise/access-control) for how restrictions apply.
 
-| Action | Required Permission |
-|--------|-------------------|
-| View custom tools | **Read**, **Write**, or **Admin** |
-| Create or edit tools | **Write** or **Admin** |
-| Delete tools | **Admin** |
+## Related docs
 
-<FAQ items={[
-  { question: "Can I use custom tools in standalone blocks (not agents)?", answer: "No. Custom tools are designed for use within Agent blocks, where the AI model decides when to call them. For deterministic tool execution, use the Function block instead." },
-  { question: "How do I pass API keys to my custom tool code?", answer: "Use double curly brace syntax such as {{MY_API_KEY}} for a value saved under Settings → Secrets. The value is bound outside the source at execution time. Exact occurrences are masked in the trace copy and replaced with the placeholder before a tool result is sent back to the Agent model. Encoded or otherwise transformed values cannot be recognized reliably. See Execution log protection under Secrets for details." },
-  { question: "Can I use external npm packages?", answer: "No. Custom tool code runs in a sandboxed environment with access to built-in Node.js modules and fetch(), but not external packages. For complex dependencies, consider calling an external API that wraps the functionality you need." },
-]} />
+- [Choosing what to use](/agents/choosing)
+- [Agent block reference](/workflows/blocks/agent)
+- [Function](/workflows/blocks/function)
+- [Secrets](/platform/credentials)
diff --git a/apps/docs/content/docs/agents/index.mdx b/apps/docs/content/docs/agents/index.mdx
index 2fe27a3073c..206d0719786 100644
--- a/apps/docs/content/docs/agents/index.mdx
+++ b/apps/docs/content/docs/agents/index.mdx
@@ -1,63 +1,46 @@
 ---
 title: Agents
-description: An agent is a workflow that reasons and acts, built around Agent blocks and the features you give them.
+description: Build workflow agents with models, tools, reusable instructions, and your data.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Card } from 'fumadocs-ui/components/card'
 import { WorkflowPreview, BUILD_AGENT_WORKFLOW } from '@/components/workflow-preview'
 
-An **agent** is a [workflow](/workflows) that reasons and acts on its own. It reads an input, decides what to do, and carries it out, calling tools and using your data along the way. You build a custom agent in Sim by composing a workflow whose thinking runs through one or more [Agent blocks](/workflows/blocks/agent).
+Build a workflow agent by connecting one or more **Agent** blocks to the steps it needs. Each Agent block sends messages to a model, lets it call configured tools, and returns a result for later blocks.
 
-An **Agent block** is the reasoning step inside that workflow: a model reads the values available to it, decides, and returns a result that later blocks read by reference. A simple agent is a single Agent block; a larger one wires several together with other blocks. The Agent block is where the model thinks; the rest of the workflow is what it acts on and through.
+## Build a workflow agent
 
-<WorkflowPreview workflow={BUILD_AGENT_WORKFLOW} height={200} highlightBlock="agent" />
-
-The example throughout is an agent that scores inbound sales leads.
-
-## The Agent block
-
-You set up the reasoning step by giving the Agent block a **model** and a **prompt**. The model is the LLM that powers it; you pick one from the available providers, and the default is `claude-sonnet-5-5`. The prompt is a system message that defines who the agent is and how it should behave, plus a user message that carries the input, usually a reference like `<start.input>`.
-
-When it runs, the Agent block reasons, calls any tools it needs, and stores its result under its own name. By default that result is free text in `content`, read by a later block as `<agent.content>`, alongside run details like the model used, token counts, tool calls, and cost. Every setting and output field is in the [Agent block reference](/workflows/blocks/agent).
-
-## What you give an agent
-
-On its own, an Agent block can only reason and write text. You extend it so it can act, follow your rules, use your data, remember, and return results other blocks can rely on. Each feature maps to something you'd want an agent to do.
+A simple agent reads an input, scores it, and returns the score:
 
-### Take an action: tools
-
-To let an agent do something in the world, give it **tools**. A tool is an action the agent can call, like sending an email, searching the web, updating a CRM record, or running another workflow. You attach tools to the Agent block, and the agent decides which to call for the task in front of it. In the lead scorer, the agent has a search tool to gather context on a thin profile and an email tool to reach out to a strong lead.
-
-Tools come from a few places:
-
-- **[Integrations](/integrations)** are the catalog of external services: Gmail, Slack, Airtable, Linear, and hundreds more.
-- **[Custom tools](/agents/custom-tools)** are tools you define once with a schema and a snippet of code, then reuse.
-- **[MCP tools](/agents/mcp)** come from an external provider you connect through the Model Context Protocol.
-- **[Workflow-as-tool](/workflows)** makes another workflow callable, so the agent runs a whole procedure as one step.
-
-<Callout type="info">
-The same integration can run two ways. As a [block](/workflows#blocks) it runs because the path reached it. As an agent tool it runs because the agent chose it. Per-tool usage controls (force a tool, or disable one) are in the [Agent block reference](/workflows/blocks/agent).
-</Callout>
-
-### Follow a procedure: skills
+<WorkflowPreview workflow={BUILD_AGENT_WORKFLOW} height={200} highlightBlock="agent" />
 
-To give an agent instructions it can follow, write a [skill](/agents/skills). A skill is a reusable playbook with a short name and description the agent always sees, plus a longer body it loads only when the skill applies. In the lead scorer, a `lead-scoring-rubric` skill spells out the bands and disqualifiers, and the agent reads the full rubric only when a lead is ambiguous. A tool is an action the agent takes; a skill is guidance it reads.
+1. Add an [Agent block](/workflows/blocks/agent) after a [Start trigger](/workflows/triggers/start).
+2. Select a **Model**. In **Messages**, use a system message for the task and rules, and a user message for the input, such as `<start.input>`.
+3. Add the tools or context the task needs, then run the workflow and inspect the result.
 
-### Use your documents: knowledge
+Without **Response Format**, later blocks read the answer as `<agent.content>`. Model, token, tool-call, and cost details are also available. The example requests a structured score, so its Response block reads `<agent.score>` after successful JSON parsing. See the [Agent reference](/workflows/blocks/agent) for model selection, settings, and outputs.
 
-To let an agent answer from your own content, connect a [knowledge base](/knowledgebase). The agent searches it and grounds its answers in what it finds, instead of relying only on the model's general training. Give the lead scorer a knowledge base of past deals and it can compare a new lead against ones you've closed before.
+## Add capabilities
 
-### Remember across runs: memory
+| Need | Configure |
+| --- | --- |
+| Take an action | Attach integration tools, [custom tools](/agents/custom-tools), [MCP tools](/agents/mcp), or another workflow as a tool. The model decides which available tools to call. |
+| Follow a reusable procedure | Select [skills](/agents/skills), such as a lead-scoring rubric. The agent sees their names and descriptions, then loads instructions when they apply. |
+| Answer from your documents | Add the [Knowledge](/integrations/knowledge) tool and select the knowledge base to search. |
+| Read a file | Use the Agent block's **Files** input with a model that supports the file type. |
+| Remember earlier runs | Configure [memory](/workflows/blocks/agent#memory) and a conversation ID. The memory mode controls which history reaches the model. |
+| Return fields for later blocks | Set **Response Format** to request a JSON shape, then reference successful structured fields directly, such as `<agent.tier>`. Provider support and malformed-output behavior vary. |
 
-To let an agent reuse information from one run to the next, give it [memory](/workflows/blocks/agent#memory), which stores and recalls values keyed to a conversation. Without it, each run starts fresh; with it, an agent in a chat carries what was said earlier into later messages.
+Tools and skills need a compatible model and the required workspace, credential, and organization access. Adding a skill supplies instructions; adding a tool gives the model an action it can call.
 
-### Return a usable result: structured output
+## Choose where an action runs
 
-To make an agent's result something later blocks can act on, give it a **structured output**: a typed object you define instead of free text. In the lead scorer, the agent returns `{ score, tier, reason }`, and a later [Condition](/workflows/blocks/condition) block reads `<agent.tier>` to branch. See [how blocks pass data](/workflows/data-flow) for reading fields.
+Use a separate workflow block when an action must be attempted whenever that path runs. Attach it as an Agent tool when the model should decide whether it is needed. For example, a lead-scoring agent might search for missing company information, while a Google Sheets block records every score that reaches it.
 
-## Choosing what to use
+The same integration can serve either role. See [Choosing what to use](/agents/choosing) for the differences among fixed steps, Agent tools, custom tools, MCP connections, workflows as tools, and skills.
 
-Start with one Agent block and a prompt, then add only what the task needs: a tool when the agent should act, a skill when it needs written guidance, a knowledge base when it should answer from your documents, memory when it should remember, and a structured output when a later block has to read its result.
+## Related docs
 
-<Card title="Choosing what to use" href="/agents/choosing" description="A side-by-side guide to tools, skills, knowledge, and the rest, with one worked example." />
+- [Agent block reference](/workflows/blocks/agent)
+- [Choosing what to use](/agents/choosing)
+- [How blocks pass data](/workflows/data-flow)
+- [Chat](/chat)
diff --git a/apps/docs/content/docs/agents/mcp.mdx b/apps/docs/content/docs/agents/mcp.mdx
index 60cce667fe1..685761f7b50 100644
--- a/apps/docs/content/docs/agents/mcp.mdx
+++ b/apps/docs/content/docs/agents/mcp.mdx
@@ -1,206 +1,149 @@
 ---
 title: Using MCP tools
-description: Connect external tools and services using the Model Context Protocol
+description: Connect external MCP servers and control which operations your workflow agents can call.
 ---
 
-import { Image } from '@/components/ui/image'
-import { Video } from '@/components/ui/video'
 import { Callout } from 'fumadocs-ui/components/callout'
 
-The Model Context Protocol ([MCP](https://modelcontextprotocol.com/)) is an open standard for connecting AI to external tools and data. Add an MCP server to your workspace and its tools become available to your agents — a way to integrate services Sim doesn't have a built-in integration for.
+MCP, the [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro), connects AI applications to external tools. Register a remote server in your workspace, authorize its connection, and give its operations to an **Agent** block or run them through an **MCP** block.
 
-<Callout type="info">
-  To use your Sim workspace from Claude, Codex, or Cursor, connect the
-  [Sim MCP server](/mcp/overview).
-</Callout>
+Registrations are workspace-scoped. Add a separate registration in each workspace that needs the server. To connect an external app to Sim itself, use the [Sim MCP server](/mcp/overview), [workflow deployment MCP](/workflows/deployment/mcp), or [Search MCP](/search/mcp).
 
-## Adding an MCP Server as a Tool
-
-MCP servers provide collections of tools that your agents can use.
-
-<div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="mcp/settings-mcp-tools.mp4" width={700} height={450} />
-</div>
-
-To add one:
-
-1. Navigate to **Settings → MCP Tools**
-
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/mcp-settings.png"
-    alt="MCP Tools settings page"
-    width={700}
-    height={147}
-    className="my-6"
-  />
-</div>
-
-2. Click **Add** to open the configuration modal
-3. Enter a **Server Name** and **Server URL**
-4. Add any required **Headers** (e.g. API keys)
-5. Click **Add MCP** to save
-
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/mcp-add-modal.png"
-    alt="Add New MCP Server modal"
-    width={450}
-    height={272}
-    className="my-6"
-  />
-</div>
-
-<Callout type="info">
-You can also configure MCP servers directly from the toolbar in an Agent block for quick setup.
-</Callout>
+## Add a server
 
-### Server Configuration Options
+You need **Write** or **Admin** access. Sim supports remote **Streamable HTTP** servers; a local stdio command is not a supported registration.
 
-| Field | Description |
-|-------|-------------|
-| **Name** | Display name for the server |
-| **URL** | The MCP server endpoint |
-| **Transport** | Currently supports `streamable-http` |
-| **Headers** | Key-value pairs for authentication or custom headers |
-| **Timeout** | Connection timeout in milliseconds (default: 30,000) |
+1. Open **Settings → MCP tools** and select **Add server**. You can also select **Add MCP Server** in an Agent's **Tools** menu.
+2. Enter the **Server Name** and **Server URL**.
+3. Add authentication **Headers** if the provider requires them. Use saved secret references for sensitive values.
+4. If the provider requires an OAuth client that cannot be registered automatically, open **Advanced settings** and enter its **Client ID** and **Client Secret**.
+5. Select **Add server**. Sim tests the connection before saving.
+6. For OAuth authentication, select **Authorize** on the saved server and complete browser sign-in.
 
-### Environment Variables in Configuration
+Open the server detail to inspect **Tools**, including parameter names, types, and required flags. A successful connection can expose no tools. When editing a registration, use **Test connection** to check connectivity.
 
-Server URLs and headers support environment variable substitution using `{{VAR_NAME}}` syntax. This keeps sensitive values like API keys out of the server configuration.
+The registration uses `streamable-http` and defaults to a 30,000 ms connection timeout. These are configuration values rather than selectable controls in the form. Each connection attempt is capped at 60,000 ms. OAuth requires HTTPS outside loopback development.
 
-```
+**Edit JSON** accepts a remote configuration with a named `mcpServers` entry containing `url` and optional `headers`, or a configuration containing `url` directly. If several entries are present, it reads the first. It does not import a desktop client's executable command configuration.
+
+### Secrets in URLs and headers
+
+URLs and headers support `{{VAR_NAME}}` substitution from available saved secrets. Type `{{` in either field to open the secret picker:
+
+```text
 URL: https://api.example.com/mcp
 Authorization: Bearer {{MCP_API_TOKEN}}
 ```
 
-When you type `{{` in the URL or header fields, a dropdown appears showing available workspace environment variables.
+When a secret is successfully substituted, Sim masks exact recognized values in stored MCP tool-call traces unless the secret's visibility setting exempts them. The real credentials are used for the provider request. See [Execution log protection](/platform/credentials#execution-log-protection) for model projection, visibility exceptions, and encoded or transformed values.
 
-When a saved secret is successfully substituted this way, exact occurrences of its value are masked in stored MCP tool-call traces. The real URL or header value still reaches the MCP server unchanged. See [Execution log protection](/platform/credentials#execution-log-protection) for the exact scope and limitations.
+### Connection identity
 
-### Testing and Validation
+Ordinary OAuth registrations use the acting user's OAuth connection. Unattended workflow runs use the run's trusted execution actor. Each member who needs an ordinary OAuth connection may need to authorize their own account.
 
-Click **Test Connection** before saving to verify the server is reachable and discover available tools. The test response shows the number of tools found and the protocol version.
+A managed connection uses the explicitly selected [Credential Group connection](/platform/connected-accounts) and its access grants. Servers managed by Connected accounts are configured there.
 
-After saving, each server displays its available tools with parameter names, types, and required flags. If a server's tools change (e.g., after a server update), click **Refresh** to fetch the latest schemas. This automatically updates any agent blocks using those tools.
+<Callout type="warn">
+MCP calls use the authorized connection's headers or OAuth credential. Review its operations before giving them to an Agent, and restrict access where needed. Allowing a generic operation such as `execute_sql` does not restrict the SQL it can run.
+</Callout>
+
+## Add tools to an Agent
 
-Tool validation badges appear on servers with issues — for example, if a tool was removed from the server but is still referenced in a workflow. Click the badge to see which workflows are affected.
+1. Open an **Agent** block with a model that supports tools.
+2. Under **Tools**, select **Add tool...**.
+3. In **MCP Servers**, open the configured server.
+4. Select individual tools, or select **Configure operations access** to attach the server with an access policy.
 
-### Domain Allowlisting
+Individual tools expose their argument fields. The Agent chooses when to call the tools and supplies model-controlled inputs. Per-tool **Permission Mode** and current workspace, credential, and organization authorization still apply.
 
-Self-hosted deployments can restrict which MCP server domains are allowed by setting the `ALLOWED_MCP_DOMAINS` environment variable (comma-separated list). When set, only servers on approved domains can be added. When unset, all domains are allowed.
+### Dynamic server attachment
 
-This governs which domains may be used. It is separate from where those domains are allowed to resolve: an MCP server on a private address is reached by naming it in `EGRESS_ALLOWED_HOSTS` or `EGRESS_ALLOWED_IP_RANGES`, described in [Security](/platform/self-hosting/security#the-ssrf-boundary). Both checks apply.
+Select **MCP Server (Advanced)** to supply a server or managed-connection ID directly, or reference an upstream value. The **Tool IDs** field accepts literal exact operation names, such as `search_docs`, without a Sim server prefix. These fields use plain inputs rather than server or operation catalog pickers.
 
-The allowlist covers the server URL itself. If the server requires OAuth, any endpoint its metadata names on a *different* origin than the server you configured is treated as content rather than as configuration, so that one has to be publicly routable. Endpoints on the server's own origin keep the server's reachability.
+Operation names in **Tool IDs** are configuration, not model arguments or upstream references. The policy applies to whichever authorized connection the server reference resolves to at runtime.
+
+### Operations access
 
-## Using MCP Tools in Agents
+| Mode | Behavior |
+| --- | --- |
+| **Only selected** | Allows the selected exact operation names. An empty selection allows nothing; newly discovered names stay excluded. |
+| **All except selected** | Denies the selected exact names. An empty selection allows everything otherwise permitted. Denied names remain saved if they temporarily disappear. |
+| **All permitted** | Allows every operation available to the authorized credential. |
 
-Once MCP servers are configured, their tools become available within your agent blocks:
+New restricted attachments start with an empty explicit selection. Existing saved configurations retain their prior access through normalization, subject to current authorization.
 
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/mcp-agent-dropdown.png"
-    alt="Using MCP Tool in Agent Block"
-    width={700}
-    height={304}
-    className="my-6"
-  />
-</div>
+The policy is saved on the Agent attachment. Discovery filters the tools offered to the model, and execution checks the resolved server, connection, and policy again before calling the provider. Names are case-sensitive. The policy can narrow credential access; it cannot grant access the credential lacks.
 
-1. Open an **Agent** block
-2. In the **Tools** section, click **Add tool…**
-3. Under **MCP Servers**, click a server to see its tools
+Missing or forbidden operations, invalid connection scopes, unverifiable schemas, and malformed arguments fail the call. An Agent attachment with no permitted operations fails clearly. Operation restrictions match names; they do not inspect arguments.
 
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/mcp-agent-tools.png"
-    alt="MCP tools list for a selected server"
-    width={400}
-    height={356}
-    className="my-6"
-  />
-</div>
+## Run or list operations with an MCP block
 
-4. Select individual tools, or choose **Configure operations access** for a dynamic server attachment
-5. The agent can now access these tools during execution
+Use an **MCP** block for explicit execution or authorized operation discovery. Select its **Action**:
 
-<Callout type="info">
-If you haven't configured a server yet, click **Add MCP Server** at the top of the dropdown to open the setup modal without leaving the block.
-</Callout>
+- **Run operation** executes one exact operation name. Configured operations show generated argument fields. If the name resolves at runtime, supply a JSON arguments object; Sim validates it against the discovered schema before execution.
+- **List operations** returns authorized operation names, descriptions, and input schemas without executing provider operations. **Search operations** filters names and descriptions. **Page size** accepts 1–100 and defaults to 100; it and **Cursor** are advanced fields.
 
-## Standalone MCP Block
+In Basic mode, select a configured connection under **MCP Server** and a discovered **Operation**. In Advanced mode, enter literal IDs/names or references. A runtime server reference requires JSON arguments. Listing hides the operation and argument fields.
 
-Use the MCP block to discover operations or run one operation with explicit inputs:
+**MCP Server** accepts one shared-server ID or managed-connection ID. Sim resolves a managed connection's parent server and verifies workspace and credential access. Both actions use the same identifier. The standalone block runs its specified operation and has no separate Agent attachment policy.
 
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/mcp-tool-block.png"
-    alt="Standalone MCP Tool Block"
-    width={700}
-    height={299}
-    className="my-6"
-  />
-</div>
+### Outputs and pagination
 
-Choose an **Action**:
+| Output | Meaning |
+| --- | --- |
+| `serverId` | The supplied server or managed-connection ID |
+| `operations` | Listed operations with `name`, `description`, and `inputSchema` |
+| `nextCursor` | Cursor for the next list page, or `null` |
+| `hasMore` | Whether more authorized operations remain in the discovered inventory |
+| `content` | The MCP content array returned by a run operation |
 
-- **List operations** discovers authorized operation names, descriptions, and input schemas without executing provider operations. Filter by name or description, set a page size from 1 to 100, and pass `nextCursor` into the next request while `hasMore` is true. An authorized list can be empty.
-- **Run operation** executes one exact operation name. Configured operations keep their generated argument fields. For an operation name resolved at runtime, supply a JSON arguments object; Sim validates it against the operation's discovered schema before execution.
+While `hasMore` is true, pass `nextCursor` into **Cursor** on the next list request. An authorized list can be empty. This pagination does not bypass the discovery limits below.
 
-**MCP Server** takes one shared-server ID or managed-connection ID. Sim resolves a managed connection's parent server internally and verifies workspace and credential access. Both actions accept the same ID; List operations returns that ID as `serverId`, alongside the discovered `operations` and pagination metadata.
+## Refresh and troubleshoot
 
-The standalone block's Basic fields select a configured connection and discovered operation. Advanced fields accept literal IDs/names or upstream references. A runtime server reference requires JSON arguments. Listing hides the operation and argument fields.
+Use **Refresh** on the server detail to fetch current schemas. Matching individual MCP bindings in draft Agent blocks receive updated schemas and server metadata. Removed operations remain referenced and can fail; review validation badges to see affected workflows. Deploy an updated draft when the deployed version needs those changes. Dynamic attachments discover authorized tools when they run.
 
-### Operations access
+Discovery normally uses a five-minute cache. Failed server probes can be cached for two minutes; Refresh forces a retry. A cached or partially discovered inventory does not prove the provider has no other operations.
 
-The **MCP Server (Advanced)** Agent attachment takes a server/connection ID or upstream reference in a plain input. Its **Tool IDs** field accepts exact MCP tool names, such as `search_docs`, entered directly. These are the names returned by List operations, without a Sim server prefix. Neither field uses a server or operation catalog picker.
+### Discovery limits
 
-Agent attachments have three access modes:
+Client discovery follows the provider's `tools/list` pages within these bounds:
 
-| Mode | Behavior |
+| Budget | Hard limit |
 | --- | --- |
-| **Only selected** | Allows only selected exact operation names. An empty selection allows nothing. Newly discovered names stay excluded. |
-| **All except selected** | Denies selected exact names. An empty selection allows everything otherwise permitted. Denied names stay saved if they temporarily disappear. |
-| **All permitted** | Allows every operation available to the authorized credential. |
+| Pages | 50 |
+| Aggregated tools | 1,000 |
+| Combined tool payload | 5 MiB |
+| Aggregate discovery time | 60 seconds |
 
-New restricted configurations start with an empty explicit selection. Existing saved workflows retain their prior access through normalization, while current organization and credential authorization still apply.
+Repeated provider cursors also stop discovery. Settings discovery may return a partial inventory after a bound or later-page failure. Runtime discovery requires completion and fails if the inventory is truncated. The standalone block's page size applies after this discovery and authorization.
 
-Operation restrictions are saved in workflow state on the Agent attachment. Tool IDs are literal configuration, not upstream references or model arguments. An operation must be available to the resolved, authorized connection and permitted by the saved restriction. The standalone block runs its explicitly specified operation and has no separate access policy.
+If a call fails, check the server's connectivity, authorization, current schema, and saved access policy. An Agent can receive the tool error and respond or try another action; a standalone block uses the workflow's configured error handling. Verify the provider's state before repeating an operation that may have side effects.
 
-Discovery filters the tools exposed to the Agent. Execution checks the actual server, connection, and saved restriction again before calling the provider. Missing or forbidden operations, unverifiable schemas, malformed arguments, and incorrect connection scopes fail the call. An Agent attachment with no permitted operations fails clearly.
+## Permissions
 
-Policies match exact, case-sensitive MCP tool names on whichever authorized connection resolves at runtime. They do not inspect operation arguments: allowing a generic `execute_sql` operation does not limit which SQL it can execute.
+| Action | Required workspace role |
+| --- | --- |
+| View, discover, or execute available MCP operations | Read, Write, or Admin |
+| Register, edit, refresh, or delete external servers | Write or Admin |
+| Change a registered server's destination host or path | Admin |
 
-## When to Use MCP Tool vs Agent
+Adding or changing a workflow's tools also requires workflow edit access. Credential grants and organization permission-group restrictions apply separately. On Enterprise-entitled workspaces, a workspace Admin can configure `disableMcpTools` through [permission groups](/platform/enterprise/access-control).
 
-| Feature | **Agent with MCP tools** | **MCP Tool block** |
-|---|---|---|
-| **Execution** | AI decides which tools to call | Deterministic — runs the tool you pick |
-| **Parameters** | AI chooses at runtime | You set them explicitly |
-| **Best for** | Dynamic, conversational flows | Structured, repeatable steps |
-| **Reasoning** | Handles complex multi-step logic | One tool, one call |
+These permissions govern external server registrations. [Workflow MCP deployment](/workflows/deployment/mcp) has its own management and invocation requirements.
 
-## Permission Requirements
+## Self-hosted network policy
 
-MCP functionality requires specific workspace permissions:
+Set `ALLOWED_MCP_DOMAINS` to a comma-separated list of exact approved hostnames to restrict server domains. When unset, there is no domain allowlist restriction.
 
-| Action | Required Permission |
-|--------|-------------------|
-| Create or update MCP servers | **Write** or **Admin** |
-| Delete MCP servers | **Admin** |
-| Use MCP tools in agents | **Write** or **Admin** |
-| View available MCP tools | **Read**, **Write**, or **Admin** |
-| Execute MCP Tool blocks | **Read**, **Write**, or **Admin** |
+Domain approval and network reachability are separate checks. Private-address servers also need `EGRESS_ALLOWED_HOSTS` or `EGRESS_ALLOWED_IP_RANGES`; see [the SSRF boundary](/platform/self-hosting/security#the-ssrf-boundary).
 
-<Callout type="warn">
-MCP servers run with the permissions of the user who configured them — only connect servers you trust, and review a server's tools before handing them to agents.
-</Callout>
+The domain allowlist applies to the configured server URL. For OAuth, an endpoint on that server's origin retains its reachability. An endpoint named by metadata on a different origin is treated as fetched content and must be publicly routable under the egress policy.
 
-import { FAQ } from '@/components/ui/faq'
+## Related docs
 
-<FAQ items={[
-  { question: "Can I use MCP servers from multiple workspaces?", answer: "MCP servers are configured per workspace. Each workspace maintains its own set of MCP server connections. If you need the same MCP server in multiple workspaces, you need to configure it separately in each workspace's settings." },
-  { question: "Can permission groups restrict access to MCP tools?", answer: "Yes. On Enterprise-entitled workspaces, any workspace admin can create a permission group that disables MCP tools for its members using the disableMcpTools option. When this is enabled, affected users will not be able to add or use MCP tools in workflows that belong to that workspace." },
-  { question: "What happens if an MCP server goes offline during workflow execution?", answer: "If the MCP server is unreachable during execution, the tool call will fail and return an error. In an Agent block, the AI may attempt to handle the failure gracefully. In a standalone MCP Tool block, the workflow step will fail. Check MCP server logs and verify the server is running and accessible to troubleshoot connectivity issues." },
-]} />
+- [Choosing what to use](/agents/choosing)
+- [Connected accounts](/platform/connected-accounts)
+- [Sim MCP server](/mcp/overview)
+- [Workflow deployment MCP](/workflows/deployment/mcp)
+- [Search MCP](/search/mcp)
diff --git a/apps/docs/content/docs/agents/skills.mdx b/apps/docs/content/docs/agents/skills.mdx
index 5690219d80a..fa11c0d4ce4 100644
--- a/apps/docs/content/docs/agents/skills.mdx
+++ b/apps/docs/content/docs/agents/skills.mdx
@@ -1,149 +1,114 @@
 ---
 title: Agent skills
-description: Reusable instruction packages your agents load on demand, managed from the Skills tab.
+description: Write reusable instructions for workflow Agents to load on demand or select them directly in Chat.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Image } from '@/components/ui/image'
 
-Agent Skills are reusable packages of instructions that give your AI agents specialized capabilities. Based on the open [Agent Skills](https://agentskills.io) format, skills let you capture domain expertise, workflows, and best practices that agents can load on demand.
+A skill is reusable Markdown guidance, such as a scoring rubric, support procedure, or writing style guide. Sim workspace skills use the name, description, and instructions from the open [Agent Skills format](https://agentskills.io/specification).
 
-## How Skills Work
+Skills supply guidance. Tools perform actions, and each action still requires its normal access and configuration.
 
-Skills use **progressive disclosure** to keep agent context lean:
+## Use a skill in an Agent
 
-1. **Discovery** — Only skill names and descriptions are included in the agent's system prompt (~50-100 tokens each)
-2. **Activation** — When the agent decides a skill is relevant, it calls the `load_skill` tool to load the full instructions into context
-3. **Execution** — The agent follows the loaded instructions to complete the task
+1. Open an **Agent** block with a model that supports tools and skills.
+2. In **Skills**, select **Add skill...** and choose the skills it should have available.
+3. Run a task that matches a selected skill, then inspect the Agent's tool calls.
 
-## Creating Skills
+<Image src="/static/skills/add-skill.png" alt="The Agent Skills menu with Add skill and Create Skill controls" width={756} height={428} className="mx-auto h-auto w-full max-w-sm" />
 
-Skills live on the **Integrations** page: click **Integrations** in the workspace sidebar, then switch to the **Skills** tab. It lists every skill in the workspace, searchable by name. Click a skill to open its detail page, where you edit, share, and delete it.
+Selected skills appear as cards that you can open or remove. Editing depends on your access to the skill.
 
-![The Skills tab on the Integrations page](/static/skills/skills-tab.png)
+At runtime, the Agent's system prompt includes an `<available_skills>` section with the selected names and descriptions. Sim adds a `load_skill` tool with a `skill_name` input. When the model calls it, the full instructions return as a tool response. Selecting a skill makes it available; the model decides whether to load it.
 
-Click **+ Add to Sim** to open the skill create page, which takes three fields:
+This uses standard tool calling across compatible models. Deep-research and evaluation models do not expose the ordinary Agent Tools and Skills controls.
 
-| Field | Description |
-|-------|-------------|
-| **Name** | A kebab-case identifier (e.g. `sql-expert`, `code-reviewer`). Max 64 characters. |
-| **Description** | A short explanation of what the skill does and when to use it. This is what the agent reads to decide whether to activate the skill. Max 1024 characters. |
-| **Content** | The full skill instructions in markdown. This is loaded when the agent activates the skill. |
+## Use a skill in Chat
 
-<Callout type="info">
-  The description is critical — it's the only thing the agent sees before deciding to load a skill. Be specific about when and why the skill should be used.
-</Callout>
-
-### Importing skills
-
-Bring in an existing skill in the open [SKILL.md](https://agentskills.io/specification) format two ways:
+Type `/` in the Chat message box to open the skills menu. Select a skill or keep typing to filter by name. The selected skill appears as a tag, such as `/format-markdown`.
 
-- **Import** — the **Import** action on the create page takes a `.md` file with YAML frontmatter, or a `.zip` containing a `SKILL.md`.
-- **Paste content** — paste the `SKILL.md` straight into **Content**. The frontmatter carries the `name` and `description`; the markdown body is the content.
+Tagging a skill includes its full instructions in the request. Sim can use them immediately, without deciding to load them through a tool first. Instructions guide the response; they do not guarantee compliance or grant additional access.
 
-Integration pages suggest **curated skills** for their service — open one (HubSpot, for example) and add a suggested skill with one click.
+## Create a workspace skill
 
-### Writing Good Skill Content
+You need **Write** or **Admin** workspace access to create a skill.
 
-Skill content follows the same conventions as [SKILL.md files](https://agentskills.io/specification):
-
-```markdown
-# SQL Expert
-
-## When to use this skill
-Use when the user asks you to write, optimize, or debug SQL queries.
-
-## Instructions
-1. Always ask which database engine (PostgreSQL, MySQL, SQLite)
-2. Use CTEs over subqueries for readability
-3. Add index recommendations when relevant
-4. Explain query plans for optimization requests
-
-## Common Patterns
-...
-```
+1. Open **Integrations** in the workspace sidebar and select **Skills**.
+2. Select **Add to Sim**.
+3. Enter **Name**, **Description**, and **Content**, then save.
 
-**Recommended structure:**
-- **When to use** — Specific triggers and scenarios
-- **Instructions** — Step-by-step guidance with numbered lists
-- **Examples** — Input/output samples showing expected behavior
-- **Common Patterns** — Reusable approaches for frequent tasks
-- **Edge Cases** — Gotchas and special considerations
+| Field | Requirements |
+| --- | --- |
+| **Name** | A workspace-unique kebab-case identifier, such as `lead-scoring-rubric`; 1–64 lowercase letters, digits, and hyphens, with no leading, trailing, or consecutive hyphens. |
+| **Description** | Explain what the skill does and when to use it; required, up to 1,024 characters. |
+| **Content** | Full Markdown instructions; required, up to 50,000 characters. |
 
-Keep skills focused and under 500 lines. If a skill grows too large, split it into multiple specialized skills.
+Search the Skills tab by name or description. Open a skill's detail page to edit it, share editor access, or delete it. Built-in skills are read-only templates; workspace skills have the editor controls described below. Integration pages can also suggest curated skills for their service, which you can add from that page.
 
-## Skill Editors
+### Write instructions
 
-Everyone in the workspace sees and uses every skill — including members who join later. Nobody needs to be added to a skill to use it.
+Keep the task and activation conditions specific. Include the steps, expected output, and edge cases that the agent needs. Keep task-specific input in the Agent block's messages.
 
-Each skill has an explicit **editors** list. Editors can edit the skill, delete it, and manage the editors list. Workspace admins can always do this too — they are editors of every skill automatically and cannot be removed from the list. Whoever creates a skill becomes an editor.
+For example, this skill defines how to score an inbound lead:
 
-Open a skill from the Skills tab to manage it. The detail page has the editable fields, a **Share** action for adding editors from your workspace members, and the **Skill Editors** list at the bottom.
-
-<Callout type="info">
-  The editors list controls who can edit a skill — it never affects who can see, use, or run it. A workflow that references a skill always executes it, no matter who runs the workflow. Treat skill content as shared team instructions, not as a secret.
-</Callout>
-
-## Using Skills in Chat
+```markdown
+---
+name: lead-scoring-rubric
+description: Score inbound sales leads using company fit and stated intent. Use when qualifying a lead or explaining its score.
+---
 
-Skills work in Chat too. Type `/` in the message box to open the skills menu, then pick a skill — or keep typing to filter by name. The skill appears in your message as a tag, e.g. `/format-markdown`.
+# Lead scoring rubric
 
-Tagging a skill loads its full instructions into the conversation, so Sim follows them for that request — no waiting for Sim to decide the skill is relevant on its own.
+1. Read the lead's company, role, use case, and stated timeline.
+2. Check the configured company-fit criteria. Identify missing evidence.
+3. Use available research tools only when more evidence is needed.
+4. Assign a score from 0 to 100 and a tier: high, medium, or low.
+5. Explain the factors behind the score. Do not invent missing facts.
 
-## Adding Skills to an Agent
+Return the score, tier, reason, and any missing information.
+Do not send outreach unless the task authorizes it.
+```
 
-Open any **Agent** block and find the **Skills** dropdown below the tools section. Select the skills you want the agent to have access to.
+The tool and response-format configuration belongs on the Agent block. Mentioning a tool or asking for fields in a skill does not create that configuration.
 
-<Image src="/static/skills/add-skill.png" alt="Add Skill" width={756} height={428} className="mx-auto h-auto w-full max-w-sm" />
+Keep skills focused. The Agent Skills specification recommends keeping the main instructions under 500 lines; this is guidance, while Sim's content limit is 50,000 characters. For large workspace instructions, split them into separate skills that can be selected independently.
 
-Selected skills appear as cards that you can click to edit or remove.
+### Import instructions
 
-### What Happens at Runtime
+Select **Import** on the create page to choose a `.md` file or a `.zip` containing `SKILL.md`. ZIP files have a 5 MiB size limit. If the archive contains several matching files, Sim selects the shallowest `SKILL.md`.
 
-When the workflow runs:
+Use simple single-line `name:` and `description:` frontmatter values followed by the Markdown body. Sim imports those three fields. Bundled scripts, reference files, assets, and other frontmatter metadata are not imported. Adapt instructions that depend on those files before using the skill.
 
-1. The agent's system prompt includes an `<available_skills>` section listing each skill's name and description
-2. A `load_skill` tool is automatically added to the agent's available tools
-3. When the agent determines a skill is relevant to the current task, it calls `load_skill` with the skill name
-4. The full skill content is returned as a tool response, giving the agent detailed instructions
+You can also paste a complete `SKILL.md` into **Content**. When it contains a `name` frontmatter field, Sim fills Name and Description from the frontmatter and uses the Markdown body as Content. Review all fields before saving.
 
-This works across all supported LLM providers — the `load_skill` tool uses standard tool-calling, so no provider-specific configuration is needed.
+## Editors and access
 
-## When to use a skill
+Workspace members can see and use workspace skills without being added as editors, subject to organization restrictions. New members receive the same use access.
 
-Use a skill for reusable procedures or knowledge shared across agents, such as a company style guide or a debugging checklist. Keep task-specific instructions in the Agent block.
+Each workspace skill has an explicit editors list:
 
-## Best Practices
+- The creator becomes an editor.
+- Editors can edit, delete, and manage the editors list while they retain workspace access, including editors with the Read workspace role.
+- Workspace Admins are editors automatically and cannot be removed from that derived access.
 
-**Writing Effective Descriptions**
-- **Be specific and keyword-rich** — Instead of "Helps with SQL", write "Write optimized SQL queries for PostgreSQL, MySQL, and SQLite, including index recommendations and query plan analysis"
-- **Include activation triggers** — Mention specific words or phrases that should prompt the skill (e.g., "Use when the user mentions PDFs, forms, or document extraction")
-- **Keep it under 200 words** — Agents scan descriptions quickly; make every word count
+Open the skill detail and use **Share** to add workspace members as editors. The **Skill Editors** list shows who can change it.
 
-**Skill Scope and Organization**
-- **One skill per domain** — A focused `sql-expert` skill works better than a broad `database-everything` skill
-- **Limit to 5-10 skills per agent** — More skills = more decision overhead; start small and add as needed
-- **Split large skills** — If a skill exceeds 500 lines, break it into focused sub-skills
+<Callout type="warn">
+The editors list controls changes to a skill, not who can load its instructions. Treat skill content as shared team instructions, not as a secret. Organization restrictions can still block skill use during a workflow run.
+</Callout>
 
-**Content Structure**
-- **Use markdown formatting** — Headers, lists, and code blocks help agents parse and follow instructions
-- **Provide examples** — Show input/output pairs so agents understand expected behavior
-- **Be explicit about edge cases** — Don't assume agents will infer special handling
+On Enterprise-entitled workspaces, a workspace Admin can configure `disableSkills` in [permission groups](/platform/enterprise/access-control). The restriction applies separately from the skill's editors list.
 
-**Testing and Iteration**
-- **Test activation** — Run your workflow and verify the agent loads the skill when expected
-- **Check for false positives** — Make sure skills aren't activating when they shouldn't
-- **Refine descriptions** — If a skill isn't loading when needed, add more keywords to the description
+## Verify activation
 
-## Learn More
+Run a representative task and inspect whether the Agent called `load_skill`. If it did not load the intended skill, make the description's task and conditions clearer. Also check the selected model, skill selection, and organization access.
 
-- [Agent Skills specification](https://agentskills.io) — The open format for portable agent skills
-- [Example skills](https://github.com/anthropics/skills) — Browse community skill examples
-- [Best practices](https://agentskills.io/what-are-skills) — Writing effective skills
+Test the resulting behavior as well as loading: instructions can be available while the model still produces an unsuitable answer.
 
-import { FAQ } from '@/components/ui/faq'
+## Related docs
 
-<FAQ items={[
-  { question: "Can permission groups disable skills for certain users?", answer: "Yes. On Enterprise-entitled workspaces, any workspace admin can create a permission group with the disableSkills option enabled. When a user is assigned to such a group in a workspace, the skills dropdown in agent blocks is disabled and they cannot add or use skills in workflows belonging to that workspace." },
-  { question: "Can I use skills in Chat?", answer: "Yes. Type / in the Chat message box to open the skills menu and pick a skill — for example /format-markdown. The tag loads the skill's full instructions into the conversation, so Sim follows them for that request without having to decide on its own to load the skill." },
-]} />
+- [Choosing what to use](/agents/choosing)
+- [Agent block reference](/workflows/blocks/agent)
+- [Agent Skills specification](https://agentskills.io/specification)
+- [Community skill examples](https://github.com/anthropics/skills)
diff --git a/apps/docs/content/docs/api-reference/authentication.mdx b/apps/docs/content/docs/api-reference/authentication.mdx
index d43896f4ee4..68ff9898935 100644
--- a/apps/docs/content/docs/api-reference/authentication.mdx
+++ b/apps/docs/content/docs/api-reference/authentication.mdx
@@ -1,124 +1,88 @@
 ---
 title: Authentication
-description: Authenticate with API keys or delegated OAuth access tokens
+description: Choose an API key or delegated OAuth token and understand its access.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 
-The Sim API accepts API keys and, when enabled by your deployment, OAuth access tokens. API keys support automation and the SDKs. OAuth lets the CLI and registered applications act on your behalf with permissions you approve.
+Authenticate API requests with a Sim API key, or an OAuth access token when your deployment enables OAuth. The Python and TypeScript SDKs use API keys. The CLI and registered OAuth applications can act with the permissions you approve.
 
-Sim supports two types of API keys — **personal keys** and **workspace keys** — each with different billing and access behaviors.
+## Choose a key [#key-types]
 
-## Key Types
-
-| Feature | **Personal Keys** | **Workspace Keys** |
+| | Personal key | Workspace key |
 | --- | --- | --- |
-| **Billing** | Workspace payer for workspace-hosted usage | Workspace payer |
-| **Scope** | Across workspaces you have access to | Shared across the workspace |
-| **Managed by** | Each user individually | Workspace admins |
-| **Permissions** | Must be enabled at workspace level | Require admin permissions |
-
-<Callout type="info">
-  Personal keys identify the user making a request; they do not select who pays.
-  Hosted usage is billed to the workspace's organization or personal billing
-  account and, for organizations, is attributed to the actor's member cap.
-  Workspace admins can disable personal API key usage for their workspace. If
-  disabled, only workspace keys can be used.
-</Callout>
+| Identity | The key owner | The workspace |
+| Scope | Workspaces the owner can currently access | One workspace |
+| Access | The owner's current role and applicable permission-group restrictions | Only operations that allow workspace keys; no admin access |
+| Managed by | The account owner, subject to key-management policy | Workspace Admins, subject to key-management policy |
+| Hosted usage payer | The workspace's billing account | The workspace's billing account |
+
+A personal key identifies the acting member; it does not choose who pays. Hosted workspace usage is billed to the workspace's organization or personal billing account. In an organization, usage attributed to a member counts toward that member's cap. See [Credits, billing and limits](/platform/costs).
 
-## Generating API Keys
+Workspace Admins can turn off **Allow personal API keys**. The workspace policy also blocks delegated OAuth access to that workspace. Permission groups can restrict personal-key and OAuth access further. Workspace keys do not inherit their creator's role or permission group; each endpoint's workspace-key policy determines whether they can call it.
 
-To generate a personal key, open **Account settings** → **Sim API keys**. Workspace
-administrators can create shared keys from **Workspace settings** → **Sim API keys**.
+## Create and store a key [#generating-api-keys]
+
+1. Open **Account settings → Sim API keys** to create a personal key, or **Workspace settings → Sim API keys** to create a workspace key.
+2. Select **Create API key**, enter a name, and create it. Workspace-key creation requires workspace **Admin** access and the applicable key-management permission.
+3. Copy the key and store it in a server-side environment variable such as `SIM_API_KEY`.
 
 <Callout type="warn">
-  API keys are only shown once when generated. Store your key securely — you will not be able to view it again.
+Sim shows the complete key once, immediately after creation. Copy it before closing the dialog. If you lose it, create a replacement and delete the old key.
 </Callout>
 
-## Using API Keys
-
-Pass your API key in the `X-API-Key` header with every request. An API key is never accepted as `Authorization: Bearer`; that header is only for [OAuth access tokens](#oauth-access-tokens).
-
-<Tabs items={['curl', 'TypeScript', 'Python']}>
-  <Tab value="curl">
-    ```bash
-    curl -X POST https://www.sim.ai/api/v2/workflows/{workflowId}/execute \
-      -H "Content-Type: application/json" \
-      -H "X-API-Key: YOUR_API_KEY" \
-      -d '{"input": {}}'
-    ```
-  </Tab>
-  <Tab value="TypeScript">
-    ```typescript
-    const response = await fetch(
-      'https://www.sim.ai/api/v2/workflows/{workflowId}/execute',
-      {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-API-Key': process.env.SIM_API_KEY!,
-        },
-        body: JSON.stringify({ input: {} }),
-      }
-    )
-    ```
-  </Tab>
-  <Tab value="Python">
-    ```python
-    import os
-
-    import requests
-
-    response = requests.post(
-        "https://www.sim.ai/api/v2/workflows/{workflowId}/execute",
-        headers={
-            "Content-Type": "application/json",
-            "X-API-Key": os.environ["SIM_API_KEY"],
-        },
-        json={"input": {}},
-    )
-    ```
-  </Tab>
-</Tabs>
-
-## Where Keys Are Used
-
-API keys authenticate access to:
-
-- **Workflow execution** — run deployed workflows via the API
-- **Logs API** — query workflow execution logs and metrics
-- **MCP servers** — authenticate connections to deployed MCP servers
-- **SDKs** — the [Python](/api-reference/python) and [TypeScript](/api-reference/typescript) SDKs use API keys for all operations
+Delete a key from the same settings page to revoke it. Update applications that used it with a replacement key.
+
+## Send an API key [#using-api-keys]
+
+Send the key in `X-API-Key`. The v2 API accepts `Authorization: Bearer` only for [OAuth access tokens](#oauth-access-tokens), not API keys. For example, with `SIM_API_KEY` and `WORKFLOW_ID` set:
+
+```bash
+curl --fail-with-body -X POST \
+  "https://www.sim.ai/api/v2/workflows/$WORKFLOW_ID/execute" \
+  -H "X-API-Key: $SIM_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"input": {}}'
+```
+
+This runs the active deployment. Use your deployment's origin for self-hosted requests. [Getting started](/api-reference/getting-started) includes complete HTTP examples and response handling; [Python](/api-reference/python) and [TypeScript](/api-reference/typescript) show SDK calls.
+
+Keys authenticate workflow execution, logs, deployed MCP servers, and other API resources that accept their key type. See each endpoint for its required access.
 
 ## OAuth access tokens
 
-Use `sim login` to authorize the CLI in your browser, or `sim login --read-only` to request read access. The CLI stores the login locally and refreshes access tokens automatically. See [CLI authentication](/cli/authentication) for profiles, sign-in, and sign-out.
+Run `sim login` to authorize the CLI in your browser, or `sim login --read-only` to request read access. The CLI stores the login locally and refreshes its access token. See [CLI authentication](/cli/authentication) for profiles, sign-in, and sign-out.
 
-Registered OAuth applications send access tokens in the `Authorization` header:
+Registered applications send OAuth access tokens in `Authorization: Bearer`:
 
 ```bash
-curl https://www.sim.ai/api/v2/workspaces \
-  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
+curl --fail-with-body 'https://www.sim.ai/api/v2/workspaces' \
+  -H "Authorization: Bearer $SIM_ACCESS_TOKEN"
 ```
 
+Use `X-API-Key` for API keys and the Bearer header for OAuth access tokens. Send one credential scheme per request.
+
 | Scope | Access |
 | --- | --- |
 | `api:read` | Read operations, including searches sent as POST requests |
-| `api:write` | Includes `api:read`, plus mutations and execution, including operations that can start external work |
+| `api:write` | Includes read access, mutations, and execution, including operations that start external work |
 | `offline_access` | Refresh tokens for continued access after the access token expires |
 
-Scopes limit what an application may do; your current workspace membership and role still apply. Each endpoint documents its required scope. Some GET endpoints that perform external discovery require `api:write`, so HTTP method alone does not determine the permission.
+Scopes limit the application's actions; your current workspace membership, role, credential access, and permission policies still apply. Each endpoint declares its required scope. Some GET endpoints that perform external discovery require `api:write`, so HTTP method alone does not determine access.
 
-Manage grants in **Settings** → **General** → **Authorized apps**. Revoking an application signs out all of its logins. `sim logout` revokes the current CLI login and removes it from your machine. The Python and TypeScript SDKs currently use API keys; they do not manage OAuth sign-in or refresh tokens.
+Manage grants in **Settings → General → Authorized apps**. Revoking an application revokes all its logins for your account. For an OAuth login, `sim logout` revokes the current login and removes it locally; the CLI reports if server revocation fails. Removing a locally stored API key does not revoke that key on the server.
 
-## Security
+The Python and TypeScript SDKs do not manage OAuth sign-in or token refresh.
 
-- Keys use the `sk-sim-` prefix and are encrypted at rest
-- Keys can be revoked at any time from the dashboard
-- Use environment variables to store keys — never hardcode them in source code
-- For browser-based applications, use a backend proxy to avoid exposing keys to the client
+## Protect credentials [#security]
 
-<Callout type="warn">
-  Never expose your API key in client-side code. Use a server-side proxy to make authenticated requests on behalf of your frontend.
-</Callout>
+Keep API keys and OAuth tokens on your server. A browser application should call an authenticated backend that checks which resources the caller may use before sending a Sim request. Do not put keys in client-side code or source control.
+
+Sim supports modern `sk-sim-` and legacy `sim_` API keys. On self-hosted deployments, stored API keys are encrypted when `API_ENCRYPTION_KEY` is configured; deployments without it retain the legacy plaintext storage behavior. Configure it using the [environment-variable reference](/platform/self-hosting/environment-variables).
+
+## Related docs
+
+- [API getting started](/api-reference/getting-started)
+- [CLI authentication](/cli/authentication)
+- [Permissions](/platform/permissions)
+- [Python SDK](/api-reference/python) and [TypeScript SDK](/api-reference/typescript)
diff --git a/apps/docs/content/docs/api-reference/getting-started.mdx b/apps/docs/content/docs/api-reference/getting-started.mdx
index 256912d0499..07f511940df 100644
--- a/apps/docs/content/docs/api-reference/getting-started.mdx
+++ b/apps/docs/content/docs/api-reference/getting-started.mdx
@@ -1,124 +1,112 @@
 ---
-title: Getting Started
-description: Base URL, OpenAPI specification, first API call, response format, error handling, and pagination
+title: Getting started
+description: Make a v2 API call, inspect its result, and handle pagination and errors.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 
-## Base URL
-
-All API requests are made to:
-
-```
-https://www.sim.ai
-```
+Use the v2 API to run workflows and manage resources you can access. This guide makes a first call to a deployed workflow, then explains asynchronous execution, response envelopes, and pagination.
 
-Every endpoint lives under `/api` on this origin, for example `https://www.sim.ai/api/v2/workflows/{workflowId}/execute`. There is no `api.sim.ai` host.
+## Base URL
 
-## OpenAPI specification
+Sim Cloud uses `https://www.sim.ai`, with API paths under `/api/v2`. There is no `api.sim.ai` host. For self-hosted Sim, replace the origin with your deployment URL.
 
-Download the [complete OpenAPI 3.1 specification](/openapi.json) as JSON for client generation, request validation, and API tooling.
+Download the [OpenAPI 3.1 specification](/openapi.json) for client generation, request validation, and API tooling.
 
-## Quick Start
+## Run a deployed workflow [#quick-start]
 
 <Steps>
-
 <Step>
-### Get your API key
+### Create an API key
 
-Open **Account settings** → **Sim API keys** to create a personal key, or **Workspace settings** → **Sim API keys** for a workspace key. These examples and the SDKs use API keys; the CLI also supports browser sign-in with `sim login`. See [Authentication](/api-reference/authentication) for key types and OAuth permissions.
+Open **Account settings → Sim API keys** for a personal key, or **Workspace settings → Sim API keys** for a workspace key. Set `SIM_API_KEY` in your server environment. See [Authentication](/api-reference/authentication) for key types, access policies, and OAuth tokens. The CLI also supports browser sign-in with `sim login`.
 </Step>
-
 <Step>
-### Find your workflow ID
+### Find the workflow ID
 
-Open a workflow in the Sim editor. The workflow ID is in the URL:
+Open the workflow in the workflow builder. Its URL contains the ID:
 
-```
+```text
 https://www.sim.ai/workspace/{workspaceId}/w/{workflowId}
 ```
 
-You can also use the [List Workflows](/api-reference/workflows/listWorkflows) endpoint to get all workflow IDs in a workspace.
+Set `WORKFLOW_ID` to that value. You can also use [List workflows](/api-reference/workflows/listWorkflows) to find IDs in a workspace.
 </Step>
-
 <Step>
-### Deploy your workflow
+### Deploy the workflow
 
-A workflow must be deployed before it can be executed via the API. Click the **Deploy** button in the editor toolbar, or use the dashboard to manage deployments.
-</Step>
+Open **Deploy** in the workflow builder and deploy the version you want to run. Deployment requires workspace **Admin** access and the applicable deployment permission.
 
+These examples run the active deployment. Draft edits take effect after you deploy an update. V2 also supports explicit manual draft execution for personal-key or OAuth callers with write access; see [Execute workflow](/api-reference/workflows/executeWorkflowV2).
+</Step>
 <Step>
-### Make your first request
+### Call and inspect the result
+
+Place named workflow input fields inside `input`. Replace the example input with fields your deployed trigger accepts.
 
 <Tabs items={['curl', 'TypeScript', 'Python']}>
   <Tab value="curl">
     ```bash
-    curl -X POST https://www.sim.ai/api/v2/workflows/{workflowId}/execute \
-      -H "Content-Type: application/json" \
-      -H "X-API-Key: YOUR_API_KEY" \
+    curl --fail-with-body -X POST \
+      "https://www.sim.ai/api/v2/workflows/$WORKFLOW_ID/execute" \
+      -H "X-API-Key: $SIM_API_KEY" \
+      -H 'Content-Type: application/json' \
       -d '{"input": {}}'
     ```
   </Tab>
   <Tab value="TypeScript">
     ```typescript
-    const response = await fetch(
-      `https://www.sim.ai/api/v2/workflows/${workflowId}/execute`,
-      {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-API-Key': process.env.SIM_API_KEY!,
-        },
-        body: JSON.stringify({ input: {} }),
-      }
-    )
-
-    const data = await response.json()
-    console.log(data.data.output)
+    const apiKey = process.env.SIM_API_KEY
+    const workflowId = process.env.WORKFLOW_ID
+    if (!apiKey || !workflowId) throw new Error('Set SIM_API_KEY and WORKFLOW_ID')
+
+    const response = await fetch(`https://www.sim.ai/api/v2/workflows/${workflowId}/execute`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
+      body: JSON.stringify({ input: {} }),
+    })
+    if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`)
+
+    const result = await response.json()
+    process.stdout.write(JSON.stringify({ status: result.data.status, output: result.data.output }))
     ```
   </Tab>
   <Tab value="Python">
     ```python
-    import requests
     import os
+    import requests
 
+    workflow_id = os.environ["WORKFLOW_ID"]
     response = requests.post(
         f"https://www.sim.ai/api/v2/workflows/{workflow_id}/execute",
-        headers={
-            "Content-Type": "application/json",
-            "X-API-Key": os.environ["SIM_API_KEY"],
-        },
+        headers={"X-API-Key": os.environ["SIM_API_KEY"]},
         json={"input": {}},
+        timeout=30,
     )
-
-    data = response.json()
-    print(data["data"]["output"])
+    response.raise_for_status()
+    result = response.json()["data"]
+    print(result["status"], result["output"])
     ```
   </Tab>
 </Tabs>
-</Step>
 
+A successful HTTP request can contain a failed workflow run. Always inspect `data.status` and `data.error`. A client timeout limits how long your application waits; it does not extend the server's execution limit or prove no run started.
+</Step>
 </Steps>
 
-## Sync vs Async Execution
-
-By default, workflow executions are **synchronous** — the API blocks until the workflow completes and returns the result directly.
+## Synchronous and asynchronous execution [#sync-vs-async-execution]
 
-For long-running workflows, use **asynchronous execution** by passing `async: true`:
+The default waits for the workflow to settle and returns a run resource. For a long-running deployed workflow, set `async: true` to receive HTTP `202` with a run ID:
 
 ```bash
-curl -X POST https://www.sim.ai/api/v2/workflows/{workflowId}/execute \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: YOUR_API_KEY" \
+curl --fail-with-body -X POST \
+  "https://www.sim.ai/api/v2/workflows/$WORKFLOW_ID/execute" \
+  -H "X-API-Key: $SIM_API_KEY" \
+  -H 'Content-Type: application/json' \
   -d '{"input": {}, "async": true}'
 ```
 
-Keyed callers can optionally provide `X-Run-Id: my-run-123` to choose the run ID. Run IDs cannot be reused; a duplicate returns `409`.
-
-This returns immediately with a `runId` and `statusUrl`:
-
 ```json
 {
   "data": {
@@ -128,20 +116,33 @@ This returns immediately with a `runId` and `statusUrl`:
 }
 ```
 
-Poll the run status endpoint until the status is terminal:
+Async requires an API key or OAuth token. It cannot be combined with streaming, manual draft execution, or output-shaping options. An optional integer `executionTimeoutSeconds` from `1` to `604800` can shorten the account's execution policy, but cannot extend it. See the [execution request](/api-reference/workflows/executeWorkflowV2) for compatible options.
+
+Set `RUN_ID` to the returned ID and poll with a delay:
 
 ```bash
-curl https://www.sim.ai/api/v2/workflows/{workflowId}/runs/{runId}?includeOutput=true \
-  -H "X-API-Key: YOUR_API_KEY"
+curl --fail-with-body \
+  "https://www.sim.ai/api/v2/workflows/$WORKFLOW_ID/runs/$RUN_ID?includeOutput=true" \
+  -H "X-API-Key: $SIM_API_KEY"
 ```
 
-<Callout type="info">
-  Execution status transitions follow: `queued` → `running` → `completed`, `failed`, `cancelled`, or `paused`. The `data.output` field is populated for completed executions when `includeOutput=true`.
-</Callout>
+| Status | Action |
+| --- | --- |
+| `queued`, `pending`, `running`, `redacting` | Continue polling; `redacting` is a transient output-redaction state |
+| `completed` | Read `data.output` when `includeOutput=true` |
+| `failed` | Inspect `data.error` |
+| `cancelled` | Stop polling |
+| `paused` | Inspect pause details and the resume condition; the workflow has not completed |
 
-## Response Format
+Runs need not pass through every state. A human pause requires submitted input; a time pause can resume automatically. See [Get workflow run](/api-reference/workflow-runs/getWorkflowRunV2) and the effective [data retention policy](/platform/enterprise/data-retention).
 
-Successful v2 responses wrap the run resource in `data`:
+Authenticated callers can send `X-Run-Id` to choose a run ID. It is a one-shot claim: reuse returns `409`, not the original response. After an uncertain enqueue or lost response, reconcile the original run ID before starting another run. A missing record does not by itself prove that no work started.
+
+For SSE tokens or a synchronous NDJSON response with heartbeats, see [API streaming](/workflows/deployment/api#streaming).
+
+## Response format
+
+Single-resource v2 JSON responses wrap the resource in `data`. For example, a synchronous execution returns:
 
 ```json
 {
@@ -150,15 +151,22 @@ Successful v2 responses wrap the run resource in `data`:
     "workflowId": "{workflowId}",
     "status": "completed",
     "output": { "result": "Hello, world!" },
+    "blockOutputs": null,
     "error": null,
+    "startedAt": "2026-10-13T12:00:00.000Z",
+    "endedAt": "2026-10-13T12:00:00.842Z",
     "durationMs": 842
   }
 }
 ```
 
-## Error Handling
+List responses use `data` as an array and include `nextCursor` when applicable. Streams and binary downloads have their own response formats.
+
+Cost units are endpoint-specific: Logs APIs report USD; Billing and workflow-run resources report credits. Read the field description before combining amounts.
 
-The API uses standard HTTP status codes. v2 errors include a stable code and human-readable message:
+## Handle failed requests [#error-handling]
+
+Rejected v2 requests use HTTP error status codes and a stable code/message envelope:
 
 ```json
 {
@@ -169,19 +177,23 @@ The API uses standard HTTP status codes. v2 errors include a stable code and hum
 }
 ```
 
-| Status | Meaning | What to do |
+| Status | Meaning | Action |
 | --- | --- | --- |
-| `400` | Invalid request parameters | Check the `details` array for specific field errors |
-| `401` | Missing or invalid API key | Verify your `X-API-Key` header |
-| `403` | Access denied | Check you have permission for this resource |
-| `404` | Resource not found | Verify the ID exists and belongs to your workspace |
-| `429` | Rate limit exceeded | Wait for the duration in the `Retry-After` header |
+| `400` | Invalid request | Check the published schema and `error.details`, when present |
+| `401` | Missing, invalid, or expired credential | Check the API key or OAuth token and its header |
+| `402` | Usage limit exceeded | Inspect billing status and account policy |
+| `403` | Access denied | Check role, scope, resource access, and permission policies |
+| `404` | Resource not found or concealed | Check the ID and selected workspace |
+| `409` | State, preview, or run-ID conflict | Follow the endpoint's conflict/reconciliation procedure |
+| `429` | Rate or capacity limit | Honor `Retry-After` before retrying an admitted-safe request |
+
+Other statuses and endpoint-specific recovery are documented in each reference. `error.details` may be a validation-issue array or an object with additional context. An execution that started and failed instead returns a run resource with `status: "failed"`.
 
 ### Unrecognized fields are rejected
 
-Every v2 endpoint validates the request against its published schema — path parameters, query string, and body — and answers `400` for any field it does not declare. A misspelled parameter is an error rather than a silent no-op, so `?limt=20` fails instead of quietly returning an unbounded list.
+V2 validates path parameters, query strings, and bodies against the published schema. Unknown fields return `400`; for example, `?limt=20` is an error. The rule also applies to endpoints with no query parameters: omit tracking tags, cache busters, and other undeclared fields.
 
-This holds for endpoints that declare no query parameters at all. Do not append tracking tags, cache busters, or other extra parameters to a v2 URL; send only what the endpoint documents.
+A validation error can look like:
 
 ```json
 {
@@ -195,28 +207,40 @@ This holds for endpoints that declare no query parameters at all. Do not append
 }
 ```
 
-<Callout type="info">
-  Use [Get Billing Status](/api-reference/billing/getBillingStatus) to inspect current credit and storage usage.
-</Callout>
+## Pagination
 
-## Rate Limits
+Paginated list endpoints, including workflows, logs, and audit logs, return an opaque `nextCursor`. Keep the workspace, filters, and sort choices the same when requesting the next page. A missing or `null` cursor means there is no next page.
 
-Rate limits depend on your subscription plan and apply separately to synchronous and asynchronous executions.
+This example requires `WORKSPACE_ID`, `SIM_API_KEY`, and `jq`:
 
-When rate limited, the API returns a `429` response with a `Retry-After` header indicating how many seconds to wait before retrying.
+```bash
+PAGE=$(curl --silent --show-error --fail-with-body --get \
+  'https://www.sim.ai/api/v2/logs' \
+  -H "X-API-Key: $SIM_API_KEY" \
+  --data-urlencode "workspaceId=$WORKSPACE_ID" \
+  --data-urlencode 'limit=20')
+
+CURSOR=$(printf '%s' "$PAGE" | jq -r '.nextCursor // empty')
+if [ -n "$CURSOR" ]; then
+  curl --fail-with-body --get 'https://www.sim.ai/api/v2/logs' \
+    -H "X-API-Key: $SIM_API_KEY" \
+    --data-urlencode "workspaceId=$WORKSPACE_ID" \
+    --data-urlencode 'limit=20' \
+    --data-urlencode "cursor=$CURSOR"
+fi
+```
 
-## Pagination
+Some endpoints return an unpaginated bounded inventory or a provider-specific partial result. Follow that endpoint's pagination and truncation fields.
 
-List endpoints (workflows, logs, audit logs) use **cursor-based pagination**:
+## Rate limits
 
-```bash
-# First page
-curl "https://www.sim.ai/api/v2/logs?limit=20" \
-  -H "X-API-Key: YOUR_API_KEY"
+V2 request limits apply to the credential and its user or workspace. Workflow execution also applies separate synchronous/asynchronous execution buckets, quota, and concurrency policy. Plan and deployment configuration determine the effective limits.
 
-# Next page — use the nextCursor from the previous response
-curl "https://www.sim.ai/api/v2/logs?limit=20&cursor=abc123" \
-  -H "X-API-Key: YOUR_API_KEY"
-```
+A rate-limited request returns `429`; `Retry-After` gives seconds to wait. Inspect [Billing status](/api-reference/billing/getBillingStatus) for a workspace's current credits and storage. Async mode does not bypass admission or usage limits.
+
+## Related docs
 
-The response includes a `nextCursor` field. When `nextCursor` is absent or `null`, you have reached the last page.
+- [Authentication](/api-reference/authentication)
+- [Python SDK](/api-reference/python) and [TypeScript SDK](/api-reference/typescript)
+- [Execute workflow](/api-reference/workflows/executeWorkflowV2)
+- [Workflow imports and workspace sync](/api-reference/workflow-sync)
diff --git a/apps/docs/content/docs/api-reference/meta.json b/apps/docs/content/docs/api-reference/meta.json
index 1d043f0872f..b39dcada178 100644
--- a/apps/docs/content/docs/api-reference/meta.json
+++ b/apps/docs/content/docs/api-reference/meta.json
@@ -5,10 +5,11 @@
     "---Getting Started---",
     "getting-started",
     "authentication",
-    "workflow-sync",
     "---SDKs---",
     "python",
     "typescript",
+    "---API guides---",
+    "workflow-sync",
     "---Endpoints---",
     "(generated)/workflows",
     "(generated)/workflow-runs",
diff --git a/apps/docs/content/docs/api-reference/python.mdx b/apps/docs/content/docs/api-reference/python.mdx
index 39aa0ed719f..632a5089019 100644
--- a/apps/docs/content/docs/api-reference/python.mdx
+++ b/apps/docs/content/docs/api-reference/python.mdx
@@ -1,768 +1,402 @@
 ---
 title: Python
+description: Execute deployed workflows from Python, poll runs, and handle SDK results.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Step, Steps } from 'fumadocs-ui/components/steps'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 
-Use the Python SDK to execute workflows from Python applications.
+Use `SimStudioClient` to execute deployed workflows from a Python application. It supports synchronous requests, server-queued asynchronous runs, rate-limit retries, and file-like inputs. Its HTTP methods are blocking; asynchronous execution does not make it an `asyncio` client.
 
-<Callout type="info">
-  The Python SDK supports Python 3.8+ with async execution support, retry helpers with exponential backoff, and usage tracking.
-</Callout>
-
-## Installation
+## Install and configure [#installation]
 
-Install the SDK using pip:
+The package requires Python `3.8+` and `requests>=2.25.0`:
 
 ```bash
 pip install simstudio-sdk
 ```
 
-## Quick Start
-
-Here's a simple example to get you started:
+Create a key in **Account settings → Sim API keys**, or use a workspace key if your administrator requires one. Keep it on your server as `SIM_API_KEY`. Set `WORKFLOW_ID` to a deployed workflow you can access. See [Authentication](/api-reference/authentication) for key types and permissions.
 
-```python
-from simstudio import SimStudioClient
+### Server compatibility
 
-# Initialize the client
-client = SimStudioClient(
-    api_key="your-api-key-here",
-    base_url="https://www.sim.ai"  # optional, defaults to https://www.sim.ai
-)
-
-# Execute a workflow
-try:
-    result = client.execute_workflow("workflow-id")
-    print("Workflow executed successfully:", result)
-except Exception as error:
-    print("Workflow execution failed:", error)
-```
+SDK `0.2.x` executes and polls through `/api/v2`. Your deployment must serve `POST /api/v2/workflows/{workflowId}/execute`; the SDK does not fall back when that route is unavailable. Upgrade an older self-hosted server, or intentionally retain `simstudio-sdk<0.2` for its legacy execution endpoints.
 
-## API Reference
+The default origin is `https://www.sim.ai`. Set `base_url` to your self-hosted deployment's origin. Versions before `0.2.1` defaulted to `https://sim.ai`; set the `www` origin explicitly when using an older SDK against Sim Cloud to avoid redirects.
 
-### SimStudioClient
+## Run a workflow [#quick-start]
 
-#### Constructor
+Use a context manager to close the HTTP session automatically:
 
 ```python
-SimStudioClient(api_key: str, base_url: str = "https://www.sim.ai")
-```
-
-**Parameters:**
-- `api_key` (str): Your Sim API key
-- `base_url` (str, optional): Base URL for the Sim API (defaults to `https://www.sim.ai`; versions before 0.2.1 default to `https://sim.ai`, which redirects to `https://www.sim.ai`, so set the `www` host explicitly on older versions)
-
-#### Methods
-
-##### execute_workflow()
-
-Execute a workflow with optional input data.
+import os
+from simstudio import SimStudioClient, SimStudioError
 
-```python
-result = client.execute_workflow(
-    "workflow-id",
-    input={"message": "Hello, world!"},
-    timeout=30.0  # 30 seconds
-)
+with SimStudioClient(
+    api_key=os.environ["SIM_API_KEY"],
+    base_url=os.getenv("SIM_BASE_URL", "https://www.sim.ai"),
+) as client:
+    try:
+        result = client.execute_workflow_sync(
+            os.environ["WORKFLOW_ID"],
+            input={"message": "Process this data"},
+            timeout=30.0,
+        )
+        if result.status == "completed":
+            print(result.output)
+            print("Duration in ms:", result.total_duration)
+        elif result.status == "paused":
+            print("The workflow is waiting to resume.")
+        else:
+            print(result.status, result.error)
+    except SimStudioError as error:
+        print(error.code, error.status, str(error))
+        raise
 ```
 
-**Parameters:**
-- `workflow_id` (str): The ID of the workflow to execute
-- `input` (dict, optional): Input data to pass to the workflow
-- `timeout` (float, optional): Timeout in seconds (default: 30.0)
-- `stream` (bool, optional): Enable streaming responses (default: False)
-- `selected_outputs` (list[str], optional): Block outputs to stream in `blockName.attribute` format (e.g., `["agent1.content"]`)
-- `async_execution` (bool, optional): Execute asynchronously (default: False)
-- `execution_timeout_seconds` (int, optional): Optional server-side async execution cap from 1 to 604800 seconds. Requires `async_execution=True` and cannot extend the account policy.
+Replace `message` with an input field defined by your deployed trigger. The SDK runs the active deployment; it does not select manual draft execution.
 
-**Returns:** `WorkflowExecutionResult | AsyncExecutionResult`
+A failed synchronous workflow returns normally with `status="failed"`, `success=False`, and `error` set. A cancelled run also returns `success=False`, often without an error. `success=True` means `completed` **or** `paused`; a pause is unfinished work. HTTP, authentication, and client timeout errors raise `SimStudioError`. This differs from the TypeScript SDK, which throws for a failed synchronous run.
 
-When `async_execution=True`, returns immediately with a `run_id` and `status_url` for polling. Otherwise, waits for completion.
+## Start an asynchronous run [#async-workflow-execution]
 
-##### get_workflow_status()
-
-Get the status of a workflow (deployment status, etc.).
+Queue a deployed run and poll its `run_id`. The initial `success=True` confirms acceptance, not completion:
 
 ```python
-status = client.get_workflow_status("workflow-id")
-print("Is deployed:", status.is_deployed)
-```
-
-**Parameters:**
-- `workflow_id` (str): The ID of the workflow
+import os
+import time
+from simstudio import AsyncExecutionResult, SimStudioClient
 
-**Returns:** `WorkflowStatus`
+waiting = {"queued", "pending", "running", "redacting"}
+workflow_id = os.environ["WORKFLOW_ID"]
 
-##### validate_workflow()
+with SimStudioClient(api_key=os.environ["SIM_API_KEY"]) as client:
+    result = client.execute_workflow(
+        workflow_id,
+        input={"message": "Process this dataset"},
+        async_execution=True,
+        execution_timeout_seconds=3600,
+    )
+    if not isinstance(result, AsyncExecutionResult):
+        raise RuntimeError("Expected an asynchronous run receipt")
 
-Validate that a workflow is ready for execution.
+    deadline = time.monotonic() + 300
+    while True:
+        run = client.get_workflow_run(workflow_id, result.run_id, include_output=True)
+        if run["status"] not in waiting:
+            break
+        if time.monotonic() >= deadline:
+            raise TimeoutError(f"Stop waiting locally; run {result.run_id} may still be active")
+        time.sleep(2)
 
-```python
-is_ready = client.validate_workflow("workflow-id")
-if is_ready:
-    # Workflow is deployed and ready
-    pass
+    if run["status"] == "completed":
+        print(run["output"])
+    elif run["status"] == "paused":
+        print("Resume condition:", run["paused"])
+    else:
+        print(run["status"], run["error"])
 ```
 
-**Parameters:**
-- `workflow_id` (str): The ID of the workflow
-
-**Returns:** `bool`
-
-##### get_workflow_run()
+The five-minute polling deadline is an application choice; it does not cancel the run. A time pause can resume automatically, while a human pause requires input. Resume can create another run attempt. Use [Get workflow run](/api-reference/workflow-runs/getWorkflowRunV2) and the [resume endpoint](/api-reference/workflow-runs/resumeWorkflowRunV2) for the current state and resume behavior.
 
-Get the status and optional outputs of a workflow execution.
+Async submission cannot include `stream=True`, `selected_outputs`, or other output-shaping options. `execution_timeout_seconds` accepts an integer from `1` to `604800`, requires async execution, and only shortens the account policy. The HTTP `timeout` remains separate.
 
-```python
-status = client.get_workflow_run("workflow-id", "run-id", include_output=True)
-print("Status:", status["status"])  # 'queued', 'running', 'completed', 'failed'
-if status["status"] == "completed":
-    print("Output:", status["output"])
-```
-
-**Parameters:**
-- `workflow_id` (str): The workflow ID
-- `run_id` (str): The run ID returned from async execution
-- `include_output` (bool, optional): Include the final output for completed executions
-- `selected_outputs` (list[str], optional): Block output selectors to include
+## Handle errors and rate limits [#error-handling]
 
-**Returns:** `Dict[str, Any]`
+`SimStudioError(message, code=None, status=None)` exposes `code` and the HTTP `status` when available. A workflow failure returned in `WorkflowExecutionResult` must be handled separately from exceptions.
 
-**Response fields:**
-- `runId` (str): The run ID
-- `workflowId` (str): The workflow ID
-- `status` (str): One of `'queued'`, `'pending'`, `'running'`, `'paused'`, `'completed'`, `'failed'`, `'cancelled'`
-- `startedAt` / `endedAt` (str): Execution timestamps
-- `durationMs` (int, optional): Duration in milliseconds
-- `output` (any, optional): The workflow output when requested for a completed execution
-- `blockOutputs` (dict, optional): Requested block outputs
-- `error` (dict, optional): Structured failure details with `code`, `message`, and optional `details`
+| Code | Meaning |
+| --- | --- |
+| `UNAUTHORIZED` | Missing, invalid, or expired credential |
+| `BAD_REQUEST` | V2 request validation failed |
+| `TIMEOUT` | The client stopped waiting |
+| `RATE_LIMIT_EXCEEDED` | SDK wrapper for an HTTP `429` |
+| `USAGE_LIMIT_EXCEEDED` | Usage policy rejected the request or run |
+| `INVALID_EXECUTION_TIMEOUT` | An unsupported or invalid async timeout option |
+| `EXECUTION_ERROR` | Transport, parsing, or execution-request failure |
+| `STATUS_ERROR`, `USAGE_ERROR` | A status or usage helper failed |
 
-##### get_job_status()
+Other server codes can pass through. V2 uses `BAD_REQUEST` for invalid JSON/request input, rather than the legacy `INVALID_JSON` branch. See [API errors](/api-reference/getting-started#error-handling).
 
-Get the status of a job created through the legacy async execution endpoint. New integrations should use `get_workflow_run()` with the run ID instead.
+`execute_with_retry` retries only rate-limit exceptions. Its defaults allow three retries after the initial attempt, with exponential delay and ±25% jitter. A supplied `Retry-After` takes precedence over the calculated delay; jitter applies to that wait too.
 
 ```python
-status = client.get_job_status("legacy-job-id")
-```
-
-##### execute_with_retry()
-
-Execute a workflow with automatic retry on rate limit errors using exponential backoff.
+import os
+from simstudio import SimStudioClient
 
-```python
-result = client.execute_with_retry(
-    "workflow-id",
-    input={"message": "Hello"},
-    timeout=30.0,
-    max_retries=3,           # Maximum number of retries
-    initial_delay=1.0,       # Initial delay in seconds
-    max_delay=30.0,          # Maximum delay in seconds
-    backoff_multiplier=2.0   # Exponential backoff multiplier
-)
+with SimStudioClient(api_key=os.environ["SIM_API_KEY"]) as client:
+    result = client.execute_with_retry(
+        os.environ["WORKFLOW_ID"],
+        input={"message": "Process this"},
+        timeout=30.0,
+        max_retries=3,
+        initial_delay=1.0,
+        max_delay=30.0,
+        backoff_multiplier=2.0,
+    )
+    print(result)
 ```
 
-**Parameters:**
-- `workflow_id` (str): The ID of the workflow to execute
-- `input` (dict, optional): Input data to pass to the workflow
-- `timeout` (float, optional): Timeout in seconds
-- `stream` (bool, optional): Enable streaming responses
-- `selected_outputs` (list, optional): Block outputs to stream
-- `async_execution` (bool, optional): Execute asynchronously
-- `max_retries` (int, optional): Maximum number of retries (default: 3)
-- `initial_delay` (float, optional): Initial delay in seconds (default: 1.0)
-- `max_delay` (float, optional): Maximum delay in seconds (default: 30.0)
-- `backoff_multiplier` (float, optional): Backoff multiplier (default: 2.0)
+`initial_delay` and `max_delay` are **seconds**. `RateLimitInfo.retry_after` is **milliseconds**. `max_delay` caps the calculated backoff, not a server-supplied wait.
 
-**Returns:** `WorkflowExecutionResult | AsyncExecutionResult`
-
-The retry logic uses exponential backoff (1s → 2s → 4s → 8s...) with ±25% jitter to prevent thundering herd. If the API provides a `retry-after` header, it will be used instead.
+<Callout type="warn">
+A client timeout or lost response does not prove the workflow never started. Avoid blindly repeating an execution that may have effects. For caller-chosen run IDs and reconciliation, use the raw v2 API described in [Getting started](/api-reference/getting-started#sync-vs-async-execution).
+</Callout>
 
-##### get_rate_limit_info()
+## Method reference [#api-reference]
 
-Get the current rate limit information from the last API response.
+### Constructor
 
-```python
-rate_limit_info = client.get_rate_limit_info()
-if rate_limit_info:
-    print("Limit:", rate_limit_info.limit)
-    print("Remaining:", rate_limit_info.remaining)
-    print("Reset:", datetime.fromtimestamp(rate_limit_info.reset))
+```text
+SimStudioClient(api_key: str, base_url: str = "https://www.sim.ai")
 ```
 
-**Returns:** `RateLimitInfo | None`
+`api_key` is required. `base_url` is an origin, without an `/api` suffix; trailing slashes are removed. The client sends the key in `X-API-Key`.
 
-##### get_usage_limits()
+### Execute
 
-Get current usage limits and quota information for your account.
+```text
+execute_workflow(workflow_id: str, input=None, *, timeout=30.0,
+    stream=None, selected_outputs=None, async_execution=None,
+    execution_timeout_seconds=None) -> WorkflowExecutionResult | AsyncExecutionResult
 
-```python
-limits = client.get_usage_limits()
-print("Sync requests remaining:", limits.rate_limit["sync"]["remaining"])
-print("Async requests remaining:", limits.rate_limit["async"]["remaining"])
-print("Current period cost:", limits.usage["currentPeriodCost"])
-print("Plan:", limits.usage["plan"])
+execute_workflow_sync(workflow_id: str, input=None, *, timeout=30.0,
+    stream=None, selected_outputs=None) -> WorkflowExecutionResult
+
+execute_with_retry(workflow_id: str, input=None, *, timeout=30.0,
+    stream=None, selected_outputs=None, async_execution=None,
+    execution_timeout_seconds=None, max_retries=3, initial_delay=1.0,
+    max_delay=30.0, backoff_multiplier=2.0)
+    -> WorkflowExecutionResult | AsyncExecutionResult
 ```
 
-**Returns:** `UsageLimits`
+All options after `*` are keyword-only. `execute_workflow_sync` forces `async_execution=False`; the retry method accepts the same execution options as `execute_workflow`.
 
-**Response structure:**
-```python
-{
-    "success": bool,
-    "rateLimit": {
-        "sync": {
-            "isLimited": bool,
-            "limit": int,
-            "remaining": int,
-            "resetAt": str
-        },
-        "async": {
-            "isLimited": bool,
-            "limit": int,
-            "remaining": int,
-            "resetAt": str
-        },
-        "authType": str  # 'api' or 'manual'
-    },
-    "usage": {
-        "currentPeriodCost": float,
-        "limit": float,
-        "plan": str  # e.g., 'free', 'pro'
-    }
-}
-```
+| Parameter | Behavior and default |
+| --- | --- |
+| `workflow_id` | Deployed workflow ID |
+| `input` | Optional value; a dictionary becomes the v2 `input` object, while a primitive or list becomes `{"input": value}` inside it; omitted/`None` becomes `{}` |
+| `timeout` | Client HTTP timeout in seconds; default `30.0` |
+| `async_execution` | Default omitted, so server execution is synchronous; `True` returns an async receipt |
+| `execution_timeout_seconds` | Async-only integer cap, `1`–`604800`; cannot extend account policy |
+| `selected_outputs` | Optional list of normalized block-name/path selectors such as `agent.content`; incompatible with async submission |
+| `stream` | Defaults omitted/false; the current SDK parser cannot consume the SSE response when `True`; use raw HTTP below |
+| `max_retries` | Retry count after the initial attempt; default `3` |
+| `initial_delay`, `max_delay` | Calculated retry delay in seconds; defaults `1.0`, `30.0` |
+| `backoff_multiplier` | Delay multiplier; default `2.0` |
 
-##### set_api_key()
+File-like objects nested in input are converted to base64. The current synchronous adapter does not expose v2 `blockOutputs`, even when `selected_outputs` is sent. Use a run read or raw HTTP when you need that map.
 
-Update the API key.
+### Read workflow deployment and runs
 
-```python
-client.set_api_key("new-api-key")
+```text
+get_workflow_status(workflow_id: str) -> WorkflowStatus
+validate_workflow(workflow_id: str) -> bool
+get_workflow_run(workflow_id: str, run_id: str, *,
+    include_output=None, selected_outputs=None) -> Dict[str, Any]
+get_job_status(job_id: str) -> Dict[str, Any]
 ```
 
-##### set_base_url()
-
-Update the base URL.
+`get_workflow_status` reads the legacy `/api/workflows/{id}/status` route. `validate_workflow` returns only its `is_deployed` flag; it returns `False` if the status request raises `SimStudioError`. It does not validate credentials, input, quota, or deployment readiness. Use the status method directly to distinguish a failed lookup from an undeployed workflow:
 
 ```python
-client.set_base_url("https://my-custom-domain.com")
+status = client.get_workflow_status("workflow-id")
+print(status.is_deployed, status.needs_redeployment)
 ```
 
-##### close()
+`get_workflow_run` reads and unwraps the v2 run resource. `include_output=True` includes final output for a completed run; default omitted/false. Run-read `selected_outputs` uses **block IDs**, as `blockId` or `blockId.path`, rather than block names. Selected block outputs are independent of `include_output`.
 
-Close the underlying HTTP session.
+`get_job_status` is for IDs created by legacy `0.1.x` async execution at `/api/jobs/{jobId}`. Use `get_workflow_run` for runs started by `0.2.x`.
 
-```python
-client.close()
+### Read limits and update the client
+
+```text
+get_rate_limit_info() -> RateLimitInfo | None
+get_usage_limits() -> UsageLimits
+set_api_key(api_key: str) -> None
+set_base_url(base_url: str) -> None
+close() -> None
 ```
 
-## Data Classes
+`get_rate_limit_info` reads cached headers from the most recent response that supplied rate information. It does not make a request. `get_usage_limits` calls the legacy account helper; see its shape below. Setters change subsequent requests. `close` closes the HTTP session; a context manager calls it automatically.
+
+## Return objects [#data-classes]
 
 ### WorkflowExecutionResult
 
-```python
-@dataclass
-class WorkflowExecutionResult:
-    success: bool
-    output: Optional[Any] = None
-    error: Optional[str] = None
-    logs: Optional[List[Any]] = None
-    metadata: Optional[Dict[str, Any]] = None
-    trace_spans: Optional[List[Any]] = None
-    total_duration: Optional[float] = None
-    status: Optional[str] = None
-```
+| Field | Python type/default | Current behavior |
+| --- | --- | --- |
+| `success` | `bool`, required | `True` only for completed or paused |
+| `status` | `Optional[str] = None` | Server status: completed, failed, paused, or cancelled |
+| `output` | `Optional[Any] = None` | Workflow output, including any returned partial result |
+| `error` | `Optional[str] = None` | Failure message, when present |
+| `metadata` | `Optional[Dict[str, Any]] = None` | SDK-built `duration`, `runId`, `startTime`, `endTime`; duration is milliseconds |
+| `total_duration` | `Optional[float] = None` | Duration in milliseconds |
+| `logs`, `trace_spans` | `Optional[list] = None` | Compatibility fields; not populated by the v2 adapter |
 
-`success` is `True` only for the `completed` and `paused` statuses. `status` carries the server's terminal status verbatim, so a cancelled run (`success=False`, `error=None`) is distinguishable from a failed one.
+Nested oversized values may be `LargeValueRef` objects with `__simLargeValueRef`, `version`, `id`, `kind`, `size`, optional `key`, `executionId`, and `preview`. Their keys are opaque server pointers, not download URLs. See [large outputs](/workflows/deployment/api#oversized-outputs).
 
 ### AsyncExecutionResult
 
-```python
-@dataclass
-class AsyncExecutionResult:
-    success: bool
-    run_id: str
-    status_url: str
-    message: str = ""
-    async_execution: bool = True
-```
+| Field | Python type/default |
+| --- | --- |
+| `success` | `bool`, required; current accepted receipts set `True` |
+| `run_id` | `str`, required |
+| `status_url` | `str`, required |
+| `message` | `str = ""`; current adapter sets `"Workflow execution queued"` |
+| `async_execution` | `bool = True` |
 
 ### WorkflowStatus
 
-```python
-@dataclass
-class WorkflowStatus:
-    is_deployed: bool
-    deployed_at: Optional[str] = None
-    needs_redeployment: bool = False
-```
+| Field | Python type/default |
+| --- | --- |
+| `is_deployed` | `bool`, required |
+| `deployed_at` | `Optional[str] = None` |
+| `needs_redeployment` | `bool = False` |
 
-### RateLimitInfo
-
-```python
-@dataclass
-class RateLimitInfo:
-    limit: int
-    remaining: int
-    reset: int
-    retry_after: Optional[int] = None
-```
+### Run dictionary
 
-### UsageLimits
+`get_workflow_run` returns the server's `data` dictionary without changing camelCase keys:
 
-```python
-@dataclass
-class UsageLimits:
-    success: bool
-    rate_limit: Dict[str, Any]
-    usage: Dict[str, Any]
-```
+| Field | Shape |
+| --- | --- |
+| `runId`, `workflowId` | String identifiers |
+| `status` | `queued`, `pending`, `running`, `redacting`, `paused`, `completed`, `failed`, or `cancelled` |
+| `trigger` | String or `None` |
+| `startedAt`, `endedAt` | ISO timestamps or `None`; queued runs report enqueue time as startedAt |
+| `durationMs` | Number or `None` |
+| `paused` | Pause details or `None`; use `pauseKind` and `resumeAt` to identify the resume condition |
+| `cost` | `{"total": number}` in credits, or `None` when unavailable/withheld |
+| `error` | Structured `code`/`message` failure, or `None` |
+| `output` | Final output when requested for a completed run, otherwise `None` |
+| `blockOutputs` | Selected block-ID/path outputs, or `None` |
+| `files` | Produced-file metadata when output is requested/available, otherwise `None` |
 
-### SimStudioError
+Each file includes `id`, `name`, byte `size`, MIME `type`, `downloadPath`, and nullable `base64`. The SDK does not expose file-inlining options; download at the returned path with an authenticated raw HTTP request. Permission policies can withhold cost or recorded output fields. See [Get workflow run](/api-reference/workflow-runs/getWorkflowRunV2) for the full contract, functional-output permission conflict, and file limits.
 
-```python
-class SimStudioError(Exception):
-    def __init__(self, message: str, code: Optional[str] = None, status: Optional[int] = None):
-        super().__init__(message)
-        self.code = code
-        self.status = status
-```
+### RateLimitInfo
 
-**Common error codes:**
-- `UNAUTHORIZED`: Invalid API key
-- `TIMEOUT`: Request timed out
-- `RATE_LIMIT_EXCEEDED`: Rate limit exceeded
-- `USAGE_LIMIT_EXCEEDED`: Usage limit exceeded
-- `EXECUTION_ERROR`: Workflow execution failed
-
-## Examples
-
-### Basic Workflow Execution
-
-<Steps>
-  <Step title="Initialize the client">
-    Set up the SimStudioClient with your API key.
-  </Step>
-  <Step title="Validate the workflow">
-    Check if the workflow is deployed and ready for execution.
-  </Step>
-  <Step title="Execute the workflow">
-    Run the workflow with your input data.
-  </Step>
-  <Step title="Handle the result">
-    Process the execution result and handle any errors.
-  </Step>
-</Steps>
+Fields are `limit: int`, `remaining: int`, `reset: int`, and `retry_after: Optional[int] = None`. V2 ISO reset headers become epoch **milliseconds**. Integer reset headers from older endpoints retain their original epoch-seconds value. For a v2 response:
 
 ```python
-import os
-from simstudio import SimStudioClient
-
-client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
-
-def run_workflow():
-    try:
-        # Check if workflow is ready
-        is_ready = client.validate_workflow("my-workflow-id")
-        if not is_ready:
-            raise Exception("Workflow is not deployed or ready")
-
-        # Execute the workflow
-        result = client.execute_workflow(
-            "my-workflow-id",
-            input={
-                "message": "Process this data",
-                "user_id": "12345"
-            }
-        )
-
-        if result.success:
-            print("Output:", result.output)
-            print("Duration:", result.metadata.get("duration") if result.metadata else None)
-        else:
-            print("Workflow failed:", result.error)
-            
-    except Exception as error:
-        print("Error:", error)
+from datetime import datetime, timezone
 
-run_workflow()
+rate = client.get_rate_limit_info()
+if rate:
+    print(rate.remaining)
+    print(datetime.fromtimestamp(rate.reset / 1000, tz=timezone.utc))
 ```
 
-### Error Handling
+Use a known response surface when converting `reset`; use `resetAt` ISO strings from the usage helper when you need a format that is unambiguous across endpoints.
 
-Handle different types of errors that may occur during workflow execution:
-
-```python
-from simstudio import SimStudioClient, SimStudioError
-import os
+### UsageLimits
 
-client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+The dataclass contains `success: bool`, `rate_limit: Dict[str, Any]`, and `usage: Dict[str, Any]`:
 
-def execute_with_error_handling():
-    try:
-        result = client.execute_workflow("workflow-id")
-        return result
-    except SimStudioError as error:
-        if error.code == "UNAUTHORIZED":
-            print("Invalid API key")
-        elif error.code == "TIMEOUT":
-            print("Workflow execution timed out")
-        elif error.code == "USAGE_LIMIT_EXCEEDED":
-            print("Usage limit exceeded")
-        elif error.code == "INVALID_JSON":
-            print("Invalid JSON in request body")
-        else:
-            print(f"Workflow error: {error}")
-        raise
-    except Exception as error:
-        print(f"Unexpected error: {error}")
-        raise
+```text
+rate_limit:
+  sync / async:
+    isLimited: bool
+    requestsPerMinute: number
+    maxBurst: number
+    remaining: number
+    resetAt: ISO timestamp
+  authType: "api" or "manual"
+usage:
+  currentPeriodCost: number (USD)
+  limit: number (USD)
+  plan: str
 ```
 
-### Context Manager Usage
-
-Use the client as a context manager to automatically handle resource cleanup:
+`requestsPerMinute` is the refill rate; `maxBurst` is the bucket capacity. There is no `rate_limit["sync"]["limit"]` field. The Python dataclass does not expose the legacy route's `storage` result.
 
 ```python
-from simstudio import SimStudioClient
-import os
-
-# Using context manager to automatically close the session
-with SimStudioClient(api_key=os.getenv("SIM_API_KEY")) as client:
-    result = client.execute_workflow("workflow-id")
-    print("Result:", result)
-# Session is automatically closed here
+limits = client.get_usage_limits()
+print("Sync remaining:", limits.rate_limit["sync"]["remaining"])
+print("Resets at:", limits.rate_limit["sync"]["resetAt"])
+print("Period cost in USD:", limits.usage["currentPeriodCost"])
 ```
 
-### Batch Workflow Execution
-
-Execute multiple workflows efficiently:
-
-```python
-from simstudio import SimStudioClient
-import os
-
-client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))   
-
-def execute_workflows_batch(workflow_data_pairs):
-    """Execute multiple workflows with different input data."""
-    results = []
-    
-    for workflow_id, input_data in workflow_data_pairs:
-        try:
-            # Validate workflow before execution
-            if not client.validate_workflow(workflow_id):
-                print(f"Skipping {workflow_id}: not deployed")
-                continue
-                
-            result = client.execute_workflow(workflow_id, input_data)
-            results.append({
-                "workflow_id": workflow_id,
-                "success": result.success,
-                "output": result.output,
-                "error": result.error
-            })
-            
-        except Exception as error:
-            results.append({
-                "workflow_id": workflow_id,
-                "success": False,
-                "error": str(error)
-            })
-    
-    return results
-
-# Example usage
-workflows = [
-    ("workflow-1", {"type": "analysis", "data": "sample1"}),
-    ("workflow-2", {"type": "processing", "data": "sample2"}),
-]
-
-results = execute_workflows_batch(workflows)
-for result in results:
-    print(f"Workflow {result['workflow_id']}: {'Success' if result['success'] else 'Failed'}")
-```
+This helper resolves account/key-owner usage and can differ from the payer for a selected workspace. For workspace credit and storage state, use [Get billing status](/api-reference/billing/getBillingStatus). Logs APIs also report USD; v2 Billing and run-resource amounts use credits.
 
-### Async Workflow Execution
+## File inputs
 
-Execute workflows asynchronously for long-running tasks:
+Include a binary file-like object under the input field your deployed trigger expects:
 
 ```python
 import os
-import time
 from simstudio import SimStudioClient
 
-client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
-
-def execute_async():
-    try:
-        # Start async execution
-        result = client.execute_workflow(
-            "workflow-id",
-            input={"data": "large dataset"},
-            async_execution=True  # Execute asynchronously
+with SimStudioClient(api_key=os.environ["SIM_API_KEY"]) as client:
+    with open("document.pdf", "rb") as document:
+        result = client.execute_workflow_sync(
+            os.environ["WORKFLOW_ID"],
+            input={"documents": [document], "query": "Summarize this document"},
         )
-
-        # Check if result is an async execution
-        if hasattr(result, 'async_execution') and result.async_execution:
-            print(f"Run ID: {result.run_id}")
-            print(f"Status endpoint: {result.status_url}")
-
-            # Poll for completion
-            status = client.get_workflow_run(
-                "workflow-id", result.run_id, include_output=True
-            )
-
-            while status["status"] in ["queued", "pending", "running"]:
-                print(f"Current status: {status['status']}")
-                time.sleep(2)  # Wait 2 seconds
-                status = client.get_workflow_run(
-                    "workflow-id", result.run_id, include_output=True
-                )
-
-            if status["status"] == "completed":
-                print("Workflow completed!")
-                print(f"Output: {status['output']}")
-                print(f"Duration: {status['durationMs']}")
-            elif status["status"] == "paused":
-                print("Workflow is paused and waiting for input or resumption.")
-            elif status["status"] == "cancelled":
-                print("Workflow was cancelled.")
-            else:
-                print(f"Workflow failed: {status['error']}")
-
-    except Exception as error:
-        print(f"Error: {error}")
-
-execute_async()
+    print(result.output)
 ```
 
-### Rate Limiting and Retry
-
-Handle rate limits automatically with exponential backoff:
+The SDK reads and base64-encodes the bytes, retaining the file name and using its `content_type` attribute when available. Otherwise MIME type defaults to `application/octet-stream`. Validate upload size and content on your backend; the execute request has a 10 MiB JSON-body limit, including base64 overhead.
 
-```python
-import os
-from simstudio import SimStudioClient, SimStudioError
+## Execute several workflows [#batch-workflow-execution]
 
-client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
+The client has no batch-execution method. A sequential loop makes one request per workflow and handles each result independently:
 
-def execute_with_retry_handling():
+```python
+for workflow_id, workflow_input in [
+    ("workflow-1", {"message": "Analyze this"}),
+    ("workflow-2", {"message": "Summarize this"}),
+]:
     try:
-        # Automatically retries on rate limit
-        result = client.execute_with_retry(
-            "workflow-id",
-            input={"message": "Process this"},
-            max_retries=5,
-            initial_delay=1.0,
-            max_delay=60.0,
-            backoff_multiplier=2.0
-        )
-
-        print(f"Success: {result}")
+        result = client.execute_workflow_sync(workflow_id, workflow_input)
+        print(workflow_id, result.status, result.output, result.error)
     except SimStudioError as error:
-        if error.code == "RATE_LIMIT_EXCEEDED":
-            print("Rate limit exceeded after all retries")
-
-            # Check rate limit info
-            rate_limit_info = client.get_rate_limit_info()
-            if rate_limit_info:
-                from datetime import datetime
-                reset_time = datetime.fromtimestamp(rate_limit_info.reset)
-                print(f"Rate limit resets at: {reset_time}")
-
-execute_with_retry_handling()
+        print(workflow_id, error.code, str(error))
 ```
 
-### Usage Monitoring
+Use this inside the configured client context. A deployment-status precheck is optional and cannot guarantee the later run will succeed.
 
-Monitor your account usage and limits:
+## Stream through HTTP [#streaming-workflow-execution]
 
-```python
-import os
-from simstudio import SimStudioClient
-
-client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
-
-def check_usage():
-    try:
-        limits = client.get_usage_limits()
-
-        print("=== Rate Limits ===")
-        print("Sync requests:")
-        print(f"  Limit: {limits.rate_limit['sync']['limit']}")
-        print(f"  Remaining: {limits.rate_limit['sync']['remaining']}")
-        print(f"  Resets at: {limits.rate_limit['sync']['resetAt']}")
-        print(f"  Is limited: {limits.rate_limit['sync']['isLimited']}")
-
-        print("\nAsync requests:")
-        print(f"  Limit: {limits.rate_limit['async']['limit']}")
-        print(f"  Remaining: {limits.rate_limit['async']['remaining']}")
-        print(f"  Resets at: {limits.rate_limit['async']['resetAt']}")
-        print(f"  Is limited: {limits.rate_limit['async']['isLimited']}")
-
-        print("\n=== Usage ===")
-        print(f"Current period cost: ${limits.usage['currentPeriodCost']:.2f}")
-        print(f"Limit: ${limits.usage['limit']:.2f}")
-        print(f"Plan: {limits.usage['plan']}")
-
-        percent_used = (limits.usage['currentPeriodCost'] / limits.usage['limit']) * 100
-        print(f"Usage: {percent_used:.1f}%")
-
-        if percent_used > 80:
-            print("⚠️  Warning: You are approaching your usage limit!")
-
-    except Exception as error:
-        print(f"Error checking usage: {error}")
-
-check_usage()
-```
-
-### Streaming Workflow Execution
-
-Execute workflows with real-time streaming responses:
+The current `0.2.x` SDK sends `stream=True` but then parses the response as JSON. It does not expose an SSE iterator; a valid SSE response fails that parser. Use raw HTTP for streaming:
 
 ```python
-from simstudio import SimStudioClient
 import os
-
-client = SimStudioClient(api_key=os.getenv("SIM_API_KEY"))
-
-def execute_with_streaming():
-    """Execute workflow with streaming enabled."""
-    try:
-        # Enable streaming for specific block outputs
-        result = client.execute_workflow(
-            "workflow-id",
-            input={"message": "Count to five"},
-            stream=True,
-            selected_outputs=["agent1.content"]  # Use blockName.attribute format
-        )
-
-        print("Workflow result:", result)
-    except Exception as error:
-        print("Error:", error)
-
-execute_with_streaming()
-```
-
-The streaming response follows the Server-Sent Events (SSE) format:
-
-```
-data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":"One"}
-
-data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":", two"}
-
-data: {"event":"done","success":true,"output":{},"metadata":{"duration":610}}
-
-data: [DONE]
-```
-
-**Flask Streaming Example:**
-
-```python
-from flask import Flask, Response, stream_with_context
 import requests
-import json
-import os
 
-app = Flask(__name__)
-
-@app.route('/stream-workflow')
-def stream_workflow():
-    """Stream workflow execution to the client."""
-
-    def generate():
-        response = requests.post(
-            'https://www.sim.ai/api/v2/workflows/WORKFLOW_ID/execute',
-            headers={
-                'Content-Type': 'application/json',
-                'X-API-Key': os.getenv('SIM_API_KEY')
-            },
-            json={
-                'input': {'message': 'Generate a story'},
-                'stream': True,
-                'selectedOutputs': ['agent1.content']
-            },
-            stream=True
-        )
-
-        for line in response.iter_lines():
-            if line:
-                decoded_line = line.decode('utf-8')
-                if decoded_line.startswith('data: '):
-                    data = decoded_line[6:]  # Remove 'data: ' prefix
-
-                    if data == '[DONE]':
-                        break
-
-                    try:
-                        parsed = json.loads(data)
-                        if 'chunk' in parsed:
-                            yield f"data: {json.dumps(parsed)}\n\n"
-                        elif parsed.get('event') == 'done':
-                            yield f"data: {json.dumps(parsed)}\n\n"
-                            print("Execution complete:", parsed.get('metadata'))
-                    except json.JSONDecodeError:
-                        pass
-
-    return Response(
-        stream_with_context(generate()),
-        mimetype='text/event-stream'
-    )
-
-if __name__ == '__main__':
-    app.run(debug=True)
+workflow_id = os.environ["WORKFLOW_ID"]
+with requests.post(
+    f"https://www.sim.ai/api/v2/workflows/{workflow_id}/execute",
+    headers={
+        "X-API-Key": os.environ["SIM_API_KEY"],
+        "X-Sim-Stream-Protocol": "agent-events-v1",
+    },
+    json={"input": {"message": "Count to five"}, "stream": True,
+          "selectedOutputs": ["agent.content"]},
+    stream=True,
+    timeout=(10, 300),
+) as response:
+    response.raise_for_status()
+    for line in response.iter_lines():
+        if line:
+            print(line.decode("utf-8"))
 ```
 
-### Environment Configuration
+This prints raw SSE. Applications must parse complete events: success ends with `{event:"final",data:...}`, failure ends with `{event:"error",...}`, then `[DONE]`. Preserve structured output and reset events; do not filter only for `chunk` or the obsolete `done` event. The protocol header enables live answer tokens and requires handling `chunk_reset`; reasoning/tool events require their separate flags.
 
-Configure the client using environment variables:
-
-<Tabs items={['Development', 'Production']}>
-  <Tab value="Development">
-    ```python
-    import os
-    from simstudio import SimStudioClient
-
-    # Development configuration
-    client = SimStudioClient(
-        api_key=os.getenv("SIM_API_KEY"),
-        base_url=os.getenv("SIM_BASE_URL", "https://www.sim.ai")
-    )
-    ```
-  </Tab>
-  <Tab value="Production">
-    ```python
-    import os
-    from simstudio import SimStudioClient
-
-    # Production configuration with error handling
-    api_key = os.getenv("SIM_API_KEY")
-    if not api_key:
-        raise ValueError("SIM_API_KEY environment variable is required")
-
-    client = SimStudioClient(
-        api_key=api_key,
-        base_url=os.getenv("SIM_BASE_URL", "https://www.sim.ai")
-    )
-    ```
-  </Tab>
-</Tabs>
+For Flask or another web backend, authenticate the caller and authorize the workflow before opening the upstream request. Forward all SSE bytes with `text/event-stream`, check upstream HTTP status before starting the downstream response, and close the upstream response if the caller disconnects. See [API streaming](/workflows/deployment/api#streaming) and the [reference client](/workflows/deployment/agent-events#reference-client) for framing and event handling.
 
-## Getting Your API Key
+## Upgrade from 0.1.x
 
-Create a key in **Account settings → Sim API keys**, or use a workspace key if your administrator requires one. See [Authentication](/api-reference/authentication) for key types and permissions. Deploy the workflow before calling it through the SDK. Keep the key in a server-side environment variable.
+`0.2.0` changed execution requests to `/api/v2`, nests named input under `input`, and sends async/timeout options in the body instead of `X-Execution-Mode` and `X-Execution-Timeout-Seconds` headers.
 
-## Requirements
+Replace `AsyncExecutionResult.job_id` with `run_id`; its old `execution_id` field is removed. Poll with `get_workflow_run(workflow_id, run_id)`, not `get_job_status`. Synchronous metadata is now SDK-built: use `metadata["runId"]` instead of the former `metadata["executionId"]`. Read `status` to distinguish failed and cancelled returns. Logs and trace spans are no longer populated by this adapter.
 
-- Python 3.8+
-- requests >= 2.25.0
+Workflow status, legacy jobs, and account usage helpers still use their original routes. This SDK does not expose every v2 operation, manual execution, resume/cancel, caller-selected run headers, or NDJSON/agent-event streaming controls.
 
-## License
+## Related docs
 
-Apache-2.0
+- [API authentication](/api-reference/authentication)
+- [TypeScript SDK](/api-reference/typescript)
+- [API getting started](/api-reference/getting-started)
+- [Get workflow run](/api-reference/workflow-runs/getWorkflowRunV2)
+- [Python package source and Apache-2.0 license](https://github.com/simstudioai/sim/tree/main/packages/python-sdk)
diff --git a/apps/docs/content/docs/api-reference/typescript.mdx b/apps/docs/content/docs/api-reference/typescript.mdx
index 9d4e9310bd3..9c23a8071ba 100644
--- a/apps/docs/content/docs/api-reference/typescript.mdx
+++ b/apps/docs/content/docs/api-reference/typescript.mdx
@@ -1,817 +1,428 @@
 ---
 title: TypeScript
+description: Execute deployed workflows from a server, poll runs, and handle SDK results.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Step, Steps } from 'fumadocs-ui/components/steps'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 
-Use the TypeScript SDK to execute workflows from server-side JavaScript or TypeScript. For browser applications, call the SDK through your authenticated backend.
+Use `SimStudioClient` from server-side JavaScript or TypeScript to execute deployed workflows. It includes TypeScript declarations, server-queued async execution, rate-limit retries, and file-input conversion. Browser applications should call an authenticated backend that keeps the Sim key private.
 
-<Callout type="info">
-  The TypeScript SDK provides full type safety, async execution support, retry helpers with exponential backoff, and usage tracking.
-</Callout>
+## Install and configure [#installation]
+
+The ESM package requires Node.js `18+`:
 
-## Installation
+```bash
+bun add simstudio-ts-sdk
+```
 
-Install the SDK using your preferred package manager:
+Create a key in **Account settings → Sim API keys**, or use a workspace key if your administrator requires one. Set `SIM_API_KEY` and `WORKFLOW_ID` in your server environment. Deploy the workflow you intend to call; SDK execution uses the active deployment. See [Authentication](/api-reference/authentication) for key types and permissions.
 
-<Tabs items={['npm', 'yarn', 'bun']}>
-  <Tab value="npm">
-    ```bash
-    npm install simstudio-ts-sdk
-    ```
-  </Tab>
-  <Tab value="yarn">
-    ```bash
-    yarn add simstudio-ts-sdk
-    ```
-  </Tab>
-  <Tab value="bun">
-    ```bash
-    bun add simstudio-ts-sdk
-    ```
-  </Tab>
-</Tabs>
+### Server compatibility
 
-## Quick Start
+SDK `0.2.x` executes and polls through `/api/v2`. Your deployment must serve `POST /api/v2/workflows/{workflowId}/execute`; the client does not fall back when that route is absent. Upgrade an older self-hosted server, or intentionally retain a `0.1.x` SDK for legacy execution.
 
-Here's a simple example to get you started:
+The default `baseUrl` is `https://www.sim.ai`. Set it to your self-hosted deployment's origin. Versions before `0.2.1` defaulted to `https://sim.ai`; set the `www` origin explicitly when using an older SDK against Sim Cloud to avoid redirects.
+
+## Run a workflow [#quick-start]
 
 ```typescript
-import { SimStudioClient } from 'simstudio-ts-sdk';
+import { SimStudioClient, SimStudioError } from 'simstudio-ts-sdk'
+
+const apiKey = process.env.SIM_API_KEY
+const workflowId = process.env.WORKFLOW_ID
+if (!apiKey || !workflowId) throw new Error('Set SIM_API_KEY and WORKFLOW_ID')
 
-// Initialize the client
 const client = new SimStudioClient({
-  apiKey: 'your-api-key-here',
-  baseUrl: 'https://www.sim.ai' // optional, defaults to https://www.sim.ai
-});
+  apiKey,
+  baseUrl: process.env.SIM_BASE_URL || 'https://www.sim.ai',
+})
 
-// Execute a workflow
 try {
-  const result = await client.executeWorkflow('workflow-id');
-  console.log('Workflow executed successfully:', result);
+  const result = await client.executeWorkflowSync(workflowId, { message: 'Process this data' })
+  const runId = result.metadata?.runId
+  if (!result.success) {
+    process.stdout.write('The workflow was cancelled.\n')
+  } else if (runId) {
+    const run = await client.getWorkflowRun(workflowId, runId, { includeOutput: true })
+    process.stdout.write(JSON.stringify({ status: run.status, output: run.output, paused: run.paused }))
+  }
 } catch (error) {
-  console.error('Workflow execution failed:', error);
+  if (error instanceof SimStudioError) {
+    process.stderr.write(`${error.code}: ${error.message}\n`)
+  }
+  throw error
 }
 ```
 
-## API Reference
+Replace `message` with a field your deployed trigger accepts. A failed synchronous run rejects with `SimStudioError`, carrying the run's error code/message. A resolved `success:false` means cancellation. `success:true` means completed **or paused**, so it does not guarantee the workflow finished. The synchronous SDK result has no `status` field; use its `metadata.runId` with `getWorkflowRun` for the exact state.
 
-### SimStudioClient
+The Python SDK instead returns a failed synchronous result normally. Both SDKs throw for rejected HTTP requests and client/transport errors.
 
-#### Constructor
+## Start an asynchronous run [#async-workflow-execution]
 
-```typescript
-new SimStudioClient(config: SimStudioConfig)
-```
-
-**Configuration:**
-- `config.apiKey` (string): Your Sim API key
-- `config.baseUrl` (string, optional): Base URL for the Sim API (defaults to `https://www.sim.ai`; versions before 0.2.1 default to `https://sim.ai`, which redirects to `https://www.sim.ai`, so set the `www` host explicitly on older versions)
-
-#### Methods
-
-##### executeWorkflow()
-
-Execute a workflow with optional input data.
+The receipt's `success:true` confirms acceptance, not completion. Poll the returned run ID:
 
 ```typescript
-const result = await client.executeWorkflow('workflow-id', { message: 'Hello, world!' }, {
-  timeout: 30000 // 30 seconds
-});
-```
-
-**Parameters:**
-- `workflowId` (string): The ID of the workflow to execute
-- `input` (any, optional): Input data to pass to the workflow
-- `options` (ExecutionOptions, optional):
-  - `timeout` (number): Timeout in milliseconds (default: 30000)
-  - `stream` (boolean): Enable streaming responses (default: false)
-  - `selectedOutputs` (string[]): Block outputs to stream in `blockName.attribute` format (e.g., `["agent1.content"]`)
-  - `async` (boolean): Execute asynchronously (default: false)
-  - `executionTimeoutSeconds` (number): Optional server-side async execution cap from 1 to 604800 seconds. Requires `async: true` and cannot extend the account policy.
-
-**Returns:** `Promise<WorkflowExecutionResult | AsyncExecutionResult>`
-
-When `async: true`, returns immediately with a `runId` and `statusUrl` for polling. Otherwise, waits for completion.
-
-##### getWorkflowStatus()
-
-Get the status of a workflow (deployment status, etc.).
-
-```typescript
-const status = await client.getWorkflowStatus('workflow-id');
-console.log('Is deployed:', status.isDeployed);
+import { setTimeout as delay } from 'node:timers/promises'
+import { SimStudioClient } from 'simstudio-ts-sdk'
+
+const apiKey = process.env.SIM_API_KEY
+const workflowId = process.env.WORKFLOW_ID
+if (!apiKey || !workflowId) throw new Error('Set SIM_API_KEY and WORKFLOW_ID')
+const client = new SimStudioClient({ apiKey })
+const waiting = new Set<string>(['queued', 'pending', 'running', 'redacting'])
+
+const receipt = await client.executeWorkflow(workflowId, { message: 'Process this dataset' }, {
+  async: true,
+  executionTimeoutSeconds: 3600,
+})
+if (!('async' in receipt) || !receipt.async) throw new Error('Expected an async run receipt')
+
+const deadline = Date.now() + 300_000
+let run = await client.getWorkflowRun(workflowId, receipt.runId, { includeOutput: true })
+while (waiting.has(run.status)) {
+  if (Date.now() >= deadline) {
+    throw new Error(`Stop waiting locally; run ${receipt.runId} may still be active`)
+  }
+  await delay(2000)
+  run = await client.getWorkflowRun(workflowId, receipt.runId, { includeOutput: true })
+}
+process.stdout.write(JSON.stringify({ status: run.status, output: run.output, error: run.error, paused: run.paused }))
 ```
 
-**Parameters:**
-- `workflowId` (string): The ID of the workflow
-
-**Returns:** `Promise<WorkflowStatus>`
+The five-minute polling deadline is an application choice and does not cancel the run. Handle `completed`, `failed`, and `cancelled` separately. Inspect a `paused` run's resume condition: time pauses can resume automatically; human pauses require input. Resume can create another attempt. See [Get workflow run](/api-reference/workflow-runs/getWorkflowRunV2) and [Resume workflow run](/api-reference/workflow-runs/resumeWorkflowRunV2).
 
-##### validateWorkflow()
+Async submission rejects `stream:true`, `selectedOutputs`, and other output-shaping options. `executionTimeoutSeconds` accepts an integer from `1` to `604800` and requires `async:true`. The effective cap is the smaller of this value and the account policy. Client `timeout` is separate and uses milliseconds.
 
-Validate that a workflow is ready for execution.
+## Handle errors and retries [#error-handling]
 
-```typescript
-const isReady = await client.validateWorkflow('workflow-id');
-if (isReady) {
-  // Workflow is deployed and ready
-}
-```
-
-**Parameters:**
-- `workflowId` (string): The ID of the workflow
+`new SimStudioError(message: string, code?: string, status?: number)` exposes a message, code, and HTTP status when available. An in-band failed run can throw without an HTTP error status.
 
-**Returns:** `Promise<boolean>`
+| Code | Meaning |
+| --- | --- |
+| `UNAUTHORIZED` | Missing, invalid, or expired credential |
+| `BAD_REQUEST` | V2 request validation failed |
+| `TIMEOUT` | The client stopped waiting |
+| `RATE_LIMIT_EXCEEDED` | SDK wrapper for HTTP `429` |
+| `USAGE_LIMIT_EXCEEDED` | A usage policy rejected the request or run |
+| `INVALID_EXECUTION_TIMEOUT` | An unsupported or invalid async timeout option |
+| `EXECUTION_ERROR` | Transport, response parsing, or execution-request failure |
+| `EXECUTION_FAILED` | Fallback code for a failed synchronous run |
+| `STATUS_ERROR`, `USAGE_ERROR` | A status or usage helper failed |
 
-##### getWorkflowRun()
+Other server error codes pass through, including block/child execution failures. V2 reports malformed JSON/request input as `BAD_REQUEST`, rather than `INVALID_JSON`. See [API errors](/api-reference/getting-started#error-handling).
 
-Get the status and optional outputs of a workflow run.
+`executeWithRetry` retries only rate-limit exceptions. By default it makes an initial attempt and up to three retries, using exponential backoff and ±25% jitter:
 
 ```typescript
-const status = await client.getWorkflowRun('workflow-id', 'run-id', {
-  includeOutput: true
-});
-console.log('Status:', status.status); // 'queued', 'running', 'completed', 'failed'
-if (status.status === 'completed') {
-  console.log('Output:', status.output);
-}
+const result = await client.executeWithRetry('workflow-id', { message: 'Process this' }, {
+  timeout: 30000,
+}, {
+  maxRetries: 3,
+  initialDelay: 1000,
+  maxDelay: 30000,
+  backoffMultiplier: 2,
+})
+process.stdout.write(JSON.stringify(result))
 ```
 
-**Parameters:**
-- `workflowId` (string): The workflow ID
-- `runId` (string): The run ID returned from async execution
-- `options.includeOutput` (boolean, optional): Include the final output for completed executions
-- `options.selectedOutputs` (string[], optional): Block output selectors to include
+All retry delays and `RateLimitInfo.retryAfter` use **milliseconds**. A supplied `Retry-After` takes precedence over calculated backoff; jitter still applies. `maxDelay` caps the calculated delay, not a server-supplied wait.
 
-**Returns:** `Promise<WorkflowRunStatus>`
-
-**Response fields:**
-- `runId` (string): The run ID
-- `workflowId` (string): The workflow ID
-- `status` (string): One of `'queued'`, `'pending'`, `'running'`, `'paused'`, `'completed'`, `'failed'`, `'cancelled'`
-- `startedAt` / `endedAt` (string): Execution timestamps
-- `durationMs` (number, nullable): Duration in milliseconds
-- `output` (any, nullable): The workflow output when requested for a completed execution
-- `blockOutputs` (object, nullable): Requested block outputs
-- `error` (object, nullable): Structured failure details with `code`, `message`, and optional `details`
+<Callout type="warn">
+A client timeout or lost response does not prove the run never started. The SDK's timeout stops waiting without aborting its fetch. Reconcile an uncertain execution before starting another run. Use raw v2 requests for caller-selected run IDs and [run-ID recovery](/api-reference/getting-started#sync-vs-async-execution).
+</Callout>
 
-##### getJobStatus()
+## Method reference [#api-reference]
 
-Get the status of a job created through the legacy async execution endpoint. New integrations should use `getWorkflowRun()` with the run ID instead.
+### Constructor
 
-```typescript
-const status = await client.getJobStatus('legacy-job-id');
+```text
+new SimStudioClient(config: SimStudioConfig)
 ```
 
-##### executeWithRetry()
+`SimStudioConfig` has required `apiKey:string` and optional `baseUrl:string`. Supply an origin without an `/api` suffix; the SDK removes trailing slashes and sends the key in `X-API-Key`.
 
-Execute a workflow with automatic retry on rate limit errors using exponential backoff.
+### Execute
 
-```typescript
-const result = await client.executeWithRetry('workflow-id', { message: 'Hello' }, {
-  timeout: 30000
-}, {
-  maxRetries: 3,           // Maximum number of retries
-  initialDelay: 1000,      // Initial delay in ms (1 second)
-  maxDelay: 30000,         // Maximum delay in ms (30 seconds)
-  backoffMultiplier: 2     // Exponential backoff multiplier
-});
+```text
+executeWorkflow(workflowId: string, input?: any, options?: ExecutionOptions)
+  -> Promise<WorkflowExecutionResult | AsyncExecutionResult>
+executeWorkflowSync(workflowId: string, input?: any, options?: SyncExecutionOptions)
+  -> Promise<WorkflowExecutionResult>
+executeWithRetry(workflowId: string, input?: any, options?: ExecutionOptions,
+  retryOptions?: RetryOptions) -> Promise<WorkflowExecutionResult | AsyncExecutionResult>
 ```
 
-**Parameters:**
-- `workflowId` (string): The ID of the workflow to execute
-- `input` (any, optional): Input data to pass to the workflow
-- `options` (ExecutionOptions, optional): Same as `executeWorkflow()`
-- `retryOptions` (RetryOptions, optional):
-  - `maxRetries` (number): Maximum number of retries (default: 3)
-  - `initialDelay` (number): Initial delay in ms (default: 1000)
-  - `maxDelay` (number): Maximum delay in ms (default: 30000)
-  - `backoffMultiplier` (number): Backoff multiplier (default: 2)
+| `ExecutionOptions` field | Behavior and default |
+| --- | --- |
+| `timeout?:number` | Client wait in milliseconds; default `30000` |
+| `async?:boolean` | Default omitted/false; true queues the active deployment |
+| `executionTimeoutSeconds?:number` | Async-only integer cap, `1`–`604800`; cannot extend account policy |
+| `selectedOutputs?:string[]` | Normalized block-name/path selectors such as `agent.content`; incompatible with async submission |
+| `stream?:boolean` | Default omitted/false; the current SDK cannot parse SSE when true; use raw HTTP below |
 
-**Returns:** `Promise<WorkflowExecutionResult | AsyncExecutionResult>`
+An object input becomes the v2 `input` object. A primitive or array is wrapped as `{input:value}` inside it; omitted/null input becomes `{}`. Nested `File` objects are converted when the runtime provides global `File`.
 
-The retry logic uses exponential backoff (1s → 2s → 4s → 8s...) with ±25% jitter to prevent thundering herd. If the API provides a `retry-after` header, it will be used instead.
+`executeWorkflowSync` forces `async:false`. `SyncExecutionOptions` excludes `async` and `executionTimeoutSeconds`. `RetryOptions` has optional `maxRetries` (default `3`), `initialDelay` (`1000` ms), `maxDelay` (`30000` ms), and `backoffMultiplier` (`2`).
 
-##### getRateLimitInfo()
+The synchronous adapter does not expose v2 `blockOutputs`, even when `selectedOutputs` is supplied. Use a run read or raw HTTP when you need the selected-output map.
 
-Get the current rate limit information from the last API response.
+### Read deployment and runs
 
-```typescript
-const rateLimitInfo = client.getRateLimitInfo();
-if (rateLimitInfo) {
-  console.log('Limit:', rateLimitInfo.limit);
-  console.log('Remaining:', rateLimitInfo.remaining);
-  console.log('Reset:', new Date(rateLimitInfo.reset * 1000));
-}
+```text
+getWorkflowStatus(workflowId: string) -> Promise<WorkflowStatus>
+validateWorkflow(workflowId: string) -> Promise<boolean>
+getWorkflowRun(workflowId: string, runId: string, options?: GetWorkflowRunOptions)
+  -> Promise<WorkflowRunStatus>
+getJobStatus(taskId: string) -> Promise<JobStatusResult>
 ```
 
-**Returns:** `RateLimitInfo | null`
-
-##### getUsageLimits()
-
-Get current usage limits and quota information for your account.
+`getWorkflowStatus` reads the legacy `/api/workflows/{id}/status` route. `validateWorkflow` returns only `isDeployed`, and returns false if the status lookup fails. It does not verify credentials, inputs, quotas, or deployment readiness. Use the status method directly to distinguish a failed lookup from an undeployed workflow:
 
 ```typescript
-const limits = await client.getUsageLimits();
-console.log('Sync requests remaining:', limits.rateLimit.sync.remaining);
-console.log('Async requests remaining:', limits.rateLimit.async.remaining);
-console.log('Current period cost:', limits.usage.currentPeriodCost);
-console.log('Plan:', limits.usage.plan);
+const deployment = await client.getWorkflowStatus('workflow-id')
+process.stdout.write(JSON.stringify(deployment))
 ```
 
-**Returns:** `Promise<UsageLimits>`
+`GetWorkflowRunOptions` contains `includeOutput?:boolean` and `selectedOutputs?:string[]`. Output is omitted/null by default; request it with `includeOutput:true` for a completed run. Run-read selectors use **block IDs**, as `blockId` or `blockId.path`, instead of block names. Selected block outputs are independent of `includeOutput`.
 
-**Response structure:**
-```typescript
-{
-  success: boolean
-  rateLimit: {
-    sync: {
-      isLimited: boolean
-      limit: number
-      remaining: number
-      resetAt: string
-    }
-    async: {
-      isLimited: boolean
-      limit: number
-      remaining: number
-      resetAt: string
-    }
-    authType: string  // 'api' or 'manual'
-  }
-  usage: {
-    currentPeriodCost: number
-    limit: number
-    plan: string  // e.g., 'free', 'pro'
-  }
-}
-```
+`getJobStatus` polls IDs created by legacy `0.1.x` async execution at `/api/jobs/{taskId}`. Use `getWorkflowRun` for runs started by `0.2.x`.
 
-##### setApiKey()
+### Read limits and update the client
 
-Update the API key.
-
-```typescript
-client.setApiKey('new-api-key');
+```text
+getRateLimitInfo() -> RateLimitInfo | null
+getUsageLimits() -> Promise<UsageLimits>
+setApiKey(apiKey: string) -> void
+setBaseUrl(baseUrl: string) -> void
 ```
 
-##### setBaseUrl()
+`getRateLimitInfo` reads cached headers from the most recent response that supplied rate information; it makes no request. `getUsageLimits` calls the legacy account helper. Setters affect subsequent requests.
 
-Update the base URL.
+## Return types [#types]
 
-```typescript
-client.setBaseUrl('https://my-custom-domain.com');
-```
-
-## Types
+The SDK supplies declarations for these types. Arbitrary workflow input/output and log fields are not schema-typed by the client.
 
 ### WorkflowExecutionResult
 
-```typescript
-interface WorkflowExecutionResult {
-  success: boolean;
-  output?: any;
-  error?: string;
-  logs?: any[];
-  metadata?: {
-    duration?: number;
-    runId?: string;
-    [key: string]: any;
-  };
-  traceSpans?: any[];
-  totalDuration?: number;
-}
-```
+| Field | Declared type | Current adapter behavior |
+| --- | --- | --- |
+| `success` | `boolean` | True for completed/paused; false for cancelled; failed rejects |
+| `executionId` | Optional `string` | V2 run ID |
+| `output` | Optional `any` | Workflow output |
+| `error` | Optional `string` | Returned message when present |
+| `metadata` | Optional object | `duration`, `executionId`, `runId`, `startTime`, `endTime`; permits other keys |
+| `totalDuration` | Optional `number` | Duration in milliseconds |
+| `logs`, `traceSpans` | Optional `any[]` | Compatibility fields; not populated by the v2 adapter |
+
+Metadata's duration is an optional number in milliseconds; identifiers/timestamps are optional strings. The current synchronous type has no `status` property.
 
 ### AsyncExecutionResult
 
-```typescript
-interface AsyncExecutionResult {
-  success: boolean;
-  runId: string;
-  statusUrl: string;
-  message: string;
-  async: true;
-}
-```
+Fields are `success:boolean`, `runId:string`, `statusUrl:string`, `message:string`, and `async:true`. The adapter sets `success:true` and `message:'Workflow execution queued'` for a `202` receipt.
 
 ### WorkflowStatus
 
-```typescript
-interface WorkflowStatus {
-  isDeployed: boolean;
-  deployedAt?: string;
-  needsRedeployment: boolean;
-}
-```
-
-### RateLimitInfo
+Fields are `isDeployed:boolean`, optional `deployedAt:string`, `needsRedeployment:boolean`, and the optional compatibility field `isPublished:boolean`. The current status endpoint does not populate `isPublished`.
 
-```typescript
-interface RateLimitInfo {
-  limit: number;
-  remaining: number;
-  reset: number;
-  retryAfter?: number;
-}
-```
+### WorkflowRunStatus
 
-### UsageLimits
+The server resource returned by `getWorkflowRun` includes:
 
-```typescript
-interface UsageLimits {
-  success: boolean;
-  rateLimit: {
-    sync: {
-      isLimited: boolean;
-      limit: number;
-      remaining: number;
-      resetAt: string;
-    };
-    async: {
-      isLimited: boolean;
-      limit: number;
-      remaining: number;
-      resetAt: string;
-    };
-    authType: string;
-  };
-  usage: {
-    currentPeriodCost: number;
-    limit: number;
-    plan: string;
-  };
-}
-```
+| Field | Shape |
+| --- | --- |
+| `runId`, `workflowId` | Strings |
+| `status` | queued, pending, running, redacting, paused, completed, failed, or cancelled |
+| `trigger` | String or null |
+| `startedAt`, `endedAt` | ISO timestamp or null; queued startedAt is enqueue time |
+| `durationMs` | Number or null |
+| `paused` | Pause-detail object or null; inspect `pauseKind` and `resumeAt` |
+| `cost` | `{total:number}` in credits, or null when unavailable/withheld |
+| `error` | `WorkflowExecutionError` with code/message and optional details, or null |
+| `output` | Requested completed-run output, otherwise null |
+| `blockOutputs` | Selected block-ID/path values, or null |
+| `files` | Produced-file metadata when output is requested/available, otherwise null |
 
-### SimStudioError
+The `0.2.x` exported interface currently omits `redacting` and `files`, although the runtime returns the server object unchanged. The polling example uses a string set so it can wait through redaction without asserting an unsupported type. The interface declares `paused` and `blockOutputs` as nullable records, and the other fields with the nullability shown above.
 
-```typescript
-class SimStudioError extends Error {
-  code?: string;
-  status?: number;
-}
-```
+Files have `id`, `name`, byte `size`, MIME `type`, `downloadPath`, and nullable `base64`. The SDK exposes no file-inlining options; use the returned download path with an authenticated HTTP request. Permission policies can withhold costs or recorded outputs. See [Get workflow run](/api-reference/workflow-runs/getWorkflowRunV2) for the full contract, functional-output permission conflict, and file limits.
 
-**Common error codes:**
-- `UNAUTHORIZED`: Invalid API key
-- `TIMEOUT`: Request timed out
-- `RATE_LIMIT_EXCEEDED`: Rate limit exceeded
-- `USAGE_LIMIT_EXCEEDED`: Usage limit exceeded
-- `EXECUTION_ERROR`: Workflow execution failed
-
-## Examples
-
-### Basic Workflow Execution
-
-<Steps>
-  <Step title="Initialize the client">
-    Set up the SimStudioClient with your API key.
-  </Step>
-  <Step title="Validate the workflow">
-    Check if the workflow is deployed and ready for execution.
-  </Step>
-  <Step title="Execute the workflow">
-    Run the workflow with your input data.
-  </Step>
-  <Step title="Handle the result">
-    Process the execution result and handle any errors.
-  </Step>
-</Steps>
+### JobStatusResult
 
-```typescript
-import { SimStudioClient } from 'simstudio-ts-sdk';
+The legacy type has `taskId:string`, `status:string`, optional `metadata:Record<string,unknown>`, `output:unknown`, and `error:string`. It describes legacy job polling, not a v2 run receipt.
 
-const client = new SimStudioClient({
-  apiKey: process.env.SIM_API_KEY!
-});
-
-async function runWorkflow() {
-  try {
-    // Check if workflow is ready
-    const isReady = await client.validateWorkflow('my-workflow-id');
-    if (!isReady) {
-      throw new Error('Workflow is not deployed or ready');
-    }
-
-    // Execute the workflow
-    const result = await client.executeWorkflow('my-workflow-id', {
-        message: 'Process this data',
-        userId: '12345'
-    });
-
-    if (result.success) {
-      console.log('Output:', result.output);
-      console.log('Duration:', result.metadata?.duration);
-    } else {
-      console.error('Workflow failed:', result.error);
-    }
-  } catch (error) {
-    console.error('Error:', error);
-  }
-}
+### LargeValueRef
 
-runWorkflow();
-```
+Oversized nested output can contain a placeholder with required `__simLargeValueRef:true`, `version:1`, `id:string`, `kind:'array'|'object'|'string'|'json'`, and `size:number`. Optional fields are `key:string`, `executionId:string`, and `preview:unknown`. These storage keys are opaque server pointers, not download URLs. See [large outputs](/workflows/deployment/api#oversized-outputs).
 
-### Error Handling
+### RateLimitInfo
 
-Handle different types of errors that may occur during workflow execution:
+Fields are `limit:number`, `remaining:number`, `reset:number`, and optional `retryAfter:number`. V2 ISO reset headers become epoch **milliseconds**; older integer headers retain their epoch-seconds value. For v2:
 
 ```typescript
-import { SimStudioClient, SimStudioError } from 'simstudio-ts-sdk';
-
-const client = new SimStudioClient({
-  apiKey: process.env.SIM_API_KEY!
-});
-
-async function executeWithErrorHandling() {
-  try {
-    const result = await client.executeWorkflow('workflow-id');
-    return result;
-  } catch (error) {
-    if (error instanceof SimStudioError) {
-      switch (error.code) {
-        case 'UNAUTHORIZED':
-          console.error('Invalid API key');
-          break;
-        case 'TIMEOUT':
-          console.error('Workflow execution timed out');
-          break;
-        case 'USAGE_LIMIT_EXCEEDED':
-          console.error('Usage limit exceeded');
-          break;
-        case 'INVALID_JSON':
-          console.error('Invalid JSON in request body');
-          break;
-        default:
-          console.error('Workflow error:', error.message);
-      }
-    } else {
-      console.error('Unexpected error:', error);
-    }
-    throw error;
-  }
+const rate = client.getRateLimitInfo()
+if (rate) {
+  process.stdout.write(`${rate.remaining} remaining; reset ${new Date(rate.reset).toISOString()}\n`)
 }
 ```
 
-### Environment Configuration
-
-Configure the client using environment variables:
-
-<Tabs items={['Development', 'Production']}>
-  <Tab value="Development">
-    ```typescript
-    import { SimStudioClient } from 'simstudio-ts-sdk';
-
-    // Development configuration
-    const apiKey = process.env.SIM_API_KEY;
-    if (!apiKey) {
-      throw new Error('SIM_API_KEY environment variable is required');
-    }
-
-    const client = new SimStudioClient({
-      apiKey,
-      baseUrl: process.env.SIM_BASE_URL // optional
-    });
-    ```
-  </Tab>
-  <Tab value="Production">
-    ```typescript
-    import { SimStudioClient } from 'simstudio-ts-sdk';
-
-    // Production configuration with validation
-    const apiKey = process.env.SIM_API_KEY;
-    if (!apiKey) {
-      throw new Error('SIM_API_KEY environment variable is required');
-    }
-
-    const client = new SimStudioClient({
-      apiKey,
-      baseUrl: process.env.SIM_BASE_URL || 'https://www.sim.ai'
-    });
-    ```
-  </Tab>
-</Tabs>
-
-### Node.js Express Integration
-
-Integrate with an Express.js server:
+Use a known response surface when converting reset values. The usage helper's `resetAt` ISO strings avoid the mixed legacy units.
 
-```typescript
-import express from 'express';
-import { SimStudioClient } from 'simstudio-ts-sdk';
-
-const app = express();
-const client = new SimStudioClient({
-  apiKey: process.env.SIM_API_KEY!
-});
-
-app.use(express.json());
-
-app.post('/execute-workflow', async (req, res) => {
-  try {
-    const { workflowId, input } = req.body;
-    
-    const result = await client.executeWorkflow(workflowId, input, {
-      timeout: 60000
-    });
-
-    res.json({
-      success: true,
-      data: result
-    });
-  } catch (error) {
-    console.error('Workflow execution error:', error);
-    res.status(500).json({
-      success: false,
-      error: error instanceof Error ? error.message : 'Unknown error'
-    });
-  }
-});
-
-app.listen(3000, () => {
-  console.log('Server running on port 3000');
-});
-```
-
-### Next.js API Route
+### UsageLimits
 
-Use with Next.js API routes:
+```text
+success: boolean
+rateLimit:
+  sync / async:
+    isLimited: boolean
+    requestsPerMinute: number
+    maxBurst: number
+    remaining: number
+    resetAt: string (ISO timestamp)
+  authType: string (server values "api" or "manual")
+usage:
+  currentPeriodCost: number (USD)
+  limit: number (USD)
+  plan: string
+storage:
+  usedBytes: number
+  limitBytes: number
+  percentUsed: number
+```
+
+`requestsPerMinute` is the refill rate; `maxBurst` is the bucket capacity. There is no `rateLimit.sync.limit` field.
 
 ```typescript
-// pages/api/workflow.ts
-import { NextApiRequest, NextApiResponse } from 'next';
-import { SimStudioClient } from 'simstudio-ts-sdk';
-
-const client = new SimStudioClient({
-  apiKey: process.env.SIM_API_KEY!
-});
-
-export default async function handler(
-  req: NextApiRequest,
-  res: NextApiResponse
-) {
-  if (req.method !== 'POST') {
-    return res.status(405).json({ error: 'Method not allowed' });
-  }
-
-  try {
-    const { workflowId, input } = req.body;
-
-    const result = await client.executeWorkflow(workflowId, input, {
-      timeout: 30000
-    });
-
-    res.status(200).json(result);
-  } catch (error) {
-    console.error('Error executing workflow:', error);
-    res.status(500).json({
-      error: 'Failed to execute workflow'
-    });
-  }
-}
+const limits = await client.getUsageLimits()
+process.stdout.write(JSON.stringify({
+  remaining: limits.rateLimit.sync.remaining,
+  resetAt: limits.rateLimit.sync.resetAt,
+  periodCostUSD: limits.usage.currentPeriodCost,
+  storageBytes: limits.storage.usedBytes,
+}))
 ```
 
-### Browser Usage
-
-Keep the Sim API key on your server. A browser application should call an authenticated backend endpoint that checks which workflow the user can run, then calls the SDK. The [Next.js API Route](#nextjs-api-route) example shows where the server-side SDK call belongs; add your application authentication and authorization before executing a workflow.
+This legacy helper resolves account/key-owner usage and can differ from the selected workspace's payer. Use [Get billing status](/api-reference/billing/getBillingStatus) for workspace credits/storage. Logs APIs also report USD; v2 Billing and run-resource amounts use credits. If calculating a usage percentage, handle a zero limit before dividing.
 
-### File Upload
+## File inputs [#file-upload]
 
-File objects are automatically detected and converted to base64 format. Include them in your input under the field name matching your workflow's API trigger input format.
+The SDK recursively converts global `File` objects to:
 
-The SDK converts File objects to this format:
 ```typescript
-{
+const inlineFile = {
   type: 'file',
-  data: 'data:mime/type;base64,base64data',
-  name: 'filename',
-  mime: 'mime/type'
+  data: 'data:application/pdf;base64,BASE64_BYTES',
+  name: 'document.pdf',
+  mime: 'application/pdf',
 }
 ```
 
-Alternatively, you can manually provide files using the URL format:
+You can also supply a URL file:
+
 ```typescript
-{
+const urlFile = {
   type: 'url',
-  data: 'https://example.com/file.pdf',
-  name: 'file.pdf',
-  mime: 'application/pdf'
+  data: 'https://example.com/document.pdf',
+  name: 'document.pdf',
+  mime: 'application/pdf',
 }
 ```
 
-Run file uploads on your backend after authenticating the caller and validating the upload. For example, in Node.js:
-
-```typescript
-import { SimStudioClient } from 'simstudio-ts-sdk';
-import { readFile } from 'node:fs/promises';
+Place files under the input field your deployed trigger expects. Run uploads on the backend after authenticating the caller and validating size/content. Base64 overhead counts toward the execute endpoint's 10 MiB JSON-body limit.
 
-const client = new SimStudioClient({ apiKey: process.env.SIM_API_KEY! });
-const fileBuffer = await readFile('./document.pdf');
-const file = new File([fileBuffer], 'document.pdf', { type: 'application/pdf' });
+For automatic conversion, this example requires **Node.js 20+**, where `File` is global:
 
-const result = await client.executeWorkflow('workflow-id', {
+```typescript
+import { readFile } from 'node:fs/promises'
+import { SimStudioClient } from 'simstudio-ts-sdk'
+
+const apiKey = process.env.SIM_API_KEY
+const workflowId = process.env.WORKFLOW_ID
+if (!apiKey || !workflowId) throw new Error('Set SIM_API_KEY and WORKFLOW_ID')
+const client = new SimStudioClient({ apiKey })
+const bytes = await readFile('./document.pdf')
+const file = new File([new Uint8Array(bytes)], 'document.pdf', { type: 'application/pdf' })
+const result = await client.executeWorkflowSync(workflowId, {
   documents: [file],
-  query: 'Summarize this document'
-});
+  query: 'Summarize this document',
+})
+process.stdout.write(JSON.stringify(result.output))
 ```
 
+On Node.js 18, use a serialized base64/URL object. Importing `File` from `node:buffer` only in the caller does not satisfy the SDK's global-File detection.
 
+## Use from a web backend [#browser-usage]
 
+Keep the key on the server. Authenticate the application caller, resolve a workflow they may run, validate the input, and only then call the SDK. A trusted server key does not authorize every browser caller to run every workflow.
 
-### Async Workflow Execution
-
-Execute workflows asynchronously for long-running tasks:
+This helper is the SDK call to use after those checks:
 
 ```typescript
-import { SimStudioClient, AsyncExecutionResult } from 'simstudio-ts-sdk';
-
-const client = new SimStudioClient({
-  apiKey: process.env.SIM_API_KEY!
-});
-
-async function executeAsync() {
-  try {
-    // Start async execution
-    const result = await client.executeWorkflow('workflow-id', { data: 'large dataset' }, {
-      async: true  // Execute asynchronously
-    });
-
-    // Check if result is an async execution
-    if ('async' in result && result.async) {
-      console.log('Run ID:', result.runId);
-      console.log('Status endpoint:', result.statusUrl);
-
-      // Poll for completion
-      let status = await client.getWorkflowRun('workflow-id', result.runId, {
-        includeOutput: true
-      });
-
-      while (status.status === 'queued' || status.status === 'pending' || status.status === 'running') {
-        console.log('Current status:', status.status);
-        await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
-        status = await client.getWorkflowRun('workflow-id', result.runId, {
-          includeOutput: true
-        });
-      }
-
-      if (status.status === 'completed') {
-        console.log('Workflow completed!');
-        console.log('Output:', status.output);
-        console.log('Duration:', status.durationMs);
-      } else if (status.status === 'paused') {
-        console.log('Workflow is paused and waiting for input or resumption.');
-      } else if (status.status === 'cancelled') {
-        console.log('Workflow was cancelled.');
-      } else {
-        console.error('Workflow failed:', status.error);
-      }
-    }
-  } catch (error) {
-    console.error('Error:', error);
-  }
+async function executeAuthorizedWorkflow(workflowId: string, input: Record<string, unknown>) {
+  return client.executeWorkflowSync(workflowId, input, { timeout: 60000 })
 }
-
-executeAsync();
 ```
 
-### Rate Limiting and Retry
+### Express integration [#nodejs-express-integration]
 
-Handle rate limits automatically with exponential backoff:
+Call the helper from a POST handler after authentication and authorization middleware. Parse JSON with a request-size limit, map rejected SDK requests to an appropriate HTTP status, and preserve cancellation/paused state instead of wrapping every resolved result as completed success.
 
-```typescript
-import { SimStudioClient, SimStudioError } from 'simstudio-ts-sdk';
+### Next.js API route
 
-const client = new SimStudioClient({
-  apiKey: process.env.SIM_API_KEY!
-});
-
-async function executeWithRetryHandling() {
-  try {
-    // Automatically retries on rate limit
-    const result = await client.executeWithRetry('workflow-id', { message: 'Process this' }, {}, {
-      maxRetries: 5,
-      initialDelay: 1000,
-      maxDelay: 60000,
-      backoffMultiplier: 2
-    });
-
-    console.log('Success:', result);
-  } catch (error) {
-    if (error instanceof SimStudioError && error.code === 'RATE_LIMIT_EXCEEDED') {
-      console.error('Rate limit exceeded after all retries');
-
-      // Check rate limit info
-      const rateLimitInfo = client.getRateLimitInfo();
-      if (rateLimitInfo) {
-        console.log('Rate limit resets at:', new Date(rateLimitInfo.reset * 1000));
-      }
-    }
-  }
-}
-```
+Call the same helper from an authenticated server route. In a Pages Router API handler, reject methods other than POST with `405`; in either router, authorize workflow selection before execution. Set the server's `SIM_API_KEY` environment variable and keep it out of browser bundles.
 
-### Usage Monitoring
+## Stream through HTTP [#streaming-workflow-execution]
 
-Monitor your account usage and limits:
+The current `0.2.x` SDK sends `stream:true` but unconditionally parses JSON. It has no SSE iterator/callback and cannot consume a valid SSE response. Use raw HTTP instead:
 
 ```typescript
-import { SimStudioClient } from 'simstudio-ts-sdk';
-
-const client = new SimStudioClient({
-  apiKey: process.env.SIM_API_KEY!
-});
-
-async function checkUsage() {
-  try {
-    const limits = await client.getUsageLimits();
-
-    console.log('=== Rate Limits ===');
-    console.log('Sync requests:');
-    console.log('  Limit:', limits.rateLimit.sync.limit);
-    console.log('  Remaining:', limits.rateLimit.sync.remaining);
-    console.log('  Resets at:', limits.rateLimit.sync.resetAt);
-    console.log('  Is limited:', limits.rateLimit.sync.isLimited);
-
-    console.log('\nAsync requests:');
-    console.log('  Limit:', limits.rateLimit.async.limit);
-    console.log('  Remaining:', limits.rateLimit.async.remaining);
-    console.log('  Resets at:', limits.rateLimit.async.resetAt);
-    console.log('  Is limited:', limits.rateLimit.async.isLimited);
-
-    console.log('\n=== Usage ===');
-    console.log('Current period cost: $' + limits.usage.currentPeriodCost.toFixed(2));
-    console.log('Limit: $' + limits.usage.limit.toFixed(2));
-    console.log('Plan:', limits.usage.plan);
-
-    const percentUsed = (limits.usage.currentPeriodCost / limits.usage.limit) * 100;
-    console.log('Usage: ' + percentUsed.toFixed(1) + '%');
-
-    if (percentUsed > 80) {
-      console.warn('⚠️  Warning: You are approaching your usage limit!');
-    }
-  } catch (error) {
-    console.error('Error checking usage:', error);
-  }
-}
-
-checkUsage();
-```
-
-### Streaming Workflow Execution
-
-Execute workflows with real-time streaming responses:
-
-```typescript
-import { SimStudioClient } from 'simstudio-ts-sdk';
-
-const client = new SimStudioClient({
-  apiKey: process.env.SIM_API_KEY!
-});
-
-async function executeWithStreaming() {
-  try {
-    // Enable streaming for specific block outputs
-    const result = await client.executeWorkflow('workflow-id', { message: 'Count to five' }, {
-      stream: true,
-      selectedOutputs: ['agent1.content'] // Use blockName.attribute format
-    });
-
-    console.log('Workflow result:', result);
-  } catch (error) {
-    console.error('Error:', error);
+const apiKey = process.env.SIM_API_KEY
+const workflowId = process.env.WORKFLOW_ID
+if (!apiKey || !workflowId) throw new Error('Set SIM_API_KEY and WORKFLOW_ID')
+
+const response = await fetch(`https://www.sim.ai/api/v2/workflows/${workflowId}/execute`, {
+  method: 'POST',
+  headers: {
+    'X-API-Key': apiKey,
+    'Content-Type': 'application/json',
+    'X-Sim-Stream-Protocol': 'agent-events-v1',
+  },
+  body: JSON.stringify({ input: { message: 'Count to five' }, stream: true,
+    selectedOutputs: ['agent.content'] }),
+})
+if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`)
+if (!response.body) throw new Error('Missing SSE response body')
+
+const decoder = new TextDecoder()
+const reader = response.body.getReader()
+try {
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    process.stdout.write(decoder.decode(value, { stream: true }))
   }
+  process.stdout.write(decoder.decode())
+} finally {
+  reader.releaseLock()
 }
 ```
 
-The streaming response follows the Server-Sent Events (SSE) format:
-
-```
-data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":"One"}
-
-data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":", two"}
-
-data: {"event":"done","success":true,"output":{},"metadata":{"duration":610}}
-
-data: [DONE]
-```
+This prints raw SSE; network chunks are not necessarily complete events. Success emits `{event:"final",data:...}`, failure emits `{event:"error",...}`, then `[DONE]`. Preserve output and reset events. The protocol header enables live answer tokens and requires `chunk_reset` handling; thinking/tool events require their separate flags. For browsers, have the authenticated backend forward the upstream stream, check HTTP status, and close/cancel it on disconnect.
 
-For browser streaming, have your authenticated backend forward the Sim SSE response. Keep the Sim API key on the backend, check the upstream response status, and parse complete SSE events across network chunks. See [streaming responses](/workflows/deployment/api#streaming) for the event format.
+See [API streaming](/workflows/deployment/api#streaming) and the [reference client](/workflows/deployment/agent-events#reference-client) for event parsing and protocol details. Synchronous NDJSON heartbeats are a separate transport selected by `Accept: application/x-ndjson`; the SDK has no option for that header.
 
-## Getting Your API Key
+## Upgrade from 0.1.x
 
-Create a key in **Account settings → Sim API keys**, or use a workspace key if your administrator requires one. See [Authentication](/api-reference/authentication) for key types and permissions. Deploy the workflow before calling it through the SDK. Keep the key in a server-side environment variable.
+`0.2.0` changed execution to `/api/v2`, nests named input under `input`, and puts async/timeout options in the body instead of `X-Execution-Mode` and `X-Execution-Timeout-Seconds` headers.
 
-## Requirements
+Replace `AsyncExecutionResult.jobId` with `runId`; its old `executionId` is removed. Poll with `getWorkflowRun(workflowId, runId)`, not `getJobStatus`. Failed synchronous runs now reject; move failure handling from a `!result.success` branch into `catch`. A resolved false result means cancellation; true also includes paused runs.
 
-- Node.js 16+
-- TypeScript 5.0+ (for TypeScript projects)
+Workflow status, legacy jobs, and account usage helpers still use their original routes. This SDK does not expose every v2 operation, manual draft execution, resume/cancel, caller-selected run headers, or NDJSON/agent-event streaming controls.
 
-## License
+## Related docs
 
-Apache-2.0
+- [API authentication](/api-reference/authentication)
+- [Python SDK](/api-reference/python)
+- [API getting started](/api-reference/getting-started)
+- [Get workflow run](/api-reference/workflow-runs/getWorkflowRunV2)
+- [TypeScript package source and Apache-2.0 license](https://github.com/simstudioai/sim/tree/main/packages/ts-sdk)
diff --git a/apps/docs/content/docs/api-reference/workflow-sync.mdx b/apps/docs/content/docs/api-reference/workflow-sync.mdx
index dd0fe5249e0..37424406c96 100644
--- a/apps/docs/content/docs/api-reference/workflow-sync.mdx
+++ b/apps/docs/content/docs/api-reference/workflow-sync.mdx
@@ -1,51 +1,59 @@
 ---
 title: Workflow imports and workspace sync
-description: Use the v2 preview, mapping, apply, and operation-status protocol from an API or CLI client
+description: Preview destination choices, apply imports or workspace sync, and reconcile their operations.
 ---
 
-An automated client exports or inspects the source, previews destination choices, applies the reviewed request, and polls its operation. The [CLI workflow guide](/cli/workflow-sync) follows this same v2 protocol; the server owns authorization, remapping, atomic writes, and durable completion for both surfaces.
+Import an exported workflow as a draft, or fork and synchronize workspaces through the v2 preview-and-apply protocol. Preview the destination bindings, apply those exact choices, then poll the returned operation to verify copies and deployment readiness. The [CLI workflow guide](/cli/workflow-sync) uses the same protocol.
 
-## CLI and HTTP interfaces
+## Choose the interface [#cli-and-http-interfaces]
 
-Paths below are relative to `/api/v2`. `{workspaceId}` is the explicitly selected current workspace.
+HTTP paths below are relative to `/api/v2`. `{workspaceId}` is the current workspace you explicitly selected.
 
 | CLI command | HTTP request |
 | --- | --- |
-| `workflows export <id> --include-references` | `GET /workflows/{workflowId}/export?includeReferences=true` |
-| `workflows import-preview` / `workflows import` | `POST /workflows/import/preview` / `POST /workflows/import` |
-| `workspaces fork-availability` / `lineage` | `GET /workspaces/{workspaceId}/fork/availability` / `.../fork/lineage` |
-| `workspaces children` / `fork-resources` | `GET /workspaces/{workspaceId}/fork/children` / `.../fork/resources?kind=tables` |
-| `workspaces fork-preview` / `fork` | `POST /workspaces/{workspaceId}/fork/preview` / `.../fork` |
-| `workspaces push-preview` / `push --yes` | `POST /workspaces/{workspaceId}/fork/push/preview` / `.../fork/push` |
-| `workspaces pull-preview` / `pull --yes` | `POST /workspaces/{workspaceId}/fork/pull/preview` / `.../fork/pull` |
-| `workspaces mappings get` / `mappings update` | `GET` / `PUT /workspaces/{workspaceId}/fork/mappings` |
-| `selectors list` / `selectors get` | `POST /selectors/list` / `POST /selectors/get` |
-| `workspaces operations get <id>` / `operations wait <id>` | `GET /workspaces/{workspaceId}/operations/{operationId}`; wait polls this endpoint |
-| `workspaces operations list` | `GET /workspaces/{workspaceId}/operations` |
+| `sim workflows export <id> --include-references` | `GET /workflows/{workflowId}/export?includeReferences=true` |
+| `sim workflows import-preview` / `sim workflows import` | `POST /workflows/import/preview` / `POST /workflows/import` |
+| `sim workspaces fork-availability` / `sim workspaces lineage` | `GET /workspaces/{workspaceId}/fork/availability` / `.../fork/lineage` |
+| `sim workspaces children` / `sim workspaces fork-resources` | `GET /workspaces/{workspaceId}/fork/children` / `.../fork/resources?kind=tables` |
+| `sim workspaces fork-preview` / `sim workspaces fork` | `POST /workspaces/{workspaceId}/fork/preview` / `.../fork` |
+| `sim workspaces push-preview` / `sim workspaces push --yes` | `POST /workspaces/{workspaceId}/fork/push/preview` / `.../fork/push` |
+| `sim workspaces pull-preview` / `sim workspaces pull --yes` | `POST /workspaces/{workspaceId}/fork/pull/preview` / `.../fork/pull` |
+| `sim workspaces mappings get` / `sim workspaces mappings update` | `GET` / `PUT /workspaces/{workspaceId}/fork/mappings` |
+| `sim selectors list` / `sim selectors get` | `POST /selectors/list` / `POST /selectors/get` |
+| `sim workspaces operations get <id>` / `sim workspaces operations wait <id>` | `GET /workspaces/{workspaceId}/operations/{operationId}`; wait polls this endpoint |
+| `sim workspaces operations list` | `GET /workspaces/{workspaceId}/operations` |
 
-The generated [sync preview reference](/api-reference/workspace-sync/previewWorkspacePull) documents every field; its sidebar includes rollback, unlink, and exclusion endpoints. Children, resource discovery, mappings, and operations are paginated; follow `nextCursor` without changing the query's scope or filters.
+The [sync reference](/api-reference/workspace-sync/previewWorkspacePull) documents fields and includes rollback, unlink, and exclusions. Children, resource discovery, mappings, and operations are paginated: follow `nextCursor` with the same scope and filters.
 
-## Permissions
+## Prerequisites and access [#permissions]
 
-Send a personal API key in `X-API-Key`, or an OAuth access token in `Authorization: Bearer …`. Existing workspace policies, credential access, permission groups, Enterprise/self-hosting gates, and workspace creation limits still apply.
+Set `BASE_URL` to your deployment origin, without `/api/v2`. Use a personal API key in `X-API-Key`, or an OAuth token in `Authorization: Bearer`. Examples use separate authorized source/destination keys where applicable. Replace all example resource IDs with IDs from your export and destination.
 
 | Operation | Required access |
 | --- | --- |
 | Export | Workflow read access |
-| Import preview and apply | Destination write access; binding credentials also requires an acting user with credential access |
-| Fork discovery, preview, and creation | Source workspace admin |
-| Sync preview/apply and mapping read/update | Admin on both workspaces on a direct fork edge |
-| Rollback / unlink | Target admin / acting-side admin, respectively |
+| Import preview/apply | Destination write access; binding credentials also requires an acting user with credential access |
+| Fork discovery, preview, creation | Source workspace Admin; creation policy must allow a new workspace |
+| Sync preview/apply and mapping read/update | Admin on both workspaces on a direct parent/child fork edge |
+| Rollback / unlink | Target Admin / acting-side Admin, respectively |
 | Selector discovery | Read access in the discovery workspace and access to the selected credential |
 | Operation get/list | Read access in the receipt workspace |
 
-Workspace API keys can import where existing authoring policy allows, but cannot bind credentials, administer forks, or execute selectors. Do not substitute a key owner for an acting user. OAuth import/fork/sync previews require `api:write`, even though preview does not commit changes. Export, fork discovery, mapping reads, selectors, and operation reads use `api:read`.
+Workspace keys can import where authoring policy allows, but cannot bind credentials, administer forks, or execute selectors. The key owner is not a substitute for an acting user. Workspace policies, permission groups, credential access, and workspace creation limits still apply.
 
-## Portable imports
+OAuth import/fork/sync previews require `api:write`, even though previews do not commit changes. Export, fork discovery, mapping reads, selectors, and operation reads use `api:read`.
 
-Default exports remain sanitized. `includeReferences=true` adds a versioned manifest of registered resource IDs and source occurrences, including nested tools. It does not include secret values. Imported provenance and source IDs are labels; they never grant access to an alleged source workspace.
+Forking and sync require the owning organization's Enterprise entitlement on billing-enabled deployments. On billing-disabled deployments, deployment configuration must enable forking. Check [Fork availability](/api-reference/workspace-sync/getWorkspaceForkAvailability) before starting. Imports, selector discovery, and operation reports have their own access rules and do not inherit the fork-specific gate.
 
-Set `BASE_URL` to your deployment, and use an authorized key for each workspace. Raw HTTP returns `{ "data": ... }`; the CLI unwraps single-resource results. Extract the export payload before saving it:
+## Import a portable workflow [#portable-imports]
+
+### Export and inspect the source
+
+Default exports clear registered credential fields and workspace bindings. `includeReferences=true` adds a versioned manifest of resource IDs and their source occurrences, including nested tools. The manifest contains identities, not secret values. Unresolved environment-variable references remain, and ordinary workflow variable values or literal configuration can remain in the full export. Inspect the payload before sharing it.
+
+Source IDs and imported provenance are labels; they do not grant access to an alleged source workspace. `includeWorkspaceBindings=true` can retain non-secret bindings for a same-workspace round trip; otherwise configure any required bindings reported by import.
+
+Raw HTTP wraps the result in `data`; the CLI unwraps a single resource. Extract that payload before saving it:
 
 ```sh
 curl -sS --fail-with-body \
@@ -54,7 +62,9 @@ curl -sS --fail-with-body \
   | jq '.data' > workflow.json
 ```
 
-Save destination mappings as `import-mappings.json`, replacing the example IDs with manifest and destination resource IDs:
+### Map destination resources
+
+Save `import-mappings.json`, using source IDs from the manifest and authorized destination IDs:
 
 ```json
 [
@@ -63,7 +73,9 @@ Save destination mappings as `import-mappings.json`, replacing the example IDs w
 ]
 ```
 
-`mappings` applies to every occurrence of a resource's `kind` and `sourceId`. For older exports, `bindings` can address individual registered occurrences. Its entries are flat objects, without `sourceId` or an `occurrence` wrapper:
+`mappings` applies to every occurrence of a resource's `kind` and `sourceId`. Destination type, provider, and parent/child compatibility are validated. `targetId:null` requests clearing and cannot satisfy a required binding. Conflicting instructions for one occurrence are rejected.
+
+For older exports, `bindings` addresses individual registered occurrences. Entries are flat objects, without `sourceId` or an `occurrence` wrapper:
 
 ```json
 [
@@ -78,7 +90,9 @@ Save destination mappings as `import-mappings.json`, replacing the example IDs w
 ]
 ```
 
-A top-level field uses `valuePath: []`. Other registered encodings are `array`, `csv`, `files`, and `environment`; multi-value occurrences can include `positions`. Use the actual registered occurrence, rather than inventing paths. Conflicting instructions for one occurrence are rejected. `targetId: null` requests clearing; it cannot satisfy a required binding. Destination type, provider, and parent-child compatibility are validated.
+A top-level field uses `valuePath:[]`. Other registered encodings are `array`, `csv`, `files`, and `environment`; multi-value occurrences can include `positions`. Use a returned registered occurrence rather than inventing a path.
+
+### Preview and complete configuration
 
 Build one request file and preview it:
 
@@ -93,7 +107,7 @@ curl -sS --fail-with-body -H "X-API-Key: $DESTINATION_API_KEY" \
   "$BASE_URL/api/v2/workflows/import/preview" > import-preview.json
 ```
 
-Inspect `data.unresolvedBindings`, `data.configuration`, `data.unresolvedConfiguration`, and `data.discovery`. Dependent choices use a different shape from bindings:
+Inspect `data.unresolvedBindings`, `data.configuration`, `data.unresolvedConfiguration`, and `data.discovery`. Dependent configuration choices have a different shape from bindings:
 
 ```json
 [
@@ -101,7 +115,9 @@ Inspect `data.unresolvedBindings`, `data.configuration`, `data.unresolvedConfigu
 ]
 ```
 
-Add these as `dependentValues` to `import-request.json` and preview again. For a field with `multiSelect: true`, `value` is a comma-separated string of selected IDs. For credential-backed selectors, discover options in the import's destination workspace using the returned `selectorKey` and `context`:
+Add them as `dependentValues` to the request and preview again. A `multiSelect:true` field uses a comma-separated string of selected IDs.
+
+For credential-backed selectors, use the import destination workspace and the preview's `selectorKey` and `context` to discover options:
 
 ```sh
 curl -sS --fail-with-body -H "X-API-Key: $DESTINATION_API_KEY" \
@@ -111,9 +127,13 @@ curl -sS --fail-with-body -H "X-API-Key: $DESTINATION_API_KEY" \
   "$BASE_URL/api/v2/selectors/list"
 ```
 
-Selector lists return `{ "data": [...], "nextCursor": null, "truncated": false }`; check both pagination and truncation. Detail uses `/selectors/get` with the same scope/context and an `id`. MCP tools use `mcp.tools` with `mcpServerId`. A missing OAuth connection can require human authorization; changing a resource ID cannot create that connection.
+Selector lists return `{ "data": [...], "nextCursor": null, "truncated": false }`; check pagination **and** truncation. Detail uses `/selectors/get` with the same workspace/key/context and an `id`. MCP tool discovery uses `mcp.tools` with `mcpServerId`. A missing OAuth connection can require human authorization; changing a resource ID cannot create the connection.
+
+Keep selector workspace, key, context, and search unchanged when paging. A changed provider page can return `409`, requiring discovery to restart. Detail can return `data:null` for a missing choice or `413` when verification exceeds provider bounds. See [List selector](/api-reference/workspace-sync/listSelector) and [Get selector](/api-reference/workspace-sync/getSelector).
+
+### Apply the reviewed import
 
-When `data.ready` is true, save a stable request ID and apply the exact reviewed choices:
+When `data.ready` is true, choose a stable `IMPORT_REQUEST_ID` for this mutation and retain it with the complete request. Apply the exact reviewed choices and fingerprint:
 
 ```sh
 jq --arg requestId "$IMPORT_REQUEST_ID" \
@@ -126,15 +146,34 @@ curl -sS --fail-with-body -H "X-API-Key: $DESTINATION_API_KEY" \
   "$BASE_URL/api/v2/workflows/import" > import-result.json
 ```
 
-Mapped import creates a draft, its graph, variables, required inline custom tools, and receipt atomically. Remapping precedes graph ID regeneration; the result includes `idMap`. Plain imports without mapping options retain their earlier behavior and return no operation receipt. Supplying mapping options, even empty arrays, requires `requestId` and `previewFingerprint`.
+Mapped import atomically creates the draft, graph, variables, required inline custom tools, and receipt. Remapping happens before graph ID regeneration; the result includes `idMap`. Plain imports without mapping options retain their earlier behavior and return no operation receipt. Supplying mapping options, even empty arrays, requires `requestId` and `previewFingerprint`.
 
-## Fork and sync
+Imported workflows remain drafts. Check reported configuration and deploy before using ordinary deployed execution.
 
-Fork preview and apply share `{ "name": "Review environment", "copy": { "tables": ["source-table"] } }`. Apply adds `requestId` and the preview's fingerprint. Eligible deployed source workflows become child drafts; resource copies must be selected explicitly.
+## Fork a workspace [#fork-and-sync]
 
-Push sends deployed workflows from the current workspace to `otherWorkspaceId`. Pull sends them from `otherWorkspaceId` to the current workspace. Either endpoint works from either side of the direct parent/child edge.
+Fork preview and apply start with the same choices:
 
-For example, save this as `sync-request.json` for a pull into the workspace in the URL:
+```json
+{
+  "name": "Review environment",
+  "copy": { "tables": ["source-table"] }
+}
+```
+
+POST the request to `/workspaces/{workspaceId}/fork/preview`. Inspect its plan and fingerprint, then POST the same choices to `/workspaces/{workspaceId}/fork` with a stable `requestId` and the returned `previewFingerprint`.
+
+Eligible deployed source workflows become **child drafts**. Resources are copied only when selected explicitly. Fork creation uses `copy`; sync uses `copyResources`. Fork `copy.files` contains workspace file IDs, while sync `copyResources.files` contains storage keys. Credentials and secret values are not copied. Inspect destination configuration before deploying a fork's workflows.
+
+## Push or pull a sync
+
+Push sends deployed workflows from the current workspace to `otherWorkspaceId`. Pull brings them from `otherWorkspaceId` into the current workspace. Either endpoint can run from either side of a direct parent/child edge, with Admin access to both.
+
+Sync can create target workflows, replace mapped target workflows, and archive mapped targets whose source was deleted or archived. It schedules deployments of the admitted snapshots. An undeployed source alone does not archive its mapped target. Excluded workflows remain excluded; review target replacements and retiring trigger URLs before apply.
+
+### Select mappings and copies
+
+For a pull into the workspace in the URL, save `sync-request.json`:
 
 ```json
 {
@@ -149,30 +188,31 @@ For example, save this as `sync-request.json` for a pull into the workspace in t
 }
 ```
 
-Sync mappings use edge `resourceType` names, such as `oauth_credential`, `service_account_credential`, `knowledge_base`, `custom_tool`, or `sandbox`; imports use `kind`, such as `credential`, `knowledge-base`, or `custom-tool`. Sync workflow identity is system-managed. Pick a knowledge document through its parent KB's dependent selector instead of writing a `knowledge_document` edge mapping.
+Sync mappings use edge `resourceType` names such as `oauth_credential`, `service_account_credential`, `knowledge_base`, `custom_tool`, and `sandbox`. Imports instead use `kind` names such as `credential`, `knowledge-base`, and `custom-tool`. Workflow identity is system-managed. Choose a knowledge document through its parent knowledge base's dependent selector instead of writing a `knowledge_document` edge mapping.
+
+Mapping inspection requires `otherWorkspaceId` and `direction` query fields. Read rows include a storage `id`; writes accept only `resourceType`, `sourceId`, and `targetId`. Project a read page with `jq '[.data[] | {resourceType, sourceId, targetId}]'` before reusing it, and follow `nextCursor` for further pages.
 
-Mapping inspection requires `otherWorkspaceId` and `direction` in its query. Read rows also contain a storage `id`; write requests accept only `resourceType`, `sourceId`, and `targetId`. Project a page with `jq '[.data[] | {resourceType, sourceId, targetId}]'` before reusing its mappings, and follow `nextCursor` to collect further pages.
+Preview does not persist inline mappings. Apply saves them in the sync transaction. Dependent overrides use source workflow/block/field identities, including original nested-tool indices. Omitting `dependentValues` reuses saved choices; supplying it replaces choices for affected workflows, and `[]` clears them. Values in a target draft alone are not saved sync configuration.
 
-Preview never saves inline mappings. Apply persists them with the sync transaction. Dependent overrides use source workflow/block/field identities, including original nested tool indices. Omission reuses saved choices; providing `dependentValues` replaces those choices for affected workflows, and `[]` clears them. Target draft values alone are not saved sync configuration.
+`dropReferences` acknowledges references deleted in the source; it cannot discard live source resources.
+
+### Preview and inspect trigger choices
 
 ```sh
 curl -sS --fail-with-body -H "X-API-Key: $SIM_API_KEY" \
   -H 'Content-Type: application/json' --data @sync-request.json \
   "$BASE_URL/api/v2/workspaces/$CURRENT_WORKSPACE/fork/pull/preview" > sync-preview.json
+```
 
-jq --arg requestId "$SYNC_REQUEST_ID" \
-  --arg fingerprint "$(jq -er '.data.previewFingerprint' sync-preview.json)" \
-  '. + {requestId: $requestId, previewFingerprint: $fingerprint, confirm: true}' \
-  sync-request.json > sync-apply.json
+Review `unresolvedBindings`, `configuration`, planned workflow actions, and retiring URLs. For selector discovery, use each configuration field's `discoveryWorkspaceId`: the source when its parent will be copied, the destination when mapped. Pass the returned context and preview any changed choices again. `ready:true` means the apply plan is ready, not that all destination deployments will be ready.
 
-curl -sS --fail-with-body -H "X-API-Key: $SIM_API_KEY" \
-  -H 'Content-Type: application/json' --data @sync-apply.json \
-  "$BASE_URL/api/v2/workspaces/$CURRENT_WORKSPACE/fork/pull" > sync-result.json
-```
+`triggerSlots` uses stable `sourceWorkflowId` and `sourceBlockId` identities and includes `ownPath`, `adoptablePaths`, and `defaultAdoptPath`:
 
-Review `unresolvedBindings`, `configuration`, planned workflow actions, and retiring trigger URLs before apply. Use each configuration field's `discoveryWorkspaceId` for `/selectors/list` or `/selectors/get`: source when its parent will be copied, destination when mapped. Pass its returned context and re-preview any changed choices. A ready preview is not a deployment-readiness report.
+- A slot with `ownPath` preserves that URL and accepts no override.
+- An arriving trigger can adopt an offered retiring path, or request a new URL with `adoptPath:null`.
+- Unknown identities, duplicate choices, or paths outside the slot's candidates are rejected. Candidates stay within the same target workflow and provider.
 
-`triggerSlots` lists stable `sourceWorkflowId` and `sourceBlockId` identities, `ownPath`, `adoptablePaths`, and `defaultAdoptPath`. A slot with `ownPath` preserves that URL and accepts no override. For an arriving trigger, `triggerMappings` can select an offered retiring path or `null` to request a new URL. Include the same choices on preview and apply:
+Include the same `triggerMappings` choices on preview and apply:
 
 ```json
 [
@@ -180,21 +220,32 @@ Review `unresolvedBindings`, `configuration`, planned workflow actions, and reti
 ]
 ```
 
-Unknown source identities, duplicate choices, and paths outside that slot's candidates are rejected. Adoption candidates stay within the same target workflow and provider; do not construct them from a different workflow's URL.
+### Apply the sync
 
-Copy selections use `copy` for fork creation and `copyResources` for sync. Fork `copy.files` contains workspace file IDs; sync `copyResources.files` contains storage keys. Credentials and secret values are not copied. `dropReferences` only acknowledges references deleted in the source; it cannot discard live source resources.
+Choose a stable `SYNC_REQUEST_ID` and preserve the exact reviewed request:
 
-Sync replaces eligible target workflows and schedules deployment of the admitted snapshots. Exclusions remain in effect. A deleted source can archive its mapped target; an undeployed source does not. Rollback restores the latest target sync's prior deployed versions, with no promise to restore arbitrary drafts or undo all resource copies.
+```sh
+jq --arg requestId "$SYNC_REQUEST_ID" \
+  --arg fingerprint "$(jq -er '.data.previewFingerprint' sync-preview.json)" \
+  '. + {requestId: $requestId, previewFingerprint: $fingerprint, confirm: true}' \
+  sync-request.json > sync-apply.json
 
-## Receipts, polling, and retries
+curl -sS --fail-with-body -H "X-API-Key: $SIM_API_KEY" \
+  -H 'Content-Type: application/json' --data @sync-apply.json \
+  "$BASE_URL/api/v2/workspaces/$CURRENT_WORKSPACE/fork/pull" > sync-result.json
+```
 
-Apply returns a single-resource envelope. This is an example completed sync report:
+For push, use `/fork/push/preview` and `/fork/push` with the same direction-relative rules. `confirm:true` acknowledges target replacement. Changes to mappings or trigger choices require another preview before apply.
+
+## Verify operations and recover [#receipts-polling-and-retries]
+
+Apply returns a single-resource envelope. A completed sync report can look like:
 
 ```json
 {
   "data": {
     "operationId": "operation-id",
-    "requestId": "release-2026-09-09",
+    "requestId": "release-2026-10-13",
     "workspaceId": "current-workspace",
     "kind": "workspace_pull",
     "applied": true,
@@ -215,7 +266,13 @@ Apply returns a single-resource envelope. This is an example completed sync repo
 }
 ```
 
-Always poll under the returned `workspaceId`. Import receipts belong to the destination. Fork-creation receipts belong to the source on which `/fork` ran. Push/pull receipts belong to the current workspace in the request URL, including a push that changes the other workspace.
+Poll under the **returned** `workspaceId`:
+
+| Mutation | Receipt workspace |
+| --- | --- |
+| Import | Destination |
+| Fork creation | Source workspace on which `/fork` ran |
+| Push/pull | Current workspace in the request URL, including a push that changes the other workspace |
 
 ```sh
 OPERATION_ID=$(jq -er '.data.operationId' sync-result.json)
@@ -225,14 +282,28 @@ curl -sS --fail-with-body -H "X-API-Key: $SIM_API_KEY" \
   "$BASE_URL/api/v2/workspaces/$OPERATION_WORKSPACE/operations/$OPERATION_ID"
 ```
 
-Poll with a delay while `status` is `processing`. Terminal outcomes are `completed`, `completed_with_warnings`, `requires_configuration`, and `failed`. Inspect `issues`, `copyProgress`, `deployments[].ready`, `pendingComponents`, and `triggerUrlChanges`. `applied: true` remains true after a follow-up failure: the transaction committed. Completed imports and forks remain drafts; a completed sync requires checking its admitted deployment results before treating the destination as ready.
+Poll with a delay while `status` is `processing`. Terminal outcomes are `completed`, `completed_with_warnings`, `requires_configuration`, and `failed`. Inspect `issues`, `copyProgress`, `deployments[].ready`, `pendingComponents`, and `triggerUrlChanges`.
+
+`applied:true` stays true after a follow-up failure: the transaction committed. Completed imports and forks remain drafts. For sync, check the **exact admitted deployments** in the receipt before treating the destination as ready.
+
+### Retry an uncertain response
+
+Request IDs deduplicate within the receipt workspace. Retain the complete apply request and original ID. Identical authorized retries return the original operation before preview-freshness checks. A changed payload under the same ID, stale preview, or blocked apply returns HTTP `409` with the v2 error envelope; other invalid input can return `400`. Follow-up failures appear on a committed operation.
+
+After an uncertain response, retry the identical request with its original ID, or query `GET /workspaces/{workspaceId}/operations?requestId=...`. Lists return `{ "data": [...], "nextCursor": ... }`; use operation get for refreshed copy/deployment status.
+
+If a stale preview is refused before commit, obtain a new preview and use a new request ID for the revised request. Do not replace a lost-response request with a fresh ID just to retry; that can create another mutation.
 
-Request IDs deduplicate within the receipt workspace. Retain the complete apply request: identical authorized retries return the original operation before checking preview freshness. A changed payload under the same ID, a stale preview, or blocked apply returns HTTP `409` with `{ "error": { "code": "CONFLICT", "message": "...", "details": {} } }`. Other invalid inputs can return `400`; follow-up failures are reported on a committed operation.
+## Rollback, unlink, and exclusions
 
-After an uncertain response, retry the identical request with the original ID, or query `GET /workspaces/{workspaceId}/operations?requestId=...`. Lists return `{ "data": [...], "nextCursor": ... }`; use operation get for refreshed completion status. If a stale preview is refused before commit, obtain a new preview and use a new request ID for the revised request. Never replace a lost-response request with a fresh ID merely to retry.
+[Rollback](/api-reference/workspace-sync/rollbackWorkspaceFork) restores the latest inbound sync's prior deployed versions. It can archive sync-created workflows and restore archived targets, but does not promise to restore arbitrary target drafts or undo all resource copies. Inspect `pendingActivations`; another rollback attempt may be needed to finish activation.
 
-## What the test harness covers
+[Unlink](/api-reference/workspace-sync/unlinkWorkspaceFork) removes the direct relationship and its mappings while retaining workspace content. [Exclusions](/api-reference/workspace-sync/updateWorkspaceForkExclusions) keep selected workflows out of later syncs.
 
-Run `bun run test:workflow-sync` from the Sim repository with Bun, dependencies, and Docker available. It creates disposable PostgreSQL 17, exercises actual authorization, API-key authentication, v2 HTTP adapters, CLI subprocesses, graph/receipt transactions, locks, and deployment outbox workers, then removes the database. Tests cover concurrent retries, stale previews, atomic refusal, immutable deployment snapshots, exclusions, pagination, and copy-worker recovery.
+## Related docs
 
-External provider options and failures use controlled fixtures; the separate realtime process uses an authenticated loopback fixture. This validates the platform protocol rather than proving every provider account is connected. Verify provider authorization and destination deployment readiness in the environment you intend to use. Migration safety is checked separately from this fresh-schema harness.
+- [CLI workflow sync](/cli/workflow-sync)
+- [Workspace forking](/platform/enterprise/forks)
+- [Import preview](/api-reference/workspace-sync/previewWorkflowImport)
+- [Operation status](/api-reference/workspace-sync/getWorkspaceOperation)
+- [Workflow-sync repository harness](https://github.com/simstudioai/sim/tree/main/apps/sim/lib/workspaces/__integration__) for `bun run test:workflow-sync`, disposable PostgreSQL, fixture boundaries, and contributor prerequisites
diff --git a/apps/docs/content/docs/chat/files.mdx b/apps/docs/content/docs/chat/files.mdx
index db82437d9d9..f49af135ef8 100644
--- a/apps/docs/content/docs/chat/files.mdx
+++ b/apps/docs/content/docs/chat/files.mdx
@@ -1,118 +1,113 @@
 ---
-title: Files & documents
-description: Upload, create, edit, and generate files — documents, presentations, images, and more.
+title: Files and documents
+description: Process attachments and create or edit workspace documents, presentations, images, and charts.
 ---
 
-import { Image } from '@/components/ui/image'
-import { Video } from '@/components/ui/video'
-import { FAQ } from '@/components/ui/faq'
+Ask Sim to read an attachment, create a deliverable, or edit a workspace file. Name the output format and filename when you need a saved result. Supported generation and processing capabilities depend on your deployment.
 
-<Video src="mothership/files-pipeline-deals-summarizer.mp4" width={700} height={450} />
+## Attach and save files [#uploading-files-to-the-workspace]
 
-Describe a document, presentation, image, or visualization and Sim creates it — streaming the content live into the resource panel as it writes. Attach any file to your message and Sim reads it, processes it, and saves it to your workspace.
+Drag a supported file into the input, paste it, or select **Attach file**. Chat supports images, PDFs, text and code files, JSON, XML, and other supported document formats.
 
-## Uploading Files to the Workspace
+Attachments are stored under `uploads/` and stay readable within the conversation. They do not automatically appear in workspace **Files** or workflow file listings. Ask Sim to save a copy when you need a workspace file:
 
-Attach any file directly to your message in Chat — drag it into the input, paste it, or click the attachment icon. Sim reads the file as context and saves it to your workspace.
+- "Summarize this document and extract the action items." Attach the document.
+- "Create a table from this CSV." Attach the CSV.
+- "Add this PDF to the Product Docs knowledge base." Attach the PDF.
+- "Describe this design mockup and write code for the layout." Attach the image.
+- "Save this attachment to workspace Files as source-data.json."
 
-Use this to:
-- Hand Sim a document and ask it to process, summarize, or extract data from it
-- Upload a CSV and have it create a table from it
-- Drop in a PDF and ask Sim to turn it into a knowledge base document
-- Attach a design mockup and ask Sim to describe it or generate code from it
+Sim can also download a file from an accessible URL: "Download the JSON at [URL] and save it as source-data.json."
 
-An attached file is stored under `uploads/` and readable by Sim for the rest of the conversation, but it does not appear in the Files panel and is not listed for workflows. Ask Sim to save a copy into workspace Files if you need it there. Sim can also fetch a file directly from a URL and save it for you: "Download the JSON at [URL] and save it to the workspace."
+A successful upload does not mean every format's contents have been parsed. For a file without a supported reader, Sim may need to process the original bytes with code. ZIP archives must be extracted before their contents can be read.
 
-## Creating Documents
+Direct uploads are deliberate input and are not automatically scanned for secrets. For stored files, Chat can mask tracked secret values or withhold content it cannot safely check. Your viewer can still open a file that Chat cannot read or receive as a rendered preview. Creating or returning a sharing link through Chat can also be refused.
 
-Sim can write any text-based file — markdown, plain text, code files, CSV, JSON, or any other format:
+## Create a text file [#creating-documents]
 
-- "Write a technical spec for the new auth system as a markdown file"
-- "Create a CSV of our test accounts with columns for name, email, and plan tier"
-- "Write a Python script that calls our workflow API and processes the response"
-- "Draft a postmortem for the outage last Tuesday and save it as a markdown file"
-- "Write a personalized outbound email for Acme Corp based on their recent funding announcement"
-- "Draft a weekly ops digest summarizing workflow run counts, errors, and top failures for the past 7 days"
+Sim can write Markdown, plain text, code, CSV, and JSON files. Ask for the content and its destination:
 
-Files are saved to your workspace and accessible from the Files panel in the sidebar.
+- "Write a technical spec for the new auth system as auth-spec.md."
+- "Create test-accounts.csv with name, email, and plan tier columns."
+- "Write a Python script that calls our workflow API and processes the response."
+- "Save a postmortem for last Tuesday's outage as outage-review.md."
+- "Draft an outbound email for Acme Corp based on its recent funding announcement and save it as acme-email.md."
+- "Save a weekly ops digest with run counts, errors, and top failures from the past seven days."
 
-## Editing Existing Files
+Saved workspace files appear in **Files** and can open in the resource panel. Text edits can appear as Sim writes; generated binary documents and media appear when their artifacts are ready.
 
-Open a file using `@filename` or the **+** menu, then describe the change:
+## Edit an existing file [#editing-existing-files]
 
-- "Update the pricing section to reflect the new tiers"
-- "Refactor this Python script to use async/await"
-- "Add a section on error handling to this spec"
-- "Rewrite the introduction of this report to be more concise"
+Open the file with an `@`-mention or the **+** menu and describe the change:
 
-## Presentations
+- "Update the pricing section with these new tiers: [details]."
+- "Refactor this Python script to use async/await."
+- "Add error handling to this spec and shorten the introduction."
 
-<Image src="/static/mothership/pptx-example.png" alt="Chat resource panel showing a generated Mothership-Use-Cases.pptx file open with the title slide and first use case slide visible" width={900} height={487} />
+Name the existing file when you want Sim to update it rather than create another copy. Editing requires the relevant file access.
 
-Sim can generate `.pptx` files:
+## Generate documents and presentations [#presentations]
 
-- "Create a pitch deck for Q3 review — 8 slides covering growth, retention, and roadmap"
-- "Turn this research report into a 10-slide presentation"
-- "Build a deck that walks through our API onboarding flow"
-- "Build a battle card deck for our top 3 competitors — one slide each covering positioning, pricing, and how we win"
-- "Create an account plan for Acme Corp — their priorities, our solution fit, and proposed next steps"
+Specify a binary format such as `.pptx`, `.docx`, `.pdf`, or `.xlsx` when you need it. Availability depends on the configured document and sandbox capabilities. A request for a document can otherwise be fulfilled as Markdown.
 
-The file is saved to your workspace and can be downloaded.
+For presentations, include the audience, slide count, and contents:
 
-## Images
+- "Create an eight-slide Q3 review as q3-review.pptx, covering growth, retention, and roadmap."
+- "Turn this research report into a 10-slide presentation."
+- "Create a deck explaining our API onboarding flow."
+- "Create a battle card deck for our top three competitors, with positioning, pricing, and our strengths."
+- "Create an Acme Corp account plan covering its priorities, our solution fit, and next steps."
 
-Sim can generate images using AI, and can use an existing image as a reference to guide the output:
+Ask Sim to save the final file to the workspace. Open it to review the content and layout, then download it from the resource panel or **Files**.
 
-**Generating images:**
-- "Generate a banner image for the new feature announcement — dark background, clean typography"
-- "Create a diagram showing the data flow through our webhook pipeline"
-- "Make a social card for the blog post with the title and author name"
+## Generate or edit an image [#images]
 
-**Using a reference image:**
-- Attach an existing image to your message, then describe what you want: "Generate a new version of this banner with a blue color scheme instead of green"
-- "Create a variation of this diagram with the boxes rearranged horizontally [attach image]"
+Describe the subject, style, size or aspect ratio, and intended use:
 
-<Image src="/static/mothership/image-example.png" alt="Chat resource panel showing a generated hero image of a Mothership-branded blimp flying over San Francisco at golden hour, alongside the chat response linking the file" width={900} height={487} />
+- "Generate a feature announcement banner with a dark background and clean typography."
+- "Create a social card with this blog title and author name: [details]."
 
-Generated images are saved as workspace files.
+For a variation, attach an image or reference a workspace image: "Generate a version of this banner with a blue color scheme instead of green." Saved generated images appear in workspace **Files**.
 
-## Charts and Visualizations
+## Create charts and diagrams [#charts-and-visualizations]
 
-Sim can generate charts and data visualizations from data you describe or reference:
+Reference the data and name the chart you need:
 
-- "Plot the workflow run counts from the metrics table as a bar chart grouped by week"
-- "Create a line chart of token usage over the past 30 days from this data [paste data]"
-- "Generate a pie chart showing the distribution of lead sources from the leads table"
+- "Plot workflow run counts from the metrics table as a weekly bar chart."
+- "Create a line chart of token usage over the past 30 days from this data: [data]."
+- "Show the distribution of lead sources from the leads table as a pie chart."
 
-<Image src="/static/mothership/chart-example.png" alt="Chat resource panel showing a generated chart file with bar charts for backend 5xx errors and error rate over time" width={900} height={571} />
+Sim can also create diagrams from a description, such as the webhook pipeline's data flow or a horizontal version of an existing diagram. Ask for a code-based diagram when exact labels and structure matter. Save the chart or visualization as a file, then inspect it in the resource panel.
 
-Visualizations are saved as files and rendered in the resource panel.
+## Process data [#calculations-data-processing]
 
-## Calculations & Data Processing
+Sim can run code for calculations and one-off transformations:
 
-For one-off calculations and data transformations, describe what you need and Sim runs it directly in the chat:
+- "Extract records from this JSON where status is 'failed'."
+- "Calculate p95 latency from these timing values: [values]."
+- "Convert these Unix timestamps to ISO 8601."
+- "Deduplicate this email list without case sensitivity."
 
-- "Parse this JSON and extract all records where status is 'failed'"
-- "Calculate the p95 latency from these timing values: [paste values]"
-- "Convert these Unix timestamps to ISO 8601"
-- "Deduplicate this list of emails, case-insensitive"
+Results can be returned in the chat. Ask Sim to save a file when you need to reuse them. The Chat workbench holds temporary computation files while its session exists; those files become workspace files only when explicitly saved or exported. Code outputs written to the per-call `SIM_OUTPUT_DIR` are exported to workspace **Files**.
 
-Results come back directly in the chat. Ask Sim to save the output as a file if you need it.
+If a requested stored file, folder input, or table snapshot is withheld, the code does not run. Check the excluded-input report before trying again. Later calls without that input remain available.
 
-## File Viewer Modes
+## View and reuse files [#file-viewer-modes]
 
-When a file opens in the resource panel, you can switch between three views:
+The viewer depends on the file type and your access:
 
-<Video src="mothership/toggle-file-view.mp4" width={700} height={450} />
+| File | Viewing and editing |
+| --- | --- |
+| Markdown | Read and edit in place |
+| Supported text with a rendered preview, such as HTML | Use **Edit Mode**, **Split Mode**, or **Preview Mode** when editing is allowed |
+| Images, PDFs, and supported Office files | Open the format's preview |
+| Unsupported files or files too large for an editor | Download the file or ask Sim to process it |
 
-| Mode | What it shows |
-|------|--------------|
-| **Editor** | Raw editable text |
-| **Preview** | Rendered output (markdown, HTML) |
-| **Split** | Editor and preview side by side |
+Workspace files can be read with a File block or passed as workflow inputs. A chat attachment must first be saved to workspace **Files** when the workflow needs a reusable workspace file.
 
-<FAQ items={[
-  { question: "Can I use files created in Chat in workflows?", answer: "Yes. Workspace files can be referenced in workflows using the File block or by passing them as inputs." },
-  { question: "What file types can I upload in Chat?", answer: "You can attach images, PDFs, text files, JSON, XML, and other document formats directly to a message." },
-  { question: "What can Sim calculate or process?", answer: "Sim can run code to parse JSON, calculate values, transform strings, deduplicate records, and convert supported formats. Results come back in the chat." },
-]} />
+## Related docs
+
+- [Files](/files)
+- [File editor](/files/editor)
+- [Generating files](/files/generating)
+- [Using files in workflows](/files/using-in-workflows)
diff --git a/apps/docs/content/docs/chat/index.mdx b/apps/docs/content/docs/chat/index.mdx
index c8ab0137ba5..9797b0edf05 100644
--- a/apps/docs/content/docs/chat/index.mdx
+++ b/apps/docs/content/docs/chat/index.mdx
@@ -1,71 +1,78 @@
 ---
 title: Chat
-description: Your AI command center. Talk to Sim — build and manage everything in natural language.
+description: Build workflows, research sources, and manage workspace resources by talking to Sim.
 ---
 
-import { Video } from '@/components/ui/video'
-import { FAQ } from '@/components/ui/faq'
+Use Chat to ask Sim to build and run workflows, research a topic, create files, query tables, and act through connected services. Name the resources and outcome you want; Sim can inspect the accessible workspace context needed for the request.
 
-<Video src="mothership/create-workflow.mp4" width={700} height={450} />
+## What you can do
 
-Use Chat to build workflows, research a topic, generate files, query tables, schedule jobs, and act through connected integrations. Reference the workspace resources you want Sim to use.
+| Task | Examples |
+| --- | --- |
+| [Workflows](/chat/workflows) | Build, edit, test, debug, deploy, and organize workflows |
+| [Research](/chat/research) | Search web sources, read pages, and save cited reports |
+| [Files and documents](/chat/files) | Process attachments; create or edit documents, presentations, images, and charts |
+| [Tables](/chat/tables) | Create tables, query or update rows, and export data |
+| [Actions and configuration](/chat/tasks) | Call connected services, set up recurring workflows, and manage credentials, secrets, and tools |
+| [Knowledge bases](/chat/knowledge) | Add documents and connectors, search content, and configure workflow retrieval |
+| [Sim Mailer](/chat/mailer) | Submit tasks by email to an enabled workspace inbox |
 
-## What You Can Do
+## Start a chat [#how-it-works]
 
-| Area | What Sim can do |
-|------|-----------------------|
-| **[Workflows](/chat/workflows)** | Build, edit, run, debug, deploy, and organize workflows |
-| **[Research](/chat/research)** | Search the web, read pages, crawl sites, produce research reports |
-| **[Files & Documents](/chat/files)** | Upload, create, edit, and generate documents, presentations, and images |
-| **[Tables](/chat/tables)** | Create, query, update, and export workspace tables |
-| **[Automation & Configuration](/chat/tasks)** | Schedule jobs, take immediate actions, connect integrations, manage tools |
-| **[Knowledge Bases](/chat/knowledge)** | Create knowledge bases, add documents, and query content in plain language |
+1. Select **New chat** in the sidebar.
+2. Choose **Build** for the workspace actions described in this section. Where available, **Search** answers questions from connected sources.
+3. Describe the task, its inputs, and the result you want.
 
-## How It Works
+**Plan** helps research needs and develop a solution before implementation. It appears only for eligible platform administrators with **Super admin mode** enabled on a deployment that enables this capability. An organization Admin role alone does not enable it.
 
-Sim can find workspace resources by name and inspect the details it needs. Reference a resource explicitly when you want to direct its attention:
+For example:
 
-- "Run the invoice workflow"
-- "Add a row to the leads table"
-- "Deploy the summarizer as a chat"
+- "Build a lead enrichment workflow that scores inbound signups and writes the results to the leads table."
+- "Research our top five competitors and save a battle card for each one."
+- "Create a workflow that takes a contract PDF, extracts key terms, and emails a summary to legal."
+- "Add a daily schedule to the prospect workflow and deploy it. At 8am America/New_York, find new high-fit prospects and post them to #outbound in Slack."
 
-No configuration, no context-setting. Just describe what you want:
+Chat can work across accessible resources. When you open Sim inside a workflow, that conversation is scoped to the workflow. In the organization view, **Build** requires permission to create organization workspaces; each action in an existing workspace still checks its access and enabled capabilities. Available actions depend on your role, connected accounts, workspace settings, and organization policy. Planning a solution does not by itself authorize deploying it or sending messages.
 
-- "Build a lead enrichment workflow that scores inbound signups and writes the results to the leads table"
-- "Research our top 5 competitors and save a battle card for each one"
-- "Schedule a daily job that checks for new high-fit prospects and posts them to #outbound in Slack"
-- "Create a workflow that takes a contract PDF, extracts the key terms, and emails a summary to legal"
+## Add context [#adding-context]
 
-For complex tasks, Sim delegates to specialized subagents automatically. You'll see them appear as collapsible sections in the chat while they work — building, researching, writing files, executing actions.
+Use the **+** menu, type `@` followed by a resource name, or drag an item from the sidebar into the input. You can reference workflows, tables, files, knowledge bases, folders, and earlier chats. Naming a resource in a request also helps Sim find it:
 
-{/* TODO: Screenshot of Chat showing a subagent section expanded mid-task — e.g., the Build or Research subagent actively working, with its collapsible header and steps visible in the thread. */}
+- "Run the invoice workflow."
+- "Add a row to the leads table."
+- "Deploy the summarizer as a chat."
 
-## Adding Context
+Attach a supported file when Sim needs its contents. Attachments stay with the conversation; ask Sim to save a copy to workspace **Files** when teammates or workflows need it. See [files in Chat](/chat/files).
 
-Bring any workspace object into the conversation via the **+** menu, `@`-mentions, or drag-and-drop from the sidebar. Sim also opens resources automatically when it creates or modifies them.
+## Inspect progress and resources [#layout]
 
-<Video src="mothership/context-menu.mp4" width={700} height={450} />
+The chat thread appears beside a resource panel. Workflows open in the workflow builder, tables in the table editor, knowledge bases in their management view, and files in a viewer appropriate to their type. Sim can open resources as it creates or modifies them.
 
-{/* TODO: Screenshot of the resource panel with multiple tabs open — a workflow tab, a table tab, and a file tab — showing different resource types side by side. */}
+Resize the panel, drag tabs to reorder them, and close tabs you no longer need. For larger requests, Sim may delegate parts of the work to other agents. Expand their activity in the chat to inspect progress.
 
-| What to add | How it appears |
-|-------------|---------------|
-| **Workflow** | Interactive canvas in the resource panel |
-| **Table** | Full table editor in the resource panel |
-| **File** | File viewer with editor, split, and preview modes |
-| **Knowledge Base** | Knowledge base management UI |
-| **Folder** | Folder contents |
-| **Past task** | A previous Chat conversation |
+Messages in the same conversation queue while Sim is working. You can edit or remove a queued message, or use **Send now** to stop the current turn and send that message. Use **Stop generation** to stop the current response.
 
-## Layout
+### Find text in a conversation
 
-Chat has two panes. On the left: the chat thread, where your messages and Sim's responses appear. On the right: the resource panel, where workflows, tables, files, and knowledge bases open as tabs. The panel is resizable; tabs are draggable and closeable.
+With the chat pane focused, press **Cmd/Ctrl + F** to open **Find in chat**. Enter text, then use **Enter** or **Shift + Enter** to move between matches. Press **Escape** to close it.
 
-<Video src="mothership/split-view.mp4" width={700} height={450} />
+Find searches loaded user and assistant message text, excluding tool/activity cards and hidden reasoning. Older messages load progressively when you reopen a conversation. While that history is loading, or if loading fails, a missing match does not establish that the message is absent. Find keeps up to 500 matches, prioritizing recent messages; a `+` after the count indicates more matches.
 
-<FAQ items={[
-  { question: "How is Chat different from working inside a single workflow?", answer: "Inside a workflow, Sim is scoped to that workflow — it helps you build and edit that one thing. In Chat, Sim has access to your entire workspace and can build workflows, manage data, run research, schedule jobs, take actions across integrations, and more." },
-  { question: "How do I reference an existing workflow or table?", answer: "Type @ followed by the name in the input, use the + menu, or drag the item from the sidebar into the chat." },
-  { question: "How long can a Chat task run?", answer: "Up to one hour. For tasks that exceed that, set up a scheduled job or break the work into steps." },
-  { question: "Can Sim work on multiple things at once?", answer: "Sim processes one message at a time. You can queue messages — they will be processed in order." },
-]} />
+When native Mac app control is available in Sim Desktop, Chat also shows the active app/action and a **Stop** control. See [Computer Use](/desktop#native-mac-app-control) for device opt-in, app approvals, and macOS permissions.
+
+## Permissions and limits
+
+Reading a resource does not grant permission to edit or execute it. Workspace writes and runs require the relevant access, and organization policies can restrict individual capabilities.
+
+Chat can mask tracked secret values or withhold stored files, table rows, and knowledge content it cannot safely check before it reaches the model. This check is separate from workspace access and tool approval. A resource can remain available in your workspace even when its content is unavailable to Chat.
+
+When tool permissions require a decision, review the action and choose **Allow** or **Skip**. **Don't ask again** offers **For this chat** and **For every chat**, subject to policy. Approval does not expand your underlying resource access.
+
+Chat runs are subject to the deployment's configured runtime and usage limits. Split long work into steps; use a deployed workflow for recurring execution. Check the result and any remaining setup or failed actions before treating the task as complete.
+
+## Related docs
+
+- [Search](/search)
+- [Permissions](/platform/permissions)
+- [Credentials](/platform/credentials)
+- [Costs](/platform/costs)
diff --git a/apps/docs/content/docs/chat/knowledge.mdx b/apps/docs/content/docs/chat/knowledge.mdx
index 2cafd69e439..bb31325bd12 100644
--- a/apps/docs/content/docs/chat/knowledge.mdx
+++ b/apps/docs/content/docs/chat/knowledge.mdx
@@ -1,83 +1,94 @@
 ---
 title: Knowledge bases
-description: Create, populate, and query knowledge bases from Chat.
+description: Create knowledge bases, add documents or connectors, and search their content from Chat.
 ---
 
-import { Video } from '@/components/ui/video'
-import { FAQ } from '@/components/ui/faq'
+Ask Sim to create a knowledge base, add source documents, or search existing content. Use a knowledge base for documents retrieved by meaning, such as support policies or product guides. Access and permitted operations follow workspace and organization policy.
 
-<Video src="mothership/kb.mp4" width={700} height={450} />
+## Create a knowledge base [#creating-knowledge-bases]
 
-Create a knowledge base, add documents to it, and query it in plain language — all through conversation. Knowledge bases you create in Chat are immediately available to Agent blocks in any workflow.
+Name the base and describe the content it should hold:
 
-## Creating Knowledge Bases
+- "Create a Product Docs knowledge base for our product documentation."
+- "Create a Support KB for support policies and troubleshooting guides."
+- "Create a competitive intelligence knowledge base."
+- "Create a knowledge base from our sales playbook and configure the outbound workflow to search it."
+- "Create a customer success knowledge base for onboarding guides and case studies."
 
-Describe the knowledge base and Sim creates it:
+## Add and process documents [#adding-documents]
 
-- "Create a knowledge base called 'Product Docs'"
-- "Set up a knowledge base for our support team — call it 'Support KB'"
-- "Create a competitive intelligence knowledge base"
-- "Create a knowledge base from our sales playbook and attach it to the outbound agent workflow"
-- "Set up a customer success knowledge base — I'll add our onboarding guides and past case studies to it"
+Attach a supported file, paste text, or provide an accessible URL:
 
-## Adding Documents
+- "Add this PDF to Product Docs." Attach the PDF.
+- "Add this text to Support KB as a new document: [content]."
+- "Fetch [URL] and add its content to competitive intelligence."
+- "Add these three case studies to the customer success knowledge base." Attach the files.
 
-Add documents by attaching files to your message, pasting text, or pointing Sim at a URL:
+PDFs, Markdown, plain text, and content fetched from web pages can be ingested. Sim can help process and index the documents. Content is searchable only after processing completes successfully and the document is enabled.
 
-- "Add this PDF to the Product Docs knowledge base [attach file]"
-- "Add the following text to the Support KB as a new document: [paste content]"
-- "Fetch the page at [URL] and add it to the competitive intelligence knowledge base"
-- "Add these three uploaded case studies to the customer success knowledge base"
+Ask Sim to check the documents added by the request and report processing failures. A saved document or an accepted upload does not itself prove the content is indexed. If processing fails, inspect the error and retry after fixing the cause.
 
-Sim processes and indexes each document automatically. Once indexed, the content is searchable by any Agent block that has the knowledge base attached.
+Chat attachments stay with their conversation. Adding one to a knowledge base is a separate request; it does not automatically save a reusable workspace file.
 
-{/* TODO: Screenshot of Sim confirming a document was added and indexed — showing the document name and its indexed status in the knowledge base. */}
+## Search the content [#querying-knowledge-bases]
 
-## Querying Knowledge Bases
+Specify the knowledge base and question:
 
-Ask Sim a question and it searches the specified knowledge base to answer:
+- "What does Product Docs say about refunds?"
+- "Search Support KB for SSO setup errors."
+- "Compare Pro and Enterprise features using the product docs."
+- "Find documents about [competitor]'s pricing in competitive intelligence."
 
-- "What does the Product Docs knowledge base say about our refund policy?"
-- "Search the Support KB for anything related to SSO setup errors"
-- "What are the key differences between our Pro and Enterprise plans, based on the product docs?"
-- "Find everything in the competitive intelligence knowledge base about [competitor]'s pricing"
+Sim retrieves matching content to answer the question. Check that the returned evidence comes from the intended documents; a partial search or no matches does not establish that the base contains no relevant information.
 
-## Connectors
+Chat can mask tracked secret values or omit documents, passages, and tag values it cannot safely check, even when indexing and access checks pass. Document-list counts can still describe the underlying collection. Check the knowledge base directly when expected content is unavailable to Chat.
 
-For knowledge bases that should stay current automatically, connectors sync content from external services on a schedule — no manual uploads needed. New content is added, changed content is re-processed, and deleted content is removed on every run.
+## Keep sources updated [#connectors]
 
-Connectors are usually configured in the knowledge base settings. Sim can also create, update, and sync them for you. Content becomes searchable after syncing and indexing, subject to the caller's access permissions.
+Connectors sync documents from external services on a configured schedule. Ask Sim to create or update the connection, or run a sync, using an available credential and the source you want:
 
-Use a [connector](/knowledgebase/connectors) to sync sources such as Notion, Google Drive, Slack, GitHub, or Confluence.
+- "Sync the support page tree from Notion into Support KB."
+- "Connect the onboarding folder in Google Drive to the customer success knowledge base."
+- "Sync this GitHub repository's documentation into Product Docs."
+- "Sync this Slack channel's history into Support KB."
 
-Examples of what you can sync:
+Supported sources also include cloud storage such as Dropbox and OneDrive, wikis and issue trackers such as Confluence and Jira, and CRM records such as HubSpot and Salesforce. See the [connector guide](/knowledgebase/connectors) for the current source list, setup requirements, and sync frequency options.
 
-- **Notion** — sync a workspace, a database, or a specific page tree
-- **Google Drive / Dropbox / OneDrive** — sync documents from cloud storage
-- **GitHub** — sync a repository's markdown and code files
-- **Slack** — sync channel history
-- **Confluence / Jira** — sync your internal wiki or issue tracker
-- **HubSpot / Salesforce** — sync CRM records into a searchable knowledge base
+New and changed content becomes searchable after syncing and processing. Source removals are reconciled during sync; they are not guaranteed to disappear on every run. Check connector status and errors if the knowledge base appears out of date. Search remains subject to the caller's access permissions.
 
-See [Connectors](/knowledgebase/connectors) for setup steps, sync frequency options, and managing connector status.
+## Use a knowledge base in a workflow [#using-knowledge-bases-in-workflows]
 
-## Managing Knowledge Bases
+Ask Sim to configure one of these retrieval paths:
 
-List, inspect, and clean up knowledge bases in plain language:
+1. Add **Knowledge Search** to an Agent block's tools and select the knowledge base.
+2. Add a Knowledge block before the Agent, select the base, and reference the search results in the Agent's prompt.
 
-- "What knowledge bases are in this workspace?"
-- "How many documents are in the Support KB?"
-- "Remove the outdated pricing doc from the Product Docs knowledge base"
-- "Delete the old-competitive-intel knowledge base"
+The base must be accessible and its documents successfully indexed. Selecting a base does not grant access to documents withheld by policy.
 
-## Using Knowledge Bases in Workflows
+A workflow can also add documents through **Knowledge Create Document** or **Knowledge Upsert Document**. Configure the intended base and content, then verify that processing completes before relying on retrieval.
 
-Knowledge bases created in Chat are immediately available to Agent blocks in any workflow. Attach a knowledge base to an Agent block and it will use semantic search to retrieve relevant content at runtime.
+## Manage documents and bases [#managing-knowledge-bases]
 
-See [Knowledge Base](/knowledgebase) for full details on document processing settings, search configuration, and connector syncing.
+Ask Sim to inspect the inventory or remove specific content:
 
-<FAQ items={[
-  { question: "How do I attach a knowledge base to a workflow?", answer: "Add a Knowledge search tool to the Agent block and select the knowledge base in that tool, or use a Knowledge block before the Agent and reference its results. You can also ask Chat to configure this for you." },
-  { question: "What file types can I add to a knowledge base?", answer: "PDFs, markdown files, plain text, and web pages fetched from URLs. Sim handles the parsing and indexing automatically." },
-  { question: "Can I add documents to a knowledge base from a workflow run?", answer: "Yes. The Knowledge Base write tool is available to Agent blocks and can be used to add documents programmatically during a workflow run." },
-]} />
+- "List knowledge bases in this workspace."
+- "How many documents are in Support KB?"
+- "Remove the outdated pricing document from Product Docs."
+- "Delete the old-competitive-intel knowledge base."
+
+Document deletion cannot be reversed by restoring the knowledge base. For connector-managed content, correct the source and sync it again rather than editing its indexed chunks.
+
+## Private knowledge graphs
+
+On deployments that enable this restricted capability, eligible platform administrators with **Super admin mode** enabled can open **Knowledge graphs** in organization settings. These private Chat memory graphs are separate from the workspace knowledge bases described above.
+
+Select **New graph**, enter a name, and choose **Create and activate**, or choose **Make active** beside an existing graph. Graph names can have 1–100 characters and cannot be `Default` in any capitalization. The **Default** graph preserves the original memory.
+
+Each graph is private to you in that organization. The active graph is selected for new chats in the organization and its workspaces; existing chats keep their original graph. Selecting or creating a graph keeps the other graphs and does not grant access to workspace knowledge-base documents.
+
+## Related docs
+
+- [Knowledge base](/knowledgebase)
+- [Connectors](/knowledgebase/connectors)
+- [Using knowledge bases in workflows](/knowledgebase/using-in-workflows)
+- [Debugging retrieval](/knowledgebase/debugging-retrieval)
diff --git a/apps/docs/content/docs/chat/mailer.mdx b/apps/docs/content/docs/chat/mailer.mdx
index da33cc8738d..d9d017fe821 100644
--- a/apps/docs/content/docs/chat/mailer.mdx
+++ b/apps/docs/content/docs/chat/mailer.mdx
@@ -1,71 +1,96 @@
 ---
 title: Sim Mailer
-description: Send emails to your workspace and let Sim handle them as tasks.
+description: Submit tasks by email to an enabled workspace inbox and follow the results in Chat.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { FAQ } from '@/components/ui/faq'
 
-Sim Mailer gives your workspace a dedicated email address. Forward or send emails to it and Sim will process them as tasks — reading the subject, body, and any attachments, then replying to the thread with the result.
+Sim Mailer gives an enabled workspace an email address. Send or forward a message to submit a task; its subject, body, and successfully prepared attachments become the prompt. Sim normally replies in the email thread with the result and a link to the conversation.
 
-## Getting Started
+## Requirements
 
-1. Navigate to **Settings** → **Inbox**
-2. Toggle the inbox on
-3. Optionally choose a custom address prefix (e.g., `acme` → `acme@mothership.sim.ai`)
-4. Copy your inbox address and start sending emails
+A workspace **Admin** configures the inbox. On Sim Cloud, availability follows the workspace's Max or Enterprise plan and active billing, rather than the sender's individual plan.
 
-If you skip the custom prefix, one is generated automatically.
+On self-hosted deployments, availability depends on configured Chat and email services. `INBOX_ENABLED` or billing-disabled configuration can allow access, but the required Chat service key must still be configured. See [self-hosted environment variables](/platform/self-hosting/environment-variables).
+
+Members keep their own workspace permissions when submitting email tasks. An allowed external email sender can submit read-only tasks; allowlisting does not grant workspace membership, workflow execution, mutation access, or raw-secret access.
+
+## Enable the inbox [#getting-started]
+
+1. Open **Settings** → **Inbox**.
+2. Switch the inbox to **On** and choose **Enable**. You can supply an **Email prefix** or leave it blank to generate one.
+3. Copy the address shown under **Sim's email**.
+4. Configure allowed senders and secret access before submitting tasks that need workspace context.
+5. Send a test message, then inspect its status and conversation in **Inbox**.
+
+The prefix is customizable. The domain comes from the deployment's email configuration and is not selected in this control; use the address shown in **Inbox**.
 
 <Callout type="info">
-  Changing your address creates a new inbox. The old address stops working immediately.
+  Changing the address creates a new inbox. The old address stops accepting tasks immediately. Update any forwarding rules or saved contacts that use it.
 </Callout>
 
-## What You Can Send
+Use **Off** to disable the inbox. Existing conversations and task history are preserved.
+
+## Configure allowed senders [#allowed-senders]
+
+Manage **Allowed senders** in **Settings** → **Inbox**:
 
-Write your email like you would to a colleague. The subject and body become the task prompt.
+- Workspace members are allowed by default.
+- An Admin can add an external email address with an optional label, or remove it from the allowlist.
 
-**Attachments are fully supported.** Images, PDFs, and documents (up to 10 MB each) are read by Sim and displayed inline in the conversation; images show as previews.
+An external email sender is different from an external workspace member. The latter has access to Sim according to their workspace role without joining the organization; an email-only sender has no such membership.
 
-| Good email | Why it works |
-|------------|-------------|
-| "Summarize the attached PDF and list action items" | Clear task with an attachment |
-| "What's in this image?" with a photo attached | Sim reads and describes the image |
-| "Draft a reply to this forwarded thread" | Uses the email body as context |
+Emails from unauthorized senders are rejected. Automated senders, rate limits, or loss of plan entitlement can also prevent a task from being accepted.
 
-## Allowed Senders
+## Select secret access
 
-Only authorized senders can create tasks. Emails from anyone else are automatically rejected.
+Under **Secrets**, **Secret access** defaults to **All secrets**. Choose **Selected secrets** to restrict raw-secret mounts. With **Selected secrets**, choose the permitted names in the **Secrets** selector. Selecting none allows no raw-secret mounts.
 
-- **Workspace members** are allowed by default — no setup needed
-- **External senders** can be added manually with an optional label for easy identification
+This setting narrows which secrets member tasks may mount; it does not grant access to secrets the sender cannot otherwise use. External email-only senders have no raw-secret access. Configure workflow credentials separately according to their access rules.
 
-External senders are email addresses that can create inbox tasks. They are not the same as external workspace members, who have workspace access in Sim without joining your organization.
+Mailer runs without an interactive approval card. Restrict allowed senders and secret access according to the actions members should be able to request; their underlying permissions and organization policies still apply.
 
-Manage your allowed senders list in **Settings** → **Inbox** → **Allowed Senders**.
+## Send a task [#what-you-can-send]
 
-## Tracking Tasks
+Write the subject and body as a specific request:
 
-Every email becomes a task you can track in **Settings** → **Inbox**:
+| Email | Context |
+| --- | --- |
+| "Summarize the attached PDF and list action items." | An attached source document |
+| "What is shown in this image?" | An attached image |
+| "Draft a reply to this forwarded thread." | The forwarded email body |
 
-- **Search** by subject, sender, or body content
-- **Filter** by status to find what you need
-- **Click** any completed or failed task to jump to the full conversation
+The per-attachment hard limit is **10 MiB**. Supported images, PDFs, and documents are attached to the Chat conversation; images can display as previews. If an attachment cannot be prepared, the conversation identifies it as unavailable and keeps any successfully prepared attachments.
 
-### Task Statuses
+Attachments stay with the conversation. Ask Sim to save a copy to workspace **Files** when you need a reusable workspace file, using a member account with the required write access.
+
+## Track tasks [#tracking-tasks]
+
+Open **Settings** → **Inbox** to inspect received messages:
+
+1. Use **Search tasks...** to match a subject, sender, or body preview in the displayed tasks.
+2. Choose a status from **All statuses** to filter the list.
+3. Select a completed or failed task with a linked chat to open its full conversation.
+
+### Task statuses
 
 | Status | Meaning |
-|--------|---------|
-| **Received** | Email accepted, queued for processing |
-| **Processing** | Sim is actively working on it |
-| **Completed** | Done — the result was sent as an email reply |
-| **Failed** | Something went wrong during execution |
-| **Rejected** | Email blocked (sender not allowed, automated sender, or rate limit exceeded) |
+| --- | --- |
+| **Received** | Accepted and queued for processing |
+| **Processing** | Sim is working on the task |
+| **Completed** | Sim finished the task successfully; the list badge reads **Complete** |
+| **Failed** | The task encountered an execution error |
+| **Rejected** | The message was blocked; inspect its rejection reason |
+
+A completed task does not prove an email reply was delivered. If a reply is missing, inspect the linked conversation and task result. Failed tasks can also have an email response describing the error.
+
+## Continue the conversation [#conversations]
 
-## Conversations
+A new email task creates a workspace conversation. You can continue it in Chat. Replies linked to an earlier email task continue its conversation when that chat is still available in the same workspace; otherwise, processing starts a new conversation.
 
-Each email task creates a conversation in your workspace. You can continue the conversation in Chat, and any follow-up emails in the same thread are linked to the same conversation.
+## Related docs
 
-<FAQ items={[
-  { question: "Can I use my own email domain?", answer: "Not currently. All inbox addresses use the @mothership.sim.ai domain. You can customize the prefix (e.g., acme@mothership.sim.ai) but not the domain itself." },
-]} />
+- [Files and documents in Chat](/chat/files)
+- [Permissions](/platform/permissions)
+- [Credentials](/platform/credentials)
+- [Costs](/platform/costs)
diff --git a/apps/docs/content/docs/chat/research.mdx b/apps/docs/content/docs/chat/research.mdx
index 2bb0bab87b3..22ce24c42c0 100644
--- a/apps/docs/content/docs/chat/research.mdx
+++ b/apps/docs/content/docs/chat/research.mdx
@@ -1,43 +1,46 @@
 ---
 title: Research
-description: Ask Sim to research anything — it searches, reads, and synthesizes from the web.
+description: Research web sources and save answers or cited reports from Chat.
 ---
 
-import { Video } from '@/components/ui/video'
-import { FAQ } from '@/components/ui/faq'
+Ask Sim to investigate a topic, read a URL, or compare sources. Specify the question, time range, and output you need. Web research is available when the deployment provides the required search or page-reading tools.
 
-<Video src="mothership/research-agent.mp4" width={700} height={450} />
+## Ask a research question [#asking-questions]
 
-Ask Sim to research anything and it figures out the best approach — searching the web, reading specific pages, crawling sites, looking up technical docs. Just describe what you want to know.
+Include enough scope to identify useful sources:
 
-## Asking Questions
+- "What did Salesforce, HubSpot, and Gong ship in the past 30 days? Cite the product updates."
+- "Find Acme Corp's public tech stack information, recent hires, and open engineering roles."
+- "Research [competitor]'s press, product changes, and job postings from the past 90 days."
+- "Check Anthropic's API documentation for its current rate limits."
+- "Read [URL] and explain what changed in this release."
+- "Check Stripe's documentation for webhook retries and idempotency handling."
+- "Compare the main providers of AI for revenue operations and explain their differences."
 
-Ask anything — about a company, a competitor, a market, a technical question, or a specific URL:
+Sim can search web sources, read pages, and look up technical documentation. It returns an answer in the chat; ask for a saved file when you need a longer deliverable.
 
-- "What did Salesforce, HubSpot, and Gong each ship in the past 30 days? Summarize the key product updates."
-- "What's Acme Corp's tech stack, recent hires, and open engineering roles?"
-- "Find everything published about [competitor] in the past 90 days — press, product changes, job postings."
-- "What are the current rate limits on the Anthropic API?"
-- "Read [URL] and tell me what changed in this release"
-- "What does Stripe's API say about handling webhooks with idempotency keys?"
-- "Who are the main players in AI-powered revenue operations, and how do they differentiate?"
+## Save a report [#research-reports]
 
-Sim returns an answer directly in the chat. For anything that needs a longer written output, ask it to save the result as a file.
+Name the comparison criteria, intended audience, and destination. For example:
 
-## Research Reports
+- "Compare 10 AI sales development tools on pricing, features, positioning, and customer feedback. Save a cited competitive analysis as ai-sales-tools.md."
+- "Map AI in healthcare diagnostics: major providers, funding, use cases, and the regulatory context. Save a report with sources and open questions."
+- "Research how our top five competitors handle multi-tenant authentication. Compare public architecture details, pricing, and documented vulnerabilities."
+- "Find public case studies on AI agents in financial compliance from the past two years. Summarize the reported outcomes and save a Markdown report."
+- "Create a battle card for [competitor] covering positioning, pricing, strengths, weaknesses, and our differentiators."
 
-When you need a structured, saved document rather than a chat answer, ask Sim to write it up. Sim searches, reads, and cross-references multiple sources until it has enough to produce a full report. The output is saved as a file in your workspace and opened in the resource panel.
+Ask for citations and for missing or conflicting evidence to be identified. Sim can combine the findings into a workspace file and open it in the resource panel. Find the saved report later in **Files**, or ask Sim to turn it into a presentation.
 
-{/* TODO: Screenshot of a completed research report open in the resource panel as a file — showing a structured markdown document with sections, findings, and citations. */}
+## Check source access and freshness
 
-- "Research the top 10 AI SDR tools — pricing, features, positioning, and what customers say. Save as a competitive analysis."
-- "Do a full market landscape for AI in healthcare diagnostics — major players, funding, use cases, and regulatory environment."
-- "Research how our top 5 competitors handle multi-tenant auth — pricing, architecture, and any known vulnerabilities. Write it up as a report."
-- "Find every public case study on AI agents in financial compliance from the past 2 years. Summarize the key outcomes and save as a markdown file."
-- "Build a battle card for [competitor] — their positioning, pricing, strengths, weaknesses, and how we win against them."
+Hosted web research reads publicly accessible pages. In Sim Desktop, the built-in browser can also work with websites you sign in to when browser tools are available. A link to a private page does not itself give Sim access.
 
-<FAQ items={[
-  { question: "Does Sim have access to real-time information?", answer: "Sim can search current web sources. Check the cited source and its publication date when freshness matters." },
-  { question: "Can Sim read pages that require login?", answer: "Hosted web research reads publicly accessible pages. In Sim Desktop, the built-in browser can also use websites you sign in to." },
-  { question: "Where are research reports saved?", answer: "Reports are saved as files in your workspace and opened in the resource panel. You can find them in the Files section of the sidebar." },
-]} />
+For connected organizational sources such as Slack or Google Drive, use [Search](/search) or ask Sim to inspect those sources under your current permissions.
+
+Check the cited source and publication date when freshness matters. Search results can be incomplete; a report should distinguish what the sources establish from what remains unknown. Request a specific site or documentation page when that source is required.
+
+## Related docs
+
+- [Files and documents in Chat](/chat/files)
+- [Search](/search)
+- [Sim Desktop](/desktop)
diff --git a/apps/docs/content/docs/chat/tables.mdx b/apps/docs/content/docs/chat/tables.mdx
index 9862fd7568c..18ec2ddae24 100644
--- a/apps/docs/content/docs/chat/tables.mdx
+++ b/apps/docs/content/docs/chat/tables.mdx
@@ -1,59 +1,82 @@
 ---
 title: Tables
-description: Create, query, and manage workspace tables from Chat.
+description: Create tables, query or update rows, and export data from Chat.
 ---
 
-import { Image } from '@/components/ui/image'
-import { FAQ } from '@/components/ui/faq'
+Ask Sim to create a workspace table, inspect its data, or change rows. Reference the table by name or with an `@`-mention. Tables can open in Chat's resource panel for review.
 
-<Image src="/static/mothership/table-example.png" alt="Chat resource panel showing the pipeline_deals table with company, deal_owner, stage, and amount columns, alongside a chat summary of total pipeline value and breakdown by stage" width={900} height={487} />
+Table reads, writes, creation, and exports follow your workspace access and organization policy. Storage and row limits depend on the plan and deployment configuration.
 
-Create a table from a description or a CSV, query it in plain language, add or update rows, and export the results — all through conversation. Tables open in the resource panel as soon as they're created or referenced.
+## Create or import a table [#creating-tables]
 
-## Creating Tables
+Describe the columns and types, or attach a CSV for Sim to import:
 
-Describe the schema and Sim creates the table:
+- "Create a leads table with name, email, company, status, and created date columns."
+- "Create a table matching this CSV." Attach the file.
+- "Create an errors table with message and workflow text columns, a timestamp date column, and a resolved boolean."
+- "Create a prospects table with company, domain, employee count, industry, fit score, and last contacted date."
+- "Create an enrichment results table for email, company, title, LinkedIn URL, and fit score."
 
-- "Create a leads table with columns for name, email, company, status, and created date"
-- "Create a table that matches the structure of this CSV [attach file]"
-- "Set up an errors table with: id (text), message (text), workflow (text), timestamp (date), resolved (boolean)"
-- "Create a prospect table for outbound — company, domain, employee count, industry, ICP score, and last contacted date"
-- "Set up an enrichment results table to store output from the lead enrichment workflow: email, company, title, LinkedIn URL, fit score"
+Inspect the schema and imported rows before using the table in an agent. Specify unique or required columns when the data needs those constraints.
 
-## Querying Data
+## Query data [#querying-data]
 
-Ask questions about table contents in plain language:
+Name the table, fields, filters, and time range:
 
-- "How many rows in the leads table have status 'qualified'?"
-- "Show me all records from the past 7 days where score is above 0.8"
-- "What are the top 5 most common error messages in the failures table?"
-- "Are there any duplicate emails in the contacts table?"
-- "How many prospects have an ICP score above 0.75 and haven't been contacted in the past 30 days?"
-- "What's the conversion rate from 'contacted' to 'meeting booked' in the pipeline table this month?"
+- "How many leads have status 'qualified'?"
+- "Show leads from the past seven days with score above 0.8."
+- "List the five most common error messages in the failures table."
+- "Find duplicate emails in the contacts table."
+- "Count prospects with a fit score above 0.75 that have not been contacted in the past 30 days."
+- "Calculate conversion from 'contacted' to 'meeting booked' in this month's pipeline data."
 
-Sim translates the question into a structured query and returns the results.
+Sim can query the matching rows and compute summaries. It can also read multiple tables and combine their results: describe the relationship, such as matching `company_id` between contacts and companies. This does not create a persistent join between the tables.
 
-## Adding and Updating Rows
+Chat can mask tracked secret values or omit rows and selected cells it cannot safely check. Matching-row totals and pagination cursors still describe the database query; a shorter response does not prove that every match was shown. Summaries based on returned rows can be incomplete.
 
-Add individual rows, bulk-update based on a condition, or delete records — all in plain language:
+Large reads may need pagination or an export. Name the subset you need instead of requesting every row when a filter can answer the question.
 
-- "Add a row to the leads table: Acme Corp, jane@acme.com, status pending"
-- "Mark all rows in the queue table as processed where created_at is before today"
-- "Update the price column for all rows where tier is 'pro' to 49"
-- "Delete all rows in the test_events table"
+## Add or update rows [#adding-and-updating-rows]
 
-## Exporting
+Provide values by column name. For bulk changes, state the condition:
 
-Export a full table or a filtered subset as a CSV. The file is saved to your workspace and can be downloaded or referenced in other workflows:
+- "Add a leads row with company=Acme Corp, email=jane@acme.com, and status=pending."
+- "Mark queue rows as processed where createdAt is before today."
+- "Set price to 49 for rows where tier is 'pro'."
 
-- "Export the leads table to a CSV"
-- "Export all rows where status is 'closed' and save as a file"
+`createdAt` is the built-in creation timestamp. Use the actual custom column name when you mean a separate date field.
 
-## Using Tables in Workflows
+Review the affected records and ask Sim to verify the updated values. Table writes can also trigger configured workflow automation.
 
-Tables created in Chat are immediately available in workflows via the [Table tool](/integrations/table). Reference a table by name — no additional configuration needed.
+A write can be saved even when its returned row is withheld from Chat. Inspect the table before repeating a change whose result could not be shown.
 
-<FAQ items={[
-  { question: "Can Sim join or combine data from multiple tables?", answer: "Yes. Describe the relationship and what you want — Sim will query both tables and combine the results." },
-  { question: "Is there a row limit?", answer: "Row limits depend on the workspace plan and deployment configuration. Use pagination for large reads; see Tables for storage and query limits." },
-]} />
+### Delete rows
+
+Deleting rows removes their stored data. Identify the table and condition before asking for a destructive action:
+
+- "Delete all rows in the test_events table."
+- "Delete contacts with status 'test' from the contacts table."
+
+Removing rows does not undo external actions previously performed by workflows using them.
+
+## Export data [#exporting]
+
+Export the whole table or a filtered subset as CSV:
+
+- "Export the leads table as leads.csv in workspace Files."
+- "Export pipeline rows where status is 'closed' and save them as closed-deals.csv."
+
+Wait for the export to complete, then inspect its row count and download the file. A CSV created from rows returned to Chat can omit rows unavailable to Chat. Use the table's own export control when you need an authorized export of the stored data. A saved workspace CSV can be referenced by other workflows.
+
+## Use a table in a workflow [#using-tables-in-workflows]
+
+Ask Sim to configure a Table block or tool with the intended table and operation, or select the table in the workflow builder. The table must be available to the workflow's execution context; naming it in Chat does not replace the block's configuration.
+
+For per-row enrichment, ask Sim to connect a deployed workflow to table columns so its outputs populate each row. See [workflow columns](/tables/workflow-columns) for dependencies and execution behavior.
+
+## Related docs
+
+- [Tables](/tables)
+- [Using tables in workflows](/tables/using-in-workflows)
+- [Table integration](/integrations/table)
+- [Files and documents in Chat](/chat/files)
diff --git a/apps/docs/content/docs/chat/tasks.mdx b/apps/docs/content/docs/chat/tasks.mdx
index 324731b9d2a..c34d2105677 100644
--- a/apps/docs/content/docs/chat/tasks.mdx
+++ b/apps/docs/content/docs/chat/tasks.mdx
@@ -1,129 +1,125 @@
 ---
-title: Automation & configuration
-description: Schedule recurring jobs, take immediate actions, connect integrations, and configure your workspace.
+title: Actions and configuration
+description: Call connected services, schedule workflows, and manage credentials, secrets, and tools from Chat.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Video } from '@/components/ui/video'
-import { FAQ } from '@/components/ui/faq'
+Ask Sim to take an action through a connected service or configure the resources a workflow needs. Immediate service calls, recurring workflows, and one-time follow-ups have different execution paths.
 
-<Video src="mothership/job-create.mp4" width={700} height={450} />
+## Take an immediate action [#taking-direct-action]
 
-Sim can act on your behalf right now — send a message, create an issue, call an API — or on a schedule, running a prompt automatically every hour, day, or week. It can also connect integrations, set environment variables, add MCP servers, and create custom tools.
+For a one-off request, name the service, target, account, and contents. Sim can call the service without building a workflow:
 
-## Scheduled Jobs
+| Request | Action |
+| --- | --- |
+| "Send a Slack message to #eng saying the deploy finished." | Post through the selected Slack connection |
+| "Email q3-report.pdf to jane@example.com." | Send through an available Gmail or Outlook connection |
+| "Create a GitHub issue in [repo]: auth tokens do not rotate on logout." | Create the issue in that repository |
+| "Add Acme Corp and ceo@acme.com to HubSpot." | Create the CRM record |
+| "Call the webhook at [URL] with this JSON: [payload]." | Make the HTTP request |
 
-A scheduled job is a saved Chat prompt that runs on a cron schedule. On each run, Sim reads the current workspace state and executes the job's prompt as if you had just sent it.
+Actions use credentials available to the acting member and remain subject to workspace access and organization policy. If the required account is not connected, complete the connection flow before the action can run.
 
-### Creating a Job
+Review any tool approval card. Choose **Allow** to run the action or **Skip** to decline it. Reuse choices under **Don't ask again** depend on policy. Check the returned result before assuming the external service changed.
 
-Describe the recurring task and how often it should run:
+An action can finish while Chat withholds its returned result. Check the connected service or affected resource before repeating an action whose result could not be shown.
 
-- "Every morning at 8am, check the leads table for new entries and post a summary to #sales in Slack"
-- "Every Monday at 9am, pull last week's workflow run counts and write a report to the workspace"
-- "Run the data sync workflow every 6 hours"
-- "On the first of every month, export the billing table to CSV and email it to finance@example.com"
-- "Every weekday at 7am, check for new funding announcements from companies in our ICP and post the top 5 to #market-intel in Slack"
-- "Every Sunday night, run the lead enrichment workflow on all prospects added in the past week and update their scores in the table"
-- "Daily at 6am, pull the previous day's workflow errors, summarize the top issues, and post to #eng-alerts"
+Undo behavior depends on the service. Some records can be edited or deleted afterward; deleting a Chat conversation does not undo a sent email or other external action.
 
-Sim sets the cron expression and stores the job prompt. The first run happens at the next scheduled time.
+## Set up recurring work [#scheduled-jobs]
 
-### Viewing Job Logs
+Recurring execution uses a workflow with a Schedule trigger. Describe the work, cadence, and timezone, then ask Sim to build or update the workflow and deploy it:
 
-- "Show me the last 5 runs of the weekly report job"
-- "Did the sync job run successfully this morning?"
-- "What did the Monday digest job do last week?"
+- "Every morning at 8am America/New_York, summarize new leads and post to #sales in Slack. Build and deploy the workflow."
+- "Every Monday at 9am Europe/London, save a report of last week's workflow run counts."
+- "Add an every-six-hours schedule to the data sync workflow and deploy it."
+- "On the first of each month at 9am America/Los_Angeles, export the billing table to CSV and email it to finance@example.com."
+- "Every weekday at 7am America/New_York, find new funding announcements for companies matching our ideal customer profile and post five to #market-intel."
+- "Every Sunday at 10pm America/New_York, enrich prospects added in the past week and update their scores."
+- "Daily at 6am UTC, summarize the previous day's workflow errors and post the main issues to #eng-alerts."
 
-Logs show run time, status (completed, failed), and a summary of what the agent did.
+A Schedule trigger stores the timing configuration, including its cron expression and timezone. The deployed workflow defines what each run does; it can include Agent blocks for reasoning.
 
-### Managing Jobs
+Test the workflow with representative inputs and review its external effects before deployment. Confirm that the intended version is active and its schedule is ready. Scheduled runs use the active deployed version; changing the draft does not change recurring execution until redeployment.
 
-- "Pause the morning summary job"
-- "Change the sync job to run every 3 hours instead of 6"
-- "Delete the onboarding digest job"
-- "What scheduled jobs are currently active?"
+### Inspect scheduled runs [#viewing-job-logs]
 
-## Taking Direct Action
+Ask Sim to read the workflow's logs:
 
-For requests that should happen right now — without building a workflow — just ask. Sim acts immediately using the credentials connected to your workspace.
+- "Show the last five scheduled runs of the weekly report workflow."
+- "Did the sync workflow's scheduled run succeed this morning?"
+- "What did the Monday digest workflow produce last week?"
 
-{/* TODO: Screenshot of Chat showing the "Taking action" subagent label active during a direct action — e.g., posting to Slack or sending an email. Shows the subagent inline in the chat thread. */}
+Logs identify the execution time, status, block outputs, and errors. If nothing ran, ask Sim to check the deployment and Schedule trigger as well as the logs.
 
-| Request | What happens |
-|---------|-------------|
-| "Send a Slack message to #eng that the deploy finished" | Posts to Slack immediately |
-| "Email the Q3 report to jane@example.com" | Sends via connected Gmail or Outlook |
-| "Create a GitHub issue: auth tokens not rotating on logout" | Opens an issue in the specified repo |
-| "Add a contact to HubSpot: Acme Corp, ceo@acme.com" | Creates the contact via HubSpot API |
-| "Call the webhook at [URL] with this JSON payload" | Makes the HTTP request |
+### Change or stop recurring work [#managing-jobs]
 
-If an integration isn't connected, Sim walks you through connecting it.
+Name the workflow and trigger you want to change:
 
-## Connecting Integrations
+- "Change the sync workflow from every six hours to every three hours, then deploy the change."
+- "Remove the morning summary workflow's Schedule trigger and deploy the change."
+- "List workflows with active Schedule triggers."
 
-Sim can connect new OAuth integrations and API credentials on demand:
+To stop all deployed entry points, ask to undeploy the workflow. That affects its other deployment surfaces too; removing one Schedule trigger is more specific. Stopping future scheduled starts does not cancel an execution already running. See [Schedule triggers](/workflows/triggers/schedule) for setup, disabled schedules, and self-hosted scheduler requirements.
 
-- "Connect my Google account"
-- "Add the Slack workspace for our team"
-- "Set up GitHub with my personal access token"
+## Follow up later
 
-{/* TODO: Screenshot of Sim walking through connecting an integration — e.g., the Integration subagent active with an OAuth prompt or confirmation that a credential was connected. */}
+Chat can watch a background workflow execution and continue when it finishes, or set a one-time timer for up to 24 hours:
 
-Once connected, Sim can use the account for authorized actions. Configure a workflow to use the intended available credential.
+- "Run the deployed invoice sync in the background and tell me when it finishes."
+- "Remind me in 45 minutes to check the import results."
 
-<Callout type="info">
-  Select the intended account when configuring each integration. Which credentials are available depends on their ownership, sharing settings, and workspace policy. See [credentials](/platform/credentials).
-</Callout>
+Ask about the recorded status or stop a pending follow-up in the same chat. Stopping a watch cancels its notification; it does not cancel the workflow execution. Request workflow cancellation separately when that is what you intend. Timers are one-time follow-ups, not recurring schedules.
 
-See [Credentials](/platform/credentials) for managing connected accounts.
+## Connect an integration [#connecting-integrations]
 
-## Environment Variables
+Ask Sim to start the connection flow for the service you need:
 
-Save API keys, connection strings, and configuration under **Secrets**, then reference them with `{{ENV_VAR}}`. Choose personal or workspace scope according to who should use the value. See [secrets](/workflows/variables#environment-variables).
+- "Connect my Google account for Gmail."
+- "Connect the Slack workspace for our team."
+- "Set up GitHub with my personal access token."
 
-- "Set the DATABASE_URL environment variable to 'postgres://...'"
-- "Add an OPENAI_API_KEY environment variable"
-- "Add a WEBHOOK_SECRET variable for the inbound webhook workflow"
-- "Update the SCORING_API_URL variable to point to the new endpoint"
-- "What environment variables are currently set?"
+Complete OAuth authorization or enter the credential in the provided secure control. A Google connection for one service does not automatically authorize every Google service.
 
-{/* TODO: Screenshot of Sim confirming an environment variable was set — e.g., a response message showing the variable name was saved. */}
+Select the intended account for each action or workflow block. Available credentials depend on ownership, sharing, and workspace policy. Ask "Which integrations are connected?" or inspect **Integrations** to identify existing connections.
 
-## MCP Servers
+## Manage secrets [#environment-variables]
 
-MCP (Model Context Protocol) servers expose tools from external services that Agent blocks can call inside workflows. Connecting an MCP server makes all of its tools available in the workflow editor's tool picker — no custom integration code required.
+Save API keys, connection strings, and configuration under **Secrets**. Choose personal or workspace scope according to the intended execution and access:
 
-Sim can add and manage MCP servers connected to your workspace:
+- "Add an OPENAI_API_KEY secret for this workspace."
+- "Set a personal DATABASE_URL connection string."
+- "Add WEBHOOK_SECRET for the inbound webhook workflow."
+- "Update SCORING_API_URL to [endpoint]."
+- "List the configured environment variable names."
 
-- "Add the Stripe MCP server using my API key"
-- "Remove the old analytics MCP server"
-- "What MCP servers are connected to this workspace?"
-- "Update the endpoint for the internal tools MCP server to [URL]"
+Provide secret values through the secure input when requested. Workflows reference environment variables with `{{ENV_VAR}}`; resolution depends on scope, grants, and execution context. See [workflow variables and secrets](/workflows/variables#environment-variables) for those rules.
 
-Once added, MCP tools appear in the workflow editor's tool picker and can be called from any Agent block.
+## Add an MCP server [#mcp-servers]
 
-{/* TODO: Screenshot of Sim confirming an MCP server was added or updated — showing the server name and its status. */}
+An MCP (Model Context Protocol) server exposes tools from another service. Ask Sim to add or manage an external server:
 
-## Custom Tools
+- "Add the internal tools MCP server at [URL] using its API key."
+- "Update that server's endpoint to [URL]."
+- "List the MCP servers connected to this workspace."
+- "Remove the old analytics MCP server."
 
-[Custom tools](/agents/custom-tools) combine a JSON parameter schema with a JavaScript function body. Use one for an internal API call, calculation, or reusable transformation, then add it to an Agent block's tools.
+Available, permitted tools can be selected for Agent blocks in the workflow builder. To use a server's tools directly in Chat, attach the server to the conversation. Server connection, tool discovery, and policy must permit the operation.
 
-Sim can build custom tools from a description:
+## Create a custom tool [#custom-tools]
 
-- "Create a custom tool that calls our internal scoring API at [URL] with a POST request and returns the score field"
-- "Build a tool for our Zendesk instance that creates a ticket with a subject and body"
-- "Create a tool that hits our internal enrichment API with a domain and returns company size, industry, and funding stage"
-- "Add a tool that calls our CRM's REST API to look up a contact by email and return their account owner"
+A custom tool combines a JSON parameter schema with a JavaScript function body. Describe its inputs, service call or calculation, and returned value:
 
+- "Create a tool that POSTs to our scoring API at [URL] and returns the score field."
+- "Create a Zendesk tool that opens a ticket with a subject and body."
+- "Create an enrichment tool that takes a domain and returns company size, industry, and funding stage."
+- "Create a CRM tool that looks up a contact by email and returns the account owner."
 
+Add the resulting tool to an Agent block's tools and configure the credentials it needs. Verify it with an input appropriate for its external effects.
 
-{/* TODO: Screenshot of Chat with the Custom Tool subagent active — showing it building a tool definition. */}
+## Related docs
 
-<FAQ items={[
-  { question: "What's the difference between a scheduled job and a deployed workflow?", answer: "A scheduled job runs a Chat prompt on a cron schedule — Sim decides what to do each time based on current workspace state. A deployed workflow runs a saved graph of blocks, which can include Agent reasoning. Use jobs when you want Sim to reason and adapt; use workflows when you want predictable, auditable execution." },
-  { question: "Can a scheduled job trigger a workflow?", answer: "Yes. Include it in the job prompt: 'Run the invoice sync workflow and then post the results to Slack.'" },
-  { question: "Can direct actions be undone?", answer: "It depends on the service and action. Some records can be edited or deleted afterward; sending an email cannot be undone by deleting the Chat task." },
-  { question: "How do I know what integrations are connected?", answer: "Ask Sim: 'What integrations are connected to this workspace?' or check the Integrations page." },
-  { question: "How do workflows reference environment variables?", answer: "Use {{ENV_VAR}} syntax. Resolution depends on the variable's scope and the execution context." },
-]} />
+- [Schedule triggers](/workflows/triggers/schedule)
+- [Workflows in Chat](/chat/workflows)
+- [Credentials](/platform/credentials)
+- [MCP servers for agents](/agents/mcp)
+- [Custom tools](/agents/custom-tools)
diff --git a/apps/docs/content/docs/chat/workflows.mdx b/apps/docs/content/docs/chat/workflows.mdx
index ec95fa219f2..c3e616e856f 100644
--- a/apps/docs/content/docs/chat/workflows.mdx
+++ b/apps/docs/content/docs/chat/workflows.mdx
@@ -1,116 +1,117 @@
 ---
 title: Workflows
-description: Create, edit, run, debug, deploy, and organize workflows from Chat.
+description: Create, edit, run, debug, and deploy workflows from Chat.
 ---
 
-import { Video } from '@/components/ui/video'
-import { FAQ } from '@/components/ui/faq'
+Ask Sim to build a workflow or change an existing one. Open the workflow in Chat's resource panel to inspect the result in the workflow builder. Creation, editing, execution, and deployment require the relevant workspace access.
 
-<Video src="mothership/create-workflow.mp4" width={700} height={450} />
+## Create a workflow [#creating-workflows]
 
-Describe a workflow and Sim builds it. Reference an existing one by name and Sim edits it. No canvas navigation required — every change appears in the resource panel in real time.
+Describe the trigger, inputs, processing steps, integrations, and expected output. For example:
 
-## Creating Workflows
+- "Build a workflow that takes a URL, reads the page, summarizes it with Claude, and sends the summary to a Slack channel."
+- "Create a webhook workflow that extracts invoice data from a PDF and writes it to the billing table."
+- "Build an outbound workflow: enrich a company name and domain, score the fit, and draft a personalized email."
+- "Create a lead enrichment workflow that takes an email from a form submission, looks up the company, and writes the enriched record to the leads table."
+- "When a new customer signs up, send a welcome email, create a HubSpot contact, and notify #new-customers in Slack."
 
-Describe what the workflow should do — what triggers it, what it should do, which integrations it needs, and what it should return. Sim builds it and opens the canvas in the resource panel.
+Sim can create the blocks and connections and help configure the required accounts. Inspect the workflow and resolve any missing credentials or inputs before running it.
 
-- "Build a workflow that takes a URL, scrapes the page, summarizes it with Claude, and sends the summary to a Slack channel"
-- "Create a workflow triggered by a webhook that extracts invoice data from a PDF and writes it to the billing table"
-- "Build an outbound workflow: take a company name and domain, enrich it with firmographic data, score the fit, and draft a personalized cold email"
-- "Create a lead enrichment workflow that takes an email from a form submission, looks up the company, and writes the enriched record to the leads table"
-- "Build a customer onboarding workflow: when a new user signs up, send a welcome email, create a HubSpot contact, and post a notification to #new-customers in Slack"
+## Edit the draft [#editing-workflows]
 
-## Editing Workflows
+Open the workflow with an `@`-mention or the **+** menu, then name the change:
 
-{/* TODO: Screenshot of Chat with the Edit subagent active and a change applied to an open workflow — e.g., a new block added or a configuration updated, visible on the canvas in the resource panel. */}
+- "Add a branch for confidence scores below 0.7."
+- "Replace GPT-4o with Claude Opus 5 on the summarizer block."
+- "Add a Slack notification containing the final output."
 
-Open an existing workflow with `@workflow-name` or the **+** menu, then describe the change. Sim reads the current structure before modifying it — you don't need to explain what already exists.
+Sim reads the existing structure before applying changes. Editing a deployed workflow changes its draft; the active deployment remains a snapshot until you successfully redeploy or activate another version.
 
-- "Add a condition that routes to a different branch if the confidence score is below 0.7"
-- "Replace the GPT-4o model with Claude Opus 5 on the summarizer block"
-- "Add a Slack notification at the end that includes the output"
+### Workflow variables
 
-## Running Workflows
+Workflow variables hold values available across that workflow's blocks at runtime:
 
-<Video src="mothership/run-workflow.mp4" width={700} height={450} />
+- "Set API_ENDPOINT on the sync workflow to 'https://api.example.com/v2'."
+- "Set MAX_RETRIES on the pipeline workflow to 5."
 
-Ask Sim to run a workflow and it handles the execution:
+Reference them with `<variable.VARIABLE_NAME>`. These are workflow values, distinct from personal or workspace secrets referenced with `{{ENV_VAR}}`.
 
-- "Run the data sync workflow"
-- "Run the invoice processor with this PDF [attach file]"
-- "Test the lead scoring workflow with these inputs: name=Acme, score=0.4"
+## Run a workflow [#running-workflows]
 
-Execution streams back to the chat. The workflow in the resource panel shows live block-by-block state.
+Specify whether you want to test the draft or run the deployed version, and provide the Start block's inputs:
 
-## Reading Logs
+- "Run the deployed data sync workflow."
+- "Test the invoice processor draft with this PDF." Attach the file.
+- "Test the lead scoring draft with name=Acme and score=0.4."
 
-Sim can retrieve and interpret execution logs for any workflow in the workspace:
+A live run in the workflow builder shows block-by-block progress. Background runs can be checked through their execution logs. Ask Sim for the outcome and the execution to inspect when a run finishes.
 
-- "Show me the last 10 runs of the pipeline workflow"
+Test runs can send messages, call APIs, and change data through connected services. Use inputs and accounts appropriate for those effects, and review any required tool approval before the run.
+
+## Read logs [#reading-logs]
+
+Ask about executions you can access:
+
+- "Show the last 10 runs of the pipeline workflow."
 - "Why did the invoice workflow fail yesterday?"
 - "What did the extractor block return in the most recent run?"
 
-Logs include per-block execution state, outputs, errors, and timing.
-
-## Debugging
+Logs include block execution state, outputs, errors, and timing. Name the workflow and run or time range so Sim can inspect the intended execution.
 
-When a workflow fails, tell Sim to debug it:
+### Debug a failure [#debugging]
 
-- "Debug the last failed run of the content pipeline"
-- "The summarizer block is returning empty output — figure out why"
+Ask Sim to investigate and, when appropriate, fix the draft:
 
-Sim reads the failure logs, identifies the cause, applies a fix, and can re-run to confirm.
+- "Debug the last failed run of the content pipeline and test the fix."
+- "The summarizer block returns empty output. Check its inputs and the last run's logs."
 
-{/* TODO: Screenshot of the Debug subagent section in Chat showing it reading logs and applying a fix. */}
+Inspect the proposed change and the verification result. A successful draft test does not update the deployed workflow.
 
-## Deploying
+## Deploy a workflow [#deploying]
 
-Sim can deploy a workflow as any of the three deployment types:
+Choose the interface callers need:
 
-| Deployment type | What it creates |
-|----------------|----------------|
-| **API** | A REST endpoint at `https://www.sim.ai/api/v2/workflows/{id}/execute` |
-| **Chat** | A hosted conversational interface with a shareable URL |
-| **MCP tool** | An MCP server that exposes the workflow as a tool |
+| Interface | Result |
+| --- | --- |
+| API | An execution endpoint at `/api/v2/workflows/{id}/execute` on your deployment's configured host |
+| Chat | A conversational interface with a shareable URL and configured access settings |
+| MCP tool | The workflow added as a tool on a workflow MCP server |
 
-Ask: "Deploy the invoice workflow as an API and generate an API key."
+For example: "Deploy the invoice workflow as an API and generate an API key."
 
-Sim can also roll back: "Revert the billing workflow to the version from last Tuesday."
+Review the returned deployment status and URL. A pending or failed deployment attempt does not prove the requested version is serving. API keys are shown once in a secure copy control; copy a new key when it is created.
 
-See [API Deployment](/workflows/deployment/api) and [Chat Deployment](/workflows/deployment/chat) for full details on each deployment type.
+Sim can also help configure reusable [custom blocks](/platform/enterprise/custom-blocks) where available. These appear in the workflow builder rather than creating another external endpoint.
 
-## Organizing Workflows
+### Restore or roll back a version
 
-Sim can create and manage folders to keep your workspace organized.
+Be explicit about the state you want to change:
 
-**Folders:**
-- "Create a folder called 'Data Pipelines'"
-- "Move the invoice workflow into the billing folder"
-- "Move the billing folder inside the finance folder"
-- "Delete the old-experiments folder"
+- "Restore last Tuesday's version of the billing workflow into the draft."
+- "Roll the billing workflow's live deployment back to version 3."
 
-**Renaming and moving:**
-- "Rename the 'test_v2' workflow to 'lead-scorer'"
-- "Move the summarizer workflow to the research folder"
+Restoring the draft does not change what callers run. Rolling back the active deployment changes the serving version and leaves the draft separate.
 
-{/* TODO: Screenshot showing Sim confirming a folder or workflow organization action — e.g., a message confirming "Moved 'invoice-processor' into 'billing' folder" with the resource panel showing the folder open. */}
+## Organize workflows [#organizing-workflows]
 
-## Workflow Variables
+Ask Sim to create folders, move workflows or folders, and rename workflows:
 
-Sim can set global variables on a workflow — values accessible across all blocks in that workflow at runtime:
+- "Create a folder called 'Data Pipelines' and move the sync workflow into it."
+- "Move the billing folder inside the finance folder."
+- "Rename 'test_v2' to 'lead-scorer' and move it to the research folder."
 
-- "Set the API_ENDPOINT variable on the sync workflow to 'https://api.example.com/v2'"
-- "Update the MAX_RETRIES variable on the pipeline workflow to 5"
+## Delete workflows [#deleting-workflows]
 
-Variables set this way are available via `<variable.VARIABLE_NAME>` syntax inside any block in the workflow.
+Deleting a workflow removes it from the active workspace and disables its deployments. Its API, chat, and MCP entry points stop working. Identify the exact workflows or folder contents before deleting them:
 
-## Deleting Workflows
+- "Delete the old_api_prototype workflow."
+- "Delete all workflows in the deprecated folder."
+- "Delete the old-experiments folder and its contents."
 
-- "Delete the old_api_prototype workflow"
-- "Delete all workflows in the deprecated folder"
+## Related docs
 
-<FAQ items={[
-  { question: "Can Sim edit a workflow while it's deployed?", answer: "Yes. Editing a workflow does not affect the live deployment. The deployed version is a snapshot — you need to ask Sim to redeploy to push changes to production." },
-  { question: "What happens to a workflow's deployment when I delete it?", answer: "Deleting a workflow removes it from the active workspace and disables its deployments. Any API endpoints, chat URLs, or MCP tools that pointed to that workflow will stop working." },
-  { question: "Can I run a workflow with specific inputs from Chat?", answer: "Yes. Describe the inputs in your message and Sim passes them to the workflow's start block." },
-]} />
+- [Workflow variables](/workflows/variables)
+- [API deployment](/workflows/deployment/api)
+- [Chat deployment](/workflows/deployment/chat)
+- [MCP deployment](/workflows/deployment/mcp)
+- [Logs and debugging](/logs-debugging)
diff --git a/apps/docs/content/docs/cli/audit-logs.mdx b/apps/docs/content/docs/cli/audit-logs.mdx
index a03c7a7c136..688d5e6c240 100644
--- a/apps/docs/content/docs/cli/audit-logs.mdx
+++ b/apps/docs/content/docs/cli/audit-logs.mdx
@@ -1,22 +1,57 @@
 ---
-title: Audit Logs
-description: Manage audit logs — every subcommand, argument, and flag
+title: Audit logs
+description: Read organization audit actions and filter by actor, resource, workspace, or time.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Read organization audit actions and filter by actor, resource, workspace, or time.
+
+Requires an organization Admin or owner, an OAuth login or personal API key, and enabled enterprise audit access for the deployment.
+
 `sim audit-logs` is also spelled `sim audit-log`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
+
+## List audit logs
+
+OAuth login or personal API key required.
+
+```bash
+sim audit-logs list [options]
+```
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--action <value>` | No | Filter by exact action name. |
+| `--resource-type <value>` | No | Filter by resource type. Accepts a comma-separated set; members are trimmed and deduplicated, and member order affects neither the result nor the cursor. |
+| `--resource-id <value>` | No | Filter by exact resource identifier. |
+| `--start-date <value>` | No | Include audit entries created at or after this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected. |
+| `--end-date <value>` | No | Include audit entries created at or before this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected. |
+| `--include-departed` | No | Include actions by users who have left the organization. |
+| `--no-include-departed` | No | Send --include-departed as false. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--organization <value>` | No | Organization whose audit trail to read; defaults to the caller’s organization. A caller that belongs to no organization, or names one it does not belong to, is refused with 403. |
+| `--actor-email <value>` | No | Filter by actor email address. |
+| `--all-workspaces` | No | Do not filter to the configured workspace (OAuth login or personal API key required for account-wide access). |
+
+</CommandTable>
+
+API request and response schemas: [listAuditLogs](/api-reference/audit-logs/listAuditLogs).
 
 ## Get audit log
 
+OAuth login or personal API key required.
+
 ```bash
 sim audit-logs get <auditLogId> [options]
 ```
 
-Get Audit Log (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -33,35 +68,13 @@ Get Audit Log (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--organization <value>` | No | Organization ID; defaults to your only organization, and is required when your account belongs to more than one (OAuth login or personal API key required). |
+| `--organization <value>` | No | Organization whose audit trail to read; defaults to the caller’s organization. A caller that belongs to no organization, or names one it does not belong to, is refused with 403. |
 
 </CommandTable>
 
-## List audit logs
-
-```bash
-sim audit-logs list [options]
-```
-
-List Audit Logs (OAuth login or personal API key required)
-
-**Options**
-
-<CommandTable>
+API request and response schemas: [getAuditLog](/api-reference/audit-logs/getAuditLog).
 
-| Option | Required | Description |
-| --- | --- | --- |
-| `--action <value>` | No | Filter by exact action name. |
-| `--resource-type <value>` | No | Filter by resource type. Accepts a comma-separated set; members are trimmed and deduplicated, and member order affects neither the result nor the cursor. |
-| `--resource-id <value>` | No | Filter by exact resource identifier. |
-| `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
-| `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
-| `--include-departed` | No | Include actions by users who have left the organization. |
-| `--no-include-departed` | No | Send --include-departed as false. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--organization <value>` | No | Organization ID; defaults to your only organization, and is required when your account belongs to more than one (OAuth login or personal API key required). |
-| `--actor-email <value>` | No | Filter by actor email address. |
-| `--all-workspaces` | No | Do not filter to the configured workspace (OAuth login or personal API key required for account-wide access). |
+## Related docs
 
-</CommandTable>
+- [Organization permissions](/platform/permissions)
+- [Authentication](/cli/authentication)
diff --git a/apps/docs/content/docs/cli/authentication.mdx b/apps/docs/content/docs/cli/authentication.mdx
index e9c8afb91f1..e4d0cabf6dd 100644
--- a/apps/docs/content/docs/cli/authentication.mdx
+++ b/apps/docs/content/docs/cli/authentication.mdx
@@ -1,20 +1,11 @@
 ---
 title: Authentication
-description: Sign in from the terminal, authenticate CI with an API key, and keep several accounts side by side
+description: Sign in locally, authenticate CI, and share a login across workspace profiles.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
-<Callout>
-These settings apply to the CLI you install locally. When Sim runs a `sim`
-command for you inside Chat, it uses your session identity — there is no profile,
-no `sim login`, and no config file.
-</Callout>
-
-`sim login` signs you in through your browser. It prefers OAuth, which stores a
-short-lived login that renews itself, and selects API-key pairing for remote
-terminals or servers without OAuth support. In CI you supply an existing API
-key through the environment instead.
+Use `sim login` for a stored browser-approved login, or supply an existing API key for CI. These settings apply to the installed CLI. Commands Sim runs inside Chat use your session identity; local login and profile-management commands are unavailable. See [Configuration](/cli/configuration) for that boundary.
 
 ## Signing in
 
@@ -22,28 +13,28 @@ key through the environment instead.
 sim login
 ```
 
-Choose a method explicitly when the credential type matters:
+The CLI prefers OAuth on a local machine. SSH sessions and headless Linux terminals select API-key pairing; a server without OAuth also selects pairing when no method is specified. An unreachable server is an error, not a reason to fall back.
+
+| Method | Credential and requirements |
+| --- | --- |
+| OAuth | Short-lived access token with automatic renewal; requires server OAuth and a browser that can reach the CLI's loopback callback |
+| API-key pairing | Permanent personal API key; approval can happen on another device, and the server must support `platform` API-key pairing |
+| Existing API key | Supply `SIM_API_KEY`; no browser or stored login is required |
+
+Choose the method explicitly when the credential type matters:
 
 ```bash
 sim login --method oauth
 sim login --method api-key
 ```
 
-`--method oauth` requires a server with OAuth support and authentication enabled;
-it never falls back to an API key. Explicit OAuth selection also overrides
-SSH/headless detection; your browser still needs to reach the CLI's
-local callback. `--method api-key` uses pairing-code approval to create a new
-permanent API key. To supply an existing key, set `SIM_API_KEY` instead.
+Explicit OAuth never falls back and overrides remote-session detection. Pairing creates a new key; use `SIM_API_KEY` to supply one you already have. Older deployments that issue only `copilot` keys must be upgraded: those keys cannot authenticate the platform CLI. OAuth discovery does not verify pairing compatibility.
 
-API-key pairing requires a server that supports `platform` API keys. Upgrade
-older deployments that only issue `copilot` keys before starting login; those
-keys cannot authenticate the platform CLI.
+### OAuth approval
 
-OAuth login opens your browser on Sim's sign-in page, then on a consent page that
-names the Sim CLI and what it will be able to do. Approve, and the browser hands
-control back to the terminal:
+The CLI opens Sim's sign-in page and then a consent page naming the Sim CLI and its requested access. Approve the request to return control to the terminal:
 
-```
+```text
 Signing in to https://www.sim.ai as profile default
 
 https://www.sim.ai/api/auth/oauth2/authorize?client_id=sim-cli&…
@@ -55,41 +46,35 @@ Waiting for you to approve in the browser…
   No default workspace. Set one with: sim configure --set-workspace <id>
 ```
 
-This is the OAuth 2.0 authorization-code flow with PKCE and a loopback redirect,
-aligned with current OAuth security guidance. The browser only ever carries a one-time code;
-the tokens are exchanged over the terminal's own connection and written to
-`~/.sim/credentials` with `0600` permissions. Access tokens last an hour and are
-renewed automatically from a refresh token. The complete login has a fixed
-30-day lifetime; after it expires, run `sim logout`, then sign in again.
+The login uses an authorization code, Proof Key for Code Exchange (PKCE), and a loopback redirect. The browser returns a one-time code; the terminal exchanges it for tokens over its own connection. Tokens are stored in `~/.sim/credentials` with `0600` permissions.
+
+Access tokens last one hour. The refresh-token family has a fixed 30-day lifetime; renewal does not extend it. After expiry, log out and sign in again.
 
 <Callout type="warn">
-Only approve a consent page you reached by running `sim login` yourself. A
-consent page that appears unprompted, or one you were sent a link to, is not
-your login.
+Only approve a consent request you reached by running `sim login` yourself. An unprompted consent page or a link sent by someone else does not belong to your login.
 </Callout>
 
-| Option | What it does |
+| Option | Behavior |
 | --- | --- |
-| `--method <method>` | `oauth` requires OAuth login; `api-key` creates a permanent key through pairing. Auto-selects when omitted |
+| `--method <method>` | Choose `oauth` or `api-key`; auto-select when omitted |
 | `--no-browser` | Print the approval URL without opening it; works with either method |
-| `--read-only` | Ask only for permission to read, never to change anything |
-| `--callback-port <port>` | Pin the loopback callback port, primarily for an SSH session that forwards the same fixed port |
-| `-y, --yes` | Overwrite an existing API-key profile without prompting |
+| `--read-only` | Request OAuth read access; pairing cannot issue this credential |
+| `--callback-port <port>` | Pin the OAuth loopback port, from 1 to 65535, for example for an SSH tunnel |
+| `-y, --yes` | Confirm overwriting an existing stored API key |
+
+A profile holds one stored credential. Replacing an API key requires confirmation or `--yes`. An existing OAuth login must be revoked with `sim logout` before another login; `--yes` does not bypass this.
 
 ### Over SSH or in a container
 
-OAuth login needs your browser to reach a listener on the machine running
-`sim`. When it cannot — an SSH session, a dev container, a remote box — use the
-API-key pairing flow. The CLI selects it automatically in an SSH session when
-no method or callback port is specified:
+OAuth needs the browser to reach a listener on the machine running `sim`. Use pairing when that connection is unavailable:
 
 ```bash
 sim login --method api-key --no-browser
 ```
 
-The terminal prints a pairing code and a URL you can open on any device:
+The terminal prints a code and an approval URL you can open on another device:
 
-```
+```text
 Signing in to https://www.sim.ai as profile default
 
 Pairing code: K7M2-P9XT
@@ -103,30 +88,24 @@ Waiting for approval…
 ```
 
 <Callout type="warn">
-Confirm the pairing code in the browser matches the one in your terminal before
-approving. That check is what binds the approval to your terminal.
+Compare the pairing code in the browser with your terminal before approving. This binds the approval to your terminal. Pairing creates a permanent personal key; revoke it in **Settings → Sim API keys** when you no longer need it.
 </Callout>
 
-The handoff issues a permanent personal API key rather than a renewing login,
-so revoke it under **Settings → API keys** when you are done with that machine.
-It also works when OAuth is unavailable or switched off, provided the server
-supports platform API-key pairing. When `--method` is omitted, the CLI checks
-OAuth availability and selects pairing if unavailable; that discovery does not
-verify pairing compatibility. An explicit `--method oauth` fails in that case.
-
-`--read-only` and `--callback-port` belong to OAuth login and have no
-meaning here, so combining either with the handoff stops the login rather than
-storing a credential you did not ask for. If your SSH session forwards a port
-from the remote loopback interface to the browser's machine, use
-`--method oauth --callback-port <port>` with that port. An ordinary container port publication
-cannot reach a listener bound to the container's own loopback interface; use
-`--method api-key` there.
+`--read-only` and `--callback-port` are OAuth-only. Combining either with pairing stops login instead of silently ignoring the option.
+
+For an SSH tunnel that forwards the remote loopback port to your browser's machine, choose OAuth and specify that same port:
+
+```bash
+sim login --method oauth --callback-port 8765 --no-browser
+```
+
+Supplying a callback port also overrides automatic SSH detection. An ordinary container port publication cannot reach a listener bound to the container's own loopback interface; use pairing there unless you provide a working loopback route.
 
 ### Picking a workspace
 
-A normal login can act across every workspace you belong to; `--read-only`
-limits it to read operations. The profile's `workspace` setting only decides the default target.
-Set it after signing in, or pass `--workspace` per command:
+A personal login can act in accessible workspaces, subject to current roles, policies, and resource access. `--read-only` narrows OAuth scope; a default workspace only selects a target and does not narrow credential scope.
+
+After OAuth login, select a default or pass a workspace per command:
 
 ```bash
 sim workspaces list
@@ -134,66 +113,39 @@ sim configure --set-workspace 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
 sim workflows list --workspace 9b4c7e02-1d58-4f36-a0c9-6e2b85df413a
 ```
 
-With the pairing-code handoff you choose the default workspace on the approval
-page instead.
+Pairing sets the default workspace chosen on the approval page.
 
-To target another workspace without a second login, add a workspace profile:
+To reuse a stored login with another default workspace:
 
 ```bash
 sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
 sim --profile acme whoami
 ```
 
-The new profile stores `auth_profile = default` and its own workspace. Omit
-`--workspace` in an interactive terminal to choose from the workspaces your
-login can access; scripts must provide the workspace ID explicitly. The picker
-is capped at 1,000 entries and asks for an explicit ID above that.
+The new profile references the active authentication profile through `auth_profile` and stores its own workspace. With the default login active, that reference is `auth_profile = default`.
+
+Omit `--workspace` in an interactive terminal to choose an accessible workspace. The picker is capped at 1,000 entries; scripts and larger inventories require an explicit ID. See [Configuration](/cli/configuration) for profile resolution.
 
 ## Checking who you are
 
 ```bash
-sim whoami                # resolved settings, plus a live check that they work
-sim whoami --no-verify    # resolved settings only, no request
+sim whoami
+sim whoami --no-verify
 ```
 
-Prints the resolved endpoint, workspace, and output format, which source each
-value came from, and whether the profile holds an OAuth login or an API key,
-then reads the configured workspace to prove the credential is accepted and can
-reach it.
-
-It exits `0` when the check passes, `1` when the credentials are wrong, and `2`
-when the check could not be made at all — no workspace to check against, or an
-endpoint that did not answer. The split matters in CI: only `1` is fixed by
-logging in again.
-
-## Signing out
-
-```bash
-sim logout           # sign out of Sim and remove the stored login
-sim logout --all     # remove the profile entirely, including its settings
-```
+`whoami` reports the endpoint, credential type, workspace, output format, and where each setting came from. It checks authentication through API metadata when available, then reads the selected workspace to verify access. Older servers can fall back to the workspace check.
 
-For an OAuth login, `sim logout` revokes that login's complete token family
-before removing it from disk, including access tokens issued before earlier
-rotations. Other machines that ran their own `sim login` remain signed in. To
-cut off every independent login for the client, revoke the grant under
-**Settings → General → Authorized apps**.
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Verification succeeded, or `--no-verify` skipped it |
+| `1` | Missing credentials or a definitive refusal, including inaccessible or missing workspace |
+| `2` | Verification could not finish, including no selected workspace or an unreachable endpoint |
 
-A workspace profile that shares authentication cannot remove the shared login.
-Remove only that local profile with `sim logout --all --profile <name>`, or log
-out of the authentication profile named by the error message. Removing an
-authentication profile entirely is refused until its workspace profiles are
-removed, so it cannot leave dangling references.
-
-<Callout type="warn">
-For a login created with `--method api-key`, `sim logout` removes the API key from
-disk but does **not** revoke it. Revoke keys under **Settings → API keys**.
-</Callout>
+For exit 1, inspect the endpoint and workspace before signing in again. A valid login cannot fix a wrong workspace or missing permission. Use `--no-verify` for offline inspection.
 
 ## Authenticating CI
 
-Set an API key and workspace in the environment; no saved login is required,
-and the environment key overrides any stored login:
+Create a key under **Settings → Sim API keys**, then store it in your CI secret manager. Supply the key and workspace without running login:
 
 ```bash
 export SIM_API_KEY="sim_…"
@@ -202,14 +154,12 @@ export SIM_WORKSPACE="2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67"
 sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --input '{"source":"nightly"}' --output json
 ```
 
-Create the key in Sim under **Settings → Sim API keys**. Store it as a secret in your
-CI provider — never commit it.
-
-`SIM_CONFIG_DIR` relocates both files if you need them somewhere other than
-`~/.sim`, such as a runner with no writable home directory.
+The environment key overrides stored authentication. Use a workspace key only for supported workspace-scoped operations; organization audit logs and fork administration require a personal credential. Never commit credentials. `SIM_CONFIG_DIR` relocates local state when a runner has no writable home directory.
 
 ### GitHub Actions
 
+This job installs Node for the CLI and Bun to install the package. Add it to a workflow with your chosen trigger:
+
 ```yaml title=".github/workflows/nightly.yml"
 jobs:
   digest:
@@ -218,16 +168,19 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: '20'
-      - run: npm install -g sim
+      - uses: oven-sh/setup-bun@v2
+      - run: bun add -g sim
       - run: sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --output json
         env:
           SIM_API_KEY: ${{ secrets.SIM_API_KEY }}
           SIM_WORKSPACE: ${{ vars.SIM_WORKSPACE }}
 ```
 
+See [Scripting](/cli/scripting) for asynchronous runs and command-specific failure handling.
+
 ## Several accounts and workspaces
 
-Use separate logins for separate identities or deployments:
+Use separate authentication profiles for different identities or deployments:
 
 ```bash
 sim login --profile dev --endpoint http://localhost:3000
@@ -237,7 +190,7 @@ sim workflows list --profile dev
 sim workflows list --profile prod
 ```
 
-Use workspace profiles when one login should target several workspaces:
+Use shared workspace profiles when the same stored identity targets several workspaces:
 
 ```bash
 sim profile add marketing --workspace c3a70e58-9f21-4d6b-b842-05e7f19c6a3d
@@ -247,33 +200,29 @@ sim workflows list --profile marketing
 sim workflows list --profile support
 ```
 
-See [Configuration](/cli/configuration) for how profiles are stored and resolved.
+Shared profiles retain separate workspace/output settings but share an endpoint and stored login. References are direct, never chained. Log in against the authentication profile rather than a profile that shares it.
 
 ## Self-hosted and non-production deployments
 
-Point the CLI at any deployment with `--endpoint`, then sign in against it:
+Use HTTPS for remote sign-in. Both OAuth and pairing refuse non-loopback HTTP endpoints. Loopback development addresses can use HTTP:
 
 ```bash
 sim login --profile local --endpoint http://localhost:3000
 ```
 
-Save it to avoid repeating the flag:
+Login saves the endpoint. You can also configure it before signing in:
 
 ```bash
 sim configure --set-endpoint http://localhost:3000 --profile local
 ```
 
-OAuth sign-in is available by default when server authentication is enabled.
-`DISABLE_AUTH=true` disables OAuth. Servers without OAuth use the pairing-code
-handoff when they support platform API keys. See
-[Sign in with Sim](/platform/self-hosting/authentication#sign-in-with-sim) for
-server configuration and upgrade requirements.
+An OAuth login belongs to its issuing deployment. Log out before changing or removing that endpoint. API keys must also belong to the selected deployment.
+
+OAuth is available by default when server authentication is enabled. `DISABLE_AUTH=true` disables OAuth. Servers without OAuth can use pairing if they support platform API keys. See [Sign in with Sim](/platform/self-hosting/authentication#sign-in-with-sim) for server setup and upgrade requirements.
 
 ## Where the login is stored
 
-Logins live in `~/.sim/credentials`, written `0600`, separate from the non-secret
-`~/.sim/config`. Commit `config` to a dotfiles repo if you like; never
-`credentials`.
+Stored authentication lives in `~/.sim/credentials`, written `0600`. Non-secret defaults live separately in `~/.sim/config`. Never copy credentials into a dotfiles repository:
 
 ```ini title="~/.sim/credentials"
 [default]
@@ -288,20 +237,41 @@ oauth_scope = offline_access api:read api:write
 api_key = sim_…
 ```
 
-A profile holds one login. A stored API key can be replaced after confirmation
-or with `--yes`; a live OAuth login must be revoked with `sim logout` before
-signing in again. Several `sim` commands running at once share one renewal, so
-a parallel shell loop cannot sign itself out.
+Concurrent local commands coordinate OAuth renewal through the credentials lock. A process rereads credentials after taking the lock and adopts an already-renewed token instead of reusing the old refresh token.
 
-Run `sim login` separately on each machine. Copying `~/.sim/credentials` copies
-one single-use refresh-token family; simultaneous use from both copies is
-treated as token replay and revokes that login. If a refresh response is lost
-because the process or connection stops, the CLI does not retry the consumed
-token: run `sim logout`, then `sim login` again. This fail-closed behavior keeps
-a copied token from surviving an ambiguous refresh.
+Run login separately on each machine. Copying the credentials file copies one single-use refresh-token family. Concurrent use of those copies can be treated as replay and revoke that login.
+
+If a refresh response is lost after the server consumes the token, the CLI does not retry that token. Recover with logout and a new login:
+
+```bash
+sim logout --profile dev
+sim login --profile dev
+```
+
+## Signing out
+
+```bash
+sim logout
+sim logout --all
+```
+
+The first command removes stored authentication; `--all` also removes the profile's settings.
+
+For OAuth, logout revokes that login's complete token family before clearing it locally, including access tokens from earlier rotations. Independent logins on other machines remain signed in. To revoke the client's grant across independent logins, use **Settings → General → Authorized apps**.
+
+A workspace profile cannot remove its shared login. Remove only that local profile with `sim logout --all --profile <name>`, or log out of its authentication profile. Deleting an authentication profile entirely is refused while workspace profiles still reference it.
+
+<Callout type="warn">
+For API-key authentication, `sim logout` removes the local key but does not revoke it. Revoke the personal key under **Settings → Sim API keys**.
+</Callout>
 
 ## Organization audit logs
 
-`sim audit-logs` requires a **personal** credential — an OAuth login, or the
-personal API key `sim login --method api-key` issues. A workspace-scoped key cannot
-read organization-level audit logs.
+`sim audit-logs` requires a personal credential: an OAuth login or personal API key. Pairing creates a personal key. A workspace key cannot read organization audit logs.
+
+## Related docs
+
+- [Configuration](/cli/configuration)
+- [Scripting](/cli/scripting)
+- [Profiles commands](/cli/profiles)
+- [Troubleshooting](/cli/troubleshooting)
diff --git a/apps/docs/content/docs/cli/billing.mdx b/apps/docs/content/docs/cli/billing.mdx
index 2058936e030..0e0f5cf781d 100644
--- a/apps/docs/content/docs/cli/billing.mdx
+++ b/apps/docs/content/docs/cli/billing.mdx
@@ -1,20 +1,22 @@
 ---
 title: Billing
-description: Manage billing — every subcommand, argument, and flag
+description: Read billing status, credit usage, and storage usage.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+Read billing status, credit usage, and storage usage.
 
-## Show billing status, credits spent this period, and storage used
+These commands accept the [global options](/cli/commands#global-options).
+
+## Show billing status, credits spent, and storage used
+
+Credits and storage require an OAuth login or personal API key.
 
 ```bash
 sim billing status [options]
 ```
 
-Show billing status, credits spent this period, and storage used (credits and storage require an OAuth login or personal API key)
-
 **Options**
 
 <CommandTable>
@@ -25,22 +27,24 @@ Show billing status, credits spent this period, and storage used (credits and st
 
 </CommandTable>
 
+API request and response schemas: [getBillingStatus](/api-reference/billing/getBillingStatus).
+
 ## List credit usage events
 
+An OAuth login or personal API key reports only your events; a workspace API key reports every member's in aggregate, unattributed.
+
 ```bash
 sim billing logs [options]
 ```
 
-List credit usage events (an OAuth login or personal API key reports only your events; a workspace API key reports every member's in aggregate, unattributed)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--source <value>` | No | Filter by usage source; sim-chat combines Copilot and workspace chat. Accepted values: `workflow`, `wand`, `sim-chat`, `mcp_copilot`, `mothership_block`, `knowledge-base`, `voice-input`, `enrichment`, `voice-output`, `api-tool`. |
-| `--period <value>` | No | Billing period. Accepted values: `1d`, `7d`, `30d`, `all`, `custom`. |
+| `--source <value>` | No | Filter by usage source; sim-chat combines Sim agent and workspace Chat usage. Accepted values: `workflow`, `wand`, `sim-chat`, `mcp_copilot`, `mothership_block`, `knowledge-base`, `voice-input`, `enrichment`, `voice-output`, `api-tool`. |
+| `--period <value>` | No | Billing period. Defaults to "30d". Accepted values: `1d`, `7d`, `30d`, `all`, `custom`. |
 | `--start-date <value>` | No | Custom period start (ISO 8601). |
 | `--end-date <value>` | No | Custom period end (ISO 8601). |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
@@ -48,3 +52,10 @@ List credit usage events (an OAuth login or personal API key reports only your e
 | `--all-workspaces` | No | Do not filter to the configured workspace (OAuth login or personal API key required for account-wide access). |
 
 </CommandTable>
+
+API request and response schemas: [listBillingLogs](/api-reference/billing/listBillingLogs).
+
+## Related docs
+
+- [Costs](/platform/costs)
+- [Authentication](/cli/authentication)
diff --git a/apps/docs/content/docs/cli/blocks.mdx b/apps/docs/content/docs/cli/blocks.mdx
index 93e6d3ce480..776cd4c7134 100644
--- a/apps/docs/content/docs/cli/blocks.mdx
+++ b/apps/docs/content/docs/cli/blocks.mdx
@@ -1,27 +1,15 @@
 ---
 title: Blocks
-description: Manage blocks — every subcommand, argument, and flag
+description: Inspect workflow blocks, integration blocks, and triggers available to the workspace.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+Inspect workflow blocks, integration blocks, and triggers available to the workspace.
 
-## Get block
-
-```bash
-sim blocks get <blockId>
-```
-
-**Arguments**
+The catalog reflects the workspace’s allowed integrations, revealed preview blocks, and deployed custom blocks.
 
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `blockId` | Yes | Block type identifier. An unversioned base type resolves to the newest version, and the response echoes the resolved id. |
-
-</CommandTable>
+These commands accept the [global options](/cli/commands#global-options).
 
 ## List blocks
 
@@ -41,8 +29,28 @@ sim blocks list [options]
 | `--source <value>` | No | Restrict to shipped blocks or to this workspace’s deployed custom blocks. Accepted values: `builtin`, `custom`. |
 | `--include-sunset` | No | Include `legacy` and `deprecated` blocks. Off by default: a sunset block keeps executing where it is already placed, but it is not offered for new authoring. Each returned entry carries `sunset.replacedBy`, the block to build with instead. |
 | `--no-include-sunset` | No | Send --include-sunset as false. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `id`, `name`, `category`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "id". Accepted values: `id`, `name`, `category`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
+
+API request and response schemas: [listBlocks](/api-reference/catalog/listBlocks).
+
+## Get block
+
+```bash
+sim blocks get <blockId>
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `blockId` | Yes | Block type identifier. An unversioned base type resolves to the newest visible version. The response echoes the resolved ID. |
+
+</CommandTable>
+
+API request and response schemas: [getBlock](/api-reference/catalog/getBlock).
diff --git a/apps/docs/content/docs/cli/chat-deployments.mdx b/apps/docs/content/docs/cli/chat-deployments.mdx
index 59ab2d52d74..e6469503896 100644
--- a/apps/docs/content/docs/cli/chat-deployments.mdx
+++ b/apps/docs/content/docs/cli/chat-deployments.mdx
@@ -1,11 +1,13 @@
 ---
-title: Chat Deployments
-description: Manage chat deployments — every subcommand, argument, and flag
+title: Chat deployments
+description: List workflow chat deployments in the workspace.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+List workflow chat deployments in the workspace.
+
+These commands accept the [global options](/cli/commands#global-options).
 
 ## List chat deployments
 
@@ -22,8 +24,14 @@ sim chat-deployments list [options]
 | `--workflow-id <value>` | No | Restrict to deployments of one workflow. |
 | `--is-active` | No | Restrict to active or inactive deployments. |
 | `--no-is-active` | No | Send --is-active as false. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `identifier`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `identifier`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
+
+API request and response schemas: [listChatDeployments](/api-reference/workflows/listChatDeployments).
+
+## Related docs
+
+- [Deploy or update a workflow chat](/cli/workflows#chat-deployments)
diff --git a/apps/docs/content/docs/cli/cli.mdx b/apps/docs/content/docs/cli/cli.mdx
index 2135fc78fb5..1c4a3a20ff5 100644
--- a/apps/docs/content/docs/cli/cli.mdx
+++ b/apps/docs/content/docs/cli/cli.mdx
@@ -1,13 +1,15 @@
 ---
-title: CLI
-description: Discover commands in this CLI — every subcommand, argument, and flag
+title: Command search
+description: Find a command by describing the task you want to perform.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+Find a command by describing the task you want to perform.
 
-## Find the command for a task, described in plain words
+These commands accept the [global options](/cli/commands#global-options).
+
+## Find commands for a task [#find-the-command-for-a-task-described-in-plain-words]
 
 ```bash
 sim cli search <query...>
@@ -22,3 +24,12 @@ sim cli search <query...>
 | `query...` | Yes | What you want to do, e.g. "cancel a workflow run" |
 
 </CommandTable>
+
+Ranks the commands this CLI ships, locally; your query is never sent anywhere. Returns the 5 best matches. Run `<command> --help` on one for its flags.
+
+**Examples**
+
+```bash
+sim cli search "cancel a running workflow"
+sim cli search list table rows
+```
diff --git a/apps/docs/content/docs/cli/commands.mdx b/apps/docs/content/docs/cli/commands.mdx
index 85c9eb0da58..e998b13dc7b 100644
--- a/apps/docs/content/docs/cli/commands.mdx
+++ b/apps/docs/content/docs/cli/commands.mdx
@@ -1,11 +1,11 @@
 ---
-title: CLI Commands
-description: Global options, and every sim command group
+title: CLI commands
+description: Find command groups, global options, and login, configuration, and Chat commands.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-Every `sim` command follows the same shape:
+Resource commands use this shape:
 
 ```bash
 sim <resource> [sub-resource] <verb> [arguments] [options]
@@ -13,11 +13,15 @@ sim <resource> [sub-resource] <verb> [arguments] [options]
 
 Some resource groups also accept a singular alias: `sim workflow get` and
 `sim workflows get` are the same command. `knowledge` also answers to `kb`.
-Each group’s reference lists its supported aliases.
+Each group’s reference lists its supported aliases. Login, configuration, and
+Chat commands appear below. To find a command for a task, use
+`sim cli search "describe your task"`.
 
 ## Global options
 
-These apply to every command, and may be written before or after it.
+Place these options before or after the command. Each command uses the settings
+relevant to its action. Telemetry commands always print text; workflow export
+prints a portable JSON document, or YAML when selected.
 
 | Option | Description |
 | --- | --- |
@@ -26,36 +30,42 @@ These apply to every command, and may be written before or after it.
 | `-w, --workspace <id>` | Workspace to target (env: SIM_WORKSPACE). |
 | `--output <format>` | Output format for this command. Accepted values: `table`, `json`, `yaml`, `text`. |
 
+Use `--help` to inspect a command. Run `sim --version` to print the CLI version;
+`--version` takes no value and exits without running a command. Deployment-version
+commands use their documented arguments or `--to-version` instead.
+
+See [output formats](/cli/output) for the JSON default and display formats.
+
 ## Command groups
 
 | Group | Description |
 | --- | --- |
-| [`sim profiles`](/cli/profiles) | List profiles or add a workspace profile that shares a stored login |
-| [`sim telemetry`](/cli/telemetry) | Control anonymous usage reporting |
-| [`sim cli`](/cli/cli) | Discover commands in this CLI |
-| [`sim audit-logs`](/cli/audit-logs) | Manage audit logs |
-| [`sim billing`](/cli/billing) | Manage billing |
-| [`sim blocks`](/cli/blocks) | Manage blocks |
-| [`sim chat-deployments`](/cli/chat-deployments) | Manage chat deployments |
-| [`sim connector-types`](/cli/connector-types) | Manage connector types |
-| [`sim credentials`](/cli/credentials) | Manage credentials |
-| [`sim custom-tools`](/cli/custom-tools) | Manage custom tools |
-| [`sim files`](/cli/files) | Manage files |
-| [`sim knowledge`](/cli/knowledge) | Manage knowledge |
-| [`sim logs`](/cli/logs) | Manage logs |
-| [`sim mcp-servers`](/cli/mcp-servers) | Manage mcp servers |
-| [`sim meta`](/cli/meta) | Manage meta |
-| [`sim organizations`](/cli/organizations) | Manage organizations |
-| [`sim permission-groups`](/cli/permission-groups) | Manage permission groups |
-| [`sim sandboxes`](/cli/sandboxes) | Manage sandboxes |
-| [`sim secrets`](/cli/secrets) | Manage secrets |
-| [`sim selectors`](/cli/selectors) | Manage selectors |
-| [`sim skills`](/cli/skills) | Manage skills |
-| [`sim tables`](/cli/tables) | Manage tables |
-| [`sim tools`](/cli/tools) | Manage tools |
-| [`sim workflow-mcp-servers`](/cli/workflow-mcp-servers) | Manage workflow mcp servers |
-| [`sim workflows`](/cli/workflows) | Manage workflows |
-| [`sim workspaces`](/cli/workspaces) | Manage workspaces |
+| [`sim profiles`](/cli/profiles) | List profiles and add a workspace profile that shares a stored login. |
+| [`sim telemetry`](/cli/telemetry) | Inspect and change this machine’s anonymous usage-reporting preference. |
+| [`sim cli`](/cli/cli) | Find a command by describing the task you want to perform. |
+| [`sim audit-logs`](/cli/audit-logs) | Read organization audit actions and filter by actor, resource, workspace, or time. |
+| [`sim billing`](/cli/billing) | Read billing status, credit usage, and storage usage. |
+| [`sim blocks`](/cli/blocks) | Inspect workflow blocks, integration blocks, and triggers available to the workspace. |
+| [`sim chat-deployments`](/cli/chat-deployments) | List workflow chat deployments in the workspace. |
+| [`sim connector-types`](/cli/connector-types) | Discover knowledge connectors and their authentication and source-configuration schemas. |
+| [`sim credentials`](/cli/credentials) | Discover providers, connect accounts, and manage credential access. |
+| [`sim custom-tools`](/cli/custom-tools) | Create and manage code-backed tools that agents can call. |
+| [`sim files`](/cli/files) | Browse workspace files, read or write content, manage versions, and configure sharing. |
+| [`sim knowledge`](/cli/knowledge) | Manage knowledge bases, indexed documents, search, tags, and connector syncs. |
+| [`sim logs`](/cli/logs) | Read run diagnostics, follow new runs, and summarize failures and latency. |
+| [`sim mcp-servers`](/cli/mcp-servers) | Connect external Model Context Protocol (MCP) servers so workflows can use their tools. |
+| [`sim meta`](/cli/meta) | Inspect API availability and the calling credential’s type and expiry. |
+| [`sim organizations`](/cli/organizations) | Manage organization membership, invitations, usage, access requests, and SSO. |
+| [`sim permission-groups`](/cli/permission-groups) | Manage organization permission groups, their configuration, and member assignments. |
+| [`sim sandboxes`](/cli/sandboxes) | Manage reusable dependency sets for Function blocks. |
+| [`sim secrets`](/cli/secrets) | Set and manage workspace or personal secrets. |
+| [`sim selectors`](/cli/selectors) | Discover destination options for registered fields, such as calendars, channels, and tables. |
+| [`sim skills`](/cli/skills) | Create reusable agent instructions and manage their editors. |
+| [`sim tables`](/cli/tables) | Manage tables, rows, schemas, views, enrichment runs, imports, and exports. |
+| [`sim tools`](/cli/tools) | Find built-in tools, inspect their parameters, and run them. |
+| [`sim workflow-mcp-servers`](/cli/workflow-mcp-servers) | Serve deployed workflows as tools for Model Context Protocol (MCP) clients. |
+| [`sim workflows`](/cli/workflows) | Build, deploy, run, and inspect workflows from the terminal. |
+| [`sim workspaces`](/cli/workspaces) | Read workspace access and manage reviewed fork, push, and pull operations. |
 
 ## Log in through the browser and store the login for the profile
 
@@ -109,6 +119,8 @@ sim whoami [options]
 
 </CommandTable>
 
+API request and response schemas: [getMeta](/api-reference/meta/getApiMeta), [getWorkspace](/api-reference/workspaces/getWorkspace).
+
 ## Switch a profile's default workspace, or set its endpoint or output format
 
 ```bash
@@ -169,3 +181,19 @@ sim chat <message> [options]
 | `-c, --conversation <id>` | No | Continue the conversation with this ID. |
 
 </CommandTable>
+
+Each turn prints the reply on stdout and the conversation ID on stderr; pass that ID back with -c to continue the same conversation. With --output json or yaml the reply is not streamed — the finished result is printed as one document, conversation ID included.
+
+**Examples**
+
+```bash
+sim chat "What workflows do I have?"
+sim chat -c "$CONVERSATION_ID" "Which of those run on a schedule?"
+sim --output json chat "Summarize yesterday's failed runs" | jq -r '.content'
+```
+
+## Related docs
+
+- [Complete command reference](/cli/reference)
+- [Authentication](/cli/authentication)
+- [Scripting](/cli/scripting)
diff --git a/apps/docs/content/docs/cli/configuration.mdx b/apps/docs/content/docs/cli/configuration.mdx
index 630e23f7090..b11e660fd2d 100644
--- a/apps/docs/content/docs/cli/configuration.mdx
+++ b/apps/docs/content/docs/cli/configuration.mdx
@@ -1,81 +1,63 @@
 ---
 title: Configuration
-description: Profiles, config files, environment variables, and how each setting is resolved
+description: Select profiles and resolve endpoint, credential, workspace, and output settings.
 ---
 
-These settings apply to the CLI you install locally. When Sim runs a `sim`
-command for you inside Chat, it uses your session identity — there is no profile,
-no `sim login`, and no config file.
+The installed CLI resolves an endpoint, credential, workspace, and output format independently. A saved default can be overridden for one command.
 
-The CLI resolves an **endpoint**, **credential**, **workspace**, and **output
-format**. The credential can be a stored OAuth login or an API key. Each resolves independently, so a saved default can still be overridden
-for a single command.
+Commands Sim runs inside Chat receive their identity, endpoint, and workspace from Chat. Local `login`, `logout`, `whoami`, `profiles`, `configure`, `update`, and `telemetry` commands are unavailable there; local profiles and config files do not apply.
 
 ## Profiles
 
-A profile selects one set of defaults, in the style of the AWS CLI. It normally
-uses its same-named stored identity, but a workspace profile can share another
-profile's identity through `auth_profile`. Select one with `-P`, `--profile`, or
-`SIM_PROFILE`:
+A profile stores defaults and normally uses its same-named stored login. A workspace profile can share another profile's authentication through `auth_profile`.
+
+Select a profile with `-P`, `--profile`, or `SIM_PROFILE`. A flag wins over the environment; omission selects `default`:
 
 ```bash
 sim workflows list --profile dev
 SIM_PROFILE=dev sim workflows list
+sim profiles --output table
 ```
 
-The profile is named `default` when you do not pick one.
-
-```bash
-sim profiles     # list them; * marks the active one
-```
-
-Add a profile for another workspace without creating or copying an API key:
-
-```bash
-sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
-```
+In table output, `*` marks the selected profile. JSON output includes an `active` boolean. An explicitly named profile must exist; `login` and `configure --set-*` can create one.
 
 ## Setting defaults
 
+Use `configure` to save settings for the selected profile:
+
 ```bash
 sim configure --set-endpoint http://localhost:3000 --profile dev
 sim configure --set-workspace 5c81f3a6-0e27-4b94-8d15-a7f60c39b2e8 --profile dev
 sim configure --set-output table
 ```
 
-| Option | What it sets |
+| Option | Saved setting |
 | --- | --- |
-| `--set-endpoint <url>` | The Sim deployment to talk to |
+| `--set-endpoint <url>` | Sim deployment |
 | `--set-workspace <id>` | Default workspace for workspace-scoped commands |
-| `--set-output <format>` | Default output format: `table`, `json`, `yaml`, or `text` |
-| `--unset <key...>` | Remove settings — `endpoint`, `workspace`, or `output` |
+| `--set-output <format>` | `table`, `json`, `yaml`, or `text` |
+| `--unset <key...>` | Remove `endpoint`, `workspace`, or `output` settings |
 
-Run `sim configure` with no flags to print the profile's stored settings.
+Without setter flags, `sim configure` prints the profile's stored settings as text. Credentials are set through [login](/cli/authentication), or supplied with `SIM_API_KEY` for CI.
 
-API keys are not settable here. Use [`sim login`](/cli/authentication), or
-`SIM_API_KEY` for CI.
+The global `--endpoint`, `--workspace`, and `--output` flags affect one invocation. `configure` rejects them; use the corresponding `--set-*` flag to persist a setting.
 
 ## Where settings come from
 
-Each setting resolves independently, and the first match wins:
+The first applicable source wins for each setting:
 
 | Rank | Source |
 | --- | --- |
-| 1 | Command-line flag — `--endpoint`, `--workspace`, `--output` |
-| 2 | Environment — `SIM_ENDPOINT`, `SIM_API_KEY`, `SIM_WORKSPACE`, `SIM_OUTPUT` |
-| 3 | `~/.sim/config` for the selected profile and `~/.sim/credentials` for its `auth_profile`, when set |
-| 4 | Built-in default — `https://www.sim.ai` and `json` |
+| 1 | Command-line flag: `--endpoint`, `--workspace`, `--output` |
+| 2 | Environment: `SIM_ENDPOINT`, `SIM_API_KEY`, `SIM_WORKSPACE`, `SIM_OUTPUT` |
+| 3 | Selected profile in `~/.sim/config`; its stored login in `~/.sim/credentials`, or the login named by `auth_profile` |
+| 4 | Defaults: endpoint `https://www.sim.ai`, output `json`; no default credential or workspace |
 
-`sim whoami` prints the winning source for each setting:
-
-```bash
-sim whoami
-```
+`SIM_API_KEY` overrides a stored OAuth login or API key. There is no command-line API-key option. Use `sim whoami` to see each resolved value and its source; `--no-verify` skips API requests.
 
 ## The files
 
-Non-secret settings live in `~/.sim/config`. It is safe to commit to a dotfiles
-repo:
+Non-secret settings live in `~/.sim/config` and can be kept in a dotfiles repository:
 
 ```ini title="~/.sim/config"
 [default]
@@ -92,7 +74,7 @@ auth_profile = default
 workspace = 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
 ```
 
-Keys live in `~/.sim/credentials`, written `0600`:
+API keys and OAuth tokens live in `~/.sim/credentials`, written with `0600` permissions. Never commit that file:
 
 ```ini title="~/.sim/credentials"
 [default]
@@ -102,107 +84,103 @@ api_key = sim_…
 api_key = sim_…
 ```
 
-Section naming follows the AWS convention: `[profile dev]` in config, `[dev]` in
-credentials. The `default` profile is `[default]` in both.
+Named config sections use `[profile dev]`; credentials use `[dev]`. The default section is `[default]` in both files. See [Stored logins](/cli/authentication#where-the-login-is-stored) for OAuth fields and refresh behavior.
+
+### Shared authentication
+
+`auth_profile` names one direct authentication profile. It shares that profile's endpoint and stored OAuth login or API key; workspace and output stay local. References cannot be chained. A shared profile cannot set its own endpoint or stored login.
+
+Create a shared profile from a stored login:
+
+```bash
+sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
+sim --profile acme tables list
+```
+
+`profile add` refuses environment-only credentials and endpoint overrides because those values would not persist in a new shell. Save the endpoint and sign in before creating the profile.
+
+An OAuth login is bound to its issuing deployment. Log out before changing or removing that authentication profile's endpoint. Change a shared endpoint on the authentication profile, not its workspace profiles.
+
+## Choosing a workspace
+
+Workspace-scoped commands need a target. Set it for one command, in the profile, or in the environment:
+
+```bash
+sim tables list --workspace 9b4c7e02-1d58-4f36-a0c9-6e2b85df413a
+sim configure --set-workspace 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
+export SIM_WORKSPACE=2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
+```
+
+To select an accessible workspace interactively, omit `--workspace` from `sim profile add <name>`. The picker accepts at most 1,000 workspaces; above that, supply an ID. Non-interactive scripts must always supply it.
 
-`auth_profile` references one direct profile and shares its endpoint and stored
-login, whether OAuth or an API key. Workspace and output remain local.
-References cannot be chained, and a shared profile cannot also set its own
-endpoint or stored login.
+`sim billing status`, `sim billing logs`, and `sim audit-logs list` accept `--all-workspaces` to omit the workspace filter. Do not combine it with an explicit `--workspace`.
 
 ## Environment variables
 
 | Variable | Effect |
 | --- | --- |
-| `SIM_PROFILE` | Profile to use |
-| `SIM_ENDPOINT` | Deployment to talk to |
-| `SIM_API_KEY` | API key — skips `sim login` entirely |
-| `SIM_WORKSPACE` | Workspace to target |
-| `SIM_OUTPUT` | Output format |
-| `SIM_CONFIG_DIR` | Relocate the config directory and update cache; file-specific overrides below still win |
+| `SIM_PROFILE` | Select a profile |
+| `SIM_ENDPOINT` | Select a deployment |
+| `SIM_API_KEY` | Authenticate with an existing key; overrides stored authentication |
+| `SIM_WORKSPACE` | Select a workspace |
+| `SIM_OUTPUT` | Select an output format |
+| `SIM_CONFIG_DIR` | Relocate config, credentials, usage state, and update cache; file-specific overrides still win |
 | `SIM_CONFIG_FILE` | Relocate only the config file |
 | `SIM_CREDENTIALS_FILE` | Relocate only the credentials file |
-| `SIM_TIMEOUT_SECONDS` | Per-request timeout; `0` waits indefinitely. Defaults to `3600`, above every timeout the server itself applies |
-| `SIM_DEBUG` | Trace each request's method, URL, status and duration to stderr |
-| `SIM_NO_UPDATE_CHECK` | Turn off update checks and notices |
-| `SIM_TELEMETRY_DISABLED` | Turn off anonymous usage reporting; see [usage data](/cli/usage-data) |
+| `SIM_TIMEOUT_SECONDS` | Per-request timeout, default `3600` seconds; `0` removes the CLI timeout |
+| `SIM_DEBUG` | Write request method, URL, status, and duration to stderr |
+| `SIM_NO_UPDATE_CHECK` | Disable automatic update checks and notices |
+| `SIM_TELEMETRY_DISABLED` | Disable anonymous usage reporting |
+| `DO_NOT_TRACK` | Cross-tool usage-reporting opt-out; takes precedence over the CLI setting |
 
-## Updates
+For CI, supply `SIM_API_KEY` and `SIM_WORKSPACE`; a saved login or config file is not required. `SIM_CONFIG_DIR` can point at a writable runner directory.
 
-The CLI checks for a newer stable release at most once per day on eligible
-interactive invocations. It prints an optional notice to stderr and continues
-your command. Installation only happens when you run `sim update`.
-
-Run `sim update` to update immediately, including in CI and when automatic checks
-are disabled. It requires a global installation and verifies that the package
-manager targets the running copy before installing. Supported managers are npm,
-pnpm, Bun, and Yarn Classic. For custom installations, select the manager with
-`sim update --package-manager bun`. Project-local and temporary package-runner
-copies must be updated through their package manager.
-
-Manual updates preserve the stable, staging, or dev release channel. Installation
-failures stop with an error; concurrent update attempts are refused. Installer
-output goes to stderr and does not mix with JSON output on stdout.
-The updater resolves the channel through the selected package manager before
-installing. Older registry or mirror releases are refused; a newer release is
-installed by its exact version so a moving tag cannot change the target.
-
-Checks are skipped in CI, when stderr is redirected, under `npm exec` or `npx`,
-from a repository checkout, and for prerelease versions. Set
-`SIM_NO_UPDATE_CHECK=1` to disable them.
-
-The check uses `registry.npmjs.org` unless `npm_config_registry` names another
-HTTP(S) registry. It sends no Sim API key, workspace, or command. Query-string
-credentials in a configured registry URL are preserved; URLs containing
-username/password userinfo are rejected. Empty registry values use npm, while
-malformed non-empty values disable the check. Redirects are not followed.
-
-The daily cache is `~/.sim/update-check.json`, or under `SIM_CONFIG_DIR`.
-`SIM_CONFIG_FILE` and `SIM_CREDENTIALS_FILE` do not relocate it. If the cache
-cannot be written, eligible invocations may check again. Concurrent commands
-can also each check. Registry checks have a one-second deadline; package-manager
-installation has a five-minute deadline. Registry-check failures suppress the
-check, while installer failures are reported.
-
-Node's `fetch` uses `HTTP(S)_PROXY` when opted in with `NODE_USE_ENV_PROXY=1`
-(Node 22.21+ or 24.0+) or `--use-env-proxy` (Node 22.21+ or 24.5+).
-
-For CI, set `SIM_API_KEY` and `SIM_WORKSPACE`; no saved login or config file is
-required.
+The request timeout does not change server execution limits. Run/operation waits have a separate `--wait-timeout`; see [Scripting](/cli/scripting#exit-codes). Debug URLs can include request selectors, so review them before sharing diagnostics. See [Usage data](/cli/usage-data) for the separate anonymous event fields.
 
-## Choosing a workspace
+## Updates
 
-Workspace-scoped commands need a workspace:
+Eligible interactive invocations check for a newer stable release using a daily cache. A notice goes to stderr and the command continues. Installation happens only when you run:
 
 ```bash
-sim tables list --workspace 9b4c7e02-1d58-4f36-a0c9-6e2b85df413a
-sim configure --set-workspace 2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
-export SIM_WORKSPACE=2f6d0b1c-8a34-4d92-b7e5-31c8a0f45d67
+sim update
 ```
 
-For a reusable selection, create a workspace profile backed by the current
-stored login:
+Manual updates also work in CI and when automatic checks are disabled. They require a global installation and verify that the selected package manager owns the running copy. Supported managers are Bun, npm, pnpm, and Yarn Classic. Select one explicitly for a custom installation:
 
 ```bash
-sim workspaces list
-sim profile add acme --workspace 7e2d9c14-6b83-4a55-8f01-c4d3e9a76b28
-sim --profile acme tables list
+sim update --package-manager bun
 ```
 
-When `--workspace` is omitted in a terminal, `profile add` presents an
-interactive picker, capped at 1,000 entries. It refuses environment-only keys
-and endpoint overrides because those values would disappear in another shell.
+Update project-local dependencies and temporary package-runner copies through their package manager. A manual update preserves the stable, staging, or dev release channel. The updater refuses older registry/mirror releases and installs the resolved exact version. Concurrent updates are refused; installation errors stop the command. Installer output goes to stderr.
+
+### Automatic notices
+
+Checks are skipped in CI, when stderr is redirected, for prerelease versions, from a repository checkout, and for temporary/project-local installations including `npm exec` and `npx`. Set `SIM_NO_UPDATE_CHECK=1` to disable them.
+
+The cache lives at `~/.sim/update-check.json`, or under `SIM_CONFIG_DIR`. `SIM_CONFIG_FILE` and `SIM_CREDENTIALS_FILE` do not move it. A failed cache write or concurrent invocations can cause additional checks.
 
-`sim billing status`, `sim billing logs`, and `sim audit-logs list` accept
-`--all-workspaces` to drop the filter instead. It cannot be combined with
-`--workspace`.
+Registry checks have a one-second deadline and fail quietly. Package-manager installation has a five-minute deadline and reports failures.
+
+### Registry and proxy behavior
+
+Automatic checks use `registry.npmjs.org` unless `npm_config_registry` supplies another HTTP(S) registry. They send no Sim API key, workspace, or command. Configured query-string credentials are preserved; username/password URL userinfo is rejected. Empty registry values use the default, malformed non-empty values disable checking, and redirects are not followed.
+
+Node's `fetch` reads `HTTP(S)_PROXY` when opted in with `NODE_USE_ENV_PROXY=1` on Node 22.21+ or 24.0+. The `--use-env-proxy` flag requires Node 22.21+ or 24.5+. See [Node's proxy options](https://nodejs.org/api/cli.html#node_use_env_proxy1).
 
 ## Repairing a bad setting
 
-An invalid `output` value fails with the list of accepted formats. A
-higher-priority source still wins, so you can repair a profile without editing
-the file:
+An invalid output format stops profile resolution. Temporarily override it through the environment, then save a valid default:
 
 ```bash
-sim --output table configure --set-output json
+SIM_OUTPUT=json sim configure --set-output json
+SIM_OUTPUT=json sim configure --profile dev --set-output json
 ```
+
+If the invalid value comes from `SIM_OUTPUT`, correct or unset that variable too. A higher-priority environment value still overrides the repaired profile.
+
+## Related docs
+
+- [Authentication](/cli/authentication)
+- [Output formats](/cli/output)
+- [Profiles commands](/cli/profiles)
+- [Troubleshooting](/cli/troubleshooting)
diff --git a/apps/docs/content/docs/cli/connector-types.mdx b/apps/docs/content/docs/cli/connector-types.mdx
index 88dd05a0cde..8b4da35396f 100644
--- a/apps/docs/content/docs/cli/connector-types.mdx
+++ b/apps/docs/content/docs/cli/connector-types.mdx
@@ -1,11 +1,15 @@
 ---
-title: Connector Types
-description: Manage connector types — every subcommand, argument, and flag
+title: Connector types
+description: Discover knowledge connectors and their authentication and source-configuration schemas.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+Discover knowledge connectors and their authentication and source-configuration schemas.
+
+Use `--detail full` to inspect a connector’s configuration before creating it.
+
+These commands accept the [global options](/cli/commands#global-options).
 
 ## List connector types
 
@@ -25,3 +29,9 @@ sim connector-types list [options]
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
+
+API request and response schemas: [listConnectorTypes](/api-reference/catalog/listConnectorTypes).
+
+## Related docs
+
+- [Create and sync knowledge connectors](/cli/knowledge#connectors)
diff --git a/apps/docs/content/docs/cli/credentials.mdx b/apps/docs/content/docs/cli/credentials.mdx
index 8e77cdac6af..4cd441379c5 100644
--- a/apps/docs/content/docs/cli/credentials.mdx
+++ b/apps/docs/content/docs/cli/credentials.mdx
@@ -1,31 +1,25 @@
 ---
 title: Credentials
-description: Manage credentials — every subcommand, argument, and flag
+description: Discover providers, connect accounts, and manage credential access.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-`sim credentials` is also spelled `sim credential`.
-
-Every command below also accepts the [global options](/cli/commands#global-options).
-
-## Disconnect credential
+Discover providers, connect accounts, and manage credential access.
 
-```bash
-sim credentials delete <credentialId> [options]
-```
+Run `sim --output json credentials providers list` to inspect the provider’s fields and authentication requirements before creating a service-account credential. OAuth connection commands return a link that a person must open to authorize the connection.
 
-Disconnect Credential (OAuth login or personal API key required)
+`sim credentials` is also spelled `sim credential`.
 
-**Arguments**
+These commands accept the [global options](/cli/commands#global-options).
 
-<CommandTable>
+## Provider discovery and connections
 
-| Argument | Required | Description |
-| --- | --- | --- |
-| `credentialId` | Yes | Credential to disconnect. |
+### List credential providers
 
-</CommandTable>
+```bash
+sim credentials providers list [options]
+```
 
 **Options**
 
@@ -33,56 +27,50 @@ Disconnect Credential (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--search <value>` | No | Case-insensitive substring match against the credential provider name. |
 
 </CommandTable>
 
-## List credential members
+API request and response schemas: [listCredentialProviders](/api-reference/credentials/listCredentialProviders).
+
+### List credentials
 
 ```bash
-sim credentials members list <credentialId> [options]
+sim credentials list [options]
 ```
 
-List Credential Members (OAuth login or personal API key required)
-
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `credentialId` | Yes | Credential whose sharing grants are managed. |
-
-</CommandTable>
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
+| `--type <value>` | No | Restrict results to this credential type. Accepted values: `oauth`, `service_account`. |
+| `--provider-id <value>` | No | Restrict results to credentials for this integration provider. |
+| `--search <value>` | No | Case-insensitive substring match against the credential display name. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `displayName`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `email`, `name`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
-## Remove credential member
+API request and response schemas: [listCredentials](/api-reference/credentials/listCredentials).
+
+### Create a service-account credential using its discovered provider schema
+
+OAuth login or personal API key required.
 
 ```bash
-sim credentials members remove <credentialId> <userId> [options]
+sim credentials create <providerId> [options]
 ```
 
-Remove Credential Member (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `credentialId` | Yes | Credential whose sharing grants are managed. |
-| `userId` | Yes | User whose explicit grant will be revoked. |
+| `providerId` | Yes | Service-account provider to create a credential for |
 
 </CommandTable>
 
@@ -92,25 +80,30 @@ Remove Credential Member (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--name <displayName>` | Yes | Name shown for the credential in Sim. |
+| `--credentials <json\|@file>` | Yes | Provider credentials as JSON (or @path / @- to read a file or stdin). |
+| `--description <description>` | No | Optional credential description. |
+| `--id <credentialId>` | No | Client-generated credential ID when provider discovery requires it. |
 
 </CommandTable>
 
-## Upsert credential member
+API request and response schemas: [createServiceAccountCredential](/api-reference/credentials/createServiceAccountCredential).
+
+### Create a short-lived link for connecting an OAuth provider
+
+OAuth login or personal API key required.
 
 ```bash
-sim credentials members upsert <credentialId> [options]
+sim credentials connect <providerId> [options]
 ```
 
-Upsert Credential Member (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `credentialId` | Yes | Credential whose sharing grants are managed. |
+| `providerId` | Yes | OAuth provider to connect |
 
 </CommandTable>
 
@@ -120,56 +113,40 @@ Upsert Credential Member (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--user <value>` | Yes | Existing workspace member to grant or change access for. |
-| `--role <value>` | Yes | Credential role to grant; workspace administrators cannot be demoted. Accepted values: `admin`, `member`. |
+| `--name <displayName>` | Yes | Name shown for the new credential in Sim. |
 
 </CommandTable>
 
-## List credential providers
+API request and response schemas: [createCredentialConnection](/api-reference/credentials/createCredentialConnection).
 
-```bash
-sim credentials providers list [options]
-```
-
-**Options**
-
-<CommandTable>
+### Create a short-lived link for reconnecting an OAuth credential
 
-| Option | Required | Description |
-| --- | --- | --- |
-| `--search <value>` | No | Case-insensitive substring match against the credential provider name. |
-
-</CommandTable>
-
-## List credentials
+OAuth login or personal API key required.
 
 ```bash
-sim credentials list [options]
+sim credentials reconnect <credentialId>
 ```
 
-**Options**
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--type <value>` | No | Restrict results to this credential type. Accepted values: `oauth`, `service_account`. |
-| `--provider-id <value>` | No | Restrict results to credentials for this integration provider. |
-| `--search <value>` | No | Case-insensitive substring match against the credential display name. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `displayName`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `credentialId` | Yes | Existing OAuth credential to re-authorize |
 
 </CommandTable>
 
-## Update credential
+API request and response schemas: [createCredentialConnection](/api-reference/credentials/createCredentialConnection).
+
+### Update credential
+
+OAuth login or personal API key required.
 
 ```bash
 sim credentials update <credentialId> [options]
 ```
 
-Update Credential (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -212,21 +189,25 @@ Update Credential (OAuth login or personal API key required)
 
 </CommandTable>
 
-## Create a service-account credential using its discovered provider schema
+API request and response schemas: [updateCredential](/api-reference/credentials/updateCredential).
+
+## Credential members
+
+### List credential members
+
+OAuth login or personal API key required.
 
 ```bash
-sim credentials create <providerId> [options]
+sim credentials members list <credentialId> [options]
 ```
 
-Create a service-account credential using its discovered provider schema (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `providerId` | Yes | Service-account provider to create a credential for |
+| `credentialId` | Yes | Credential whose sharing grants are managed. |
 
 </CommandTable>
 
@@ -236,28 +217,29 @@ Create a service-account credential using its discovered provider schema (OAuth
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <displayName>` | Yes | Name shown for the credential in Sim. |
-| `--credentials <json\|@file>` | Yes | Provider credentials as JSON (or @path / @- to read a file or stdin). |
-| `--description <description>` | No | Optional credential description. |
-| `--id <credentialId>` | No | Client-generated credential ID when provider discovery requires it. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "email". Accepted values: `email`, `name`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
-## Create a short-lived link for connecting an OAuth provider
+API request and response schemas: [listCredentialMembers](/api-reference/credentials/listCredentialMembers).
+
+### Upsert credential member
+
+OAuth login or personal API key required.
 
 ```bash
-sim credentials connect <providerId> [options]
+sim credentials members upsert <credentialId> [options]
 ```
 
-Create a short-lived link for connecting an OAuth provider (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `providerId` | Yes | OAuth provider to connect |
+| `credentialId` | Yes | Credential whose sharing grants are managed. |
 
 </CommandTable>
 
@@ -267,17 +249,57 @@ Create a short-lived link for connecting an OAuth provider (OAuth login or perso
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <displayName>` | Yes | Name shown for the new credential in Sim. |
+| `--user <value>` | Yes | Existing workspace member to grant or change access for. |
+| `--role <value>` | Yes | Credential role to grant; workspace administrators cannot be demoted. Accepted values: `admin`, `member`. |
 
 </CommandTable>
 
-## Create a short-lived link for reconnecting an OAuth credential
+API request and response schemas: [upsertCredentialMember](/api-reference/credentials/upsertCredentialMember).
+
+### Remove credential member
+
+OAuth login or personal API key required.
+
+This revokes the selected user’s explicit credential grant.
 
 ```bash
-sim credentials reconnect <credentialId>
+sim credentials members remove <credentialId> <userId> [options]
 ```
 
-Create a short-lived link for reconnecting an OAuth credential (OAuth login or personal API key required)
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `credentialId` | Yes | Credential whose sharing grants are managed. |
+| `userId` | Yes | User whose explicit grant will be revoked. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `-y, --yes` | Yes | Confirm this operation. |
+
+</CommandTable>
+
+API request and response schemas: [removeCredentialMember](/api-reference/credentials/removeCredentialMember).
+
+## Disconnect credentials
+
+### Disconnect credential
+
+OAuth login or personal API key required.
+
+This disconnects the credential and removes its stored authentication.
+
+```bash
+sim credentials delete <credentialId> [options]
+```
 
 **Arguments**
 
@@ -285,6 +307,22 @@ Create a short-lived link for reconnecting an OAuth credential (OAuth login or p
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `credentialId` | Yes | Existing OAuth credential to re-authorize |
+| `credentialId` | Yes | Credential to disconnect. |
 
 </CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `-y, --yes` | Yes | Confirm this operation. |
+
+</CommandTable>
+
+API request and response schemas: [deleteCredential](/api-reference/credentials/deleteCredential).
+
+## Related docs
+
+- [Credentials](/platform/credentials)
diff --git a/apps/docs/content/docs/cli/custom-tools.mdx b/apps/docs/content/docs/cli/custom-tools.mdx
index 5c83e67c805..a952d869ce1 100644
--- a/apps/docs/content/docs/cli/custom-tools.mdx
+++ b/apps/docs/content/docs/cli/custom-tools.mdx
@@ -1,18 +1,20 @@
 ---
-title: Custom Tools
-description: Manage custom tools — every subcommand, argument, and flag
+title: Custom tools
+description: Create and manage code-backed tools that agents can call.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Create and manage code-backed tools that agents can call.
+
 `sim custom-tools` is also spelled `sim custom-tool`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
 
-## Create custom tool
+## List custom tools
 
 ```bash
-sim custom-tools create [options]
+sim custom-tools list [options]
 ```
 
 **Options**
@@ -21,16 +23,19 @@ sim custom-tools create [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--title <value>` | Yes | Display title, unique within the workspace. |
-| `--schema <json\|@file>` | Yes | OpenAI function schema: &#123;"type":"function","function":&#123;"name":"...","parameters":&#123;"type":"object","properties":&#123;&#125;&#125;&#125;&#125; (JSON, or @path / @- to read a file or stdin). |
-| `--code <value>` | Yes | Tool implementation executed in the sandboxed function runtime. |
+| `--search <value>` | No | Case-insensitive substring match against the tool title. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `title`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Delete custom tool
+API request and response schemas: [listCustomTools](/api-reference/custom-tools/listCustomTools).
+
+## Get custom tool
 
 ```bash
-sim custom-tools delete <customToolId> [options]
+sim custom-tools get <customToolId>
 ```
 
 **Arguments**
@@ -43,20 +48,32 @@ sim custom-tools delete <customToolId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getCustomTool](/api-reference/custom-tools/getCustomTool).
+
+## Create custom tool
+
+```bash
+sim custom-tools create [options]
+```
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--title <value>` | Yes | Display title, unique within the workspace. |
+| `--schema <json\|@file>` | Yes | OpenAI function schema: &#123;"type":"function","function":&#123;"name":"...","parameters":&#123;"type":"object","properties":&#123;&#125;&#125;&#125;&#125; (JSON, or @path / @- to read a file or stdin). |
+| `--code <value>` | Yes | Tool implementation executed in the sandboxed function runtime. |
 
 </CommandTable>
 
-## Get custom tool
+API request and response schemas: [createCustomTool](/api-reference/custom-tools/createCustomTool).
+
+## Update custom tool
 
 ```bash
-sim custom-tools get <customToolId>
+sim custom-tools update <customToolId> [options]
 ```
 
 **Arguments**
@@ -69,29 +86,26 @@ sim custom-tools get <customToolId>
 
 </CommandTable>
 
-## List custom tools
-
-```bash
-sim custom-tools list [options]
-```
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--search <value>` | No | Case-insensitive substring match against the tool title. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `title`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--title <value>` | No | New display title for the tool. |
+| `--schema <json\|@file>` | No | OpenAI function schema: &#123;"type":"function","function":&#123;"name":"...","parameters":&#123;"type":"object","properties":&#123;&#125;&#125;&#125;&#125; (JSON, or @path / @- to read a file or stdin). |
+| `--code <value>` | No | Replacement tool implementation. |
 
 </CommandTable>
 
-## Update custom tool
+API request and response schemas: [updateCustomTool](/api-reference/custom-tools/updateCustomTool).
+
+## Delete custom tool
+
+This deletes the custom tool.
 
 ```bash
-sim custom-tools update <customToolId> [options]
+sim custom-tools delete <customToolId> [options]
 ```
 
 **Arguments**
@@ -110,8 +124,12 @@ sim custom-tools update <customToolId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--title <value>` | No | New display title for the tool. |
-| `--schema <json\|@file>` | No | OpenAI function schema: &#123;"type":"function","function":&#123;"name":"...","parameters":&#123;"type":"object","properties":&#123;&#125;&#125;&#125;&#125; (JSON, or @path / @- to read a file or stdin). |
-| `--code <value>` | No | Replacement tool implementation. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
+
+API request and response schemas: [deleteCustomTool](/api-reference/custom-tools/deleteCustomTool).
+
+## Related docs
+
+- [Custom tools](/agents/custom-tools)
diff --git a/apps/docs/content/docs/cli/files.mdx b/apps/docs/content/docs/cli/files.mdx
index 853e60ce484..315ec4600c8 100644
--- a/apps/docs/content/docs/cli/files.mdx
+++ b/apps/docs/content/docs/cli/files.mdx
@@ -1,35 +1,51 @@
 ---
 title: Files
-description: Manage files — every subcommand, argument, and flag
+description: Browse workspace files, read or write content, manage versions, and configure sharing.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Browse workspace files, read or write content, manage versions, and configure sharing.
+
 `sim files` is also spelled `sim file`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
+
+## Browse and inspect
 
-## Delete several files at once
+### List file resources and child folders together
 
 ```bash
-sim files batch-delete [options]
+sim files ls [path] [options]
 ```
 
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `path` | No | Folder path to list; defaults to the root folder |
+
+</CommandTable>
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--file-ids <value...>` | Yes | File identifiers to delete. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--search <text>` | No | Filter folders and resources by name. |
+| `--limit <n>` | No | Maximum combined items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Create file
+API request and response schemas: [listFiles](/api-reference/files/listFiles), [listFileFolders](/api-reference/files/listFilesFolders).
+
+### List files
 
 ```bash
-sim files create [options]
+sim files list [options]
 ```
 
 **Options**
@@ -38,34 +54,46 @@ sim files create [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | Yes | File name, including its extension. Path separators and dot segments are rejected. |
-| `--content-type <value>` | No | MIME type. When omitted, it is inferred from the file extension. |
 | `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
-| `--content <value>` | No | Initial file content. Omit or send an empty string for a zero-byte file. The 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`. Use an upload session for anything larger. |
-| `--encoding <value>` | No | Encoding of the content field. Accepted values: `utf-8`, `base64`. |
+| `--recursive` | No | Include subfolders in the folder filter. Defaults to true when searching and false otherwise. Ignored without a folder filter. |
+| `--no-recursive` | No | Send --recursive as false. |
+| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live files, `archived` for files a delete soft-deleted. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
+| `--search <value>` | No | Case-insensitive substring match against the file name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "uploadedAt". Accepted values: `name`, `size`, `uploadedAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Create a file folder at a path
+API request and response schemas: [listFiles](/api-reference/files/listFiles).
+
+### Search file content
 
 ```bash
-sim files folders create <path>
+sim files search [options]
 ```
 
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `--query <value>` | Yes | Regular expression, or exact text when `mode` is `exact`. |
+| `--mode <value>` | No | How `query` is read. Defaults to "regex". Accepted values: `exact`, `regex`. |
+| `--max-results <value>` | No | Maximum matching lines to return. Defaults to 50. |
+| `--folder <value...>` | No | Folders to search, by path as shown in the app; omit to search the whole workspace (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--include-subfolders` | No | Whether each folder scope includes nested folders; on by default. |
+| `--no-include-subfolders` | No | Send --include-subfolders as false. |
 
 </CommandTable>
 
-## Delete folder
+API request and response schemas: [searchFileContent](/api-reference/files/searchFileContent).
+
+### Show file metadata and sharing status
 
 ```bash
-sim files folders delete <path> [options]
+sim files describe <fileId> [options]
 ```
 
 **Arguments**
@@ -74,7 +102,7 @@ sim files folders delete <path> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `fileId` | Yes | File identifier. |
 
 </CommandTable>
 
@@ -84,18 +112,29 @@ sim files folders delete <path> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--recursive` | No | Delete the folder and its descendants. |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--scope <value>` | No | Which lifecycle set to read from: `active` (default) resolves live files only and returns `404` for a file a delete soft-deleted; `archived` also resolves soft-deleted files, so metadata stays readable before the file is restored. Authorization is identical for both. Accepted values: `active`, `archived`. |
 
 </CommandTable>
 
-## List folders
+API request and response schemas: [getFile](/api-reference/files/getFile).
+
+## Upload, create, and read
+
+### Upload a file to the workspace
 
 ```bash
-sim files folders list [options]
+sim files upload <path> [options]
 ```
 
-Also available as `sim files folders ls`.
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `path` | Yes | Local file to upload |
+
+</CommandTable>
 
 **Options**
 
@@ -103,39 +142,39 @@ Also available as `sim files folders ls`.
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--parent <value>` | No | Direct parent folder path. |
-| `--search <value>` | No | Case-insensitive substring match against the folder name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--scope <value>` | No | Which lifecycle set to list: `active` (default) returns live folders only; `archived` returns folders a recursive delete soft-deleted, which is how a caller finds a path to hand to the folder restore. Authorization is identical for both. Accepted values: `active`, `archived`. |
-| `--recursive <value>` | No | Whether parentPath includes every descendant instead of direct children only. Accepted values: `true`, `1`, `yes`, `on`, `y`, `enabled`, `false`, `0`, `no`, `off`, `n`, `disabled`. |
-| `--depth <value>` | No | Deepest level below parentPath to include when recursive is true. |
+| `--folder <path>` | No | Folder path as shown in the app; defaults to the root folder. |
+| `--name <name>` | No | Store it under a different name. |
 
 </CommandTable>
 
-## Rename or move a file folder
+API request and response schemas: [createFileUpload](/api-reference/files/createFileUpload), [createFileUploadPartUrls](/api-reference/files/createFileUploadPartUrls), [completeFileUpload](/api-reference/files/completeFileUpload), [abortFileUpload](/api-reference/files/abortFileUpload).
+
+### Create file
 
 ```bash
-sim files folders move <path> <destination>
+sim files create [options]
 ```
 
-Also available as `sim files folders mv`.
-
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
-| `destination` | Yes | Folder path as shown in the app; the leading / is optional |
+| `--name <value>` | Yes | File name, including its extension. Path separators and dot segments are rejected. |
+| `--content-type <value>` | No | MIME type. When omitted, it is inferred from the file extension. |
+| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
+| `--content <value>` | No | Initial file content. Omit or send an empty string for a zero-byte file. The complete JSON request is capped at 10 MiB, including encoding and the envelope; the separate decoded-file limit is 50 MiB. For larger payloads, use `sim files upload <path>`. Defaults to "". |
+| `--encoding <value>` | No | Encoding of the content field. Defaults to "utf-8". Accepted values: `utf-8`, `base64`. |
 
 </CommandTable>
 
-## Restore an archived file folder
+API request and response schemas: [createFile](/api-reference/files/createFile).
+
+### Download a file’s content to stdout or a local file
 
 ```bash
-sim files folders restore <path>
+sim files get <fileId> [options]
 ```
 
 **Arguments**
@@ -144,14 +183,27 @@ sim files folders restore <path>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `fileId` | Yes | File whose content to read |
 
 </CommandTable>
 
-## Delete file
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `-o, --output-file <path>` | No | Write content to a file instead of stdout. |
+| `--force` | No | Overwrite --output-file if it already exists. |
+
+</CommandTable>
+
+API request and response schemas: [downloadFile](/api-reference/files/downloadFile).
+
+### Read a file’s text content as JSON or YAML
 
 ```bash
-sim files delete <fileId> [options]
+sim files read <fileId> [options]
 ```
 
 **Arguments**
@@ -160,7 +212,7 @@ sim files delete <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier. |
+| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`, or `uploads/<name>` for a Chat upload. |
 
 </CommandTable>
 
@@ -170,14 +222,20 @@ sim files delete <fileId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--max-bytes <value>` | No | Optional ceiling on the source bytes fed to the parser, lowering but never raising the server limit. |
+| `--offset <value>` | No | First line to return, 1-based; 0 also starts at the first line. Absent starts at the first line. |
+| `--limit <value>` | No | How many lines to return from `offset`. Absent reads to the end. |
 
 </CommandTable>
 
-## Permanently delete a previous version of a file
+API request and response schemas: [readFileText](/api-reference/files/readFileText).
+
+## Edit and organize
+
+### Apply one exact or anchor-based edit to a text file
 
 ```bash
-sim files versions delete <fileId> <version> [options]
+sim files edit <fileId> [options]
 ```
 
 **Arguments**
@@ -187,7 +245,6 @@ sim files versions delete <fileId> <version> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `fileId` | Yes | File identifier. |
-| `version` | Yes | Version number. |
 
 </CommandTable>
 
@@ -197,14 +254,17 @@ sim files versions delete <fileId> <version> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--edit <json\|@file>` | Yes | One edit object: &#123;"mode":"search_replace","search":"old","content":"new","replaceAll":false&#125;, &#123;"mode":"replace_between","beforeAnchor":"start line","afterAnchor":"end line","content":"new"&#125;, &#123;"mode":"insert_after","anchor":"line","content":"new"&#125;, or &#123;"mode":"delete_between","startAnchor":"first line deleted","endAnchor":"ending line kept"&#125;. Anchored modes also accept occurrence starting at 1 (JSON, or @path / @- to read a file or stdin). |
+| `--expected-revision <value>` | No | Revision from Get file metadata or an earlier write; the request is refused with `409` when the content moved on. |
 
 </CommandTable>
 
-## Show the metadata of one version of a file
+API request and response schemas: [editFileContent](/api-reference/files/editFileContent).
+
+### Replace a file’s contents
 
 ```bash
-sim files versions describe <fileId> <version>
+sim files set-content <fileId> [options]
 ```
 
 **Arguments**
@@ -214,14 +274,27 @@ sim files versions describe <fileId> <version>
 | Argument | Required | Description |
 | --- | --- | --- |
 | `fileId` | Yes | File identifier. |
-| `version` | Yes | Version number. |
 
 </CommandTable>
 
-## List the recorded versions of a file
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--content <value>` | Yes | Complete replacement content for the file. The complete JSON request is capped at 10 MiB, including UTF-8 encoding, escaping, base64, and the envelope. The separate decoded-file limit is 50 MiB. Small patches can edit a larger stored text file without sending its full content. |
+| `--encoding <value>` | No | Content encoding. Defaults to "utf-8". Accepted values: `utf-8`, `base64`. |
+| `--expected-revision <value>` | No | Revision from Get file metadata or an earlier write; the request is refused with `409` when the content moved on. |
+
+</CommandTable>
+
+API request and response schemas: [updateFileContent](/api-reference/files/updateFileContent).
+
+### Rename a file
 
 ```bash
-sim files versions list <fileId> [options]
+sim files rename <fileId> [options]
 ```
 
 **Arguments**
@@ -240,29 +313,19 @@ sim files versions list <fileId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `version`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--name <value>` | Yes | New file name, including its extension. |
 
 </CommandTable>
 
-## Read the text content of one version of a file as JSON or YAML
+API request and response schemas: [renameFile](/api-reference/files/renameFile).
+
+### Move files into another folder
 
 ```bash
-sim files versions read <fileId> <version> [options]
+sim files move [options]
 ```
 
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `fileId` | Yes | File identifier. |
-| `version` | Yes | Version number. |
-
-</CommandTable>
+Also available as `sim files mv`.
 
 **Options**
 
@@ -270,16 +333,19 @@ sim files versions read <fileId> <version> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--max-bytes <value>` | No | Optional ceiling on the source bytes fed to the parser, lowering but never raising the server limit. |
-| `--offset <value>` | No | First line to return, 1-based; 0 also starts at the first line. Absent starts at the first line. |
-| `--limit <value>` | No | How many lines to return from `offset`. Absent reads to the end. |
+| `--file-ids <value...>` | Yes | File identifiers to update. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--to <value>` | No | Destination folder path; omit for root. |
 
 </CommandTable>
 
-## Make a previous version of a file current again
+API request and response schemas: [moveFileItems](/api-reference/files/moveFileItems).
+
+### Unzip an archive into a new folder beside it
+
+This writes every file in the archive into the workspace.
 
 ```bash
-sim files versions revert <fileId> <version> [options]
+sim files unzip <fileId> [options]
 ```
 
 **Arguments**
@@ -289,7 +355,6 @@ sim files versions revert <fileId> <version> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `fileId` | Yes | File identifier. |
-| `version` | Yes | Version number. |
 
 </CommandTable>
 
@@ -299,15 +364,18 @@ sim files versions revert <fileId> <version> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--expected-current-version <value>` | No | Revert only while this is still the current version; otherwise the request fails with `409`. Omit to revert whatever is current. Collaborative edits and repeated workflow writes that fold into the current version keep its number, so prefer `expectedRevision` to guard content. |
-| `--expected-revision <value>` | No | Revert only while the file still holds the content this revision names, as returned by Get File Metadata or an earlier write; otherwise the request fails with `409`. Unlike a version number, it also catches edits that folded into the current version. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Download the content of one version of a file
+API request and response schemas: [unzipFile](/api-reference/files/unzipFile).
+
+## Sharing
+
+### Show a file’s share settings
 
 ```bash
-sim files versions download <fileId> <version> [options]
+sim files share get <fileId>
 ```
 
 **Arguments**
@@ -317,25 +385,17 @@ sim files versions download <fileId> <version> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `fileId` | Yes | File identifier. |
-| `version` | Yes | Version number. |
 
 </CommandTable>
 
-**Options**
+API request and response schemas: [getFileShare](/api-reference/files/getFileShare).
 
-<CommandTable>
+### Enable or disable sharing for a file
 
-| Option | Required | Description |
-| --- | --- | --- |
-| `-o, --output-file <path>` | No | Write content to a file instead of stdout. |
-| `--force` | No | Overwrite --output-file if it already exists. |
-
-</CommandTable>
-
-## Apply one exact or anchor-based edit to a text file
+OAuth login or personal API key required.
 
 ```bash
-sim files edit <fileId> [options]
+sim files share set <fileId> [options]
 ```
 
 **Arguments**
@@ -354,15 +414,21 @@ sim files edit <fileId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--edit <json\|@file>` | Yes | One edit object: &#123;"mode":"search_replace","search":"old","content":"new","replaceAll":false&#125;, &#123;"mode":"replace_between","beforeAnchor":"start line","afterAnchor":"end line","content":"new"&#125;, &#123;"mode":"insert_after","anchor":"line","content":"new"&#125;, or &#123;"mode":"delete_between","startAnchor":"first line deleted","endAnchor":"ending line kept"&#125;. Anchored modes also accept occurrence starting at 1 (JSON, or @path / @- to read a file or stdin). |
-| `--expected-revision <value>` | No | Revision from Get File Metadata or an earlier write; the request is refused with `409` when the content moved on. |
+| `--is-active <true\|false>` | Yes | Whether the share should resolve. Disabling preserves the token and the whole access configuration, so re-enabling restores the share as it was; enabling rewrites the credentials the resulting mode does not use. Accepted values: `true`, `false`. |
+| `--auth-type <value>` | No | How access to the share is gated. The stored mode is kept when omitted. Enabling `public` clears the stored password and empties `allowedEmails`; `password` empties `allowedEmails`; `email` and `sso` clear the stored password. Accepted values: `public`, `password`, `email`, `sso`. |
+| `--password <value>` | No | Password of 15 to 1024 characters for a password-gated share. Kept when omitted; enabling `password` with neither a supplied nor a stored password is a 400. Taken literally, except that a request from the Sim agent resolves a whole-value `{{ENV_VAR}}` reference to that variable before the rules apply. |
+| `--allowed-emails <value...>` | No | Allowed addresses or `@domain` patterns for email and SSO shares. Kept when omitted; enabling `email` or `sso` with an empty resulting list is a 400. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 
 </CommandTable>
 
-## Show file metadata and sharing status
+API request and response schemas: [upsertFileShare](/api-reference/files/upsertFileShare).
+
+## Versions
+
+### List the recorded versions of a file
 
 ```bash
-sim files describe <fileId> [options]
+sim files versions list <fileId> [options]
 ```
 
 **Arguments**
@@ -381,14 +447,19 @@ sim files describe <fileId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--scope <value>` | No | Which lifecycle set to read from: `active` (default) resolves live files only and returns `404` for a file a delete soft-deleted; `archived` also resolves soft-deleted files, so metadata stays readable before the file is restored. Authorization is identical for both. Accepted values: `active`, `archived`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "version". Accepted values: `version`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
-## Show a file’s share settings
+API request and response schemas: [listFileVersions](/api-reference/files/listFileVersions).
+
+### Show the metadata of one version of a file
 
 ```bash
-sim files share get <fileId>
+sim files versions describe <fileId> <version>
 ```
 
 **Arguments**
@@ -398,17 +469,18 @@ sim files share get <fileId>
 | Argument | Required | Description |
 | --- | --- | --- |
 | `fileId` | Yes | File identifier. |
+| `version` | Yes | Version number. |
 
 </CommandTable>
 
-## Enable or disable sharing for a file
+API request and response schemas: [getFileVersion](/api-reference/files/getFileVersion).
+
+### Read the text content of one version of a file as JSON or YAML
 
 ```bash
-sim files share set <fileId> [options]
+sim files versions read <fileId> <version> [options]
 ```
 
-Enable or disable sharing for a file (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -416,6 +488,7 @@ Enable or disable sharing for a file (OAuth login or personal API key required)
 | Argument | Required | Description |
 | --- | --- | --- |
 | `fileId` | Yes | File identifier. |
+| `version` | Yes | Version number. |
 
 </CommandTable>
 
@@ -425,59 +498,48 @@ Enable or disable sharing for a file (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--is-active <true\|false>` | Yes | Whether the share should resolve. Disabling preserves the token and the whole access configuration, so re-enabling restores the share as it was; enabling rewrites the credentials the resulting mode does not use. Accepted values: `true`, `false`. |
-| `--auth-type <value>` | No | How access to the share is gated. The stored mode is kept when omitted. Enabling `public` clears the stored password and empties `allowedEmails`; `password` empties `allowedEmails`; `email` and `sso` clear the stored password. Accepted values: `public`, `password`, `email`, `sso`. |
-| `--password <value>` | No | Password of 15 to 1024 characters for a password-gated share. Kept when omitted; enabling `password` with neither a supplied nor a stored password is a 400. Taken literally, except that a request from the Sim agent resolves a whole-value `&#123;&#123;ENV_VAR&#125;&#125;` reference to that variable before the rules apply. |
-| `--allowed-emails <value...>` | No | Allowed addresses or `@domain` patterns for email and SSO shares. Kept when omitted; enabling `email` or `sso` with an empty resulting list is a 400. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--max-bytes <value>` | No | Optional ceiling on the source bytes fed to the parser, lowering but never raising the server limit. |
+| `--offset <value>` | No | First line to return, 1-based; 0 also starts at the first line. Absent starts at the first line. |
+| `--limit <value>` | No | How many lines to return from `offset`. Absent reads to the end. |
 
 </CommandTable>
 
-## List files
+API request and response schemas: [readFileVersionText](/api-reference/files/readFileVersionText).
+
+### Download the content of one version of a file
 
 ```bash
-sim files list [options]
+sim files versions download <fileId> <version> [options]
 ```
 
-**Options**
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
-| `--recursive` | No | Include subfolders in the folder filter. Defaults to true when searching and false otherwise. Ignored without a folder filter. |
-| `--no-recursive` | No | Send --recursive as false. |
-| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live files, `archived` for files a delete soft-deleted. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
-| `--search <value>` | No | Case-insensitive substring match against the file name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `size`, `uploadedAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `fileId` | Yes | File identifier. |
+| `version` | Yes | Version number. |
 
 </CommandTable>
 
-## Move files into another folder
-
-```bash
-sim files move [options]
-```
-
-Also available as `sim files mv`.
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--file-ids <value...>` | Yes | File identifiers to update. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--to <value>` | No | Destination folder path; omit for root. |
+| `-o, --output-file <path>` | No | Write content to a file instead of stdout. |
+| `--force` | No | Overwrite --output-file if it already exists. |
 
 </CommandTable>
 
-## Read a file’s text content as JSON or YAML
+API request and response schemas: [downloadFileVersion](/api-reference/files/downloadFileVersion).
+
+### Make a previous version of a file current again
 
 ```bash
-sim files read <fileId> [options]
+sim files versions revert <fileId> <version> [options]
 ```
 
 **Arguments**
@@ -486,7 +548,8 @@ sim files read <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier, or the file’s VFS path: `files/&lt;folder&gt;/&lt;name&gt;`, or `uploads/&lt;name&gt;` for a Chat upload. |
+| `fileId` | Yes | File identifier. |
+| `version` | Yes | Version number. |
 
 </CommandTable>
 
@@ -496,16 +559,19 @@ sim files read <fileId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--max-bytes <value>` | No | Optional ceiling on the source bytes fed to the parser, lowering but never raising the server limit. |
-| `--offset <value>` | No | First line to return, 1-based; 0 also starts at the first line. Absent starts at the first line. |
-| `--limit <value>` | No | How many lines to return from `offset`. Absent reads to the end. |
+| `--expected-current-version <value>` | No | Revert only while this is still the current version; otherwise the request fails with `409`. Omit to revert whatever is current. Collaborative edits and repeated workflow writes that fold into the current version keep its number, so prefer `expectedRevision` to guard content. |
+| `--expected-revision <value>` | No | Revert only while the file still holds the content this revision names, as returned by Get file metadata or an earlier write; otherwise the request fails with `409`. Unlike a version number, it also catches edits that folded into the current version. |
 
 </CommandTable>
 
-## Rename a file
+API request and response schemas: [revertFileVersion](/api-reference/files/revertFileVersion).
+
+### Permanently delete a previous version of a file
+
+This permanently removes the version from history and schedules deletion of its stored content; storage cleanup may retry in the background.
 
 ```bash
-sim files rename <fileId> [options]
+sim files versions delete <fileId> <version> [options]
 ```
 
 **Arguments**
@@ -515,6 +581,7 @@ sim files rename <fileId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `fileId` | Yes | File identifier. |
+| `version` | Yes | Version number. |
 
 </CommandTable>
 
@@ -524,14 +591,20 @@ sim files rename <fileId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | Yes | New file name, including its extension. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Restore an archived file
+API request and response schemas: [deleteFileVersion](/api-reference/files/deleteFileVersion).
+
+## Archive and restore
+
+### Delete file
+
+This archives the file.
 
 ```bash
-sim files restore <fileId>
+sim files delete <fileId> [options]
 ```
 
 **Arguments**
@@ -544,42 +617,25 @@ sim files restore <fileId>
 
 </CommandTable>
 
-## Search file content
-
-```bash
-sim files search [options]
-```
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--query <value>` | Yes | Regular expression, or exact text when `mode` is `exact`. |
-| `--mode <value>` | No | How `query` is read. Accepted values: `exact`, `regex`. |
-| `--max-results <value>` | No | Maximum matching lines to return. |
-| `--folder <value...>` | No | Folders to search, by path as shown in the app; omit to search the whole workspace (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--include-subfolders` | No | Whether each folder scope includes nested folders; on by default. |
-| `--no-include-subfolders` | No | Send --include-subfolders as false. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Unzip an archive into a new folder beside it
+API request and response schemas: [deleteFile](/api-reference/files/deleteFile).
 
-```bash
-sim files unzip <fileId> [options]
-```
+### Delete several files at once
 
-**Arguments**
-
-<CommandTable>
+This archives the listed files; restore them with `files restore`.
 
-| Argument | Required | Description |
-| --- | --- | --- |
-| `fileId` | Yes | File identifier. |
-
-</CommandTable>
+```bash
+sim files batch-delete [options]
+```
 
 **Options**
 
@@ -587,14 +643,17 @@ sim files unzip <fileId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
+| `--file-ids <value...>` | Yes | File identifiers to delete. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Replace a file’s contents
+API request and response schemas: [bulkDeleteFiles](/api-reference/files/bulkDeleteFiles).
+
+### Restore an archived file
 
 ```bash
-sim files set-content <fileId> [options]
+sim files restore <fileId>
 ```
 
 **Arguments**
@@ -607,22 +666,40 @@ sim files set-content <fileId> [options]
 
 </CommandTable>
 
+API request and response schemas: [restoreFile](/api-reference/files/restoreFile).
+
+## Folders
+
+### List folders
+
+```bash
+sim files folders list [options]
+```
+
+Also available as `sim files folders ls`.
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--content <value>` | Yes | Complete replacement content for the file. The 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`. |
-| `--encoding <value>` | No | Content encoding. Accepted values: `utf-8`, `base64`. |
-| `--expected-revision <value>` | No | Revision from Get File Metadata or an earlier write; the request is refused with `409` when the content moved on. |
+| `--parent <value>` | No | Direct parent folder path. |
+| `--search <value>` | No | Case-insensitive substring match against the folder name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--scope <value>` | No | Which lifecycle set to list: `active` (default) returns live folders only; `archived` returns folders a recursive delete soft-deleted, which is how a caller finds a path to hand to the folder restore. Authorization is identical for both. Accepted values: `active`, `archived`. |
+| `--recursive <value>` | No | Whether parentPath includes every descendant instead of direct children only. Accepted values: `true`, `1`, `yes`, `on`, `y`, `enabled`, `false`, `0`, `no`, `off`, `n`, `disabled`. |
+| `--depth <value>` | No | Deepest level below parentPath to include when recursive is true. |
 
 </CommandTable>
 
-## Upload a file to the workspace
+API request and response schemas: [listFileFolders](/api-reference/files/listFilesFolders).
+
+### Create a file folder at a path
 
 ```bash
-sim files upload <path> [options]
+sim files folders create <path>
 ```
 
 **Arguments**
@@ -631,25 +708,18 @@ sim files upload <path> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Local file to upload |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-**Options**
+API request and response schemas: [createFileFolder](/api-reference/files/createFilesFolder).
 
-<CommandTable>
+### Delete folder
 
-| Option | Required | Description |
-| --- | --- | --- |
-| `--folder <path>` | No | Folder path as shown in the app; defaults to the root folder. |
-| `--name <name>` | No | Store it under a different name. |
-
-</CommandTable>
-
-## Download a file’s content to stdout or a local file
+This archives the file folder and, when recursive, everything inside it.
 
 ```bash
-sim files get <fileId> [options]
+sim files folders delete <path> [options]
 ```
 
 **Arguments**
@@ -658,7 +728,7 @@ sim files get <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File whose content to read |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
@@ -668,15 +738,17 @@ sim files get <fileId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-o, --output-file <path>` | No | Write content to a file instead of stdout. |
-| `--force` | No | Overwrite --output-file if it already exists. |
+| `--recursive` | No | Archive the folder and its descendants. Defaults to "false". |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## List file resources and child folders together
+API request and response schemas: [deleteFileFolder](/api-reference/files/deleteFilesFolder).
+
+### Restore an archived file folder
 
 ```bash
-sim files ls [path] [options]
+sim files folders restore <path>
 ```
 
 **Arguments**
@@ -685,22 +757,34 @@ sim files ls [path] [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | No | Folder path to list; defaults to the root folder |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-**Options**
+API request and response schemas: [restoreFileFolder](/api-reference/files/restoreFilesFolder).
+
+### Rename or move a file folder
+
+```bash
+sim files folders move <path> <destination>
+```
+
+Also available as `sim files folders mv`.
+
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--search <text>` | No | Filter folders and resources by name. |
-| `--limit <n>` | No | Maximum combined items to return (0 for everything). Defaults to `0`. |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `destination` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-## Create a file directory at a path
+API request and response schemas: [relocateFileFolder](/api-reference/files/relocateFilesFolder).
+
+### Create a file directory at a path
 
 ```bash
 sim files mkdir <path>
@@ -715,3 +799,10 @@ sim files mkdir <path>
 | `path` | Yes | Folder path to create; the leading / is optional |
 
 </CommandTable>
+
+API request and response schemas: [createFileFolder](/api-reference/files/createFilesFolder).
+
+## Related docs
+
+- [Files](/files)
+- [Output formats](/cli/output)
diff --git a/apps/docs/content/docs/cli/index.mdx b/apps/docs/content/docs/cli/index.mdx
index f9996d4c3f9..ce66c969e07 100644
--- a/apps/docs/content/docs/cli/index.mdx
+++ b/apps/docs/content/docs/cli/index.mdx
@@ -1,115 +1,89 @@
 ---
 title: Sim CLI
-description: Drive workflows, tables, files, knowledge bases, and logs from your shell
+description: Run workflows and manage Sim resources from your terminal.
 ---
 
-import { Step, Steps } from 'fumadocs-ui/components/steps'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-
-`sim` is the command line for Sim. Sign in once, then run workflows, query tables,
-move files, search knowledge bases, and read run logs from the terminal. Results
-are JSON by default, so they pipe into `jq`, cron jobs, CI pipelines, and coding
-agents; use `--output table` to read them as tables. Don't know a command? Run
-`sim cli search "<what you want to do>"`. See [Output formats](/cli/output) for commands that emit raw content
-or local configuration.
+Use `sim` to run workflows, query tables, move files, search knowledge bases, and read logs. Structured results default to JSON for scripts, CI jobs, and coding agents. Select `--output table` for a readable table.
 
 ## Install
 
-<Tabs items={['npm', 'pnpm', 'bun']}>
-  <Tab value="npm">
-    ```bash
-    npm install -g sim
-    ```
-  </Tab>
-  <Tab value="pnpm">
-    ```bash
-    pnpm add -g sim
-    ```
-  </Tab>
-  <Tab value="bun">
-    ```bash
-    bun add -g sim
-    ```
-  </Tab>
-</Tabs>
-
-Requires Node.js 20 or newer. Verify with `sim --version`.
-
-The CLI shows optional update notices on eligible interactive invocations. Run
-`sim update` when you want to install the update. See
-[Updates](/cli/configuration#updates) for installation requirements and how to
-disable notices.
-
-To run it without installing, use `npx sim <command>`.
-
-Using Sim as a library instead? See the [TypeScript](/api-reference/typescript)
-and [Python](/api-reference/python) SDKs, or the
-[HTTP API](/api-reference/getting-started).
+The installed CLI requires Node.js 20 or newer. Install it globally with Bun, then check the version:
 
-## Your first command
+```bash
+bun add -g sim
+sim --version
+```
+
+To run a command without a global installation:
+
+```bash
+bunx sim --help
+```
 
-<Steps>
+The package also supports npm and pnpm installations. Keep using the package manager that owns your installation when upgrading; another manager may install a second copy on your `PATH`.
 
-<Step>
-### Sign in
+Eligible interactive invocations can show an update notice. Run `sim update` to update the active global installation. See [Updates](/cli/configuration#updates) for supported managers, release channels, and notice controls.
+
+## Your first command
+
+### 1. Sign in
 
 ```bash
 sim login
 ```
 
-The CLI opens your browser for approval. Local sign-in prefers OAuth; remote
-terminals use API-key pairing. After OAuth sign-in, choose a default workspace
-with `sim configure --set-workspace <id>`. For SSH and containers, use
-`sim login --method api-key --no-browser` and approve the pairing code.
+Local sign-in prefers OAuth and opens a browser for approval. SSH sessions and headless Linux terminals select API-key pairing. To choose pairing explicitly without opening a browser:
+
+```bash
+sim login --method api-key --no-browser
+```
+
+Approve the code shown in your terminal. See [Authentication](/cli/authentication) for CI credentials, remote terminals, multiple accounts, and self-hosted deployments.
 
-See [Authentication](/cli/authentication) for CI keys, multiple accounts, and
-self-hosted deployments.
-</Step>
+### 2. Choose a workspace
 
-<Step>
-### Check what you are pointed at
+After OAuth login, list your workspaces and set a default:
 
 ```bash
-sim whoami
+sim workspaces list
+sim configure --set-workspace <workspaceId>
 ```
 
-This prints the resolved endpoint, workspace, and output format — and **where
-each one came from**. It is the fastest way to explain a surprising result.
-</Step>
+Pairing sets the default workspace you choose on its approval page. Override that target for one command with `--workspace <workspaceId>`.
 
-<Step>
-### List your workflows
+### 3. Check the resolved settings
 
 ```bash
-sim workflows list
+sim whoami
 ```
 
+This shows the endpoint, credential type, workspace, and output format, including the source of each setting. It also checks authentication and access to the selected workspace. Use `--no-verify` to inspect settings offline.
+
+### 4. List and run a workflow
+
+```bash
+sim workflows list --output table
 ```
-ID                                    NAME           FOLDER     DEPLOYED  RUNS  LAST RUN
-3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8  Refund triage  /Support   yes       412   2026-08-15 14:02:11
-b8c0d247-9e13-4a86-97f5-2ad4e1638c09  Weekly digest  /Reporting no        18    2026-08-11 09:00:04
-```
-</Step>
 
-<Step>
-### Run one
+Example table output; timestamps are UTC:
+
+```text
+ID                                    NAME           FOLDER      DEPLOYED  RUNS  LAST RUN
+3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8  Refund triage  /Support    yes       412   2026-08-15 14:02:11
+b8c0d247-9e13-4a86-97f5-2ad4e1638c09  Weekly digest  /Reporting  no        18    2026-08-11 09:00:04
+```
 
 ```bash
 sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --input '{"ticketId":"T-4821"}'
 ```
 
-This command runs the active deployment. Deploy from the editor or with
-`sim workflows deploy <id>`. To run the current saved workflow state instead,
-use `sim workflows run <id> --manual`.
-</Step>
-
-</Steps>
+Ordinary execution runs the active deployment. Deploy from the workflow builder or with `sim workflows deploy <workflowId>`. To execute the current saved workflow state, use `sim workflows run <workflowId> --manual`.
 
 ## How commands are shaped
 
-Every command reads the same way:
+Resource commands use this shape:
 
-```bash
+```text
 sim <resource> [sub-resource] <verb> [arguments] [options]
 ```
 
@@ -119,11 +93,18 @@ sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --limit 50
 sim knowledge documents upload 4c1b7f60-2d55-4a3e-9c18-70b6ea2f9d31 ./handbook.pdf
 ```
 
-Some resource groups also accept a singular alias: `sim workflow get` and
-`sim workflows get` are the same command. `knowledge` also answers to `kb`.
-Each group’s reference lists its supported aliases.
+In the installed CLI, commands such as `login`, `whoami`, `configure`, `update`, and `chat` run directly under `sim`. Local setup and maintenance commands are unavailable when Sim runs commands inside Chat; see [Configuration](/cli/configuration). Some resource groups have singular aliases: `sim workflow get` and `sim workflows get` are equivalent. `knowledge` also accepts `kb`; each group reference lists its aliases.
+
+## Find a command
+
+Search by the task you want to complete, then inspect the result's arguments and options:
+
+```bash
+sim cli search "cancel a workflow run"
+sim workflows runs cancel --help
+```
 
-Every command accepts `--help`, at any depth:
+Help is available at every depth:
 
 ```bash
 sim --help
@@ -133,38 +114,40 @@ sim tables rows query --help
 
 ## What you can do
 
-| Group | What it covers |
+| Group | Capabilities |
 | --- | --- |
-| [`workflows`](/cli/workflows) | Run, deploy, roll back, import, export, and organize workflows |
-| [`logs`](/cli/logs) | Read run diagnostics, including the full trace tree |
-| [`tables`](/cli/tables) | Query, insert, update, and import rows; manage columns and views |
-| [`files`](/cli/files) | Upload, download, share, and organize workspace files |
-| [`knowledge`](/cli/knowledge) | Search knowledge bases and manage their documents and tags |
-| [`skills`](/cli/skills) | Manage agent skills |
-| [`sandboxes`](/cli/sandboxes) | Manage sandbox dependencies, managed CLIs, and system packages |
-| [`mcp-servers`](/cli/mcp-servers) | Manage MCP server connections and their tools |
+| [`workflows`](/cli/workflows) | Build, deploy, run, roll back, import, export, and organize workflows |
+| [`logs`](/cli/logs) | Inspect runs and recursive traces |
+| [`tables`](/cli/tables) | Query and change rows; manage columns, views, imports, and exports |
+| [`files`](/cli/files) | Upload, download, share, version, and organize workspace files |
+| [`knowledge`](/cli/knowledge) | Search knowledge bases and manage documents, connectors, and tags |
+| [`skills`](/cli/skills) | Manage skills and their editors |
+| [`sandboxes`](/cli/sandboxes) | Configure dependencies, managed CLIs, and system packages |
+| [`mcp-servers`](/cli/mcp-servers) | Connect external Model Context Protocol (MCP) servers and discover tools |
 | [`custom-tools`](/cli/custom-tools) | Manage custom tool definitions |
 | [`credentials`](/cli/credentials) | Connect, reconnect, and disconnect integration credentials |
-| [`secrets`](/cli/secrets) | Set and remove workspace secrets |
-| [`billing`](/cli/billing) | Check plan status and credit usage |
-| [`audit-logs`](/cli/audit-logs) | Read organization audit logs |
-| [`workspaces`](/cli/workspaces) | Inspect the active workspace and its members |
-| [`blocks`](/cli/blocks) | Browse the block catalog and read one block's configuration fields |
-| [`tools`](/cli/tools) | Browse and execute built-in tools |
-| [`connector-types`](/cli/connector-types) | Browse knowledge-base connector types and their config fields |
-| [`chat-deployments`](/cli/chat-deployments) | List the hosted chats a workspace serves |
-| [`workflow-mcp-servers`](/cli/workflow-mcp-servers) | Publish workflows as MCP tools for outside agents |
-| [`meta`](/cli/meta) | Check what this API supports and which limits apply |
-
-The [command overview](/cli/commands) has the global options and the commands
-that take no resource; the [complete reference](/cli/reference) documents every
-subcommand, argument, and flag on one page. Both are generated from the CLI
-itself.
-
-## Where to go next
-
-- [Authentication](/cli/authentication) — signing in, API keys for CI, and multiple accounts
-- [Configuration](/cli/configuration) — profiles, config files, environment variables, and precedence
-- [Output formats](/cli/output) — `table`, `json`, `yaml`, and `text`, and when to use each
-- [Scripting](/cli/scripting) — piping, file inputs, exit codes, and automation recipes
-- [Troubleshooting](/cli/troubleshooting) — what each error means, and how to resolve it
+| [`secrets`](/cli/secrets) | Manage personal and workspace secrets |
+| [`workspaces`](/cli/workspaces) | Manage members, invitations, forks, and workspace sync |
+| [`organizations`](/cli/organizations) | Manage organization access, members, usage, domains, and SSO |
+| [`permission-groups`](/cli/permission-groups) | Manage restrictions and group membership |
+| [`billing`](/cli/billing) | Inspect plan status and credit usage |
+| [`audit-logs`](/cli/audit-logs) | Read organization audit actions |
+| [`blocks`](/cli/blocks) | Inspect the block catalog and configuration fields |
+| [`tools`](/cli/tools) | Inspect and execute built-in tools |
+| [`connector-types`](/cli/connector-types) | Inspect knowledge-base connector types and fields |
+| [`selectors`](/cli/selectors) | Discover and verify configuration choices |
+| [`chat-deployments`](/cli/chat-deployments) | List deployed workflow chats |
+| [`workflow-mcp-servers`](/cli/workflow-mcp-servers) | Expose deployed workflows as MCP tools |
+| [`meta`](/cli/meta) | Inspect API availability and credential status |
+
+The [command overview](/cli/commands) lists global options and root commands. The [complete reference](/cli/reference) contains every subcommand, argument, and option on one page. Both are generated from the CLI.
+
+## Related docs
+
+- [Authentication](/cli/authentication)
+- [Configuration](/cli/configuration)
+- [Output formats](/cli/output)
+- [Scripting](/cli/scripting)
+- [Workflow imports and workspace sync](/cli/workflow-sync)
+- [Troubleshooting](/cli/troubleshooting)
+- [TypeScript SDK](/api-reference/typescript), [Python SDK](/api-reference/python), and [HTTP API](/api-reference/getting-started)
diff --git a/apps/docs/content/docs/cli/knowledge.mdx b/apps/docs/content/docs/cli/knowledge.mdx
index e449824c7b9..29bad7ed758 100644
--- a/apps/docs/content/docs/cli/knowledge.mdx
+++ b/apps/docs/content/docs/cli/knowledge.mdx
@@ -1,21 +1,46 @@
 ---
 title: Knowledge
-description: Manage knowledge — every subcommand, argument, and flag
+description: Manage knowledge bases, indexed documents, search, tags, and connector syncs.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Manage knowledge bases, indexed documents, search, tags, and connector syncs.
+
 `sim knowledge` is also spelled `sim kb`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
+
+## Knowledge bases
 
-## Index files the workspace already stores
+### List knowledge bases
 
 ```bash
-sim knowledge from-workspace-files create <knowledgeBaseId> [options]
+sim knowledge list [options]
 ```
 
-Index files the workspace already stores (OAuth login or personal API key required)
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--scope <value>` | No | Lifecycle scope: active or archived knowledge bases. Use Restore knowledge base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches. Defaults to "active". Accepted values: `active`, `archived`. |
+| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
+| `--search <value>` | No | Case-insensitive substring match against the resource name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+
+</CommandTable>
+
+API request and response schemas: [listKnowledgeBases](/api-reference/knowledge-bases/listKnowledgeBases).
+
+### Get knowledge base
+
+```bash
+sim knowledge get <knowledgeBaseId>
+```
 
 **Arguments**
 
@@ -27,24 +52,35 @@ Index files the workspace already stores (OAuth login or personal API key requir
 
 </CommandTable>
 
+API request and response schemas: [getKnowledgeBase](/api-reference/knowledge-bases/getKnowledgeBase).
+
+### Create knowledge base
+
+```bash
+sim knowledge create [options]
+```
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--file <value...>` | Yes | Workspace file ID or key (repeatable) (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--name <value>` | Yes | Human-readable knowledge base name. |
+| `--description <value>` | No | Optional knowledge base description. |
+| `--chunking-config <json\|@file>` | No | Chunking configuration; defaults are applied when omitted. (JSON, or @path / @- to read a file or stdin). |
+| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 
 </CommandTable>
 
-## Declare the tag definitions a knowledge base needs
+API request and response schemas: [createKnowledgeBase](/api-reference/knowledge-bases/createKnowledgeBase).
+
+### Update knowledge base
 
 ```bash
-sim knowledge tags save <knowledgeBaseId> [options]
+sim knowledge update <knowledgeBaseId> [options]
 ```
 
-Declare the tag definitions a knowledge base needs (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -61,18 +97,21 @@ Declare the tag definitions a knowledge base needs (OAuth login or personal API
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--definitions <json\|@file>` | Yes | Tag definitions: [&#123;"tagSlot":"tag1","displayName":"category","fieldType":"text"&#125;] (JSON, or @path / @- to read a file or stdin). |
+| `--name <value>` | No | New knowledge base name. |
+| `--description <value>` | No | New knowledge base description. |
+| `--chunking-config <json\|@file>` | No | New document chunking configuration. (JSON, or @path / @- to read a file or stdin). |
+| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 
 </CommandTable>
 
-## Create tag
+API request and response schemas: [updateKnowledgeBase](/api-reference/knowledge-bases/updateKnowledgeBase).
+
+### Move a knowledge base to a folder
 
 ```bash
-sim knowledge tags create <knowledgeBaseId> [options]
+sim knowledge mv <knowledgeBaseId> <folder>
 ```
 
-Create Tag (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -80,29 +119,20 @@ Create Tag (OAuth login or personal API key required)
 | Argument | Required | Description |
 | --- | --- | --- |
 | `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
+| `folder` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-**Options**
-
-<CommandTable>
-
-| Option | Required | Description |
-| --- | --- | --- |
-| `--display-name <value>` | Yes | Name tag filters and document reads use for this tag. |
-| `--field-type <value>` | No | Value type stored in the slot; it decides which slots are usable and which filter operators apply. Defaults to text, so a number, date, or boolean slot must name its type here. Slot capacity per type: text 7, number 5, date 2, boolean 3. Accepted values: `text`, `number`, `date`, `boolean`. |
-| `--tag-slot <value>` | No | Slot to store the tag in. Omit to take the next free slot for the field type; a slot that does not belong to the field type, or one already in use, is rejected. Accepted values: `tag1`, `tag2`, `tag3`, `tag4`, `tag5`, `tag6`, `tag7`, `number1`, `number2`, `number3`, `number4`, `number5`, `date1`, `date2`, `boolean1`, `boolean2`, `boolean3`. |
+API request and response schemas: [updateKnowledgeBase](/api-reference/knowledge-bases/updateKnowledgeBase).
 
-</CommandTable>
+### Delete knowledge base
 
-## Delete tag
+This archives the knowledge base and every document in it; restore with `knowledge restore`.
 
 ```bash
-sim knowledge tags delete <knowledgeBaseId> <tagId> [options]
+sim knowledge delete <knowledgeBaseId> [options]
 ```
 
-Delete Tag (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -110,7 +140,6 @@ Delete Tag (OAuth login or personal API key required)
 | Argument | Required | Description |
 | --- | --- | --- |
 | `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
-| `tagId` | Yes | Unique tag definition identifier. |
 
 </CommandTable>
 
@@ -124,14 +153,14 @@ Delete Tag (OAuth login or personal API key required)
 
 </CommandTable>
 
-## Remove tag definitions no document still uses
+API request and response schemas: [deleteKnowledgeBase](/api-reference/knowledge-bases/deleteKnowledgeBase).
+
+### Restore an archived knowledge base
 
 ```bash
-sim knowledge tags cleanup <knowledgeBaseId> [options]
+sim knowledge restore <knowledgeBaseId>
 ```
 
-Remove tag definitions no document still uses (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -142,33 +171,49 @@ Remove tag definitions no document still uses (OAuth login or personal API key r
 
 </CommandTable>
 
+API request and response schemas: [restoreKnowledgeBase](/api-reference/knowledge-bases/restoreKnowledgeBase).
+
+## Search and export
+
+### Search knowledge
+
+```bash
+sim knowledge search [options]
+```
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--unused` | No | Whether to remove only the tag definitions no document in the knowledge base still carries a value for. Defaults to true. Pass --no-unused to delete every definition on the knowledge base, which also clears its slot on every document and chunk and is not recoverable. |
-| `--no-unused` | No | Send --unused as false. |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--kb <value...>` | Yes | Knowledge base ID (repeatable) (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--query <value>` | No | Text to search for. |
+| `--top-k <value>` | No | Maximum number of search results to return. Must be a whole number between 1 and 100. Defaults to 10. |
+| `--tag-filters <json\|@file>` | No | Tag filters as [&#123;"tagName":"...","operator":"...","value":"..."&#125;] (JSON, or @path / @- to read a file or stdin). |
+| `--search-mode <value>` | No | Search algorithm. Accepted values: `vector`, `hybrid`. |
+| `--reranker-enabled` | No | Reorder retrieved chunks with a reranking model before truncating to `topK`. Ignored for tag-only searches. A completed reranking call adds a search unit. If reranking is unavailable, results keep their retrieval order; check `rerankerStatus`. |
+| `--no-reranker-enabled` | No | Send --reranker-enabled as false. |
+| `--reranker-model <value>` | No | Reranking model to use when `rerankerEnabled` is true. Defaults to `rerank-v4.0-fast`. Accepted values: `rerank-v4.0-pro`, `rerank-v4.0-fast`, `rerank-v3.5`. |
+| `--reranker-input-count <value>` | No | How many candidate chunks to retrieve before reranking. Defaults to four times `topK`, capped at 100. A larger pool costs more retrieval work but gives the reranker more to choose from. |
 
 </CommandTable>
 
-## Show which tag slot a create would take for a field type
+API request and response schemas: [searchKnowledge](/api-reference/knowledge-bases/searchKnowledge).
+
+### Export a knowledge base as a .simkb.zip bundle
 
 ```bash
-sim knowledge tags next-slot <knowledgeBaseId> [options]
+sim knowledge export <knowledgeBaseId> [options]
 ```
 
-Show which tag slot a create would take for a field type (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
+| `knowledgeBaseId` | Yes | Knowledge base to export |
 
 </CommandTable>
 
@@ -178,14 +223,20 @@ Show which tag slot a create would take for a field type (OAuth login or persona
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--field-type <value>` | Yes | Value type stored in the slot; it decides which slots are usable and which filter operators apply. Slot capacity per type: text 7, number 5, date 2, boolean 3. Accepted values: `text`, `number`, `date`, `boolean`. |
+| `-o, --output-file <path>` | No | Write the bundle to this path instead of the name the server suggests; pass - to stream it to stdout. |
+| `--force` | No | Overwrite --output-file if it already exists. |
+| `--no-vectors` | No | Leave chunk vectors out of the bundle, so an import re-embeds every chunk. |
 
 </CommandTable>
 
-## List tags
+API request and response schemas: [exportKnowledgeBase](/api-reference/knowledge-bases/exportKnowledgeBase).
+
+## Documents
+
+### List documents
 
 ```bash
-sim knowledge tags list <knowledgeBaseId>
+sim knowledge documents list <knowledgeBaseId> [options]
 ```
 
 **Arguments**
@@ -198,14 +249,30 @@ sim knowledge tags list <knowledgeBaseId>
 
 </CommandTable>
 
-## Show how many documents and chunks carry each tag
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--search <value>` | No | Case-insensitive substring match against the document filename. |
+| `--enabled-filter <value>` | No | Filter by whether documents are enabled for search. Defaults to "all". Accepted values: `all`, `enabled`, `disabled`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `filename`. Defaults to "uploadedAt". Accepted values: `filename`, `fileSize`, `tokenCount`, `chunkCount`, `uploadedAt`, `processingStatus`, `enabled`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--tag-filters <value>` | No | A JSON-encoded array of at most 10 tag filters, using the same display-name shape as knowledge search: `[{"tagName":"category","operator":"eq","value":"billing"}]`. Every filter must hold, including two that name the same tag. A name that is not defined in this knowledge base is rejected, never ignored. |
+
+</CommandTable>
+
+API request and response schemas: [listKnowledgeDocuments](/api-reference/knowledge-bases/listKnowledgeDocuments).
+
+### Get document
 
 ```bash
-sim knowledge tags usage <knowledgeBaseId>
+sim knowledge documents get <knowledgeBaseId> <documentId>
 ```
 
-Show how many documents and chunks carry each tag (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -213,25 +280,26 @@ Show how many documents and chunks carry each tag (OAuth login or personal API k
 | Argument | Required | Description |
 | --- | --- | --- |
 | `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
+| `documentId` | Yes | Unique knowledge document identifier. |
 
 </CommandTable>
 
-## Update tag
+API request and response schemas: [getKnowledgeDocument](/api-reference/knowledge-bases/getKnowledgeDocument).
+
+### Upload a document to a knowledge base
 
 ```bash
-sim knowledge tags update <knowledgeBaseId> <tagId> [options]
+sim knowledge documents upload <knowledgeBaseId> <path> [options]
 ```
 
-Update Tag (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
-| `tagId` | Yes | Unique tag definition identifier. |
+| `knowledgeBaseId` | Yes | Knowledge base to upload into |
+| `path` | Yes | Local file to upload |
 
 </CommandTable>
 
@@ -241,19 +309,23 @@ Update Tag (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--display-name <value>` | No | New tag display name. |
-| `--field-type <value>` | No | New value type for the tag. Accepted values: `text`, `number`, `date`, `boolean`. |
+| `--name <name>` | No | Store it under a different name. |
+| `--tag <value...>` | No | Document tags, in tag1 through tag7 order. |
+| `--recipe <name>` | No | Document processing recipe. Accepted values: `default`, `plain`, `markdown`, `code`. |
+| `--lang <code>` | No | Document language tag: hyphen-separated letter and digit subtags, for example en or en-US. |
 
 </CommandTable>
 
-## Enable, disable, or delete many chunks at once
+API request and response schemas: [createKnowledgeDocumentUpload](/api-reference/knowledge-bases/createKnowledgeDocumentUpload), [createKnowledgeDocumentUploadPartUrls](/api-reference/knowledge-bases/createKnowledgeDocumentUploadPartUrls), [completeKnowledgeDocumentUpload](/api-reference/knowledge-bases/completeKnowledgeDocumentUpload), [abortKnowledgeDocumentUpload](/api-reference/knowledge-bases/abortKnowledgeDocumentUpload).
+
+### Update document
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge chunks batch-update <knowledgeBaseId> <documentId> [options]
+sim knowledge documents update <knowledgeBaseId> <documentId> [options]
 ```
 
-Enable, disable, or delete many chunks at once (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -271,20 +343,43 @@ Enable, disable, or delete many chunks at once (OAuth login or personal API key
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--operation <value>` | Yes | What to do with the selected chunks. Accepted values: `enable`, `disable`, `delete`. |
-| `--chunk <value...>` | Yes | Chunks to operate on, by identifier. An id naming no chunk in the document is reported in errors and does not fail the request. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--filename <value>` | No | New filename for the document. |
+| `--enabled` | No | Whether the document participates in search. Disabling keeps it indexed. |
+| `--no-enabled` | No | Send --enabled as false. |
+| `--tag1 <value>` | No | New value for tag slot 1. |
+| `--tag2 <value>` | No | New value for tag slot 2. |
+| `--tag3 <value>` | No | New value for tag slot 3. |
+| `--tag4 <value>` | No | New value for tag slot 4. |
+| `--tag5 <value>` | No | New value for tag slot 5. |
+| `--tag6 <value>` | No | New value for tag slot 6. |
+| `--tag7 <value>` | No | New value for tag slot 7. |
+| `--number1 <value>` | No | New value for number tag slot 1. |
+| `--number2 <value>` | No | New value for number tag slot 2. |
+| `--number3 <value>` | No | New value for number tag slot 3. |
+| `--number4 <value>` | No | New value for number tag slot 4. |
+| `--number5 <value>` | No | New value for number tag slot 5. |
+| `--date1 <value>` | No | New value for date tag slot 1, formatted YYYY-MM-DD. |
+| `--date2 <value>` | No | New value for date tag slot 2, formatted YYYY-MM-DD. |
+| `--boolean1` | No | New value for boolean tag slot 1. |
+| `--no-boolean1` | No | Send --boolean1 as false. |
+| `--boolean2` | No | New value for boolean tag slot 2. |
+| `--no-boolean2` | No | Send --boolean2 as false. |
+| `--boolean3` | No | New value for boolean tag slot 3. |
+| `--no-boolean3` | No | Send --boolean3 as false. |
+| `--retry-processing` | No | Requeue a failed or stuck document for processing. Send it alone — no other field may accompany it — and it answers with a queue acknowledgement rather than the document. |
 
 </CommandTable>
 
-## Create chunk
+API request and response schemas: [updateKnowledgeDocument](/api-reference/knowledge-bases/updateKnowledgeDocument).
+
+### Enable or disable every matching document
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge chunks create <knowledgeBaseId> <documentId> [options]
+sim knowledge documents batch-update <knowledgeBaseId> [options]
 ```
 
-Create Chunk (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -292,7 +387,6 @@ Create Chunk (OAuth login or personal API key required)
 | Argument | Required | Description |
 | --- | --- | --- |
 | `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
-| `documentId` | Yes | Unique knowledge document identifier. |
 
 </CommandTable>
 
@@ -302,20 +396,23 @@ Create Chunk (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--content <value>` | Yes | Text to embed. It is embedded on write, so the chunk is searchable immediately. |
-| `--enabled` | No | Whether the new chunk participates in search. |
-| `--no-enabled` | No | Send --enabled as false. |
+| `--operation <value>` | Yes | Whether the selected documents become enabled or disabled for search. Accepted values: `enable`, `disable`. |
+| `--document <value...>` | No | Documents to update, by identifier. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--select-all` | No | Apply to every document in the knowledge base. |
+| `--enabled-filter <value>` | No | With `selectAll`, restrict the update to documents in this state. Accepted values: `all`, `enabled`, `disabled`. |
 
 </CommandTable>
 
-## Delete chunk
+API request and response schemas: [bulkUpdateKnowledgeDocuments](/api-reference/knowledge-bases/bulkUpdateKnowledgeDocuments).
+
+### Delete a document from a knowledge base
+
+This deletes the document and its embeddings.
 
 ```bash
-sim knowledge chunks delete <knowledgeBaseId> <documentId> <chunkId> [options]
+sim knowledge documents delete <knowledgeBaseId> <documentId> [options]
 ```
 
-Delete Chunk (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -324,7 +421,6 @@ Delete Chunk (OAuth login or personal API key required)
 | --- | --- | --- |
 | `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
 | `documentId` | Yes | Unique knowledge document identifier. |
-| `chunkId` | Yes | Unique chunk identifier. |
 
 </CommandTable>
 
@@ -338,14 +434,16 @@ Delete Chunk (OAuth login or personal API key required)
 
 </CommandTable>
 
-## Get chunk
+API request and response schemas: [deleteKnowledgeDocument](/api-reference/knowledge-bases/deleteKnowledgeDocument).
+
+### Index files the workspace already stores
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge chunks get <knowledgeBaseId> <documentId> <chunkId>
+sim knowledge from-workspace-files create <knowledgeBaseId> [options]
 ```
 
-Get Chunk (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -353,19 +451,31 @@ Get Chunk (OAuth login or personal API key required)
 | Argument | Required | Description |
 | --- | --- | --- |
 | `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
-| `documentId` | Yes | Unique knowledge document identifier. |
-| `chunkId` | Yes | Unique chunk identifier. |
 
 </CommandTable>
 
-## List chunks
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--file <value...>` | Yes | Workspace file ID or canonical files/&lt;folder&gt;/&lt;name&gt; path (repeatable) (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+
+</CommandTable>
+
+API request and response schemas: [addWorkspaceFilesToKnowledgeBase](/api-reference/knowledge-bases/addWorkspaceFilesToKnowledgeBase).
+
+## Chunks
+
+### List chunks
+
+OAuth login or personal API key required.
 
 ```bash
 sim knowledge chunks list <knowledgeBaseId> <documentId> [options]
 ```
 
-List Chunks (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -384,22 +494,24 @@ List Chunks (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--search <value>` | No | Case-insensitive substring match against chunk content. |
-| `--enabled <value>` | No | Restrict to enabled or disabled chunks. `all` returns both. Accepted values: `true`, `false`, `all`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `chunkIndex`, `tokenCount`, `enabled`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--enabled <value>` | No | Restrict to enabled or disabled chunks. `all` returns both. Defaults to "all". Accepted values: `true`, `false`, `all`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "chunkIndex". Accepted values: `chunkIndex`, `tokenCount`, `enabled`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
-## Update chunk
+API request and response schemas: [listKnowledgeChunks](/api-reference/knowledge-bases/listKnowledgeChunks).
+
+### Get chunk
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge chunks update <knowledgeBaseId> <documentId> <chunkId> [options]
+sim knowledge chunks get <knowledgeBaseId> <documentId> <chunkId>
 ```
 
-Update Chunk (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -412,26 +524,16 @@ Update Chunk (OAuth login or personal API key required)
 
 </CommandTable>
 
-**Options**
-
-<CommandTable>
-
-| Option | Required | Description |
-| --- | --- | --- |
-| `--content <value>` | No | Replacement text. Changing it re-embeds the chunk and re-derives its token and character counts. |
-| `--enabled` | No | Whether the chunk participates in search. Disabling keeps it indexed. |
-| `--no-enabled` | No | Send --enabled as false. |
+API request and response schemas: [getKnowledgeChunk](/api-reference/knowledge-bases/getKnowledgeChunk).
 
-</CommandTable>
+### Create chunk
 
-## Enable or disable every matching document
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge documents batch-update <knowledgeBaseId> [options]
+sim knowledge chunks create <knowledgeBaseId> <documentId> [options]
 ```
 
-Enable or disable every matching document (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -439,6 +541,7 @@ Enable or disable every matching document (OAuth login or personal API key requi
 | Argument | Required | Description |
 | --- | --- | --- |
 | `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
+| `documentId` | Yes | Unique knowledge document identifier. |
 
 </CommandTable>
 
@@ -448,17 +551,20 @@ Enable or disable every matching document (OAuth login or personal API key requi
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--operation <value>` | Yes | Whether the selected documents become enabled or disabled for search. Accepted values: `enable`, `disable`. |
-| `--document <value...>` | No | Documents to update, by identifier. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--select-all` | No | Apply to every document in the knowledge base. |
-| `--enabled-filter <value>` | No | With `selectAll`, restrict the update to documents in this state. Accepted values: `all`, `enabled`, `disabled`. |
+| `--content <value>` | Yes | Text embedded before the response. Search includes it when the chunk and document are enabled and the document has completed processing. |
+| `--enabled` | No | Whether the new chunk participates in search. Defaults to true. |
+| `--no-enabled` | No | Send --enabled as false. |
 
 </CommandTable>
 
-## Delete a document from a knowledge base
+API request and response schemas: [createKnowledgeChunk](/api-reference/knowledge-bases/createKnowledgeChunk).
+
+### Update chunk
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge documents delete <knowledgeBaseId> <documentId> [options]
+sim knowledge chunks update <knowledgeBaseId> <documentId> <chunkId> [options]
 ```
 
 **Arguments**
@@ -469,6 +575,7 @@ sim knowledge documents delete <knowledgeBaseId> <documentId> [options]
 | --- | --- | --- |
 | `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
 | `documentId` | Yes | Unique knowledge document identifier. |
+| `chunkId` | Yes | Unique chunk identifier. |
 
 </CommandTable>
 
@@ -478,31 +585,22 @@ sim knowledge documents delete <knowledgeBaseId> <documentId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--content <value>` | No | Replacement text. Changing it re-embeds the chunk and re-derives its token and character counts. |
+| `--enabled` | No | Whether the chunk participates in search. Disabling keeps it indexed. |
+| `--no-enabled` | No | Send --enabled as false. |
 
 </CommandTable>
 
-## Get document
-
-```bash
-sim knowledge documents get <knowledgeBaseId> <documentId>
-```
-
-**Arguments**
-
-<CommandTable>
+API request and response schemas: [updateKnowledgeChunk](/api-reference/knowledge-bases/updateKnowledgeChunk).
 
-| Argument | Required | Description |
-| --- | --- | --- |
-| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
-| `documentId` | Yes | Unique knowledge document identifier. |
+### Enable, disable, or delete many chunks at once
 
-</CommandTable>
+OAuth login or personal API key required.
 
-## List documents
+This applies --operation to every named chunk; with --operation delete it deletes them and their embeddings, which cannot be undone.
 
 ```bash
-sim knowledge documents list <knowledgeBaseId> [options]
+sim knowledge chunks batch-update <knowledgeBaseId> <documentId> [options]
 ```
 
 **Arguments**
@@ -512,6 +610,7 @@ sim knowledge documents list <knowledgeBaseId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
+| `documentId` | Yes | Unique knowledge document identifier. |
 
 </CommandTable>
 
@@ -521,24 +620,24 @@ sim knowledge documents list <knowledgeBaseId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--search <value>` | No | Case-insensitive substring match against the document filename. |
-| `--enabled-filter <value>` | No | Filter by whether documents are enabled for search. Accepted values: `all`, `enabled`, `disabled`. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `filename` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `filename`, `fileSize`, `tokenCount`, `chunkCount`, `uploadedAt`, `processingStatus`, `enabled`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--tag-filters <value>` | No | A JSON-encoded array of at most 10 tag filters, using the same display-name shape as knowledge search: `[&#123;"tagName":"category","operator":"eq","value":"billing"&#125;]`. Every filter must hold, including two that name the same tag. A name that is not defined in this knowledge base is rejected, never ignored. |
+| `--operation <value>` | Yes | What to do with the selected chunks. Accepted values: `enable`, `disable`, `delete`. |
+| `--chunk <value...>` | Yes | Chunks to operate on, by identifier. An id naming no chunk in the document is reported in errors and does not fail the request. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Update document
+API request and response schemas: [bulkUpdateKnowledgeChunks](/api-reference/knowledge-bases/bulkUpdateKnowledgeChunks).
+
+### Delete chunk
+
+OAuth login or personal API key required.
+
+This deletes the chunk and its embedding.
 
 ```bash
-sim knowledge documents update <knowledgeBaseId> <documentId> [options]
+sim knowledge chunks delete <knowledgeBaseId> <documentId> <chunkId> [options]
 ```
 
-Update Document (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -547,6 +646,7 @@ Update Document (OAuth login or personal API key required)
 | --- | --- | --- |
 | `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
 | `documentId` | Yes | Unique knowledge document identifier. |
+| `chunkId` | Yes | Unique chunk identifier. |
 
 </CommandTable>
 
@@ -556,37 +656,18 @@ Update Document (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--filename <value>` | No | New filename for the document. |
-| `--enabled` | No | Whether the document participates in search. Disabling keeps it indexed. |
-| `--no-enabled` | No | Send --enabled as false. |
-| `--tag1 <value>` | No | New value for tag slot 1. |
-| `--tag2 <value>` | No | New value for tag slot 2. |
-| `--tag3 <value>` | No | New value for tag slot 3. |
-| `--tag4 <value>` | No | New value for tag slot 4. |
-| `--tag5 <value>` | No | New value for tag slot 5. |
-| `--tag6 <value>` | No | New value for tag slot 6. |
-| `--tag7 <value>` | No | New value for tag slot 7. |
-| `--number1 <value>` | No | New value for number tag slot 1. |
-| `--number2 <value>` | No | New value for number tag slot 2. |
-| `--number3 <value>` | No | New value for number tag slot 3. |
-| `--number4 <value>` | No | New value for number tag slot 4. |
-| `--number5 <value>` | No | New value for number tag slot 5. |
-| `--date1 <value>` | No | New value for date tag slot 1, formatted YYYY-MM-DD. |
-| `--date2 <value>` | No | New value for date tag slot 2, formatted YYYY-MM-DD. |
-| `--boolean1` | No | New value for boolean tag slot 1. |
-| `--no-boolean1` | No | Send --boolean1 as false. |
-| `--boolean2` | No | New value for boolean tag slot 2. |
-| `--no-boolean2` | No | Send --boolean2 as false. |
-| `--boolean3` | No | New value for boolean tag slot 3. |
-| `--no-boolean3` | No | Send --boolean3 as false. |
-| `--retry-processing` | No | Requeue a failed or stuck document for processing. Send it alone — no other field may accompany it — and it answers with a queue acknowledgement rather than the document. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Upload a document to a knowledge base
+API request and response schemas: [deleteKnowledgeChunk](/api-reference/knowledge-bases/deleteKnowledgeChunk).
+
+## Tags
+
+### List tags
 
 ```bash
-sim knowledge documents upload <knowledgeBaseId> <path> [options]
+sim knowledge tags list <knowledgeBaseId>
 ```
 
 **Arguments**
@@ -595,51 +676,52 @@ sim knowledge documents upload <knowledgeBaseId> <path> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Knowledge base to upload into |
-| `path` | Yes | Local file to upload |
+| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
 
 </CommandTable>
 
-**Options**
+API request and response schemas: [listKnowledgeTags](/api-reference/knowledge-bases/listKnowledgeTags).
+
+### Create tag
+
+OAuth login or personal API key required.
+
+```bash
+sim knowledge tags create <knowledgeBaseId> [options]
+```
+
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--name <name>` | No | Store it under a different name. |
-| `--tag <value...>` | No | Document tags, in tag1 through tag7 order. |
-| `--recipe <name>` | No | Document processing recipe. Accepted values: `default`, `plain`, `markdown`, `code`. |
-| `--lang <code>` | No | Document language tag: hyphen-separated letter and digit subtags, for example en or en-US. |
+| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
 
 </CommandTable>
 
-## Create knowledge base
-
-```bash
-sim knowledge create [options]
-```
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | Yes | Human-readable knowledge base name. |
-| `--description <value>` | No | Optional knowledge base description. |
-| `--chunking-config <json\|@file>` | No | Chunking configuration; defaults are applied when omitted. (JSON, or @path / @- to read a file or stdin). |
-| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
+| `--display-name <value>` | Yes | Name tag filters and document reads use for this tag. |
+| `--field-type <value>` | No | Value type stored in the slot; it decides which slots are usable and which filter operators apply. Defaults to text, so a number, date, or boolean slot must name its type here. Slot capacity per type: text 7, number 5, date 2, boolean 3. Accepted values: `text`, `number`, `date`, `boolean`. |
+| `--tag-slot <value>` | No | Slot to store the tag in. Omit to take the next free slot for the field type; a slot that does not belong to the field type, or one already in use, is rejected. Accepted values: `tag1`, `tag2`, `tag3`, `tag4`, `tag5`, `tag6`, `tag7`, `number1`, `number2`, `number3`, `number4`, `number5`, `date1`, `date2`, `boolean1`, `boolean2`, `boolean3`. |
 
 </CommandTable>
 
-## Create knowledge connector
+API request and response schemas: [createKnowledgeTag](/api-reference/knowledge-bases/createKnowledgeTag).
+
+### Declare the tag definitions a knowledge base needs
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge connectors create <knowledgeBaseId> [options]
+sim knowledge tags save <knowledgeBaseId> [options]
 ```
 
-Create Knowledge Connector (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -656,30 +738,28 @@ Create Knowledge Connector (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--connector-type <value>` | Yes | Registered connector type. |
-| `--credential-id <value>` | No | OAuth credential identifier for connector types whose `auth.mode` is `oauth` (see connector types); omit it for `apiKey` connectors. |
-| `--api-key <value>` | No | Write-only API key for connector types whose `auth.mode` is `apiKey` (see connector types), or a personal access token for an OAuth connector that also accepts one, such as GitHub. Send it instead of `credentialId`. Pass a raw key, or a secret reference written as the whole value `&#123;&#123;SECRET_NAME&#125;&#125;`, which the server resolves; `$SECRET_NAME` is not a reference. |
-| `--source-config <json\|@file>` | Yes | Connector-specific source selection and filtering configuration. (JSON, or @path / @- to read a file or stdin). |
-| `--sync-interval-minutes <value>` | No | Scheduled synchronization interval in minutes; zero disables scheduling. |
+| `--definitions <json\|@file>` | Yes | Tag definitions: [&#123;"tagSlot":"tag1","displayName":"category","fieldType":"text"&#125;] (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Delete knowledge connector
+API request and response schemas: [bulkSaveKnowledgeTagDefinitions](/api-reference/knowledge-bases/bulkSaveKnowledgeTagDefinitions).
+
+### Update tag
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge connectors delete <knowledgeBaseId> <connectorId> [options]
+sim knowledge tags update <knowledgeBaseId> <tagId> [options]
 ```
 
-Delete Knowledge Connector (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Knowledge base that owns the connector. |
-| `connectorId` | Yes | Connector selected for the operation. |
+| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
+| `tagId` | Yes | Unique tag definition identifier. |
 
 </CommandTable>
 
@@ -689,47 +769,48 @@ Delete Knowledge Connector (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--delete-documents` | No | Also permanently delete documents produced by this connector. |
-| `--no-delete-documents` | No | Send --delete-documents as false. |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--display-name <value>` | No | New tag display name. |
+| `--field-type <value>` | No | New value type for the tag. Accepted values: `text`, `number`, `date`, `boolean`. |
 
 </CommandTable>
 
-## Get knowledge connector
+API request and response schemas: [updateKnowledgeTag](/api-reference/knowledge-bases/updateKnowledgeTag).
+
+### Show how many documents and chunks carry each tag
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge connectors get <knowledgeBaseId> <connectorId>
+sim knowledge tags usage <knowledgeBaseId>
 ```
 
-Get Knowledge Connector (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Knowledge base that owns the connector. |
-| `connectorId` | Yes | Connector selected for the operation. |
+| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
 
 </CommandTable>
 
-## List knowledge connector documents
+API request and response schemas: [listKnowledgeTagUsage](/api-reference/knowledge-bases/listKnowledgeTagUsage).
+
+### Show which tag slot a create would take for a field type
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge connectors documents list <knowledgeBaseId> <connectorId> [options]
+sim knowledge tags next-slot <knowledgeBaseId> [options]
 ```
 
-List Knowledge Connector Documents (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Knowledge base that owns the connector. |
-| `connectorId` | Yes | Connector selected for the operation. |
+| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
 
 </CommandTable>
 
@@ -739,29 +820,30 @@ List Knowledge Connector Documents (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--include-excluded` | No | Include documents explicitly excluded by a user. |
-| `--no-include-excluded` | No | Send --include-excluded as false. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--field-type <value>` | Yes | Value type stored in the slot; it decides which slots are usable and which filter operators apply. Slot capacity per type: text 7, number 5, date 2, boolean 3. Accepted values: `text`, `number`, `date`, `boolean`. |
 
 </CommandTable>
 
-## Update knowledge connector documents
+API request and response schemas: [getNextKnowledgeTagSlot](/api-reference/knowledge-bases/getNextKnowledgeTagSlot).
+
+### Delete tag
+
+OAuth login or personal API key required.
+
+This deletes the tag and clears its values on every document and chunk.
 
 ```bash
-sim knowledge connectors documents update <knowledgeBaseId> <connectorId> [options]
+sim knowledge tags delete <knowledgeBaseId> <tagId> [options]
 ```
 
-Update Knowledge Connector Documents (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Knowledge base that owns the connector. |
-| `connectorId` | Yes | Connector selected for the operation. |
+| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
+| `tagId` | Yes | Unique tag definition identifier. |
 
 </CommandTable>
 
@@ -771,19 +853,22 @@ Update Knowledge Connector Documents (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--operation <value>` | Yes | Whether to restore or exclude the selected documents. Accepted values: `restore`, `exclude`. |
-| `--document <value...>` | Yes | Connector document identifiers to update. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## List knowledge connectors
+API request and response schemas: [deleteKnowledgeTag](/api-reference/knowledge-bases/deleteKnowledgeTag).
+
+### Remove tag definitions no document still uses
+
+OAuth login or personal API key required.
+
+This deletes every tag definition no document still uses. Their slots become free for a different field.
 
 ```bash
-sim knowledge connectors list <knowledgeBaseId> [options]
+sim knowledge tags cleanup <knowledgeBaseId> [options]
 ```
 
-List Knowledge Connectors (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -800,28 +885,31 @@ List Knowledge Connectors (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `connectorType`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--unused` | No | Whether to remove only the tag definitions no document in the knowledge base still carries a value for. Defaults to true. Pass --no-unused to delete every definition on the knowledge base, which also clears its slot on every document and chunk and is not recoverable. |
+| `--no-unused` | No | Send --unused as false. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Queue a knowledge connector synchronization
+API request and response schemas: [deleteKnowledgeTagDefinitions](/api-reference/knowledge-bases/deleteKnowledgeTagDefinitions).
+
+## Connectors
+
+### List knowledge connectors
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge connectors sync <knowledgeBaseId> <connectorId> [options]
+sim knowledge connectors list <knowledgeBaseId> [options]
 ```
 
-Queue a knowledge connector synchronization (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Knowledge base that owns the connector. |
-| `connectorId` | Yes | Connector selected for the operation. |
+| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
 
 </CommandTable>
 
@@ -831,19 +919,22 @@ Queue a knowledge connector synchronization (OAuth login or personal API key req
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--rehydrate` | No | Re-fetch and re-index every existing connector document. |
-| `--no-rehydrate` | No | Send --rehydrate as false. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `connectorType`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Update knowledge connector
+API request and response schemas: [listKnowledgeConnectors](/api-reference/knowledge-bases/listKnowledgeConnectors).
+
+### Get knowledge connector
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge connectors update <knowledgeBaseId> <connectorId> [options]
+sim knowledge connectors get <knowledgeBaseId> <connectorId>
 ```
 
-Update Knowledge Connector (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -855,22 +946,14 @@ Update Knowledge Connector (OAuth login or personal API key required)
 
 </CommandTable>
 
-**Options**
-
-<CommandTable>
-
-| Option | Required | Description |
-| --- | --- | --- |
-| `--source-config <json\|@file>` | No | Replacement source selection and filtering configuration. Updating a runnable connector queues synchronization; paused connectors remain paused. (JSON, or @path / @- to read a file or stdin). |
-| `--sync-interval-minutes <value>` | No | New scheduled synchronization interval in minutes. |
-| `--status <value>` | No | New connector state. Accepted values: `active`, `paused`. |
+API request and response schemas: [getKnowledgeConnector](/api-reference/knowledge-bases/getKnowledgeConnector).
 
-</CommandTable>
+### Create knowledge connector
 
-## Create a knowledge folder at a path
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge folders create <path>
+sim knowledge connectors create <knowledgeBaseId> [options]
 ```
 
 **Arguments**
@@ -879,14 +962,32 @@ sim knowledge folders create <path>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--connector-type <value>` | Yes | Registered connector type. |
+| `--credential-id <value>` | No | OAuth credential identifier for connector types whose `auth.mode` is `oauth` (see connector types); omit it for `apiKey` connectors. |
+| `--api-key <value>` | No | Write-only API key for connector types whose `auth.mode` is `apiKey` (see connector types), or a personal access token for an OAuth connector that also accepts one, such as GitHub. Send it instead of `credentialId`. Pass a raw key, or a secret reference written as the whole value `{{SECRET_NAME}}`, which the server resolves; `$SECRET_NAME` is not a reference. |
+| `--source-config <json\|@file>` | Yes | Connector-specific source selection and filtering configuration. (JSON, or @path / @- to read a file or stdin). |
+| `--sync-interval-minutes <value>` | No | Scheduled synchronization interval in minutes; zero disables scheduling. Defaults to 1440. |
 
 </CommandTable>
 
-## Delete folder
+API request and response schemas: [createKnowledgeConnector](/api-reference/knowledge-bases/createKnowledgeConnector).
+
+### Update knowledge connector
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge folders delete <path> [options]
+sim knowledge connectors update <knowledgeBaseId> <connectorId> [options]
 ```
 
 **Arguments**
@@ -895,7 +996,8 @@ sim knowledge folders delete <path> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `knowledgeBaseId` | Yes | Knowledge base that owns the connector. |
+| `connectorId` | Yes | Connector selected for the operation. |
 
 </CommandTable>
 
@@ -905,18 +1007,32 @@ sim knowledge folders delete <path> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--recursive` | No | Delete the folder and its descendants. |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--source-config <json\|@file>` | No | Replacement source selection and filtering configuration. Updating a runnable connector queues synchronization; paused connectors remain paused. (JSON, or @path / @- to read a file or stdin). |
+| `--sync-interval-minutes <value>` | No | New scheduled synchronization interval in minutes. |
+| `--status <value>` | No | New connector state. Accepted values: `active`, `paused`. |
 
 </CommandTable>
 
-## List knowledge folders
+API request and response schemas: [updateKnowledgeConnector](/api-reference/knowledge-bases/updateKnowledgeConnector).
+
+### Queue a knowledge connector synchronization
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge folders list [options]
+sim knowledge connectors sync <knowledgeBaseId> <connectorId> [options]
 ```
 
-Also available as `sim knowledge folders ls`.
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `knowledgeBaseId` | Yes | Knowledge base that owns the connector. |
+| `connectorId` | Yes | Connector selected for the operation. |
+
+</CommandTable>
 
 **Options**
 
@@ -924,36 +1040,53 @@ Also available as `sim knowledge folders ls`.
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--parent <value>` | No | Direct parent folder path. |
-| `--search <value>` | No | Case-insensitive substring match against the folder name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--rehydrate` | No | Re-fetch and re-index every existing connector document. Defaults to false. |
+| `--no-rehydrate` | No | Send --rehydrate as false. |
 
 </CommandTable>
 
-## Rename or move a knowledge folder
+API request and response schemas: [syncKnowledgeConnector](/api-reference/knowledge-bases/syncKnowledgeConnector).
+
+### List knowledge connector documents
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge folders move <path> <destination>
+sim knowledge connectors documents list <knowledgeBaseId> <connectorId> [options]
 ```
 
-Also available as `sim knowledge folders mv`.
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
-| `destination` | Yes | Folder path as shown in the app; the leading / is optional |
+| `knowledgeBaseId` | Yes | Knowledge base that owns the connector. |
+| `connectorId` | Yes | Connector selected for the operation. |
 
 </CommandTable>
 
-## Delete knowledge base
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--include-excluded` | No | Include documents explicitly excluded by a user. |
+| `--no-include-excluded` | No | Send --include-excluded as false. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+
+</CommandTable>
+
+API request and response schemas: [listKnowledgeConnectorDocuments](/api-reference/knowledge-bases/listKnowledgeConnectorDocuments).
+
+### Update knowledge connector documents
+
+OAuth login or personal API key required.
 
 ```bash
-sim knowledge delete <knowledgeBaseId> [options]
+sim knowledge connectors documents update <knowledgeBaseId> <connectorId> [options]
 ```
 
 **Arguments**
@@ -962,7 +1095,8 @@ sim knowledge delete <knowledgeBaseId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
+| `knowledgeBaseId` | Yes | Knowledge base that owns the connector. |
+| `connectorId` | Yes | Connector selected for the operation. |
 
 </CommandTable>
 
@@ -972,14 +1106,21 @@ sim knowledge delete <knowledgeBaseId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--operation <value>` | Yes | Whether to restore or exclude the selected documents. Accepted values: `restore`, `exclude`. |
+| `--document <value...>` | Yes | Connector document identifiers to update. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 
 </CommandTable>
 
-## Get knowledge base
+API request and response schemas: [updateKnowledgeConnectorDocuments](/api-reference/knowledge-bases/updateKnowledgeConnectorDocuments).
+
+### Delete knowledge connector
+
+OAuth login or personal API key required.
+
+This deletes the connector; --delete-documents also deletes its synchronized documents.
 
 ```bash
-sim knowledge get <knowledgeBaseId>
+sim knowledge connectors delete <knowledgeBaseId> <connectorId> [options]
 ```
 
 **Arguments**
@@ -988,35 +1129,31 @@ sim knowledge get <knowledgeBaseId>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
+| `knowledgeBaseId` | Yes | Knowledge base that owns the connector. |
+| `connectorId` | Yes | Connector selected for the operation. |
 
 </CommandTable>
 
-## List knowledge bases
-
-```bash
-sim knowledge list [options]
-```
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--scope <value>` | No | Lifecycle scope: active or archived knowledge bases. Use Restore Knowledge Base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches. Accepted values: `active`, `archived`. |
-| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
-| `--search <value>` | No | Case-insensitive substring match against the resource name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--delete-documents` | No | Also permanently delete documents produced by this connector. |
+| `--no-delete-documents` | No | Send --delete-documents as false. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Restore an archived knowledge base
+API request and response schemas: [deleteKnowledgeConnector](/api-reference/knowledge-bases/deleteKnowledgeConnector).
+
+## Folders
+
+### List knowledge resources and child folders together
 
 ```bash
-sim knowledge restore <knowledgeBaseId>
+sim knowledge ls [path] [options]
 ```
 
 **Arguments**
@@ -1025,49 +1162,30 @@ sim knowledge restore <knowledgeBaseId>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
+| `path` | No | Folder path to list; defaults to the root folder |
 
 </CommandTable>
 
-## Search knowledge
-
-```bash
-sim knowledge search [options]
-```
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--kb <value...>` | Yes | Knowledge base ID (repeatable) (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--query <value>` | No | Text to search for. |
-| `--top-k <value>` | No | Maximum number of search results to return. Must be a whole number between 1 and 100. |
-| `--tag-filters <json\|@file>` | No | Tag filters as [&#123;"tagName":"...","operator":"...","value":"..."&#125;] (JSON, or @path / @- to read a file or stdin). |
-| `--search-mode <value>` | No | Search algorithm. Accepted values: `vector`, `hybrid`. |
-| `--reranker-enabled` | No | Re-order retrieved chunks with a reranking model before truncating to `topK`. Ignored for a tag-only search, and billed as an additional search unit. Reranking is best-effort — a provider failure falls back to vector ordering, so check `rerankerStatus` on the response. |
-| `--no-reranker-enabled` | No | Send --reranker-enabled as false. |
-| `--reranker-model <value>` | No | Reranking model to use when `rerankerEnabled` is true. Defaults to `rerank-v4.0-fast`. Accepted values: `rerank-v4.0-pro`, `rerank-v4.0-fast`, `rerank-v3.5`. |
-| `--reranker-input-count <value>` | No | How many candidate chunks to retrieve before reranking. Defaults to four times `topK`, capped at 100. A larger pool costs more retrieval work but gives the reranker more to choose from. |
+| `--search <text>` | No | Filter folders and resources by name. |
+| `--limit <n>` | No | Maximum combined items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Update knowledge base
+API request and response schemas: [listKnowledgeBases](/api-reference/knowledge-bases/listKnowledgeBases), [listKnowledgeFolders](/api-reference/knowledge-bases/listKnowledgeFolders).
+
+### List knowledge folders
 
 ```bash
-sim knowledge update <knowledgeBaseId> [options]
+sim knowledge folders list [options]
 ```
 
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
-
-</CommandTable>
+Also available as `sim knowledge folders ls`.
 
 **Options**
 
@@ -1075,17 +1193,19 @@ sim knowledge update <knowledgeBaseId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | New knowledge base name. |
-| `--description <value>` | No | New knowledge base description. |
-| `--chunking-config <json\|@file>` | No | New document chunking configuration. (JSON, or @path / @- to read a file or stdin). |
-| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
+| `--parent <value>` | No | Direct parent folder path. |
+| `--search <value>` | No | Case-insensitive substring match against the folder name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
-## Move a knowledge base to a folder
+API request and response schemas: [listKnowledgeFolders](/api-reference/knowledge-bases/listKnowledgeFolders).
+
+### Create a knowledge folder at a path
 
 ```bash
-sim knowledge mv <knowledgeBaseId> <folder>
+sim knowledge folders create <path>
 ```
 
 **Arguments**
@@ -1094,15 +1214,18 @@ sim knowledge mv <knowledgeBaseId> <folder>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Unique knowledge base identifier. |
-| `folder` | Yes | Folder path as shown in the app; the leading / is optional |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-## Export a knowledge base as a .simkb.zip bundle
+API request and response schemas: [createKnowledgeFolder](/api-reference/knowledge-bases/createKnowledgeFolder).
+
+### Delete folder
+
+This archives the knowledge folder and, when recursive, everything inside it.
 
 ```bash
-sim knowledge export <knowledgeBaseId> [options]
+sim knowledge folders delete <path> [options]
 ```
 
 **Arguments**
@@ -1111,7 +1234,7 @@ sim knowledge export <knowledgeBaseId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `knowledgeBaseId` | Yes | Knowledge base to export |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
@@ -1121,40 +1244,35 @@ sim knowledge export <knowledgeBaseId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-o, --output-file <path>` | No | Write the bundle to this path instead of the name the server suggests; pass - to stream it to stdout. |
-| `--force` | No | Overwrite --output-file if it already exists. |
-| `--no-vectors` | No | Leave chunk vectors out of the bundle, so an import re-embeds every chunk. |
+| `--recursive` | No | Archive the folder and its descendants. Defaults to "false". |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## List knowledge resources and child folders together
+API request and response schemas: [deleteKnowledgeFolder](/api-reference/knowledge-bases/deleteKnowledgeFolder).
+
+### Rename or move a knowledge folder
 
 ```bash
-sim knowledge ls [path] [options]
+sim knowledge folders move <path> <destination>
 ```
 
+Also available as `sim knowledge folders mv`.
+
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | No | Folder path to list; defaults to the root folder |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `destination` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-**Options**
-
-<CommandTable>
-
-| Option | Required | Description |
-| --- | --- | --- |
-| `--search <text>` | No | Filter folders and resources by name. |
-| `--limit <n>` | No | Maximum combined items to return (0 for everything). Defaults to `0`. |
-
-</CommandTable>
+API request and response schemas: [relocateKnowledgeFolder](/api-reference/knowledge-bases/relocateKnowledgeFolder).
 
-## Create a knowledge directory at a path
+### Create a knowledge directory at a path
 
 ```bash
 sim knowledge mkdir <path>
@@ -1169,3 +1287,11 @@ sim knowledge mkdir <path>
 | `path` | Yes | Folder path to create; the leading / is optional |
 
 </CommandTable>
+
+API request and response schemas: [createKnowledgeFolder](/api-reference/knowledge-bases/createKnowledgeFolder).
+
+## Related docs
+
+- [Knowledge Base](/knowledgebase)
+- [Tags and filters](/knowledgebase/tags)
+- [Export and import](/knowledgebase/export-import)
diff --git a/apps/docs/content/docs/cli/logs.mdx b/apps/docs/content/docs/cli/logs.mdx
index 159e4a4909c..5ae8626c80d 100644
--- a/apps/docs/content/docs/cli/logs.mdx
+++ b/apps/docs/content/docs/cli/logs.mdx
@@ -1,13 +1,57 @@
 ---
 title: Logs
-description: Manage logs — every subcommand, argument, and flag
+description: Read run diagnostics, follow new runs, and summarize failures and latency.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Read run diagnostics, follow new runs, and summarize failures and latency.
+
 `sim logs` is also spelled `sim log`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
+
+## List run logs, such as failed or errored runs, by workflow, trigger or time
+
+```bash
+sim logs list [options]
+```
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--workflow <value...>` | No | Comma-separated workflow identifiers to include. An empty entry is rejected. At most 200 entries. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--trigger <value...>` | No | Comma-separated, lowercase trigger types or webhook provider IDs. Matching is exact and case-sensitive; unknown values select no runs. An empty entry is rejected. The sentinel `all` disables this filter, even when listed with other values. At most 100 entries. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--level <value>` | No | Severity level to include. Accepted values: `info`, `error`. |
+| `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
+| `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
+| `--min-duration-ms <value>` | No | Minimum total execution duration in milliseconds. Whole milliseconds from 0 to 2147483647; the stored duration is a 32-bit integer, so a fractional or out-of-range bound is rejected. |
+| `--max-duration-ms <value>` | No | Maximum total execution duration in milliseconds. Whole milliseconds from 0 to 2147483647; the stored duration is a 32-bit integer, so a fractional or out-of-range bound is rejected. |
+| `--min-cost <value>` | No | Minimum execution cost in USD, from 0 to 1000000. A run is never charged a negative amount, so a negative bound is rejected rather than treated as a filter that matches every run. |
+| `--max-cost <value>` | No | Maximum execution cost in USD, from 0 to 1000000. A run is never charged a negative amount, so a negative bound is rejected rather than treated as a filter that matches every run. |
+| `--model <value>` | No | AI model used during execution. |
+| `--details <value>` | No | Response detail level; full is requested by default to name each run’s workflow. Accepted values: `basic`, `full`. |
+| `--include-trace-spans` | No | Include trace spans in JSON or YAML output (implies full detail). |
+| `--include-final-output` | No | Include final output in JSON or YAML output (implies full detail). |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--include-handled-errors` | No | Whether `level=error` also selects runs that finished at `info` after a block error was recovered by an error path. Off by default: such a run succeeded, so it is an error only to a caller auditing error handling. Every row reports `hasHandledErrors` whether or not this is set. Job runs carry no block trace, so the flag never widens that branch. |
+| `--no-include-handled-errors` | No | Send --include-handled-errors as false. |
+| `--status <value>` | No | Comma-separated execution statuses to include, from `pending` \| `running` \| `paused` \| `redacting` \| `completed` \| `failed` \| `cancelled`. An empty entry is rejected. ANDed with `level`, which reports severity rather than lifecycle. |
+| `--workflow-name <value>` | No | Case-insensitive substring match against the run's workflow name. Runs whose workflow has been deleted match nothing, because the name is no longer joinable. |
+| `--include-job-runs` | No | Include Chat and Sim-agent jobs alongside workflow runs. Jobs use `kind: "job"` and have no workflow or cost ledger. Workflow, folder, model, or status filters exclude jobs. This option is valid only when sorting by `startedAt`. |
+| `--no-include-job-runs` | No | Send --include-job-runs as false. |
+| `--run-id <value>` | No | Exact run identifier to match. |
+| `--sort-by <value>` | No | Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs sort before recorded values in ascending order and after them in descending order. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected when job runs are included. Defaults to "startedAt". Accepted values: `startedAt`, `durationMs`, `cost`, `status`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
+| `--folder <value...>` | No | Folder path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+
+</CommandTable>
+
+API request and response schemas: [listLogs](/api-reference/logs/listLogs).
 
 ## Show run diagnostics
 
@@ -37,6 +81,8 @@ sim logs get <runId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getLog](/api-reference/logs/getLog).
+
 ## Summarize run counts, failures and latency over a window
 
 ```bash
@@ -57,50 +103,12 @@ sim logs stats [options]
 | `--no-include-handled-errors` | No | Send --include-handled-errors as false. |
 | `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
 | `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
-| `--segment-count <value>` | No | Number of equal time buckets to divide the window into, from 1 to 500. It is the ceiling on how many buckets a series carries: with `includeEmpty=true` exactly this many are returned, otherwise only the buckets holding at least one run. Buckets are never narrower than one minute, so on a short window the series extends past the end of the window rather than being compressed, and the trailing buckets are empty. |
+| `--segment-count <value>` | No | Number of equal time buckets to divide the window into, from 1 to 500. It is the ceiling on how many buckets a series carries: with `includeEmpty=true` exactly this many are returned, otherwise only the buckets holding at least one run. Buckets are never narrower than one minute, so on a short window the series extends past the end of the window rather than being compressed, and the trailing buckets are empty. Defaults to 72. |
 | `--include-empty <value>` | No | Whether buckets with no runs are included in every series. Off by default, so each series carries only the buckets that hold at least one run; set it to publish exactly `segmentCount` buckets per series, empty ones included. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected. Accepted values: `true`, `1`, `yes`, `on`, `y`, `enabled`, `false`, `0`, `no`, `off`, `n`, `disabled`. |
 
 </CommandTable>
 
-## List run logs, such as failed or errored runs, by workflow, trigger or time
-
-```bash
-sim logs list [options]
-```
-
-**Options**
-
-<CommandTable>
-
-| Option | Required | Description |
-| --- | --- | --- |
-| `--workflow <value...>` | No | Comma-separated workflow identifiers to include. An empty entry is rejected. At most 200 entries. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--trigger <value...>` | No | Comma-separated, lowercase trigger types or webhook provider IDs. Matching is exact and case-sensitive; unknown values select no runs. An empty entry is rejected. The sentinel `all` disables this filter, even when listed with other values. At most 100 entries. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--level <value>` | No | Severity level to include. Accepted values: `info`, `error`. |
-| `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
-| `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
-| `--min-duration-ms <value>` | No | Minimum total execution duration in milliseconds. Whole milliseconds from 0 to 2147483647; the stored duration is a 32-bit integer, so a fractional or out-of-range bound is rejected. |
-| `--max-duration-ms <value>` | No | Maximum total execution duration in milliseconds. Whole milliseconds from 0 to 2147483647; the stored duration is a 32-bit integer, so a fractional or out-of-range bound is rejected. |
-| `--min-cost <value>` | No | Minimum execution cost in USD, from 0 to 1000000. A run is never charged a negative amount, so a negative bound is rejected rather than treated as a filter that matches every run. |
-| `--max-cost <value>` | No | Maximum execution cost in USD, from 0 to 1000000. A run is never charged a negative amount, so a negative bound is rejected rather than treated as a filter that matches every run. |
-| `--model <value>` | No | AI model used during execution. |
-| `--details <value>` | No | Response detail level; full is requested by default to name each run’s workflow. Accepted values: `basic`, `full`. |
-| `--include-trace-spans` | No | Include trace spans in JSON or YAML output (implies full detail). |
-| `--include-final-output` | No | Include final output in JSON or YAML output (implies full detail). |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--include-handled-errors` | No | Whether `level=error` also selects runs that finished at `info` after a block error was recovered by an error path. Off by default: such a run succeeded, so it is an error only to a caller auditing error handling. Every row reports `hasHandledErrors` whether or not this is set. Job runs carry no block trace, so the flag never widens that branch. |
-| `--no-include-handled-errors` | No | Send --include-handled-errors as false. |
-| `--status <value>` | No | Comma-separated execution statuses to include, from `pending` \| `running` \| `paused` \| `redacting` \| `completed` \| `failed` \| `cancelled`. An empty entry is rejected. ANDed with `level`, which reports severity rather than lifecycle. |
-| `--workflow-name <value>` | No | Case-insensitive substring match against the run's workflow name. Runs whose workflow has been deleted match nothing, because the name is no longer joinable. |
-| `--include-job-runs` | No | Include Chat and Sim-agent jobs alongside workflow runs. Jobs use `kind: "job"` and have no workflow or cost ledger. Workflow, folder, model, or status filters exclude jobs. This option is valid only when sorting by `startedAt`. |
-| `--no-include-job-runs` | No | Send --include-job-runs as false. |
-| `--run-id <value>` | No | Exact run identifier to match. |
-| `--sort-by <value>` | No | Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs sort before recorded values in ascending order and after them in descending order. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected when job runs are included. Accepted values: `startedAt`, `durationMs`, `cost`, `status`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--folder <value...>` | No | Folder path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-
-</CommandTable>
+API request and response schemas: [getLogStats](/api-reference/logs/getLogStats).
 
 ## Watch runs live as they arrive, printing each new run once
 
@@ -123,3 +131,20 @@ sim logs follow [options]
 | `--interval <seconds>` | No | Seconds between polls. Defaults to `3`. |
 
 </CommandTable>
+
+Each run prints once, when it is first seen, so its status is the status it had at that moment. With --output json every run is a JSON object on its own line (JSONL) rather than a member of an array, because a follow never ends and so can never close one; --output yaml emits a --- separated document stream. Progress and retries go to stderr, leaving stdout a clean stream of rows. Ctrl-C stops the follow.
+
+**Examples**
+
+```bash
+sim logs follow --level error
+sim logs follow --workflow 00000000-0000-4000-8000-000000000000 -n 0
+sim --output json logs follow | jq -r '.runId'
+```
+
+API request and response schemas: [listLogs](/api-reference/logs/listLogs).
+
+## Related docs
+
+- [Logs and debugging](/logs-debugging)
+- [Output formats](/cli/output)
diff --git a/apps/docs/content/docs/cli/mcp-servers.mdx b/apps/docs/content/docs/cli/mcp-servers.mdx
index bb9559b297b..60b6c97c803 100644
--- a/apps/docs/content/docs/cli/mcp-servers.mdx
+++ b/apps/docs/content/docs/cli/mcp-servers.mdx
@@ -1,18 +1,24 @@
 ---
-title: MCP Servers
-description: Manage mcp servers — every subcommand, argument, and flag
+title: MCP servers
+description: Connect external Model Context Protocol (MCP) servers so workflows can use their tools.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Connect external Model Context Protocol (MCP) servers so workflows can use their tools.
+
+To serve Sim workflows to MCP clients instead, use [workflow MCP servers](/cli/workflow-mcp-servers).
+
 `sim mcp-servers` is also spelled `sim mcp-server`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
+
+## Server connections
 
-## Create MCP server
+### List MCP servers
 
 ```bash
-sim mcp-servers create [options]
+sim mcp-servers list [options]
 ```
 
 **Options**
@@ -21,25 +27,19 @@ sim mcp-servers create [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | Yes | Server display name. |
-| `--description <value>` | No | Optional server description. |
-| `--transport <value>` | No | Transport protocol. Defaults to `streamable-http` on creation. Accepted values: `streamable-http`. |
-| `--url <value>` | Yes | Absolute HTTP or HTTPS endpoint URL without `&#123;&#123;ENV_VAR&#125;&#125;` references. It determines server identity and is immutable: delete and recreate the server to change endpoints. |
-| `--auth-type <value>` | No | Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server does not advertise OAuth. A server publishing RFC 9728 metadata is therefore stored as `oauth`, and headers configured afterwards will not authenticate — send this field explicitly to pin the method. Accepted values: `none`, `headers`, `oauth`. |
-| `--headers <json\|@file>` | No | Write-only request headers sent to the server. Replaced wholesale rather than merged on update: sending this field drops every stored header it does not repeat. (JSON, or @path / @- to read a file or stdin). |
-| `--timeout <value>` | No | Per-request timeout in milliseconds. Defaults to 30000 on creation. |
-| `--retries <value>` | No | Number of retries per request. Defaults to 3 on creation. |
-| `--enabled` | No | Whether workflows can use the server's tools. Defaults to true on creation. |
-| `--no-enabled` | No | Send --enabled as false. |
-| `--oauth-client-id <value>` | No | Pre-registered OAuth client identifier. Changing it on update revokes the stored OAuth grant and forces reauthorization. |
-| `--oauth-client-secret <value>` | No | Write-only pre-registered OAuth client secret. Sending it on update as null or a new value revokes the stored OAuth grant and forces reauthorization, as does switching away from OAuth authentication. (--oauth-client-secret null sends the word, not JSON null). |
+| `--search <value>` | No | Case-insensitive substring match against the server name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Delete MCP server
+API request and response schemas: [listMcpServers](/api-reference/mcp-servers/listMcpServers).
+
+### Get MCP server
 
 ```bash
-sim mcp-servers delete <mcpServerId> [options]
+sim mcp-servers get <mcpServerId>
 ```
 
 **Arguments**
@@ -52,20 +52,41 @@ sim mcp-servers delete <mcpServerId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getMcpServer](/api-reference/mcp-servers/getMcpServer).
+
+### Create MCP server
+
+```bash
+sim mcp-servers create [options]
+```
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--name <value>` | Yes | Server display name. |
+| `--description <value>` | No | Optional server description. |
+| `--transport <value>` | No | Transport protocol. Defaults to `streamable-http` on creation. Accepted values: `streamable-http`. |
+| `--url <value>` | Yes | Absolute HTTP or HTTPS endpoint URL without `{{ENV_VAR}}` references. It determines server identity and is immutable: delete and recreate the server to change endpoints. |
+| `--auth-type <value>` | No | Authentication method. On creation, omission without `headers` probes once: an OAuth challenge selects `oauth`, an unauthenticated success selects `none`, and other outcomes fall back to `headers`. An OAuth client ID selects `oauth` when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method. Accepted values: `none`, `headers`, `oauth`. |
+| `--headers <json\|@file>` | No | Write-only request headers sent to the server. Replaced wholesale rather than merged on update: sending this field drops every stored header it does not repeat. (JSON, or @path / @- to read a file or stdin). |
+| `--timeout <value>` | No | Per-request timeout in milliseconds. Defaults to 30000 on creation. |
+| `--retries <value>` | No | Number of retries per request. Defaults to 3 on creation. |
+| `--enabled` | No | Whether workflows can use the server's tools. Defaults to true on creation. |
+| `--no-enabled` | No | Send --enabled as false. |
+| `--oauth-client-id <value>` | No | Pre-registered OAuth client identifier. Changing it on update revokes the stored OAuth grant and forces reauthorization. |
+| `--oauth-client-secret <value>` | No | Write-only pre-registered OAuth client secret. Sending it on update as null or a new value revokes the stored OAuth grant and forces reauthorization, as does switching away from OAuth authentication. (--oauth-client-secret null sends the word, not JSON null). |
 
 </CommandTable>
 
-## Get MCP server
+API request and response schemas: [createMcpServer](/api-reference/mcp-servers/createMcpServer).
+
+### Update MCP server
 
 ```bash
-sim mcp-servers get <mcpServerId>
+sim mcp-servers update <mcpServerId> [options]
 ```
 
 **Arguments**
@@ -78,33 +99,39 @@ sim mcp-servers get <mcpServerId>
 
 </CommandTable>
 
-## List MCP servers
-
-```bash
-sim mcp-servers list [options]
-```
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--search <value>` | No | Case-insensitive substring match against the server name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--name <value>` | No | Server display name. |
+| `--description <value>` | No | Optional server description. |
+| `--transport <value>` | No | Transport protocol. Defaults to `streamable-http` on creation. Accepted values: `streamable-http`. |
+| `--url <value>` | No | Immutable server URL. When provided, it must equal the current URL; use delete and create to change endpoints. |
+| `--auth-type <value>` | No | Authentication method. On creation, omission without `headers` probes once: an OAuth challenge selects `oauth`, an unauthenticated success selects `none`, and other outcomes fall back to `headers`. An OAuth client ID selects `oauth` when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method. Accepted values: `none`, `headers`, `oauth`. |
+| `--headers <json\|@file>` | No | Write-only request headers sent to the server. Replaced wholesale rather than merged on update: sending this field drops every stored header it does not repeat. (JSON, or @path / @- to read a file or stdin). |
+| `--timeout <value>` | No | Per-request timeout in milliseconds. Defaults to 30000 on creation. |
+| `--retries <value>` | No | Number of retries per request. Defaults to 3 on creation. |
+| `--enabled` | No | Whether workflows can use the server's tools. Defaults to true on creation. |
+| `--no-enabled` | No | Send --enabled as false. |
+| `--oauth-client-id <value>` | No | Pre-registered OAuth client identifier. Changing it on update revokes the stored OAuth grant and forces reauthorization. |
+| `--oauth-client-secret <value>` | No | Write-only pre-registered OAuth client secret. Sending it on update as null or a new value revokes the stored OAuth grant and forces reauthorization, as does switching away from OAuth authentication. (--oauth-client-secret null sends the word, not JSON null). |
 
 </CommandTable>
 
-## List MCP server tools
+API request and response schemas: [updateMcpServer](/api-reference/mcp-servers/updateMcpServer).
+
+## Tool discovery
+
+### List MCP server tools
+
+OAuth login or personal API key required.
 
 ```bash
 sim mcp-servers tools list <mcpServerId> [options]
 ```
 
-List MCP Server Tools (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -126,10 +153,16 @@ List MCP Server Tools (OAuth login or personal API key required)
 
 </CommandTable>
 
-## Update MCP server
+API request and response schemas: [listMcpServerTools](/api-reference/mcp-servers/listMcpServerTools).
+
+## Remove servers
+
+### Delete MCP server
+
+This removes the MCP server and the tools it provides.
 
 ```bash
-sim mcp-servers update <mcpServerId> [options]
+sim mcp-servers delete <mcpServerId> [options]
 ```
 
 **Arguments**
@@ -148,17 +181,12 @@ sim mcp-servers update <mcpServerId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | Server display name. |
-| `--description <value>` | No | Optional server description. |
-| `--transport <value>` | No | Transport protocol. Defaults to `streamable-http` on creation. Accepted values: `streamable-http`. |
-| `--url <value>` | No | Immutable server URL. When provided, it must equal the current URL; use delete and create to change endpoints. |
-| `--auth-type <value>` | No | Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server does not advertise OAuth. A server publishing RFC 9728 metadata is therefore stored as `oauth`, and headers configured afterwards will not authenticate — send this field explicitly to pin the method. Accepted values: `none`, `headers`, `oauth`. |
-| `--headers <json\|@file>` | No | Write-only request headers sent to the server. Replaced wholesale rather than merged on update: sending this field drops every stored header it does not repeat. (JSON, or @path / @- to read a file or stdin). |
-| `--timeout <value>` | No | Per-request timeout in milliseconds. Defaults to 30000 on creation. |
-| `--retries <value>` | No | Number of retries per request. Defaults to 3 on creation. |
-| `--enabled` | No | Whether workflows can use the server's tools. Defaults to true on creation. |
-| `--no-enabled` | No | Send --enabled as false. |
-| `--oauth-client-id <value>` | No | Pre-registered OAuth client identifier. Changing it on update revokes the stored OAuth grant and forces reauthorization. |
-| `--oauth-client-secret <value>` | No | Write-only pre-registered OAuth client secret. Sending it on update as null or a new value revokes the stored OAuth grant and forces reauthorization, as does switching away from OAuth authentication. (--oauth-client-secret null sends the word, not JSON null). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
+
+API request and response schemas: [deleteMcpServer](/api-reference/mcp-servers/deleteMcpServer).
+
+## Related docs
+
+- [MCP connections](/agents/mcp)
diff --git a/apps/docs/content/docs/cli/meta.mdx b/apps/docs/content/docs/cli/meta.mdx
index 66f7a488b23..ff6113c27e4 100644
--- a/apps/docs/content/docs/cli/meta.mdx
+++ b/apps/docs/content/docs/cli/meta.mdx
@@ -1,14 +1,21 @@
 ---
-title: Meta
-description: Manage meta — every subcommand, argument, and flag
+title: API status
+description: Inspect API availability and the calling credential’s type and expiry.
 ---
 
-import { CommandTable } from '@/components/ui/command-table'
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+Inspect API availability and the calling credential’s type and expiry.
 
-## Show what this API supports and which limits apply
+These commands accept the [global options](/cli/commands#global-options).
+
+## Show API availability and the calling credential’s type and expiry
 
 ```bash
 sim meta status
 ```
+
+API request and response schemas: [getMeta](/api-reference/meta/getApiMeta).
+
+## Related docs
+
+- [Authentication](/cli/authentication)
diff --git a/apps/docs/content/docs/cli/organizations.mdx b/apps/docs/content/docs/cli/organizations.mdx
index 05c47a2d394..d339914d780 100644
--- a/apps/docs/content/docs/cli/organizations.mdx
+++ b/apps/docs/content/docs/cli/organizations.mdx
@@ -1,38 +1,66 @@
 ---
 title: Organizations
-description: Manage organizations — every subcommand, argument, and flag
+description: Manage organization membership, invitations, usage, access requests, and SSO.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+Manage organization membership, invitations, usage, access requests, and SSO.
 
-## Add organization domain
+These commands accept the [global options](/cli/commands#global-options).
+
+## Organizations and workspaces
+
+### List organizations
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations domains add [options]
+sim organizations list [options]
 ```
 
-Add Organization Domain (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--organization <value>` | Yes | Organization identifier. |
-| `--domain <value>` | Yes | Domain to claim and verify through a DNS TXT record. |
+| `--search <value>` | No | Case-insensitive substring match against the organization name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## List organization domains
+API request and response schemas: [listOrganizations](/api-reference/organizations/listOrganizations).
+
+### Get organization
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations domains list [options]
+sim organizations get <organizationId>
 ```
 
-List Organization Domains (OAuth login or personal API key required)
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `organizationId` | Yes | Organization identifier. |
+
+</CommandTable>
+
+API request and response schemas: [getOrganization](/api-reference/organizations/getOrganization).
+
+### List organization workspaces
+
+OAuth login or personal API key required.
+
+```bash
+sim organizations workspaces [options]
+```
 
 **Options**
 
@@ -41,19 +69,48 @@ List Organization Domains (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
+| `--search <value>` | No | Case-insensitive substring match against the workspace name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `id`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `domain`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
-## Remove organization domain
+API request and response schemas: [listOrganizationWorkspaces](/api-reference/organizations/listOrganizationWorkspaces).
+
+## Members and credit limits
+
+### List organization members
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations domains remove <domainId> [options]
+sim organizations members list [options]
 ```
 
-Remove Organization Domain (OAuth login or personal API key required)
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--organization <value>` | Yes | Organization identifier. |
+| `--search <value>` | No | Case-insensitive substring match against member name or email. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `email`, `joinedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+
+</CommandTable>
+
+API request and response schemas: [listOrganizationMembers](/api-reference/organizations/listOrganizationMembers).
+
+### Get organization member credit limit
+
+OAuth login or personal API key required.
+
+```bash
+sim organizations members usage-limit get <userId> [options]
+```
 
 **Arguments**
 
@@ -61,7 +118,7 @@ Remove Organization Domain (OAuth login or personal API key required)
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `domainId` | Yes | Domain claim owned by this organization. |
+| `userId` | Yes | User ID of an organization member or external collaborator with workspace access in this organization. Use List Organization Members or List Workspace Members to find it. |
 
 </CommandTable>
 
@@ -72,25 +129,26 @@ Remove Organization Domain (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Verify organization domain
+API request and response schemas: [getOrganizationMemberUsageLimit](/api-reference/organizations/getOrganizationMemberUsageLimit).
+
+### Update organization member
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations domains verify <domainId> [options]
+sim organizations members update <userId> [options]
 ```
 
-Verify Organization Domain (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `domainId` | Yes | Domain claim owned by this organization. |
+| `userId` | Yes | User identifier of the organization member. |
 
 </CommandTable>
 
@@ -101,24 +159,27 @@ Verify Organization Domain (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
+| `--role <value>` | Yes | New organization role. Ownership transfers use a separate operation. Accepted values: `member`, `admin`. |
 
 </CommandTable>
 
-## Cancel organization access request
+API request and response schemas: [updateOrganizationMember](/api-reference/organizations/updateOrganizationMember).
+
+### Update organization member credit limit
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations access-requests cancel <requestId> [options]
+sim organizations members usage-limit update <userId> [options]
 ```
 
-Cancel Organization Access Request (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `requestId` | Yes | Access request identifier. |
+| `userId` | Yes | User ID of an organization member or external collaborator with workspace access in this organization. Use List Organization Members or List Workspace Members to find it. |
 
 </CommandTable>
 
@@ -129,16 +190,31 @@ Cancel Organization Access Request (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
+| `--credit-limit <number\|null>` | Yes | Credit cap for this person. Send null to clear the cap or 0 to prevent further credit-consuming usage. Organization limits still apply. |
 
 </CommandTable>
 
-## Create organization access request
+API request and response schemas: [updateOrganizationMemberUsageLimit](/api-reference/organizations/updateOrganizationMemberUsageLimit).
+
+### Remove organization member
+
+OAuth login or personal API key required.
+
+This removes the member, revokes their organization workspace access, and ends their sessions.
 
 ```bash
-sim organizations access-requests create [options]
+sim organizations members remove <userId> [options]
 ```
 
-Create Organization Access Request (OAuth login or personal API key required)
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `userId` | Yes | User identifier of the organization member. |
+
+</CommandTable>
 
 **Options**
 
@@ -147,19 +223,22 @@ Create Organization Access Request (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--target <json\|@file>` | Yes | Target returned by Discover Workspace Access Requests or Discover Organization Access Requests. The target must currently be requestable. (JSON, or @path / @- to read a file or stdin). |
-| `--reason <value>` | No | Why the acting user needs this access. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Discover organization access requests
+API request and response schemas: [removeOrganizationMember](/api-reference/organizations/removeOrganizationMember).
+
+## Invitations
+
+### List organization invitations
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations access-requests discover [options]
+sim organizations invitations list [options]
 ```
 
-Discover Organization Access Requests (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -167,42 +246,35 @@ Discover Organization Access Requests (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--search <value>` | No | Case-insensitive substring match against the access item label. |
-| `--target-kind <value>` | No | Category of access to discover. Accepted values: `feature`, `integration`, `provider`, `model`, `tool`, `knowledge_connector`, `file_share_auth`, `chat_deploy_auth`, `usage_limit`. |
-| `--state <value>` | No | Filter by the acting user’s current access. Requestable items can be submitted for review. Accepted values: `allowed`, `requestable`, `unavailable`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `label`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--search <value>` | No | Case-insensitive substring match against the invitee email. |
+| `--status <value>` | No | Filter by current invitation status. Omit to include all statuses. Accepted values: `pending`, `accepted`, `rejected`, `cancelled`, `expired`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `email`, `createdAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
-## Get organization access request settings
+API request and response schemas: [listOrganizationInvitations](/api-reference/organizations/listOrganizationInvitations).
+
+### Get organization invitation
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations access-requests settings get [options]
+sim organizations invitations get <invitationId> [options]
 ```
 
-Get Organization Access Request Settings (OAuth login or personal API key required)
-
-**Options**
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--organization <value>` | Yes | Organization identifier. |
+| `invitationId` | Yes | Invitation identifier. |
 
 </CommandTable>
 
-## Update organization access request settings
-
-```bash
-sim organizations access-requests settings update [options]
-```
-
-Update Organization Access Request Settings (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -210,18 +282,19 @@ Update Organization Access Request Settings (OAuth login or personal API key req
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--allow-requests <true\|false>` | Yes | Allow new requests and approvals. Disabling requests preserves history and still allows cancellation and decline. Accepted values: `true`, `false`. |
 
 </CommandTable>
 
-## List my organization access requests
+API request and response schemas: [getOrganizationInvitation](/api-reference/organizations/getOrganizationInvitation).
+
+### Create organization invitation
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations access-requests mine [options]
+sim organizations invitations create [options]
 ```
 
-List My Organization Access Requests (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -229,21 +302,30 @@ List My Organization Access Requests (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--status <value>` | No | Filter by request status; omit to include all statuses. Accepted values: `pending`, `fulfilled`, `declined`, `cancelled`, `closed`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `createdAt`, `targetLabel`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--email <value>` | Yes | Email address of the person to invite. |
+| `--role <value>` | No | Organization role to offer. Defaults to member; grants no workspace-specific permissions. Accepted values: `member`, `admin`. |
 
 </CommandTable>
 
-## List organization access requests
+API request and response schemas: [createOrganizationInvitation](/api-reference/organizations/createOrganizationInvitation).
+
+### Resend organization invitation
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations access-requests list [options]
+sim organizations invitations resend <invitationId> [options]
 ```
 
-List Organization Access Requests (OAuth login or personal API key required)
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `invitationId` | Yes | Invitation identifier. |
+
+</CommandTable>
 
 **Options**
 
@@ -252,30 +334,28 @@ List Organization Access Requests (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--status <value>` | No | Filter by request status; omit to include all statuses. Accepted values: `pending`, `fulfilled`, `declined`, `cancelled`, `closed`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `createdAt`, `targetLabel`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--search <value>` | No | Case-insensitive substring match against the target label or requester name or email. |
 
 </CommandTable>
 
-## Preview organization access request
+API request and response schemas: [resendOrganizationInvitation](/api-reference/organizations/resendOrganizationInvitation).
+
+### Revoke organization invitation
+
+OAuth login or personal API key required.
+
+This cancels the invitation and all its workspace grants, preventing acceptance.
 
 ```bash
-sim organizations access-requests preview <requestId> [options]
+sim organizations invitations revoke <invitationId> [options]
 ```
 
-Preview Organization Access Request (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `requestId` | Yes | Access request identifier. |
+| `invitationId` | Yes | Invitation identifier. |
 
 </CommandTable>
 
@@ -286,24 +366,27 @@ Preview Organization Access Request (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Resolve organization access request
+API request and response schemas: [revokeOrganizationInvitation](/api-reference/organizations/revokeOrganizationInvitation).
+
+### List organization invitation workspaces
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations access-requests resolve <requestId> [options]
+sim organizations invitations workspaces <invitationId> [options]
 ```
 
-Resolve Organization Access Request (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `requestId` | Yes | Access request identifier. |
+| `invitationId` | Yes | Invitation identifier. |
 
 </CommandTable>
 
@@ -314,21 +397,26 @@ Resolve Organization Access Request (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--action <value>` | Yes | apply: Apply the reviewed change to the governing group or member credit cap. decline: Decline the request without changing permissions or credit limits. Accepted values: `apply`, `decline`. |
-| `--expected-fingerprint <value>` | No | Fingerprint from Preview Organization Access Request. Review its changes and impact before applying; a stale preview returns a conflict. Available when action is apply. Required when action is apply. |
-| `--new-limit-credits <value>` | No | Required only for a usage-limit request: a whole-number credit cap greater than the current cap. Omit for permission requests. Available when action is apply. |
-| `--reason <value>` | No | Required explanation for declining this request. Available when action is decline. Required when action is decline. |
+| `--search <value>` | No | Case-insensitive substring match against the workspace name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `id`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
-## Create organization invitation
+API request and response schemas: [listOrganizationInvitationWorkspaces](/api-reference/organizations/listOrganizationInvitationWorkspaces).
+
+## Usage
+
+### Get organization usage summary
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations invitations create [options]
+sim organizations usage summary [options]
 ```
 
-Create Organization Invitation (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -336,29 +424,49 @@ Create Organization Invitation (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--email <value>` | Yes | Email address of the person to invite. |
-| `--role <value>` | No | Organization role to offer. Defaults to member; grants no workspace-specific permissions. Accepted values: `member`, `admin`. |
+| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Defaults to "30d". Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
+| `--start-date <value>` | No | First calendar date included, in the selected timezone. Requires preset=custom. |
+| `--end-date <value>` | No | Last calendar date included, in the selected timezone. Requires preset=custom. |
+| `--timezone <value>` | No | IANA timezone for calendar boundaries; defaults to UTC. |
 
 </CommandTable>
 
-## Get organization invitation
+API request and response schemas: [getOrganizationUsageSummary](/api-reference/organizations/getOrganizationUsageSummary).
+
+### Get organization usage breakdown
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations invitations get <invitationId> [options]
+sim organizations usage breakdown [options]
 ```
 
-Get Organization Invitation (OAuth login or personal API key required)
-
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `invitationId` | Yes | Invitation identifier. |
+| `--organization <value>` | Yes | Organization identifier. |
+| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Defaults to "30d". Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
+| `--start-date <value>` | No | First calendar date included, in the selected timezone. Requires preset=custom. |
+| `--end-date <value>` | No | Last calendar date included, in the selected timezone. Requires preset=custom. |
+| `--timezone <value>` | No | IANA timezone for calendar boundaries; defaults to UTC. |
+| `--dimension <value>` | Yes | Usage grouping dimension. Accepted values: `member`, `workspace`, `workflow`, `model`, `byok`, `source`. |
+| `--limit <value>` | No | Maximum ranked groups to return. Remaining usage is summarized in other. Must be a whole number from 1 to 100. Defaults to 50. |
 
 </CommandTable>
 
+API request and response schemas: [getOrganizationUsageBreakdown](/api-reference/organizations/getOrganizationUsageBreakdown).
+
+### List organization usage events
+
+OAuth login or personal API key required.
+
+```bash
+sim organizations usage events [options]
+```
+
 **Options**
 
 <CommandTable>
@@ -366,17 +474,30 @@ Get Organization Invitation (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
+| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Defaults to "30d". Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
+| `--start-date <value>` | No | First calendar date included, in the selected timezone. Requires preset=custom. |
+| `--end-date <value>` | No | Last calendar date included, in the selected timezone. Requires preset=custom. |
+| `--timezone <value>` | No | IANA timezone for calendar boundaries; defaults to UTC. |
+| `--source <value>` | No | Restrict events to one product surface. Accepted values: `workflow`, `wand`, `sim-chat`, `mcp_copilot`, `mothership_block`, `knowledge-base`, `voice-input`, `enrichment`, `voice-output`, `api-tool`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `createdAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
-## List organization invitations
+API request and response schemas: [listOrganizationUsageEvents](/api-reference/organizations/listOrganizationUsageEvents).
+
+## Access requests
+
+### Discover organization access requests
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations invitations list [options]
+sim organizations access-requests discover [options]
 ```
 
-List Organization Invitations (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -384,33 +505,48 @@ List Organization Invitations (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--search <value>` | No | Case-insensitive substring match against the invitee email. |
-| `--status <value>` | No | Filter by current invitation status. Omit to include all statuses. Accepted values: `pending`, `accepted`, `rejected`, `cancelled`, `expired`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `email`, `createdAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--search <value>` | No | Case-insensitive substring match against the access item label. |
+| `--target-kind <value>` | No | Category of access to discover. Accepted values: `feature`, `integration`, `provider`, `model`, `tool`, `knowledge_connector`, `file_share_auth`, `chat_deploy_auth`, `usage_limit`. |
+| `--state <value>` | No | Filter by the acting user’s current access. Requestable items can be submitted for review. Accepted values: `allowed`, `requestable`, `unavailable`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "label". Accepted values: `label`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
-## List organization invitation workspaces
+API request and response schemas: [discoverOrganizationAccessRequests](/api-reference/access-requests/discoverOrganizationAccessRequests).
+
+### Create organization access request
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations invitations workspaces <invitationId> [options]
+sim organizations access-requests create [options]
 ```
 
-List Organization Invitation Workspaces (OAuth login or personal API key required)
-
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `invitationId` | Yes | Invitation identifier. |
+| `--organization <value>` | Yes | Organization identifier. |
+| `--target <json\|@file>` | Yes | Target returned by Discover Workspace Access Requests or Discover Organization Access Requests. The target must currently be requestable. (JSON, or @path / @- to read a file or stdin). |
+| `--reason <value>` | No | Why the acting user needs this access. Defaults to "". |
 
 </CommandTable>
 
+API request and response schemas: [createOrganizationAccessRequest](/api-reference/access-requests/createOrganizationAccessRequest).
+
+### List my organization access requests
+
+OAuth login or personal API key required.
+
+```bash
+sim organizations access-requests mine [options]
+```
+
 **Options**
 
 <CommandTable>
@@ -418,29 +554,31 @@ List Organization Invitation Workspaces (OAuth login or personal API key require
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--search <value>` | No | Case-insensitive substring match against the workspace name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `id`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--status <value>` | No | Filter by request status; omit to include all statuses. Accepted values: `pending`, `fulfilled`, `declined`, `cancelled`, `closed`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `createdAt`, `targetLabel`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
-## Resend organization invitation
+API request and response schemas: [listMyOrganizationAccessRequests](/api-reference/access-requests/listMyOrganizationAccessRequests).
+
+### Cancel organization access request
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations invitations resend <invitationId> [options]
+sim organizations access-requests cancel <requestId> [options]
 ```
 
-Resend Organization Invitation (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `invitationId` | Yes | Invitation identifier. |
+| `requestId` | Yes | Access request identifier. |
 
 </CommandTable>
 
@@ -454,23 +592,15 @@ Resend Organization Invitation (OAuth login or personal API key required)
 
 </CommandTable>
 
-## Revoke organization invitation
+API request and response schemas: [cancelOrganizationAccessRequest](/api-reference/access-requests/cancelOrganizationAccessRequest).
 
-```bash
-sim organizations invitations revoke <invitationId> [options]
-```
-
-Revoke Organization Invitation (OAuth login or personal API key required)
-
-**Arguments**
-
-<CommandTable>
+### List organization access requests
 
-| Argument | Required | Description |
-| --- | --- | --- |
-| `invitationId` | Yes | Invitation identifier. |
+OAuth login or personal API key required.
 
-</CommandTable>
+```bash
+sim organizations access-requests list [options]
+```
 
 **Options**
 
@@ -479,25 +609,32 @@ Revoke Organization Invitation (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--status <value>` | No | Filter by request status; omit to include all statuses. Accepted values: `pending`, `fulfilled`, `declined`, `cancelled`, `closed`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `createdAt`, `targetLabel`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--search <value>` | No | Case-insensitive substring match against the target label or requester name or email. |
 
 </CommandTable>
 
-## Delete SSO provider
+API request and response schemas: [listOrganizationAccessRequests](/api-reference/access-requests/listOrganizationAccessRequests).
+
+### Preview organization access request
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations sso providers delete <providerId> [options]
+sim organizations access-requests preview <requestId> [options]
 ```
 
-Delete SSO Provider (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `providerId` | Yes | Identity provider identifier. |
+| `requestId` | Yes | Access request identifier. |
 
 </CommandTable>
 
@@ -508,25 +645,26 @@ Delete SSO Provider (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Get SSO provider
+API request and response schemas: [previewOrganizationAccessRequest](/api-reference/access-requests/previewOrganizationAccessRequest).
+
+### Resolve organization access request
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations sso providers get <providerId> [options]
+sim organizations access-requests resolve <requestId> [options]
 ```
 
-Get SSO Provider (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `providerId` | Yes | Identity provider identifier. |
+| `requestId` | Yes | Access request identifier. |
 
 </CommandTable>
 
@@ -537,17 +675,23 @@ Get SSO Provider (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
+| `--action <value>` | Yes | apply: Apply the reviewed change to the governing group or member credit cap. decline: Decline the request without changing permissions or credit limits. Accepted values: `apply`, `decline`. |
+| `--expected-fingerprint <value>` | Conditional | Fingerprint from Preview Organization Access Request. Review its changes and impact before applying; a stale preview returns a conflict. Available when action is apply. Required when action is apply. |
+| `--new-limit-credits <value>` | Conditional | Required only for a usage-limit request: a whole-number credit cap greater than the current cap. Omit for permission requests. Available when action is apply. |
+| `--reason <value>` | Conditional | Required explanation for declining this request. Available when action is decline. Required when action is decline. |
 
 </CommandTable>
 
-## List SSO providers
+API request and response schemas: [resolveOrganizationAccessRequest](/api-reference/access-requests/resolveOrganizationAccessRequest).
+
+### Get organization access request settings
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations sso providers list [options]
+sim organizations access-requests settings get [options]
 ```
 
-List SSO Providers (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -555,20 +699,19 @@ List SSO Providers (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `providerId`, `domain`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
-## Save SSO provider
+API request and response schemas: [getOrganizationAccessRequestSettings](/api-reference/access-requests/getOrganizationAccessRequestSettings).
+
+### Update organization access request settings
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations sso providers save [options]
+sim organizations access-requests settings update [options]
 ```
 
-Save SSO Provider (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -576,73 +719,22 @@ Save SSO Provider (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--provider-type <value>` | Yes | oidc: Configure an OpenID Connect identity provider. saml: Configure a SAML identity provider. Accepted values: `oidc`, `saml`. |
-| `--provider-id <value>` | Yes | Globally unique provider ID; saving an existing provider replaces its supplied configuration. |
-| `--issuer <value>` | Yes | Identity provider issuer URL. |
-| `--domain <value>` | Yes | Email domain already verified by this organization. |
-| `--jit-provisioning-enabled` | No | Allow SSO sign-in to provision organization membership, subject to eligibility and available seats. |
-| `--no-jit-provisioning-enabled` | No | Send --jit-provisioning-enabled as false. |
-| `--mapping <json\|@file>` | No | Identity-provider claims mapped to user fields. (JSON, or @path / @- to read a file or stdin). |
-| `--client-id <value>` | No | Identity provider client identifier. Available when providerType is oidc. Required when providerType is oidc. |
-| `--client-secret <value\|@file>` | No | Write-only OIDC client secret; the redacted marker from providers get preserves an existing secret. Passing it inline exposes it to shell history and process listings. Required when --provider-type is oidc (@path / @- reads a file or stdin verbatim, including trailing newlines; @@value for a literal leading @). |
-| `--scopes <json\|@file>` | No | OIDC scopes; offline_access is omitted. Available when providerType is oidc. (JSON, or @path / @- to read a file or stdin). |
-| `--pkce` | No | Use PKCE for the authorization flow. Available when providerType is oidc. |
-| `--no-pkce` | No | Send --pkce as false. |
-| `--authorization-endpoint <value>` | No | Optional authorization endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc. |
-| `--token-endpoint <value>` | No | Optional token endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc. |
-| `--user-info-endpoint <value>` | No | Optional UserInfo endpoint. Available when providerType is oidc. |
-| `--skip-user-info-endpoint` | No | Read identity claims from the ID token instead of calling UserInfo. Available when providerType is oidc. |
-| `--no-skip-user-info-endpoint` | No | Send --skip-user-info-endpoint as false. |
-| `--jwks-endpoint <value>` | No | Optional signing-key endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc. |
-| `--entry-point <value>` | No | Identity provider SAML sign-in endpoint. Available when providerType is saml. Required when providerType is saml. |
-| `--cert <value>` | No | Identity provider signing certificate. Available when providerType is saml. Required when providerType is saml. |
-| `--callback-url <value>` | No | SAML callback URL; defaults to this provider’s Sim callback. Available when providerType is saml. |
-| `--audience <value>` | No | SAML audience; omission preserves the saved value. Available when providerType is saml. |
-| `--want-assertions-signed` | No | Require signed assertions; omission preserves the saved value. Available when providerType is saml. |
-| `--no-want-assertions-signed` | No | Send --want-assertions-signed as false. |
-| `--signature-algorithm <value>` | No | Signature algorithm accepted by the SAML configuration validator; omission preserves the saved value. Available when providerType is saml. |
-| `--digest-algorithm <value>` | No | Digest algorithm accepted by the SAML configuration validator; omission preserves the saved value. Available when providerType is saml. |
-| `--identifier-format <value>` | No | SAML NameID format; omission clears the saved value. Available when providerType is saml. |
-| `--idp-metadata <value>` | No | Identity provider metadata XML; omission clears the saved document. Available when providerType is saml. |
-
-</CommandTable>
-
-## Set primary SSO provider
-
-```bash
-sim organizations sso providers primary <providerId> [options]
-```
-
-Set Primary SSO Provider (OAuth login or personal API key required)
-
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `providerId` | Yes | Identity provider identifier. |
+| `--allow-requests <true\|false>` | Yes | Allow new requests and approvals. Disabling requests preserves history and still allows cancellation and decline. Accepted values: `true`, `false`. |
 
 </CommandTable>
 
-**Options**
+API request and response schemas: [updateOrganizationAccessRequestSettings](/api-reference/access-requests/updateOrganizationAccessRequestSettings).
 
-<CommandTable>
+## Verified domains
 
-| Option | Required | Description |
-| --- | --- | --- |
-| `--organization <value>` | Yes | Organization identifier. |
+### List organization domains
 
-</CommandTable>
-
-## Get SSO policy
+OAuth login or personal API key required.
 
 ```bash
-sim organizations sso policy get [options]
+sim organizations domains list [options]
 ```
 
-Get SSO Policy (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -650,17 +742,22 @@ Get SSO Policy (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "domain". Accepted values: `domain`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
-## Update SSO policy
+API request and response schemas: [listOrganizationDomains](/api-reference/organizations/listOrganizationDomains).
+
+### Add organization domain
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations sso policy update [options]
+sim organizations domains add [options]
 ```
 
-Update SSO Policy (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -668,43 +765,27 @@ Update SSO Policy (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--require-sso <true\|false>` | Yes | Require organization SSO on future sign-ins; existing sessions remain active. Accepted values: `true`, `false`. |
+| `--domain <value>` | Yes | Domain to claim and verify through a DNS TXT record. |
 
 </CommandTable>
 
-## Get organization
-
-```bash
-sim organizations get <organizationId>
-```
-
-Get Organization (OAuth login or personal API key required)
-
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `organizationId` | Yes | Organization identifier. |
+API request and response schemas: [addOrganizationDomain](/api-reference/organizations/addOrganizationDomain).
 
-</CommandTable>
+### Verify organization domain
 
-## Get organization member credit limit
+OAuth login or personal API key required.
 
 ```bash
-sim organizations members usage-limit get <userId> [options]
+sim organizations domains verify <domainId> [options]
 ```
 
-Get Organization Member Credit Limit (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `userId` | Yes | User ID of an organization member or external collaborator with workspace access in this organization. Use List Organization Members or List Workspace Members to find it. |
+| `domainId` | Yes | Domain claim owned by this organization. |
 
 </CommandTable>
 
@@ -718,21 +799,25 @@ Get Organization Member Credit Limit (OAuth login or personal API key required)
 
 </CommandTable>
 
-## Update organization member credit limit
+API request and response schemas: [verifyOrganizationDomain](/api-reference/organizations/verifyOrganizationDomain).
+
+### Remove organization domain
+
+OAuth login or personal API key required.
+
+This removes the domain claim and revokes verified SSO authority for its providers.
 
 ```bash
-sim organizations members usage-limit update <userId> [options]
+sim organizations domains remove <domainId> [options]
 ```
 
-Update Organization Member Credit Limit (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `userId` | Yes | User ID of an organization member or external collaborator with workspace access in this organization. Use List Organization Members or List Workspace Members to find it. |
+| `domainId` | Yes | Domain claim owned by this organization. |
 
 </CommandTable>
 
@@ -743,18 +828,22 @@ Update Organization Member Credit Limit (OAuth login or personal API key require
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--credit-limit <number\|null>` | Yes | Credit cap for this person. Send null to clear the cap or 0 to prevent further credit-consuming usage. Organization limits still apply. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## List organization members
+API request and response schemas: [removeOrganizationDomain](/api-reference/organizations/removeOrganizationDomain).
+
+## SSO providers and policy
+
+### List SSO providers
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations members list [options]
+sim organizations sso providers list [options]
 ```
 
-List Organization Members (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -762,28 +851,29 @@ List Organization Members (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--search <value>` | No | Case-insensitive substring match against member name or email. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `email`, `joinedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "providerId". Accepted values: `providerId`, `domain`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
-## Remove organization member
+API request and response schemas: [listSsoProviders](/api-reference/organizations/listSsoProviders).
+
+### Get SSO provider
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations members remove <userId> [options]
+sim organizations sso providers get <providerId> [options]
 ```
 
-Remove Organization Member (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `userId` | Yes | User identifier of the organization member. |
+| `providerId` | Yes | Identity provider identifier. |
 
 </CommandTable>
 
@@ -794,27 +884,20 @@ Remove Organization Member (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Update organization member
+API request and response schemas: [getSsoProvider](/api-reference/organizations/getSsoProvider).
 
-```bash
-sim organizations members update <userId> [options]
-```
+### Save SSO provider
 
-Update Organization Member (OAuth login or personal API key required)
+OAuth login or personal API key required.
 
-**Arguments**
+Choose `--provider-type oidc` or `saml`. OIDC requires `--client-id` and `--client-secret`; SAML requires `--entry-point` and `--cert`. Both require an organization-verified domain. The option descriptions state which omitted fields are preserved or cleared.
 
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `userId` | Yes | User identifier of the organization member. |
-
-</CommandTable>
+```bash
+sim organizations sso providers save [options]
+```
 
 **Options**
 
@@ -823,42 +906,57 @@ Update Organization Member (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--role <value>` | Yes | New organization role. Ownership transfers use a separate operation. Accepted values: `member`, `admin`. |
+| `--provider-type <value>` | Yes | oidc: Configure an OpenID Connect identity provider. saml: Configure a SAML identity provider. Accepted values: `oidc`, `saml`. |
+| `--provider-id <value>` | Yes | Globally unique provider ID; saving an existing provider replaces its supplied configuration. |
+| `--issuer <value>` | Yes | Identity provider issuer URL. |
+| `--domain <value>` | Yes | Email domain already verified by this organization. |
+| `--jit-provisioning-enabled` | No | Allow SSO sign-in to provision organization membership, subject to eligibility and available seats. Defaults to true. |
+| `--no-jit-provisioning-enabled` | No | Send --jit-provisioning-enabled as false. |
+| `--mapping <json\|@file>` | No | Identity-provider claims mapped to user fields. Defaults to &#123;"id":"sub","email":"email","name":"name","image":"picture"&#125;. (JSON, or @path / @- to read a file or stdin). |
+| `--client-id <value>` | Conditional | Identity provider client identifier. Available when providerType is oidc. Required when providerType is oidc. |
+| `--client-secret <value\|@file>` | Conditional | Write-only OIDC client secret; the redacted marker from providers get preserves an existing secret. Passing it inline exposes it to shell history and process listings. Required when --provider-type is oidc (@path / @- reads a file or stdin verbatim, including trailing newlines; @@value for a literal leading @). |
+| `--scopes <json\|@file>` | No | OIDC scopes; offline_access is omitted. Available when providerType is oidc. Defaults to ["openid","profile","email"]. (JSON, or @path / @- to read a file or stdin). |
+| `--pkce` | No | Use PKCE for the authorization flow. Available when providerType is oidc. Defaults to true. |
+| `--no-pkce` | No | Send --pkce as false. |
+| `--authorization-endpoint <value>` | No | Optional authorization endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc. |
+| `--token-endpoint <value>` | No | Optional token endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc. |
+| `--user-info-endpoint <value>` | No | Optional UserInfo endpoint. Available when providerType is oidc. |
+| `--skip-user-info-endpoint` | No | Read identity claims from the ID token instead of calling UserInfo. Available when providerType is oidc. Defaults to false. |
+| `--no-skip-user-info-endpoint` | No | Send --skip-user-info-endpoint as false. |
+| `--jwks-endpoint <value>` | No | Optional signing-key endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc. |
+| `--entry-point <value>` | Conditional | Identity provider SAML sign-in endpoint. Available when providerType is saml. Required when providerType is saml. |
+| `--cert <value>` | Conditional | Identity provider signing certificate. Available when providerType is saml. Required when providerType is saml. |
+| `--callback-url <value>` | No | SAML callback URL; defaults to this provider’s Sim callback. Available when providerType is saml. |
+| `--audience <value>` | No | SAML audience; omission preserves the saved value. Available when providerType is saml. |
+| `--want-assertions-signed` | No | Require signed assertions; omission preserves the saved value. Available when providerType is saml. |
+| `--no-want-assertions-signed` | No | Send --want-assertions-signed as false. |
+| `--signature-algorithm <value>` | No | Signature algorithm accepted by the SAML configuration validator; omission preserves the saved value. Available when providerType is saml. |
+| `--digest-algorithm <value>` | No | Digest algorithm accepted by the SAML configuration validator; omission preserves the saved value. Available when providerType is saml. |
+| `--identifier-format <value>` | No | SAML NameID format; omission clears the saved value. Available when providerType is saml. |
+| `--idp-metadata <value>` | No | Identity provider metadata XML; omission clears the saved document. Available when providerType is saml. |
 
 </CommandTable>
 
-## Get organization usage breakdown
+API request and response schemas: [saveSsoProvider](/api-reference/organizations/saveSsoProvider).
+
+### Set primary SSO provider
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations usage breakdown [options]
+sim organizations sso providers primary <providerId> [options]
 ```
 
-Get Organization Usage Breakdown (OAuth login or personal API key required)
-
-**Options**
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--organization <value>` | Yes | Organization identifier. |
-| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
-| `--start-date <value>` | No | First calendar date included, in the selected timezone. Requires preset=custom. |
-| `--end-date <value>` | No | Last calendar date included, in the selected timezone. Requires preset=custom. |
-| `--timezone <value>` | No | IANA timezone for calendar boundaries; defaults to UTC. |
-| `--dimension <value>` | Yes | Usage grouping dimension. Accepted values: `member`, `workspace`, `workflow`, `model`, `byok`, `source`. |
-| `--limit <value>` | No | Maximum ranked groups to return. Remaining usage is summarized in other. Must be a whole number from 1 to 100. Defaults to 50. |
+| `providerId` | Yes | Identity provider identifier. |
 
 </CommandTable>
 
-## Get organization usage summary
-
-```bash
-sim organizations usage summary [options]
-```
-
-Get Organization Usage Summary (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -866,20 +964,30 @@ Get Organization Usage Summary (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
-| `--start-date <value>` | No | First calendar date included, in the selected timezone. Requires preset=custom. |
-| `--end-date <value>` | No | Last calendar date included, in the selected timezone. Requires preset=custom. |
-| `--timezone <value>` | No | IANA timezone for calendar boundaries; defaults to UTC. |
 
 </CommandTable>
 
-## List organization usage events
+API request and response schemas: [setPrimarySsoProvider](/api-reference/organizations/setPrimarySsoProvider).
+
+### Delete SSO provider
+
+OAuth login or personal API key required.
+
+This removes the identity provider used for SSO sign-in; linked accounts remain.
 
 ```bash
-sim organizations usage events [options]
+sim organizations sso providers delete <providerId> [options]
 ```
 
-List Organization Usage Events (OAuth login or personal API key required)
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `providerId` | Yes | Identity provider identifier. |
+
+</CommandTable>
 
 **Options**
 
@@ -888,47 +996,40 @@ List Organization Usage Events (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
-| `--start-date <value>` | No | First calendar date included, in the selected timezone. Requires preset=custom. |
-| `--end-date <value>` | No | Last calendar date included, in the selected timezone. Requires preset=custom. |
-| `--timezone <value>` | No | IANA timezone for calendar boundaries; defaults to UTC. |
-| `--source <value>` | No | Restrict events to one product surface. Accepted values: `workflow`, `wand`, `sim-chat`, `mcp_copilot`, `mothership_block`, `knowledge-base`, `voice-input`, `enrichment`, `voice-output`, `api-tool`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `createdAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## List organizations
+API request and response schemas: [deleteSsoProvider](/api-reference/organizations/deleteSsoProvider).
+
+### Get SSO policy
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations list [options]
+sim organizations sso policy get [options]
 ```
 
-List Organizations (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--search <value>` | No | Case-insensitive substring match against the organization name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--organization <value>` | Yes | Organization identifier. |
 
 </CommandTable>
 
-## List organization workspaces
+API request and response schemas: [getSsoPolicy](/api-reference/organizations/getSsoPolicy).
+
+### Update SSO policy
+
+OAuth login or personal API key required.
 
 ```bash
-sim organizations workspaces [options]
+sim organizations sso policy update [options]
 ```
 
-List Organization Workspaces (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -936,9 +1037,13 @@ List Organization Workspaces (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--search <value>` | No | Case-insensitive substring match against the workspace name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `id`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--require-sso <true\|false>` | Yes | Require organization SSO on future sign-ins; existing sessions remain active. Accepted values: `true`, `false`. |
 
 </CommandTable>
+
+API request and response schemas: [updateSsoPolicy](/api-reference/organizations/updateSsoPolicy).
+
+## Related docs
+
+- [Organizations](/platform/organization)
+- [Permissions](/platform/permissions)
diff --git a/apps/docs/content/docs/cli/output.mdx b/apps/docs/content/docs/cli/output.mdx
index 67df6820722..ead4f4f601f 100644
--- a/apps/docs/content/docs/cli/output.mdx
+++ b/apps/docs/content/docs/cli/output.mdx
@@ -1,18 +1,18 @@
 ---
 title: Output formats
-description: table, json, yaml, and text — what each is for, and how to select one
+description: Select a format, parse results, and separate output from diagnostics.
 ---
 
-Commands that return structured API data support four output formats.
+Commands that return structured API data support four formats. JSON is the default.
 
-| Format | For |
+| Format | Output |
 | --- | --- |
-| `json` | agents, scripts, and piping into `jq` (default) |
-| `table` | reading |
-| `yaml` | piping into anything that reads YAML |
-| `text` | shell loops — tab-separated, no header, no colour |
+| `json` | Raw field names and values for scripts, agents, and `jq` |
+| `table` | Formatted values for reading in a terminal |
+| `yaml` | Raw values for YAML consumers |
+| `text` | Formatted, tab-separated values without color or a list header |
 
-Select one per command, save it to the profile, or set it in the environment:
+Select a format for one command, save a default, or use an environment variable:
 
 ```bash
 sim tables get tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --output table
@@ -20,47 +20,53 @@ sim configure --set-output table
 SIM_OUTPUT=yaml sim logs list > logs.yaml
 ```
 
-`--output` works before or after the command.
+`--output` can appear before or after the command. Commands use it when their action supports formatted output; the exceptions are listed below.
 
 ## What each format emits
 
-`json` and `yaml` emit the API's raw values, not the table's formatting — a
-duration stays `1500`, not `"1.5s"`.
+### JSON and YAML
 
-Paginated lists include the rows under `data` and the continuation cursor under
-`nextCursor`. A `null` cursor means no pages remain:
+Machine formats preserve API values: a duration remains `1500`, rather than the display string `"1.5s"`. Single-resource API responses are unwrapped from their outer `data` envelope. Cursor-paginated results retain rows under `data` and the continuation under `nextCursor`:
 
 ```json
 { "data": [{ "runId": "9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543" }], "nextCursor": null }
 ```
 
-Read list rows with `jq '.data[]'` and check for more pages with `jq '.nextCursor'`.
+Read rows with `jq '.data[]'` and check `.nextCursor` for continuation. A null cursor means pagination is finished; inspect any command-specific truncation flags or notices too. See [Pagination](/cli/scripting#pagination) for limits and memory behavior.
 
-`table` formats for reading: timestamps without milliseconds, sizes as `4.2 MB`,
-booleans as `yes`/`no`, costs as `$0.0142`. Long cells are clipped to keep rows
-on one line; switch to `json` for the full value.
+### Tables and text
 
-`text` uses the rendered cells, tab-separated, with no header or colour:
+Tables show UTC timestamps without milliseconds, formatted sizes, `yes`/`no` booleans, and formatted monetary amounts. Each command's reference specifies its units. Long table cells are clipped to one line; use JSON or YAML to inspect the returned value in full.
+
+Text uses the same formatted cells, flattened to one line and separated by tabs. Lists have no header or color; single records use a label and value on each line. Text values are not clipped to the table's column width:
 
 ```bash
-SIM_OUTPUT=text sim files list | while IFS=$'\t' read -r id name folder size type uploader uploaded; do
-  echo "$id $name"
+sim files list --output text | while IFS=$'\t' read -r id name folder size type uploader uploaded; do
+  printf '%s %s\n' "$id" "$name"
 done
 ```
 
-An absent value is an em-dash in `table` and an empty field in `text`.
+An absent value displays as an em dash in a table and an empty field in text. Use JSON when field types or empty-field positions matter.
+
+## Separate results and diagnostics
+
+Results go to stdout. Errors, progress, update notices, and operational notes go to stderr, so this pipe receives only the result:
+
+```bash
+sim logs list --output json | jq '.data[]'
+```
+
+In JSON/YAML mode, API errors use an `error` object on stderr with `code`, `message`, and optional `details`. Configuration errors, argument-parser errors, and some command outcome messages remain text. See [Exit codes](/cli/scripting#exit-codes) before branching on a command's outcome.
 
 ## Reading a run in detail
 
-`sim logs get` prints a concise summary. Add `--trace` for the recursive trace
-with span inputs, outputs, errors, timing, and cost:
+In table mode, `sim logs get` prints a summary. Add `--trace` to print recursive spans with inputs, outputs, errors, timing, and cost:
 
 ```bash
-sim logs get 9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543 --trace
+sim logs get 9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543 --trace --output table
 ```
 
-`json` and `yaml` always carry the complete response, so `--trace` is a no-op
-there:
+JSON and YAML include the returned trace without `--trace`; the flag does not change those formats:
 
 ```bash
 sim logs get 9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543 --output json | jq '.traceSpans'
@@ -68,16 +74,27 @@ sim logs get 9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543 --output json | jq '.traceSpan
 
 ## Exceptions
 
-`sim configure` prints local configuration for humans. `sim profiles` honors `--output`.
-`sim files get` writes the file’s raw content to stdout or `--output-file`.
+| Command | Output behavior |
+| --- | --- |
+| `sim configure` | Prints local settings as text |
+| `sim profiles` | Honors `--output`; JSON includes an `active` boolean |
+| `sim telemetry status`, `enable`, `disable` | Always print text |
+| `sim files get` | Streams file content to stdout; `--output-file` saves content and prints a save receipt |
+| `sim chat` | Streams reply text in table/text modes and prints the conversation ID to stderr; JSON/YAML wait for the finished result including that ID |
+| `sim workflows export` | Emits YAML when selected; otherwise emits JSON, including in table/text mode |
 
-`sim chat` streams reply text in `table` and `text` modes. In `json` or `yaml`
-mode it waits for the finished result and includes the conversation ID.
+File downloads refuse binary content on an interactive terminal. Pipe stdout or use `--output-file`; overwriting an existing output file requires `--force`.
 
-`sim workflows export` always emits raw JSON, or YAML when the profile says so,
-so that it round-trips through `import`:
+Workflow import accepts JSON. Pin that format when exporting a file you plan to import, even if your profile prefers YAML:
 
 ```bash
-sim workflows export 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 > wf.json
+sim workflows export 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --output json > wf.json
 sim workflows import --workflow @wf.json
 ```
+
+## Related docs
+
+- [Configuration](/cli/configuration)
+- [Scripting](/cli/scripting)
+- [Logs commands](/cli/logs)
+- [File commands](/cli/files)
diff --git a/apps/docs/content/docs/cli/permission-groups.mdx b/apps/docs/content/docs/cli/permission-groups.mdx
index eebbfa89431..dd6bafa29b9 100644
--- a/apps/docs/content/docs/cli/permission-groups.mdx
+++ b/apps/docs/content/docs/cli/permission-groups.mdx
@@ -1,22 +1,28 @@
 ---
-title: Permission Groups
-description: Manage permission groups — every subcommand, argument, and flag
+title: Permission groups
+description: Manage organization permission groups, their configuration, and member assignments.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Manage organization permission groups, their configuration, and member assignments.
+
+Use the linked API request schema for the supported `--config` keys. Supplied arrays replace their entire lists; omitted settings remain unchanged on update.
+
 `sim permission-groups` is also spelled `sim permission-group`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
+
+## Group configuration
+
+### List permission groups
 
-## Add permission group member
+OAuth login or personal API key required.
 
 ```bash
-sim permission-groups members add [options]
+sim permission-groups list [options]
 ```
 
-Add Permission Group Member (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -24,18 +30,32 @@ Add Permission Group Member (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--group <value>` | Yes | Permission group identifier. |
-| `--user <value>` | Yes | Existing organization member to add. |
+| `--search <value>` | No | Case-insensitive substring match against the group name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Bulk add permission group members
+API request and response schemas: [listPermissionGroups](/api-reference/permission-groups/listPermissionGroups).
+
+### Get permission group
+
+OAuth login or personal API key required.
 
 ```bash
-sim permission-groups members batch-add [options]
+sim permission-groups get <groupId> [options]
 ```
 
-Bulk Add Permission Group Members (OAuth login or personal API key required)
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `groupId` | Yes | Permission group identifier. |
+
+</CommandTable>
 
 **Options**
 
@@ -44,20 +64,19 @@ Bulk Add Permission Group Members (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--group <value>` | Yes | Permission group identifier. |
-| `--user <value...>` | No | User IDs to add; cannot be combined with --all-members (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--all-members` | No | Add every current organization member; cannot be combined with --user. |
 
 </CommandTable>
 
-## List permission group members
+API request and response schemas: [getPermissionGroup](/api-reference/permission-groups/getPermissionGroup).
+
+### Create permission group
+
+OAuth login or personal API key required.
 
 ```bash
-sim permission-groups members list [options]
+sim permission-groups create [options]
 ```
 
-List Permission Group Members (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -65,28 +84,32 @@ List Permission Group Members (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--group <value>` | Yes | Permission group identifier. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `assignedAt`, `userId`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--name <value>` | Yes | Group name, unique within the organization. |
+| `--description <value>` | No | Optional group description. |
+| `--config <json\|@file>` | No | Group settings to set. Omitted keys use the default permission configuration. (JSON, or @path / @- to read a file or stdin). |
+| `--default` | No | Whether the group is the organization default. Only one group can be the default. |
+| `--no-default` | No | Send --default as false. |
+| `--workspace-ids <json\|@file>` | Conditional | Workspace IDs targeted by a non-default group. Required when creating a non-default group; omit for a default group. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Remove permission group member
+API request and response schemas: [createPermissionGroup](/api-reference/permission-groups/createPermissionGroup).
+
+### Update permission group
+
+OAuth login or personal API key required.
 
 ```bash
-sim permission-groups members remove <userId> [options]
+sim permission-groups update <groupId> [options]
 ```
 
-Remove Permission Group Member (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `userId` | Yes | User identifier of the member to remove. |
+| `groupId` | Yes | Permission group identifier. |
 
 </CommandTable>
 
@@ -97,19 +120,27 @@ Remove Permission Group Member (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--group <value>` | Yes | Permission group identifier. |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--name <value>` | No | Group name, unique within the organization. |
+| `--description <value>` | No | Group description. Null or an empty string clears it; omission leaves it unchanged. (--description null sends the word, not JSON null). |
+| `--config <json\|@file>` | No | Patch of group settings. Omitted keys remain unchanged; each supplied array replaces that entire list. (JSON, or @path / @- to read a file or stdin). |
+| `--default` | No | Whether the group is the organization default. Only one group can be the default. |
+| `--no-default` | No | Send --default as false. |
+| `--workspace-ids <json\|@file>` | No | Workspace identifiers for a non-default group. Required on creation; an empty update makes the group inactive. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Create permission group
+API request and response schemas: [updatePermissionGroup](/api-reference/permission-groups/updatePermissionGroup).
+
+## Member assignments
+
+### List permission group members
+
+OAuth login or personal API key required.
 
 ```bash
-sim permission-groups create [options]
+sim permission-groups members list [options]
 ```
 
-Create Permission Group (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -117,32 +148,22 @@ Create Permission Group (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--name <value>` | Yes | Group name, unique within the organization. |
-| `--description <value>` | No | Optional group description. |
-| `--config <json\|@file>` | No | Group settings to set. Omitted keys use the default permission configuration. (JSON, or @path / @- to read a file or stdin). |
-| `--default` | No | Whether the group is the organization default. Only one group can be the default. |
-| `--no-default` | No | Send --default as false. |
-| `--workspace-ids <json\|@file>` | No | Workspace IDs targeted by a non-default group. Required when creating a non-default group; omit for a default group. (JSON, or @path / @- to read a file or stdin). |
+| `--group <value>` | Yes | Permission group identifier. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "assignedAt". Accepted values: `assignedAt`, `userId`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Delete permission group
-
-```bash
-sim permission-groups delete <groupId> [options]
-```
-
-Delete Permission Group (OAuth login or personal API key required)
+API request and response schemas: [listPermissionGroupMembers](/api-reference/permission-groups/listPermissionGroupMembers).
 
-**Arguments**
+### Add permission group member
 
-<CommandTable>
+OAuth login or personal API key required.
 
-| Argument | Required | Description |
-| --- | --- | --- |
-| `groupId` | Yes | Permission group identifier. |
-
-</CommandTable>
+```bash
+sim permission-groups members add [options]
+```
 
 **Options**
 
@@ -151,25 +172,30 @@ Delete Permission Group (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--group <value>` | Yes | Permission group identifier. |
+| `--user <value>` | Yes | Existing organization member to add. |
 
 </CommandTable>
 
-## Get permission group
+API request and response schemas: [addPermissionGroupMember](/api-reference/permission-groups/addPermissionGroupMember).
+
+### Remove permission group member
+
+OAuth login or personal API key required.
+
+This removes the member assignment and changes which permission groups apply to the user.
 
 ```bash
-sim permission-groups get <groupId> [options]
+sim permission-groups members remove <userId> [options]
 ```
 
-Get Permission Group (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `groupId` | Yes | Permission group identifier. |
+| `userId` | Yes | User identifier of the member to remove. |
 
 </CommandTable>
 
@@ -180,17 +206,21 @@ Get Permission Group (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
+| `--group <value>` | Yes | Permission group identifier. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## List permission groups
+API request and response schemas: [removePermissionGroupMember](/api-reference/permission-groups/removePermissionGroupMember).
+
+### Bulk add permission group members
+
+OAuth login or personal API key required.
 
 ```bash
-sim permission-groups list [options]
+sim permission-groups members batch-add [options]
 ```
 
-List Permission Groups (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -198,21 +228,26 @@ List Permission Groups (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--search <value>` | No | Case-insensitive substring match against the group name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--group <value>` | Yes | Permission group identifier. |
+| `--user <value...>` | No | User IDs to add; cannot be combined with --all-members (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--all-members` | No | Add every current organization member; cannot be combined with --user. |
 
 </CommandTable>
 
-## Update permission group
+API request and response schemas: [bulkAddPermissionGroupMembers](/api-reference/permission-groups/bulkAddPermissionGroupMembers).
+
+## Delete groups
+
+### Delete permission group
+
+OAuth login or personal API key required.
+
+This permanently deletes the permission group and its member assignments.
 
 ```bash
-sim permission-groups update <groupId> [options]
+sim permission-groups delete <groupId> [options]
 ```
 
-Update Permission Group (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -230,11 +265,12 @@ Update Permission Group (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--name <value>` | No | Group name, unique within the organization. |
-| `--description <value>` | No | Group description. Null or an empty string clears it; omission leaves it unchanged. (--description null sends the word, not JSON null). |
-| `--config <json\|@file>` | No | Patch of group settings. Omitted keys remain unchanged; each supplied array replaces that entire list. (JSON, or @path / @- to read a file or stdin). |
-| `--default` | No | Whether the group is the organization default. Only one group can be the default. |
-| `--no-default` | No | Send --default as false. |
-| `--workspace-ids <json\|@file>` | No | Workspace identifiers for a non-default group. Required on creation; an empty update makes the group inactive. (JSON, or @path / @- to read a file or stdin). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
+
+API request and response schemas: [deletePermissionGroup](/api-reference/permission-groups/deletePermissionGroup).
+
+## Related docs
+
+- [Permission groups](/platform/permissions)
diff --git a/apps/docs/content/docs/cli/profiles.mdx b/apps/docs/content/docs/cli/profiles.mdx
index 5cdb26f604b..be05de4dc08 100644
--- a/apps/docs/content/docs/cli/profiles.mdx
+++ b/apps/docs/content/docs/cli/profiles.mdx
@@ -1,13 +1,17 @@
 ---
 title: Profiles
-description: List profiles or add a workspace profile that shares a stored login — every subcommand, argument, and flag
+description: List profiles and add a workspace profile that shares a stored login.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+List profiles and add a workspace profile that shares a stored login.
+
+Adding a profile reuses the active stored login and selects a default workspace. Supply `--workspace` when running without an interactive terminal.
+
 `sim profiles` is also spelled `sim profile`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
 
 ## List configured profiles
 
@@ -40,3 +44,10 @@ sim profiles add <name> [options]
 | `-w, --workspace <id>` | No | Existing workspace to use; omit for an interactive picker. |
 
 </CommandTable>
+
+API request and response schemas: [getWorkspace](/api-reference/workspaces/getWorkspace), [listWorkspaces](/api-reference/workspaces/listWorkspaces).
+
+## Related docs
+
+- [Configuration](/cli/configuration)
+- [Authentication](/cli/authentication)
diff --git a/apps/docs/content/docs/cli/reference.mdx b/apps/docs/content/docs/cli/reference.mdx
index f46c03bb001..27318d9e39e 100644
--- a/apps/docs/content/docs/cli/reference.mdx
+++ b/apps/docs/content/docs/cli/reference.mdx
@@ -8,14 +8,16 @@ import { CommandTable } from '@/components/ui/command-table'
 Every command on one page, generated from the CLI itself. Start at the
 [overview](/cli/commands) to browse; this page is for searching and for tools.
 
-Append `.mdx` to any page for its raw Markdown —
+Append `.mdx` to an authored guide or CLI reference page for its raw Markdown —
 [`/cli/reference.mdx`](/cli/reference.mdx) is this page as plain text. The docs
 are also published as [`/llms.txt`](/llms.txt) and
 [`/llms-full.txt`](/llms-full.txt).
 
 ## Global options
 
-These apply to every command, and may be written before or after it.
+Place these options before or after the command. Each command uses the settings
+relevant to its action. Telemetry commands always print text; workflow export
+prints a portable JSON document, or YAML when selected.
 
 | Option | Description |
 | --- | --- |
@@ -24,6 +26,13 @@ These apply to every command, and may be written before or after it.
 | `-w, --workspace <id>` | Workspace to target (env: SIM_WORKSPACE). |
 | `--output <format>` | Output format for this command. Accepted values: `table`, `json`, `yaml`, `text`. |
 
+Use `--help` to inspect a command. `sim --version` prints the CLI version,
+takes no value, and exits without running a command. Deployment-version commands
+use their documented arguments or `--to-version`.
+
+API schema links describe HTTP payloads. See [CLI output formats](/cli/output)
+for resource unwrapping, pagination envelopes, and display formats.
+
 ## sim login
 
 Log in through the browser and store the login for the profile
@@ -82,6 +91,8 @@ sim whoami [options]
 
 </CommandTable>
 
+API request and response schemas: [getMeta](/api-reference/meta/getApiMeta), [getWorkspace](/api-reference/workspaces/getWorkspace).
+
 ## sim configure
 
 Switch a profile's default workspace, or set its endpoint or output format
@@ -149,8 +160,22 @@ sim chat <message> [options]
 
 </CommandTable>
 
+Each turn prints the reply on stdout and the conversation ID on stderr; pass that ID back with -c to continue the same conversation. With --output json or yaml the reply is not streamed — the finished result is printed as one document, conversation ID included.
+
+**Examples**
+
+```bash
+sim chat "What workflows do I have?"
+sim chat -c "$CONVERSATION_ID" "Which of those run on a schedule?"
+sim --output json chat "Summarize yesterday's failed runs" | jq -r '.content'
+```
+
 ## sim profiles
 
+List profiles and add a workspace profile that shares a stored login.
+
+Adding a profile reuses the active stored login and selects a default workspace. Supply `--workspace` when running without an interactive terminal.
+
 Also spelled `sim profile`.
 
 ### sim profiles list
@@ -189,19 +214,25 @@ sim profiles add <name> [options]
 
 </CommandTable>
 
+API request and response schemas: [getWorkspace](/api-reference/workspaces/getWorkspace), [listWorkspaces](/api-reference/workspaces/listWorkspaces).
+
 ## sim telemetry
 
+Inspect and change this machine’s anonymous usage-reporting preference.
+
 ### sim telemetry status
 
-Show whether usage reporting is on, and why not if it is off
+Show usage-reporting status
 
 ```bash
 sim telemetry status
 ```
 
+Telemetry commands always print text. DO_NOT_TRACK and SIM_TELEMETRY_DISABLED override the saved preference; a build without a reporting destination remains off. See the usage-data guide for the data collected.
+
 ### sim telemetry enable
 
-Turn usage reporting on for this machine
+Enable the usage-reporting preference for this machine
 
 ```bash
 sim telemetry enable
@@ -217,9 +248,11 @@ sim telemetry disable
 
 ## sim cli
 
+Find a command by describing the task you want to perform.
+
 ### sim cli search
 
-Find the command for a task, described in plain words
+Find commands for a task
 
 ```bash
 sim cli search <query...>
@@ -235,13 +268,26 @@ sim cli search <query...>
 
 </CommandTable>
 
+Ranks the commands this CLI ships, locally; your query is never sent anywhere. Returns the 5 best matches. Run `<command> --help` on one for its flags.
+
+**Examples**
+
+```bash
+sim cli search "cancel a running workflow"
+sim cli search list table rows
+```
+
 ## sim audit-logs
 
+Read organization audit actions and filter by actor, resource, workspace, or time.
+
+Requires an organization Admin or owner, an OAuth login or personal API key, and enabled enterprise audit access for the deployment.
+
 Also spelled `sim audit-log`.
 
 ### sim audit-logs get
 
-Get Audit Log (OAuth login or personal API key required)
+Get audit log (OAuth login or personal API key required)
 
 ```bash
 sim audit-logs get <auditLogId> [options]
@@ -263,13 +309,15 @@ sim audit-logs get <auditLogId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--organization <value>` | No | Organization ID; defaults to your only organization, and is required when your account belongs to more than one (OAuth login or personal API key required). |
+| `--organization <value>` | No | Organization whose audit trail to read; defaults to the caller’s organization. A caller that belongs to no organization, or names one it does not belong to, is refused with 403. |
 
 </CommandTable>
 
+API request and response schemas: [getAuditLog](/api-reference/audit-logs/getAuditLog).
+
 ### sim audit-logs list
 
-List Audit Logs (OAuth login or personal API key required)
+List audit logs (OAuth login or personal API key required)
 
 ```bash
 sim audit-logs list [options]
@@ -284,23 +332,27 @@ sim audit-logs list [options]
 | `--action <value>` | No | Filter by exact action name. |
 | `--resource-type <value>` | No | Filter by resource type. Accepts a comma-separated set; members are trimmed and deduplicated, and member order affects neither the result nor the cursor. |
 | `--resource-id <value>` | No | Filter by exact resource identifier. |
-| `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
-| `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
+| `--start-date <value>` | No | Include audit entries created at or after this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected. |
+| `--end-date <value>` | No | Include audit entries created at or before this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected. |
 | `--include-departed` | No | Include actions by users who have left the organization. |
 | `--no-include-departed` | No | Send --include-departed as false. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--organization <value>` | No | Organization ID; defaults to your only organization, and is required when your account belongs to more than one (OAuth login or personal API key required). |
+| `--organization <value>` | No | Organization whose audit trail to read; defaults to the caller’s organization. A caller that belongs to no organization, or names one it does not belong to, is refused with 403. |
 | `--actor-email <value>` | No | Filter by actor email address. |
 | `--all-workspaces` | No | Do not filter to the configured workspace (OAuth login or personal API key required for account-wide access). |
 
 </CommandTable>
 
+API request and response schemas: [listAuditLogs](/api-reference/audit-logs/listAuditLogs).
+
 ## sim billing
 
+Read billing status, credit usage, and storage usage.
+
 ### sim billing status
 
-Show billing status, credits spent this period, and storage used (credits and storage require an OAuth login or personal API key)
+Show billing status, credits spent, and storage used (credits and storage require an OAuth login or personal API key)
 
 ```bash
 sim billing status [options]
@@ -316,6 +368,8 @@ sim billing status [options]
 
 </CommandTable>
 
+API request and response schemas: [getBillingStatus](/api-reference/billing/getBillingStatus).
+
 ### sim billing logs
 
 List credit usage events (an OAuth login or personal API key reports only your events; a workspace API key reports every member's in aggregate, unattributed)
@@ -330,8 +384,8 @@ sim billing logs [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--source <value>` | No | Filter by usage source; sim-chat combines Copilot and workspace chat. Accepted values: `workflow`, `wand`, `sim-chat`, `mcp_copilot`, `mothership_block`, `knowledge-base`, `voice-input`, `enrichment`, `voice-output`, `api-tool`. |
-| `--period <value>` | No | Billing period. Accepted values: `1d`, `7d`, `30d`, `all`, `custom`. |
+| `--source <value>` | No | Filter by usage source; sim-chat combines Sim agent and workspace Chat usage. Accepted values: `workflow`, `wand`, `sim-chat`, `mcp_copilot`, `mothership_block`, `knowledge-base`, `voice-input`, `enrichment`, `voice-output`, `api-tool`. |
+| `--period <value>` | No | Billing period. Defaults to "30d". Accepted values: `1d`, `7d`, `30d`, `all`, `custom`. |
 | `--start-date <value>` | No | Custom period start (ISO 8601). |
 | `--end-date <value>` | No | Custom period end (ISO 8601). |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
@@ -340,11 +394,17 @@ sim billing logs [options]
 
 </CommandTable>
 
+API request and response schemas: [listBillingLogs](/api-reference/billing/listBillingLogs).
+
 ## sim blocks
 
+Inspect workflow blocks, integration blocks, and triggers available to the workspace.
+
+The catalog reflects the workspace’s allowed integrations, revealed preview blocks, and deployed custom blocks.
+
 ### sim blocks get
 
-Get Block
+Get block
 
 ```bash
 sim blocks get <blockId>
@@ -356,13 +416,15 @@ sim blocks get <blockId>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `blockId` | Yes | Block type identifier. An unversioned base type resolves to the newest version, and the response echoes the resolved id. |
+| `blockId` | Yes | Block type identifier. An unversioned base type resolves to the newest visible version. The response echoes the resolved ID. |
 
 </CommandTable>
 
+API request and response schemas: [getBlock](/api-reference/catalog/getBlock).
+
 ### sim blocks list
 
-List Blocks
+List blocks
 
 ```bash
 sim blocks list [options]
@@ -380,17 +442,21 @@ sim blocks list [options]
 | `--source <value>` | No | Restrict to shipped blocks or to this workspace’s deployed custom blocks. Accepted values: `builtin`, `custom`. |
 | `--include-sunset` | No | Include `legacy` and `deprecated` blocks. Off by default: a sunset block keeps executing where it is already placed, but it is not offered for new authoring. Each returned entry carries `sunset.replacedBy`, the block to build with instead. |
 | `--no-include-sunset` | No | Send --include-sunset as false. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `id`, `name`, `category`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "id". Accepted values: `id`, `name`, `category`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listBlocks](/api-reference/catalog/listBlocks).
+
 ## sim chat-deployments
 
+List workflow chat deployments in the workspace.
+
 ### sim chat-deployments list
 
-List Chat Deployments
+List chat deployments
 
 ```bash
 sim chat-deployments list [options]
@@ -405,17 +471,23 @@ sim chat-deployments list [options]
 | `--workflow-id <value>` | No | Restrict to deployments of one workflow. |
 | `--is-active` | No | Restrict to active or inactive deployments. |
 | `--no-is-active` | No | Send --is-active as false. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `identifier`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `identifier`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listChatDeployments](/api-reference/workflows/listChatDeployments).
+
 ## sim connector-types
 
+Discover knowledge connectors and their authentication and source-configuration schemas.
+
+Use `--detail full` to inspect a connector’s configuration before creating it.
+
 ### sim connector-types list
 
-List Connector Types
+List connector types
 
 ```bash
 sim connector-types list [options]
@@ -434,13 +506,21 @@ sim connector-types list [options]
 
 </CommandTable>
 
+API request and response schemas: [listConnectorTypes](/api-reference/catalog/listConnectorTypes).
+
 ## sim credentials
 
+Discover providers, connect accounts, and manage credential access.
+
+Run `sim --output json credentials providers list` to inspect the provider’s fields and authentication requirements before creating a service-account credential. OAuth connection commands return a link that a person must open to authorize the connection.
+
 Also spelled `sim credential`.
 
 ### sim credentials delete
 
-Disconnect Credential (OAuth login or personal API key required)
+Disconnect credential (OAuth login or personal API key required)
+
+This disconnects the credential and removes its stored authentication.
 
 ```bash
 sim credentials delete <credentialId> [options]
@@ -466,9 +546,11 @@ sim credentials delete <credentialId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteCredential](/api-reference/credentials/deleteCredential).
+
 ### sim credentials members list
 
-List Credential Members (OAuth login or personal API key required)
+List credential members (OAuth login or personal API key required)
 
 ```bash
 sim credentials members list <credentialId> [options]
@@ -491,14 +573,18 @@ sim credentials members list <credentialId> [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `email`, `name`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "email". Accepted values: `email`, `name`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
+API request and response schemas: [listCredentialMembers](/api-reference/credentials/listCredentialMembers).
+
 ### sim credentials members remove
 
-Remove Credential Member (OAuth login or personal API key required)
+Remove credential member (OAuth login or personal API key required)
+
+This revokes the selected user’s explicit credential grant.
 
 ```bash
 sim credentials members remove <credentialId> <userId> [options]
@@ -525,9 +611,11 @@ sim credentials members remove <credentialId> <userId> [options]
 
 </CommandTable>
 
+API request and response schemas: [removeCredentialMember](/api-reference/credentials/removeCredentialMember).
+
 ### sim credentials members upsert
 
-Upsert Credential Member (OAuth login or personal API key required)
+Upsert credential member (OAuth login or personal API key required)
 
 ```bash
 sim credentials members upsert <credentialId> [options]
@@ -554,9 +642,11 @@ sim credentials members upsert <credentialId> [options]
 
 </CommandTable>
 
+API request and response schemas: [upsertCredentialMember](/api-reference/credentials/upsertCredentialMember).
+
 ### sim credentials providers list
 
-List Credential Providers
+List credential providers
 
 ```bash
 sim credentials providers list [options]
@@ -572,9 +662,11 @@ sim credentials providers list [options]
 
 </CommandTable>
 
+API request and response schemas: [listCredentialProviders](/api-reference/credentials/listCredentialProviders).
+
 ### sim credentials list
 
-List Credentials
+List credentials
 
 ```bash
 sim credentials list [options]
@@ -589,15 +681,17 @@ sim credentials list [options]
 | `--type <value>` | No | Restrict results to this credential type. Accepted values: `oauth`, `service_account`. |
 | `--provider-id <value>` | No | Restrict results to credentials for this integration provider. |
 | `--search <value>` | No | Case-insensitive substring match against the credential display name. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `displayName`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `displayName`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listCredentials](/api-reference/credentials/listCredentials).
+
 ### sim credentials update
 
-Update Credential (OAuth login or personal API key required)
+Update credential (OAuth login or personal API key required)
 
 ```bash
 sim credentials update <credentialId> [options]
@@ -645,6 +739,8 @@ sim credentials update <credentialId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateCredential](/api-reference/credentials/updateCredential).
+
 ### sim credentials create
 
 Create a service-account credential using its discovered provider schema (OAuth login or personal API key required)
@@ -676,6 +772,8 @@ sim credentials create <providerId> [options]
 
 </CommandTable>
 
+API request and response schemas: [createServiceAccountCredential](/api-reference/credentials/createServiceAccountCredential).
+
 ### sim credentials connect
 
 Create a short-lived link for connecting an OAuth provider (OAuth login or personal API key required)
@@ -704,6 +802,8 @@ sim credentials connect <providerId> [options]
 
 </CommandTable>
 
+API request and response schemas: [createCredentialConnection](/api-reference/credentials/createCredentialConnection).
+
 ### sim credentials reconnect
 
 Create a short-lived link for reconnecting an OAuth credential (OAuth login or personal API key required)
@@ -722,13 +822,17 @@ sim credentials reconnect <credentialId>
 
 </CommandTable>
 
+API request and response schemas: [createCredentialConnection](/api-reference/credentials/createCredentialConnection).
+
 ## sim custom-tools
 
+Create and manage code-backed tools that agents can call.
+
 Also spelled `sim custom-tool`.
 
 ### sim custom-tools create
 
-Create Custom Tool
+Create custom tool
 
 ```bash
 sim custom-tools create [options]
@@ -746,9 +850,13 @@ sim custom-tools create [options]
 
 </CommandTable>
 
+API request and response schemas: [createCustomTool](/api-reference/custom-tools/createCustomTool).
+
 ### sim custom-tools delete
 
-Delete Custom Tool
+Delete custom tool
+
+This deletes the custom tool.
 
 ```bash
 sim custom-tools delete <customToolId> [options]
@@ -774,9 +882,11 @@ sim custom-tools delete <customToolId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteCustomTool](/api-reference/custom-tools/deleteCustomTool).
+
 ### sim custom-tools get
 
-Get Custom Tool
+Get custom tool
 
 ```bash
 sim custom-tools get <customToolId>
@@ -792,9 +902,11 @@ sim custom-tools get <customToolId>
 
 </CommandTable>
 
+API request and response schemas: [getCustomTool](/api-reference/custom-tools/getCustomTool).
+
 ### sim custom-tools list
 
-List Custom Tools
+List custom tools
 
 ```bash
 sim custom-tools list [options]
@@ -807,15 +919,17 @@ sim custom-tools list [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--search <value>` | No | Case-insensitive substring match against the tool title. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `title`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `title`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listCustomTools](/api-reference/custom-tools/listCustomTools).
+
 ### sim custom-tools update
 
-Update Custom Tool
+Update custom tool
 
 ```bash
 sim custom-tools update <customToolId> [options]
@@ -843,14 +957,20 @@ sim custom-tools update <customToolId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateCustomTool](/api-reference/custom-tools/updateCustomTool).
+
 ## sim files
 
+Browse workspace files, read or write content, manage versions, and configure sharing.
+
 Also spelled `sim file`.
 
 ### sim files batch-delete
 
 Delete several files at once
 
+This archives the listed files; restore them with `files restore`.
+
 ```bash
 sim files batch-delete [options]
 ```
@@ -866,9 +986,11 @@ sim files batch-delete [options]
 
 </CommandTable>
 
+API request and response schemas: [bulkDeleteFiles](/api-reference/files/bulkDeleteFiles).
+
 ### sim files create
 
-Create File
+Create file
 
 ```bash
 sim files create [options]
@@ -883,11 +1005,13 @@ sim files create [options]
 | `--name <value>` | Yes | File name, including its extension. Path separators and dot segments are rejected. |
 | `--content-type <value>` | No | MIME type. When omitted, it is inferred from the file extension. |
 | `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
-| `--content <value>` | No | Initial file content. Omit or send an empty string for a zero-byte file. The 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`. Use an upload session for anything larger. |
-| `--encoding <value>` | No | Encoding of the content field. Accepted values: `utf-8`, `base64`. |
+| `--content <value>` | No | Initial file content. Omit or send an empty string for a zero-byte file. The complete JSON request is capped at 10 MiB, including encoding and the envelope; the separate decoded-file limit is 50 MiB. For larger payloads, use `sim files upload <path>`. Defaults to "". |
+| `--encoding <value>` | No | Encoding of the content field. Defaults to "utf-8". Accepted values: `utf-8`, `base64`. |
 
 </CommandTable>
 
+API request and response schemas: [createFile](/api-reference/files/createFile).
+
 ### sim files folders create
 
 Create a file folder at a path
@@ -906,9 +1030,13 @@ sim files folders create <path>
 
 </CommandTable>
 
+API request and response schemas: [createFileFolder](/api-reference/files/createFilesFolder).
+
 ### sim files folders delete
 
-Delete Folder
+Delete folder
+
+This archives the file folder and, when recursive, everything inside it.
 
 ```bash
 sim files folders delete <path> [options]
@@ -930,11 +1058,13 @@ sim files folders delete <path> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--recursive` | No | Delete the folder and its descendants. |
+| `--recursive` | No | Archive the folder and its descendants. Defaults to "false". |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
+API request and response schemas: [deleteFileFolder](/api-reference/files/deleteFilesFolder).
+
 ### sim files folders list
 
 List folders
@@ -953,14 +1083,16 @@ Also available as `sim files folders ls`.
 | --- | --- | --- |
 | `--parent <value>` | No | Direct parent folder path. |
 | `--search <value>` | No | Case-insensitive substring match against the folder name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--scope <value>` | No | Which lifecycle set to list: `active` (default) returns live folders only; `archived` returns folders a recursive delete soft-deleted, which is how a caller finds a path to hand to the folder restore. Authorization is identical for both. Accepted values: `active`, `archived`. |
 | `--recursive <value>` | No | Whether parentPath includes every descendant instead of direct children only. Accepted values: `true`, `1`, `yes`, `on`, `y`, `enabled`, `false`, `0`, `no`, `off`, `n`, `disabled`. |
 | `--depth <value>` | No | Deepest level below parentPath to include when recursive is true. |
 
 </CommandTable>
 
+API request and response schemas: [listFileFolders](/api-reference/files/listFilesFolders).
+
 ### sim files folders move
 
 Rename or move a file folder
@@ -982,6 +1114,8 @@ Also available as `sim files folders mv`.
 
 </CommandTable>
 
+API request and response schemas: [relocateFileFolder](/api-reference/files/relocateFilesFolder).
+
 ### sim files folders restore
 
 Restore an archived file folder
@@ -1000,9 +1134,13 @@ sim files folders restore <path>
 
 </CommandTable>
 
+API request and response schemas: [restoreFileFolder](/api-reference/files/restoreFilesFolder).
+
 ### sim files delete
 
-Delete File
+Delete file
+
+This archives the file.
 
 ```bash
 sim files delete <fileId> [options]
@@ -1028,10 +1166,14 @@ sim files delete <fileId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteFile](/api-reference/files/deleteFile).
+
 ### sim files versions delete
 
 Permanently delete a previous version of a file
 
+This permanently removes the version from history and schedules deletion of its stored content; storage cleanup may retry in the background.
+
 ```bash
 sim files versions delete <fileId> <version> [options]
 ```
@@ -1057,6 +1199,8 @@ sim files versions delete <fileId> <version> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteFileVersion](/api-reference/files/deleteFileVersion).
+
 ### sim files versions describe
 
 Show the metadata of one version of a file
@@ -1076,6 +1220,8 @@ sim files versions describe <fileId> <version>
 
 </CommandTable>
 
+API request and response schemas: [getFileVersion](/api-reference/files/getFileVersion).
+
 ### sim files versions list
 
 List the recorded versions of a file
@@ -1100,13 +1246,15 @@ sim files versions list <fileId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `version`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "version". Accepted values: `version`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
+API request and response schemas: [listFileVersions](/api-reference/files/listFileVersions).
+
 ### sim files versions read
 
 Read the text content of one version of a file as JSON or YAML
@@ -1138,6 +1286,8 @@ sim files versions read <fileId> <version> [options]
 
 </CommandTable>
 
+API request and response schemas: [readFileVersionText](/api-reference/files/readFileVersionText).
+
 ### sim files versions revert
 
 Make a previous version of a file current again
@@ -1164,10 +1314,12 @@ sim files versions revert <fileId> <version> [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--expected-current-version <value>` | No | Revert only while this is still the current version; otherwise the request fails with `409`. Omit to revert whatever is current. Collaborative edits and repeated workflow writes that fold into the current version keep its number, so prefer `expectedRevision` to guard content. |
-| `--expected-revision <value>` | No | Revert only while the file still holds the content this revision names, as returned by Get File Metadata or an earlier write; otherwise the request fails with `409`. Unlike a version number, it also catches edits that folded into the current version. |
+| `--expected-revision <value>` | No | Revert only while the file still holds the content this revision names, as returned by Get file metadata or an earlier write; otherwise the request fails with `409`. Unlike a version number, it also catches edits that folded into the current version. |
 
 </CommandTable>
 
+API request and response schemas: [revertFileVersion](/api-reference/files/revertFileVersion).
+
 ### sim files versions download
 
 Download the content of one version of a file
@@ -1198,6 +1350,8 @@ sim files versions download <fileId> <version> [options]
 
 </CommandTable>
 
+API request and response schemas: [downloadFileVersion](/api-reference/files/downloadFileVersion).
+
 ### sim files edit
 
 Apply one exact or anchor-based edit to a text file
@@ -1223,10 +1377,12 @@ sim files edit <fileId> [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--edit <json\|@file>` | Yes | One edit object: &#123;"mode":"search_replace","search":"old","content":"new","replaceAll":false&#125;, &#123;"mode":"replace_between","beforeAnchor":"start line","afterAnchor":"end line","content":"new"&#125;, &#123;"mode":"insert_after","anchor":"line","content":"new"&#125;, or &#123;"mode":"delete_between","startAnchor":"first line deleted","endAnchor":"ending line kept"&#125;. Anchored modes also accept occurrence starting at 1 (JSON, or @path / @- to read a file or stdin). |
-| `--expected-revision <value>` | No | Revision from Get File Metadata or an earlier write; the request is refused with `409` when the content moved on. |
+| `--expected-revision <value>` | No | Revision from Get file metadata or an earlier write; the request is refused with `409` when the content moved on. |
 
 </CommandTable>
 
+API request and response schemas: [editFileContent](/api-reference/files/editFileContent).
+
 ### sim files describe
 
 Show file metadata and sharing status
@@ -1255,6 +1411,8 @@ sim files describe <fileId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getFile](/api-reference/files/getFile).
+
 ### sim files share get
 
 Show a file’s share settings
@@ -1273,6 +1431,8 @@ sim files share get <fileId>
 
 </CommandTable>
 
+API request and response schemas: [getFileShare](/api-reference/files/getFileShare).
+
 ### sim files share set
 
 Enable or disable sharing for a file (OAuth login or personal API key required)
@@ -1299,14 +1459,16 @@ sim files share set <fileId> [options]
 | --- | --- | --- |
 | `--is-active <true\|false>` | Yes | Whether the share should resolve. Disabling preserves the token and the whole access configuration, so re-enabling restores the share as it was; enabling rewrites the credentials the resulting mode does not use. Accepted values: `true`, `false`. |
 | `--auth-type <value>` | No | How access to the share is gated. The stored mode is kept when omitted. Enabling `public` clears the stored password and empties `allowedEmails`; `password` empties `allowedEmails`; `email` and `sso` clear the stored password. Accepted values: `public`, `password`, `email`, `sso`. |
-| `--password <value>` | No | Password of 15 to 1024 characters for a password-gated share. Kept when omitted; enabling `password` with neither a supplied nor a stored password is a 400. Taken literally, except that a request from the Sim agent resolves a whole-value `&#123;&#123;ENV_VAR&#125;&#125;` reference to that variable before the rules apply. |
+| `--password <value>` | No | Password of 15 to 1024 characters for a password-gated share. Kept when omitted; enabling `password` with neither a supplied nor a stored password is a 400. Taken literally, except that a request from the Sim agent resolves a whole-value `{{ENV_VAR}}` reference to that variable before the rules apply. |
 | `--allowed-emails <value...>` | No | Allowed addresses or `@domain` patterns for email and SSO shares. Kept when omitted; enabling `email` or `sso` with an empty resulting list is a 400. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 
 </CommandTable>
 
+API request and response schemas: [upsertFileShare](/api-reference/files/upsertFileShare).
+
 ### sim files list
 
-List Files
+List files
 
 ```bash
 sim files list [options]
@@ -1323,12 +1485,14 @@ sim files list [options]
 | `--no-recursive` | No | Send --recursive as false. |
 | `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live files, `archived` for files a delete soft-deleted. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
 | `--search <value>` | No | Case-insensitive substring match against the file name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `size`, `uploadedAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "uploadedAt". Accepted values: `name`, `size`, `uploadedAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listFiles](/api-reference/files/listFiles).
+
 ### sim files move
 
 Move files into another folder
@@ -1350,6 +1514,8 @@ Also available as `sim files mv`.
 
 </CommandTable>
 
+API request and response schemas: [moveFileItems](/api-reference/files/moveFileItems).
+
 ### sim files read
 
 Read a file’s text content as JSON or YAML
@@ -1364,7 +1530,7 @@ sim files read <fileId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `fileId` | Yes | File identifier, or the file’s VFS path: `files/&lt;folder&gt;/&lt;name&gt;`, or `uploads/&lt;name&gt;` for a Chat upload. |
+| `fileId` | Yes | File identifier, or the file’s VFS path: `files/<folder>/<name>`, or `uploads/<name>` for a Chat upload. |
 
 </CommandTable>
 
@@ -1380,6 +1546,8 @@ sim files read <fileId> [options]
 
 </CommandTable>
 
+API request and response schemas: [readFileText](/api-reference/files/readFileText).
+
 ### sim files rename
 
 Rename a file
@@ -1408,6 +1576,8 @@ sim files rename <fileId> [options]
 
 </CommandTable>
 
+API request and response schemas: [renameFile](/api-reference/files/renameFile).
+
 ### sim files restore
 
 Restore an archived file
@@ -1426,9 +1596,11 @@ sim files restore <fileId>
 
 </CommandTable>
 
+API request and response schemas: [restoreFile](/api-reference/files/restoreFile).
+
 ### sim files search
 
-Search File Content
+Search file content
 
 ```bash
 sim files search [options]
@@ -1441,18 +1613,22 @@ sim files search [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--query <value>` | Yes | Regular expression, or exact text when `mode` is `exact`. |
-| `--mode <value>` | No | How `query` is read. Accepted values: `exact`, `regex`. |
-| `--max-results <value>` | No | Maximum matching lines to return. |
+| `--mode <value>` | No | How `query` is read. Defaults to "regex". Accepted values: `exact`, `regex`. |
+| `--max-results <value>` | No | Maximum matching lines to return. Defaults to 50. |
 | `--folder <value...>` | No | Folders to search, by path as shown in the app; omit to search the whole workspace (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `--include-subfolders` | No | Whether each folder scope includes nested folders; on by default. |
 | `--no-include-subfolders` | No | Send --include-subfolders as false. |
 
 </CommandTable>
 
+API request and response schemas: [searchFileContent](/api-reference/files/searchFileContent).
+
 ### sim files unzip
 
 Unzip an archive into a new folder beside it
 
+This writes every file in the archive into the workspace.
+
 ```bash
 sim files unzip <fileId> [options]
 ```
@@ -1477,6 +1653,8 @@ sim files unzip <fileId> [options]
 
 </CommandTable>
 
+API request and response schemas: [unzipFile](/api-reference/files/unzipFile).
+
 ### sim files set-content
 
 Replace a file’s contents
@@ -1501,12 +1679,14 @@ sim files set-content <fileId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--content <value>` | Yes | Complete replacement content for the file. The 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`. |
-| `--encoding <value>` | No | Content encoding. Accepted values: `utf-8`, `base64`. |
-| `--expected-revision <value>` | No | Revision from Get File Metadata or an earlier write; the request is refused with `409` when the content moved on. |
+| `--content <value>` | Yes | Complete replacement content for the file. The complete JSON request is capped at 10 MiB, including UTF-8 encoding, escaping, base64, and the envelope. The separate decoded-file limit is 50 MiB. Small patches can edit a larger stored text file without sending its full content. |
+| `--encoding <value>` | No | Content encoding. Defaults to "utf-8". Accepted values: `utf-8`, `base64`. |
+| `--expected-revision <value>` | No | Revision from Get file metadata or an earlier write; the request is refused with `409` when the content moved on. |
 
 </CommandTable>
 
+API request and response schemas: [updateFileContent](/api-reference/files/updateFileContent).
+
 ### sim files upload
 
 Upload a file to the workspace
@@ -1536,6 +1716,8 @@ sim files upload <path> [options]
 
 </CommandTable>
 
+API request and response schemas: [createFileUpload](/api-reference/files/createFileUpload), [createFileUploadPartUrls](/api-reference/files/createFileUploadPartUrls), [completeFileUpload](/api-reference/files/completeFileUpload), [abortFileUpload](/api-reference/files/abortFileUpload).
+
 ### sim files get
 
 Download a file’s content to stdout or a local file
@@ -1565,6 +1747,8 @@ sim files get <fileId> [options]
 
 </CommandTable>
 
+API request and response schemas: [downloadFile](/api-reference/files/downloadFile).
+
 ### sim files ls
 
 List file resources and child folders together
@@ -1594,6 +1778,8 @@ sim files ls [path] [options]
 
 </CommandTable>
 
+API request and response schemas: [listFiles](/api-reference/files/listFiles), [listFileFolders](/api-reference/files/listFilesFolders).
+
 ### sim files mkdir
 
 Create a file directory at a path
@@ -1612,8 +1798,12 @@ sim files mkdir <path>
 
 </CommandTable>
 
+API request and response schemas: [createFileFolder](/api-reference/files/createFilesFolder).
+
 ## sim knowledge
 
+Manage knowledge bases, indexed documents, search, tags, and connector syncs.
+
 Also spelled `sim kb`.
 
 ### sim knowledge from-workspace-files create
@@ -1640,10 +1830,12 @@ sim knowledge from-workspace-files create <knowledgeBaseId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--file <value...>` | Yes | Workspace file ID or key (repeatable) (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--file <value...>` | Yes | Workspace file ID or canonical files/&lt;folder&gt;/&lt;name&gt; path (repeatable) (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 
 </CommandTable>
 
+API request and response schemas: [addWorkspaceFilesToKnowledgeBase](/api-reference/knowledge-bases/addWorkspaceFilesToKnowledgeBase).
+
 ### sim knowledge tags save
 
 Declare the tag definitions a knowledge base needs (OAuth login or personal API key required)
@@ -1672,9 +1864,11 @@ sim knowledge tags save <knowledgeBaseId> [options]
 
 </CommandTable>
 
+API request and response schemas: [bulkSaveKnowledgeTagDefinitions](/api-reference/knowledge-bases/bulkSaveKnowledgeTagDefinitions).
+
 ### sim knowledge tags create
 
-Create Tag (OAuth login or personal API key required)
+Create tag (OAuth login or personal API key required)
 
 ```bash
 sim knowledge tags create <knowledgeBaseId> [options]
@@ -1702,9 +1896,13 @@ sim knowledge tags create <knowledgeBaseId> [options]
 
 </CommandTable>
 
+API request and response schemas: [createKnowledgeTag](/api-reference/knowledge-bases/createKnowledgeTag).
+
 ### sim knowledge tags delete
 
-Delete Tag (OAuth login or personal API key required)
+Delete tag (OAuth login or personal API key required)
+
+This deletes the tag and clears its values on every document and chunk.
 
 ```bash
 sim knowledge tags delete <knowledgeBaseId> <tagId> [options]
@@ -1731,10 +1929,14 @@ sim knowledge tags delete <knowledgeBaseId> <tagId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteKnowledgeTag](/api-reference/knowledge-bases/deleteKnowledgeTag).
+
 ### sim knowledge tags cleanup
 
 Remove tag definitions no document still uses (OAuth login or personal API key required)
 
+This deletes every tag definition no document still uses. Their slots become free for a different field.
+
 ```bash
 sim knowledge tags cleanup <knowledgeBaseId> [options]
 ```
@@ -1761,6 +1963,8 @@ sim knowledge tags cleanup <knowledgeBaseId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteKnowledgeTagDefinitions](/api-reference/knowledge-bases/deleteKnowledgeTagDefinitions).
+
 ### sim knowledge tags next-slot
 
 Show which tag slot a create would take for a field type (OAuth login or personal API key required)
@@ -1789,9 +1993,11 @@ sim knowledge tags next-slot <knowledgeBaseId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getNextKnowledgeTagSlot](/api-reference/knowledge-bases/getNextKnowledgeTagSlot).
+
 ### sim knowledge tags list
 
-List Tags
+List tags
 
 ```bash
 sim knowledge tags list <knowledgeBaseId>
@@ -1807,6 +2013,8 @@ sim knowledge tags list <knowledgeBaseId>
 
 </CommandTable>
 
+API request and response schemas: [listKnowledgeTags](/api-reference/knowledge-bases/listKnowledgeTags).
+
 ### sim knowledge tags usage
 
 Show how many documents and chunks carry each tag (OAuth login or personal API key required)
@@ -1825,9 +2033,11 @@ sim knowledge tags usage <knowledgeBaseId>
 
 </CommandTable>
 
+API request and response schemas: [listKnowledgeTagUsage](/api-reference/knowledge-bases/listKnowledgeTagUsage).
+
 ### sim knowledge tags update
 
-Update Tag (OAuth login or personal API key required)
+Update tag (OAuth login or personal API key required)
 
 ```bash
 sim knowledge tags update <knowledgeBaseId> <tagId> [options]
@@ -1855,10 +2065,14 @@ sim knowledge tags update <knowledgeBaseId> <tagId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateKnowledgeTag](/api-reference/knowledge-bases/updateKnowledgeTag).
+
 ### sim knowledge chunks batch-update
 
 Enable, disable, or delete many chunks at once (OAuth login or personal API key required)
 
+This applies --operation to every named chunk; with --operation delete it deletes them and their embeddings, which cannot be undone.
+
 ```bash
 sim knowledge chunks batch-update <knowledgeBaseId> <documentId> [options]
 ```
@@ -1886,9 +2100,11 @@ sim knowledge chunks batch-update <knowledgeBaseId> <documentId> [options]
 
 </CommandTable>
 
+API request and response schemas: [bulkUpdateKnowledgeChunks](/api-reference/knowledge-bases/bulkUpdateKnowledgeChunks).
+
 ### sim knowledge chunks create
 
-Create Chunk (OAuth login or personal API key required)
+Create chunk (OAuth login or personal API key required)
 
 ```bash
 sim knowledge chunks create <knowledgeBaseId> <documentId> [options]
@@ -1911,15 +2127,19 @@ sim knowledge chunks create <knowledgeBaseId> <documentId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--content <value>` | Yes | Text to embed. It is embedded on write, so the chunk is searchable immediately. |
-| `--enabled` | No | Whether the new chunk participates in search. |
+| `--content <value>` | Yes | Text embedded before the response. Search includes it when the chunk and document are enabled and the document has completed processing. |
+| `--enabled` | No | Whether the new chunk participates in search. Defaults to true. |
 | `--no-enabled` | No | Send --enabled as false. |
 
 </CommandTable>
 
+API request and response schemas: [createKnowledgeChunk](/api-reference/knowledge-bases/createKnowledgeChunk).
+
 ### sim knowledge chunks delete
 
-Delete Chunk (OAuth login or personal API key required)
+Delete chunk (OAuth login or personal API key required)
+
+This deletes the chunk and its embedding.
 
 ```bash
 sim knowledge chunks delete <knowledgeBaseId> <documentId> <chunkId> [options]
@@ -1947,9 +2167,11 @@ sim knowledge chunks delete <knowledgeBaseId> <documentId> <chunkId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteKnowledgeChunk](/api-reference/knowledge-bases/deleteKnowledgeChunk).
+
 ### sim knowledge chunks get
 
-Get Chunk (OAuth login or personal API key required)
+Get chunk (OAuth login or personal API key required)
 
 ```bash
 sim knowledge chunks get <knowledgeBaseId> <documentId> <chunkId>
@@ -1967,9 +2189,11 @@ sim knowledge chunks get <knowledgeBaseId> <documentId> <chunkId>
 
 </CommandTable>
 
+API request and response schemas: [getKnowledgeChunk](/api-reference/knowledge-bases/getKnowledgeChunk).
+
 ### sim knowledge chunks list
 
-List Chunks (OAuth login or personal API key required)
+List chunks (OAuth login or personal API key required)
 
 ```bash
 sim knowledge chunks list <knowledgeBaseId> <documentId> [options]
@@ -1993,17 +2217,19 @@ sim knowledge chunks list <knowledgeBaseId> <documentId> [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--search <value>` | No | Case-insensitive substring match against chunk content. |
-| `--enabled <value>` | No | Restrict to enabled or disabled chunks. `all` returns both. Accepted values: `true`, `false`, `all`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `chunkIndex`, `tokenCount`, `enabled`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--enabled <value>` | No | Restrict to enabled or disabled chunks. `all` returns both. Defaults to "all". Accepted values: `true`, `false`, `all`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "chunkIndex". Accepted values: `chunkIndex`, `tokenCount`, `enabled`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
+API request and response schemas: [listKnowledgeChunks](/api-reference/knowledge-bases/listKnowledgeChunks).
+
 ### sim knowledge chunks update
 
-Update Chunk (OAuth login or personal API key required)
+Update chunk (OAuth login or personal API key required)
 
 ```bash
 sim knowledge chunks update <knowledgeBaseId> <documentId> <chunkId> [options]
@@ -2033,6 +2259,8 @@ sim knowledge chunks update <knowledgeBaseId> <documentId> <chunkId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateKnowledgeChunk](/api-reference/knowledge-bases/updateKnowledgeChunk).
+
 ### sim knowledge documents batch-update
 
 Enable or disable every matching document (OAuth login or personal API key required)
@@ -2064,10 +2292,14 @@ sim knowledge documents batch-update <knowledgeBaseId> [options]
 
 </CommandTable>
 
+API request and response schemas: [bulkUpdateKnowledgeDocuments](/api-reference/knowledge-bases/bulkUpdateKnowledgeDocuments).
+
 ### sim knowledge documents delete
 
 Delete a document from a knowledge base
 
+This deletes the document and its embeddings.
+
 ```bash
 sim knowledge documents delete <knowledgeBaseId> <documentId> [options]
 ```
@@ -2093,9 +2325,11 @@ sim knowledge documents delete <knowledgeBaseId> <documentId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteKnowledgeDocument](/api-reference/knowledge-bases/deleteKnowledgeDocument).
+
 ### sim knowledge documents get
 
-Get Document
+Get document
 
 ```bash
 sim knowledge documents get <knowledgeBaseId> <documentId>
@@ -2112,9 +2346,11 @@ sim knowledge documents get <knowledgeBaseId> <documentId>
 
 </CommandTable>
 
+API request and response schemas: [getKnowledgeDocument](/api-reference/knowledge-bases/getKnowledgeDocument).
+
 ### sim knowledge documents list
 
-List Documents
+List documents
 
 ```bash
 sim knowledge documents list <knowledgeBaseId> [options]
@@ -2138,17 +2374,19 @@ sim knowledge documents list <knowledgeBaseId> [options]
 | --- | --- | --- |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--search <value>` | No | Case-insensitive substring match against the document filename. |
-| `--enabled-filter <value>` | No | Filter by whether documents are enabled for search. Accepted values: `all`, `enabled`, `disabled`. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `filename` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `filename`, `fileSize`, `tokenCount`, `chunkCount`, `uploadedAt`, `processingStatus`, `enabled`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--enabled-filter <value>` | No | Filter by whether documents are enabled for search. Defaults to "all". Accepted values: `all`, `enabled`, `disabled`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `filename`. Defaults to "uploadedAt". Accepted values: `filename`, `fileSize`, `tokenCount`, `chunkCount`, `uploadedAt`, `processingStatus`, `enabled`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--tag-filters <value>` | No | A JSON-encoded array of at most 10 tag filters, using the same display-name shape as knowledge search: `[&#123;"tagName":"category","operator":"eq","value":"billing"&#125;]`. Every filter must hold, including two that name the same tag. A name that is not defined in this knowledge base is rejected, never ignored. |
+| `--tag-filters <value>` | No | A JSON-encoded array of at most 10 tag filters, using the same display-name shape as knowledge search: `[{"tagName":"category","operator":"eq","value":"billing"}]`. Every filter must hold, including two that name the same tag. A name that is not defined in this knowledge base is rejected, never ignored. |
 
 </CommandTable>
 
+API request and response schemas: [listKnowledgeDocuments](/api-reference/knowledge-bases/listKnowledgeDocuments).
+
 ### sim knowledge documents update
 
-Update Document (OAuth login or personal API key required)
+Update document (OAuth login or personal API key required)
 
 ```bash
 sim knowledge documents update <knowledgeBaseId> <documentId> [options]
@@ -2198,6 +2436,8 @@ sim knowledge documents update <knowledgeBaseId> <documentId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateKnowledgeDocument](/api-reference/knowledge-bases/updateKnowledgeDocument).
+
 ### sim knowledge documents upload
 
 Upload a document to a knowledge base
@@ -2230,9 +2470,11 @@ sim knowledge documents upload <knowledgeBaseId> <path> [options]
 
 </CommandTable>
 
+API request and response schemas: [createKnowledgeDocumentUpload](/api-reference/knowledge-bases/createKnowledgeDocumentUpload), [createKnowledgeDocumentUploadPartUrls](/api-reference/knowledge-bases/createKnowledgeDocumentUploadPartUrls), [completeKnowledgeDocumentUpload](/api-reference/knowledge-bases/completeKnowledgeDocumentUpload), [abortKnowledgeDocumentUpload](/api-reference/knowledge-bases/abortKnowledgeDocumentUpload).
+
 ### sim knowledge create
 
-Create Knowledge Base
+Create knowledge base
 
 ```bash
 sim knowledge create [options]
@@ -2251,9 +2493,11 @@ sim knowledge create [options]
 
 </CommandTable>
 
+API request and response schemas: [createKnowledgeBase](/api-reference/knowledge-bases/createKnowledgeBase).
+
 ### sim knowledge connectors create
 
-Create Knowledge Connector (OAuth login or personal API key required)
+Create knowledge connector (OAuth login or personal API key required)
 
 ```bash
 sim knowledge connectors create <knowledgeBaseId> [options]
@@ -2277,15 +2521,19 @@ sim knowledge connectors create <knowledgeBaseId> [options]
 | --- | --- | --- |
 | `--connector-type <value>` | Yes | Registered connector type. |
 | `--credential-id <value>` | No | OAuth credential identifier for connector types whose `auth.mode` is `oauth` (see connector types); omit it for `apiKey` connectors. |
-| `--api-key <value>` | No | Write-only API key for connector types whose `auth.mode` is `apiKey` (see connector types), or a personal access token for an OAuth connector that also accepts one, such as GitHub. Send it instead of `credentialId`. Pass a raw key, or a secret reference written as the whole value `&#123;&#123;SECRET_NAME&#125;&#125;`, which the server resolves; `$SECRET_NAME` is not a reference. |
+| `--api-key <value>` | No | Write-only API key for connector types whose `auth.mode` is `apiKey` (see connector types), or a personal access token for an OAuth connector that also accepts one, such as GitHub. Send it instead of `credentialId`. Pass a raw key, or a secret reference written as the whole value `{{SECRET_NAME}}`, which the server resolves; `$SECRET_NAME` is not a reference. |
 | `--source-config <json\|@file>` | Yes | Connector-specific source selection and filtering configuration. (JSON, or @path / @- to read a file or stdin). |
-| `--sync-interval-minutes <value>` | No | Scheduled synchronization interval in minutes; zero disables scheduling. |
+| `--sync-interval-minutes <value>` | No | Scheduled synchronization interval in minutes; zero disables scheduling. Defaults to 1440. |
 
 </CommandTable>
 
+API request and response schemas: [createKnowledgeConnector](/api-reference/knowledge-bases/createKnowledgeConnector).
+
 ### sim knowledge connectors delete
 
-Delete Knowledge Connector (OAuth login or personal API key required)
+Delete knowledge connector (OAuth login or personal API key required)
+
+This deletes the connector; --delete-documents also deletes its synchronized documents.
 
 ```bash
 sim knowledge connectors delete <knowledgeBaseId> <connectorId> [options]
@@ -2314,9 +2562,11 @@ sim knowledge connectors delete <knowledgeBaseId> <connectorId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteKnowledgeConnector](/api-reference/knowledge-bases/deleteKnowledgeConnector).
+
 ### sim knowledge connectors get
 
-Get Knowledge Connector (OAuth login or personal API key required)
+Get knowledge connector (OAuth login or personal API key required)
 
 ```bash
 sim knowledge connectors get <knowledgeBaseId> <connectorId>
@@ -2333,9 +2583,11 @@ sim knowledge connectors get <knowledgeBaseId> <connectorId>
 
 </CommandTable>
 
+API request and response schemas: [getKnowledgeConnector](/api-reference/knowledge-bases/getKnowledgeConnector).
+
 ### sim knowledge connectors documents list
 
-List Knowledge Connector Documents (OAuth login or personal API key required)
+List knowledge connector documents (OAuth login or personal API key required)
 
 ```bash
 sim knowledge connectors documents list <knowledgeBaseId> <connectorId> [options]
@@ -2365,9 +2617,11 @@ sim knowledge connectors documents list <knowledgeBaseId> <connectorId> [options
 
 </CommandTable>
 
+API request and response schemas: [listKnowledgeConnectorDocuments](/api-reference/knowledge-bases/listKnowledgeConnectorDocuments).
+
 ### sim knowledge connectors documents update
 
-Update Knowledge Connector Documents (OAuth login or personal API key required)
+Update knowledge connector documents (OAuth login or personal API key required)
 
 ```bash
 sim knowledge connectors documents update <knowledgeBaseId> <connectorId> [options]
@@ -2395,9 +2649,11 @@ sim knowledge connectors documents update <knowledgeBaseId> <connectorId> [optio
 
 </CommandTable>
 
+API request and response schemas: [updateKnowledgeConnectorDocuments](/api-reference/knowledge-bases/updateKnowledgeConnectorDocuments).
+
 ### sim knowledge connectors list
 
-List Knowledge Connectors (OAuth login or personal API key required)
+List knowledge connectors (OAuth login or personal API key required)
 
 ```bash
 sim knowledge connectors list <knowledgeBaseId> [options]
@@ -2419,12 +2675,14 @@ sim knowledge connectors list <knowledgeBaseId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `connectorType`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `connectorType`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listKnowledgeConnectors](/api-reference/knowledge-bases/listKnowledgeConnectors).
+
 ### sim knowledge connectors sync
 
 Queue a knowledge connector synchronization (OAuth login or personal API key required)
@@ -2450,14 +2708,16 @@ sim knowledge connectors sync <knowledgeBaseId> <connectorId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--rehydrate` | No | Re-fetch and re-index every existing connector document. |
+| `--rehydrate` | No | Re-fetch and re-index every existing connector document. Defaults to false. |
 | `--no-rehydrate` | No | Send --rehydrate as false. |
 
 </CommandTable>
 
+API request and response schemas: [syncKnowledgeConnector](/api-reference/knowledge-bases/syncKnowledgeConnector).
+
 ### sim knowledge connectors update
 
-Update Knowledge Connector (OAuth login or personal API key required)
+Update knowledge connector (OAuth login or personal API key required)
 
 ```bash
 sim knowledge connectors update <knowledgeBaseId> <connectorId> [options]
@@ -2486,6 +2746,8 @@ sim knowledge connectors update <knowledgeBaseId> <connectorId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateKnowledgeConnector](/api-reference/knowledge-bases/updateKnowledgeConnector).
+
 ### sim knowledge folders create
 
 Create a knowledge folder at a path
@@ -2504,9 +2766,13 @@ sim knowledge folders create <path>
 
 </CommandTable>
 
+API request and response schemas: [createKnowledgeFolder](/api-reference/knowledge-bases/createKnowledgeFolder).
+
 ### sim knowledge folders delete
 
-Delete Folder
+Delete folder
+
+This archives the knowledge folder and, when recursive, everything inside it.
 
 ```bash
 sim knowledge folders delete <path> [options]
@@ -2528,11 +2794,13 @@ sim knowledge folders delete <path> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--recursive` | No | Delete the folder and its descendants. |
+| `--recursive` | No | Archive the folder and its descendants. Defaults to "false". |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
+API request and response schemas: [deleteKnowledgeFolder](/api-reference/knowledge-bases/deleteKnowledgeFolder).
+
 ### sim knowledge folders list
 
 List knowledge folders
@@ -2551,11 +2819,13 @@ Also available as `sim knowledge folders ls`.
 | --- | --- | --- |
 | `--parent <value>` | No | Direct parent folder path. |
 | `--search <value>` | No | Case-insensitive substring match against the folder name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
+API request and response schemas: [listKnowledgeFolders](/api-reference/knowledge-bases/listKnowledgeFolders).
+
 ### sim knowledge folders move
 
 Rename or move a knowledge folder
@@ -2577,9 +2847,13 @@ Also available as `sim knowledge folders mv`.
 
 </CommandTable>
 
+API request and response schemas: [relocateKnowledgeFolder](/api-reference/knowledge-bases/relocateKnowledgeFolder).
+
 ### sim knowledge delete
 
-Delete Knowledge Base
+Delete knowledge base
+
+This archives the knowledge base and every document in it; restore with `knowledge restore`.
 
 ```bash
 sim knowledge delete <knowledgeBaseId> [options]
@@ -2605,9 +2879,11 @@ sim knowledge delete <knowledgeBaseId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteKnowledgeBase](/api-reference/knowledge-bases/deleteKnowledgeBase).
+
 ### sim knowledge get
 
-Get Knowledge Base
+Get knowledge base
 
 ```bash
 sim knowledge get <knowledgeBaseId>
@@ -2623,9 +2899,11 @@ sim knowledge get <knowledgeBaseId>
 
 </CommandTable>
 
+API request and response schemas: [getKnowledgeBase](/api-reference/knowledge-bases/getKnowledgeBase).
+
 ### sim knowledge list
 
-List Knowledge Bases
+List knowledge bases
 
 ```bash
 sim knowledge list [options]
@@ -2637,15 +2915,17 @@ sim knowledge list [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--scope <value>` | No | Lifecycle scope: active or archived knowledge bases. Use Restore Knowledge Base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches. Accepted values: `active`, `archived`. |
+| `--scope <value>` | No | Lifecycle scope: active or archived knowledge bases. Use Restore knowledge base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches. Defaults to "active". Accepted values: `active`, `archived`. |
 | `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 | `--search <value>` | No | Case-insensitive substring match against the resource name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listKnowledgeBases](/api-reference/knowledge-bases/listKnowledgeBases).
+
 ### sim knowledge restore
 
 Restore an archived knowledge base
@@ -2664,9 +2944,11 @@ sim knowledge restore <knowledgeBaseId>
 
 </CommandTable>
 
+API request and response schemas: [restoreKnowledgeBase](/api-reference/knowledge-bases/restoreKnowledgeBase).
+
 ### sim knowledge search
 
-Search Knowledge
+Search knowledge
 
 ```bash
 sim knowledge search [options]
@@ -2680,19 +2962,21 @@ sim knowledge search [options]
 | --- | --- | --- |
 | `--kb <value...>` | Yes | Knowledge base ID (repeatable) (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `--query <value>` | No | Text to search for. |
-| `--top-k <value>` | No | Maximum number of search results to return. Must be a whole number between 1 and 100. |
+| `--top-k <value>` | No | Maximum number of search results to return. Must be a whole number between 1 and 100. Defaults to 10. |
 | `--tag-filters <json\|@file>` | No | Tag filters as [&#123;"tagName":"...","operator":"...","value":"..."&#125;] (JSON, or @path / @- to read a file or stdin). |
 | `--search-mode <value>` | No | Search algorithm. Accepted values: `vector`, `hybrid`. |
-| `--reranker-enabled` | No | Re-order retrieved chunks with a reranking model before truncating to `topK`. Ignored for a tag-only search, and billed as an additional search unit. Reranking is best-effort — a provider failure falls back to vector ordering, so check `rerankerStatus` on the response. |
+| `--reranker-enabled` | No | Reorder retrieved chunks with a reranking model before truncating to `topK`. Ignored for tag-only searches. A completed reranking call adds a search unit. If reranking is unavailable, results keep their retrieval order; check `rerankerStatus`. |
 | `--no-reranker-enabled` | No | Send --reranker-enabled as false. |
 | `--reranker-model <value>` | No | Reranking model to use when `rerankerEnabled` is true. Defaults to `rerank-v4.0-fast`. Accepted values: `rerank-v4.0-pro`, `rerank-v4.0-fast`, `rerank-v3.5`. |
 | `--reranker-input-count <value>` | No | How many candidate chunks to retrieve before reranking. Defaults to four times `topK`, capped at 100. A larger pool costs more retrieval work but gives the reranker more to choose from. |
 
 </CommandTable>
 
+API request and response schemas: [searchKnowledge](/api-reference/knowledge-bases/searchKnowledge).
+
 ### sim knowledge update
 
-Update Knowledge Base
+Update knowledge base
 
 ```bash
 sim knowledge update <knowledgeBaseId> [options]
@@ -2721,6 +3005,8 @@ sim knowledge update <knowledgeBaseId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateKnowledgeBase](/api-reference/knowledge-bases/updateKnowledgeBase).
+
 ### sim knowledge mv
 
 Move a knowledge base to a folder
@@ -2740,6 +3026,8 @@ sim knowledge mv <knowledgeBaseId> <folder>
 
 </CommandTable>
 
+API request and response schemas: [updateKnowledgeBase](/api-reference/knowledge-bases/updateKnowledgeBase).
+
 ### sim knowledge export
 
 Export a knowledge base as a .simkb.zip bundle
@@ -2770,6 +3058,8 @@ sim knowledge export <knowledgeBaseId> [options]
 
 </CommandTable>
 
+API request and response schemas: [exportKnowledgeBase](/api-reference/knowledge-bases/exportKnowledgeBase).
+
 ### sim knowledge ls
 
 List knowledge resources and child folders together
@@ -2799,6 +3089,8 @@ sim knowledge ls [path] [options]
 
 </CommandTable>
 
+API request and response schemas: [listKnowledgeBases](/api-reference/knowledge-bases/listKnowledgeBases), [listKnowledgeFolders](/api-reference/knowledge-bases/listKnowledgeFolders).
+
 ### sim knowledge mkdir
 
 Create a knowledge directory at a path
@@ -2817,8 +3109,12 @@ sim knowledge mkdir <path>
 
 </CommandTable>
 
+API request and response schemas: [createKnowledgeFolder](/api-reference/knowledge-bases/createKnowledgeFolder).
+
 ## sim logs
 
+Read run diagnostics, follow new runs, and summarize failures and latency.
+
 Also spelled `sim log`.
 
 ### sim logs get
@@ -2851,6 +3147,8 @@ sim logs get <runId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getLog](/api-reference/logs/getLog).
+
 ### sim logs stats
 
 Summarize run counts, failures and latency over a window
@@ -2873,11 +3171,13 @@ sim logs stats [options]
 | `--no-include-handled-errors` | No | Send --include-handled-errors as false. |
 | `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
 | `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
-| `--segment-count <value>` | No | Number of equal time buckets to divide the window into, from 1 to 500. It is the ceiling on how many buckets a series carries: with `includeEmpty=true` exactly this many are returned, otherwise only the buckets holding at least one run. Buckets are never narrower than one minute, so on a short window the series extends past the end of the window rather than being compressed, and the trailing buckets are empty. |
+| `--segment-count <value>` | No | Number of equal time buckets to divide the window into, from 1 to 500. It is the ceiling on how many buckets a series carries: with `includeEmpty=true` exactly this many are returned, otherwise only the buckets holding at least one run. Buckets are never narrower than one minute, so on a short window the series extends past the end of the window rather than being compressed, and the trailing buckets are empty. Defaults to 72. |
 | `--include-empty <value>` | No | Whether buckets with no runs are included in every series. Off by default, so each series carries only the buckets that hold at least one run; set it to publish exactly `segmentCount` buckets per series, empty ones included. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected. Accepted values: `true`, `1`, `yes`, `on`, `y`, `enabled`, `false`, `0`, `no`, `off`, `n`, `disabled`. |
 
 </CommandTable>
 
+API request and response schemas: [getLogStats](/api-reference/logs/getLogStats).
+
 ### sim logs list
 
 List run logs, such as failed or errored runs, by workflow, trigger or time
@@ -2914,12 +3214,14 @@ sim logs list [options]
 | `--include-job-runs` | No | Include Chat and Sim-agent jobs alongside workflow runs. Jobs use `kind: "job"` and have no workflow or cost ledger. Workflow, folder, model, or status filters exclude jobs. This option is valid only when sorting by `startedAt`. |
 | `--no-include-job-runs` | No | Send --include-job-runs as false. |
 | `--run-id <value>` | No | Exact run identifier to match. |
-| `--sort-by <value>` | No | Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs sort before recorded values in ascending order and after them in descending order. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected when job runs are included. Accepted values: `startedAt`, `durationMs`, `cost`, `status`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. `durationMs` and `cost` are null until a run settles; those runs sort before recorded values in ascending order and after them in descending order. Only `startedAt` can order Chat and Sim-agent job runs, so any other value is rejected when job runs are included. Defaults to "startedAt". Accepted values: `startedAt`, `durationMs`, `cost`, `status`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--folder <value...>` | No | Folder path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 
 </CommandTable>
 
+API request and response schemas: [listLogs](/api-reference/logs/listLogs).
+
 ### sim logs follow
 
 Watch runs live as they arrive, printing each new run once
@@ -2944,13 +3246,29 @@ sim logs follow [options]
 
 </CommandTable>
 
+Each run prints once, when it is first seen, so its status is the status it had at that moment. With --output json every run is a JSON object on its own line (JSONL) rather than a member of an array, because a follow never ends and so can never close one; --output yaml emits a --- separated document stream. Progress and retries go to stderr, leaving stdout a clean stream of rows. Ctrl-C stops the follow.
+
+**Examples**
+
+```bash
+sim logs follow --level error
+sim logs follow --workflow 00000000-0000-4000-8000-000000000000 -n 0
+sim --output json logs follow | jq -r '.runId'
+```
+
+API request and response schemas: [listLogs](/api-reference/logs/listLogs).
+
 ## sim mcp-servers
 
+Connect external Model Context Protocol (MCP) servers so workflows can use their tools.
+
+To serve Sim workflows to MCP clients instead, use [workflow MCP servers](/cli/workflow-mcp-servers).
+
 Also spelled `sim mcp-server`.
 
 ### sim mcp-servers create
 
-Create MCP Server
+Create MCP server
 
 ```bash
 sim mcp-servers create [options]
@@ -2965,8 +3283,8 @@ sim mcp-servers create [options]
 | `--name <value>` | Yes | Server display name. |
 | `--description <value>` | No | Optional server description. |
 | `--transport <value>` | No | Transport protocol. Defaults to `streamable-http` on creation. Accepted values: `streamable-http`. |
-| `--url <value>` | Yes | Absolute HTTP or HTTPS endpoint URL without `&#123;&#123;ENV_VAR&#125;&#125;` references. It determines server identity and is immutable: delete and recreate the server to change endpoints. |
-| `--auth-type <value>` | No | Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server does not advertise OAuth. A server publishing RFC 9728 metadata is therefore stored as `oauth`, and headers configured afterwards will not authenticate — send this field explicitly to pin the method. Accepted values: `none`, `headers`, `oauth`. |
+| `--url <value>` | Yes | Absolute HTTP or HTTPS endpoint URL without `{{ENV_VAR}}` references. It determines server identity and is immutable: delete and recreate the server to change endpoints. |
+| `--auth-type <value>` | No | Authentication method. On creation, omission without `headers` probes once: an OAuth challenge selects `oauth`, an unauthenticated success selects `none`, and other outcomes fall back to `headers`. An OAuth client ID selects `oauth` when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method. Accepted values: `none`, `headers`, `oauth`. |
 | `--headers <json\|@file>` | No | Write-only request headers sent to the server. Replaced wholesale rather than merged on update: sending this field drops every stored header it does not repeat. (JSON, or @path / @- to read a file or stdin). |
 | `--timeout <value>` | No | Per-request timeout in milliseconds. Defaults to 30000 on creation. |
 | `--retries <value>` | No | Number of retries per request. Defaults to 3 on creation. |
@@ -2977,9 +3295,13 @@ sim mcp-servers create [options]
 
 </CommandTable>
 
+API request and response schemas: [createMcpServer](/api-reference/mcp-servers/createMcpServer).
+
 ### sim mcp-servers delete
 
-Delete MCP Server
+Delete MCP server
+
+This removes the MCP server and the tools it provides.
 
 ```bash
 sim mcp-servers delete <mcpServerId> [options]
@@ -3005,9 +3327,11 @@ sim mcp-servers delete <mcpServerId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteMcpServer](/api-reference/mcp-servers/deleteMcpServer).
+
 ### sim mcp-servers get
 
-Get MCP Server
+Get MCP server
 
 ```bash
 sim mcp-servers get <mcpServerId>
@@ -3023,9 +3347,11 @@ sim mcp-servers get <mcpServerId>
 
 </CommandTable>
 
+API request and response schemas: [getMcpServer](/api-reference/mcp-servers/getMcpServer).
+
 ### sim mcp-servers list
 
-List MCP Servers
+List MCP servers
 
 ```bash
 sim mcp-servers list [options]
@@ -3038,15 +3364,17 @@ sim mcp-servers list [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--search <value>` | No | Case-insensitive substring match against the server name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listMcpServers](/api-reference/mcp-servers/listMcpServers).
+
 ### sim mcp-servers tools list
 
-List MCP Server Tools (OAuth login or personal API key required)
+List MCP server tools (OAuth login or personal API key required)
 
 ```bash
 sim mcp-servers tools list <mcpServerId> [options]
@@ -3073,9 +3401,11 @@ sim mcp-servers tools list <mcpServerId> [options]
 
 </CommandTable>
 
+API request and response schemas: [listMcpServerTools](/api-reference/mcp-servers/listMcpServerTools).
+
 ### sim mcp-servers update
 
-Update MCP Server
+Update MCP server
 
 ```bash
 sim mcp-servers update <mcpServerId> [options]
@@ -3101,7 +3431,7 @@ sim mcp-servers update <mcpServerId> [options]
 | `--description <value>` | No | Optional server description. |
 | `--transport <value>` | No | Transport protocol. Defaults to `streamable-http` on creation. Accepted values: `streamable-http`. |
 | `--url <value>` | No | Immutable server URL. When provided, it must equal the current URL; use delete and create to change endpoints. |
-| `--auth-type <value>` | No | Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server does not advertise OAuth. A server publishing RFC 9728 metadata is therefore stored as `oauth`, and headers configured afterwards will not authenticate — send this field explicitly to pin the method. Accepted values: `none`, `headers`, `oauth`. |
+| `--auth-type <value>` | No | Authentication method. On creation, omission without `headers` probes once: an OAuth challenge selects `oauth`, an unauthenticated success selects `none`, and other outcomes fall back to `headers`. An OAuth client ID selects `oauth` when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method. Accepted values: `none`, `headers`, `oauth`. |
 | `--headers <json\|@file>` | No | Write-only request headers sent to the server. Replaced wholesale rather than merged on update: sending this field drops every stored header it does not repeat. (JSON, or @path / @- to read a file or stdin). |
 | `--timeout <value>` | No | Per-request timeout in milliseconds. Defaults to 30000 on creation. |
 | `--retries <value>` | No | Number of retries per request. Defaults to 3 on creation. |
@@ -3112,21 +3442,29 @@ sim mcp-servers update <mcpServerId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateMcpServer](/api-reference/mcp-servers/updateMcpServer).
+
 ## sim meta
 
+Inspect API availability and the calling credential’s type and expiry.
+
 ### sim meta status
 
-Show what this API supports and which limits apply
+Show API availability and the calling credential’s type and expiry
 
 ```bash
 sim meta status
 ```
 
+API request and response schemas: [getMeta](/api-reference/meta/getApiMeta).
+
 ## sim organizations
 
+Manage organization membership, invitations, usage, access requests, and SSO.
+
 ### sim organizations domains add
 
-Add Organization Domain (OAuth login or personal API key required)
+Add organization domain (OAuth login or personal API key required)
 
 ```bash
 sim organizations domains add [options]
@@ -3143,9 +3481,11 @@ sim organizations domains add [options]
 
 </CommandTable>
 
+API request and response schemas: [addOrganizationDomain](/api-reference/organizations/addOrganizationDomain).
+
 ### sim organizations domains list
 
-List Organization Domains (OAuth login or personal API key required)
+List organization domains (OAuth login or personal API key required)
 
 ```bash
 sim organizations domains list [options]
@@ -3159,14 +3499,18 @@ sim organizations domains list [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `domain`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "domain". Accepted values: `domain`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
+API request and response schemas: [listOrganizationDomains](/api-reference/organizations/listOrganizationDomains).
+
 ### sim organizations domains remove
 
-Remove Organization Domain (OAuth login or personal API key required)
+Remove organization domain (OAuth login or personal API key required)
+
+This removes the domain claim and revokes verified SSO authority for its providers.
 
 ```bash
 sim organizations domains remove <domainId> [options]
@@ -3193,9 +3537,11 @@ sim organizations domains remove <domainId> [options]
 
 </CommandTable>
 
+API request and response schemas: [removeOrganizationDomain](/api-reference/organizations/removeOrganizationDomain).
+
 ### sim organizations domains verify
 
-Verify Organization Domain (OAuth login or personal API key required)
+Verify organization domain (OAuth login or personal API key required)
 
 ```bash
 sim organizations domains verify <domainId> [options]
@@ -3221,9 +3567,11 @@ sim organizations domains verify <domainId> [options]
 
 </CommandTable>
 
+API request and response schemas: [verifyOrganizationDomain](/api-reference/organizations/verifyOrganizationDomain).
+
 ### sim organizations access-requests cancel
 
-Cancel Organization Access Request (OAuth login or personal API key required)
+Cancel organization access request (OAuth login or personal API key required)
 
 ```bash
 sim organizations access-requests cancel <requestId> [options]
@@ -3249,9 +3597,11 @@ sim organizations access-requests cancel <requestId> [options]
 
 </CommandTable>
 
+API request and response schemas: [cancelOrganizationAccessRequest](/api-reference/access-requests/cancelOrganizationAccessRequest).
+
 ### sim organizations access-requests create
 
-Create Organization Access Request (OAuth login or personal API key required)
+Create organization access request (OAuth login or personal API key required)
 
 ```bash
 sim organizations access-requests create [options]
@@ -3265,13 +3615,15 @@ sim organizations access-requests create [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
 | `--target <json\|@file>` | Yes | Target returned by Discover Workspace Access Requests or Discover Organization Access Requests. The target must currently be requestable. (JSON, or @path / @- to read a file or stdin). |
-| `--reason <value>` | No | Why the acting user needs this access. |
+| `--reason <value>` | No | Why the acting user needs this access. Defaults to "". |
 
 </CommandTable>
 
+API request and response schemas: [createOrganizationAccessRequest](/api-reference/access-requests/createOrganizationAccessRequest).
+
 ### sim organizations access-requests discover
 
-Discover Organization Access Requests (OAuth login or personal API key required)
+Discover organization access requests (OAuth login or personal API key required)
 
 ```bash
 sim organizations access-requests discover [options]
@@ -3287,16 +3639,18 @@ sim organizations access-requests discover [options]
 | `--search <value>` | No | Case-insensitive substring match against the access item label. |
 | `--target-kind <value>` | No | Category of access to discover. Accepted values: `feature`, `integration`, `provider`, `model`, `tool`, `knowledge_connector`, `file_share_auth`, `chat_deploy_auth`, `usage_limit`. |
 | `--state <value>` | No | Filter by the acting user’s current access. Requestable items can be submitted for review. Accepted values: `allowed`, `requestable`, `unavailable`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `label`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "label". Accepted values: `label`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
+API request and response schemas: [discoverOrganizationAccessRequests](/api-reference/access-requests/discoverOrganizationAccessRequests).
+
 ### sim organizations access-requests settings get
 
-Get Organization Access Request Settings (OAuth login or personal API key required)
+Get organization access request settings (OAuth login or personal API key required)
 
 ```bash
 sim organizations access-requests settings get [options]
@@ -3312,9 +3666,11 @@ sim organizations access-requests settings get [options]
 
 </CommandTable>
 
+API request and response schemas: [getOrganizationAccessRequestSettings](/api-reference/access-requests/getOrganizationAccessRequestSettings).
+
 ### sim organizations access-requests settings update
 
-Update Organization Access Request Settings (OAuth login or personal API key required)
+Update organization access request settings (OAuth login or personal API key required)
 
 ```bash
 sim organizations access-requests settings update [options]
@@ -3331,9 +3687,11 @@ sim organizations access-requests settings update [options]
 
 </CommandTable>
 
+API request and response schemas: [updateOrganizationAccessRequestSettings](/api-reference/access-requests/updateOrganizationAccessRequestSettings).
+
 ### sim organizations access-requests mine
 
-List My Organization Access Requests (OAuth login or personal API key required)
+List my organization access requests (OAuth login or personal API key required)
 
 ```bash
 sim organizations access-requests mine [options]
@@ -3347,16 +3705,18 @@ sim organizations access-requests mine [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
 | `--status <value>` | No | Filter by request status; omit to include all statuses. Accepted values: `pending`, `fulfilled`, `declined`, `cancelled`, `closed`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `createdAt`, `targetLabel`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `createdAt`, `targetLabel`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
+API request and response schemas: [listMyOrganizationAccessRequests](/api-reference/access-requests/listMyOrganizationAccessRequests).
+
 ### sim organizations access-requests list
 
-List Organization Access Requests (OAuth login or personal API key required)
+List organization access requests (OAuth login or personal API key required)
 
 ```bash
 sim organizations access-requests list [options]
@@ -3370,17 +3730,19 @@ sim organizations access-requests list [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
 | `--status <value>` | No | Filter by request status; omit to include all statuses. Accepted values: `pending`, `fulfilled`, `declined`, `cancelled`, `closed`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `createdAt`, `targetLabel`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `createdAt`, `targetLabel`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 | `--search <value>` | No | Case-insensitive substring match against the target label or requester name or email. |
 
 </CommandTable>
 
+API request and response schemas: [listOrganizationAccessRequests](/api-reference/access-requests/listOrganizationAccessRequests).
+
 ### sim organizations access-requests preview
 
-Preview Organization Access Request (OAuth login or personal API key required)
+Preview organization access request (OAuth login or personal API key required)
 
 ```bash
 sim organizations access-requests preview <requestId> [options]
@@ -3406,9 +3768,11 @@ sim organizations access-requests preview <requestId> [options]
 
 </CommandTable>
 
+API request and response schemas: [previewOrganizationAccessRequest](/api-reference/access-requests/previewOrganizationAccessRequest).
+
 ### sim organizations access-requests resolve
 
-Resolve Organization Access Request (OAuth login or personal API key required)
+Resolve organization access request (OAuth login or personal API key required)
 
 ```bash
 sim organizations access-requests resolve <requestId> [options]
@@ -3432,15 +3796,17 @@ sim organizations access-requests resolve <requestId> [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
 | `--action <value>` | Yes | apply: Apply the reviewed change to the governing group or member credit cap. decline: Decline the request without changing permissions or credit limits. Accepted values: `apply`, `decline`. |
-| `--expected-fingerprint <value>` | No | Fingerprint from Preview Organization Access Request. Review its changes and impact before applying; a stale preview returns a conflict. Available when action is apply. Required when action is apply. |
-| `--new-limit-credits <value>` | No | Required only for a usage-limit request: a whole-number credit cap greater than the current cap. Omit for permission requests. Available when action is apply. |
-| `--reason <value>` | No | Required explanation for declining this request. Available when action is decline. Required when action is decline. |
+| `--expected-fingerprint <value>` | Conditional | Fingerprint from Preview Organization Access Request. Review its changes and impact before applying; a stale preview returns a conflict. Available when action is apply. Required when action is apply. |
+| `--new-limit-credits <value>` | Conditional | Required only for a usage-limit request: a whole-number credit cap greater than the current cap. Omit for permission requests. Available when action is apply. |
+| `--reason <value>` | Conditional | Required explanation for declining this request. Available when action is decline. Required when action is decline. |
 
 </CommandTable>
 
+API request and response schemas: [resolveOrganizationAccessRequest](/api-reference/access-requests/resolveOrganizationAccessRequest).
+
 ### sim organizations invitations create
 
-Create Organization Invitation (OAuth login or personal API key required)
+Create organization invitation (OAuth login or personal API key required)
 
 ```bash
 sim organizations invitations create [options]
@@ -3458,9 +3824,11 @@ sim organizations invitations create [options]
 
 </CommandTable>
 
+API request and response schemas: [createOrganizationInvitation](/api-reference/organizations/createOrganizationInvitation).
+
 ### sim organizations invitations get
 
-Get Organization Invitation (OAuth login or personal API key required)
+Get organization invitation (OAuth login or personal API key required)
 
 ```bash
 sim organizations invitations get <invitationId> [options]
@@ -3486,9 +3854,11 @@ sim organizations invitations get <invitationId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getOrganizationInvitation](/api-reference/organizations/getOrganizationInvitation).
+
 ### sim organizations invitations list
 
-List Organization Invitations (OAuth login or personal API key required)
+List organization invitations (OAuth login or personal API key required)
 
 ```bash
 sim organizations invitations list [options]
@@ -3503,16 +3873,18 @@ sim organizations invitations list [options]
 | `--organization <value>` | Yes | Organization identifier. |
 | `--search <value>` | No | Case-insensitive substring match against the invitee email. |
 | `--status <value>` | No | Filter by current invitation status. Omit to include all statuses. Accepted values: `pending`, `accepted`, `rejected`, `cancelled`, `expired`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `email`, `createdAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `email`, `createdAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
+API request and response schemas: [listOrganizationInvitations](/api-reference/organizations/listOrganizationInvitations).
+
 ### sim organizations invitations workspaces
 
-List Organization Invitation Workspaces (OAuth login or personal API key required)
+List organization invitation workspaces (OAuth login or personal API key required)
 
 ```bash
 sim organizations invitations workspaces <invitationId> [options]
@@ -3536,16 +3908,18 @@ sim organizations invitations workspaces <invitationId> [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
 | `--search <value>` | No | Case-insensitive substring match against the workspace name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `id`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `id`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
+API request and response schemas: [listOrganizationInvitationWorkspaces](/api-reference/organizations/listOrganizationInvitationWorkspaces).
+
 ### sim organizations invitations resend
 
-Resend Organization Invitation (OAuth login or personal API key required)
+Resend organization invitation (OAuth login or personal API key required)
 
 ```bash
 sim organizations invitations resend <invitationId> [options]
@@ -3571,9 +3945,13 @@ sim organizations invitations resend <invitationId> [options]
 
 </CommandTable>
 
+API request and response schemas: [resendOrganizationInvitation](/api-reference/organizations/resendOrganizationInvitation).
+
 ### sim organizations invitations revoke
 
-Revoke Organization Invitation (OAuth login or personal API key required)
+Revoke organization invitation (OAuth login or personal API key required)
+
+This cancels the invitation and all its workspace grants, preventing acceptance.
 
 ```bash
 sim organizations invitations revoke <invitationId> [options]
@@ -3600,9 +3978,13 @@ sim organizations invitations revoke <invitationId> [options]
 
 </CommandTable>
 
+API request and response schemas: [revokeOrganizationInvitation](/api-reference/organizations/revokeOrganizationInvitation).
+
 ### sim organizations sso providers delete
 
-Delete SSO Provider (OAuth login or personal API key required)
+Delete SSO provider (OAuth login or personal API key required)
+
+This removes the identity provider used for SSO sign-in; linked accounts remain.
 
 ```bash
 sim organizations sso providers delete <providerId> [options]
@@ -3629,9 +4011,11 @@ sim organizations sso providers delete <providerId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteSsoProvider](/api-reference/organizations/deleteSsoProvider).
+
 ### sim organizations sso providers get
 
-Get SSO Provider (OAuth login or personal API key required)
+Get SSO provider (OAuth login or personal API key required)
 
 ```bash
 sim organizations sso providers get <providerId> [options]
@@ -3657,9 +4041,11 @@ sim organizations sso providers get <providerId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getSsoProvider](/api-reference/organizations/getSsoProvider).
+
 ### sim organizations sso providers list
 
-List SSO Providers (OAuth login or personal API key required)
+List SSO providers (OAuth login or personal API key required)
 
 ```bash
 sim organizations sso providers list [options]
@@ -3673,14 +4059,18 @@ sim organizations sso providers list [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `providerId`, `domain`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "providerId". Accepted values: `providerId`, `domain`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
+API request and response schemas: [listSsoProviders](/api-reference/organizations/listSsoProviders).
+
 ### sim organizations sso providers save
 
-Save SSO Provider (OAuth login or personal API key required)
+Save SSO provider (OAuth login or personal API key required)
+
+Choose `--provider-type oidc` or `saml`. OIDC requires `--client-id` and `--client-secret`; SAML requires `--entry-point` and `--cert`. Both require an organization-verified domain. The option descriptions state which omitted fields are preserved or cleared.
 
 ```bash
 sim organizations sso providers save [options]
@@ -3697,22 +4087,22 @@ sim organizations sso providers save [options]
 | `--provider-id <value>` | Yes | Globally unique provider ID; saving an existing provider replaces its supplied configuration. |
 | `--issuer <value>` | Yes | Identity provider issuer URL. |
 | `--domain <value>` | Yes | Email domain already verified by this organization. |
-| `--jit-provisioning-enabled` | No | Allow SSO sign-in to provision organization membership, subject to eligibility and available seats. |
+| `--jit-provisioning-enabled` | No | Allow SSO sign-in to provision organization membership, subject to eligibility and available seats. Defaults to true. |
 | `--no-jit-provisioning-enabled` | No | Send --jit-provisioning-enabled as false. |
-| `--mapping <json\|@file>` | No | Identity-provider claims mapped to user fields. (JSON, or @path / @- to read a file or stdin). |
-| `--client-id <value>` | No | Identity provider client identifier. Available when providerType is oidc. Required when providerType is oidc. |
-| `--client-secret <value\|@file>` | No | Write-only OIDC client secret; the redacted marker from providers get preserves an existing secret. Passing it inline exposes it to shell history and process listings. Required when --provider-type is oidc (@path / @- reads a file or stdin verbatim, including trailing newlines; @@value for a literal leading @). |
-| `--scopes <json\|@file>` | No | OIDC scopes; offline_access is omitted. Available when providerType is oidc. (JSON, or @path / @- to read a file or stdin). |
-| `--pkce` | No | Use PKCE for the authorization flow. Available when providerType is oidc. |
+| `--mapping <json\|@file>` | No | Identity-provider claims mapped to user fields. Defaults to &#123;"id":"sub","email":"email","name":"name","image":"picture"&#125;. (JSON, or @path / @- to read a file or stdin). |
+| `--client-id <value>` | Conditional | Identity provider client identifier. Available when providerType is oidc. Required when providerType is oidc. |
+| `--client-secret <value\|@file>` | Conditional | Write-only OIDC client secret; the redacted marker from providers get preserves an existing secret. Passing it inline exposes it to shell history and process listings. Required when --provider-type is oidc (@path / @- reads a file or stdin verbatim, including trailing newlines; @@value for a literal leading @). |
+| `--scopes <json\|@file>` | No | OIDC scopes; offline_access is omitted. Available when providerType is oidc. Defaults to ["openid","profile","email"]. (JSON, or @path / @- to read a file or stdin). |
+| `--pkce` | No | Use PKCE for the authorization flow. Available when providerType is oidc. Defaults to true. |
 | `--no-pkce` | No | Send --pkce as false. |
 | `--authorization-endpoint <value>` | No | Optional authorization endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc. |
 | `--token-endpoint <value>` | No | Optional token endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc. |
 | `--user-info-endpoint <value>` | No | Optional UserInfo endpoint. Available when providerType is oidc. |
-| `--skip-user-info-endpoint` | No | Read identity claims from the ID token instead of calling UserInfo. Available when providerType is oidc. |
+| `--skip-user-info-endpoint` | No | Read identity claims from the ID token instead of calling UserInfo. Available when providerType is oidc. Defaults to false. |
 | `--no-skip-user-info-endpoint` | No | Send --skip-user-info-endpoint as false. |
 | `--jwks-endpoint <value>` | No | Optional signing-key endpoint; otherwise resolved through issuer discovery. Available when providerType is oidc. |
-| `--entry-point <value>` | No | Identity provider SAML sign-in endpoint. Available when providerType is saml. Required when providerType is saml. |
-| `--cert <value>` | No | Identity provider signing certificate. Available when providerType is saml. Required when providerType is saml. |
+| `--entry-point <value>` | Conditional | Identity provider SAML sign-in endpoint. Available when providerType is saml. Required when providerType is saml. |
+| `--cert <value>` | Conditional | Identity provider signing certificate. Available when providerType is saml. Required when providerType is saml. |
 | `--callback-url <value>` | No | SAML callback URL; defaults to this provider’s Sim callback. Available when providerType is saml. |
 | `--audience <value>` | No | SAML audience; omission preserves the saved value. Available when providerType is saml. |
 | `--want-assertions-signed` | No | Require signed assertions; omission preserves the saved value. Available when providerType is saml. |
@@ -3724,9 +4114,11 @@ sim organizations sso providers save [options]
 
 </CommandTable>
 
+API request and response schemas: [saveSsoProvider](/api-reference/organizations/saveSsoProvider).
+
 ### sim organizations sso providers primary
 
-Set Primary SSO Provider (OAuth login or personal API key required)
+Set primary SSO provider (OAuth login or personal API key required)
 
 ```bash
 sim organizations sso providers primary <providerId> [options]
@@ -3752,9 +4144,11 @@ sim organizations sso providers primary <providerId> [options]
 
 </CommandTable>
 
+API request and response schemas: [setPrimarySsoProvider](/api-reference/organizations/setPrimarySsoProvider).
+
 ### sim organizations sso policy get
 
-Get SSO Policy (OAuth login or personal API key required)
+Get SSO policy (OAuth login or personal API key required)
 
 ```bash
 sim organizations sso policy get [options]
@@ -3770,9 +4164,11 @@ sim organizations sso policy get [options]
 
 </CommandTable>
 
+API request and response schemas: [getSsoPolicy](/api-reference/organizations/getSsoPolicy).
+
 ### sim organizations sso policy update
 
-Update SSO Policy (OAuth login or personal API key required)
+Update SSO policy (OAuth login or personal API key required)
 
 ```bash
 sim organizations sso policy update [options]
@@ -3789,9 +4185,11 @@ sim organizations sso policy update [options]
 
 </CommandTable>
 
+API request and response schemas: [updateSsoPolicy](/api-reference/organizations/updateSsoPolicy).
+
 ### sim organizations get
 
-Get Organization (OAuth login or personal API key required)
+Get organization (OAuth login or personal API key required)
 
 ```bash
 sim organizations get <organizationId>
@@ -3807,9 +4205,11 @@ sim organizations get <organizationId>
 
 </CommandTable>
 
+API request and response schemas: [getOrganization](/api-reference/organizations/getOrganization).
+
 ### sim organizations members usage-limit get
 
-Get Organization Member Credit Limit (OAuth login or personal API key required)
+Get organization member credit limit (OAuth login or personal API key required)
 
 ```bash
 sim organizations members usage-limit get <userId> [options]
@@ -3835,9 +4235,11 @@ sim organizations members usage-limit get <userId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getOrganizationMemberUsageLimit](/api-reference/organizations/getOrganizationMemberUsageLimit).
+
 ### sim organizations members usage-limit update
 
-Update Organization Member Credit Limit (OAuth login or personal API key required)
+Update organization member credit limit (OAuth login or personal API key required)
 
 ```bash
 sim organizations members usage-limit update <userId> [options]
@@ -3864,9 +4266,11 @@ sim organizations members usage-limit update <userId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateOrganizationMemberUsageLimit](/api-reference/organizations/updateOrganizationMemberUsageLimit).
+
 ### sim organizations members list
 
-List Organization Members (OAuth login or personal API key required)
+List organization members (OAuth login or personal API key required)
 
 ```bash
 sim organizations members list [options]
@@ -3880,15 +4284,19 @@ sim organizations members list [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
 | `--search <value>` | No | Case-insensitive substring match against member name or email. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `email`, `joinedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `email`, `joinedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listOrganizationMembers](/api-reference/organizations/listOrganizationMembers).
+
 ### sim organizations members remove
 
-Remove Organization Member (OAuth login or personal API key required)
+Remove organization member (OAuth login or personal API key required)
+
+This removes the member, revokes their organization workspace access, and ends their sessions.
 
 ```bash
 sim organizations members remove <userId> [options]
@@ -3915,9 +4323,11 @@ sim organizations members remove <userId> [options]
 
 </CommandTable>
 
+API request and response schemas: [removeOrganizationMember](/api-reference/organizations/removeOrganizationMember).
+
 ### sim organizations members update
 
-Update Organization Member (OAuth login or personal API key required)
+Update organization member (OAuth login or personal API key required)
 
 ```bash
 sim organizations members update <userId> [options]
@@ -3944,9 +4354,11 @@ sim organizations members update <userId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateOrganizationMember](/api-reference/organizations/updateOrganizationMember).
+
 ### sim organizations usage breakdown
 
-Get Organization Usage Breakdown (OAuth login or personal API key required)
+Get organization usage breakdown (OAuth login or personal API key required)
 
 ```bash
 sim organizations usage breakdown [options]
@@ -3959,7 +4371,7 @@ sim organizations usage breakdown [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
+| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Defaults to "30d". Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
 | `--start-date <value>` | No | First calendar date included, in the selected timezone. Requires preset=custom. |
 | `--end-date <value>` | No | Last calendar date included, in the selected timezone. Requires preset=custom. |
 | `--timezone <value>` | No | IANA timezone for calendar boundaries; defaults to UTC. |
@@ -3968,9 +4380,11 @@ sim organizations usage breakdown [options]
 
 </CommandTable>
 
+API request and response schemas: [getOrganizationUsageBreakdown](/api-reference/organizations/getOrganizationUsageBreakdown).
+
 ### sim organizations usage summary
 
-Get Organization Usage Summary (OAuth login or personal API key required)
+Get organization usage summary (OAuth login or personal API key required)
 
 ```bash
 sim organizations usage summary [options]
@@ -3983,16 +4397,18 @@ sim organizations usage summary [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
+| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Defaults to "30d". Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
 | `--start-date <value>` | No | First calendar date included, in the selected timezone. Requires preset=custom. |
 | `--end-date <value>` | No | Last calendar date included, in the selected timezone. Requires preset=custom. |
 | `--timezone <value>` | No | IANA timezone for calendar boundaries; defaults to UTC. |
 
 </CommandTable>
 
+API request and response schemas: [getOrganizationUsageSummary](/api-reference/organizations/getOrganizationUsageSummary).
+
 ### sim organizations usage events
 
-List Organization Usage Events (OAuth login or personal API key required)
+List organization usage events (OAuth login or personal API key required)
 
 ```bash
 sim organizations usage events [options]
@@ -4005,21 +4421,23 @@ sim organizations usage events [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
-| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
+| `--preset <value>` | No | Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days. Defaults to "30d". Accepted values: `current-period`, `previous-period`, `7d`, `30d`, `custom`. |
 | `--start-date <value>` | No | First calendar date included, in the selected timezone. Requires preset=custom. |
 | `--end-date <value>` | No | Last calendar date included, in the selected timezone. Requires preset=custom. |
 | `--timezone <value>` | No | IANA timezone for calendar boundaries; defaults to UTC. |
 | `--source <value>` | No | Restrict events to one product surface. Accepted values: `workflow`, `wand`, `sim-chat`, `mcp_copilot`, `mothership_block`, `knowledge-base`, `voice-input`, `enrichment`, `voice-output`, `api-tool`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `createdAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `createdAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
+API request and response schemas: [listOrganizationUsageEvents](/api-reference/organizations/listOrganizationUsageEvents).
+
 ### sim organizations list
 
-List Organizations (OAuth login or personal API key required)
+List organizations (OAuth login or personal API key required)
 
 ```bash
 sim organizations list [options]
@@ -4032,15 +4450,17 @@ sim organizations list [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--search <value>` | No | Case-insensitive substring match against the organization name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listOrganizations](/api-reference/organizations/listOrganizations).
+
 ### sim organizations workspaces
 
-List Organization Workspaces (OAuth login or personal API key required)
+List organization workspaces (OAuth login or personal API key required)
 
 ```bash
 sim organizations workspaces [options]
@@ -4054,19 +4474,25 @@ sim organizations workspaces [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
 | `--search <value>` | No | Case-insensitive substring match against the workspace name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `id`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `id`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listOrganizationWorkspaces](/api-reference/organizations/listOrganizationWorkspaces).
+
 ## sim permission-groups
 
+Manage organization permission groups, their configuration, and member assignments.
+
+Use the linked API request schema for the supported `--config` keys. Supplied arrays replace their entire lists; omitted settings remain unchanged on update.
+
 Also spelled `sim permission-group`.
 
 ### sim permission-groups members add
 
-Add Permission Group Member (OAuth login or personal API key required)
+Add permission group member (OAuth login or personal API key required)
 
 ```bash
 sim permission-groups members add [options]
@@ -4084,9 +4510,11 @@ sim permission-groups members add [options]
 
 </CommandTable>
 
+API request and response schemas: [addPermissionGroupMember](/api-reference/permission-groups/addPermissionGroupMember).
+
 ### sim permission-groups members batch-add
 
-Bulk Add Permission Group Members (OAuth login or personal API key required)
+Bulk add permission group members (OAuth login or personal API key required)
 
 ```bash
 sim permission-groups members batch-add [options]
@@ -4105,9 +4533,11 @@ sim permission-groups members batch-add [options]
 
 </CommandTable>
 
+API request and response schemas: [bulkAddPermissionGroupMembers](/api-reference/permission-groups/bulkAddPermissionGroupMembers).
+
 ### sim permission-groups members list
 
-List Permission Group Members (OAuth login or personal API key required)
+List permission group members (OAuth login or personal API key required)
 
 ```bash
 sim permission-groups members list [options]
@@ -4121,15 +4551,19 @@ sim permission-groups members list [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
 | `--group <value>` | Yes | Permission group identifier. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `assignedAt`, `userId`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "assignedAt". Accepted values: `assignedAt`, `userId`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listPermissionGroupMembers](/api-reference/permission-groups/listPermissionGroupMembers).
+
 ### sim permission-groups members remove
 
-Remove Permission Group Member (OAuth login or personal API key required)
+Remove permission group member (OAuth login or personal API key required)
+
+This removes the member assignment and changes which permission groups apply to the user.
 
 ```bash
 sim permission-groups members remove <userId> [options]
@@ -4157,9 +4591,11 @@ sim permission-groups members remove <userId> [options]
 
 </CommandTable>
 
+API request and response schemas: [removePermissionGroupMember](/api-reference/permission-groups/removePermissionGroupMember).
+
 ### sim permission-groups create
 
-Create Permission Group (OAuth login or personal API key required)
+Create permission group (OAuth login or personal API key required)
 
 ```bash
 sim permission-groups create [options]
@@ -4177,13 +4613,17 @@ sim permission-groups create [options]
 | `--config <json\|@file>` | No | Group settings to set. Omitted keys use the default permission configuration. (JSON, or @path / @- to read a file or stdin). |
 | `--default` | No | Whether the group is the organization default. Only one group can be the default. |
 | `--no-default` | No | Send --default as false. |
-| `--workspace-ids <json\|@file>` | No | Workspace IDs targeted by a non-default group. Required when creating a non-default group; omit for a default group. (JSON, or @path / @- to read a file or stdin). |
+| `--workspace-ids <json\|@file>` | Conditional | Workspace IDs targeted by a non-default group. Required when creating a non-default group; omit for a default group. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
+API request and response schemas: [createPermissionGroup](/api-reference/permission-groups/createPermissionGroup).
+
 ### sim permission-groups delete
 
-Delete Permission Group (OAuth login or personal API key required)
+Delete permission group (OAuth login or personal API key required)
+
+This permanently deletes the permission group and its member assignments.
 
 ```bash
 sim permission-groups delete <groupId> [options]
@@ -4210,9 +4650,11 @@ sim permission-groups delete <groupId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deletePermissionGroup](/api-reference/permission-groups/deletePermissionGroup).
+
 ### sim permission-groups get
 
-Get Permission Group (OAuth login or personal API key required)
+Get permission group (OAuth login or personal API key required)
 
 ```bash
 sim permission-groups get <groupId> [options]
@@ -4238,9 +4680,11 @@ sim permission-groups get <groupId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getPermissionGroup](/api-reference/permission-groups/getPermissionGroup).
+
 ### sim permission-groups list
 
-List Permission Groups (OAuth login or personal API key required)
+List permission groups (OAuth login or personal API key required)
 
 ```bash
 sim permission-groups list [options]
@@ -4254,15 +4698,17 @@ sim permission-groups list [options]
 | --- | --- | --- |
 | `--organization <value>` | Yes | Organization identifier. |
 | `--search <value>` | No | Case-insensitive substring match against the group name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listPermissionGroups](/api-reference/permission-groups/listPermissionGroups).
+
 ### sim permission-groups update
 
-Update Permission Group (OAuth login or personal API key required)
+Update permission group (OAuth login or personal API key required)
 
 ```bash
 sim permission-groups update <groupId> [options]
@@ -4294,13 +4740,17 @@ sim permission-groups update <groupId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updatePermissionGroup](/api-reference/permission-groups/updatePermissionGroup).
+
 ## sim sandboxes
 
+Manage reusable dependency sets for Function blocks.
+
 Also spelled `sim sandbox`.
 
 ### sim sandboxes create
 
-Create Sandbox (OAuth login or personal API key required)
+Create sandbox (OAuth login or personal API key required)
 
 ```bash
 sim sandboxes create [options]
@@ -4314,15 +4764,19 @@ sim sandboxes create [options]
 | --- | --- | --- |
 | `--name <value>` | Yes | Display name, unique within the workspace; 1 to 64 characters. |
 | `--language <value>` | Yes | Dependency ecosystem: `javascript` installs from npm, `python` from PyPI. Accepted values: `javascript`, `python`. |
-| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
-| `--cli-tools <value...>` | No | Pinned managed CLI ids installed into the sandbox, at most 10, no duplicates. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--system-packages <value...>` | No | Debian packages installed into the sandbox, one per entry. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
+| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. Defaults to []. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
+| `--cli-tools <value...>` | No | Pinned managed CLI ids installed into the sandbox, at most 10, no duplicates. Defaults to []. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--system-packages <value...>` | No | Debian packages installed into the sandbox, one per entry. Defaults to []. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
 
 </CommandTable>
 
+API request and response schemas: [createSandbox](/api-reference/sandboxes/createSandbox).
+
 ### sim sandboxes delete
 
-Delete Sandbox (OAuth login or personal API key required)
+Delete sandbox (OAuth login or personal API key required)
+
+This deletes the sandbox; Function blocks that select it fail until re-pointed.
 
 ```bash
 sim sandboxes delete <sandboxId> [options]
@@ -4348,9 +4802,11 @@ sim sandboxes delete <sandboxId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteSandbox](/api-reference/sandboxes/deleteSandbox).
+
 ### sim sandboxes get
 
-Get Sandbox
+Get sandbox
 
 ```bash
 sim sandboxes get <sandboxId>
@@ -4366,9 +4822,11 @@ sim sandboxes get <sandboxId>
 
 </CommandTable>
 
+API request and response schemas: [getSandbox](/api-reference/sandboxes/getSandbox).
+
 ### sim sandboxes list
 
-List Sandboxes
+List sandboxes
 
 ```bash
 sim sandboxes list [options]
@@ -4381,15 +4839,17 @@ sim sandboxes list [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--search <value>` | No | Case-insensitive substring match against the sandbox name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listSandboxes](/api-reference/sandboxes/listSandboxes).
+
 ### sim sandboxes update
 
-Update Sandbox (OAuth login or personal API key required)
+Update sandbox (OAuth login or personal API key required)
 
 ```bash
 sim sandboxes update <sandboxId> [options]
@@ -4419,13 +4879,21 @@ sim sandboxes update <sandboxId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateSandbox](/api-reference/sandboxes/updateSandbox).
+
 ## sim secrets
 
+Set and manage workspace or personal secrets.
+
+Personal secrets belong to the caller across workspaces. Workspace secrets are shared resources. Listings include stored values only for workspace secrets marked visible (unredacted); all other entries contain metadata.
+
 Also spelled `sim secret`.
 
 ### sim secrets delete
 
-Delete Secret (OAuth login or personal API key required)
+Delete secret (OAuth login or personal API key required)
+
+This deletes the secret; anything using it may stop working.
 
 ```bash
 sim secrets delete <name> [options]
@@ -4452,9 +4920,11 @@ sim secrets delete <name> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteSecret](/api-reference/secrets/deleteSecret).
+
 ### sim secrets list
 
-List Secrets (OAuth login or personal API key required)
+List secrets (OAuth login or personal API key required)
 
 ```bash
 sim secrets list [options]
@@ -4468,12 +4938,14 @@ sim secrets list [options]
 | --- | --- | --- |
 | `--scope <value>` | No | Restrict results to one ownership scope. Accepted values: `workspace`, `personal`. |
 | `--search <value>` | No | Case-insensitive substring match against the secret name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listSecrets](/api-reference/secrets/listSecrets).
+
 ### sim secrets set
 
 Create or replace a named secret, such as an API key or environment variable (OAuth login or personal API key required)
@@ -4506,11 +4978,19 @@ sim secrets set <name> [options]
 
 </CommandTable>
 
+Omit --value to enter it privately in a terminal. For an existing workspace secret, passing only --description or a redaction flag keeps the stored value and does not prompt. Personal secrets always require a value; they accept no writable metadata. In scripts, pass --value @path or --value @-.
+
+API request and response schemas: [setSecret](/api-reference/secrets/setSecret).
+
 ## sim selectors
 
+Discover destination options for registered fields, such as calendars, channels, and tables.
+
+A selector key identifies the field’s option source. Its context accepts only declared dependencies; missing OAuth access requires a person to authorize the connection.
+
 ### sim selectors get
 
-Get Selector Option (OAuth login or personal API key required)
+Get selector option (OAuth login or personal API key required)
 
 ```bash
 sim selectors get [options]
@@ -4522,15 +5002,17 @@ sim selectors get [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--selector-key <value>` | Yes | Registered selector key for discovering this field’s destination options. Accepted values: `airtable.bases`, `airtable.tables`, `asana.workspaces`, `attio.lists`, `attio.objects`, `bigquery.datasets`, `bigquery.tables`, `bitbucket.workspaces`, `bitbucket.repositories`, `calcom.eventTypes`, `calcom.schedules`, `clickup.workspaces`, `clickup.spaces`, `clickup.folders`, `clickup.lists`, `coda.docs`, `coda.pages`, `coda.tables`, `coda.columns`, `coda.rows`, `coda.formulas`, `coda.controls`, `coda.folders`, `coda.permissions`, `confluence.spaces`, `confluence.spacesById`, `confluence.pages`, `google.tasks.lists`, `fivetran.groups`, `fivetran.connections`, `gmail.labels`, `google.calendar`, `google.drive`, `google.sheets`, `harmonic.savedSearches`, `hubspot.lists`, `hubspot.owners`, `hubspot.pipelines`, `hubspot.pipelineStages`, `hubspot.properties`, `jsm.requestTypes`, `jsm.serviceDesks`, `microsoft.planner.plans`, `notion.databases`, `notion.pages`, `netsuite.recordTypes`, `netsuite.asyncTasks`, `pipedrive.pipelines`, `sharepoint.lists`, `trello.boards`, `zoho_desk.organizations`, `zoho_desk.departments`, `zoho_desk.agents`, `zoom.meetings`, `slack.channels`, `snowflake.databases`, `snowflake.schemas`, `snowflake.tables`, `snowflake.warehouses`, `snowflake.roles`, `snowflake.fileFormats`, `snowflake.procedures`, `slack.users`, `outlook.folders`, `outlook.calendars`, `microsoft.teams`, `microsoft.chats`, `microsoft.channels`, `microsoft.planner`, `onedrive.files`, `onedrive.folders`, `sharepoint.sites`, `microsoft.excel`, `microsoft.excel.drives`, `microsoft.excel.sheets`, `microsoft.word`, `wealthbox.contacts`, `jira.issues`, `jira.projects`, `jira.projectKeys`, `linear.projects`, `linear.teams`, `monday.boards`, `monday.groups`, `webflow.sites`, `webflow.collections`, `webflow.items`, `planetscale.databases`, `powerbi.workspaces`, `powerbi.datasets`, `powerbi.reports`, `planetscale.branches`, `planetscale.backups`, `planetscale.deployRequests`, `cloudwatch.logGroups`, `cloudwatch.logStreams`, `imap.mailboxes`, `mcp.tools`, `managedAgent.agents`, `managedAgent.environments`, `managedAgent.vaults`, `managedAgent.memoryStores`, `knowledge.documents`, `sim.workflows`, `table.columns`, `table.outputColumns`, `workspace.secretNames`, `workspace.sandboxes`, `providers.ollamaEmbeddingModels`, `providers.openrouterEmbeddingModels`. |
-| `--context <json\|@file>` | No | Only the dependencies declared by the selector, such as oauthCredential and channelId. Missing OAuth connections require human authorization. (JSON, or @path / @- to read a file or stdin). |
-| `--id <value>` | Yes | Resource identifier. |
+| `--selector-key <value>` | Yes | Registered selector key from an import or sync preview, such as `gmail.labels`. Accepted values: `airtable.bases`, `airtable.tables`, `asana.workspaces`, `attio.lists`, `attio.objects`, `bigquery.datasets`, `bigquery.tables`, `bitbucket.workspaces`, `bitbucket.repositories`, `calcom.eventTypes`, `calcom.schedules`, `clickup.workspaces`, `clickup.spaces`, `clickup.folders`, `clickup.lists`, `coda.docs`, `coda.pages`, `coda.tables`, `coda.columns`, `coda.rows`, `coda.formulas`, `coda.controls`, `coda.folders`, `coda.permissions`, `confluence.spaces`, `confluence.spacesById`, `confluence.pages`, `google.tasks.lists`, `fivetran.groups`, `fivetran.connections`, `gmail.labels`, `google.calendar`, `google.drive`, `google.sheets`, `harmonic.savedSearches`, `hubspot.lists`, `hubspot.owners`, `hubspot.pipelines`, `hubspot.pipelineStages`, `hubspot.properties`, `jsm.requestTypes`, `jsm.serviceDesks`, `microsoft.planner.plans`, `notion.databases`, `notion.pages`, `netsuite.recordTypes`, `netsuite.asyncTasks`, `pipedrive.pipelines`, `sharepoint.lists`, `trello.boards`, `zoho_desk.organizations`, `zoho_desk.departments`, `zoho_desk.agents`, `zoom.meetings`, `slack.channels`, `snowflake.databases`, `snowflake.schemas`, `snowflake.tables`, `snowflake.warehouses`, `snowflake.roles`, `snowflake.fileFormats`, `snowflake.procedures`, `slack.users`, `outlook.folders`, `outlook.calendars`, `microsoft.teams`, `microsoft.chats`, `microsoft.channels`, `microsoft.planner`, `onedrive.files`, `onedrive.folders`, `sharepoint.sites`, `microsoft.excel`, `microsoft.excel.drives`, `microsoft.excel.sheets`, `microsoft.word`, `wealthbox.contacts`, `jira.issues`, `jira.projects`, `jira.projectKeys`, `linear.projects`, `linear.teams`, `monday.boards`, `monday.groups`, `webflow.sites`, `webflow.collections`, `webflow.items`, `planetscale.databases`, `powerbi.workspaces`, `powerbi.datasets`, `powerbi.reports`, `planetscale.branches`, `planetscale.backups`, `planetscale.deployRequests`, `cloudwatch.logGroups`, `cloudwatch.logStreams`, `imap.mailboxes`, `mcp.tools`, `managedAgent.agents`, `managedAgent.environments`, `managedAgent.vaults`, `managedAgent.memoryStores`, `knowledge.documents`, `sim.workflows`, `table.columns`, `table.outputColumns`, `workspace.secretNames`, `workspace.sandboxes`, `providers.ollamaEmbeddingModels`, `providers.openrouterEmbeddingModels`. |
+| `--context <json\|@file>` | No | Only the dependencies declared by the selector, such as oauthCredential and channelId. Missing OAuth connections require human authorization. Defaults to &#123;&#125;. (JSON, or @path / @- to read a file or stdin). |
+| `--id <value>` | Yes | Provider option ID to resolve with the same selector and declared context. |
 
 </CommandTable>
 
+API request and response schemas: [getSelector](/api-reference/workspace-sync/getSelector).
+
 ### sim selectors list
 
-List Selector Options (OAuth login or personal API key required)
+List selector options (OAuth login or personal API key required)
 
 ```bash
 sim selectors list [options]
@@ -4542,21 +5024,25 @@ sim selectors list [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--selector-key <value>` | Yes | Registered selector key for discovering this field’s destination options. Accepted values: `airtable.bases`, `airtable.tables`, `asana.workspaces`, `attio.lists`, `attio.objects`, `bigquery.datasets`, `bigquery.tables`, `bitbucket.workspaces`, `bitbucket.repositories`, `calcom.eventTypes`, `calcom.schedules`, `clickup.workspaces`, `clickup.spaces`, `clickup.folders`, `clickup.lists`, `coda.docs`, `coda.pages`, `coda.tables`, `coda.columns`, `coda.rows`, `coda.formulas`, `coda.controls`, `coda.folders`, `coda.permissions`, `confluence.spaces`, `confluence.spacesById`, `confluence.pages`, `google.tasks.lists`, `fivetran.groups`, `fivetran.connections`, `gmail.labels`, `google.calendar`, `google.drive`, `google.sheets`, `harmonic.savedSearches`, `hubspot.lists`, `hubspot.owners`, `hubspot.pipelines`, `hubspot.pipelineStages`, `hubspot.properties`, `jsm.requestTypes`, `jsm.serviceDesks`, `microsoft.planner.plans`, `notion.databases`, `notion.pages`, `netsuite.recordTypes`, `netsuite.asyncTasks`, `pipedrive.pipelines`, `sharepoint.lists`, `trello.boards`, `zoho_desk.organizations`, `zoho_desk.departments`, `zoho_desk.agents`, `zoom.meetings`, `slack.channels`, `snowflake.databases`, `snowflake.schemas`, `snowflake.tables`, `snowflake.warehouses`, `snowflake.roles`, `snowflake.fileFormats`, `snowflake.procedures`, `slack.users`, `outlook.folders`, `outlook.calendars`, `microsoft.teams`, `microsoft.chats`, `microsoft.channels`, `microsoft.planner`, `onedrive.files`, `onedrive.folders`, `sharepoint.sites`, `microsoft.excel`, `microsoft.excel.drives`, `microsoft.excel.sheets`, `microsoft.word`, `wealthbox.contacts`, `jira.issues`, `jira.projects`, `jira.projectKeys`, `linear.projects`, `linear.teams`, `monday.boards`, `monday.groups`, `webflow.sites`, `webflow.collections`, `webflow.items`, `planetscale.databases`, `powerbi.workspaces`, `powerbi.datasets`, `powerbi.reports`, `planetscale.branches`, `planetscale.backups`, `planetscale.deployRequests`, `cloudwatch.logGroups`, `cloudwatch.logStreams`, `imap.mailboxes`, `mcp.tools`, `managedAgent.agents`, `managedAgent.environments`, `managedAgent.vaults`, `managedAgent.memoryStores`, `knowledge.documents`, `sim.workflows`, `table.columns`, `table.outputColumns`, `workspace.secretNames`, `workspace.sandboxes`, `providers.ollamaEmbeddingModels`, `providers.openrouterEmbeddingModels`. |
-| `--context <json\|@file>` | No | Only the dependencies declared by the selector, such as oauthCredential and channelId. Missing OAuth connections require human authorization. (JSON, or @path / @- to read a file or stdin). |
+| `--selector-key <value>` | Yes | Registered selector key from an import or sync preview, such as `gmail.labels`. Accepted values: `airtable.bases`, `airtable.tables`, `asana.workspaces`, `attio.lists`, `attio.objects`, `bigquery.datasets`, `bigquery.tables`, `bitbucket.workspaces`, `bitbucket.repositories`, `calcom.eventTypes`, `calcom.schedules`, `clickup.workspaces`, `clickup.spaces`, `clickup.folders`, `clickup.lists`, `coda.docs`, `coda.pages`, `coda.tables`, `coda.columns`, `coda.rows`, `coda.formulas`, `coda.controls`, `coda.folders`, `coda.permissions`, `confluence.spaces`, `confluence.spacesById`, `confluence.pages`, `google.tasks.lists`, `fivetran.groups`, `fivetran.connections`, `gmail.labels`, `google.calendar`, `google.drive`, `google.sheets`, `harmonic.savedSearches`, `hubspot.lists`, `hubspot.owners`, `hubspot.pipelines`, `hubspot.pipelineStages`, `hubspot.properties`, `jsm.requestTypes`, `jsm.serviceDesks`, `microsoft.planner.plans`, `notion.databases`, `notion.pages`, `netsuite.recordTypes`, `netsuite.asyncTasks`, `pipedrive.pipelines`, `sharepoint.lists`, `trello.boards`, `zoho_desk.organizations`, `zoho_desk.departments`, `zoho_desk.agents`, `zoom.meetings`, `slack.channels`, `snowflake.databases`, `snowflake.schemas`, `snowflake.tables`, `snowflake.warehouses`, `snowflake.roles`, `snowflake.fileFormats`, `snowflake.procedures`, `slack.users`, `outlook.folders`, `outlook.calendars`, `microsoft.teams`, `microsoft.chats`, `microsoft.channels`, `microsoft.planner`, `onedrive.files`, `onedrive.folders`, `sharepoint.sites`, `microsoft.excel`, `microsoft.excel.drives`, `microsoft.excel.sheets`, `microsoft.word`, `wealthbox.contacts`, `jira.issues`, `jira.projects`, `jira.projectKeys`, `linear.projects`, `linear.teams`, `monday.boards`, `monday.groups`, `webflow.sites`, `webflow.collections`, `webflow.items`, `planetscale.databases`, `powerbi.workspaces`, `powerbi.datasets`, `powerbi.reports`, `planetscale.branches`, `planetscale.backups`, `planetscale.deployRequests`, `cloudwatch.logGroups`, `cloudwatch.logStreams`, `imap.mailboxes`, `mcp.tools`, `managedAgent.agents`, `managedAgent.environments`, `managedAgent.vaults`, `managedAgent.memoryStores`, `knowledge.documents`, `sim.workflows`, `table.columns`, `table.outputColumns`, `workspace.secretNames`, `workspace.sandboxes`, `providers.ollamaEmbeddingModels`, `providers.openrouterEmbeddingModels`. |
+| `--context <json\|@file>` | No | Only the dependencies declared by the selector, such as oauthCredential and channelId. Missing OAuth connections require human authorization. Defaults to &#123;&#125;. (JSON, or @path / @- to read a file or stdin). |
 | `--search <value>` | No | Provider option search text. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 
 </CommandTable>
 
+API request and response schemas: [listSelector](/api-reference/workspace-sync/listSelector).
+
 ## sim skills
 
+Create reusable agent instructions and manage their editors.
+
 Also spelled `sim skill`.
 
 ### sim skills create
 
-Create Skill (OAuth login or personal API key required)
+Create skill (OAuth login or personal API key required)
 
 ```bash
 sim skills create [options]
@@ -4574,9 +5060,13 @@ sim skills create [options]
 
 </CommandTable>
 
+API request and response schemas: [createSkill](/api-reference/skills/createSkill).
+
 ### sim skills delete
 
-Delete Skill (OAuth login or personal API key required)
+Delete skill (OAuth login or personal API key required)
+
+This deletes the skill.
 
 ```bash
 sim skills delete <skillId> [options]
@@ -4602,9 +5092,11 @@ sim skills delete <skillId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteSkill](/api-reference/skills/deleteSkill).
+
 ### sim skills get
 
-Get Skill
+Get skill
 
 ```bash
 sim skills get <skillId>
@@ -4620,9 +5112,11 @@ sim skills get <skillId>
 
 </CommandTable>
 
+API request and response schemas: [getSkill](/api-reference/skills/getSkill).
+
 ### sim skills editors create
 
-Grant Skill Editor (OAuth login or personal API key required)
+Grant skill editor (OAuth login or personal API key required)
 
 ```bash
 sim skills editors create <skillId> [options]
@@ -4648,9 +5142,11 @@ sim skills editors create <skillId> [options]
 
 </CommandTable>
 
+API request and response schemas: [grantSkillEditor](/api-reference/skills/grantSkillEditor).
+
 ### sim skills editors list
 
-List Skill Editors
+List skill editors
 
 ```bash
 sim skills editors list <skillId> [options]
@@ -4672,15 +5168,19 @@ sim skills editors list <skillId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `email`, `name`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "email". Accepted values: `email`, `name`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listSkillEditors](/api-reference/skills/listSkillEditors).
+
 ### sim skills editors delete
 
-Revoke Skill Editor (OAuth login or personal API key required)
+Revoke skill editor (OAuth login or personal API key required)
+
+This revokes the explicit skill editor grant for the selected email.
 
 ```bash
 sim skills editors delete <skillId> [options]
@@ -4707,9 +5207,11 @@ sim skills editors delete <skillId> [options]
 
 </CommandTable>
 
+API request and response schemas: [revokeSkillEditor](/api-reference/skills/revokeSkillEditor).
+
 ### sim skills list
 
-List Skills
+List skills
 
 ```bash
 sim skills list [options]
@@ -4722,15 +5224,17 @@ sim skills list [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--search <value>` | No | Case-insensitive substring match against the skill name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listSkills](/api-reference/skills/listSkills).
+
 ### sim skills update
 
-Update Skill (OAuth login or personal API key required)
+Update skill (OAuth login or personal API key required)
 
 ```bash
 sim skills update <skillId> [options]
@@ -4758,13 +5262,17 @@ sim skills update <skillId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateSkill](/api-reference/skills/updateSkill).
+
 ## sim tables
 
+Manage tables, rows, schemas, views, enrichment runs, imports, and exports.
+
 Also spelled `sim table`.
 
 ### sim tables columns create
 
-Add Column
+Add column
 
 ```bash
 sim tables columns create <tableId> [options]
@@ -4790,9 +5298,13 @@ sim tables columns create <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [addTableColumn](/api-reference/tables/addTableColumn).
+
 ### sim tables columns delete
 
-Delete Column
+Delete column
+
+This deletes the column and its values in every row.
 
 ```bash
 sim tables columns delete <tableId> [options]
@@ -4819,9 +5331,11 @@ sim tables columns delete <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteTableColumn](/api-reference/tables/deleteTableColumn).
+
 ### sim tables columns update
 
-Update Column
+Update column
 
 ```bash
 sim tables columns update <tableId> [options]
@@ -4848,9 +5362,11 @@ sim tables columns update <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateTableColumn](/api-reference/tables/updateTableColumn).
+
 ### sim tables groups create
 
-Add Workflow Group
+Add workflow group
 
 ```bash
 sim tables groups create <tableId> [options]
@@ -4873,15 +5389,19 @@ sim tables groups create <tableId> [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--group <json\|@file>` | Yes | Workflow or enrichment producer definition. (JSON, or @path / @- to read a file or stdin). |
-| `--output-columns <json\|@file>` | No | Columns to create for producer outputs. An entry naming a column the table already has attaches that column to the group instead of creating it (its `type` must match), and an output whose column already exists may omit its entry entirely — so `[]` attaches existing columns only. (JSON, or @path / @- to read a file or stdin). |
-| `--auto-run` | No | Whether to schedule existing rows after group creation. |
+| `--output-columns <json\|@file>` | No | Columns to create for producer outputs. An entry naming a column the table already has attaches that column to the group instead of creating it (its `type` must match), and an output whose column already exists may omit its entry entirely — so `[]` attaches existing columns only. Defaults to []. (JSON, or @path / @- to read a file or stdin). |
+| `--auto-run` | No | Whether to schedule existing rows after group creation. Defaults to false. |
 | `--no-auto-run` | No | Send --auto-run as false. |
 
 </CommandTable>
 
+API request and response schemas: [addWorkflowGroup](/api-reference/tables/addTableWorkflowGroup).
+
 ### sim tables groups delete
 
-Delete Workflow Group
+Delete workflow group
+
+This deletes the group AND its output columns with all of their row data; the workflow it pointed at is untouched.
 
 ```bash
 sim tables groups delete <tableId> [options]
@@ -4908,9 +5428,11 @@ sim tables groups delete <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteWorkflowGroup](/api-reference/tables/deleteTableWorkflowGroup).
+
 ### sim tables groups list
 
-List Workflow Groups
+List workflow groups
 
 ```bash
 sim tables groups list <tableId>
@@ -4926,9 +5448,11 @@ sim tables groups list <tableId>
 
 </CommandTable>
 
+API request and response schemas: [listWorkflowGroups](/api-reference/tables/listTableWorkflowGroups).
+
 ### sim tables groups update
 
-Update Workflow Group
+Update workflow group
 
 ```bash
 sim tables groups update <tableId> [options]
@@ -4965,9 +5489,13 @@ sim tables groups update <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateWorkflowGroup](/api-reference/tables/updateTableWorkflowGroup).
+
 ### sim tables batch-delete
 
-Bulk Delete Tables and Folders
+Bulk delete tables and folders
+
+This archives the selected tables and folders, including their rows. Restore eligible tables with `tables restore`.
 
 ```bash
 sim tables batch-delete [options]
@@ -4979,12 +5507,14 @@ sim tables batch-delete [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--table-ids <json\|@file>` | No | Tables to archive, by identifier. (JSON, or @path / @- to read a file or stdin). |
+| `--table-ids <json\|@file>` | No | Tables to archive, by identifier. Defaults to []. (JSON, or @path / @- to read a file or stdin). |
 | `--folder <value...>` | No | Folder path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
+API request and response schemas: [bulkDeleteTables](/api-reference/tables/bulkDeleteTables).
+
 ### sim tables rows update-each
 
 Apply a distinct patch to each listed row
@@ -5013,9 +5543,11 @@ sim tables rows update-each <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [bulkUpdateTableRows](/api-reference/tables/bulkUpdateTableRows).
+
 ### sim tables rows create
 
-Create Rows
+Create rows
 
 ```bash
 sim tables rows create <tableId> [options]
@@ -5042,9 +5574,13 @@ sim tables rows create <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [createTableRows](/api-reference/tables/createTableRows).
+
 ### sim tables rows delete
 
-Delete Row
+Delete row
+
+This deletes the row.
 
 ```bash
 sim tables rows delete <tableId> <rowId> [options]
@@ -5071,10 +5607,14 @@ sim tables rows delete <tableId> <rowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteTableRow](/api-reference/tables/deleteTableRow).
+
 ### sim tables rows batch-delete
 
 Delete rows matching a filter, or an explicit list of ids
 
+This deletes every matching row and cannot be undone.
+
 ```bash
 sim tables rows batch-delete <tableId> [options]
 ```
@@ -5102,9 +5642,11 @@ sim tables rows batch-delete <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteTableRows](/api-reference/tables/deleteTableRows).
+
 ### sim tables rows get
 
-Get Row
+Get row
 
 ```bash
 sim tables rows get <tableId> <rowId> [options]
@@ -5127,14 +5669,16 @@ sim tables rows get <tableId> <rowId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--include-run-state` | No | Include per-workflow-group run state on the returned row. Off by default. |
+| `--include-run-state` | No | Include per-workflow-group run outcomes on the row. Off by default. Run state above 2 MiB returns `413`; omit this option to read the row without run state. |
 | `--no-include-run-state` | No | Send --include-run-state as false. |
 
 </CommandTable>
 
+API request and response schemas: [getTableRow](/api-reference/tables/getTableRow).
+
 ### sim tables rows list
 
-List Rows
+List rows
 
 ```bash
 sim tables rows list <tableId> [options]
@@ -5158,11 +5702,13 @@ sim tables rows list <tableId> [options]
 | --- | --- | --- |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--include-run-state` | No | Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it only when asked. Caps `limit` at 200. |
+| `--include-run-state` | No | Include per-workflow-group run outcomes on every row. Off by default. Caps `limit` at 200. Run state above 2 MiB returns `413`; request fewer rows or omit run state. |
 | `--no-include-run-state` | No | Send --include-run-state as false. |
 
 </CommandTable>
 
+API request and response schemas: [listTableRows](/api-reference/tables/listTableRows).
+
 ### sim tables rows query
 
 Query rows with a filter and sort
@@ -5191,11 +5737,13 @@ sim tables rows query <tableId> [options]
 | `--sort <json\|@file>` | No | Ordered sort keys: [&#123;"field":"createdAt","direction":"desc"&#125;] (direction: asc or desc) (JSON, or @path / @- to read a file or stdin). |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--include-run-state` | No | Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it only when asked. Incompatible with `limit: 0`, and caps `limit` at 200. |
+| `--include-run-state` | No | Include per-workflow-group run outcomes on every row. Off by default. Each request above 2 MiB of run state returns 413; request fewer rows or omit run state. CLI --limit 0 still fetches bounded pages. |
 | `--no-include-run-state` | No | Send --include-run-state as false. |
 
 </CommandTable>
 
+API request and response schemas: [queryRows](/api-reference/tables/queryTableRows).
+
 ### sim tables rows count
 
 Count rows matching a filter
@@ -5224,6 +5772,8 @@ sim tables rows count <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [queryRowsCount](/api-reference/tables/countTableRows).
+
 ### sim tables rows enrich
 
 Run one row’s enrichment group
@@ -5244,6 +5794,8 @@ sim tables rows enrich <tableId> <rowId> <groupId>
 
 </CommandTable>
 
+API request and response schemas: [runRowEnrichment](/api-reference/tables/runRowEnrichment).
+
 ### sim tables rows search
 
 Search cells for a value and return their coordinates
@@ -5274,10 +5826,14 @@ sim tables rows search <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [searchTableRows](/api-reference/tables/searchTableRows).
+
 ### sim tables rows batch-update
 
 Update every row matching a filter
 
+This updates every matching row and cannot be undone.
+
 ```bash
 sim tables rows batch-update <tableId> [options]
 ```
@@ -5305,9 +5861,11 @@ sim tables rows batch-update <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateRowsByFilter](/api-reference/tables/updateTableRows).
+
 ### sim tables rows update
 
-Update Row
+Update row
 
 ```bash
 sim tables rows update <tableId> <rowId> [options]
@@ -5334,10 +5892,14 @@ sim tables rows update <tableId> <rowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateTableRow](/api-reference/tables/updateTableRow).
+
 ### sim tables dispatches cancel
 
 Cancel a running dispatch
 
+This stops the dispatch. Cells already handed to the queue keep running — use `tables cancel-runs` to stop those.
+
 ```bash
 sim tables dispatches cancel <tableId> <dispatchId> [options]
 ```
@@ -5363,6 +5925,8 @@ sim tables dispatches cancel <tableId> <dispatchId> [options]
 
 </CommandTable>
 
+API request and response schemas: [cancelTableDispatch](/api-reference/tables/cancelTableDispatch).
+
 ### sim tables dispatches create
 
 Start a column or enrichment run
@@ -5388,7 +5952,7 @@ sim tables dispatches create <tableId> [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--group-ids <value...>` | Yes | Workflow or enrichment groups to run. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--run-mode <value>` | No | Whether to run all or only incomplete cells. Accepted values: `all`, `incomplete`. |
+| `--run-mode <value>` | No | Whether to run all or only incomplete cells. Defaults to "all". Accepted values: `all`, `incomplete`. |
 | `--row-ids <value...>` | No | Explicit row subset to run. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `--filter <json\|@file>` | No | Predicate: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; groups use all/any. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
 | `--exclude-row-ids <value...>` | No | Rows excluded from a select-all run scope. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
@@ -5396,9 +5960,11 @@ sim tables dispatches create <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [createTableDispatch](/api-reference/tables/createTableDispatch).
+
 ### sim tables dispatches get
 
-Get Run Dispatch
+Get run dispatch
 
 ```bash
 sim tables dispatches get <tableId> <dispatchId>
@@ -5415,9 +5981,11 @@ sim tables dispatches get <tableId> <dispatchId>
 
 </CommandTable>
 
+API request and response schemas: [getTableDispatch](/api-reference/tables/getTableDispatch).
+
 ### sim tables dispatches list
 
-List Run Dispatches
+List run dispatches
 
 ```bash
 sim tables dispatches list <tableId>
@@ -5433,6 +6001,8 @@ sim tables dispatches list <tableId>
 
 </CommandTable>
 
+API request and response schemas: [listTableDispatches](/api-reference/tables/listTableDispatches).
+
 ### sim tables exports cancel
 
 Stop a running export
@@ -5452,9 +6022,11 @@ sim tables exports cancel <tableId> <exportId>
 
 </CommandTable>
 
+API request and response schemas: [cancelTableExport](/api-reference/tables/cancelTableExport).
+
 ### sim tables exports create
 
-Create Table Export
+Create table export
 
 ```bash
 sim tables exports create <tableId> [options]
@@ -5476,13 +6048,15 @@ sim tables exports create <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--format <value>` | No | Export file format. Accepted values: `csv`, `json`. |
+| `--format <value>` | No | Export file format. Defaults to "csv". Accepted values: `csv`, `json`. |
 
 </CommandTable>
 
+API request and response schemas: [createTableExport](/api-reference/tables/createTableExport).
+
 ### sim tables exports get
 
-Get Table Export
+Get table export
 
 ```bash
 sim tables exports get <tableId> <exportId>
@@ -5499,6 +6073,8 @@ sim tables exports get <tableId> <exportId>
 
 </CommandTable>
 
+API request and response schemas: [getTableExport](/api-reference/tables/getTableExport).
+
 ### sim tables exports download
 
 Get the download URL for a finished export
@@ -5518,10 +6094,14 @@ sim tables exports download <tableId> <exportId>
 
 </CommandTable>
 
+API request and response schemas: [tableExportDownload](/api-reference/tables/downloadTableExport).
+
 ### sim tables imports cancel
 
 Stop a running import
 
+This stops the import between row batches, so whatever it already wrote stays and nothing resumes it. A replace import empties the table before its first batch, so cancelling one leaves only part of the new file; an append adds its rows again if you import the file a second time.
+
 ```bash
 sim tables imports cancel <importId> [options]
 ```
@@ -5546,9 +6126,11 @@ sim tables imports cancel <importId> [options]
 
 </CommandTable>
 
+API request and response schemas: [cancelTableImport](/api-reference/tables/cancelTableImport).
+
 ### sim tables imports get
 
-Get Table Import
+Get table import
 
 ```bash
 sim tables imports get <importId>
@@ -5564,10 +6146,14 @@ sim tables imports get <importId>
 
 </CommandTable>
 
+API request and response schemas: [getTableImport](/api-reference/tables/getTableImport).
+
 ### sim tables cancel-runs
 
 Stop every running column job
 
+This cancels running column jobs — the whole table with --scope all, one row with --scope row.
+
 ```bash
 sim tables cancel-runs <tableId> [options]
 ```
@@ -5596,9 +6182,11 @@ sim tables cancel-runs <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [cancelTableRuns](/api-reference/tables/cancelTableRuns).
+
 ### sim tables create
 
-Create Table
+Create table
 
 ```bash
 sim tables create [options]
@@ -5617,6 +6205,8 @@ sim tables create [options]
 
 </CommandTable>
 
+API request and response schemas: [createTable](/api-reference/tables/createTable).
+
 ### sim tables folders create
 
 Create a table folder at a path
@@ -5635,9 +6225,13 @@ sim tables folders create <path>
 
 </CommandTable>
 
+API request and response schemas: [createTableFolder](/api-reference/tables/createTablesFolder).
+
 ### sim tables folders delete
 
-Delete Folder
+Delete folder
+
+This archives the table folder and, when recursive, everything inside it.
 
 ```bash
 sim tables folders delete <path> [options]
@@ -5659,11 +6253,13 @@ sim tables folders delete <path> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--recursive` | No | Delete the folder and its descendants. |
+| `--recursive` | No | Archive the folder and its descendants. Defaults to "false". |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
+API request and response schemas: [deleteTableFolder](/api-reference/tables/deleteTablesFolder).
+
 ### sim tables folders list
 
 List table folders
@@ -5682,11 +6278,13 @@ Also available as `sim tables folders ls`.
 | --- | --- | --- |
 | `--parent <value>` | No | Direct parent folder path. |
 | `--search <value>` | No | Case-insensitive substring match against the folder name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
+API request and response schemas: [listTableFolders](/api-reference/tables/listTablesFolders).
+
 ### sim tables folders move
 
 Rename or move a table folder
@@ -5708,6 +6306,8 @@ Also available as `sim tables folders mv`.
 
 </CommandTable>
 
+API request and response schemas: [relocateTableFolder](/api-reference/tables/relocateTablesFolder).
+
 ### sim tables folders restore
 
 Restore an archived table folder
@@ -5726,9 +6326,11 @@ sim tables folders restore <path>
 
 </CommandTable>
 
+API request and response schemas: [restoreTableFolder](/api-reference/tables/restoreTablesFolder).
+
 ### sim tables views create
 
-Create View
+Create view
 
 ```bash
 sim tables views create <tableId> [options]
@@ -5755,9 +6357,13 @@ sim tables views create <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [createTableView](/api-reference/tables/createTableView).
+
 ### sim tables views delete
 
-Delete View
+Delete view
+
+This deletes the saved view and its filters.
 
 ```bash
 sim tables views delete <tableId> <viewId> [options]
@@ -5784,9 +6390,11 @@ sim tables views delete <tableId> <viewId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteTableView](/api-reference/tables/deleteTableView).
+
 ### sim tables views get
 
-Get View
+Get view
 
 ```bash
 sim tables views get <tableId> <viewId>
@@ -5803,9 +6411,11 @@ sim tables views get <tableId> <viewId>
 
 </CommandTable>
 
+API request and response schemas: [getTableView](/api-reference/tables/getTableView).
+
 ### sim tables views list
 
-List Views
+List views
 
 ```bash
 sim tables views list <tableId>
@@ -5821,9 +6431,11 @@ sim tables views list <tableId>
 
 </CommandTable>
 
+API request and response schemas: [listTableViews](/api-reference/tables/listTableViews).
+
 ### sim tables views update
 
-Update View
+Update view
 
 ```bash
 sim tables views update <tableId> <viewId> [options]
@@ -5854,9 +6466,13 @@ sim tables views update <tableId> <viewId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateTableView](/api-reference/tables/updateTableView).
+
 ### sim tables delete
 
-Delete Table
+Delete table
+
+This archives the table and all of its rows; restore with `tables restore`.
 
 ```bash
 sim tables delete <tableId> [options]
@@ -5882,9 +6498,11 @@ sim tables delete <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteTable](/api-reference/tables/deleteTable).
+
 ### sim tables enrichment get
 
-Get Row Group Run
+Get row group run
 
 ```bash
 sim tables enrichment get <tableId> <rowId> <groupId>
@@ -5902,9 +6520,11 @@ sim tables enrichment get <tableId> <rowId> <groupId>
 
 </CommandTable>
 
+API request and response schemas: [getRowEnrichment](/api-reference/tables/getRowEnrichment).
+
 ### sim tables get
 
-Get Table
+Get table
 
 ```bash
 sim tables get <tableId>
@@ -5920,9 +6540,11 @@ sim tables get <tableId>
 
 </CommandTable>
 
+API request and response schemas: [getTable](/api-reference/tables/getTable).
+
 ### sim tables list
 
-List Tables
+List tables
 
 ```bash
 sim tables list [options]
@@ -5937,15 +6559,17 @@ sim tables list [options]
 | `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live tables, `archived` for tables a delete archived and a table restore can bring back. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
 | `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 | `--search <value>` | No | Case-insensitive substring match against the resource name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listTables](/api-reference/tables/listTables).
+
 ### sim tables move
 
-Move Tables and Folders
+Move tables and folders
 
 ```bash
 sim tables move [options]
@@ -5957,12 +6581,14 @@ sim tables move [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--table-ids <json\|@file>` | No | Tables to move, by identifier. (JSON, or @path / @- to read a file or stdin). |
+| `--table-ids <json\|@file>` | No | Tables to move, by identifier. Defaults to []. (JSON, or @path / @- to read a file or stdin). |
 | `--folder <value...>` | No | Table folders to move, by path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `--to <value>` | No | Destination folder path; omit for root. |
 
 </CommandTable>
 
+API request and response schemas: [moveTables](/api-reference/tables/moveTables).
+
 ### sim tables restore
 
 Restore an archived table
@@ -5981,9 +6607,11 @@ sim tables restore <tableId>
 
 </CommandTable>
 
+API request and response schemas: [restoreTable](/api-reference/tables/restoreTable).
+
 ### sim tables update
 
-Update Table
+Update table
 
 ```bash
 sim tables update <tableId> [options]
@@ -6011,6 +6639,8 @@ sim tables update <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateTable](/api-reference/tables/updateTable).
+
 ### sim tables mv
 
 Move a table to a folder
@@ -6030,9 +6660,11 @@ sim tables mv <tableId> <folder>
 
 </CommandTable>
 
+API request and response schemas: [updateTable](/api-reference/tables/updateTable).
+
 ### sim tables upsert
 
-Insert a row, or update the one that conflicts on a unique column
+Insert a row, or replace the one matching a unique column
 
 ```bash
 sim tables upsert <tableId> [options]
@@ -6059,10 +6691,18 @@ sim tables upsert <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [upsertTableRow](/api-reference/tables/upsertTableRow).
+
 ### sim tables import
 
 Import a CSV, into a new table by default
 
+Choose exactly one source: a local CSV path or `--file-id`. For a new table imported with `--file-id`, supply `--name`. With `--table-id`, omit the new-table `--name` and `--folder` flags; `--mode`, `--mapping`, and `--create-columns` apply only to an existing table.
+
+**Replace mode deletes all existing rows before loading the CSV and cannot be undone.** It requires `--yes`; cancellation leaves only the rows already imported.
+
+The command watches the import by default. `--no-wait` returns a queued receipt. A completed import can still report `rowsRejected`, `cellsRejected`, and `rejectedSamples`; inspect them before accepting the result.
+
 ```bash
 sim tables import [path] [options]
 ```
@@ -6073,7 +6713,7 @@ sim tables import [path] [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | No | Local CSV file to import; omit when using --file-id |
+| `path` | No | Local CSV file to import; choose exactly one source: this path or --file-id |
 
 </CommandTable>
 
@@ -6083,7 +6723,7 @@ sim tables import [path] [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <name>` | No | Identifier for the new table: letters, numbers, and underscores; defaults to the sanitized file name. |
+| `--name <name>` | Conditional | Name for a new table: letters, numbers, and underscores. A local CSV defaults to its sanitized filename; required with --file-id unless --table-id names an existing table. |
 | `--table-id <id>` | No | Import into this existing table instead of creating one. |
 | `--mode <append\|replace>` | No | How to write into --table-id (default: append). Accepted values: `append`, `replace`. |
 | `--folder <path>` | No | Folder path for the new table, as shown in the app. |
@@ -6091,11 +6731,13 @@ sim tables import [path] [options]
 | `--mapping <json\|@file>` | No | Column mapping (--table-id only). |
 | `--create-columns <json\|@file>` | No | Columns to create (--table-id only). |
 | `--timezone <iana>` | No | Timezone for date parsing, e.g. America/New_York. |
-| `-y, --yes` | No | Confirm this destructive operation (required with --mode replace). |
+| `-y, --yes` | Conditional | Confirm this destructive operation (required with --mode replace). |
 | `--no-wait` | No | Return once the import is queued instead of watching it. |
 
 </CommandTable>
 
+API request and response schemas: [createTableImport](/api-reference/tables/createTableImport), [createTableImportPartUrls](/api-reference/tables/createTableImportPartUrls), [completeTableImport](/api-reference/tables/completeTableImportUpload), [cancelTableImport](/api-reference/tables/cancelTableImport), [getTableImport](/api-reference/tables/getTableImport).
+
 ### sim tables ls
 
 List table resources and child folders together
@@ -6125,6 +6767,8 @@ sim tables ls [path] [options]
 
 </CommandTable>
 
+API request and response schemas: [listTables](/api-reference/tables/listTables), [listTableFolders](/api-reference/tables/listTablesFolders).
+
 ### sim tables mkdir
 
 Create a table directory at a path
@@ -6143,8 +6787,14 @@ sim tables mkdir <path>
 
 </CommandTable>
 
+API request and response schemas: [createTableFolder](/api-reference/tables/createTablesFolder).
+
 ## sim tools
 
+Find built-in tools, inspect their parameters, and run them.
+
+Inspect a tool with `sim tools get <toolId>` before passing its parameters to `sim tools execute`.
+
 ### sim tools execute
 
 Run one built-in tool and print what it produced (OAuth login or personal API key required)
@@ -6159,7 +6809,7 @@ sim tools execute <toolId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `toolId` | Yes | Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id. |
+| `toolId` | Yes | Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID. |
 
 </CommandTable>
 
@@ -6169,15 +6819,17 @@ sim tools execute <toolId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--input <json\|@file>` | No | Tool arguments as JSON, keyed by the parameter ids `sim tools get &lt;toolId&gt;` lists (JSON, or @path / @- to read a file or stdin). |
+| `--input <json\|@file>` | No | Tool arguments as JSON, keyed by the parameter ids `sim tools get <toolId>` lists. Defaults to &#123;&#125;. (JSON, or @path / @- to read a file or stdin). |
 | `--credential-id <value>` | No | Credential to authenticate with, required for OAuth tools. |
 | `--timeout <value>` | No | Seconds to wait before abandoning the call. |
 
 </CommandTable>
 
+API request and response schemas: [executeTool](/api-reference/catalog/executeTool).
+
 ### sim tools get
 
-Get Tool
+Get tool
 
 ```bash
 sim tools get <toolId>
@@ -6189,13 +6841,15 @@ sim tools get <toolId>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `toolId` | Yes | Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id. |
+| `toolId` | Yes | Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID. |
 
 </CommandTable>
 
+API request and response schemas: [getTool](/api-reference/catalog/getTool).
+
 ### sim tools list
 
-List Tools
+List tools
 
 ```bash
 sim tools list [options]
@@ -6210,17 +6864,23 @@ sim tools list [options]
 | `--search <value>` | No | Case-insensitive substring match against the tool id, name, and description. |
 | `--hosted-api-key <value>` | No | Restrict to tools by how their API key is supplied. Accepted values: `always`, `conditional`, `none`. |
 | `--oauth-provider <value>` | No | Restrict to tools that authenticate against this OAuth service. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `id`, `name`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "id". Accepted values: `id`, `name`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listTools](/api-reference/catalog/listTools).
+
 ## sim workflow-mcp-servers
 
+Serve deployed workflows as tools for Model Context Protocol (MCP) clients.
+
+These servers expose Sim workflows. To connect a server that provides external tools, use [MCP servers](/cli/mcp-servers).
+
 ### sim workflow-mcp-servers create
 
-Create Workflow MCP Server (OAuth login or personal API key required)
+Create workflow MCP server (OAuth login or personal API key required)
 
 ```bash
 sim workflow-mcp-servers create [options]
@@ -6234,15 +6894,19 @@ sim workflow-mcp-servers create [options]
 | --- | --- | --- |
 | `--name <value>` | Yes | Server display name, shown to connecting MCP clients. |
 | `--description <value>` | No | Optional server description. |
-| `--is-public` | No | Whether the server answers MCP clients without a Sim API key. Defaults to false — a public server executes the workflows it publishes for anyone holding its URL. |
+| `--is-public` | No | Whether the server accepts MCP clients without a Sim API key. Defaults to false; a public server lets anyone holding its URL execute the workflows it exposes. |
 | `--no-is-public` | No | Send --is-public as false. |
-| `--workflow <value...>` | No | Deployed workflows to publish as tools on the new server. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--workflow <value...>` | No | Deployed workflows to expose as MCP tools on the new server. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 
 </CommandTable>
 
+API request and response schemas: [createWorkflowMcpServer](/api-reference/mcp-servers/createWorkflowMcpServer).
+
 ### sim workflow-mcp-servers delete
 
-Delete Workflow MCP Server (OAuth login or personal API key required)
+Delete workflow MCP server (OAuth login or personal API key required)
+
+This deletes the MCP server, and any agent calling its tools loses access.
 
 ```bash
 sim workflow-mcp-servers delete <serverId> [options]
@@ -6268,9 +6932,11 @@ sim workflow-mcp-servers delete <serverId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteWorkflowMcpServer](/api-reference/mcp-servers/deleteWorkflowMcpServer).
+
 ### sim workflow-mcp-servers tools create
 
-Publish Workflow As MCP Tool (OAuth login or personal API key required)
+Deploy workflow as MCP tool (OAuth login or personal API key required)
 
 ```bash
 sim workflow-mcp-servers tools create <serverId> [options]
@@ -6292,16 +6958,18 @@ sim workflow-mcp-servers tools create <serverId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--workflow-id <value>` | Yes | Deployed workflow to publish. The workflow must already be deployed. |
+| `--workflow-id <value>` | Yes | Workflow to expose as an MCP tool. It must already be deployed. |
 | `--tool-name <value>` | No | Name MCP clients call. Normalized to the MCP tool-name grammar, and derived from the workflow name when omitted. |
 | `--tool-description <value>` | No | Description shown to MCP clients. Derived from the workflow name when omitted. |
 | `--parameter-descriptions <json\|@file>` | No | Per-field description overrides applied to the schema generated from the deployed workflow inputs, as [&#123;"name":"email","description":"Customer email address"&#125;]. A name matching no input field is ignored (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
+API request and response schemas: [deployWorkflowMcpTool](/api-reference/mcp-servers/deployWorkflowMcpTool).
+
 ### sim workflow-mcp-servers tools list
 
-List Workflow MCP Tools (OAuth login or personal API key required)
+List workflow MCP tools (OAuth login or personal API key required)
 
 ```bash
 sim workflow-mcp-servers tools list <serverId>
@@ -6317,9 +6985,13 @@ sim workflow-mcp-servers tools list <serverId>
 
 </CommandTable>
 
+API request and response schemas: [listWorkflowMcpTools](/api-reference/mcp-servers/listWorkflowMcpTools).
+
 ### sim workflow-mcp-servers tools delete
 
-Unpublish Workflow MCP Tool (OAuth login or personal API key required)
+Undeploy workflow MCP tool (OAuth login or personal API key required)
+
+This withdraws the tool, and any agent calling it loses access.
 
 ```bash
 sim workflow-mcp-servers tools delete <serverId> <workflowId> [options]
@@ -6332,7 +7004,7 @@ sim workflow-mcp-servers tools delete <serverId> <workflowId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `serverId` | Yes | Unique workflow-MCP server identifier. |
-| `workflowId` | Yes | Workflow published as a tool on this server. |
+| `workflowId` | Yes | Workflow registered as an MCP tool on this server. |
 
 </CommandTable>
 
@@ -6346,9 +7018,11 @@ sim workflow-mcp-servers tools delete <serverId> <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [undeployWorkflowMcpTool](/api-reference/mcp-servers/undeployWorkflowMcpTool).
+
 ### sim workflow-mcp-servers get
 
-Get Workflow MCP Server (OAuth login or personal API key required)
+Get workflow MCP server (OAuth login or personal API key required)
 
 ```bash
 sim workflow-mcp-servers get <serverId>
@@ -6364,9 +7038,11 @@ sim workflow-mcp-servers get <serverId>
 
 </CommandTable>
 
+API request and response schemas: [getWorkflowMcpServer](/api-reference/mcp-servers/getWorkflowMcpServer).
+
 ### sim workflow-mcp-servers list
 
-List Workflow MCP Servers (OAuth login or personal API key required)
+List workflow MCP servers (OAuth login or personal API key required)
 
 ```bash
 sim workflow-mcp-servers list [options]
@@ -6378,15 +7054,17 @@ sim workflow-mcp-servers list [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listWorkflowMcpServers](/api-reference/mcp-servers/listWorkflowMcpServers).
+
 ### sim workflow-mcp-servers update
 
-Update Workflow MCP Server (OAuth login or personal API key required)
+Update workflow MCP server (OAuth login or personal API key required)
 
 ```bash
 sim workflow-mcp-servers update <serverId> [options]
@@ -6415,13 +7093,19 @@ sim workflow-mcp-servers update <serverId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateWorkflowMcpServer](/api-reference/mcp-servers/updateWorkflowMcpServer).
+
 ## sim workflows
 
+Build, deploy, run, and inspect workflows from the terminal.
+
 Also spelled `sim workflow`.
 
 ### sim workflows activate create
 
-Activate Workflow Version (OAuth login or personal API key required)
+Activate workflow version (OAuth login or personal API key required)
+
+This changes which deployed version runs in production for every API and chat consumer.
 
 ```bash
 sim workflows activate create <workflowId> <version> [options]
@@ -6448,10 +7132,14 @@ sim workflows activate create <workflowId> <version> [options]
 
 </CommandTable>
 
+API request and response schemas: [activateWorkflowVersion](/api-reference/workflows/activateWorkflowVersion).
+
 ### sim workflows operations apply
 
 Edit a workflow’s blocks, connections and settings with a batch of operations (OAuth login or personal API key required)
 
+This edits the draft graph: the batch adds, edits, or deletes blocks and their edges as written.
+
 ```bash
 sim workflows operations apply <workflowId> [options]
 ```
@@ -6479,13 +7167,17 @@ sim workflows operations apply <workflowId> [options]
 | `--no-atomic` | No | Send --atomic as false. |
 | `--layout <value>` | No | Whether to reposition blocks the batch touched. `targeted` (default) nudges only the affected subgraph; `none` leaves every position exactly as supplied. Accepted values: `targeted`, `none`. |
 | `--set-block-enabled <json\|@file>` | No | Blocks to enable or disable, applied after --operations: [&#123;"block_id":"&lt;uuid&gt;","enabled":false&#125;]. Disabling a loop or parallel cascades to its unlocked descendants; enabling a block whose container is disabled is declined (JSON, or @path / @- to read a file or stdin). |
-| `-y, --yes` | No | Confirm this operation (required unless --dry-run). |
+| `-y, --yes` | Conditional | Confirm this operation (required unless --dry-run). |
 
 </CommandTable>
 
+API request and response schemas: [applyWorkflowOperations](/api-reference/workflows/applyWorkflowOperations).
+
 ### sim workflows variables update
 
-Update Workflow Variables
+Update workflow variables
+
+This applies the listed variable changes; variables omitted from the operations remain unchanged.
 
 ```bash
 sim workflows variables update <workflowId> [options]
@@ -6512,10 +7204,14 @@ sim workflows variables update <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [applyWorkflowVariables](/api-reference/workflows/applyWorkflowVariables).
+
 ### sim workflows runs cancel
 
 Cancel a running workflow run
 
+Canceling a paused run prevents resuming that run. Starting a new run can repeat side effects already performed.
+
 ```bash
 sim workflows runs cancel <runId> [options]
 ```
@@ -6540,6 +7236,8 @@ sim workflows runs cancel <runId> [options]
 
 </CommandTable>
 
+API request and response schemas: [cancelWorkflowRun](/api-reference/workflow-runs/cancelRunV2).
+
 ### sim workflows runs get
 
 Show run status (requested outputs are included in JSON or YAML output)
@@ -6573,6 +7271,8 @@ sim workflows runs get <runId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getWorkflowRun](/api-reference/workflow-runs/getWorkflowRunV2).
+
 ### sim workflows runs list
 
 List runs for a workflow
@@ -6594,10 +7294,12 @@ sim workflows runs list [options]
 | `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--order <value>` | No | Sort direction by run start time. This list is sortable only by run start time, so it takes `order` in place of `sortBy`/`sortOrder`, which it rejects. Accepted values: `asc`, `desc`. |
+| `--order <value>` | No | Sort direction by run start time. This list is sortable only by run start time, so it takes `order` in place of `sortBy`/`sortOrder`, which it rejects. Defaults to "desc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
+API request and response schemas: [listWorkflowRuns](/api-reference/workflow-runs/listWorkflowRunsV2).
+
 ### sim workflows runs resume
 
 Resume a paused run (output is included in JSON or YAML output)
@@ -6628,9 +7330,11 @@ sim workflows runs resume <runId> [options]
 
 </CommandTable>
 
+API request and response schemas: [resumeWorkflow](/api-reference/workflow-runs/resumeWorkflowRunV2).
+
 ### sim workflows runs wait
 
-Wait for a run to reach a terminal state, then show it
+Wait until a run finishes or needs input
 
 ```bash
 sim workflows runs wait <runId> [options]
@@ -6657,9 +7361,13 @@ sim workflows runs wait <runId> [options]
 
 </CommandTable>
 
+Exit codes: 0 completed, 1 failed, 2 cancelled, 3 needs input, 4 timed out. Time-based pauses continue waiting; a human pause or an unspecified pause kind ends the wait with code 3. Use `sim workflows runs resume` with the pause context to continue.
+
+API request and response schemas: [getWorkflowRun](/api-reference/workflow-runs/getWorkflowRunV2).
+
 ### sim workflows versions compare
 
-Compare Workflow Versions
+Compare workflow versions
 
 ```bash
 sim workflows versions compare <workflowId> [options]
@@ -6686,9 +7394,11 @@ sim workflows versions compare <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [compareWorkflowVersions](/api-reference/workflows/compareWorkflowVersionsV2).
+
 ### sim workflows versions get
 
-Get Workflow Version
+Get workflow version
 
 ```bash
 sim workflows versions get <workflowId> <version>
@@ -6705,9 +7415,11 @@ sim workflows versions get <workflowId> <version>
 
 </CommandTable>
 
+API request and response schemas: [getWorkflowVersion](/api-reference/workflows/getWorkflowVersionV2).
+
 ### sim workflows versions list
 
-List Workflow Versions
+List workflow versions
 
 ```bash
 sim workflows versions list <workflowId> [options]
@@ -6734,9 +7446,11 @@ sim workflows versions list <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [listWorkflowVersions](/api-reference/workflows/listWorkflowVersionsV2).
+
 ### sim workflows versions update
 
-Update Workflow Version
+Update workflow version
 
 ```bash
 sim workflows versions update <workflowId> <version> [options]
@@ -6764,9 +7478,11 @@ sim workflows versions update <workflowId> <version> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateWorkflowVersion](/api-reference/workflows/updateWorkflowVersionV2).
+
 ### sim workflows create
 
-Create Workflow
+Create workflow
 
 ```bash
 sim workflows create [options]
@@ -6784,6 +7500,8 @@ sim workflows create [options]
 
 </CommandTable>
 
+API request and response schemas: [createWorkflow](/api-reference/workflows/createWorkflowV2).
+
 ### sim workflows folders create
 
 Create a workflow folder at a path
@@ -6802,9 +7520,13 @@ sim workflows folders create <path>
 
 </CommandTable>
 
+API request and response schemas: [createWorkflowFolder](/api-reference/workflows/createWorkflowsFolder).
+
 ### sim workflows folders delete
 
-Delete Workflow Folder
+Delete workflow folder
+
+This archives the workflow folder and, when recursive, everything inside it.
 
 ```bash
 sim workflows folders delete <path> [options]
@@ -6826,11 +7548,13 @@ sim workflows folders delete <path> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--recursive` | No | Delete the folder and its descendants. |
+| `--recursive` | No | Archive the folder and its descendants. Defaults to "false". |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
+API request and response schemas: [deleteWorkflowFolder](/api-reference/workflows/deleteWorkflowsFolder).
+
 ### sim workflows folders list
 
 List workflow folders
@@ -6849,11 +7573,13 @@ Also available as `sim workflows folders ls`.
 | --- | --- | --- |
 | `--parent <value>` | No | Direct parent folder path. |
 | `--search <value>` | No | Case-insensitive substring match against the folder name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
+API request and response schemas: [listWorkflowFolders](/api-reference/workflows/listWorkflowsFolders).
+
 ### sim workflows folders move
 
 Rename or move a workflow folder
@@ -6875,9 +7601,13 @@ Also available as `sim workflows folders mv`.
 
 </CommandTable>
 
+API request and response schemas: [relocateWorkflowFolder](/api-reference/workflows/relocateWorkflowsFolder).
+
 ### sim workflows delete
 
-Delete Workflow
+Delete workflow
+
+This archives the workflow and its run history; restore with `workflows restore`.
 
 ```bash
 sim workflows delete <workflowId> [options]
@@ -6903,10 +7633,14 @@ sim workflows delete <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteWorkflow](/api-reference/workflows/deleteWorkflowV2).
+
 ### sim workflows chat unpublish
 
 Take a workflow’s chat deployment offline (OAuth login or personal API key required)
 
+This takes the chat offline and frees its identifier. The workflow itself stays deployed and executable.
+
 ```bash
 sim workflows chat unpublish <workflowId> [options]
 ```
@@ -6931,6 +7665,8 @@ sim workflows chat unpublish <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deleteWorkflowChatDeployment](/api-reference/workflows/deleteWorkflowChatDeployment).
+
 ### sim workflows chat status
 
 Show a workflow’s chat deployment (OAuth login or personal API key required)
@@ -6949,9 +7685,15 @@ sim workflows chat status <workflowId>
 
 </CommandTable>
 
+API request and response schemas: [getWorkflowChatDeployment](/api-reference/workflows/getWorkflowChatDeployment).
+
 ### sim workflows chat publish
 
-Publish or replace a workflow’s chat deployment (OAuth login or personal API key required)
+Deploy or replace a workflow chat (OAuth login or personal API key required)
+
+This replaces visitor access settings for the chat deployment. Omitted authentication fields reset to defaults, including the password and allowed-email list; avatar and welcome-message behavior follows their option descriptions.
+
+Omitting `--auth-type` selects public access: anyone holding the URL can chat. Supply the complete password or allow-list settings again when replacing a restricted deployment.
 
 ```bash
 sim workflows chat publish <workflowId> [options]
@@ -6976,22 +7718,24 @@ sim workflows chat publish <workflowId> [options]
 | `--identifier <value>` | Yes | URL slug the deployed chat answers on. Must be free across live deployments. |
 | `--title <value>` | Yes | Title shown to visitors. |
 | `--description <value>` | No | Description shown to visitors. Omitted clears it. |
-| `--customizations <json\|@file>` | No | Presentation overrides. Omitted fields take platform defaults. (JSON, or @path / @- to read a file or stdin). |
-| `--auth-type <value>` | No | How visitors are gated. `public` leaves the chat open to anyone holding the URL. Accepted values: `public`, `password`, `email`, `sso`. |
-| `--password <value>` | No | Write-only password of 15 to 1024 characters, not only whitespace. Required whenever `authType` is `password`, and rejected otherwise. Never readable back. Taken literally, except that a request from the Sim agent resolves a whole-value `&#123;&#123;ENV_VAR&#125;&#125;` reference to that variable before the rules apply. |
+| `--customizations <json\|@file>` | No | Presentation overrides. Omitted `primaryColor` and `welcomeMessage` use platform defaults; an omitted or empty `imageUrl` keeps the existing avatar. An empty `welcomeMessage` keeps the existing message. (JSON, or @path / @- to read a file or stdin). |
+| `--auth-type <value>` | No | How visitors are gated. `public` leaves the chat open to anyone holding the URL. Defaults to "public". Accepted values: `public`, `password`, `email`, `sso`. |
+| `--password <value>` | Conditional | Write-only password of 15 to 1024 characters, not only whitespace. Required whenever `authType` is `password`, and rejected otherwise. Never readable back. Taken literally, except that a request from the Sim agent resolves a whole-value `{{ENV_VAR}}` reference to that variable before the rules apply. |
 | `--allowed-emails <json\|@file>` | No | Email addresses or domains admitted under `email` and `sso` gating. At least one is required for those modes. (JSON, or @path / @- to read a file or stdin). |
 | `--output-configs <json\|@file>` | No | Block outputs to surface to visitors. Omitted surfaces none. (JSON, or @path / @- to read a file or stdin). |
-| `--include-thinking` | No | Allow visitors to receive provider thinking events. |
+| `--include-thinking` | No | Allow visitors to receive provider thinking events. Defaults to false. |
 | `--no-include-thinking` | No | Send --include-thinking as false. |
-| `--include-tool-calls` | No | Allow visitors to receive tool lifecycle events. |
+| `--include-tool-calls` | No | Allow visitors to receive tool lifecycle events. Defaults to false. |
 | `--no-include-tool-calls` | No | Send --include-tool-calls as false. |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
+API request and response schemas: [replaceWorkflowChatDeployment](/api-reference/workflows/replaceWorkflowChatDeployment).
+
 ### sim workflows deploy
 
-Deploy Workflow (OAuth login or personal API key required)
+Deploy workflow (OAuth login or personal API key required)
 
 ```bash
 sim workflows deploy <workflowId> [options]
@@ -7018,9 +7762,11 @@ sim workflows deploy <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [deployWorkflow](/api-reference/workflows/deployWorkflow).
+
 ### sim workflows duplicate create
 
-Duplicate Workflow
+Duplicate workflow
 
 ```bash
 sim workflows duplicate create <workflowId> [options]
@@ -7047,6 +7793,8 @@ sim workflows duplicate create <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [duplicateWorkflow](/api-reference/workflows/duplicateWorkflow).
+
 ### sim workflows run
 
 Run a deployed workflow or execute saved state manually
@@ -7072,10 +7820,10 @@ sim workflows run <workflowId> [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--input <json\|@file>` | No | Trigger input as JSON (JSON, or @path / @- to read a file or stdin). |
-| `--async` | No | Queue the run and return immediately. |
+| `--async` | No | Queue the run and return immediately. Defaults to false. |
 | `--execution-timeout-seconds <value>` | No | Maximum duration of an asynchronous run, in seconds, capped by the plan's execution timeout. Requires `async: true`; otherwise returns `400`. |
 | `--select-output <value...>` | No | Return blockName.path values (e.g. agent_1.content), or childWorkflowId.blockName.path for a child workflow (applies to every invocation) — in blockOutputs on a sync run, or from the streamed result with --follow; missing paths are omitted. Not available with --async (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--include-file-base64` | No | Inline eligible output files as base64 content (default: true; Sim’s in-app agent gets file references only unless this flag is passed). Rejected when `async` is true. |
+| `--include-file-base64` | No | Inline eligible output files as base64 content. Defaults to true for the installed CLI; Chat defaults to file references and admits requested bytes only for synchronous runs. Rejected when async is true. |
 | `--no-include-file-base64` | No | Send --include-file-base64 as false. |
 | `--base64-max-bytes <value>` | No | Maximum total bytes of file content to inline as base64, lowering but never raising the server limit of 16 MiB. Rejected when `async` is true. |
 | `--run-id <value>` | No | One-shot identifier for this run; NOT an idempotency key — reusing a claimed value fails with RUN_ID_CONFLICT instead of replaying the first result, and a fresh value starts another run. |
@@ -7091,10 +7839,14 @@ sim workflows run <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [executeWorkflow](/api-reference/workflows/executeWorkflowV2).
+
 ### sim workflows export
 
 Print a workflow as a portable JSON document
 
+The export clears credentials, passwords, and table sub-block values, but it is not a general secret scanner. Inspect literal variables and inline configuration before sharing the document.
+
 ```bash
 sim workflows export <workflowId> [options]
 ```
@@ -7116,14 +7868,16 @@ sim workflows export <workflowId> [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--include-references` | No | Include non-secret resource identities for mapped import. |
-| `--include-workspace-bindings` | No | Whether to keep workspace-scoped bindings — table, knowledge base, document, folder, channel, and other resource selectors — in the exported state. Defaults to false, the sharing-safe export in which those ids are cleared because they resolve nowhere else. Send true for a same-workspace round trip so the re-imported workflow can run without re-selecting them. Credentials, passwords, and table sub-block values are cleared either way. |
+| `--include-workspace-bindings` | No | Keep non-secret table, knowledge base, document, folder, channel, and other workspace bindings for a same-workspace import. Defaults to false, which clears these IDs. Registered credential fields and opaque table/tool values are cleared either way; environment references and ordinary workflow variables remain included. |
 | `--no-include-workspace-bindings` | No | Send --include-workspace-bindings as false. |
 
 </CommandTable>
 
+API request and response schemas: [exportWorkflow](/api-reference/workflows/exportWorkflow).
+
 ### sim workflows get
 
-Get Workflow
+Get workflow
 
 ```bash
 sim workflows get <workflowId>
@@ -7139,6 +7893,8 @@ sim workflows get <workflowId>
 
 </CommandTable>
 
+API request and response schemas: [getWorkflow](/api-reference/workflows/getWorkflow).
+
 ### sim workflows deployment status
 
 Show a workflow’s current deployment
@@ -7157,9 +7913,11 @@ sim workflows deployment status <workflowId>
 
 </CommandTable>
 
+API request and response schemas: [getWorkflowDeployment](/api-reference/workflows/getWorkflowDeployment).
+
 ### sim workflows deployment update
 
-Update Workflow Public API Access (OAuth login or personal API key required)
+Update workflow public API access (OAuth login or personal API key required)
 
 ```bash
 sim workflows deployment update <workflowId> [options]
@@ -7185,9 +7943,11 @@ sim workflows deployment update <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateWorkflowPublicApi](/api-reference/workflows/updateWorkflowPublicApi).
+
 ### sim workflows state get
 
-Get Workflow State
+Get workflow state
 
 ```bash
 sim workflows state get <workflowId>
@@ -7203,9 +7963,13 @@ sim workflows state get <workflowId>
 
 </CommandTable>
 
+API request and response schemas: [getWorkflowState](/api-reference/workflows/getWorkflowState).
+
 ### sim workflows state replace
 
-Replace Workflow State (OAuth login or personal API key required)
+Replace workflow state (OAuth login or personal API key required)
+
+This replaces the entire draft graph and cannot be undone.
 
 ```bash
 sim workflows state replace <workflowId> [options]
@@ -7234,13 +7998,15 @@ sim workflows state replace <workflowId> [options]
 | `--loops <json\|@file>` | No | Ignored on write: loop containers are recomputed from `blocks`. (JSON, or @path / @- to read a file or stdin). |
 | `--parallels <json\|@file>` | No | Ignored on write: parallel containers are recomputed from `blocks`. (JSON, or @path / @- to read a file or stdin). |
 | `--variables <json\|@file>` | No | Replacement variable set. Omit to leave the stored variables untouched. (JSON, or @path / @- to read a file or stdin). |
-| `-y, --yes` | No | Confirm this operation (required unless --dry-run). |
+| `-y, --yes` | Conditional | Confirm this operation (required unless --dry-run). |
 
 </CommandTable>
 
+API request and response schemas: [replaceWorkflowState](/api-reference/workflows/replaceWorkflowState).
+
 ### sim workflows import
 
-Import Workflow
+Import workflow
 
 ```bash
 sim workflows import [options]
@@ -7256,19 +8022,21 @@ sim workflows import [options]
 | `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 | `--name <value>` | No | Override for the imported workflow name. |
 | `--description <value>` | No | Override for the imported workflow description. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
+| `--mappings <json\|@file>` | No | Mapping entries addressed by resource kind and source identifier. (JSON, or @path / @- to read a file or stdin). |
 | `--bindings <json\|@file>` | No | Resolved and unresolved source occurrences with their destination selections. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
-| `--request-id <value>` | No | Stable client request ID for reconciliation and identical retries. |
-| `--preview-fingerprint <value>` | No | Fingerprint of the reviewed preview and its choices. |
+| `--dependent-values <json\|@file>` | No | Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated. (JSON, or @path / @- to read a file or stdin). |
+| `--request-id <value>` | No | Stable client request ID for mapped import. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can create another workflow. |
+| `--preview-fingerprint <value>` | No | Fingerprint returned by an import preview with the same choices. A changed plan returns 409; preview again. Do not invent this value. |
 | `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
 | `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
 
 </CommandTable>
 
+API request and response schemas: [importWorkflow](/api-reference/workflows/importWorkflow).
+
 ### sim workflows list
 
-List Workflows
+List workflows
 
 ```bash
 sim workflows list [options]
@@ -7286,14 +8054,16 @@ sim workflows list [options]
 | `--no-deployed-only` | No | Send --deployed-only as false. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 | `--search <value>` | No | Case-insensitive substring match against the resource name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `position`, `name`, `createdAt`, `updatedAt`, `runCount`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "position". Accepted values: `position`, `name`, `createdAt`, `updatedAt`, `runCount`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
+API request and response schemas: [listWorkflows](/api-reference/workflows/listWorkflows).
+
 ### sim workflows move
 
-Move Workflows
+Move workflows
 
 ```bash
 sim workflows move [options]
@@ -7310,9 +8080,11 @@ sim workflows move [options]
 
 </CommandTable>
 
+API request and response schemas: [moveWorkflows](/api-reference/workflows/moveWorkflows).
+
 ### sim workflows import-preview
 
-Preview Workflow Import
+Preview workflow import
 
 ```bash
 sim workflows import-preview [options]
@@ -7328,12 +8100,14 @@ sim workflows import-preview [options]
 | `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 | `--name <value>` | No | Override for the imported workflow name. |
 | `--description <value>` | No | Override for the imported workflow description. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
+| `--mappings <json\|@file>` | No | Mapping entries addressed by resource kind and source identifier. (JSON, or @path / @- to read a file or stdin). |
 | `--bindings <json\|@file>` | No | Resolved and unresolved source occurrences with their destination selections. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
+| `--dependent-values <json\|@file>` | No | Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
+API request and response schemas: [previewWorkflowImport](/api-reference/workspace-sync/previewWorkflowImport).
+
 ### sim workflows restore
 
 Restore an archived workflow
@@ -7352,9 +8126,13 @@ sim workflows restore <workflowId>
 
 </CommandTable>
 
+API request and response schemas: [restoreWorkflow](/api-reference/workflows/restoreWorkflow).
+
 ### sim workflows revert create
 
-Revert Workflow To Version (OAuth login or personal API key required)
+Revert workflow to version (OAuth login or personal API key required)
+
+This overwrites the draft graph with the selected version and cannot be undone.
 
 ```bash
 sim workflows revert create <workflowId> <version> [options]
@@ -7381,9 +8159,13 @@ sim workflows revert create <workflowId> <version> [options]
 
 </CommandTable>
 
+API request and response schemas: [revertWorkflowVersion](/api-reference/workflows/revertWorkflowVersion).
+
 ### sim workflows rollback
 
-Rollback Workflow (OAuth login or personal API key required)
+Rollback workflow (OAuth login or personal API key required)
+
+This changes which deployed version runs in production for every API and chat consumer.
 
 ```bash
 sim workflows rollback <workflowId> [options]
@@ -7410,10 +8192,14 @@ sim workflows rollback <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [rollbackWorkflow](/api-reference/workflows/rollbackWorkflow).
+
 ### sim workflows undeploy
 
 Take a workflow out of deployment (OAuth login or personal API key required)
 
+This takes the workflow offline for every API and chat consumer, and agents calling its MCP tools lose access until it is deployed again.
+
 ```bash
 sim workflows undeploy <workflowId> [options]
 ```
@@ -7438,9 +8224,11 @@ sim workflows undeploy <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [undeployWorkflow](/api-reference/workflows/undeployWorkflow).
+
 ### sim workflows update
 
-Update Workflow
+Update workflow
 
 ```bash
 sim workflows update <workflowId> [options]
@@ -7468,6 +8256,8 @@ sim workflows update <workflowId> [options]
 
 </CommandTable>
 
+API request and response schemas: [updateWorkflow](/api-reference/workflows/updateWorkflowV2).
+
 ### sim workflows mv
 
 Move a workflow to a folder
@@ -7487,6 +8277,8 @@ sim workflows mv <workflowId> <folder>
 
 </CommandTable>
 
+API request and response schemas: [updateWorkflow](/api-reference/workflows/updateWorkflowV2).
+
 ### sim workflows ls
 
 List workflow resources and child folders together
@@ -7516,6 +8308,8 @@ sim workflows ls [path] [options]
 
 </CommandTable>
 
+API request and response schemas: [listWorkflows](/api-reference/workflows/listWorkflows), [listWorkflowFolders](/api-reference/workflows/listWorkflowsFolders).
+
 ### sim workflows mkdir
 
 Create a workflow directory at a path
@@ -7534,13 +8328,17 @@ sim workflows mkdir <path>
 
 </CommandTable>
 
+API request and response schemas: [createWorkflowFolder](/api-reference/workflows/createWorkflowsFolder).
+
 ## sim workspaces
 
+Read workspace access and manage reviewed fork, push, and pull operations.
+
 Also spelled `sim workspace`.
 
 ### sim workspaces access-requests cancel
 
-Cancel Workspace Access Request (OAuth login or personal API key required)
+Cancel workspace access request (OAuth login or personal API key required)
 
 ```bash
 sim workspaces access-requests cancel <requestId>
@@ -7556,9 +8354,11 @@ sim workspaces access-requests cancel <requestId>
 
 </CommandTable>
 
+API request and response schemas: [cancelWorkspaceAccessRequest](/api-reference/access-requests/cancelWorkspaceAccessRequest).
+
 ### sim workspaces access-requests create
 
-Create Workspace Access Request (OAuth login or personal API key required)
+Create workspace access request (OAuth login or personal API key required)
 
 ```bash
 sim workspaces access-requests create [options]
@@ -7571,13 +8371,15 @@ sim workspaces access-requests create [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--target <json\|@file>` | Yes | Target returned by Discover Workspace Access Requests or Discover Organization Access Requests. The target must currently be requestable. (JSON, or @path / @- to read a file or stdin). |
-| `--reason <value>` | No | Why the acting user needs this access. |
+| `--reason <value>` | No | Why the acting user needs this access. Defaults to "". |
 
 </CommandTable>
 
+API request and response schemas: [createWorkspaceAccessRequest](/api-reference/access-requests/createWorkspaceAccessRequest).
+
 ### sim workspaces access-requests discover
 
-Discover Workspace Access Requests (OAuth login or personal API key required)
+Discover workspace access requests (OAuth login or personal API key required)
 
 ```bash
 sim workspaces access-requests discover [options]
@@ -7592,16 +8394,18 @@ sim workspaces access-requests discover [options]
 | `--search <value>` | No | Case-insensitive substring match against the access item label. |
 | `--target-kind <value>` | No | Category of access to discover. Accepted values: `feature`, `integration`, `provider`, `model`, `tool`, `knowledge_connector`, `file_share_auth`, `chat_deploy_auth`, `usage_limit`. |
 | `--state <value>` | No | Filter by the acting user’s current access. Requestable items can be submitted for review. Accepted values: `allowed`, `requestable`, `unavailable`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `label`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "label". Accepted values: `label`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
+API request and response schemas: [discoverWorkspaceAccessRequests](/api-reference/access-requests/discoverWorkspaceAccessRequests).
+
 ### sim workspaces access-requests mine
 
-List My Workspace Access Requests (OAuth login or personal API key required)
+List my workspace access requests (OAuth login or personal API key required)
 
 ```bash
 sim workspaces access-requests mine [options]
@@ -7614,16 +8418,18 @@ sim workspaces access-requests mine [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--status <value>` | No | Filter by request status; omit to include all statuses. Accepted values: `pending`, `fulfilled`, `declined`, `cancelled`, `closed`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `createdAt`, `targetLabel`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `createdAt`, `targetLabel`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
+API request and response schemas: [listMyWorkspaceAccessRequests](/api-reference/access-requests/listMyWorkspaceAccessRequests).
+
 ### sim workspaces invitations create
 
-Create Workspace Invitations (OAuth login or personal API key required)
+Create workspace invitations (OAuth login or personal API key required)
 
 ```bash
 sim workspaces invitations create [options]
@@ -7636,14 +8442,16 @@ sim workspaces invitations create [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--emails <value...>` | Yes | Email addresses to invite. Each address is processed separately; inspect failed for unsuccessful recipients. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--permission <value>` | No | Workspace permission to grant. Existing workspace access is preserved. Accepted values: `admin`, `write`, `read`. |
-| `--membership <value>` | No | Organization membership: member or admin uses a seat when billing is enabled. External grants workspace access only and requires an eligible paid account when billing is enabled. Existing members of another organization remain external. Accepted values: `member`, `admin`, `external`. |
+| `--permission <value>` | No | Workspace permission to grant. Existing workspace access is preserved. Defaults to "read". Accepted values: `admin`, `write`, `read`. |
+| `--membership <value>` | No | Organization membership: member or admin uses a seat when billing is enabled. External grants workspace access only and requires an eligible paid account when billing is enabled. Existing members of another organization remain external. Defaults to "member". Accepted values: `member`, `admin`, `external`. |
 
 </CommandTable>
 
+API request and response schemas: [createWorkspaceInvitations](/api-reference/workspaces/createWorkspaceInvitations).
+
 ### sim workspaces fork
 
-Fork Workspace (OAuth login or personal API key required)
+Fork workspace (OAuth login or personal API key required)
 
 ```bash
 sim workspaces fork [options]
@@ -7657,40 +8465,48 @@ sim workspaces fork [options]
 | --- | --- | --- |
 | `--name <value>` | No | Display name of the workflow or workspace. |
 | `--copy <json\|@file>` | No | Explicit resource selections to copy into the new fork; omitted resource kinds are not copied. (JSON, or @path / @- to read a file or stdin). |
-| `--request-id <value>` | Yes | Stable client request ID for reconciliation and identical retries. |
-| `--preview-fingerprint <value>` | Yes | Fingerprint of the reviewed preview and its choices. |
+| `--request-id <value>` | Yes | Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation. |
+| `--preview-fingerprint <value>` | Yes | Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value. |
 | `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
 | `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
 
 </CommandTable>
 
+API request and response schemas: [forkWorkspace](/api-reference/workspace-sync/forkWorkspace).
+
 ### sim workspaces get
 
-Get Workspace
+Get workspace
 
 ```bash
 sim workspaces get
 ```
 
+API request and response schemas: [getWorkspace](/api-reference/workspaces/getWorkspace).
+
 ### sim workspaces fork-availability
 
-Get Workspace Fork Availability (OAuth login or personal API key required)
+Get workspace fork availability (OAuth login or personal API key required)
 
 ```bash
 sim workspaces fork-availability
 ```
 
+API request and response schemas: [getWorkspaceForkAvailability](/api-reference/workspace-sync/getWorkspaceForkAvailability).
+
 ### sim workspaces lineage
 
-Get Workspace Fork Lineage (OAuth login or personal API key required)
+Get workspace fork lineage (OAuth login or personal API key required)
 
 ```bash
 sim workspaces lineage
 ```
 
+API request and response schemas: [getWorkspaceForkLineage](/api-reference/workspace-sync/getWorkspaceForkLineage).
+
 ### sim workspaces mappings get
 
-Get Workspace Fork Mappings (OAuth login or personal API key required)
+Get workspace fork mappings (OAuth login or personal API key required)
 
 ```bash
 sim workspaces mappings get [options]
@@ -7706,14 +8522,16 @@ sim workspaces mappings get [options]
 | `--direction <value>` | Yes | Push means current to other; pull means other to current, independent of parent/child orientation. Accepted values: `push`, `pull`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--sort-by <value>` | No | Supported stable sort key for this collection. Accepted values: `id`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`. |
+| `--sort-by <value>` | No | Supported stable sort key for this collection. Defaults to "id". Accepted values: `id`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`. |
 
 </CommandTable>
 
+API request and response schemas: [getWorkspaceForkMappings](/api-reference/workspace-sync/getWorkspaceForkMappings).
+
 ### sim workspaces mappings update
 
-Update Workspace Fork Mappings (OAuth login or personal API key required)
+Update workspace fork mappings (OAuth login or personal API key required)
 
 ```bash
 sim workspaces mappings update [options]
@@ -7727,13 +8545,15 @@ sim workspaces mappings update [options]
 | --- | --- | --- |
 | `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
 | `--direction <value>` | Yes | Push means current to other; pull means other to current, independent of parent/child orientation. Accepted values: `push`, `pull`. |
-| `--mappings <json\|@file>` | Yes | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
+| `--mappings <json\|@file>` | Yes | Mapping entries addressed by resource type and `sourceId`. `targetId: null` clears a mapping. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
+API request and response schemas: [updateWorkspaceForkMappings](/api-reference/workspace-sync/updateWorkspaceForkMappings).
+
 ### sim workspaces operations get
 
-Get Workspace Operation
+Get workspace operation
 
 ```bash
 sim workspaces operations get <operationId>
@@ -7749,9 +8569,11 @@ sim workspaces operations get <operationId>
 
 </CommandTable>
 
+API request and response schemas: [getWorkspaceOperation](/api-reference/workspace-sync/getWorkspaceOperation).
+
 ### sim workspaces operations list
 
-List Workspace Operations
+List workspace operations
 
 ```bash
 sim workspaces operations list [options]
@@ -7765,13 +8587,15 @@ sim workspaces operations list [options]
 | --- | --- | --- |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--request-id <value>` | No | Stable client request ID for reconciliation and identical retries. |
+| `--request-id <value>` | No | Find an uncertain mutation by the original client request ID; keep the same filter while paging. |
 
 </CommandTable>
 
+API request and response schemas: [listWorkspaceOperations](/api-reference/workspace-sync/listWorkspaceOperations).
+
 ### sim workspaces operations wait
 
-Wait for copy and deployment readiness; exit 3 for configuration, 1 for failure, or 4 for timeout
+Wait for workspace copy and deployment readiness
 
 ```bash
 sim workspaces operations wait <operationId> [options]
@@ -7797,17 +8621,23 @@ sim workspaces operations wait <operationId> [options]
 
 </CommandTable>
 
+Exit codes: 0 completed (including completion with warnings), 1 follow-up work failed, 3 destination configuration is required, 4 timed out. The mutation may already be committed; reconcile using the same operation or request ID rather than repeating it with a new ID.
+
+API request and response schemas: [getWorkspaceOperation](/api-reference/workspace-sync/getWorkspaceOperation).
+
 ### sim workspaces permission-config
 
-Get Workspace Permission Config (OAuth login or personal API key required)
+Get workspace permission config (OAuth login or personal API key required)
 
 ```bash
 sim workspaces permission-config
 ```
 
+API request and response schemas: [getWorkspacePermissionConfig](/api-reference/workspaces/getWorkspacePermissionConfig).
+
 ### sim workspaces children
 
-List Workspace Fork Children (OAuth login or personal API key required)
+List workspace fork children (OAuth login or personal API key required)
 
 ```bash
 sim workspaces children [options]
@@ -7821,14 +8651,16 @@ sim workspaces children [options]
 | --- | --- | --- |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--sort-by <value>` | No | Supported stable sort key for this collection. Accepted values: `createdAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `desc`. |
+| `--sort-by <value>` | No | Supported stable sort key for this collection. Defaults to "createdAt". Accepted values: `createdAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `desc`. |
 
 </CommandTable>
 
+API request and response schemas: [listWorkspaceForkChildren](/api-reference/workspace-sync/listWorkspaceForkChildren).
+
 ### sim workspaces fork-resources
 
-List Workspace Fork Resources (OAuth login or personal API key required)
+List workspace fork resources (OAuth login or personal API key required)
 
 ```bash
 sim workspaces fork-resources [options]
@@ -7842,12 +8674,14 @@ sim workspaces fork-resources [options]
 | --- | --- | --- |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--kind <value>` | Yes | Resource or operation kind. Accepted values: `files`, `tables`, `knowledgeBases`, `customTools`, `skills`, `mcpServers`, `workflowMcpServers`. |
-| `--sort-by <value>` | No | Supported stable sort key for this collection. Accepted values: `id`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`. |
+| `--kind <value>` | Yes | Kind of source resource to list for copy selection. Accepted values: `files`, `tables`, `knowledgeBases`, `customTools`, `skills`, `mcpServers`, `workflowMcpServers`. |
+| `--sort-by <value>` | No | Supported stable sort key for this collection. Defaults to "id". Accepted values: `id`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`. |
 
 </CommandTable>
 
+API request and response schemas: [listWorkspaceForkResources](/api-reference/workspace-sync/listWorkspaceForkResources).
+
 ### sim workspaces members
 
 List workspace members
@@ -7866,9 +8700,11 @@ sim workspaces members [options]
 
 </CommandTable>
 
+API request and response schemas: [listWorkspaceMembers](/api-reference/workspaces/listWorkspaceMembers).
+
 ### sim workspaces list
 
-List Workspaces
+List workspaces
 
 ```bash
 sim workspaces list [options]
@@ -7880,15 +8716,17 @@ sim workspaces list [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listWorkspaces](/api-reference/workspaces/listWorkspaces).
+
 ### sim workspaces fork-preview
 
-Preview Workspace Fork (OAuth login or personal API key required)
+Preview workspace fork (OAuth login or personal API key required)
 
 ```bash
 sim workspaces fork-preview [options]
@@ -7905,9 +8743,11 @@ sim workspaces fork-preview [options]
 
 </CommandTable>
 
+API request and response schemas: [previewWorkspaceFork](/api-reference/workspace-sync/previewWorkspaceFork).
+
 ### sim workspaces pull-preview
 
-Preview Workspace Pull (OAuth login or personal API key required)
+Preview workspace pull (OAuth login or personal API key required)
 
 ```bash
 sim workspaces pull-preview [options]
@@ -7920,17 +8760,19 @@ sim workspaces pull-preview [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
+| `--mappings <json\|@file>` | No | Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync. (JSON, or @path / @- to read a file or stdin). |
+| `--dependent-values <json\|@file>` | No | Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them. (JSON, or @path / @- to read a file or stdin). |
 | `--copy-resources <json\|@file>` | No | Explicit source resources to copy before syncing the workflows. (JSON, or @path / @- to read a file or stdin). |
 | `--drop-references <json\|@file>` | No | Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped. (JSON, or @path / @- to read a file or stdin). |
 | `--trigger-mappings <json\|@file>` | No | Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
+API request and response schemas: [previewWorkspacePull](/api-reference/workspace-sync/previewWorkspacePull).
+
 ### sim workspaces push-preview
 
-Preview Workspace Push (OAuth login or personal API key required)
+Preview workspace push (OAuth login or personal API key required)
 
 ```bash
 sim workspaces push-preview [options]
@@ -7943,17 +8785,21 @@ sim workspaces push-preview [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
+| `--mappings <json\|@file>` | No | Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync. (JSON, or @path / @- to read a file or stdin). |
+| `--dependent-values <json\|@file>` | No | Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them. (JSON, or @path / @- to read a file or stdin). |
 | `--copy-resources <json\|@file>` | No | Explicit source resources to copy before syncing the workflows. (JSON, or @path / @- to read a file or stdin). |
 | `--drop-references <json\|@file>` | No | Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped. (JSON, or @path / @- to read a file or stdin). |
 | `--trigger-mappings <json\|@file>` | No | Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
+API request and response schemas: [previewWorkspacePush](/api-reference/workspace-sync/previewWorkspacePush).
+
 ### sim workspaces pull
 
-Pull Workspace (OAuth login or personal API key required)
+Pull workspace (OAuth login or personal API key required)
+
+This replaces target workflows and may archive targets whose sources were deleted.
 
 ```bash
 sim workspaces pull [options]
@@ -7966,22 +8812,26 @@ sim workspaces pull [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
+| `--mappings <json\|@file>` | No | Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync. (JSON, or @path / @- to read a file or stdin). |
+| `--dependent-values <json\|@file>` | No | Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them. (JSON, or @path / @- to read a file or stdin). |
 | `--copy-resources <json\|@file>` | No | Explicit source resources to copy before syncing the workflows. (JSON, or @path / @- to read a file or stdin). |
 | `--drop-references <json\|@file>` | No | Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped. (JSON, or @path / @- to read a file or stdin). |
 | `--trigger-mappings <json\|@file>` | No | Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected. (JSON, or @path / @- to read a file or stdin). |
-| `--request-id <value>` | Yes | Stable client request ID for reconciliation and identical retries. |
-| `--preview-fingerprint <value>` | Yes | Fingerprint of the reviewed preview and its choices. |
+| `--request-id <value>` | Yes | Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation. |
+| `--preview-fingerprint <value>` | Yes | Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value. |
 | `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
 | `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
+API request and response schemas: [pullWorkspace](/api-reference/workspace-sync/pullWorkspace).
+
 ### sim workspaces push
 
-Push Workspace (OAuth login or personal API key required)
+Push workspace (OAuth login or personal API key required)
+
+This replaces target workflows and may archive targets whose sources were deleted.
 
 ```bash
 sim workspaces push [options]
@@ -7994,22 +8844,26 @@ sim workspaces push [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
+| `--mappings <json\|@file>` | No | Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync. (JSON, or @path / @- to read a file or stdin). |
+| `--dependent-values <json\|@file>` | No | Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them. (JSON, or @path / @- to read a file or stdin). |
 | `--copy-resources <json\|@file>` | No | Explicit source resources to copy before syncing the workflows. (JSON, or @path / @- to read a file or stdin). |
 | `--drop-references <json\|@file>` | No | Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped. (JSON, or @path / @- to read a file or stdin). |
 | `--trigger-mappings <json\|@file>` | No | Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected. (JSON, or @path / @- to read a file or stdin). |
-| `--request-id <value>` | Yes | Stable client request ID for reconciliation and identical retries. |
-| `--preview-fingerprint <value>` | Yes | Fingerprint of the reviewed preview and its choices. |
+| `--request-id <value>` | Yes | Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation. |
+| `--preview-fingerprint <value>` | Yes | Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value. |
 | `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
 | `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
+API request and response schemas: [pushWorkspace](/api-reference/workspace-sync/pushWorkspace).
+
 ### sim workspaces fork-rollback
 
-Rollback Workspace Fork (OAuth login or personal API key required)
+Rollback workspace fork (OAuth login or personal API key required)
+
+This restores the latest sync using its prior deployed versions.
 
 ```bash
 sim workspaces fork-rollback [options]
@@ -8026,9 +8880,13 @@ sim workspaces fork-rollback [options]
 
 </CommandTable>
 
+API request and response schemas: [rollbackWorkspaceFork](/api-reference/workspace-sync/rollbackWorkspaceFork).
+
 ### sim workspaces unlink
 
-Unlink Workspace Fork (OAuth login or personal API key required)
+Unlink workspace fork (OAuth login or personal API key required)
+
+This removes the fork relationship and its persisted mappings.
 
 ```bash
 sim workspaces unlink [options]
@@ -8045,9 +8903,11 @@ sim workspaces unlink [options]
 
 </CommandTable>
 
+API request and response schemas: [unlinkWorkspaceFork](/api-reference/workspace-sync/unlinkWorkspaceFork).
+
 ### sim workspaces sync-exclusions
 
-Update Workspace Fork Exclusions (OAuth login or personal API key required)
+Update workspace fork exclusions (OAuth login or personal API key required)
 
 ```bash
 sim workspaces sync-exclusions [options]
@@ -8063,3 +8923,5 @@ sim workspaces sync-exclusions [options]
 | `--fork-sync-excluded <true\|false>` | Yes | Whether the named workflows should be skipped as sync sources and targets. Accepted values: `true`, `false`. |
 
 </CommandTable>
+
+API request and response schemas: [updateWorkspaceForkExclusions](/api-reference/workspace-sync/updateWorkspaceForkExclusions).
diff --git a/apps/docs/content/docs/cli/sandboxes.mdx b/apps/docs/content/docs/cli/sandboxes.mdx
index 4ebd42422e1..4382b6ec5c1 100644
--- a/apps/docs/content/docs/cli/sandboxes.mdx
+++ b/apps/docs/content/docs/cli/sandboxes.mdx
@@ -1,44 +1,43 @@
 ---
 title: Sandboxes
-description: Manage sandboxes — every subcommand, argument, and flag
+description: Manage reusable dependency sets for Function blocks.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Manage reusable dependency sets for Function blocks.
+
 `sim sandboxes` is also spelled `sim sandbox`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
 
-## Create sandbox
+## List sandboxes
 
 ```bash
-sim sandboxes create [options]
+sim sandboxes list [options]
 ```
 
-Create Sandbox (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | Yes | Display name, unique within the workspace; 1 to 64 characters. |
-| `--language <value>` | Yes | Dependency ecosystem: `javascript` installs from npm, `python` from PyPI. Accepted values: `javascript`, `python`. |
-| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
-| `--cli-tools <value...>` | No | Pinned managed CLI ids installed into the sandbox, at most 10, no duplicates. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--system-packages <value...>` | No | Debian packages installed into the sandbox, one per entry. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
+| `--search <value>` | No | Case-insensitive substring match against the sandbox name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Delete sandbox
+API request and response schemas: [listSandboxes](/api-reference/sandboxes/listSandboxes).
+
+## Get sandbox
 
 ```bash
-sim sandboxes delete <sandboxId> [options]
+sim sandboxes get <sandboxId>
 ```
 
-Delete Sandbox (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -49,20 +48,38 @@ Delete Sandbox (OAuth login or personal API key required)
 
 </CommandTable>
 
+API request and response schemas: [getSandbox](/api-reference/sandboxes/getSandbox).
+
+## Create sandbox
+
+OAuth login or personal API key required.
+
+```bash
+sim sandboxes create [options]
+```
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--name <value>` | Yes | Display name, unique within the workspace; 1 to 64 characters. |
+| `--language <value>` | Yes | Dependency ecosystem: `javascript` installs from npm, `python` from PyPI. Accepted values: `javascript`, `python`. |
+| `--dependencies <value...>` | No | Package specifiers installed into the sandbox, one per entry. Defaults to []. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
+| `--cli-tools <value...>` | No | Pinned managed CLI ids installed into the sandbox, at most 10, no duplicates. Defaults to []. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--system-packages <value...>` | No | Debian packages installed into the sandbox, one per entry. Defaults to []. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
 
 </CommandTable>
 
-## Get sandbox
+API request and response schemas: [createSandbox](/api-reference/sandboxes/createSandbox).
+
+## Update sandbox
+
+OAuth login or personal API key required.
 
 ```bash
-sim sandboxes get <sandboxId>
+sim sandboxes update <sandboxId> [options]
 ```
 
 **Arguments**
@@ -75,33 +92,32 @@ sim sandboxes get <sandboxId>
 
 </CommandTable>
 
-## List sandboxes
-
-```bash
-sim sandboxes list [options]
-```
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--search <value>` | No | Case-insensitive substring match against the sandbox name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--name <value>` | No | New display name, unique within the workspace; 1 to 64 characters. |
+| `--language <value>` | No | Replacement dependency ecosystem. The whole spec is revalidated against it, so a Python dependency list does not survive a switch to JavaScript. Accepted values: `javascript`, `python`. |
+| `--dependencies <value...>` | No | Replacement package list; replaces the whole list. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
+| `--cli-tools <value...>` | No | Replacement managed CLI list; replaces the whole list. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--system-packages <value...>` | No | Replacement Debian package list; replaces the whole list. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
 
 </CommandTable>
 
-## Update sandbox
+API request and response schemas: [updateSandbox](/api-reference/sandboxes/updateSandbox).
+
+## Delete sandbox
+
+OAuth login or personal API key required.
+
+This deletes the sandbox; Function blocks that select it fail until re-pointed.
 
 ```bash
-sim sandboxes update <sandboxId> [options]
+sim sandboxes delete <sandboxId> [options]
 ```
 
-Update Sandbox (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -118,10 +134,12 @@ Update Sandbox (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | New display name, unique within the workspace; 1 to 64 characters. |
-| `--language <value>` | No | Replacement dependency ecosystem. The whole spec is revalidated against it, so a Python dependency list does not survive a switch to JavaScript. Accepted values: `javascript`, `python`. |
-| `--dependencies <value...>` | No | Replacement package list; replaces the whole list. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
-| `--cli-tools <value...>` | No | Replacement managed CLI list; replaces the whole list. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--system-packages <value...>` | No | Replacement Debian package list; replaces the whole list. (space-separated, or @path / @- with one value per line; in a file, blank lines and # comments are ignored, while inline values are sent as typed and may not be empty; @@value for a literal leading @). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
+
+API request and response schemas: [deleteSandbox](/api-reference/sandboxes/deleteSandbox).
+
+## Related docs
+
+- [Function sandboxes](/workflows/blocks/function#sandboxes)
diff --git a/apps/docs/content/docs/cli/scripting.mdx b/apps/docs/content/docs/cli/scripting.mdx
index 7c494033d0f..cfa3efff57d 100644
--- a/apps/docs/content/docs/cli/scripting.mdx
+++ b/apps/docs/content/docs/cli/scripting.mdx
@@ -1,19 +1,24 @@
 ---
 title: Scripting
-description: File and stdin inputs, list flags, pagination, exit codes, and automation recipes
+description: Pass inputs, paginate results, and handle run and mutation outcomes in scripts.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
-Use these patterns to pass inputs, page through results, and handle command outcomes.
+Use JSON output and explicit authentication/workspace settings for unattended commands. Enable pipeline failure handling in shell scripts so a failed command is not hidden by a successful parser:
 
-## Reading input from files and stdin
+```bash
+set -euo pipefail
+export SIM_API_KEY="${SIM_API_KEY:?missing}"
+export SIM_WORKSPACE="${SIM_WORKSPACE:?missing}"
+export SIM_OUTPUT=json
+```
+
+See [Authentication](/cli/authentication#authenticating-ci) for CI setup. Examples below assume Bash and `jq`.
 
-Any flag that takes JSON or a list also accepts `@path` to read a file, or `@-`
-to read stdin.
+## Reading input from files and stdin
 
-When Sim runs a command for you, `@path` reads from the chat's sandbox, not from
-workspace Files. Use `sim files read` for a workspace path.
+JSON flags and primitive-list flags accept `@path` to read a file or `@-` to read stdin:
 
 ```bash
 sim workflows import --workflow @wf.json
@@ -21,10 +26,13 @@ sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --filter @filter.json
 cat wf.json | sim workflows import --workflow @-
 ```
 
+JSON input and the assembled JSON request body have a 10 MiB limit. JSON flags require JSON, including workflow imports; YAML exports must be converted before import. File-aware text flags, such as secret `--value`, are identified in the command reference; ordinary string flags do not all support file input.
+
+When Sim runs a command inside Chat, `@path` reads the Chat sandbox rather than workspace Files. Use `sim files read` for workspace file content. That embedded invocation has no stdin, so use `@path` or inline input instead of `@-`.
+
 ## List flags
 
-Primitive lists take space-separated values. With `@`, the file supplies one
-value per line:
+Primitive lists use space-separated values. An input file supplies one value per line:
 
 ```bash
 sim files mv --file-ids wf_3Qm8ZtLpR2yVnKd7BsXwC wf_5Hn1JvTqW9xUcMb4RzPgL --to Archive
@@ -32,26 +40,22 @@ sim files mv --file-ids @file-ids.txt --to Archive
 printf 'wf_3Qm8ZtLpR2yVnKd7BsXwC\nwf_5Hn1JvTqW9xUcMb4RzPgL\n' | sim files mv --file-ids @- --to Archive
 ```
 
-Arrays of objects stay JSON.
+Empty list entries are rejected. Arrays of objects remain JSON. Dependency-manifest flags can ignore blank lines and `#` comments; this exception does not apply to every list file.
 
 ## Passing a literal leading `@`
 
-Because `@` introduces a file reference, a value that genuinely starts with one
-is written `@@`. Only the leading `@` is dropped, and every `@`-aware flag
-accepts the escape:
+File-aware flags interpret a leading `@` as a file reference. Write `@@` to pass a literal leading `@`; only the first character is removed:
 
 ```bash
 sim files share set wf_3Qm8ZtLpR2yVnKd7BsXwC --is-active true --auth-type email --allowed-emails @@example.org
 sim secrets set API_HOST --scope workspace --value @@internal
 ```
 
-Without it, `--allowed-emails @example.org` can only be read as a request to
-open a file named `example.org`.
+Without escaping, `--allowed-emails @example.org` tries to open a file named `example.org`.
 
 ## Filtering table rows
 
-`--filter` takes the same predicate tree the API uses: `all` (AND) or `any` (OR)
-groups of `{field, op, value}` conditions, nestable.
+`--filter` accepts a predicate tree. Use `all` for AND, `any` for OR, and `{field, op, value}` for a condition. Groups can be nested:
 
 ```bash
 sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 \
@@ -60,11 +64,9 @@ sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 \
   --limit 50
 ```
 
-Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`,
-`ncontains`, `startsWith`, `endsWith`, `like`, `ilike`, `nlike`, `nilike`,
-`isEmpty`, `isNotEmpty`, `isNull`, `isNotNull`.
+Operators are `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`, `ncontains`, `startsWith`, `endsWith`, `like`, `ilike`, `nlike`, `nilike`, `isEmpty`, `isNotEmpty`, `isNull`, and `isNotNull`. Supported operators depend on the column type. Omit `value` for the empty/null checks.
 
-`--sort` is also JSON, an ordered list of keys:
+`--sort` is an ordered JSON list:
 
 ```bash
 sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --sort '[{"field":"createdAt","direction":"desc"}]'
@@ -72,210 +74,199 @@ sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --sort '[{"field":"cr
 
 ## Pagination
 
-Resource lists and directory `ls` follow every page by default. Pass `--limit N`
-to cap the returned items:
+Inventory commands such as `workflows list` and `files list`, and resource directory `ls`, fetch all pages by default. Use a limit for a smaller result:
 
 ```bash
 sim workflows list --output json
 sim files ls /Reports --limit 50
 ```
 
-Table rows (including queries), logs, audit/billing events, workflow runs and
-versions, and knowledge documents/chunks retain a default limit of `100`.
-Connector document lists also use this cap. Use `--limit 0` to fetch every page
-of a large dataset:
+Data/history lists default to 100 items, including table rows and queries, logs, audit/billing events, workflow runs/versions, and knowledge documents/chunks. Connector document lists and other bounded collections also use this default. The command reference states each invocation's limit; these CLI limits differ from API per-page defaults.
+
+`--limit 0` fetches every remaining page:
 
 ```bash
 sim logs list --limit 0 --output json > all-logs.json
 ```
 
-Pages are fetched sequentially, accumulated in memory, and printed as one
-result. A large table can consume substantial memory; use filters or an explicit
-limit when you only need a subset. Each API request fetches at most 100 items.
+Pages are fetched sequentially, accumulated in memory, and printed as one result. Each paginated API request fetches at most 100 items. For large datasets, use filters or an explicit limit.
 
-Paginated JSON and YAML results have the shape `{ data: [...], nextCursor }`.
-`nextCursor` is the cursor after the last returned row, or `null` when all pages
-have been fetched. Scripts that read list rows should use `.data[]`:
+Paginated JSON/YAML output has `{ data: [...], nextCursor }`. The cursor follows the last returned row; null ends pagination:
 
 ```bash
 sim logs list --output json | jq -r '.data[].runId'
 ```
 
-The capped dataset commands accept `--cursor` to resume from the previous
-result's `nextCursor`. Keep the same resource, filters, and sort order, and stop
-when the cursor is `null`:
+Commands with `--cursor` can continue from the previous result. Keep the same scope, resource, filters, and sort order:
 
 ```bash
-sim tables rows list tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --limit 100 --output json
-sim tables rows list tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --limit 100 --cursor "$nextCursor" --output json
+sim tables rows list tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --limit 100 --output json > page.json
+if next_cursor=$(jq -er '.nextCursor' page.json); then
+  sim tables rows list tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --limit 100 --cursor "$next_cursor" --output json
+fi
 ```
 
-`--limit` applies to each invocation starting at its cursor. `--limit 0` with
-`--cursor` fetches every remaining page. Table-row queries, logs (including
-billing and audit logs), workflow run/version histories, and knowledge
-document/chunk lists all support this continuation.
+Run the next command only when the cursor is non-null. `--limit` applies to each invocation starting at its cursor; `--limit 0 --cursor ...` fetches all remaining pages. Table-row queries, logs, billing/audit logs, workflow run/version histories, and knowledge document/chunk lists support continuation.
 
-## Organization access and invitations
+## Exit codes
+
+Results go to stdout; diagnostics go to stderr. JSON/YAML modes serialize API errors as `{error:{code,message,details?}}`. Display formats use `Error:` plus any supplied code/details. Configuration and argument-parser errors, run-wait outcome messages, and unexpected stack traces can remain text. Do not assume every stderr stream is a single JSON document.
+
+Most successful actions exit 0; API, configuration, or argument failures exit 1. Interactive secret entry cancelled with Ctrl-C exits 130. Other outcomes are command-specific:
+
+| Code | `sim whoami` |
+| --- | --- |
+| `0` | Verified, or verification skipped with `--no-verify` |
+| `1` | Missing credential or definitive refusal, including workspace access |
+| `2` | No verification verdict: unset workspace or unreachable endpoint |
+
+| Code | `sim workflows runs wait` |
+| --- | --- |
+| `0` | Completed |
+| `1` | Failed run or command/request failure |
+| `2` | Cancelled run |
+| `3` | Human pause or unspecified pause kind; input is needed |
+| `4` | Wait timed out |
+
+| Code | Workspace operation wait, or import/fork/push/pull with `--wait` |
+| --- | --- |
+| `0` | Completed, including completion with warnings |
+| `1` | Failed completion or command/request failure |
+| `3` | Committed operation requires configuration |
+| `4` | Wait timed out |
+
+Both waits default to 3600 seconds; `--wait-timeout 0` waits indefinitely. `SIM_TIMEOUT_SECONDS` independently bounds one API request. A timeout does not cancel the underlying run or operation.
 
-Organization commands use `--organization`; workspace commands use `--workspace`
-or the active profile. Use `userId` from `organizations members list` or
-`workspaces members list` for member credit limits, including external collaborators.
+A synchronous or followed workflow run prints its result before exiting 1 for failure/cancellation. A paused run is not failed and can return 0; use `runs wait` or inspect status if your script requires completion. Fetching a failed run or listing runs only reports their state.
 
-`access-requests mine` shows your requests in the selected scope. Organization
-`access-requests list` is the administrator inbox across all organization workspaces.
-Use discovery to find the exact target to submit:
+Capture a failure without losing its output:
 
 ```bash
-sim workspaces access-requests discover --workspace "$workspace_id" --state requestable --output json
-sim workspaces access-requests create --workspace "$workspace_id" \
-  --target '{"kind":"feature","configKey":"hideTablesTab"}' --reason 'Maintain team data'
-sim workspaces access-requests mine --workspace "$workspace_id"
+if sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --output json > result.json; then
+  printf 'command succeeded\n'
+else
+  status=$?
+  printf 'command exited %s; inspect result.json and stderr\n' "$status" >&2
+  exit "$status"
+fi
 ```
 
-Administrators preview a request before approving it. Inspect `canApply`, `changes`,
-and `impact`: permission approvals change the governing group for all affected
-members. Pass the reviewed fingerprint explicitly; a conflict means you need a
-new preview.
+For verification failures, inspect the endpoint, credential, and workspace before logging in again:
 
 ```bash
-sim organizations access-requests preview "$request_id" --organization "$organization_id" --output json > preview.json
-sim organizations access-requests resolve "$request_id" --organization "$organization_id" \
-  --action apply --expected-fingerprint "$(jq -r '.fingerprint' preview.json)"
+if sim whoami --output json > identity.json; then
+  :
+else
+  status=$?
+  case "$status" in
+    1) printf 'profile refused; inspect identity.json\n' >&2 ;;
+    2) printf 'verification incomplete; check workspace and endpoint\n' >&2 ;;
+  esac
+  exit "$status"
+fi
 ```
 
-For a credit-cap request, applying also requires `--new-limit-credits` greater than
-the current cap. To decline instead, use `--action decline --reason 'Explanation'`.
+See [Troubleshooting](/cli/troubleshooting) for recovery and reporting unexpected failures.
+
+## Polling a long run
 
-Administrators can also set a cap directly. `0` prevents further credit-consuming
-usage; `null` removes only the per-person cap, so organization limits still apply:
+Start asynchronously, retain the run ID, then wait:
 
 ```bash
-sim organizations members usage-limit update "$user_id" --organization "$organization_id" --credit-limit 5000
-sim organizations members usage-limit update "$user_id" --organization "$organization_id" --credit-limit null
+run_id=$(sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --async --output json | jq -er '.runId')
+sim workflows runs wait "$run_id" --workflow 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --wait-timeout 3600 --output json
 ```
 
-Workspace invitations accept a list of up to 50 emails. Recipients are processed
-independently. If any fail, the CLI prints the full result and exits `1`; successful
-invitations and grants remain committed. Inspect `failed` and current invitations
-before retrying, especially when delivery could not be confirmed.
+Time-based pauses continue waiting. Human or unspecified pauses return exit 3 and include the pause context needed by `sim workflows runs resume`. Inspect the saved result before resuming; use `sim logs get "$run_id" --trace --output table` for diagnostics.
+
+Starting another run is not an idempotent retry of the first. After a lost response or wait timeout, inspect the existing run rather than starting another execution blindly.
+
+## Selecting workflow output
+
+`--select-output` returns named values in `blockOutputs` on a synchronous run or its streamed result with `--follow`. It cannot be combined with `--async`. Use `blockName.field` selectors; outputs not produced by the run are omitted:
 
 ```bash
-sim workspaces invitations create --workspace "$workspace_id" \
-  --emails alex@example.com sam@example.com --permission write --membership member --output json
+sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --follow --select-output agent_1.content --output json
+```
+
+For a finished run, `runs get` accepts `blockName.path` or `blockId.path`. Names resolve against the workflow's current blocks:
+
+```bash
+sim workflows runs get "$run_id" --workflow 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 \
+  --select-output 1d4c8f02-7b63-4a19-8e52-63f0a7c5d9b1.content --output json
 ```
 
 ## Destructive commands
 
-Deletions require an explicit selector **and** `--yes`. There is no "delete
-everything" default:
+Deletion requires an explicit target and `--yes`; omission does not select everything:
 
 ```bash
 sim tables rows batch-delete tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --row row_2f81c0a94db54e6f8a13c7e0526bd94a row_6b3e59d0af1c42d7b80e94f3a271c568 --yes
 sim files delete wf_8Kd2NpVrY6zTfQa3XwBmS --yes
 ```
 
-Without `--yes` the command explains what it would have destroyed and stops.
+Without confirmation, the command explains the consequence and stops. Commands that support a non-writing `--dry-run` do not require `--yes` for that preview.
 
 <Callout type="warn">
-On `batch-delete` and `batch-update`, `--limit` has no default and is not a page
-size — it is a ceiling on how many matching rows the one call may touch. Leave it
-off and the command acts on **every** row the filter matches, however many that
-is. `--limit 0` is not the unbounded form here and is rejected; pass a whole
-number of 1 or more to cap the blast radius, or omit the flag deliberately.
+For row `batch-delete` and `batch-update`, `--limit` caps how many matching rows one call may change. It has no default: omission affects every matching row. `--limit 0` is rejected; use a whole number of at least 1. On `batch-delete`, an explicit `--row` list cannot be combined with this filter cap.
 </Callout>
 
-## Exit codes
+Other commands require confirmation for replacement or cancellation too. Read the [command reference](/cli/reference) for consequences, including chat-setting resets and partial table imports. Cancelling an import does not undo rows already written; replace mode clears the table before loading.
 
-| Code | Meaning |
-| --- | --- |
-| `0` | Success |
-| `1` | API/configuration/argument failure, or a failed workflow when using `workflows runs wait` |
-| `2` | `whoami`: no verification verdict; `workflows runs wait`: the run was cancelled |
-| `3` | `workflows runs wait`: the run is paused for human input |
-| `4` | `workflows runs wait`: the wait timed out |
-| `130` | Interactive secret entry was cancelled with Ctrl-C |
+## Working with folders
 
-Errors print one line to stderr, prefixed `Error:`, plus the API's error code and
-validation details when it supplies them. Failures are safe to branch on:
+Workflow, table, file, and knowledge-base directories share path commands:
 
 ```bash
-if ! sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --output json > result.json; then
-  echo "run failed" >&2
-  exit 1
-fi
+sim tables ls Reports
+sim tables mkdir Reports/Quarterly
+sim tables folders mv Reports/Quarterly Archive/Quarterly
+sim tables folders delete Archive --recursive --yes
 ```
 
-An unexpected error prints a stack trace — that is a bug in the CLI, so please
-[open an issue](https://github.com/simstudioai/sim/issues).
-
-`sim whoami` splits its failure in two because the fixes differ: `1` means the
-credentials are wrong and a fresh `sim login` is the answer, while `2` means the
-CLI never got a verdict — no workspace to check against, or an endpoint that did
-not answer — and logging in again would not help.
+`ls` lists resources at a path and that folder's direct children. It does not descend further. Pass the displayed `ref` to the next command. Use `list` for resources only or `folders ls` for folders only. A leading `/` is optional.
 
-```bash
-sim whoami > /dev/null
-case $? in
-  0) ;;                                  # ready
-  1) echo "run: sim login" >&2; exit 1 ;;
-  2) echo "endpoint unreachable, retrying later" >&2; exit 75 ;;
-esac
-```
+## Organization access and invitations
 
-## Selecting workflow output
+Organization commands use `--organization`; workspace commands use `--workspace` or the active profile. Get `userId` from `organizations members list` or `workspaces members list` when setting member credit caps, including external collaborators.
 
-`--select-output` returns the named values in `blockOutputs` on a sync run, or
-from the streamed result with `--follow`. It cannot be combined with `--async`.
-It takes `blockName.field` selectors; fields that a run did not produce are
-simply omitted:
+`access-requests mine` shows your requests in the selected scope. Organization `access-requests list` is the Admin inbox across organization workspaces. Discover the target before submitting:
 
 ```bash
-sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --follow --select-output agent_1.content --output json
+sim workspaces access-requests discover --workspace "$workspace_id" --state requestable --output json
+sim workspaces access-requests create --workspace "$workspace_id" \
+  --target '{"kind":"feature","configKey":"hideTablesTab"}' --reason 'Maintain team data'
+sim workspaces access-requests mine --workspace "$workspace_id"
 ```
 
-To narrow a run that has already finished, read it back with
-`workflows runs get`, which takes the same `blockName.path` or `blockId.path`
-selectors; names resolve against the workflow's current blocks:
+An Admin previews a request before applying it. Inspect `canApply`, `changes`, and `impact`: a permission approval changes the governing group for all affected members. Apply the reviewed fingerprint; a conflict requires a new preview:
 
 ```bash
-sim workflows runs get "$run_id" --workflow 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 \
-  --select-output 1d4c8f02-7b63-4a19-8e52-63f0a7c5d9b1.content --output json
+sim organizations access-requests preview "$request_id" --organization "$organization_id" --output json > preview.json
+sim organizations access-requests resolve "$request_id" --organization "$organization_id" \
+  --action apply --expected-fingerprint "$(jq -er '.fingerprint' preview.json)"
 ```
 
-## Polling a long run
+Applying a credit-cap request also requires `--new-limit-credits` greater than the current cap. To decline, use `--action decline --reason 'Explanation'`.
 
-Start the run asynchronously, then use the CLI’s wait command:
+An Admin can set a cap directly. Zero prevents further credit-consuming usage; `null` removes only the per-person cap, leaving organization limits in effect:
 
 ```bash
-run_id=$(sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --async --output json | jq -r '.runId')
-sim workflows runs wait "$run_id" --workflow 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --wait-timeout 3600 --output json
+sim organizations members usage-limit update "$user_id" --organization "$organization_id" --credit-limit 5000
+sim organizations members usage-limit update "$user_id" --organization "$organization_id" --credit-limit null
 ```
 
-The command polls until the run completes, fails, is cancelled, or pauses for
-human input. Time-based pauses continue waiting. Its exit code identifies the
-outcome; `--wait-timeout 0` waits indefinitely.
-
-Use `sim logs get "$run_id" --trace` for full diagnostics. A run paused for human
-input includes the context ID needed by `sim workflows runs resume`.
-
-## Working with folders
-
-Every folder-backed resource — `workflows`, `tables`, `files`, `knowledge` —
-shares the same path commands:
+Workspace invitations accept up to 50 emails. Recipients are processed independently. Any failure makes the CLI print the full result and exit 1; successful invitations and grants remain committed. Inspect `failed` and current invitations before retrying, especially when delivery was uncertain:
 
 ```bash
-sim tables ls Reports
-sim tables mkdir Reports/Quarterly
-sim tables folders mv Reports/Quarterly Archive/Quarterly
-sim tables folders delete Archive --recursive --yes
+sim workspaces invitations create --workspace "$workspace_id" \
+  --emails alex@example.com sam@example.com --permission write --membership member --output json
 ```
 
-`ls` lists the resources at a path plus that folder's direct children, never
-deeper. Its `ref` column is the value to pass to the next command. Use `list` for
-resources only, or `folders ls` for folders only. A leading `/` is optional.
-
 ## A nightly job, end to end
 
+This script starts one run, waits for its outcome, and preserves the run ID for recovery. The wait is inside an `if` so `set -e` does not exit before outcome handling:
+
 ```bash title="nightly-digest.sh"
 #!/usr/bin/env bash
 set -euo pipefail
@@ -284,10 +275,28 @@ export SIM_API_KEY="${SIM_API_KEY:?missing}"
 export SIM_WORKSPACE="${SIM_WORKSPACE:?missing}"
 export SIM_OUTPUT=json
 
-run_id=$(sim workflows run 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --input '{"source":"nightly"}' | jq -r '.runId')
+workflow_id=3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8
+sim workflows run "$workflow_id" --async --input '{"source":"nightly"}' > started.json
+run_id=$(jq -er '.runId' started.json)
 
-if [ "$(sim workflows runs get "$run_id" --workflow 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 | jq -r '.status')" != "completed" ]; then
-  sim logs get "$run_id" >&2
-  exit 1
+if sim workflows runs wait "$run_id" --workflow "$workflow_id" --wait-timeout 3600 > result.json; then
+  exit 0
+else
+  status=$?
 fi
+
+case "$status" in
+  1|2) sim logs get "$run_id" --trace --output table >&2 || true ;;
+  3) printf 'run %s needs input; inspect result.json before resuming\n' "$run_id" >&2 ;;
+  4) printf 'wait expired; inspect existing run %s before retrying\n' "$run_id" >&2 ;;
+esac
+exit "$status"
 ```
+
+## Related docs
+
+- [Output formats](/cli/output)
+- [Workflow commands](/cli/workflows)
+- [Workflow imports and workspace sync](/cli/workflow-sync)
+- [Organization commands](/cli/organizations)
+- [Troubleshooting](/cli/troubleshooting)
diff --git a/apps/docs/content/docs/cli/secrets.mdx b/apps/docs/content/docs/cli/secrets.mdx
index 2b6d70dc1f5..1027c17bea1 100644
--- a/apps/docs/content/docs/cli/secrets.mdx
+++ b/apps/docs/content/docs/cli/secrets.mdx
@@ -1,51 +1,26 @@
 ---
 title: Secrets
-description: Manage secrets — every subcommand, argument, and flag
+description: Set and manage workspace or personal secrets.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-`sim secrets` is also spelled `sim secret`.
-
-Every command below also accepts the [global options](/cli/commands#global-options).
-
-## Delete secret
-
-```bash
-sim secrets delete <name> [options]
-```
-
-Delete Secret (OAuth login or personal API key required)
-
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `name` | Yes | Secret to delete. |
+Set and manage workspace or personal secrets.
 
-</CommandTable>
-
-**Options**
-
-<CommandTable>
+Personal secrets belong to the caller across workspaces. Workspace secrets are shared resources. Listings include stored values only for workspace secrets marked visible (unredacted); all other entries contain metadata.
 
-| Option | Required | Description |
-| --- | --- | --- |
-| `--scope <value>` | Yes | Whether the secret belongs to the workspace or to the caller. A personal secret belongs to the caller across every workspace, not to one workspace. Accepted values: `workspace`, `personal`. |
-| `-y, --yes` | Yes | Confirm this operation. |
+`sim secrets` is also spelled `sim secret`.
 
-</CommandTable>
+These commands accept the [global options](/cli/commands#global-options).
 
 ## List secrets
 
+OAuth login or personal API key required.
+
 ```bash
 sim secrets list [options]
 ```
 
-List Secrets (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -54,20 +29,22 @@ List Secrets (OAuth login or personal API key required)
 | --- | --- | --- |
 | `--scope <value>` | No | Restrict results to one ownership scope. Accepted values: `workspace`, `personal`. |
 | `--search <value>` | No | Case-insensitive substring match against the secret name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listSecrets](/api-reference/secrets/listSecrets).
+
 ## Create or replace a named secret, such as an API key or environment variable
 
+OAuth login or personal API key required.
+
 ```bash
 sim secrets set <name> [options]
 ```
 
-Create or replace a named secret, such as an API key or environment variable (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -91,3 +68,44 @@ Create or replace a named secret, such as an API key or environment variable (OA
 | `--no-unredacted` | No | Send --unredacted as false. |
 
 </CommandTable>
+
+Omit --value to enter it privately in a terminal. For an existing workspace secret, passing only --description or a redaction flag keeps the stored value and does not prompt. Personal secrets always require a value; they accept no writable metadata. In scripts, pass --value @path or --value @-.
+
+API request and response schemas: [setSecret](/api-reference/secrets/setSecret).
+
+## Delete secret
+
+OAuth login or personal API key required.
+
+This deletes the secret; anything using it may stop working.
+
+```bash
+sim secrets delete <name> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `name` | Yes | Secret to delete. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--scope <value>` | Yes | Whether the secret belongs to the workspace or to the caller. A personal secret belongs to the caller across every workspace, not to one workspace. Accepted values: `workspace`, `personal`. |
+| `-y, --yes` | Yes | Confirm this operation. |
+
+</CommandTable>
+
+API request and response schemas: [deleteSecret](/api-reference/secrets/deleteSecret).
+
+## Related docs
+
+- [Credentials and secrets](/platform/credentials)
diff --git a/apps/docs/content/docs/cli/selectors.mdx b/apps/docs/content/docs/cli/selectors.mdx
index 6ec54c24305..7a13af40734 100644
--- a/apps/docs/content/docs/cli/selectors.mdx
+++ b/apps/docs/content/docs/cli/selectors.mdx
@@ -1,50 +1,58 @@
 ---
 title: Selectors
-description: Manage selectors — every subcommand, argument, and flag
+description: Discover destination options for registered fields, such as calendars, channels, and tables.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+Discover destination options for registered fields, such as calendars, channels, and tables.
 
-## Get selector option
+A selector key identifies the field’s option source. Its context accepts only declared dependencies; missing OAuth access requires a person to authorize the connection.
+
+These commands accept the [global options](/cli/commands#global-options).
+
+## List selector options
+
+OAuth login or personal API key required.
 
 ```bash
-sim selectors get [options]
+sim selectors list [options]
 ```
 
-Get Selector Option (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--selector-key <value>` | Yes | Registered selector key for discovering this field’s destination options. Accepted values: `airtable.bases`, `airtable.tables`, `asana.workspaces`, `attio.lists`, `attio.objects`, `bigquery.datasets`, `bigquery.tables`, `bitbucket.workspaces`, `bitbucket.repositories`, `calcom.eventTypes`, `calcom.schedules`, `clickup.workspaces`, `clickup.spaces`, `clickup.folders`, `clickup.lists`, `coda.docs`, `coda.pages`, `coda.tables`, `coda.columns`, `coda.rows`, `coda.formulas`, `coda.controls`, `coda.folders`, `coda.permissions`, `confluence.spaces`, `confluence.spacesById`, `confluence.pages`, `google.tasks.lists`, `fivetran.groups`, `fivetran.connections`, `gmail.labels`, `google.calendar`, `google.drive`, `google.sheets`, `harmonic.savedSearches`, `hubspot.lists`, `hubspot.owners`, `hubspot.pipelines`, `hubspot.pipelineStages`, `hubspot.properties`, `jsm.requestTypes`, `jsm.serviceDesks`, `microsoft.planner.plans`, `notion.databases`, `notion.pages`, `netsuite.recordTypes`, `netsuite.asyncTasks`, `pipedrive.pipelines`, `sharepoint.lists`, `trello.boards`, `zoho_desk.organizations`, `zoho_desk.departments`, `zoho_desk.agents`, `zoom.meetings`, `slack.channels`, `snowflake.databases`, `snowflake.schemas`, `snowflake.tables`, `snowflake.warehouses`, `snowflake.roles`, `snowflake.fileFormats`, `snowflake.procedures`, `slack.users`, `outlook.folders`, `outlook.calendars`, `microsoft.teams`, `microsoft.chats`, `microsoft.channels`, `microsoft.planner`, `onedrive.files`, `onedrive.folders`, `sharepoint.sites`, `microsoft.excel`, `microsoft.excel.drives`, `microsoft.excel.sheets`, `microsoft.word`, `wealthbox.contacts`, `jira.issues`, `jira.projects`, `jira.projectKeys`, `linear.projects`, `linear.teams`, `monday.boards`, `monday.groups`, `webflow.sites`, `webflow.collections`, `webflow.items`, `planetscale.databases`, `powerbi.workspaces`, `powerbi.datasets`, `powerbi.reports`, `planetscale.branches`, `planetscale.backups`, `planetscale.deployRequests`, `cloudwatch.logGroups`, `cloudwatch.logStreams`, `imap.mailboxes`, `mcp.tools`, `managedAgent.agents`, `managedAgent.environments`, `managedAgent.vaults`, `managedAgent.memoryStores`, `knowledge.documents`, `sim.workflows`, `table.columns`, `table.outputColumns`, `workspace.secretNames`, `workspace.sandboxes`, `providers.ollamaEmbeddingModels`, `providers.openrouterEmbeddingModels`. |
-| `--context <json\|@file>` | No | Only the dependencies declared by the selector, such as oauthCredential and channelId. Missing OAuth connections require human authorization. (JSON, or @path / @- to read a file or stdin). |
-| `--id <value>` | Yes | Resource identifier. |
+| `--selector-key <value>` | Yes | Registered selector key from an import or sync preview, such as `gmail.labels`. Accepted values: `airtable.bases`, `airtable.tables`, `asana.workspaces`, `attio.lists`, `attio.objects`, `bigquery.datasets`, `bigquery.tables`, `bitbucket.workspaces`, `bitbucket.repositories`, `calcom.eventTypes`, `calcom.schedules`, `clickup.workspaces`, `clickup.spaces`, `clickup.folders`, `clickup.lists`, `coda.docs`, `coda.pages`, `coda.tables`, `coda.columns`, `coda.rows`, `coda.formulas`, `coda.controls`, `coda.folders`, `coda.permissions`, `confluence.spaces`, `confluence.spacesById`, `confluence.pages`, `google.tasks.lists`, `fivetran.groups`, `fivetran.connections`, `gmail.labels`, `google.calendar`, `google.drive`, `google.sheets`, `harmonic.savedSearches`, `hubspot.lists`, `hubspot.owners`, `hubspot.pipelines`, `hubspot.pipelineStages`, `hubspot.properties`, `jsm.requestTypes`, `jsm.serviceDesks`, `microsoft.planner.plans`, `notion.databases`, `notion.pages`, `netsuite.recordTypes`, `netsuite.asyncTasks`, `pipedrive.pipelines`, `sharepoint.lists`, `trello.boards`, `zoho_desk.organizations`, `zoho_desk.departments`, `zoho_desk.agents`, `zoom.meetings`, `slack.channels`, `snowflake.databases`, `snowflake.schemas`, `snowflake.tables`, `snowflake.warehouses`, `snowflake.roles`, `snowflake.fileFormats`, `snowflake.procedures`, `slack.users`, `outlook.folders`, `outlook.calendars`, `microsoft.teams`, `microsoft.chats`, `microsoft.channels`, `microsoft.planner`, `onedrive.files`, `onedrive.folders`, `sharepoint.sites`, `microsoft.excel`, `microsoft.excel.drives`, `microsoft.excel.sheets`, `microsoft.word`, `wealthbox.contacts`, `jira.issues`, `jira.projects`, `jira.projectKeys`, `linear.projects`, `linear.teams`, `monday.boards`, `monday.groups`, `webflow.sites`, `webflow.collections`, `webflow.items`, `planetscale.databases`, `powerbi.workspaces`, `powerbi.datasets`, `powerbi.reports`, `planetscale.branches`, `planetscale.backups`, `planetscale.deployRequests`, `cloudwatch.logGroups`, `cloudwatch.logStreams`, `imap.mailboxes`, `mcp.tools`, `managedAgent.agents`, `managedAgent.environments`, `managedAgent.vaults`, `managedAgent.memoryStores`, `knowledge.documents`, `sim.workflows`, `table.columns`, `table.outputColumns`, `workspace.secretNames`, `workspace.sandboxes`, `providers.ollamaEmbeddingModels`, `providers.openrouterEmbeddingModels`. |
+| `--context <json\|@file>` | No | Only the dependencies declared by the selector, such as oauthCredential and channelId. Missing OAuth connections require human authorization. Defaults to &#123;&#125;. (JSON, or @path / @- to read a file or stdin). |
+| `--search <value>` | No | Provider option search text. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 
 </CommandTable>
 
-## List selector options
+API request and response schemas: [listSelector](/api-reference/workspace-sync/listSelector).
+
+## Get selector option
+
+OAuth login or personal API key required.
 
 ```bash
-sim selectors list [options]
+sim selectors get [options]
 ```
 
-List Selector Options (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--selector-key <value>` | Yes | Registered selector key for discovering this field’s destination options. Accepted values: `airtable.bases`, `airtable.tables`, `asana.workspaces`, `attio.lists`, `attio.objects`, `bigquery.datasets`, `bigquery.tables`, `bitbucket.workspaces`, `bitbucket.repositories`, `calcom.eventTypes`, `calcom.schedules`, `clickup.workspaces`, `clickup.spaces`, `clickup.folders`, `clickup.lists`, `coda.docs`, `coda.pages`, `coda.tables`, `coda.columns`, `coda.rows`, `coda.formulas`, `coda.controls`, `coda.folders`, `coda.permissions`, `confluence.spaces`, `confluence.spacesById`, `confluence.pages`, `google.tasks.lists`, `fivetran.groups`, `fivetran.connections`, `gmail.labels`, `google.calendar`, `google.drive`, `google.sheets`, `harmonic.savedSearches`, `hubspot.lists`, `hubspot.owners`, `hubspot.pipelines`, `hubspot.pipelineStages`, `hubspot.properties`, `jsm.requestTypes`, `jsm.serviceDesks`, `microsoft.planner.plans`, `notion.databases`, `notion.pages`, `netsuite.recordTypes`, `netsuite.asyncTasks`, `pipedrive.pipelines`, `sharepoint.lists`, `trello.boards`, `zoho_desk.organizations`, `zoho_desk.departments`, `zoho_desk.agents`, `zoom.meetings`, `slack.channels`, `snowflake.databases`, `snowflake.schemas`, `snowflake.tables`, `snowflake.warehouses`, `snowflake.roles`, `snowflake.fileFormats`, `snowflake.procedures`, `slack.users`, `outlook.folders`, `outlook.calendars`, `microsoft.teams`, `microsoft.chats`, `microsoft.channels`, `microsoft.planner`, `onedrive.files`, `onedrive.folders`, `sharepoint.sites`, `microsoft.excel`, `microsoft.excel.drives`, `microsoft.excel.sheets`, `microsoft.word`, `wealthbox.contacts`, `jira.issues`, `jira.projects`, `jira.projectKeys`, `linear.projects`, `linear.teams`, `monday.boards`, `monday.groups`, `webflow.sites`, `webflow.collections`, `webflow.items`, `planetscale.databases`, `powerbi.workspaces`, `powerbi.datasets`, `powerbi.reports`, `planetscale.branches`, `planetscale.backups`, `planetscale.deployRequests`, `cloudwatch.logGroups`, `cloudwatch.logStreams`, `imap.mailboxes`, `mcp.tools`, `managedAgent.agents`, `managedAgent.environments`, `managedAgent.vaults`, `managedAgent.memoryStores`, `knowledge.documents`, `sim.workflows`, `table.columns`, `table.outputColumns`, `workspace.secretNames`, `workspace.sandboxes`, `providers.ollamaEmbeddingModels`, `providers.openrouterEmbeddingModels`. |
-| `--context <json\|@file>` | No | Only the dependencies declared by the selector, such as oauthCredential and channelId. Missing OAuth connections require human authorization. (JSON, or @path / @- to read a file or stdin). |
-| `--search <value>` | No | Provider option search text. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--selector-key <value>` | Yes | Registered selector key from an import or sync preview, such as `gmail.labels`. Accepted values: `airtable.bases`, `airtable.tables`, `asana.workspaces`, `attio.lists`, `attio.objects`, `bigquery.datasets`, `bigquery.tables`, `bitbucket.workspaces`, `bitbucket.repositories`, `calcom.eventTypes`, `calcom.schedules`, `clickup.workspaces`, `clickup.spaces`, `clickup.folders`, `clickup.lists`, `coda.docs`, `coda.pages`, `coda.tables`, `coda.columns`, `coda.rows`, `coda.formulas`, `coda.controls`, `coda.folders`, `coda.permissions`, `confluence.spaces`, `confluence.spacesById`, `confluence.pages`, `google.tasks.lists`, `fivetran.groups`, `fivetran.connections`, `gmail.labels`, `google.calendar`, `google.drive`, `google.sheets`, `harmonic.savedSearches`, `hubspot.lists`, `hubspot.owners`, `hubspot.pipelines`, `hubspot.pipelineStages`, `hubspot.properties`, `jsm.requestTypes`, `jsm.serviceDesks`, `microsoft.planner.plans`, `notion.databases`, `notion.pages`, `netsuite.recordTypes`, `netsuite.asyncTasks`, `pipedrive.pipelines`, `sharepoint.lists`, `trello.boards`, `zoho_desk.organizations`, `zoho_desk.departments`, `zoho_desk.agents`, `zoom.meetings`, `slack.channels`, `snowflake.databases`, `snowflake.schemas`, `snowflake.tables`, `snowflake.warehouses`, `snowflake.roles`, `snowflake.fileFormats`, `snowflake.procedures`, `slack.users`, `outlook.folders`, `outlook.calendars`, `microsoft.teams`, `microsoft.chats`, `microsoft.channels`, `microsoft.planner`, `onedrive.files`, `onedrive.folders`, `sharepoint.sites`, `microsoft.excel`, `microsoft.excel.drives`, `microsoft.excel.sheets`, `microsoft.word`, `wealthbox.contacts`, `jira.issues`, `jira.projects`, `jira.projectKeys`, `linear.projects`, `linear.teams`, `monday.boards`, `monday.groups`, `webflow.sites`, `webflow.collections`, `webflow.items`, `planetscale.databases`, `powerbi.workspaces`, `powerbi.datasets`, `powerbi.reports`, `planetscale.branches`, `planetscale.backups`, `planetscale.deployRequests`, `cloudwatch.logGroups`, `cloudwatch.logStreams`, `imap.mailboxes`, `mcp.tools`, `managedAgent.agents`, `managedAgent.environments`, `managedAgent.vaults`, `managedAgent.memoryStores`, `knowledge.documents`, `sim.workflows`, `table.columns`, `table.outputColumns`, `workspace.secretNames`, `workspace.sandboxes`, `providers.ollamaEmbeddingModels`, `providers.openrouterEmbeddingModels`. |
+| `--context <json\|@file>` | No | Only the dependencies declared by the selector, such as oauthCredential and channelId. Missing OAuth connections require human authorization. Defaults to &#123;&#125;. (JSON, or @path / @- to read a file or stdin). |
+| `--id <value>` | Yes | Provider option ID to resolve with the same selector and declared context. |
 
 </CommandTable>
+
+API request and response schemas: [getSelector](/api-reference/workspace-sync/getSelector).
diff --git a/apps/docs/content/docs/cli/skills.mdx b/apps/docs/content/docs/cli/skills.mdx
index 76bdf2da396..e2bb3753445 100644
--- a/apps/docs/content/docs/cli/skills.mdx
+++ b/apps/docs/content/docs/cli/skills.mdx
@@ -1,42 +1,45 @@
 ---
 title: Skills
-description: Manage skills — every subcommand, argument, and flag
+description: Create reusable agent instructions and manage their editors.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Create reusable agent instructions and manage their editors.
+
 `sim skills` is also spelled `sim skill`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
+
+## Skill instructions
 
-## Create skill
+### List skills
 
 ```bash
-sim skills create [options]
+sim skills list [options]
 ```
 
-Create Skill (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | Yes | Kebab-case name, unique within the workspace and not reserved by a built-in skill. |
-| `--description <value>` | Yes | One-line summary of when the skill applies. |
-| `--content <value>` | Yes | Skill body containing the instructions given to the agent. |
+| `--search <value>` | No | Case-insensitive substring match against the skill name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Delete skill
+API request and response schemas: [listSkills](/api-reference/skills/listSkills).
+
+### Get skill
 
 ```bash
-sim skills delete <skillId> [options]
+sim skills get <skillId>
 ```
 
-Delete Skill (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -47,20 +50,36 @@ Delete Skill (OAuth login or personal API key required)
 
 </CommandTable>
 
+API request and response schemas: [getSkill](/api-reference/skills/getSkill).
+
+### Create skill
+
+OAuth login or personal API key required.
+
+```bash
+sim skills create [options]
+```
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--name <value>` | Yes | Kebab-case name, unique within the workspace and not reserved by a built-in skill. |
+| `--description <value>` | Yes | One-line summary of when the skill applies. |
+| `--content <value>` | Yes | Skill body containing the instructions given to the agent. |
 
 </CommandTable>
 
-## Get skill
+API request and response schemas: [createSkill](/api-reference/skills/createSkill).
+
+### Update skill
+
+OAuth login or personal API key required.
 
 ```bash
-sim skills get <skillId>
+sim skills update <skillId> [options]
 ```
 
 **Arguments**
@@ -73,14 +92,28 @@ sim skills get <skillId>
 
 </CommandTable>
 
-## Grant skill editor
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--name <value>` | No | New kebab-case skill name. |
+| `--description <value>` | No | New one-line summary of when the skill applies. |
+| `--content <value>` | No | Replacement skill body. |
+
+</CommandTable>
+
+API request and response schemas: [updateSkill](/api-reference/skills/updateSkill).
+
+## Editors
+
+### List skill editors
 
 ```bash
-sim skills editors create <skillId> [options]
+sim skills editors list <skillId> [options]
 ```
 
-Grant Skill Editor (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -97,14 +130,20 @@ Grant Skill Editor (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--email <value>` | Yes | Email address of a current workspace member. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "email". Accepted values: `email`, `name`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## List skill editors
+API request and response schemas: [listSkillEditors](/api-reference/skills/listSkillEditors).
+
+### Grant skill editor
+
+OAuth login or personal API key required.
 
 ```bash
-sim skills editors list <skillId> [options]
+sim skills editors create <skillId> [options]
 ```
 
 **Arguments**
@@ -123,20 +162,22 @@ sim skills editors list <skillId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `email`, `name`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--email <value>` | Yes | Email address of a current workspace member. |
 
 </CommandTable>
 
-## Revoke skill editor
+API request and response schemas: [grantSkillEditor](/api-reference/skills/grantSkillEditor).
+
+### Revoke skill editor
+
+OAuth login or personal API key required.
+
+This revokes the explicit skill editor grant for the selected email.
 
 ```bash
 sim skills editors delete <skillId> [options]
 ```
 
-Revoke Skill Editor (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -158,33 +199,20 @@ Revoke Skill Editor (OAuth login or personal API key required)
 
 </CommandTable>
 
-## List skills
-
-```bash
-sim skills list [options]
-```
-
-**Options**
+API request and response schemas: [revokeSkillEditor](/api-reference/skills/revokeSkillEditor).
 
-<CommandTable>
+## Delete skills
 
-| Option | Required | Description |
-| --- | --- | --- |
-| `--search <value>` | No | Case-insensitive substring match against the skill name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+### Delete skill
 
-</CommandTable>
+OAuth login or personal API key required.
 
-## Update skill
+This deletes the skill.
 
 ```bash
-sim skills update <skillId> [options]
+sim skills delete <skillId> [options]
 ```
 
-Update Skill (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -201,8 +229,12 @@ Update Skill (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | New kebab-case skill name. |
-| `--description <value>` | No | New one-line summary of when the skill applies. |
-| `--content <value>` | No | Replacement skill body. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
+
+API request and response schemas: [deleteSkill](/api-reference/skills/deleteSkill).
+
+## Related docs
+
+- [Skills](/agents/skills)
diff --git a/apps/docs/content/docs/cli/tables.mdx b/apps/docs/content/docs/cli/tables.mdx
index 79f0a440134..ce1f3e06bec 100644
--- a/apps/docs/content/docs/cli/tables.mdx
+++ b/apps/docs/content/docs/cli/tables.mdx
@@ -1,44 +1,45 @@
 ---
 title: Tables
-description: Manage tables — every subcommand, argument, and flag
+description: Manage tables, rows, schemas, views, enrichment runs, imports, and exports.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Manage tables, rows, schemas, views, enrichment runs, imports, and exports.
+
 `sim tables` is also spelled `sim table`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
+
+## Tables
 
-## Add column
+### List tables
 
 ```bash
-sim tables columns create <tableId> [options]
+sim tables list [options]
 ```
 
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `tableId` | Yes | Unique table identifier. |
-
-</CommandTable>
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--column <json\|@file>` | Yes | Column definition to add. (JSON, or @path / @- to read a file or stdin). |
+| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live tables, `archived` for tables a delete archived and a table restore can bring back. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
+| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
+| `--search <value>` | No | Case-insensitive substring match against the resource name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Delete column
+API request and response schemas: [listTables](/api-reference/tables/listTables).
+
+### Get table
 
 ```bash
-sim tables columns delete <tableId> [options]
+sim tables get <tableId>
 ```
 
 **Arguments**
@@ -51,21 +52,33 @@ sim tables columns delete <tableId> [options]
 
 </CommandTable>
 
+API request and response schemas: [getTable](/api-reference/tables/getTable).
+
+### Create table
+
+```bash
+sim tables create [options]
+```
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--column-name <value>` | Yes | Name of the column to delete. |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--name <value>` | Yes | Identifier: letters, numbers, and underscores; cannot start with a number. |
+| `--description <value>` | No | Optional table description. |
+| `--schema <json\|@file>` | Yes | Table schema: &#123;"columns":[&#123;"name":"email","type":"string"&#125;]&#125; (JSON, or @path / @- to read a file or stdin). |
+| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 
 </CommandTable>
 
-## Update column
+API request and response schemas: [createTable](/api-reference/tables/createTable).
+
+### Update table
 
 ```bash
-sim tables columns update <tableId> [options]
+sim tables update <tableId> [options]
 ```
 
 **Arguments**
@@ -84,44 +97,59 @@ sim tables columns update <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--column-name <value>` | Yes | Current name of the column to update. |
-| `--updates <json\|@file>` | Yes | Mutable column fields. (JSON, or @path / @- to read a file or stdin). |
+| `--name <value>` | No | Identifier: letters, numbers, and underscores; cannot start with a number. |
+| `--description <value>` | No | Replacement table description, or null to clear it. (--description null sends the word, not JSON null). |
+| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 
 </CommandTable>
 
-## Add workflow group
+API request and response schemas: [updateTable](/api-reference/tables/updateTable).
+
+### Move tables and folders
 
 ```bash
-sim tables groups create <tableId> [options]
+sim tables move [options]
 ```
 
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `tableId` | Yes | Unique table identifier. |
+| `--table-ids <json\|@file>` | No | Tables to move, by identifier. Defaults to []. (JSON, or @path / @- to read a file or stdin). |
+| `--folder <value...>` | No | Table folders to move, by path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--to <value>` | No | Destination folder path; omit for root. |
 
 </CommandTable>
 
-**Options**
+API request and response schemas: [moveTables](/api-reference/tables/moveTables).
+
+### Move a table to a folder
+
+```bash
+sim tables mv <tableId> <folder>
+```
+
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--group <json\|@file>` | Yes | Workflow or enrichment producer definition. (JSON, or @path / @- to read a file or stdin). |
-| `--output-columns <json\|@file>` | No | Columns to create for producer outputs. An entry naming a column the table already has attaches that column to the group instead of creating it (its `type` must match), and an output whose column already exists may omit its entry entirely — so `[]` attaches existing columns only. (JSON, or @path / @- to read a file or stdin). |
-| `--auto-run` | No | Whether to schedule existing rows after group creation. |
-| `--no-auto-run` | No | Send --auto-run as false. |
+| `tableId` | Yes | Unique table identifier. |
+| `folder` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-## Delete workflow group
+API request and response schemas: [updateTable](/api-reference/tables/updateTable).
+
+### Delete table
+
+This archives the table and all of its rows; restore with `tables restore`.
 
 ```bash
-sim tables groups delete <tableId> [options]
+sim tables delete <tableId> [options]
 ```
 
 **Arguments**
@@ -140,31 +168,38 @@ sim tables groups delete <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--group-id <value>` | Yes | Workflow group to delete. |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## List workflow groups
+API request and response schemas: [deleteTable](/api-reference/tables/deleteTable).
+
+### Bulk delete tables and folders
+
+This archives the selected tables and folders, including their rows. Restore eligible tables with `tables restore`.
 
 ```bash
-sim tables groups list <tableId>
+sim tables batch-delete [options]
 ```
 
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `tableId` | Yes | Unique table identifier. |
+| `--table-ids <json\|@file>` | No | Tables to archive, by identifier. Defaults to []. (JSON, or @path / @- to read a file or stdin). |
+| `--folder <value...>` | No | Folder path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Update workflow group
+API request and response schemas: [bulkDeleteTables](/api-reference/tables/bulkDeleteTables).
+
+### Restore an archived table
 
 ```bash
-sim tables groups update <tableId> [options]
+sim tables restore <tableId>
 ```
 
 **Arguments**
@@ -177,49 +212,45 @@ sim tables groups update <tableId> [options]
 
 </CommandTable>
 
-**Options**
+API request and response schemas: [restoreTable](/api-reference/tables/restoreTable).
+
+## Rows and queries
+
+### List rows
+
+```bash
+sim tables rows list <tableId> [options]
+```
+
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--group-id <value>` | Yes | Workflow group to update. |
-| `--workflow-id <value>` | No | Replacement backing workflow identifier. |
-| `--name <value>` | No | Replacement workflow-group display name. |
-| `--dependencies <json\|@file>` | No | Replacement input dependencies. (JSON, or @path / @- to read a file or stdin). |
-| `--outputs <json\|@file>` | No | Replacement producer outputs. (JSON, or @path / @- to read a file or stdin). |
-| `--new-output-columns <json\|@file>` | No | Columns to add for new outputs. (JSON, or @path / @- to read a file or stdin). |
-| `--mapping-updates <json\|@file>` | No | Existing output-column mapping changes. (JSON, or @path / @- to read a file or stdin). |
-| `--input-mappings <json\|@file>` | No | Replacement workflow input mappings. (JSON, or @path / @- to read a file or stdin). |
-| `--deployment-mode <value>` | No | Replacement workflow execution mode. Accepted values: `live`, `deployed`. |
-| `--type <value>` | No | Workflow-group producer type. Must match the group's stored type — a group's producer cannot be changed after creation. Accepted values: `manual`, `enrichment`. |
-| `--auto-run` | No | Replacement automatic-run setting. |
-| `--no-auto-run` | No | Send --auto-run as false. |
+| `tableId` | Yes | Unique table identifier. |
 
 </CommandTable>
 
-## Bulk delete tables and folders
-
-```bash
-sim tables batch-delete [options]
-```
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--table-ids <json\|@file>` | No | Tables to archive, by identifier. (JSON, or @path / @- to read a file or stdin). |
-| `--folder <value...>` | No | Folder path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--include-run-state` | No | Include per-workflow-group run outcomes on every row. Off by default. Caps `limit` at 200. Run state above 2 MiB returns `413`; request fewer rows or omit run state. |
+| `--no-include-run-state` | No | Send --include-run-state as false. |
 
 </CommandTable>
 
-## Apply a distinct patch to each listed row
+API request and response schemas: [listTableRows](/api-reference/tables/listTableRows).
+
+### Get row
 
 ```bash
-sim tables rows update-each <tableId> [options]
+sim tables rows get <tableId> <rowId> [options]
 ```
 
 **Arguments**
@@ -229,6 +260,7 @@ sim tables rows update-each <tableId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
+| `rowId` | Yes | Unique table row identifier. |
 
 </CommandTable>
 
@@ -238,14 +270,17 @@ sim tables rows update-each <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--updates <json\|@file>` | Yes | One merge patch per row. Each row identifier may appear at most once. (JSON, or @path / @- to read a file or stdin). |
+| `--include-run-state` | No | Include per-workflow-group run outcomes on the row. Off by default. Run state above 2 MiB returns `413`; omit this option to read the row without run state. |
+| `--no-include-run-state` | No | Send --include-run-state as false. |
 
 </CommandTable>
 
-## Create rows
+API request and response schemas: [getTableRow](/api-reference/tables/getTableRow).
+
+### Query rows with a filter and sort
 
 ```bash
-sim tables rows create <tableId> [options]
+sim tables rows query <tableId> [options]
 ```
 
 **Arguments**
@@ -264,15 +299,21 @@ sim tables rows create <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--data <json\|@file>` | No | One row keyed by column name (JSON, or @path / @-; choose exactly one body flag). |
-| `--rows <json\|@file>` | No | Several rows keyed by column name (JSON, or @path / @-; choose exactly one body flag). |
+| `--filter <json\|@file>` | No | Condition: &#123;"field":"status","op":"eq","value":"active"&#125;. Groups: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125; or &#123;"any":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; group entries may also be nested groups. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
+| `--sort <json\|@file>` | No | Ordered sort keys: [&#123;"field":"createdAt","direction":"desc"&#125;] (direction: asc or desc) (JSON, or @path / @- to read a file or stdin). |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--include-run-state` | No | Include per-workflow-group run outcomes on every row. Off by default. Each request above 2 MiB of run state returns 413; request fewer rows or omit run state. CLI --limit 0 still fetches bounded pages. |
+| `--no-include-run-state` | No | Send --include-run-state as false. |
 
 </CommandTable>
 
-## Delete row
+API request and response schemas: [queryRows](/api-reference/tables/queryTableRows).
+
+### Count rows matching a filter
 
 ```bash
-sim tables rows delete <tableId> <rowId> [options]
+sim tables rows count <tableId> [options]
 ```
 
 **Arguments**
@@ -282,7 +323,6 @@ sim tables rows delete <tableId> <rowId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
-| `rowId` | Yes | Unique table row identifier. |
 
 </CommandTable>
 
@@ -292,14 +332,16 @@ sim tables rows delete <tableId> <rowId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--filter <json\|@file>` | No | Condition: &#123;"field":"status","op":"eq","value":"active"&#125;. Groups: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125; or &#123;"any":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; group entries may also be nested groups. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Delete rows matching a filter, or an explicit list of ids
+API request and response schemas: [queryRowsCount](/api-reference/tables/countTableRows).
+
+### Search cells for a value and return their coordinates
 
 ```bash
-sim tables rows batch-delete <tableId> [options]
+sim tables rows search <tableId> [options]
 ```
 
 **Arguments**
@@ -318,17 +360,18 @@ sim tables rows batch-delete <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
+| `--query <value>` | Yes | Value to search for. |
 | `--filter <json\|@file>` | No | Predicate: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; groups use all/any. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
-| `--limit <value>` | No | Maximum matching rows to delete. (caps a --filter match only; omit it to act on every match, and note 0 is not accepted). |
-| `--row <value...>` | No | Explicit row identifiers to delete. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--sort <json\|@file>` | No | Ordered sort keys: [&#123;"field":"createdAt","direction":"desc"&#125;] (direction: asc or desc) (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Get row
+API request and response schemas: [searchTableRows](/api-reference/tables/searchTableRows).
+
+### Create rows
 
 ```bash
-sim tables rows get <tableId> <rowId> [options]
+sim tables rows create <tableId> [options]
 ```
 
 **Arguments**
@@ -338,7 +381,6 @@ sim tables rows get <tableId> <rowId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
-| `rowId` | Yes | Unique table row identifier. |
 
 </CommandTable>
 
@@ -348,15 +390,17 @@ sim tables rows get <tableId> <rowId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--include-run-state` | No | Include per-workflow-group run state on the returned row. Off by default. |
-| `--no-include-run-state` | No | Send --include-run-state as false. |
+| `--data <json\|@file>` | No | One row keyed by column name (JSON, or @path / @-; choose exactly one body flag). |
+| `--rows <json\|@file>` | No | Several rows keyed by column name (JSON, or @path / @-; choose exactly one body flag). |
 
 </CommandTable>
 
-## List rows
+API request and response schemas: [createTableRows](/api-reference/tables/createTableRows).
+
+### Update row
 
 ```bash
-sim tables rows list <tableId> [options]
+sim tables rows update <tableId> <rowId> [options]
 ```
 
 **Arguments**
@@ -366,6 +410,7 @@ sim tables rows list <tableId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
+| `rowId` | Yes | Unique table row identifier. |
 
 </CommandTable>
 
@@ -375,17 +420,16 @@ sim tables rows list <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--include-run-state` | No | Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it only when asked. Caps `limit` at 200. |
-| `--no-include-run-state` | No | Send --include-run-state as false. |
+| `--data <json\|@file>` | Yes | Partial row-data patch keyed by column name. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Query rows with a filter and sort
+API request and response schemas: [updateTableRow](/api-reference/tables/updateTableRow).
+
+### Apply a distinct patch to each listed row
 
 ```bash
-sim tables rows query <tableId> [options]
+sim tables rows update-each <tableId> [options]
 ```
 
 **Arguments**
@@ -404,19 +448,18 @@ sim tables rows query <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--filter <json\|@file>` | No | Condition: &#123;"field":"status","op":"eq","value":"active"&#125;. Groups: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125; or &#123;"any":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; group entries may also be nested groups. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
-| `--sort <json\|@file>` | No | Ordered sort keys: [&#123;"field":"createdAt","direction":"desc"&#125;] (direction: asc or desc) (JSON, or @path / @- to read a file or stdin). |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--include-run-state` | No | Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it only when asked. Incompatible with `limit: 0`, and caps `limit` at 200. |
-| `--no-include-run-state` | No | Send --include-run-state as false. |
+| `--updates <json\|@file>` | Yes | One merge patch per row. Each row identifier may appear at most once. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Count rows matching a filter
+API request and response schemas: [bulkUpdateTableRows](/api-reference/tables/bulkUpdateTableRows).
+
+### Update every row matching a filter
+
+This updates every matching row and cannot be undone.
 
 ```bash
-sim tables rows count <tableId> [options]
+sim tables rows batch-update <tableId> [options]
 ```
 
 **Arguments**
@@ -435,11 +478,16 @@ sim tables rows count <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--filter <json\|@file>` | No | Condition: &#123;"field":"status","op":"eq","value":"active"&#125;. Groups: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125; or &#123;"any":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; group entries may also be nested groups. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
+| `--filter <json\|@file>` | Yes | Predicate: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; groups use all/any. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
+| `--data <json\|@file>` | Yes | Row-data patch applied to every matching row. (JSON, or @path / @- to read a file or stdin). |
+| `--limit <value>` | No | Maximum matching rows to update. (caps a --filter match only; omit it to act on every match, and note 0 is not accepted). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Run one row’s enrichment group
+API request and response schemas: [updateRowsByFilter](/api-reference/tables/updateTableRows).
+
+### Run one row’s enrichment group
 
 ```bash
 sim tables rows enrich <tableId> <rowId> <groupId>
@@ -457,10 +505,14 @@ sim tables rows enrich <tableId> <rowId> <groupId>
 
 </CommandTable>
 
-## Search cells for a value and return their coordinates
+API request and response schemas: [runRowEnrichment](/api-reference/tables/runRowEnrichment).
+
+### Delete row
+
+This deletes the row.
 
 ```bash
-sim tables rows search <tableId> [options]
+sim tables rows delete <tableId> <rowId> [options]
 ```
 
 **Arguments**
@@ -470,6 +522,7 @@ sim tables rows search <tableId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
+| `rowId` | Yes | Unique table row identifier. |
 
 </CommandTable>
 
@@ -479,16 +532,18 @@ sim tables rows search <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--query <value>` | Yes | Value to search for. |
-| `--filter <json\|@file>` | No | Predicate: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; groups use all/any. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
-| `--sort <json\|@file>` | No | Ordered sort keys: [&#123;"field":"createdAt","direction":"desc"&#125;] (direction: asc or desc) (JSON, or @path / @- to read a file or stdin). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Update every row matching a filter
+API request and response schemas: [deleteTableRow](/api-reference/tables/deleteTableRow).
+
+### Delete rows matching a filter, or an explicit list of ids
+
+This deletes every matching row and cannot be undone.
 
 ```bash
-sim tables rows batch-update <tableId> [options]
+sim tables rows batch-delete <tableId> [options]
 ```
 
 **Arguments**
@@ -507,17 +562,19 @@ sim tables rows batch-update <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--filter <json\|@file>` | Yes | Predicate: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; groups use all/any. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
-| `--data <json\|@file>` | Yes | Row-data patch applied to every matching row. (JSON, or @path / @- to read a file or stdin). |
-| `--limit <value>` | No | Maximum matching rows to update. (caps a --filter match only; omit it to act on every match, and note 0 is not accepted). |
+| `--filter <json\|@file>` | No | Predicate: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; groups use all/any. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
+| `--limit <value>` | No | Maximum matching rows to delete. (caps a --filter match only; omit it to act on every match, and note 0 is not accepted). |
+| `--row <value...>` | No | Explicit row identifiers to delete. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Update row
+API request and response schemas: [deleteTableRows](/api-reference/tables/deleteTableRows).
+
+### Insert a row, or replace the one matching a unique column
 
 ```bash
-sim tables rows update <tableId> <rowId> [options]
+sim tables upsert <tableId> [options]
 ```
 
 **Arguments**
@@ -527,7 +584,6 @@ sim tables rows update <tableId> <rowId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
-| `rowId` | Yes | Unique table row identifier. |
 
 </CommandTable>
 
@@ -537,14 +593,19 @@ sim tables rows update <tableId> <rowId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--data <json\|@file>` | Yes | Partial row-data patch keyed by column name. (JSON, or @path / @- to read a file or stdin). |
+| `--data <json\|@file>` | Yes | Complete set of row cells keyed by column name. On the update branch this REPLACES the matched row: any column not present here is cleared, unlike a single-row update, which merges. (JSON, or @path / @- to read a file or stdin). |
+| `--on <value>` | No | Unique column to resolve the conflict against. |
 
 </CommandTable>
 
-## Cancel a running dispatch
+API request and response schemas: [upsertTableRow](/api-reference/tables/upsertTableRow).
+
+## Columns
+
+### Add column
 
 ```bash
-sim tables dispatches cancel <tableId> <dispatchId> [options]
+sim tables columns create <tableId> [options]
 ```
 
 **Arguments**
@@ -554,7 +615,6 @@ sim tables dispatches cancel <tableId> <dispatchId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
-| `dispatchId` | Yes | Unique table run-dispatch identifier. |
 
 </CommandTable>
 
@@ -564,14 +624,16 @@ sim tables dispatches cancel <tableId> <dispatchId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--column <json\|@file>` | Yes | Column definition to add. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Start a column or enrichment run
+API request and response schemas: [addTableColumn](/api-reference/tables/addTableColumn).
+
+### Update column
 
 ```bash
-sim tables dispatches create <tableId> [options]
+sim tables columns update <tableId> [options]
 ```
 
 **Arguments**
@@ -590,19 +652,19 @@ sim tables dispatches create <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--group-ids <value...>` | Yes | Workflow or enrichment groups to run. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--run-mode <value>` | No | Whether to run all or only incomplete cells. Accepted values: `all`, `incomplete`. |
-| `--row-ids <value...>` | No | Explicit row subset to run. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--filter <json\|@file>` | No | Predicate: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; groups use all/any. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
-| `--exclude-row-ids <value...>` | No | Rows excluded from a select-all run scope. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--max-rows <n>` | No | Stop after this many eligible rows have run (1-1,000,000). Omit for an unbounded run. |
+| `--column-name <value>` | Yes | Current name of the column to update. |
+| `--updates <json\|@file>` | Yes | Mutable column fields. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Get run dispatch
+API request and response schemas: [updateTableColumn](/api-reference/tables/updateTableColumn).
+
+### Delete column
+
+This deletes the column and its values in every row.
 
 ```bash
-sim tables dispatches get <tableId> <dispatchId>
+sim tables columns delete <tableId> [options]
 ```
 
 **Arguments**
@@ -612,14 +674,28 @@ sim tables dispatches get <tableId> <dispatchId>
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
-| `dispatchId` | Yes | Unique table run-dispatch identifier. |
 
 </CommandTable>
 
-## List run dispatches
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--column-name <value>` | Yes | Name of the column to delete. |
+| `-y, --yes` | Yes | Confirm this operation. |
+
+</CommandTable>
+
+API request and response schemas: [deleteTableColumn](/api-reference/tables/deleteTableColumn).
+
+## Saved views
+
+### List views
 
 ```bash
-sim tables dispatches list <tableId>
+sim tables views list <tableId>
 ```
 
 **Arguments**
@@ -632,10 +708,12 @@ sim tables dispatches list <tableId>
 
 </CommandTable>
 
-## Stop a running export
+API request and response schemas: [listTableViews](/api-reference/tables/listTableViews).
+
+### Get view
 
 ```bash
-sim tables exports cancel <tableId> <exportId>
+sim tables views get <tableId> <viewId>
 ```
 
 **Arguments**
@@ -645,14 +723,16 @@ sim tables exports cancel <tableId> <exportId>
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
-| `exportId` | Yes | Unique table-export identifier. |
+| `viewId` | Yes | Unique saved-view identifier. |
 
 </CommandTable>
 
-## Create table export
+API request and response schemas: [getTableView](/api-reference/tables/getTableView).
+
+### Create view
 
 ```bash
-sim tables exports create <tableId> [options]
+sim tables views create <tableId> [options]
 ```
 
 **Arguments**
@@ -671,14 +751,17 @@ sim tables exports create <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--format <value>` | No | Export file format. Accepted values: `csv`, `json`. |
+| `--name <value>` | Yes | Saved-view display name. |
+| `--config <json\|@file>` | Yes | Saved filter, sort, and column-layout configuration. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Get table export
+API request and response schemas: [createTableView](/api-reference/tables/createTableView).
+
+### Update view
 
 ```bash
-sim tables exports get <tableId> <exportId>
+sim tables views update <tableId> <viewId> [options]
 ```
 
 **Arguments**
@@ -688,31 +771,32 @@ sim tables exports get <tableId> <exportId>
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
-| `exportId` | Yes | Unique table-export identifier. |
+| `viewId` | Yes | Unique saved-view identifier. |
 
 </CommandTable>
 
-## Get the download URL for a finished export
-
-```bash
-sim tables exports download <tableId> <exportId>
-```
-
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `tableId` | Yes | Unique table identifier. |
-| `exportId` | Yes | Unique table-export identifier. |
+| `--name <value>` | No | Replacement saved-view display name. |
+| `--config <json\|@file>` | No | Complete replacement saved-view configuration. (JSON, or @path / @- to read a file or stdin). |
+| `--config-patch <json\|@file>` | No | Saved-view configuration fields to shallow-merge. (JSON, or @path / @- to read a file or stdin). |
+| `--default` | No | Whether to promote this view to the table default. |
+| `--no-default` | No | Send --default as false. |
 
 </CommandTable>
 
-## Stop a running import
+API request and response schemas: [updateTableView](/api-reference/tables/updateTableView).
+
+### Delete view
+
+This deletes the saved view and its filters.
 
 ```bash
-sim tables imports cancel <importId> [options]
+sim tables views delete <tableId> <viewId> [options]
 ```
 
 **Arguments**
@@ -721,7 +805,8 @@ sim tables imports cancel <importId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `importId` | Yes | Unique table-import identifier. |
+| `tableId` | Yes | Unique table identifier. |
+| `viewId` | Yes | Unique saved-view identifier. |
 
 </CommandTable>
 
@@ -735,10 +820,14 @@ sim tables imports cancel <importId> [options]
 
 </CommandTable>
 
-## Get table import
+API request and response schemas: [deleteTableView](/api-reference/tables/deleteTableView).
+
+## Producer groups and runs
+
+### List workflow groups
 
 ```bash
-sim tables imports get <importId>
+sim tables groups list <tableId>
 ```
 
 **Arguments**
@@ -747,14 +836,16 @@ sim tables imports get <importId>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `importId` | Yes | Unique table-import identifier. |
+| `tableId` | Yes | Unique table identifier. |
 
 </CommandTable>
 
-## Stop every running column job
+API request and response schemas: [listWorkflowGroups](/api-reference/tables/listTableWorkflowGroups).
+
+### Add workflow group
 
 ```bash
-sim tables cancel-runs <tableId> [options]
+sim tables groups create <tableId> [options]
 ```
 
 **Arguments**
@@ -773,53 +864,60 @@ sim tables cancel-runs <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--scope <value>` | Yes | Whether to cancel across the table or one row. Accepted values: `all`, `row`. |
-| `--row-id <value>` | No | Row whose runs should be canceled for row scope. |
-| `--filter <json\|@file>` | No | Predicate: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; groups use all/any. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
-| `--exclude-row-ids <value...>` | No | Rows excluded from an all-scope cancellation. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--group <json\|@file>` | Yes | Workflow or enrichment producer definition. (JSON, or @path / @- to read a file or stdin). |
+| `--output-columns <json\|@file>` | No | Columns to create for producer outputs. An entry naming a column the table already has attaches that column to the group instead of creating it (its `type` must match), and an output whose column already exists may omit its entry entirely — so `[]` attaches existing columns only. Defaults to []. (JSON, or @path / @- to read a file or stdin). |
+| `--auto-run` | No | Whether to schedule existing rows after group creation. Defaults to false. |
+| `--no-auto-run` | No | Send --auto-run as false. |
 
 </CommandTable>
 
-## Create table
+API request and response schemas: [addWorkflowGroup](/api-reference/tables/addTableWorkflowGroup).
+
+### Update workflow group
 
 ```bash
-sim tables create [options]
+sim tables groups update <tableId> [options]
 ```
 
-**Options**
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | Yes | Identifier: letters, numbers, and underscores; cannot start with a number. |
-| `--description <value>` | No | Optional table description. |
-| `--schema <json\|@file>` | Yes | Table schema: &#123;"columns":[&#123;"name":"email","type":"string"&#125;]&#125; (JSON, or @path / @- to read a file or stdin). |
-| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
+| `tableId` | Yes | Unique table identifier. |
 
 </CommandTable>
 
-## Create a table folder at a path
-
-```bash
-sim tables folders create <path>
-```
-
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `--group-id <value>` | Yes | Workflow group to update. |
+| `--workflow-id <value>` | No | Replacement backing workflow identifier. |
+| `--name <value>` | No | Replacement workflow-group display name. |
+| `--dependencies <json\|@file>` | No | Replacement input dependencies. (JSON, or @path / @- to read a file or stdin). |
+| `--outputs <json\|@file>` | No | Replacement producer outputs. (JSON, or @path / @- to read a file or stdin). |
+| `--new-output-columns <json\|@file>` | No | Columns to add for new outputs. (JSON, or @path / @- to read a file or stdin). |
+| `--mapping-updates <json\|@file>` | No | Existing output-column mapping changes. (JSON, or @path / @- to read a file or stdin). |
+| `--input-mappings <json\|@file>` | No | Replacement workflow input mappings. (JSON, or @path / @- to read a file or stdin). |
+| `--deployment-mode <value>` | No | Replacement workflow execution mode. Accepted values: `live`, `deployed`. |
+| `--type <value>` | No | Workflow-group producer type. Must match the group's stored type — a group's producer cannot be changed after creation. Accepted values: `manual`, `enrichment`. |
+| `--auto-run` | No | Replacement automatic-run setting. |
+| `--no-auto-run` | No | Send --auto-run as false. |
 
 </CommandTable>
 
-## Delete folder
+API request and response schemas: [updateWorkflowGroup](/api-reference/tables/updateTableWorkflowGroup).
+
+### Delete workflow group
+
+This deletes the group AND its output columns with all of their row data; the workflow it pointed at is untouched.
 
 ```bash
-sim tables folders delete <path> [options]
+sim tables groups delete <tableId> [options]
 ```
 
 **Arguments**
@@ -828,7 +926,7 @@ sim tables folders delete <path> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `tableId` | Yes | Unique table identifier. |
 
 </CommandTable>
 
@@ -838,55 +936,55 @@ sim tables folders delete <path> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--recursive` | No | Delete the folder and its descendants. |
+| `--group-id <value>` | Yes | Workflow group to delete. |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## List table folders
+API request and response schemas: [deleteWorkflowGroup](/api-reference/tables/deleteTableWorkflowGroup).
+
+### Get row group run
 
 ```bash
-sim tables folders list [options]
+sim tables enrichment get <tableId> <rowId> <groupId>
 ```
 
-Also available as `sim tables folders ls`.
-
-**Options**
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--parent <value>` | No | Direct parent folder path. |
-| `--search <value>` | No | Case-insensitive substring match against the folder name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `tableId` | Yes | Unique table identifier. |
+| `rowId` | Yes | Unique table row identifier. |
+| `groupId` | Yes | Workflow or enrichment group to run. |
 
 </CommandTable>
 
-## Rename or move a table folder
+API request and response schemas: [getRowEnrichment](/api-reference/tables/getRowEnrichment).
+
+### List run dispatches
 
 ```bash
-sim tables folders move <path> <destination>
+sim tables dispatches list <tableId>
 ```
 
-Also available as `sim tables folders mv`.
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
-| `destination` | Yes | Folder path as shown in the app; the leading / is optional |
+| `tableId` | Yes | Unique table identifier. |
 
 </CommandTable>
 
-## Restore an archived table folder
+API request and response schemas: [listTableDispatches](/api-reference/tables/listTableDispatches).
+
+### Get run dispatch
 
 ```bash
-sim tables folders restore <path>
+sim tables dispatches get <tableId> <dispatchId>
 ```
 
 **Arguments**
@@ -895,14 +993,17 @@ sim tables folders restore <path>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `tableId` | Yes | Unique table identifier. |
+| `dispatchId` | Yes | Unique table run-dispatch identifier. |
 
 </CommandTable>
 
-## Create view
+API request and response schemas: [getTableDispatch](/api-reference/tables/getTableDispatch).
+
+### Start a column or enrichment run
 
 ```bash
-sim tables views create <tableId> [options]
+sim tables dispatches create <tableId> [options]
 ```
 
 **Arguments**
@@ -921,15 +1022,23 @@ sim tables views create <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | Yes | Saved-view display name. |
-| `--config <json\|@file>` | Yes | Saved filter, sort, and column-layout configuration. (JSON, or @path / @- to read a file or stdin). |
+| `--group-ids <value...>` | Yes | Workflow or enrichment groups to run. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--run-mode <value>` | No | Whether to run all or only incomplete cells. Defaults to "all". Accepted values: `all`, `incomplete`. |
+| `--row-ids <value...>` | No | Explicit row subset to run. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--filter <json\|@file>` | No | Predicate: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; groups use all/any. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
+| `--exclude-row-ids <value...>` | No | Rows excluded from a select-all run scope. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--max-rows <n>` | No | Stop after this many eligible rows have run (1-1,000,000). Omit for an unbounded run. |
 
 </CommandTable>
 
-## Delete view
+API request and response schemas: [createTableDispatch](/api-reference/tables/createTableDispatch).
+
+### Cancel a running dispatch
+
+This stops the dispatch. Cells already handed to the queue keep running — use `tables cancel-runs` to stop those.
 
 ```bash
-sim tables views delete <tableId> <viewId> [options]
+sim tables dispatches cancel <tableId> <dispatchId> [options]
 ```
 
 **Arguments**
@@ -939,7 +1048,7 @@ sim tables views delete <tableId> <viewId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
-| `viewId` | Yes | Unique saved-view identifier. |
+| `dispatchId` | Yes | Unique table run-dispatch identifier. |
 
 </CommandTable>
 
@@ -953,10 +1062,14 @@ sim tables views delete <tableId> <viewId> [options]
 
 </CommandTable>
 
-## Get view
+API request and response schemas: [cancelTableDispatch](/api-reference/tables/cancelTableDispatch).
+
+### Stop every running column job
+
+This cancels running column jobs — the whole table with --scope all, one row with --scope row.
 
 ```bash
-sim tables views get <tableId> <viewId>
+sim tables cancel-runs <tableId> [options]
 ```
 
 **Arguments**
@@ -966,30 +1079,37 @@ sim tables views get <tableId> <viewId>
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
-| `viewId` | Yes | Unique saved-view identifier. |
 
 </CommandTable>
 
-## List views
-
-```bash
-sim tables views list <tableId>
-```
-
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `tableId` | Yes | Unique table identifier. |
+| `--scope <value>` | Yes | Whether to cancel across the table or one row. Accepted values: `all`, `row`. |
+| `--row-id <value>` | No | Row whose runs should be canceled for row scope. |
+| `--filter <json\|@file>` | No | Predicate: &#123;"all":[&#123;"field":"status","op":"eq","value":"active"&#125;]&#125;; groups use all/any. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, ncontains, startsWith, endsWith, like, ilike, nlike, nilike, isEmpty, isNotEmpty, isNull, isNotNull (JSON, or @path / @- to read a file or stdin). |
+| `--exclude-row-ids <value...>` | No | Rows excluded from an all-scope cancellation. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Update view
+API request and response schemas: [cancelTableRuns](/api-reference/tables/cancelTableRuns).
+
+## Imports
+
+### Import a CSV, into a new table by default
+
+Choose exactly one source: a local CSV path or `--file-id`. For a new table imported with `--file-id`, supply `--name`. With `--table-id`, omit the new-table `--name` and `--folder` flags; `--mode`, `--mapping`, and `--create-columns` apply only to an existing table.
+
+**Replace mode deletes all existing rows before loading the CSV and cannot be undone.** It requires `--yes`; cancellation leaves only the rows already imported.
+
+The command watches the import by default. `--no-wait` returns a queued receipt. A completed import can still report `rowsRejected`, `cellsRejected`, and `rejectedSamples`; inspect them before accepting the result.
 
 ```bash
-sim tables views update <tableId> <viewId> [options]
+sim tables import [path] [options]
 ```
 
 **Arguments**
@@ -998,8 +1118,7 @@ sim tables views update <tableId> <viewId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `tableId` | Yes | Unique table identifier. |
-| `viewId` | Yes | Unique saved-view identifier. |
+| `path` | No | Local CSV file to import; choose exactly one source: this path or --file-id |
 
 </CommandTable>
 
@@ -1009,18 +1128,25 @@ sim tables views update <tableId> <viewId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | Replacement saved-view display name. |
-| `--config <json\|@file>` | No | Complete replacement saved-view configuration. (JSON, or @path / @- to read a file or stdin). |
-| `--config-patch <json\|@file>` | No | Saved-view configuration fields to shallow-merge. (JSON, or @path / @- to read a file or stdin). |
-| `--default` | No | Whether to promote this view to the table default. |
-| `--no-default` | No | Send --default as false. |
+| `--name <name>` | Conditional | Name for a new table: letters, numbers, and underscores. A local CSV defaults to its sanitized filename; required with --file-id unless --table-id names an existing table. |
+| `--table-id <id>` | No | Import into this existing table instead of creating one. |
+| `--mode <append\|replace>` | No | How to write into --table-id (default: append). Accepted values: `append`, `replace`. |
+| `--folder <path>` | No | Folder path for the new table, as shown in the app. |
+| `--file-id <id>` | No | Import a file already in the workspace instead of a local path. |
+| `--mapping <json\|@file>` | No | Column mapping (--table-id only). |
+| `--create-columns <json\|@file>` | No | Columns to create (--table-id only). |
+| `--timezone <iana>` | No | Timezone for date parsing, e.g. America/New_York. |
+| `-y, --yes` | Conditional | Confirm this destructive operation (required with --mode replace). |
+| `--no-wait` | No | Return once the import is queued instead of watching it. |
 
 </CommandTable>
 
-## Delete table
+API request and response schemas: [createTableImport](/api-reference/tables/createTableImport), [createTableImportPartUrls](/api-reference/tables/createTableImportPartUrls), [completeTableImport](/api-reference/tables/completeTableImportUpload), [cancelTableImport](/api-reference/tables/cancelTableImport), [getTableImport](/api-reference/tables/getTableImport).
+
+### Get table import
 
 ```bash
-sim tables delete <tableId> [options]
+sim tables imports get <importId>
 ```
 
 **Arguments**
@@ -1029,7 +1155,27 @@ sim tables delete <tableId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `tableId` | Yes | Unique table identifier. |
+| `importId` | Yes | Unique table-import identifier. |
+
+</CommandTable>
+
+API request and response schemas: [getTableImport](/api-reference/tables/getTableImport).
+
+### Stop a running import
+
+This stops the import between row batches, so whatever it already wrote stays and nothing resumes it. A replace import empties the table before its first batch, so cancelling one leaves only part of the new file; an append adds its rows again if you import the file a second time.
+
+```bash
+sim tables imports cancel <importId> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `importId` | Yes | Unique table-import identifier. |
 
 </CommandTable>
 
@@ -1043,10 +1189,14 @@ sim tables delete <tableId> [options]
 
 </CommandTable>
 
-## Get row group run
+API request and response schemas: [cancelTableImport](/api-reference/tables/cancelTableImport).
+
+## Exports
+
+### Create table export
 
 ```bash
-sim tables enrichment get <tableId> <rowId> <groupId>
+sim tables exports create <tableId> [options]
 ```
 
 **Arguments**
@@ -1056,70 +1206,63 @@ sim tables enrichment get <tableId> <rowId> <groupId>
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
-| `rowId` | Yes | Unique table row identifier. |
-| `groupId` | Yes | Workflow or enrichment group to run. |
 
 </CommandTable>
 
-## Get table
-
-```bash
-sim tables get <tableId>
-```
-
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `tableId` | Yes | Unique table identifier. |
+| `--format <value>` | No | Export file format. Defaults to "csv". Accepted values: `csv`, `json`. |
 
 </CommandTable>
 
-## List tables
+API request and response schemas: [createTableExport](/api-reference/tables/createTableExport).
+
+### Get table export
 
 ```bash
-sim tables list [options]
+sim tables exports get <tableId> <exportId>
 ```
 
-**Options**
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live tables, `archived` for tables a delete archived and a table restore can bring back. `folderPath` resolves against active folders only, so pairing it with `scope=archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
-| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
-| `--search <value>` | No | Case-insensitive substring match against the resource name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `tableId` | Yes | Unique table identifier. |
+| `exportId` | Yes | Unique table-export identifier. |
 
 </CommandTable>
 
-## Move tables and folders
+API request and response schemas: [getTableExport](/api-reference/tables/getTableExport).
+
+### Get the download URL for a finished export
 
 ```bash
-sim tables move [options]
+sim tables exports download <tableId> <exportId>
 ```
 
-**Options**
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--table-ids <json\|@file>` | No | Tables to move, by identifier. (JSON, or @path / @- to read a file or stdin). |
-| `--folder <value...>` | No | Table folders to move, by path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--to <value>` | No | Destination folder path; omit for root. |
+| `tableId` | Yes | Unique table identifier. |
+| `exportId` | Yes | Unique table-export identifier. |
 
 </CommandTable>
 
-## Restore an archived table
+API request and response schemas: [tableExportDownload](/api-reference/tables/downloadTableExport).
+
+### Stop a running export
 
 ```bash
-sim tables restore <tableId>
+sim tables exports cancel <tableId> <exportId>
 ```
 
 **Arguments**
@@ -1129,13 +1272,18 @@ sim tables restore <tableId>
 | Argument | Required | Description |
 | --- | --- | --- |
 | `tableId` | Yes | Unique table identifier. |
+| `exportId` | Yes | Unique table-export identifier. |
 
 </CommandTable>
 
-## Update table
+API request and response schemas: [cancelTableExport](/api-reference/tables/cancelTableExport).
+
+## Folders
+
+### List table resources and child folders together
 
 ```bash
-sim tables update <tableId> [options]
+sim tables ls [path] [options]
 ```
 
 **Arguments**
@@ -1144,7 +1292,7 @@ sim tables update <tableId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `tableId` | Yes | Unique table identifier. |
+| `path` | No | Folder path to list; defaults to the root folder |
 
 </CommandTable>
 
@@ -1154,33 +1302,40 @@ sim tables update <tableId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | Identifier: letters, numbers, and underscores; cannot start with a number. |
-| `--description <value>` | No | Replacement table description, or null to clear it. (--description null sends the word, not JSON null). |
-| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
+| `--search <text>` | No | Filter folders and resources by name. |
+| `--limit <n>` | No | Maximum combined items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Move a table to a folder
+API request and response schemas: [listTables](/api-reference/tables/listTables), [listTableFolders](/api-reference/tables/listTablesFolders).
+
+### List table folders
 
 ```bash
-sim tables mv <tableId> <folder>
+sim tables folders list [options]
 ```
 
-**Arguments**
+Also available as `sim tables folders ls`.
+
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `tableId` | Yes | Unique table identifier. |
-| `folder` | Yes | Folder path as shown in the app; the leading / is optional |
+| `--parent <value>` | No | Direct parent folder path. |
+| `--search <value>` | No | Case-insensitive substring match against the folder name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
-## Insert a row, or update the one that conflicts on a unique column
+API request and response schemas: [listTableFolders](/api-reference/tables/listTablesFolders).
+
+### Create a table folder at a path
 
 ```bash
-sim tables upsert <tableId> [options]
+sim tables folders create <path>
 ```
 
 **Arguments**
@@ -1189,25 +1344,18 @@ sim tables upsert <tableId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `tableId` | Yes | Unique table identifier. |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-**Options**
-
-<CommandTable>
-
-| Option | Required | Description |
-| --- | --- | --- |
-| `--data <json\|@file>` | Yes | Complete set of row cells keyed by column name. On the update branch this REPLACES the matched row: any column not present here is cleared, unlike a single-row update, which merges. (JSON, or @path / @- to read a file or stdin). |
-| `--on <value>` | No | Unique column to resolve the conflict against. |
+API request and response schemas: [createTableFolder](/api-reference/tables/createTablesFolder).
 
-</CommandTable>
+### Delete folder
 
-## Import a CSV, into a new table by default
+This archives the table folder and, when recursive, everything inside it.
 
 ```bash
-sim tables import [path] [options]
+sim tables folders delete <path> [options]
 ```
 
 **Arguments**
@@ -1216,7 +1364,7 @@ sim tables import [path] [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | No | Local CSV file to import; omit when using --file-id |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
@@ -1226,23 +1374,17 @@ sim tables import [path] [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <name>` | No | Identifier for the new table: letters, numbers, and underscores; defaults to the sanitized file name. |
-| `--table-id <id>` | No | Import into this existing table instead of creating one. |
-| `--mode <append\|replace>` | No | How to write into --table-id (default: append). Accepted values: `append`, `replace`. |
-| `--folder <path>` | No | Folder path for the new table, as shown in the app. |
-| `--file-id <id>` | No | Import a file already in the workspace instead of a local path. |
-| `--mapping <json\|@file>` | No | Column mapping (--table-id only). |
-| `--create-columns <json\|@file>` | No | Columns to create (--table-id only). |
-| `--timezone <iana>` | No | Timezone for date parsing, e.g. America/New_York. |
-| `-y, --yes` | No | Confirm this destructive operation (required with --mode replace). |
-| `--no-wait` | No | Return once the import is queued instead of watching it. |
+| `--recursive` | No | Archive the folder and its descendants. Defaults to "false". |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## List table resources and child folders together
+API request and response schemas: [deleteTableFolder](/api-reference/tables/deleteTablesFolder).
+
+### Restore an archived table folder
 
 ```bash
-sim tables ls [path] [options]
+sim tables folders restore <path>
 ```
 
 **Arguments**
@@ -1251,22 +1393,34 @@ sim tables ls [path] [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | No | Folder path to list; defaults to the root folder |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-**Options**
+API request and response schemas: [restoreTableFolder](/api-reference/tables/restoreTablesFolder).
+
+### Rename or move a table folder
+
+```bash
+sim tables folders move <path> <destination>
+```
+
+Also available as `sim tables folders mv`.
+
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--search <text>` | No | Filter folders and resources by name. |
-| `--limit <n>` | No | Maximum combined items to return (0 for everything). Defaults to `0`. |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `destination` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-## Create a table directory at a path
+API request and response schemas: [relocateTableFolder](/api-reference/tables/relocateTablesFolder).
+
+### Create a table directory at a path
 
 ```bash
 sim tables mkdir <path>
@@ -1281,3 +1435,10 @@ sim tables mkdir <path>
 | `path` | Yes | Folder path to create; the leading / is optional |
 
 </CommandTable>
+
+API request and response schemas: [createTableFolder](/api-reference/tables/createTablesFolder).
+
+## Related docs
+
+- [Tables](/tables)
+- [Workflow columns](/tables/workflow-columns)
diff --git a/apps/docs/content/docs/cli/telemetry.mdx b/apps/docs/content/docs/cli/telemetry.mdx
index 9bea4c847d4..8853ac89b6f 100644
--- a/apps/docs/content/docs/cli/telemetry.mdx
+++ b/apps/docs/content/docs/cli/telemetry.mdx
@@ -1,26 +1,33 @@
 ---
 title: Telemetry
-description: Control anonymous usage reporting — every subcommand, argument, and flag
+description: Inspect and change this machine’s anonymous usage-reporting preference.
 ---
 
-import { CommandTable } from '@/components/ui/command-table'
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+Inspect and change this machine’s anonymous usage-reporting preference.
 
-## Show whether usage reporting is on, and why not if it is off
+These commands accept the [global options](/cli/commands#global-options).
+
+## Show usage-reporting status [#show-whether-usage-reporting-is-on-and-why-not-if-it-is-off]
 
 ```bash
 sim telemetry status
 ```
 
-## Turn usage reporting on for this machine
+Telemetry commands always print text. DO_NOT_TRACK and SIM_TELEMETRY_DISABLED override the saved preference; a build without a reporting destination remains off. See the usage-data guide for the data collected.
+
+## Turn usage reporting off for this machine
 
 ```bash
-sim telemetry enable
+sim telemetry disable
 ```
 
-## Turn usage reporting off for this machine
+## Enable the usage-reporting preference for this machine [#turn-usage-reporting-on-for-this-machine]
 
 ```bash
-sim telemetry disable
+sim telemetry enable
 ```
+
+## Related docs
+
+- [Usage data](/cli/usage-data)
diff --git a/apps/docs/content/docs/cli/tools.mdx b/apps/docs/content/docs/cli/tools.mdx
index 93f264a8186..ed3972a2d47 100644
--- a/apps/docs/content/docs/cli/tools.mdx
+++ b/apps/docs/content/docs/cli/tools.mdx
@@ -1,29 +1,21 @@
 ---
 title: Tools
-description: Manage tools — every subcommand, argument, and flag
+description: Find built-in tools, inspect their parameters, and run them.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+Find built-in tools, inspect their parameters, and run them.
 
-## Run one built-in tool and print what it produced
-
-```bash
-sim tools execute <toolId> [options]
-```
-
-Run one built-in tool and print what it produced (OAuth login or personal API key required)
+Inspect a tool with `sim tools get <toolId>` before passing its parameters to `sim tools execute`.
 
-**Arguments**
-
-<CommandTable>
+These commands accept the [global options](/cli/commands#global-options).
 
-| Argument | Required | Description |
-| --- | --- | --- |
-| `toolId` | Yes | Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id. |
+## List tools
 
-</CommandTable>
+```bash
+sim tools list [options]
+```
 
 **Options**
 
@@ -31,12 +23,17 @@ Run one built-in tool and print what it produced (OAuth login or personal API ke
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--input <json\|@file>` | No | Tool arguments as JSON, keyed by the parameter ids `sim tools get &lt;toolId&gt;` lists (JSON, or @path / @- to read a file or stdin). |
-| `--credential-id <value>` | No | Credential to authenticate with, required for OAuth tools. |
-| `--timeout <value>` | No | Seconds to wait before abandoning the call. |
+| `--search <value>` | No | Case-insensitive substring match against the tool id, name, and description. |
+| `--hosted-api-key <value>` | No | Restrict to tools by how their API key is supplied. Accepted values: `always`, `conditional`, `none`. |
+| `--oauth-provider <value>` | No | Restrict to tools that authenticate against this OAuth service. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "id". Accepted values: `id`, `name`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
+API request and response schemas: [listTools](/api-reference/catalog/listTools).
+
 ## Get tool
 
 ```bash
@@ -49,27 +46,40 @@ sim tools get <toolId>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `toolId` | Yes | Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id. |
+| `toolId` | Yes | Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID. |
 
 </CommandTable>
 
-## List tools
+API request and response schemas: [getTool](/api-reference/catalog/getTool).
+
+## Run one built-in tool and print what it produced
+
+OAuth login or personal API key required.
 
 ```bash
-sim tools list [options]
+sim tools execute <toolId> [options]
 ```
 
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `toolId` | Yes | Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID. |
+
+</CommandTable>
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--search <value>` | No | Case-insensitive substring match against the tool id, name, and description. |
-| `--hosted-api-key <value>` | No | Restrict to tools by how their API key is supplied. Accepted values: `always`, `conditional`, `none`. |
-| `--oauth-provider <value>` | No | Restrict to tools that authenticate against this OAuth service. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `id`, `name`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--input <json\|@file>` | No | Tool arguments as JSON, keyed by the parameter ids `sim tools get <toolId>` lists. Defaults to &#123;&#125;. (JSON, or @path / @- to read a file or stdin). |
+| `--credential-id <value>` | No | Credential to authenticate with, required for OAuth tools. |
+| `--timeout <value>` | No | Seconds to wait before abandoning the call. |
 
 </CommandTable>
+
+API request and response schemas: [executeTool](/api-reference/catalog/executeTool).
diff --git a/apps/docs/content/docs/cli/troubleshooting.mdx b/apps/docs/content/docs/cli/troubleshooting.mdx
index 4ad1a9b2f22..81a766a60ab 100644
--- a/apps/docs/content/docs/cli/troubleshooting.mdx
+++ b/apps/docs/content/docs/cli/troubleshooting.mdx
@@ -1,147 +1,160 @@
 ---
 title: Troubleshooting
-description: The failures whose cause is not obvious from the error message
+description: Diagnose profile, connection, input, output, and update failures.
 ---
 
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+Start by checking the version and resolved settings:
 
-Most command errors print to stderr and exit `1`. `sim whoami` and
-`sim workflows runs wait` use additional codes to distinguish outcomes; see
-[Exit codes](/cli/scripting#exit-codes). The cases below explain failures whose
-cause may not be obvious from the message.
+```bash
+sim --version
+sim whoami --no-verify
+sim whoami
+```
+
+`--no-verify` stays offline. Normal `whoami` checks authentication and access to the selected workspace. Inspect its `verification` result before changing credentials.
 
-Start with `sim whoami`. It prints the resolved endpoint, workspace, and output
-format, **and where each came from** — which explains most surprises on its own —
-then checks the resolved key against the API. Add `--no-verify` to skip the check
-and stay offline.
+Most command failures exit 1. Verification, run waiting, and workspace-operation waiting have additional outcomes; see [Exit codes](/cli/scripting#exit-codes).
 
 ## A command targets the wrong workspace or deployment
 
-Each setting resolves independently, and a flag beats the environment, which
-beats the profile. A stale `SIM_WORKSPACE` in your shell silently outranks the
-workspace you configured.
+Flags override the environment, which overrides profile defaults. A stale `SIM_WORKSPACE` can outrank the workspace saved in your profile. `whoami` shows each winning value and source:
 
 ```bash
-sim whoami
+sim whoami --no-verify --profile <name>
 ```
 
-API-key pairing sets the default workspace selected on its approval page.
-After OAuth login, set one with `sim configure --set-workspace <id>`.
-The default target does not restrict your credential: use `--workspace` to reach
-another workspace that credential can access.
+After OAuth login, set a default with `sim configure --set-workspace <id>`. Pairing sets the default chosen on its approval page. A default target does not restrict credential scope; `--workspace` can select another accessible workspace.
+
+See [Configuration](/cli/configuration#where-settings-come-from) for the full precedence rules.
 
 ## An error ends in `— run: sim login --profile <name>`
 
-The API rejected the key with a `401`. Either it was revoked, or it belongs to a
-different deployment than the endpoint you are pointed at — a key minted against
-a local stack will not authenticate against production. Check the endpoint before
-re-authenticating:
+A 401 means the API rejected authentication. The credential may be revoked, expired, or issued by another deployment. Check the endpoint before signing in again:
+
+```bash
+sim whoami --no-verify --profile <name>
+```
+
+For a stored OAuth login, logout is required before a new login:
 
 ```bash
-sim whoami --profile <name>
+sim logout --profile <name>
+sim login --profile <name>
 ```
 
+`whoami` exit 1 can also mean a valid credential cannot access the selected workspace, or the workspace does not exist. A 403/404 workspace refusal needs an access or target correction rather than repeated login.
+
+### OAuth refresh or endpoint mismatch
+
+An OAuth login cannot move to another deployment. Restore its original endpoint, or log out before configuring a new one. Workspace profiles share their authentication profile's endpoint.
+
+Sign in separately on each machine. Copied credential files can reuse one single-use refresh family and cause revocation. If a refresh response was lost, the CLI will not retry the consumed token; log out and sign in again. See [Stored logins](/cli/authentication#where-the-login-is-stored).
+
 ## `Could not reach https://www.sim.ai: <reason>`
 
-The request never got a response: DNS, TLS, a proxy, or a self-hosted stack that
-is not running. Confirm the endpoint the CLI actually used with `sim whoami`, and
-that it has the right scheme and port:
+DNS, TLS, a proxy, or an unavailable self-hosted service can prevent a response. Check the resolved endpoint's scheme and port:
 
 ```bash
+sim whoami --no-verify
 sim configure --set-endpoint http://localhost:3000 --profile local
 ```
 
+Loopback development endpoints can use HTTP. Remote browser sign-in requires HTTPS for OAuth and pairing.
+
+### Endpoint redirects
+
+The CLI does not follow API redirects: they can change a write's method/body or forward a credential to another origin. Configure the actual API endpoint shown by the error. The hosted default is `https://www.sim.ai`.
+
+### Proxy settings
+
+Node must opt in before `fetch` uses `HTTP(S)_PROXY`. Set `NODE_USE_ENV_PROXY=1` before launching the CLI, using Node 22.21+ or 24.0+. The equivalent `--use-env-proxy` Node flag requires 22.21+ or 24.5+. Older runtimes need an upgrade. See [Registry and proxy behavior](/cli/configuration#registry-and-proxy-behavior).
+
 ## A JSON flag rejects a value that looks like valid JSON
 
-Your shell consumed the quotes. Wrap the whole value in single quotes, or read it
-from a file:
+A shell may consume unquoted JSON quotes. Quote the whole value or read JSON from a file:
 
 ```bash
 sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --filter '{"all":[{"field":"status","op":"eq","value":"open"}]}'
 sim tables rows query tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --filter @filter.json
 ```
 
+Workflow imports require JSON, even if an export was saved as YAML. File-aware flags interpret `@value` as a path; write `@@value` for a literal leading `@`. See [Scripting](/cli/scripting).
+
 ## A value looks truncated
 
-`table` clips long cells to keep rows on one line. The data is not truncated —
-switch to a machine format to see it in full:
+Table display clips long cells. Select JSON/YAML to inspect the returned values:
 
 ```bash
 sim logs get 9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543 --output json
 ```
 
+Changing format does not remove server-side caps. Check any reported truncation flag/notice, filters, and pagination before assuming the response contains everything.
+
 ## In an interactive terminal, `sim files get` refuses to print to the terminal
 
-Writing arbitrary binary to an interactive terminal can corrupt it, so non-text
-content has to go to a file or a pipe:
+Binary content must go to a file or a pipe:
 
 ```bash
 sim files get wf_8Kd2NpVrY6zTfQa3XwBmS -o ./image.png
 sim files get wf_8Kd2NpVrY6zTfQa3XwBmS | shasum
 ```
 
+An existing output file requires `--force`. With `--output-file`, file content is saved and stdout contains a save receipt. See [File commands](/cli/files).
+
 ## A stored output format is invalid
 
-A higher-priority source still wins, so you can repair the profile without
-editing the file by hand:
+Use an environment override to repair the saved default:
 
 ```bash
-sim --output table configure --set-output json
+SIM_OUTPUT=json sim configure --set-output json
+SIM_OUTPUT=json sim configure --profile <name> --set-output json
 ```
 
+`configure` rejects global `--output`, `--endpoint`, and `--workspace`; persistence uses `--set-*`. If an invalid environment variable caused the error, correct or unset it as well.
+
 ## A command is missing that the documentation describes
 
-The docs track the current release, so a command that exists here and not in
-`sim --help` usually means the installed CLI is older than the feature. Compare
-`sim --version` against the published version and upgrade:
+Compare the installed version and command help. These docs describe the current source; an older installed CLI or self-hosted server can lack an operation:
 
 ```bash
 sim --version
+sim --help
+sim update
 ```
 
-Run `sim update` to update the active global installation. If this older release
-does not yet have the `update` command, upgrade with the package manager you installed it with — using a different
-one installs a second copy instead of replacing the executable on your `PATH`:
-
-<Tabs items={['npm', 'pnpm', 'bun', 'Yarn Classic']}>
-  <Tab value="npm">
-    ```bash
-    npm install -g sim@latest
-    ```
-  </Tab>
-  <Tab value="pnpm">
-    ```bash
-    pnpm add -g sim@latest
-    ```
-  </Tab>
-  <Tab value="bun">
-    ```bash
-    bun add -g sim@latest
-    ```
-  </Tab>
-  <Tab value="Yarn Classic">
-    ```bash
-    yarn global add sim@latest
-    ```
-  </Tab>
-</Tabs>
-
-The CLI also shows an optional update notice through a cached daily check on
-eligible interactive invocations. Your command continues, and you choose when to
-run `sim update`. Checks stay quiet when stderr is redirected, in CI, and under
-`npm exec` or `npx`.
+`sim update` verifies the active global installation and preserves its stable/staging/dev channel. If an older Bun installation has no update command, update the package through Bun:
+
+```bash
+bun add -g sim@latest
+```
+
+Use the corresponding staging/dev tag for an intentional prerelease installation. Installations made with npm, pnpm, or Yarn Classic should be upgraded through their original manager; a different manager can create another executable on `PATH`. Project-local and temporary package-runner copies must be updated through their package manager too.
+
+See [Updates](/cli/configuration#updates) for supported managers and copy-detection behavior.
 
 ## An update notice appears in output I am parsing
 
-It should not: the notice is written to stderr, never stdout, so `--output json`
-piped to `jq` is unaffected. If something merges the two streams, silence it:
+Notices go to stderr, so a JSON stdout pipe is unaffected. If your runner combines streams, separate stdout/stderr or suppress automatic checks:
 
 ```bash
 export SIM_NO_UPDATE_CHECK=1
 ```
 
+Checks are already quiet in CI and when stderr is redirected. Manual `sim update` remains available when notices are disabled.
+
+## A sync apply or wait did not return a clear outcome
+
+Retain the original request/operation IDs and exact input. An operation may have committed even when its response was lost or its follow-up copying/deployment failed. Query it in the receipt workspace or retry only identical input with the original request ID. See [Reconcile completion and retries](/cli/workflow-sync#reconcile-completion-and-retries).
+
+A workflow wait timeout also leaves its run active. Inspect that run ID; do not assume another execution is a retry of the same work.
+
 ## Anything else
 
-An unexpected error prints a stack trace. That is a bug in the CLI — please
-[open an issue](https://github.com/simstudioai/sim/issues) with the command you
-ran, the trace, and the output of `sim --version`.
+For an unexpected stack trace, [open an issue](https://github.com/simstudioai/sim/issues) with the CLI version, command, sanitized trace, and relevant resolved settings. Remove credentials, sensitive inputs, and private file contents before posting. Debug output can contain request selectors.
+
+## Related docs
+
+- [Authentication](/cli/authentication)
+- [Configuration](/cli/configuration)
+- [Output formats](/cli/output)
+- [Scripting](/cli/scripting)
diff --git a/apps/docs/content/docs/cli/usage-data.mdx b/apps/docs/content/docs/cli/usage-data.mdx
index 9c21bd5f092..37a814cc9d9 100644
--- a/apps/docs/content/docs/cli/usage-data.mdx
+++ b/apps/docs/content/docs/cli/usage-data.mdx
@@ -1,82 +1,85 @@
 ---
 title: Usage data
-description: What the CLI reports about how it is used, what it never sends, and how to turn reporting off
+description: Inspect CLI usage fields, reporting controls, and local state.
 ---
 
-The `sim` CLI reports anonymous usage data so the team can see which commands
-are used, which fail, and how long they take. Reporting is on by default and
-takes one command to turn off.
+The installed CLI sends anonymous usage events by default when its build includes a reporting destination. The events record which commands execute, their outcomes, and duration. Disable reporting for this installation with:
 
-## What is sent
+```bash
+sim telemetry disable
+sim telemetry status
+```
+
+Telemetry commands always print text, regardless of `--output`.
+
+## Turning it off
 
-One event per command, after the command finishes:
+Reporting follows this precedence. `sim telemetry status` names the first reason that disables it:
 
-| Field | Example | Notes |
+| Priority | Control | Scope |
 | --- | --- | --- |
-| Command | `workflows list` | The command's name, never its arguments |
-| Flags | `--output`, `--workspace` | Flag names only, never their values |
-| Argument count | `1` | How many positional arguments, never what they were |
-| Outcome | exit code `0`, `SimApiError`, HTTP `404`, API code `NOT_FOUND` | Never an error message |
-| Duration | `1432` ms | From process start to completion |
-| CLI, Node, OS, CPU | `2.1.2`, `22.14.0`, `darwin`, `arm64` | |
-| Terminal and CI | `is_tty`, `is_ci` | Whether stdout is a terminal, whether a CI variable is set |
-| Coding agent | `claude-code`, or `none` | The AI coding agent whose shell the CLI runs in, if any |
-| Deployment kind | `hosted` or `self_hosted` | Never the address |
-| Device and session ids | random UUIDs | See below |
+| 1 | `DO_NOT_TRACK=1` | Cross-tool environment opt-out |
+| 2 | `SIM_TELEMETRY_DISABLED=1` | CLI environment opt-out |
+| 3 | `sim telemetry disable` | Saved preference in this installation's usage state |
+| 4 | No destination configured in the build | No event can be sent |
 
-## What is never sent
+```bash
+export DO_NOT_TRACK=1
+export SIM_TELEMETRY_DISABLED=1
+sim telemetry disable
+```
 
-Nothing you type. No argument values, flag values, file paths, workflow or
-workspace ids, error messages, environment variable values, credentials, or the
-address of the deployment you talk to. The report leaves your machine from a
-separate short-lived process that is not given your API key.
+Use whichever control matches your environment. `sim telemetry enable` changes the saved preference but cannot override an environment opt-out or add a missing build destination.
 
-## Location
+Disabling reporting also withholds the coding-agent name from Sim API requests. Requests still identify the CLI and its version/runtime through client headers; that request attribution is separate from the anonymous usage event.
 
-The report carries no location of its own. The analytics service derives an
-approximate location (country and city) from the address the report arrived
-from, the way any HTTP request exposes one, and Sim uses that only to see
-which regions use the CLI.
+## What is sent
 
-## Identity
+When enabled, reporting sends one event after an executed command finishes. Telemetry commands, help/version output, parse failures before execution, and the run that displays the first notice are excluded.
 
-The first run mints a random device id and stores it in `telemetry.json` under
-`~/.sim` (or `SIM_CONFIG_DIR`). It is not derived from your hardware, account,
-or network. Commands run within thirty minutes of each other share a session id
-and are numbered, so a sequence of commands can be read back. No profile is
-created for the device, and the data is not joined to your Sim account.
+| Field | Example | Contents |
+| --- | --- | --- |
+| Command | `workflows list` | Registered command name, without argument values |
+| Flags | `--output`, `--workspace` | Names of supplied flags, without values |
+| Argument count | `1` | Count of positional arguments |
+| Outcome | exit `0`, `SimApiError`, HTTP `404`, `NOT_FOUND` | Exit code, error class, HTTP status, and API error code when available; no message |
+| Duration | `1432` ms | Time from process start to completion |
+| CLI, Node, OS, CPU | `2.1.2`, `22.14.0`, `darwin`, `arm64` | Runtime/version information |
+| Terminal and CI | `is_tty`, `is_ci` | Whether stdout is a terminal and whether a CI environment was detected |
+| Coding agent | `claude-code` or `none` | Detected coding agent driving the shell |
+| Deployment kind | `hosted` or `self_hosted` | Deployment classification, without its address |
+| Device/session IDs | Random UUIDs | Installation identifier and a time-based command session |
+
+These are illustrative values, not a required CLI or Node version.
 
-Deleting `telemetry.json` forgets the device id and shows the first-run notice
-again.
+## What is never sent
 
-## Turning it off
+The usage payload excludes argument values, flag values, file paths, workflow/workspace IDs, error messages, environment-variable values, credentials, and the deployment address. It includes no Sim account identity and requests no analytics person profile.
 
-Any of these turns reporting off. The first one that applies is the one
-`sim telemetry status` names.
+A separate short-lived process sends the event. It is not given your Sim API key, and the CLI does not wait for delivery before returning your prompt.
 
-```bash
-export DO_NOT_TRACK=1            # the cross-tool convention, honoured before anything else
-export SIM_TELEMETRY_DISABLED=1  # this CLI only, for one shell or CI job
-sim telemetry disable            # this machine, saved in telemetry.json
-```
+## Identity
 
-`sim telemetry enable` reverses the saved setting. `sim telemetry status` shows
-the current state.
+Usage state is stored in `~/.sim/telemetry.json`, or under `SIM_CONFIG_DIR`. The random device ID is not derived from hardware, account, or network information. Reported commands less than 30 minutes apart share a session ID and sequence number.
 
-Turning reporting off also stops the CLI from telling the API which coding
-agent, if any, is driving it. The CLI still identifies itself as the CLI on
-every request, the way every official client does; that is how a request is
-attributed, not usage data.
+Deleting `telemetry.json` resets the device ID, notice state, and saved enabled/disabled preference. Reporting can return to its default. Environment opt-outs still apply.
+
+## Location
+
+The event contains no location field. The receiving analytics service sees the request's IP address and can derive an approximate country/city from it. This network-derived information is separate from the client payload's device and session IDs.
 
 ## The first-run notice
 
-The first time the CLI would report from an interactive terminal it prints a
-short notice on stderr and does not report that run. The notice is not shown in
-CI or when stderr is redirected, and it is shown once per device.
+The first eligible interactive run prints a notice on stderr and does not report that run. The notice is shown once per saved device state. It is not shown in CI or when stderr is redirected; those conditions alone do not disable reporting.
 
 ## Self-hosted deployments
 
-Reporting is tied to the CLI build, not to the deployment it talks to. The
-published `sim` package reports to Sim. A build made from the repository without
-`SIM_CLI_TELEMETRY_KEY` set has no destination and reports nothing; setting it
-to your own PostHog project token at build time reports to your own project.
+Reporting follows the CLI build, not the Sim deployment it calls. A configured build can report while targeting a self-hosted endpoint.
+
+Building from the repository without `SIM_CLI_TELEMETRY_KEY` supplies no reporting destination. Set that build-time variable to your own PostHog project token to configure a destination; `SIM_CLI_TELEMETRY_HOST` can select its host. Run `sim telemetry status` to inspect the effective state of your installed build.
+
+## Related docs
+
+- [Telemetry commands](/cli/telemetry)
+- [Configuration](/cli/configuration)
+- [Output formats](/cli/output)
diff --git a/apps/docs/content/docs/cli/workflow-mcp-servers.mdx b/apps/docs/content/docs/cli/workflow-mcp-servers.mdx
index 8237adc8c0a..2a630a233d4 100644
--- a/apps/docs/content/docs/cli/workflow-mcp-servers.mdx
+++ b/apps/docs/content/docs/cli/workflow-mcp-servers.mdx
@@ -1,42 +1,48 @@
 ---
-title: Workflow MCP Servers
-description: Manage workflow mcp servers — every subcommand, argument, and flag
+title: Workflow MCP servers
+description: Serve deployed workflows as tools for Model Context Protocol (MCP) clients.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+Serve deployed workflows as tools for Model Context Protocol (MCP) clients.
 
-## Create workflow MCP server
+These servers expose Sim workflows. To connect a server that provides external tools, use [MCP servers](/cli/mcp-servers).
+
+These commands accept the [global options](/cli/commands#global-options).
+
+## Servers
+
+### List workflow MCP servers
+
+OAuth login or personal API key required.
 
 ```bash
-sim workflow-mcp-servers create [options]
+sim workflow-mcp-servers list [options]
 ```
 
-Create Workflow MCP Server (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | Yes | Server display name, shown to connecting MCP clients. |
-| `--description <value>` | No | Optional server description. |
-| `--is-public` | No | Whether the server answers MCP clients without a Sim API key. Defaults to false — a public server executes the workflows it publishes for anyone holding its URL. |
-| `--no-is-public` | No | Send --is-public as false. |
-| `--workflow <value...>` | No | Deployed workflows to publish as tools on the new server. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Delete workflow MCP server
+API request and response schemas: [listWorkflowMcpServers](/api-reference/mcp-servers/listWorkflowMcpServers).
+
+### Get workflow MCP server
+
+OAuth login or personal API key required.
 
 ```bash
-sim workflow-mcp-servers delete <serverId> [options]
+sim workflow-mcp-servers get <serverId>
 ```
 
-Delete Workflow MCP Server (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -47,24 +53,40 @@ Delete Workflow MCP Server (OAuth login or personal API key required)
 
 </CommandTable>
 
+API request and response schemas: [getWorkflowMcpServer](/api-reference/mcp-servers/getWorkflowMcpServer).
+
+### Create workflow MCP server
+
+OAuth login or personal API key required.
+
+```bash
+sim workflow-mcp-servers create [options]
+```
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--name <value>` | Yes | Server display name, shown to connecting MCP clients. |
+| `--description <value>` | No | Optional server description. |
+| `--is-public` | No | Whether the server accepts MCP clients without a Sim API key. Defaults to false; a public server lets anyone holding its URL execute the workflows it exposes. |
+| `--no-is-public` | No | Send --is-public as false. |
+| `--workflow <value...>` | No | Deployed workflows to expose as MCP tools on the new server. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
 
 </CommandTable>
 
-## Publish workflow as MCP tool
+API request and response schemas: [createWorkflowMcpServer](/api-reference/mcp-servers/createWorkflowMcpServer).
+
+### Update workflow MCP server
+
+OAuth login or personal API key required.
 
 ```bash
-sim workflow-mcp-servers tools create <serverId> [options]
+sim workflow-mcp-servers update <serverId> [options]
 ```
 
-Publish Workflow As MCP Tool (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -81,21 +103,25 @@ Publish Workflow As MCP Tool (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--workflow-id <value>` | Yes | Deployed workflow to publish. The workflow must already be deployed. |
-| `--tool-name <value>` | No | Name MCP clients call. Normalized to the MCP tool-name grammar, and derived from the workflow name when omitted. |
-| `--tool-description <value>` | No | Description shown to MCP clients. Derived from the workflow name when omitted. |
-| `--parameter-descriptions <json\|@file>` | No | Per-field description overrides applied to the schema generated from the deployed workflow inputs, as [&#123;"name":"email","description":"Customer email address"&#125;]. A name matching no input field is ignored (JSON, or @path / @- to read a file or stdin). |
+| `--name <value>` | No | Server display name, shown to connecting MCP clients. |
+| `--description <value>` | No | New server description, or null to clear it. (--description null sends the word, not JSON null). |
+| `--is-public` | No | Whether the server answers MCP clients without a Sim API key. |
+| `--no-is-public` | No | Send --is-public as false. |
 
 </CommandTable>
 
-## List workflow MCP tools
+API request and response schemas: [updateWorkflowMcpServer](/api-reference/mcp-servers/updateWorkflowMcpServer).
+
+## Workflow tools
+
+### List workflow MCP tools
+
+OAuth login or personal API key required.
 
 ```bash
 sim workflow-mcp-servers tools list <serverId>
 ```
 
-List Workflow MCP Tools (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -106,14 +132,16 @@ List Workflow MCP Tools (OAuth login or personal API key required)
 
 </CommandTable>
 
-## Unpublish workflow MCP tool
+API request and response schemas: [listWorkflowMcpTools](/api-reference/mcp-servers/listWorkflowMcpTools).
+
+### Deploy workflow as MCP tool [#publish-workflow-as-mcp-tool]
+
+OAuth login or personal API key required.
 
 ```bash
-sim workflow-mcp-servers tools delete <serverId> <workflowId> [options]
+sim workflow-mcp-servers tools create <serverId> [options]
 ```
 
-Unpublish Workflow MCP Tool (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -121,7 +149,6 @@ Unpublish Workflow MCP Tool (OAuth login or personal API key required)
 | Argument | Required | Description |
 | --- | --- | --- |
 | `serverId` | Yes | Unique workflow-MCP server identifier. |
-| `workflowId` | Yes | Workflow published as a tool on this server. |
 
 </CommandTable>
 
@@ -131,18 +158,25 @@ Unpublish Workflow MCP Tool (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--workflow-id <value>` | Yes | Workflow to expose as an MCP tool. It must already be deployed. |
+| `--tool-name <value>` | No | Name MCP clients call. Normalized to the MCP tool-name grammar, and derived from the workflow name when omitted. |
+| `--tool-description <value>` | No | Description shown to MCP clients. Derived from the workflow name when omitted. |
+| `--parameter-descriptions <json\|@file>` | No | Per-field description overrides applied to the schema generated from the deployed workflow inputs, as [&#123;"name":"email","description":"Customer email address"&#125;]. A name matching no input field is ignored (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Get workflow MCP server
+API request and response schemas: [deployWorkflowMcpTool](/api-reference/mcp-servers/deployWorkflowMcpTool).
+
+### Undeploy workflow MCP tool [#unpublish-workflow-mcp-tool]
+
+OAuth login or personal API key required.
+
+This withdraws the tool, and any agent calling it loses access.
 
 ```bash
-sim workflow-mcp-servers get <serverId>
+sim workflow-mcp-servers tools delete <serverId> <workflowId> [options]
 ```
 
-Get Workflow MCP Server (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -150,37 +184,34 @@ Get Workflow MCP Server (OAuth login or personal API key required)
 | Argument | Required | Description |
 | --- | --- | --- |
 | `serverId` | Yes | Unique workflow-MCP server identifier. |
+| `workflowId` | Yes | Workflow registered as an MCP tool on this server. |
 
 </CommandTable>
 
-## List workflow MCP servers
-
-```bash
-sim workflow-mcp-servers list [options]
-```
-
-List Workflow MCP Servers (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Update workflow MCP server
+API request and response schemas: [undeployWorkflowMcpTool](/api-reference/mcp-servers/undeployWorkflowMcpTool).
+
+## Delete servers
+
+### Delete workflow MCP server
+
+OAuth login or personal API key required.
+
+This deletes the MCP server, and any agent calling its tools loses access.
 
 ```bash
-sim workflow-mcp-servers update <serverId> [options]
+sim workflow-mcp-servers delete <serverId> [options]
 ```
 
-Update Workflow MCP Server (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -197,9 +228,12 @@ Update Workflow MCP Server (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | Server display name, shown to connecting MCP clients. |
-| `--description <value>` | No | New server description, or null to clear it. (--description null sends the word, not JSON null). |
-| `--is-public` | No | Whether the server answers MCP clients without a Sim API key. |
-| `--no-is-public` | No | Send --is-public as false. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
+
+API request and response schemas: [deleteWorkflowMcpServer](/api-reference/mcp-servers/deleteWorkflowMcpServer).
+
+## Related docs
+
+- [MCP connections](/agents/mcp)
diff --git a/apps/docs/content/docs/cli/workflow-sync.mdx b/apps/docs/content/docs/cli/workflow-sync.mdx
index 076494631f3..7431f696b9b 100644
--- a/apps/docs/content/docs/cli/workflow-sync.mdx
+++ b/apps/docs/content/docs/cli/workflow-sync.mdx
@@ -1,15 +1,36 @@
 ---
 title: Workflow imports and workspace sync
-description: Preview resource bindings, apply reviewed changes, and verify readiness from an LLM or CI client
+description: Preview destination choices, apply reviewed changes, and reconcile operation completion.
 ---
 
-Use an explicit profile and workspace for every environment. Fork administration requires a personal API key or OAuth login; workspace API keys cannot administer fork edges. Fork creation requires source admin access. Sync and mapping changes require admin access on both workspaces.
+Import an exported workflow as a draft, or fork and sync related workspaces. Preview the destination bindings, apply the same choices, and inspect the operation receipt before using the destination.
 
-These commands use the same v2 operations as a direct API client. See the [API workflow guide](/api-reference/workflow-sync) for HTTP requests, response envelopes, and the command-to-endpoint mapping. CLI JSON output unwraps single-resource responses, so read `.previewFingerprint`; raw HTTP clients read `.data.previewFingerprint`.
+These commands use the v2 protocol described in the [API workflow guide](/api-reference/workflow-sync). CLI single-resource results omit the outer HTTP `data` envelope: read `.previewFingerprint` in CLI output and `.data.previewFingerprint` in raw HTTP output. Paginated CLI lists retain `{data, nextCursor}`.
+
+## Prerequisites
+
+Use an explicit profile and workspace for each environment. Replace example resource IDs with IDs from your export and destination. Save a stable request ID and the exact input for each intended mutation before applying it.
+
+| Operation | Required access |
+| --- | --- |
+| Export | Workflow read access |
+| Import preview/apply | Destination write access; credential binding requires an acting personal/OAuth identity with credential access |
+| Fork discovery, preview, creation | Personal API key or OAuth login and source workspace Admin; creation policy must allow a new workspace |
+| Sync and mapping changes | Personal API key or OAuth login and Admin access to both workspaces on a direct parent/child fork edge |
+| Selectors | Read access in the discovery workspace and access to the chosen credential; workspace keys are unsupported |
+| Operation reads | Read access in the receipt workspace |
+
+Workspace keys cannot administer fork relationships or stand in for a user when binding credentials. OAuth import/fork/sync previews require `api:write`; export, discovery, mapping reads, selectors, and operation reads use `api:read`.
+
+Forking and sync require Enterprise on billing-enabled deployments. Billing-disabled deployments must enable forking through deployment configuration. Check `workspaces fork-availability` before starting. Import and operation reports do not inherit this fork-specific gate.
 
 ## Import a workflow with destination bindings
 
-Portable export is opt-in. It adds a versioned reference manifest to the sanitized graph; credentials and secret values stay in their original workspace.
+### 1. Export and inspect the workflow
+
+`--include-references` adds a versioned manifest of resource identities and their occurrences. Default export clears registered credential fields and workspace bindings. It does not remove every ordinary variable value or literal configuration; inspect the payload before sharing it. Credentials and secret values are not transferred as destination resources.
+
+Pin JSON because import does not accept YAML:
 
 ```sh
 sim --profile source --workspace "$SOURCE_WORKSPACE" --output json \
@@ -19,7 +40,11 @@ sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
   workflows import-preview --workflow @workflow.json > preview.json
 ```
 
-Read `unresolvedBindings` and `unresolvedConfiguration`. Resource mappings select a destination by resource kind and source ID. For example, `mappings.json` can contain:
+`--include-workspace-bindings` can preserve non-secret bindings for a same-workspace round trip. Otherwise, configure required bindings reported by import.
+
+### 2. Map destination resources
+
+Read `unresolvedBindings` and `unresolvedConfiguration`. Resource mappings select a destination by `kind` and source ID. Save an array such as this in `mappings.json`:
 
 ```json
 [
@@ -28,7 +53,9 @@ Read `unresolvedBindings` and `unresolvedConfiguration`. Resource mappings selec
 ]
 ```
 
-Use the existing credentials, tables, files, sandboxes, and other resource commands to discover or create destination resources. An older export without reference metadata can use `--bindings @bindings.json` to address individual source fields. For example, a nested Agent tool's credential binding is:
+Use the credential, table, file, sandbox, and other resource commands to discover or create destination resources. A mapping applies to registered occurrences of that source resource. `targetId:null` requests clearing and cannot satisfy a required binding. Source IDs are labels, not permission to read a source workspace.
+
+Older exports without a reference manifest can use `--bindings @bindings.json` for individual registered source fields. A nested Agent tool credential can be addressed as:
 
 ```json
 [
@@ -43,9 +70,11 @@ Use the existing credentials, tables, files, sandboxes, and other resource comma
 ]
 ```
 
-Use the field path and encoding registered for the actual export. A top-level field uses its own `subBlockKey` and `valuePath: []`. Field bindings have no `sourceId`; they address an occurrence directly. Conflicting resource mappings and field bindings are rejected. Include `--bindings` on both preview and apply when using them.
+Use the path and encoding registered for the actual export. A top-level field uses its own `subBlockKey` and `valuePath:[]`. Field bindings have no `sourceId`; they address an occurrence directly. Conflicting mappings/bindings are rejected. Include `--bindings` in both preview and apply when using them.
+
+### 3. Resolve dependent choices
 
-Dependent choices use the selector key and destination context returned by preview. For example:
+Use the selector key and destination context returned by preview to discover valid values. For example:
 
 ```sh
 sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
@@ -53,15 +82,19 @@ sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
   --context '{"oauthCredential":"destination-connection"}'
 ```
 
-MCP tool discovery uses `mcp.tools` with `mcpServerId`. OAuth connections may require a human to authorize the provider before discovery can succeed.
+MCP tool discovery uses `mcp.tools` with `mcpServerId`. OAuth connections can require human provider authorization before discovery succeeds. Check selector pagination and truncation rather than assuming one result contains every provider option.
 
-Import dependent values use source block IDs and field keys:
+Import-dependent values use source block IDs and the returned field key. Save values in `values.json`:
 
 ```json
 [{ "blockId": "source-agent", "subBlockKey": "tools[0].folder", "value": "destination-label" }]
 ```
 
-Preview again with the exact choices, then apply with that fingerprint and a request ID saved by your client:
+Keep the field key unchanged, including nested tool indices. A field with `multiSelect:true` accepts selected IDs as one comma-separated string.
+
+### 4. Preview and apply the same choices
+
+Preview again with the exact mappings and values. When the preview is ready, apply its fingerprint using the request ID saved for this mutation:
 
 ```sh
 sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
@@ -71,15 +104,19 @@ sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
 sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
   workflows import --workflow @workflow.json \
   --mappings @mappings.json --dependent-values @values.json \
-  --preview-fingerprint "$(jq -r .previewFingerprint preview.json)" \
-  --request-id "$REQUEST_ID" --wait
+  --preview-fingerprint "$(jq -er '.previewFingerprint' preview.json)" \
+  --request-id "$IMPORT_REQUEST_ID" --wait
 ```
 
-Mapped import creates a draft atomically after required bindings and configuration are resolved. The receipt includes the imported IDs and `idMap`. Imports without mapping options retain the existing behavior; they do not return a durable operation receipt. Supplying mapping options, even an empty `--mappings '[]'`, requires both `--request-id` and `--preview-fingerprint`. JSON flags accept `@file` and `@-` for stdin.
+Mapped import creates the draft atomically after required bindings/configuration resolve. The receipt includes imported IDs and `idMap`; remapping occurs before graph ID regeneration. The workflow remains a draft and must be deployed for ordinary execution.
+
+Plain imports without mapping options retain their earlier behavior and return no durable operation receipt. Supplying mapping options, including `--mappings '[]'`, requires both `--request-id` and `--preview-fingerprint`. JSON flags accept `@file` or `@-` for local stdin.
 
 ## Fork, push, and pull
 
-Inspect `workspaces fork-availability`, `lineage`, and `fork-resources`, then use `fork-preview` and `fork` with identical name and copy selections. A fork creates child drafts; resource copying must be explicitly selected.
+### Create a fork
+
+Inspect `workspaces fork-availability`, `lineage`, and `fork-resources`. Resource copies are opt-in. Preview and apply the identical name and copy selections:
 
 ```sh
 sim --profile source --workspace "$SOURCE_WORKSPACE" --output json \
@@ -92,11 +129,17 @@ sim --profile source --workspace "$SOURCE_WORKSPACE" --output json \
 sim --profile source --workspace "$SOURCE_WORKSPACE" --output json \
   workspaces fork --name "Review environment" \
   --copy '{"tables":["source-table"]}' \
-  --preview-fingerprint "$(jq -r .previewFingerprint fork-preview.json)" \
+  --preview-fingerprint "$(jq -er '.previewFingerprint' fork-preview.json)" \
   --request-id "$FORK_REQUEST_ID" --wait
 ```
 
-Push means the current workspace sends its deployed workflows to `--other-workspace-id`. Pull means the other workspace sends them to the current workspace. These meanings are the same on either side of the edge.
+Eligible deployed source workflows become child drafts. Neither fork nor sync copies credentials or secret values. Review destination configuration before deploying forked workflows.
+
+### Select the sync direction and mappings
+
+Push sends the current workspace's deployed workflows to `--other-workspace-id`. Pull brings the other workspace's deployed workflows into the current workspace. Direction is relative to the selected workspace, regardless of which side is the parent. The pair must form a direct fork relationship.
+
+Sync can replace target workflows and archive mapped targets whose source was deleted or archived. Review those actions before confirming:
 
 ```sh
 sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
@@ -104,59 +147,98 @@ sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
 
 sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
   workspaces pull --other-workspace-id "$SOURCE_WORKSPACE" \
-  --preview-fingerprint "$(jq -r .previewFingerprint sync-preview.json)" \
+  --preview-fingerprint "$(jq -er '.previewFingerprint' sync-preview.json)" \
   --request-id "$SYNC_REQUEST_ID" --yes --wait
 ```
 
-Include the same inline mappings and dependent values on preview and apply. Sync values identify `sourceWorkflowId`, `sourceBlockId`, and `subBlockKey`; preview target IDs are not stable public override identities. Sync mapping entries use `resourceType`, `sourceId`, and `targetId` as returned by mapping inspection; import entries use `kind`. Inline sync mappings persist on the fork edge in the same transaction as the sync.
-
-`workspaces mappings get` also returns a storage `id` on each row. Strip it before reusing a result as input: `jq '[.data[] | {resourceType, sourceId, targetId}]'`. Use `oauth_credential` or `service_account_credential` for sync credential mappings, according to the credential type.
+Include identical inline mappings, dependent values, and trigger choices on preview/apply when using them. Sync mapping entries use `resourceType`, `sourceId`, and `targetId`; import entries use `kind`. Inline sync mappings persist in the same transaction as the sync.
 
-For example, `--mappings` and `--dependent-values` take these respective arrays:
+For example, `--mappings` takes:
 
 ```json
 [{ "resourceType": "oauth_credential", "sourceId": "source-connection", "targetId": "destination-connection" }]
 ```
 
+Use `oauth_credential` or `service_account_credential` according to credential type. `workspaces mappings get` requires the other workspace and direction, and returns storage `id` fields. Strip them before reuse:
+
+```sh
+sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \
+  workspaces mappings get --other-workspace-id "$SOURCE_WORKSPACE" --direction pull --limit 0 \
+  | jq '[.data[] | {resourceType, sourceId, targetId}]' > sync-mappings.json
+```
+
+### Configure copies and dependent values
+
+Fork creation uses `--copy`; sync uses `--copy-resources`, for example `'{"tables":["source-table"]}'`. Fork `copy.files` contains workspace file IDs. Sync `copyResources.files` contains storage keys.
+
+Sync-dependent values identify source workflows, blocks, and field keys, rather than provisional preview target IDs:
+
 ```json
 [{ "sourceWorkflowId": "source-workflow", "sourceBlockId": "source-agent", "subBlockKey": "tools[0].folder", "value": "destination-label" }]
 ```
 
-Use `--copy-resources` for sync copies, such as `'{"tables":["source-table"]}'`; fork creation uses `--copy`. Fork `copy.files` takes workspace file IDs; sync `copyResources.files` takes storage keys. Neither copies credentials or secret values.
+Discover each field in its returned `discoveryWorkspaceId` using the returned selector context. This is the source when its parent resource is being copied and the destination when the parent is mapped. Keep nested field keys unchanged; multi-select values are one comma-separated string.
+
+Omitting `--dependent-values` reuses saved choices. Supplying the flag replaces choices for affected workflows, and `[]` clears them. A value in a target draft alone is not saved sync configuration. `dropReferences` acknowledges references deleted in the source; it cannot discard live source resources.
+
+### Review trigger URLs and target changes
 
-For each sync configuration field, run selector discovery in its `discoveryWorkspaceId` with the returned context. This is the source workspace when the parent resource is being copied, and the destination workspace for an existing mapping. Use the returned field key unchanged, including nested tool indices. When `multiSelect` is true, send selected IDs as one comma-separated string.
+Preview's `ready` means the change can commit; it is not deployment readiness. Sync replaces eligible targets and deploys admitted snapshots while preserving exclusions. Merely undeploying a source does not archive its mapped target.
 
-Saved sync choices apply when `--dependent-values` is omitted. Supplying the flag replaces saved choices for the affected workflows; an explicit `[]` clears them. Values that exist only in a target draft are not saved sync choices.
+Inspect `triggerSlots` before replacing webhook triggers:
 
-Sync preview's `ready` describes whether the change can commit; it does not report deployment readiness. Sync replaces eligible target workflows and deploys the admitted snapshots. It preserves exclusions. Deleting a source can archive its mapped target; merely undeploying it does not. Rollback restores the latest target sync using prior deployed versions, and does not restore arbitrary drafts or undo every resource copy.
+- Slots with `ownPath` preserve that URL and accept no override.
+- Other slots can adopt a path from `adoptablePaths`, or select `adoptPath:null` for a new URL.
+- `--trigger-mappings` entries use `sourceWorkflowId`, `sourceBlockId`, and `adoptPath`. Unknown, duplicate, or unavailable choices are rejected.
 
-Inspect preview's `triggerSlots` before replacing webhook triggers. Slots with `ownPath` keep it. For other slots, `--trigger-mappings` accepts entries with `sourceWorkflowId`, `sourceBlockId`, and `adoptPath` selected from `adoptablePaths`, or `null` for a new URL. Pass the identical choices to preview and apply; unknown, duplicate, and unavailable choices are rejected.
+Pass identical trigger choices to preview and apply. Candidates belong to the same target workflow and provider. Review reported trigger URL changes before using the destination.
+
+Rollback restores the latest inbound sync using prior deployed versions. It can archive sync-created workflows and restore archived targets, but does not restore arbitrary drafts or undo every resource copy. Inspect pending activation work. Unlink removes the relationship/mappings while retaining content; exclusions keep selected workflows out of later syncs. See [Workspace commands](/cli/workspaces).
 
 ## Reconcile completion and retries
 
-A successful apply returns `operationId`, `requestId`, `applied`, `status`, resource IDs, and structured issues. `applied: true` means the transaction committed, even if later copying or deployment fails.
+An apply receipt includes `operationId`, `requestId`, `workspaceId`, `applied`, `status`, resource IDs, and issues. `applied:true` means the transaction committed, even if later copying or deployment fails.
 
-Poll in the receipt's `workspaceId`, which may differ from the workspace receiving workflows:
+Poll in the receipt's workspace, which can differ from the workspace receiving workflows:
 
 | Operation | Receipt workspace |
 | --- | --- |
-| Import | Destination workspace |
+| Import | Destination |
 | Fork creation | Source workspace on which `fork` ran |
-| Push or pull | Current `--workspace` on which the command ran |
+| Push/pull | Current `--workspace` on which the command ran |
 
 ```sh
 sim --profile automation --workspace "$OPERATION_WORKSPACE_ID" --output json \
   workspaces operations wait "$OPERATION_ID" --wait-timeout 300
 ```
 
-If the response was lost, use `workspaces operations list --request-id "$REQUEST_ID"` in that same workspace, or retry the identical mutation. List results retain `{ "data": [...], "nextCursor": ... }`; single operation and preview results are unwrapped. Operation lists contain stored snapshots; use `operations get` or `operations wait` to refresh completion status.
+The default wait is 3600 seconds; zero waits indefinitely. The request timeout is separate. Wait outcomes are:
 
-Verify deployment readiness before treating a synced environment as ready. Inspect trigger URL changes and configuration issues in the report. Completion with warnings exits successfully; required configuration exits 3, failed completion exits 1, and wait timeout exits 4. Timeout and uncertain-mutation diagnostics retain reconciliation IDs.
+| Exit code | Outcome |
+| --- | --- |
+| `0` | Completed, including completion with warnings |
+| `1` | Failed completion or command/request failure |
+| `3` | Operation committed but requires configuration |
+| `4` | Wait timed out; the operation can still continue |
 
-After a lost response, retry the exact mutation with the original request ID. Identical retries return the same operation. Changing inputs under that ID returns 409. If a preview is stale and nothing committed, request a new preview and use a new request ID for the revised request. The CLI never invents a fresh ID to retry an uncertain mutation.
+Inspect `issues`, copied-resource progress, the exact admitted deployments' readiness, and trigger URL changes. Completed imports and forks remain drafts. For sync, verify deployment readiness before using the environment.
+
+### Recover a lost response
+
+Use `workspaces operations list --request-id "$REQUEST_ID"` in the same receipt workspace, or retry the identical mutation with its original ID. Lists retain `{data, nextCursor}` and contain stored snapshots; `operations get` or `operations wait` refreshes completion status. Timeout and uncertain-mutation diagnostics retain reconciliation IDs.
+
+Identical authorized retries return the original operation. Changed inputs under that request ID return 409. If a preview is stale and nothing committed, obtain a new preview and use a new ID for the revised request. The CLI does not invent a new ID to retry an uncertain mutation.
 
 ## Validation boundary
 
-The repository's `bun run test:workflow-sync` harness starts a disposable PostgreSQL database and exercises real authorization, v2 HTTP adapters, CLI subprocesses, transactions, receipts, and deployment workers. External provider responses and the separate realtime process use controlled fixtures. This covers platform behavior and failure recovery; a provider connection still needs validation in the destination environment.
+Validate provider connections in the destination environment as well as the platform operation report. Repository integration fixtures do not establish a live provider connection.
+
+## Related docs
 
-Completed imports and forks are drafts. For sync, check the report's deployment readiness and copied-resource progress before using the environment.
+- [API workflow guide](/api-reference/workflow-sync)
+- [Workspace forking](/platform/enterprise/forks)
+- [Workflow commands](/cli/workflows)
+- [Workspace commands](/cli/workspaces)
+- [Selectors](/cli/selectors)
+- [Exit codes](/cli/scripting#exit-codes)
+- [Workflow-sync contributor harness](/api-reference/workflow-sync#related-docs)
diff --git a/apps/docs/content/docs/cli/workflows.mdx b/apps/docs/content/docs/cli/workflows.mdx
index 019d9691255..0e670a1d73f 100644
--- a/apps/docs/content/docs/cli/workflows.mdx
+++ b/apps/docs/content/docs/cli/workflows.mdx
@@ -1,51 +1,49 @@
 ---
 title: Workflows
-description: Manage workflows — every subcommand, argument, and flag
+description: Build, deploy, run, and inspect workflows from the terminal.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Build, deploy, run, and inspect workflows from the terminal.
+
 `sim workflows` is also spelled `sim workflow`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
+
+## Workflows
 
-## Activate workflow version
+### List workflows
 
 ```bash
-sim workflows activate create <workflowId> <version> [options]
+sim workflows list [options]
 ```
 
-Activate Workflow Version (OAuth login or personal API key required)
-
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
-| `version` | Yes | Numeric deployment version. |
-
-</CommandTable>
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. The folder filter resolves against active folders only, so pairing it with `archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
+| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
+| `--deployed-only` | No | Return only workflows with an active deployment when true. |
+| `--no-deployed-only` | No | Send --deployed-only as false. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--search <value>` | No | Case-insensitive substring match against the resource name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "position". Accepted values: `position`, `name`, `createdAt`, `updatedAt`, `runCount`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
-## Edit a workflow’s blocks, connections and settings with a batch of operations
+API request and response schemas: [listWorkflows](/api-reference/workflows/listWorkflows).
+
+### Get workflow
 
 ```bash
-sim workflows operations apply <workflowId> [options]
+sim workflows get <workflowId>
 ```
 
-Edit a workflow’s blocks, connections and settings with a batch of operations (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -56,27 +54,32 @@ Edit a workflow’s blocks, connections and settings with a batch of operations
 
 </CommandTable>
 
+API request and response schemas: [getWorkflow](/api-reference/workflows/getWorkflow).
+
+### Create workflow
+
+```bash
+sim workflows create [options]
+```
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--dry-run` | No | Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (`409`) as a committed write. `needsRedeployment` describes the pre-write state. For semantic operations, `mintedBlockIds` is empty; `previewBlockIds` contains provisional IDs with a warning, since committing mints new IDs. |
-| `--no-dry-run` | No | Send --dry-run as false. |
-| `--operations <json\|@file>` | Yes | Edits to apply, in a single batch, keyed by operation_type: [&#123;"operation_type":"add","block_id":"my-fn","params":&#123;"type":"function","name":"My Fn","inputs":&#123;"code":"return &#123;ok:true&#125;"&#125;&#125;&#125;,&#123;"operation_type":"edit","block_id":"&lt;uuid&gt;","params":&#123;"name":"Renamed","connections":&#123;"success":"my-fn"&#125;&#125;&#125;,&#123;"operation_type":"delete","block_id":"&lt;uuid&gt;"&#125;]. Also extract_from_subflow, whose params carry &#123;"subflowId":"&lt;loop-id&gt;"&#125;, and insert_into_subflow, which creates a block and so takes an add’s params plus that subflowId (JSON, or @path / @- to read a file or stdin). |
-| `--atomic` | No | Fail the whole batch when any operation is declined or any block input would be dropped. The default applies what it can and reports the rest in `skipped` and `inputValidationErrors`; `true` writes nothing and answers `409` instead. |
-| `--no-atomic` | No | Send --atomic as false. |
-| `--layout <value>` | No | Whether to reposition blocks the batch touched. `targeted` (default) nudges only the affected subgraph; `none` leaves every position exactly as supplied. Accepted values: `targeted`, `none`. |
-| `--set-block-enabled <json\|@file>` | No | Blocks to enable or disable, applied after --operations: [&#123;"block_id":"&lt;uuid&gt;","enabled":false&#125;]. Disabling a loop or parallel cascades to its unlocked descendants; enabling a block whose container is disabled is declined (JSON, or @path / @- to read a file or stdin). |
-| `-y, --yes` | No | Confirm this operation (required unless --dry-run). |
+| `--name <value>` | Yes | Workflow name. |
+| `--description <value>` | No | Optional workflow description. |
+| `--folder <value>` | No | Existing folder path (leading / optional); create it first with sim workflows mkdir &lt;path&gt;. |
 
 </CommandTable>
 
-## Update workflow variables
+API request and response schemas: [createWorkflow](/api-reference/workflows/createWorkflowV2).
+
+### Update workflow
 
 ```bash
-sim workflows variables update <workflowId> [options]
+sim workflows update <workflowId> [options]
 ```
 
 **Arguments**
@@ -95,15 +98,18 @@ sim workflows variables update <workflowId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--operations <json\|@file>` | Yes | Variable changes to apply in order, keyed by operation: [&#123;"operation":"add","name":"my_var","type":"string","value":"hello"&#125;,&#123;"operation":"edit","name":"my_var","value":"updated"&#125;,&#123;"operation":"delete","name":"my_var"&#125;] (JSON, or @path / @- to read a file or stdin). |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--name <value>` | No | Replacement workflow name. |
+| `--description <value>` | No | Replacement workflow description; null clears it. (--description null sends the word, not JSON null). |
+| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 
 </CommandTable>
 
-## Cancel a running workflow run
+API request and response schemas: [updateWorkflow](/api-reference/workflows/updateWorkflowV2).
+
+### Duplicate workflow
 
 ```bash
-sim workflows runs cancel <runId> [options]
+sim workflows duplicate create <workflowId> [options]
 ```
 
 **Arguments**
@@ -112,7 +118,7 @@ sim workflows runs cancel <runId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `runId` | Yes | Unique workflow run identifier. |
+| `workflowId` | Yes | Unique workflow identifier. |
 
 </CommandTable>
 
@@ -122,81 +128,66 @@ sim workflows runs cancel <runId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--workflow <workflowId>` | Yes | Workflow ID. |
+| `--name <value>` | No | Name for the copy. Defaults to the source name, deduplicated within the folder. |
+| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 
 </CommandTable>
 
-## Show run status
+API request and response schemas: [duplicateWorkflow](/api-reference/workflows/duplicateWorkflow).
+
+### Move workflows
 
 ```bash
-sim workflows runs get <runId> [options]
+sim workflows move [options]
 ```
 
-Show run status (requested outputs are included in JSON or YAML output)
-
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `runId` | Yes | Unique workflow run identifier. |
-
-</CommandTable>
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--workflow <workflowId>` | Yes | Workflow ID. |
-| `--include-output` | No | Include the final output in JSON or YAML output. |
-| `--select-output <value...>` | No | Include blockName.path or blockId.path values (e.g. agent_1.content) in JSON or YAML output; names resolve against the workflow’s current blocks, and missing paths are omitted (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--include-file-base64` | No | Inline each produced file's bytes as base64. Requires `includeOutput`. A file above the inline ceiling answers `413` naming its download path; fetch large files from `downloadPath` instead. |
-| `--no-include-file-base64` | No | Send --include-file-base64 as false. |
-| `--base64-max-bytes <value>` | No | Per-file inline ceiling, lowering but never raising the server limit of 16 MiB. |
+| `--workflow <value...>` | Yes | Workflows to move. Duplicates are collapsed. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--to <value>` | Yes | Destination folder path; / moves the workflows to the workspace root. |
 
 </CommandTable>
 
-## List runs for a workflow
+API request and response schemas: [moveWorkflows](/api-reference/workflows/moveWorkflows).
+
+### Move a workflow to a folder
 
 ```bash
-sim workflows runs list [options]
+sim workflows mv <workflowId> <folder>
 ```
 
-**Options**
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--workflow <workflowId>` | Yes | Workflow ID. |
-| `--status <value>` | No | Filter by run status. Accepted values: `pending`, `running`, `completed`, `failed`, `cancelled`, `paused`. |
-| `--trigger <value>` | No | Filter by trigger type. |
-| `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
-| `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--order <value>` | No | Sort direction by run start time. This list is sortable only by run start time, so it takes `order` in place of `sortBy`/`sortOrder`, which it rejects. Accepted values: `asc`, `desc`. |
+| `workflowId` | Yes | Unique workflow identifier. |
+| `folder` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-## Resume a paused run
+API request and response schemas: [updateWorkflow](/api-reference/workflows/updateWorkflowV2).
+
+### Delete workflow
+
+This archives the workflow and its run history; restore with `workflows restore`.
 
 ```bash
-sim workflows runs resume <runId> [options]
+sim workflows delete <workflowId> [options]
 ```
 
-Resume a paused run (output is included in JSON or YAML output)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `runId` | Yes | Unique workflow run identifier. |
+| `workflowId` | Yes | Unique workflow identifier. |
 
 </CommandTable>
 
@@ -206,16 +197,16 @@ Resume a paused run (output is included in JSON or YAML output)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--workflow <workflowId>` | Yes | Workflow ID. |
-| `--context <value>` | Yes | Pause context ID returned by run status. |
-| `--input <json\|@file>` | No | Resume input as JSON (JSON, or @path / @- to read a file or stdin). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Wait for a run to reach a terminal state, then show it
+API request and response schemas: [deleteWorkflow](/api-reference/workflows/deleteWorkflowV2).
+
+### Restore an archived workflow
 
 ```bash
-sim workflows runs wait <runId> [options]
+sim workflows restore <workflowId>
 ```
 
 **Arguments**
@@ -224,25 +215,18 @@ sim workflows runs wait <runId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `runId` | Yes | Unique workflow run identifier. |
+| `workflowId` | Yes | Unique workflow identifier. |
 
 </CommandTable>
 
-**Options**
-
-<CommandTable>
-
-| Option | Required | Description |
-| --- | --- | --- |
-| `--workflow <workflowId>` | Yes | Workflow ID. |
-| `--wait-timeout <seconds>` | No | Give up after this many seconds, or 0 to wait indefinitely (default: 3600). Bounds the whole wait; SIM_TIMEOUT_SECONDS bounds one request. |
+API request and response schemas: [restoreWorkflow](/api-reference/workflows/restoreWorkflow).
 
-</CommandTable>
+## Draft state and edits
 
-## Compare workflow versions
+### Get workflow state
 
 ```bash
-sim workflows versions compare <workflowId> [options]
+sim workflows state get <workflowId>
 ```
 
 **Arguments**
@@ -255,21 +239,16 @@ sim workflows versions compare <workflowId> [options]
 
 </CommandTable>
 
-**Options**
-
-<CommandTable>
+API request and response schemas: [getWorkflowState](/api-reference/workflows/getWorkflowState).
 
-| Option | Required | Description |
-| --- | --- | --- |
-| `--base <value>` | Yes | Deployment version to compare from. |
-| `--target <value>` | Yes | Deployment version to compare to, in the same workflow. |
+### Replace workflow state
 
-</CommandTable>
+OAuth login or personal API key required.
 
-## Get workflow version
+This replaces the entire draft graph and cannot be undone.
 
 ```bash
-sim workflows versions get <workflowId> <version>
+sim workflows state replace <workflowId> [options]
 ```
 
 **Arguments**
@@ -279,14 +258,36 @@ sim workflows versions get <workflowId> <version>
 | Argument | Required | Description |
 | --- | --- | --- |
 | `workflowId` | Yes | Unique workflow identifier. |
-| `version` | Yes | Numeric deployment version. |
 
 </CommandTable>
 
-## List workflow versions
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--dry-run` | No | Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (`409`) as a committed write. `needsRedeployment` describes the pre-write state. For semantic operations, `mintedBlockIds` is empty; `previewBlockIds` contains provisional IDs with a warning, since committing mints new IDs. |
+| `--no-dry-run` | No | Send --dry-run as false. |
+| `--blocks <json\|@file>` | Yes | Blocks keyed by block id. (JSON, or @path / @- to read a file or stdin). |
+| `--edges <json\|@file>` | Yes | Directed connections between blocks. (JSON, or @path / @- to read a file or stdin). |
+| `--loops <json\|@file>` | No | Ignored on write: loop containers are recomputed from `blocks`. (JSON, or @path / @- to read a file or stdin). |
+| `--parallels <json\|@file>` | No | Ignored on write: parallel containers are recomputed from `blocks`. (JSON, or @path / @- to read a file or stdin). |
+| `--variables <json\|@file>` | No | Replacement variable set. Omit to leave the stored variables untouched. (JSON, or @path / @- to read a file or stdin). |
+| `-y, --yes` | Conditional | Confirm this operation (required unless --dry-run). |
+
+</CommandTable>
+
+API request and response schemas: [replaceWorkflowState](/api-reference/workflows/replaceWorkflowState).
+
+### Edit a workflow’s blocks, connections and settings with a batch of operations
+
+OAuth login or personal API key required.
+
+This edits the draft graph: the batch adds, edits, or deletes blocks and their edges as written.
 
 ```bash
-sim workflows versions list <workflowId> [options]
+sim workflows operations apply <workflowId> [options]
 ```
 
 **Arguments**
@@ -305,15 +306,25 @@ sim workflows versions list <workflowId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--dry-run` | No | Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (`409`) as a committed write. `needsRedeployment` describes the pre-write state. For semantic operations, `mintedBlockIds` is empty; `previewBlockIds` contains provisional IDs with a warning, since committing mints new IDs. |
+| `--no-dry-run` | No | Send --dry-run as false. |
+| `--operations <json\|@file>` | Yes | Edits to apply, in a single batch, keyed by operation_type: [&#123;"operation_type":"add","block_id":"my-fn","params":&#123;"type":"function","name":"My Fn","inputs":&#123;"code":"return &#123;ok:true&#125;"&#125;&#125;&#125;,&#123;"operation_type":"edit","block_id":"&lt;uuid&gt;","params":&#123;"name":"Renamed","connections":&#123;"success":"my-fn"&#125;&#125;&#125;,&#123;"operation_type":"delete","block_id":"&lt;uuid&gt;"&#125;]. Also extract_from_subflow, whose params carry &#123;"subflowId":"&lt;loop-id&gt;"&#125;, and insert_into_subflow, which creates a block and so takes an add’s params plus that subflowId (JSON, or @path / @- to read a file or stdin). |
+| `--atomic` | No | Fail the whole batch when any operation is declined or any block input would be dropped. The default applies what it can and reports the rest in `skipped` and `inputValidationErrors`; `true` writes nothing and answers `409` instead. |
+| `--no-atomic` | No | Send --atomic as false. |
+| `--layout <value>` | No | Whether to reposition blocks the batch touched. `targeted` (default) nudges only the affected subgraph; `none` leaves every position exactly as supplied. Accepted values: `targeted`, `none`. |
+| `--set-block-enabled <json\|@file>` | No | Blocks to enable or disable, applied after --operations: [&#123;"block_id":"&lt;uuid&gt;","enabled":false&#125;]. Disabling a loop or parallel cascades to its unlocked descendants; enabling a block whose container is disabled is declined (JSON, or @path / @- to read a file or stdin). |
+| `-y, --yes` | Conditional | Confirm this operation (required unless --dry-run). |
 
 </CommandTable>
 
-## Update workflow version
+API request and response schemas: [applyWorkflowOperations](/api-reference/workflows/applyWorkflowOperations).
+
+### Update workflow variables
+
+This applies the listed variable changes; variables omitted from the operations remain unchanged.
 
 ```bash
-sim workflows versions update <workflowId> <version> [options]
+sim workflows variables update <workflowId> [options]
 ```
 
 **Arguments**
@@ -323,7 +334,6 @@ sim workflows versions update <workflowId> <version> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `workflowId` | Yes | Unique workflow identifier. |
-| `version` | Yes | Numeric deployment version. |
 
 </CommandTable>
 
@@ -333,33 +343,50 @@ sim workflows versions update <workflowId> <version> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | New label for the deployment version. |
-| `--description <value>` | No | New release note for the deployment version, or null to clear it. (--description null sends the word, not JSON null). |
+| `--operations <json\|@file>` | Yes | Variable changes to apply in order, keyed by operation: [&#123;"operation":"add","name":"my_var","type":"string","value":"hello"&#125;,&#123;"operation":"edit","name":"my_var","value":"updated"&#125;,&#123;"operation":"delete","name":"my_var"&#125;] (JSON, or @path / @- to read a file or stdin). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Create workflow
+API request and response schemas: [applyWorkflowVariables](/api-reference/workflows/applyWorkflowVariables).
+
+## Deployments and versions
+
+### Deploy workflow
+
+OAuth login or personal API key required.
 
 ```bash
-sim workflows create [options]
+sim workflows deploy <workflowId> [options]
 ```
 
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `workflowId` | Yes | Unique workflow identifier. |
+
+</CommandTable>
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | Yes | Workflow name. |
-| `--description <value>` | No | Optional workflow description. |
-| `--folder <value>` | No | Existing folder path (leading / optional); create it first with sim workflows mkdir &lt;path&gt;. |
+| `--name <value>` | No | Optional label for the deployment version. |
+| `--description <value>` | No | Optional release note for the deployment version. |
 
 </CommandTable>
 
-## Create a workflow folder at a path
+API request and response schemas: [deployWorkflow](/api-reference/workflows/deployWorkflow).
+
+### Show a workflow’s current deployment
 
 ```bash
-sim workflows folders create <path>
+sim workflows deployment status <workflowId>
 ```
 
 **Arguments**
@@ -368,14 +395,18 @@ sim workflows folders create <path>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `workflowId` | Yes | Unique workflow identifier. |
 
 </CommandTable>
 
-## Delete workflow folder
+API request and response schemas: [getWorkflowDeployment](/api-reference/workflows/getWorkflowDeployment).
+
+### Update workflow public API access
+
+OAuth login or personal API key required.
 
 ```bash
-sim workflows folders delete <path> [options]
+sim workflows deployment update <workflowId> [options]
 ```
 
 **Arguments**
@@ -384,7 +415,7 @@ sim workflows folders delete <path> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `workflowId` | Yes | Unique workflow identifier. |
 
 </CommandTable>
 
@@ -394,18 +425,27 @@ sim workflows folders delete <path> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--recursive` | No | Delete the folder and its descendants. |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--is-public-api <true\|false>` | Yes | Whether the deployed workflow should accept unauthenticated public API execution. Accepted values: `true`, `false`. |
 
 </CommandTable>
 
-## List workflow folders
+API request and response schemas: [updateWorkflowPublicApi](/api-reference/workflows/updateWorkflowPublicApi).
+
+### List workflow versions
 
 ```bash
-sim workflows folders list [options]
+sim workflows versions list <workflowId> [options]
 ```
 
-Also available as `sim workflows folders ls`.
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `workflowId` | Yes | Unique workflow identifier. |
+
+</CommandTable>
 
 **Options**
 
@@ -413,36 +453,36 @@ Also available as `sim workflows folders ls`.
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--parent <value>` | No | Direct parent folder path. |
-| `--search <value>` | No | Case-insensitive substring match against the folder name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
-## Rename or move a workflow folder
+API request and response schemas: [listWorkflowVersions](/api-reference/workflows/listWorkflowVersionsV2).
+
+### Get workflow version
 
 ```bash
-sim workflows folders move <path> <destination>
+sim workflows versions get <workflowId> <version>
 ```
 
-Also available as `sim workflows folders mv`.
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | Yes | Folder path as shown in the app; the leading / is optional |
-| `destination` | Yes | Folder path as shown in the app; the leading / is optional |
+| `workflowId` | Yes | Unique workflow identifier. |
+| `version` | Yes | Numeric deployment version. |
 
 </CommandTable>
 
-## Delete workflow
+API request and response schemas: [getWorkflowVersion](/api-reference/workflows/getWorkflowVersionV2).
+
+### Update workflow version
 
 ```bash
-sim workflows delete <workflowId> [options]
+sim workflows versions update <workflowId> <version> [options]
 ```
 
 **Arguments**
@@ -452,6 +492,7 @@ sim workflows delete <workflowId> [options]
 | Argument | Required | Description |
 | --- | --- | --- |
 | `workflowId` | Yes | Unique workflow identifier. |
+| `version` | Yes | Numeric deployment version. |
 
 </CommandTable>
 
@@ -461,18 +502,19 @@ sim workflows delete <workflowId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--name <value>` | No | New label for the deployment version. |
+| `--description <value>` | No | New release note for the deployment version, or null to clear it. (--description null sends the word, not JSON null). |
 
 </CommandTable>
 
-## Take a workflow’s chat deployment offline
+API request and response schemas: [updateWorkflowVersion](/api-reference/workflows/updateWorkflowVersionV2).
+
+### Compare workflow versions
 
 ```bash
-sim workflows chat unpublish <workflowId> [options]
+sim workflows versions compare <workflowId> [options]
 ```
 
-Take a workflow’s chat deployment offline (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -489,18 +531,23 @@ Take a workflow’s chat deployment offline (OAuth login or personal API key req
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--base <value>` | Yes | Deployment version to compare from. |
+| `--target <value>` | Yes | Deployment version to compare to, in the same workflow. |
 
 </CommandTable>
 
-## Show a workflow’s chat deployment
+API request and response schemas: [compareWorkflowVersions](/api-reference/workflows/compareWorkflowVersionsV2).
+
+### Activate workflow version
+
+OAuth login or personal API key required.
+
+This changes which deployed version runs in production for every API and chat consumer.
 
 ```bash
-sim workflows chat status <workflowId>
+sim workflows activate create <workflowId> <version> [options]
 ```
 
-Show a workflow’s chat deployment (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -508,16 +555,31 @@ Show a workflow’s chat deployment (OAuth login or personal API key required)
 | Argument | Required | Description |
 | --- | --- | --- |
 | `workflowId` | Yes | Unique workflow identifier. |
+| `version` | Yes | Numeric deployment version. |
 
 </CommandTable>
 
-## Publish or replace a workflow’s chat deployment
+**Options**
 
-```bash
-sim workflows chat publish <workflowId> [options]
-```
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `-y, --yes` | Yes | Confirm this operation. |
+
+</CommandTable>
+
+API request and response schemas: [activateWorkflowVersion](/api-reference/workflows/activateWorkflowVersion).
 
-Publish or replace a workflow’s chat deployment (OAuth login or personal API key required)
+### Revert workflow to version
+
+OAuth login or personal API key required.
+
+This overwrites the draft graph with the selected version and cannot be undone.
+
+```bash
+sim workflows revert create <workflowId> <version> [options]
+```
 
 **Arguments**
 
@@ -526,6 +588,7 @@ Publish or replace a workflow’s chat deployment (OAuth login or personal API k
 | Argument | Required | Description |
 | --- | --- | --- |
 | `workflowId` | Yes | Unique workflow identifier. |
+| `version` | Yes | Numeric deployment version, or `active` for the currently live version. |
 
 </CommandTable>
 
@@ -535,30 +598,22 @@ Publish or replace a workflow’s chat deployment (OAuth login or personal API k
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--identifier <value>` | Yes | URL slug the deployed chat answers on. Must be free across live deployments. |
-| `--title <value>` | Yes | Title shown to visitors. |
-| `--description <value>` | No | Description shown to visitors. Omitted clears it. |
-| `--customizations <json\|@file>` | No | Presentation overrides. Omitted fields take platform defaults. (JSON, or @path / @- to read a file or stdin). |
-| `--auth-type <value>` | No | How visitors are gated. `public` leaves the chat open to anyone holding the URL. Accepted values: `public`, `password`, `email`, `sso`. |
-| `--password <value>` | No | Write-only password of 15 to 1024 characters, not only whitespace. Required whenever `authType` is `password`, and rejected otherwise. Never readable back. Taken literally, except that a request from the Sim agent resolves a whole-value `&#123;&#123;ENV_VAR&#125;&#125;` reference to that variable before the rules apply. |
-| `--allowed-emails <json\|@file>` | No | Email addresses or domains admitted under `email` and `sso` gating. At least one is required for those modes. (JSON, or @path / @- to read a file or stdin). |
-| `--output-configs <json\|@file>` | No | Block outputs to surface to visitors. Omitted surfaces none. (JSON, or @path / @- to read a file or stdin). |
-| `--include-thinking` | No | Allow visitors to receive provider thinking events. |
-| `--no-include-thinking` | No | Send --include-thinking as false. |
-| `--include-tool-calls` | No | Allow visitors to receive tool lifecycle events. |
-| `--no-include-tool-calls` | No | Send --include-tool-calls as false. |
 | `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Deploy workflow
+API request and response schemas: [revertWorkflowVersion](/api-reference/workflows/revertWorkflowVersion).
+
+### Rollback workflow
+
+OAuth login or personal API key required.
+
+This changes which deployed version runs in production for every API and chat consumer.
 
 ```bash
-sim workflows deploy <workflowId> [options]
+sim workflows rollback <workflowId> [options]
 ```
 
-Deploy Workflow (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -575,15 +630,21 @@ Deploy Workflow (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | Optional label for the deployment version. |
-| `--description <value>` | No | Optional release note for the deployment version. |
+| `--to-version <value>` | No | Deployment version to reactivate. Omit to select the previous active version. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Duplicate workflow
+API request and response schemas: [rollbackWorkflow](/api-reference/workflows/rollbackWorkflow).
+
+### Take a workflow out of deployment
+
+OAuth login or personal API key required.
+
+This takes the workflow offline for every API and chat consumer, and agents calling its MCP tools lose access until it is deployed again.
 
 ```bash
-sim workflows duplicate create <workflowId> [options]
+sim workflows undeploy <workflowId> [options]
 ```
 
 **Arguments**
@@ -602,12 +663,15 @@ sim workflows duplicate create <workflowId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | Name for the copy. Defaults to the source name, deduplicated within the folder. |
-| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Run a deployed workflow or execute saved state manually
+API request and response schemas: [undeployWorkflow](/api-reference/workflows/undeployWorkflow).
+
+## Run and inspect
+
+### Run a deployed workflow or execute saved state manually
 
 ```bash
 sim workflows run <workflowId> [options]
@@ -630,10 +694,10 @@ sim workflows run <workflowId> [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--input <json\|@file>` | No | Trigger input as JSON (JSON, or @path / @- to read a file or stdin). |
-| `--async` | No | Queue the run and return immediately. |
+| `--async` | No | Queue the run and return immediately. Defaults to false. |
 | `--execution-timeout-seconds <value>` | No | Maximum duration of an asynchronous run, in seconds, capped by the plan's execution timeout. Requires `async: true`; otherwise returns `400`. |
 | `--select-output <value...>` | No | Return blockName.path values (e.g. agent_1.content), or childWorkflowId.blockName.path for a child workflow (applies to every invocation) — in blockOutputs on a sync run, or from the streamed result with --follow; missing paths are omitted. Not available with --async (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--include-file-base64` | No | Inline eligible output files as base64 content (default: true; Sim’s in-app agent gets file references only unless this flag is passed). Rejected when `async` is true. |
+| `--include-file-base64` | No | Inline eligible output files as base64 content. Defaults to true for the installed CLI; Chat defaults to file references and admits requested bytes only for synchronous runs. Rejected when async is true. |
 | `--no-include-file-base64` | No | Send --include-file-base64 as false. |
 | `--base64-max-bytes <value>` | No | Maximum total bytes of file content to inline as base64, lowering but never raising the server limit of 16 MiB. Rejected when `async` is true. |
 | `--run-id <value>` | No | One-shot identifier for this run; NOT an idempotency key — reusing a claimed value fails with RUN_ID_CONFLICT instead of replaying the first result, and a fresh value starts another run. |
@@ -649,10 +713,39 @@ sim workflows run <workflowId> [options]
 
 </CommandTable>
 
-## Print a workflow as a portable JSON document
+API request and response schemas: [executeWorkflow](/api-reference/workflows/executeWorkflowV2).
+
+### List runs for a workflow
 
 ```bash
-sim workflows export <workflowId> [options]
+sim workflows runs list [options]
+```
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--workflow <workflowId>` | Yes | Workflow ID. |
+| `--status <value>` | No | Filter by run status. Accepted values: `pending`, `running`, `completed`, `failed`, `cancelled`, `paused`. |
+| `--trigger <value>` | No | Filter by trigger type. |
+| `--start-date <value>` | No | Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
+| `--end-date <value>` | No | Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--order <value>` | No | Sort direction by run start time. This list is sortable only by run start time, so it takes `order` in place of `sortBy`/`sortOrder`, which it rejects. Defaults to "desc". Accepted values: `asc`, `desc`. |
+
+</CommandTable>
+
+API request and response schemas: [listWorkflowRuns](/api-reference/workflow-runs/listWorkflowRunsV2).
+
+### Show run status
+
+Requested outputs are included in JSON or YAML output.
+
+```bash
+sim workflows runs get <runId> [options]
 ```
 
 **Arguments**
@@ -661,7 +754,7 @@ sim workflows export <workflowId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
+| `runId` | Yes | Unique workflow run identifier. |
 
 </CommandTable>
 
@@ -671,16 +764,21 @@ sim workflows export <workflowId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--include-references` | No | Include non-secret resource identities for mapped import. |
-| `--include-workspace-bindings` | No | Whether to keep workspace-scoped bindings — table, knowledge base, document, folder, channel, and other resource selectors — in the exported state. Defaults to false, the sharing-safe export in which those ids are cleared because they resolve nowhere else. Send true for a same-workspace round trip so the re-imported workflow can run without re-selecting them. Credentials, passwords, and table sub-block values are cleared either way. |
-| `--no-include-workspace-bindings` | No | Send --include-workspace-bindings as false. |
+| `--workflow <workflowId>` | Yes | Workflow ID. |
+| `--include-output` | No | Include the final output in JSON or YAML output. |
+| `--select-output <value...>` | No | Include blockName.path or blockId.path values (e.g. agent_1.content) in JSON or YAML output; names resolve against the workflow’s current blocks, and missing paths are omitted (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--include-file-base64` | No | Inline each produced file's bytes as base64. Requires `includeOutput`. A file above the inline ceiling answers `413` naming its download path; fetch large files from `downloadPath` instead. |
+| `--no-include-file-base64` | No | Send --include-file-base64 as false. |
+| `--base64-max-bytes <value>` | No | Per-file inline ceiling, lowering but never raising the server limit of 16 MiB. |
 
 </CommandTable>
 
-## Get workflow
+API request and response schemas: [getWorkflowRun](/api-reference/workflow-runs/getWorkflowRunV2).
+
+### Wait until a run finishes or needs input [#wait-for-a-run-to-reach-a-terminal-state-then-show-it]
 
 ```bash
-sim workflows get <workflowId>
+sim workflows runs wait <runId> [options]
 ```
 
 **Arguments**
@@ -689,14 +787,31 @@ sim workflows get <workflowId>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
+| `runId` | Yes | Unique workflow run identifier. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--workflow <workflowId>` | Yes | Workflow ID. |
+| `--wait-timeout <seconds>` | No | Give up after this many seconds, or 0 to wait indefinitely (default: 3600). Bounds the whole wait; SIM_TIMEOUT_SECONDS bounds one request. |
 
 </CommandTable>
 
-## Show a workflow’s current deployment
+Exit codes: 0 completed, 1 failed, 2 cancelled, 3 needs input, 4 timed out. Time-based pauses continue waiting; a human pause or an unspecified pause kind ends the wait with code 3. Use `sim workflows runs resume` with the pause context to continue.
+
+API request and response schemas: [getWorkflowRun](/api-reference/workflow-runs/getWorkflowRunV2).
+
+### Resume a paused run
+
+Output is included in JSON or YAML output.
 
 ```bash
-sim workflows deployment status <workflowId>
+sim workflows runs resume <runId> [options]
 ```
 
 **Arguments**
@@ -705,25 +820,39 @@ sim workflows deployment status <workflowId>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
+| `runId` | Yes | Unique workflow run identifier. |
 
 </CommandTable>
 
-## Update workflow public API access
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--workflow <workflowId>` | Yes | Workflow ID. |
+| `--context <value>` | Yes | Pause context ID returned by run status. |
+| `--input <json\|@file>` | No | Resume input as JSON (JSON, or @path / @- to read a file or stdin). |
+
+</CommandTable>
+
+API request and response schemas: [resumeWorkflow](/api-reference/workflow-runs/resumeWorkflowRunV2).
+
+### Cancel a running workflow run
+
+Canceling a paused run prevents resuming that run. Starting a new run can repeat side effects already performed.
 
 ```bash
-sim workflows deployment update <workflowId> [options]
+sim workflows runs cancel <runId> [options]
 ```
 
-Update Workflow Public API Access (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
+| `runId` | Yes | Unique workflow run identifier. |
 
 </CommandTable>
 
@@ -733,14 +862,20 @@ Update Workflow Public API Access (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--is-public-api <true\|false>` | Yes | Whether the deployed workflow should accept unauthenticated public API execution. Accepted values: `true`, `false`. |
+| `--workflow <workflowId>` | Yes | Workflow ID. |
 
 </CommandTable>
 
-## Get workflow state
+API request and response schemas: [cancelWorkflowRun](/api-reference/workflow-runs/cancelRunV2).
+
+## Chat deployments
+
+### Show a workflow’s chat deployment
+
+OAuth login or personal API key required.
 
 ```bash
-sim workflows state get <workflowId>
+sim workflows chat status <workflowId>
 ```
 
 **Arguments**
@@ -753,14 +888,20 @@ sim workflows state get <workflowId>
 
 </CommandTable>
 
-## Replace workflow state
+API request and response schemas: [getWorkflowChatDeployment](/api-reference/workflows/getWorkflowChatDeployment).
+
+### Deploy or replace a workflow chat [#publish-or-replace-a-workflows-chat-deployment]
+
+OAuth login or personal API key required.
+
+This replaces visitor access settings for the chat deployment. Omitted authentication fields reset to defaults, including the password and allowed-email list; avatar and welcome-message behavior follows their option descriptions.
+
+Omitting `--auth-type` selects public access: anyone holding the URL can chat. Supply the complete password or allow-list settings again when replacing a restricted deployment.
 
 ```bash
-sim workflows state replace <workflowId> [options]
+sim workflows chat publish <workflowId> [options]
 ```
 
-Replace Workflow State (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
@@ -777,84 +918,91 @@ Replace Workflow State (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--dry-run` | No | Validate and lint without writing, auditing, or notifying collaborators. Returns the same validation, preparation warnings, lint findings, and ID-ownership conflicts (`409`) as a committed write. `needsRedeployment` describes the pre-write state. For semantic operations, `mintedBlockIds` is empty; `previewBlockIds` contains provisional IDs with a warning, since committing mints new IDs. |
-| `--no-dry-run` | No | Send --dry-run as false. |
-| `--blocks <json\|@file>` | Yes | Blocks keyed by block id. (JSON, or @path / @- to read a file or stdin). |
-| `--edges <json\|@file>` | Yes | Directed connections between blocks. (JSON, or @path / @- to read a file or stdin). |
-| `--loops <json\|@file>` | No | Ignored on write: loop containers are recomputed from `blocks`. (JSON, or @path / @- to read a file or stdin). |
-| `--parallels <json\|@file>` | No | Ignored on write: parallel containers are recomputed from `blocks`. (JSON, or @path / @- to read a file or stdin). |
-| `--variables <json\|@file>` | No | Replacement variable set. Omit to leave the stored variables untouched. (JSON, or @path / @- to read a file or stdin). |
-| `-y, --yes` | No | Confirm this operation (required unless --dry-run). |
+| `--identifier <value>` | Yes | URL slug the deployed chat answers on. Must be free across live deployments. |
+| `--title <value>` | Yes | Title shown to visitors. |
+| `--description <value>` | No | Description shown to visitors. Omitted clears it. |
+| `--customizations <json\|@file>` | No | Presentation overrides. Omitted `primaryColor` and `welcomeMessage` use platform defaults; an omitted or empty `imageUrl` keeps the existing avatar. An empty `welcomeMessage` keeps the existing message. (JSON, or @path / @- to read a file or stdin). |
+| `--auth-type <value>` | No | How visitors are gated. `public` leaves the chat open to anyone holding the URL. Defaults to "public". Accepted values: `public`, `password`, `email`, `sso`. |
+| `--password <value>` | Conditional | Write-only password of 15 to 1024 characters, not only whitespace. Required whenever `authType` is `password`, and rejected otherwise. Never readable back. Taken literally, except that a request from the Sim agent resolves a whole-value `{{ENV_VAR}}` reference to that variable before the rules apply. |
+| `--allowed-emails <json\|@file>` | No | Email addresses or domains admitted under `email` and `sso` gating. At least one is required for those modes. (JSON, or @path / @- to read a file or stdin). |
+| `--output-configs <json\|@file>` | No | Block outputs to surface to visitors. Omitted surfaces none. (JSON, or @path / @- to read a file or stdin). |
+| `--include-thinking` | No | Allow visitors to receive provider thinking events. Defaults to false. |
+| `--no-include-thinking` | No | Send --include-thinking as false. |
+| `--include-tool-calls` | No | Allow visitors to receive tool lifecycle events. Defaults to false. |
+| `--no-include-tool-calls` | No | Send --include-tool-calls as false. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Import workflow
+API request and response schemas: [replaceWorkflowChatDeployment](/api-reference/workflows/replaceWorkflowChatDeployment).
+
+### Take a workflow’s chat deployment offline
+
+OAuth login or personal API key required.
+
+This takes the chat offline and frees its identifier. The workflow itself stays deployed and executable.
 
 ```bash
-sim workflows import [options]
+sim workflows chat unpublish <workflowId> [options]
 ```
 
-**Options**
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--workflow <json\|@file>` | Yes | Workflow export object, bare workflow state, or JSON string containing either form. (JSON, or @path / @- to read a file or stdin). |
-| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
-| `--name <value>` | No | Override for the imported workflow name. |
-| `--description <value>` | No | Override for the imported workflow description. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
-| `--bindings <json\|@file>` | No | Resolved and unresolved source occurrences with their destination selections. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
-| `--request-id <value>` | No | Stable client request ID for reconciliation and identical retries. |
-| `--preview-fingerprint <value>` | No | Fingerprint of the reviewed preview and its choices. |
-| `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
-| `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
+| `workflowId` | Yes | Unique workflow identifier. |
 
 </CommandTable>
 
-## List workflows
-
-```bash
-sim workflows list [options]
-```
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--scope <value>` | No | Which lifecycle set to list: `active` (default) for live workflows, `archived` for workflows a `DELETE` archived. The folder filter resolves against active folders only, so pairing it with `archived` returns an empty page when the containing folder was archived too. Accepted values: `active`, `archived`. |
-| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
-| `--deployed-only` | No | Return only workflows with an active deployment when true. |
-| `--no-deployed-only` | No | Send --deployed-only as false. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
-| `--search <value>` | No | Case-insensitive substring match against the resource name. |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `position`, `name`, `createdAt`, `updatedAt`, `runCount`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Move workflows
+API request and response schemas: [deleteWorkflowChatDeployment](/api-reference/workflows/deleteWorkflowChatDeployment).
+
+## Export and import
+
+### Print a workflow as a portable JSON document
+
+The export clears credentials, passwords, and table sub-block values, but it is not a general secret scanner. Inspect literal variables and inline configuration before sharing the document.
 
 ```bash
-sim workflows move [options]
+sim workflows export <workflowId> [options]
 ```
 
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `workflowId` | Yes | Unique workflow identifier. |
+
+</CommandTable>
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--workflow <value...>` | Yes | Workflows to move. Duplicates are collapsed. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--to <value>` | Yes | Destination folder path; / moves the workflows to the workspace root. |
+| `--include-references` | No | Include non-secret resource identities for mapped import. |
+| `--include-workspace-bindings` | No | Keep non-secret table, knowledge base, document, folder, channel, and other workspace bindings for a same-workspace import. Defaults to false, which clears these IDs. Registered credential fields and opaque table/tool values are cleared either way; environment references and ordinary workflow variables remain included. |
+| `--no-include-workspace-bindings` | No | Send --include-workspace-bindings as false. |
 
 </CommandTable>
 
-## Preview workflow import
+API request and response schemas: [exportWorkflow](/api-reference/workflows/exportWorkflow).
+
+### Preview workflow import
 
 ```bash
 sim workflows import-preview [options]
@@ -870,44 +1018,57 @@ sim workflows import-preview [options]
 | `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
 | `--name <value>` | No | Override for the imported workflow name. |
 | `--description <value>` | No | Override for the imported workflow description. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
+| `--mappings <json\|@file>` | No | Mapping entries addressed by resource kind and source identifier. (JSON, or @path / @- to read a file or stdin). |
 | `--bindings <json\|@file>` | No | Resolved and unresolved source occurrences with their destination selections. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
+| `--dependent-values <json\|@file>` | No | Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Restore an archived workflow
+API request and response schemas: [previewWorkflowImport](/api-reference/workspace-sync/previewWorkflowImport).
+
+### Import workflow
 
 ```bash
-sim workflows restore <workflowId>
+sim workflows import [options]
 ```
 
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
+| `--workflow <json\|@file>` | Yes | Workflow export object, bare workflow state, or JSON string containing either form. (JSON, or @path / @- to read a file or stdin). |
+| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
+| `--name <value>` | No | Override for the imported workflow name. |
+| `--description <value>` | No | Override for the imported workflow description. |
+| `--mappings <json\|@file>` | No | Mapping entries addressed by resource kind and source identifier. (JSON, or @path / @- to read a file or stdin). |
+| `--bindings <json\|@file>` | No | Resolved and unresolved source occurrences with their destination selections. (JSON, or @path / @- to read a file or stdin). |
+| `--dependent-values <json\|@file>` | No | Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated. (JSON, or @path / @- to read a file or stdin). |
+| `--request-id <value>` | No | Stable client request ID for mapped import. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can create another workflow. |
+| `--preview-fingerprint <value>` | No | Fingerprint returned by an import preview with the same choices. A changed plan returns 409; preview again. Do not invent this value. |
+| `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
+| `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
 
 </CommandTable>
 
-## Revert workflow to version
+API request and response schemas: [importWorkflow](/api-reference/workflows/importWorkflow).
+
+## Folders
+
+### List workflow resources and child folders together
 
 ```bash
-sim workflows revert create <workflowId> <version> [options]
+sim workflows ls [path] [options]
 ```
 
-Revert Workflow To Version (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
-| `version` | Yes | Numeric deployment version, or `active` for the currently live version. |
+| `path` | No | Folder path to list; defaults to the root folder |
 
 </CommandTable>
 
@@ -917,27 +1078,20 @@ Revert Workflow To Version (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--search <text>` | No | Filter folders and resources by name. |
+| `--limit <n>` | No | Maximum combined items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Rollback workflow
+API request and response schemas: [listWorkflows](/api-reference/workflows/listWorkflows), [listWorkflowFolders](/api-reference/workflows/listWorkflowsFolders).
+
+### List workflow folders
 
 ```bash
-sim workflows rollback <workflowId> [options]
+sim workflows folders list [options]
 ```
 
-Rollback Workflow (OAuth login or personal API key required)
-
-**Arguments**
-
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
-
-</CommandTable>
+Also available as `sim workflows folders ls`.
 
 **Options**
 
@@ -945,43 +1099,39 @@ Rollback Workflow (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--to-version <value>` | No | Deployment version to reactivate. Omit to select the previous active version. |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--parent <value>` | No | Direct parent folder path. |
+| `--search <value>` | No | Case-insensitive substring match against the folder name. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "name". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
 
 </CommandTable>
 
-## Take a workflow out of deployment
+API request and response schemas: [listWorkflowFolders](/api-reference/workflows/listWorkflowsFolders).
+
+### Create a workflow folder at a path
 
 ```bash
-sim workflows undeploy <workflowId> [options]
+sim workflows folders create <path>
 ```
 
-Take a workflow out of deployment (OAuth login or personal API key required)
-
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-**Options**
+API request and response schemas: [createWorkflowFolder](/api-reference/workflows/createWorkflowsFolder).
 
-<CommandTable>
+### Delete workflow folder
 
-| Option | Required | Description |
-| --- | --- | --- |
-| `-y, --yes` | Yes | Confirm this operation. |
-
-</CommandTable>
-
-## Update workflow
+This archives the workflow folder and, when recursive, everything inside it.
 
 ```bash
-sim workflows update <workflowId> [options]
+sim workflows folders delete <path> [options]
 ```
 
 **Arguments**
@@ -990,7 +1140,7 @@ sim workflows update <workflowId> [options]
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
@@ -1000,57 +1150,35 @@ sim workflows update <workflowId> [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | Replacement workflow name. |
-| `--description <value>` | No | Replacement workflow description; null clears it. (--description null sends the word, not JSON null). |
-| `--folder <value>` | No | Folder path as shown in the app; the leading / is optional. |
+| `--recursive` | No | Archive the folder and its descendants. Defaults to "false". |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Move a workflow to a folder
-
-```bash
-sim workflows mv <workflowId> <folder>
-```
-
-**Arguments**
+API request and response schemas: [deleteWorkflowFolder](/api-reference/workflows/deleteWorkflowsFolder).
 
-<CommandTable>
-
-| Argument | Required | Description |
-| --- | --- | --- |
-| `workflowId` | Yes | Unique workflow identifier. |
-| `folder` | Yes | Folder path as shown in the app; the leading / is optional |
-
-</CommandTable>
-
-## List workflow resources and child folders together
+### Rename or move a workflow folder
 
 ```bash
-sim workflows ls [path] [options]
+sim workflows folders move <path> <destination>
 ```
 
+Also available as `sim workflows folders mv`.
+
 **Arguments**
 
 <CommandTable>
 
 | Argument | Required | Description |
 | --- | --- | --- |
-| `path` | No | Folder path to list; defaults to the root folder |
+| `path` | Yes | Folder path as shown in the app; the leading / is optional |
+| `destination` | Yes | Folder path as shown in the app; the leading / is optional |
 
 </CommandTable>
 
-**Options**
-
-<CommandTable>
-
-| Option | Required | Description |
-| --- | --- | --- |
-| `--search <text>` | No | Filter folders and resources by name. |
-| `--limit <n>` | No | Maximum combined items to return (0 for everything). Defaults to `0`. |
+API request and response schemas: [relocateWorkflowFolder](/api-reference/workflows/relocateWorkflowsFolder).
 
-</CommandTable>
-
-## Create a workflow directory at a path
+### Create a workflow directory at a path
 
 ```bash
 sim workflows mkdir <path>
@@ -1065,3 +1193,11 @@ sim workflows mkdir <path>
 | `path` | Yes | Folder path to create; the leading / is optional |
 
 </CommandTable>
+
+API request and response schemas: [createWorkflowFolder](/api-reference/workflows/createWorkflowsFolder).
+
+## Related docs
+
+- [Workflow builder](/workflows)
+- [Import and workspace sync](/cli/workflow-sync)
+- [Scripting and exit codes](/cli/scripting#exit-codes)
diff --git a/apps/docs/content/docs/cli/workspaces.mdx b/apps/docs/content/docs/cli/workspaces.mdx
index 3125fe12195..826b0d42133 100644
--- a/apps/docs/content/docs/cli/workspaces.mdx
+++ b/apps/docs/content/docs/cli/workspaces.mdx
@@ -1,39 +1,51 @@
 ---
 title: Workspaces
-description: Manage workspaces — every subcommand, argument, and flag
+description: Read workspace access and manage reviewed fork, push, and pull operations.
 ---
 
 import { CommandTable } from '@/components/ui/command-table'
 
+Read workspace access and manage reviewed fork, push, and pull operations.
+
 `sim workspaces` is also spelled `sim workspace`.
 
-Every command below also accepts the [global options](/cli/commands#global-options).
+These commands accept the [global options](/cli/commands#global-options).
+
+## Workspace access
 
-## Cancel workspace access request
+### List workspaces
 
 ```bash
-sim workspaces access-requests cancel <requestId>
+sim workspaces list [options]
 ```
 
-Cancel Workspace Access Request (OAuth login or personal API key required)
-
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `requestId` | Yes | Access request identifier. |
+| `--sort-by <value>` | No | Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`. Defaults to "createdAt". Accepted values: `name`, `createdAt`, `updatedAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Create workspace access request
+API request and response schemas: [listWorkspaces](/api-reference/workspaces/listWorkspaces).
+
+### Get workspace
 
 ```bash
-sim workspaces access-requests create [options]
+sim workspaces get
 ```
 
-Create Workspace Access Request (OAuth login or personal API key required)
+API request and response schemas: [getWorkspace](/api-reference/workspaces/getWorkspace).
+
+### List workspace members
+
+```bash
+sim workspaces members [options]
+```
 
 **Options**
 
@@ -41,185 +53,155 @@ Create Workspace Access Request (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--target <json\|@file>` | Yes | Target returned by Discover Workspace Access Requests or Discover Organization Access Requests. The target must currently be requestable. (JSON, or @path / @- to read a file or stdin). |
-| `--reason <value>` | No | Why the acting user needs this access. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
 
 </CommandTable>
 
-## Discover workspace access requests
+API request and response schemas: [listWorkspaceMembers](/api-reference/workspaces/listWorkspaceMembers).
+
+### Create workspace invitations
+
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces access-requests discover [options]
+sim workspaces invitations create [options]
 ```
 
-Discover Workspace Access Requests (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--search <value>` | No | Case-insensitive substring match against the access item label. |
-| `--target-kind <value>` | No | Category of access to discover. Accepted values: `feature`, `integration`, `provider`, `model`, `tool`, `knowledge_connector`, `file_share_auth`, `chat_deploy_auth`, `usage_limit`. |
-| `--state <value>` | No | Filter by the acting user’s current access. Requestable items can be submitted for review. Accepted values: `allowed`, `requestable`, `unavailable`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `label`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--emails <value...>` | Yes | Email addresses to invite. Each address is processed separately; inspect failed for unsuccessful recipients. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--permission <value>` | No | Workspace permission to grant. Existing workspace access is preserved. Defaults to "read". Accepted values: `admin`, `write`, `read`. |
+| `--membership <value>` | No | Organization membership: member or admin uses a seat when billing is enabled. External grants workspace access only and requires an eligible paid account when billing is enabled. Existing members of another organization remain external. Defaults to "member". Accepted values: `member`, `admin`, `external`. |
 
 </CommandTable>
 
-## List my workspace access requests
+API request and response schemas: [createWorkspaceInvitations](/api-reference/workspaces/createWorkspaceInvitations).
 
-```bash
-sim workspaces access-requests mine [options]
-```
+### Get workspace permission config
 
-List My Workspace Access Requests (OAuth login or personal API key required)
+OAuth login or personal API key required.
 
-**Options**
+```bash
+sim workspaces permission-config
+```
 
-<CommandTable>
+API request and response schemas: [getWorkspacePermissionConfig](/api-reference/workspaces/getWorkspacePermissionConfig).
 
-| Option | Required | Description |
-| --- | --- | --- |
-| `--status <value>` | No | Filter by request status; omit to include all statuses. Accepted values: `pending`, `fulfilled`, `declined`, `cancelled`, `closed`. |
-| `--sort-by <value>` | No | Field used to sort the result. Accepted values: `createdAt`, `targetLabel`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
-| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+## Access requests
 
-</CommandTable>
+### Discover workspace access requests
 
-## Create workspace invitations
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces invitations create [options]
+sim workspaces access-requests discover [options]
 ```
 
-Create Workspace Invitations (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--emails <value...>` | Yes | Email addresses to invite. Each address is processed separately; inspect failed for unsuccessful recipients. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--permission <value>` | No | Workspace permission to grant. Existing workspace access is preserved. Accepted values: `admin`, `write`, `read`. |
-| `--membership <value>` | No | Organization membership: member or admin uses a seat when billing is enabled. External grants workspace access only and requires an eligible paid account when billing is enabled. Existing members of another organization remain external. Accepted values: `member`, `admin`, `external`. |
+| `--search <value>` | No | Case-insensitive substring match against the access item label. |
+| `--target-kind <value>` | No | Category of access to discover. Accepted values: `feature`, `integration`, `provider`, `model`, `tool`, `knowledge_connector`, `file_share_auth`, `chat_deploy_auth`, `usage_limit`. |
+| `--state <value>` | No | Filter by the acting user’s current access. Requestable items can be submitted for review. Accepted values: `allowed`, `requestable`, `unavailable`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "label". Accepted values: `label`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`, `desc`. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
 
 </CommandTable>
 
-## Fork workspace
+API request and response schemas: [discoverWorkspaceAccessRequests](/api-reference/access-requests/discoverWorkspaceAccessRequests).
+
+### Create workspace access request
+
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces fork [options]
+sim workspaces access-requests create [options]
 ```
 
-Fork Workspace (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | Display name of the workflow or workspace. |
-| `--copy <json\|@file>` | No | Explicit resource selections to copy into the new fork; omitted resource kinds are not copied. (JSON, or @path / @- to read a file or stdin). |
-| `--request-id <value>` | Yes | Stable client request ID for reconciliation and identical retries. |
-| `--preview-fingerprint <value>` | Yes | Fingerprint of the reviewed preview and its choices. |
-| `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
-| `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
+| `--target <json\|@file>` | Yes | Target returned by Discover Workspace Access Requests or Discover Organization Access Requests. The target must currently be requestable. (JSON, or @path / @- to read a file or stdin). |
+| `--reason <value>` | No | Why the acting user needs this access. Defaults to "". |
 
 </CommandTable>
 
-## Get workspace
+API request and response schemas: [createWorkspaceAccessRequest](/api-reference/access-requests/createWorkspaceAccessRequest).
 
-```bash
-sim workspaces get
-```
+### List my workspace access requests
 
-## Get workspace fork availability
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces fork-availability
-```
-
-Get Workspace Fork Availability (OAuth login or personal API key required)
-
-## Get workspace fork lineage
-
-```bash
-sim workspaces lineage
-```
-
-Get Workspace Fork Lineage (OAuth login or personal API key required)
-
-## Get workspace fork mappings
-
-```bash
-sim workspaces mappings get [options]
+sim workspaces access-requests mine [options]
 ```
 
-Get Workspace Fork Mappings (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
-| `--direction <value>` | Yes | Push means current to other; pull means other to current, independent of parent/child orientation. Accepted values: `push`, `pull`. |
+| `--status <value>` | No | Filter by request status; omit to include all statuses. Accepted values: `pending`, `fulfilled`, `declined`, `cancelled`, `closed`. |
+| `--sort-by <value>` | No | Field used to sort the result. Defaults to "createdAt". Accepted values: `createdAt`, `targetLabel`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `asc`, `desc`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--sort-by <value>` | No | Supported stable sort key for this collection. Accepted values: `id`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`. |
 
 </CommandTable>
 
-## Update workspace fork mappings
+API request and response schemas: [listMyWorkspaceAccessRequests](/api-reference/access-requests/listMyWorkspaceAccessRequests).
+
+### Cancel workspace access request
+
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces mappings update [options]
+sim workspaces access-requests cancel <requestId>
 ```
 
-Update Workspace Fork Mappings (OAuth login or personal API key required)
-
-**Options**
+**Arguments**
 
 <CommandTable>
 
-| Option | Required | Description |
+| Argument | Required | Description |
 | --- | --- | --- |
-| `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
-| `--direction <value>` | Yes | Push means current to other; pull means other to current, independent of parent/child orientation. Accepted values: `push`, `pull`. |
-| `--mappings <json\|@file>` | Yes | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
+| `requestId` | Yes | Access request identifier. |
 
 </CommandTable>
 
-## Get workspace operation
+API request and response schemas: [cancelWorkspaceAccessRequest](/api-reference/access-requests/cancelWorkspaceAccessRequest).
 
-```bash
-sim workspaces operations get <operationId>
-```
+## Forks and lineage
 
-**Arguments**
+### Get workspace fork availability
 
-<CommandTable>
+OAuth login or personal API key required.
 
-| Argument | Required | Description |
-| --- | --- | --- |
-| `operationId` | Yes | Durable operation identifier to use for polling. |
+```bash
+sim workspaces fork-availability
+```
 
-</CommandTable>
+API request and response schemas: [getWorkspaceForkAvailability](/api-reference/workspace-sync/getWorkspaceForkAvailability).
 
-## List workspace operations
+### List workspace fork resources
+
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces operations list [options]
+sim workspaces fork-resources [options]
 ```
 
 **Options**
@@ -230,52 +212,78 @@ sim workspaces operations list [options]
 | --- | --- | --- |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--request-id <value>` | No | Stable client request ID for reconciliation and identical retries. |
+| `--kind <value>` | Yes | Kind of source resource to list for copy selection. Accepted values: `files`, `tables`, `knowledgeBases`, `customTools`, `skills`, `mcpServers`, `workflowMcpServers`. |
+| `--sort-by <value>` | No | Supported stable sort key for this collection. Defaults to "id". Accepted values: `id`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`. |
 
 </CommandTable>
 
-## Wait for copy and deployment readiness; exit 3 for configuration, 1 for failure, or 4 for timeout
+API request and response schemas: [listWorkspaceForkResources](/api-reference/workspace-sync/listWorkspaceForkResources).
+
+### Preview workspace fork
+
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces operations wait <operationId> [options]
+sim workspaces fork-preview [options]
 ```
 
-**Arguments**
+**Options**
 
 <CommandTable>
 
-| Argument | Required | Description |
+| Option | Required | Description |
 | --- | --- | --- |
-| `operationId` | Yes | Operation ID returned by import, fork, push, or pull |
+| `--name <value>` | No | Display name of the workflow or workspace. |
+| `--copy <json\|@file>` | No | Explicit resource selections to copy into the new fork; omitted resource kinds are not copied. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
+API request and response schemas: [previewWorkspaceFork](/api-reference/workspace-sync/previewWorkspaceFork).
+
+### Fork workspace
+
+OAuth login or personal API key required.
+
+```bash
+sim workspaces fork [options]
+```
+
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--wait-timeout <seconds>` | No | Maximum total wait (default 3600; 0 waits indefinitely). |
+| `--name <value>` | No | Display name of the workflow or workspace. |
+| `--copy <json\|@file>` | No | Explicit resource selections to copy into the new fork; omitted resource kinds are not copied. (JSON, or @path / @- to read a file or stdin). |
+| `--request-id <value>` | Yes | Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation. |
+| `--preview-fingerprint <value>` | Yes | Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value. |
+| `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
+| `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
 
 </CommandTable>
 
-## Get workspace permission config
+API request and response schemas: [forkWorkspace](/api-reference/workspace-sync/forkWorkspace).
+
+### Get workspace fork lineage
+
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces permission-config
+sim workspaces lineage
 ```
 
-Get Workspace Permission Config (OAuth login or personal API key required)
+API request and response schemas: [getWorkspaceForkLineage](/api-reference/workspace-sync/getWorkspaceForkLineage).
 
-## List workspace fork children
+### List workspace fork children
+
+OAuth login or personal API key required.
 
 ```bash
 sim workspaces children [options]
 ```
 
-List Workspace Fork Children (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -284,37 +292,46 @@ List Workspace Fork Children (OAuth login or personal API key required)
 | --- | --- | --- |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--sort-by <value>` | No | Supported stable sort key for this collection. Accepted values: `createdAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `desc`. |
+| `--sort-by <value>` | No | Supported stable sort key for this collection. Defaults to "createdAt". Accepted values: `createdAt`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "desc". Accepted values: `desc`. |
 
 </CommandTable>
 
-## List workspace fork resources
+API request and response schemas: [listWorkspaceForkChildren](/api-reference/workspace-sync/listWorkspaceForkChildren).
+
+## Mappings
+
+### Get workspace fork mappings
+
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces fork-resources [options]
+sim workspaces mappings get [options]
 ```
 
-List Workspace Fork Resources (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
+| `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
+| `--direction <value>` | Yes | Push means current to other; pull means other to current, independent of parent/child orientation. Accepted values: `push`, `pull`. |
 | `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
 | `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
-| `--kind <value>` | Yes | Resource or operation kind. Accepted values: `files`, `tables`, `knowledgeBases`, `customTools`, `skills`, `mcpServers`, `workflowMcpServers`. |
-| `--sort-by <value>` | No | Supported stable sort key for this collection. Accepted values: `id`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`. |
+| `--sort-by <value>` | No | Supported stable sort key for this collection. Defaults to "id". Accepted values: `id`. |
+| `--sort-order <value>` | No | Sort direction. Defaults to "asc". Accepted values: `asc`. |
 
 </CommandTable>
 
-## List workspace members
+API request and response schemas: [getWorkspaceForkMappings](/api-reference/workspace-sync/getWorkspaceForkMappings).
+
+### Update workspace fork mappings
+
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces members [options]
+sim workspaces mappings update [options]
 ```
 
 **Options**
@@ -323,14 +340,22 @@ sim workspaces members [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
+| `--direction <value>` | Yes | Push means current to other; pull means other to current, independent of parent/child orientation. Accepted values: `push`, `pull`. |
+| `--mappings <json\|@file>` | Yes | Mapping entries addressed by resource type and `sourceId`. `targetId: null` clears a mapping. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## List workspaces
+API request and response schemas: [updateWorkspaceForkMappings](/api-reference/workspace-sync/updateWorkspaceForkMappings).
+
+## Push and pull
+
+### Preview workspace push
+
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces list [options]
+sim workspaces push-preview [options]
 ```
 
 **Options**
@@ -339,39 +364,57 @@ sim workspaces list [options]
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
-| `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
-| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `0`. |
+| `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
+| `--mappings <json\|@file>` | No | Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync. (JSON, or @path / @- to read a file or stdin). |
+| `--dependent-values <json\|@file>` | No | Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them. (JSON, or @path / @- to read a file or stdin). |
+| `--copy-resources <json\|@file>` | No | Explicit source resources to copy before syncing the workflows. (JSON, or @path / @- to read a file or stdin). |
+| `--drop-references <json\|@file>` | No | Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped. (JSON, or @path / @- to read a file or stdin). |
+| `--trigger-mappings <json\|@file>` | No | Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Preview workspace fork
+API request and response schemas: [previewWorkspacePush](/api-reference/workspace-sync/previewWorkspacePush).
+
+### Push workspace
+
+OAuth login or personal API key required.
+
+This replaces target workflows and may archive targets whose sources were deleted.
 
 ```bash
-sim workspaces fork-preview [options]
+sim workspaces push [options]
 ```
 
-Preview Workspace Fork (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--name <value>` | No | Display name of the workflow or workspace. |
-| `--copy <json\|@file>` | No | Explicit resource selections to copy into the new fork; omitted resource kinds are not copied. (JSON, or @path / @- to read a file or stdin). |
+| `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
+| `--mappings <json\|@file>` | No | Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync. (JSON, or @path / @- to read a file or stdin). |
+| `--dependent-values <json\|@file>` | No | Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them. (JSON, or @path / @- to read a file or stdin). |
+| `--copy-resources <json\|@file>` | No | Explicit source resources to copy before syncing the workflows. (JSON, or @path / @- to read a file or stdin). |
+| `--drop-references <json\|@file>` | No | Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped. (JSON, or @path / @- to read a file or stdin). |
+| `--trigger-mappings <json\|@file>` | No | Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected. (JSON, or @path / @- to read a file or stdin). |
+| `--request-id <value>` | Yes | Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation. |
+| `--preview-fingerprint <value>` | Yes | Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value. |
+| `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
+| `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Preview workspace pull
+API request and response schemas: [pushWorkspace](/api-reference/workspace-sync/pushWorkspace).
+
+### Preview workspace pull
+
+OAuth login or personal API key required.
 
 ```bash
 sim workspaces pull-preview [options]
 ```
 
-Preview Workspace Pull (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -379,22 +422,26 @@ Preview Workspace Pull (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
+| `--mappings <json\|@file>` | No | Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync. (JSON, or @path / @- to read a file or stdin). |
+| `--dependent-values <json\|@file>` | No | Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them. (JSON, or @path / @- to read a file or stdin). |
 | `--copy-resources <json\|@file>` | No | Explicit source resources to copy before syncing the workflows. (JSON, or @path / @- to read a file or stdin). |
 | `--drop-references <json\|@file>` | No | Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped. (JSON, or @path / @- to read a file or stdin). |
 | `--trigger-mappings <json\|@file>` | No | Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected. (JSON, or @path / @- to read a file or stdin). |
 
 </CommandTable>
 
-## Preview workspace push
+API request and response schemas: [previewWorkspacePull](/api-reference/workspace-sync/previewWorkspacePull).
+
+### Pull workspace
+
+OAuth login or personal API key required.
+
+This replaces target workflows and may archive targets whose sources were deleted.
 
 ```bash
-sim workspaces push-preview [options]
+sim workspaces pull [options]
 ```
 
-Preview Workspace Push (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -402,49 +449,76 @@ Preview Workspace Push (OAuth login or personal API key required)
 | Option | Required | Description |
 | --- | --- | --- |
 | `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
+| `--mappings <json\|@file>` | No | Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync. (JSON, or @path / @- to read a file or stdin). |
+| `--dependent-values <json\|@file>` | No | Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them. (JSON, or @path / @- to read a file or stdin). |
 | `--copy-resources <json\|@file>` | No | Explicit source resources to copy before syncing the workflows. (JSON, or @path / @- to read a file or stdin). |
 | `--drop-references <json\|@file>` | No | Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped. (JSON, or @path / @- to read a file or stdin). |
 | `--trigger-mappings <json\|@file>` | No | Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected. (JSON, or @path / @- to read a file or stdin). |
+| `--request-id <value>` | Yes | Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation. |
+| `--preview-fingerprint <value>` | Yes | Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value. |
+| `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
+| `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
 
-## Pull workspace
+API request and response schemas: [pullWorkspace](/api-reference/workspace-sync/pullWorkspace).
+
+## Operation status
+
+### List workspace operations
 
 ```bash
-sim workspaces pull [options]
+sim workspaces operations list [options]
 ```
 
-Pull Workspace (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
-| `--copy-resources <json\|@file>` | No | Explicit source resources to copy before syncing the workflows. (JSON, or @path / @- to read a file or stdin). |
-| `--drop-references <json\|@file>` | No | Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped. (JSON, or @path / @- to read a file or stdin). |
-| `--trigger-mappings <json\|@file>` | No | Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected. (JSON, or @path / @- to read a file or stdin). |
-| `--request-id <value>` | Yes | Stable client request ID for reconciliation and identical retries. |
-| `--preview-fingerprint <value>` | Yes | Fingerprint of the reviewed preview and its choices. |
-| `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
-| `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--limit <n>` | No | Maximum items to return (0 for everything). Defaults to `100`. |
+| `--cursor <value>` | No | Continue from nextCursor returned by a previous result. |
+| `--request-id <value>` | No | Find an uncertain mutation by the original client request ID; keep the same filter while paging. |
 
 </CommandTable>
 
-## Push workspace
+API request and response schemas: [listWorkspaceOperations](/api-reference/workspace-sync/listWorkspaceOperations).
+
+### Get workspace operation
 
 ```bash
-sim workspaces push [options]
+sim workspaces operations get <operationId>
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `operationId` | Yes | Durable operation identifier to use for polling. |
+
+</CommandTable>
+
+API request and response schemas: [getWorkspaceOperation](/api-reference/workspace-sync/getWorkspaceOperation).
+
+### Wait for workspace copy and deployment readiness [#wait-for-copy-and-deployment-readiness-exit-3-for-configuration-1-for-failure-or-4-for-timeout]
+
+```bash
+sim workspaces operations wait <operationId> [options]
 ```
 
-Push Workspace (OAuth login or personal API key required)
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `operationId` | Yes | Operation ID returned by import, fork, push, or pull |
+
+</CommandTable>
 
 **Options**
 
@@ -452,47 +526,47 @@ Push Workspace (OAuth login or personal API key required)
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
-| `--mappings <json\|@file>` | No | Mappings keyed by resource type and source identifier. (JSON, or @path / @- to read a file or stdin). |
-| `--dependent-values <json\|@file>` | No | Destination-dependent choices keyed by source workflow, block, and field identities. (JSON, or @path / @- to read a file or stdin). |
-| `--copy-resources <json\|@file>` | No | Explicit source resources to copy before syncing the workflows. (JSON, or @path / @- to read a file or stdin). |
-| `--drop-references <json\|@file>` | No | Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped. (JSON, or @path / @- to read a file or stdin). |
-| `--trigger-mappings <json\|@file>` | No | Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected. (JSON, or @path / @- to read a file or stdin). |
-| `--request-id <value>` | Yes | Stable client request ID for reconciliation and identical retries. |
-| `--preview-fingerprint <value>` | Yes | Fingerprint of the reviewed preview and its choices. |
-| `--wait` | No | Wait for the committed operation to finish; missing configuration and failure exit nonzero. |
-| `--wait-timeout <seconds>` | No | Maximum operation wait in seconds (default 3600; 0 waits indefinitely). |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--wait-timeout <seconds>` | No | Maximum total wait (default 3600; 0 waits indefinitely). |
 
 </CommandTable>
 
-## Rollback workspace fork
+Exit codes: 0 completed (including completion with warnings), 1 follow-up work failed, 3 destination configuration is required, 4 timed out. The mutation may already be committed; reconcile using the same operation or request ID rather than repeating it with a new ID.
+
+API request and response schemas: [getWorkspaceOperation](/api-reference/workspace-sync/getWorkspaceOperation).
+
+## Exclusions and recovery
+
+### Update workspace fork exclusions
+
+OAuth login or personal API key required.
 
 ```bash
-sim workspaces fork-rollback [options]
+sim workspaces sync-exclusions [options]
 ```
 
-Rollback Workspace Fork (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
-| `-y, --yes` | Yes | Confirm this operation. |
+| `--workflow <value...>` | Yes | Workflow identifiers in the current workspace. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--fork-sync-excluded <true\|false>` | Yes | Whether the named workflows should be skipped as sync sources and targets. Accepted values: `true`, `false`. |
 
 </CommandTable>
 
-## Unlink workspace fork
+API request and response schemas: [updateWorkspaceForkExclusions](/api-reference/workspace-sync/updateWorkspaceForkExclusions).
+
+### Rollback workspace fork
+
+OAuth login or personal API key required.
+
+This restores the latest sync using its prior deployed versions.
 
 ```bash
-sim workspaces unlink [options]
+sim workspaces fork-rollback [options]
 ```
 
-Unlink Workspace Fork (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
@@ -504,21 +578,32 @@ Unlink Workspace Fork (OAuth login or personal API key required)
 
 </CommandTable>
 
-## Update workspace fork exclusions
+API request and response schemas: [rollbackWorkspaceFork](/api-reference/workspace-sync/rollbackWorkspaceFork).
+
+### Unlink workspace fork
+
+OAuth login or personal API key required.
+
+This removes the fork relationship and its persisted mappings.
 
 ```bash
-sim workspaces sync-exclusions [options]
+sim workspaces unlink [options]
 ```
 
-Update Workspace Fork Exclusions (OAuth login or personal API key required)
-
 **Options**
 
 <CommandTable>
 
 | Option | Required | Description |
 | --- | --- | --- |
-| `--workflow <value...>` | Yes | Workflow identifiers in the current workspace. (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
-| `--fork-sync-excluded <true\|false>` | Yes | Whether the named workflows should be skipped as sync sources and targets. Accepted values: `true`, `false`. |
+| `--other-workspace-id <value>` | Yes | Workspace on the other side of the direct fork edge. |
+| `-y, --yes` | Yes | Confirm this operation. |
 
 </CommandTable>
+
+API request and response schemas: [unlinkWorkspaceFork](/api-reference/workspace-sync/unlinkWorkspaceFork).
+
+## Related docs
+
+- [Workspace sync](/cli/workflow-sync)
+- [Workspaces](/platform/workspaces)
diff --git a/apps/docs/content/docs/desktop/index.mdx b/apps/docs/content/docs/desktop/index.mdx
index 134bc8574ce..58f48c67fa4 100644
--- a/apps/docs/content/docs/desktop/index.mdx
+++ b/apps/docs/content/docs/desktop/index.mdx
@@ -1,155 +1,187 @@
 ---
 title: Sim Desktop
-description: Install the macOS app — Sim in its own window, with a built-in browser, a terminal, and access to local folders.
+description: Install the macOS app and configure browser, terminal, local file, and available Mac app controls.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Image } from '@/components/ui/image'
 
-Sim Desktop is the macOS app for your Sim workspace. Everything the web app does, it does — plus the things a browser tab cannot: a built-in browser and terminal, read-only access to folders you pick, and native notifications when a task finishes.
+Sim Desktop opens your Sim workspace in a macOS app. It adds a built-in browser, terminal sessions, local file tools, and native notifications. Available builds and deployments can also provide native Mac app control. Your account, workspaces, and workflows are shared with the web app.
 
 <Image
   src="/static/desktop/sim-desktop.png"
-  alt="Sim Desktop — Chat on the left, the built-in browser on the right"
+  alt="Sim Desktop with Chat on the left and a built-in browser tab on the right"
   width={1600}
   height={892}
 />
 
-## Download
+## Download and requirements
 
 **[Download Sim Desktop for macOS](https://www.sim.ai/api/desktop/update/download)**
 
-One universal build runs natively on both Apple Silicon and Intel Macs. It is signed and notarized by Sim, so Gatekeeper accepts it with no override.
+The official build is signed and notarized. One universal installer supports Apple Silicon and Intel Macs running **macOS 12 Monterey or later**. Use the web app on other platforms.
 
-<Callout type="info">
-  That link is never version-pinned — it is a redirect resolved at request time, so it always lands on the newest release. Bookmark it, share it, or put it in an MDM policy; it stays correct.
+The download link redirects to the latest available desktop installer for that deployment. Results can be cached for five minutes. To install a specific version, download `Sim-<version>-universal.dmg` from [GitHub releases](https://github.com/simstudioai/sim/releases).
 
-  It resolves against sim.ai. Every deployment serves the same endpoint on its own origin, so if you self-host use yours — `https://sim.example.com/api/desktop/update/download` — to get the build your deployment offers.
-</Callout>
+You need outbound access to your Sim deployment and GitHub's release downloads. For a self-hosted deployment:
 
-To install a specific version instead of the newest one, pick it from [the releases page](https://github.com/simstudioai/sim/releases) and download that release's `Sim-<version>-universal.dmg`.
+- Use your own download endpoint, such as `https://sim.example.com/api/desktop/update/download`.
+- Allow the Sim server to reach both `api.github.com` and `github.com` for release lookup and manifests. Blocking either can make the download endpoint return `502`.
+- Use a certificate trusted by macOS. The app rejects certificate errors without an override; install a private CA in the system trust store if required.
 
-## Install
+See [Desktop app on your deployment](/platform/self-hosting/desktop) for server URLs, update channels, and network troubleshooting.
 
-<Steps>
+## Install and sign in
 
-<Step>
+<Steps>
+<Step title="Install in Applications">
 
-### Open the disk image and drag Sim to Applications
+Open the disk image and drag Sim to **Applications**. Launch it from there.
 
 <Callout type="warn">
-  Install to `/Applications`. macOS App Translocation runs an app from a randomized read-only path when it is launched from Downloads, which silently breaks auto-updates.
+  Automatic self-update requires a Developer ID build installed in Applications. Builds elsewhere use the manual installer update path.
 </Callout>
 
 </Step>
+<Step title="Choose your server">
 
-<Step>
+Fresh official installs open sim.ai. If you self-host, choose **Sim → Server…** in the menu bar and enter your deployment's origin before signing in.
 
-### Sign in
+</Step>
+<Step title="Sign in">
 
-Launch Sim and sign in as you normally would.
+Sign in with your existing Sim account. Google, Microsoft, and SSO sign-ins finish in your default browser, which hands the session back to the app.
 
-Google, Microsoft, and SSO sign-ins finish in your default browser — those providers refuse to render inside an embedded browser. Sim opens the page, you approve, and the browser hands the session back to the app. The app gets its own session, so signing out of one surface does not sign out the other.
+The app has its own session. Signing out of the app does not sign you out of Sim in your browser, or the reverse.
 
 </Step>
+</Steps>
 
-<Step>
-
-### Point it at your deployment, if you self-host
-
-Fresh installs open sim.ai. To use your own deployment, choose **Sim → Server…** in the menu bar and enter its URL. See [Desktop App on Your Deployment](/platform/self-hosting/desktop) for what changes when you switch.
+## Browser, terminal, and local files
 
-</Step>
+| Capability | Behavior |
+| --- | --- |
+| **Browser** | Open websites in tabs with their own sessions and saved passwords. Chat can use the sites you sign into here. |
+| **Terminal** | Open local shell sessions beside Chat. Chat can run commands in those sessions; tmux and shell integration are supported. |
+| **Local file tools** | Read and search folders you approve, import files, and use authorized files in browser uploads. |
+| **Notifications** | Receive a notification when Chat finishes responding. Clicking it opens that chat. Errors and turns with queued follow-up messages do not produce completion notifications. |
+| **Control Center** | Open recent chats from Sim's menu-bar icon. |
+| **Launch at login** | Optionally open Sim when you sign in to your Mac. The app restores its previous location when launched. |
 
-</Steps>
+Browser and Terminal are enabled by default. Turn them off with **Let Chat browse the web** or **Let Chat run commands** in their Settings sections.
 
-## What the desktop app adds
+### Local file access
 
-- **A built-in browser.** A real browser inside the app, with its own tabs, saved passwords, and sessions. Chat can drive it — sign in once and your agents work on the sites you are already signed into.
-- **A built-in terminal.** Real shell sessions in a panel next to Chat, with tmux and shell integration, that Chat can run commands in.
-- **Local folder access.** When a task needs a folder on your Mac, Chat offers to open the native folder picker. The grant is read-only, scoped to the folder you picked, and revocable.
-- **Notifications.** A native notification when a Chat task finishes. Clicking it opens that chat. Tasks that end in an error, or that have another message queued behind them, do not notify.
-- **Control Center.** A menu-bar icon with your recent chats, so Sim is one click away from any app.
-- **Launch at login.** Sim starts with your Mac, and however you launch it, it opens where you left off.
+By default, local file tools ask for folder access when they need an unapproved path. A selected-folder grant is scoped to that folder, read-only through the filesystem tool interface, and revocable. Use **File → Folder Access…** to manage selected folders.
 
-Both the browser and the terminal are capabilities you grant, not defaults you are stuck with — each has a single switch in settings that turns it off entirely.
+**Settings → Account → Desktop → Full file access** is off by default. Enabling it lets local file tools access files without individual folder approvals.
 
 <Callout type="warn">
-  **What a folder grant does and does not do.** Granting a folder does not copy or upload it, and an agent cannot attach or stage a file from it — that stays your deliberate act. But when an agent reads or searches inside the grant, what it reads is a tool result, and tool results go to your Sim server and to the model like anything else in the conversation. The file stays on your Mac; what an agent reads out of it does not.
+  Granting a folder does not automatically upload its contents. Later reads send returned content to your Sim deployment and model. Chat can also import authorized local files or stage a granted file for upload to a website through the browser.
 </Callout>
 
-## Keyboard shortcuts
+### Native Mac-app control
 
-These are the app's own shortcuts. The [workflow editor and table shortcuts](/keyboard-shortcuts) work the same in the app as in the browser.
+**Computer Use** appears under **Settings → Account → Desktop** only when the deployment and installed app provide it. It requires **macOS 14 or later** and is off by default on each Mac. Browser, Terminal, and local file permissions are separate controls.
 
-| Shortcut | Action |
-|---|---|
-| `Cmd` + `K` | Search |
-| `Cmd` + `B` | Toggle the sidebar |
-| `Cmd` + `N` | New chat |
-| `Cmd` + `Shift` + `N` | New window |
-| `Cmd` + `,` | Settings |
-| `Cmd` + `[` | Back |
-| `Cmd` + `R` | Reload |
-| `Cmd` + `0` / `+` / `-` | Reset, increase, or decrease zoom |
+To enable it when available:
 
-With the built-in browser or terminal focused, the tab shortcuts act on its tabs rather than on the window:
+1. Open **Computer Use** and turn **Allow Mothership to use Mac apps** to **On** to allow Sim to use native apps.
+2. Use **Open System Settings** to grant **Accessibility** for app interaction and **Screen Recording** for screenshots. Grant these permissions yourself, then return to Sim to refresh their status.
+3. When Sim requests an app, choose **Allow for This Task**, **Always Allow**, or **Cancel**. **Always Allow** saves that app's permission on this Mac.
 
-| Shortcut | Action |
-|---|---|
-| `Cmd` + `T` | New tab |
-| `Cmd` + `W` | Close tab |
-| `Cmd` + `Shift` + `T` | Reopen the last closed tab |
-| `Ctrl` + `Tab` / `Ctrl` + `Shift` + `Tab` | Next / previous tab |
-| `Cmd` + `1`–`8` | Jump to that tab |
-| `Cmd` + `9` | Jump to the last tab |
-| `Cmd` + `L` | Focus the address bar (browser only) |
-| `Cmd` + `F` | Find on the page (browser only) |
+Sim can read approved app windows and interact through clicks, text, keyboard shortcuts, scrolling, and supported accessibility controls. Screenshots and returned app content can be sent to your Sim deployment and model. Some actions require bringing the app to the foreground; app compatibility and macOS permissions can still limit what succeeds.
+
+The conversation shows the active app and action. Select **Stop**, or press **Cmd + Shift + Escape** when that shortcut is available, to cancel active and queued computer actions. Stopping cannot undo input already delivered to an app. Verify the app's current state before repeating an interrupted action.
+
+Use **Revoke** under **Approved apps** to remove a saved permission, or switch Computer Use off. Signing out or changing deployments clears the device opt-in and app approvals. Computer Use cannot operate Sim's own permission controls or macOS System Settings.
+
+### Terminal access
+
+Terminal commands run with your macOS account's permissions. They can modify files outside selected-folder grants; those grants do not confine the shell. Disable **Settings → Account → Terminal → Let Chat run commands** to remove this capability.
+
+Command confirmation depends on Chat's tool-permission settings and whether the run is interactive. With approvals enabled, command runs can wait for approval unless the tool is auto-allowed. Noninteractive runs do not wait for a per-command decision.
 
 ## Settings
 
-The desktop app adds three sections under **Settings → Account**. They appear only when you are running the app, and they apply to this Mac rather than to your account.
+Desktop settings appear under **Settings → Account** when the app exposes the corresponding capability. They apply to this Mac.
 
 ### Desktop
 
-- **Launch Sim at login**
-- **Show Sim in Control Center** — the menu-bar icon
-- **Automatically download updates**
-- **Enable desktop notifications**, with **Play notification sounds** and **Notify only when Sim isn't focused**
+| Setting | Behavior |
+| --- | --- |
+| **Launch Sim at login** | Start Sim when you sign in to macOS. Off by default. |
+| **Prevent sleep while a chat is running** | Keep the Mac awake during Chat activity. On by default. |
+| **Show Sim in Control Center** | Show Sim's menu-bar icon and recent chats. |
+| **Automatically download updates** | Download available updates in the background. |
+| **Full file access** | Allow local file tools to access files without individual folder approvals. Off by default. |
+| **Enable desktop notifications** | Enable completion notifications. |
+| **Play notification sounds** | Play a sound with notifications. |
+| **Notify only when Sim isn't focused** | Suppress completion notifications while you are working in Sim. |
 
-It also shows the installed version, and the version waiting to be applied when an update is ready.
+This section also shows the installed version and a downloaded version waiting for restart.
 
 ### Browser
 
-- **Let Chat browse the web** — the master switch for the built-in browser
-- **Search suggestions**, **Theme**, **Default zoom**, and **Download location**
-- **Browsing data** — clear cookies, site data, and cached images and files
+| Setting or action | Behavior |
+| --- | --- |
+| **Let Chat browse the web** | Enable or disable the built-in browser. |
+| **Search suggestions** | Send address-bar typing to Google for live completions. |
+| **Theme**, **Default zoom** | Set the browser's appearance and page zoom. |
+| **Download location** | Choose where browser downloads are saved. |
+| **Passwords** | Manage saved browser passwords. |
+| **Browsing data** | Clear cookies, site data, and cached images and files. |
 
 ### Terminal
 
-- **Let Chat run commands** — the master switch for the built-in terminal
-- **Theme** and **Default zoom**
+Use **Let Chat run commands** to enable or disable Terminal. **Theme** and **Default zoom** control its appearance.
 
-The menu bar carries the rest: **Sim → Settings…** (`Cmd` + `,`), **Server…** to change deployments, **Check for Updates…**, and **Sign Out**.
+The **Sim** menu also contains **Settings…**, **Server…**, **Check for Updates…**, and **Sign Out**.
 
-## Updates
+## Keyboard shortcuts
+
+The [workflow and table shortcuts](/keyboard-shortcuts) also work in Desktop. Focus determines whether a shortcut acts on Sim, the browser, or Terminal.
+
+| Shortcut | Action |
+| --- | --- |
+| `Cmd` + `K` | Open search |
+| `Cmd` + `B` | Toggle the sidebar |
+| `Cmd` + `N` | New chat |
+| `Cmd` + `Shift` + `N` | New window |
+| `Cmd` + `,` | Settings |
+| `Cmd` + `[` / `]` | Back / forward in Sim or the focused browser |
+| `Cmd` + `R` | Reload Sim or the focused browser; clear the focused terminal's screen |
+| `Cmd` + `0` / `+` / `-` | Reset / increase / decrease zoom in the focused surface |
 
-Sim checks the deployment it is pointed at rather than a global feed. How it applies what it finds depends on how the app was installed. Nothing is ever forced mid-session either way.
+When Browser or Terminal is focused:
 
-**Installed in `/Applications`, signed by Sim** — what the download link above gives you. The app replaces itself. With **Automatically download updates** on, it downloads in the background and offers to restart; choose **Later** and the update applies the next time you quit. With it off, nothing downloads until you ask: **Sim → Check for Updates…** reports the available version and waits for you to choose **Download**.
+| Shortcut | Action |
+| --- | --- |
+| `Cmd` + `T` | New tab |
+| `Cmd` + `W` | Close the focused tab |
+| `Cmd` + `Shift` + `T` | Reopen the last closed tab |
+| `Ctrl` + `Tab` / `Ctrl` + `Shift` + `Tab` | Next / previous tab |
+| `Cmd` + `1`–`8` | Jump to that tab |
+| `Cmd` + `9` | Jump to the last tab |
+| `Cmd` + `L` | Focus the browser address bar |
+| `Cmd` + `F` | Find on the browser page |
 
-**Anywhere else** — outside `/Applications`, or a build not signed with a Developer ID. The app cannot replace itself, so it offers you the installer to download and swap in by hand.
+The last two shortcuts apply to Browser. With Sim focused, `Cmd` + `L` opens Logs.
 
-Updates come from the deployment you are connected to, so a self-hosted install controls which build its own users are offered. That control depends on the feed staying reachable: if it is not, a self-updating stable build falls back to Sim's public GitHub releases rather than stalling. See [Desktop App on Your Deployment](/platform/self-hosting/desktop).
+## Updates
 
-## Requirements
+The app checks the deployment it is connected to for updates. It does not force a restart during your session.
 
-- **macOS 12 Monterey or later**, on Apple Silicon or Intel.
-- **Outbound access to your Sim deployment**, and to `github.com`, which is where installers and updates are downloaded from.
-- **If you self-host**, your Sim server needs its own outbound access to both `api.github.com`, which is what resolves *which* release to offer, and `github.com`. An allowlist carrying only `github.com` leaves the download endpoint answering `502`.
-- **A system-trusted TLS certificate**, if you self-host. The app rejects certificate errors outright and offers no override, so a private CA must be installed in the macOS keychain.
+| Installation | Update behavior |
+| --- | --- |
+| Developer ID build in **Applications** | The app can replace itself. With **Automatically download updates** on, it downloads in the background and offers to restart. Choose **Later** to apply the downloaded update when you next quit. With the setting off, **Sim → Check for Updates…** offers a version and waits for **Download**. |
+| Build outside **Applications**, or without Developer ID signing | The app offers an installer for you to download and install manually. |
 
-<Callout>
-  The desktop app is macOS-only today. The web app works in any browser on any platform, and your account, workspaces, and workflows are the same either way.
-</Callout>
+If the deployment's update feed is unavailable, an eligible stable build falls back to Sim's public GitHub releases. Prerelease builds skip the check instead. See [Desktop app on your deployment](/platform/self-hosting/desktop#what-an-installed-app-does-when-the-feed-fails) for feed failures and release selection.
+
+## Related docs
+
+- [Desktop app on your deployment](/platform/self-hosting/desktop)
+- [Chat](/chat)
+- [Keyboard shortcuts](/keyboard-shortcuts)
diff --git a/apps/docs/content/docs/files/editor.mdx b/apps/docs/content/docs/files/editor.mdx
index b40166a2c80..1dbb06ff48f 100644
--- a/apps/docs/content/docs/files/editor.mdx
+++ b/apps/docs/content/docs/files/editor.mdx
@@ -1,55 +1,61 @@
 ---
 title: Editor
-description: A rich markdown editor for your files — type markdown and watch it render, or edit visually.
+description: Format Markdown documents, edit their source, and download them from Files.
 ---
 
-import { Image } from '@/components/ui/image'
-import { Card, Cards } from 'fumadocs-ui/components/card'
-import { Callout } from 'fumadocs-ui/components/callout'
-
-Every markdown file in your workspace opens in a **rich editor**. Type markdown and it renders as you go, or format visually with the toolbar and slash menu. The file is saved as plain markdown.
-
-<div className="mx-auto w-full overflow-hidden rounded-lg my-6">
-  <Image src="/static/files/editor/overview.png" alt="A markdown file rendered in the editor: headings, bold, italic, and a link, a nested bullet list, and a table" width={900} height={410} />
-</div>
+Open a Markdown file in **Files** to read or edit it. Select **New file** to create a document. Rich editing requires edit access and supported document size and syntax; files remain stored as Markdown.
 
 ## Formatting text
 
-Select any text to bring up the formatting toolbar — bold, italic, strikethrough, inline code, and links. The same marks appear instantly as you type the markdown for them, like `**bold**` or `*italic*`. Links show a hover card so you can open, copy, edit, or remove them without hunting through the source.
+Select text to open the formatting toolbar for bold, italic, strikethrough, inline code, and links. You can also type Markdown, such as `**bold**` and `*italic*`. A link's hover card lets you open, copy, edit, or remove it.
 
-## Structure
+| Action | Shortcut or Markdown |
+| --- | --- |
+| Bold | **Cmd/Ctrl + B** |
+| Italic | **Cmd/Ctrl + I** |
+| Link selected text | **Cmd/Ctrl + K** |
+| Heading | `# ` through `###### ` |
+| Blockquote | `> ` |
+| Divider | `---` |
 
-Headings, blockquotes, and dividers keep long documents scannable. Type `# ` through `###### ` for headings, `> ` for a quote, and `---` for a divider.
+Bullet, numbered, and nested lists are supported. Task lists have checkboxes you can tick in the document when editing is allowed.
 
-## Lists and checklists
+## Insert blocks [#slash-menu-and-shortcuts]
 
-Bullet, ordered, and nested lists all work, plus task lists you can tick right in the document.
+Type `/` at the start of a block or after whitespace to open the insertion menu. Choose a heading, list, table, code block, image, or another available block. The menu does not open inside tables, code blocks, inline code, or links.
 
 ## Tables
 
-Insert a table from the slash menu, then click any cell for the floating table toolbar — add or remove rows and columns, toggle the header row, or delete the table. Drag a column border to resize it.
+Insert a table from the slash menu. Select a cell to open the table toolbar, then add or remove rows and columns, or delete the table. The header row stays in place; you can edit its text. Column resizing and merged cells are not supported.
 
 ## Code blocks
 
-Fenced code blocks are syntax-highlighted, with a language picker in the corner. Pick `mermaid` to render a live diagram instead of code.
+Fenced code blocks have syntax highlighting and a language picker. Choose `mermaid` to render a diagram. Select **Show source** when you need to edit its definition.
 
 ## Images
 
-Paste or drag an image straight into the document, then drag a corner to resize it.
+Paste or drag an image into the document, or insert one from the slash menu. Drag a corner to resize it. Uploaded images are stored as files and referenced from the Markdown document.
 
-## Slash menu and shortcuts
+## Markdown fidelity
 
-Type `/` anywhere to insert any block — heading, list, table, code block, image, and more — without leaving the keyboard. Familiar shortcuts work too: **Cmd/Ctrl + B** for bold, **Cmd/Ctrl + I** for italic, and **Cmd/Ctrl + K** to add a link over selected text.
+Rich editing can normalize Markdown syntax, such as changing `_italic_` to `*italic*` or a setext heading to a `#` heading. It does not promise byte-for-byte preservation of the entire document.
 
-## Markdown fidelity
+YAML frontmatter is kept separately and restored when the document is saved. Footnotes, HTML comments, and raw HTML constructs retain their source text. Preserving that source does not mean every HTML construct renders as a visual editing control.
+
+If a document cannot safely round-trip through rich editing, it opens with a read-only rich preview and an **Edit source** action for members with edit access. Examples include hard line breaks inside headings, non-canonical HTML entities such as `&copy;`, and some reference or image constructs.
+
+Rich editing supports up to 262,144 characters. **Edit source** can open text files up to 50 MiB, but saving sends the entire content in a JSON request capped at 10 MiB, including encoding and escaping. Download or process files elsewhere when these limits prevent editing.
+
+A file may also be temporarily read-only while Sim is writing it or the collaborative editor is connecting.
+
+## Download a document
+
+Select **Download** in the viewer. For an open Markdown document, the download can use the visible snapshot without saving it or advancing the collaborative file. Downloading a snapshot is separate from saving changes to the workspace.
 
-The editor round-trips your markdown exactly — it saves what you wrote, with no reformatting churn.
+When a Markdown export includes eligible stored images, Sim downloads a ZIP containing the document and an `assets/` folder, with image references rewritten to those assets. An export without bundled assets is a Markdown file. Missing or oversized assets can retain their original links, so check the exported document before sharing it elsewhere.
 
-<Callout type="info">
-A few constructs still can't round-trip: a `<br>` inside a table cell, a hard line break inside a heading, and non-canonical HTML entities such as `&copy;`. Files over 256 KB also open read-only. Footnotes, HTML comments, and raw HTML are preserved byte-for-byte and stay editable.
-</Callout>
+## Related docs
 
-<Cards>
-  <Card title="Generating files" href="/files/generating" description="Have a workflow produce a document from a run." />
-  <Card title="Using files in workflows" href="/files/using-in-workflows" description="Read a file into a workflow and produce one from a run." />
-</Cards>
+- [Files](/files)
+- [Using files in workflows](/files/using-in-workflows)
+- [Generating files](/files/generating)
diff --git a/apps/docs/content/docs/files/generating.mdx b/apps/docs/content/docs/files/generating.mdx
index 7ad2759531d..af204fa6122 100644
--- a/apps/docs/content/docs/files/generating.mdx
+++ b/apps/docs/content/docs/files/generating.mdx
@@ -1,66 +1,76 @@
 ---
 title: Generating files
-description: How a workflow produces a document, report, or media file and saves it to the workspace Files store.
+description: Save text or file objects produced by a workflow to workspace Files.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Card, Cards } from 'fumadocs-ui/components/card'
+A workflow can produce text, such as a summary or CSV, or a file object, such as an image or audio clip. Save the result to workspace **Files** when it needs a stable workspace identity for later runs, editing, or sharing.
 
-A generated file is an artifact a workflow run creates: a report, a CSV, a rendered audio clip. It starts as a value a block produces and becomes a workspace file when a [File](/integrations/file) block writes it to the [Files](/files) store. Once saved, it has a name, a size, and a URL, and any later run can read it back.
+A file returned by a block can belong only to the execution. Returning it and saving it to Files are separate actions.
 
+## Save text with Write [#saving-content-with-the-file-block]
 
-{/* VISUAL: flow diagram: [Agent/Function block produces content] → [File block, Write] → [Files panel, file visible] */}
+To save an Agent's summary as Markdown:
 
-## What produces file content
+1. Connect the Agent to a [File](/integrations/file) block.
+2. Select **Write**.
+3. Set **File Name** to `research_summary.md`.
+4. Set **Content** to `<agent.content>` and leave **File** empty.
+5. Choose a destination folder if needed, then run the workflow.
 
-Most generated files start as the output of an earlier block. Two patterns are common.
+The saved file appears in workspace **Files**. Write returns:
 
-A block returns **text content** you want to keep. An [Agent](/workflows/blocks/agent) writes an analysis or summary; a [Function](/workflows/blocks/function) builds a CSV or formats a report. That text is part of the block's output, read by reference as `<agent.content>` or `<function.result>`. To make it a file, you pass that value into a File block set to Write.
+| Field | Meaning |
+| --- | --- |
+| `id` | Canonical workspace file ID |
+| `name` | Saved name, including any suffix added to avoid a duplicate |
+| `size` | Stored file size in bytes |
+| `url` | File access URL; it does not grant public access |
+| `version` | Content version recorded by the write |
+| `revision` | Opaque token identifying the written content |
 
-A block returns a **file object** directly. ElevenLabs text-to-speech returns an `audioFile`; an image generator returns a generated image; the File block's own Read operation returns parsed files. These are already [UserFile](/files/passing-files) objects (an object with `id`, `name`, `url`, `size`, and `type`), so they appear in the output panel as files with no Write step. You can hand one to a downstream block, or write its content to the Files store to persist it.
+The content type is inferred from the extension: `.md` becomes `text/markdown`, and `.csv` becomes `text/csv`. **Content Type** in advanced mode overrides it. Setting `application/pdf` on a text string does not render a PDF; use an actual PDF file for that format.
 
-<Callout type="info">
-A block's output is remembered under the block's name for the rest of the run, and a later block reads it by key, like `<elevenlabs.audioFile>` or `<agent.content>`. Producing content and saving it are two separate steps: the producing block holds the value, the File block persists it.
-</Callout>
+A [Function](/workflows/blocks/function) can build text deterministically, such as CSV or JSON. Use `<function.result>` as **Content** when the returned value is the text you want to store. See [Using files in workflows](/files/using-in-workflows) for the full read → summarize → save example.
 
-## Saving content with the File block
+## Save an existing file
 
-The [File](/integrations/file) block's **Write** operation creates a new workspace file. It takes two required fields: a `fileName` (like `report.md`) and the `content` string to store. It returns the saved file's details.
+If a block already returns a file object, pass it to Write's **File** input and leave **Content** empty. Set **File Name** and the destination folder. Provide exactly one source: text in **Content**, or an existing object in **File**.
 
-{/* VISUAL: File Write anatomy: inputs (fileName, content, contentType?) → outputs (id, name, size, url) */}
+For example, ElevenLabs text-to-speech returns `<elevenlabs.audioFile>`. An image generator returns an image file, and a remote Function can return `<function.files[0]>`. These objects can go directly to compatible attachment or upload inputs. Write's **File** input copies their bytes into workspace Files so later runs can reuse them.
 
-To save an Agent's analysis, connect Agent into a File block, set the operation to Write, and reference the Agent's output: `fileName` = `research_summary.md`, `content` = `<agent.content>`. When the workflow runs, the File block writes the file and produces:
+At the tool level, `file_write` accepts `fileInput` and can inherit the source name when `fileName` is omitted. The current block editor still requires **File Name**.
 
-- `id`: the canonical file ID, used to fetch the file later.
-- `name`: the final file name after any deduplication (see below).
-- `size`: the byte count.
-- `url`: an absolute URL to download or preview the file.
+## Create, overwrite, or append
 
-The content type is detected from the file extension: `.csv` becomes `text/csv`, `.pdf` becomes `application/pdf`, `.md` becomes `text/markdown`. To set it yourself, fill in `contentType` in advanced mode.
+By default, Write keeps an existing file with the same name in the destination folder and adds a numeric suffix to the new file: `data.csv`, `data (1).csv`, then `data (2).csv`.
 
-If a file with the same name already exists in the workspace, Write does not overwrite it. It appends a numeric suffix instead: a second `data.csv` is saved as `data (1).csv`, a third as `data (2).csv`. To add to an existing file rather than create a new one, use the **Append** operation, which writes content to the end of a named file.
+Turn on **Overwrite Existing File** to replace the file at the exact destination name and folder. If that path does not exist, Write creates it. Use **Append** to add text to the end of an existing file instead. Select the file directly, or use its name with a folder scope to avoid targeting an ambiguous name.
 
-## Where the file goes
+For file tools or API operations that accept `expectedRevision`, use it to guard a content change based on an earlier read. A version number can stay the same across coalesced collaborative or workflow writes, so it is not an exact content precondition. For Write, `expectedRevision` requires `overwrite: true`. See the [file content API](/api-reference/files/updateFileContent) and [version history API](/api-reference/files/listFileVersions).
 
-A saved file lands in the workspace [Files](/files) store, the same place uploads live. It shows up in the Files panel in the sidebar with its name, size, type icon, and modified date, grouped by category: document, image, audio, video, or code. From there you can preview it, rename it, move it into a folder, or download it by URL.
+## Generate files with Function [#what-produces-file-content]
 
-{/* VISUAL: Files panel UI: generated files listed with name, size, type icon, owner, modified date, folder */}
+A remote Function can write files under `/tmp/sim/outputs`. Sim returns those files as the block's `files` output, ready for a compatible downstream input:
 
-Files are scoped to the workspace, not to one workflow. A file written by one workflow is visible to every other workflow in the same workspace. Any later run can read it back with the File block's Read or Get operation, or by selecting it in a file picker.
+```python
+with open('/tmp/sim/outputs/summary.csv', 'w') as handle:
+    handle.write('category,count\ncompleted,12\nfailed,2\n')
+```
 
-During a run, the file also appears in the output panel as the File block's output, shown as a structured object with its `id`, `name`, `url`, and `size`. The output panel shows you one run as it happens, while the Files store is where the file stays afterward.
+Pass `<function.files[0]>` to File **Write** to keep this execution artifact in workspace Files. Automatic exports allow up to 20 files and 50 MiB total; exceeding a cap fails the export rather than returning a partial set.
 
-{/* VISUAL: output panel tree: file object (id, name, url, size, type) during a run, beside the same file in the Files store */}
+The Chat workbench uses a per-call `SIM_OUTPUT_DIR`; outputs written there are exported to workspace Files. Use the environment-provided directory in that context. The separate Function tool also supports explicit `outputPath` and `outputSandboxPath` persistence. These are tool capabilities, not fields in the current Function block editor.
 
-## Returning a generated file from a deployment
+## Reuse and return a file [#where-the-file-goes]
 
-When a workflow is deployed as an [API](/workflows/deployment/api), a generated file can be part of the response. Reference the file in a [Response](/workflows/blocks/response) block, or include its ID in the object you return. The caller uses the `url` or `id` to fetch the file from the workspace store. The file itself stays in the Files store, and the response carries a pointer to it, not the bytes.
+Saved files belong to the workspace. Authorized later runs can select them in a file picker or read them by canonical ID with **Read**; use **Get Content** when the next step needs extracted text. Renaming or moving a file does not require another workflow to generate it again.
 
-## Next
+A [Response](/workflows/blocks/response) block can return a file object or a saved file ID to an API caller. The response does not create public access. API-key callers download saved workspace files through the Files API, or run-produced files through the run-file endpoint. Optional base64 output can include eligible bytes within its limits. See [Passing files](/files/passing-files#receiving-files-in-api-responses).
 
-<Cards>
-  <Card title="Files overview" href="/files" description="The artifact layer of your workspace." />
-  <Card title="Using files in workflows" href="/files/using-in-workflows" description="Provide files to a workflow and receive files back." />
-  <Card title="File block" href="/integrations/file" description="Read, Get, Write, and Append operations in full." />
-  <Card title="API deployment" href="/workflows/deployment/api" description="Expose a workflow as an API and return file references." />
-</Cards>
+## Related docs [#next]
+
+- [Files](/files)
+- [Using files in workflows](/files/using-in-workflows)
+- [Passing files](/files/passing-files)
+- [File block](/integrations/file)
+- [API deployment](/workflows/deployment/api)
diff --git a/apps/docs/content/docs/files/index.mdx b/apps/docs/content/docs/files/index.mdx
index 555aaefa26f..dd157140834 100644
--- a/apps/docs/content/docs/files/index.mdx
+++ b/apps/docs/content/docs/files/index.mdx
@@ -1,24 +1,74 @@
 ---
 title: Files
-description: Files are the documents, images, spreadsheets, and PDFs your workflows read and produce.
+description: Upload, create, organize, and share workspace documents and media.
 ---
 
-import { Card, Cards } from 'fumadocs-ui/components/card'
+**Files** stores the documents and media you upload, create, or save to a workspace. Use it when you need the file itself: a contract to review, an image to attach, or a report to download and reuse.
 
-A **file** is a document, image, spreadsheet, or PDF in your workspace. Files are how documents and media move into and out of your agents. Your team uploads them, you create them in the editor, or a workflow produces them, and they all live in one store shared across the workspace.
+Use [Tables](/tables) for structured rows and fields, and a [knowledge base](/knowledgebase) when an agent needs to search across documents. Adding a file to Files does not automatically add it to a knowledge base.
 
-Any [workflow](/workflows) can read a file or produce one. You might upload a contract for an agent to review, generate a report from a table, or hand a workflow the document it needs to answer a question.
+## Upload or create a file
 
-## How files fit the workspace
+1. Open **Files** in the workspace sidebar.
+2. Select **Upload**, or drag files into the list. Open a folder first to upload into it.
+3. Select **New file** to create a Markdown document, or **New folder** to organize files.
+4. Open a file to view it. Members with edit access can edit supported text files.
 
-- **[Workflows](/workflows)** read files, like a PDF to summarize, and produce them, like a rendered report. See [using files in workflows](/files/using-in-workflows).
-- **[Knowledge bases](/knowledgebase)** are built from files you upload, turning their contents into searchable memory.
-- **[Deployments](/workflows/deployment)** can take a file as input and return one as output.
+Workspace uploads support files up to 5 GiB each, subject to available workspace storage. This storage limit does not mean every viewer, workflow block, or external service can process a file that size. See [file limits](/files/passing-files#file-limits) before using a large file in a workflow.
 
-Use a file when the document or media itself is what matters. Use a [table](/tables) when you need structured rows and fields, and a [knowledge base](/knowledgebase) when an agent needs to search across many documents.
+## Preview, edit, and download
 
-<Cards>
-  <Card title="Using files in workflows" href="/files/using-in-workflows" description="Read a file into a workflow and produce one from a run." />
-  <Card title="Passing files" href="/files/passing-files" description="Provide files to a workflow and receive generated files back." />
-  <Card title="Knowledge bases" href="/knowledgebase" description="Make uploaded documents searchable for your agents." />
-</Cards>
+The viewer depends on the file's format, size, and your access:
+
+| Format | Available view |
+| --- | --- |
+| Markdown | Rich editing, with source editing when rich editing cannot preserve the document |
+| Text and code | Text editor |
+| CSV, HTML, SVG, Mermaid, and chart files | Format-specific previews; supported text files can also be edited |
+| PDF, DOCX, PPTX, and XLSX | Document, slide, or spreadsheet preview |
+| Common images, audio, and video | Image view or browser playback |
+| Unsupported formats | Download the file to open it elsewhere |
+
+HEIC and HEIF previews use server conversion. TIFF files are download-only. Browser media support and viewer size limits still apply. See [Editor](/files/editor) for Markdown formatting, source editing, and export behavior.
+
+Use **Download** in the file menu or viewer. Downloading multiple files or a folder produces a ZIP archive, subject to the [archive download limits](/api-reference/files/bulkDownloadFiles). A generated document's download can contain rendered bytes whose size and type differ from its stored generation source.
+
+## Organize files
+
+Use folders to group related files. The list can be searched, filtered, and sorted by properties such as type, size, owner, and last update. Open a file's menu to **Rename**, **Move to**, or **Pin** it.
+
+**Delete** removes the file from active Files and makes it eligible for the workspace's deletion lifecycle. Recovery and later cleanup depend on the effective [data retention policy](/platform/enterprise/data-retention); deletion does not promise immediate removal of every stored byte.
+
+## Access and sharing
+
+Workspace files are private to members and callers with the required workspace access. Read access allows viewing and downloading; write access is required to upload, create, edit, rename, move, or delete files. Enterprise permission groups can restrict Files and sharing.
+
+To share a file outside the workspace:
+
+1. Open its menu and select **Share**.
+2. Choose an available access mode.
+3. Select **Share**, then **Copy link**.
+
+| Access mode | Who can view and download |
+| --- | --- |
+| **Public** | Anyone with the link |
+| **Password** | Anyone with the link and password |
+| **Email** | Allowed emails or domains after verification with a one-time code |
+| **SSO** | Allowed emails signed in through SSO, when this mode is available |
+
+An administrator can disable public sharing or particular access modes. Sharing requires write access and a user identity; a workspace API key cannot enable a file share. To revoke a link, reopen **Share** and select **Unshare**. **Copy Link** in the file menu copies the workspace URL; it does not enable public sharing.
+
+## Reuse files in agents
+
+A workflow can read a workspace file when its execution identity has access. See [Using files in workflows](/files/using-in-workflows) for a read → summarize → save example.
+
+A file produced during a workflow run can remain an execution artifact without appearing in Files. [Save it to Files](/files/generating) when later runs need it. Execution files follow the run's lifecycle and are not retained indefinitely.
+
+[Chat attachments](/chat/files) stay private to the conversation until explicitly saved to workspace Files. Saving an attachment makes it a workspace resource; it does not create a public share link.
+
+## Related docs
+
+- [Editor](/files/editor)
+- [Using files in workflows](/files/using-in-workflows)
+- [Generating files](/files/generating)
+- [Passing files](/files/passing-files)
diff --git a/apps/docs/content/docs/files/passing-files.mdx b/apps/docs/content/docs/files/passing-files.mdx
index 22d22c94df5..90e07a59ac5 100644
--- a/apps/docs/content/docs/files/passing-files.mdx
+++ b/apps/docs/content/docs/files/passing-files.mdx
@@ -1,178 +1,187 @@
 ---
 title: Passing files
-description: How file objects move between blocks, into workflows via the API, and back out in responses.
+description: Reference files between blocks, supply files to the v2 API, and download run outputs.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 
-A file moves through a workflow as a standardized **file object**. Blocks receive it, act on it, and pass it on — this page covers the object's shape, how to reference it between blocks, and how files enter and leave through the API.
+Pass a file object to a compatible file input, or reference one of its properties when a block needs a specific value. Workflow file objects, API upload descriptors, and the API's run-file download records have different shapes.
 
-## File Objects
+## File objects
 
-When blocks output files (like Gmail attachments, generated images, or parsed documents), they return a standardized file object:
+Blocks that return platform files use a `UserFile` object. For example, a workspace file includes:
 
 ```json
 {
-  "id": "f_8c2...",
+  "id": "wf_V1StGXR8z5jdHi6BmyT7q",
   "name": "report.pdf",
-  "url": "https://...",
+  "url": "https://www.sim.ai/api/files/serve/ENCODED_STORAGE_KEY?context=workspace",
   "size": 245678,
   "type": "application/pdf",
-  "base64": "JVBERi0xLjQK..."
+  "key": "workspace/WORKSPACE_ID/FILE_STORAGE_KEY",
+  "context": "workspace"
 }
 ```
 
-You can access any of these properties when referencing files from previous blocks.
+The IDs, key, and URL above illustrate the fields. Use the values Sim returns; do not construct them yourself.
 
-## The File Block
+| Field | Meaning |
+| --- | --- |
+| `id` | Opaque file identifier |
+| `name` | Filename, including its extension |
+| `url` | Access URL; authentication and lifetime depend on its source |
+| `size` | Recorded file size in bytes |
+| `type` | MIME type |
+| `key` | Storage locator used by Sim; it is not a public access grant |
+| `context` | Optional storage context, such as `workspace` or `execution` |
+| `base64` | Optional encoded bytes; not included on every object |
+| `version` | Optional content version for a workspace file |
 
-The **File block** brings a file into a workflow. It accepts files from any source and outputs standardized file objects every block understands.
+The internal `key` and `context` fields may be omitted from output pickers and displayed logs. Their absence in a preview does not mean a file reference is unusable.
 
-**Inputs:**
-- **Uploaded files** - Drag and drop or select files directly
-- **External URLs** - Any publicly accessible file URL
-- **Files from other blocks** - Pass files from Gmail attachments, Slack downloads, etc.
+Generated documents can store generation source separately from the rendered download. Their recorded size or type can differ from the bytes a download returns.
 
-**Outputs:**
-- A list of `UserFile` objects with consistent structure (`id`, `name`, `url`, `size`, `type`, `base64`)
-- `contents` - Extracted text per file (the Get Content operation)
-- `combinedContent` - All fetched files' text merged into one string (the Fetch operation)
+**Read** returns file objects. **Get Content** returns extracted text in `contents`; **Fetch** returns file objects and `combinedContent`. For the operation settings, see [Using files in workflows](/files/using-in-workflows#the-file-block).
 
-**Example usage:**
+## Pass files between blocks [#passing-files-between-blocks]
 
-```
-// Get all files from the File block
-<file.files>
+Use the output picker or type `<` in a reference-capable input to select an earlier block's output. Keep the array index when selecting one file:
 
-// Get the first file
+```text
+<file.files>
 <file.files[0]>
-
-// Get the first file's extracted text (Get Content operation)
+<gmail.attachments[0]>
+<gmail.attachments[0].name>
 <file.contents[0]>
 ```
 
-The File block automatically:
-- Detects file types from URLs and extensions
-- Extracts text from PDFs, CSVs, and documents
-- Generates base64 encoding for binary files
-- Creates presigned URLs for secure access
-
-Use the File block when you need to normalize files from different sources before passing them to other blocks like Vision, STT, or email integrations.
+Pass the full object to a file input when possible. The receiving block determines which formats, object or array inputs, and sizes it supports. Sim does not convert every file format for every block.
 
-## Passing Files Between Blocks
+Use `.base64` only when the object includes it. JavaScript without imports can explicitly read bytes with `await sim.files.readBase64(file)` or text with `await sim.files.readText(file)` under the Function helper limits. In remote Function code, `<file.files[0].path>` requests a file mount; it is a special indexed reference, not a UserFile property. See [Function files](/workflows/blocks/function#files).
 
-Reference files from previous blocks using the tag dropdown. Click in any file input field and type `<` to see available outputs.
+## Supply files to the API [#triggering-workflows-with-files]
 
-**Common patterns:**
+Before calling the workflow, add a **Files** input named `document` to the entry trigger's input format and deploy that version. The UI uses the field type `file[]`; `files` remains a legacy compatibility alias. With a Start block named `Start`, the first processed file is available as `<start.document[0]>`.
 
-```
-// Single file from a block
-<gmail.attachments[0]>
-
-// Pass the whole file object
-<file_parser.files[0]>
-
-// Access specific properties
-<gmail.attachments[0].name>
-<gmail.attachments[0].base64>
-```
-
-Most blocks accept the full file object and extract what they need automatically. You don't need to manually extract `base64` or `url` in most cases.
-
-## Triggering Workflows with Files
-
-When calling a workflow via API that expects file input, include files in your request:
+Set `WORKFLOW_ID` and `SIM_API_KEY` in your shell. On self-hosted Sim, replace the Cloud origin with your deployment URL. Put workflow fields inside the v2 request's `input` object.
 
 <Tabs items={['Base64', 'URL']}>
   <Tab value="Base64">
+    This example uploads a small text file containing `Hello, Sim.` followed by a newline. For another file, replace the encoded bytes, MIME type, and name together.
+
     ```bash
-    curl -X POST "https://www.sim.ai/api/v2/workflows/YOUR_WORKFLOW_ID/execute" \
-      -H "Content-Type: application/json" \
-      -H "x-api-key: YOUR_API_KEY" \
+    curl --fail-with-body -X POST \
+      "https://www.sim.ai/api/v2/workflows/$WORKFLOW_ID/execute" \
+      -H "X-API-Key: $SIM_API_KEY" \
+      -H 'Content-Type: application/json' \
       -d '{
-        "document": {
-          "name": "report.pdf",
-          "base64": "JVBERi0xLjQK...",
-          "type": "application/pdf"
+        "input": {
+          "document": [{
+            "type": "file",
+            "data": "data:text/plain;base64,SGVsbG8sIFNpbS4K",
+            "name": "notes.txt",
+            "mime": "text/plain"
+          }]
         }
       }'
     ```
   </Tab>
   <Tab value="URL">
+    Replace the example URL with a downloadable file URL that passes your deployment's network policy.
+
     ```bash
-    curl -X POST "https://www.sim.ai/api/v2/workflows/YOUR_WORKFLOW_ID/execute" \
-      -H "Content-Type: application/json" \
-      -H "x-api-key: YOUR_API_KEY" \
+    curl --fail-with-body -X POST \
+      "https://www.sim.ai/api/v2/workflows/$WORKFLOW_ID/execute" \
+      -H "X-API-Key: $SIM_API_KEY" \
+      -H 'Content-Type: application/json' \
       -d '{
-        "document": {
-          "name": "report.pdf",
-          "url": "https://example.com/report.pdf",
-          "type": "application/pdf"
+        "input": {
+          "document": [{
+            "type": "url",
+            "data": "https://example.com/report.pdf",
+            "name": "report.pdf",
+            "mime": "application/pdf"
+          }]
         }
       }'
     ```
   </Tab>
 </Tabs>
 
-The workflow's Start block should have an input field configured to receive the file parameter.
+For a new file, `type` selects `file` or `url`; it is not the MIME type. `data` is a base64 data URL or a download URL, `name` is required, and `mime` is optional. The engine stores accepted new input files in execution storage and supplies an array of UserFile objects to the file-typed field before blocks run.
+
+Authorized workspace-member callers can also supply an existing stored reference such as `{ "id": "CANONICAL_FILE_ID" }` or `{ "key": "STORAGE_KEY" }`. Public or system callers cannot use an arbitrary ID or key to read workspace files; their supplied stored references are limited to files already authorized for that execution. A caller-provided identifier does not grant access to neighboring files or another workspace.
 
-## Receiving Files in API Responses
+## Download files from API responses [#receiving-files-in-api-responses]
 
-When a workflow outputs files, they're included in the response:
+Return the file object or saved file ID through a [Response](/workflows/blocks/response) block. A synchronous v2 response wraps the result in `data.output` and includes `data.runId`, `data.status`, and `data.error`. Check the run status even when the HTTP request succeeds.
+
+For a completed run that returned an execution-produced file:
+
+1. Set `RUN_ID` to the returned run ID.
+2. Read the run with `includeOutput=true`.
+3. Take the file's `id` or `downloadPath` from `data.files` and download it with the same authentication.
+
+```bash
+curl --fail-with-body \
+  "https://www.sim.ai/api/v2/workflows/$WORKFLOW_ID/runs/$RUN_ID?includeOutput=true" \
+  -H "X-API-Key: $SIM_API_KEY"
+```
+
+Each projected entry in `data.files` has this shape:
 
 ```json
 {
-  "success": true,
-  "output": {
-    "generatedFile": {
-      "name": "output.png",
-      "url": "https://...",
-      "base64": "iVBORw0KGgo...",
-      "type": "image/png",
-      "size": 34567
-    }
-  }
+  "id": "file_123",
+  "name": "output.png",
+  "size": 34567,
+  "type": "image/png",
+  "downloadPath": "/api/v2/workflows/WORKFLOW_ID/runs/RUN_ID/files/file_123",
+  "base64": null
 }
 ```
 
-Use `url` for direct downloads or `base64` for inline processing.
+Set `FILE_ID` to the returned file ID:
 
-## Blocks That Work with Files
+```bash
+curl --fail-with-body \
+  "https://www.sim.ai/api/v2/workflows/$WORKFLOW_ID/runs/$RUN_ID/files/$FILE_ID" \
+  -H "X-API-Key: $SIM_API_KEY" \
+  --output output.png
+```
 
-**File inputs:**
-- **File** - Parse documents, images, and text files
-- **Agent** - Read images with a vision-capable model, or documents as text
-- **Mistral Parser** - Extract text from PDFs
+The ordinary `/api/files/serve/...` URL in a workflow file object requires a session and does not accept `X-API-Key`. Use the [run-file download endpoint](/api-reference/workflow-runs/downloadWorkflowRunFileV2) for execution artifacts. If you saved a workspace file with Write and returned its ID, use [Download file](/api-reference/files/downloadFile) at `/api/v2/files/{fileId}?workspaceId={workspaceId}`.
 
-**File outputs:**
-- **Gmail** - Email attachments
-- **Slack** - Downloaded files
-- **TTS** - Generated audio files
-- **Video Generator** - Generated videos
-- **Image Generator** - Generated images
+Execution files follow the run's retention lifecycle and may later return `404`. Save them to Files when later runs need a workspace resource. Returning a pointer or downloading it does not make a public share link.
 
-**File storage:**
-- **Supabase** - Upload/download from storage
-- **S3** - AWS S3 operations
-- **Google Drive** - Drive file operations
-- **Dropbox** - Dropbox file operations
+To inline eligible output bytes, request `includeFileBase64: true`. The execute request's `base64MaxBytes` can lower the 16 MiB total inline ceiling; it cannot raise it. Async execution rejects these options. On a run read, base64 requires `includeOutput=true` and has a per-file ceiling; an oversized file can return `413` with its download path. Use authenticated downloads for large outputs. See [Execute workflow](/api-reference/workflows/executeWorkflowV2) and [Get workflow run](/api-reference/workflow-runs/getWorkflowRunV2) for the full option contracts.
 
-<Callout type="info">
-  Files are automatically available to downstream blocks. The engine handles all file transfer and format conversion.
-</Callout>
+## File limits
 
-## Best Practices
+There is no single limit for every upload or read path. Storage quota, parser limits, sandbox budgets, and the receiving provider's limits apply independently.
 
-1. **Use file objects directly** - Pass the full file object rather than extracting individual properties. Blocks handle the conversion automatically.
+| Path | Current hard limit |
+| --- | --- |
+| Workspace direct upload | 5 GiB per file, subject to workspace storage quota |
+| Legacy buffered workspace upload | 100 MiB per file |
+| New base64 or URL input processed for a workflow file field | 20 MiB per file |
+| File Fetch | 100 MiB download; 30-second download timeout |
+| File Get Content | 64 MiB source per file and 64 MiB combined extracted text |
+| File Write text or existing-file input | 50 MiB per file |
+| Function buffered mounts | 10 MiB per file; 50 MiB total |
+| Function URL mounts | 500 MiB per file; 2 GiB total |
+| Function automatic exports | 20 files; 50 MiB total |
 
-2. **Check file types** - Ensure the file type matches what the receiving block expects. An Agent using a vision-capable model can read images, while the File block handles documents.
+Workspace uploads use upload sessions for large transfers; API callers should follow the [file upload API](/api-reference/files/createFileUpload) rather than assume a multipart JSON or buffered upload shares the 5 GiB ceiling. A large stored file can still exceed a parser, model, or third-party upload limit. See [Function](/workflows/blocks/function) and the receiving block's reference before processing it.
 
-3. **Consider file size** - Large files increase run time. For very large files, consider using storage blocks (S3, Supabase) for intermediate storage.
+## Blocks that work with files
 
-import { FAQ } from '@/components/ui/faq'
+| Task | Examples |
+| --- | --- |
+| Read or extract content | [File](/integrations/file), [Agent](/workflows/blocks/agent), [Mistral Parser](/integrations/mistral_parse) |
+| Analyze an image or transcribe audio | Vision, STT |
+| Receive or send attachments | [Gmail](/integrations/gmail), [Slack](/integrations/slack) |
+| Generate media | TTS, Image Generator, Video Generator |
+| Store files externally | [Supabase](/integrations/supabase), [S3](/integrations/s3), [Google Drive](/integrations/google_drive), [Dropbox](/integrations/dropbox) |
 
-<FAQ items={[
-  { question: "What is the maximum file size for uploads?", answer: "There is no single limit for every file path. Workspace storage, workflow uploads, Function mounts, and external tools have separate limits. Check the receiving operation before passing a large file; Function sandbox mounts currently limit each inline file to 10 MB." },
-  { question: "How do file fields work in the Start block's input format?", answer: "When you define a field with type 'files' in the Start block's input format, the engine automatically processes incoming file data (base64 or URL) and uploads it to storage, converting it into UserFile objects before the workflow runs." },
-]} />
+These integrations support particular file operations; check their format and authentication requirements. Agent attachment support depends on the selected model and provider.
diff --git a/apps/docs/content/docs/files/using-in-workflows.mdx b/apps/docs/content/docs/files/using-in-workflows.mdx
index a97a9883f00..d7dff297457 100644
--- a/apps/docs/content/docs/files/using-in-workflows.mdx
+++ b/apps/docs/content/docs/files/using-in-workflows.mdx
@@ -1,98 +1,98 @@
 ---
 title: Using files in workflows
-description: Read a file's contents in a workflow, pass a file to a block that needs one, or save a new file from a run.
+description: Read a workspace file, summarize it with an Agent, and save the result.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
 import { WorkflowPreview, FILE_SUMMARY_WORKFLOW } from '@/components/workflow-preview'
 
-A file is a document, image, spreadsheet, or PDF in your workspace. A workflow can read a file to act on its contents, pass a file to a block or tool that needs one (attach a PDF to an email, send an image to a vision model), or produce a new file and save it. The [File](/integrations/file) block is how a file enters or leaves a workflow; the work in between is done by whatever block the task calls for.
-
-What you do with a file depends on the task, so this page covers the File block's operations and how a file moves between blocks rather than one fixed recipe. The example we'll use throughout reads `report.pdf`, asks an agent to summarize it, and saves the summary as `summary.md`, which exercises reading, processing, and writing in one workflow.
+Use a File block to read `report.pdf`, an Agent to summarize it, and another File block to save `summary.md`. You can also pass a file directly to a compatible block, such as an email attachment or image input.
 
 <WorkflowPreview workflow={FILE_SUMMARY_WORKFLOW} height={200} />
 
-## The File block
+Before running the example, upload `report.pdf` to workspace **Files** and choose an Agent model and provider that support PDF attachments. The execution identity must have access to the file and permission to create the summary.
 
-The **File** block is one block with five operations, chosen from a dropdown. Each operation is a different way a file, or its contents, enters or leaves the workflow.
+## Read the file [#reading-a-file-in]
 
-| Operation | What it does | Outputs |
-| --- | --- | --- |
-| **Read** | Take an existing workspace file, by file picker or by file ID. | `files` |
-| **Get Content** | Extract a workspace file's text, by file picker or by file ID. | `contents` |
-| **Fetch** | Download and parse a file from an external URL. | `files`, `combinedContent` |
-| **Write** | Create a new workspace file from a name and text content. | `id`, `name`, `size`, `url` |
-| **Append** | Add text to the end of an existing workspace file. | `id`, `name`, `size`, `url` |
+1. Add a [File](/integrations/file) block named `File`.
+2. Select **Read** and choose `report.pdf` in the file picker.
+3. Connect it to an Agent block named `Agent`.
 
-Read hands the next block the **file itself**; Get Content hands it the **text inside**. Fetch brings in both for an external URL. Write and Append put a file out. A workflow uses only the operations its task needs, often just Read. The two sections below cover Read and Write; the other operations are variants noted alongside.
+Read returns `files`, an array of file objects. Reference the first file as `<file.files[0]>`, or the array as `<file.files>`. Each object carries its ID, name, URL, byte size, MIME type, and storage key. See the [file object fields](/files/passing-files#file-objects).
 
-{/* VISUAL: File block config UI. Operation dropdown open showing Read / Get Content / Fetch / Write / Append */}
+In advanced mode, Read can take a canonical workspace file ID. Use that for a file saved earlier in the same run. If another block already returned the file object you need, pass that object directly to a compatible input.
 
-## Reading a file in
+## Summarize with Agent [#processing-the-file]
 
-In our example, the first File block is set to **Read**, with `report.pdf` chosen from the file picker. When it runs, it produces `files`: a list of **file objects**, one per file read. The first is `<file1.files[0]>`.
+In the Agent block:
 
-When the next step needs the file's *text* rather than the file itself, use **Get Content** instead: it extracts the text and outputs `contents`, an array with one string per file, read as `<file1.contents[0]>`.
+1. Set **Files** to `<file.files[0]>`.
+2. Add the instruction “Summarize this document” to **Messages**.
+3. Select a model and provider that support the file's format.
 
-A **file object** is the standard shape Sim uses for every file. It carries the file's details:
+The summary is available as `<agent.content>`. Attachment support varies by model and provider. Sim does not automatically turn an unsupported attachment into prompt text; use **Get Content** and reference the extracted string in **Messages** for a text-only path.
 
-```jsonc
-{
-  "id": "wf_V1StGXR8z5jdHi6B…", // workspace file ID
-  "name": "report.pdf",
-  "url": "https://…",         // where to access it
-  "size": 248120,             // bytes
-  "type": "application/pdf"
-}
-```
+## Save the summary [#writing-a-file-out]
 
-You rarely type a reference by hand. Wherever a block parameter accepts a file or a value, the builder lists the available outputs and you pick the one you want. Read mode also takes a file ID directly in advanced mode, which is how you read a file produced earlier in the same run.
+1. Connect the Agent to a second File block.
+2. Select **Write**.
+3. Set **File Name** to `summary.md`.
+4. Set **Content** to `<agent.content>` and leave **File** empty.
+5. Run the workflow, then open **Files** to verify the saved summary.
 
-<Callout type="info">
-**Fetch** brings in files that live outside the workspace. Point it at a URL, and add request headers (such as `Authorization: Bearer …`) when the download needs authentication. It outputs `files` like Read does, plus `combinedContent`: the fetched files' text merged into one string.
-</Callout>
+Write returns `id`, `name`, `size`, `url`, `version`, and `revision`. By default, a duplicate name in the destination folder gets a numeric suffix. Turn on **Overwrite Existing File** only when you want to replace that file's contents.
 
-{/* VISUAL: File block in Read mode, file picker open with report.pdf selected; callout on the files[] output */}
+Saving is optional. You can return the summary, send it to Slack, or email it as text without creating a workspace file. To save a binary file returned by another block, use Write's **File** input instead of **Content**; see [Generating files](/files/generating).
 
-## Processing the file
+## Choose another file operation [#the-file-block]
 
-Once a file is read, a processing block reads that output by name. Two blocks do this, and they consume the file differently.
+These operations cover common file-processing paths:
 
-### Agent block
+| Operation | Use it for | Outputs |
+| --- | --- | --- |
+| **Read** | Obtain workspace file objects by picker, canonical ID, or folder selection | `files` |
+| **Get Content** | Extract text from supported files | `contents`, and `lineRanges` when a line window is requested |
+| **Fetch** | Download and parse an HTTP(S) file URL, with optional request headers | `files`, `combinedContent` |
+| **Write** | Save text or an existing file object to workspace Files | `id`, `name`, `size`, `url`, `version`, `revision` |
+| **Append** | Add text to an existing file | `id`, `name`, `size`, `url`, `version`, `revision` |
 
-An [Agent](/workflows/blocks/agent) block has a **Files** input. Reference the read file there, `<file1.files[0]>`, and write the instruction in the prompt: "Summarize this document." The agent receives the file object, not just its text, so a **vision-capable model** can analyze images and scanned pages directly. Other models work from the file's text content.
+The current File block also supports listing, searching, applying edits, archives, sharing, and folder operations. See the [File block reference](/integrations/file) for their inputs and limits.
 
-In our example the Agent reads `<file1.files[0]>`, summarizes it, and keeps the summary under its own name as `<agent1.content>`.
+### Extract text
 
-{/* VISUAL: Agent block config. Files input bound to <file1.files[0]>, prompt "Summarize this document" */}
+Select **Get Content** when the next step needs text rather than the original file. Its `contents` array has one extracted string per selected file: `<file.contents[0]>` reads the first one. Optional offset and limit fields request a line window; line numbers refer to extracted text, not PDF pages or spreadsheet rows.
 
-### Function block
+Read and Get Content can select folders. A folder selection expands at run time and includes nested folders by default, so newly added files can be picked up by a later run. Turn off the subfolder option to include direct files only.
 
-A [Function](/workflows/blocks/function) block runs code, and it usually works with file **text**. Read the file with **Get Content** and pass the extracted text, `<file1.contents[0]>`, and the code can parse, filter, or reshape it and return the result as its own output. A Function can also take the file object itself and read it in code with the `sim.files` helpers, like `await sim.files.readText(file)` — see [the Function block](/workflows/blocks/function) for those. Use a Function when the file is structured text (a CSV or JSON dump) and you want exact, deterministic processing instead of a model's interpretation.
+### Fetch a URL
 
-<Callout type="info">
-The two blocks differ in what they take. An **Agent** takes the file object on its Files input, while a **Function** typically takes the file's text from Get Content's `contents`. Both store their result under their own name for the next block to read.
-</Callout>
+Select **Fetch**, enter the file URL, and provide request headers when needed, such as `Authorization: Bearer …`. The URL must pass the deployment's network validation and download limits. Fetch returns file objects in `files` and extracted text in `combinedContent`. It does not automatically save the fetched file to workspace Files.
 
-## Writing a file out
+### Process with Function
 
-Writing a file is optional, and many workflows skip it. The agent's summary could be returned in the response, posted to Slack, or emailed as-is without ever becoming a workspace file. Write a file when you specifically need a new one to keep, download, or hand to a later run.
+For deterministic CSV or JSON processing, use **Get Content** and reference its text in a [Function](/workflows/blocks/function). For example, parse a JSON file after extraction:
 
-The last block in our example is a File block set to **Write**. Give it a file name and the content to save:
+```javascript
+return JSON.parse(<file.contents[0]>);
+```
+
+For a text file, JavaScript without imports can read the original file bytes with a helper:
 
-- `fileName`: `summary.md`
-- `content`: `<agent1.content>`
+```javascript
+const file = <file.files[0]>;
+return await sim.files.readText(file);
+```
 
-Write creates a new workspace file and returns its `id`, `name`, `size`, and `url`. If a file with that name already exists, Write keeps both by adding a numeric suffix to the new one. The saved file lands in your workspace [files](/files), ready for the next run, a download, or another workflow.
+`readText` decodes file bytes; it does not extract PDF text. Use Get Content for document parsing. Python, Shell, and JavaScript with imports can use an indexed file-path reference such as `<file.files[0].path>` to request a sandbox mount under `/tmp/sim/inputs`. This special reference resolves to the mounted path; `.path` is not a stored property you can read after assigning the whole object to a variable.
 
-{/* VISUAL: run log showing the File Write step with the returned file id, name, and url */}
+Files written under `/tmp/sim/outputs` return as Function `files` output. Pass them to a compatible attachment/upload input, or use File Write to save them. See [Generating files](/files/generating#what-produces-file-content).
 
-<Callout type="info">
-**Append** adds to a file instead of replacing it. Target an existing workspace file by name and give it the content to add to the end. Use it to accumulate across runs, such as appending each run's observation to one `notes.md`.
-</Callout>
+### Append to an existing file
 
-## Composing the steps
+Select **Append**, choose an existing file, and provide the text to add. Use it for a running `notes.md` or log. Selecting a file directly avoids ambiguous names; when using a name, specify a folder scope if the name exists in several folders.
 
-Each block references the previous one by name, so you compose only the steps a task needs. A contract read by an Agent that returns a verdict stops at processing, and an uploaded image described by a vision model never touches Write, while a fetched CSV cleaned by a Function and saved as a new file uses all three. Reading a file in is common, and writing one out is only for when the result is itself a file.
+## Related docs [#composing-the-steps]
 
-For the file-object schema in full, base64 access, and how files move across API and chat triggers, see [Passing files](/files/passing-files).
+- [Passing files](/files/passing-files): object fields, API input, and authenticated downloads
+- [Generating files](/files/generating): text and binary persistence
+- [Function](/workflows/blocks/function): code, file mounts, and sandbox exports
+- [File block](/integrations/file): complete operation reference
diff --git a/apps/docs/content/docs/getting-started/index.mdx b/apps/docs/content/docs/getting-started/index.mdx
index 4156a12b51b..7ffba324222 100644
--- a/apps/docs/content/docs/getting-started/index.mdx
+++ b/apps/docs/content/docs/getting-started/index.mdx
@@ -1,95 +1,136 @@
 ---
-title: Getting Started
-description: Build your first agent in 10 minutes — a people researcher with web search tools and structured output.
+title: Getting started
+description: Build and test a research agent with web search tools and structured output.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Card, Cards } from 'fumadocs-ui/components/card'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
-import { Video } from '@/components/ui/video'
-import { Image } from '@/components/ui/image'
 
-Build a people research agent in 10 minutes. It takes a name through a chat interface, searches the web with AI search tools, and returns structured JSON with the person's location, profession, and education.
+Build an agent that receives a person's name, searches for their professional background, and returns `location`, `profession`, and `education` fields. You will test it in the workflow builder before deploying it.
 
-<Image
-  src="/static/getting-started/started-1.png"
-  alt="The finished people research workflow"
-  width={800}
-  height={340}
-/>
+## Prerequisites
 
-## Tutorial
+- A workspace where you can create and edit workflows.
+- An available model that supports tool calls and structured output.
+- Access to Exa and Linkup search tools. Use Sim-provided credentials where offered, or enter your own provider keys where prompted. Self-hosted deployments must supply the credentials they use.
+
+Model and tool calls can incur usage charges. See [Costs](/platform/costs) and [Credentials](/platform/credentials) for hosted credentials and your own keys.
+
+## Build the agent
 
 <Steps>
-  <Step title="Create a workflow and add an Agent">
-    In the sidebar, click the **+** next to **Workflows** and name the new workflow "Getting Started". The **Start block** is already on the canvas — it's the entry point that receives your chat input.
+<Step title="Create a workflow">
+
+Click **+** beside **Workflows** in the sidebar. Right-click the new workflow, choose **Rename**, and name it `People research`.
+
+The new workflow contains a **Start** block. Its built-in `input` field receives messages from the workflow test chat; you do not need to add a custom field for this tutorial.
+
+</Step>
+<Step title="Add and connect Agent">
+
+Open **Toolbar** and drag **Agent** into the workflow. Check that **Start** connects to **Agent**. If no connection appears, drag from Start's output handle to Agent's input handle.
+
+Select **Agent** to open its fields in **Editor**. Choose a model that supports tools and structured output, and configure its credentials if prompted.
+
+</Step>
+<Step title="Configure Messages">
+
+In **Messages**, create these two messages. Use the role dropdown to choose **System** or **User**, and the plus button to add another message.
+
+| Role | Content |
+| --- | --- |
+| **System** | `Research the person named in the user's message using the available search tools. Find their location, profession, and education. Use Unknown for anything you cannot verify. Include sources in your answer.` |
+| **User** | `<start.input>` |
 
-    Drag an **Agent block** onto the canvas and configure its **Messages**:
-    - **System**: "You are a people research agent. When given a person's name, use your search tools to find their location, profession, educational background, and other relevant details."
-    - **User**: insert `<start.input>` so the agent reads whatever the chat receives.
+`<start.input>` inserts the message passed into Start. See [References](/workflows/connections) for using block outputs in another block.
 
-    Leave the **Model** on the default (`claude-sonnet-5-5`), or pick any other.
+</Step>
+<Step title="Add search tools">
 
-    <div className="mx-auto w-full overflow-hidden rounded-lg">
-      <Video src="getting-started/started-2.mp4" width={700} height={450} />
-    </div>
-  </Step>
+In Agent's **Tools**, open **Add tool...** and add **Exa** and **Linkup**. Select Exa's search operation and configure the fields shown for each tool, including credentials where required.
 
-  <Step title="Add search tools">
-    In the Agent block's **Tools** section, add **Exa** and **Linkup**. The agent decides when to call them.
+The agent chooses which tools to call. A tool with a missing credential or required setting can fail when the agent calls it.
 
-    <div className="mx-auto w-3/5 overflow-hidden rounded-lg">
-      <Video src="getting-started/started-3.mp4" width={700} height={450} />
-    </div>
-  </Step>
+</Step>
+<Step title="Test and inspect the run">
 
-  <Step title="Test it">
-    Open the **Chat panel**, select `agent.content` as the output to display, and send: *"John is a software engineer from San Francisco who studied Computer Science at Stanford University."*
+Click **Open chat** beside the workflow's More actions menu. This opens the workflow test chat, which has an **Outputs** dropdown. The **Chat** tab in the panel is where you talk to Sim about building the workflow.
 
-    The agent searches, then returns what it found.
+In **Outputs**, select **Agent → content**. Send:
 
-    {/* Why this callout exists: the largest funnel drop in platform data (2026-06) is created-a-workflow -> first-successful-run, 92% -> 49% — this is the stall point it targets. */}
-    <Callout type="info">
-    If the run doesn't go green, open the output dropdown and read what each block returned — the failure is almost always visible there. The two most common causes are a missing API key on a tool and a reference pointing at a value that isn't there. For the full method, see [tracing a failure backward](/logs-debugging).
-    </Callout>
+```text
+Research the professional background of Tim Berners-Lee. Find his profession,
+education, and a publicly documented location. Mark anything you cannot verify
+as Unknown.
+```
 
-    <div className="mx-auto w-full overflow-hidden rounded-lg">
-      <Video src="getting-started/started-4.mp4" width={700} height={450} />
-    </div>
-  </Step>
+Expand **Logs** at the bottom of the builder and select Agent's row. Inspect its output, tool calls, and sources. Check that the results identify the intended person and support the returned facts.
 
-  <Step title="Add structured output">
-    In the Agent block's **Response Format**, click the magic wand (✨) and prompt: *"create a schema named person, that contains location, profession, and education"*. The schema is generated for you.
+</Step>
+<Step title="Define structured output">
 
-    <div className="mx-auto w-full overflow-hidden rounded-lg">
-      <Video src="getting-started/started-5.mp4" width={700} height={450} />
-    </div>
-  </Step>
+In Agent's **Response Format**, paste this schema:
 
-  <Step title="Test the structured output">
-    Back in the **Chat panel**, select the new structured output option and send: *"Sarah is a marketing manager from New York who has an MBA from Harvard Business School."*
+```json
+{
+  "name": "person",
+  "description": "A researched professional profile",
+  "strict": true,
+  "schema": {
+    "type": "object",
+    "properties": {
+      "location": {
+        "type": "string",
+        "description": "A publicly documented location, or Unknown"
+      },
+      "profession": {
+        "type": "string",
+        "description": "The person's profession, or Unknown"
+      },
+      "education": {
+        "type": "string",
+        "description": "The person's education, or Unknown"
+      }
+    },
+    "required": ["location", "profession", "education"],
+    "additionalProperties": false
+  }
+}
+```
 
-    The agent now returns JSON with `location`, `profession`, and `education` fields — ready for any downstream block to read by name.
+You can also use the generation control beside **Response Format** to create a schema from a description. Check the generated schema before running it.
 
-    <div className="mx-auto w-full overflow-hidden rounded-lg">
-      <Video src="getting-started/started-6.mp4" width={700} height={450} />
-    </div>
-  </Step>
+`person` names the schema. Its properties become outputs directly on Agent; it does not add a nested `person` field. Replace the System message with:
+
+```text
+Research the person named in the user's message using the available search tools.
+Return only the location, profession, and education fields defined by the response
+format. Use Unknown for anything you cannot verify.
+```
+
+Keep the User message set to `<start.input>`.
+
+</Step>
+<Step title="Verify the structured result">
+
+Send the same prompt in the workflow test chat. In **Outputs**, select Agent's `location`, `profession`, and `education` fields. Open Agent's complete output in **Logs** and check their values before using them downstream.
+
+When the model returns the schema's fields as valid JSON, they are available as `<agent.location>`, `<agent.profession>`, and `<agent.education>`. Structured output requests a shape; it does not verify the facts.
+
+<Callout type="warn">
+  A model can return malformed JSON even when a response format is configured. Sim can then fall back to `content` and add `_responseFormatWarning`. Inspect the output and correct the response or model configuration before relying on the schema fields.
+</Callout>
+
+</Step>
 </Steps>
 
-## Next
-
-<Cards>
-  <Card title="Workflows" href="/workflows">
-    The full model: blocks, connections, triggers, and how runs execute.
-  </Card>
-  <Card title="Agent block" href="/workflows/blocks/agent">
-    Everything the block you just used can do — tools, memory, skills, structured output.
-  </Card>
-  <Card title="Integrations" href="/integrations">
-    supported services your agents can act on, from Gmail to HubSpot.
-  </Card>
-  <Card title="Deploy it" href="/workflows/deployment">
-    Ship the workflow as an API, a chat, or an MCP server.
-  </Card>
-</Cards>
+## Fix a failed run
+
+Select the failed block in **Logs** and read its error, input, and output. Check the credentials on the model or tool, then confirm that each reference points to an existing output. Rerun after correcting the failure. See [Logs and debugging](/logs-debugging) for tracing a failure through earlier blocks.
+
+## Related docs
+
+- [Agent block](/workflows/blocks/agent): Tools, memory, skills, and response formats.
+- [Connections](/workflows/connections): Pass outputs between blocks.
+- [Deploy a workflow](/workflows/deployment): Expose the agent through an API, chat, or MCP server.
+- [Integrations](/integrations): Configure tools for other services.
diff --git a/apps/docs/content/docs/index.mdx b/apps/docs/content/docs/index.mdx
index 9c342ce5adf..de576fd7832 100644
--- a/apps/docs/content/docs/index.mdx
+++ b/apps/docs/content/docs/index.mdx
@@ -1,55 +1,8 @@
 ---
 title: Documentation
+description: Start with the Sim introduction or build your first agent.
 ---
 
-import { Card, Cards } from 'fumadocs-ui/components/card'
+Read the [Introduction](/introduction) to learn how Sim works, or follow [Getting started](/getting-started) to build and test your first agent.
 
-Welcome to Sim, the open-source AI workspace where teams build, deploy, and manage AI agents. Create agents visually with the workflow builder, conversationally through Chat, or programmatically with the API — connected to the integration catalog and every major LLM.
-
-## Quick Start
-
-<Cards>
-  <Card title="Introduction" href="/introduction">
-    Learn what you can build with Sim
-  </Card>
-  <Card title="Getting Started" href="/getting-started">
-    Build your first agent in 10 minutes
-  </Card>
-  <Card title="Blocks" href="/workflows#blocks">
-    Learn about the building blocks
-  </Card>
-  <Card title="Tools & Integrations" href="/integrations">
-    Explore the integration catalog
-  </Card>
-</Cards>
-
-## Core Concepts
-
-<Cards>
-  <Card title="Connections" href="/workflows/connections">
-    Understand how data flows between blocks
-  </Card>
-  <Card title="Variables" href="/workflows/variables">
-    Work with workflow and environment variables
-  </Card>
-  <Card title="Logs & debugging" href="/logs-debugging">
-    Inspect workflow runs and diagnose failures
-  </Card>
-  <Card title="Triggers" href="/workflows#triggers">
-    Start agents via API, webhooks, or schedules
-  </Card>
-</Cards>
-
-## Advanced Features
-
-<Cards>
-  <Card title="Team Management" href="/platform/permissions">
-    Set up workspace roles and permissions
-  </Card>
-  <Card title="MCP Integration" href="/agents/mcp">
-    Connect external services with Model Context Protocol
-  </Card>
-  <Card title="SDKs" href="/api-reference">
-    Integrate Sim into your applications
-  </Card>
-</Cards>
+This URL redirects to the Introduction in the documentation site.
diff --git a/apps/docs/content/docs/introduction/index.mdx b/apps/docs/content/docs/introduction/index.mdx
index f099f381c63..c9afe906d42 100644
--- a/apps/docs/content/docs/introduction/index.mdx
+++ b/apps/docs/content/docs/introduction/index.mdx
@@ -1,102 +1,52 @@
 ---
 title: Introduction
-description: Sim is the open-source AI workspace where teams build, deploy, and manage AI agents.
+description: Build, deploy, and manage AI agents in a shared workspace.
 ---
 
-import { Card, Cards } from 'fumadocs-ui/components/card'
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Image } from '@/components/ui/image'
-import { Video } from '@/components/ui/video'
-import { FAQ } from '@/components/ui/faq'
-
-Sim is the open-source AI workspace where teams build, deploy, and manage AI agents. Build visually in the workflow builder, conversationally in **Chat**, or with code through the API. Connect the integration catalog and every major LLM to create agents that automate real work.
-
-<div className="mx-auto w-full overflow-hidden rounded-lg my-6">
-  <Image
-    src="/static/introduction.png"
-    loading="eager"
-    fetchPriority="high"
-    alt="Sim workflow editor with an empty canvas, Editor panel, and workspace navigation"
-    width={2304}
-    height={1600}
-    className="w-full"
-  />
-</div>
-
-## How you build
-
-When you open Sim, the first thing you meet is **Chat**, a conversation over your whole workspace. You describe the system you want, and Sim scaffolds it: workflows, tables, knowledge bases, and the wiring between them. You then open what it built, run it, and refine it.
-
-- **Chat.** Describe a system in natural language and Sim creates and edits the resources for you. The fastest way to start.
-- **Workflow builder.** Design agent logic visually by connecting blocks in the builder. The clearest way to see and fine-tune what runs.
-- **API and SDK.** Build and trigger agents programmatically.
-
-You can mix these on one system, scaffolding in Chat and then fine-tuning in the builder.
-
-<Callout type="info">
-Sim generates the architecture, and you verify the execution. Even when you build conversationally, it helps to understand the resources Sim creates, so you can inspect, run, and improve them.
-</Callout>
-
-## The anatomy of a workspace
-
-A Sim system is not a single chat response. It is a set of resources that live in a **workspace** and connect to each other. The sidebar mirrors that anatomy, and these are its parts.
-
-- **[Chat](/chat)** is your AI command center. Talk to Sim — build and manage everything in natural language.
-- **[Workflows](/workflows)** are visual programs made of blocks, where your logic runs. Most other resources become useful through a workflow.
-- **[Agents and tools](/agents)** are how a workflow acts. An agent reasons with a model, and tools let it take actions like sending an email or querying an API.
-- **[Tables](/tables)** hold structured rows your workflows read, write, and process.
-- **[Knowledge bases](/knowledgebase)** are searchable memory. An agent retrieves relevant passages from your documents to ground its answers.
-- **[Files](/files)** are the documents and media your workflows store, read, and produce.
-- **[Deployments](/workflows/deployment)** expose a workflow to the outside world as an API, a chat, or an MCP server.
-- **[Logs](/logs-debugging)** record every run, block by block, so you can verify what happened.
-
-<div className="mx-auto w-full overflow-hidden rounded-lg my-6">
-  <Video src="introduction/build-workflow.mp4" width={700} height={450} />
-</div>
-
-## What you can build
-
-- **AI assistants and chatbots.** Conversational agents that search the web, manage calendars, send email, and act on your business systems.
-- **Business process automation.** Data entry, report generation, customer responses, and content workflows.
-- **Data processing and analysis.** Extract from documents, analyze datasets, and sync data across platforms.
-- **API integration workflows.** Unified endpoints that orchestrate multi-service logic and event-driven automation.
-
-## Integrations
-
-Sim provides native integrations with supported services:
-
-- **AI models.** OpenAI, Anthropic, Google Gemini, Groq, Cerebras, and local models via Ollama or VLLM.
-- **Communication.** Gmail, Slack, Microsoft Teams, Telegram, WhatsApp.
-- **Productivity.** Notion, Google Workspace, Airtable.
-- **Development.** GitHub, Jira, Linear, automated browser testing.
-- **Search and data.** Google Search, Perplexity, Firecrawl, Exa AI.
-- **Databases.** PostgreSQL, MySQL, Supabase, Pinecone, Qdrant.
-
-For anything not built in, [MCP support](/agents/mcp) connects any external service or tool.
-
-## Deployment options
-
-- **Cloud-hosted.** Launch immediately at [sim.ai](https://www.sim.ai) with managed infrastructure, scaling, and observability.
-- **Self-hosted.** Deploy on your own infrastructure with Docker Compose or Kubernetes, with support for local models.
-
-## Next steps
-
-<Cards>
-  <Card title="Quickstart" href="/getting-started">
-    Build your first agent in 10 minutes
-  </Card>
-  <Card title="Building with Chat" href="/chat">
-    Build and manage your workspace in natural language
-  </Card>
-  <Card title="Workflows" href="/workflows">
-    The executable center, and the blocks it's built from
-  </Card>
-  <Card title="Blocks" href="/workflows#blocks">
-    The building blocks of a workflow
-  </Card>
-</Cards>
-
-<FAQ items={[
-  { question: "Is Sim open source?", answer: "Yes. Sim is open source under the Apache 2.0 license. The full source code is available on GitHub and you can self-host it, contribute to development, or modify it for your own needs. Enterprise features (SSO, access control) have a separate license that requires a subscription for production use." },
-  { question: "Can I self-host Sim?", answer: "Yes. Sim provides Docker Compose configurations for self-hosted deployments. The stack includes the Sim application, a PostgreSQL database with pgvector, and a realtime collaboration server. You can also integrate local AI models via Ollama for a fully offline setup." },
-]} />
+Sim is the open-source AI workspace where teams build, deploy, and manage AI agents. Connect models and tools, store shared data, and inspect what happens when an agent runs.
+
+## Choose how to build
+
+| Method | Use it to |
+| --- | --- |
+| **[Chat](/chat)** | Describe what you need and ask Sim to create or edit workspace resources. Open what it creates, run it, and check the result. |
+| **[Workflow builder](/workflows)** | Connect blocks into agent logic, configure their inputs, and inspect execution step by step. |
+| **[API and SDKs](/api-reference)** | Create resources and run deployed workflows from your application. |
+
+You can start in Chat and refine the same workflow in the builder. On self-hosted deployments, Chat depends on the deployment's configuration and can be disabled.
+
+Follow [Getting started](/getting-started) to build an agent with web search tools and structured output.
+
+## Workspace resources
+
+A workspace holds the resources your team and agents use:
+
+| Resource | Purpose |
+| --- | --- |
+| **[Workflows](/workflows)** | Executable logic made of connected blocks. Use Agent blocks for model reasoning and tools for actions such as sending email or querying an API. |
+| **[Tables](/tables)** | Structured rows that workflows can read, update, and process. |
+| **[Files](/files)** | Documents and media you upload, create, and share with agents. |
+| **[Knowledge bases](/knowledgebase)** | Searchable documents. Retrieve relevant passages for an agent to use in its answers. |
+| **[Logs](/logs-debugging)** | Run records and block inputs, outputs, errors, timing, and costs. |
+
+[Deploy a workflow](/workflows/deployment) to make it available through an API, a chat interface, or an MCP server. MCP (Model Context Protocol) lets AI applications discover and call tools exposed by a server.
+
+## Models and integrations
+
+Use the [integration catalog](/integrations) to connect supported models, communication services, productivity apps, search tools, and databases. These tools let agents research a topic, process documents, update business systems, and return results to another application.
+
+For tools outside the catalog, connect an [external MCP server](/agents/mcp) or create a [custom tool](/agents/custom-tools). Configure the credentials and permissions each service requires.
+
+## Choose a deployment
+
+- **Sim Cloud:** Sign in at [sim.ai](https://www.sim.ai) to use the managed service.
+- **Self-hosted:** Run Sim on your infrastructure with [Docker Compose](/platform/self-hosting/docker) or [Kubernetes](/platform/self-hosting/kubernetes). You can connect local models through Ollama or vLLM. Chat and external integrations can still require network access.
+
+The core source is available on [GitHub](https://github.com/simstudioai/sim) under the Apache 2.0 license. Enterprise features use a separate license that requires an active Enterprise subscription for production use. See [self-hosting](/platform/self-hosting) for installation requirements and configuration.
+
+## Related docs
+
+- [Getting started](/getting-started): Build and test a research agent.
+- [Chat](/chat): Build and manage workspace resources conversationally.
+- [Workflows](/workflows): Blocks, connections, triggers, and execution.
+- [Quick reference](/quick-reference): Look up builder actions.
diff --git a/apps/docs/content/docs/keyboard-shortcuts/index.mdx b/apps/docs/content/docs/keyboard-shortcuts/index.mdx
index f0aebc459a0..778fa9dd122 100644
--- a/apps/docs/content/docs/keyboard-shortcuts/index.mdx
+++ b/apps/docs/content/docs/keyboard-shortcuts/index.mdx
@@ -1,95 +1,103 @@
 ---
-title: Keyboard Shortcuts
-description: Keyboard and mouse shortcuts for the workflow editor and for tables.
+title: Keyboard shortcuts
+description: Keyboard and pointer controls for workspace navigation, workflows, and tables.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
+`Mod` means `Cmd` on macOS and `Ctrl` on Windows and Linux. Editing shortcuts act on the focused surface. Some workspace commands also work while you are typing; an editor can keep a shortcut it owns.
 
-Sim has keyboard shortcuts for the workflow editor and for tables. Each set works when that surface is focused and you are not typing in a field. The macOS app adds its own window, tab, and navigation shortcuts on top of these — see [Sim Desktop](/desktop#keyboard-shortcuts).
+The macOS app adds window, tab, and browser controls. See [Sim Desktop](/desktop#keyboard-shortcuts).
 
-<Callout type="info">
-  **Mod** is `Cmd` on macOS and `Ctrl` on Windows and Linux.
-</Callout>
+## Workspace navigation
 
-## Workflow editor
+| Shortcut | Action |
+| --- | --- |
+| `Mod` + `K` | Open search |
+| `Mod` + `B` | Collapse or expand the sidebar, outside an editable field |
+| `Mod` + `Shift` + `P` | Create a workflow, outside an editable field |
+| `Mod` + `L` | Open Logs; a focused Desktop browser uses it for the address bar |
 
-### Mouse
+## Workflow builder
 
-| Action | Control |
-|--------|---------|
-| Pan the canvas | Middle-drag, left-drag in Hand mode, or scroll / trackpad |
-| Select multiple blocks | `Shift` + drag on empty space, or left-drag in Select mode |
-| Drag a block | Left-drag on the block header |
-| Add to selection | `Mod` / `Shift` + click on blocks |
+### Keyboard actions
 
-### Actions
+Keep focus outside an editable field for running, clipboard, history, layout, and Toolbar shortcuts.
 
 | Shortcut | Action |
-|----------|--------|
-| `Mod` + `Enter` | Run the workflow (or cancel if running) |
+| --- | --- |
+| `Mod` + `Enter` | Run the workflow, or stop it while running |
+| `Mod` + `Shift` + `A` | Add an Agent block to the active workflow |
 | `Mod` + `Z` | Undo |
 | `Mod` + `Shift` + `Z` | Redo |
 | `Mod` + `C` / `X` / `V` | Copy / cut / paste selected blocks |
-| `Delete` or `Backspace` | Delete selected blocks or edges |
-| `Shift` + `L` | Auto-layout the canvas |
-| `Mod` + `Shift` + `F` | Fit to view |
-| `Mod` + `F` | Search and replace in the workflow |
-| `Mod` + `Shift` + `Enter` | Accept Copilot changes |
-| `Mod` + `Alt` + `F` | Focus the Toolbar search |
+| `Delete` or `Backspace` | Delete selected blocks or connections |
+| `Shift` + `L` | Auto-layout the workflow |
+| `Mod` + `Shift` + `F` | Fit the workflow to the view |
+| `Mod` + `F` | Open workflow search and replace |
+| `Mod` + `Shift` + `Enter` | Accept Sim's proposed workflow changes |
+| `Mod` + `Alt` + `F` | Open Toolbar and focus its search |
+| `Mod` + `D` | Clear the workflow console; persisted run logs remain |
+
+### Pointer controls
+
+| Task | Control |
+| --- | --- |
+| Pan the builder | Middle-drag, left-drag in Hand mode, or scroll / use a trackpad |
+| Select multiple blocks | Left-drag on empty space in Select mode, or `Shift` + drag in Hand mode |
+| Move a block | Left-drag its header |
+| Add blocks to the selection | `Mod` or `Shift` + click |
 
 ## Tables
 
-These work when a table is focused and no cell is being edited.
+Select a cell and keep the table focused. Navigation and selection shortcuts apply while no cell is being edited. Editing, cut, paste, clearing cells, and adding rows require the corresponding permissions; table locks can prevent changes.
 
 ### Navigation
 
 | Shortcut | Action |
-|----------|--------|
+| --- | --- |
 | Arrow keys | Move one cell |
 | `Mod` + Arrow keys | Jump to the edge of the table |
 | `Tab` / `Shift` + `Tab` | Move to the next / previous cell |
-| `Escape` | Clear the selection |
+| `Escape` | Close table find if open; otherwise clear the selection |
 
 ### Selection
 
 | Shortcut | Action |
-|----------|--------|
+| --- | --- |
 | `Shift` + Arrow keys | Extend the selection by one cell |
 | `Mod` + `Shift` + Arrow keys | Extend the selection to the edge |
 | `Shift` + `Space` | Select the current row |
 | `Mod` + `Space` | Select the current column |
+| `Mod` + `A` | Select all table rows; press again to clear the selection |
 
 ### Editing
 
 | Shortcut | Action |
-|----------|--------|
-| `Enter` or `F2` | Start editing the selected cell |
-| Any character | Start editing with that character |
-| `Escape` | Cancel editing |
-| `Shift` + `Enter` | Insert a new row below |
-| `Space` | Expand row details |
+| --- | --- |
+| `Enter` or `F2` | Open the selected cell's editor; toggle a boolean cell |
+| Any character | Start editing the selected cell with that character |
+| `Escape` | Cancel the current edit |
+| `Shift` + `Enter` | Insert a row below; open the new-row form when required fields need values |
+| `Space` | Open the selected row's editor |
+| `Mod` + `D` | Fill selected cells down from the top of the selection |
 
-### Clipboard
+### Clipboard and history
 
 | Shortcut | Action |
-|----------|--------|
+| --- | --- |
 | `Mod` + `C` / `X` / `V` | Copy / cut / paste cells |
-| `Delete` or `Backspace` | Clear the selected cells |
+| `Delete` or `Backspace` | Clear selected cells |
+| `Mod` + `Z` | Undo |
+| `Mod` + `Y` | Redo |
 
-### History
+### Find
 
 | Shortcut | Action |
-|----------|--------|
-| `Mod` + `Z` | Undo |
-| `Mod` + `Shift` + `Z` or `Mod` + `Y` | Redo |
+| --- | --- |
+| `Mod` + `F` | Open table find |
+| `Escape` | Close table find |
 
-## Global
+## Related docs
 
-| Shortcut | Action |
-|----------|--------|
-| `Mod` + `K` | Open search |
-| `Mod` + `Shift` + `A` | Create a new agent |
-| `Mod` + `Shift` + `P` | Create a new workflow |
-| `Mod` + `L` | Go to logs |
-| `Mod` + `D` | Clear the terminal console |
-| `Mod` + `B` | Collapse / expand the sidebar |
+- [Quick reference](/quick-reference)
+- [Tables](/tables)
+- [Sim Desktop](/desktop#keyboard-shortcuts)
diff --git a/apps/docs/content/docs/knowledgebase/chunking-strategies.mdx b/apps/docs/content/docs/knowledgebase/chunking-strategies.mdx
index 7ce25cf3b5f..949371f5109 100644
--- a/apps/docs/content/docs/knowledgebase/chunking-strategies.mdx
+++ b/apps/docs/content/docs/knowledgebase/chunking-strategies.mdx
@@ -1,120 +1,144 @@
 ---
 title: Chunking strategies
-description: The chunking settings and strategies, for the rare case you need to override Auto.
+description: Choose passage sizes and boundaries for knowledge base documents.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { FAQ } from '@/components/ui/faq'
+**Auto** is the default chunking strategy. Start with its default settings, inspect the chunks returned by real questions, then change settings when passages combine unrelated topics or lose needed context.
 
-<Callout type="warn">
-**Advanced.** Leave the strategy on **Auto** and the settings on their defaults unless you have a specific reason to change them and know how chunk boundaries affect retrieval. Auto inspects each file and routes it to the right chunker on its own. The rest of this page is for the case where you've confirmed Auto isn't producing the chunks you want.
-</Callout>
+Choose a different strategy when you need specific boundaries:
 
-If you do override Auto, the short version:
-
-- Sentence integrity matters (Q&A, legal text) → **[Sentence](#sentence)**
-- Content has structural markers Text misses (code, custom formats) → **[Recursive](#recursive)**
-- You need uniform chunk sizes → **[Token](#token)**
-- Content has explicit delimiters → **[Regex](#regex)**
-- Each record must be its own chunk → **[convert to JSONL](#one-record-per-chunk)**
+| Need | Strategy |
+| --- | --- |
+| General prose | [Text](#text) |
+| Custom structure or code markers | [Recursive](#recursive) |
+| Whole sentences where possible | [Sentence](#sentence) |
+| A fixed sliding window | [Token](#token) |
+| Explicit delimiters | [Regex](#regex) |
+| Structured records | [Auto with JSONL](#one-record-per-chunk), with batching and oversized-record limits |
 
 ## Settings
 
-| Setting | Unit | Default | Range | Description |
-|---------|------|---------|-------|-------------|
-| Max Chunk Size | tokens | 1,024 | 100–4,000 | Upper bound on chunk size. 1 token ≈ 4 characters. |
-| Min Chunk Size | characters | 100 | 100–2,000 | Tiny fragments below this are dropped. |
-| Overlap | tokens | 200 | 0–500 | Tokens repeated between adjacent chunks to preserve context. |
+Set these values when creating a base:
+
+| Setting | Unit | Default | Range | Behavior |
+| --- | --- | --- | --- | --- |
+| **Max Chunk Size** | Estimated tokens | 1,024 | 100–4,000 | Size target before overlap; splitters can append overlapping text afterward. |
+| **Min Chunk Size** | Characters | 100 | 1–2,000 | Minimum fragment size in strategies that apply it; it is not enforced by every splitter. |
+| **Overlap** | Estimated tokens | 200 | 0–500 | Context repeated between adjacent chunks in strategies that support overlap. |
+
+Overlap must be smaller than Max Chunk Size. Min Chunk Size must be smaller than Max Chunk Size converted to characters (`maxSize × 4`).
+
+The prose splitters estimate one token as roughly four characters. Tabular chunking uses a denser estimate of roughly three characters per token. These estimates guide splitting; they are not exact model-tokenizer counts.
 
-[Pinecone's chunking guide](https://www.pinecone.io/learn/chunking-strategies/) covers the size and overlap tradeoffs.
+Text, Recursive, Sentence, and Regex retain small fragments rather than applying the minimum-size filter. Token can filter small windows, with a fallback that retains them when filtering would remove every window. JSON/YAML applies the minimum in some paths; tabular chunking groups rows independently of this setting.
 
-Every strategy splits the document at boundaries, then packs adjacent splits together up to the max chunk size, so a chunk usually spans several splits and a split boundary is not a chunk boundary. This is why a precise [Regex](#regex) can still produce chunks containing multiple matches.
+Overlap increases stored text and can produce similar hits from neighboring chunks. Text, Recursive, and non-strict Regex append overlap after forming chunks, so the final chunk can exceed the base size target. Token uses overlapping windows, and Sentence tries to repeat whole sentences.
 
-## Strategies
+## Auto
 
-### Auto
+Auto chooses from the parsed document type, MIME type, and tabular content shape:
 
-Sim inspects the file and routes to the right chunker:
+- JSON, JSONL, and YAML use structural chunking when they parse as objects or arrays.
+- CSV and Excel content is grouped by row with headers preserved. Delimited text can also be detected as tabular content.
+- Other content, including ordinary PDF, Word, text, Markdown, HTML, and PowerPoint documents, uses Text.
 
-- `.json`, `.jsonl`, `.yaml`, `.yml` → structural chunking (records are never split mid-way; small records may still be batched together up to the chunk size)
-- `.csv`, `.xlsx`, `.xls`, `.tsv` → grouped by row, with headers preserved
-- Everything else (`.pdf`, `.docx`, `.txt`, `.md`, `.html`, `.pptx`, …) → Text strategy
+Use `.json`, `.jsonl`, `.yaml`, or `.yml` when you need structural parsing. A plain `.txt` upload is not automatically treated as JSON just because it contains valid JSON. `.tsv` is not an offered knowledge-base upload extension; use an accepted format such as `.csv`.
 
-Routing is based on detected MIME type and content shape, not just the extension — a `.txt` file containing valid JSON is still routed structurally.
+Structural chunking keeps records together when they fit, batches small records, and splits oversized records or rows. Auto is not a guarantee of one record per chunk.
 
-Pick Auto unless you've confirmed it isn't producing the chunks you want.
+## Text
 
-### Text
+Text splits general prose using a separator hierarchy:
 
-Hierarchical splitter that walks down a separator list: horizontal rules → markdown headings → paragraphs (`\n\n`) → lines (`\n`) → sentence punctuation (`. ! ?`) → clause punctuation (`; ,`) → spaces. It tries the largest separator first and falls back when a piece is still too large.
+Horizontal rules → Markdown headings → paragraphs (`\n\n`) → lines (`\n`) → sentence punctuation (`. `, `! `, `? `) → clause punctuation (`; `, `, `) → spaces.
 
+It tries larger structural boundaries first and falls back when a piece is too large. Adjacent pieces can be packed together up to the size target before overlap is added.
 
+## Recursive
 
-Use it for general prose.
+Recursive uses the same approach with a separator hierarchy you provide. For example, split code on `\nclass `, then `\nfunction `, then `\n\n`.
 
-### Recursive
+Enter custom separators in the creation form. The v2 API also accepts the built-in `plain`, `markdown`, and `code` recipes through `strategyOptions.recipe` with `strategy: "recursive"`. Use Recursive when your content has markers the Text hierarchy misses.
 
-Same algorithm as Text, but you supply your own separator hierarchy or pick a built-in recipe (`plain`, `markdown`, `code`).
+## Sentence
 
+Sentence splits at sentence boundaries, with abbreviation handling, then packs whole sentences up to the size target. A sentence that exceeds the target is split at word boundaries.
 
+Use it when an incomplete sentence would change the meaning, such as Q&A or legal text. Overlap prefers whole sentences; when none fits, it falls back to a text tail.
 
-Use Recursive when your content has structural markers the default Text separators miss — splitting code on `\nclass `, `\nfunction `, then `\n\n`, for example.
+## Token
 
-### Sentence
+Token uses a fixed sliding window aligned to word boundaries. It does not recognize paragraphs or sentences, and its token sizes are estimates rather than exact tokenizer counts.
 
-Splits on sentence boundaries (`. `, `! `, `? `, with abbreviation handling) and packs whole sentences up to the chunk size. A sentence is never split mid-way unless it individually exceeds the limit.
+Use it when a regular window is more useful than structural boundaries.
 
+## Regex
 
+Regex splits text at a pattern you supply, then normally packs adjacent segments up to the size target. A pattern such as `(?=\n\s*\{\s*"id"\s*:)` can find record boundaries, but small segments can still share a chunk.
 
-Use it when sentence integrity matters — Q&A, legal text, or anything where mid-sentence cuts hurt comprehension.
+A consuming delimiter is removed from the split text. Positive lookaround preserves it: `(?=X)` splits before `X`, and `(?<=X)` splits after it.
 
-### Token
+Patterns can be up to **500 characters**. Negative lookaround, backreferences, and repeat counts above **1,000** are unsupported. Positive lookaround is supported.
 
-Fixed-size sliding window aligned to word boundaries. No awareness of paragraphs or sentences.
+### Strict boundaries
 
-LlamaIndex provides the same as `TokenTextSplitter`. Useful when downstream processing requires uniform chunk sizes; otherwise prefer Text or Sentence.
+Enable **Each match is its own chunk (don't merge)** under **Chunk Boundaries** to keep each nonempty segment separate:
 
-### Regex
+- Adjacent segments are not merged.
+- Overlap is disabled.
+- Oversized segments produced by a successful split are divided at word boundaries.
 
-Splits on every match of a regex pattern you supply, then packs splits up to the chunk size by default — the same merge behavior as every other chunker. A precise boundary regex like `(?=\n\s*\{\s*"id"\s*:)` will still produce chunks containing multiple matches if those matches are small enough to fit together. This is standard across LangChain, LlamaIndex, Chonkie, and [Unstructured](https://docs.unstructured.io/api-reference/partition/chunking-documents).
+The checkbox refers to the segments separated by matches, not to returning only the matched delimiter text.
 
-Use Regex when your content has explicit delimiters that don't fit any other strategy.
+For example, given:
 
-#### Strict boundaries
+```text
+Question: How long do refunds take?
+Answer: Refunds are issued within 14 days.
 
-The regex strategy has an opt-in **"Each match is its own chunk (don't merge)"** checkbox. When enabled:
+Question: Where can I find invoices?
+Answer: Open Billing in workspace settings.
+```
 
-- Every regex match becomes its own chunk
-- Adjacent splits are not packed together
-- Overlap is disabled
-- Splits that exceed the chunk size are still sub-split at word boundaries
+Use this pattern to split before the next question while retaining its label:
 
+```text
+(?=\nQuestion:)
+```
 
+With strict boundaries enabled, each question-and-answer segment is separate, provided it fits the size target. Check the generated chunks to confirm the pattern matches your actual source.
 
-Turn it on when each match is a discrete record (one QA pair, one log entry) and you need each isolated for retrieval.
+### If the pattern does not split
+
+The prose splitters normalize text before splitting:
+
+- `\r\n` and lone `\r` become `\n`.
+- Three or more newlines become `\n\n`.
+- Tabs become spaces, and repeated spaces collapse to one.
+
+Adjust patterns that depend on the original whitespace. In non-strict mode, content that already fits the size target returns as one chunk without applying the pattern. If an oversized document produces no splits, non-strict mode falls back to word boundaries; strict mode returns it as a single chunk. Fix the pattern before relying on strict record boundaries.
 
 ## One record per chunk
 
-Each record (each QA pair, each log line, each row) as its own chunk is structural chunking, not regex chunking. Two paths:
+For structured input, JSONL makes record boundaries explicit:
+
+```json title="records.jsonl"
+{"id":"refunds","question":"How long do refunds take?","answer":"Within 14 days."}
+{"id":"invoices","question":"Where can I find invoices?","answer":"In Billing settings."}
+```
 
-1. **Convert to JSONL** (one record per line) and upload. Sim's Auto strategy treats it as structured data and never splits a record mid-way. Small records may still be batched together up to the chunk size. Lowering the size reduces batching; use strict Regex boundaries when each match must become its own chunk. See [LlamaIndex's `JSONNodeParser`](https://docs.llamaindex.ai/en/stable/module_guides/loading/node_parsers/) and [Unstructured's element-based chunking](https://docs.unstructured.io/api-reference/partition/chunking-documents).
+Auto can batch these small records into one chunk. Lowering Max Chunk Size reduces batching, but records that exceed the target can still be split. Use strict Regex boundaries when each delimited segment must stay separate, subject to its oversized-segment behavior.
 
-2. **Use Regex with strict boundaries enabled** when you can't restructure the source.
+Structural parsing is useful for nested records and escaped values. It does not guarantee recovery of malformed entries; inspect parsing errors and the resulting chunks.
 
-Prefer option 1. Structural parsers handle nested records, escaped delimiters, and malformed entries that regex won't.
+## Change settings on an existing base
 
-## Further reading
+The UI selects the strategy at creation and displays existing chunking settings as read-only. To use a different strategy through the UI, create a base with that strategy and upload the documents again.
 
-- [LangChain — Text Splitters](https://python.langchain.com/docs/concepts/text_splitters/)
-- [LlamaIndex — Node Parsers](https://docs.llamaindex.ai/en/stable/module_guides/loading/node_parsers/)
-- [Chonkie](https://github.com/chonkie-inc/chonkie)
-- [Unstructured — Chunking](https://docs.unstructured.io/api-reference/partition/chunking-documents)
-- [Pinecone — Chunking Strategies](https://www.pinecone.io/learn/chunking-strategies/)
+The [Update knowledge base API](/api-reference/knowledge-bases/updateKnowledgeBase) can change the sizes, overlap, strategy, and strategy options. It replaces the configuration object rather than merging it: read the current configuration, change the intended fields, and send back every setting you want to retain. Omitted size fields take their defaults, and an omitted strategy uses Auto. Changed settings apply to later document processing; existing chunks are not automatically rebuilt.
 
-## FAQ
+## Related docs
 
-<FAQ items={[
-  { question: "What does overlap actually do?", answer: "Overlap repeats tokens from the end of one chunk at the start of the next, so a query spanning a chunk boundary can still match. Higher values increase storage and may surface duplicate hits in search." },
-  { question: "Can I change the chunking strategy on an existing knowledge base?", answer: "No. Chunking config is set at creation. To change it, create a new knowledge base and re-upload your documents." },
-  { question: "Why isn't my regex producing any splits?", answer: "Sim normalizes content before splitting: \\r\\n becomes \\n, runs of three or more newlines collapse to \\n\\n, and tabs become spaces. Patterns that depend on those characters won't match. Also: in non-strict mode, content that fits within the chunk size returns as a single chunk regardless of matches — enable strict boundaries to force splits." },
-]} />
+- [Debugging retrieval](/knowledgebase/debugging-retrieval) — decide whether the problem comes from chunk boundaries.
+- [Using a knowledge base in a workflow](/knowledgebase/using-in-workflows) — inspect retrieved content and order.
+- [Knowledge Base](/knowledgebase) — supported uploads and processing.
diff --git a/apps/docs/content/docs/knowledgebase/connectors.mdx b/apps/docs/content/docs/knowledgebase/connectors.mdx
index aa2f2e03144..905b61ac805 100644
--- a/apps/docs/content/docs/knowledgebase/connectors.mdx
+++ b/apps/docs/content/docs/knowledgebase/connectors.mdx
@@ -1,225 +1,234 @@
 ---
 title: Connectors
-description: Automatically sync documents from external sources into your knowledge base
+description: Sync external documents into a knowledge base and manage their access and lifecycle.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
-import { Image } from '@/components/ui/image'
-import { FAQ } from '@/components/ui/faq'
 
-For organization Search with each person's source permissions, use the [Search connector guides](/search). This page covers connectors inside general knowledge bases.
+Connectors sync documents from external services into a knowledge base. New content is indexed, changed content is reprocessed, and content removed from the selected source scope leaves search after reconciliation.
 
-Connectors continuously sync documents from external services into your knowledge base, so you never have to upload files manually. New content is added, changed content is re-processed, and deleted content is removed — all automatically.
+This guide covers indexed knowledge bases. [Organization Search](/search) has its own live-provider catalog and queries supported providers on demand; adding a knowledge-base connector does not enable it there.
 
-This page covers indexed workspace knowledge bases. [Organization Search](/search) has a separate live-provider catalog and queries its supported providers on demand; adding a knowledge-base connector does not automatically enable it in Search.
+## Choose a connection method
 
-## Available Connectors
+Creating a connection requires workspace write access. For supported providers, **Connection method** controls who can search imported documents:
 
-<Image src="/static/connectors/connectors-sources.png" alt="The current Connect Source picker showing searchable connectors including Airtable, Asana, Ashby, Azure DevOps, Bitbucket, Box, and ClickUp" width={750} height={680} className="mx-auto h-auto w-full max-w-md" />
+| Method | Access |
+| --- | --- |
+| **Workspace** | Everyone with access to the workspace can search the synced documents. The connection does not mirror each person's source permissions. |
+| **Member accounts** | Members sync through their connected accounts; source access determines which documents they can read. |
+| **Admin or service account** / **Service account** | An administrative credential syncs content and supported source permissions. |
 
-Sim ships with 66 built-in connectors:
+The available methods depend on the provider and deployment configuration. A workspace Admin must configure permission-aware methods or switch a connection out of Workspace mode. The [Search source guides](/search) explain provider-specific permission setup.
 
-| Category | Connectors |
-|----------|-----------|
-| **Productivity** | Coda, Notion, Confluence, Asana, Linear, Jira, Jira Service Management, Monday, Trello, ClickUp, Google Calendar, Google Sheets, Google Forms, Microsoft Excel, Typeform |
-| **Cloud Storage** | Google Drive, Dropbox, OneDrive, SharePoint, Box, Amazon S3, SFTP |
-| **Documents** | Google Docs, Google Slides, Mintlify, WordPress, Webflow, DocuSign |
-| **Development** | GitHub, GitLab, Bitbucket, Azure DevOps, Sentry |
-| **Communication** | Slack, Discord, Microsoft Teams, Google Chat, Reddit, X, YouTube |
-| **Email** | Gmail, Outlook |
-| **CRM** | HubSpot, Salesforce |
-| **Support** | Intercom, ServiceNow, Zendesk, Zoho Desk |
-| **Incident Management** | incident.io, Rootly, PagerDuty |
-| **Data** | Airtable, Databricks |
-| **Note-taking** | Obsidian |
-| **Meetings** | Zoom, Google Meet, Gong, Grain, Granola, Fathom, Fireflies, Circleback |
-| **Recruiting** | Greenhouse, Ashby |
-| **HR** | Workday Help |
-| **Compliance** | Google Vault |
-
-## Adding a Connector
-
-From inside a knowledge base, click **+ New connector** in the top right to open the connector picker. Select a service, then complete the setup steps:
+For GitLab in Workspace mode, a PAT with `read_api` and access to the selected project is enough. The administrator-token and non-admin CSV permission paths apply to its permission-aware method; see [GitLab](/search/gitlab).
+
+## Create a connection
+
+Open a knowledge base, choose **New connector**, and select the service.
 
 <Steps>
 <Step>
 
 ### Authenticate
 
-Most connectors use **OAuth** — select an existing credential from the dropdown or click **Connect new account** to authorize through the service. Tokens are refreshed automatically.
-
-Other connectors use **API keys** or **personal access tokens** instead. The setup modal tells you which credential each connector expects — for example:
-
-| Connector | Where to get the key |
-|-----------|---------------------|
-| **Obsidian** | Install the [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin, then copy the key from its settings |
-| **Coda** | API token from Account settings → API connections, saved as a Coda service account credential |
-| **Fireflies** | Generate from the Integrations page in your Fireflies account |
-| **Typeform** | Personal access token from your Typeform account settings |
-| **Azure DevOps** | Personal access token with Wiki (Read), Work Items (Read), and Code (Read) scopes |
-| **GitLab** | Personal access token with `read_api` scope and access to the selected project |
-| **YouTube** | YouTube Data API key from the Google Cloud Console |
-| **Amazon S3** | Secret Access Key (the Access Key ID, region, and bucket are entered as config fields) |
-| **Sentry** | Auth token with `project:read` and `event:read` scopes |
-| **PagerDuty** | REST API key from Integrations → API Access Keys |
-| **SFTP** | Password or unencrypted private key, plus a required SHA-256 host key fingerprint (host, port, username, and root path are entered as config fields) |
-| **Mintlify** | API key — optional for public documentation sites, which sync from `llms.txt` |
-| **Databricks** | Personal access token from your workspace's user settings (the workspace host is entered as a config field) |
-| **Workday Help** | Register an API client for integrations in your tenant, then enter the client secret and refresh token together as `clientSecret:refreshToken` (the client ID, tenant host, and tenant name are entered as config fields) |
-
-Enter an API key directly, or type `{{` to select an accessible personal or workspace secret. Sim resolves the secret when you connect and stores an encrypted copy of the token. Later changes to the secret do not automatically update the connector.
+For OAuth, select an accessible credential or choose **Connect &lt;service&gt; account**. The account picker can offer **Connect another &lt;service&gt; account** when accounts already exist. OAuth tokens refresh automatically while the grant remains valid.
 
-<Callout type="info">
-  If you rotate an API key in the external service, update it in Sim as well — OAuth tokens refresh automatically, but API keys do not.
-</Callout>
+API-key and personal-access-token connections use the credential shown in their setup field. These examples identify the credential and any required companion fields:
 
-For GitLab in a regular knowledge base, a project-readable PAT is enough. Imported content uses the knowledge base's access rules; it does not mirror each person's GitLab permissions. The administrator-token and non-admin CSV setup paths apply when using [GitLab source permissions](/search/gitlab).
+| Connector | Credential or prerequisite |
+| --- | --- |
+| Obsidian | Install the [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin and copy its API key from the plugin settings. |
+| Coda | Generate an [API token](https://help.coda.io/hc/en-us/articles/39763414725389-Manage-your-Coda-account-settings) under **Account settings → API settings**; save it as a Coda service account credential. |
+| Fireflies | Copy the API key from **Settings → Developer settings** ([setup guide](https://guide.fireflies.ai/articles/3737786777-learn-about-fireflies-api)). |
+| Typeform | Generate a [personal access token](https://help.typeform.com/hc/en-us/articles/13599952215572-Typeform-API-personal-access-token) under **Your settings → Personal tokens**. |
+| Azure DevOps | PAT with Project and Team Read, Wiki Read, Work Items Read, and Code Read. |
+| GitLab | PAT with `read_api` and access to the selected project; permission-aware methods have additional requirements. |
+| YouTube | YouTube Data API key from Google Cloud Console. |
+| Amazon S3 | Secret Access Key; enter Access Key ID, region, and bucket as configuration fields. |
+| Sentry | Auth token with `project:read` and `event:read`. |
+| PagerDuty | Create a [REST API key](https://support.pagerduty.com/main/docs/api-access-keys) under **Integrations → Developer Tools → API Access Keys**. |
+| SFTP | Password or unencrypted private key, plus a required SHA-256 host-key fingerprint; enter host, port, username, and root path as configuration fields. |
+| Mintlify | Access Token only when the documentation site needs a bearer token. Public sites can sync from `llms.txt` without one. |
+| Databricks | Create a [personal access token](https://docs.databricks.com/aws/en/dev-tools/auth/pat) under **Settings → Developer → Access tokens → Manage**; enter the workspace host separately. |
+| Workday Help | Register an API client for integrations and enter `clientSecret:refreshToken`; configure client ID, tenant host, and tenant name separately. |
+
+Enter a key directly or type `{{` to select an accessible secret. A reference must be the whole value, such as `{{SOURCE_API_KEY}}`. Sim resolves it at setup and stores an encrypted token snapshot. Updating the secret later does not update that connection.
+
+If an OAuth grant is revoked, reconnect the account. API keys and PATs do not refresh automatically; a rotated directly entered key needs a replacement connection using the new key. For credentials managed as connected accounts or service accounts, update the credential through its supported account flow. Review the removal options for the old connection before replacing it.
 
 </Step>
 <Step>
 
-### Configure
-
-Each connector has source-specific fields that control what gets synced. Examples:
+### Configure the source
 
-- **Notion** — sync an entire workspace, a specific database, or a single page tree
-- **GitHub** — specify a repository, branch, and optional file extension filter
-- **GitLab** — specify a project path or ID and your instance host (leave blank for GitLab.com), then choose repository files, wiki pages, issues, or merge requests. Each connector syncs one project; submodules need their own connectors.
-- **Confluence** — enter your Atlassian domain and choose spaces, or **All** for all spaces accessible at each sync. Optionally filter by content type or label. PDF, Word (`.docx`, Word 97–2003 `.doc`), Excel (`.xlsx`), and PowerPoint (`.pptx`) attachments on matching pages and blog posts are included as separate documents, and so are PNG, JPEG, WebP, and GIF images when **Image Attachments** is on.
-- **Azure DevOps** — choose what to sync (wiki pages, work items, repository files, or all), with optional work item type/state filters, a custom WIQL query, and repository/branch/path filters
-- **Amazon S3** — point at a bucket with an optional key prefix and a customizable file extension allowlist; S3-compatible stores (Cloudflare R2, MinIO) are supported via a custom endpoint
-- **YouTube** — sync a channel (by `@handle` or ID) or playlist, with an optional published-after date filter and the option to exclude Shorts
-- **Sentry** — filter issues by search query (e.g. `is:unresolved`), environment, and time window; self-hosted Sentry is supported via a custom host
-- **Obsidian** — provide your vault URL (`https://127.0.0.1:27124` by default) and optionally restrict to a folder path
-- **Fireflies** — optionally filter by host email or cap the number of transcripts synced
+Fill in the service's source fields. Examples:
 
-Configuration is validated on save — if a repository doesn't exist or a domain is unreachable, you'll see an error immediately.
+- **Notion:** choose a workspace, database, or page tree.
+- **GitHub:** specify a repository, branch, and optional file-extension filter.
+- **GitLab:** select one project by path or ID and an instance host, or leave the host blank for GitLab.com in Workspace mode. Choose repository files, wiki pages, issues, or merge requests. Submodules need separate connections.
+- **Confluence:** enter the Atlassian site and select spaces, or **All** for spaces accessible at each sync. Filter by content type or label if needed. See [Confluence attachments](#confluence-attachments) for files and images.
+- **Azure DevOps:** choose wiki pages, work items, repository files, or all. Optional fields include work-item type/state, a WIQL query, and repository/branch/path filters.
+- **Amazon S3:** choose a bucket, optional key prefix, and file-extension allowlist. A custom endpoint supports S3-compatible stores such as Cloudflare R2 or MinIO.
+- **YouTube:** choose a channel by `@handle` or ID, or a playlist. Optional filters include published-after date and **Exclude Shorts**, which skips videos shorter than 60 seconds.
+- **Sentry:** set a query such as `is:unresolved`, environment, or time window. A custom host supports self-hosted Sentry.
+- **Obsidian:** enter the vault URL and, optionally, a folder path. The plugin's local default is `https://127.0.0.1:27124`.
+- **Fireflies:** optionally filter by host email or cap the transcript count.
 
-Confluence attachment indexing requires `read:attachment:confluence`. For a service account, include it when creating the scoped API token; see the [Confluence scope list](/search/confluence#using-a-service-account). Attachments are checked even when the parent page has not changed. Files over 100 MB appear as skipped; convert Word 6/95 files to `.docx`, and `.xls` and `.ppt` files to `.xlsx` and `.pptx`, before attaching them. Spaces that were already connected pick up newly supported formats on their next sync.
+<Callout type="info">
+Sim Cloud cannot connect to localhost or private-network vault URLs. An Obsidian connection needs an allowed public HTTPS endpoint. On self-hosted deployments, the vault must be reachable from the Sim server and allowed by its [outbound-network policy](/platform/self-hosting/security#the-ssrf-boundary).
+</Callout>
 
-Each image is read once by a vision model, which writes out what it holds: a table becomes one line per row with its column headers, a scan becomes its full text, and a screenshot or diagram becomes its visible text plus a description of what it shows. That text is what search finds. Logos, icons, and other decorative images are kept as documents but have nothing to search, so they show 0 chunks. Images under 2 KB, SVG, and HEIC files are not indexed. Image reading uses a Gemini key: the workspace's own key when one is added, otherwise the platform's, and each image is billed as a model call. Without any Gemini key, images are left out of the sync until one is added. One sync reads at most 500 new or changed images, and the rest are picked up by the next sync; a full resync does not read unchanged images again. New Confluence connectors read images by default. Connectors created before image support keep images off until you set **Image Attachments** to **Read with AI** in the connector's settings; the next sync then reads them. To stop indexing images, set it to **Don't index**: the next sync removes the images already indexed, and switching back reads them again, billed per image.
+Sim validates source configuration when saving. A missing repository, inaccessible source, or invalid configuration can fail setup; permission-aware member syncing can also discover per-account failures during a later sync.
 
 </Step>
 <Step>
 
-### Choose sync frequency
+### Choose the sync frequency
 
-| Frequency | Notes |
-|-----------|-------|
-| Every hour | Best for fast-moving sources |
-| Every 6 hours | Good balance for most sources |
-| **Daily** (default) | Suitable for content that changes infrequently |
-| Weekly | For stable, rarely-updated sources |
-| Manual only | Sync only when you trigger it manually |
+| **Sync Frequency** | Interval |
+| --- | --- |
+| **Live** | Every 5 minutes. |
+| **Every hour** | Every 60 minutes. |
+| **Every 6 hours** | Every 360 minutes. |
+| **Daily** | Every 1,440 minutes; the default. |
+| **Weekly** | Every 10,080 minutes. |
+| **Manual only** | No scheduled content sync; use **Sync now**. |
 
-Sub-hourly frequencies require a Max or Enterprise plan.
+Sub-hourly syncing requires usable Max or Enterprise access on hosted workspaces with billing enabled. Self-hosted or billing-disabled workspaces do not have that plan gate.
+
+Permission-aware methods can check permissions hourly even when the content schedule is longer. With Manual only, documents can become unavailable after 24 hours without a successful permission check. Read the schedule hint shown for the selected connection method.
 
 </Step>
 <Step>
 
-### Configure metadata tags (optional)
+### Select metadata tags
+
+If the connector exposes **Metadata tags**, uncheck fields you do not need. Setup enables them by default. For example, Notion can populate Labels and Last Modified; GitHub can populate Repository and File Path.
 
-If the connector supports metadata tags, you'll see checkboxes for each available tag type (e.g., Labels, Last Modified, Notebook). All are enabled by default — uncheck any you don't need.
+Tags share the base's [17-slot capacity](/knowledgebase/tags). Compatible existing definitions can be reused; new ones consume slots. When capacity is exhausted, some metadata can be omitted, or setup can fail if none of the selected tags can be mapped. Uncheck optional fields or review existing definitions before retrying.
 
-Tag slots are shared across all documents in a knowledge base. See [Tags](/knowledgebase/tags) for details.
+Choose tags before connecting: the Settings tab does not offer a metadata-tag editor, and changing source configuration does not automatically free existing definitions' slots.
 
 </Step>
 <Step>
 
-### Connect & Sync
+### Connect and verify
+
+Choose **Connect & Sync** to save the connection and queue its first sync. Documents appear as they are fetched and processed; they become searchable only after indexing completes and the caller has access.
 
-Click **Connect & Sync** to save the connector and trigger the first sync. Documents will start appearing as they're processed.
+Open **Connected Sources** to check the connection's status and sync history. If the initial sync could not be queued, follow its error and start **Sync now** after correcting the cause.
 
 </Step>
 </Steps>
 
-## Managing Connectors
-
-Open **Connected Sources** from the knowledge base to see all active connectors. Each card shows the connector's status, the last sync time and document count, and the next scheduled sync:
-
-<Image src="/static/connectors/connectors-sync-history.png" alt="Connected Sources panel showing a Google Docs connector with Active status, last sync details, and a sync history log with dated entries" width={800} height={466} className="mx-auto h-auto w-full max-w-xl" />
+## Manage a connection
 
-The action buttons on each connector card:
+**Connected Sources** shows the connected service, status, document count, and available last/next sync details. Open **Connection actions** for:
 
-| Button | Action |
-|--------|--------|
-| **↻** (Refresh) | Trigger a manual sync immediately. Disabled while syncing or disabled; a 5-minute cooldown applies after each manual trigger |
-| **⚙** (Settings) | Open the edit modal to change source config or sync frequency |
-| **⏸ / ▶** (Pause / Resume) | Pause scheduled syncs without removing the connector. Resume works from both paused and disabled states |
-| **🗑** (Delete) | Remove the connector. A confirmation modal appears with an option to also delete all synced documents |
-| **∨** (Chevron) | Expand to show sync history |
+| Action | Effect |
+| --- | --- |
+| **Sync now** | Queue a manual sync. Unavailable while queued or syncing; resume paused or disabled connections first. |
+| **Settings** | Edit source configuration or sync frequency and open the Documents tab. |
+| **Pause syncing** / **Resume syncing** | Stop or resume scheduled syncing. A paused connection must be resumed before a manual sync. |
+| **Sync history** / **Hide history** | Show or hide recent sync runs. |
+| **Remove connection** | Stop syncing and remove the connection, subject to its document-removal options. |
 
-### Editing a Connector
+After a healthy sync completes with no failed documents, a **one-minute cooldown** applies before another manual sync. Error recovery and failed runs bypass that cooldown.
 
-Click the settings icon to open the edit modal. It has two tabs:
+Before removing a connection, review its document consequence. In Workspace mode, **Also delete synced documents** is optional; otherwise the documents remain as plain documents. Permission-aware connections require deletion of their synced documents when removed. Logical removal can finish before physical storage cleanup completes.
 
-**Settings** — change any source-specific config fields (e.g., switch the GitHub branch) and update the sync frequency.
+### Sync history
 
-**Documents** — browse all documents this connector has synced and manage exclusions (see [Excluding Documents](#excluding-documents) below).
+History shows the latest **10 runs**, with time, state, document-change counts, and error or notice details. Counts identify documents added, updated, deleted, failed, or skipped; **No changes** means no content changes were recorded.
 
-### Sync History
+**In progress…** means work is running. **Continuing** can mean a large listing is resuming across runs rather than failing. **Partial**, **Failed**, or **Interrupted** entries need their accompanying notice or error inspected. Member-account connections also report member sync progress and accounts that need reconnecting.
 
-Expand any connector card by clicking the chevron to see a log of recent syncs:
+## Exclude documents
 
-- Each row shows the date/time and a summary of what changed: **+N** (added, green), **~N** (updated, amber), **-N** (deleted, red), **!N** (failed, red), or **No changes**
-- A spinner indicates a sync currently in progress
-- Error rows show a red icon and the failure message
+1. Open **Settings** for the connection and select **Documents**.
+2. Use the document-status picker to inspect **Included**, **Excluded**, **Failed**, or **Skipped** documents.
+3. Select **Exclude** on a document to remove it from search and skip it on later syncs, even if the source changes.
 
-The log retains the most recent 10 sync runs.
+To reverse this, select **Excluded** and choose **Restore**. Retained completed content can become available again; the next sync refreshes it from the source. For failed or skipped documents, read the reason and fix the source or configuration. Retry failed documents when offered, or sync again after correcting skipped source content.
 
-## Excluding Documents
+## Sync behavior and recovery
 
-Sometimes a connector syncs documents you don't want in your knowledge base — drafts, templates, confidential pages, and so on. You can exclude them individually.
+A sync lists the selected source scope and compares it with stored content. New documents are processed; changed documents are re-chunked and re-embedded. Unchanged content usually avoids re-indexing, although the source may still be listed or read to verify changes and permissions.
 
-<Image src="/static/connectors/connectors-excluded.png" alt="Edit Google Docs modal showing the Documents tab with Active (37) and Excluded (0) filter buttons and a 'No excluded documents' message" width={800} height={774} className="mx-auto h-auto w-full max-w-md" />
+A base can have multiple connections. Each owns its documents, and a Knowledge block can search their combined content within the caller's access. Their metadata definitions share the same tag slots.
 
-To exclude a document, open the connector's settings modal, go to the **Documents** tab, and click **Exclude** next to any document. Excluded documents are skipped on every subsequent sync even if the source content changes.
+### Content removed from the source scope
 
-To reverse an exclusion, switch to the **Excluded** tab and click **Restore** — the document will be pulled in on the next sync.
+Content deleted or removed from the selected source view leaves search after a successful reconciliation. Examples include:
 
-## How Syncing Works
+- Archived Confluence pages or Webflow CMS items.
+- Asana tasks whose projects are all archived; a task still reachable through an active project remains included.
+- Retired ServiceNow articles when no explicit workflow-state selection overrides the default.
+- Files in Google Drive trash or Outlook messages in Deleted Items.
+- Canceled incident.io incidents under the default filter; **All (including canceled)** or an explicit selection can include them.
 
-On each run the connector fetches documents from the source and compares them against what's already stored. Only changed documents are reprocessed — new content is added, updated content is re-chunked and re-embedded, deleted content is removed. A connector syncing thousands of documents will only do real work when something actually changes.
+An incomplete source listing keeps unlisted documents instead of treating them all as deleted. Incremental listings also do not prove that an unlisted item was removed. Restoring content at the source makes it eligible for a later sync; its document ID is not guaranteed to change.
 
-### Content Removed From View
+### Statuses
 
-Content that still exists at the source but is no longer current is treated the same as deleted, and is removed from your knowledge base. This covers an archived Confluence page, a task in an archived Asana project, an archived Webflow CMS item, a retired ServiceNow knowledge article, a spreadsheet in the Google Drive trash, a message moved to Outlook's Deleted Items, and a cancelled incident.io incident.
+| Status | Meaning |
+| --- | --- |
+| **Active** | Available for its schedule or manual sync. |
+| **Pending** | A sync is queued. |
+| **Syncing** | A sync is in progress. |
+| **Paused** | Syncing is suspended; resume before starting another run. |
+| **Error** | A sync failed. Read the error; scheduled retries use backoff. |
+| **Disabled** | Syncing requires intervention, including after 10 consecutive full-sync failures. |
 
-This keeps agents from citing content your team has already retired. Restoring the item at the source brings it back on the next sync as a new document.
+A single-document failure can leave the rest of the sync running. Transient failures can be retried; unsupported or invalid content needs a source/configuration change. Read the Documents filters and history to distinguish failed indexing from a failed source listing.
 
-### Connector Status
+Full-sync failures increase the retry delay. After **10 consecutive failures**, the connection is disabled. Correct the source or credential issue, reconnect an invalid OAuth grant when needed, and choose **Resume syncing**. Resume alone does not repair a revoked credential.
 
-| Status | Meaning |
-|--------|---------|
-| **Active** | Running normally on schedule |
-| **Syncing** | A sync is currently in progress |
-| **Paused** | Scheduled syncs are suspended; manual sync is still available |
-| **Error** | The last sync failed; will retry on the next scheduled run with backoff |
-| **Disabled** | Syncing has been paused automatically after 10 consecutive failures |
+## Confluence attachments
 
-A disabled connector requires intervention — either reconnect the OAuth account or use the Resume button to re-enable syncing.
+Matching pages and blog posts include PDF, Word (`.docx` and Word 97–2003 `.doc`), Excel (`.xlsx`), and PowerPoint (`.pptx`) attachments as separate documents. Attachment indexing requires `read:attachment:confluence`; include it in a service account's scoped token. See [Confluence setup](/search/confluence#using-a-service-account).
 
-### Handling Failures
+Attachments are checked even when the parent page is unchanged. Files over **100 MiB** appear as skipped. Convert Word 6/95 files to `.docx`, `.xls` to `.xlsx`, and `.ppt` to `.pptx`. Existing connections pick up supported attachments on later syncs.
 
-If a single document fails (e.g., a permission issue or timeout), the sync continues and retries that document next time. If an entire sync fails, the connector backs off and retries with increasing delays. After 10 consecutive full-sync failures the connector is automatically set to **Disabled** to avoid spinning indefinitely.
+### Image attachments
 
-## Metadata Tags
+**Image Attachments → Read with AI** converts PNG, JPEG, WebP, and GIF attachments into searchable text. GIF extraction uses the first frame. Tables become rows with headers, scans become extracted text, and diagrams or screenshots include visible text and a description. Decorative images remain documents with zero chunks.
 
-Connectors can auto-populate [tags](/knowledgebase/tags) with metadata from the source — for example, a Notion connector can tag documents with their Labels and Last Modified date; a GitHub connector can tag documents with Repository and File Path. These tags are then available for filtered search in the Knowledge block.
+Images smaller than **2 KiB**, SVG, HEIC, and AVIF files are not indexed through this image path. It needs a Gemini key: an available workspace key first, otherwise the deployment's key. Without a key, images are deferred until one is configured.
 
-You can disable specific tag types during setup or at any time from the connector settings to free up tag slots for manual tagging or other connectors.
+New knowledge-base Confluence connections enable image reading by default. Connections created before image support keep it off until you choose **Read with AI**; their next sync then indexes images.
 
-<Callout type="info">
-  Tag slots are shared across all documents in a knowledge base. If multiple connectors each populate tags, they draw from the same pool of 17 slots.
-</Callout>
+The default admission limit is **500 new or changed images per sync**. Remaining images wait for another sync. Self-hosted operators can configure `KB_IMAGE_EXTRACTIONS_PER_SYNC`. Unchanged images reuse their extraction, including during a full resync; transient or malformed responses can cause additional model requests.
 
-## Multiple Connectors
+Image extraction follows [model billing](/platform/costs): BYOK usage is billed by the provider, while platform-key usage follows the deployment's Sim billing policy. Choose **Don't index** to stop image indexing; the next sync removes indexed images. Switching back processes them again and incurs the applicable model usage.
 
-<Image src="/static/connectors/connectors-list.png" alt="Knowledge base document list showing synced Google Docs documents with Name, Size, Tokens, Chunks, Uploaded date, Status, and Tags columns" width={800} height={189} />
+## Available connectors
 
-You can add as many connectors as you need to a single knowledge base. Each manages its own documents independently, and all content is searchable together through the Knowledge block. Keep tag slot usage in mind when combining connectors that each populate metadata tags.
+The source picker lists the available services. Built-in connectors include:
 
-<FAQ items={[
-  { question: "Do I need to re-authenticate connectors?", answer: "OAuth connectors refresh tokens automatically. API key and personal access token connectors need manual updates if you rotate the credential in the external service." },
-]} />
+| Category | Connectors |
+| --- | --- |
+| Productivity | Coda, Notion, Confluence, Asana, Linear, Plane, Jira, Jira Service Management, Monday, Trello, ClickUp, Google Calendar, Google Sheets, Google Forms, Microsoft Excel, Typeform |
+| Cloud storage | Google Drive, Dropbox, OneDrive, SharePoint, Box, Amazon S3, SFTP |
+| Documents | Google Docs, Google Slides, Mintlify, WordPress, Webflow, DocuSign |
+| Development | GitHub, GitLab, Bitbucket, Azure DevOps, Sentry |
+| Communication | Slack, Discord, Microsoft Teams, Google Chat, Reddit, X, YouTube |
+| Email | Gmail, Outlook |
+| CRM | HubSpot, Salesforce |
+| Support | Intercom, ServiceNow, Zendesk, Zoho Desk |
+| Incident management | incident.io, Rootly, PagerDuty |
+| Data | Airtable, Databricks |
+| Note-taking | Obsidian |
+| Meetings | Zoom, Google Meet, Gong, Grain, Granola, Fathom, Fireflies, Circleback, Otter |
+| Recruiting | Greenhouse, Ashby |
+| HR | Workday Help |
+| Compliance | Google Vault |
+
+## Related docs
+
+- [Tags and filtering](/knowledgebase/tags) — definitions, slot capacity, and operators.
+- [Debugging retrieval](/knowledgebase/debugging-retrieval) — verify indexed content and access.
+- [Using a knowledge base in a workflow](/knowledgebase/using-in-workflows) — retrieve synced passages.
+- [Organization Search](/search) — live providers and permission-aware source setup.
diff --git a/apps/docs/content/docs/knowledgebase/debugging-retrieval.mdx b/apps/docs/content/docs/knowledgebase/debugging-retrieval.mdx
index 84908c1839f..1e4166872cf 100644
--- a/apps/docs/content/docs/knowledgebase/debugging-retrieval.mdx
+++ b/apps/docs/content/docs/knowledgebase/debugging-retrieval.mdx
@@ -1,84 +1,91 @@
 ---
 title: Debugging retrieval
-description: Why a Knowledge block search returns no results, wrong results, or duplicates, and how to fix each one.
+description: Check missing, irrelevant, or duplicate Knowledge block results.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
+Inspect the Knowledge block's output in [Logs](/logs-debugging) before changing the Agent's prompt. Check which chunks came back, whether they answer the question, and which documents they came from.
 
-A [Knowledge block](/integrations/knowledge) search reads a query, embeds it as a vector, and returns the chunks of your documents that are closest to it. When the search misbehaves, it does so in one of three ways: it returns nothing, it returns the wrong chunks, or it returns the same content twice. Each one has a short list of causes you can check in the search results, in the document list, and in your tag filters.
+## Read the results
 
-## What a result looks like
+A search returns a `results` array. An empty array means no eligible chunk was returned. For a populated result, inspect:
 
-A search returns a `results` array. Each entry is one chunk of one document, with the fields you use to diagnose retrieval:
-
-| Field | What it is |
+| Field | What to check |
 | --- | --- |
-| `documentName` | The source document the chunk came from. |
-| `sourceUrl` | Where the document was uploaded or synced from (`null` for manual uploads). |
-| `content` | The chunk text that matched. |
-| `chunkIndex` | The chunk's position in the document (`0` is the first chunk). |
-| `similarity` | How close the chunk is to your query, `0` to `1` (higher is closer). |
-| `rerankerScore` | An optional relevance score, present only when [Cohere reranking](/integrations/knowledge) is on. |
-| `metadata` | The chunk's tag values, by their display names. |
+| `content` | Does the passage contain the answer and enough context to interpret it? |
+| `documentName`, `documentId` | Is this the intended source document? |
+| `sourceUrl` | Open the external source when available; uploaded files without an external source have `null`. |
+| `chunkIndex` | Find the passage within the document. Index `0` is the first chunk. |
+| `metadata` | Compare the document's tag values, keyed by display name, with your filters. |
+| `rank` | The result's one-based position in the returned order. |
+| `rankScore` | Retrieval score, or reranker score when reranking is applied. |
+| `similarity` | Cosine similarity to the query. It does not determine Hybrid or reranker ordering. |
+| `rerankerScore` | Present when a reranker applied its relevance ordering. |
 
-{/* VISUAL: two result panels side by side. Left: empty `results: []`. Right: one populated result object with documentName, content, chunkIndex, similarity 0.92, metadata, sourceUrl annotated. */}
+Read the content alongside the scores. A high similarity means the passage is close in meaning; it does not guarantee that it answers the question. There is no universal relevance cutoff across embedding models and document collections. Recency policy can also affect returned order, so use `rank` to read that order.
 
-The **similarity score** is the first thing to read. As a rough guide: above `0.8` is usually relevant, `0.6` to `0.8` is marginal, and below `0.6` is often noise. A search with a query always scores chunks this way. A tag-only search (filters, no query) returns every matching chunk with `similarity: 1`, because there's no query to measure distance against.
+Tag-only retrieval has no query to compare and returns `similarity: 1` for every match. It returns up to **Number of Results** without vector ranking.
 
 ## Empty results
 
-An empty `results` array means no chunk matched. There are three causes, listed here in the order worth checking.
-
-### The documents aren't ready
+### Check processing
 
-Only documents that finished processing are searchable. Every document carries a `processingStatus`, and the Knowledge block silently skips anything that isn't `completed`. A knowledge base full of half-processed documents looks empty even though the upload succeeded.
+Use **List Documents** to inspect `processingStatus`. Only `completed` documents are eligible for search:
 
-| `processingStatus` | Meaning | Searchable |
+| `processingStatus` | Meaning | Eligible for search |
 | --- | --- | --- |
-| `pending` | Queued, not started. | No |
-| `processing` | Being chunked and embedded. | No |
-| `completed` | Ready. | Yes |
-| `failed` | Chunking or embedding errored. | No |
+| `pending` | Queued for processing. | No |
+| `processing` | Text extraction, chunking, or embedding is in progress. | No |
+| `completed` | Processing finished. | Yes, if enabled, included, and accessible. |
+| `failed` | Processing failed. | No |
 
-{/* VISUAL: the four processingStatus states in a row, with a checkmark only on `completed`. */}
+An upload or sync request can succeed before indexing finishes. For `pending` or `processing`, wait and check the status again. For `failed`, inspect `processingError` with **Get Document**, fix the cause, and choose **Retry** from the document menu. Replace or re-upload the file when the error calls for different content or a supported format.
 
-Run the block's **List Documents** operation and check the status of each document. If a document is `pending` or `processing`, wait for it to finish. If it's `failed`, read its `processingError` (via **Get Document**) and re-upload. See [chunking strategies](/knowledgebase/chunking-strategies) for what happens during processing.
+The UI can also show **Skipped**, a separate indexing outcome for content that cannot be indexed safely. Read its reason. Decorative connector images can complete with zero chunks; they have no text to retrieve.
 
-### The query doesn't match the content
+### Check enabled state and access
 
-If your documents are `completed` but the search still returns nothing, the query may not be close to anything stored. Confirm the content actually exists: run **List Chunks** and read what's in the knowledge base. If the answer is there but the search misses it, the problem is wording, not data. Try a simpler query, or use a term that appears in the content. See [wrong results](#wrong-results-or-low-relevance) below for the deeper version of this.
+Confirm that both the document and its relevant chunks are enabled. **Update Chunk** with `enabled: false` removes a chunk from search without deleting it; connector-managed chunks are read-only.
 
-### Tag filters exclude everything
+Excluded, archived, or deleted documents do not appear in search. For connector documents, inspect whether they are included and whether the acting principal has current source access. A workspace-shared connection and a permission-aware connection can expose different document sets. See [Connectors](/knowledgebase/connectors).
 
-[Tag filters](/knowledgebase/tags) restrict the document set before the vector search runs, and they combine with AND logic: a document must match every filter to be searched. A filter like `Department equals 'engineering'` returns nothing if no document carries that tag value.
+### Check tag filters
 
-Check the tag values actually set on your documents (**Get Document** shows them), and confirm the filter value matches exactly. To rule filters out as the cause, remove them and search by query alone.
+[Tag filters](/knowledgebase/tags) combine with AND. `Department equals "engineering"` excludes documents without that value, and an additional date or status filter can exclude the remaining documents.
 
-## Wrong results or low relevance
+Use **Get Document** to inspect assigned values and **List Tags** to check definitions. Text matching is case-insensitive; other types need valid values. Remove filters temporarily and search by query alone to isolate the cause.
+
+Connector metadata uses the same tag slots as manual definitions. Check the definition and its actual values instead of assuming an available slot belongs to your manual tag.
 
-Wrong results are chunks that come back but don't answer the query, even though better content exists in the knowledge base. The vector search found something semantically near the query, but it wasn't near enough to be a good match. Read the `similarity` scores: a top result at `0.65` is the search telling you nothing good matched.
+### Check the stored content
+
+Use **List Chunks** for the expected document and read the text Sim indexed. If the answer is absent, update the uploaded content or the connector source. If it is present, try a more specific query and check the [retrieval mode](/knowledgebase/using-in-workflows#retrieval-mode).
+
+## Wrong results or low relevance
 
-Common causes:
+If chunks return but do not answer the question, work through these changes:
 
-- **The query relies on an exact term or identifier.** Semantic search can match paraphrases, but a product code or error ID may need literal matching. Try [Hybrid retrieval](/knowledgebase/using-in-workflows#retrieval-mode) and include the exact identifier in the query.
-- **Chunks are too large.** A 1,024-token chunk blends many topics into one embedding, so its score is diluted across all of them. Smaller chunks (256 to 512 tokens) often retrieve more precisely. See [chunking strategies](/knowledgebase/chunking-strategies).
-- **Context is split across a chunk boundary.** The sentence that answers the query sits in one chunk and the subject it refers to sits in the previous one, so neither chunk scores well on its own. Overlap during chunking reduces this.
+1. **Use the exact identifier.** For error codes, SKUs, or ticket keys, include the literal string and try **Hybrid (full-text + vector)**.
+2. **Narrow the scope.** Use a tag filter when the question belongs to a known department, date range, or document category. Check that the filter describes the intended content.
+3. **Retrieve more candidates.** Increase **Number of Results** if the useful passage falls outside the returned set.
+4. **Try reranking.** Enable **Rerank Results** when the initial set contains relevant passages but the order is unhelpful. Its advanced candidate-count setting can widen the second pass.
+5. **Inspect chunk boundaries.** Large chunks can mix topics; small ones can separate an answer from its subject or definition. Try a different size on representative content and compare the results. For example, evaluate 256–512-token chunks against the default 1,024-token setting rather than assuming one size suits every source.
 
-Two fixes that don't require re-chunking: narrow the search with a tag filter first so the vector search runs over fewer, more relevant documents, or turn on **Cohere reranking**. Reranking re-scores the initial vector results with a model tuned for relevance and adds a `rerankerScore` to each result. It's worth enabling when you see marginal results (`0.6` to `0.75`) that a human would call relevant. It costs one search unit per call and adds latency, and if the reranker is unavailable the search falls back to vector ordering automatically.
+Overlap can preserve context across adjacent chunks. Its default is 200 tokens for strategies that apply overlap. See [chunking strategies](/knowledgebase/chunking-strategies) before changing boundaries or reprocessing documents.
 
-<Callout type="info">
-A high `similarity` score is not a guarantee the chunk answers the query, only that it's close in meaning. Vet the top results yourself, or use reranking, before trusting a search to ground an agent's answer.
-</Callout>
+Reranking adds a model call and latency. Completed hosted-key calls are metered as one search unit; BYOK calls are billed by the provider. If the reranker is unavailable, the search retains its retrieval order and does not add `rerankerScore`. See [workflow retrieval](/knowledgebase/using-in-workflows) and [Costs](/platform/costs).
 
 ## Duplicates
 
-Duplicates are the same or near-identical content appearing more than once in `results`. Read the `documentName` and `chunkIndex` of the repeated entries to tell which case you have.
+Compare `documentId`, `documentName`, and `chunkIndex` on repeated results:
 
-- **Same document, adjacent `chunkIndex` values.** This is overlap. Chunking repeats some tokens between consecutive chunks (200 by default) to preserve context, so neighboring chunks share text and can both match. Lowering overlap reduces the repetition, at the cost of context at chunk boundaries. See [chunking strategies](/knowledgebase/chunking-strategies).
-- **Different `documentName`, identical content.** The same material was uploaded as two documents, or [synced from a connector](/knowledgebase/connectors) that holds it in more than one place. Consolidate the duplicate documents, or check the connector's source.
+- **Same document, adjacent chunk indexes:** overlap can make neighboring chunks share text and both match. Lower overlap to reduce repetition, then check whether queries still retrieve enough context.
+- **Different documents, identical content:** the material may have been uploaded twice or synced from multiple locations. Consolidate duplicate uploads or exclude the unwanted connector document.
 
-## Disabled chunks and claimed tag slots
+Do not sort Hybrid results by `similarity` to remove apparent ordering differences. Keep the returned order and inspect whether repeated chunks provide distinct context.
 
-A chunk can be disabled with the **Update Chunk** operation (`enabled: false`), which removes it from all searches without deleting it. A disabled chunk never appears in results, even when it's the best match. If a chunk you know is relevant is missing from a search, confirm it isn't disabled.
+## Related docs
 
-The same goes for tag slots when you use [connectors](/knowledgebase/connectors). Synced documents auto-populate tag values (a repository name, a last-modified date), and those occupy the same slots manual tags would. A filter that returns nothing can be filtering on a slot the connector already claimed.
+- [Using a knowledge base in a workflow](/knowledgebase/using-in-workflows) — settings and result fields.
+- [Chunking strategies](/knowledgebase/chunking-strategies) — sizes, overlap, and record boundaries.
+- [Tags and filtering](/knowledgebase/tags) — types and filter operators.
+- [Connectors](/knowledgebase/connectors) — source access, exclusions, and sync errors.
diff --git a/apps/docs/content/docs/knowledgebase/export-import.mdx b/apps/docs/content/docs/knowledgebase/export-import.mdx
index 3b1d1672f5a..0b151f397df 100644
--- a/apps/docs/content/docs/knowledgebase/export-import.mdx
+++ b/apps/docs/content/docs/knowledgebase/export-import.mdx
@@ -1,13 +1,40 @@
 ---
 title: Export
-description: Download a knowledge base as one archive of its documents, chunks, tags, and settings.
+description: Download a knowledge base's documents, chunks, tags, and settings in one archive.
 ---
 
-An **export** is a single archive that holds a knowledge base: every document, the chunks Sim split it into, the tag definitions and values, and the chunking settings. Use it to keep a copy of a base outside Sim.
+Export a knowledge base as a `.simkb.zip` archive. It carries the base's configuration, tag definitions and values, stored document files, and completed chunk text, with vectors included by default.
 
-To export, right-click a base in the knowledge base list and choose **Export**, or open the base and click the **Export** button in the header. The download is named `<base name>.simkb.zip`.
+## Access and scope
 
-## What the archive contains
+Export requires at least workspace read access and the **Knowledge Base Export** capability. Enterprise permission groups can restrict members' exports. The API accepts supported personal credentials or a workspace API key; OAuth callers need `api:read`. A workspace API key uses its workspace role and operation policy rather than a member's permission group. See [API authentication](/api-reference/authentication).
+
+The archive includes active, included documents readable by the workspace as a whole. It does not include every document a particular member can personally access through source permissions. Archived, deleted, and excluded documents are left out.
+
+Documents with neither a stored file nor completed chunks are omitted. A document still processing can contribute its stored file, but not unfinished chunk text. Disabled flags are preserved for documents and chunks that are included.
+
+## Download the archive
+
+Right-click a base in the knowledge base list and choose **Export**, or open the base and choose **Export** in its header. The download is named `<base name>.simkb.zip`.
+
+### API
+
+```http
+GET /api/v2/knowledge/{knowledgeBaseId}/export?workspaceId={workspaceId}&vectors=true
+```
+
+The response is the ZIP archive. Set `vectors=false` to leave out embeddings. See [Export knowledge base](/api-reference/knowledge-bases/exportKnowledgeBase) for the request contract.
+
+### CLI
+
+```bash
+sim knowledge export <knowledgeBaseId> --output-file kb.zip
+sim knowledge export <knowledgeBaseId> --output-file kb.zip --no-vectors
+```
+
+The CLI uses the selected workspace profile. An existing output file requires `--force` to overwrite it. See the [CLI reference](/cli/reference).
+
+## Archive contents
 
 ```text
 <base name>.simkb.zip
@@ -18,46 +45,43 @@ To export, right-click a base in the knowledge base list and choose **Export**,
     └── <documentId>.ndjson
 ```
 
-- **`manifest.json`** describes the export (format version 1): the base name, description, and chunking config; the embedding model and dimension and whether vectors are included; the tag definitions; and a document list with each document's filename, MIME type, size, enabled flag, tag values, entry paths, and chunk, token, and character counts.
-- **`files/`** holds each document's original file, when it has one.
-- **`chunks/`** holds one NDJSON file per document, with one JSON line per chunk: its index, content, token count, start and end offsets, enabled flag, and the vector when vectors are included.
+Files and chunk entries are present when the document has that content.
 
-The export includes every document a workspace member can read, its file and its chunk text. Documents synced from a [connector](/knowledgebase/connectors) export as plain documents: their text and, where Sim stored it, their file.
+| Entry | Contents |
+| --- | --- |
+| `manifest.json` | Format version `1`, export time, base name and description, chunking configuration, embedding model and dimensions, whether vectors are included, tag definitions, and the document list. |
+| `files/<documentId>/<filename>` | The document's original stored file, when available. |
+| `chunks/<documentId>.ndjson` | One JSON line per chunk: index, content, token count, start/end offsets, enabled flag, and an optional vector. NDJSON is newline-delimited JSON. |
 
-## What stays behind
-
-An export never includes:
+Each document entry records its filename, MIME type, file size, enabled flag, tag values, entry paths, and chunk, token, and character counts. [Connector](/knowledgebase/connectors) documents export as plain documents with their text and any stored file.
 
-- Access-control lists
-- Connector links and credentials
-- Who uploaded each document
-- Internal storage keys
+## Vectors and portability
 
-Live [Organization Search](/search) queries providers directly and has no index to export. If an operator selects the legacy indexed Search backend, its organization index is not included in a workspace knowledge-base export.
+Vectors are the embeddings used to compare chunks with a query. Each exported vector is encoded as base64 float32 values in its chunk's NDJSON line.
 
-## Vectors
+The manifest records the base's embedding model and dimensions. Reusing its vectors requires both to match the destination configuration; equal dimensions alone do not make vectors from different models comparable. Use `vectors=false` or `--no-vectors` when you need a text-and-file archive without vectors.
 
-Vectors are embeddings, the numbers a model produces so search can compare chunks. They are included by default. Each chunk's vector is stored as base64-encoded float32 values in its NDJSON line.
+## What stays behind
 
-Vectors are only valid for a deployment that uses the same embedding model and dimension. The manifest records both for the base you exported. To skip vectors, set `vectors=false` on the API or pass `--no-vectors` to the CLI.
+The archive does not include:
 
-## Limits and governance
+- Access-control lists or source-permission grants.
+- Connector links and credentials.
+- Uploader identities.
+- Internal storage keys or secret-provenance sidecars.
 
-A base with more than 2,000 documents cannot be exported. The request returns `413`.
+Live [Organization Search](/search) queries providers directly and has no document index to export. A legacy indexed organization Search backend is also outside a workspace knowledge-base export.
 
-Organization admins can withhold export through the permission group setting **Knowledge Base Export** (enterprise). Every export records an audit event.
+## Limits and audit
 
-## API
+Export preflight accepts at most **2,000** active, included, workspace-readable document rows. A larger eligible set returns `413`, even if some empty documents would otherwise be omitted from the archive.
 
-```http
-GET /api/v2/knowledge/{knowledgeBaseId}/export?workspaceId={workspaceId}&vectors=true
-```
+The bundle format also bounds each document to **5,000 chunks** and each chunk's content to **100,000 characters**. These are format limits, independent of vector inclusion.
 
-The response is the archive. See the [API reference](/api-reference/getting-started) for authentication.
+Each authorized export records an audit event with the base, vector option, and document count.
 
-## CLI
+## Related docs
 
-```bash
-sim knowledge export <knowledgeBaseId> --output-file kb.zip
-sim knowledge export <knowledgeBaseId> --output-file kb.zip --no-vectors
-```
+- [Knowledge Base](/knowledgebase) — uploads, processing, and embedding compatibility.
+- [Connectors](/knowledgebase/connectors) — source content and access methods.
+- [Access control](/platform/enterprise/access-control) — permission-group restrictions.
diff --git a/apps/docs/content/docs/knowledgebase/index.mdx b/apps/docs/content/docs/knowledgebase/index.mdx
index 19b210b6438..7f907823470 100644
--- a/apps/docs/content/docs/knowledgebase/index.mdx
+++ b/apps/docs/content/docs/knowledgebase/index.mdx
@@ -1,54 +1,70 @@
 ---
 title: Knowledge Base
-description: A store of documents your agents can search by meaning.
+description: Store documents that your agents can search and use in their answers.
 ---
 
-import { Video } from '@/components/ui/video'
 import { Card, Cards } from 'fumadocs-ui/components/card'
-import { FAQ } from '@/components/ui/faq'
 
-A **knowledge base** is a store of documents your agents can search by meaning. You upload files, Sim splits them into chunks and indexes them, and a [Knowledge block](/knowledgebase/using-in-workflows) retrieves the chunks most relevant to a query. This is how an agent answers from your own content instead of the model's general training.
+A **knowledge base** stores documents for your agents to search. Sim extracts their text, splits it into passages called chunks, and creates embeddings: numerical representations used to match a question to relevant content. The [Knowledge block](/knowledgebase/using-in-workflows) retrieves those chunks for an Agent to use in its answer.
 
-<div className="mx-auto w-full overflow-hidden rounded-lg my-6">
-  <Video src="knowledgebase-1.mp4" width={700} height={450} />
-</div>
+Upload files for a fixed collection, or use a [connector](/knowledgebase/connectors) to keep content in sync with an external source. [Organization Search](/search) has a separate live-provider catalog; connecting a source to a knowledge base does not enable it in Search.
 
-## How a document becomes searchable
+## Create a knowledge base
 
-When you upload a document, Sim processes it in the background:
+1. Open **Knowledge Base** in your workspace and choose **New base**.
+2. Enter a name and, optionally, a description. Leave **Chunking Strategy** on **Auto** unless you need different boundaries. See [chunking strategies](/knowledgebase/chunking-strategies) for the settings.
+3. Add files when creating the base, or open it and choose **New documents**.
+4. Wait for processing to finish before searching. A successful upload starts processing; it does not mean the document is indexed yet.
 
-1. **Extract** the text, with a parser for each file type and OCR for scanned PDFs.
-2. **Chunk** it into passages, with a size and overlap you can tune.
-3. **Embed** each chunk as a vector so it can be matched by meaning, not just keywords.
+Creating a base and adding documents require workspace write access and the relevant [permission-group capabilities](/platform/enterprise/access-control).
 
-A document is searchable once its status reads `completed`. Open any document to view, edit, merge, or split its chunks.
+## Supported files and limits
 
-Every knowledge base records the embedding model and the vector width it was built with, and keeps them for its lifetime. Two bases built differently cannot be searched in one request — vectors are only comparable when they come from the same model at the same size — so search them separately, or rebuild one to match. On Sim Cloud every base uses `text-embedding-3-small` at 1,536 dimensions; self-hosted deployments choose both with [`KB_EMBEDDING_MODEL` and `EMBEDDING_OUTPUT_DIMS`](/platform/self-hosting/environment-variables), including models on their own Ollama.
+| Content | File extensions |
+| --- | --- |
+| PDF | `.pdf` |
+| Word | `.doc`, `.docx` |
+| Text and Markdown | `.txt`, `.md` |
+| HTML | `.html`, `.htm` |
+| Excel and CSV | `.xls`, `.xlsx`, `.csv` |
+| PowerPoint | `.pptx` |
+| Structured data | `.json`, `.jsonl`, `.yaml`, `.yml` |
 
-## What you can upload
+Each file can be up to **100 MiB**. One upload action accepts at most **20 files**, with **500 MiB** total. Legacy `.ppt` files are not supported; convert them to `.pptx` first.
 
-Sim accepts PDF, Word, text, Markdown, HTML, Excel, PowerPoint, CSV, JSON, and YAML files, up to 100 MB each (best under 50 MB). Scanned PDFs work too: with Azure or [Mistral OCR](https://docs.mistral.ai/ocr/) configured, Sim extracts text from image-based pages.
+Scanned PDFs need Azure-hosted Mistral OCR or [Mistral OCR](https://docs.mistral.ai/studio/document-processing/basic_ocr) configured on the deployment. Password-protected, malformed, or overly complex files can fail processing even when they meet the upload-size limit. Read the document's error to find the required change.
 
-## Shaping what a search returns
+## Verify processing
 
-Two things control retrieval quality, and each has its own page:
+Sim processes documents in the background:
 
-- **Chunking** decides how a document is split. Smaller chunks are more precise; larger ones keep more context. See [chunking strategies](/knowledgebase/chunking-strategies).
-- **Tags** label documents so a search can filter to a subset. See [tags and filtering](/knowledgebase/tags).
+1. **Extract** text using the parser for the file type, with OCR for scanned PDFs.
+2. **Chunk** the text using the base's settings.
+3. **Embed** the chunks so a query can match them by meaning.
 
-To keep a base in sync with an outside source like Google Drive, use a [connector](/knowledgebase/connectors).
+A document becomes eligible for search when `processingStatus` is `completed`. It and its chunks must also be enabled, included, and readable by the caller. See [debugging retrieval](/knowledgebase/debugging-retrieval) for status and access checks.
 
-## Next
+Open a completed document to inspect its chunks. For uploaded documents, you can edit, add, disable, or delete chunks. Connector-managed chunks are read-only; change their content at the source and sync again.
+
+## Retrieve and refine
+
+Add a [Knowledge block](/knowledgebase/using-in-workflows) before an Agent, then reference `<knowledge.results>` in the Agent's prompt. The block can retrieve by query, by [tags](/knowledgebase/tags), or by both. Its retrieval mode controls whether a query uses semantic matching alone or combines it with keyword matching.
+
+Inspect the returned content before changing settings. Use tags to select the relevant document set, and adjust [chunking](/knowledgebase/chunking-strategies) when passages lose context or combine unrelated topics.
+
+## Embedding compatibility
+
+Each base records its embedding model and dimensions at creation and retains them for later document processing. The default configuration uses `text-embedding-3-small` at 1,536 dimensions. Self-hosted operators can choose a supported model and width with [`KB_EMBEDDING_MODEL` and `EMBEDDING_OUTPUT_DIMS`](/platform/self-hosting/environment-variables), including an embedding model on their own Ollama server.
+
+A query search across multiple bases requires the same embedding model and dimensions in every base. Search incompatible bases separately, or rebuild them with matching configuration. Tag-only searches do not compare vectors and do not require this compatibility. Each Knowledge block selects one base; use separate blocks when a workflow needs several.
+
+## Related docs
 
 <Cards>
-  <Card title="Using a knowledge base in a workflow" href="/knowledgebase/using-in-workflows" description="The Knowledge block: search, tags, reranking, and reading the results." />
-  <Card title="Chunking strategies" href="/knowledgebase/chunking-strategies" description="How chunk size and boundaries shape retrieval." />
-  <Card title="Tags and filtering" href="/knowledgebase/tags" description="Label documents and narrow a search." />
-  <Card title="Connectors" href="/knowledgebase/connectors" description="Sync documents from an external source." />
-  <Card title="Debugging retrieval" href="/knowledgebase/debugging-retrieval" description="Diagnose why a search returns the wrong chunks." />
+  <Card title="Using a knowledge base in a workflow" href="/knowledgebase/using-in-workflows" description="Configure retrieval and pass chunks to an Agent." />
+  <Card title="Connectors" href="/knowledgebase/connectors" description="Sync documents and manage source access." />
+  <Card title="Tags and filtering" href="/knowledgebase/tags" description="Define metadata and narrow a search." />
+  <Card title="Debugging retrieval" href="/knowledgebase/debugging-retrieval" description="Check missing, irrelevant, or duplicate results." />
+  <Card title="Chunking strategies" href="/knowledgebase/chunking-strategies" description="Choose passage sizes and boundaries." />
+  <Card title="Export" href="/knowledgebase/export-import" description="Download documents, chunks, tags, and settings." />
 </Cards>
-
-<FAQ items={[
-  { question: "Does it support scanned PDFs?", answer: "Yes. With Azure or Mistral OCR configured, Sim extracts text from image-based and scanned PDF pages." },
-  { question: "Can I search across multiple knowledge bases?", answer: "Each Knowledge block searches one knowledge base. Use multiple Knowledge blocks in a workflow to search across several." },
-]} />
diff --git a/apps/docs/content/docs/knowledgebase/tags.mdx b/apps/docs/content/docs/knowledgebase/tags.mdx
index 1d84bb9835c..deb57a44c42 100644
--- a/apps/docs/content/docs/knowledgebase/tags.mdx
+++ b/apps/docs/content/docs/knowledgebase/tags.mdx
@@ -1,109 +1,90 @@
 ---
 title: Tags and filtering
+description: Define document metadata and use it to narrow Knowledge block searches.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
 import { Image } from '@/components/ui/image'
-import { FAQ } from '@/components/ui/faq'
 
-Tags let you attach structured metadata to documents so the Knowledge block can filter results precisely — by department, date, priority, status, or any dimension you define.
+Tags attach structured metadata to documents. Use them to select a department, date range, priority, or status before retrieving chunks.
 
-## How Tags Work
+A **tag definition** belongs to the knowledge base and gives a tag its name and type. A **tag value** belongs to a document. For example, define a Text tag named `Department`, then set `Department = "engineering"` on the documents that need it.
 
-Tags have two layers:
+## Types and capacity
 
-1. **Tag definitions** — created at the knowledge base level. A definition has a name (e.g., "Department") and a type (Text, Number, Date, or Boolean). Definitions are shared across all documents.
-2. **Tag values** — set per document. Once a definition exists, you assign a value to it on each document that needs it (e.g., `Department = "engineering"`).
+Each knowledge base has **17 tag slots**, shared by its documents and connectors:
 
-## Tag Slots
+| Type | Slots | Values |
+| --- | --- | --- |
+| Text | 7 | Strings up to 512 characters; matching is case-insensitive. |
+| Number | 5 | Valid numbers. |
+| Date | 2 | Valid dates in `YYYY-MM-DD` format. |
+| Boolean | 3 | `true` or `false`. |
 
-Each knowledge base has **17 tag slots** distributed across four types:
+The type picker shows usage, such as **Text (0/7)**, and only offers types with available slots. A connector's metadata tags use the same pool; choose the metadata you need during [connector setup](/knowledgebase/connectors).
 
-| Type | Slots | Accepted values |
-|------|-------|-----------------|
-| **Text** | 7 | Any string — matching is case-insensitive |
-| **Number** | 5 | Any valid number |
-| **Date** | 2 | `YYYY-MM-DD` format |
-| **Boolean** | 3 | `true` or `false` |
+## Define and manage tags
 
-The type dropdown in the creation form shows current slot usage for each type (e.g., `Text (0/7)` means none of the 7 text slots are in use yet).
+You need workspace write access to create or delete definitions.
 
-<Callout type="info">
-  Slots are shared across all documents and connectors in a knowledge base. Connectors that auto-populate metadata tags draw from the same pool. Plan your schema with that in mind.
-</Callout>
+1. Click the knowledge base name in the header and choose **Tags**.
+2. Choose **Add Tag**.
+3. Enter a **Tag Name**, choose a **Type**, and select **Create Tag**. Press Enter to submit or Escape to cancel.
 
-## Defining Tags
+<Image src="/static/tags/tags-kb-menu.png" alt="Tags in the knowledge base header's dropdown menu" width={700} height={346} className="mx-auto h-auto w-full max-w-md" />
 
-Tag definitions live at the knowledge base level. To manage them, click the knowledge base name in the header to open the context menu and select **Tags**:
+Names can be up to 100 characters and must be unique within the base, ignoring case. The Tags modal shows each definition's document count. Click a definition to view the documents with assigned values.
 
-<Image src="/static/tags/tags-kb-menu.png" alt="Knowledge base header showing the dropdown menu with Rename, Tags, and Delete options" width={700} height={346} className="mx-auto h-auto w-full max-w-md" />
+The modal supports creating and deleting definitions. To rename a definition without clearing its values, use [Update knowledge tag](/api-reference/knowledge-bases/updateKnowledgeTag) in the API.
 
-This opens the Tags modal, which lists all defined tags and shows how many documents each one is assigned to. Click **Add Tag** to define a new one:
+Deleting a definition clears its values from every document and chunk that uses the slot. The confirmation dialog shows the affected documents. Review this consequence before selecting the trash icon and confirming.
 
-<Image src="/static/tags/tags-create.png" alt="Tags modal showing 0 defined tags, a Tag Name input field, and a Type dropdown set to Text (0/7), with Cancel and Create Tag buttons" width={700} height={471} className="mx-auto h-auto w-full max-w-md" />
+## Set document values
 
-Enter a **Tag Name** and pick a **Type**, then click **Create Tag**. The name must be unique within the knowledge base. The type dropdown only shows types that still have available slots. Press Enter to submit or Escape to cancel.
+Right-click a document and choose **Tags**. Set the values for its defined tags in the document's tag panel.
 
-To delete a tag definition, click the trash icon next to it. Deleting a definition removes the tag value from every document it was assigned to — the modal shows you which documents are affected before you confirm.
+The **Tags** column shows assigned values; documents without values show dashes. Use **Filter** to narrow the document list by tag values.
 
-Clicking any existing tag definition opens a dialog showing all documents that have a value set for it, along with their current tag values.
+## Filter a workflow search
 
-## Setting Tag Values on Documents
+Open the Knowledge block and add **Tag Filters**. Each filter has:
 
-Once a definition exists, you assign values document by document. Right-click any document (or click the `…` menu) to open the document context menu, then select **Tags**:
+- **Tag** — a definition from the selected base.
+- **Operator** — a comparison supported by that type.
+- **Value** — a fixed value or a workflow reference, such as `<start.department>`.
 
-This opens the tag panel for that document where you can set a value for each defined tag.
+For example, use `Department equals "engineering"` with a query about incident handling. The filter restricts candidate documents, and the query retrieves relevant chunks within them.
 
-## Viewing Tags in the Document List
+Add filters with the **+** button. Filters combine with AND, including filters on the same tag; a document must match every condition. A document without the required tag value will not match a comparison.
 
-The **Tags** column in the document list shows the current tag values for each document at a glance. Documents with no tags assigned show `– – –`:
+### Operators
 
-<Image src="/static/tags/tags-document-list.png" alt="Knowledge base document list showing Name, Size, Tokens, Chunks, Uploaded, Status, and Tags columns — Document1.txt shows no tags (– – –) while Document2.txt shows the value 'Waleed'" width={900} height={209} />
+| Type | UI operators |
+| --- | --- |
+| Text | **equals**, **not equals**, **contains**, **does not contain**, **starts with**, **ends with** |
+| Number | **equals**, **not equals**, **greater than**, **greater than or equal**, **less than**, **less than or equal**, **between** |
+| Date | **equals**, **after**, **on or after**, **before**, **on or before**, **between** |
+| Boolean | **is**, **is not** |
 
-Use the **Filter** and **Sort** controls in the top right to narrow the list by tag values or sort by them.
+**between** takes a lower and upper value and includes both bounds. Date comparisons apply to the specified calendar days. Text operators match literal text without case sensitivity.
 
-## Using Tags in the Knowledge Block
+### Query and tags
 
-In a workflow, open the Knowledge block and configure **Tag Filters** to restrict which documents are searched:
+| Input | Behavior |
+| --- | --- |
+| Tags only | Return matching chunks up to **Number of Results**, without vector ranking. Each match has `similarity: 1`. |
+| Query only | Retrieve from readable documents using the selected retrieval mode. |
+| Query and tags | Filter documents first, then retrieve within the matching set. |
 
-<Image src="/static/tags/tags-knowledge-block.png" alt="Knowledge block editor showing Operation: search, Knowledge Base: test, Search Query field (optional), Number of Results, and a Tag Filters section with Filter 1 containing Tag: Name, Operator: equals, and a Value field" width={900} height={620} />
+Tag-only retrieval does not generate a query embedding. Adding tags to a query narrows candidates but does not reduce the query-embedding charge. See [Using a knowledge base in a workflow](/knowledgebase/using-in-workflows) for retrieval modes and output fields.
 
-Each filter has three parts:
-- **Tag** — select a tag definition from the knowledge base
-- **Operator** — depends on the tag type (see below)
-- **Value** — the value to match against
+## Connector metadata
 
-Add as many filters as you need with the **+** button. Multiple filters are combined with AND logic — a document must match all filters to be included in the search.
+Connectors can define and populate tags from source metadata. Notion can set **Labels** and **Last Modified**; GitHub can set **Repository** and **File Path**. You can use these definitions in the same filters as manual tags.
 
-### Operators by Type
+Metadata checkboxes are available during connector setup. Uncheck fields you do not need before connecting. Compatible existing definitions can be reused; new definitions consume available slots. Existing definitions retain their slots until deleted. The connector's Settings tab does not offer a metadata-tag editor, and changing source configuration does not automatically free tag slots.
 
-| Type | Available operators |
-|------|-------------------|
-| **Text** | `equals`, `not equals`, `contains`, `does not contain`, `starts with`, `ends with` |
-| **Number** | `equals`, `not equals`, `greater than`, `greater than or equal`, `less than`, `less than or equal`, `between` |
-| **Date** | `equals`, `after`, `on or after`, `before`, `on or before`, `between` |
-| **Boolean** | `is`, `is not` |
+## Related docs
 
-Tag values in filter fields can be static strings or workflow variable references (e.g., `<start.department>`), so filtering can adapt dynamically at runtime.
-
-## Search Modes
-
-The Knowledge block behaves differently depending on what you provide:
-
-| What you provide | Behaviour |
-|-----------------|-----------|
-| **Tags only** (no search query) | Returns matching chunks up to Number of Results, without vector ranking |
-| **Query only** (no tag filters) | Semantic vector search across all documents in the knowledge base |
-| **Both tags and query** | Tag filters run first to narrow the document set, then vector search runs within that subset |
-
-The combined mode is the most precise — tag filtering cuts down the candidate set cheaply before the more expensive vector similarity comparison runs.
-
-## Connector-Populated Tags
-
-Connectors can auto-populate tags with metadata from the source. A Notion connector might set **Last Modified** and **Labels**; a GitHub connector might set **Repository** and **File Path**. These work exactly like manually defined tags and are available in Knowledge block filters.
-
-You can disable specific metadata tag types during connector setup or in connector settings to free up slots for manual use. See [Connectors](/knowledgebase/connectors) for details.
-
-<FAQ items={[
-  { question: "Can I rename a tag definition?", answer: "No. Tag definitions cannot be renamed after creation. Delete the old definition and create a new one with the correct name. Deleting will remove the tag value from all documents it was assigned to." },
-]} />
+- [Connectors](/knowledgebase/connectors) — select source metadata during setup.
+- [Using a knowledge base in a workflow](/knowledgebase/using-in-workflows) — combine query and tag inputs.
+- [Debugging retrieval](/knowledgebase/debugging-retrieval) — diagnose filters that exclude expected results.
diff --git a/apps/docs/content/docs/knowledgebase/using-in-workflows.mdx b/apps/docs/content/docs/knowledgebase/using-in-workflows.mdx
index afd4bec3100..f27e89856c2 100644
--- a/apps/docs/content/docs/knowledgebase/using-in-workflows.mdx
+++ b/apps/docs/content/docs/knowledgebase/using-in-workflows.mdx
@@ -1,62 +1,44 @@
 ---
 title: Using a knowledge base in a workflow
-description: How the Knowledge block searches a knowledge base and what it returns, so an agent can ground its answers in your documents.
+description: Retrieve document chunks with the Knowledge block and pass them to an Agent.
 ---
 
 import { WorkflowPreview, OutputBundle, SUPPORT_KB_WORKFLOW } from '@/components/workflow-preview'
 
-A **Knowledge block** searches a [knowledge base](/knowledgebase) and hands the matching passages to a later block, so an [Agent](/workflows/blocks/agent) can answer from your documents instead of the model's memory alone. This page covers searching, narrowing with tags, reranking, and reading the results.
+Use a **Knowledge block** to retrieve passages from a [knowledge base](/knowledgebase), then pass them to an [Agent](/workflows/blocks/agent). In this example, the workflow searches product docs for a customer's question and answers from the returned content.
 
 <WorkflowPreview workflow={SUPPORT_KB_WORKFLOW} height={180} />
 
-In this workflow, the Knowledge block searches a base of product docs for the customer's question, and the Agent answers from the passages it returns.
+## Search and answer
 
-## Search
+1. Set the Knowledge block's **Operation** to **Search**.
+2. Select a **Knowledge Base**.
+3. Set **Search Query** to `<start.input>`, the customer's question.
+4. Connect the Knowledge block to an Agent. Reference `<knowledge.results>` in the Agent's prompt, and tell it to answer from the returned `content` and cite `documentName` or `sourceUrl` where available.
 
-A **Knowledge block** set to **Search** takes a query, compares it against the chunks in a base, and returns the closest matches. (The block can also manage documents and chunks, but Search is what a workflow uses to retrieve context.) You point it at a knowledge base and give it a query; in our example the query is `<start.input>`, the customer's question.
+**Number of Results** (`topK`) defaults to **10** and accepts **1–100** chunks. Increase it when relevant passages fall outside the returned set; decrease it when the Agent receives too much unrelated content.
 
-Search is semantic, not keyword matching. The block turns the query into a vector and finds the chunks whose meaning is closest, so "refund timelines" can match a passage that says "we process returns within 14 days" with no shared words.
+Search only returns completed, enabled, included documents and enabled chunks that the acting principal can read. An upload or connector sync can finish its initial request before indexing completes. See [debugging retrieval](/knowledgebase/debugging-retrieval) if expected content is missing.
 
-**Number of Results** (topK) sets how many chunks come back, 10 by default. Fewer give the agent a tight, focused set; more widen the net at the cost of noise and tokens.
+## Query and tag filters
 
-You can also search by tags, instead of or alongside a query:
+A query matches chunks by meaning. For example, “refund timelines” can match “we process returns within 14 days.” Hybrid retrieval also uses keywords, as described under [Retrieval mode](#retrieval-mode).
 
-| What you provide | What it does |
+| Input | Behavior |
 | --- | --- |
-| Query only | Semantic search across every document in the base. The default. |
-| Tags only | Returns matching chunks up to Number of Results, without vector ranking. |
-| Query and tags | Tags narrow the document set first, then semantic search runs within it. The most precise. |
+| Query only | Search readable documents using the selected retrieval mode. |
+| Tags only | Return matching chunks up to **Number of Results**, without vector ranking or a query-embedding call. |
+| Query and tags | Narrow the document set with tags, then retrieve within that set. |
 
-## Tag Filters
+Provide a query, tag filters, or both.
 
-**Tag Filters** restrict a search to documents carrying specific [tags](/knowledgebase/tags). Each filter has three parts: a **Tag** (a tag defined on the base, like `Department`), an **Operator** (`equals`, `contains`, `greater than`, and others depending on the tag's type), and a **Value** to match.
+**Tag Filters** have a **Tag**, **Operator**, and **Value**. For example, `Department equals "Billing"` restricts the search to billing documents. Add filters with the **+** button; they combine with AND, so a document must match all of them. Values can be fixed strings or references such as `<start.department>`.
 
-In our example, adding `Department equals "Billing"` makes the search consider only billing documents. Add more filters with the **+** button; multiple filters combine with AND, so a document must match all of them. A filter value can be a fixed string or a reference like `<start.department>`, so the scope can change per run.
+Tags narrow candidates; they do not reduce the query-embedding charge. See [Tags and filtering](/knowledgebase/tags) for types, operators, and slot limits.
 
-Filters run before the vector comparison, so they make a search both more precise and cheaper. See [Tags and filtering](/knowledgebase/tags) for the full operator list by tag type.
+## Outputs
 
-## Retrieval Mode
-
-**Retrieval Mode** is an advanced setting that chooses how matches are found.
-
-| Mode | What it does |
-| --- | --- |
-| Vector only | The default. Ranks purely on meaning, as described above. |
-| Hybrid | Also runs a keyword search over the same chunks and blends the two rankings. |
-
-Semantic search is strong on paraphrase and weak on literal strings: an error code, a ticket key like `PROJ-1234`, a SKU, or a rare product name carries little meaning for the model, so the chunk containing it may not rank near the top. Hybrid adds a keyword pass that matches those tokens exactly, then merges the two lists so a chunk found by either signal can surface.
-
-Turn it on when your documents are full of identifiers, codes, or names people search for verbatim. Leave it off for prose-heavy bases where questions are asked in natural language. Hybrid costs no extra API calls — the keyword pass runs entirely in the database.
-
-## Rerank Results
-
-**Rerank Results** is an optional second pass. Vector search ranks by raw similarity; reranking re-scores the top matches with a dedicated relevance model (Cohere's rerank models) and reorders them, which sharpens the ordering when the best answer isn't the literal closest vector.
-
-Leave it off for most searches. Turn it on when retrieval returns roughly the right documents but in the wrong order. When enabled, you pick a **Rerank Model**; self-hosted deployments also supply a Cohere API key.
-
-## Retrieved chunks
-
-The Search operation produces an **output** stored under the block's name, the same as any other block. Its main value is `results`: an array of the matched chunks, ranked best first. A later block reads it by reference, for example `<knowledge.results>`.
+The block stores its output under its name. A later block reads `results` with `<knowledge.results>`:
 
 <OutputBundle
   blockName="knowledge"
@@ -73,39 +55,64 @@ The Search operation produces an **output** stored under the block's name, the s
             { key: 'content', type: 'string', value: '"Refunds are issued within 14 days…"' },
             { key: 'documentName', type: 'string', value: '"refund-policy.pdf"' },
             { key: 'similarity', type: 'number', value: '0.92' },
+            { key: 'rankScore', type: 'number', value: '0.92' },
+            { key: 'rank', type: 'number', value: '1' },
             { key: 'sourceUrl', type: 'null', expanded: false },
           ],
         },
       ],
     },
     { key: 'query', type: 'string', value: '"refund policy"' },
-    { key: 'totalResults', type: 'number', value: '5' },
+    { key: 'totalResults', type: 'number', value: '1' },
   ]}
 />
 
-Each result in the array is an object with these fields:
+This example shows one result from Vector only retrieval without reranking. Each result can include:
 
-| Field | What it is |
+| Field | Meaning |
 | --- | --- |
-| `content` | The chunk's text. This is what the agent reads. |
-| `documentName` | The source document's filename, for citation. |
-| `sourceUrl` | A link to the original, if the document came from a [connector](/knowledgebase/connectors). `null` for uploaded files. |
-| `chunkIndex` | The chunk's position within its document. |
-| `similarity` | How close the chunk is to the query, higher is better. For example `0.92`. |
-| `metadata` | The document's attributes, including its tags. |
-| `documentId` | The source document's identifier. |
+| `content` | The chunk text the Agent reads. |
+| `documentName` | The source document's name, useful for citation. |
+| `sourceUrl` | The original source link when available; `null` for uploaded files without an external source. |
+| `documentId` | The source document's ID. |
+| `chunkIndex` | The chunk's position in its document; `0` is the first chunk. |
+| `metadata` | Document tags, keyed by their display names. |
+| `similarity` | Cosine similarity to the query; higher values mean a closer match. It remains this value in Hybrid mode and is `1` for tag-only matches. |
+| `rankScore` | Retrieval score: cosine similarity for Vector only, fused score for Hybrid, or reranker score when reranking is applied. |
+| `rank` | One-based position in the returned order. Recency policy can affect this order. |
+| `rerankerScore` | Relevance score, present when reranking is applied. |
+
+The output also includes `query` and `totalResults`, the number of returned chunks. Keep the returned order when passing results to the Agent; sorting by `similarity` can discard Hybrid, recency, or reranker ordering.
+
+See [data flow](/workflows/data-flow) for references between blocks.
+
+## Retrieval mode
+
+**Retrieval Mode** is available in advanced mode:
+
+| Setting | Behavior |
+| --- | --- |
+| **Automatic** | The default. Use the workspace's retrieval policy. |
+| **Hybrid (full-text + vector)** | Combine keyword and semantic rankings. |
+| **Vector only** | Retrieve by semantic similarity. |
+
+Automatic uses Hybrid with a recency boost where member-scoped knowledge access is enabled, and Vector only without that boost elsewhere. An explicit mode overrides the retrieval choice; recency boosting remains a workspace policy.
+
+Try Hybrid for error codes, ticket keys such as `PROJ-1234`, SKUs, or rare names that readers search for verbatim. The keyword pass runs in the database and adds no model API call.
+
+## Rerank results
 
-The output also carries `query` (the text that was searched) and `totalResults` (the count).
+Enable **Rerank Results** when retrieval finds relevant passages but puts them in an unhelpful order. Select a **Rerank Model**; self-hosted deployments also supply a **Cohere API Key**.
 
-To ground an answer, wire the Knowledge block before an [Agent](/workflows/blocks/agent) block and reference the chunks in the Agent's prompt with `<knowledge.results>`. The agent reads the `content` of each result and can cite `documentName` and `sourceUrl`. See [how blocks reference output](/workflows/data-flow) for how one block reads another's output by name.
+Reranking sends candidates to a relevance model for a second pass. By default, Sim retrieves up to four times **Number of Results**, capped at 100 candidates. In advanced mode, **Documents Sent to Reranker** lets you choose the candidate count; Sim uses at least the requested result count and at most 100. These candidates are chunks, rather than whole source files.
 
-## When retrieval looks wrong
+A reranker model call adds latency. Completed calls using a hosted key are metered as one search unit; with your own key, the provider bills your account. See [Costs](/platform/costs) for the deployment's billing policy.
 
-When the agent's answer is off, the cause is usually in retrieval, not the agent. Read the Knowledge block's output in the [run logs](/logs-debugging) and check the chunks it actually returned:
+If reranking is unavailable, the search still succeeds: results keep their retrieval order and omit `rerankerScore`. Tag-only searches and searches with no candidates skip reranking.
 
-- **No results, or wrong documents.** A tag filter may be excluding what you want, or the documents may not be indexed yet. A document is only searchable once its processing status is `completed`; while it is `pending`, `processing`, or `failed`, its chunks won't appear.
-- **Low similarity scores across the board.** The query is too vague, or the information simply isn't in the base. Rewrite the query to match how the documents phrase things.
-- **Right documents, wrong order.** Turn on Rerank Results, or raise Number of Results so the relevant chunk is included.
-- **An exact code, ID, or name isn't found.** Switch Retrieval Mode to Hybrid so a keyword pass runs alongside the semantic one.
+## Related docs
 
-See [debugging retrieval](/knowledgebase/debugging-retrieval) for the full diagnostic path, and [chunking strategies](/knowledgebase/chunking-strategies) for how chunk boundaries shape what a search can return.
+- [Debugging retrieval](/knowledgebase/debugging-retrieval) — check returned content, processing, filters, and ranking.
+- [Tags and filtering](/knowledgebase/tags) — define the metadata used by **Tag Filters**.
+- [Chunking strategies](/knowledgebase/chunking-strategies) — change how documents become passages.
+- [Knowledge block reference](/integrations/knowledge) — document, chunk, tag, and connector operations.
diff --git a/apps/docs/content/docs/logs-debugging/alerts.mdx b/apps/docs/content/docs/logs-debugging/alerts.mdx
index 9fc6f54df4a..24e9f9a7282 100644
--- a/apps/docs/content/docs/logs-debugging/alerts.mdx
+++ b/apps/docs/content/docs/logs-debugging/alerts.mdx
@@ -5,6 +5,10 @@ description: Send an alert when a watched workflow fails or exceeds an operation
 
 Use a [Sim Workspace Events trigger](/workflows/triggers/sim) to run an alert workflow when another workflow fails, slows down, exceeds a cost threshold, or goes quiet. Add delivery blocks for the channel you use, such as Slack, email, or an incident API.
 
+## Before you start
+
+You need permission to create and deploy the alert workflow, a credential for its delivery service, and a watched test workflow where you can reproduce the condition.
+
 ## Example: notify Slack after repeated failures
 
 1. Create a workflow with **Sim Workspace Events** as its trigger.
@@ -18,12 +22,23 @@ Workflow <workspaceevent.workflowName> has failed repeatedly.
 Latest run: <workspaceevent.triggeringRun.runId>
 ```
 
-6. Deploy the alert workflow to activate it. Trigger representative failures in a watched test workflow, then inspect the alert workflow's [run log](/logs-debugging) and the Slack message.
+6. Deploy the alert workflow to activate it.
+
+## Verify the alert
+
+Trigger three consecutive failures in a watched test workflow. Inspect the alert workflow's [run log](/logs-debugging), confirm its delivery block completed, and check the Slack message for the source workflow and run ID.
 
 ## Choose another condition
 
 Choose **Run Error** to respond to each failed run. Other conditions include failure rate, error count, latency, cost, and inactivity. Cost thresholds use credits. See the [event and rule reference](/workflows/triggers/sim) for settings, defaults, and event-specific outputs.
 
-Rule-based subscriptions have a one-hour cooldown after firing; plain events such as Run Error do not. Rate-based rules need at least five runs in their window. A subscription does not receive events about its own workflow, and runs started by this trigger do not emit new workspace events.
+Run-backed alert rules have a one-hour cooldown after firing. **No Activity** has a per-watched-workflow cooldown of at least one hour or the inactivity window, whichever is longer. Plain events such as Run Error have no rule cooldown. Rate-based rules need at least five runs in their window. A subscription does not receive events about its own workflow, and runs started by this trigger do not emit new workspace events.
+
+## If an alert is missing
+
+Delivery behavior comes from the action blocks you configure. Check that the alert workflow is deployed, the source workflow matches its filter, the condition and cooldown allow it to fire, and the delivery block completed successfully.
+
+## Related docs
 
-Delivery behavior comes from the action blocks you configure. If an alert is missing, check that the alert workflow is deployed, the source workflow matches its filter, the condition and cooldown allow it to fire, and the delivery block completed successfully.
+- [Sim Workspace Events](/workflows/triggers/sim) for event settings and outputs
+- [Logs](/logs-debugging) for tracing a failed alert run
diff --git a/apps/docs/content/docs/logs-debugging/index.mdx b/apps/docs/content/docs/logs-debugging/index.mdx
index 14edf8f61a9..78c106702d8 100644
--- a/apps/docs/content/docs/logs-debugging/index.mdx
+++ b/apps/docs/content/docs/logs-debugging/index.mdx
@@ -1,96 +1,64 @@
 ---
 title: Logs
-description: A log is the recorded trace of one workflow run, and debugging is reading that trace backward from the block that failed.
+description: Trace a workflow failure through the inputs, outputs, and errors recorded for its run.
 ---
 
 import { Image } from '@/components/ui/image'
 
-A **log** is the recorded trace of one workflow run. Every time a workflow runs, Sim writes down what triggered it, which blocks ran in what order, and for each block its exact input, its output, and any error. That trace is the ground truth for debugging: it replays what each block received, what it did, and what it returned, so you can find where something went wrong.
+Open **Logs** to inspect a recorded workflow run. Start with its error, then follow the resolved inputs back to the block that supplied an unexpected value. The [Run logs reference](/logs-debugging/logging) explains filters, refresh, the editor console, and snapshots.
 
+## Read a run trace
 
+Each run has a unique execution ID, a trigger, status, duration, and recorded cost in credits. Triggers include manual, API, schedule, webhook, MCP, and **Sim agent** for runs started through Chat.
 
-The **Logs page** lists every run across your workspace, one row per run. The [Logging reference](/logs-debugging/logging) covers the page itself: the columns, filters, and sidebar. This page covers what a log captures and how to trace a failure back to its cause.
-
-<Image
-  src="/static/logs/workspace-logs.png"
-  alt="The Logs page: one row per run with workflow, date, status, cost in credits, trigger, and duration"
-  width={1064}
-  height={800}
-/>
-
-## What a log records
-
-### The run
-
-Each row on the Logs page is one **run**. It records the **trigger** that started it (manual, api, schedule, chat, webhook, mcp, mothership, copilot, or workflow), a **status**, a **duration**, and the **cost** in credits. It also carries an **execution ID** that uniquely names the run.
-
-The status shows the run's outcome at a glance, with failed runs badged **Error**. When you are hunting a failure, you filter the list to the errors and start there.
-
-### The blocks
-
-Open a run and **Log Details** shows the trace. The **Trace** tab lists each block as a span with its timing, in the order they ran; each **block execution** records the [block](/workflows#blocks)'s name and type, its own status, its **input**, its **output**, and an error message if it failed.
+Select a run to open **Log Details**. **Overview** contains run metadata and available workflow input, output, cost, and files. **Trace** shows timed spans for blocks, nested workflows, model requests, and tool calls. Access settings can hide trace, snapshot, or cost details.
 
 <Image
   src="/static/logs/log-trace.png"
-  alt="The current Log Details Trace tab showing workflow, agent, model, and tool spans with their durations"
+  alt="Log Details Trace tab with nested workflow, agent, model, and tool spans and their durations"
   width={518}
   height={540}
   className="mx-auto h-auto w-full max-w-md"
 />
 
-This is the level you debug at, because a run fails when one of its blocks fails, and a block usually fails because of the input it received. In this run, one glance at the spans shows where the time went: Agent 1 took 7.84s of the 7.86s total.
-
-### Input and output
-
-Each block in the sidebar has two tabs. The **Input** tab shows the resolved values the block actually ran with: the literal values you typed, and the earlier outputs it read by reference. Exact values successfully substituted from Secrets through `{{KEY}}` are masked in this trace copy; see [Execution log protection](/platform/credentials#execution-log-protection). The **Output** tab shows what the block produced, formatted as an object, with markdown rendered for agent-generated text.
-
-The input tab is the important one. A block reads earlier outputs by name, written `<blockName.field>`, and the input tab shows what those references resolved to at run time. If a reference pointed at a value that was not there, you see it here as missing or wrong, not as the tag you wrote. See [how blocks pass data](/workflows/data-flow) for how those references resolve.
-
-The same inspector follows you into the editor: during manual and chat runs, the console shows each block's Output and Input live, with values as a typed tree.
-
-<Image
-  src="/static/logs/run-inspector.png"
-  alt="The editor's run console: blocks with their durations on the left, and the selected Agent's Output tab showing content, model, and tokens as a typed tree"
-  width={900}
-  height={354}
-/>
-
-### The snapshot
+Select a span to read its collapsible **Input**, **Output** or **Error**, and any **Thinking** or **Error message** sections. Input shows the values after references resolve; output shows what that step returned. Compare these values with the [data references](/workflows/data-flow) in your workflow.
 
-A workflow changes over time. A log does not. Clicking **View Snapshot** opens a frozen copy of the workflow exactly as it was when that run happened: the blocks, the connections, the configuration. This matters when a run failed last week and you have edited the workflow since. The snapshot shows the version that actually ran, not today's version.
+Protected resolved secret values are masked in the log-facing copy. Workspace **Unredacted** exceptions and transformed values have different boundaries; see [Execution log protection](/platform/credentials#execution-log-protection).
 
-## Tracing a failure backward
+A handled block error can appear in a successful run. For a failed run, find the unhandled error rather than assuming every error span caused the final status.
 
-Debugging follows the same repeatable loop each time. You start at the block that failed and walk back to the block that caused it.
+## Trace a failure backward
 
-1. **Find the failed block.** Open the errored run. The sidebar marks the block whose status is **error**. Read its error message.
-2. **Read its input.** Open the block's Input tab. This is what it actually ran with, after every reference resolved.
-3. **Verify the input.** Ask whether that input is what the block expected. An empty field, a value of the wrong type, a missing nested key: the mismatch is usually visible here.
-4. **Walk back to the source.** A bad input came from somewhere. Find the earlier block whose output the failed block referenced, and open that block's Output tab. Either it produced the wrong value, or it never ran.
-5. **Fix and rerun.** Correct the reference, the configuration, or the upstream block, then run the workflow again.
-6. **Compare the traces.** Open the new run's log next to the old one. The block that was **error** is now **success**, and its input is the value you expected. That confirms the fix.
-
-{/* VISUAL: the debugging loop as a flowchart: failed block → read input → verify expectation → walk back to source block → fix → rerun → compare logs. */}
-
-{/* VISUAL: side-by-side of a failed run and a successful run, same blocks, highlighting the one input/output that changed between them. */}
+1. Open the failed run and select its failed span in **Trace**. Read the error message.
+2. Expand **Input** to see what the step received after references resolved.
+3. Check required fields, types, and nested keys against the block's expected input.
+4. Find the upstream block referenced by the incorrect input. Inspect its output and confirm that it ran.
+5. Correct the reference, configuration, or upstream behavior, then run the workflow again.
+6. Compare the new trace with the failed run. Confirm that the input is correct and the step completes successfully.
 
 ### Common failures
 
-Most errors come down to a handful of input mismatches. Knowing the shape speeds up step 3.
-
-- **Missing input.** A field the block needs was left empty, or its reference resolved to nothing.
-- **Wrong reference.** The tag names an output that does not exist, or uses the wrong field name.
-- **Type mismatch.** A string where an object was expected, or the reverse.
-- **Missing nested key.** The referenced object exists, but the specific field inside it does not.
-- **Empty agent message.** An [Agent](/workflows/blocks/agent) returned nothing, so the next block had nothing to read.
-- **External error.** A tool or API the block called returned an error of its own, surfaced in the block's error message.
+| Failure | What to check |
+| --- | --- |
+| Missing input | A required field is empty or its reference resolves to no value. |
+| Wrong reference | The block or output field named in the reference does not exist. |
+| Type mismatch | A step receives a string where it expects an object, or another incompatible type. |
+| Missing nested key | The object exists, but the requested field does not. |
+| Empty agent message | An [Agent](/workflows/blocks/agent) returns no content for the next step to read. |
+| External error | A tool or API returns an error; inspect its message and request inputs. |
 
-When a value is the wrong shape, reshape it in a [Function](/workflows/blocks/function) block, whose result becomes its own output that later blocks can read.
+Use a [Function](/workflows/blocks/function) block to reshape a value when the next step expects a different structure.
 
-## AI-assisted debugging
+## Troubleshoot in Chat
 
-Sim can read a run's logs and propose a fix from the trace: the error message, the input the block received, and the output the upstream block produced. The logs stay the ground truth. You confirm a proposed fix the same way you confirm your own: rerun the workflow and compare the new trace against the failed one.
+When available on a failed run, select **Troubleshoot in Chat** to give Sim its debugging context. This action depends on Chat being enabled and the run supporting troubleshooting. Verify any proposed fix by rerunning the workflow and comparing traces.
 
 ## Retention
 
-Logs are kept so you can debug a run after it happened. Free plans retain logs for **7 days**, after which they are archived to cloud storage and removed from the database. Pro, Team, and Enterprise plans retain logs indefinitely.
+Sim Cloud Free defaults to 30 days of log retention. Paid plans and billing-disabled deployments have no plan-based default expiry; configured policies can still remove older logs. See [Data retention](/enterprise/data-retention) for the effective policy and cleanup behavior.
+
+## Related docs
+
+- [Run logs](/logs-debugging/logging) for filters, details, console, and snapshots
+- [Alerts](/logs-debugging/alerts) for failure and operational notifications
+- [Data flow](/workflows/data-flow) for resolving block references
diff --git a/apps/docs/content/docs/logs-debugging/logging.mdx b/apps/docs/content/docs/logs-debugging/logging.mdx
index d974e26782a..de4264fbf5b 100644
--- a/apps/docs/content/docs/logs-debugging/logging.mdx
+++ b/apps/docs/content/docs/logs-debugging/logging.mdx
@@ -1,97 +1,60 @@
 ---
-title: Logging
-description: Where run logs live — the real-time console, the Logs page, and what each entry records.
+title: Run logs
+description: Find recorded runs, inspect their details, and compare them with the workflow that ran.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Image } from '@/components/ui/image'
 
-Every workflow run is logged. There are two places to read them: the **Console** for the run you're watching, and the **Logs page** for everything.
-
-## Real-time Console
-
-During manual or chat runs, the Console panel in the editor shows each block as it runs — active-block highlighting, outputs as they complete, per-block timing, and success/error status.
-
-<div className="flex justify-center">
-  <Image
-    src="/static/logs/console.png"
-    alt="The current run console with block timings and the selected block output"
-    width={1008}
-    height={380}
-    className="my-6"
-  />
-</div>
-
-## Logs page
-
-Every run from every trigger — manual, API, chat, schedule, webhook — lands on the Logs page, with filtering by time range, status, trigger type, folder, and workflow, full-text search, and a **Live mode** that streams new entries in as they're recorded.
-
-<div className="flex justify-center">
-  <Image
-    src="/static/logs/logs.png"
-    alt="The current workspace Logs page"
-    width={1064}
-    height={800}
-    className="my-6"
-  />
-</div>
-
-## Log details
-
-Click any entry to open its sidebar: the run's timeline (start/end, total duration, per-block timing) and each block's data flow.
-
-<div className="flex justify-center">
-  <Image
-    src="/static/logs/logs-sidebar.png"
-    alt="The current Log Details sidebar with run metadata, output, and credit total"
-    width={518}
-    height={760}
-    className="my-6 mx-auto h-auto w-full max-w-sm"
-  />
-</div>
-
-<Tabs items={['Output', 'Input']}>
-  <Tab>
-    The block's result — JSON-formatted structured data, markdown rendering for AI content, and a copy button.
-  </Tab>
-  <Tab>
-    What the block received — resolved variable values, referenced outputs, and environment variables. Exact secret values activated by a successful `{{KEY}}` substitution are masked in this trace view. See [Execution log protection](/platform/credentials#execution-log-protection).
-  </Tab>
-</Tabs>
-
-## Workflow snapshots
-
-**View Snapshot** opens a frozen copy of the workflow exactly as it was at run time — structure, block states, connections — and each block is clickable to its inputs and outputs. This is how you debug a run of a workflow you've since changed.
-
-<div className="flex justify-center">
-  <Image
-    src="/static/logs/logs-frozen-canvas.png"
-    alt="Workflow Snapshot"
-    width={600}
-    height={628}
-    className="my-6 mx-auto h-auto w-full max-w-md"
-  />
-</div>
-
-<Callout type="info">
-Snapshots exist for runs after the enhanced logging system was introduced. Older migrated logs show "Logged State Not Found".
-</Callout>
+Use **Logs** to find recorded runs in your workspace. Use the workflow builder's console to watch a manual or chat run as it executes. For a debugging procedure, see [Trace a failure](/logs-debugging).
 
-## Retention
+## Find a run
 
-- **Free**: 7 days — logs are archived to cloud storage, then deleted.
-- **Pro / Team / Enterprise**: retained indefinitely.
+The list shows workflow, date, status, cost in credits, trigger, and duration. Filter by time range, status, trigger, folder, or workflow. Search text matches run IDs; it does not search arbitrary input or output text. Structured filters also support date, duration, and cost. For example:
 
-## Next
+```text
+status:error workflow:"Support" duration:>5s
+```
 
-- [Alerts](/logs-debugging/alerts) for notifications on failures and slow runs
-- [Cost calculation](/platform/costs) for what each run costs
-- [External API](/api-reference/getting-started) for programmatic log access
+The list holds a stable snapshot. Select **Refresh**, **N new logs**, or **Updates available** to load new or changed runs. With editing access, select **Export** to download a CSV using the current filters.
+
+<Image
+  src="/static/logs/logs.png"
+  alt="Workspace Logs list with workflow, date, status, credits, trigger, and duration columns"
+  width={1064}
+  height={800}
+/>
+
+## Read log details
+
+Select an entry to open **Log Details**. The run records its execution ID, workflow ID, trigger, start and end timestamps, duration in milliseconds, final output, trace spans, and associated files where available. Use the copy controls to copy identifiers or data.
+
+### Overview
+
+**Overview** shows run metadata and available **Workflow Input**, **Workflow Output**, and cost details. Current usage-ledger itemization can include **Base Run**, model and tool usage, and token totals. Older runs may have a total without itemized rows.
+
+### Trace
+
+**Trace** shows the block and child spans with their timing and status. Select a span to inspect stacked, collapsible **Input**, **Output** or **Error**, and any **Thinking** or **Error message** sections. Inputs contain resolved variable values and referenced outputs. Structured data can be inspected and copied; agent text can render as Markdown.
+
+Workspace access settings govern which trace, workflow data, snapshot, and cost details are visible. Protected resolved secret values are masked in the log-facing copy, subject to documented exceptions. See [Permission groups](/enterprise/access-control) and [Execution log protection](/platform/credentials#execution-log-protection).
 
-import { FAQ } from '@/components/ui/faq'
+## Watch a manual run
 
-<FAQ items={[
-  { question: "What data is captured in each run log?", answer: "Each log entry includes the run ID, workflow ID, trigger type, start and end timestamps, total duration in milliseconds, cost breakdown (total cost, token counts, and per-model breakdowns), run data with trace spans, final output, and any associated files. The log details sidebar lets you inspect block-level inputs and outputs." },
-  { question: "Are saved secrets visible in logs?", answer: "When a value saved under Secrets is successfully substituted through {{KEY}}, exact, case-sensitive occurrences are masked throughout the log-facing copy, including the live block-log display, Logs Overview input and output, Trace, log-read APIs, and the Logs block's Get Run Details output. Direct reads such as environmentVariables['KEY'] or shell $KEY also activate masking when Sim can recognize the read in the code beforehand; a name built at runtime, a reassigned binding, or a hardcoded literal is not recognized. This is not a general redactor: encoded, hashed, or transformed values are not matched. Functional execution responses, streams, and callbacks remain unchanged. See Execution log protection under Secrets for details." },
-]} />
+During manual or chat runs, the workflow builder's console highlights active blocks and shows outputs as they complete, per-block timing, and success or error status. Select a block and use its **Output** and **Input** tabs to inspect values as a typed tree. These console tabs are separate from the recorded run's trace sections.
+
+## Open the run snapshot
+
+Select **View Snapshot** to inspect the saved workflow structure, block configurations, and connections from that run, where available. Inspect its blocks and recorded inputs and outputs to compare the version that ran with your current draft.
+
+Some older migrated logs have no saved workflow state and show **Logged State Not Found**. A log's existence does not guarantee that a snapshot is available or that your access settings allow it.
+
+## Retention
+
+Sim Cloud Free defaults to 30 days. Paid plans and billing-disabled deployments have no plan-based default log expiry. Organization or workspace policies can change effective retention; cleanup removes expired data rather than providing a recoverable archive. See [Data retention](/enterprise/data-retention).
+
+## Related docs
+
+- [Debug a run](/logs-debugging) for tracing errors through resolved values
+- [Alerts](/logs-debugging/alerts) for notifications on failures and slow runs
+- [Costs](/platform/costs) for run charges and credit units
+- [API getting started](/api-reference/getting-started) for programmatic log access
diff --git a/apps/docs/content/docs/mcp/authentication.mdx b/apps/docs/content/docs/mcp/authentication.mdx
index de694a2066c..471f62bf165 100644
--- a/apps/docs/content/docs/mcp/authentication.mdx
+++ b/apps/docs/content/docs/mcp/authentication.mdx
@@ -1,15 +1,15 @@
 ---
 title: Authentication
-description: Sign in with OAuth, or connect with an API key
+description: Choose OAuth access or an API key, and revoke access when it is no longer needed.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
+Use OAuth for an app that supports browser sign-in. Use an API key for a client that needs a fixed credential. Both remain subject to the credential's current resource access and operation permissions.
+
 ## OAuth
 
-Most apps sign in with OAuth. The first time you connect, your app opens Sim in
-the browser, you sign in, and you approve its access. The app then holds a
-token that renews itself; you do not copy any secret.
+On first connection, your app opens Sim in the browser. Sign in and review the requested access before approving it. The app stores a one-hour access token, so you do not copy a secret. With `offline_access`, it can refresh access for up to 30 days from the initial grant; after that, sign in again. Refreshing does not extend that fixed lifetime.
 
 The approval screen names the app and what it can do:
 
@@ -18,9 +18,7 @@ The approval screen names the app and what it can do:
 | Read-only | `api:read` | Reading workspaces, workflows, runs, tables, files, knowledge bases, and logs |
 | Full | `api:write` | Everything above, plus creating, changing, running, deploying, and deleting |
 
-Most apps request full access. To connect an app for reads only, configure it
-to request the `api:read` scope; changes then fail with an insufficient-scope
-error.
+For reads only, configure the app to request `api:read`; changes then fail with an insufficient-scope error. A token's scope does not grant a workspace role or bypass resource permissions.
 
 Tokens are issued for the Sim MCP server itself. An app cannot take one to
 another service and use it there.
@@ -53,18 +51,22 @@ claude mcp add --transport http sim https://mcp.sim.ai/mcp \
 }
 ```
 
-A personal key acts as you in every workspace you can access. A workspace key
-reaches only its own workspace, and a few account-level operations refuse it;
-`search_operations` marks them `personalCredentialOnly`.
+A personal key uses your current access in the workspaces you can reach. A workspace key reaches only its own workspace and follows workspace-key operation and role policies rather than its creator's human permission group. Some operations refuse workspace keys; `search_operations` marks them `personalCredentialOnly`.
+
+The Cursor process must receive `SIM_API_KEY` for its environment interpolation to work. For a self-hosted deployment, replace the Cloud URL in both examples with your server URL.
 
 <Callout type="warn">
-  An API key does not expire until you revoke it. Prefer OAuth for any app that
-  can open a browser, and store keys in your app's secret or environment
+  Keys created in Sim settings have no default expiration. Revoke a key when it is no longer needed. Prefer OAuth for an app that
+  supports browser sign-in, and store keys in your app's secret or environment
   settings rather than in a shared config file.
 </Callout>
 
 ## Organization policy
 
-The server follows your organization's access policy. If an administrator turns
-off **OAuth apps** or **personal API keys** for your permission group, requests
-with that credential are refused in the affected workspaces.
+Organization policy can restrict personal credentials in affected workspaces. The **Personal API Keys** policy applies to personal API-key and OAuth requests; OAuth requests also require **OAuth App Access**. OAuth approval and refresh remain subject to organization policy. See [Permission groups](/enterprise/access-control) for policy resolution.
+
+## Related docs
+
+- [Connect an app](/mcp/overview) for server URLs and client configuration
+- [API authentication](/api-reference/authentication) for key creation and credential scope
+- [Tools](/mcp/tools) for read and write operation behavior
diff --git a/apps/docs/content/docs/mcp/overview.mdx b/apps/docs/content/docs/mcp/overview.mdx
index dee6082ea4f..8d4994f4067 100644
--- a/apps/docs/content/docs/mcp/overview.mdx
+++ b/apps/docs/content/docs/mcp/overview.mdx
@@ -1,24 +1,22 @@
 ---
 title: Sim MCP
-description: Build, run, and manage everything in your Sim workspace from Claude, Codex, Cursor, and other MCP apps
+description: Connect an AI app to Sim's JSON API operations through MCP.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 
-The Sim MCP server gives an AI app the whole Sim API through the
-[Model Context Protocol](https://modelcontextprotocol.io). Your agent can list
-workspaces, run and deploy workflows, query and edit tables, manage files and
-knowledge bases, read run logs, and more. It covers the same operations as the
-[API](/api-reference/getting-started) and the [CLI](/cli).
+Connect an AI app to Sim to manage workspaces, run and deploy workflows, and work with tables, files, knowledge bases, and logs. Sim MCP exposes JSON API operations through the [Model Context Protocol](https://modelcontextprotocol.io), a standard for connecting AI apps to tools. See [Tools](/mcp/tools) for supported requests and limits.
+
+## Choose the server URL
 
 | Deployment | Server URL |
 | --- | --- |
 | Sim Cloud | `https://mcp.sim.ai/mcp` |
 | Self-hosted | `https://<your-sim-host>/api/mcp`, or your [`SIM_MCP_URL`](/platform/self-hosting/environment-variables) |
 
-The server uses the Streamable HTTP transport. Sign in with OAuth, the default
-in every app below, or send an [API key](/mcp/authentication#api-keys).
+The server uses Streamable HTTP. Sign in with OAuth or send an [API key](/mcp/authentication#api-keys). Replace the Cloud URL in every example below when connecting to a self-hosted deployment.
+
+Claude's hosted connectors call from Anthropic's infrastructure, so your server must be reachable from it over the internet. A `localhost` URL works with clients that connect from your machine, such as Claude Code, Codex, Cursor, and VS Code. See [Claude's network requirements](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
 
 ## Connect an app
 
@@ -32,9 +30,9 @@ in every app below, or send an [API key](/mcp/authentication#api-keys).
     browser.
   </Tab>
   <Tab value="Claude">
-    Add `https://mcp.sim.ai/mcp` as a custom connector under **Settings →
+    Add `https://mcp.sim.ai/mcp` as a custom connector under **Customize →
     Connectors**, then connect it and sign in to Sim. For Team or Enterprise,
-    an owner first adds it under **Organization settings → Connectors**. See
+    an authorized organization administrator first adds it under **Organization settings → Connectors**. If asked for an OAuth client strategy, choose **Register automatically**. See
     [Claude's custom connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
   </Tab>
   <Tab value="Codex">
@@ -70,15 +68,7 @@ in every app below, or send an [API key](/mcp/authentication#api-keys).
   </Tab>
 </Tabs>
 
-Any other app that supports remote MCP servers with OAuth works the same way:
-give it the server URL and choose **Streamable HTTP** if asked.
-
-<Callout type="info">
-  Claude's hosted connectors call your server from Claude's infrastructure, so a
-  self-hosted Sim must be reachable from the internet. A `localhost` URL works
-  only with apps that run on your machine, such as Claude Code, Codex, Cursor,
-  and VS Code.
-</Callout>
+For another app that supports remote MCP servers with OAuth, enter the server URL and choose **Streamable HTTP** if asked. Follow that app's connection and sign-in procedure.
 
 ## Try it
 
@@ -92,18 +82,22 @@ Ask your app:
 The agent finds the right operation, reads its inputs, and calls it. See
 [Tools](/mcp/tools) for how that works.
 
-## What your agent can do
+## Access and approvals
 
-The server acts as you. It sees the workspaces you can see, with your role in
-each, and every call is authorized, rate limited, and logged exactly like the
-same request to the API. Reads leave your resources unchanged, and apps can ask
-you to confirm each change. See [Authentication](/mcp/authentication) to limit
-an app to reads.
+Access follows the connection credential, workspace role, and operation policy. Each call uses the API's authorization, rate limits, validation, and logging. Personal credentials use your current access; workspace API keys are limited to their workspace. See [Authentication](/mcp/authentication) to choose credential scope or read-only OAuth access.
+
+The server separates read and write tools; your app controls whether it asks for confirmation before a change.
 
 ## Other Sim MCP surfaces
 
-This server is for operating Sim. Two other MCP features do different jobs:
+These features have separate purposes:
 
 - [Search MCP](/search/mcp) searches your organization's live provider sources with current access checks.
 - [MCP deployment](/workflows/deployment/mcp) exposes your own workflows as
   tools, and [MCP tools](/agents/mcp) connect external servers to Sim agents.
+
+## Related docs
+
+- [Authentication](/mcp/authentication) for scopes, credentials, and revocation
+- [Tools](/mcp/tools) for operation discovery, calls, and result limits
+- [API getting started](/api-reference/getting-started) and [CLI](/cli) for other ways to operate Sim
diff --git a/apps/docs/content/docs/mcp/tools.mdx b/apps/docs/content/docs/mcp/tools.mdx
index 6bf6e0fee84..600892d00e3 100644
--- a/apps/docs/content/docs/mcp/tools.mdx
+++ b/apps/docs/content/docs/mcp/tools.mdx
@@ -1,12 +1,11 @@
 ---
 title: Tools
-description: How an agent finds, reads, and calls Sim operations through four tools
+description: Discover an operation, inspect its request, and call it with the correct access.
 ---
 
-The Sim API has more than 200 operations. Instead of one tool per operation,
-which would crowd your app's tool list and your agent's context, the server
-exposes four tools. The agent searches for an operation, reads its inputs, and
-calls it.
+Sim MCP exposes four tools for discovering and calling its supported JSON API operations. Search for an operation, inspect its inputs, then call the read or write tool named in its description.
+
+## Tools
 
 | Tool | Does |
 | --- | --- |
@@ -15,8 +14,9 @@ calls it.
 | `call_read_operation` | Runs an operation that only needs read access, such as `listWorkspaces`, `queryRows`, or `getWorkflowRun`. |
 | `call_write_operation` | Runs an operation that needs write access: one that creates, changes, runs, or deletes something, or reaches out to another service, such as `createTable`, `executeWorkflow`, or `listMcpServerTools`. |
 
-Reads and writes are separate tools so your app can approve reads once and still
-ask you before each change.
+The operation's required access determines the tool, rather than its HTTP method: a read can use POST, and a GET that contacts another service can require write access. Your app controls tool approvals.
+
+`search_operations` returns the total number of matches and at most `limit` operations: 25 by default, 100 maximum. Catalog search has no cursor. Narrow the keywords or `domain` when matches exceed that limit; this is separate from paginating API resources.
 
 ## Calling an operation
 
@@ -36,11 +36,25 @@ fills the parts of the request it needs:
 | --- | --- |
 | `params` | Path parameters, such as `tableId` or `workflowId` |
 | `query` | Query-string parameters; most operations need `workspaceId` |
-| `body` | The JSON request body (write operations only) |
-| `headers` | Headers the operation declares, such as `upload-token` |
+| `body` | The JSON request body when the operation declares one, including read operations such as `queryRows` |
+| `headers` | Only headers the operation declares, such as `upload-token` |
 
-The result is the same JSON the API returns, usually `{ "data": … }`. List
-operations page with `limit` and `cursor`. A failed call returns the API's error,
+For example, `queryRows` uses the read tool with a JSON body:
+
+```json
+{
+  "operation": "queryRows",
+  "params": { "tableId": "tbl_8f2c" },
+  "body": { "workspaceId": "ws_91ab", "limit": 50 }
+}
+```
+
+Keep authentication in your app's connection configuration. You cannot pass undeclared authentication or protocol headers, including `X-API-Key`, `Authorization`, or `Accept`, through the call's `headers` field.
+
+## Results and errors
+
+The result is the same JSON the API returns, usually `{ "data": … }`. Paginated list
+operations use `limit` and `cursor`; check the operation because some lists do not support pagination. A failed API call returns its error,
 such as `{ "error": { "code": "NOT_FOUND", "message": "…" } }`, so the agent can
 correct its request.
 
@@ -48,8 +62,14 @@ correct its request.
 
 - **Same rules as the API.** Permissions, rate limits, and request validation
   are the API's own; nothing is looser through MCP.
-- **1 MiB per result.** Page through larger lists with `limit` and `cursor`.
+- **1 MiB per API result.** Request smaller pages for paginated lists. A single-resource result may also exceed the limit. The size check happens after the API executes: if a write returns a size error, check the resource state before repeating it because the change may already have succeeded.
 - **No streaming.** Run a workflow without `stream: true` to wait for its
   result, or with `async: true` and poll `getWorkflowRun`.
 - **No file bytes.** Downloads, knowledge base exports, and multipart document
   uploads are not available over MCP; use the [CLI](/cli/files) or the API.
+
+## Related docs
+
+- [Authentication](/mcp/authentication) for scopes and credential access
+- [API getting started](/api-reference/getting-started) for response and pagination contracts
+- [Workflow runs](/workflows/deployment/api) for synchronous and asynchronous execution
diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json
index 649510a1483..255c174d82c 100644
--- a/apps/docs/content/docs/meta.json
+++ b/apps/docs/content/docs/meta.json
@@ -1,7 +1,7 @@
 {
-  "title": "Sim Documentation",
+  "title": "Sim documentation",
   "pages": [
-    "---Get Started---",
+    "---Get started---",
     "./introduction/index",
     "./getting-started/index",
     "./desktop/index",
diff --git a/apps/docs/content/docs/platform/connected-accounts.mdx b/apps/docs/content/docs/platform/connected-accounts.mdx
index 3127c214355..43272029f90 100644
--- a/apps/docs/content/docs/platform/connected-accounts.mdx
+++ b/apps/docs/content/docs/platform/connected-accounts.mdx
@@ -1,118 +1,123 @@
 ---
 title: Credential Groups
-description: Collect accounts in one organization credential group and control which workspaces can use them.
+description: Collect account connections for an organization and grant workspaces access by integration.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
-**Credential Groups** collects people's accounts in one shared pool for your organization, also called a **credential group**. An organization admin chooses the providers, invites people to connect, and allows specific workspaces to use the pool. Workflows in those workspaces can find an account by email through the [Credential block](/workflows/blocks/credential).
+**Credential Groups** collects people's account connections in one organization pool. Organization administrators configure providers, request connections, and choose which integrations each workspace may use. Workflows find an account by invitation email through the [Credential block](/workflows/blocks/credential).
 
-Each organization has at most one pool. Creating it does not give any workspace access; the workspace allowlist starts empty.
+An organization has at most one pool. Its workspace access starts empty.
 
-## Availability
+## Availability and access
 
-Sim Cloud requires an active Enterprise plan. Organization owners and admins manage the pool, subject to the organization's permission settings. A workspace admin who is not an organization admin cannot change the pool or its workspace access.
+Sim Cloud requires an active Enterprise plan. On self-hosted deployments, enable `CREDENTIAL_GROUPS=true`, or `ENTERPRISE_ENABLED=true` for the enterprise suite. Personal workspaces cannot use an organization pool.
 
-For self-hosted deployments, set `CREDENTIAL_GROUPS=true`, or `ENTERPRISE_ENABLED=true` to enable the whole enterprise suite. Availability is organization-scoped; personal workspaces cannot use an organization pool.
+Organization owners and admins manage **Settings → Credential Groups**, subject to permission settings. Workspace Admin access alone does not allow changing the pool or its grants.
 
-Manage the pool under **Settings → Credential Groups**. It remains available independently of Search. Search administrators use **Settings → Sources**, while members connect personal Search accounts under **Integrations** in the main sidebar. These surfaces can share grants without sharing their purpose or resource settings.
+Credential Groups is available independently of Search. Search administrators configure **Settings → Sources**; members connect personal Search accounts under **Integrations**. Adding a provider to Credential Groups does not create a Search source or start indexing. Managed MCP connections support live tool calls.
 
-## Set up connected accounts
+## Set up the pool
 
-Open your organization’s **Settings → Credential Groups**. Select **Set up connected accounts** if this is your first time.
+Open the organization's **Settings → Credential Groups**. If no pool exists, select **Set up Credential Groups**.
 
-The page has three tabs:
-
-| Tab | What you manage |
+| Tab | Purpose |
 | --- | --- |
-| **Providers** | Services people can connect and their shared configuration |
-| **People** | Connection requests, each person's connected accounts, and revocation |
-| **Workspace access** | Workspaces allowed to use the organization's accounts |
+| **Integrations** | Add providers and manage their shared configuration |
+| **People** | Request connections, inspect accounts, resend invitations, and revoke access |
+| **Access** | Grant a workspace all or selected integrations |
 
-### 1. Add providers
+### 1. Add integrations
 
-In **Providers**, select **Add provider** and search the catalog. Complete any required configuration before adding the provider. Added providers appear in the list; use **Configure** to edit their settings or **Remove** in the row menu to remove them.
+In **Integrations**, select **Add integration**, search the catalog, and complete any required setup. Use **Configure** to change an added provider's settings or **Remove** in its menu to remove it.
 
-| Provider | Organization setup |
+| Provider | Required organization setup |
 | --- | --- |
-| OAuth providers, such as Gmail or Google Drive | Add the provider from the available catalog. Each invited person authorizes their account. |
-| Slack | Supply the Slack App ID, Slack workspace ID, OAuth client ID, and client secret, then complete app verification. The organization uses one app and Slack workspace. Existing workspace Slack bots remain separate. |
-| Fireflies and Granola | Add the provider. Sim supplies the MCP endpoint and handles OAuth client registration. People only complete their own authorization. |
-| HubSpot (member access) | The deployment supplies a registered HubSpot MCP OAuth app. People sign in and allow CRM read access. See [HubSpot Search](/search/hubspot). |
-| Databricks | Enter a name, the tenant's MCP URL, a registered OAuth client ID, and a client secret if required by that client. |
-
-For Databricks, **Add** validates and saves the configuration before the provider appears in the list. Cancelling the form leaves nothing added. Use an official Databricks HTTPS MCP endpoint, such as `https://your-workspace.cloud.databricks.com/api/2.0/mcp/sql`, and the OAuth client registered for your deployment. People connecting later use this organization configuration.
+| OAuth providers such as Gmail or Google Drive | Add the provider; each invited person authorizes their account |
+| Slack | Supply the Slack App ID, Slack workspace ID, OAuth client ID, and client secret, then verify the app; the organization uses one app and Slack workspace |
+| Fireflies and Granola | Add the provider; Sim supplies the MCP endpoint and handles OAuth client registration |
+| HubSpot member access | The deployment must supply a registered HubSpot MCP OAuth app; people authorize CRM read access; see [HubSpot Search](/search/hubspot) |
+| Databricks | Enter a name, the tenant's HTTPS MCP URL, a registered OAuth client ID, and a client secret if that client requires one |
 
-When editing Databricks, leaving the client secret blank preserves the saved secret. Changing the MCP URL or OAuth client requires people to reconnect.
+Existing workspace Slack bots and their triggers remain separate from the organization's personal Slack connections.
 
-Adding a provider makes account connections available; it does not add a Search source or start document indexing. Search source setup is managed under **Settings → Sources**. Live Search queries providers on demand. Credential Groups has no indexing controls or status indicators. Managed MCP providers support live tool calls.
+For Databricks, use an official endpoint such as `https://your-workspace.cloud.databricks.com/api/2.0/mcp/sql` and the OAuth client registered for the deployment. **Add** validates and saves the configuration before the provider appears; cancelling adds nothing. Leaving the client secret blank while editing preserves it. Changing the endpoint or OAuth client requires people to reconnect.
 
-### 2. Invite people
+### 2. Request connections
 
-Open **Settings → Credential Groups → People**. Set up the provider before inviting people; a Search source does not replace required OAuth or managed MCP configuration.
+Configure the providers before inviting people. A Search source does not replace required OAuth or managed MCP setup.
 
-1. Select **Request connections**.
-2. Enter their email addresses and select **Send requests**.
-3. Each person opens the invitation, signs in to Sim with the verified invitation email, and authorizes the providers they want to connect.
-4. They select **Submit** to finish the connection form.
+1. Open **People** and select **Request connections**.
+2. Enter email addresses and select **Send requests**.
+3. Each invitee opens the invitation, signs in with its verified Sim email, and authorizes the providers they want to contribute.
+4. They select **Submit** to finish the form.
 
-Invitees can contribute accounts without joining your organization. The invitation grants access to their connection form; it does not grant access to your workspaces or workflows.
+Invitees can contribute accounts without joining your organization. The invitation gives access to the connection form, not to your workspaces or workflows.
 
-Use the invitation email in workflow lookups. For example, if you invite `alex@example.com`, **Find Organization Account** with that email and **Gmail** finds Alex's active Gmail contribution.
+Use the invitation email for workflow lookups. For example, inviting `alex@example.com` lets **Find Organization Account** look up Alex's active Gmail contribution with that email and **Gmail**.
 
 #### How the email is associated with a Sim user
 
-On first use, the invitation email must match the signed-in user's verified Sim email. Sim then binds the invitation to that user's account. Another person cannot take it over by opening the link, and a later email change does not transfer it to a different Sim user. The invitation email remains the workflow lookup key.
+On first use, the invitation email must match the signed-in user's verified Sim email. Sim binds the invitation to that user account. Opening the link as another person cannot take it over, and a later email change does not transfer it to another Sim user. The invitation email remains the workflow lookup key.
 
-The verified Sim user who starts authorization must complete it. A provider account can use a different email from the invitation; the saved contribution belongs to the bound Sim user. Managed MCP connections likewise use that Sim user’s authorization. Keep using the invitation email for workflow lookups. Search separately checks current provider identity and any source-specific requirements.
+The verified Sim user who starts authorization must complete it. The provider account may have a different email; its contribution belongs to the bound Sim user. Managed MCP connections use that person's authorization too. Search separately checks current provider identity and source-specific access requirements.
 
-In **People**, open a person's actions menu and select **Resend** when they need another invitation. **Revoke** stops the organization from using that person's contributions. The person cannot undo an administrator's revocation by reconnecting on their own.
+Use **Resend** in a person's menu when they need the invitation again. **Revoke** stops the organization from using their contributions. They cannot undo an administrator's revocation by reconnecting themselves.
 
-### 3. Allow workspaces
+### 3. Grant workspace access
 
-Open **Workspace access** and select **Add workspaces** to choose one or more workspaces. The list shows workspaces that have access; use a row's **Remove** action to withdraw it. Adding or removing a workspace applies immediately. Only workspaces in this organization can be allowed.
+1. Open **Access** and select **Add workspace**.
+2. Choose one workspace in this organization.
+3. Under **Integrations**, choose specific integration types or **All integrations**.
+4. Select **Add workspace** to save the grant.
 
-<Callout>
-An allowed workspace gives every authorized manual and deployed workflow in that workspace access to **every active account in the pool**. This includes scheduled, webhook, and public deployments that pass their normal workflow authorization. There is no separate workflow allowlist or restriction to the running user's own contributions.
+A selected grant requires at least one integration. **All integrations** also includes integrations added to the pool later. Use **Edit access** to change the selection, **Save access** to save it, or **Remove access** to withdraw the grant.
+
+<Callout type="warn">
+Every normally authorized workflow in the workspace can use active accounts for its allowed integration types, including scheduled, webhook, and public deployments. There is no separate workflow allowlist or restriction to the running person's own contributions. Choose **All integrations** only when this exposure is intended.
 </Callout>
 
-For example, allowing the Support workspace lets its authorized workflows use Alex's Gmail contribution even when someone else runs the workflow. Allowing the workspace does not grant anyone permission to edit or run a workflow they could not otherwise access.
+For example, allowing Gmail in the Support workspace lets its authorized workflows use Alex's Gmail contribution even when someone else runs them. The grant does not give anyone permission to edit or run a workflow they could not otherwise access.
 
-Removing a workspace stops subsequent use of the pool. It does not recall provider requests already in flight or remove data a workflow has already received. Chat continues to use each person's own connections; workspace access does not give Chat access to other people's accounts.
+Changes apply to subsequent calls. Removing access cannot recall a provider request already in flight or erase data already received. Standalone Chat continues to use each person's own connections; the workspace grant does not give Chat other people's accounts.
 
-## Use accounts in workflows
+## Use account references in workflows
 
-Use the **Credential** block's organization operations in an allowed workspace:
+In an eligible workspace, use the Credential block's organization operations:
 
-- **Find Organization Account** selects an OAuth account by invitation email and provider.
-- **List Organization Accounts** returns a page of OAuth accounts, optionally filtered by email and providers.
-- **Find Organization MCP Connection** selects a person's managed MCP connection by invitation email and MCP provider.
-- **List Organization MCP Connections** returns a page of managed MCP connections, optionally filtered by email and provider.
+| Operation | Result |
+| --- | --- |
+| **Find Organization Account** | One OAuth account matching the invitation email and provider |
+| **List Organization Accounts** | A page of OAuth accounts, optionally filtered by email and providers |
+| **Find Organization MCP Connection** | One managed MCP connection matching the invitation email and MCP provider |
+| **List Organization MCP Connections** | A page of managed MCP connections, optionally filtered by email and provider |
 
-The organization is determined by the workflow's workspace. You do not enter a credential group ID or organization ID in the block.
+The workflow's workspace determines the organization. You do not enter a credential group or organization ID.
 
-The outputs are account references, without tokens. Use an OAuth `credentialId` in the corresponding integration block's credential field. For managed MCP, `credentialId` identifies the person's connection; `mcpServerId` identifies shared configuration and cannot select that person's authorization by itself.
+Outputs contain account references, not tokens. Use an OAuth `credentialId` in a compatible integration block's credential field. For managed MCP, `credentialId` selects the person's connection. `mcpServerId` identifies shared configuration and cannot select that person's authorization by itself.
 
 See the [Credential block reference](/workflows/blocks/credential#organization-accounts) for inputs, outputs, pagination, and connection-event triggers.
 
 ## Reconnect or stop sharing
 
-People can open **Settings → Account → Connected accounts** to view accounts they contributed, including contributions to organizations they have not joined. **Reconnect** starts authorization again. **Disconnect** stops the organization from using that account in subsequent calls.
+Contributors can open **Settings → Account → Connected accounts** to inspect their contributions, including contributions to organizations they have not joined. **Reconnect** starts authorization again. **Disconnect** stops subsequent organization use of that account.
 
-For administrators, the controls have different scopes:
+Administrative controls have different scopes:
 
 | Action | Effect |
 | --- | --- |
-| Remove a provider | Stops use of that provider's contributions in the pool |
-| Revoke a person | Stops use of all that person's contributions to the organization |
-| Remove a workspace from the allowlist | Stops that workspace's workflows from using the pool |
-
-## Current limits and troubleshooting
-
-- **One pool per organization:** there are no additional groups, per-workflow grants, or per-account workspace allowlists.
-- **One Databricks configuration:** multiple tenant endpoints cannot be added as separate Databricks providers in the same pool.
-- **Organization operations are missing:** confirm the feature is enabled for the organization and the workflow's workspace is allowed.
-- **An invitation rejects your sign-in:** use the verified Sim account matching the invitation email. The provider account can have a different email; the invitation stays bound to the verified Sim user.
-- **A Find operation fails:** it requires exactly one active matching connection. Check the invitation email, provider, connection status, and workspace access. It never chooses an arbitrary account when there are zero or multiple matches.
-- **A list seems incomplete:** organization list operations return up to 100 connections per page. Follow `nextCursor` while `hasMore` is true.
-- **A legacy Credential Group block fails:** replace it with the appropriate Credential block operation or trigger, update its output references, and redeploy the workflow.
+| Remove an integration | Stops use of that provider's contributions in the pool |
+| Revoke a person | Stops use of all their contributions to the organization |
+| Change a workspace grant | Limits it to the selected integration types |
+| Remove a workspace grant | Stops its workflows from using the pool |
+
+## Limits and troubleshooting
+
+- **Pool and grant limits:** one pool per organization and up to 1,000 workspace grants. Grants select integration types, not individual people's accounts. There is no separate per-workflow allowlist.
+- **Databricks:** one tenant configuration per pool; multiple endpoints cannot be added as separate Databricks providers.
+- **Missing organization operations:** check organization availability, the workspace grant, and its selected integration types.
+- **Rejected sign-in:** use the verified Sim account matching the invitation email. The provider account can have a different email.
+- **Failed Find operation:** it requires exactly one active match. Check email, provider, connection status, and allowed integration type. Zero or multiple matches cause an error; Sim does not choose an arbitrary account.
+- **Incomplete list:** list operations return up to 100 connections per page. Follow `nextCursor` while `hasMore` is true.
+- **Migration-review error:** an operator must review existing pool policies and Search dependencies before enabling workflow sharing. Setting the feature flag does not migrate old grants; affected people may need to reconnect.
+- **Legacy Credential Group block:** replace it with the appropriate Credential operation or trigger, update output references, and redeploy.
diff --git a/apps/docs/content/docs/platform/costs.mdx b/apps/docs/content/docs/platform/costs.mdx
index 583f1aceb73..9f77c9e5829 100644
--- a/apps/docs/content/docs/platform/costs.mdx
+++ b/apps/docs/content/docs/platform/costs.mdx
@@ -1,528 +1,317 @@
 ---
-title: Cost calculation
+title: Credits, billing and limits
+description: Understand Cloud usage charges, BYOK, subscriptions, spend controls, and execution limits.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { Image } from '@/components/ui/image'
+import { Tab, Tabs } from '@/components/ui/tabs'
 
-Sim calculates workflow usage from the base run charge, billable model usage, and hosted tool usage.
+Sim Cloud measures billable usage in **credits**: **1 credit = $0.005**, or **$1 = 200 credits**. For example, $10 of usage is 2,000 credits.
 
-## Credits
+The plan and execution tables below describe Cloud defaults. Enterprise agreements and deployment configuration can change them. Billing-disabled self-hosted deployments do not apply Sim plan-based usage billing; provider and infrastructure costs still apply. See [Self-hosted limits](#self-hosted-limits).
 
-Sim uses **credits** as the unit of measurement for all usage. **1 credit = $0.005**.
+## What a workflow run costs
 
-All plan limits, usage meters, and billing thresholds are displayed in credits throughout the Sim UI. Dollar amounts in this documentation are provided for reference.
+A billable workflow run can include:
 
-## How Costs Are Calculated
+| Component | Charge |
+| --- | --- |
+| Base run | 1 credit ($0.005), including runs without model calls |
+| Hosted models | Recorded model usage at the applicable Sim rate |
+| Hosted tools | Operation charges when using Sim-provided provider keys |
+| Sandbox runtime | Applicable runtime charges, such as a Pi sandbox |
 
-Workflow runs can include these cost components:
+With your own provider keys, you pay the provider directly for those calls. The workflow base charge and unrelated hosted-tool or sandbox usage still apply. Local Ollama or vLLM inference avoids an external model API charge, but still needs infrastructure and any enabled Sim run charge.
 
-**Base Run Charge**: 1 credit ($0.005) per run
-
-**AI Model Usage**: Variable cost based on token consumption.
-
-**Hosted Tool Usage**: Per-operation charges for tools using Sim-provided keys.
+For a simple uncached model call, with prices in USD per million tokens:
 
 ```text
-modelCost = (inputTokens × inputPrice + outputTokens × outputPrice) / 1,000,000
-totalCredits = baseRunCharge + (billableModelCost + hostedToolCost) × 200
+modelCostUSD = (inputTokens × inputPrice + outputTokens × outputPrice) / 1,000,000
+runCredits = 1 + billableModelCostUSD × 200 + hostedToolCostUSD × 200 + sandboxCostUSD × 200
 ```
 
-<Callout type="info">
-  AI model prices are per million tokens. A workflow with no billable model usage or hosted tool usage incurs only the base run charge.
-</Callout>
+Cached input, cache writes, model routing, and provider-specific usage can change the calculation. Use the recorded run cost to compare configurations. Internal child executions that share their parent's base charge do not add another base fee.
 
-## Model Breakdown in Logs
+### Inspect recorded usage
 
-For workflows using AI blocks, you can view detailed cost information in the logs:
+Open a run in **Logs → Overview** to inspect its cost rows, **Total**, and available input/output token counts. Current runs list ledger items such as **Base Run** and model or tool charges. Older runs may contain only a total. Displayed credit rows are apportioned so they add up to the displayed total.
 
-<div className="flex justify-center">
-  <Image
-    src="/static/logs/logs-cost.png"
-    alt="Model Breakdown"
-    width={600}
-    height={153}
-    className="my-6"
-  />
-</div>
+Chat, Knowledge Base processing, and dictation also record usage outside ordinary workflow runs. The **Agent block** source label in organization Insights refers to the **Sim Chat** workflow block, whose usage is metered separately from its containing workflow. Ordinary Agent model calls are part of Workflow usage. See [Usage monitoring](/platform/enterprise/usage-tracking) for attribution.
 
-The model breakdown shows:
-- **Token Usage**: Input and output token counts for each model
-- **Cost Breakdown**: Individual costs per model and operation
-- **Model Distribution**: Which models were used and how many times
-- **Total Cost**: Aggregate cost for the entire workflow run
+### Hosted tool rates
 
-## Pricing Options
+These are configured hosted-tool base rates in USD, not a provider's retail subscription price. Actual usage is recorded per operation. A provider credit, such as a Firecrawl credit, is a different unit from a Sim credit.
 
-With Sim-provided model keys, model usage is billed through Sim. With your own keys, you pay the provider directly; the workflow base charge still applies. Check the provider's current pricing when estimating a run, and use the run's recorded usage to compare configurations.
+| Provider | Operation | Base rate |
+| --- | --- | --- |
+| Firecrawl | Scrape, Crawl, Search, Extract, Map | $0.001 per Firecrawl credit reported by the operation |
+| Exa | Search, Get Contents, Find Similar Links, Answer | Cost returned by the API |
+| Serper | Search with up to 10 results | $0.001 |
+| Serper | Search with more than 10 results | $0.002 |
+| Perplexity | Search | $0.005 per request |
+| Perplexity | Chat | Token-based, depending on the model |
+| Linkup | Standard search | $0.006 |
+| Linkup | Deep search | $0.055 |
+| Parallel AI | Turbo or Fast search, up to 10 returned results | $0.001 |
+| Parallel AI | Basic or Advanced search, up to 10 returned results | $0.005 |
+| Parallel AI | Search results beyond 10 | $0.001 per additional returned result |
+| Parallel AI | Extract | $0.001 per URL |
+| Parallel AI | Deep Research | $0.005–$2.40, depending on processor tier |
+| Jina AI | Read URL | $0.20 per million tokens |
+| Jina AI | Search | $0.20 per million tokens, with a 10,000-token minimum |
+| Google Cloud | Translate / Detect | $0.00002 per character |
+| Google Maps | Geocode, Directions, Elevation, Timezone, Reverse Geocode, Geolocate, Validate Address | $0.005 per request |
+| Google Maps | Distance Matrix | $0.005 per returned matrix element |
+| Google Maps | Snap to Roads | $0.01 per request |
+| Google Maps | Place Details | $0.017 per request |
+| Google Maps | Places Search | $0.032 per request |
+| Google Cloud | PageSpeed; Books Search and Details | No hosted-tool charge |
+| Brandfetch | Search | No hosted-tool charge |
+| Brandfetch | Get Brand | $0.04 per request |
 
-## Hosted Tool Pricing
+Supported providers can use your own keys instead. A workflow containing a no-charge tool still has its base run charge.
 
-When workflows use tool blocks with Sim's hosted API keys, costs are charged per operation. Use your own keys via BYOK to pay providers directly instead.
+## Bring your own key (BYOK)
 
-<Tabs items={['Firecrawl', 'Exa', 'Serper', 'Perplexity', 'Linkup', 'Parallel AI', 'Jina AI', 'Google Cloud', 'Brandfetch']}>
-  <Tab>
-    **Firecrawl** - Web scraping, crawling, search, and extraction
-
-    | Operation | Cost |
-    |-----------|------|
-    | Scrape | $0.001 per credit used |
-    | Crawl | $0.001 per credit used |
-    | Search | $0.001 per credit used |
-    | Extract | $0.001 per credit used |
-    | Map | $0.001 per credit used |
-  </Tab>
+Store your provider keys under **Settings → BYOK** to use them instead of Sim-hosted keys. BYOK avoids Sim's model or tool usage charge for the provider calls it covers; you pay that provider directly.
 
-  <Tab>
-    **Exa** - AI-powered search and research
-
-    | Operation | Cost |
-    |-----------|------|
-    | Search | Dynamic (returned by API) |
-    | Get Contents | Dynamic (returned by API) |
-    | Find Similar Links | Dynamic (returned by API) |
-    | Answer | Dynamic (returned by API) |
-  </Tab>
+### Key scope and precedence
 
-  <Tab>
-    **Serper** - Google search API
+| Scope | Applies to | Who manages it | Cloud availability |
+| --- | --- | --- | --- |
+| **Workspace** | One workspace | Workspace Admin | Any plan |
+| **Organization** | Current and future workspaces in the organization | Organization Owner or Admin | Active Pro for Teams, Max for Teams, or Enterprise |
 
-    | Operation | Cost |
-    |-----------|------|
-    | Search (≤10 results) | $0.001 |
-    | Search (>10 results) | $0.002 |
-  </Tab>
+Saved-key precedence is resolved separately for each provider:
 
-  <Tab>
-    **Perplexity** - AI-powered chat and web search
+1. Use that provider's workspace key pool when one is configured.
+2. Otherwise, use its eligible organization key pool.
+3. Otherwise, use the next available configured source, including a Sim-hosted key where supported.
 
-    | Operation | Cost |
-    |-----------|------|
-    | Search | $0.005 per request |
-    | Chat | Token-based (varies by model) |
-  </Tab>
+A workspace OpenAI key does not override the organization's Anthropic key. The settings page marks inherited providers so you can inspect inheritance before adding an override. A nonempty workspace pool is exclusive; a corrupt workspace key is not a reason to borrow an organization key.
 
-  <Tab>
-    **Linkup** - Web search and content retrieval
+### Add or remove keys
 
-    | Operation | Cost |
-    |-----------|------|
-    | Standard search | ~$0.006 |
-    | Deep search | ~$0.055 |
-  </Tab>
+1. Open **Settings → BYOK**.
+2. Choose **Workspace**, or **Organization** if you are an organization administrator.
+3. Select **Add Key** for the provider, enter the key, and save.
 
-  <Tab>
-    **Parallel AI** - Web search, extraction, and deep research
-
-    | Operation | Cost |
-    |-----------|------|
-    | Search (≤10 results) | $0.005 |
-    | Search (>10 results) | $0.005 + $0.001 per additional result |
-    | Extract | $0.001 per URL |
-    | Deep Research | $0.005–$2.40 (varies by processor tier) |
-  </Tab>
+You can store several keys for a provider in each scope. Requests rotate across the keys in the selected pool. Keys are encrypted at rest; the browser receives a masked display value, not the full saved key.
 
-  <Tab>
-    **Jina AI** - Web reading and search
+Deleting the last workspace key lets that provider inherit an eligible organization key or use its next available configured source. Deleting an organization key affects workspaces that inherited it. Key deletion takes effect on subsequent resolution.
 
-    | Operation | Cost |
-    |-----------|------|
-    | Read URL | $0.20 per 1M tokens |
-    | Search | $0.20 per 1M tokens (minimum 10K tokens) |
-  </Tab>
+If the organization's plan lapses, its keys stop applying and workspaces use their next available source. Saved organization keys remain, and organization administrators can delete them; adding or updating them requires an active organization plan.
 
-  <Tab>
-    **Google Cloud** - Translate, Maps, PageSpeed, and Books APIs
-
-    | Operation | Cost |
-    |-----------|------|
-    | Translate / Detect | $0.00002 per character |
-    | Maps (Geocode, Directions, Distance Matrix, Elevation, Timezone, Reverse Geocode, Geolocate, Validate Address) | $0.005 per request |
-    | Maps (Snap to Roads) | $0.01 per request |
-    | Maps (Place Details) | $0.017 per request |
-    | Maps (Places Search) | $0.032 per request |
-    | PageSpeed | Free |
-    | Books (Search, Details) | Free |
-  </Tab>
-
-  <Tab>
-    **Brandfetch** - Brand assets, logos, colors, and company info
-
-    | Operation | Cost |
-    |-----------|------|
-    | Search | Free |
-    | Get Brand | $0.04 per request |
-  </Tab>
-</Tabs>
-
-## Bring Your Own Key (BYOK)
-
-Use your own API keys for supported providers instead of Sim's hosted keys to pay base prices with no markup.
+<Callout type="warn">
+The Pi block's **Create PR**, **Update PR**, and **Plan** modes run a model client inside a sandbox. The resolved key, including an inherited organization key, is exposed to that sandbox. To keep an organization key out, configure a workspace key for that provider. Pi web search requires an explicit block key and does not fall back to stored keys. See [Pi](/workflows/blocks/pi).
+</Callout>
 
-### Supported Providers
+### Provider catalog
 
-The BYOK settings page groups providers the same way.
+The settings page groups keys into **Models**, **Search & web**, and **Enrichment**. It is the current catalog; the following lists describe the supported uses.
 
 <Tabs items={['Models', 'Search & web', 'Enrichment']}>
   <Tab>
-    | Provider | Usage |
-    |----------|-------|
-    | OpenAI | LLM calls and Knowledge Base embeddings |
-    | Anthropic | LLM calls |
-    | Google | LLM calls |
-    | Mistral | LLM calls and Knowledge Base OCR |
-    | Z.ai | LLM calls |
+    | Provider | Use |
+    | --- | --- |
+    | OpenAI | Model calls and Knowledge Base embeddings |
+    | Anthropic | Model calls |
+    | Google | Model calls |
+    | Mistral | Model calls and Knowledge Base OCR |
+    | Z.ai | Model calls |
     | Cohere | Embeddings and Knowledge Base reranking |
-    | xAI | LLM calls |
-    | Kimi | LLM calls |
-    | Fireworks | LLM calls |
-    | Together AI | LLM calls |
-    | Baseten | LLM calls |
-    | Ollama Cloud | LLM calls |
+    | xAI | Model calls |
+    | Kimi | Model calls |
+    | TypeSafe | Jev evaluation models |
+    | Fireworks | Model calls |
+    | Together AI | Model calls |
+    | Baseten | Model calls |
+    | Nebius | Model calls |
+    | Ollama Cloud | Model calls |
+    | Kie | Model calls |
     | Fal.ai | Image and video generation |
   </Tab>
   <Tab>
-    | Provider | Usage |
-    |----------|-------|
-    | Firecrawl | Web scraping, crawling, search, and extraction |
-    | Exa | AI-powered search and research |
-    | Context.dev | Web scraping, crawling, search, and brand intelligence |
+    | Provider | Use |
+    | --- | --- |
+    | Firecrawl | Scraping, crawling, search, and extraction |
+    | Exa | Search and research |
+    | Context.dev | Scraping, crawling, search, and brand intelligence |
+    | TinyFish | Web agent automation, search, and page fetching |
     | Serper | Google search API |
-    | Linkup | Web search and content retrieval |
-    | Parallel AI | Web search, extraction, and deep research |
-    | Perplexity | AI-powered chat and web search |
+    | Linkup | Search and content retrieval |
+    | Parallel AI | Search, extraction, and deep research |
+    | Perplexity | Chat and web search |
     | Jina AI | Web reading and search |
     | Google Cloud | Translate, Maps, PageSpeed, and Books APIs |
   </Tab>
   <Tab>
-    | Provider | Usage |
-    |----------|-------|
-    | Brandfetch | Brand assets, logos, colors, and company info |
-    | Hunter | Email finder, verification, and domain search |
+    | Provider | Use |
+    | --- | --- |
+    | Brandfetch | Brand assets and company information |
+    | Hunter | Email finding, verification, and domain search |
     | People Data Labs | Person and company enrichment, search, and identity |
-    | Findymail | Email finder, verification, and phone lookup |
+    | Findymail | Email finding, verification, and phone lookup |
     | Prospeo | Person and company enrichment and search |
     | Wiza | Prospect search, individual reveal, and company enrichment |
     | Datagma | Email, phone, person, and company enrichment |
     | Dropcontact | Contact enrichment and email finding |
-    | LeadMagic | Email finding, validation, and B2B profile enrichment |
+    | LeadMagic | Email finding, validation, and profile enrichment |
     | Icypeas | Email finding and verification |
     | Enrow | Email finding and verification |
-    | ZeroBounce | Real-time email validation and deliverability checks |
-    | NeverBounce | Real-time email verification and list cleaning |
-    | MillionVerifier | Real-time email verification and deliverability checks |
+    | ZeroBounce | Email validation and deliverability checks |
+    | NeverBounce | Email verification and list cleaning |
+    | MillionVerifier | Email verification and deliverability checks |
   </Tab>
 </Tabs>
 
-### Key scopes
-
-A key is stored at one of two scopes.
-
-| Scope | Applies to | Who can manage | Plan |
-|-------|------------|----------------|------|
-| **Workspace** | That workspace only | Workspace **admin** | Any plan on Sim Cloud |
-| **Organization** | Every current and future workspace in the organization | Organization **admin** or **owner** | Any organization plan on Sim Cloud — Pro for Teams, Max for Teams, or Enterprise |
-
-Organization keys let you set a provider key once instead of repeating it in every workspace. A new workspace added to the organization picks them up automatically.
+## Cloud plans and credit allowances
 
-### Which key a run uses
+Current monthly pricing and allocations are:
 
-Precedence is resolved **per provider**, not per workspace:
+| Plan | Monthly price | Included credits | Weekly refresh |
+| --- | --- | --- | --- |
+| Free | $0 | 1,000 one-time | None |
+| Pro | $25 per seat | 6,000/month per seat | 2,000/week per seat |
+| Max | $100 per seat | 25,000/month per seat | 4,000/week per seat |
+| Enterprise | By agreement | By agreement | By agreement |
 
-1. The workspace's own key for that provider, if it has one
-2. Otherwise, the organization's key for that provider
-3. Otherwise, Sim's hosted key, with the multiplier applied
+Pro and Max are available for individuals or teams. Team subscriptions pool credits across internal seats. For example, Max for Teams with three seats has a 75,000-credit monthly allocation and a 12,000-credit weekly refresh allowance. External collaborators do not add seats, but their work in an organization-owned workspace is billed to that organization.
 
-So a workspace that stores its own OpenAI key still inherits the organization's Anthropic key. A workspace key always wins over the organization key for the same provider — adding one is how you override inheritance for a single workspace.
+See [current pricing](https://www.sim.ai/pricing) and **Settings → Subscription** for the plan available to your account. Internal membership, external eligibility, and workspace migration are explained in [Roles and permissions](/platform/permissions#internal-and-external-membership).
 
-The BYOK settings page tags every provider your workspace is inheriting, so you can see which keys come from the organization before you override them.
+### Weekly refresh
 
-### Setup
+Each seven-day window from the billing period's start excludes usage up to the weekly refresh allowance from billable usage. It is an allowance against that week's usage, not an accumulating wallet balance. Unused allowance does not carry forward. Team allowances scale with seats.
 
-1. Navigate to **Settings** → **BYOK** in your workspace
-2. Choose **Workspace** or **Organization** (organization admins only)
-3. Click **Add Key** for your provider
-4. Enter your API key and save
+### Annual billing
 
-You can store several keys per provider per scope. Requests are distributed evenly across the keys in whichever scope is in effect.
+Pro and Max annual subscriptions have a 15% discount while retaining their advertised included credits. Team pricing uses the same per-seat rate.
 
-<Callout type="info">
-  BYOK keys are encrypted at rest and are never returned to the browser in full — the settings page only ever shows a masked value.
-</Callout>
+| Plan | Monthly billing | Annual equivalent per month | Annual price per seat |
+| --- | --- | --- | --- |
+| Pro | $25 | $21.25 | $255 |
+| Max | $100 | $85 | $1,020 |
 
-<Callout type="warn">
-  The Pi block's **Create PR**, **Update PR**, and **Plan** modes run the model client inside a sandbox, so the resolved key — including an inherited organization key — is exposed to that sandbox. To keep an organization key out of it, give the workspace its own key for that provider. Pi's optional web search never falls back to a stored key; it always requires an explicit key on the block.
-</Callout>
+Use subscription settings to choose the billing interval. The usage display names the current billing period; check it when comparing usage across an interval change.
 
-Deleting a workspace key makes that workspace fall back to the organization key if one exists, and to Sim's hosted keys otherwise. Deleting an organization key makes every workspace that was inheriting it fall back the same way.
+## Control spending
 
-If your organization's plan lapses, organization keys stop applying and those workspaces fall back to Sim's hosted keys with the multiplier. The keys are retained, and organization admins can still delete them, but adding or updating them requires an active organization plan.
+By default, paid usage is capped at the included allowance and any applied credit balance. Under **Settings → Subscription**, either:
 
-## Voice Input
+- Turn on **Allow usage to go past included usage** under **Enable on-demand usage** to remove the normal usage cap.
+- Set a higher **Usage limit** to allow overage up to a specific ceiling.
 
-Voice input uses ElevenLabs Scribe v2 Realtime for speech-to-text transcription. It is available in Chat and in deployed chat voice mode.
+Applied credit balance increases the covered allowance. A balance grant alone does not enable on-demand billing. Disabling on-demand returns the limit to the covered amount; the control is disabled while current usage is already above that amount, until usage falls back or the period resets.
 
-| Context | Cost per session | Max duration |
-|---------|-----------------|--------------|
-| Chat (workspace) | ~5 credits ($0.024) | 3 minutes |
-| Deployed chat (voice mode) | ~2 credits ($0.008) | 1 minute |
+Organization owners and admins manage organization billing and spend limits. Workspace Admin access alone does not grant that authority. Organization **Manage credits** controls a member's usage cap; it is not a credit-purchase control.
 
-Each voice session is billed when it starts. In deployed chat voice mode, each conversation turn (speak → agent responds → speak again) is a separate session. Multi-turn conversations are billed per turn.
+### Subscription and overage example
 
-<Callout type="info">
-  Voice input requires `ELEVENLABS_API_KEY` to be configured. When the key is not set, voice input controls are hidden.
-</Callout>
+If a Pro account has 7,000 billable credits after weekly-refresh deductions and applied credits, its charge is $25 for the subscription plus $5 for the 1,000-credit overage. Continuing beyond the allowance requires on-demand usage or a higher limit.
 
-## Plans
+For team plans, overage is calculated against the organization's pooled allowance. Usage in organization-owned workspaces is billed to that organization, including external collaborators' work. Attributed human usage can also count toward the person's organization member cap. The organization receives one bill. Enterprise usage and limits follow the agreement rather than ordinary Pro/Max overage billing.
 
-Sim has two paid plan tiers - **Pro** and **Max**. Either can be used individually or with a team. Team plans pool credits across all seats in the organization.
+### Threshold billing
 
-| Plan | Price | Credits Included | Weekly Refresh |
-|------|-------|------------------|----------------|
-| **Community** | $0 | 1,000 (one-time) | - |
-| **Pro** | $25/mo | 6,000/mo | +2,000/week |
-| **Max** | $100/mo | 25,000/mo | +4,000/week |
-| **Enterprise** | Custom | Custom | - |
+The default incremental billing threshold is $100 of unbilled overage, equivalent to 20,000 credits. Sim automatically settles eligible overage during the billing period instead of waiting for one large period-end bill.
 
-To use Pro or Max with a team, select **Get For Team** in subscription settings and choose the tier and number of seats. Credits are pooled across the organization at the per-seat rate (e.g. Max for Teams with 3 seats = 75,000 credits/mo pooled).
+| Point in period | Total overage | New settlement |
+| --- | --- | --- |
+| Day 10 | $120 | $120 |
+| Day 15 | $180 | None; only $60 remains unbilled |
+| Day 20 | $260 | $140, the unbilled amount since the first settlement |
 
-Internal organization members use seats and contribute to the team's pooled credit allocation. External workspace members do not join your organization or count toward its seat total. They appear in the roster with an External label.
+Any remaining eligible overage is settled at period end. Applied balances and billing eligibility affect the amount charged.
 
-### Weekly Refresh Credits
+## Cloud limits
 
-Paid plans include a weekly credit allowance that does not count toward your plan limit. Each week, usage up to the weekly refresh amount is excluded from billable usage. This allowance resets every 7 days from your billing period start and does not carry over - use it or lose it.
-
-| Plan | Weekly Refresh |
-|------|----------------|
-| **Pro** | 2,000 credits/week ($10.00) |
-| **Max** | 4,000 credits/week ($20.00) |
-
-For team plans, the weekly refresh scales with seats (e.g. Max for Teams with 3 seats = 12,000 credits/week).
-
-### Annual Billing
-
-All paid plans are available with annual billing at a **15% discount**. Switch between monthly and annual billing in Settings → Subscription.
-
-| Plan | Monthly | Annual (per month) | Annual Total |
-|------|---------|-------------------|--------------|
-| **Pro** | $25/mo | $21.25/mo | $255/yr |
-| **Max** | $100/mo | $85/mo | $1,020/yr |
-
-Team plans follow the same pricing per seat.
-
-### On-Demand Billing
-
-By default, your usage is capped at the credits included in your plan. To allow usage beyond your plan's included amount, you can either enable **on-demand billing** or manually edit your usage limit to any value above your plan's minimum.
-
-- **Enable On-Demand**: Removes the usage cap entirely. You pay for any overage at the end of the billing period.
-- **Edit Usage Limit**: Set a specific cap above your plan's included amount to control how much overage you're willing to allow.
-- **Disable On-Demand**: Resets your usage limit back to the plan's included amount (only available if your current usage hasn't already exceeded it).
-
-<Callout type="info">
-  On-demand billing for team plans is managed by organization owners and
-  administrators. Workspace admin permission alone does not grant billing
-  authority.
-</Callout>
-
-## Plan Limits
+These defaults follow the paid tier: Pro and Pro for Teams share Pro limits; Max and Max for Teams share Max limits. Enterprise values may be customized. Request rate, concurrent runs, storage, and run duration are separate limits.
 
 ### Workspaces
 
-| Plan | Personal Workspaces | Shared (Organization) Workspaces |
-|------|---------------------|----------------------------------|
-| **Free** | 1 | — |
-| **Pro** | Up to 3 | — |
-| **Max** | Up to 10 | — |
-| **Team / Enterprise** | — | Unlimited (Owners and Admins) |
-
-Team and Enterprise plans unlock shared workspaces that belong to your organization. Every workspace created under a Team or Enterprise plan is organization-owned: Owners and Admins can create unlimited shared workspaces, while organization Members cannot create workspaces. When someone joins the organization as an internal member, personal workspaces they own move into the organization and their usage is billed to it from then on. Internal members count toward your seat total — Enterprise invites require an available seat at invite time, while Team plans add a seat automatically when the invitee accepts. External workspace members get access to specific workspaces without joining your organization or using one of your seats; they must already be on a paid Sim plan (their own Pro or Max subscription, or another organization that seats them), and invitees who already belong to another organization always join this way. When a Team or Enterprise subscription is cancelled or downgraded, existing shared workspaces remain accessible to current members but new invites are disabled until the organization is upgraded again.
-
-### Rate Limits
-
-| Plan | Sync (req/min) | Async (req/min) |
-|------|----------------|-----------------|
-| **Free** | 50 | 200 |
-| **Pro** | 150 | 1,000 |
-| **Max** | 300 | 2,500 |
-| **Enterprise** | 600 | 5,000 |
-
-Rate limits follow the paid tier: Pro and Pro for Teams share the Pro limits, while Max and Max for Teams share the Max limits.
-
-### Concurrent Executions
+Free accounts have one personal workspace by default and Pro accounts up to three. Organization workspaces are uncapped for eligible organization owners and admins. For Max and other current account limits, check the workspace creation controls and [pricing](https://www.sim.ai/pricing), rather than assuming a personal-workspace cap from another deployment.
 
-| Plan | Concurrent Executions |
-|------|-----------------------|
-| **Free** | 10 |
-| **Pro** | 50 |
-| **Max** | 200 |
-| **Enterprise** | 1,000 by default (customizable) |
+Accepting internal membership moves owned personal workspaces into the organization. See [Joining an organization](/platform/permissions#joining-an-organization) for the ownership and seat consequences.
 
-The concurrency limit applies per billing account. For organization-based plans, the limit is shared by all workspaces, members, and API keys under that organization. Teams plans follow their tier: Pro for Teams uses the Pro limit and Max for Teams uses the Max limit. An admitted async execution holds a slot while queued and running; synchronous executions hold one while running. Workflow-in-workflow blocks execute inside the parent run and do not consume another concurrency slot.
+### Rate limits
 
-### File Storage
+| Plan | Synchronous runs/minute | Asynchronous runs/minute |
+| --- | --- | --- |
+| Free | 50 | 200 |
+| Pro | 150 | 1,000 |
+| Max | 300 | 2,500 |
+| Enterprise default | 600 | 5,000 |
 
-| Plan | Storage |
-|------|---------|
-| **Free** | 5 GB |
-| **Pro** | 50 GB |
-| **Max** | 500 GB |
-| **Enterprise** | 500 GB (customizable) |
+Execution rate buckets can burst above the sustained per-minute rate. General API endpoint requests have a separate request bucket; these run rates do not describe every API call. See [API usage and limits](/api-reference/getting-started).
 
-Storage follows the paid tier: Pro and Pro for Teams share the Pro limit, while Max and Max for Teams share the Max limit. Organization storage is pooled across the organization's workspaces.
+### Concurrent executions
 
-### Run Time Limits
+| Plan | Concurrent runs |
+| --- | --- |
+| Free | 10 |
+| Pro | 50 |
+| Max | 200 |
+| Enterprise default | 1,000; customizable |
 
-| Plan | Sync | Async |
-|------|------|-------|
-| **Free** | 5 minutes | 90 minutes |
-| **Pro / Max / Team** | 50 minutes | 90 minutes |
-| **Enterprise** | 50 minutes | 90 minutes by default; configurable up to 7 days |
+The limit applies per billing account. An organization's workspaces, members, and API keys share its concurrency pool. An admitted async run holds a slot while queued and running; a synchronous run holds one while running. Workflow-in-workflow blocks execute within the parent run and do not consume another slot.
 
-**Sync runs** complete immediately and return results directly. These are triggered via the API with `async: false` (default) or through the UI.
-**Async runs** (triggered via API with `async: true`, webhooks, schedules, polling triggers, or table workflow columns) run in the background. A direct async API request can shorten the account policy for that request, but cannot extend it.
+### File storage
 
-<Callout type="info">
-  If a workflow exceeds its time limit, it will be terminated and marked as failed with a timeout error. Design long-running workflows to use async runs or break them into smaller workflows.
-</Callout>
-
-## Billing Model
-
-Sim uses a **base subscription + overage** billing model:
+| Plan | Storage default |
+| --- | --- |
+| Free | 5 GiB |
+| Pro | 50 GiB |
+| Max | 500 GiB |
+| Enterprise | 500 GiB; customizable |
 
-### How It Works
+Organization storage is pooled across its workspaces. Storage limits are independent of the credit allowance.
 
-**Pro Plan ($25/month - 6,000 credits):**
-- Monthly subscription includes 6,000 credits of usage
-- Usage under 6,000 credits → No additional charges
-- Usage over 6,000 credits (with on-demand enabled) → Pay the overage at month end
-- Example: 7,000 credits used = $25 (subscription) + $5 (overage for 1,000 extra credits at $0.005/credit)
+### Run time limits
 
-**Team Plans:**
-- Usage is pooled across internal team members in the organization
-- Usage in an organization-owned workspace is billed to that workspace's organization, including work performed by external collaborators
-- Each authenticated actor's usage is also counted toward their member cap for that organization
-- Overage is calculated from total team usage against the pooled limit
-- Organization owner receives one bill
+| Plan | Synchronous run | Asynchronous run |
+| --- | --- | --- |
+| Free | 5 minutes | 90 minutes |
+| Pro / Max, including team subscriptions | 50 minutes | 90 minutes |
+| Enterprise default | 50 minutes | 90 minutes; configurable up to 7 days |
 
-**Enterprise Plans:**
-- Fixed monthly price, no overages
-- Custom usage limits per agreement
+Synchronous execution waits for the workflow to finish and returns its result, or streams it when streaming is selected. Asynchronous API calls, webhooks, schedules, polling triggers, and table workflow columns run in the background.
 
-### Threshold Billing
+A direct async API request can shorten the account's timeout for that request; it cannot extend it. A run exceeding its limit fails with a timeout error. Individual blocks, remote sandboxes, and providers can have shorter independent limits. See [How workflows run](/workflows/how-it-runs).
 
-When on-demand is enabled and unbilled overage reaches $100, Sim automatically bills the full unbilled amount.
+### Self-hosted limits
 
-**Example:**
-- Day 10: $120 overage → Bill $120 immediately
-- Day 15: Additional $60 usage ($180 total) → Already billed, no action
-- Day 20: Another $80 usage ($260 total, $140 unbilled) → Bill $140 immediately
+Billing-disabled deployments have no default plan-based workspace cap, workflow timeout, or storage enforcement. Operators can opt into rate, storage, and workflow timeout enforcement with the corresponding free-tier environment settings. The hosted billing-account concurrency reservation applies only when hosting and billing are enabled.
 
-This spreads large overage charges throughout the month instead of one large bill at period end.
+This does not remove protocol, provider, block, sandbox, or deployment resource limits. See [Self-hosting configuration](/platform/self-hosting/environment-variables) for exact settings.
 
-## Usage Monitoring
+## Monitor usage through the UI or API
 
-Monitor your usage and billing in Settings → Subscription:
+Use **Settings → Subscription** to inspect the current allowance, usage limit, billing period, on-demand setting, and plan. Organization administrators can inspect [Usage monitoring](/platform/enterprise/usage-tracking) for source, workspace, and member attribution.
 
-- **Current Usage**: Real-time credit usage for the current billing period
-- **Usage Limits**: Plan limits with a visual progress bar
-- **On-Demand Billing**: Toggle on-demand billing to allow usage beyond your plan's included credits
-- **Plan Management**: Upgrade, downgrade, or switch between monthly and annual billing
+For workspace billing information, use [Get billing status](/api-reference/billing/getBillingStatus). [List billing logs](/api-reference/billing/listBillingLogs) exposes billable events. Billing and run-resource responses use credits, while Logs endpoints explicitly report USD; use each endpoint's documented unit.
 
-### Programmatic Usage Tracking
+The legacy `GET /api/users/me/usage-limits` endpoint accepts an API key in `X-API-Key`. It reports the authenticated account or key owner's usage and subscription, which can differ from a workflow's workspace payer. Its `usage.currentPeriodCost` and `usage.limit` are in USD. It also returns storage `usedBytes`, `limitBytes`, and `percentUsed`.
 
-You can query your current usage and limits programmatically using the API:
-
-**Endpoint:**
-```text
-GET /api/users/me/usage-limits
-```
-
-**Authentication:**
-- Include your API key in the `X-API-Key` header
-
-**Example Request:**
-```bash
-curl -X GET -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" https://www.sim.ai/api/users/me/usage-limits
-```
+Its rate fields are:
 
-**Example Response:**
-```json
-{
-  "success": true,
-  "rateLimit": {
-    "sync": {
-      "isLimited": false,
-      "requestsPerMinute": 150,
-      "maxBurst": 300,
-      "remaining": 300,
-      "resetAt": "2025-09-08T22:51:55.999Z"
-    },
-    "async": {
-      "isLimited": false,
-      "requestsPerMinute": 1000,
-      "maxBurst": 2000,
-      "remaining": 2000,
-      "resetAt": "2025-09-08T22:51:56.155Z"
-    },
-    "authType": "api"
-  },
-  "usage": {
-    "currentPeriodCost": 12.34,
-    "limit": 100,
-    "plan": "pro_6000"
-  }
-}
-```
-
-**Rate Limit Fields:**
-- `requestsPerMinute`: Sustained rate limit (tokens refill at this rate)
-- `maxBurst`: Maximum tokens you can accumulate (burst capacity)
-- `remaining`: Current tokens available (can be up to `maxBurst`)
-
-**Response Fields:**
-- `currentPeriodCost` reflects usage in the current billing period (in dollars)
-- `limit` is derived from individual limits (Free/Pro/Max) or pooled organization limits (Team/Enterprise)
-- `plan` is the highest-priority active plan associated with your user
-
-## Purchasing Additional Credits
-
-Pro and Team plan users can buy additional credits at any time in **Settings → Subscription → Credit Balance**:
-
-- **Range**: $10 to $1,000 per purchase
-- **Conversion**: 1 credit = $0.005 (a $10 purchase adds 2,000 credits)
-- **Availability**: Credits are added immediately after payment
-- **Expiration**: Purchased credits do not expire
-- **Refunds**: Purchases are non-refundable
-- **Team plans**: Only organization owners and admins can purchase credits. Purchased credits are added to the team's shared pool.
-
-<Callout type="info">
-  Enterprise users should contact support for credit adjustments.
-</Callout>
+| Field | Meaning |
+| --- | --- |
+| `requestsPerMinute` | Sustained token refill rate |
+| `maxBurst` | Maximum accumulated tokens |
+| `remaining` | Available tokens, up to `maxBurst` |
+| `resetAt` | Reported bucket reset time |
 
-## Cost Optimization Strategies
+See [API authentication](/api-reference/authentication) before selecting a personal or workspace key for monitoring.
 
-- **Model Selection**: Choose models based on task complexity. Simple tasks can use GPT-4.1-nano while complex reasoning might need o1 or Claude Opus.
-- **Prompt Engineering**: Well-structured, concise prompts reduce token usage without sacrificing quality.
-- **Local Models**: Use Ollama or VLLM for non-critical tasks to eliminate API costs entirely.
-- **Caching and Reuse**: Store frequently used results in variables or files to avoid repeated AI model calls.
-- **Batch Processing**: Process multiple items in a single AI request rather than making individual calls.
+## Voice dictation usage
 
-## Next Steps
+Chat dictation uses ElevenLabs Scribe v2 Realtime. A workspace or organization dictation session has a three-minute maximum and records its charge when the token is issued, even if you stop speaking earlier. Its configured base cost is $0.024 per session, before the deployment's applicable cost policy.
 
-- Review your current usage in [Settings → Subscription](https://www.sim.ai/settings/subscription)
-- Learn about [Logging](/logs-debugging/logging) to track run details
-- Explore the [External API](/api-reference/getting-started) for programmatic cost monitoring
-- Check out [workflow optimization techniques](/workflows#blocks) to reduce costs
+The deployment must configure `ELEVENLABS_API_KEY`; dictation controls are hidden when the service is unavailable. Deployed-chat voice mode is a separate surface; see [Chat deployments](/workflows/deployment/chat) for its setup rather than applying the dictation session limit to it.
 
-import { FAQ } from '@/components/ui/faq'
+## Related docs
 
-<FAQ items={[
-  { question: "How much does a single workflow run cost?", answer: "Every run incurs a base charge of 1 credit ($0.005), plus billable model usage and hosted tool usage. Runs without either metered component pay only the base charge." },
-  { question: "What is the credit-to-dollar conversion rate?", answer: "1 credit equals $0.005. All plan limits, usage meters, and billing thresholds in the Sim UI are displayed in credits." },
-  { question: "Do unused weekly refresh credits carry over?", answer: "No. Weekly refresh credits reset every 7 days and do not accumulate. If you do not use them within the week, they are lost." },
-  { question: "What happens when I exceed my plan's credit limit?", answer: "By default, your usage is capped at your plan's included credits and runs will stop. If you enable on-demand billing or manually raise your usage limit in Settings, you can continue running workflows and pay for the overage at the end of the billing period." },
-  { question: "How does the 1.1x hosted model multiplier work?", answer: "When you use Sim's hosted API keys (instead of bringing your own), a 1.1x multiplier is applied to the base model pricing for Agent blocks. This covers infrastructure and API management costs. You can avoid this multiplier by using your own API keys via the BYOK feature." },
-  { question: "Are there any free options for AI models?", answer: "Yes. If you run local models through Ollama or VLLM, there are no API costs for those model calls. You still pay the base run charge of 1 credit per run." },
-  { question: "When does threshold billing trigger?", answer: "When on-demand billing is enabled and your unbilled overage reaches $100, Sim automatically bills the full unbilled amount. This spreads large charges throughout the month instead of accumulating one large bill at period end." },
-]} />
+- [Secrets](/platform/credentials)
+- [Logs](/logs-debugging/logging)
+- [API getting started](/api-reference/getting-started)
diff --git a/apps/docs/content/docs/platform/credentials.mdx b/apps/docs/content/docs/platform/credentials.mdx
index 742fbe1f48d..30c1218e444 100644
--- a/apps/docs/content/docs/platform/credentials.mdx
+++ b/apps/docs/content/docs/platform/credentials.mdx
@@ -1,206 +1,176 @@
 ---
 title: Secrets
-description: Manage API keys and environment variables for your workflows
+description: Save sensitive values, control access, and understand runtime resolution and protection.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Image } from '@/components/ui/image'
-import { FAQ } from '@/components/ui/faq'
 
-Secrets are key-value pairs that store sensitive data like API keys, tokens, and passwords. Instead of hardcoding values into your workflows, you store them as secrets and reference them by name at runtime.
+Secrets store API keys, tokens, passwords, and other values by name. Reference a saved value with `{{KEY}}` instead of placing a literal secret in a workflow field. Saved secret values are encrypted before storage.
 
-## Managing Secrets
+## Scope and access
 
-To manage secrets, open your workspace **Settings** and navigate to the **Secrets** tab.
+Open **Settings → Secrets** in your workspace. The editor has **Workspace** and **Personal** sections.
 
-<Image
-  src="/static/secrets/secrets-list.png"
-  alt="Secrets tab showing Workspace and Personal sections with inline key-value rows"
-  width={700}
-  height={479}
-  className="mx-auto h-auto w-full max-w-xl"
-/>
-
-Secrets are organized into two sections:
-
-- **Workspace** — shared with all members of your workspace
-- **Personal** — private to you
-
-External workspace members count as workspace members for workspace-scoped secrets. They can use workspace secrets according to their workspace permission level, even though they are not members of your organization.
-
-### Adding a Secret
-
-Type a key name (e.g. `OPENAI_API_KEY`) into the **Key** column and its value into the **Value** column in the last empty row. A new empty row appears automatically as you type. Existing values are masked by default.
+| Scope | Storage and management | Runtime access |
+| --- | --- | --- |
+| **Workspace** | Stored for this workspace; workspace Admins and that secret's Credential Admins can manage and reveal it | Workspace Admins and members with an active Credential Member or Admin grant can use it |
+| **Personal** | Stored once for its owner across their workspaces; the editor manages your own values | Resolves under the authorized personal identity and current credential grants |
 
-When you're done, click **Save** to persist all changes.
+Workspace members, including external collaborators, can see workspace secret names. Seeing a name or having Write workspace access does not automatically grant use or reveal access. Creating a workspace secret requires **Write** or **Admin**. Managing an existing one requires Admin authority on the secret or workspace.
 
-<Callout type="info">
-Keys must use only letters, numbers, and underscores — no spaces or special characters.
-</Callout>
+Personal secrets belong to their owner. Workspace and organization Admin roles do not grant access to them. Existing explicit personal credential grants can participate in runtime resolution, but the current Secrets editor and membership API do not create new personal-secret shares.
 
-### Bulk Import
+Credential Members can reveal a workspace secret only when its Admin enables [Show value in logs and Chat](#visibility). See [Roles and permissions](/platform/permissions#credential-access) for credential grants.
 
-You can populate multiple secrets at once by pasting `.env`-style content into any key or value field. The parser supports standard `KEY=VALUE` pairs, `export KEY=VALUE`, quoted values, and inline comments.
+## Add, import, edit, or delete a secret
 
-### Editing and Deleting
+<Image
+  src="/static/secrets/secrets-list.png"
+  alt="Secrets editor with Workspace and Personal rows, masked values, Details, and Save"
+  width={700}
+  height={479}
+/>
 
-Click directly into any key or value cell to edit it. To delete a secret, click the trash icon on its row and save.
+1. In the last empty row of the appropriate section, enter a **Key** such as `OPENAI_API_KEY` and its **Value**.
+2. Use only letters, numbers, and underscores in the key. A new empty row appears as you type; saved values are masked by default.
+3. Select **Save** to persist the changes.
 
-## Using Secrets in Workflows
+To import several values, paste `.env` content into a key or value field. The parser supports `KEY=VALUE`, `export KEY=VALUE`, quoted values, and inline comments.
 
-To reference a secret in any input field, type `{{` to open the variable dropdown. Your available secrets are listed grouped by scope (workspace, then personal).
+Edit cells directly. To delete a secret, select its row's trash icon and save. Update workflow references before deleting it: blocks that require the deleted value cannot resolve it.
 
-<Image
-  src="/static/credentials/secret-dropdown.png"
-  alt="Typing {{ in an input opens a dropdown showing available secrets"
-  width={400}
-  height={165}
-  className="mx-auto h-auto w-full max-w-[400px]"
-/>
+## Use a secret
 
-Select the secret you want to use. The reference appears highlighted in blue and is resolved to its actual value at runtime.
+Type `{{` in an input to open the variable picker. Available secrets are grouped by scope. Selecting one inserts a reference such as `{{OPENAI_API_KEY}}`; Sim resolves it to the real authorized value at runtime.
 
 <Image
   src="/static/credentials/secret-resolved.png"
-  alt="A resolved secret reference shown as {{OPENAI_API_KEY}}"
+  alt="An input containing {{ with the Workspace secret picker open"
   width={400}
   height={166}
-  className="mx-auto h-auto w-full max-w-[400px]"
 />
 
-### Execution log protection
+Among secrets the execution actor may use, the **workspace value takes precedence** over a personal value with the same name. An inaccessible workspace secret does not shadow an authorized personal value.
 
-When a saved secret is successfully substituted through a `{{KEY}}` reference, Sim masks exact, case-sensitive occurrences of its resolved value in log-facing content. This includes the editor's live block-log display, Logs Overview input and output, stored execution traces, log-read API responses, and the Logs block's **Get Run Details** output. Function and Agent span inputs, outputs, and errors, Agent thinking, and Agent tool-call arguments, results, and errors are protected. The replacement is normally shown as `{{KEY}}`.
+### Resolution identity
 
-Secret resolution and functional workflow behavior are unchanged: blocks, tools, and downstream steps receive the real runtime value. Stored functional execution data, workflow execution responses, streams, callbacks, block state, and snapshots are not rewritten. Log-facing views and read APIs receive a separate protected copy, so the Logs Overview **Workflow Input** and **Workflow Output** are masked without changing the underlying workflow result. Model requests receive another protected projection: exact secret values known to the run are replaced with `{{KEY}}` before model-visible messages, prompts, tool arguments, or tool continuations leave Sim.
+Workspace secrets authorize against the execution actor: an identifiable caller, or the workspace's configured billing account for background execution. The run sees only the workspace secrets that identity may use.
 
-Code that reads a secret straight off the runtime environment — `environmentVariables['KEY']`, `environmentVariables.KEY`, or `const { KEY } = environmentVariables` in JavaScript, `environmentVariables['KEY']` or `environmentVariables.get('KEY')` in Python, `$KEY` or `${KEY}` in shell — also activates masking, provided Sim can see the read in the code before it runs. A hardcoded literal never does: Sim has no way to know it came from a secret.
+The personal namespace depends on the trigger:
 
-<Callout type="warn">
-Direct reads are found by reading the code, not by running it, so recognition stops where the code stops being readable ahead of time. An unrecognized read is not masked, and does not appear under **See usage**.
+| Run started by | Personal namespace |
+| --- | --- |
+| Clicking **Run** or using a personal API key | The person running it |
+| A workspace API key, schedule, webhook, or deployed chat | The workflow owner |
+| An unauthenticated public API URL | None |
 
-Where a read is recognized, Sim reports it rather than trying to prove it is not one. Code that shadows the environment binding with its own object, overwrites a variable before reading it, or assigns to the name instead of reading it is still reported. Naming a secret costs only an exact value the code never emits; failing to name one leaves it unmasked. **See usage** can therefore occasionally list a secret the code had available but did not read.
+The workflow-owner fallback supports background workflows authored against that owner's keys; it is not a grant to borrow any person's secrets. An owner who has left the workspace or is suspended cannot supply that personal namespace. A stale workspace execution identity can also lose its secret access.
 
-Assigning to the injected binding does not change the stored secret — it is an ordinary object built from the run's payload and discarded when the run ends. Edit a secret under **Settings → Secrets**.
+Use workspace secrets with appropriate grants for production and public deployments. If an owner leaves, blocks requiring their personal values may fail even though workspace-backed blocks can continue. A public API caller receives no personal namespace.
 
-A read is **not** recognized when:
+## Secret details
 
-- **The name is built at runtime.** `environmentVariables[keyName]`, `$@`, `${!indirect}`, `eval`, `printenv`, or a sourced file hide which secret is being read.
-- **The read is of a different object.** `other.environmentVariables['KEY']` reads something that merely shares the name.
-- **The read cannot be told apart from text.** A `$KEY` inside single quotes or a quoted heredoc (`<<'EOF'`) never expands, and Sim treats anything its scanner cannot place as not running.
+Select **Details** on a row to open its detail page. You can inspect the key and, when authorized, reveal or edit the value. Return to **Secrets** or save changes from the detail page.
 
-Both masking and model-bound projection match only exact values in either case. Encoded, hashed, fragmented, or otherwise transformed versions are not matched, and a value assembled or emitted piece by piece cannot be matched at all — determining whether arbitrary code will eventually reveal a value is not decidable in general. Treat these as a safety net, not a boundary: do not deliberately return, print, or transmit secrets.
-</Callout>
+Workspace secrets also have:
 
-### Copilot code execution
+- **Description** for an optional purpose or rotation note.
+- **Members** and **Share** to grant teammates Credential **Member** or **Admin** access.
+- **Visibility** to control **Show value in logs and Chat**.
 
-Copilot's Function and code-execution tools receive a saved secret only when their code explicitly contains a valid `{{KEY}}` reference. Direct `environmentVariables.KEY` access, shell `$KEY`, dynamic names, literals, and configured-but-unused secrets do not mount a value. Code execution requires workspace write access, and the caller must be allowed to **use** the secret — the same set a workflow resolves for them: your own Personal secrets, and Workspace secrets you hold an active grant on as a Credential Member or Credential Admin, which a workspace admin holds on every key. A secret you hold no grant on does not mount, and neither does one whose grant is revoked or still pending.
+Description, member-sharing, and visibility controls do not apply to personal secrets.
 
-This matches what a workflow Function block already resolves for the same person, deliberately. Being able to run a secret is not normally the same as being able to read it: Credential Members can reveal a workspace secret under **Settings → Secrets** only when a Credential Admin has enabled **Show value in logs and Chat**. **See usage** remains visible only to that secret's admins, so a Credential Member using a secret in code is recorded for whoever can rotate it.
+### Visibility
 
-Headless surfaces use their saved **Secret access** setting:
+By default, Sim protects recognized secret values in log-facing and model-bound content. **Show value in logs and Chat** opts one workspace secret out of that protection. With it enabled:
 
-- **Sim Chat block** — under **Show additional fields**
-- **Scheduled Tasks** — in the task modal
-- **Inbox** — under **Settings → Inbox → Secrets**
+- Run logs, Chat, and code output can show its real value instead of `{{KEY}}`.
+- Files written with the value can remain readable and attachable.
+- The Secrets API list can include its value when the caller has the required access.
+- Credential Members can reveal it under **Settings → Secrets**, without gaining edit permission.
 
-Choose **All secrets** or **Selected secrets**. Existing configurations default to **All secrets** for compatibility. **All secrets** still means only secrets explicitly referenced with `{{KEY}}` that the execution actor may use; it never injects the full environment. Inbox messages from allowed external senders do not receive raw-secret access at all — an inbound message that Sim cannot match to a workspace member runs with no secret actor, so no `{{KEY}}` resolves for it.
+<Callout type="warn">
+The value can become visible to anyone who can see the workspace's runs, including public shared-log links and exports, regardless of the secret's member restrictions. Enable this only for values safe to print, such as a non-sensitive base URL.
+</Callout>
 
-Code receives the real authorized value at runtime. Before any Copilot-visible tool result is returned, exact occurrences of activated secret values are replaced with `{{KEY}}`; local side effects and runtime results are not rewritten. Encoded, hashed, URL-encoded, otherwise transformed, or network-exfiltrated values cannot be inferred and masked reliably, so code should not deliberately return, transform, print, or transmit secrets to unintended destinations.
+Only a workspace or Credential Admin can change this workspace-only setting. It affects future runs: already masked logs stay masked, and previously written plaintext remains even after protection is restored. If another protected secret has the same value, protection wins.
 
-## Secret Details
+### See usage
 
-Click **Details** on any secret row to open its detail view.
+Select **See usage** to open its **Logs** and **References** views:
 
-<Image
-  src="/static/secrets/secret-details.png"
-  alt="Secret details view showing Key, Value, Description, and Members sections"
-  width={700}
-  height={351}
-  className="mx-auto h-auto w-full max-w-xl"
-/>
+- **Logs** lists runs that resolved the secret: source workflow, Sim agent or MCP server; trigger; resolution identity; last use; and a link to the most recent run. Rows are grouped by day, so repeated scheduled runs can share one row.
+- **References** shows saved workflow fields, custom tools, and MCP configuration that name the secret. A saved reference can exist before anything has run; it is different from recorded use.
 
-From here you can:
+Only Admins of a workspace secret, or the owner of a personal secret, can inspect its usage. Other members see a disabled action because the trail identifies workflows, people, and run IDs. Two owners with the same personal key name see their own records independently.
 
-- View the **Key** and reveal the **Value** when visibility is enabled; Credential Admins can edit it
-- Toggle **Visibility** — show the value unmasked in run output; see [Visibility](#visibility)
-- Edit the **Description** — an optional note telling teammates what the secret is for. Workspace secrets only; a personal secret is not shared, so it has none
-- Manage **Members** — invite teammates by email and assign them an **Admin** or **Member** role
-- Open **See usage** — where this secret has actually been used
+Usage is recorded separately from execution logs, so log expiry does not delete the usage record. It records recognized resolution, subject to the limits below. An empty trail means no use was recognized; it does not prove the secret was never used. Check both usage and references before rotating or deleting a key.
 
-Click **Save** to apply changes, or **Back** to return to the list.
+## Execution log protection
 
-### Visibility
+After a saved secret is successfully substituted through `{{KEY}}`, Sim masks exact, case-sensitive occurrences of its resolved value in log-facing content, unless it is exempt under **Show value in logs and Chat**. The replacement is normally `{{KEY}}`.
 
-By default, a secret's resolved value is masked everywhere Sim shows run output (see [Execution log protection](#execution-log-protection)). For values that aren't actually sensitive — a non-secret shared base URL — that masking makes your own logs harder to read.
+Protected content includes:
 
-**Show value in logs and Chat** turns masking off for one workspace secret. With it on:
+- The editor's live block logs and Logs **Overview** workflow input and output.
+- Stored execution traces, log-read API responses, and the Logs block's **Get Run Details** output.
+- Function and Agent span inputs, outputs, and errors.
+- Agent thinking and tool-call arguments, results, and errors.
 
-- Run logs, Chat, and code output show the real value instead of `{{KEY}}`
-- Files a run writes with the value in them stay readable and attachable
-- The Secrets API list includes the value for this secret, so external agents can read it directly instead of scraping logs
-- Credential Members can reveal the value under **Settings → Secrets**, without gaining permission to edit it
+Blocks, tools, and downstream steps still receive the real runtime value. Sim protects a separate copy for logs; it does not rewrite stored functional execution data, execution responses, streams, callbacks, block state, or snapshots. A workflow that returns a secret can therefore put it in its functional response even when the corresponding Logs view is masked.
 
-The value becomes visible to **anyone who can see this workspace's runs** — including publicly shared log links and log exports, and regardless of member restrictions on the secret itself. Only turn it on for values you'd be comfortable printing in a log.
+Model requests receive a separate protected projection. Exact recognized secret values are replaced before model-visible messages, prompts, tool arguments, or tool continuations leave Sim. This follows the same visibility exception and exact-value limitations; it does not remove secrets from the runtime operations that need them.
 
-The switch applies to future runs only. Logs written while the secret was masked stay masked, and anything written while it was visible keeps the value even if you turn masking back on. If another secret holds the same value, that value stays masked — masking always wins a conflict. Workspace secrets only; the same people who can edit the description can flip it.
+### Direct environment reads in workflow code
 
-### See usage
+Sim also activates protection when it recognizes a direct secret read in workflow code before execution:
 
-**See usage** lists the runs that resolved this secret: when it was last used, what used it (a workflow, the Sim agent, or an MCP server), how it was triggered, who it resolved under, and a link to the most recent run in Logs. Rows are grouped by day, so a workflow on a schedule reads as one row per day rather than thousands.
+| Language | Recognized forms |
+| --- | --- |
+| JavaScript | `environmentVariables['KEY']`, `environmentVariables.KEY`, `const { KEY } = environmentVariables` |
+| Python | `environmentVariables['KEY']`, `environmentVariables.get('KEY')` |
+| Shell | `$KEY`, `${KEY}` |
 
-This answers the question worth asking before rotating a key: who has been using it, inside what, and how recently.
+The scanner reads code rather than executing it. It can report a named key even if code shadows the environment binding with its own object, overwrites a variable before reading it, or assigns to the name rather than reading it. **See usage** can therefore include a secret that the run had available but did not read.
 
-Only Credential Admins on a workspace secret, or the owner of a personal one, can see its usage. For everyone else the action is visible but disabled because the trail names workflows, people, and run IDs. Two people who each hold a personal secret under the same name see only their own runs.
+Assigning to the injected environment object does not change the stored secret. The object is built for the run and discarded afterward. Edit stored values under **Settings → Secrets**.
 
-<Callout>
-Usage is recorded independently of execution logs, so it outlives them: logs expire under your workspace's retention setting, while the record of who touched a credential does not. It records what a run resolved, subject to the recognition limits under [Execution log protection](#execution-log-protection) — a read Sim cannot attribute is left out rather than guessed at, so treat an empty trail as "nothing recognized," not proof a secret was never used.
-</Callout>
+The scanner does not recognize a secret read when:
+
+- Its name is built at runtime, as in `environmentVariables[keyName]`, `${!indirect}`, or `$@`.
+- `eval`, `printenv`, or a sourced file hides which key is read.
+- The code reads another object, such as `other.environmentVariables['KEY']`.
+- It cannot distinguish executable expansion from text. A shell `$KEY` inside single quotes or a quoted heredoc such as `<<'EOF'` does not expand.
 
-## Workspace vs. Personal
+An unrecognized read does not activate masking or appear under **See usage**. A hardcoded literal by itself does not activate secret protection.
 
-| Feature | Workspace | Personal |
-|---|---|---|
-| **Who sees the name** | All workspace members, including external workspace members | Only you |
-| **Who sees the value** | Workspace admins and that secret's Credential Admins; Credential Members when **Show value in logs and Chat** is enabled | Only you |
-| **Use in workflows and code** | Workspace admins and members with an active Credential Member or Credential Admin grant | Only you can use |
-| **Best for** | Production workflows, shared services | Testing, personal API keys |
-| **Who can edit** | Workspace admins and that secret's Credential Admins | Only you |
+### Protection limits
 
-<Callout type="info">
-Among secrets available to the execution actor, the **workspace secret takes precedence**. An inaccessible workspace secret does not shadow an authorized personal secret.
+<Callout type="warn">
+Masking and model projection match exact values. Encoded, URL-encoded, hashed, transformed, fragmented, or piece-by-piece values are outside that protection. Do not deliberately return, print, or transmit a secret to an unintended destination. Protection is a safety net, not a boundary for arbitrary code.
 </Callout>
 
-### Resolution Order
+## Secrets in Chat code execution
 
-When a workflow runs, secrets resolve in this order:
+Sim's Function and code-execution tools in Chat mount a saved secret only when their code explicitly includes a valid `{{KEY}}` reference. Direct `environmentVariables.KEY` reads, shell `$KEY`, dynamic names, hardcoded literals, and configured-but-unused secrets do not mount values through this path.
 
-1. **Workspace secrets** are checked first, and always resolve against the identity running the workflow — the caller when one can be identified, otherwise the workspace's billing account. A run only sees the workspace secrets that identity is allowed to use.
-2. **Personal secrets** are used as a fallback, from whichever identity is running:
+Code execution requires workspace **Write** access. The execution actor must be allowed to use every requested secret: their personal namespace and active credential grants, or workspace Admin access to workspace secrets. Pending, revoked, or absent grants do not mount a value. This is use authority, separate from the authority to reveal a value in Settings or inspect its usage.
 
-| Run started by | Personal secrets come from |
-| --- | --- |
-| Clicking Run, or a personal API key | The person running it |
-| A workspace API key, schedule, webhook, or deployed chat | The workflow owner |
-| A public API URL with no authentication | Nobody — personal secrets do not resolve |
+Code receives the real authorized value. Before a tool result returns to Sim, exact occurrences of activated protected values are replaced with `{{KEY}}`. Local side effects and functional runtime results are unchanged. Protection does not prevent code from sending a real value over the network; the same transformation and transmission limits apply.
+
+### Headless secret selection
+
+The **Sim Chat** block exposes **Secret access** under **Show additional fields**. Inbox exposes it under **Settings → Inbox → Secrets**. Choose **All secrets** or **Selected secrets**.
 
-The workflow owner is the fallback only where nobody can be identified but somebody in the workspace set the trigger up, since those workflows are usually built against the owner's own keys. A public URL can be called by anyone, so it never borrows a person's keys at all — put every secret such a workflow needs in **Workspace**.
+Existing configurations default to **All secrets** for compatibility. This means explicitly referenced secrets that the execution actor may use; it does not inject the full environment. **Selected secrets** narrows that set. A reference outside the selected set rejects the code request rather than running it with a partial environment.
 
-If the workflow owner later leaves the workspace, the run keeps working: it resolves workspace secrets as normal and simply resolves no personal ones, so any block that needed a personal secret fails on its own with the missing key named. Move that secret to **Workspace** to fix it for good.
+Inbox messages from allowed external senders do not receive raw-secret access. If Sim cannot match the sender to a workspace member, it runs without a secret actor, so `{{KEY}}` cannot resolve through this path. Allowing an email sender is not a credential grant.
 
-## Best Practices
+Recurring work uses deployed workflow [Schedule triggers](/workflows/triggers/schedule). Configure secret access on the blocks that execute it; see [Chat actions and configuration](/chat/tasks) for the current setup flow.
 
-- **Use workspace secrets for production** so workflows work regardless of who triggers them
-- **Use personal secrets for development** to keep test keys separate
-- **Name keys descriptively** — `STRIPE_SECRET_KEY` over `KEY1`
-- **Never hardcode secrets** in workflow input fields — always use `{{KEY}}` references
+## Related docs
 
-<FAQ items={[
-  { question: "Are my secrets encrypted at rest?", answer: "Yes. Values saved under Secrets are encrypted before being stored in the database." },
-  { question: "Can a saved secret still appear in a workflow result?", answer: "Yes. Functional workflow data is not rewritten, so the raw value can still reach downstream blocks and tools and can appear in workflow execution responses, streams, or callbacks if your workflow deliberately returns or prints it. Log-facing views and read APIs receive a protected copy after a successful {{KEY}} resolution. Before content is sent to a model, exact values from the run's authorized secret catalog are replaced with placeholders, but encoded or otherwise transformed values remain outside that protection." },
-  { question: "What happens if both a workspace secret and a personal secret have the same key name?", answer: "Among secrets available to the execution actor, the workspace secret takes precedence and the personal secret is the fallback. An inaccessible workspace secret does not shadow an authorized personal value." },
-  { question: "Who determines which personal secret is used for automated runs?", answer: "Whoever is running it, when that can be identified. Clicking Run or calling with a personal API key uses that person's personal secrets. A workspace API key, schedule, webhook, or deployed chat has no identifiable caller, so it falls back to the workflow owner's — those triggers are set up inside the workspace and the workflow is usually built against the owner's own keys. A public API URL with no authentication can be called by anyone, so no personal secrets resolve at all — those workflows run on workspace secrets only." },
-  { question: "What happens to automated runs if the workflow owner leaves the workspace?", answer: "They keep running. Workspace secrets resolve as normal, because they are checked against the workspace's billing account rather than the owner. Personal secrets stop resolving, so any block that referenced one fails with that key named — move it to Workspace to fix it permanently." },
-  { question: "Can I import secrets from a .env file?", answer: "Yes. Paste .env-style content (KEY=VALUE format) into any key or value field and the secrets will be auto-populated. The parser supports export KEY=VALUE, quoted values, and inline comments." },
-  { question: "What happens if I delete a secret that is used in a workflow?", answer: "The workflow will fail at any block that references the deleted secret during execution because the value cannot be resolved. Update any references before deleting a secret." },
-]} />
+- [Roles and permissions](/platform/permissions)
+- [Workflow variables](/workflows/variables)
+- [Logs](/logs-debugging/logging)
diff --git a/apps/docs/content/docs/platform/enterprise/access-control.mdx b/apps/docs/content/docs/platform/enterprise/access-control.mdx
index d5ccb0d225c..cb77f55df4e 100644
--- a/apps/docs/content/docs/platform/enterprise/access-control.mdx
+++ b/apps/docs/content/docs/platform/enterprise/access-control.mdx
@@ -1,257 +1,140 @@
 ---
-title: Access Control
-description: Restrict which models, blocks, and platform features each group of users can access
+title: Permission groups
+description: Limit models, blocks, tools, and platform actions for people in your organization's workspaces
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { FAQ } from '@/components/ui/faq'
-import { Image } from '@/components/ui/image'
 
-Access Control lets organization admins define permission groups that restrict what each set of users can do — which AI model providers they can use, which workflow blocks they can place, and which platform features are visible to them. Permission groups are scoped to the **organization**. The organization's **default group** governs everyone org-wide; every other group targets a **specific set of workspaces** and, by default, governs **all members of those workspaces** (including external members) — or only specific members once you add them. A user is governed by exactly one group in any given workspace. Restrictions are enforced both in the workflow executor and in Chat, based on the organization that owns the workflow's workspace.
+Permission groups restrict what people can use in an organization's workspaces. Set a provider or block allowlist, deny individual models or tool operations, or limit platform actions such as exports and deployments. Workspace membership and roles still determine which resources a person can access; a group does not grant access.
 
----
-
-## How it works
-
-Each group belongs to a specific organization and has a name, an optional description, a **workspace scope**, an optional **member** list, and a configuration that defines what its members can and cannot do. Personal or grandfathered workspaces that do not belong to an organization have no permission groups.
-
-Sim resolves the governing group for a user in a workspace deterministically:
-
-1. a non-default group targeting that workspace that the user is an **explicit member** of takes precedence; otherwise
-2. a non-default group targeting that workspace that has **no members** (so it governs all members of the workspace, including external members) applies; otherwise
-3. the organization's **default group** applies (if one is set); otherwise
-4. no restrictions apply.
-
-Assignment-time checks keep this unambiguous: a workspace has at most one all-members group, and a user is an explicit member of at most one group per workspace.
-
-When a user runs a workflow or uses Chat, Sim reads the resolved group's configuration and applies it:
-
-- **In the executor:** If a workflow uses a disallowed block type or model provider, execution halts immediately with an error. This applies to both manual runs and scheduled or API-triggered deployments.
-- **In Chat:** Disallowed blocks are filtered out of the block list so they cannot be added to a workflow. Disallowed tool types (MCP, custom tools, skills) are **not** filtered during generation — Sim is told about the restriction but may still produce a step that uses one. Such a run fails at execution with an error naming the restriction.
-
----
-
-## Setup
-
-### 1. Open Permission groups settings
-
-Go to **Settings → Organization → Permission groups** from any workspace in your organization. Permission groups are defined once at the organization level and apply to every workspace under it. Only organization owners and admins can manage them.
-
-<Image src="/static/enterprise/access-control-groups.png" alt="Access Control settings showing a list of permission groups: Contractors, Sales, Engineering, and Marketing, each with Details and Delete actions" width={900} height={477} className="mx-auto h-auto w-full max-w-xl" />
-
-### 2. Create a permission group
-
-Click **+ Create** and enter a name (required) and optional description. A group either targets a **specific set of workspaces** (pick them from the multi-select) or is the **organization default group**. A workspace-scoped group applies to **all members** of its workspaces by default, including external members — you can narrow it to specific people later. Marking the group as the **default** makes it govern every workspace in the organization and every member not covered by another group (including external members); only one group per organization can be the default, and the default always applies to all workspaces.
-
-### 3. Configure permissions
-
-Click **Details** on a group to open its configuration. It has four tabs — **General**, **Model Providers**, **Blocks**, and **Platform**. Name, description, and the permission settings are buffered until you save; the workspace scope, the default-group switch, and member changes are applied immediately, so **Discard** does not undo them.
-
-Throughout the editor, a **checked** box means allowed. Clearing a checkbox is what applies a restriction.
-
-#### General
-
-Holds the group's **Name** and **Description**, the **Default group** switch, the **Workspaces** the group governs, and its **Members**.
-
-A workspace-scoped group with **no members** applies to everyone in its workspaces (including external members). Add members here — searching your organization by name or email — to restrict the group to only those people; removing every member returns it to governing everyone. The default group ignores members and governs every workspace in the organization.
-
-#### Model Providers
-
-Controls which AI model providers members of this group can use.
-
-<Image src="/static/enterprise/access-control-model-providers.png" alt="Model Providers tab showing a grid of AI providers including Ollama, vLLM, OpenAI, Anthropic, Google, Azure OpenAI, and others with checkboxes to allow or restrict access" width={900} height={430} className="mx-auto h-auto w-full max-w-xl" />
-
-The list shows all providers available in Sim.
-
-- **All checked (default):** All providers are allowed.
-- **Subset checked:** Only the selected providers are allowed. Any workflow block or agent using a provider not on the list will fail at execution time.
-
-Expand a provider row to reach its **model denylist**. Clearing individual models blocks exactly those models while leaving the rest of the provider available — useful when a provider is sanctioned but a specific model is not.
+Organization owners and admins manage groups under **Settings → Organization → Permission groups**. Billing-enabled deployments require Enterprise. Billing-disabled deployments use the feature configuration described under [Self-hosted setup](#self-hosted-setup). Workspaces without an organization have no permission groups.
 
-#### Blocks
+## Create and configure a group
 
-Controls which workflow blocks members can place and execute.
+1. Open **Settings → Organization → Permission groups** and click **Create group**.
+2. Enter a name and optional description. Select at least one workspace, or make the group the **Default group** for the organization.
+3. Open the group's row. Configure its **General**, **Model Providers**, **Blocks**, and **Platform** tabs.
+4. Click **Save** to save its name, description, and permission configuration.
 
-<Image src="/static/enterprise/access-control-blocks.png" alt="Blocks tab showing Core Blocks (Agent, API, Condition, Function, Knowledge, etc.) and Tools (integrations like 1Password, Ahrefs, Airtable, and more) with checkboxes to allow or restrict each" width={900} height={634} />
-
-Blocks are split into two sections: **Core Blocks** (Agent, API, Condition, Function, etc.) and **Tools** (all integration blocks).
-
-- **All checked (default):** All blocks are allowed.
-- **Subset checked:** Only the selected blocks are allowed. Workflows that already contain a disallowed block will fail when run — they are not automatically modified.
-
-Expand an integration block to reach its **tool denylist**. Clearing individual tools blocks those operations while leaving the rest of the integration usable — for example, allowing a member to read from a service but not to delete in it.
-
-<Callout type="info">
-  The `start_trigger` block (the entry point of every workflow) is always allowed and cannot be restricted.
+<Callout type="warn">
+Changes to workspace scope, the default-group switch, and membership take effect immediately. **Discard** only discards the buffered name, description, and permission changes.
 </Callout>
 
-#### Platform
-
-Controls the modules, actions, and credentials available to group members. Every row refuses at the API, not only in the UI — clearing a box revokes the access; it does not merely hide a tab.
-
-<Image src="/static/enterprise/access-control-platform.png" alt="Platform tab showing feature toggles grouped by category" width={900} height={566} className="mx-auto h-auto w-full max-w-xl" />
-
-**Modules**
+In the provider, block, and platform permission lists, a checked box allows the item. Clear it to restrict the item. The **Project Issues** project checklist is an exception: checked projects are restricted.
 
-| Feature | What clearing it withholds |
-|---------|---------------------------|
-| Chat | Revokes Chat. Members cannot ask Sim to build or edit anything. |
-| Sim Mailer | Revokes the Sim Mailer inbox. Members cannot read or send mail. |
-| Sandboxes | Revokes the Sandboxes module. Members cannot view, create, or change a workspace sandbox. |
+### General
 
-**Knowledge Base**
+The **General** tab sets the name, description, workspaces, members, and default-group status. Sim selects a single governing group for each person and workspace:
 
-| Feature | What clearing it withholds |
-|---------|---------------------------|
-| Knowledge Base | Revokes the Knowledge Base module. Members cannot open, search, or query any knowledge base. |
-| Knowledge Base Creation | Prevents creating knowledge bases, leaving existing ones queryable. |
-| Knowledge Base Uploads | Prevents uploading local documents, leaving sanctioned connectors as the only source. |
+1. A non-default group targeting that workspace with the person as an explicit member.
+2. Otherwise, a non-default group targeting that workspace in inheritance membership mode with no named members. It governs all workspace members, including external members.
+3. Otherwise, the organization's default group, if configured.
+4. Otherwise, no permission-group restrictions.
 
-The **Knowledge Base** row also carries a **connector allowlist** — *Connectors knowledge bases may sync from*. Leave it untouched to allow every connector, or select a subset to limit which external sources a knowledge base may sync.
+The default is a fallback. Its restrictions are not combined with a selected workspace group. Only one group can be the organization default; it applies across the organization's workspaces and ignores a named-member list.
 
-**Tables**
+An ordinary workspace group starts by governing all members of its selected workspaces. Adding named members narrows it to those people. Removing its last member can make it govern everyone again. **SCIM explicit-membership groups behave differently:** an empty explicit group governs nobody. See [SCIM provisioning](/platform/enterprise/scim).
 
-| Feature | What clearing it withholds |
-|---------|---------------------------|
-| Tables | Revokes the Tables module. Members cannot read or write any table. |
-| Table Creation | Prevents creating tables, leaving existing ones usable. |
-| Table Export | Prevents downloading a whole table as CSV or JSON. |
+Assignment checks allow at most one all-members group per workspace and at most one explicit group per person on a shared workspace. Conflicting individual assignments are rejected; conflicting people in bulk additions are skipped. Scope changes or removing the last inheritance-mode member can also be rejected if they would create a conflict. Sim does not silently move memberships between groups.
 
-**Files**
+A non-default group needs a workspace when created, but you can later remove all its workspaces. It then governs nobody until you add a workspace. External workspace members cannot be selected as named organization members; the workspace's all-members group or organization default can still govern them.
 
-| Feature | What clearing it withholds |
-|---------|---------------------------|
-| Files | Revokes the Files module. Members cannot list, upload, or download workspace files. |
-| Public Sharing | Revokes public file sharing. Members cannot create a share link. |
-| Bulk Download | Prevents downloading folders as an archive. |
+### Model Providers
 
-The **Public Sharing** row also carries an **auth-mode allowlist** — *Auth modes public file-share links may use* (Anyone with link, Password, Email, SSO). Select a subset to force share links onto stronger authentication.
+All providers are allowed by default. Select a subset to allow only those providers. Expand a provider to deny individual models while leaving its other models available.
 
-**Deployment**
+The **Agent default** chooses the initial model for new Agent blocks. Choose an allowed model, or **Platform default** to use Sim's default. This setting does not itself restrict models or rewrite existing blocks.
 
-| Feature | What clearing it withholds |
-|---------|---------------------------|
-| Public API | Revokes public API access. Calls to a deployed workflow are refused. |
-| API Deployment | Prevents deploying a workflow as an API endpoint. |
-| MCP Server | Prevents exposing a workflow as an MCP server. |
-| Chat Deployment | Prevents publishing a workflow as a chat. |
-| Webhook Triggers | Prevents making a workflow reachable from an inbound webhook. |
+### Blocks
 
-The **Chat Deployment** row also carries an **auth-mode allowlist** — *Auth modes chat deployments may use* (Public, Password, Email, SSO).
+**Core Blocks** contains blocks such as Agent, API, and Function; **Tools** contains integration blocks. All are allowed by default. Select a subset to restrict block types, then expand an integration to deny individual operations—for example, allow reads while refusing deletes.
 
-**Tools**
+The `start_trigger` entry block is always allowed. Existing workflows are not rewritten when a restriction changes. A run fails if it reaches a blocked type, provider, model, or tool operation.
 
-| Feature | What clearing it withholds |
-|---------|---------------------------|
-| MCP Tools | Blocks agents from calling MCP tools. |
-| Custom Tools | Blocks agents from calling user-defined custom tools. |
-| Skills | Blocks agents from loading skills. |
-| Tool Auto-Approval | Prevents auto-approving tool calls, so every call must be confirmed. |
+### Platform
 
-**Logs**
+Most platform restrictions refuse the protected operation at the server as well as limiting its UI. **Trace Spans** and **Execution Cost** instead control which fields an otherwise authorized log read or export returns.
 
-| Feature | What clearing it withholds |
-|---------|---------------------------|
-| Trace Spans | Withholds per-block trace spans from logs and from the API. |
-| Log Export | Prevents downloading execution logs as a CSV. |
-| Execution Cost | Withholds execution cost. Logs and member exports omit cost and token spend; organization-level data drains, configurable by org admins only, are not projected. |
+| Category | Permission | Effect when restricted |
+| --- | --- | --- |
+| Modules | Chat | Prevents using Chat to ask Sim to build or edit. |
+| Modules | Sim Mailer | Prevents reading or sending through the Sim Mailer inbox. |
+| Modules | Sandboxes | Prevents viewing, creating, or changing workspace sandboxes. |
+| Knowledge Base | Knowledge Base | Prevents opening, searching, or querying knowledge bases. |
+| Knowledge Base | Knowledge Base Creation | Prevents creating bases; existing permitted bases remain usable. |
+| Knowledge Base | Knowledge Base Uploads | Prevents local document uploads. |
+| Knowledge Base | Knowledge Base Export | Prevents exporting a knowledge base. |
+| Tables | Tables | Prevents table reads and writes. |
+| Tables | Table Creation | Prevents creating tables. |
+| Tables | Table Export | Prevents whole-table CSV or JSON downloads. |
+| Files | Files | Prevents listing, uploading, or downloading workspace files. |
+| Files | Public Sharing | Prevents creating file-share links. |
+| Files | Bulk Download | Prevents downloading folders as archives. |
+| Deployment | Public API | Refuses governed public API access to deployed workflows. |
+| Deployment | API Deployment | Prevents deploying workflows as API endpoints. |
+| Deployment | MCP Server | Prevents exposing workflows through MCP servers. |
+| Deployment | Chat Deployment | Prevents deploying workflows as chats. |
+| Deployment | Webhook Triggers | Prevents exposing workflows through inbound webhooks. |
+| Tools | MCP Tools | Prevents agents from calling MCP tools. |
+| Tools | Custom Tools | Prevents agents from calling custom tools. |
+| Tools | Skills | Prevents agents from loading skills. |
+| Tools | Tool Auto-Approval | Prevents storing an always-allow preference for tool calls. |
+| Logs | Trace Spans | Withholds per-block spans from log reads and API responses. |
+| Logs | Log Export | Prevents CSV execution-log downloads. |
+| Logs | Execution Cost | Omits cost and token spend from governed logs and member exports. Organization-admin data drains are not projected this way. |
+| Collaboration | Invitations | Prevents workspace or organization invitations in the applicable scope. |
+| Collaboration | Workspace Creation | Prevents creating workspaces. |
+| Collaboration | Member Directory | Withholds other members' names and emails; organization owners and admins retain roster access. |
+| Credentials & Access | Integrations | Prevents viewing, adding, or removing integration connections. |
+| Credentials & Access | Secrets | Prevents reading, adding, or changing workspace environment variables. |
+| Credentials & Access | API Keys | Prevents listing, creating, or revoking workspace API keys. |
+| Credentials & Access | Personal API Keys | Prevents using personal API keys against the workspace. |
+| Credentials & Access | Personal Credentials | Prevents connecting personal credentials, leaving workspace-shared credentials available. |
+| Credentials & Access | CLI Access | Prevents CLI login approval and use of CLI OAuth tokens for the public API. API keys retain their separate policies. |
+| Credentials & Access | OAuth App Access | Prevents OAuth apps from accessing governed workspaces. |
 
-**Collaboration**
+Additional lists narrow selected capabilities:
 
-| Feature | What clearing it withholds |
-|---------|---------------------------|
-| Invitations | Prevents inviting anyone to a workspace or to the organization. |
-| Workspace Creation | Prevents creating new workspaces. A new one is not covered by any workspace-scoped group until you add it, though the organization's default group still governs it. |
-| Member Directory | Withholds the member directory. Members cannot see the names or email addresses of other members. Organization owners and admins keep access — the roster routes exempt those roles. |
+- **Knowledge Base** has a connector allowlist. Leave it unrestricted to allow all connectors, or select permitted sources.
+- **Public Sharing** has an auth-mode allowlist: Anyone with link, Password, Email, and SSO.
+- **Chat Deployment** has an auth-mode allowlist: Public, Password, Email, and SSO.
+- **Project Issues** restricts issue access for the checked projects. Governed teammates must have workspace access to every active environment in a selected project.
 
-**Credentials & Access**
+Restricting **Tool Auto-Approval** prevents remembering approval for future calls. It does not undo approval of the current call or force confirmation for tools that do not require it. Future calls that require confirmation prompt again.
 
-| Feature | What clearing it withholds |
-|---------|---------------------------|
-| Integrations | Revokes integration connections. Members cannot view, add, or remove an OAuth connection. |
-| Secrets | Revokes secrets. Members cannot read, add, or change a workspace environment variable. |
-| API Keys | Revokes workspace API keys. Members cannot list, create, or revoke one. |
-| Personal API Keys | Prevents members from using a personal API key against this workspace. |
-| Personal Credentials | Prevents connecting personal credentials, leaving only workspace-shared ones. |
-| CLI Access | Prevents approving a CLI login or using Sim CLI OAuth tokens for the public API. Existing API keys retain their own restrictions. |
-| OAuth App Access | Prevents OAuth apps from accessing the group's workspaces. The organization default group also governs authorization, token issuance and refresh, and account-level billing and audit reads. |
+#### Organization-level permissions
 
-##### Rows read from the organization default group
+**Workspace Creation** and **Member Directory** read only the organization default, because those actions have no workspace scope. Other groups show them as inactive with an **Organization** tag, and **Select All** skips them. A newly created workspace uses the organization default until you add it to a workspace group.
 
-Two rows — **Workspace Creation** and **Member Directory** — are read only from the organization's **default group**, because the act they govern names no workspace. On any other group the editor renders them inert, tags them **Organization**, and skips them in **Select All**. Set them on the default group.
+**Integrations**, **API Keys**, **Invitations**, **Personal API Keys**, **CLI Access**, and **OAuth App Access** use the selected workspace group for workspace operations. Account-level operations use the organization default: minting a personal key, sending organization invitations, approving CLI login, authorizing or refreshing OAuth, and account-level billing or audit reads.
 
-Six more rows — **Integrations**, **API Keys**, **Invitations**, **Personal API Keys**, **CLI Access**, and **OAuth App Access** — apply on the group in front of you for anything scoped to one of its workspaces. Account-level actions use the organization's default group, including minting a personal key, sending an organization-wide invitation, approving a CLI login, and authorizing or refreshing an OAuth app.
-
-### 4. Choose who it applies to
-
-A user is governed by one group per workspace, so adding a user is rejected when it would conflict with another of their groups on a shared workspace (skipped rather than added in bulk). The default group ignores members entirely — it always governs everyone not covered by a workspace group.
-
-A workspace also has at most one all-members group. Adding a workspace to a group, or removing a group's last member, is rejected when doing so would violate that — memberships and scopes are never silently moved.
-
-Manage which workspaces a group governs from the **Workspaces** list on the same **General** tab. A non-default group is created targeting at least one workspace, but you can later remove all of them — a group with no workspaces simply governs nothing until you add one back.
-
-External workspace members (people who have access to a workspace but belong to a different organization) can't be added as named members, but a workspace-scoped group with no members — and the organization default group — still governs them.
-
----
+## How enforcement applies
 
-## Enforcement
+A human's governing group applies to session, personal API-key, OAuth, and delegated operations. Workflow restrictions are checked during execution, including deployments invoked by API, schedule, or webhook, using the operation's authorized identity. They do not replace workspace roles, credential access, or OAuth scopes.
 
-### Workflow execution
+A **workspace API key** acts as the workspace. It has workspace-role and operation policies but no human user's permission group; Sim does not apply the key creator's group as a substitute. A human's permission to create or manage that key is still governed.
 
-Restrictions are enforced at the point of execution, not at save time. If a group's configuration changes after a workflow is built:
-
-- **Block restrictions:** Any workflow run that reaches a disallowed block halts immediately with an error. The workflow is not modified — only execution is blocked.
-- **Model provider restrictions:** Any block or agent that uses a disallowed provider halts immediately with an error.
-- **Tool restrictions (MCP, custom tools, skills):** Agents that use a disallowed tool type halt immediately with an error.
-
-This applies regardless of how the workflow is triggered — manually, via API, via schedule, or via webhook.
-
-### Chat
-
-When a user opens Chat, their permission group is read before any block or tool suggestions are made:
-
-- Blocks not in the allowed list are filtered out of the block picker entirely — they do not appear as options.
-- Generation is not gated for these three tool kinds, so Sim can still produce a step that uses one. The restriction is enforced when the run reaches it: execution fails with an error naming it.
-
----
-
-<FAQ items={[
-  {
-    question: "Who can create and manage permission groups?",
-    answer: "Any organization owner or admin on an Enterprise-entitled organization can create, edit, and delete permission groups. On Sim Cloud that means the organization must be on the Enterprise plan; self-hosted deployments use environment variables instead of the plan check."
-  },
-  {
-    question: "What happens to a workflow that was built before a block was restricted?",
-    answer: "The workflow is not modified — it still exists and can be edited. However, any run that reaches a disallowed block will halt immediately with an error. The block must be removed or the user's group configuration must be updated before the workflow can run successfully."
-  },
-  {
-    question: "Does Chat respect the same restrictions as the executor?",
-    answer: "Sim uses the permission group governing the workflow's workspace. Disallowed blocks are filtered from the block picker. Generated workflows can still reference a restricted tool type; execution rejects it with an error naming the restriction."
-  },
-  {
-    question: "Can I apply different restrictions to different people or workspaces?",
-    answer: "Yes. Scope each group to the workspaces it should govern, and either let it apply to everyone there or add members to target specific people. A workspace can have one all-members group plus additional groups that target specific people, who are governed by their own group instead. Who can access a given workspace is still controlled separately by workspace invitations and permissions."
-  }
-]} />
-
----
+Chat filters restricted blocks from its available block catalog. Generated steps can still reference a restricted MCP tool, custom tool, or skill; execution rejects the restricted operation when reached. After changing a group, verify both the person's available UI and a representative authorized run. For an existing workflow that fails, remove the restricted item or change the governing policy.
 
 ## Self-hosted setup
 
-Self-hosted deployments use environment variables instead of the billing/plan check.
-
-### Environment variables
+On billing-disabled deployments, enable permission groups through the enterprise feature configuration or explicitly set:
 
 ```bash
 ACCESS_CONTROL_ENABLED=true
 NEXT_PUBLIC_ACCESS_CONTROL_ENABLED=true
 ```
 
-You can also set a server-level block allowlist using the `ALLOWED_INTEGRATIONS` environment variable. This is applied as an additional constraint on top of any permission group configuration — a block must be allowed by both the environment allowlist and the user's group to be usable.
+The enterprise master configuration can enable the feature; an explicit feature value takes precedence. Billing-enabled self-hosted deployments still require Enterprise. See [self-hosted enterprise setup](/platform/enterprise/self-hosted).
+
+`ALLOWED_INTEGRATIONS` adds an instance-wide block allowlist. A block must satisfy both that list and the applicable group policy; `start_trigger` remains available.
 
 ```bash
-# Only these block types are available across the entire instance
 ALLOWED_INTEGRATIONS=slack,gmail,agent,function,condition
 ```
 
-Once enabled, permission groups are managed through **Settings → Organization → Permission groups** the same way as Sim Cloud.
+## Related docs
+
+- [Workspace permissions](/platform/workspaces)
+- [SCIM provisioning](/platform/enterprise/scim)
+- [Audit logs](/platform/enterprise/audit-logs)
diff --git a/apps/docs/content/docs/platform/enterprise/audit-logs.mdx b/apps/docs/content/docs/platform/enterprise/audit-logs.mdx
index 39c7a63ddb6..13980ad02fe 100644
--- a/apps/docs/content/docs/platform/enterprise/audit-logs.mdx
+++ b/apps/docs/content/docs/platform/enterprise/audit-logs.mdx
@@ -1,77 +1,77 @@
 ---
-title: Audit Logs
-description: Track configuration and security events across your organization's workspaces
+title: Audit logs
+description: Investigate configuration and security events across your organization
 ---
 
-import { FAQ } from '@/components/ui/faq'
-import { Image } from '@/components/ui/image'
+Audit logs record the actor, time, and affected resource for configuration and security events. Organization owners and admins can investigate changes across the organization's workspaces, export CSV, or send events to a [data drain](/platform/enterprise/data-drains).
 
-Audit logs record configuration and security events across your organization, including the actor, time, and affected resource. Use them to investigate changes and incidents.
+Billing-enabled deployments require Enterprise. Billing-disabled deployments use audit-log feature configuration and still need an organization for the organization viewer and API. Workspace admin access alone does not grant organization audit access.
 
----
+## Find events
+
+Open **Settings → Organization → Audit logs**. Search actions, actors, resource names, or descriptions, then narrow by resource type and date. Links from a workspace's Insights view also scope the feed to that workspace; remove the workspace chip to return to the organization feed.
 
-## Viewing audit logs
+| Column | Content |
+| --- | --- |
+| **Timestamp** | Time of the recorded action. |
+| **Event** | Action identifier, such as `workflow.created`. |
+| **Description** | Human-readable action summary. |
+| **Actor** | Email or name when available; a system fallback for actions without one. |
 
-### In the UI
+By default, queries include actors who are current organization members and anonymous actions. API and CSV queries can set `includeDeparted=true` to include departed and external workspace actors. External workspace members may act on workspace resources without joining the organization; invitation metadata records internal or external membership.
 
-Go to **Settings → Organization → Audit logs** in your workspace. Logs are displayed in a table with the following columns:
+Historical visibility depends on current workspace ownership and stored organization attribution. Workspace moves or physical deletion can change which events an organization query returns. Export events you need to retain under independent archive controls.
 
-<Image src="/static/enterprise/audit-logs.png" alt="Audit Logs settings showing a table of events with columns for Timestamp, Event, Description, and Actor, along with search and filter controls" width={900} height={830} className="mx-auto h-auto w-full max-w-xl" />
+## Export and integrate
 
-| Column | Description |
-|--------|-------------|
-| **Timestamp** | When the action occurred. |
-| **Event** | The action taken, e.g. `workflow.created`. |
-| **Description** | A human-readable summary of the action. |
-| **Actor** | The email address of the user who performed the action. |
+Download CSV from the viewer, paginate the API, or use an audit-log drain for continuous delivery. CSV includes resource, workspace, and actor IDs; IP address; user agent; surface; and per-action metadata. The JSON API omits IP addresses and user agents.
 
-Use the search bar, event type filter, and date range selector to narrow results.
+CSV is capped at **10,000 rows or 64 MiB**. An oversized record can also stop it early. `X-Export-Truncated: 1` indicates a partial download; narrow the filters and export again. CSV export is itself an audited operation.
 
-### Via API
+### Organization API
 
-Audit logs are also accessible through the Sim API for integration with external SIEM or log management tools.
+For new integrations, use the [v2 audit-log reference](/api-reference/audit-logs/listAuditLogs). It supports `orgId`, `actorEmail`, UTC date filters, and the v2 pagination envelope. The v1 request below remains supported; changing only its URL to v2 does not preserve its query or response contract.
 
 ```http
 GET /api/v1/audit-logs
-X-API-Key: <api-key>
+X-API-Key: <personal-api-key>
 ```
 
-**Query parameters:**
+The key's owner must be an organization owner or admin. Workspace API keys are refused. Rate limits apply, and `X-RateLimit-*` headers report the current quota.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `action` | string | Filter by event type (e.g. `workflow.created`) |
-| `resourceType` | string | Filter by resource type (e.g. `workflow`) |
-| `resourceId` | string | Filter by a specific resource ID |
-| `workspaceId` | string | Filter by workspace |
-| `actorId` | string | Filter by a current organization member’s user ID. For a departed-actor filter, use the CSV export with `includeDeparted=true`. |
-| `startDate` | string | ISO 8601 date — return logs on or after this date |
-| `endDate` | string | ISO 8601 date — return logs on or before this date |
-| `includeDeparted` | boolean | Include logs from members who have since left the organization (default `false`) |
-| `limit` | number | Results per page (1–100, default 50) |
-| `cursor` | string | Opaque cursor for fetching the next page |
+| v1 query parameter | Behavior |
+| --- | --- |
+| `action` | Event identifier, such as `workflow.created`. |
+| `resourceType` | Resource type; accepts comma-separated types. |
+| `resourceId` | Specific resource ID. |
+| `workspaceId` | Workspace in the caller's organization. |
+| `actorId` | Current organization member's user ID. Departed-actor filtering is supported by CSV with `includeDeparted=true`. |
+| `startDate`, `endDate` | ISO 8601 lower and upper date bounds. |
+| `includeDeparted` | Includes actors outside current organization membership; default `false`. |
+| `limit` | Page size, 1–100; default 50. |
+| `cursor` | Opaque next-page cursor. |
 
-**Example response:**
+A v1 page contains `data`, an optional `nextCursor`, and `limits`. Each entry has `id`, `action`, `resourceType`, nullable resource ID/name, description, actor ID/name/email, workspace ID, arbitrary per-action `metadata`, and `createdAt`.
 
 ```json
 {
   "data": [
     {
-      "id": "abc123",
+      "id": "audit-event-id",
       "action": "workflow.created",
       "resourceType": "workflow",
-      "resourceId": "wf_xyz",
-      "resourceName": "Customer Onboarding",
-      "description": "Created workflow \"Customer Onboarding\"",
-      "actorId": "usr_abc",
+      "resourceId": "workflow-id",
+      "resourceName": "Customer onboarding",
+      "description": "Created workflow \"Customer onboarding\"",
+      "actorId": "user-id",
       "actorName": "Alice Smith",
-      "actorEmail": "alice@company.com",
-      "workspaceId": "ws_def",
+      "actorEmail": "alice@example.com",
+      "workspaceId": "workspace-id",
       "metadata": {},
       "createdAt": "2026-04-20T21:16:00.000Z"
     }
   ],
-  "nextCursor": "eyJpZCI6ImFiYzEyMyJ9",
+  "nextCursor": "opaque-next-page-cursor",
   "limits": {
     "workflowExecutionRateLimit": {
       "sync": { "requestsPerMinute": 60, "maxBurst": 10, "remaining": 59, "resetAt": "2026-04-20T21:17:00.000Z" },
@@ -82,88 +82,57 @@ X-API-Key: <api-key>
 }
 ```
 
-Paginate by passing the `nextCursor` value as the `cursor` parameter in the next request. When `nextCursor` is absent, you have reached the last page. Each entry also includes `actorName`; `metadata` is an arbitrary per-action JSON object. The `limits` object reports your current rate-limit and usage status.
-
-The organization audit API requires a personal API key belonging to an organization owner or admin. Workspace API keys are refused. Rate limits apply — the response includes `X-RateLimit-*` headers with your current limit and remaining quota.
-
----
+The limits above are illustrative. Pass `nextCursor` as the next request's `cursor`; its absence ends pagination. Keep filters unchanged across pages.
 
-## Event types
+## Recorded events and limits
 
-Audit log events follow a `resource.action` naming pattern. The table below lists the main categories.
+Events use identifiers such as `resource.action`. These categories are representative, not an exhaustive event catalog.
 
 | Category | Example events |
-|----------|---------------|
-| **Authentication** | `auth.login_succeeded`, `auth.login_failed`, `auth.logout`, `auth.impersonation_started`, `auth.impersonation_ended`, `auth.sessions_revoked` |
-| **Workflows** | `workflow.created`, `workflow.deleted`, `workflow.deployed`, `workflow.locked` |
-| **Workspaces** | `workspace.created`, `workspace.updated`, `workspace.deleted` |
-| **Members** | `member.invited`, `member.removed`, `member.role_changed` |
-| **Permission groups** | `permission_group.created`, `permission_group.updated`, `permission_group.deleted` |
-| **Environments** | `environment.updated`, `environment.deleted` |
-| **Knowledge bases** | `knowledge_base.created`, `knowledge_base.deleted`, `connector.synced` |
-| **Tables** | `table.created`, `table.updated`, `table.deleted` |
-| **API keys** | `api_key.created`, `api_key.revoked` |
-| **Credentials** | `credential.created`, `credential.deleted`, `oauth.disconnected` |
-| **Organization** | `organization.updated`, `org_member.added`, `org_member.role_changed`, `organization.sso_provider.updated` |
-| **Exports and drains** | `audit_logs.exported`, `data_drain.created`, `data_drain.updated`, `data_drain.ran`, `data_drain.tested` |
-
-Authentication failures and password-reset requests use an anonymous actor and identify the target account separately. Impersonation and administrative session revocations identify the operator and the target organization. Table-row mutations record operation summaries and counts without copying row contents.
-
-Most audit writes are best effort: a database outage or process loss can prevent persistence even when the underlying action succeeds. Deployment activation uses an awaited, idempotent audit insert before its outbox checkpoint. Audit logs are not a complete tool-invocation stream or a transactionally guaranteed ledger for every operation.
-
-Organization visibility depends on current workspace ownership or stored organization attribution. Older workspace events without organization metadata may no longer appear in organization queries after the workspace is physically deleted.
-
-Workspace invitation events include whether the invite is for an internal organization member or an external workspace member in their metadata. External workspace members can appear as actors on workspace-scoped events, and appear in the roster with an External label without becoming organization members.
-
----
-
-<FAQ items={[
-  {
-    question: "Who can view audit logs?",
-    answer: "Organization owners and admins can view audit logs. On Sim Cloud, you must be on the Enterprise plan."
-  },
-  {
-    question: "Are audit logs tamper-proof?",
-    answer: "The Sim interface and API do not provide audit-entry edits or deletion. Database administrators can still alter stored records, and entries are not cryptographically sealed. Use a data drain to archive them under your own storage and retention controls."
-  },
-  {
-    question: "Can I export audit logs?",
-    answer: "Yes. Download CSV from the audit viewer or paginate the API for your SIEM. CSV includes event, workspace, resource and actor IDs, IP address, user agent, surface and metadata. Organization administrators can include departed actors for historical investigations. CSV downloads are recorded in the audit trail and capped at 10,000 rows or 64 MiB. Oversized records also end the download early; the X-Export-Truncated header indicates a partial export. For continuous delivery, use an audit-log data drain."
-  },
-  {
-    question: "Are logs scoped to a single workspace or the whole organization?",
-    answer: "Audit logs are scoped to your organization and include activity across all workspaces within it. You can filter by workspaceId to narrow results to a specific workspace."
-  },
-  {
-    question: "What information is included in each log entry?",
-    answer: "Each entry includes the event type, a description, the actor's name and email, the affected resource, the workspace, and a timestamp. The JSON API omits IP addresses and user agents; authorized CSV exports and audit-log drains include them."
-  },
-  {
-    question: "Can I filter logs by a specific user?",
-    answer: "Yes. The JSON API accepts actorId for current organization members. CSV exports also support departed actors when includeDeparted=true. Workspace-scoped logs may include external workspace members who acted inside a workspace without joining the organization."
-  }
-]} />
-
----
+| --- | --- |
+| Authentication | `auth.login_succeeded`, `auth.login_failed`, `auth.logout`, `auth.impersonation_started`, `auth.impersonation_ended`, `auth.sessions_revoked` |
+| Workflows | `workflow.created`, `workflow.deleted`, `workflow.deployed`, `workflow.locked` |
+| Workspaces | `workspace.created`, `workspace.updated`, `workspace.deleted` |
+| Members | `member.invited`, `member.removed`, `member.role_changed` |
+| Permission groups | `permission_group.created`, `permission_group.updated`, `permission_group.deleted` |
+| Environments | `environment.updated`, `environment.deleted` |
+| Knowledge bases | `knowledge_base.created`, `knowledge_base.deleted`, `connector.synced` |
+| Tables | `table.created`, `table.updated`, `table.deleted` |
+| API keys | `api_key.created`, `api_key.revoked` |
+| Credentials | `credential.created`, `credential.deleted`, `oauth.disconnected` |
+| Organization | `organization.updated`, `org_member.added`, `org_member.role_changed`, `organization.sso_provider.updated` |
+| Exports and drains | `audit_logs.exported`, `data_drain.created`, `data_drain.updated`, `data_drain.ran`, `data_drain.tested` |
+
+Authentication failures and password-reset requests use an anonymous actor and record the target account separately. Impersonation and administrative session revocations identify the operator and target organization. Table-row mutations record summaries and counts without copying row contents.
+
+Most audit writes are best effort: an outage or process loss can prevent persistence after an action succeeds. Deployment activation uses an awaited, idempotent insert before its outbox checkpoint. The feed is not a complete tool-call stream or a guaranteed transactional ledger for every operation.
+
+The interface and API provide no audit-entry editing or deletion. Database administrators can alter stored records, and entries are not cryptographically sealed. Use a drain to retain your own archive.
 
 ## Self-hosted setup
 
-Self-hosted deployments use environment variables instead of the billing/plan check.
-
-### Environment variables
+On billing-disabled deployments, enable audit logs through enterprise configuration or explicitly set:
 
 ```bash
 AUDIT_LOGS_ENABLED=true
 NEXT_PUBLIC_AUDIT_LOGS_ENABLED=true
 ```
 
-Once enabled, audit logs are viewable in **Settings → Organization → Audit logs** and accessible via the API.
+Explicit feature values take precedence over the enterprise master setting. Billing-enabled self-hosted deployments retain the Enterprise gate. See [self-hosted enterprise setup](/platform/enterprise/self-hosted).
+
+### Deployment-admin API
 
-`GET /api/v1/audit-logs` authenticates with an `x-api-key` whose owner is an admin or owner of an organization, so it is unreachable on a deployment where nobody belongs to one yet. On Sim Cloud it additionally requires an active Enterprise subscription; self-hosted, `AUDIT_LOGS_ENABLED` takes that role. The admin-key equivalent needs neither an organization nor a plan:
+Operators can use a separate instance-wide API with `ADMIN_API_KEY`, without an organization or plan:
 
 ```http
 GET /api/v1/admin/audit-logs
 x-admin-key: <admin-api-key>
 ```
 
-It accepts the same filters plus `actorEmail`, drops `includeDeparted`, and paginates with `limit` (max 250) and `offset` instead of the organization endpoint's `limit` (max 100) and `cursor`. It returns entries across the whole deployment rather than one organization. `GET /api/v1/admin/audit-logs/<id>` returns a single entry. Set `ADMIN_API_KEY` to use it — see the [self-hosted enterprise guide](/platform/enterprise/self-hosted).
+This endpoint returns events across the deployment, including IP addresses and user agents. It supports the organization endpoint's event/resource/workspace/date filters plus `actorEmail`, omits `includeDeparted`, and uses `limit` (default 50, maximum 250) and `offset` (default 0) pagination. `GET /api/v1/admin/audit-logs/<id>` returns one entry. Keep the deployment-admin key separate from personal organization keys.
+
+## Related docs
+
+- [Data drains](/platform/enterprise/data-drains)
+- [Permission groups](/platform/enterprise/access-control)
+- [Audit-log CLI](/cli/audit-logs)
diff --git a/apps/docs/content/docs/platform/enterprise/custom-blocks.mdx b/apps/docs/content/docs/platform/enterprise/custom-blocks.mdx
index 7184c315202..f3f310fd922 100644
--- a/apps/docs/content/docs/platform/enterprise/custom-blocks.mdx
+++ b/apps/docs/content/docs/platform/enterprise/custom-blocks.mdx
@@ -1,144 +1,82 @@
 ---
-title: Custom Blocks
+title: Custom blocks
 description: Publish a deployed workflow as a reusable block for your organization
 ---
 
-import { FAQ } from '@/components/ui/faq'
+import { Callout } from 'fumadocs-ui/components/callout'
 import { Image } from '@/components/ui/image'
 
-Custom blocks let you package a deployed workflow as a reusable block for your whole organization. Once published, the block appears in the workflow editor's block toolbar alongside built-in blocks like Agent and Function. Anyone in your organization can drop it into a workflow, fill in its inputs, and use its outputs — without needing access to the workflow behind it.
+Publish a workflow as a custom block so teammates can provide its inputs and use selected outputs without access to its source workflow. The block always runs the source's latest deployment. Use it for a shared knowledge lookup, an authenticated internal API, an enrichment step, or a prompt and guardrail maintained in one place.
 
-A custom block always runs the **latest deployed version** of its source workflow, so improving the block is as simple as redeploying that workflow.
+Publishing and managing a block requires admin access to its source workspace. Billing-enabled deployments require an Enterprise organization. On billing-disabled deployments, enable the custom-block feature through enterprise configuration or `CUSTOM_BLOCKS_ENABLED=true` and `NEXT_PUBLIC_CUSTOM_BLOCKS_ENABLED=true`. An organization is still required; see [self-hosted enterprise setup](/platform/enterprise/self-hosted).
 
----
-
-## Common uses
-
-Consumers see only the inputs and outputs by default, unless the author enables **Trace runs in consumer logs**. Identity splits at execution: the source workflow's owner supplies personal variables and delegated calls, and the source workspace supplies workspace variables and carries the billing. Common patterns:
-
-- **Internal API gateway.** Wrap an authenticated internal or partner endpoint — "Create Ticket", "Charge Account", "Provision User" — behind a block that takes only the business inputs. Teammates call it without the base URL, API key, or auth headers, and when the endpoint changes you update one workflow instead of every consumer's.
-- **Blessed knowledge lookup.** Package a vetted retrieval pipeline — chunking, filters, reranking — as "Search Company Docs" with a single query input, so teams reuse the approved retrieval instead of each rebuilding it.
-- **Governed LLM step.** Share a prompt, model, and guardrail combination like "Summarize (house style)". You control the model and prompt org-wide; changing them is a redeploy, not a hunt through everyone's workflows.
-- **Data enrichment.** Expose "Enrich Company" or "Lookup Customer by Email" that hides the provider keys and returns clean fields.
-- **Compliance gate.** Offer "Redact PII" or "Policy Check" as a standardized step teams drop into their flows, with the rules maintained in one place.
-
----
-
-## Before you start
+## Publish a block
 
-- **Deploy the workflow first.** Only deployed workflows can be published as a block. If the workflow isn't deployed, deploy it, then come back.
-- **Be a workspace admin.** Publishing and managing custom blocks requires workspace admin access.
+1. Deploy the source workflow.
+2. Open **Settings → Workspace → Custom blocks** and click **Create block**.
+3. Select its **Workspace** and **Workflow**. The picker lists organization workspaces and deployed workflows. You must be an admin of the selected source workspace.
+4. Set the block's presentation and interface using the fields below.
+5. Review its trace policy, then click **Save**.
 
----
-
-## Publishing a block
-
-### 1. Open Custom blocks settings
-
-Go to **Settings → Organization → Custom blocks** and click **Create block**.
+Only one custom block can be published per source workflow. The source is fixed after publication; publishing another workflow requires a separate block.
 
-<Image src="/static/enterprise/custom-blocks-list.png" alt="Custom blocks settings page listing a published block with its icon, name, and description, with a Create block button in the header" width={900} height={570} />
+### Name and icon
 
+| Field | Behavior |
+| --- | --- |
+| **Icon** | Optional square PNG, JPEG, SVG, or WebP, up to 5 MiB. Falls back to the organization logo, then a default glyph. |
+| **Name** | Toolbar display name, up to 60 characters. |
+| **Description** | Summary of what consumers can do, up to 280 characters. |
 
-### 2. Choose the source workflow
+### Inputs
 
-| Field | Description |
-|-------|-------------|
-| **Workspace** | The workspace that holds the workflow you want to publish. Only workspaces in your organization are listed. |
-| **Workflow** | The workflow to publish. Only deployed workflows appear. If a workflow isn't deployed, deploy it first, then return here. |
+Every input on the deployed workflow's **Start** block becomes a custom-block field, with its name, type, and description. You cannot select only some Start inputs.
 
-The block runs the source workflow's latest deployment. You publish one block per workflow, and the source workflow can't be changed later — to point at a different workflow, delete the block and publish a new one.
+For each input, set an optional placeholder of up to 200 characters and use **Required** when consumers must supply it. You can store overrides for up to 50 inputs. Inputs are read from the latest deployment: adding or renaming a Start input and redeploying updates the custom block automatically; overrides for deleted inputs are ignored.
 
-### 3. Name and describe the block
+### Outputs
 
-| Field | Description |
-|-------|-------------|
-| **Icon** | Optional. A square image (PNG, JPEG, SVG, or WebP) shown on the block. Falls back to your organization's logo, then a default glyph. |
-| **Name** | The block's display name in the toolbar (e.g. `Invoice Parser`). Max 60 characters. |
-| **Description** | A short summary of what the block does. Max 280 characters. |
+Choose the values consumers can reference, grouped by their source block and output path. Expose at least one and at most 50 outputs. Each needs a unique name of up to 60 characters; `success`, `error`, and `cost` are reserved.
 
-### 4. Configure inputs
+Review exposed output paths when you change the source workflow. Redeployment updates execution but does not author a new output interface for you.
 
-Every input on the source workflow's **Start** block is exposed as a field on the custom block. You don't choose which inputs to include — they all carry over, along with each input's name, type, and description.
+### Trace policy
 
-For each input you can add an optional **placeholder** (max 200 characters) — the hint text shown in the empty field to tell consumers what to enter.
+**Trace runs in consumer logs** is off by default. The source workflow still has its own execution log; its internal trace is omitted from the consumer's log. Consumers with independent source-workspace access can still read logs there.
 
-Because inputs are read live from the deployed workflow, renaming or adding a Start input and redeploying updates the block's fields automatically.
+<Callout type="warn">
+Enabling consumer tracing exposes source block names, inputs, outputs, and prompts to anyone authorized to read the consuming workflow's logs, including people without source-workspace access. Review the data the source can handle before enabling it.
+</Callout>
 
-### 5. Choose outputs
+Changing the trace policy applies to future runs; it does not rewrite earlier logs. Failures return a reference ID so the publisher can find the source run while nested error details remain redacted for consumers.
 
-Pick which of the workflow's outputs consumers can use, and give each one a name. Outputs are grouped by the block they come from, so you can expose exactly the values that matter and hide everything internal.
+## Use a custom block
 
-- **At least one output is required.**
-- Each exposed output needs a unique **name** (max 60 characters) — that's the name consumers reference in their workflows.
+Open the workflow builder's toolbar and find **Custom Blocks**. Drag a published block into the workflow, fill its inputs, and reference its named outputs downstream. Availability is subject to [permission groups](/platform/enterprise/access-control).
 
-<Image src="/static/enterprise/custom-blocks-form.png" alt="Create block form filled in: Workspace and Workflow selectors, an uploaded icon, Name and Description fields, an expanded input with a placeholder, and two selected outputs each given a name" width={900} height={570} />
+<Image src="/static/enterprise/custom-blocks-toolbar.png" alt="Workflow toolbar showing published blocks in the Custom Blocks section" width={400} height={476} className="mx-auto h-auto w-full max-w-xs" />
 
-### 6. Choose whether runs are traced
+The source workflow's owner supplies personal variables and delegated calls. Its workspace supplies workspace variables and carries billing. Consumer inputs cross that boundary; consumers do not acquire the owner's credentials or source-workspace access. Review inputs and exposed outputs as the block's public interface.
 
-**Trace runs in consumer logs** is off by default. Leave it off and your block stays a single step in every workflow that uses it: nothing about the run is recorded anywhere a consumer can reach.
+Run a representative consumer workflow after publishing. Verify the required inputs, selected outputs, trace visibility, and source run in Logs.
 
-Turn it on and the block's steps appear inside the trace of every workflow that runs it, org-wide. That means anyone who can read those workflows' logs sees your workflow's block names, inputs, outputs, and prompts — including people with no access to this workspace. It is the same information curated outputs and redacted errors otherwise keep on your side of the block, so turn it on when you want consumers to be able to debug your block themselves, and leave it off otherwise.
+## Update, disable, or delete a block
 
-You can change this at any time; it applies to runs from that point on. Failures always return a reference id either way, so you can find a run in your own logs even with tracing off.
+Open the block under **Settings → Workspace → Custom blocks**. Blocks from other source workspaces are visible for organization reuse; managing them requires admin access to their source workspace.
 
-### 7. Save
-
-Click **Save changes**. The block is published immediately and becomes available to everyone in your organization in the workflow editor's block toolbar.
-
----
+- Edit the name, description, icon, input overrides, outputs, or trace policy. Editing the publication does not change the source workflow.
+- To change execution, edit and redeploy the source. Every consumer then uses that deployment; there is no version pin or separate republish step.
+- Setting the publication's `enabled` field to `false` through the API hides it from new selections and makes existing placements unavailable at execution. Set it to `true` to restore availability. This is separate from disabling a placed canvas block.
+- Deleting permanently removes the publication. Existing placements remain in consumer workflows and fail because their custom block is missing.
 
-## Using a custom block
+<Callout type="warn">
+Replace custom-block placements in affected drafts and deployments before deleting. The usage warning includes both. Deletion does not rewrite consumer graphs or delete the source workflow.
+</Callout>
 
-In the workflow editor, open the block toolbar. Published custom blocks appear under a **Custom blocks** section. Drag one into your workflow like any other block, fill in its inputs (using the placeholders as a guide), and reference its outputs in downstream blocks.
+Undeploying the source makes the block unavailable until the source is deployed again. Deleting the source workflow also removes its publication and leaves consumer placements broken. To switch to another source, publish that workflow as a new block and replace old placements before removing the old publication.
 
-<Image src="/static/enterprise/custom-blocks-toolbar.png" alt="Workflow editor block toolbar with a Custom Blocks section listing two published blocks below Core Blocks" width={400} height={476} className="mx-auto h-auto w-full max-w-xs" />
-
-Consumers don't need any access to the source workflow. The block runs on its own, using only the inputs provided, and returns only the outputs you exposed. Its internal steps, models, and intermediate values stay hidden unless the block's publisher turned on **Trace runs in consumer logs**, in which case they appear under the block in the run's trace.
-
-<Image src="/static/enterprise/custom-blocks-canvas.png" alt="A custom block connected to a Start block in the workflow editor, with its query input filled in and the run output showing the returned fields" width={900} height={570} />
-
----
-
-## Managing blocks
-
-Open a block from **Settings → Organization → Custom blocks** to edit or delete it.
-
-- **Editing** changes only the block's presentation, interface, and trace policy — name, description, icon, input placeholders, exposed outputs, and whether runs are traced in consumer logs. The source workflow can't be re-pointed.
-- **Changing what the block does** is done by editing and **redeploying the source workflow**. The block picks up the new deployment automatically; there's nothing to republish.
-- **Deleting** a block is permanent. Workflows already using it will have that block removed, so replace it before deleting if it's in active use.
-
----
-
-## Good to know
-
-- **Always current.** A custom block runs the source workflow's latest deployment. There are no versions to pin or manage.
-- **Access control.** Custom blocks appear in [Access Control](/platform/enterprise/access-control) alongside built-in blocks, so you can allowlist or restrict them per permission group.
-- **Disabled blocks.** A disabled block can't be added to new workflows, but existing placements keep working.
-- **Removed blocks.** Deleting a block (or deleting its source workflow) removes it from workflows that used it.
-- **Not deployed.** If the source workflow is undeployed, the block shows a clear error when run. Redeploy the workflow to fix it.
-
----
+## Related docs
 
-<FAQ items={[
-  {
-    question: "Who can publish custom blocks?",
-    answer: "Workspace admins. Once a block is published, anyone in your organization can use it in their workflows unless it's restricted with Access Control."
-  },
-  {
-    question: "Which version of the workflow does the block run?",
-    answer: "Always the latest deployed version. When you edit and redeploy the source workflow, every workflow using the block picks up the change automatically — there's no separate republish step."
-  },
-  {
-    question: "Can consumers see the workflow behind a block?",
-    answer: "A custom block only exposes the inputs it needs and the outputs you chose to share, and consumers don't need any access to the source workflow. Its steps and intermediate values stay hidden unless you enable Trace runs in consumer logs, which surfaces them in the consumer's run trace."
-  },
-  {
-    question: "Can I change which workflow a block points to?",
-    answer: "No. The source workflow is fixed when you publish. To point at a different workflow, delete the block and publish a new one."
-  },
-  {
-    question: "What happens if I delete a block or its source workflow?",
-    answer: "The block is removed from every workflow that used it. Deleting is permanent, so replace the block first if it's in active use."
-  }
-]} />
+- [Workflow deployment](/workflows/deployment)
+- [Permission groups](/platform/enterprise/access-control)
+- [Execution logs](/logs-debugging/logging)
diff --git a/apps/docs/content/docs/platform/enterprise/data-drains.mdx b/apps/docs/content/docs/platform/enterprise/data-drains.mdx
index 41b61a04e40..2ff716d4a2b 100644
--- a/apps/docs/content/docs/platform/enterprise/data-drains.mdx
+++ b/apps/docs/content/docs/platform/enterprise/data-drains.mdx
@@ -1,269 +1,196 @@
 ---
-title: Data Drains
-description: Continuously export workflow logs, audit logs, and Chat data to your own object store, data warehouse, observability platform, or HTTPS endpoint on a schedule
+title: Data drains
+description: Export retained logs and Chat data to storage, a warehouse, Datadog, or a webhook endpoint.
 ---
 
-import { FAQ } from '@/components/ui/faq'
-import { Image } from '@/components/ui/image'
+import { Callout } from 'fumadocs-ui/components/callout'
 
-Data Drains let organization owners and admins on Enterprise plans continuously export Sim data to a destination they control — a customer-owned S3 bucket, Google Cloud Storage bucket, Azure Blob container, BigQuery table, Snowflake table, Datadog logs intake, or an HTTPS webhook. A drain runs on a schedule, picks up rows after its last acknowledged delivery, and writes them to the destination. Viewing drain configuration and run history is restricted to owners and admins as well, since destinations expose internal bucket names, table identifiers, and webhook URLs.
+Data drains periodically export one source of retained Sim data to a destination you control. Organization owners and admins manage configuration and run history because those records expose destination identifiers and URLs. Billing-enabled deployments require Enterprise; billing-disabled deployments use the feature and scheduler configuration under [Self-hosted setup](#self-hosted-setup).
 
-Drains are independent of [Data Retention](/platform/enterprise/data-retention) but designed to compose with it — see [Pairing with Data Retention](#pairing-with-data-retention) below.
+A new drain starts with all retained history. Delivery is at least once: retries, partial acceptance, or a crash after delivery can duplicate rows. Deduplicate downstream by each source row's `id`.
 
----
-
-## Setup
-
-Go to **Settings → Organization → Data drains** in your workspace, then click **New drain**.
-
-<Image src="/static/enterprise/data-drains-list.png" alt="Data Drains settings page showing two configured drains — one exporting workflow logs to Amazon S3 daily, another exporting Chat conversations to an HTTPS webhook hourly" width={900} height={885} className="mx-auto h-auto w-full max-w-md" />
-
-<Image src="/static/enterprise/data-drains-new.png" alt="New data drain dialog with fields for name, source, cadence, destination, and S3 credentials" width={900} height={491} className="mx-auto h-auto w-full max-w-xl" />
+## Create and verify a drain
 
-Each drain has four pieces:
+1. Prepare the destination and credentials. Sim does not create buckets, containers, datasets, or tables.
+2. Open **Settings → Organization → Data drains** and click **Create drain**.
+3. On **New drain**, enter a name unique within the organization, choose one source, a destination, and **Every hour** or **Every day**.
+4. Fill the destination fields below and click **Create**.
+5. Open the drain's detail page. Use **Test connection**, then **Run now** and check **Recent runs** and the destination's received rows.
 
-1. A **source** — the category of data to export
-2. A **destination** — where the data goes
-3. A **schedule** — how often it runs
-4. A **name** — unique within your organization
+The detail page shows the last ten runs with status, trigger, time, row count, bytes, and failure details. Destination locators are also available through API run reads. **Run now** requires an enabled drain; an overlapping run can be refused. The **Enabled** switch pauses future runs without deleting configuration or the cursor.
 
----
-
-## Sources
+## Sources and row format
 
-A drain exports exactly one source. To export multiple sources, create multiple drains.
+Create separate drains for different sources. Every delivered row is JSON-safe NDJSON: one JSON object per line, with an `id` for deduplication.
 
-| Source | Description |
-|---|---|
-| **Workflow logs** | Workflow execution records (one row per execution, only after the run reaches a terminal state). |
-| **Job logs** | Background job records (deployed APIs, schedules, webhooks). Only terminal-state rows are exported. |
-| **Audit logs** | Organization- and workspace-scoped audit events — logins, permission changes, resource creation/deletion, drain configuration changes. |
-| **Chats** | Chat snapshots, including organization-owned chats outside a workspace. |
-| **Chat runs** | Chat run records (terminal state only), with safe correlation context. Internal controller tokens and billing recovery receipts are excluded. |
+| UI source | Wire value | Records |
+| --- | --- | --- |
+| Workflow logs | `workflow_logs` | Terminal workflow executions. |
+| Job logs | `job_logs` | Terminal background jobs for deployed APIs, schedules, and webhooks. |
+| Audit logs | `audit_logs` | Organization and workspace audit events, including departed actors. |
+| Chats | `copilot_chats` | Chat snapshots, including organization-owned chats outside a workspace. |
+| Chat runs | `copilot_runs` | Terminal Chat runs with correlation context; controller tokens and billing recovery receipts are excluded. |
 
-Each row is delivered as a single line of NDJSON. The shape of each row is part of the public schema and stable across versions; every row carries an `id` field that downstream consumers can use to dedupe.
+Workflow, job, and Chat-run cursors use terminal timestamps; audit and Chat cursors use creation time. Reads use the primary database and leave a five-minute stability window. This reduces late-commit gaps but does not guarantee change-data capture.
 
-Workflow, job, and Chat run drains advance by their terminal timestamp; audit and Chat drains advance by creation time. A new drain exports all retained history. Reads use the primary database and leave a five-minute stability window before selecting new records. This reduces late-commit gaps but is not a change-data-capture guarantee. Drains deliver rows at least once. A failed run can deliver a row again, so consumers should deduplicate by its `id`. Mutable fields on **Chats** (messages, title, `lastSeenAt`) are a point-in-time snapshot and won't be re-emitted if the chat is later updated. Treat the export as append-only and reconstitute current state from your own system of record if you need it.
+Chats are point-in-time snapshots. Later changes to messages, title, or `lastSeenAt` are not emitted again. An append-only archive therefore does not track every subsequent change to a conversation.
 
----
+The export uses each source's row schema. Inspect representative rows before defining warehouse columns; BigQuery receives top-level fields directly. Drains do not apply a new blanket PII scrub. Workflow log masking depends on the stored [data-retention redaction policy](/platform/enterprise/data-retention) used when the data was persisted; configuring `PII_URL` alone does not sanitize exported history.
 
-## Destinations
+## Destination reference
 
-### Amazon S3 (or any S3-compatible store)
+### Amazon S3 and compatible stores
 
-Writes one NDJSON object per delivered chunk to your bucket.
+Writes one NDJSON object per chunk.
 
-- **Bucket** — the bucket name. Must already exist; Sim does not create buckets.
-- **Region** — AWS region (e.g. `us-east-1`).
-- **Prefix** *(optional)* — folder path inside the bucket. Trailing slash optional.
-- **Access key ID / Secret access key** — IAM credentials with `s3:PutObject` on the bucket. The "Test connection" button performs a real write probe to verify, then deletes it.
-- **Endpoint** *(optional)* — for non-AWS stores like MinIO, Cloudflare R2, or GCS S3-interop. Leave blank for AWS S3.
-- **Force path-style** *(optional)* — required for MinIO/Ceph, must be off for AWS S3 and R2.
+| Field | Requirement |
+| --- | --- |
+| **Bucket** | Existing bucket. |
+| **Region** | AWS region, such as `us-east-1`. |
+| **Prefix** | Optional object prefix; trailing slash is optional. |
+| **Access key ID / Secret access key** | Credentials with `s3:PutObject`. `s3:DeleteObject` allows cleanup of the zero-byte connection-test probe; without it, the probe can remain. |
+| **Endpoint** | Optional HTTPS endpoint for a compatible store; leave blank for AWS. Sim Cloud requires public addresses. Self-hosted Sim can use private MinIO/Ceph or loopback endpoints permitted by its [outbound-network policy](/platform/self-hosting/security#the-ssrf-boundary). |
+| **Force path-style** | Enable if the provider requires it. Leave off for standard AWS virtual-hosted addressing. |
 
-Object keys are deterministic:
+Objects use `AES256` server-side encryption and this layout:
 
-```
+```text
 {prefix}/{source}/{drainId}/{yyyy}/{mm}/{dd}/{runId}-{seq}.ndjson
 ```
 
-Objects are written with `AES256` server-side encryption.
+The final SDK hostname is validated and its resolved address pinned. Signed request paths are preserved without redirects. An outbound gateway that cannot preserve signed targets fails closed.
 
 ### Google Cloud Storage
 
-Writes one NDJSON object per delivered chunk to your GCS bucket.
-
-- **Bucket** — the bucket name. Must already exist; Sim does not create buckets.
-- **Prefix** *(optional)* — folder path inside the bucket. Trailing slash optional.
-- **Service account JSON key** — paste the full JSON key for a service account with `storage.objects.create` (and `storage.objects.delete` if you want "Test connection" to clean up its probe). Sim authenticates via OAuth2 service-account JWT and uploads through the GCS JSON API.
+Supply an existing **Bucket**, optional **Prefix**, and the full **Service account JSON key**. The service account needs `storage.objects.create`; `storage.objects.delete` lets the connection test remove its probe. Sim uses OAuth2 service-account JWT authentication and the GCS JSON API.
 
-Object names follow the same `{prefix}/{source}/{drainId}/{yyyy}/{mm}/{dd}/{runId}-{seq}.ndjson` layout as S3. Object metadata mirrors the S3 destination's `sim-*` keys via `x-goog-meta-*` headers.
+Object names use the S3 layout above. `sim-*` object metadata uses `x-goog-meta-*` headers.
 
 ### Azure Blob Storage
 
-Writes one NDJSON block blob per delivered chunk to your container.
+Supply **Account name** (3–24 lowercase characters), an existing **Container**, optional **Prefix**, and an **Account key** with write access. Each chunk becomes an NDJSON block blob using the same object layout. Metadata keys are lowercased for Azure.
 
-- **Account name** — your storage account (3–24 lowercase chars).
-- **Container** — must already exist; Sim does not create containers.
-- **Prefix** *(optional)* — folder path inside the container.
-- **Account key** — a storage account access key with write access to the container.
-
-Blob names follow the same `{prefix}/{source}/{drainId}/{yyyy}/{mm}/{dd}/{runId}-{seq}.ndjson` layout. The `sim-*` metadata is exposed as Azure blob metadata (collapsed to lowercase per Azure's identifier rules).
-
-For sovereign clouds, set **Endpoint suffix** to `blob.core.usgovcloudapi.net` (US Gov), `blob.core.chinacloudapi.cn` (China), or `blob.core.cloudapi.de` (Germany).
+**Endpoint suffix** supports `blob.core.usgovcloudapi.net` for US Gov and `blob.core.chinacloudapi.cn` for China. Sim also accepts the legacy Germany suffix `blob.core.cloudapi.de`; verify that the particular account still uses that endpoint before selecting it.
 
 ### Google BigQuery
 
-Streams each row into a target table via the `tabledata.insertAll` API, with per-row insertId dedup.
+Supply **Project ID**, **Dataset ID**, **Table ID**, and a **Service account JSON key**. Domain-scoped project IDs such as `example.com:my-project` are accepted. The table must already exist with compatible columns for the source's top-level fields; rows are not wrapped in one JSON or STRING column. Sim sets `ignoreUnknownValues: false`.
+
+The account needs `roles/bigquery.dataEditor` for inserts and `roles/bigquery.metadataViewer` for the `tables.get` connection probe. Sim uses OAuth2 service-account JWT authentication and `tabledata.insertAll`.
 
-- **Project ID** — your GCP project (supports domain-scoped IDs like `example.com:my-project`).
-- **Dataset ID / Table ID** — must already exist; Sim does not create tables. The table schema must match the source row shape, with a compatible column for each top-level field. Sim sends those fields directly and sets `ignoreUnknownValues` to `false`; it does not wrap the row in a single JSON or STRING column.
-- **Service account JSON key** — needs `roles/bigquery.dataEditor` (insert) and `roles/bigquery.metadataViewer` (for the `tables.get` probe used by "Test connection"). Sim authenticates via OAuth2 service-account JWT.
+Each row's `insertId` uses `{drainId}-{runId}-{sequence}-{index}`; IDs exceeding 128 characters are hashed. BigQuery offers best-effort deduplication for repeated IDs for up to one minute, so duplicates remain possible during any retry. Partial `insertErrors` fail the chunk and report row indices; rows already accepted can be repeated. Deduplicate source IDs downstream. See [BigQuery streaming behavior](https://docs.cloud.google.com/bigquery/docs/write-api-rest).
 
-Each row is sent with an `insertId` of `{drainId}-{runId}-{sequence}-{index}`. BigQuery dedupes inserts with the same `insertId` for ~60 seconds, so retries inside that window won't duplicate. If a chunk reports partial failure (`insertErrors`), the run fails with the offending row indices and an outer-driver retry may duplicate rows that already succeeded — the dispatcher's bounded retry minimizes this risk. Enforced per-request limits: 10 MB body, 50,000 rows.
+Sim's request guards are **10 MiB and 50,000 rows**. The tighter source-record and chunk limits below normally apply first.
 
 ### Snowflake
 
-Inserts each row into a target VARIANT column via the Snowflake SQL API v2 with key-pair JWT auth.
+Supply **Account**, **User**, **Warehouse**, **Database**, **Schema**, **Table**, and an unencrypted PKCS8 RSA **Private key (PEM)**. Prefer `<orgname>-<acctname>`; legacy `<locator>.<region>.<cloud>` identifiers are also accepted. Register the matching public key on the user with `ALTER USER ... SET RSA_PUBLIC_KEY = '...'`.
 
-- **Account** — the Snowflake account identifier. Preferred form is `<orgname>-<acctname>` (no dots). Legacy `<locator>.<region>.<cloud>` is also accepted.
-- **User / Warehouse / Database / Schema / Table** — must already exist. The user needs `INSERT` privilege on the table and `USAGE` on the warehouse, database, and schema.
-- **Column** *(optional)* — target VARIANT column name. Defaults to `DATA` (matches Snowflake's unquoted identifier folding).
-- **Role** *(optional)* — Snowflake role to assume.
-- **Private key (PEM)** — PKCS8-encoded RSA private key. Register the matching public key on the Snowflake user via `ALTER USER ... SET RSA_PUBLIC_KEY = '...'`.
+The user needs `INSERT` on the existing table and `USAGE` on its warehouse, database, and schema. **Role** is optional. **Column** is an existing VARIANT column, defaulting to `DATA`.
 
-Each chunk becomes a single `INSERT INTO "DB"."SCHEMA"."TABLE" ("col") SELECT PARSE_JSON(column1) FROM VALUES (?), ...` with one TEXT binding per row. Identifiers are quoted to preserve case. The destination handles Snowflake's async 202-then-poll pattern transparently. Per-row JSON payloads are capped at 16 MB to match Snowflake's VARIANT limit.
+Sim uses key-pair JWT authentication and SQL API v2. Each chunk uses `INSERT INTO "DB"."SCHEMA"."TABLE" ("col") SELECT PARSE_JSON(column1) FROM VALUES (?), ...`, with one TEXT binding per row. Identifiers are quoted to preserve case. The runner polls asynchronous `202` responses. Sim guards destination JSON at 16 MiB per row; the source-record limit is the tighter 1 MiB. This is a Sim limit rather than a statement of Snowflake's current maximum.
 
 ### Datadog Logs
 
-POSTs each row as a log entry to Datadog's v2 logs intake.
+Choose **Site** from `us1`, `us3`, `us5`, `eu1`, `ap1`, `ap2`, or `gov`. Supply a logs-write **API key**, not an Application key. **Service** defaults to `sim`; optional **Tags** are comma-separated.
 
-- **Site** — your Datadog site: `us1`, `us3`, `us5`, `eu1`, `ap1`, `ap2`, or `gov`.
-- **Service** *(optional)* — value for the reserved `service` field. Defaults to `sim`.
-- **Tags** *(optional)* — comma-separated `ddtags` appended to every entry alongside auto-injected `sim_drain_id:`, `sim_run_id:`, and `sim_source:` tags.
-- **API key** — a Datadog API key (not an Application key) with logs-write permission.
+Sim posts to v2 logs intake, exposes top-level row fields as log attributes, and adds `sim_drain_id:`, `sim_run_id:`, and `sim_source:` tags. It sets the reserved `ddsource`, `service`, `ddtags`, and `message` fields, overriding source fields with those names.
 
-Top-level row fields are auto-indexed as Datadog log attributes. The reserved fields `ddsource`, `service`, `ddtags`, and `message` are always set by Sim and override anything in the row. Payloads above 1 KB are gzip-compressed. Enforced limits match Datadog's intake: 5 MB of uncompressed JSON per request, 1000 entries per request, and 1 MB per entry. Expanded log entries are split into bounded requests before compression.
+Expanded entries are split before compression. Requests are limited to **5,000,000 uncompressed bytes**, **1,000 entries**, and **1,000,000 bytes per entry**, with a defensive 6 MiB wire-size cap. Payloads larger than 1,024 bytes use gzip.
 
-### HTTPS Webhook
+### HTTPS webhook
 
-POSTs each chunk as NDJSON to your endpoint.
+Supply **URL**, **Signing secret**, optional **Bearer token**, and optional **Signature header name** (default `X-Sim-Signature`). On Sim Cloud, the URL must use HTTPS and resolve to public addresses. Self-hosted deployments apply their [outbound-network policy](/platform/self-hosting/security#the-ssrf-boundary): approved private endpoints and loopback are available, with HTTP only where that policy permits it. Sim blocks cloud-metadata addresses and pins the resolved address for the run to prevent DNS rebinding.
 
-- **URL** — must be HTTPS. Sim resolves the hostname and refuses to deliver to private, loopback, or cloud-metadata IPs. The resolved IP is pinned for the duration of a run to prevent DNS rebinding.
-- **Signing secret** — shared secret used for HMAC-SHA256 signing.
-- **Bearer token** *(optional)* — sent as `Authorization: Bearer <token>`.
-- **Signature header name** *(optional)* — defaults to `X-Sim-Signature`.
+Each chunk includes:
 
-Each request includes:
-
-```
+```http
 Content-Type: application/x-ndjson
 User-Agent: Sim-DataDrain/1.0
 X-Sim-Timestamp: <unix-seconds>
 X-Sim-Signature-Version: v1
-X-Sim-Signature: t=<unix-seconds>,v1=<hex(hmac-sha256)>
-X-Sim-Drain-Id: <drain id>
-X-Sim-Run-Id: <run id>
-X-Sim-Source: <source name>
-X-Sim-Sequence: <chunk index>
-X-Sim-Row-Count: <rows in this chunk>
+X-Sim-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>
+X-Sim-Drain-Id: <drain-id>
+X-Sim-Run-Id: <run-id>
+X-Sim-Source: <source-wire-value>
+X-Sim-Sequence: <zero-based-chunk-index>
+X-Sim-Row-Count: <row-count>
 Idempotency-Key: <runId>-<sequence>
 ```
 
-The signature is computed as `HMAC-SHA256(secret, "${timestamp}.${body}")` and serialized as `t=<timestamp>,v1=<hex>`. Verify by recomputing over the same string and rejecting timestamps older than ~5 minutes — this defends against captured-request replay attacks.
+Sim signs the exact string `${timestamp}.${body}` with HMAC-SHA256 and the signing secret. Recompute using the original request body and reject old timestamps—for example, those older than five minutes—to limit replay. A bearer token, when configured, is sent as `Authorization: Bearer <token>`.
 
-Failed deliveries retry up to 3 times with exponential backoff (500ms, 1s, 2s with ±20% jitter), respecting `Retry-After` on 429/503. Non-retryable 4xx responses fail the run immediately.
+Delivery retries up to three times after the initial attempt: 500 ms, 1 s, and 2 s with ±20% jitter. `Retry-After` is respected on `429` and `503`; non-retryable `4xx` responses fail immediately.
 
----
+## Checkpoints, bounds, and failures
 
-## Schedule
+An opaque cursor advances only after acknowledged delivery. Later failures resume after the last acknowledged chunk, but a crash between remote acceptance and checkpointing can replay data. A database claim prevents overlapping runs for one drain and fences stale workers.
 
-| Cadence | Drain runs |
-|---|---|
-| **Hourly** | Once per hour. |
-| **Daily** | Once per day. |
+| Bound | Limit |
+| --- | --- |
+| Database page | 100 rows |
+| Source record, transcript, or execution archive before materialization | 1 MiB |
+| NDJSON chunk | 4 MiB |
+| One run | 100 chunks, 10,000 rows, or 100 MiB |
+| Work window / hard deadline | 20 minutes / 25 minutes |
 
-You can also disable a drain with the **Enabled** toggle (it stops running but is preserved), or trigger an out-of-schedule run with **Run now** on any drain row.
+A queued run that reaches its work window schedules continuation. Oversized records and missing execution archives fail visibly without advancing past the incomplete record.
 
----
+The webhook idempotency key covers retries of one chunk within one run. A later replay has a new run ID; partially accepted destination requests can also repeat rows. Keep source-ID deduplication even when the destination offers its own deduplication.
 
-## Delivery semantics
+## Pair with data retention
 
-Drains use an **opaque cursor** that checkpoints each acknowledged chunk. If a later chunk fails, the next run resumes after the last acknowledged checkpoint. A crash between remote delivery and checkpointing can replay a chunk.
+<Callout type="warn">
+Retention does not wait for a drain. Failed delivery or backlog can let cleanup delete records before export. Set a cadence shorter than the retention window and monitor recent runs, progress, and destination receipt.
+</Callout>
 
-A database claim prevents overlapping runs for the same drain and fences stale workers. Each run is bounded to 10,000 rows, 100 chunks, 100 MB of NDJSON, and a 20-minute work window, with a 25-minute hard deadline. A queued run that reaches a window limit schedules a continuation. Chunks are capped at 4 MB; individual database records, chat transcripts, and execution archives are capped at 1 MB before materialization. Oversized records fail visibly without advancing past them. Missing execution archives also fail rather than reporting an incomplete record as delivered.
+| Source | Retention category |
+| --- | --- |
+| Workflow logs and Job logs | Log retention |
+| Chats and Chat runs | Task cleanup |
+| Audit logs | No age-based audit-retention setting currently |
 
-This is **at-least-once delivery**. Deduplicate by the source row’s `id`. The webhook `Idempotency-Key` protects retries of a chunk within one run; a replay in a later run has a new run ID. A destination that partially accepts a request may also repeat previously accepted rows on retry.
+For a 30-day log window, **Every hour** or **Every day** provides opportunities to export before expiry; cadence alone does not guarantee every row arrives. Source deletion, workspace scope changes, late commits, and persistent failures can still leave gaps.
 
-The **last 10 runs** for each drain are visible by expanding its row in the settings page, with status, row count, bytes written, destination locator (`s3://...` or webhook URL), and the error message if it failed.
+Your destination owns exported data lifecycle and erasure after delivery. Sim does not remove external objects when source data or a drain is deleted.
 
----
+## Rotate credentials or delete a drain
 
-## Security
+Destination credentials are encrypted at rest using key-rotation-aware encryption and are not returned by API reads. An API update can supply a complete replacement credential payload; omitting credentials preserves the stored secret. Source and destination type cannot be changed on an existing drain.
 
-- Destination credentials are encrypted at rest using the same key-rotation–aware encryption that protects OAuth tokens.
-- Credentials are **never** returned by the Sim API after creation. Updates accept new credentials; omitting them leaves the existing encrypted blob in place.
-- Webhook URLs and the final S3 SDK hostname are SSRF-validated with the resolved IP pinned to the connection. Private, loopback, and metadata IPs are rejected. S3 signed request paths are preserved without following redirects. A configured outbound gateway that cannot preserve signed request targets fails closed.
-- Every create, update, delete, manual run, and test-connection call is recorded in the [Audit Log](/platform/enterprise/audit-logs).
-
----
+The current settings detail page edits **Enabled** only. Changing credentials there requires recreating the drain, which starts retained-history backfill again and can duplicate archived data. Use a supported API credential replacement when cursor continuity matters; do not delete the existing drain merely to rotate a key.
 
-## Pairing with Data Retention
-
-Drains and [Data Retention](/platform/enterprise/data-retention) are independent modules. Sim does **not** gate retention on drain progress — if a drain is failing, retention will still purge data on its own schedule. Keep the two configurations independent and pair them deliberately.
-
-To safely use both together, set the drain cadence shorter than the retention period for the same data category:
-
-| Drain source | Pairs with retention setting |
-|---|---|
-| Workflow logs, Job logs | **Log retention** |
-| Chats, Chat runs | **Task cleanup** |
-| Audit logs | *(no retention setting today — audit logs are kept indefinitely)* |
-
-For example, with **Log retention** set to 30 days, set the workflow-logs drain to **Hourly** or **Daily** so every row is exported well before retention purges it from Sim. Monitor recent drain runs in the settings page; if a drain has been failing for longer than your retention window, you may lose rows that retention purges before they are exported.
-
-After data lands in your bucket or webhook system, archive lifecycle (transitions to Glacier, expiration, GDPR right-to-erasure propagation) is governed by your own infrastructure — Sim has no further visibility into that data once delivery succeeds.
-
----
-
-<FAQ items={[
-  {
-    question: "Who can configure data drains?",
-    answer: "Only organization owners and admins can view, create, edit, run, or delete drains. On Sim Cloud, the organization must be on an Enterprise plan."
-  },
-  {
-    question: "Can I export multiple sources to the same destination?",
-    answer: "Yes — create one drain per source, all pointing at the same bucket or endpoint. S3 destinations namespace by source automatically; webhook receivers can branch on the `X-Sim-Source` header."
-  },
-  {
-    question: "Does deleting a drain delete the data already exported?",
-    answer: "No. Deletion only removes the drain's configuration and its run history from Sim. Data already written to your bucket or sent to your webhook is yours and is unaffected."
-  },
-  {
-    question: "What happens if my credentials stop working mid-run?",
-    answer: "The run fails and is recorded with the error. Already acknowledged chunks retain their checkpoints. Once you update the credentials, the next run resumes from the last acknowledged position; an uncheckpointed delivery may be repeated."
-  },
-  {
-    question: "What format is the data in?",
-    answer: "Object-storage and webhook destinations receive NDJSON, one row per line. BigQuery, Snowflake, and Datadog use the destination-specific payloads described above."
-  }
-]} />
-
----
+**Delete** removes configuration and run history, without deleting exported bytes. Create, update, delete, manual-run, and connection-test actions emit best-effort [audit events](/platform/enterprise/audit-logs).
 
 ## Self-hosted setup
 
-### Environment variables
+Enable the feature through enterprise configuration or explicitly set:
 
 ```bash
 DATA_DRAINS_ENABLED=true
 NEXT_PUBLIC_DATA_DRAINS_ENABLED=true
 ```
 
-On a self-hosted deployment the feature resolves on when `DATA_DRAINS_ENABLED` is `true`, or when it is unset and `ENTERPRISE_ENABLED` is `true`. An explicit `DATA_DRAINS_ENABLED=false` wins over the master switch. That resolved value — not the bare variable — gates the **Settings → Organization → Data drains** page, the server-side mutating endpoints, and the cron dispatcher. When it resolves off the page is hidden, drain create/update/delete/run requests return `404`, and the dispatcher is a no-op.
+An explicit feature value takes precedence over `ENTERPRISE_ENABLED`. When disabled, the page is hidden, mutating drain requests return `404`, and the dispatcher does no work. Billing-enabled deployments retain the Enterprise gate. Keep server and public feature configuration aligned; `bunx sim-setup doctor` checks the pair. See [self-hosted enterprise setup](/platform/enterprise/self-hosted).
 
-Inside a workspace the browser reads that resolved value from the server, so the page follows the server whether or not `NEXT_PUBLIC_DATA_DRAINS_ENABLED` is set. Set it to the same value anyway: it backs the client fallback on surfaces rendered outside a workspace, and on a Compose install or source checkout `npx sim-setup doctor` reports the pair disagreeing.
-
-### Scheduling the dispatcher
-
-The dispatcher is an HTTP endpoint, not a self-scheduling job — something has to call it:
-
-```
-GET /api/cron/run-data-drains
-```
-
-It authenticates with a bearer token equal to `CRON_SECRET` and returns `401` when that variable is unset, so a self-hosted deployment must set it:
+The dispatcher requires scheduled calls to `GET /api/cron/run-data-drains`. Set the same `CRON_SECRET` on the app and its caller; the endpoint returns `401` when it is unset. Generate a secret if needed, then install it in both configurations:
 
 ```bash
 openssl rand -hex 32
 ```
 
-Set the same value as `CRON_SECRET` on both the app and whatever invokes the endpoint. Generating it in your shell does not configure either one.
-
-Both shipped deployments schedule this endpoint hourly for you — Helm through `cronjobs.jobs.runDataDrains`, Docker Compose through its `cron` service. A deployment that runs neither schedules it itself:
+Helm's `cronjobs.jobs.runDataDrains` and Docker Compose's `cron` service call it hourly when their schedulers are enabled. If neither runs, configure an external scheduler:
 
 ```bash
-curl -H "Authorization: Bearer $CRON_SECRET" \
+curl --fail-with-body \
+  -H "Authorization: Bearer $CRON_SECRET" \
   https://sim.example.com/api/cron/run-data-drains
 ```
 
-Each due drain is dispatched as a `run-data-drain` background job. With Trigger.dev enabled, it runs in the configured Trigger.dev project. Otherwise the database queue executes the registered drain runner. Per-drain database claims apply in both modes. The database fallback limits active drain jobs to two per app process; Trigger.dev workers use serialized per-drain jobs. See [background jobs](/platform/self-hosting/background-jobs).
+Trigger.dev is optional. The database backend executes the registered runner with at most two active drain jobs per app process; Trigger.dev uses serialized per-drain jobs. Database claims apply in both modes. Verify scheduler calls and actual destination receipt after enabling the feature.
+
+## Related docs
+
+- [Data retention](/platform/enterprise/data-retention)
+- [Audit logs](/platform/enterprise/audit-logs)
+- [Background jobs](/platform/self-hosting/background-jobs)
diff --git a/apps/docs/content/docs/platform/enterprise/data-retention.mdx b/apps/docs/content/docs/platform/enterprise/data-retention.mdx
index 4b57215fced..67f58f4a62d 100644
--- a/apps/docs/content/docs/platform/enterprise/data-retention.mdx
+++ b/apps/docs/content/docs/platform/enterprise/data-retention.mdx
@@ -1,233 +1,172 @@
 ---
-title: Data Retention
-description: Control how long execution logs, deleted resources, and Chat data are kept before permanent deletion — and redact PII from workflow data
+title: Data retention
+description: Configure cleanup periods and PII redaction for your organization's workspace data
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { FAQ } from '@/components/ui/faq'
 import { Image } from '@/components/ui/image'
 
-Data Retention lets organization owners and admins on Enterprise plans control two things:
+Data retention controls age-based cleanup of logs, deleted resources, Chat data, and previous file versions. The same policy can redact PII in workflow inputs, block outputs, or persisted logs.
 
-1. **Retention periods** — how long execution logs, soft-deleted resources, and Chat data are kept before they are permanently deleted.
-2. **PII redaction** — masking personally identifiable information out of your workflow data at up to three points: workflow input, block outputs, and logs.
+Organization owners and admins set the organization policy and workspace overrides. Billing-enabled deployments require Enterprise to configure these policies. Billing-disabled deployments can configure them; applying cleanup also requires the feature and a scheduler. See [self-hosted setup](#self-hosted-setup).
 
-Both are configured once at the **organization level** and apply to every workspace, with optional **per-workspace overrides** for workspaces that need different rules.
-
----
+## Defaults
 
-## Setup
+Cloud plan defaults apply when no configurable policy takes precedence:
 
-Go to **Settings → Organization → Data retention** in your workspace.
+| Deployment or plan | Execution/job logs | Soft-deleted resources | Chat task cleanup | Previous file versions |
+| --- | --- | --- | --- | --- |
+| Free Cloud | 30 days | 30 days | No default age expiry | 30 days |
+| Pro or Max Cloud, including Teams | No default age expiry | 90 days | No default age expiry | 180 days |
+| Enterprise | No default age expiry | No default age expiry | No default age expiry | No default age expiry |
+| Billing-disabled self-hosting | No plan-based age expiry | No plan-based age expiry | No plan-based age expiry | No plan-based age expiry |
 
-<Image src="/static/enterprise/data-retention.png" alt="Data Retention settings showing the Retention policies list with the Organization default row and its summary of retention periods and PII stages" width={900} height={537} />
+Enterprise and billing-disabled deployments retain data without an age-based expiry until configured otherwise. This does not prevent manual deletion, storage cleanup, or the file-version count limits below. PII redaction is off until a stored policy enables a stage and selects entities or patterns.
 
-The page shows your **retention policies** as a list:
+## Configure a policy
 
-- The **Organization** row (tagged *Default*) holds the settings that apply to every workspace without its own override.
-- Each **workspace override** row below it applies to one or more specific workspaces.
+1. Open **Settings → Organization → Data retention**.
+2. Open the **Organization** default row, or choose **Add override** for selected workspaces.
+3. Choose retention periods and any PII stages, entities, languages, and custom patterns.
+4. Save the policy and verify its summary in the policy list.
 
-Open a row to edit it, or click **Add override** to create a workspace override. Each policy has a **Retention** section, and — when PII redaction is enabled — a **PII redaction** section.
+The three UI retention fields offer **1 day**, **3 days**, **7 days**, **14 days**, **30 days**, **60 days**, **90 days**, **180 days**, **1 year**, **5 years**, or **Forever**. One year is 365 days and five years is 1,825 days. The API accepts integer hours from 24 to 43,800, or `null` for Forever.
 
----
+<Callout type="warn">
+Shortening a retention period makes older data eligible for permanent deletion on the next successful cleanup passes. Once removed, that data cannot be recovered by restoring the old policy.
+</Callout>
 
-## Retention periods
+Cleanup runs in bounded scheduled passes rather than at the exact expiry time. **Forever** disables age-based deletion for that category; it does not remove count caps or undo a manual deletion.
 
-Each policy has three independent retention settings, each with the same set of options: **1 day, 3 days, 7 days, 14 days, 30 days, 60 days, 90 days, 180 days, 1 year, 5 years,** or **Forever**.
+### Workspace overrides
 
-Setting a period to **Forever** means that category of data is never automatically deleted. On a workspace override, each field can also be set to **Inherit from organization** to fall back to the organization default for just that field.
+An override can target one or more workspaces, and a workspace can belong to only one override. Each retention field can **Inherit from organization** independently or set a period, including Forever. An omitted API field inherits; `null` explicitly disables age expiry.
 
-### Log retention
+PII settings use **Inherit** or **Override** for the whole policy. Override replaces the organization's redaction policy for that workspace; stages are not merged. Removing an override restores organization defaults.
 
-Controls how long **execution logs** are kept.
+<Image src="/static/enterprise/data-retention-override.png" alt="Workspace override with Log retention set to 30 days, other retention fields inherited, and a PII Inherit or Override choice" width={900} height={537} />
 
-When the retention period expires, log records are permanently deleted, along with any files associated with those executions in cloud storage. This covers:
+## What each retention field removes
 
-- Workflow execution logs
-- Background job logs (deployed APIs, schedules, and webhooks)
+### Log retention
 
-### Soft deletion cleanup
+Cleans workflow execution logs and background job logs for deployed APIs, schedules, and webhooks, based on `startedAt`. Related execution files are also scheduled for storage cleanup; logical record deletion does not guarantee immediate physical removal of every object.
 
-Controls how long **soft-deleted resources** remain recoverable before permanent removal.
+Logs and referenced files for an active paused execution are protected while that execution still has live paused state. They become eligible after that protection ends and the retention window applies.
 
-When you delete a workflow, folder, knowledge base, table, or file, it is initially soft-deleted and can be recovered from Recently Deleted. Once the soft deletion cleanup period expires, those resources are permanently removed and cannot be recovered.
+### Soft deletion cleanup
 
-Resources covered:
+Permanently removes resources that have remained soft-deleted beyond the window:
 
-- Workflows
-- Workflow folders
-- Knowledge bases (and their documents)
-- Tables
-- Files
+- Workflows and workflow folders
+- Knowledge bases and their documents
+- Tables and files
 - MCP server configurations
 - Agent memory
 - Chat conversations
 
-### Task cleanup
+Recover supported resources through Recently Deleted before cleanup removes them. Not every stored resource in this list has a corresponding recovery action in that interface. Permanent cleanup cannot be undone.
 
-Controls how long **Chat data** is kept, including:
+### Task cleanup
 
-- Chat conversations and run history
-- Run checkpoints and async tool calls
-- Inbox tasks
+Removes old Chat conversations, run history, checkpoints, async tool calls, and inbox tasks. Chat conversations and runs use their last update time; inbox tasks use creation time. This is separate from execution-log retention and soft-deletion cleanup.
 
 ### Previous file versions
 
-Every change to a file's content keeps the previous content as a version you can read or revert to through the API, CLI, or MCP server. This setting controls how long a version is kept after a newer one replaces it. The newest ten versions of each file are always kept, whatever their age.
-
-Without a setting, previous versions are kept until a file reaches 500 of them. The setting isn't on the settings page yet: set `fileVersionRetentionHours` through the data retention API, either for the organization or in a workspace override.
+`fileVersionRetentionHours` is available through the data-retention API, including workspace overrides; it is not yet a settings-page field. Read or revert versions through the [Files API](/api-reference/files/listFileVersions), [CLI](/cli/files), or MCP.
 
-Each setting is independent. You can configure a short log retention period alongside a long soft deletion cleanup period, or any combination that fits your compliance requirements.
-
----
+File edits can coalesce into an editing session rather than create a version for every keystroke. Sessions have a ten-minute window and five-minute idle threshold. Age cleanup protects the current version and nine newest previous versions, regardless of age. Superseded versions also have a 500-version ceiling; Free cleanup keeps at most 99 previous versions. Forever prevents age expiry but does not remove that ceiling.
 
 ## PII redaction
 
-When PII redaction is enabled for your organization, each policy gains a **PII redaction** section that masks personally identifiable information — names, emails, phone numbers, credit-card numbers, national IDs, and more — from your workflow data. Sim detects and masks PII with [Microsoft Presidio](https://microsoft.github.io/presidio/); each match is replaced with a placeholder token such as `<EMAIL_ADDRESS>`.
+A stored policy must enable a redaction stage and select entity types or custom patterns. A reachable `PII_URL` alone does not enable redaction. Matches are replaced with tokens such as `<EMAIL_ADDRESS>` using the Presidio service.
 
-Redaction is configured per **stage** — the point in a run where masking is applied. Select a stage, then choose which entity types and custom patterns to redact for it:
+| Stage | Effect |
+| --- | --- |
+| **Logs** | Masks workflow data as logs are persisted. Execution uses the original data. |
+| **Workflow input** | Masks inputs before execution, so the workflow computes on masked values. |
+| **Block outputs** | Masks outputs before downstream blocks consume them. |
 
-| Stage | What it does |
-|---|---|
-| **Logs** | Redacts workflow logs when they are persisted. Observability-only — the workflow still runs on the original data. |
-| **Workflow input** | Redacts the workflow input **before execution**. The workflow runs on the masked data, which may change its output. |
-| **Block outputs** | Masks every block output **before the next block reads it**. Runs in-flight and may change output and execution performance. |
-
-<Image src="/static/enterprise/data-retention-pii.png" alt="PII redaction section with the Block outputs stage selected, showing the entity type grid grouped by Common, United States, United Kingdom, and Other regions" width={900} height={537} />
+<Image src="/static/enterprise/data-retention-pii.png" alt="PII redaction controls with Block outputs selected and entity types grouped by region" width={900} height={537} />
 
 <Callout type="warn">
-The **Workflow input** and **Block outputs** stages alter what the workflow computes on, not just what is stored. Redacted data is masked during the run and may affect workflow output. Enable them only where that trade-off is acceptable.
+Workflow input and Block outputs redaction alter computation. Test affected workflows with representative values before applying these stages: masking can change outputs and add execution latency.
 </Callout>
 
-### Entity types and language
+### Entity types and languages
 
-For each stage, choose the **entity types** to redact from the searchable grid. They are grouped as:
+Choose entities separately for each stage:
 
-- **Common** — person name, email, phone, credit card, IP address, location, date or time, URL, IBAN, crypto wallet, nationality/religious/political group, medical license, VIN
-- **United States** — SSN, passport, driver's license, bank account, ITIN
-- **United Kingdom** — NHS number, National Insurance number
-- **Other regions** — Spanish (NIF, NIE), Italian (fiscal code, driver's licence, VAT code, passport, identity card), Polish (PESEL), Singaporean (NRIC/FIN, UEN), Australian (ABN, ACN, TFN, Medicare), Indian (PAN, Aadhaar, vehicle registration, voter ID, passport), and Finnish (personal identity code) identifiers
+| Group | Available entity families |
+| --- | --- |
+| Common | Person name, email, phone, credit card, IP address, location, date/time, URL, IBAN, crypto wallet, nationality/religious/political group, medical license, VIN |
+| United States | SSN, passport, driver's license, bank account, ITIN |
+| United Kingdom | NHS number, National Insurance number |
+| Other regions | Spanish NIF/NIE; Italian fiscal code, driver's licence, VAT code, passport, identity card; Polish PESEL; Singaporean NRIC/FIN and UEN; Australian ABN, ACN, TFN, Medicare; Indian PAN, Aadhaar, vehicle registration, voter ID, passport; Finnish personal identity code |
 
-The **Block outputs** stage is restricted to regex- and checksum-based recognizers, to support in-flight masking without name-model detection. Types that need name-model detection — person name, location, date or time, and nationality/religious/political group — are not offered for that stage.
+English, Spanish, Italian, Polish, and Finnish are supported. The selected language filters which recognizers and identifiers are available.
 
-Detection is language-aware: pick the **language** whose recognizers should apply. English, Spanish, Italian, Polish, and Finnish are supported, and the grid filters to the identifiers available for the selected language.
-
-<Callout type="warn">
-Some recognizers match loosely and over-redact — US Social Security Number, US bank account number, and Date or time have no checksum and match aggressively. Enable these only where false positives are acceptable.
-</Callout>
+**Block outputs** supports regex- and checksum-based recognizers only. It does not offer person name, location, date/time, or nationality/religious/political group detection that depends on name models. SSN, US bank-account, and date/time recognizers can match loosely without a checksum; enable them where false positives are acceptable.
 
 ### Custom patterns
 
-Beyond the built-in entity types, each stage can redact anything a **regular expression** matches — employee IDs, internal URLs, ticket numbers. Give each pattern a name, a regex, and a replacement token; every match is replaced with the replacement text wrapped in angle brackets (e.g. `EMPLOYEE_ID` → `<EMPLOYEE_ID>`).
-
----
-
-## Per-workspace overrides
-
-Retention and PII redaction are configured at the **organization level** and apply to every workspace by default. When a workspace needs different rules, add a **workspace override**.
-
-<Image src="/static/enterprise/data-retention-override.png" alt="Add workspace override panel showing the workspace picker, retention fields set to Inherit from organization, and the PII redaction Inherit or Override switch" width={900} height={537} />
-
-- An override targets one or more workspaces (a workspace can belong to only one override).
-- Each **retention** field either sets its own period or **inherits** the organization value.
-- **PII redaction** on an override is either **Inherit** (use the organization's redaction) or **Override** (workspace-specific). Choosing Override replaces the organization's redaction rules entirely for that workspace — it is not merged stage-by-stage.
-
-Removing an override returns its workspaces to the organization defaults.
-
----
-
-## Defaults
+Add up to 20 patterns per stage. Each has a name, regular expression, and replacement text. For example, replacement `EMPLOYEE_ID` produces `<EMPLOYEE_ID>` for each match. Use patterns for identifiers such as employee IDs, internal URLs, or ticket numbers.
 
-By default, retention settings are unconfigured — no data is automatically deleted in any category, and no PII is redacted, until you configure it. Setting a retention period to **Forever** has the same effect as leaving it unconfigured, but makes the intent explicit and lets you change it later without configuring from scratch.
+### Scope and failures
 
----
-
-<FAQ items={[
-  {
-    question: "Who can configure data retention settings?",
-    answer: "Only organization owners and admins can configure data retention settings. On Sim Cloud, the organization must be on an Enterprise plan."
-  },
-  {
-    question: "Is deletion immediate once the retention period expires?",
-    answer: "No. Deletion runs on a scheduled cleanup job. Data is deleted when the job next runs after the retention period has elapsed — not at the exact moment it expires."
-  },
-  {
-    question: "Can deleted data be recovered after the soft deletion cleanup period?",
-    answer: "No. Once the soft deletion cleanup period expires and the cleanup job runs, resources are permanently deleted and cannot be recovered."
-  },
-  {
-    question: "Does a policy apply to all workspaces?",
-    answer: "The organization policy applies to every workspace that does not have its own override. Add a per-workspace override to give specific workspaces different retention periods or PII redaction rules."
-  },
-  {
-    question: "What happens if I shorten the retention period?",
-    answer: "The next cleanup job will delete any data that is older than the new, shorter period — including data that would have been kept under the previous setting. Shortening the period is irreversible for data that falls outside the new window."
-  },
-  {
-    question: "Does PII redaction change how my workflows run?",
-    answer: "The Logs stage does not — it only masks data as it is persisted, so the workflow runs on the original data. The Workflow input and Block outputs stages do: they mask data in-flight, so the workflow computes on the redacted values, which can change its output."
-  },
-  {
-    question: "What is the minimum retention period?",
-    answer: "1 day (24 hours)."
-  },
-  {
-    question: "What is the maximum retention period?",
-    answer: "5 years, or Forever — the same option list applies to all three settings."
-  }
-]} />
+Redaction applies to text strings at the configured workflow stages. It does not retroactively sanitize retained history, inspect every binary file, or intercept every arbitrary outbound request. Detection can miss PII or mask unrelated text; review the selected recognizers and patterns against your data.
 
----
+If log redaction fails, affected strings are replaced with `[REDACTION_FAILED]` rather than stored unmasked. Failure at Workflow input or Block outputs stops the run instead of passing unredacted values downstream.
 
 ## Self-hosted setup
 
-### Retention periods
+### Enable cleanup and schedule it
+
+On billing-disabled deployments, enable retention through enterprise configuration or explicitly set:
 
 ```bash
-NEXT_PUBLIC_DATA_RETENTION_ENABLED=true
 DATA_RETENTION_ENABLED=true
+NEXT_PUBLIC_DATA_RETENTION_ENABLED=true
 ```
 
-Once enabled, retention settings are configurable through **Settings → Organization → Data retention** the same way as Sim Cloud.
-
-### Scheduling the deletion pass
+An explicit feature value takes precedence over the enterprise master configuration. No plan-based default window is introduced: configure the windows you intend to apply.
 
-`DATA_RETENTION_ENABLED` permits deletion; it does not perform it. Deletion runs when a scheduled request reaches one of four endpoints, each authenticated with a bearer token equal to `CRON_SECRET`:
+Deletion requires all three: an enabled feature, an effective retention period, and a scheduled authenticated request. Set `CRON_SECRET` on the app and use the same secret on the scheduler.
 
 | Category | Endpoint |
-|----------|----------|
+| --- | --- |
 | Execution and job logs | `GET /api/logs/cleanup` |
 | Soft-deleted resources | `GET /api/cron/cleanup-soft-deletes` |
-| Chats and Chat runs | `GET /api/cron/cleanup-tasks` |
+| Chat data and runs | `GET /api/cron/cleanup-tasks` |
 | Previous file versions | `GET /api/cron/cleanup-file-versions` |
 
 <Callout type="warn">
-Neither shipped deployment schedules these four endpoints — not the Helm chart, not Docker Compose's `cron` service. An operator who sets `DATA_RETENTION_ENABLED=true` alone still deletes nothing. Add them to `cronjobs.jobs`, or call them daily from an external scheduler.
+The shipped Helm and Docker Compose schedules omit these four endpoints. Add calls through Helm's `cronjobs.jobs` or an external scheduler; enabling the feature alone performs no deletion.
 </Callout>
 
 ```bash
-# Use the value already configured as CRON_SECRET on the app — a token
-# generated here and not installed there returns 401.
-curl -H "Authorization: Bearer $CRON_SECRET" \
+curl --fail-with-body \
+  -H "Authorization: Bearer $CRON_SECRET" \
   https://sim.example.com/api/logs/cleanup
 ```
 
-Each call fans the work out as background jobs. Trigger.dev is not required: when it is not configured the dispatcher runs the cleanup chunks inline instead of enqueuing them, so deletion completes on a default self-host.
+Use the secret already configured on the app. A newly generated token that was not installed there returns `401`. Schedule each category you use, then check cleanup results. Trigger.dev is optional: without it, the dispatcher runs bounded cleanup chunks inline. A successful request is not a guarantee that all eligible stored bytes disappeared in one pass.
 
-### PII redaction
+### Deploy the PII service
 
-PII redaction runs against a standalone [Presidio](https://microsoft.github.io/presidio/) service. Deploy it (see `apps/pii`) and point Sim at it:
+Deploy `apps/pii`, which exposes `/analyze` and `/anonymize`, and set its reachable URL:
 
 ```bash
-# The Presidio service exposing /analyze and /anonymize
-# Helm — setting pii.enabled wires this for you, and a manual value is then
-# ignored. Set it by hand only for an external Presidio with pii.enabled:
-# false. The bundled Service is <release>-sim-pii, or <release>-pii when the
-# release name already contains "sim".
-PII_URL=http://<service>.<namespace>.svc.cluster.local:5001
-# Docker Compose — no shipped file defines a PII service. Add one to the
-# same project, then use its service name.
-# PII_URL=http://pii:5001
+PII_URL=http://pii:5001
 ```
 
-All PII stages are configurable under **Settings → Organization → Data retention**.
+On Helm, `pii.enabled` deploys and wires the bundled service automatically; a manual `PII_URL` is ignored while it is enabled. For an external service, set `pii.enabled: false` and supply `PII_URL`. The bundled service is `<release>-sim-pii`, or `<release>-pii` when the release name already contains `sim`.
+
+Docker Compose does not ship a PII service. Add one to the project or point to a reachable external service. After verifying service access, save a policy with enabled stages and selected entities or patterns under **Data retention**.
+
+## Related docs
+
+- [Data drains](/platform/enterprise/data-drains)
+- [Files](/files)
+- [Execution logs](/logs-debugging/logging)
+- [Self-hosted enterprise setup](/platform/enterprise/self-hosted)
diff --git a/apps/docs/content/docs/platform/enterprise/forks.mdx b/apps/docs/content/docs/platform/enterprise/forks.mdx
index c33c941c936..a12c77c1517 100644
--- a/apps/docs/content/docs/platform/enterprise/forks.mdx
+++ b/apps/docs/content/docs/platform/enterprise/forks.mdx
@@ -1,416 +1,201 @@
 ---
-title: Workspace Forks
-description: Clone a workspace, keep it linked to its parent, and push or pull deployed workflow changes
+title: Workspace forks
+description: Create a linked workspace and push or pull deployed workflow changes between environments
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { FAQ } from '@/components/ui/faq'
 import { Image } from '@/components/ui/image'
 
-Workspace Forks let you clone a workspace into a child, keep the two linked, and move **deployed** workflow changes between them later. Think of **Deploy** as a git commit: only what you have deployed is what Forks can copy or sync. **Sync** is always a force push or force pull — the target side is overwritten for the workflows in the sync. There is no merge UI.
+A fork creates a child workspace linked to its source. Later, push or pull deployed workflow changes across that direct parent–child relationship. One workspace has at most one parent, and a parent can have many children. Siblings and grandparents cannot sync directly.
 
-One workspace has at most one parent. A parent can have many children. You can only sync along a **direct** parent↔child edge — not with a grandparent or sibling.
+Only deployed, synced workflows move. Sync replaces eligible target workflows rather than merging their editor changes. Target-native workflows and excluded workflows remain outside the sync.
 
----
-
-## Who can use Forks
+## Availability and permissions
 
-| Requirement | Detail |
-|-------------|--------|
-| **Plan** | Enterprise on Sim Cloud |
-| **Role** | Workspace **admin** — non-admins never see the Forks tab |
-| **Self-hosted** | Set `FORKING_ENABLED` / `NEXT_PUBLIC_FORKING_ENABLED` (see [Self-hosted setup](#self-hosted-setup)) |
+Billing-enabled deployments require Enterprise, including when self-hosted. Billing-disabled deployments require forking enabled in the deployment feature configuration; see [Self-hosted setup](#self-hosted-setup). Workspace-creation policies and storage/resource limits still apply.
 
-On Sim Cloud, your organization may also need the feature turned on for your account before the tab appears.
-
----
+| Action | Required access |
+| --- | --- |
+| View forks or create a child | Admin of the source/current workspace. |
+| Sync or edit mappings | Admin of both workspaces on the direct edge. |
+| Change a workflow's sync checkbox | Admin of that workflow's workspace. |
+| Change the new-workflow default | Admin of any workspace in the lineage. |
+| Roll back | Admin of the target that received the sync. |
+| Disconnect | Admin of the acting side; other-workspace membership is not required. |
+| Open the other workspace | Membership in that workspace. |
 
-## Setup
+## Create a fork
 
-### 1. Open Forks
+1. Open **Settings → Workspace → Workspace forks** in the source.
+2. Click **Create fork** and name the child. The default is `{workspace} (fork)`.
+3. Review **Copy resources**. Resources start selected; deselect only those you intend to reconnect or replace.
+4. Review the cleared-reference warning and click **Fork**.
+5. Open the child, configure credentials and secrets, and check **Activity** for background-copy results. Deploy its workflows when they are ready.
 
-Go to **Settings → Workspace → Workspace forks** in the workspace you want to fork from (or manage).
+<Image src="/static/enterprise/forks-create-warning.png" alt="Fork dialog warning that deselected resources clear references in copied workflows" width={900} height={953} className="mx-auto h-auto w-full max-w-md" />
 
-<Image src="/static/enterprise/forks-list.png" alt="Workspace Forks settings page showing Parent and Forks sections with Docs, See activity, and Create fork actions" width={900} height={369} />
+Deployed workflows arrive as drafts. Undeployed workflows and uncommitted drafts stay in the source. If no eligible workflow is copied, the child receives a blank starter workflow. Deselecting a referenced resource clears the corresponding child fields.
 
-You will see:
+The child stays in the source's organization and Project, inherits workspace mode and personal-key policy, and receives a snapshot of workspace memberships and roles, including external members. The creator becomes a child admin. Later membership changes do not sync automatically.
 
-- **Parent** — if this workspace was forked from another
-- **Forks** — children of this workspace
-- **See activity** — history of forks, syncs, and rollbacks
-- **Create fork** — start a new child
+Workspace-specific permission-group scopes and retention overrides are not copied onto the new workspace; organization fallback policies still apply. Table rows, knowledge documents, and file contents can continue copying after workspace creation. A created workspace is not proof that every copy finished.
 
-### 2. Create a fork
+## Push or pull changes
 
-Click **Create fork**. Name the child (defaults to `{workspace} (fork)`), then review **Copy resources**.
+From the **child**, open **Settings → Workspace → Workspace forks**, open the **Parent** menu, and choose **Edit mappings**. Child rows on the parent offer **Open workspace** and **Disconnect**. Opening is disabled when you lack other-workspace access; disconnecting remains available to an admin on your side.
 
-<Image src="/static/enterprise/forks-create-modal.png" alt="Fork workspace modal with name field and Copy resources list fully selected" width={900} height={884} className="mx-auto h-auto w-full max-w-md" />
-
-Everything under **Copy resources** starts **selected**. That is usually what you want: tables, knowledge bases, files, custom tools, skills, and MCP servers the child will need.
-
-<Callout type="info">
-  If you deselect a resource, references to it in the forked workflows are **cleared** in the child. You will see a warning before you confirm.
-</Callout>
+### 1. Choose direction and review workflows
 
-<Image src="/static/enterprise/forks-create-warning.png" alt="Fork workspace modal showing a warning that deselected resources will clear references in the fork" width={900} height={953} className="mx-auto h-auto w-full max-w-md" />
+- **Push** sends this workspace's deployed workflows to the other workspace.
+- **Pull** brings the other workspace's deployed workflows into this workspace.
 
-Click **Fork**. The child workspace is created immediately. Deployed workflows land as **drafts** in the child. Large content (table rows, knowledge base files, file blobs) may finish copying in the background — watch **Activity** on the source workspace.
+Review which workflows will be created, replaced, or archived and compare the source deployment with the target. Missing counterparts are created. A mapped counterpart is archived when its source was deleted; merely undeploying the source does not archive it. Native target workflows are left alone.
 
-<Callout type="info">
-  Only **deployed** workflows are forked, and only the ones that are [synced](#synced-workflows). Drafts and undeployed work stay in the parent. If there is nothing to copy, the child starts with a blank starter workflow.
+<Callout type="warn">
+Sync overwrites the eligible target workflows, including target draft edits. Review the affected workflow and archive lists before confirming. There is no merge operation.
 </Callout>
 
-### 3. Open the parent edge (from the child)
-
-Open the **child** workspace → **Settings → Workspace → Workspace forks**. On the **Parent** row, open the menu and choose **Edit mappings**.
-
-Child rows (when you are on the parent) only offer **Open workspace** and **Disconnect** — mapping and sync are owned by the child configuring how it relates to its parent.
+### 2. Map or copy resources
 
-**Open workspace** is disabled with a tooltip if you do not have access to the other workspace. **Disconnect** stays available so you can still sever the link.
+| Choice | Use |
+| --- | --- |
+| **Map** | Keep each environment's existing resource and rewrite source references to its target counterpart. |
+| **Copy** | Create an independent target clone of a table, file, knowledge base, tool, skill, or supported MCP configuration. |
 
-### 4. Understand mappings
+For example, copy a Leads table into staging for experiments, but map each environment's Slack credential to its own connection. Mappings take precedence over copying. Resources used by the synced workflows default to selected for copy; **Not used by any workflow** resources default off.
 
-A **mapping** means: “this resource in the source is the same logical thing as that resource in the target.” When you sync, workflow fields that pointed at the source resource are rewritten to the target resource so blocks keep working.
+Credentials and environment-variable values are never copied. Map credentials to the same integration kind and secret names to target names such as `{{API_KEY}}`. Values remain in their own workspace. A secret reference used only inside a Note block does not block sync.
 
-| Approach | When to use it |
-|----------|----------------|
-| **Map** | Both sides already have (or should keep) their own resource — e.g. each workspace’s Slack credential, Gmail account, or secret value |
-| **Copy** | The target should receive a **new** clone of the source resource — a new table, knowledge base, file, or MCP server config |
+Environment-variable mapping does not sanitize every literal value. Review inline configuration, copied MCP headers, and OAuth client configuration for values that should differ between environments.
 
-**Credentials** and **Secrets** are **map-only**. They are never copied. Secret *values* never leave their workspace; only names like `{{API_KEY}}` appear in workflow text.
+### 3. Reconfigure dependent fields
 
-Mappings are saved on the fork relationship. You can click **Save** without syncing. Sync always uses the saved mappings.
+Mapping a credential or parent resource can invalidate choices such as Gmail labels, Slack channels, or knowledge documents. Pick those fields again for the target; required fields block **Sync** until configured.
 
-After you map or copy a parent resource (credential, knowledge base, table, …), **dependent fields** — Gmail labels, Slack channels, knowledge base documents, and similar — often need a fresh pick in the target. Required dependents block **Sync** until they are filled. Workspace file-folder scopes are mapped by canonical path; an empty folder selection creates no mapping requirement, and **Include Subfolders** does not block by itself.
+<Image src="/static/enterprise/forks-reconfigure.png" alt="A mapped resource's dependent Document field marked required for sync" width={900} height={242} className="mx-auto h-auto w-full max-w-xl" />
 
-### 5. Map, reconfigure, then Sync
+Resolve **Blocking sync** entries by mapping, selecting a supported resource for copy, deploying a referenced source workflow, or fixing its source reference. For a resource deleted at the source, you may explicitly drop its reference. That choice clears every occurrence of that resource in the sync, rather than only the displayed field. Live source resources cannot be dropped this way.
 
-On the sync page you will see direction (**Push** / **Pull**), deployed workflow changes, **Mappings**, optional **Copy resources**, and any **Blocking sync** items.
+Published custom blocks keep invoking their published source environment. Map them to a custom block published in the target; copying a workflow does not turn that invocation into a local implementation. See [custom-block authority](/platform/enterprise/custom-blocks).
 
-<Image src="/static/enterprise/forks-sync-overview.png" alt="Sync detail page with Push and Pull direction, deployed workflows, and mapping status badges" width={900} height={497} />
+### 4. Review trigger URLs and save
 
-- **Push** — overwrite the **other** workspace with this workspace’s deployed workflows
-- **Pull** — overwrite **this** workspace with the other’s deployed workflows
+In **Trigger URLs in** the target, review preserved URLs and any offered adoption choices for arriving triggers. Existing target trigger slots retain their own URLs. An arriving slot can use an offered retiring target path or request a new one. Retired webhook URLs stop serving; update external callers where needed.
 
-Both are force operations. Confirm carefully.
+Save mapping and dependent-field changes. While they are unsaved, the header offers **Save** and **Discard**; after saving, it returns to **Sync**. Copy selections and trigger choices belong to the current sync review; saving mappings does not persist every review choice.
 
-<Image src="/static/enterprise/forks-copy-resources.png" alt="Copy resources section showing resources used by workflows and a Not used by any workflow group" width={900} height={334} className="mx-auto h-auto w-full max-w-xl" />
+### 5. Confirm and verify completion
 
-Resources referenced by the workflows in the sync default to selected for copy. Unused ones sit under **Not used by any workflow** (off by default). If you **map** a resource, it leaves the copy list — maps win.
+Click **Sync**, review the overwrite confirmation, and confirm. If the source or reviewed scope changed, reload and review again rather than applying a stale comparison.
 
-<Image src="/static/enterprise/forks-reconfigure.png" alt="Dependent field reconfigure card under a mapped resource with a required field marked" width={900} height={242} className="mx-auto h-auto w-full max-w-xl" />
+A push/pull acknowledgement can precede content copying and deployment activation. Open **See activity** or **Activity**, expand the operation, and inspect copy progress, deployment results, and warnings. If deployment requires configuration or fails, open the affected workflow, fix it, and redeploy. Verify the target's active deployment and trigger/chat endpoints before sending traffic there.
 
-**Sync** stays disabled until:
+### Automated preview and retry protocol
 
-- Every blocking reference is mapped, copied, or fixed in the source
-- Required credentials and secrets are mapped
-- Required dependent fields are filled
-- Sync details have finished loading
+The [API and CLI sync guide](/api-reference/workflow-sync) covers preview fingerprints, mappings, dependent values, copy choices, and trigger choices. Apply exactly the reviewed request with its `previewFingerprint` and a stable `requestId`.
 
-### 6. Confirm and run
+After an uncertain response, retry the identical payload with the original request ID or find the original operation by request ID. A fresh ID can repeat the mutation. A changed payload under the same ID or a stale preview is refused; obtain a new preview and ID for a revised request that was not committed.
 
-Click **Sync**. You will get an overwrite confirmation.
-
-<Image src="/static/enterprise/forks-sync-confirm.png" alt="Overwrite target workspace confirmation dialog warning that syncing overwrites changes on the target" width={900} height={438} className="mx-auto h-auto w-full max-w-md" />
-
-On success you will see a toast such as **Pushed to "…"** or **Pulled from "…"**. If some workflows fail to redeploy, you get a warning to open and redeploy them manually.
-
----
+An operation receipt with `applied: true` means the transaction committed, including when follow-up work fails. Poll under the receipt's `workspaceId` while `status` is `processing`; inspect `issues`, `copyProgress`, admitted deployment `ready` values, and `pendingComponents`. Terminal status alone does not make a copied draft live. Fork-creation receipts belong to the source; push/pull receipts belong to the current workspace named in the request URL.
 
 ## Synced workflows
 
-The **Synced workflows** section on the Forks page lists this workspace's deployed workflows in their sidebar folder structure, each with a checkbox. **Checked means the workflow syncs.** Uncheck one — or a whole folder at once — to keep it out of forking entirely. Think of an unchecked workflow as `.gitignore`d:
-
-- **Never sent** — pushes from this workspace do not carry it, the other side pulling from this workspace does not receive it, and creating a new fork does not copy it
-- **Never touched** — a sync into this workspace will not overwrite or archive it, even if its counterpart was deleted on the other side. It stays deployed and keeps serving, and a previously-synced counterpart on the other side keeps running on its last deployed version.
+The **Synced workflows** list shows this workspace's deployed workflows in folder order. Checked workflows participate. Uncheck a workflow or folder to exclude it:
 
-The checkbox list belongs to **this workspace's copy** only. Unchecking a workflow here does not unsync its counterpart in the parent or a fork — each workspace manages its own list. If the pair has synced before, the link between them is kept, so re-checking later resumes updating the same counterpart instead of creating a duplicate.
+- It is not sent by push, received when the other side pulls, or copied into new forks.
+- Sync into this workspace does not replace or archive it, even if its counterpart was deleted. It keeps its current deployment.
 
-On the sync page, unsynced workflows still appear in the **Deployed workflows** list, greyed out, with a tooltip naming which workspace they are unsynced in. The sync will not touch them.
+Each workspace manages its own checkboxes. Unchecking here does not change the counterpart's checkbox. Existing identity mappings remain, so rechecking resumes updates to the same counterpart instead of creating a duplicate. Excluded workflows appear greyed out in the sync review with their workspace named.
 
-**Example:** a staging fork leaves `Scratch experiment` unchecked so it can never reach production, and production leaves `Billing hotfix` unchecked so no push from staging can ever overwrite it.
+For example, staging can exclude a scratch experiment while production excludes a local billing hotfix that staging must not overwrite.
 
 ### Sync new workflows by default
 
-Above the list, **Sync new workflows by default** decides where a **newly created** workflow starts:
-
-| Setting | A new workflow… |
-|---------|-----------------|
-| **Sync** (default) | joins fork sync — it arrives checked and syncs as soon as you deploy it |
-| **Don't sync** | starts outside fork sync — it arrives unchecked and only syncs after you check it |
-
-Three things to know:
-
-- **It applies to the whole fork lineage.** The toggle writes every workspace in the lineage — the root, every ancestor, every descendant — so a parent and its forks can never disagree about what "new" means. Any workspace admin in the lineage can change it, and each workspace whose value changes gets its own audit entry naming the workspace the change came from. A new fork inherits the value at creation.
-- **It is forward-only.** Flipping it never moves an existing workflow in or out of sync. The checkbox list above stays the record of what syncs.
-- **"New" means genuinely new.** Creating, duplicating, or importing a workflow takes this setting, as does the blank starter workflow a fork gets when there is nothing to copy. A workflow that arrives as a **copy** — from a fork, or from a push or pull — ignores this setting. Only synced workflows are copied, and they always arrive synced, so a workflow you deliberately synced never lands unsynced on the other side.
-
-**Example:** a template workspace turns this off so every scratch workflow the team creates stays local, then checks only the handful meant to reach the forks.
-
----
-
-## Activity
-
-**See activity** (or the Activity view from the Forks header) lists forks, pushes, pulls, and rollbacks that involve this workspace — including events recorded on the other side of the edge.
-
-<Image src="/static/enterprise/forks-activity.png" alt="Activity view showing Fork and Push events with expandable detail rows" width={900} height={614} className="mx-auto h-auto w-full max-w-xl" />
-
-Expand a row for names of workflows and resources that were created, updated, or archived, and any warnings (for example failed background copies or deploy failures). A push or pull that copies resources fills their content in the background, and that progress and outcome show in the same row.
+| Setting | New workflow behavior |
+| --- | --- |
+| **Sync** (default) | Starts checked and can sync after deployment. |
+| **Don't sync** | Starts unchecked until an admin selects it. |
 
----
-
-## Rollback vs Disconnect
+This setting applies to the whole lineage: root, ancestors, descendants, and siblings. Any workspace admin in that lineage can change it; changed workspaces receive audit entries naming the originating workspace. New forks inherit it.
 
-| Action | What it does | Keep in mind |
-|--------|--------------|--------------|
-| **Rollback** | Undoes the **last sync into this workspace** — restores each affected workflow to its prior deployed version and removes workflows that sync created | Copied resources from past syncs **may remain**. Rollback does not delete tables, KBs, or files that were copied in. |
-| **Disconnect** | Permanently removes the fork relationship | Both workspaces stay. Saved mappings and sync history for the pair are deleted. Forking again creates a **new** child, not a reconnect. |
-
----
+The change is forward-only. It does not alter existing checkboxes. Creating, duplicating, importing, or creating a blank starter workflow uses this default. Workflows arriving through fork, push, or pull are already selected for sync and arrive synced regardless of the default.
 
-## Permissions
-
-| Action | Who |
-|--------|-----|
-| See Forks / create a fork | Admin on this workspace (+ feature available) |
-| Sync / edit mappings | Admin on **both** sides of the edge |
-| Check / uncheck **Synced workflows** | Admin on the workspace those workflows live in |
-| Change **Sync new workflows by default** | Admin on any one workspace in the lineage — the change applies to every member |
-| Rollback | Admin on the workspace the sync landed in |
-| Disconnect | Admin on **this** side only (you can disconnect even without access to the other workspace) |
-| Open the other workspace | You must be a member of that workspace |
-
----
-
-## Resource reference
-
-How each resource behaves at **fork** time vs **sync** time. Use this when you are deciding what to select under **Copy resources**, or why Sync is asking you to map something.
-
-### At a glance
+## Resource behavior
 
 | Resource | Fork | Sync |
-|----------|------|------|
-| Deployed workflows | Copied as drafts when [synced](#synced-workflows) | Updated / created / archived (force overwrite) |
-| Undeployed workflows | Not copied | Not synced |
-| [Unsynced workflows](#synced-workflows) | Never | Never — not sent, not overwritten, not archived |
-| Files | Optional copy (default on) | Map or copy |
-| File folders referenced by workflows | Mirrored with their ancestor folders, even when empty | Map by canonical path |
-| Tables | Optional copy (default on) | Map or copy |
-| Knowledge bases (+ documents) | Optional copy; uploaded documents come with the KB, [connector-synced ones do not](#connector-synced-documents-are-not-copied) | Map or copy; documents follow the KB |
-| Custom tools | Optional copy (default on) | Map or copy |
-| Skills | Optional copy (default on) | Map or copy |
-| External MCP servers | Optional copy (config only; sign-in cleared) | Map or copy (config only; sign-in cleared) |
-| Workflow MCP servers | Optional copy (server shells + attachments when workflows copy) | Kept in sync automatically with the workflows |
-| Deployed chats | Carried with a **new** chat URL | Created on the target if it has no chat yet |
-| Credentials | Never — fields cleared | Map only |
-| Secrets | Values never; `{{KEY}}` names kept | Map key names only |
-| Public API | Child starts private | Flag follows the workflow |
-| Schedules / webhooks / triggers | Not live until you deploy in the child | Follow whatever you deploy on the target |
-| History, API keys, memory, scheduled jobs | Never | Never |
-
----
-
-### Workflows
-
-Only **deployed** workflows move, and only the ones checked under [Synced workflows](#synced-workflows). An unsynced workflow never moves in either direction.
-
-| Feature | Behavior |
-|---|----------|
-| **Fork** | Each synced deployed workflow becomes a **draft** in the child. Run history is not copied. Only folders that contain a copied workflow are kept. |
-| **Sync** | The change list shows what will be updated, created, or archived. The target is overwritten for those workflows. |
-
-**Example:** Parent has `Support triage` deployed and `WIP experiment` as a draft. The fork gets only `Support triage` as a draft. A later push updates the child from the parent’s latest deploy of `Support triage`.
-
----
-
-### Files
-
-| Feature | Behavior |
-|---|----------|
-| **Fork** | Listed under **Copy resources** (default on). A copied file keeps its containing folder structure. Folder scopes referenced by copied workflows are mirrored with their ancestors even when they are empty; mirroring a scope does not implicitly copy every file inside it. Deselect a file → that file field clears. |
-| **Sync** | Map to a file that already exists on the target, or copy. Files used by the sync’s workflows default to selected. Selected workspace file-folder scopes are mapped separately by canonical path. The same path is suggested automatically when it exists on both sides; otherwise create or choose the intended target folder before syncing. |
-
-**Example:** A workflow attaches `Brand/brand-guide.pdf` and searches an empty `/Incoming` folder. Fork with Files selected → the child gets its own file under `/Brand`, and `/Incoming` is also created so the search scope still points somewhere valid without copying unrelated files into it.
-
-Only concrete, active workspace folder selections participate in this mapping. Leaving **Folder** empty means “anywhere in the workspace” and never blocks sync. **Include Subfolders** only changes how a selected scope is expanded. Folder selectors backed by external providers are credential-scoped provider values, not workspace file-folder mappings.
-
----
-
-### Tables
+| --- | --- | --- |
+| Deployed workflows | Eligible workflows become drafts; only their needed workflow folders are copied. | Create or replace counterparts; archive mapped counterparts deleted at source. |
+| Workspace files | Optional copy; references clear when omitted. | Map or copy. |
+| Tables | Optional copy, with rows possibly filled in later. | Map an existing dataset or copy a new one. |
+| Knowledge bases | Optional copy with settings, tags, and uploaded documents. | Map or copy the base; documents follow it. |
+| Custom tools | Optional definition copy. | Map or copy. |
+| Skills | Optional content copy; references to other copied resources are rewritten. | Map or copy. |
+| External MCP servers | Optional connection-configuration copy; OAuth sign-in cleared. | Map or copy; copied servers need sign-in. |
+| Workflow MCP servers | Optional server shells and attachments to copied workflows. | Attachments stay aligned automatically. |
+| Published custom blocks | Remain invocations of their published source. | Map to a publication in the target. |
+| Chat deployments | Configuration and a new URL; child workflow must be deployed before serving. | Create only when the target has no existing chat record and is ready to deploy. |
+| Credentials | Never copied; workflow fields cleared. | Map only, with compatible integration kind. |
+| Secrets | Values never copied; `{{KEY}}` names retained. | Map names only. |
+| Public API | Child starts private. | Source flag follows the workflow. |
+| Schedules, webhooks, triggers | Inactive until the child deploys. | Activation follows target deployment. |
+| Run history, Sim API keys, memory, scheduled jobs, BYOK keys | Not copied. | Not copied. |
 
-| Feature | Behavior |
-|---|----------|
-| **Fork** | Optional copy (default on). Rows may finish copying in the background after the fork is created. Deselect → table fields clear. |
-| **Sync** | Map if both sides should keep pointing at “the same” logical table through the mapping, or copy for an independent dataset on the target. |
+### Files and folder scopes
 
-**Example:** An enrichment workflow uses a “Leads” table. Copy on fork so the child can experiment without touching production data. On sync, map if you intentionally want both sides aligned to paired tables, or copy a new table when the target should get a fresh clone.
+Copied files keep their containing folder structure. Referenced workspace folder scopes and their ancestors are mirrored even when empty; that does not copy every file within the scope. On sync, map folder scopes by canonical path. Matching paths are suggested; otherwise create or choose the intended target folder.
 
----
-
-### Knowledge bases and documents
-
-| Feature | Behavior |
-|---|----------|
-| **Fork** | Optional copy (default on). Tag definitions come with the knowledge base, along with every **uploaded** document in it. Deselect → knowledge base / document fields clear. |
-| **Sync** | Map or copy the knowledge base. Documents are not mapped by themselves — they follow the knowledge base (copied with it, or re-picked when you map to an existing one). |
-
-**Example:** An agent searches knowledge base “Product docs.” Fork with that knowledge base selected → the child gets the base, tags, and the uploaded documents. On sync, mapping to the child’s existing “Product docs” means re-picking which document the tool should use.
+For example, copying `Brand/brand-guide.pdf` and a workflow's empty `/Incoming` search scope creates both folders without copying unrelated incoming files. An empty **Folder** means anywhere in the workspace and does not block sync. **Include Subfolders** changes scope expansion only. External-provider folder choices remain credential-dependent values rather than workspace-folder mappings.
 
-#### Connector-synced documents are not copied
+### Connector-synced documents are not copied
 
-Connectors themselves never cross a fork edge — the child gets no Confluence, Notion, Google Drive, or other sync running against it. Documents that a **connector** put in the knowledge base are therefore not copied either. Only documents you **uploaded** come across.
+Knowledge-base copies include active uploaded documents, tag definitions, and settings. Connectors and their managed documents do not cross the edge.
 
 <Callout type="warn">
-  Fork a knowledge base whose content is entirely connector-synced and the child gets the base, its tags, and its settings — but **no documents**. Add the connector in the child to fill it.
+A knowledge base containing only connector-managed content arrives with no documents. Add a connector in the child to populate it, or download source documents and upload them as an intentional frozen snapshot.
 </Callout>
 
-This is deliberate. A copied connector document would arrive detached from any connector, so nothing would ever update, re-sync, or remove it — and when you added the connector in the child it would ingest every page again *alongside* the stale copy. Chain a few forks (prod → UAT → staging) and each hop leaves another dead generation behind, so one page comes back several times in a single knowledge search. Skipping them keeps the child’s own connector the single owner of that content.
-
-| To get connector content into the child | Do this |
-|---|---|
-| Keep it live | Add the same connector in the child and let it sync. It re-ingests everything, so nothing is lost. |
-| Keep a frozen snapshot | Download the documents from the source and upload them to the child’s knowledge base — uploaded documents copy on every later fork. |
-
-A document whose connector was **deleted** in the source is no longer connector-managed, so it copies like any other uploaded document.
-
----
-
-### Custom tools
-
-| Feature | Behavior |
-|---|----------|
-| **Fork** | Optional copy (default on). The tool definition comes along so agent / tool picks keep working. |
-| **Sync** | Map when both sides already maintain the same tool; copy when the target should receive the source’s definition as a new tool. |
-
-**Example:** A `lookup_customer` custom tool used by an agent. Fork with Custom tools selected → the child’s agent still has the tool. On push, a brand-new tool on the child can be copied into the parent if you leave it selected under **Copy resources**.
-
----
-
-### Skills
-
-| Feature | Behavior |
-|---|----------|
-| **Fork** | Optional copy (default on). Skill content comes along. Links inside the skill to files or other Sim resources are updated when those resources were also copied. Deselect → skill fields on agents clear. |
-| **Sync** | Map or copy, same idea as custom tools. |
-
-**Example:** A “Support tone” skill on an agent. Deselecting it on fork clears the skill on the child’s agent until you attach one again.
-
----
-
-### External MCP servers
-
-Servers you connect to an external MCP endpoint (not “publish this workflow as MCP”).
-
-| Feature | Behavior |
-|---|----------|
-| **Fork** | Optional copy (default on). **Connection settings** (URL, headers, transport) copy. **Sign-in / OAuth is not copied** — OAuth servers show up disconnected until someone signs in again in the child. Tool picks on MCP and agent blocks follow the new server. |
-| **Sync** | Map or copy under the same rules. Mapping is typical when each workspace has its own server aimed at the same upstream system. |
-
-**Example:** An MCP server for an internal API. After fork, open MCP settings in the child and complete OAuth (or confirm API headers) before those tools will run. On sync, map child ↔ parent servers so tool selections survive push and pull.
-
----
-
-### Workflow MCP servers
+Skipping managed documents avoids stale detached copies alongside the child's later connector ingestion. If a document's connector was deleted at the source, it is no longer connector-managed and can copy like an uploaded document. When mapping to an existing knowledge base, reselect dependent documents from that target base.
 
-Servers that **publish workflows as MCP tools**.
+### MCP and chat configuration
 
-| Feature | Behavior |
-|---|----------|
-| **Fork** | Optional under **Copy resources**. You get matching server shells in the child. When the workflow was also forked, its tool attachment on that server is carried over. |
-| **Sync** | These are not shown in the mapping list. Attachments stay aligned as you sync — tools are added, updated, or removed to match the source. |
+External MCP copies include URL, headers, transport, and supported OAuth client configuration, but never OAuth tokens. Reauthorize copied servers and inspect literal headers before using them. Workflow MCP attachments follow synced workflows rather than appearing as a separate resource-mapping list.
 
-**Example:** Parent exposes `Support triage` on a workflow MCP server. Fork with Workflow MCP servers selected → the child gets a matching server and the attachment to the child’s copy of the workflow.
+Chat copies include authentication configuration, such as password hashes or allowed emails, and block selection, with a new URL. Conversation history is not copied. On sync, any existing target chat record—including an archived one—prevents creating another. Deploy child workflows before testing copied chat URLs.
 
----
-
-### Deployed chats
+## Activity, rollback, and disconnect
 
-| Feature | Behavior |
-|---|----------|
-| **Fork** | Live chat deployments on copied workflows come along with a **new chat URL**. Conversation history is not copied — only the chat setup (including which blocks feed the chat). |
-| **Sync** | If the target workflow has **no** chat yet, the source’s live chat is created there (again with a new URL). Existing chats on the target are left alone. Workflows that are not ready to deploy do not get a chat. |
+**See activity** includes forks, pushes, pulls, and rollbacks involving this workspace, including operations recorded from the other side. Expand an event for changed resources, copy progress, and warnings.
 
-**Example:** Parent has a public chat on `Support triage`. The fork gets its own chat URL right away. A later push onto a parent workflow that never had a chat can create one there.
-
----
+### Rollback
 
-### Credentials
+Rollback applies only to the last sync into the target. It restores eligible workflows' prior deployed versions, unarchives workflows that sync archived, and archives/undeploys workflows that sync created. It does not restore arbitrary prior drafts or remove copied tables, files, or knowledge bases. Created chats are archived with their workflows.
 
-| Feature | Behavior |
-|---|----------|
-| **Fork** | **Never copied.** Credential fields in workflows are cleared. Connect or pick credentials in the child. |
-| **Sync** | **Map only.** Every credential used by the synced workflows must be mapped to a credential on the target (same kind of integration). Sync stays blocked until that is done. Then re-pick dependents (labels, calendars, channels, …). |
-
-**Example:** A Gmail block using “Support inbox.” Fork clears it. Before the first sync, map it to the child’s “Support inbox” credential and re-pick the label.
-
----
+Check restored deployment readiness. Activation can remain pending or fail after the restore commits; the undo point is retained while restored versions are not live so retrying can drive the remaining activations. Hard-deleted workflows or versions cannot be restored and are reported as skipped. A newer sync requires reviewing the newest undo point.
 
-### Secrets (environment variables)
+### Disconnect
 
-| Feature | Behavior |
-|---|----------|
-| **Fork** | **Values never leave the source.** Workflow text still contains `{{KEY}}` names. Create matching secrets (or the names you will map to) under the child’s **Secrets**. |
-| **Sync** | Map source key names to target key names. Values stay in each workspace. Unmapped required secrets block Sync. |
+Disconnect permanently deletes the edge, its mappings and saved dependent choices, workflow identity links, and pair sync history. Both workspaces and their data remain. Disconnecting also separates the fork subtree's Project grouping. The old edge cannot be reconnected; a later fork creates a new child.
 
-Notes are documentation: a `{{KEY}}` that appears only inside a Note block never needs mapping and never blocks Sync.
+## Troubleshoot sync
 
-**Example:** Workflows use `{{OPENAI_API_KEY}}`. After fork, add that secret in the child (or map `OPENAI_API_KEY` to whatever name the child uses) before runs and syncs succeed.
-
----
-
-### Public API
-
-| Feature | Behavior |
-|---|----------|
-| **Fork** | Child workflows start **private** — not exposed as public API endpoints, even if the parent was. |
-| **Sync** | The source workflow’s public API setting is carried. Push a public endpoint and the target becomes public too. |
-
----
+If **Sync** is disabled, resolve the listed blockers, required credentials or secrets, and required dependent fields. Wait for details to load; reload after a failed load. Save edited mappings before continuing.
 
-### Not carried
+If a newly deployed workflow is missing from the plan, check its **Synced workflows** checkbox. Changing the lineage default affects future creations only. If a copied table or knowledge base looks empty, inspect Activity before repeating the fork or sync. For an OAuth MCP server, reconnect in the target. For a copied chat, check workflow deployment and any existing target chat record.
 
-These do not move at fork or sync time:
-
-- Undeployed workflows and local drafts
-- Execution / run history
-- Sim API keys
-- Memory stores and scheduled jobs
-- BYOK provider keys
-- Permission groups (the child inherits the organization, but groups are not specially applied by forking)
-
-Schedules, webhooks, and triggers are not live in the child until you **deploy** there — same “deploy = commit” rule.
-
----
-
-## Edge cases to keep in mind
-
-- **Force overwrite** — Sync does not merge editor changes. Anything only on the target that conflicts with the source’s deployed workflows can be lost. Use the confirm dialog’s archive list carefully.
-- **Deselect on fork** — Cleared references are intentional. Prefer copying the resource, or plan to reconnect it in the child.
-- **Background copy** — Right after fork, large tables / knowledge bases / files may still be copying. Check **Activity** if something looks empty.
-- **OAuth MCP** — Expect a reconnect in the child (and after a copied server on sync).
-- **Rollback ≠ undo copies** — Workflow versions roll back; copied resources can remain as orphans.
-- **Disconnect is permanent** — You cannot “reconnect” the same edge; you would fork again into a new workspace.
-- **No grandparent sync** — Only the direct parent↔child pair.
-- **The sync default is lineage-wide** — **Sync new workflows by default** is one shared setting for the whole lineage, so changing it from a fork also changes it in the parent and every sibling fork.
-
----
-
-<FAQ items={[
-  { question: "Why is Sync greyed out?", answer: "Usually a blocking reference, an unmapped credential or secret, or a required dependent field (label, channel, document, …) still empty. Open Blocking sync and the mapping sections — each row explains what to fix. Sync also stays disabled while details are loading or if loading failed (reload the page)." },
-  { question: "Is sync a merge?", answer: "No. Deploy is like a commit; sync is a force push or force pull of deployed workflows onto the target. Use Rollback only for the last sync into a workspace, and remember copied resources may remain." },
-  { question: "Who can disconnect a fork I cannot open?", answer: "Any admin on your side of the edge. Disconnect does not require access to the other workspace — so you are not stuck if the other side lost membership." },
-  { question: "I deployed a new workflow and sync ignored it. Why?", answer: "Sync new workflows by default is off for this fork lineage, so the workflow was created outside fork sync. Open Settings → Workspace → Workspace forks and check it under Synced workflows. Turning the toggle back on only affects workflows created after that — it never moves an existing one." },
-  { question: "Does turning Sync new workflows by default off stop my current syncs?", answer: "No. It is forward-only and never rewrites an existing workflow's checkbox, so everything already synced keeps syncing. It also applies to every workspace in the fork lineage, not just the one you changed it from." }
-]} />
+## Self-hosted setup
 
----
+On billing-disabled deployments, enable forking through enterprise configuration or explicitly set:
 
-## Self-hosted setup
+```bash
+FORKING_ENABLED=true
+NEXT_PUBLIC_FORKING_ENABLED=true
+```
 
-Self-hosted deployments turn Forks on with an environment variable instead of the Enterprise plan.
+Explicit feature values take precedence over the master configuration. Billing-enabled self-hosted deployments still require Enterprise. See [self-hosted enterprise setup](/platform/enterprise/self-hosted).
 
-| Variable | Description |
-|----------|-------------|
-| `FORKING_ENABLED`, `NEXT_PUBLIC_FORKING_ENABLED` | Enables workspace forking when billing is not used as the entitlement gate |
+## Related docs
 
-Once enabled, use the same **Settings → Workspace → Workspace forks** UI as Sim Cloud. Only workspace admins can manage forks.
+- [API and CLI workflow sync](/api-reference/workflow-sync)
+- [Workflow deployment](/workflows/deployment)
+- [Custom blocks](/platform/enterprise/custom-blocks)
+- [Knowledge-base connectors](/knowledgebase/connectors)
diff --git a/apps/docs/content/docs/platform/enterprise/index.mdx b/apps/docs/content/docs/platform/enterprise/index.mdx
index 52acd3e5216..0e30e3f342e 100644
--- a/apps/docs/content/docs/platform/enterprise/index.mdx
+++ b/apps/docs/content/docs/platform/enterprise/index.mdx
@@ -1,21 +1,21 @@
 ---
 title: Enterprise
-description: Enterprise features for business organizations
+description: Configure organization access, provisioning, security, and operations
 ---
 
-Sim Enterprise adds organization controls for access, provisioning, operations, and branding. Organization owners and admins configure these features in Settings.
+Sim Enterprise adds controls for organization access, member provisioning, security, operations, and branding. On Sim Cloud, these features require an Enterprise subscription. Organization owners and admins manage organization controls in **Settings → Organization**.
 
 | Feature | Use it to |
-|---|---|
+| --- | --- |
 | [Permission groups](/platform/enterprise/access-control) | Restrict features, models, blocks, and tools by workspace and member |
 | [Single sign-on](/platform/enterprise/sso) | Connect a SAML or OIDC identity provider |
-| [Verified domains](/platform/enterprise/verified-domains) | Prove domain ownership for SSO and provisioning |
-| [Directory provisioning](/platform/enterprise/scim) | Sync users and group-based access from your directory |
-| [Security](/platform/enterprise/security) | Manage session policies and view configured outbound IP addresses |
-| [Session policies](/platform/enterprise/session-policies) | Set session lifetimes and revoke member sessions |
+| [Verified domains](/platform/enterprise/verified-domains) | Prove domain ownership for sign-in and provisioning |
+| [Directory provisioning](/platform/enterprise/scim) | Sync members and group-based access from your directory |
+| [Security](/platform/enterprise/security) | Find session controls and configured outbound IP addresses |
+| [Session policies](/platform/enterprise/session-policies) | Limit session lifetimes and revoke member sessions |
 | [Audit logs](/platform/enterprise/audit-logs) | Investigate configuration and security events |
-| [Insights](/platform/enterprise/usage-tracking) | Explore credit usage, workflow performance, and recorded chat activity |
-| [Data retention](/platform/enterprise/data-retention) | Set retention windows and configure PII redaction |
+| [Insights](/platform/enterprise/usage-tracking) | Explore credit usage, workflow performance, and recorded Chat activity |
+| [Data retention](/platform/enterprise/data-retention) | Configure retention windows and PII redaction |
 | [Data drains](/platform/enterprise/data-drains) | Export logs and Chat records to your own destination |
 | [Custom blocks](/platform/enterprise/custom-blocks) | Share a workflow as a block across the organization |
 | [Workspace forks](/platform/enterprise/forks) | Copy a workspace and sync deployed workflow changes |
@@ -23,17 +23,13 @@ Sim Enterprise adds organization controls for access, provisioning, operations,
 
 ## Self-hosted setup
 
-Self-hosted deployments unlock enterprise features through environment configuration instead of billing. One switch turns on the whole set:
+On a self-hosted deployment with billing disabled, enable enterprise features through environment variables:
 
 ```bash
 ENTERPRISE_ENABLED=true
 NEXT_PUBLIC_ENTERPRISE_ENABLED=true
 ```
 
-Each feature also keeps its own flag, so you can enable them one at a time or switch a single feature back off.
+Individual feature flags override the master switch. Most enterprise settings also need an organization that owns the workspace. Choose one instance-wide organization or provision separate organizations through the Admin API.
 
-Most of these features read their settings from the organization that owns a workspace, so a deployment also needs an organization model — either one instance-wide organization that every user joins automatically, or organizations you provision yourself through the Admin API.
-
-See the [self-hosted enterprise guide](/platform/enterprise/self-hosted) for the full variable list, both organization patterns, the Admin API reference, and troubleshooting.
-
-Once enabled, each feature is configured through the same Settings UI as Sim Cloud. When invitations are disabled (`DISABLE_INVITATIONS`, `NEXT_PUBLIC_DISABLE_INVITATIONS`), use the Admin API (`x-admin-key` header) to manage organization membership and workspace access. Internal members join the organization; external workspace members only receive access to a specific workspace.
+See [Self-hosted enterprise](/platform/enterprise/self-hosted) for flags, organization setup, background schedules, and Admin API examples. Once enabled, configure features through the same Settings UI as Sim Cloud.
diff --git a/apps/docs/content/docs/platform/enterprise/meta.json b/apps/docs/content/docs/platform/enterprise/meta.json
index c87d6bad42d..40747acf94a 100644
--- a/apps/docs/content/docs/platform/enterprise/meta.json
+++ b/apps/docs/content/docs/platform/enterprise/meta.json
@@ -8,13 +8,13 @@
     "security",
     "session-policies",
     "access-control",
+    "forks",
     "custom-blocks",
-    "whitelabeling",
     "audit-logs",
     "usage-tracking",
     "data-retention",
     "data-drains",
-    "forks"
+    "whitelabeling"
   ],
   "defaultOpen": false
 }
diff --git a/apps/docs/content/docs/platform/enterprise/scim/entra.mdx b/apps/docs/content/docs/platform/enterprise/scim/entra.mdx
index 8009198537f..b5dd7863028 100644
--- a/apps/docs/content/docs/platform/enterprise/scim/entra.mdx
+++ b/apps/docs/content/docs/platform/enterprise/scim/entra.mdx
@@ -1,127 +1,144 @@
 ---
 title: Microsoft Entra provisioning
-description: Connect Microsoft Entra ID to Sim and verify user and group provisioning
+description: Connect Microsoft Entra ID and verify member and group provisioning
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Image } from '@/components/ui/image'
 
-Use a non-gallery enterprise application in Microsoft Entra ID to create, update, and deactivate Sim members. Configure [single sign-on](/platform/enterprise/sso) separately for authentication.
+Use a non-gallery enterprise application in Microsoft Entra ID to create, update, and deactivate Sim organization members. Configure [single sign-on](/platform/enterprise/sso) separately for authentication.
 
 ## Before you start
 
-- An Enterprise organization in Sim, with an owner or administrator who can manage provisioning.
-- Each user email domain [verified in Sim](/platform/enterprise/verified-domains).
-- An Entra administrator who can create enterprise applications and manage provisioning.
-- A Sim deployment reachable by Entra over HTTPS. Self-hosted deployments must also meet the [SCIM rollout requirements](/platform/enterprise/scim#deployment-and-upgrades).
+- Use an Enterprise organization in Sim and an organization owner or admin account.
+- [Verify each provisioned email domain](/platform/enterprise/verified-domains).
+- Use an Entra administrator who can create enterprise applications and manage provisioning.
+- Make Sim reachable by Entra over HTTPS. Self-hosted deployments must meet the [SCIM rollout requirements](/platform/enterprise/scim#deployment-and-upgrades).
 
-Automated user provisioning is available with Entra ID Free. Group provisioning and group-based application assignment require Entra ID P1 or higher. See [Microsoft's licensing comparison](https://learn.microsoft.com/en-us/entra/fundamentals/licensing).
+Automated user provisioning is available with Entra ID Free. Group provisioning and group-based application assignment require P1 or higher. See [Microsoft licensing](https://learn.microsoft.com/en-us/entra/fundamentals/licensing).
 
-Start with dedicated test users. Provisioned members use a seat and receive workspace access only through a mapping or an existing grant.
+Start with dedicated test accounts. Provisioned members use a seat and receive workspace access through mappings or existing grants.
 
 ## Connect Entra to Sim
 
 <Steps>
-
 <Step>
 ### Enable provisioning in Sim
 
-Open **Settings → Organization → Single sign-on → Provisioning** and turn on **Enable directory provisioning**. Copy the **Base URL** from **Connection**. Under **Tokens**, choose an expiry and select **Issue token**. Copy the token before closing its dialog; Sim shows it once.
+Open **Settings → Organization → Single sign-on → Provisioning** and enable **Enable directory provisioning**. Copy **Connection → Base URL**. Under **Tokens**, choose an expiry and select **Issue token**. Copy the token before closing its dialog; Sim shows it once.
 </Step>
 
 <Step>
 ### Create the enterprise application
 
-In Microsoft Entra ID, open **Enterprise applications → New application → Create your own application**. Enter a name, such as **Sim provisioning**, select **Integrate any other application you don't find in the gallery (Non-gallery)**, and select **Create**.
-
+In Entra, open **Enterprise applications → New application → Create your own application**. Name the app, for example **Sim provisioning**, choose **Integrate any other application you don't find in the gallery (Non-gallery)**, and select **Create**.
 </Step>
 
 <Step>
 ### Configure the connection
 
-In the new application's **Provisioning** page, select **New configuration**. Choose **Bearer authentication** and enter:
+Open the app's **Provisioning** page, select **New configuration**, and choose **Bearer authentication**.
 
 | Field | Value |
 | --- | --- |
-| Tenant URL | The HTTPS Base URL copied from Sim, ending in `/api/scim/v2` |
-| Secret token | Your Sim token, without a `Bearer ` prefix |
+| **Tenant URL** | Sim's HTTPS Base URL ending in `/api/scim/v2` |
+| **Secret token** | Your Sim token, without a `Bearer ` prefix |
 
-Select **Test connection**, then **Create** after the test succeeds. Entra adds the bearer prefix itself. A successful connection test verifies connectivity and authentication; continue with a test assignment to verify provisioning.
+Select **Test connection**, then **Create** after it succeeds. Entra adds the bearer prefix. A successful test confirms connectivity and authentication; a test assignment verifies provisioning.
 
-<Image src="/static/enterprise/entra/connection.png" alt="Entra provisioning connection settings with the deployment URL redacted and secret token masked" width={808} height={305} className="mx-auto h-auto w-full max-w-xl" />
+<Image src="/static/enterprise/entra/connection.png" alt="Entra Bearer authentication fields with a redacted Tenant URL and masked Secret token" width={808} height={305} className="mx-auto h-auto w-full max-w-xl" />
 
 <Callout type="info">
-  These steps use Entra's current provisioning experience. In the legacy experience, choose **Automatic** provisioning, enter the same credentials under **Admin Credentials**, test the connection, and save. See [Microsoft's SCIM configuration guide](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups).
+  In Entra's legacy provisioning experience, choose **Automatic**, enter the same values under **Admin Credentials**, test, and save. See [Microsoft SCIM configuration](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups).
 </Callout>
-
 </Step>
 
 <Step>
-### Limit the scope and review mappings
+### Set scope and attribute mappings
+
+In the configuration's **Properties**, keep **Scope** set to **Sync only assigned users and groups**. Review accidental deletion protection before broadening the rollout.
 
-Under the provisioning configuration's **Properties**, keep **Scope** set to **Sync only assigned users and groups**. Review accidental deletion protection before broadening the rollout.
+Under **Users and groups → Add user/group**, choose a test account and select **Assign**. On the Free plan, assign accounts individually.
 
-In the application's **Users and groups**, select **Add user/group**, choose a test user, and select **Assign**. On the Free plan, assign users individually.
+Under **Attribute mapping**, review the user mappings:
 
-Under **Attribute mapping**, review the user mappings. The defaults map `userPrincipalName` to `userName`, `mail` to the work email, and `displayName` to `displayName`. Use a valid email address from a verified Sim domain; if your UPN differs from the user's email, adjust the mappings before provisioning. Keep `userName` as the matching attribute.
+| Entra attribute | SCIM attribute |
+| --- | --- |
+| `userPrincipalName` | `userName`, retained as the matching attribute |
+| `mail` | Work email |
+| `displayName` | `displayName` |
 
-If **Mail** is empty, Entra omits the work email and Sim uses `userName` as the account email. That UPN must be a valid email address in a verified Sim domain.
+Use an email in a verified Sim domain. If the UPN differs from the account email, adjust mappings before provisioning. When **Mail** is empty, Entra omits the work email and Sim uses `userName` as the account email; that UPN must be a valid email address in a verified domain.
 
-<Image src="/static/enterprise/entra/scope.png" alt="Entra provisioning properties restricted to assigned users and groups" width={810} height={250} className="mx-auto h-auto w-full max-w-xl" />
+<Image src="/static/enterprise/entra/scope.png" alt="Entra Properties showing assigned-only provisioning scope, accidental deletion protection, and Skip out of scope deletions disabled" width={810} height={250} className="mx-auto h-auto w-full max-w-xl" />
 </Step>
-
 </Steps>
 
-## Verify a user lifecycle
+## Verify the user lifecycle
 
-Open **Provision on demand**, search for the assigned test user, and select **Provision**. Review the import, scope, matching, and action results. In Sim, confirm that the member appears under **Organization → Members** and that **Single sign-on → Provisioning → Activity** shows successful requests.
+1. Open **Provision on demand**, search for the assigned test account, and select **Provision**. Inspect the import, scope, matching, and action results.
+2. In Sim, confirm the member under **Organization → Members** and successful requests under **Single sign-on → Provisioning → Activity**.
+3. Change its display name in Entra and provision again. Confirm the new name in Sim. An unchanged repeat should report that source and target already match.
+4. Remove the app assignment, then provision that account on demand again. Confirm Sim deactivates the member.
+5. Reassign and provision it to verify reactivation of the same account. Assignment changes can take a few minutes to reach provisioning.
 
-<Image src="/static/enterprise/entra/provision-user.png" alt="Successful on-demand user provisioning in Entra with account details redacted" width={812} height={626} className="mx-auto h-auto w-full max-w-xl" />
+<Image src="/static/enterprise/entra/provision-user.png" alt="Successful Entra on-demand import, scope, matching, and action checks with account details redacted" width={812} height={626} className="mx-auto h-auto w-full max-w-xl" />
 
-Change the test user's display name in Entra and provision them again. Confirm the new name in Sim. Repeating provisioning without changes should report that the source and target already match.
+### Deactivation and directory deletion
 
-Remove the test user's app assignment, then run on-demand provisioning for that user again. Confirm that Sim deactivates the existing member. Reassign the user and provision again to verify reactivation of the same account. Assignment changes can take a few minutes to become available to provisioning.
+| Entra change | Provisioning behavior |
+| --- | --- |
+| App unassignment | Deactivates the Sim member. Entra then stops managing the account and does not send a later directory deletion. |
+| Soft deletion while still managed | Deactivates the Sim member. |
+| Permanent deletion while still managed | Sends SCIM `DELETE`, which removes organization membership. Entra normally permanently deletes accounts 30 days after soft deletion; an administrator can purge earlier. |
 
-Sim deactivation suspends access while retaining organization membership, ownership, and the seat. For users still managed by the provisioning job, soft deletion deactivates the Sim member and permanent deletion sends a SCIM `DELETE` that removes organization membership. Entra normally permanently deletes users 30 days after soft deletion, or sooner if an administrator purges them. After app unassignment, Entra stops managing the user and does not send a later directory deletion. See [Microsoft's deprovisioning lifecycle](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works#deprovisioning) and [Sim's deactivation behavior](/platform/enterprise/scim#what-it-does).
+Sim deactivation suspends access while retaining membership, ownership, and the seat. See [Microsoft's deprovisioning lifecycle](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works#deprovisioning) and [Sim's lifecycle behavior](/platform/enterprise/scim#what-it-does).
 
 <Callout type="info">
-  Disabled or deleted Entra users cannot be selected for on-demand provisioning. [Start automatic provisioning](#start-automatic-provisioning) and complete the initial cycle before testing those changes through a scheduled cycle. See [Microsoft's on-demand limitations](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand).
+  Disabled or deleted Entra accounts do not appear in on-demand search. Start automatic provisioning and finish the initial cycle before testing those changes through a scheduled cycle. See [Microsoft on-demand limitations](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand).
 </Callout>
 
-## Provision groups and map access
-
-With Entra ID P1 or higher, create a dedicated security group with **Assigned** membership and add your test users as direct members. Assign that group to the enterprise application under **Users and groups**. Review the group mapping under **Attribute mapping** and keep group provisioning enabled.
+## Provision groups and verify access
 
-Run **Provision on demand** for the group and select its test members, or wait for a scheduled cycle. On-demand provisioning supports one group with up to five selected members at a time. Nested group membership is not supported; see [Microsoft's assignment guidance](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal).
+With P1 or higher, create a security group with **Assigned** membership and add test accounts as direct members. Assign it under **Users and groups**. Review **Attribute mapping** and keep group provisioning enabled.
 
-Once the group appears under **Single sign-on → Provisioning → Group mappings** in Sim, map it to a workspace, permission group, or the organization admin role. Start with a workspace mapping and confirm that the test members gain access.
+1. Run **Provision on demand** for one group and select up to five test members, or wait for a scheduled cycle. Nested membership is unsupported; see [Microsoft group assignment](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal).
+2. Once the group appears under **Single sign-on → Provisioning → Group mappings** in Sim, map it to a workspace, permission group, or organization admin role. Start with a workspace mapping and confirm access.
+3. Remove a test member from the group while retaining a separate direct app assignment. After synchronization, confirm the directory workspace grant is withdrawn while the account remains active.
+4. Add the member back and verify access returns.
 
-Remove a test user from the group while keeping a separate direct app assignment. After the group membership sync, confirm that the directory workspace grant is withdrawn while the user remains an active organization member. Add them back and verify that access returns. Read [how Sim withdraws directory access](/platform/enterprise/scim#how-access-is-withdrawn) before mapping groups that overlap with existing manual access.
+Read [How access is withdrawn](/platform/enterprise/scim#how-access-is-withdrawn) before mapping groups that overlap manual access.
 
 ## Start automatic provisioning
 
-After the test succeeds, return to the provisioning **Overview** and select **Start provisioning**. Wait for the initial cycle to complete and inspect **Provisioning logs** for failures. Entra normally runs subsequent cycles about every 40 minutes; changes are not immediate. See [Microsoft's provisioning lifecycle](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works).
+After testing, return to the provisioning **Overview** and select **Start provisioning**. Wait for the initial cycle and inspect **Provisioning logs** for failures. Subsequent cycles normally run about every 40 minutes; changes are not immediate. See [Microsoft's provisioning lifecycle](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works).
 
-Keep the scope limited to assigned users and groups as you add more members. Use **Provision on demand** for a small test; use the regular cycle to verify directory account disablement and deletion.
+Keep the scope limited to assigned accounts and groups. Use on-demand provisioning for small tests, and regular cycles for directory disablement or deletion.
 
-During a scheduled lifecycle test, leave the job running after changing the test user. **Restart provisioning** clears the change watermark and begins a new initial cycle; changing mappings or scoping filters also resets it. Wait for the incremental cycle and inspect that user's provisioning log before making further changes.
+Leave the job running during a scheduled lifecycle test. **Restart provisioning** clears its change watermark and starts another initial cycle; changing mappings or scoping filters also resets it. Wait for the incremental cycle and inspect the account's log before changing more settings.
 
-## Rotate the token
+## Rotate a token
 
-Issue a replacement token in Sim while the current token remains active. In Entra, open the provisioning configuration's **Connectivity** page, replace **Secret token**, select **Test connection**, and save. Confirm a successful provisioning request before revoking the old token in Sim. Sim allows two active tokens so rotation can overlap.
+Issue a replacement token in Sim while the current one remains active. In Entra's provisioning configuration, open **Connectivity**, replace **Secret token**, select **Test connection**, and save. Confirm a successful provisioning request before revoking the old token. Sim allows two active tokens for overlapping rotation.
 
 ## Troubleshooting
 
 | Symptom | Check |
 | --- | --- |
-| Connection test fails | Enter only the token in **Secret token**. Check the complete HTTPS Tenant URL, token expiry, and whether provisioning is enabled in Sim. |
-| User is out of scope | Assign the user to this enterprise application and check the provisioning scope and scoping filters. Allow time for assignment changes to propagate. |
-| User creation fails | Verify the email domain in Sim, available seats, and whether the account belongs to another Sim organization. Review the mapped UPN and work email. |
-| Repeat provisioning reports **Skipped** | Inspect the reason. **RedundantExport** means the source and target already match. |
-| Directory disablement or deletion has not reached Sim | Check the user's scheduled provisioning log, the `IsSoftDeleted` mapping to `active`, enabled **Update** actions, and accidental deletion protection. Confirm **Skip out of scope deletions** is disabled. A successful connection test alone does not verify a lifecycle change. |
-| Group assignment is unavailable | Check your Entra license. The Free plan supports individual user assignment but requires an upgrade for group assignment and provisioning. |
-| Member has no workspace access | Provision the directory group and add a workspace mapping in Sim. User provisioning creates organization membership. |
-| Disabled member still uses a seat | Sim suspends access on deactivation. Removing organization membership is a separate offboarding action. |
-
-Use Entra's **Provisioning logs** and Sim's **Provisioning → Activity** to inspect failures. Invalid or revoked tokens appear only in Entra because Sim cannot associate those requests with a connection.
+| Connection test fails | Enter the token alone. Check the full HTTPS Tenant URL, token expiry, and Sim provisioning switch. |
+| Account is out of scope | Check app assignment, provisioning scope, and scoping filters. Allow time for assignment propagation. |
+| User creation fails | Verify the domain, available seats, and whether the account belongs to another Sim organization. Check mapped UPN and work email. |
+| Repeat provisioning is **Skipped** | Inspect its reason. **RedundantExport** means source and target already match. |
+| Disablement or deletion has not reached Sim | Inspect the scheduled log, `IsSoftDeleted` mapping to `active`, enabled **Update** actions, and accidental deletion protection. Confirm **Skip out of scope deletions** is disabled. A connection test does not verify lifecycle changes. |
+| Group assignment is unavailable | Check licensing. Free supports individual assignment; group assignment and provisioning require an upgrade. |
+| Member has no workspace access | Provision the directory group and add a Sim workspace mapping. User provisioning adds organization membership. |
+| A disabled member still uses a seat | Deactivation suspends access; organization removal is separate. |
+
+Use Entra's **Provisioning logs** and Sim's **Provisioning → Activity**. Invalid or revoked tokens appear only in Entra because Sim cannot associate them with a connection.
+
+## Related docs
+
+- [Directory provisioning](/platform/enterprise/scim)
+- [Single sign-on](/platform/enterprise/sso)
+- [Verified domains](/platform/enterprise/verified-domains)
diff --git a/apps/docs/content/docs/platform/enterprise/scim/index.mdx b/apps/docs/content/docs/platform/enterprise/scim/index.mdx
index c75d13bbaf5..a3630aefa7c 100644
--- a/apps/docs/content/docs/platform/enterprise/scim/index.mdx
+++ b/apps/docs/content/docs/platform/enterprise/scim/index.mdx
@@ -1,51 +1,58 @@
 ---
 title: Directory provisioning (SCIM)
-description: Create, update, and deactivate Sim members automatically from your identity provider
+description: Sync organization members and group-based access from your identity provider
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { Image } from '@/components/ui/image'
-import { FAQ } from '@/components/ui/faq'
+import { Tab, Tabs } from '@/components/ui/tabs'
 
-Directory provisioning connects your identity provider to Sim over SCIM 2.0. Your provider creates members when someone joins, updates them when their details change, and deactivates them when it sends a deactivation request — without anyone touching Sim.
+Directory provisioning uses SCIM 2.0, a standard protocol for syncing accounts, to create, update, and deactivate organization members from your identity provider. Map directory groups to workspace access, permission groups, or the organization admin role.
 
-It pairs with [SSO](/platform/enterprise/sso). SSO proves who someone is when they sign in. Directory provisioning decides who exists and what they can reach, before and after that.
+Configure [SSO](/platform/enterprise/sso) separately for authentication. SCIM can manage membership without a saved SSO provider.
 
-<Callout type="info">
-  Included with Enterprise plans. The settings are under **Single sign-on → Provisioning**. On self-hosted deployments, enable the SSO settings page to reach this tab. A saved SSO provider is not required for SCIM; [verify each email domain](/platform/enterprise/verified-domains) before provisioning users at that domain. Self-hosted deployments get it with the other enterprise features through `ENTERPRISE_ENABLED=true` and `NEXT_PUBLIC_ENTERPRISE_ENABLED=true`, or turn just this feature on or off with `SCIM_ENABLED` and `NEXT_PUBLIC_SCIM_ENABLED`, alongside the [SSO variables](/platform/enterprise/sso#self-hosted-setup).
-</Callout>
+## Before you start
+
+- On Sim Cloud, use an Enterprise organization and an organization owner or admin account.
+- [Verify every email domain](/platform/enterprise/verified-domains) you will provision. Sim refuses account creation or an email change to an unverified domain.
+- On self-hosted deployments, enable SSO to reach **Single sign-on → Provisioning**, and enable SCIM. The enterprise master pair enables both; individual setup uses `SSO_ENABLED`, `NEXT_PUBLIC_SSO_ENABLED`, `SCIM_ENABLED`, and `NEXT_PUBLIC_SCIM_ENABLED`. See [Self-hosted SSO setup](/platform/enterprise/sso#self-hosted-setup) and [Deployment and upgrades](#deployment-and-upgrades).
 
 ## What it does
 
-| Your provider does this | Sim does this |
+| Directory request | Sim behavior |
 | --- | --- |
-| Assigns a person to the Sim app | Creates or links their account; new organization members join as Members |
-| Updates their name or email | Updates the Sim account, and ends their sessions if the address changed |
-| Deactivates them | Blocks sign-in and stops their personal API keys. Everything they own, and every grant they hold, is left untouched; shared workspace keys keep working |
-| Reactivates them | Lifts the suspension; current group memberships and mappings determine access |
-| Sends a SCIM DELETE request | Removes their organization membership, ends their sessions, deletes their personal API keys, and reassigns what they owned |
-| Adds them to a group | Grants whatever that group maps to |
+| Provision a person | Creates or links an account and adds new organization members as Members. Workspace access requires a mapping or existing grant. |
+| Update name or email | Updates the account. An email change ends its sessions. |
+| Deactivate a person | Suspends sign-in and personal API keys, and blocks scheduled runs or triggers acting as that person. Ownership, credentials, grants, and workspace history are retained. Shared workspace keys keep working. |
+| Reactivate a person | Lifts the suspension. Current group memberships and mappings govern directory access. |
+| Send SCIM `DELETE` | Removes organization membership, ends sessions, deletes personal API keys, and reassigns owned resources. The Sim account survives. |
+| Add or remove group membership | Applies or withdraws the group's mapped access. |
 
-Deactivation preserves ownership, credentials, and workspace history. It also blocks scheduled runs and triggers acting as that person. Changes to group membership or mappings can still withdraw access while someone is suspended.
+Deactivation itself does not withdraw grants. Group or mapping changes can still withdraw access and reassign ownership while someone is suspended. A deactivated member keeps their seat until removed from the organization.
 
-## Turn it on
+Deactivation deletes the member's sessions and stops personal API-key authentication when it completes. Organization security-version invalidation reaches cached browser sessions on other application instances within up to 60 seconds.
 
-<Steps>
+Sim refuses directory suspension or removal of an organization owner. Transfer ownership in Sim first.
 
-<Step>
-### Verify your domain
+### Match an existing account
+
+Sim links an account already in your organization or in no organization, using its verified-domain email. An account in another organization causes a conflict: a Sim account can belong to only one organization, so remove it there before provisioning here.
 
-Sim only provisions people whose email is in a domain your organization has verified. See [Verified domains](/platform/enterprise/verified-domains).
+New members follow the organization's seat policy. Fixed-seat plans reject a join when full; add seats and let the provider retry. Team seat policies grow the billed seat count with membership. Cloud SCIM availability still requires Enterprise.
+
+## Enable provisioning
+
+<Steps>
+<Step>
+### Verify domains
 
-This is what stops another tenant's directory from claiming an address it does not own.
+Verify each provisioned email domain under **Settings → Organization → Single sign-on → Domains**. This prevents a directory from claiming addresses its organization does not own.
 </Step>
 
 <Step>
-### Enable directory provisioning
+### Enable the connection
 
-Open **Settings → Organization → Single sign-on → Provisioning** and turn on **Enable directory provisioning**. Sim shows your SCIM base URL:
+Open **Single sign-on → Provisioning** and turn on **Enable directory provisioning**. Copy the **Base URL** under **Connection**:
 
 ```
 https://<your-sim-domain>/api/scim/v2
@@ -55,168 +62,145 @@ https://<your-sim-domain>/api/scim/v2
 <Step>
 ### Issue a token
 
-In **Tokens**, choose whether the token expires (never, 90 days, or a year) and select **Issue token**. It appears once — copy it straight into your provider.
+Under **Tokens**, choose **Never expires**, **Expires in 90 days**, or **Expires in 1 year**, then select **Issue token**. Copy the token before closing the dialog; Sim shows it once.
 
-Two tokens can be active at a time, so you can rotate without downtime: issue the new one, update your provider, confirm a sync succeeds, then revoke the old one.
+At most two tokens can be active. To rotate, issue a replacement, update the provider, confirm a successful provisioning request, then revoke the old token.
 </Step>
 
 <Step>
-### Configure your provider
+### Configure the provider
 
 <Tabs items={['Okta', 'Microsoft Entra ID', 'OneLogin', 'JumpCloud']}>
 <Tab value="Okta">
 
-For a step-by-step walkthrough, see [Okta provisioning](/platform/enterprise/scim/okta).
+Follow [Okta provisioning](/platform/enterprise/scim/okta) for integration selection, setup, and lifecycle checks. The evaluation **SCIM 2.0 Test App (Header Auth)** template expects the complete `Authorization` header in **API Token**:
 
-If you use OIDC for sign-in, create a separate provisioning integration: Okta cannot add SCIM to a custom OIDC app. In the Okta Integration Network catalog, add **SCIM 2.0 Test App (Header Auth)** for a private integration. See [Okta's setup guide](https://developer.okta.com/docs/guides/scim-provisioning-integration-connect/main/).
-
-In that app, open **Provisioning → Integration → Configure API Integration**, enable API integration, and enter:
-
-- **Base URL**: `https://<your-sim-domain>/api/scim/v2`
-- **API Token**: `Bearer <your-sim-token>` (include `Bearer` and a space)
-
-Select **Test API Credentials**, then save. Under **Provisioning → To App**, enable Create Users, Update User Attributes, and Deactivate Users. Assign a test user first, then use **Push Groups** for groups you want to map in Sim. Keep assignment groups separate from groups you push, as required by Okta.
-
-For an existing custom SAML or SWA app instead, follow [Okta's custom-app SCIM guide](https://help.okta.com/en-us/Content/Topics/apps/apps_app_integration_wizard_scim.htm). Its SCIM connection fields differ: set the unique identifier to `userName`, choose HTTP Header authentication, and enable the relevant provisioning actions.
+```
+Bearer <your-sim-token>
+```
 
-Okta never deletes users over SCIM. Unassigning someone, or deactivating them in Okta, sends a deactivation — which Sim applies as a suspension.
+Classic OIDC apps need a separate provisioning integration; OIDC apps created in the newer Okta Integration Wizard can support SCIM. The guide separates evaluation templates from production integration requirements. Keep app-assignment groups separate from Group Push groups.
 
+Okta sends deactivation rather than SCIM user `DELETE`, so offboarding suspends access while retaining membership and the seat.
 </Tab>
 <Tab value="Microsoft Entra ID">
 
-For a step-by-step walkthrough, see [Microsoft Entra provisioning](/platform/enterprise/scim/entra).
-
-Create a non-gallery enterprise application. Open **Provisioning → New configuration** and choose **Bearer authentication**. In the legacy experience, set Provisioning Mode to **Automatic** instead.
-
-- **Tenant URL**: `https://<your-sim-domain>/api/scim/v2`
-- **Secret token**: your Sim token, without a `Bearer ` prefix
-
-Test the connection and create the configuration. Keep **Sync only assigned users and groups** as the scope, assign a test user, and verify them with **Provision on demand** before starting automatic provisioning. Group provisioning requires Entra ID P1 or higher; individual user provisioning is available on the Free plan.
+Follow [Microsoft Entra provisioning](/platform/enterprise/scim/entra) to create a non-gallery application, configure **Bearer authentication**, and test assigned users before starting the automatic job.
 
-Entra runs an initial cycle over everyone in scope, then incremental cycles roughly every 40 minutes. Unassignment normally sends a deactivation. Soft-deleted directory users are retained for 30 days; hard deletion can then send a SCIM DELETE during a provisioning cycle. An administrator can hard-delete earlier, and users already unassigned may no longer be managed. See [Microsoft’s provisioning lifecycle](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works).
+Use the Sim Base URL as **Tenant URL**. Enter the token alone in **Secret token**, without `Bearer `. User provisioning is available with Entra ID Free; group provisioning requires P1 or higher.
 
+Entra's incremental cycles normally run about every 40 minutes. Unassignment and soft deletion deactivate a Sim member; permanent deletion can send SCIM `DELETE` while the provisioning job still manages the account. See the guide for the 30-day directory deletion window, early purge, and on-demand limits.
 </Tab>
 <Tab value="OneLogin">
 
-Add **SCIM Provisioner with SAML (SCIM v2 Core)**. Use the SCIM 2.0 connector, since Sim does not support SCIM 1.1.
+Add **SCIM Provisioner with SAML (SCIM v2 Core)**. Use version 2.0; Sim does not support SCIM 1.1.
 
-- **SCIM Base URL**: `https://<your-sim-domain>/api/scim/v2`
-- **SCIM Bearer Token**: your Sim token
-
-In **Parameters**, map `scimusername` to the user's email. Check that **SCIM JSON Template** uses `urn:ietf:params:scim:schemas:core:2.0:User` and sends that email as `userName` or in `emails`. Save, enable the API connection, then enable provisioning. See [OneLogin's custom connector guide](https://onelogin.service-now.com/kb?id=kb_article_view&sysparm_article=KB0013904).
+| Field | Value |
+| --- | --- |
+| **SCIM Base URL** | `https://<your-sim-domain>/api/scim/v2` |
+| **SCIM Bearer Token** | Your Sim token |
 
-Choose what happens when a user is deleted in OneLogin. **Suspend** maps to a Sim suspension; **Delete** removes their membership. If administrative approval is enabled, approve the pending provisioning actions in OneLogin before expecting a sync. See [OneLogin's provisioning test guide](https://developers.onelogin.com/docs/scim/test-your-scim/).
+In **Parameters**, map `scimusername` to the account's email. Confirm that **SCIM JSON Template** uses `urn:ietf:params:scim:schemas:core:2.0:User` and sends the email as `userName` or in `emails`. Save, enable the API connection, then enable provisioning. See [OneLogin custom connectors](https://onelogin.service-now.com/kb?id=kb_article_view&sysparm_article=KB0013904).
 
+Choose the deletion behavior: **Suspend** suspends the Sim account; **Delete** removes organization membership. If administrative approval is enabled, approve pending actions before expecting synchronization. See [OneLogin provisioning tests](https://developers.onelogin.com/docs/scim/test-your-scim/).
 </Tab>
 <Tab value="JumpCloud">
 
-Open an application's **Provisioning** tab and configure a **Custom SCIM** integration. You can use an existing application, a custom SAML application, or a URL Bookmark for provisioning without SAML.
-
-- **Base URL**: `https://<your-sim-domain>/api/scim/v2`
-- **Token** (also called **Token Key**): your Sim token
-- **Test User Email**: an unused address in a domain verified by your Sim organization
+Open the application's **Provisioning** tab and configure **Custom SCIM**. Use an existing application, a custom SAML application, or a URL Bookmark for provisioning without SAML.
 
-Select **Test Connection**, enable group management if you plan to map groups, then select **Activate**. Activation creates and deletes a test user and, with group management enabled, a test group. See [JumpCloud's custom SCIM guide](https://jumpcloud.com/support/provision-and-manage-users-and-groups-in-apps-using-custom-scim-identity-management-integration).
+| Field | Value |
+| --- | --- |
+| **Base URL** | `https://<your-sim-domain>/api/scim/v2` |
+| **Token** or **Token Key** | Your Sim token |
+| **Test User Email** | An unused address in a domain verified by your Sim organization |
 
+Select **Test Connection**, enable group management if you will map groups, then select **Activate**. Activation creates and deletes a test account and, with group management enabled, a test group. The test email must not already exist in Sim. See [JumpCloud custom SCIM](https://jumpcloud.com/support/provision-and-manage-users-and-groups-in-apps-using-custom-scim-identity-management-integration).
 </Tab>
 </Tabs>
 </Step>
 
 <Step>
-### Map your groups
+### Map directory groups
 
-Groups mean nothing to Sim until you say what they stand for. In **Single sign-on → Provisioning → Group mappings**, point each pushed group at one or more of:
+Under **Provisioning → Group mappings**, map each synced group to one or more targets:
 
-- a **permission group**, which governs models, integrations, and capabilities
-- a **workspace**, at Read, Write, or Admin
-- the **organization admin role**
+- A **Permission group**, which governs models, integrations, and capabilities.
+- A **Workspace**, with **Read**, **Write**, or **Admin** access.
+- The **Organization admin** role.
 
-A group can carry several mappings. When two groups grant the same workspace at different levels, the stronger one wins. The organization's default permission group cannot be a target: it governs by having no members.
+When multiple groups grant the same workspace at different levels, the strongest grant wins. The organization's default permission group cannot be a mapping target.
 
-Under **Provisioning rules**, select **Manage rules**. **Match permission groups by name** maps new or renamed directory groups to existing permission groups with the exact same name, including capitalization. After enabling it for groups already synced, select **Reconcile now** or wait for the next scheduled reconciliation. Sim creates no permission groups; renaming a directory group updates its automatic mapping and preserves mappings added manually.
+<Callout type="warn">
+  Mapping a permission group permanently switches it to explicit membership: it applies only to its members, and an empty mapped group applies to nobody. A group that previously applied to everyone in its workspaces stops doing so when mapped. Use permission groups created for directory membership rather than existing organization-wide groups.
+</Callout>
 
-Mapping a permission group to a directory group switches that permission group to explicit membership permanently: it governs exactly the people in it, and an empty group governs nobody. A permission group that governed everyone in its workspaces stops doing so the moment it is mapped, so map groups you created for the directory rather than your organization-wide ones.
+Under **Provisioning rules → Manage rules**, **Match permission groups by name** maps new or renamed directory groups to existing non-default permission groups with an exact, case-sensitive name match. Sim does not create permission groups. A rename updates automatic mappings and preserves manually added ones.
 
+For groups already synced before enabling name matching, select **Reconcile now** or wait for scheduled reconciliation.
 </Step>
-
 </Steps>
 
-<Image src="/static/enterprise/scim-provisioning.png" alt="Provisioning tab with an active SCIM connection, tokens, provisioning rules, group mappings, and recent activity" width={832} height={1284} className="mx-auto h-auto w-full max-w-md" />
-
 ## How access is withdrawn
 
-Sim records every grant it makes on your behalf. When someone leaves a group, what the directory granted is taken back.
+Sim tracks grants made through directory mappings. Removing a member from a group or removing its mapping withdraws the tracked access.
 
-**Lock managed membership**, on by default for a new connection, makes the directory the source of truth for provisioned members: Sim refuses invitations, workspace grants, workspace role changes, and organization role changes for them, because the next sync would revert them anyway. Access a member already held by hand when a mapping started covering it counts as directory access from then on, so it is withdrawn with the mapping. Removals stay possible so an administrator can always act in an emergency.
+**Lock managed membership** is enabled by default on a new connection. It makes the directory authoritative for provisioned members: Sim refuses manual invitations, workspace grants, workspace role changes, and organization role changes for them. Manual access already held when a mapping begins covering it becomes directory-managed and is withdrawn with that mapping. Administrators can still remove access in an emergency.
 
-With locking off, access held before the directory mapping is preserved. If someone had manual Read access and the directory raises it to Admin, removing the mapping restores Read. A workspace role raised by hand above the directory's level is also left alone. The upgrade limitation below applies to grants recorded by older versions.
+With locking off, prior manual workspace access is preserved. If a member had manual Read access and a directory mapping raises it to Admin, removing the mapping restores Read. A role manually raised above the directory's level also remains. [Older grants have a baseline limitation](#deployment-and-upgrades).
+
+You can manually invite people the directory does not manage. For managed members with locking on, grant access through directory groups.
 
 ## Provisioning and SSO together
 
-An active provisioned member can sign in once SSO is configured for their verified domain. Provisioning and SSO resolve to the same account.
+An active provisioned member can authenticate through SSO configured for the same verified domain. Both systems resolve to the same account.
+
+To prevent SSO from adding new organization members, enable **Provisioning rules → Manage rules → Disable just-in-time provisioning**. While the SCIM connection is active and entitled, this overrides **Sign-in → First sign-in → Automatic**. Existing members can still sign in, including members added by invitation; they do not all have to be SCIM-provisioned.
 
-To stop SSO from creating organization memberships, open **Provisioning rules → Manage rules** and enable **Disable just-in-time provisioning**. While the SCIM connection is active and entitled, this overrides **Sign-in → First sign-in → Automatic**. Existing organization members can still sign in, including members added by invitation; the setting does not require every existing member to have been provisioned by SCIM.
+## Inspect activity and reconcile access
 
-## Watching a sync
+Connection switches, rules, tokens, and mappings save immediately. **Provisioning** has no page-level Save button.
 
-Changes to the enable switch, provisioning rules, tokens, and mappings save immediately. There is no page-level Save button on this tab.
+**Provisioning → Activity** shows recent authenticated requests, their status, and failure details. A wrong, expired, or revoked token cannot be associated with a connection, so its authentication error appears only in the provider's logs.
 
-**Single sign-on → Provisioning → Activity** lists recent authenticated requests with their status and, for a failure, what was wrong. Providers report a failed cycle without saying what they sent, so this is usually the fastest way to see the cause. A request that fails to authenticate has no connection to log against, so a wrong or revoked token shows up only as your provider's own authentication error.
+**Reconcile now** reapplies group mappings and changed connection rules. For scheduled reconciliation, call `GET /api/cron/scim-reconcile` with the configured `CRON_SECRET`. Helm and production Docker Compose include an hourly schedule when their cron service is configured and running. This endpoint runs directly; it does not require Trigger.dev. See [Background schedules](/platform/enterprise/self-hosted#schedule-the-background-jobs).
 
-The scheduled reconciliation task re-applies group mappings hourly when the background task runner is configured and running. You can run it on demand with **Reconcile now**, which is also how a change to the connection settings reaches members before the next sync.
+## Disable provisioning
+
+Turning the connection off stops synchronization; it does not reverse suspension or prior access changes. Deactivated members stay deactivated. To restore an account without the directory, remove it from the organization and invite it again.
 
 ## Deployment and upgrades
 
-Apply the database migrations before deploying the new application code. The SCIM tables and suspension fields are additive, so the older application can continue running against the expanded schema during rollout.
-
-Keep `SCIM_ENABLED=false` and `NEXT_PUBLIC_SCIM_ENABLED=false` on the new deployment until all older application instances and workers have been drained. Older versions do not enforce SCIM suspensions or explicit permission-group membership. Enable provisioning only after every instance runs the new code. These explicit flags also override the hosted default.
-
-Once SCIM has suspended users or established managed access, rolling back to code that predates SCIM is not safe: it cannot enforce those restrictions. Disabling the SCIM connection stops synchronization but does not undo suspensions or restore old membership semantics.
-
-Migration `0325_scim_manual_workspace_baseline` adds tracking of prior manual workspace access. It cannot reconstruct levels overwritten by older SCIM code. Review those existing directory-owned grants before withdrawing mappings with membership locking off, and restore prior manual access explicitly where needed.
-
-## Reference
-
-- Base URL: `https://<your-sim-domain>/api/scim/v2`
-- Authentication: `Authorization: Bearer <token>`
-- Resources: `/Users`, `/Groups`, plus `/ServiceProviderConfig`, `/ResourceTypes`, and `/Schemas`
-- Filters: `eq` only, up to ten terms joined with `and`. Users: `id`, `userName`, `externalId`, `emails.value` (also `emails[type eq "work"].value`), `active`. Groups: `id`, `displayName`, `externalId`
-- Limits: sustained 1,500 requests per minute per connection with a burst capacity of 3,000, 1 MB per request, 5,000 members per group
-- `userName` is stored and returned lower-cased. Unmodeled top-level attributes and custom schema extensions are retained, and a PUT preserves ones it omits. Passwords are neither stored nor returned; Sim controls `id`, `meta`, and group membership
-- Group display names are unique within a connection, ignoring case
-- Page size: up to 100 per request
-
-<FAQ items={[
-  {
-    question: "What happens to someone's workflows when they are deactivated?",
-    answer: "Deactivation itself preserves their workspaces, workflows, and credentials. It blocks sign-in, personal API keys, and scheduled runs or triggers acting as that person. Reactivation lifts the suspension. Separate group or mapping changes can still withdraw workspace access and reassign ownership. A deactivated member keeps their seat until they are removed."
-  },
-  {
-    question: "Can the directory provision someone outside our verified domains?",
-    answer: "No. Sim refuses to create or move an account to an address whose domain your organization has not verified. This is what prevents one tenant's directory from claiming an account it does not own."
-  },
-  {
-    question: "What if the email already belongs to a Sim account?",
-    answer: "If the account is in your organization, or in none, Sim attaches to it. If it belongs to a different organization, Sim returns a conflict — a Sim account can belong to only one organization, so someone has to be removed there first."
-  },
-  {
-    question: "Can the directory deactivate or remove our organization owner?",
-    answer: "No. Sim refuses, because it would leave nobody able to administer billing or transfer ownership. Transfer ownership in Sim first."
-  },
-  {
-    question: "What happens when we run out of seats?",
-    answer: "Sim refuses the new member with a message your provider shows to its administrator. Add seats in Sim and the next sync will pick them up. Team plans grow their seat count automatically; fixed-seat plans do not."
-  },
-  {
-    question: "Does a deactivation sign someone out immediately?",
-    answer: "Their sessions are deleted and their personal API keys stop authenticating when deactivation completes. Cached browser sessions are invalidated through the organization's security version; other application instances can take up to 60 seconds to observe that change."
-  },
-  {
-    question: "What happens to deactivated members if we turn provisioning off?",
-    answer: "They stay deactivated. Disabling the connection stops the directory from making changes; it does not undo the ones it made. To restore someone without the directory, remove them from the organization and invite them again."
-  },
-  {
-    question: "Can we still invite people manually?",
-    answer: "You can invite people the directory does not manage. With Lock managed membership enabled, grant access to provisioned members through your identity provider; Sim refuses manual grants and role changes for them."
-  }
-]} />
+Apply database migrations before the new application code. The SCIM tables and suspension fields are additive, allowing older code to run against the expanded schema during rollout.
+
+<Callout type="warn">
+  Keep `SCIM_ENABLED=false` and `NEXT_PUBLIC_SCIM_ENABLED=false` until all older application instances and workers are drained. Older code does not enforce SCIM suspension or explicit permission-group membership. These explicit flags also override the hosted default.
+</Callout>
+
+After SCIM has suspended accounts or established managed access, rolling back to code that predates SCIM is unsafe: it cannot enforce those restrictions. Disabling synchronization does not undo suspension or restore earlier membership semantics.
+
+Migration `0325_scim_manual_workspace_baseline` tracks prior manual workspace access, but cannot reconstruct levels overwritten by older SCIM code. Review existing directory-owned grants before withdrawing mappings with locking off. Restore prior manual access explicitly where needed.
+
+## Protocol reference
+
+| Item | Contract |
+| --- | --- |
+| Base URL | `https://<your-sim-domain>/api/scim/v2` |
+| Authentication | `Authorization: Bearer <token>` |
+| Resources | `/Users`, `/Groups`, `/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas` |
+| Filters | `eq` only, up to 10 terms joined by `and` |
+| User filter fields | `id`, `userName`, `externalId`, `emails.value`, `emails[type eq "work"].value`, `active` |
+| Group filter fields | `id`, `displayName`, `externalId` |
+| Request rate | Sustained 1,500 requests per minute per connection; burst capacity 3,000 |
+| Request body | Maximum 1,000,000 bytes (1 MB) |
+| Group membership | Maximum 5,000 members per group |
+| List page | Maximum 100 resources per request |
+
+Sim stores and returns `userName` in lowercase. Group display names are unique within a connection, ignoring case. Unmodeled top-level attributes and custom schema extensions are retained; a `PUT` preserves those it omits. Passwords are neither stored nor returned. Sim controls `id`, `meta`, and group membership.
+
+## Related docs
+
+- [Single sign-on](/platform/enterprise/sso)
+- [Verified domains](/platform/enterprise/verified-domains)
+- [Okta provisioning](/platform/enterprise/scim/okta)
+- [Microsoft Entra provisioning](/platform/enterprise/scim/entra)
+- [Permission groups](/platform/enterprise/access-control)
diff --git a/apps/docs/content/docs/platform/enterprise/scim/okta.mdx b/apps/docs/content/docs/platform/enterprise/scim/okta.mdx
index 7fcd660cbd3..f5cf8d12c66 100644
--- a/apps/docs/content/docs/platform/enterprise/scim/okta.mdx
+++ b/apps/docs/content/docs/platform/enterprise/scim/okta.mdx
@@ -1,109 +1,141 @@
 ---
 title: Okta provisioning
-description: Connect a private Okta SCIM integration to Sim and verify user and group provisioning
+description: Connect Okta to Sim and verify member and group provisioning
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 import { Image } from '@/components/ui/image'
 
-Use an Okta SCIM integration to create, update, and deactivate Sim members. This guide covers provisioning; configure [single sign-on](/platform/enterprise/sso) separately for authentication.
+Connect an Okta SCIM 2.0 integration to create, update, and deactivate Sim organization members. Configure [single sign-on](/platform/enterprise/sso) separately for authentication.
 
 ## Before you start
 
-- An Enterprise organization in Sim, with an owner or administrator who can manage provisioning.
-- Each user email domain [verified in Sim](/platform/enterprise/verified-domains).
-- An Okta administrator account with access to application provisioning.
-- A Sim deployment reachable by Okta over HTTPS. For self-hosted deployments, use its public URL and apply the [SCIM rollout requirements](/platform/enterprise/scim#deployment-and-upgrades).
+- Use an Enterprise organization in Sim and an organization owner or admin account.
+- [Verify each provisioned email domain](/platform/enterprise/verified-domains).
+- Use an Okta administrator with access to application provisioning.
+- Make the Sim deployment reachable by Okta over HTTPS. Self-hosted deployments must meet the [SCIM rollout requirements](/platform/enterprise/scim#deployment-and-upgrades).
 
-Start with a test user and a dedicated group before assigning your organization. Provisioned members use a seat; they receive workspace access only through a mapping or an existing grant.
+Start with a test account and a dedicated group. Provisioned members use a seat and receive workspace access through mappings or existing grants.
 
-## Connect Okta to Sim
+## Choose an integration
 
-<Steps>
+SCIM support depends on how the Okta app was created:
+
+| Integration | SCIM setup |
+| --- | --- |
+| OIDC app created with the newer **Okta Integration Wizard** | Can support SCIM; follow the instructions for that creation experience |
+| OIDC app created with **Classic experience** | Does not support adding SCIM; use a separate provisioning integration |
+| Custom SAML or SWA app created with **Classic experience** | Enable SCIM under **General → App Settings → Provisioning**, then configure its SCIM fields |
+
+See [Okta's custom-app SCIM instructions](https://help.okta.com/en-us/Content/Topics/apps/apps_app_integration_wizard_scim.htm). If the provisioning option is missing, confirm that the feature is enabled for your Okta organization.
+
+<Callout type="warn">
+  The Header Auth Test App walkthrough below is for evaluation. [Okta support limits SCIM Test Apps to development and testing](https://support.okta.com/help/s/article/What-are-SCIM-20-Test-Apps?language=en_US), although its developer guide also describes private template integrations. For production, confirm a supported integration route for your Okta organization using the corresponding official instructions. This guide does not establish a published or certified Sim OIN integration.
+</Callout>
+
+### Connect a supported custom app
+
+1. In Sim, open **Settings → Organization → Single sign-on → Provisioning** and enable **Enable directory provisioning**. Copy **Connection → Base URL**, choose a token expiry under **Tokens**, and select **Issue token**. Copy it before closing the dialog; it is shown once.
+2. In the supported Okta app, enable SCIM. For a Classic SAML or SWA app, open **General → App Settings → Edit**, set **Provisioning** to **SCIM**, and save.
+3. Open **Provisioning → Integration** and configure **SCIM connector base URL** with Sim's Base URL. Set **Unique identifier field for users** to `userName`.
+4. Enable the supported push actions needed for your deployment: **Push New Users**, **Push Profile Updates**, and **Push Groups** for group-based access.
+5. Configure **HTTP Header** authentication to send `Authorization: Bearer <your-sim-token>`. Use the chosen integration's documented credential fields; they differ from the Test App's **API Token** field below.
+6. Test and save the connection. Under **Provisioning → To App**, enable user creation, attribute updates, and deactivation. Leave password synchronization disabled.
+
+Use an application username and primary email in a domain verified by Sim. If Okta usernames differ from email addresses, review the attribute mappings before assigning members. Then complete the lifecycle and group checks below.
+
+## Evaluate with the Header Auth Test App
 
+These steps use Okta's [private SCIM template guide](https://developer.okta.com/docs/guides/scim-provisioning-integration-connect/main/). The screenshots show the Test App configuration.
+
+<Steps>
 <Step>
 ### Enable provisioning in Sim
 
-Open **Settings → Organization → Single sign-on → Provisioning** and turn on **Enable directory provisioning**. Copy the **Base URL** from **Connection**. Under **Tokens**, choose an expiry and select **Issue token**. Copy the token before closing its dialog; Sim shows it once.
+Open **Settings → Organization → Single sign-on → Provisioning** and enable **Enable directory provisioning**. Copy **Connection → Base URL**. Under **Tokens**, choose an expiry and select **Issue token**. Copy the token before closing its dialog.
 </Step>
 
 <Step>
-### Add the Okta integration
-
-In the Okta Admin Console, open **Applications and Resources → Applications → Browse App Catalog**. Search for **SCIM 2.0 Test App (Header Auth)** and select **Add Integration**. Give the app a recognizable name, such as **Sim provisioning**.
+### Add the evaluation app
 
-For a provisioning-only app, hide its application icon from users and turn off automatic sign-in from the landing page. On **Sign-On Options**, select **Secure Web Authentication**, use your Sim HTTPS login URL, and set **Application username format** to **Email**. Complete the app setup. These template settings do not configure Sim SSO.
+In Okta, open **Applications and Resources → Applications → Browse App Catalog**. Search for **SCIM 2.0 Test App (Header Auth)**, select **Add Integration**, and name it, for example **Sim provisioning evaluation**.
 
-<Callout type="info">
-  Okta cannot add SCIM to a custom OIDC app. Keep this provisioning app alongside your OIDC sign-in app. For an existing custom SAML or SWA app, use [Okta's custom-app SCIM instructions](https://help.okta.com/en-us/Content/Topics/apps/apps_app_integration_wizard_scim.htm); those connection fields differ from the catalog template below.
-</Callout>
+For a provisioning-only app, hide its icon from members and turn off automatic sign-in from the landing page. Under **Sign-On Options**, choose **Secure Web Authentication**, use your Sim HTTPS login URL, and set **Application username format** to **Email**. Complete setup. These template options do not configure Sim SSO.
 </Step>
 
 <Step>
 ### Configure API integration
 
-In the new Okta app, open **Provisioning → Integration → Configure API Integration** and select **Enable API integration**.
+Open **Provisioning → Integration → Configure API Integration** and select **Enable API integration**.
 
 | Field | Value |
 | --- | --- |
-| Base URL | The URL copied from Sim, ending in `/api/scim/v2` |
-| API Token | `Bearer <your-sim-token>` — include `Bearer` and a space before the token |
+| **Base URL** | Sim's HTTPS URL ending in `/api/scim/v2` |
+| **API Token** | `Bearer <your-sim-token>` — include the prefix and a space |
 
-Select **Test API Credentials** and save after the test succeeds. A successful connection test checks connectivity and authentication; continue with a test assignment to verify provisioning.
+Select **Test API Credentials**, then save. The Header Auth template sends **API Token** as the complete `Authorization` header. Entering the token alone produces **A bearer token is required**.
 
-The Header Auth template sends this field as the complete `Authorization` header. Entering only the token produces **A bearer token is required**.
+<Image src="/static/enterprise/okta/api-integration.png" alt="Header Auth Test App API integration showing a successful credential test, a redacted Base URL, and a masked token" width={1001} height={678} className="mx-auto h-auto w-full max-w-xl" />
 
-<Image src="/static/enterprise/okta/api-integration.png" alt="Okta API integration with a successful credential test; the test deployment URL is redacted" width={1001} height={678} className="mx-auto h-auto w-full max-w-xl" />
+A successful credential test confirms connectivity and authentication. Assign a test account to verify provisioning itself.
 </Step>
 
 <Step>
 ### Enable provisioning actions
 
-Under **Provisioning → To App**, select **Edit**, enable **Create Users**, **Update User Attributes**, and **Deactivate Users**, then save. Leave **Sync Password** disabled: Sim does not synchronize passwords through SCIM.
+Under **Provisioning → To App → Edit**, enable **Create Users**, **Update User Attributes**, and **Deactivate Users**, then save. Leave **Sync Password** disabled; Sim does not synchronize passwords through SCIM.
 
-Use an email address from a verified Sim domain for the application username and primary email. Review the attribute mappings if your Okta usernames differ from users' email addresses.
+Use a verified-domain email for both the application username and primary email. Review mappings if Okta usernames differ from email addresses.
 
-<Image src="/static/enterprise/okta/provisioning-actions.png" alt="Okta provisioning actions with Create Users, Update User Attributes, and Deactivate Users enabled, and Sync Password disabled" width={1001} height={832} className="mx-auto h-auto w-full max-w-xl" />
+<Image src="/static/enterprise/okta/provisioning-actions.png" alt="Header Auth Test App actions with user creation, attribute updates, and deactivation enabled, and password synchronization disabled" width={1001} height={832} className="mx-auto h-auto w-full max-w-xl" />
 </Step>
-
 </Steps>
 
-This uses Okta's [private integration template](https://developer.okta.com/docs/guides/scim-provisioning-integration-connect/main/). It does not make the integration a published or certified Okta Integration Network application.
+## Verify the user lifecycle
 
-## Verify a user lifecycle
+1. Assign a test account from **Assignments**. Confirm it appears in Sim's organization and **Provisioning → Activity** shows successful requests.
+2. Update **Display name** in Okta and confirm the change in Sim. Sim uses mapped `displayName`, falling back to the structured name when omitted.
+3. If the account belongs to a pushed group, remove it from that group and confirm the downstream removal before unassigning the app.
+4. Unassign the account and confirm Sim marks it deactivated.
+5. Reassign it and confirm the existing member becomes active again.
 
-Assign one test user to the app from **Assignments**. In Sim, confirm that the account appears in the organization and that **Provisioning → Activity** shows successful requests. Update the user's **Display name** in Okta and confirm it in Sim. Sim uses the mapped `displayName`, falling back to the structured name when it is omitted.
+Okta sends deactivation, not SCIM user `DELETE`. Sim suspends access while retaining organization membership, ownership, and the seat. Removing organization membership is a separate offboarding action. See [Sim deactivation behavior](/platform/enterprise/scim#what-it-does) and [Okta's offboarding order](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/app-assignments-group-push.htm).
 
-Unassign the test user and check that Sim marks them as deactivated. Reassign the same user and confirm that the existing member becomes active again. If the user belongs to a pushed group, remove them from that group and confirm the downstream removal **before** unassigning the app; see [Okta's offboarding order](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/app-assignments-group-push.htm).
+## Push groups and verify access
 
-Okta deactivates users over SCIM; it does not send a SCIM DELETE. Sim suspends access while retaining the user's organization membership, ownership, and seat. See [deactivation behavior](/platform/enterprise/scim#what-it-does) before using unassignment for offboarding.
+Use separate groups for app assignment and Group Push; Okta does not support using the same group for both. Assign accounts to the app first.
 
-## Push groups and map access
+1. Under **Push Groups → Find groups by name**, select the group.
+2. Leave **Push group memberships immediately** enabled. For a new downstream group, save with **Create Group** selected.
+3. In Sim, open **Single sign-on → Provisioning → Group mappings** and map the synced group to a workspace, permission group, or organization admin role. Workspace access requires a workspace mapping. Name matching can map existing permission groups automatically.
+4. Confirm a test member gains workspace access. Remove it from the pushed group while keeping its app assignment, and confirm the directory grant is withdrawn. Add it back and verify access returns without another account being created.
 
-Use separate groups for app assignment and Group Push. Okta does not support using the same group for both purposes. Assign the users to the app first. Under **Push Groups → Find groups by name**, select the group, leave **Push group memberships immediately** enabled, and save with **Create Group** selected for a new downstream group.
+<Image src="/static/enterprise/okta/group-push.png" alt="Header Auth Test App Group Push selecting an engineering group and Create Group for the downstream group" width={1001} height={927} className="mx-auto h-auto w-full max-w-xl" />
 
-<Image src="/static/enterprise/okta/group-push.png" alt="Okta Group Push selecting an engineering group and creating its downstream group in Sim" width={1001} height={927} className="mx-auto h-auto w-full max-w-xl" />
+With **Lock managed membership** enabled, Sim blocks manual invitations and grants for provisioned members. Read [How access is withdrawn](/platform/enterprise/scim#how-access-is-withdrawn) before mapping groups that overlap existing manual access.
 
-Once the group appears under **Single sign-on → Provisioning → Group mappings** in Sim, map it to a workspace, permission group, or the organization admin role. Workspace access requires a workspace mapping. If name matching is enabled, Sim can automatically map matching permission groups.
+## Rotate a token
 
-Use a workspace mapping for the first test. Confirm that the member gains access, then remove them from the pushed group while keeping their app assignment. Confirm that the directory grant is withdrawn. Add them back and verify access is restored without creating another account.
+Issue a replacement token in Sim while the current one remains active. Update the chosen integration's credential field. For the Header Auth template, replace **Provisioning → Integration → API Token** with `Bearer <new-token>`.
 
-With **Lock managed membership** enabled, manage access for provisioned members through directory groups; manual invitations and grants are blocked. Read [how access is withdrawn](/platform/enterprise/scim#how-access-is-withdrawn) before mapping groups that overlap with existing manual access.
-
-## Rotate the token
-
-Issue a replacement token in Sim while the current token remains active. In Okta, edit **Provisioning → Integration** and replace **API Token** with `Bearer <new-token>`. Test the credentials, save, and confirm a successful provisioning request before revoking the old token in Sim. Sim allows two active tokens so rotation can overlap.
+Test credentials, save, and confirm a successful provisioning request before revoking the old token. Sim allows two active tokens for overlapping rotation.
 
 ## Troubleshooting
 
 | Symptom | Check |
 | --- | --- |
-| Credential test fails | Include `Bearer ` before the token. Use the complete HTTPS base URL and a current Sim token, and confirm provisioning is enabled and reachable. |
-| User creation fails | Confirm the email domain is verified, a seat is available, and the account does not belong to another Sim organization. |
-| User exists but has no workspace access | Push the directory group and add a Sim workspace mapping. Assignment alone creates organization membership. |
-| Name or membership changes do not arrive | Check the app assignment, provisioning actions, attribute mappings, and Group Push status in Okta. |
-| A pushed group is missing members | Confirm those users are active in Okta and successfully assigned to the app. After activation, repush the group; see [Okta's Group Push troubleshooting](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-group-push-troubleshoot.htm). |
-| A deactivated member still uses a seat | Deactivation suspends access. Removing organization membership is a separate offboarding action. |
-
-Use **View Logs** in the Okta app and **Provisioning → Activity** in Sim to inspect failures. Requests with an invalid or revoked token appear only in Okta because Sim cannot associate them with a connection.
+| Credential test fails | For Header Auth, include `Bearer `. Check the complete HTTPS URL, token expiry, provisioning switch, and network reachability. |
+| User creation fails | Verify the email domain, available seats, and whether the account belongs to another Sim organization. |
+| Member has no workspace access | Push the group and add a workspace mapping. App assignment creates organization membership. |
+| Name or membership updates do not arrive | Check app assignment, provisioning actions, attribute mappings, and Group Push status. |
+| A pushed group is missing members | Confirm those accounts are active and successfully assigned to the app. After activation, repush the group; see [Okta Group Push troubleshooting](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-group-push-troubleshoot.htm). |
+| A deactivated member still uses a seat | Deactivation suspends access; remove organization membership to complete that offboarding step. |
+
+Use **View Logs** in the Okta app and **Provisioning → Activity** in Sim. Invalid or revoked tokens appear only in Okta because Sim cannot associate them with a connection.
+
+## Related docs
+
+- [Directory provisioning](/platform/enterprise/scim)
+- [Single sign-on](/platform/enterprise/sso)
+- [Verified domains](/platform/enterprise/verified-domains)
diff --git a/apps/docs/content/docs/platform/enterprise/security.mdx b/apps/docs/content/docs/platform/enterprise/security.mdx
index 0a67efba9cd..4b1ba001f2d 100644
--- a/apps/docs/content/docs/platform/enterprise/security.mdx
+++ b/apps/docs/content/docs/platform/enterprise/security.mdx
@@ -1,34 +1,33 @@
 ---
 title: Security
-description: Manage organization session policies and view configured outbound IP addresses
+description: Find session controls and configured outbound IP addresses
 ---
 
-Organization owners and admins open **Settings → Security** to manage session policies and view outbound IP addresses.
+Organization owners and admins open **Settings → Organization → Security** to manage session policies and view outbound IP addresses. On Sim Cloud, this page requires an Enterprise organization.
 
 ## Session policies
 
-Set **Max session lifetime** and **Idle timeout** in hours, then select **Save**. Leave either field empty to use its default behavior. **Discard** restores your saved values.
+Set session lifetime and idle limits, or use **Sign out all members** to revoke member sessions except your current session. This action does not revoke API keys.
 
-**Sign out all members** opens a confirmation before revoking the organization's browser sessions, except your current session. It does not revoke API keys.
-
-See [Session policies](/platform/enterprise/session-policies) for limits, defaults, and how changes affect existing sessions.
+See [Session policies](/platform/enterprise/session-policies) for setup, defaults, limits, and enforcement.
 
 ## Outbound IP addresses
 
-Copy your organization's configured addresses in `/32` format and allowlist **every listed address** on the destination firewall. These addresses apply to supported HTTPS connections from Sim and its background workers.
-
-Contact Sim support or your deployment administrator to configure dedicated IPs and confirm connection coverage.
+Copy your organization's configured addresses in `/32` format and allowlist **every listed address** on the destination firewall. Contact Sim support or your deployment administrator to configure dedicated IPs and confirm coverage for the connections you use.
 
 ### Connection coverage
 
-Dedicated routing supports public IPv4 destinations over HTTPS on port 443. It applies to supported Search connector API requests, HTTP request blocks, MCP and A2A connections, and HTTP requests made through Sim's local Function runtime. Background jobs use the same organization assignment.
-
-Native database connections, AWS SDK integrations, remote sandbox traffic, and browser requests keep their existing network paths. Other provider SDKs and OAuth authorization or token refresh calls require separate coverage confirmation. Dedicated IPs do not change access permissions in connected services.
+Dedicated routing supports public IPv4 destinations over HTTPS on port 443. Its coverage depends on the connection:
 
-Google Drive, Fireflies, Google Workspace user and group discovery, and Atlassian OAuth site discovery currently use their existing network paths.
+| Connection | Routing behavior |
+| --- | --- |
+| Supported Search connector API requests, HTTP request blocks, MCP and A2A connections, and HTTP requests through Sim's local Function runtime | Use the organization's dedicated routing assignment; background jobs use the same assignment |
+| Native database connections, AWS SDK integrations, remote sandbox traffic, and browser requests | Keep their existing network paths |
+| Google Drive, Fireflies, Google Workspace user and group discovery, and Atlassian OAuth site discovery | Currently keep their existing network paths |
+| Other provider SDKs and OAuth authorization or token refresh calls | Require separate coverage confirmation |
 
-If dedicated routing is unavailable, affected requests fail instead of using shared IPs. Organizations without dedicated routing keep their existing behavior.
+Dedicated IPs do not change permissions in connected services. If dedicated routing is unavailable, affected requests fail instead of using shared IPs. Organizations without dedicated routing keep their existing behavior.
 
-## Availability
+## Self-hosted availability
 
-On Sim Cloud, Security settings require an Enterprise organization and an owner or admin role. On self-hosted deployments, the outbound IP section is available to organization administrators; session controls appear only when session policies are enabled. See [self-hosted enterprise configuration](/platform/enterprise/self-hosted).
+The outbound IP section is available to organization administrators on self-hosted deployments. Session controls appear when session policies are enabled. See [Self-hosted enterprise](/platform/enterprise/self-hosted).
diff --git a/apps/docs/content/docs/platform/enterprise/self-hosted.mdx b/apps/docs/content/docs/platform/enterprise/self-hosted.mdx
index bc8c776d41b..d3d2555c045 100644
--- a/apps/docs/content/docs/platform/enterprise/self-hosted.mdx
+++ b/apps/docs/content/docs/platform/enterprise/self-hosted.mdx
@@ -1,35 +1,28 @@
 ---
-title: Self-hosted Enterprise
-description: Run the full enterprise feature set on a self-hosted deployment without billing
+title: Self-hosted enterprise
+description: Enable enterprise features and configure organizations on a self-hosted deployment
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 
-On Sim Cloud, enterprise features are unlocked by an Enterprise subscription. Self-hosted deployments have no subscription, so they are unlocked by environment configuration instead.
+On a self-hosted deployment with billing disabled, enable enterprise features through environment variables. Then create an organization and attach its workspaces: branding, PII redaction, permission groups, custom blocks, data drains, and organization audit scope depend on the organization that owns a workspace.
 
-There are two parts to getting this right, and skipping the second is the most common reason features appear to do nothing:
-
-1. **Enable the features** with `ENTERPRISE_ENABLED`.
-2. **Give them an organization to apply to.** White-labeling, PII redaction, permission groups, custom blocks, data drains, and audit scoping all read their settings from the organization that owns a workspace. A deployment where everyone works in personal workspaces has no organization for those settings to come from.
+This guide covers the standard billing-disabled configuration. If billing is enabled, subscription gates apply and instance-organization variables are ignored.
 
 ## Enable the feature set
 
-Set the master switch and its client twin. Both are required. The server value decides access and most of what a workspace shows: settings sections and nearly all block fields read the deployment's server-resolved configuration, so the sidebar and the API answer the same question. The `NEXT_PUBLIC_` value covers what still reads the browser's own configuration: the SSO entry point on the login page, which renders before any workspace loads, and the Function block's Sandbox selector. On a Compose install or source checkout, `npx sim-setup doctor` reports a twin that disagrees with its server flag; see [Verify your install](/platform/self-hosting/verify).
+Set both the server flag and its browser twin, then restart the application:
 
 ```bash
 ENTERPRISE_ENABLED=true
 NEXT_PUBLIC_ENTERPRISE_ENABLED=true
 ```
 
-That turns on organizations, permission groups, SSO, white-labeling, audit logs,
-usage tracking, custom blocks, session policies, data retention, data drains, workspace
-forks, the Sandbox entitlement, and the inbox.
-
-### Turning one feature off
+The server flag controls access and the server-resolved workspace settings. The browser twin also enables controls that read browser configuration directly, including SSO on the login page and the Function block's **Sandbox** selector. On a Compose install or source checkout, `bunx sim-setup doctor` reports mismatched twins. See [Verify your install](/platform/self-hosting/verify).
 
-Every feature keeps its own flag, and an explicitly set flag always wins over the master switch. To run the suite without data drains:
+Individual flags override the master switch. For example, to enable the suite with data drains disabled:
 
 ```bash
 ENTERPRISE_ENABLED=true
@@ -38,125 +31,70 @@ DATA_DRAINS_ENABLED=false
 NEXT_PUBLIC_DATA_DRAINS_ENABLED=false
 ```
 
-The individual flags also work on their own if you would rather opt in one at a time and leave the master switch unset.
-
-Three features do not need a flag at all: **custom branding**, **session policies**, and the **Sim Mailer inbox** are already on wherever billing is disabled, which is every self-hosted deployment. They preserve behavior that predates these flags. Set the corresponding variable to `false` to turn one off.
-
-| Feature | Server variable | Client variable |
-|---------|-----------------|-----------------|
-| Everything below | `ENTERPRISE_ENABLED` | `NEXT_PUBLIC_ENTERPRISE_ENABLED` |
-| Organizations | `ORGANIZATIONS_ENABLED` | `NEXT_PUBLIC_ORGANIZATIONS_ENABLED` |
-| Permission groups | `ACCESS_CONTROL_ENABLED` | `NEXT_PUBLIC_ACCESS_CONTROL_ENABLED` |
-| SAML and OIDC sign-in | `SSO_ENABLED` | `NEXT_PUBLIC_SSO_ENABLED` |
-| Directory provisioning (SCIM) | `SCIM_ENABLED` | `NEXT_PUBLIC_SCIM_ENABLED` |
-| Custom branding — on by default | `WHITELABELING_ENABLED` | `NEXT_PUBLIC_WHITELABELING_ENABLED` |
-| Audit logs | `AUDIT_LOGS_ENABLED` | `NEXT_PUBLIC_AUDIT_LOGS_ENABLED` |
-| Insights | `USAGE_MONITORING_ENABLED` | `NEXT_PUBLIC_USAGE_MONITORING_ENABLED` |
-| Custom blocks | `CUSTOM_BLOCKS_ENABLED` | `NEXT_PUBLIC_CUSTOM_BLOCKS_ENABLED` |
-| Session policies — on by default | `SESSION_POLICIES_ENABLED` | `NEXT_PUBLIC_SESSION_POLICIES_ENABLED` |
-| Data retention deletion | `DATA_RETENTION_ENABLED` | `NEXT_PUBLIC_DATA_RETENTION_ENABLED` |
-| Data drains | `DATA_DRAINS_ENABLED` | `NEXT_PUBLIC_DATA_DRAINS_ENABLED` |
-| Credential Groups | `CREDENTIAL_GROUPS` | — |
-| Workspace forks | `FORKING_ENABLED` | `NEXT_PUBLIC_FORKING_ENABLED` |
-| Sim Mailer inbox — on by default | `INBOX_ENABLED` | `NEXT_PUBLIC_INBOX_ENABLED` |
-| Sandboxes | `SANDBOXES_ENABLED` | `NEXT_PUBLIC_SANDBOXES_ENABLED` |
-
-Sandboxes also need a remote execution provider and a dedicated Function base image before they can run anything. `SANDBOXES_ENABLED` grants the server-side entitlement, and the server also verifies the provider credentials and an immutable Function base before it reports Sandboxes as available. Until then a workspace offers no Shell language, and **Settings → Sandboxes** stays in the sidebar but shows an upgrade notice instead of the sandbox list. `NEXT_PUBLIC_SANDBOXES_ENABLED` asserts that readiness to the browser rather than checking it: it reveals the Function block's Sandbox selector, and `npx sim-setup doctor` compares it with the selected provider's readiness. Set it only after the selected provider has credentials and a valid immutable Function base configured.
-
-JavaScript without `import` or `require` does not use the remote provider and continues to run in the local isolated VM when all Sandbox flags are off. Python, Shell, JavaScript with external imports, and selected custom Sandboxes fail with an explicit configuration error until the remote Function base is ready.
-
-See [Sandboxes](/platform/self-hosting/sandboxes) for the provider credentials, the Function base-image build, and the promotion procedure.
-
-<Callout type="warn">
-  Data retention is the one feature that deletes data. Its flag controls the cleanup pass, not the settings screen — retention windows are always configurable. Nothing is ever deleted until you enable it, and even then only against windows you configured explicitly. Sim never applies the hosted plan defaults to a self-hosted deployment.
-</Callout>
-
-## Schedule the background jobs
-
-Data drains and retention are started by cron-driven HTTP endpoints rather than by the app on their own schedules. What happens next differs: retention's cleanup runs inline in the app process, while each due data drain is handed to a background job. Every endpoint authenticates with a bearer token equal to `CRON_SECRET` and returns `401` when it is unset:
-
-```bash
-openssl rand -hex 32
-```
-
-Persist that value as `CRON_SECRET` on the app **and** on whatever calls these endpoints. Generating it in a shell configures neither, and a mismatch returns `401`, so the work silently never runs.
-
-| Feature | Endpoint | Suggested schedule | Scheduled for you |
-|---------|----------|--------------------|-------------------|
-| Data drains | `GET /api/cron/run-data-drains` | Hourly | Yes — Helm and Docker Compose both call it |
-| Retention — logs | `GET /api/logs/cleanup` | Daily | **No** — schedule it yourself |
-| Retention — soft deletes | `GET /api/cron/cleanup-soft-deletes` | Daily | **No** — schedule it yourself |
-| Retention — Chat tasks | `GET /api/cron/cleanup-tasks` | Daily | **No** — schedule it yourself |
-| Retention — file versions | `GET /api/cron/cleanup-file-versions` | Daily | **No** — schedule it yourself |
-| OAuth token cleanup | `GET /api/cron/cleanup-oauth-tokens` | Hourly | Yes — Helm and Docker Compose both call it |
-
-<Callout type="warn">
-  Both shipped deployments schedule the data-drain dispatcher and OAuth token cleanup, but **not** the four configurable data-retention endpoints. Setting `DATA_RETENTION_ENABLED=true` alone deletes no retained product data — those windows are evaluated only when one of the four endpoints is called. Add them to `cronjobs.jobs` yourself, or drive them from an external scheduler.
-
-  OAuth token cleanup runs independently of sign-in activity, removing expired and revoked credentials. See [Sign in with Sim](/platform/self-hosting/authentication#sign-in-with-sim) for provider configuration.
-</Callout>
-
-```bash
-curl -H "Authorization: Bearer $CRON_SECRET" \
-  https://sim.example.com/api/logs/cleanup
-```
-
-The two features differ in what they need to run the work. Retention's cleanup dispatcher executes inline when Trigger.dev is not configured, so it completes on a default self-host. Data drains have no inline path: without `TRIGGER_DEV_ENABLED` and a configured Trigger.dev project, each due drain is claimed and enqueued to the database, and nothing drains that queue for this job type. See [background jobs](/platform/self-hosting/background-jobs).
+You can also leave the master switch unset and enable individual features. The [feature flag reference](#feature-flag-reference) lists them all.
 
 ## Choose an organization model
 
-### Pattern 1: one organization for the whole instance
+### One organization for the instance
 
-Best when everyone on the deployment belongs to the same company. Set a name and every user joins that organization automatically at signup, with their workspaces created org-owned.
+Use this when everyone on the deployment belongs to the same company. Set the instance organization's name:
 
 ```bash
 INSTANCE_ORG_NAME="Acme Inc"
 ```
 
-Optionally pin the slug and the owner:
+New accounts join it at signup, and their workspaces are created as organization-owned. Optionally set its slug and an existing account to own it:
 
 ```bash
 INSTANCE_ORG_SLUG=acme-inc
 INSTANCE_ORG_OWNER_EMAIL=admin@acme.com
 ```
 
-The organization is created the first time a user signs up. If `INSTANCE_ORG_OWNER_EMAIL` is not set, or names a user who does not exist yet, the first user to sign up becomes the owner; move ownership later with the Admin API. Provisioning is idempotent and safe across multiple replicas.
-
-<Callout type="info">
-  Instance-organization mode only applies when billing is disabled. With billing enabled, organizations are created through the normal subscription flow and these variables are ignored.
-</Callout>
+The organization is created on the first signup after enabling this mode. If the owner email is unset or does not match an existing account, the account that triggers creation becomes the owner. Transfer ownership later through the Admin API if needed. Creation is idempotent across replicas.
 
-#### Existing deployments
+#### Backfill existing accounts and workspaces
 
-Users and workspaces created before you set `INSTANCE_ORG_NAME` stay where they are. Move them across once with the backfill script, which adds every user to the organization and attaches their workspaces:
+Setting `INSTANCE_ORG_NAME` does not move existing accounts or workspaces. Run the consolidation script from the repository root. If the organization does not exist yet, provide an owner email that matches an **existing Sim account**:
 
 ```bash
-# Preview
-DATABASE_URL=... INSTANCE_ORG_NAME="Acme Inc" \
+# Preview the changes
+DATABASE_URL=... \
+INSTANCE_ORG_NAME="Acme Inc" \
+INSTANCE_ORG_OWNER_EMAIL=admin@acme.com \
   bun run apps/sim/scripts/consolidate-users-into-organization.ts
 
-# Apply
-DATABASE_URL=... INSTANCE_ORG_NAME="Acme Inc" \
+# Apply the same changes
+DATABASE_URL=... \
+INSTANCE_ORG_NAME="Acme Inc" \
+INSTANCE_ORG_OWNER_EMAIL=admin@acme.com \
   bun run apps/sim/scripts/consolidate-users-into-organization.ts --apply
 ```
 
-It is a dry run unless you pass `--apply`, and it is safe to re-run. Users who already belong to a different organization are reported and skipped, since a user can only belong to one.
+The script adds accounts to the organization and attaches their workspaces. It is a dry run unless you pass `--apply`, and is safe to rerun. Accounts already in another organization are reported and skipped because an account can belong to only one organization. When the instance organization already exists, the script uses its current owner.
 
-### Pattern 2: many organizations you manage yourself
+### Separate organizations managed through the Admin API
 
-Best when one deployment serves several teams that should not see each other's data. Leave `INSTANCE_ORG_NAME` unset and provision organizations through the Admin API.
+Leave `INSTANCE_ORG_NAME` unset when one deployment serves multiple teams. Create organizations, add members, and attach workspaces through the Admin API.
+
+Generate an admin key once:
+
+```bash
+openssl rand -hex 32
+```
 
-Set an admin key first:
+Persist that value as `ADMIN_API_KEY` in the **application's environment**, then restart the application. Use the same value in the shell or client issuing the following requests:
 
 ```bash
-ADMIN_API_KEY=$(openssl rand -hex 32)
+ADMIN_API_KEY='<the-same-key-configured-on-the-application>'
 ```
 
+Generating or assigning a value in the caller's shell does not configure the running application. Requests use the exact `x-admin-key` header.
+
 <Steps>
 <Step>
 ### Create an organization
 
-The owner must not already belong to another organization.
+The owner account must exist and must not belong to another organization.
 
 ```bash
 curl -X POST https://sim.example.com/api/v1/admin/organizations \
@@ -164,6 +102,8 @@ curl -X POST https://sim.example.com/api/v1/admin/organizations \
   -H "Content-Type: application/json" \
   -d '{"name": "Acme Inc", "ownerId": "user_123", "slug": "acme-inc"}'
 ```
+
+Use the returned organization ID as `ORG_ID` in subsequent commands. Creating the organization does not attach a workspace.
 </Step>
 
 <Step>
@@ -178,25 +118,34 @@ curl -X POST https://sim.example.com/api/v1/admin/organizations/$ORG_ID/members
 </Step>
 
 <Step>
-### Move a workspace into the organization
+### Attach a workspace
 
-Organization-scoped features only apply to workspaces the organization owns.
+Enterprise settings apply only to workspaces the organization owns. Generate a fresh UUID for each new move. From the repository root:
 
 ```bash
+OPERATION_ID=$(bun -e 'import { generateId } from "@sim/utils/id"; process.stdout.write(generateId())')
+
 curl -X POST https://sim.example.com/api/v1/admin/dashboard/workspaces/$WORKSPACE_ID/move \
   -H "x-admin-key: $ADMIN_API_KEY" \
   -H "Content-Type: application/json" \
-  -d "{\"destinationOrganizationId\": \"$ORG_ID\"}"
+  -d "{\"operationId\": \"$OPERATION_ID\", \"destinationOrganizationId\": \"$ORG_ID\"}"
+```
+
+Keep the same `OPERATION_ID` when retrying this move; generate a new one only for a new operation. Inspect `data.followUpJobs` in the response for pending or failed follow-up work. Check it again with:
+
+```bash
+curl "https://sim.example.com/api/v1/admin/dashboard/workspaces/$WORKSPACE_ID/move-operations/$OPERATION_ID?destinationOrganizationId=$ORG_ID" \
+  -H "x-admin-key: $ADMIN_API_KEY"
 ```
 </Step>
 
 <Step>
 ### Configure organization settings
 
-Branding, retention, and session policies can be set from the API instead of the UI.
+Use the Settings UI or these API requests:
 
-<Tabs items={['Whitelabel', 'Data retention', 'Session policy']}>
-<Tab value="Whitelabel">
+<Tabs items={['Branding', 'Data retention', 'Session policy']}>
+<Tab value="Branding">
 ```bash
 curl -X PATCH https://sim.example.com/api/v1/admin/organizations/$ORG_ID/whitelabel \
   -H "x-admin-key: $ADMIN_API_KEY" \
@@ -224,57 +173,127 @@ curl -X PATCH https://sim.example.com/api/v1/admin/organizations/$ORG_ID/session
 </Step>
 </Steps>
 
-### Reading enterprise data with the admin key
+When invitations are disabled with `DISABLE_INVITATIONS` and `NEXT_PUBLIC_DISABLE_INVITATIONS`, use the Admin API to manage organization membership and workspace access. Internal members join the organization. External workspace members receive access to a specific workspace without joining the organization.
+
+### Read audit logs and permission groups
 
-Two enterprise reads have admin-key equivalents that need no organization and no Enterprise plan, which is what makes them usable on a billing-free deployment:
+Admin-key reads do not require an organization or Enterprise subscription:
 
 ```bash
-# Audit log entries across the whole deployment, with the same filters as the UI
+# Deployment audit entries, with filters also available in the UI
 curl "https://sim.example.com/api/v1/admin/audit-logs?limit=50&workspaceId=$WORKSPACE_ID" \
   -H "x-admin-key: $ADMIN_API_KEY"
 
-# A single entry
+# One audit entry
 curl "https://sim.example.com/api/v1/admin/audit-logs/$AUDIT_LOG_ID" \
   -H "x-admin-key: $ADMIN_API_KEY"
 
-# Permission groups, optionally scoped to one organization
+# Permission groups, optionally scoped to an organization
 curl "https://sim.example.com/api/v1/admin/access-control?organizationId=$ORG_ID" \
   -H "x-admin-key: $ADMIN_API_KEY"
 ```
 
-The organization-scoped `/api/v1/audit-logs` endpoint documented in the [audit logs guide](/platform/enterprise/audit-logs) needs an API key whose owner is an admin or owner of an organization, so reach for the admin endpoints when no organization exists yet.
+The organization-scoped `/api/v1/audit-logs` endpoint uses an API key whose owner is an organization admin or owner. Use the admin endpoint when no organization exists yet. See [Audit logs](/platform/enterprise/audit-logs).
 
-Deleting an organization requires echoing its slug, because the delete cascades to members, invitations, and permission groups, and detaches its workspaces:
+### Delete an organization
+
+Deleting an organization removes its memberships, invitations, permission groups, and organization settings. Its workspaces are detached and survive. A non-terminal subscription prevents deletion; cancel it first.
+
+Confirm the target by passing its exact slug:
 
 ```bash
 curl -X DELETE "https://sim.example.com/api/v1/admin/organizations/$ORG_ID?confirmSlug=acme-inc" \
   -H "x-admin-key: $ADMIN_API_KEY"
 ```
 
-## Verifying it worked
+## Schedule the background jobs
 
-If a feature is enabled but nothing appears, check these in order.
+Configure a scheduler to call the maintenance endpoints. Generate a cron secret:
 
-**The settings section is missing.** The server-side variable is not set, or the app was not restarted after adding it. Variables are read at boot from the container environment, so a restart is enough — no rebuild.
+```bash
+openssl rand -hex 32
+```
 
-**Settings → Sandboxes shows an upgrade notice instead of the sandbox list.** The Sandbox entitlement resolves off — `SANDBOXES_ENABLED=false`, or `SANDBOXES_ENABLED` unset without the `ENTERPRISE_ENABLED` master switch — or the selected provider failed the server's readiness check: missing credentials, or a Function base that is not an immutable reference. The page stays in the sidebar either way. See [Sandboxes](/platform/self-hosting/sandboxes).
+Persist the same value as `CRON_SECRET` on the application and its scheduler. Each endpoint requires `Authorization: Bearer <CRON_SECRET>` and returns `401` if the secret is unset or does not match.
 
-**The section appears but the login page has no SSO option, or the Function block has no Sandbox selector.** The `NEXT_PUBLIC_` twin is unset or `false` while the server-side feature resolves on. A workspace follows the server, but the login page renders before any workspace loads and reads the twin, and the Sandbox selector does too. Set both. On a Compose install or source checkout, `npx sim-setup doctor` reports a twin that disagrees with its server flag; for Sandboxes it compares `NEXT_PUBLIC_SANDBOXES_ENABLED` with the selected provider's readiness instead.
+| Feature | Endpoint | Suggested schedule | Included in Helm and production Compose schedules |
+| --- | --- | --- | --- |
+| Data drains | `GET /api/cron/run-data-drains` | Hourly | Yes |
+| SCIM reconciliation | `GET /api/cron/scim-reconcile` | Hourly | Yes |
+| Retention: logs | `GET /api/logs/cleanup` | Daily | No |
+| Retention: soft deletes | `GET /api/cron/cleanup-soft-deletes` | Daily | No |
+| Retention: Chat tasks | `GET /api/cron/cleanup-tasks` | Daily | No |
+| Retention: file versions | `GET /api/cron/cleanup-file-versions` | Daily | No |
+| OAuth token cleanup | `GET /api/cron/cleanup-oauth-tokens` | Hourly | Yes |
 
-**The feature is on but has no effect inside a workspace.** The workspace is not owned by an organization. Check `workspace_mode` and `organization_id`:
+Included schedules still require the cron service to be configured and running. For an external scheduler, a request looks like:
+
+```bash
+curl -H "Authorization: Bearer $CRON_SECRET" \
+  https://sim.example.com/api/logs/cleanup
+```
+
+<Callout type="warn">
+  Configuring retention windows and enabling deletion are separate actions. Set `DATA_RETENTION_ENABLED=true` to allow retention cleanup, and schedule the four retention endpoints yourself, for example through Helm's `cronjobs.jobs`. Neither the flag alone nor the shipped cron schedules expire retained product data. Billing-disabled deployments use only explicitly configured windows, without hosted-plan defaults.
+</Callout>
+
+Retention and data-drain work use the configured job backend. Without Trigger.dev, they have in-process execution paths; with Trigger.dev configured, external workers run the jobs. SCIM reconciliation runs directly through its authenticated cron endpoint and does not require Trigger.dev. See [Background jobs](/platform/self-hosting/background-jobs) for operational setup and [Data retention](/platform/enterprise/data-retention) for effective policy.
+
+OAuth token cleanup removes expired and revoked credentials independently of sign-in activity. See [Sign in with Sim](/platform/self-hosting/authentication#sign-in-with-sim) for provider configuration.
+
+## Feature flag reference
+
+Explicit individual flags override the master switch, including when set to `false`. With billing disabled and no enterprise flags set, custom branding, session policies, and the Sim Mailer inbox remain enabled by default. Other features require opt-in.
+
+| Feature | Server variable | Browser variable |
+| --- | --- | --- |
+| Enterprise suite | `ENTERPRISE_ENABLED` | `NEXT_PUBLIC_ENTERPRISE_ENABLED` |
+| Organizations | `ORGANIZATIONS_ENABLED` | `NEXT_PUBLIC_ORGANIZATIONS_ENABLED` |
+| Permission groups | `ACCESS_CONTROL_ENABLED` | `NEXT_PUBLIC_ACCESS_CONTROL_ENABLED` |
+| SAML and OIDC sign-in | `SSO_ENABLED` | `NEXT_PUBLIC_SSO_ENABLED` |
+| Directory provisioning | `SCIM_ENABLED` | `NEXT_PUBLIC_SCIM_ENABLED` |
+| Custom branding — enabled by default | `WHITELABELING_ENABLED` | `NEXT_PUBLIC_WHITELABELING_ENABLED` |
+| Audit logs | `AUDIT_LOGS_ENABLED` | `NEXT_PUBLIC_AUDIT_LOGS_ENABLED` |
+| Insights | `USAGE_MONITORING_ENABLED` | `NEXT_PUBLIC_USAGE_MONITORING_ENABLED` |
+| Custom blocks | `CUSTOM_BLOCKS_ENABLED` | `NEXT_PUBLIC_CUSTOM_BLOCKS_ENABLED` |
+| Session policies — enabled by default | `SESSION_POLICIES_ENABLED` | `NEXT_PUBLIC_SESSION_POLICIES_ENABLED` |
+| Retention deletion | `DATA_RETENTION_ENABLED` | `NEXT_PUBLIC_DATA_RETENTION_ENABLED` |
+| Data drains | `DATA_DRAINS_ENABLED` | `NEXT_PUBLIC_DATA_DRAINS_ENABLED` |
+| Credential groups | `CREDENTIAL_GROUPS` | — |
+| Workspace forks | `FORKING_ENABLED` | `NEXT_PUBLIC_FORKING_ENABLED` |
+| Sim Mailer inbox — enabled by default | `INBOX_ENABLED` | `NEXT_PUBLIC_INBOX_ENABLED` |
+| Sandboxes | `SANDBOXES_ENABLED` | `NEXT_PUBLIC_SANDBOXES_ENABLED` |
+
+### Sandbox readiness
+
+A Sandbox entitlement also requires a remote execution provider with credentials and an immutable Function base image. Until the server verifies readiness, the Function block offers no **Shell** language, and **Settings → Sandboxes** shows an upgrade notice instead of a sandbox list.
+
+`NEXT_PUBLIC_SANDBOXES_ENABLED` exposes the Function block's **Sandbox** selector; it asserts readiness rather than checking it. Set it only after configuring the selected provider and Function base. `bunx sim-setup doctor` compares it with provider readiness.
+
+JavaScript without `import`, `require`, a selected sandbox, or a sandbox file-path reference runs in local Node child workers in the app container when Sandbox flags are off. Python, Shell, JavaScript with external imports, and selected custom Sandboxes require the remote Function base and fail with a configuration error until it is ready. See [Sandboxes](/platform/self-hosting/sandboxes).
+
+## Verify the setup
+
+| Symptom | Check |
+| --- | --- |
+| A settings section is missing | Check its server flag and restart the app after changing environment variables. These values load at boot; a rebuild is not needed. |
+| The login page has no SSO option, or Function has no Sandbox selector | Set the matching `NEXT_PUBLIC_` flag. Run `bunx sim-setup doctor` to check twins and Sandbox readiness. |
+| **Settings → Sandboxes** shows an upgrade notice | Check Sandbox entitlement, provider credentials, and the immutable Function base. |
+| An enabled feature has no effect in a workspace | Confirm that the workspace belongs to an organization. Use the backfill or workspace move procedure if needed. |
+| Retention deletes nothing | Check `DATA_RETENTION_ENABLED`, explicit windows, scheduler requests, and `CRON_SECRET`. |
+
+To inspect workspace ownership:
 
 ```sql
 SELECT id, name, workspace_mode, organization_id FROM workspace;
 ```
 
-A workspace showing `personal` or a null `organization_id` will not pick up branding, PII redaction, permission groups, or drains. Use the backfill script or the workspace move endpoint.
-
-**Retention is configured but nothing is deleted.** Either `DATA_RETENTION_ENABLED` is unset — configuring windows and running the cleanup pass are separate switches by design — or nothing is calling the cleanup endpoints. The Helm chart does not schedule them; see [Schedule the background jobs](#schedule-the-background-jobs).
+A workspace with `personal` mode or a null `organization_id` does not inherit organization branding, PII redaction, permission groups, or drains.
 
-## Related
+## Related docs
 
 - [Environment variables](/platform/self-hosting/environment-variables)
-- [Single Sign-On](/platform/enterprise/sso)
-- [Access control](/platform/enterprise/access-control)
+- [Single sign-on](/platform/enterprise/sso)
+- [Permission groups](/platform/enterprise/access-control)
 - [Roles and permissions](/platform/permissions)
 - [Workspaces](/platform/workspaces)
diff --git a/apps/docs/content/docs/platform/enterprise/session-policies.mdx b/apps/docs/content/docs/platform/enterprise/session-policies.mdx
index b4b0d4267dd..c38b5cc2d2f 100644
--- a/apps/docs/content/docs/platform/enterprise/session-policies.mdx
+++ b/apps/docs/content/docs/platform/enterprise/session-policies.mdx
@@ -1,76 +1,41 @@
 ---
-title: Session Policies
-description: Set session lifetime limits and sign out every member of your organization at once
+title: Session policies
+description: Limit member session lifetimes and revoke organization sessions
 ---
 
-import { FAQ } from '@/components/ui/faq'
+Session policies control how long organization members stay signed in. Organization owners and admins can configure them on Enterprise plans, or on self-hosted deployments where session policies are enabled.
 
-Session Policies let organization owners and admins on Enterprise plans control how long member sign-in sessions last, and sign out every member org-wide in one action. Policies apply to every member of the organization on every device.
+The limits apply to member sign-in sessions across devices, including SSO sessions. Your identity provider can enforce additional session rules.
 
----
-
-## Setup
-
-Go to **Settings → Security → Session policies** in your organization settings.
-
-Both limits are optional. Leave a field empty to keep the default behavior: sessions last 30 days and extend automatically while a member stays active.
-
----
-
-## Settings
+## Set session limits
 
-### Max session lifetime
+Open **Settings → Organization → Security → Session policies**. Enter whole numbers in hours, then select **Save**. **Discard** restores the saved values.
 
-Caps how long a session can exist from the moment a member signs in, regardless of activity. When the limit is reached, the member must sign in again.
+| Setting | Behavior | Accepted values |
+| --- | --- | --- |
+| **Max session lifetime (hours)** | Caps a session's age from sign-in, regardless of activity. A value of `168` requires sign-in again at least weekly. | 1–8760 hours |
+| **Idle timeout (hours)** | Expires a session after inactivity. Activity refreshes the session within any maximum lifetime. | 48–8760 hours |
 
-Use this to enforce periodic re-authentication — for example, a value of `168` requires everyone to sign in again at least weekly. Accepts 1 to 8760 hours (1 year).
+Both fields are optional. Leaving a field empty removes that organization limit. With neither limit set, sessions use the default 30-day sliding expiry and extend automatically while a member stays active.
 
-### Idle timeout
+The idle minimum is 48 hours because session activity refreshes are recorded at most once every 24 hours. A shorter limit could expire a session while its member is actively using Sim.
 
-Signs a member out after this many hours without activity. Activity extends the session, so members who use Sim regularly stay signed in; dormant sessions expire.
-
-Accepts 48 to 8760 hours. The 48-hour minimum exists because session activity is recorded at most once per day — a shorter window could sign out members who are actively working.
+## How enforcement works
 
-### Sign out all members
+- New sign-ins receive an expiry constrained by the current policy.
+- Saving a tighter policy shortens existing member sessions. Changes reach other application instances within about a minute.
+- Saving a looser policy does not immediately extend stored session expiries. Later session refreshes and new sign-ins use the current limits.
 
-The **Sign out all members** action immediately revokes every member session in the organization except your own. Members are signed out on their next request — typically within a minute — and must sign in again.
+When a session expires, the member must sign in again on their next request. Workflow changes that have already synced remain saved; don't rely on session recovery to preserve an edit that has not synced.
 
-Use this after a security incident, an offboarding wave, or before tightening a policy you want to take effect everywhere at once.
+## Sign out all members
 
----
+Use **Sign out all members** after a security incident or when you need members to authenticate again. Confirm the action to revoke the organization's member sessions, except **your current session**. Your sessions on other devices are also revoked.
 
-## How enforcement works
-
-- **New sign-ins** get an expiry that respects the policy from the moment the session is created.
-- **Existing sessions** are shortened immediately when you save a tighter policy — no member keeps a longer session than the new policy allows.
-- **Loosening a policy never extends existing sessions.** Members pick up the longer limit the next time they sign in.
-- Changes propagate to active members within about a minute; there is no need to redeploy or wait for sessions to naturally expire.
-
----
+Members must sign in again on their next request, typically within a minute. Revocation affects sign-in sessions only: API keys, deployed workflows, webhooks, and schedules keep working. Manage those credentials and resources separately when offboarding a member or responding to an incident.
 
-## FAQ
+## Related docs
 
-<FAQ
-  items={[
-    {
-      question: 'Do session policies apply to SSO sign-ins?',
-      answer:
-        'Yes. Sessions created through SSO follow the same lifetime and idle limits as any other sign-in method. Your identity provider may enforce its own, stricter session rules on top.',
-    },
-    {
-      question: 'What happens to a member who is working when their session expires?',
-      answer:
-        'They are redirected to sign in again on their next request. Unsaved workflow changes in the editor are preserved by the collaborative editor, which continuously syncs edits.',
-    },
-    {
-      question: 'Does "Sign out all members" affect API keys or running workflows?',
-      answer:
-        'No. It revokes browser sign-in sessions only. API keys, deployed workflows, webhooks, and schedules keep working — manage those separately from the API keys settings.',
-    },
-    {
-      question: 'Why is the minimum idle timeout 48 hours?',
-      answer:
-        'Session activity is recorded at most once per 24 hours for performance. The minimum is twice that window so a member who stays active always registers activity before the idle limit can expire their session.',
-    },
-  ]}
-/>
+- [Single sign-on](/platform/enterprise/sso)
+- [Directory provisioning](/platform/enterprise/scim)
+- [Self-hosted enterprise](/platform/enterprise/self-hosted)
diff --git a/apps/docs/content/docs/platform/enterprise/sso.mdx b/apps/docs/content/docs/platform/enterprise/sso.mdx
index 501115becd7..289016189dd 100644
--- a/apps/docs/content/docs/platform/enterprise/sso.mdx
+++ b/apps/docs/content/docs/platform/enterprise/sso.mdx
@@ -1,466 +1,363 @@
 ---
-title: Single Sign-On (SSO)
-description: Configure SAML 2.0 or OIDC-based single sign-on for your organization
+title: Single sign-on (SSO)
+description: Configure SAML or OpenID Connect sign-in for your organization
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { FAQ } from '@/components/ui/faq'
-import { Image } from '@/components/ui/image'
+import { TabsList, TabsTrigger } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 
-Single Sign-On lets your team sign in to Sim through your company's identity provider instead of managing separate passwords. Sim supports both OIDC and SAML 2.0, and an organization can use more than one identity provider at a time.
+Single sign-on (SSO) lets members authenticate through your organization's identity provider. Sim supports OpenID Connect (OIDC) and SAML 2.0, with multiple providers per organization.
 
----
+SSO authenticates accounts. First-sign-in provisioning can add organization membership, but workspace access is granted separately. Use [directory provisioning](/platform/enterprise/scim) to manage members and group-based access from your directory.
 
 ## Before you start
 
-<Callout type="warn">
-  [Verify your email domain](/platform/enterprise/verified-domains) first. SSO cannot be saved until the domain shows as **Verified**, and DNS changes take time to propagate.
+- On Sim Cloud, use an Enterprise organization and an organization owner or admin account.
+- On self-hosted deployments, enable the [SSO flags](#self-hosted-setup) and create an organization.
+- [Verify the email domain](/platform/enterprise/verified-domains) before saving its provider.
+- Choose a **Provider ID** before configuring the identity provider. It is globally unique across Sim organizations, appears in callback URLs, and cannot be changed after saving. Use an organization-specific ID such as `acme-okta`.
 
-  The verified domain is what authorizes your identity provider. Removing it later immediately disables SSO sign-in for everyone on that domain until it is verified again.
+<Callout type="warn">
+  Domain verification authorizes your identity provider to sign in accounts on that domain. Removing the verified domain in Sim stops new SSO sign-ins through its providers until verification is restored. It does not end existing sessions.
 </Callout>
 
-Decide your **Provider ID** before configuring your identity provider. It becomes part of the callback URL you register there, and it is **fixed once saved** — changing it later means deleting the provider and setting it up again.
-
----
-
-## Setup
-
-### 1. Open SSO settings
+## Configure a provider
 
-Go to **Settings → Organization → Single sign-on**. The page has three tabs:
+Open **Settings → Organization → Single sign-on**. The page has these tabs:
 
-| Tab | Manage |
+| Tab | Configure |
 | --- | --- |
-| **Sign-in** | OIDC or SAML configuration, callback URLs, and first-sign-in membership |
-| **Domains** | DNS verification shared by SSO and SCIM |
+| **Sign-in** | Identity providers, callback URLs, first-sign-in membership, and allowed sign-in methods |
+| **Domains** | Domain ownership shared by SSO and SCIM |
 | **Provisioning** | SCIM connection, tokens, rules, group mappings, and activity |
 
-Use **Domains** to verify ownership, then return to **Sign-in** to configure your provider. Switching tabs preserves an unsaved sign-in draft while you stay on this page; use **Save** or **Update** to commit it. The selected tab and provider are included in the URL, so they can be bookmarked or shared. On self-hosted deployments, Provisioning appears when SCIM is enabled.
+On self-hosted deployments, **Provisioning** appears when SCIM is enabled. Switching tabs preserves an unsaved sign-in draft while you remain on this page. Select **Save** or **Update** to commit changes. The selected tab and provider are in the URL, so you can bookmark or share them.
 
-An organization can run several identity providers at once: Okta for `eng.acme.com` and Microsoft Entra ID for `acme.com`, for example. **Sign-in** lists them; select **Add identity provider** for another, or a row to view, edit, or delete one. Sim routes each sign-in by the email domain. When a domain has more than one provider, the one marked **Primary** is used, which is how you [switch identity providers](#switching-identity-providers) without downtime.
+Under **Sign-in**, select **Add identity provider**, or select an existing provider to view it. Use **Domains** to verify ownership first.
 
-### 2. Choose a protocol
+### Choose a protocol
 
-| Protocol | Use when |
-|----------|----------|
-| **OIDC** | Your IdP supports OpenID Connect — Okta, Microsoft Entra ID, Auth0, Google Workspace |
-| **SAML 2.0** | Your IdP is SAML-only — ADFS, Shibboleth, or older enterprise IdPs |
+Use OIDC when your provider supports OpenID Connect, or SAML 2.0 for a SAML connection. The provider guides below cover Okta, Microsoft Entra ID, Google Workspace, and AD FS.
 
-### 3. Fill in the form
+### Enter the required fields
 
-<Image src="/static/enterprise/sso-form.png" alt="Sign-in tab showing the OIDC configuration form with advanced options collapsed" width={832} height={1095} className="mx-auto h-auto w-full max-w-md" />
-
-**Fields required for both protocols:**
-
-| Field | What to enter |
-|-------|--------------|
-| **Provider ID** | A short slug identifying this connection. Letters, numbers, and dashes only. It must be **unique across every Sim organization**, so include something specific to you, such as `azure-ad-acme`. If the ID is taken, Sim asks you to choose another. |
-| **Issuer URL** | The identity provider's issuer URL. Must be HTTPS. |
-| **Domain** | Your organization's email domain, e.g. `company.com`. Users with this domain will be routed through SSO at sign-in. |
-| **First sign-in → On first SSO sign-in** | **Automatic** adds a user authenticated through this verified SSO connection to the organization as a Member and consumes a billed seat. Team seat counts grow with membership; fixed-seat plans require available capacity. **Invite only** authenticates the user without creating organization membership. Neither mode grants workspace access automatically. |
-
-**OIDC additional fields:**
+| Field | Value |
+| --- | --- |
+| **Provider ID** | Letters, numbers, and dashes only. Choose a globally unique ID, such as `acme-okta`. Sim rejects an ID already used by another organization. |
+| **Issuer URL** | Your identity provider's HTTPS issuer URL |
+| **Domain** | The verified email domain served by this connection, such as `acme.com` |
+| **On first SSO sign-in** | **Automatic** adds new organization members; **Invite only** authenticates without adding membership. See [membership behavior](#membership-and-account-linking). |
 
-| Field | What to enter |
-|-------|--------------|
-| **Client ID** | The application client ID from your IdP. |
-| **Client secret** | The client secret from your IdP. |
-| **Scopes** | Under **Advanced options**. Comma-separated OIDC scopes; default: `openid,profile,email`. |
+For OIDC, also enter **Client ID** and **Client secret**. Sim discovers authorization, token, UserInfo, and JWKS endpoints from `{issuer}/.well-known/openid-configuration`. Under **Advanced options**, you can set **Scopes** (default `openid,profile,email`) and override authorization, token, or JWKS endpoints if discovery does not supply usable values.
 
-<Callout type="info">
-  For OIDC, Sim automatically fetches endpoints (`authorization_endpoint`, `token_endpoint`, `userinfo_endpoint`, `jwks_uri`) from your issuer's `/.well-known/openid-configuration` discovery document. You only need to provide the issuer URL.
-</Callout>
+For SAML, also enter **Entry point URL**, the provider's SSO service URL, and **Identity provider certificate**, its Base64 X.509 certificate. Under **Advanced options**, you can configure Audience, Callback URL override, signed-assertion requirements, NameID format, and IdP metadata XML. Metadata does not replace the required certificate.
 
-**SAML additional fields:**
+**Attribute mapping** lets either protocol override the email, name, and stable user-ID claim names. Leave a mapping blank to use the protocol default.
 
-| Field | What to enter |
-|-------|--------------|
-| **Entry point URL** | The IdP's SSO service URL where Sim sends authentication requests. |
-| **Identity provider certificate** | The Base-64 encoded X.509 certificate from your IdP for verifying assertions. |
+### Register the callback URL
 
-### 4. Copy the callback URL
+Copy **Callback URL** for OIDC or **ACS URL (Reply URL)** for SAML, then register it in your identity provider:
 
-Copy **Callback URL** for OIDC or **ACS URL (Reply URL)** for SAML. This is the endpoint that receives your identity provider's authentication response. Register it in your IdP before saving. On Sim Cloud, `<your-sim-domain>` is `www.sim.ai`; self-hosted deployments use their own domain. If you set a SAML **Callback URL override** under Advanced options, the copyable ACS URL uses that override.
-
-**OIDC providers** (Okta, Microsoft Entra ID, Google Workspace, Auth0):
-```
-https://<your-sim-domain>/api/auth/sso/callback/{provider-id}
-```
+| Protocol | Callback format |
+| --- | --- |
+| OIDC | `https://<your-sim-domain>/api/auth/sso/callback/{provider-id}` |
+| SAML | `https://<your-sim-domain>/api/auth/sso/saml2/callback/{provider-id}` |
 
-**SAML providers** (ADFS, Shibboleth):
-```
-https://<your-sim-domain>/api/auth/sso/saml2/callback/{provider-id}
-```
+Sim Cloud uses `www.sim.ai`; self-hosted deployments use their public domain. Use your chosen **Provider ID** in both systems. For SAML, register the **SP Entity ID** as the provider's audience/Entity ID. If you set a **Callback URL override**, Sim's copyable ACS URL uses that override.
 
-### 5. Save and test
+## Provider guides
 
-Click **Save**. To test, sign out and use the **Sign in with SSO** button on the login page. Enter an email address at your configured domain — Sim will redirect you to your identity provider.
+<Tabs updateAnchor defaultValue="okta">
+<TabsList>
+  <TabsTrigger value="okta" aria-controls="okta">Okta (OIDC)</TabsTrigger>
+  <TabsTrigger value="microsoft-entra-id-with-oidc" aria-controls="microsoft-entra-id-with-oidc">Microsoft Entra ID (OIDC)</TabsTrigger>
+  <TabsTrigger value="microsoft-entra-id-with-saml" aria-controls="microsoft-entra-id-with-saml">Microsoft Entra ID (SAML)</TabsTrigger>
+  <TabsTrigger value="google-workspace" aria-controls="google-workspace">Google Workspace (OIDC)</TabsTrigger>
+  <TabsTrigger value="ad-fs" aria-controls="ad-fs">AD FS (SAML)</TabsTrigger>
+</TabsList>
+<Tab value="okta" id="okta">
 
----
+1. In the Okta Admin Console, open **Applications and Resources → Applications → Create App Integration**. These steps use **Classic experience**; select **OIDC - OpenID Connect**, then **Web Application**.
+2. Set **Sign-in redirect URI** to your chosen Sim callback:
+   ```
+   https://<your-sim-domain>/api/auth/sso/callback/acme-okta
+   ```
+3. Under **Assignments**, grant access to the people or groups who should sign in.
+4. Copy **Client ID** and **Client Secret** from **General**.
+5. Copy your Okta organization domain from the Admin Console account menu, for example `dev-1234567.okta.com`. Do not use its `-admin` hostname.
 
-## Editing and advanced configuration
+| Sim field | Value |
+| --- | --- |
+| **Provider type** | OIDC |
+| **Provider ID** | `acme-okta` |
+| **Issuer URL** | `https://dev-1234567.okta.com` |
+| **Domain** | `acme.com` |
+| **Client ID** | From the Okta app |
+| **Client secret** | From the Okta app |
 
-For a saved connection, open **Sign-in**, select the provider, and select **Edit**. The Provider ID remains fixed. **Delete** removes that sign-in path only: accounts and memberships it admitted stay. If you delete the primary provider and the domain has another verified provider, that one becomes primary; otherwise people at the domain sign in another way until a provider serves it again. A saved OIDC client secret appears as a mask with a suffix when available; **Replace** lets you enter a new secret, and **Keep saved** cancels that replacement. Select **Update** to save the provider, or **Discard** to abandon changes.
+Use the organization issuer for ordinary sign-in. A custom authorization server requires API Access Management and uses `https://<your-okta-domain>/oauth2/<authorization-server-id>`. The `default` custom server is included in the Integrator Free Plan but not every production organization. See [Okta authorization servers](https://developer.okta.com/docs/concepts/auth-servers/) and [Find your Okta domain](https://developer.okta.com/docs/guides/find-your-domain/main/).
 
-**Advanced options** contains OIDC scopes and optional authorization, token, and JWKS endpoint overrides. For SAML, it contains Audience, Callback URL override, signed-assertion requirements, NameID format, and optional IdP metadata XML. **Attribute mapping** lets either protocol override the email, name, and stable user-ID claim names. Leave a mapping blank to use the protocol default.
+To launch Sim from an Okta dashboard tile, set **Login initiated by** to **Either Okta or App**, show the icon, and choose the flow that redirects to the app to initiate OIDC login. Set **Initiate login URI** to the saved provider's **Initiate login URL** from Sim:
 
-SCIM settings save immediately in the **Provisioning** tab. Its **Disable just-in-time provisioning** rule overrides Automatic first-sign-in membership while the connection is active and entitled. Existing members can still sign in. See [directory provisioning](/platform/enterprise/scim#provisioning-and-sso-together).
+```
+https://<your-sim-domain>/sso/launch/acme-okta
+```
 
-Follow the [Okta](/platform/enterprise/scim/okta) or [Microsoft Entra](/platform/enterprise/scim/entra) provisioning walkthrough to connect a SCIM app and verify synchronization separately from sign-in.
+See [Okta OIDC setup](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm). For SCIM, the creation experience matters: Classic OIDC apps need a separate provisioning integration, while the newer Okta Integration Wizard can support SCIM on OIDC. See [Okta provisioning](/platform/enterprise/scim/okta).
 
-## Switching identity providers
+</Tab>
+<Tab value="microsoft-entra-id-with-oidc" id="microsoft-entra-id-with-oidc">
 
-To move a domain from one identity provider to another, for example from Microsoft Entra ID to Okta, set up the new provider next to the current one and switch when it works. Nobody loses access along the way.
+1. Open **Microsoft Entra ID → App registrations → New registration**.
+2. Under **Redirect URI**, select **Web** and enter:
+   ```
+   https://<your-sim-domain>/api/auth/sso/callback/acme-entra
+   ```
+3. Open **Certificates & secrets → New client secret**. Copy the secret value immediately; it is shown once.
+4. From **Overview**, copy **Application (client) ID** and **Directory (tenant) ID**.
+5. Keep `email` in Sim's OIDC scopes. You can also request **email** under **Token configuration → Add optional claim → ID**. Confirm that the account supplies an email in your verified domain: a user principal name is not necessarily that address, and the email claim is not guaranteed for every account.
+6. If **Enterprise applications → your app → Properties → Assignment required** is **Yes**, assign the people or groups who should sign in. Entra rejects unassigned accounts before they reach Sim.
 
-1. **Add the new provider** under **Sign-in** with the same verified domain. It is saved alongside the current provider, which stays **Primary**, so sign-in does not change yet.
-2. **Test it.** Open the new provider and copy its **Test sign-in link**. Anyone at the domain who opens the link signs in through the new provider; everyone else still uses the current one.
-3. **Make it primary.** Select **Make primary** on the new provider. From their next sign-in, everyone at the domain goes through it. People already signed in stay signed in.
-4. **Remove the old provider** once you are confident, or keep it to switch back with **Make primary**.
+| Sim field | Value |
+| --- | --- |
+| **Provider type** | OIDC |
+| **Provider ID** | `acme-entra` |
+| **Issuer URL** | `https://login.microsoftonline.com/{tenant-id}/v2.0` |
+| **Domain** | `acme.com` |
+| **Client ID** | Application (client) ID |
+| **Client secret** | Secret value |
 
-The first time someone signs in through the new provider, Sim links it to their existing account by email address, so their workspaces and membership carry over. This requires the new provider to send the same email addresses as the old one.
+See [Microsoft app registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) and [ID token claims](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference).
 
----
+</Tab>
+<Tab value="microsoft-entra-id-with-saml" id="microsoft-entra-id-with-saml">
 
-## Provider Guides
+1. Open **Enterprise applications → New application → Create your own application**. Choose **Integrate any other application you don't find in the gallery**.
+2. Open **Single sign-on** and select **SAML**.
+3. In **Basic SAML Configuration**, set **Identifier (Entity ID)** to Sim's **SP Entity ID**, and **Reply URL (Assertion Consumer Service URL)** to Sim's **ACS URL (Reply URL)**.
+4. Under **Attributes & Claims**, retain the standard schema claim URIs for email, name, and name identifier, or configure matching **Attribute mapping** in Sim.
+5. Under **SAML Certificates**, download **Certificate (Base64)** for Sim's required certificate field. You can also download **Federation Metadata XML** for **IdP metadata XML** under Advanced options; it does not replace the certificate.
+6. From the application's **Set up** panel, copy **Login URL** and **Microsoft Entra Identifier**.
+7. Under **Users and groups**, assign the people who should sign in. Entra rejects unassigned accounts before they reach Sim.
 
-<Tabs items={['Okta', 'Microsoft Entra ID', 'Microsoft Entra ID (SAML)', 'Google Workspace', 'ADFS']}>
+| Sim field | Value |
+| --- | --- |
+| **Provider type** | SAML |
+| **Provider ID** | `acme-entra-saml` |
+| **Issuer URL** | Microsoft Entra Identifier, such as `https://sts.windows.net/{tenant-id}/` |
+| **Domain** | `acme.com` |
+| **Entry point URL** | Login URL |
+| **Identity provider certificate** | Contents of Certificate (Base64) |
 
-<Tab value="Okta">
+<Callout type="warn">
+  The Entity ID registered in Entra must match Sim's **SP Entity ID** exactly. Sim validates the assertion's audience against it; a mismatch prevents sign-in.
+</Callout>
 
-### Okta (OIDC)
+See [Microsoft SAML setup](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso).
 
-**In Okta** ([official docs](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm)):
+</Tab>
+<Tab value="google-workspace" id="google-workspace">
 
-1. Go to **Applications → Create App Integration**
-2. Select **OIDC - OpenID Connect**, then **Web Application**
-3. Set the **Sign-in redirect URI** to your Sim callback URL:
+1. In Google Cloud Console, configure **Google Auth platform → Audience** as **Internal** if sign-in should be restricted to your Google Workspace organization. Branding and consent settings live under **Google Auth platform → Branding**.
+2. Open **APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID** and choose **Web application**.
+3. Add this **Authorized redirect URI**:
    ```
-   https://<your-sim-domain>/api/auth/sso/callback/okta
+   https://<your-sim-domain>/api/auth/sso/callback/acme-google
    ```
-4. Under **Assignments**, grant access to the relevant users or groups
-5. Copy the **Client ID** and **Client Secret** from the app's **General** tab
-6. To open Sim from the Okta dashboard, set **Login initiated by** to **Either Okta or App**, show the app icon to users, choose **Redirect to app to initiate login (OIDC Compliant)**, and set **Initiate login URI** to the provider's **Initiate login URL** from Sim:
-   ```
-   https://<your-sim-domain>/sso/launch/okta
-   ```
-7. Copy your Okta organization domain from the account menu in the Admin Console, e.g. `dev-1234567.okta.com`. The Admin Console's `-admin` hostname is a different URL. See [Find your Okta domain](https://developer.okta.com/docs/guides/find-your-domain/main/).
-
-**In Sim:**
+4. Copy **Client ID** and **Client Secret**.
 
-| Field | Value |
-|-------|-------|
-| Provider Type | OIDC |
-| Provider ID | `okta` |
-| Issuer URL | `https://dev-1234567.okta.com` |
-| Domain | `company.com` |
-| Client ID | From Okta app |
-| Client Secret | From Okta app |
+| Sim field | Value |
+| --- | --- |
+| **Provider type** | OIDC |
+| **Provider ID** | `acme-google` |
+| **Issuer URL** | `https://accounts.google.com` |
+| **Domain** | `acme.com` |
+| **Client ID** | From Google Cloud Console |
+| **Client secret** | From Google Cloud Console |
 
-For ordinary OIDC sign-in, use your Okta organization issuer as shown. A custom authorization server requires API Access Management; its issuer is `https://<your-okta-domain>/oauth2/<authorization-server-id>`. The `default` custom server is included in Okta's Integrator Free Plan but is not available in every production organization. See [Okta's authorization server guide](https://developer.okta.com/docs/concepts/auth-servers/).
+**Internal** restricts the OAuth app to your Workspace organization; Sim's verified **Domain** selects the email domain this SSO connection serves. See [Google OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect) and [OAuth consent setup](https://developers.google.com/workspace/guides/configure-oauth-consent).
 
 </Tab>
+<Tab value="ad-fs" id="ad-fs">
 
-<Tab value="Microsoft Entra ID">
-
-### Microsoft Entra ID (OIDC)
-
-**In Azure** ([official docs](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app)):
-
-1. Go to **Microsoft Entra ID → App registrations → New registration**
-2. Under **Redirect URI**, select **Web** and enter your Sim callback URL, using the Provider ID you chose:
+1. Open **AD FS Management → Relying Party Trusts → Add Relying Party Trust**.
+2. Choose **Claims aware**, then **Enter data about the relying party manually**.
+3. Set **Relying party identifier** to Sim's **SP Entity ID**. Sim Cloud normally shows `https://www.sim.ai`; copy the value from your own deployment.
+4. Add a **SAML Assertion Consumer Service** endpoint with HTTP POST binding:
    ```
-   https://<your-sim-domain>/api/auth/sso/callback/azure-ad-acme
+   https://<your-sim-domain>/api/auth/sso/saml2/callback/acme-adfs
    ```
-3. After registration, go to **Certificates & secrets → New client secret** and copy the value immediately — it won't be shown again
-4. Go to **Overview** and copy the **Application (client) ID** and **Directory (tenant) ID**
-5. Keep `email` in Sim's OIDC scopes. On Entra's v2.0 endpoint, this scope requests the email claim; alternatively, add **email** under **Token configuration → Add optional claim → ID**. Confirm the account supplies an email in your verified domain: a user principal name is not necessarily that email, and the claim is not guaranteed for every account. See [Microsoft's ID token claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference)
-6. If **Enterprise applications → Sim → Properties → Assignment required** is **Yes**, assign the users or groups who should sign in. Microsoft rejects unassigned users before they reach Sim
-
-**In Sim:**
-
-| Field | Value |
-|-------|-------|
-| Provider Type | OIDC |
-| Provider ID | `azure-ad-acme` (must be globally unique) |
-| Issuer URL | `https://login.microsoftonline.com/{tenant-id}/v2.0` |
-| Domain | `company.com` |
-| Client ID | Application (client) ID |
-| Client Secret | Secret value |
-
-</Tab>
-
-<Tab value="Microsoft Entra ID (SAML)">
-
-### Microsoft Entra ID (SAML 2.0)
+5. Under **Certificates**, export the **Token-signing certificate** using **View Certificate → Details → Copy to File → Base-64 encoded X.509 (.CER)**. Paste the text, including its header and footer, into Sim.
+6. Copy the **Federation Service identifier** from **Service → Federation Service Properties**, and the SSO endpoint, such as `https://adfs.acme.com/adfs/ls`.
 
-Use this when your tenant is configured for SAML rather than OIDC. Both are supported; OIDC is simpler if you have the choice.
-
-**In Azure** ([official docs](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso)):
-
-1. Go to **Enterprise applications → New application → Create your own application**, choose **Integrate any other application you don't find in the gallery**
-2. Open **Single sign-on** and select **SAML**
-3. Edit **Basic SAML Configuration** and set both values from Sim's SSO settings page:
-   - **Identifier (Entity ID)** — the **SP Entity ID** field
-   - **Reply URL (Assertion Consumer Service URL)** — the **ACS URL (Reply URL)** field
-4. Under **Attributes & Claims**, confirm the default claims are present. Sim reads the standard schema claim URIs for email, name, and name identifier
-5. Under **SAML Certificates**, download **Certificate (Base64)**. Its contents go in Sim's required **Identity provider certificate** field. You can optionally also download **Federation Metadata XML** and paste it into Sim's **IdP metadata XML** field under **Advanced options** — it does not replace the certificate
-6. From the **Set up** panel for your application, copy the **Login URL** and the **Microsoft Entra Identifier**
-7. Under **Users and groups**, assign the people who should be able to sign in — Microsoft rejects unassigned users before they reach Sim
-
-**In Sim:**
+| Sim field | Value |
+| --- | --- |
+| **Provider type** | SAML |
+| **Provider ID** | `acme-adfs` |
+| **Issuer URL** | Federation Service identifier, such as `https://adfs.acme.com/adfs/services/trust` |
+| **Domain** | `acme.com` |
+| **Entry point URL** | `https://adfs.acme.com/adfs/ls` |
+| **Identity provider certificate** | Contents of the exported Base64 certificate |
 
-| Field | Value |
-|-------|-------|
-| Provider Type | SAML |
-| Provider ID | `azure-ad-acme` (must be globally unique) |
-| Issuer URL | **Microsoft Entra Identifier**, e.g. `https://sts.windows.net/{tenant-id}/` |
-| Domain | `company.com` |
-| Entry point URL | **Login URL** from Entra |
-| Identity provider certificate | Contents of the Base64 certificate |
-
-<Callout type="info">
-  The **Identifier (Entity ID)** you set in Entra is what Sim validates the assertion's audience against. If it does not match the **SP Entity ID** shown in Sim exactly, sign-in fails with an audience mismatch.
+<Callout type="warn">
+  **Issuer URL** identifies AD FS; **SP Entity ID** identifies Sim. Sim's form requires an HTTPS issuer. AD FS may use an `http://` Federation Service identifier: work with your AD FS administrator to resolve that mismatch before changing an existing federation's identifier.
 </Callout>
 
-</Tab>
+See [Microsoft relying-party setup](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust).
 
-<Tab value="Google Workspace">
-
-### Google Workspace (OIDC)
+</Tab>
+</Tabs>
 
-**In Google Cloud Console** ([official docs](https://developers.google.com/identity/openid-connect/openid-connect)):
+## Save and verify sign-in
 
-1. Go to **APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID**
-2. Set the application type to **Web application**
-3. Add your Sim callback URL to **Authorized redirect URIs**:
-   ```
-   https://<your-sim-domain>/api/auth/sso/callback/google-workspace
-   ```
-4. Copy the **Client ID** and **Client Secret**
+Select **Save** for a new provider. Sign out, select **Sign in with SSO** on your deployment's login page, and enter an email in the verified domain. Sim selects the domain's provider, redirects to it, and returns the authenticated account to Sim.
 
-**In Sim:**
+If multiple providers serve the domain, ordinary sign-in uses the one marked **Primary**. Other providers can be reached through their **Test sign-in link**.
 
-| Field | Value |
-|-------|-------|
-| Provider Type | OIDC |
-| Provider ID | `google-workspace` |
-| Issuer URL | `https://accounts.google.com` |
-| Domain | `company.com` |
-| Client ID | From Google Cloud Console |
-| Client Secret | From Google Cloud Console |
-
-<Callout type="info">
-  To restrict sign-in to your Google Workspace domain, configure the OAuth consent screen and ensure your app is set to **Internal** (Workspace users only) under **User type**. Setting the app to Internal limits access to users within your Google Workspace organization.
+<Callout type="warn">
+  Start SAML testing from Sim's **Sign in with SSO** flow. Sim rejects unsolicited SAML assertions, so a test started from an identity-provider app portal can fail even with a correct configuration.
 </Callout>
 
-</Tab>
-
-<Tab value="ADFS">
+An OIDC dashboard can use the saved provider's **Initiate login URL**. Sim starts that provider's sign-in without asking for an email when the domain is verified and the launch includes a matching issuer. An already signed-in account goes directly to Sim.
 
-### ADFS (SAML 2.0)
+## Membership and account linking
 
-**In ADFS** ([official docs](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust)):
+Under **First sign-in → On first SSO sign-in**, choose:
 
-1. Open **AD FS Management → Relying Party Trusts → Add Relying Party Trust**
-2. Choose **Claims aware**, then **Enter data about the relying party manually**
-3. Set the **Relying party identifier** (Entity ID) to the **SP Entity ID** shown in Sim's SSO settings. SAML compares the assertion's audience against it, so it must match exactly:
-   ```
-   https://www.sim.ai
-   ```
-4. Add an endpoint: **SAML Assertion Consumer Service** (HTTP POST) with the URL:
-   ```
-   https://<your-sim-domain>/api/auth/sso/saml2/callback/adfs
-   ```
-5. Export the **Token-signing certificate** from **Certificates**: right-click → **View Certificate → Details → Copy to File**, choose **Base-64 encoded X.509 (.CER)**. Paste the file's text into **Identity provider certificate**, including the certificate header and footer.
-6. Note the **ADFS Federation Service endpoint URL** (e.g. `https://adfs.company.com/adfs/ls`)
+| Mode | Organization membership |
+| --- | --- |
+| **Automatic** | Adds a new account as a **Member** without an organization invitation. Team seat counts grow with membership; fixed-seat plans require available capacity. IdP role claims do not select the organization role. |
+| **Invite only** | Authenticates the account without creating membership. Existing membership and workspace access remain available; grant new access separately. |
 
-**In Sim:**
+Neither mode grants workspace access. After sign-in, members enter a workspace they can access or see a no-access state until an administrator grants access. For directory-managed workspace grants, push a group through [SCIM](/platform/enterprise/scim) and map it to a workspace.
 
-| Field | Value |
-|-------|-------|
-| Provider Type | SAML |
-| Provider ID | `adfs` |
-| Issuer URL | `https://adfs.company.com/adfs/services/trust` (the ADFS Federation Service identifier) |
-| Domain | `company.com` |
-| Entry point URL | `https://adfs.company.com/adfs/ls` |
-| Identity provider certificate | Contents of the exported Base64 certificate |
-
-<Callout type="info">
-  The **Issuer URL** is the identity provider's own identifier, found in ADFS under **Service → Federation Service Properties → Federation Service identifier**. It is not Sim's URL — Sim's identifier is the **SP Entity ID** shown in the SSO settings, which you register in ADFS as the relying party identifier.
-
-  Sim requires this field to use `https`. ADFS often defaults its Federation Service identifier to an `http://` URI; if yours does, change it to `https` in ADFS so both sides agree.
-</Callout>
+Pending invitations and existing external workspace access take precedence over automatic membership, preserving their intended roles and grants. External workspace members access a specific workspace without joining the organization or consuming its seats.
 
-</Tab>
+When a new SSO identity asserts the email of an existing Sim account, Sim links it automatically. The provider's verified domain authorizes that linking for OIDC and SAML without requiring an `email_verified` claim. Sim matches the asserted email; it does not resolve aliases or different user principal names to an existing address. Send the same email when switching providers to preserve the account and its access.
 
-</Tabs>
+An active, entitled SCIM connection can override **Automatic** with **Disable just-in-time provisioning**. Existing members, including invited members, can still sign in. See [Provisioning and SSO together](/platform/enterprise/scim#provisioning-and-sso-together).
 
----
-
-## How sign-in works after setup
+## Require single sign-on
 
-Once SSO is configured, users with your domain (`company.com`) can sign in through your identity provider:
+In **Sign-in**, set **Allowed sign-in methods** to **Single sign-on**. This option becomes available when the organization has an identity provider on a verified domain.
 
-1. User goes to `sim.ai` and clicks **Sign in with SSO**
-2. They enter their work email (e.g. `alice@company.com`)
-3. Sim looks up the provider that serves `company.com` and redirects them to it
-4. After authenticating, they are returned to Sim
-5. If **First sign-in** is **Automatic**, Sim adds them to the organization as a Member, growing a Team seat count or validating available fixed-seat capacity
-6. They land in an accessible workspace, or see a clear no-access state until an admin grants workspace access
+- The requirement applies when a session is created. Turning it on leaves current sessions active; members meet it at their next sign-in. Use **Settings → Organization → Security → Sign out all members** to revoke current member sessions too.
+- Members who try password, email-code, or social sign-in see a message directing them to the identity provider.
+- Organization owners retain the deployment's other enabled sign-in methods for recovery. An owner who has only used SSO can set a password through **Forgot password** and turn off the requirement if the provider fails.
+- The requirement stops enforcing if no sign-in provider remains on a verified domain, or the organization loses SSO entitlement. It can be switched back to other methods at any time.
+- Desktop handoff from an already authenticated browser remains available because it derives from an admitted session.
 
-People can also open Sim straight from an OIDC identity provider's app dashboard, such as the Okta tile. Open **Sign-in**, select the provider, and copy its **Initiate login URL** from **Identity provider**. Set it as the app's initiate login URI in your identity provider. Sim starts sign-in through that provider without asking for an email, and only when the provider's domain is verified and the request comes from its own issuer. People who are already signed in go straight to Sim.
+Turning the requirement off permits the deployment's other configured sign-in methods again. Enabling an SSO provider alone does not disable them.
 
-With **Automatic** provisioning, no invitation is required for organization membership. The join follows the organization's seat policy and does not infer a role from IdP claims: every newly provisioned user starts as a Member. Team subscriptions grow their billed seat count with membership; fixed-seat plans reject the join when capacity is full. With **Invite only**, SSO proves identity but does not create new membership or workspace access; new access must be granted separately, while existing organization membership and workspace access remain available.
+### Offboard a member
 
-<Callout type="warn">
-  Start SAML sign-in from Sim's **Sign in with SSO** flow. Sim rejects unsolicited SAML assertions, so an IdP-initiated SAML test from an app portal can fail even when the configuration is correct.
-</Callout>
+Disabling an account in the identity provider stops future SSO authentication. SSO alone does not revoke current Sim sessions or other sign-in methods. Remove the member in Sim as part of offboarding, or use [SCIM deactivation](/platform/enterprise/scim#what-it-does) to suspend access. SCIM suspension stops sign-in and personal API keys while preserving ownership; shared workspace keys continue working.
 
-SSO provisioning creates internal organization members but does not grant workspace access. To grant workspace access from your identity provider, use [directory provisioning](/platform/enterprise/scim) and map a pushed group to a workspace. External workspace members are different: they are invited to a specific workspace without joining your organization or consuming one of your seats. Existing invitations and external access take precedence over automatic provisioning so their intended role and workspace grants are preserved.
+## Edit or replace a provider
 
-## Require single sign-on
+Select a saved provider under **Sign-in**, then select **Edit**. Its **Provider ID** stays fixed. Select **Update** to save, or **Discard** to abandon edits.
 
-By default members can sign in with a password, an email code, or your identity provider. To make single sign-on the only way in, open **Settings → Organization → Single sign-on → Sign-in** and set **Allowed sign-in methods** to **Single sign-on**. It becomes available once the organization has an identity provider on a verified domain.
+Saved OIDC secrets appear masked, with a suffix when available. **Replace** enters a new secret; **Keep saved** cancels replacement. SCIM settings in **Provisioning** save immediately and have no page-level Save action.
 
-- The requirement is checked when a session is created, so turning it on signs nobody out. Members keep working and meet the requirement at their next sign-in. To end current sessions too, use **Sign out all members** under **Settings → Organization → Security**.
-- Organization owners keep every sign-in method. If the identity provider breaks, an owner can still sign in with a password — setting one through **Forgot password** if they only ever signed in through the identity provider — and turn the requirement back off.
-- If the last identity provider is deleted or its domain verification lapses, the requirement stops being enforced instead of locking the organization out, and you can switch back to any method at any time.
-- Desktop app handoff from an already signed-in browser keeps working, because that session derives from one the requirement already admitted.
-- A member who tries a password, an email code, or a social sign-in such as Google or GitHub sees a message telling them to sign in through their identity provider.
+Deleting a provider removes its sign-in path, while accounts and memberships remain. If another verified provider serves the same domain, it becomes primary when the deleted provider was primary. Otherwise accounts must use another allowed sign-in method until a provider serves the domain again.
 
-<Callout type="info">
-  Turning the requirement off restores password and email sign-in immediately for everyone.
-</Callout>
+### Switching identity providers
 
----
+Configure and test a new provider before switching a domain:
 
-<FAQ items={[
-  {
-    question: "Which SSO providers are supported?",
-    answer: "Any identity provider that supports OIDC or SAML 2.0. This includes Okta, Microsoft Entra ID (Azure AD), Google Workspace, Auth0, OneLogin, JumpCloud, Ping Identity, ADFS, Shibboleth, and more."
-  },
-  {
-    question: "What is the Domain field used for?",
-    answer: "The domain (e.g. company.com) is how Sim routes users to the right identity provider. When a user enters their email on the SSO sign-in page, Sim matches their email domain to the provider that serves it and redirects them there. If a domain has more than one provider, Sim uses the one marked Primary."
-  },
-  {
-    question: "Can we use more than one identity provider?",
-    answer: "Yes. Different domains can use different providers, for example Okta for eng.acme.com and Microsoft Entra ID for acme.com. A domain can also have several providers while you move between them: sign-in uses its primary provider, and the others are reachable through a test sign-in link. SCIM provisioning stays organization-wide and works alongside any number of providers."
-  },
-  {
-    question: "Do I need to provide OIDC endpoints manually?",
-    answer: "No. For OIDC providers, Sim automatically fetches the authorization, token, and JWKS endpoints from the discovery document at {issuer}/.well-known/openid-configuration. You only need to provide the issuer URL."
-  },
-  {
-    question: "What happens when a user signs in with SSO for the first time?",
-    answer: "Sim creates or links their account. If first-sign-in provisioning is Automatic and a seat is available, Sim adds them to your organization as a Member; no manual organization invite is needed. Workspace access is always granted separately. If provisioning is Invite only, or the user already has a pending invitation or external workspace access, Sim preserves that flow instead of creating membership automatically."
-  },
-  {
-    question: "Does disabling someone in the identity provider remove their Sim access?",
-    answer: "When [directory provisioning](/platform/enterprise/scim) sends a deactivation, Sim blocks sign-in and personal API keys while preserving ownership. Shared workspace keys keep working. With SSO alone, disabling the IdP account only blocks future SSO authentication; remove the member in Sim as part of offboarding."
-  },
-  {
-    question: "Can I still use email/password login after enabling SSO?",
-    answer: "Yes, unless you require single sign-on. Enabling SSO does not disable password login on its own; set Allowed sign-in methods to Single sign-on to refuse password, email-code, and social sign-in for members. Organization owners keep password sign-in as a way back in if the identity provider breaks, and can set a password through Forgot password if they never had one."
-  },
-  {
-    question: "A user already has an account with the same email — what happens when they sign in with SSO?",
-    answer: "Sim links the SSO identity to that account automatically. Linking is authorized by your verified domain: because you proved ownership of the domain before configuring SSO, Sim treats your identity provider as authoritative for email addresses on it. This works for OIDC and SAML without requiring an email_verified claim. Matching uses the address sent as email; Sim does not resolve different aliases or user principal names to an existing account. If the asserted address differs from the existing account, Sim treats it as a separate account."
-  },
-  {
-    question: "Who can configure SSO on Sim Cloud?",
-    answer: "Organization owners and admins can configure SSO. You must be on the Enterprise plan."
-  },
-  {
-    question: "What is the Callback URL?",
-    answer: "The Callback URL (also called Redirect URI or ACS URL) is the endpoint in Sim that receives the authentication response from your identity provider. Use your own deployment's domain — on Sim Cloud that is www.sim.ai. For OIDC providers it follows the format: https://<your-sim-domain>/api/auth/sso/callback/{provider-id}. For SAML providers it is: https://<your-sim-domain>/api/auth/sso/saml2/callback/{provider-id}. You must register this URL in your identity provider before SSO will work."
-  },
-  {
-    question: "How do I update or replace an existing SSO configuration?",
-    answer: "Open Settings → Organization → Single sign-on → Sign-in, select the provider, and select Edit. Change the fields and select Update. The Provider ID cannot be changed; replacing it means deleting the provider and adding a new one."
-  }
-]} />
+1. Add it with the same verified domain. The current provider remains **Primary**.
+2. Open the new provider and copy **Test sign-in link**. Test accounts use that provider; ordinary sign-in still uses the current primary.
+3. Confirm the new provider asserts the same account emails, then select **Make primary**. New sign-ins use it; existing sessions remain active.
+4. Keep the old provider to switch back with **Make primary**, or delete it after verification.
 
----
+Different domains can also use different providers, such as Okta for `eng.acme.com` and Entra for `acme.com`. SCIM remains organization-wide alongside these providers.
 
 ## Self-hosted setup
 
-Self-hosted deployments use environment variables instead of the billing/plan check.
-
-### Environment variables
+For a deployment with billing disabled, enable SSO and its browser twin:
 
 ```bash
-# Required
 SSO_ENABLED=true
 NEXT_PUBLIC_SSO_ENABLED=true
 
-# Optional: directory provisioning (SCIM), configured from Single sign-on → Provisioning
-SCIM_ENABLED=true
-NEXT_PUBLIC_SCIM_ENABLED=true
-
-# Required if you want users auto-added to your organization on first SSO sign-in
+# Organization membership on first SSO sign-in
 ORGANIZATIONS_ENABLED=true
 NEXT_PUBLIC_ORGANIZATIONS_ENABLED=true
 
-# Optional: comma-separated provider IDs to trust for automatic account linking.
-# This applies to non-SSO providers only — SSO linking is authorized by the
-# verified domain on the provider itself, not by this list.
-SSO_TRUSTED_PROVIDER_IDS=custom-oidc,partner-saml
+# Optional directory provisioning tab
+SCIM_ENABLED=true
+NEXT_PUBLIC_SCIM_ENABLED=true
 ```
 
-<Callout type="info">
-  When someone signs in with SSO and an account with the same email already exists
-  (for example, they previously signed up with email/password), Sim links the SSO
-  identity to that account automatically. That linking is authorized by the verified
-  domain attached to the provider, so it works for both OIDC and SAML and does not
-  depend on your IdP asserting `email_verified`.
-</Callout>
+The enterprise master pair also enables these features. See [Self-hosted enterprise](/platform/enterprise/self-hosted) for organization setup.
 
-You can register providers through the **Settings UI** (same as cloud) or by running the registration script directly against your database.
+`SSO_TRUSTED_PROVIDER_IDS` is an optional comma-separated list for non-SSO provider account linking. It does not authorize SSO linking; SSO trust comes from the provider's verified domain.
 
-Restricted networks can opt out of the DNS challenge with the server-only `SSO_SKIP_DOMAIN_VERIFICATION=true` setting. Add the domain and click **Verify** before saving SSO. This trusts administrator claims across the instance and is ignored on Sim Cloud. See [skipping DNS verification](/platform/enterprise/verified-domains#skip-dns-verification) for the trust implications and [DNS network requirements](/platform/enterprise/verified-domains#restricted-networks) for the default setup.
+Restricted networks can use the server-only `SSO_SKIP_DOMAIN_VERIFICATION=true` setting. Add the domain and select **Verify** before saving SSO. See [DNS requirements](/platform/enterprise/verified-domains#restricted-networks) and [bypass trust consequences](/platform/enterprise/verified-domains#skip-dns-verification).
 
 ### Script-based registration
 
-Use this when you need to register an SSO provider without going through the UI — for example, during initial deployment or CI/CD automation.
+Deployment operators can register directly against the database from the repository root. Provide `DATABASE_URL` or `POSTGRES_URL`, an existing account's `SSO_USER_EMAIL`, and `SSO_ORGANIZATION_ID` to bind the provider to the organization. Without the organization ID, the provider is user-scoped and does not add organization membership at first sign-in.
+
+<Callout type="warn">
+  Direct registration replaces the stored configuration for the same **Provider ID** and records its organization domain as verified without the DNS challenge. Run it only with operator authority and the intended organization ID. This bypasses the ordinary Settings verification flow.
+</Callout>
+
+OIDC example:
 
 ```bash
-# OIDC example (Okta)
+DATABASE_URL=... \
 SSO_ENABLED=true \
-NEXT_PUBLIC_APP_URL=https://your-instance.com \
+NEXT_PUBLIC_APP_URL=https://sim.example.com \
 SSO_PROVIDER_TYPE=oidc \
-SSO_PROVIDER_ID=okta \
+SSO_PROVIDER_ID=acme-okta \
 SSO_ISSUER=https://dev-1234567.okta.com \
-SSO_DOMAIN=company.com \
-SSO_USER_EMAIL=admin@company.com \
+SSO_DOMAIN=acme.com \
+SSO_USER_EMAIL=admin@acme.com \
+SSO_ORGANIZATION_ID=org_123 \
 SSO_OIDC_CLIENT_ID=your-client-id \
 SSO_OIDC_CLIENT_SECRET=your-client-secret \
 bun run packages/db/scripts/register-sso-provider.ts
 ```
 
+SAML example:
+
 ```bash
-# SAML example (ADFS)
+DATABASE_URL=... \
 SSO_ENABLED=true \
-NEXT_PUBLIC_APP_URL=https://your-instance.com \
+NEXT_PUBLIC_APP_URL=https://sim.example.com \
 SSO_PROVIDER_TYPE=saml \
-SSO_PROVIDER_ID=adfs \
-SSO_ISSUER=https://adfs.company.com/adfs/services/trust \
-SSO_SAML_AUDIENCE=https://your-instance.com \
-SSO_DOMAIN=company.com \
-SSO_USER_EMAIL=admin@company.com \
-SSO_SAML_ENTRY_POINT=https://adfs.company.com/adfs/ls \
+SSO_PROVIDER_ID=acme-adfs \
+SSO_ISSUER=https://adfs.acme.com/adfs/services/trust \
+SSO_SAML_AUDIENCE=https://sim.example.com \
+SSO_DOMAIN=acme.com \
+SSO_USER_EMAIL=admin@acme.com \
+SSO_ORGANIZATION_ID=org_123 \
+SSO_SAML_ENTRY_POINT=https://adfs.acme.com/adfs/ls \
 SSO_SAML_CERT="-----BEGIN CERTIFICATE-----
 ...
 -----END CERTIFICATE-----" \
 bun run packages/db/scripts/register-sso-provider.ts
 ```
 
-The script outputs the callback URL to configure in your IdP once it completes.
+The script prints the callback URL to register in the identity provider. These commands configure the database; persist the SSO feature flags in the running application's environment separately.
 
-To remove a provider:
+To remove one provider:
 
 ```bash
-SSO_USER_EMAIL=admin@company.com \
+DATABASE_URL=... \
+SSO_USER_EMAIL=admin@acme.com \
+SSO_PROVIDER_ID=acme-okta \
 bun run packages/db/scripts/deregister-sso-provider.ts
 ```
+
+Omitting `SSO_PROVIDER_ID` removes **all providers owned by that account**.
+
+## Related docs
+
+- [Verified domains](/platform/enterprise/verified-domains)
+- [Directory provisioning](/platform/enterprise/scim)
+- [Okta provisioning](/platform/enterprise/scim/okta)
+- [Microsoft Entra provisioning](/platform/enterprise/scim/entra)
+- [Session policies](/platform/enterprise/session-policies)
diff --git a/apps/docs/content/docs/platform/enterprise/usage-tracking.mdx b/apps/docs/content/docs/platform/enterprise/usage-tracking.mdx
index 21a1343a2c2..fba4f443d8f 100644
--- a/apps/docs/content/docs/platform/enterprise/usage-tracking.mdx
+++ b/apps/docs/content/docs/platform/enterprise/usage-tracking.mdx
@@ -1,176 +1,107 @@
 ---
 title: Insights
-description: Explore organization credit usage, workflow performance, and recorded chat activity
+description: Compare organization credit usage with workflow performance and recorded Chat activity
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { FAQ } from '@/components/ui/faq'
-import { Image } from '@/components/ui/image'
+Insights shows credit consumption by source, member, workspace, and model, alongside retained workflow and Chat activity. Use it to find spending drivers, investigate workflow performance, and export credit events for reporting.
 
-Insights shows how your organization consumes credits across every part of the platform — which members, which workspaces, which models, and which product features. Use it to monitor spend against your commitment, find what is driving it, and export the underlying events for chargeback.
+Organization owners and admins open **Settings → Organization → Insights**. Regular members cannot view organization usage, including their own contribution. Billing-enabled deployments require Enterprise; billing-disabled deployments use the feature configuration under [Self-hosted setup](#self-hosted-setup).
 
-Spend figures are in **credits** (1 credit = $0.005). See [cost calculation](/platform/costs) for how credits are derived.
+## Choose a period
 
----
-
-## Viewing usage
-
-Go to **Settings → Organization → Insights** in your workspace.
-
-The period selector applies to every tab:
-
-| Period | What it covers |
-|--------|----------------|
-| **Current period** | Your organization's current billing period |
-| **Previous period** | The period immediately before it |
-| **Last 7 days** / **Last 30 days** | A rolling window ending now |
-| **Custom range** | Any range up to 92 days |
-
-<Callout type="info">
-  Daily bars are drawn in your browser's timezone, while a billing period begins at a fixed UTC instant. The first and last bar of a period can therefore be partial, and two admins in different timezones will see the same total split across slightly different days.
-</Callout>
-
-### Tabs
+| Period | Scope |
+| --- | --- |
+| **Current period** | Organization's current billing period. |
+| **Previous period** | Immediately preceding billing period. |
+| **Last 7 days** / **Last 30 days** | Rolling window ending now. |
+| **Custom range** | Selected dates, up to 92 days. |
 
-| Tab | Answers |
-|-----|---------|
-| **Overview** | Credit consumption, recorded activity, workflow failure rate, and usage by source |
-| **Activity** | Run trends and performance, grouped by workspace, workflow, chat member, or trigger |
-| **Members** | Which people are driving usage |
-| **Workspaces** | Which workspaces are driving usage — select one to drill in |
-| **Models** | Which models we are paying for |
+The period applies to every tab. Daily bars use your browser's timezone, while billing periods begin at a fixed UTC instant. The first and last bars can be partial. Different timezones can split the same total differently across days.
 
-Selecting a workspace opens its detail view, which splits that workspace's usage into **Sources** (what kind of work) and **Workflows** (the individual workflow runs). **Open logs** jumps to [audit logs](/platform/enterprise/audit-logs) filtered to that workspace.
+Spend is in **credits**, where 1 credit = $0.005; the UI rounds displayed credits. [Logs](/logs-debugging/logging) and Logs API costs are in USD, while Billing and run-resource API amounts use their documented credit units. Check the endpoint contract before comparing amounts. See [cost calculation](/platform/costs).
 
-<Image src="/static/enterprise/usage-tracking-workspace-detail.png" alt="A workspace's detail view with a Sources section listing Sim Chat and Workflow, and a Workflows section ranking individual workflows by credits" width={900} height={598} className="mx-auto h-auto w-full max-w-xl" />
+## Read the tabs
 
-**Sources** adds up to the workspace's total, while **Workflows** covers only the workflow-run part of it. In the example above, Sources totals 4,435 credits but the workflows list only accounts for the 161 credits under Workflow — the other 4,274 came from Chat, which no workflow produced.
+| Tab | Shows |
+| --- | --- |
+| **Overview** | Credit consumption, recorded activity, workflow failure rate, and sources. |
+| **Activity** | Run trends and performance by workspace, workflow, chat member, or trigger. |
+| **Members** | Credit consumption attributed to people. |
+| **Workspaces** | Credit consumption by workspace; select one to drill in. |
+| **Models** | Paid model usage. |
 
----
+A workspace detail splits usage into **Sources** and **Workflows**. Sources covers all attributed credits; Workflows covers only the workflow-run ledger. For example, 4,274 Chat credits plus 161 Workflow credits totals 4,435, while the workflow list accounts for 161. **Open logs**, where available, opens [audit logs](/platform/enterprise/audit-logs) filtered to that workspace.
 
 ## Activity and performance
 
-The **Activity** tab shows workflow runs, recorded chat runs, members with chat activity, and workflow failure rate. Group the breakdown by **Workspaces**, **Workflows**, **Members**, or **Triggers**, and sort by run volume, failure count, or average workflow duration. Member breakdowns rank chat runs only. Results are paginated; totals and sorting include the whole selected period, not just the visible page. Select a workspace to narrow the activity view, then use **All workspaces** to clear that filter.
-
-- **Workflow runs** count retained execution records whose start time falls in the selected period, including runs that are still running, paused, or cancelled.
-- **Recorded chat runs** count distinct recorded execution IDs across workspace and organization chats. Continuations count once, in the period containing their first retained start. Calls without a persisted chat run are not included.
-- **Members with chat activity** count distinct users attributed to those chat runs. This measures recorded chat activity, not logins, all active users, or people billed for automated workflows.
-- **Workflow failure rate** is failed runs divided by completed plus failed runs. Paused, cancelled, and unfinished runs do not enter the denominator. A dash means there are no completed or failed runs to measure.
-- **Average duration** uses the recorded duration of completed or failed workflows. Missing durations are excluded; a dash means no duration is available.
+In **Activity**, group by **Workspaces**, **Workflows**, **Members**, or **Triggers**. Sort by run volume, failure count, or average workflow duration. Members rank recorded Chat runs. Pages limit visible rows; totals and sorting cover the whole selected period. Select a workspace to narrow results and use **All workspaces** to clear it.
 
-Activity follows retained history and current organization/workspace ownership. Deleting history or moving a workspace can change historical activity totals. Status and duration reflect the latest recorded outcome, even for a run that started in an earlier period. The activity view does not read chat transcripts or workflow trace payloads.
+| Metric | Definition |
+| --- | --- |
+| Workflow runs | Retained execution records starting in the period, including running, paused, and cancelled runs. |
+| Recorded chat runs | Distinct recorded execution IDs across workspace and organization chats. Continuations count once, at the first retained start; calls without a persisted run are excluded. |
+| Members with chat activity | Distinct users attributed to those recorded runs. This is not a login or all-active-member count. |
+| Workflow failure rate | Failed ÷ (completed + failed). Paused, cancelled, and unfinished runs are excluded; a dash means no completed/failed sample. |
+| Average duration | Known nonnegative durations of completed or failed workflows. Missing durations are excluded; a dash means none are available. |
 
-Credit totals continue to come from the billing ledger. Activity counts need not match billing-event counts, and the credit export does not export activity. Exact per-chat cost, connector/skill adoption, and generated-artifact attribution are not available in this view.
+These metrics follow retained history and current workspace/organization ownership. Deletion or moving a workspace can change historical totals. Outcome and duration reflect the latest recorded state even when a run started earlier. Activity does not read Chat transcripts or workflow trace payloads.
 
----
+Credits come from a separate billing ledger, so activity counts need not match credit-event counts. The credit export does not export activity. This view does not provide exact per-chat cost, connector/skill adoption, or attribution of generated artifacts.
 
-## What each source means
+## Credit sources
 
-A **source** is the part of the platform that consumed the credits. Every charge belongs to exactly one source, so the Sources breakdown always adds up to your total.
+Each charge has one source. The exact **Agent block** label in Insights refers to the **Sim Chat** workflow block (`mothership_block`), rather than the ordinary Agent block.
 
-| Source | Platform features that bill to it |
-|--------|-----------------------------------|
-| **Workflow** | Every workflow run — model calls made on Sim's hosted keys, hosted-key tool calls (web search, scraping, and similar), and the per-run base charge |
-| **Sim Chat** | The Chat panel, agent calls made through the API, and the email Inbox |
-| **Agent block** | The Agent block running inside a workflow |
-| **Knowledge Base** | Embedding documents on upload or connector sync, and semantic search queries |
-| **Wand** | Inline AI generation in editors |
-| **Enrichment** | Table column enrichment |
-| **Voice input** | Voice sessions |
-| **Voice output** | Spoken responses in deployed chats |
-| **API tool call** | A hosted-key tool invoked directly through the tool execution API, outside any workflow run |
-| **Sim Chat (MCP)** | Retired. Appears only for historical periods |
+| Source | Recorded charges |
+| --- | --- |
+| **Workflow** | Workflow model calls on hosted keys, hosted-key tool calls, and the per-run base charge. |
+| **Sim Chat** | Chat panel, API agent calls, and email Inbox usage, combined. |
+| **Agent block** | Sim Chat workflow-block usage, metered separately from its containing workflow. |
+| **Knowledge Base** | Upload/connector embedding and semantic search. |
+| **Wand** | Inline AI generation in editors. |
+| **Enrichment** | Table enrichment. |
+| **Voice input** | Voice sessions. |
+| **Voice output** | Spoken responses in deployed chats. |
+| **API tool call** | Direct hosted-key tool calls through the tool API outside a workflow run. |
+| **Sim Chat (MCP)** | Retired source visible in historical periods. |
 
-### Nuances worth knowing
+An ordinary Agent block's hosted model calls remain under Workflow. The Workflow base charge applies even without model calls. To assess a workflow using the Sim Chat block, read its Workflow charges and the separately metered Agent block source; neither charge is counted twice.
 
-These follow from how charges are recorded, and they explain most questions about why a number looks the way it does.
+A hosted-key tool called inside a workflow belongs to Workflow; the same tool called directly belongs to API tool call. Chat panel, API agent, and Inbox charges cannot be separated by source. Dedicated workspace attribution can distinguish them when those surfaces actually name different workspaces. Usage without a workspace appears under **No workspace** and remains part of the organization total.
 
-**Workflow covers the whole run, not just the base charge.** A workflow row includes three things: the models it called on Sim's hosted keys, any hosted-key tool calls, and the per-run base charge. The base charge applies to every run, including runs with no model calls.
+### Reconcile totals
 
-**Agent block is billed separately from the workflow that contains it.** An Agent block runs inside a workflow but is metered on its own, so its credits appear under **Agent block** rather than **Workflow**. Nothing is counted twice — but it also means Workflow alone understates what your workflows cost. Read the two lines together.
+Members, Workspaces, and Sources are separate groupings of the same ledger. Each covers the period's charges; adding groupings together double-counts. Rounding can obscure small differences.
 
-**Sim Chat covers three surfaces.** The Chat panel, headless agent calls through the API, and the Inbox all record as **Sim Chat** and cannot be separated from one another. If you need per-surface attribution today, separate them by workspace instead.
+Models covers model charges only. Base charges, hosted tools, and fixed charges explain why it can be lower than the total. The current billing period lets you compare consumption with Billing; rolling windows do not align with invoices, and consumption is not a complete invoice including other fees or taxes.
 
-**Only workflow runs carry workflow attribution.** Chat, Agent block, Wand, Knowledge Base, and voice usage are not produced by a workflow and have no workflow attached. That is the gap between a workspace's **Sources** and **Workflows** sections shown above.
+## Bring your own keys
 
-**Hosted-key tool calls bill in two places, depending on who made them.** A hosted-key tool called *inside* a workflow run is folded into that run and appears under **Workflow**. The same tool called directly through the tool execution API belongs to no run, so it records under **API tool call** instead.
+A workflow model call using a workspace or organization provider key has zero model credits while its token usage is still recorded. Those tokens are not broken out in the Insights panel's credit totals. This statement describes verified workflow-model recording; other own-key surfaces do not have an equivalent breakdown here.
 
-**Some usage has no workspace.** Agent calls made through the API may not name a workspace, particularly from headless or self-hosted callers. That usage is grouped under **No workspace** on the Workspaces tab. It is still counted in your total.
+BYOK does not remove the workflow base charge or separate hosted-tool and sandbox charges. Confirm which key was used when investigating an expected zero-cost model call.
 
-**Models excludes non-model charges.** The Models tab covers model usage only, so it will read lower than your period total — the difference is per-run base charges, hosted-key tool charges, and fixed charges such as voice sessions.
+## Export credit events
 
-<Callout type="warn">
-  Each tab is a different slice of the same charges, not an additional set of them. Members, Workspaces, and Sources each add up to your period total on their own; adding two tabs together double-counts.
-</Callout>
+Click **Export** for the selected period and filters, or **All events** for the individual ledger entries and their filters. CSV columns are `Date, Source, Description, Workflow, Credits`; credits are numeric with four decimal places and can be summed.
 
----
+Exports stop at **100,000 events**. A truncated export still downloads and shows a notice; narrow the date range and export the remaining periods. Fractional CSV values can differ from whole-credit UI rounding.
 
-## Bring your own keys (BYOK)
-
-When a workspace or organization supplies its own provider key, Sim does not charge for that model usage. Those calls are still recorded, measured in **tokens** rather than credits — the credit cost is zero by definition — and they are not included in the credit totals anywhere in the panel.
-
-<Callout type="info">
-  This usage is not broken out in the panel today. Of what is recorded, only model usage in workflow runs is covered: tool calls and Chat usage made on your own keys are not recorded at all.
-</Callout>
-
----
-
-## Exporting
-
-**Export credits** downloads the events behind the current period and filters as a CSV with columns `Date, Source, Description, Workflow, Credits`. Credits are exported as plain numbers so the column can be summed, and carry decimals — an individual event often costs a fraction of a credit.
-
-**Credit events** opens the full ledger — every credit-consuming event, newest first, with its own filters and export.
-
-Very large exports are capped. When that happens the download still succeeds and Sim tells you it was truncated; narrow the date range to capture everything.
-
----
-
-<FAQ items={[
-  {
-    question: "Who can view Insights?",
-    answer: "Organization owners and admins. On Sim Cloud you must be on the Enterprise plan. Regular members cannot see organization usage, including their own."
-  },
-  {
-    question: "Why doesn't the Models tab add up to my total?",
-    answer: "The Models tab covers model usage only. Your total also includes per-run base charges, hosted-key tool charges, and fixed charges such as voice sessions. Use the Sources breakdown on the Overview tab for a figure that reconciles to the total."
-  },
-  {
-    question: "Why is Sim Chat so much larger than Workflow?",
-    answer: "Sim Chat covers the Chat panel, API agent calls, and the Inbox together, and conversational usage is typically token-heavy. It is common for Chat to be the largest line in an organization that uses it."
-  },
-  {
-    question: "Can I see how much the Inbox or the API specifically costs?",
-    answer: "Not directly — both record as Sim Chat. Where those surfaces run in dedicated workspaces, the Workspaces tab gives you the equivalent breakdown."
-  },
-  {
-    question: "What is “No workspace”?",
-    answer: "Usage that was not attributed to a workspace, most often agent calls made through the API without a workspace context. It is included in your organization total."
-  },
-  {
-    question: "Is there an API for usage data?",
-    answer: "The billing API exposes billing status and usage events; the [Billing CLI](/cli/billing) provides commands for those reads. Use this page's CSV export for the organization report shown in Settings."
-  },
-  {
-    question: "Why does a period show partial days at each end?",
-    answer: "Daily buckets follow your browser's timezone while billing periods begin at a fixed UTC instant, so the first and last bucket of a period can cover part of a day."
-  },
-  {
-    question: "Does this match my invoice?",
-    answer: "The Overview total for the current period is the same figure your billing page reports. Rolling windows such as Last 7 days do not align with a billing period and will not match an invoice."
-  }
-]} />
-
----
+For automation, use the organization usage [summary](/api-reference/organizations/getOrganizationUsageSummary), [breakdown](/api-reference/organizations/getOrganizationUsageBreakdown), and [events](/api-reference/organizations/listOrganizationUsageEvents) APIs. [Billing CLI](/cli/billing) account reads are a separate view from this organization report.
 
 ## Self-hosted setup
 
-Self-hosted deployments use environment variables instead of the billing/plan check.
-
-### Environment variables
+Enable Insights through enterprise configuration or explicitly set:
 
 ```bash
 USAGE_MONITORING_ENABLED=true
 NEXT_PUBLIC_USAGE_MONITORING_ENABLED=true
 ```
 
-Once enabled, Insights is viewable in **Settings → Organization → Insights** for organization owners and admins.
+Explicit values take precedence over the enterprise master configuration. Billing-enabled deployments retain the Enterprise gate. Organization owner/admin access is still required. See [self-hosted enterprise setup](/platform/enterprise/self-hosted).
+
+## Related docs
+
+- [Costs and credits](/platform/costs)
+- [Audit logs](/platform/enterprise/audit-logs)
+- [Data retention](/platform/enterprise/data-retention)
diff --git a/apps/docs/content/docs/platform/enterprise/verified-domains.mdx b/apps/docs/content/docs/platform/enterprise/verified-domains.mdx
index b396a2191b4..ed883d87934 100644
--- a/apps/docs/content/docs/platform/enterprise/verified-domains.mdx
+++ b/apps/docs/content/docs/platform/enterprise/verified-domains.mdx
@@ -1,96 +1,74 @@
 ---
-title: Verified Domains
-description: Prove ownership of your email domains for single sign-on and directory provisioning
+title: Verified domains
+description: Prove email-domain ownership for single sign-on and directory provisioning
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Image } from '@/components/ui/image'
-import { FAQ } from '@/components/ui/faq'
 
-Verified Domains let organization owners and admins on Enterprise plans prove they control an email domain (like `acme.com`) with a DNS TXT record. Verify a domain before configuring single sign-on for it or provisioning members at that domain through SCIM.
+Verify an email domain before configuring SSO for it or provisioning members at that domain through SCIM. Organization owners and admins prove ownership with a DNS TXT record. On Sim Cloud, domain verification requires an Enterprise organization.
 
-<Callout type="warn">
-  Configuring SSO for a domain requires it to be verified first. Verifying proves your organization controls the domain — without it, anyone could point another company's domain at their own identity provider. The domain-verification migration preserved domains configured for SSO before this requirement was introduced.
-</Callout>
-
----
+A verified domain authorizes your organization to use its identity provider for addresses on that domain. Each domain belongs to one organization; subdomains such as `eng.acme.com` must be verified separately from `acme.com`.
 
 ## Verify a domain
 
-Go to **Settings → Organization → Single sign-on → Domains**. The **Verified domains** section is shared by sign-in and directory provisioning.
+Open **Settings → Organization → Single sign-on → Domains**. The **Verified domains** section is shared by sign-in and directory provisioning.
 
-<Image src="/static/enterprise/sso-domains.png" loading="eager" alt="Domains tab showing a verified domain and the DNS record for a pending domain" width={832} height={663} className="mx-auto h-auto w-full max-w-xl" />
+<Image src="/static/enterprise/sso-domains.png" alt="Domains tab showing a verified domain and the DNS record for a pending domain" width={832} height={663} className="mx-auto h-auto w-full max-w-xl" />
 
-1. Enter the domain, for example `acme.com`, and click **Add domain**.
-2. Sim shows a DNS **TXT record** to publish — a host (`_sim-challenge.acme.com`) and a unique value (`sim-domain-verification=…`).
-3. Add that TXT record at your DNS provider.
-4. Click **Verify**. Sim looks up the record; on success the domain is marked **Verified**.
+1. Enter the domain, for example `acme.com`, and select **Add domain**.
+2. Copy the TXT host and value shown by Sim: `_sim-challenge.acme.com` and `sim-domain-verification=…`.
+3. Add that TXT record at your DNS provider. Keep existing records; the challenge uses its own host.
+4. Select **Verify**. Sim looks up the record and marks the domain **Verified** when it matches.
 
 <Callout type="warn">
-  Some DNS providers append the zone automatically. If yours does, enter `_sim-challenge` when managing the `acme.com` zone, or `_sim-challenge.eng` to verify `eng.acme.com` from that zone. Check the resulting record name: it must match the full host Sim shows, without a repeated domain such as `_sim-challenge.acme.com.acme.com`.
+  Some DNS providers append the zone automatically. In the `acme.com` zone, use `_sim-challenge` if your provider adds the zone, or `_sim-challenge.eng` for `eng.acme.com`. The resulting name must match Sim's full host, without a repeated suffix such as `_sim-challenge.acme.com.acme.com`.
 </Callout>
 
-DNS changes can take time to propagate. If verification does not succeed immediately, check the record name and value, then wait and retry. Keep the TXT record published. Sim verifies it when you select **Verify**; removing the DNS record does not itself revoke a completed verification.
+DNS changes can take time to propagate. If verification fails, check the record name and value, then wait and retry. Keep the record published. Sim checks it when you select **Verify**; removing the DNS record does not automatically revoke a completed verification.
 
-Add each domain you own separately. Subdomains (`eng.acme.com`) are verified independently of the apex.
+Domains configured for SSO before domain verification was introduced were preserved as verified by the migration. New claims require verification.
 
----
+## Remove a verified domain
 
-## FAQ
-
-<FAQ
-  items={[
-    {
-      question: 'Where does the TXT record go?',
-      answer:
-        'On the dedicated host _sim-challenge.<your-domain>. Add the supplied TXT value there without replacing existing records on your domain.',
-    },
-    {
-      question: 'What happens to domains we already use for SSO?',
-      answer:
-        'Domains configured before domain verification was introduced were preserved as verified by the migration. New domains must complete DNS verification.',
-    },
-    {
-      question: 'Can two organizations verify the same domain?',
-      answer:
-        'No. A verified domain belongs to exactly one organization. Once verified, another organization cannot claim it.',
-    },
-    {
-      question: 'What if I remove a verified domain?',
-      answer:
-        'New SSO sign-ins for that domain stop immediately, including through an existing provider. SCIM cannot create users or change an email to that domain until it is verified again. Removing the domain does not itself end existing sessions. Re-add and verify it to restore the ownership proof.',
-    },
-  ]}
-/>
+Removing a domain in Sim stops new SSO sign-ins for that domain, including through an existing provider. SCIM can no longer create accounts or change an account's email to that domain until it is verified again. Existing sessions are not ended by domain removal.
 
----
+Re-add and verify the domain to restore its ownership proof. Another organization cannot claim it while it remains verified for yours.
 
 ## Self-hosted setup
 
-Domain verification appears on the single sign-on page when SSO is enabled:
+Enable SSO to expose **Domains** in the single sign-on settings:
 
 ```bash
 SSO_ENABLED=true
 NEXT_PUBLIC_SSO_ENABLED=true
 ```
 
-`ENTERPRISE_ENABLED` turns both on together, but it needs its own browser twin — set `NEXT_PUBLIC_ENTERPRISE_ENABLED` alongside it, or the server and the settings page enable SSO while the login page still hides its SSO entry point. See the [self-hosted enterprise guide](/platform/enterprise/self-hosted).
+You can instead enable the enterprise suite with both `ENTERPRISE_ENABLED=true` and `NEXT_PUBLIC_ENTERPRISE_ENABLED=true`. Set the browser twin too: the login page's SSO entry point reads it before a workspace loads. See [Self-hosted enterprise](/platform/enterprise/self-hosted).
 
-Once enabled, verify domains from **Settings → Organization → Single sign-on → Domains**. The older `/workspace/<workspaceId>/settings/domains` path still resolves to the same page.
+The older `/workspace/<workspaceId>/settings/domains` path still resolves to **Single sign-on → Domains**.
 
 ### Restricted networks
 
-Sim queries `1.1.1.1` and `8.8.8.8` directly from the application server. Allow outbound DNS on UDP and TCP port 53 to these addresses. The lookup uses public DNS rather than the server's local resolver or an HTTP proxy, so the TXT record must be published in a publicly delegated DNS zone. A Route 53 private hosted zone is not visible to these resolvers.
+The application server queries `1.1.1.1` and `8.8.8.8` directly. Allow outbound DNS on UDP and TCP port 53 to both addresses. Verification uses public DNS, not the server's local resolver or an HTTP proxy.
+
+Publish the TXT record in a publicly delegated zone. Private zones, including Route 53 private hosted zones, are not visible to these resolvers.
 
 ### Skip DNS verification
 
-For a deployment where the operator trusts every organization owner and admin to claim email domains, set this server-only variable and restart the application:
+<Callout type="warn">
+  This option delegates domain-claim authority to every organization owner and admin in the self-hosted instance. They can authorize an identity provider for any unclaimed email domain without proving ownership. Enable it only when the operator trusts those administrators to make that decision. It is off by default and ignored on Sim Cloud.
+</Callout>
+
+Set the server-only variable and restart the application:
 
 ```bash
 SSO_SKIP_DOMAIN_VERIFICATION=true
 ```
 
-For Helm deployments, use an application image built from a revision that includes this setting. Upgrading the chart alone does not make an older application image support the variable. Override `app.image.tag` with a compatible released image or a build you publish yourself; set `app.image.repository` as well for a custom repository:
+Under **Domains**, add the domain and select **Verify**. No TXT record or DNS access is needed. Sim records the domain as verified for SSO account linking and SCIM provisioning; another organization still cannot claim it. Existing pending domains can be verified the same way.
+
+For Helm, the application image must support this variable. Updating the chart alone does not add support to an older image. Override `app.image.tag` with a compatible released image or your own build, and set `app.image.repository` if using a custom repository:
 
 ```yaml
 app:
@@ -100,12 +78,11 @@ app:
     SSO_SKIP_DOMAIN_VERIFICATION: "true"
 ```
 
-If `app.image.digest` is set, replace it with a compatible image digest instead — it takes precedence over the tag.
+If `app.image.digest` is set, replace it with a compatible digest instead; it takes precedence over the tag.
 
-Add the domain under **Domains**, then click **Verify**. No TXT record or DNS access is needed. The domain is recorded as verified for SSO account linking and SCIM provisioning, and another organization still cannot claim the same domain. Existing pending domains can be verified the same way.
+Removing the variable or setting it to `false` restores DNS verification for pending and future claims. Already verified domains stay verified. Remove a domain in **Domains** to revoke its trust.
 
-<Callout type="warn">
-  This option is off by default and ignored on Sim Cloud. It applies to every organization in the self-hosted instance: an organization administrator can authorize their identity provider for any unclaimed email domain without proving ownership. Enable it only when those administrators are trusted to make that decision.
-</Callout>
+## Related docs
 
-Removing the variable or setting it to `false` restores DNS verification for pending and future claims. Domains already verified remain verified; remove a domain in **Domains** to revoke its trust.
+- [Single sign-on](/platform/enterprise/sso)
+- [Directory provisioning](/platform/enterprise/scim)
diff --git a/apps/docs/content/docs/platform/enterprise/whitelabeling.mdx b/apps/docs/content/docs/platform/enterprise/whitelabeling.mdx
index f2c3de3e524..046bc2b223a 100644
--- a/apps/docs/content/docs/platform/enterprise/whitelabeling.mdx
+++ b/apps/docs/content/docs/platform/enterprise/whitelabeling.mdx
@@ -1,147 +1,85 @@
 ---
 title: White-labeling
-description: Replace Sim branding with your own logo, colors, and links
+description: Set organization branding or a self-hosted deployment's default identity, colors, and links
 ---
 
-import { FAQ } from '@/components/ui/faq'
-import { Image } from '@/components/ui/image'
+Organization white-labeling sets the logo, colors, and links shown inside your organization's workspaces. Authorized external workspace members also see the workspace's organization branding. Public login, manifest, and file-share surfaces use the separate [instance-wide branding](#instance-wide-branding) baseline.
 
-White-labeling lets you replace Sim's default branding — logo, colors, and support links — with your own. Members of your organization see your brand instead of Sim's throughout the workspace.
+Organization owners and admins configure white-labeling. Billing-enabled deployments require Enterprise. On billing-disabled deployments, organization white-labeling defaults on; explicit `WHITELABELING_ENABLED=false` and `NEXT_PUBLIC_WHITELABELING_ENABLED=false` disable it. See [self-hosted enterprise setup](/platform/enterprise/self-hosted).
 
----
-
-## Setup
-
-### 1. Open White-labeling settings
-
-Go to **Settings → Organization → White-labeling** in your workspace.
-
-<Image src="/static/enterprise/whitelabeling.png" alt="Whitelabeling settings showing brand identity fields (Logo, Wordmark, Brand name), color pickers for primary and accent colors, and link fields for support email and documentation URL" width={900} height={884} className="mx-auto h-auto w-full max-w-xl" />
-
-### 2. Configure brand identity
-
-| Field | Description |
-|-------|-------------|
-| **Logo** | Shown in the collapsed sidebar. Square image (PNG, JPEG, SVG, or WebP). Max 5 MB. |
-| **Wordmark** | Shown in the expanded sidebar and application loading screens. Wide image (PNG, JPEG, SVG, or WebP). Max 5 MB. |
-| **Brand name** | Replaces "Sim" in the sidebar and select UI elements. Max 64 characters. |
-
-Loading screens use the wordmark, never the square logo. Without a wordmark, they show the brand name; when the name is still Sim, they use the built-in Sim wordmark.
-
-### 3. Configure colors
-
-All colors must be valid hex values (e.g. `#701ffc`).
-
-| Field | Description |
-|-------|-------------|
-| **Primary color** | Main accent color used for buttons and active states. |
-| **Primary hover color** | Color shown when hovering over primary elements. |
-| **Accent color** | Secondary accent for highlights and secondary interactive elements. |
-| **Accent hover color** | Color shown when hovering over accent elements. |
-
-### 4. Configure links
-
-Replace Sim's default support and legal links with your own.
-
-| Field | Description |
-|-------|-------------|
-| **Support email** | Shown in help prompts. Must be a valid email address. |
-| **Documentation URL** | Link to your internal documentation. Must be a valid URL. |
-| **Terms of service URL** | Link to your terms page. Must be a valid URL. |
-| **Privacy policy URL** | Link to your privacy page. Must be a valid URL. |
-
-### 5. Save
-
-Click **Save changes**. The new branding is applied immediately for all members of your organization.
-
----
+## Configure organization branding
 
-## What gets replaced
+1. Open **Settings → Organization → White-labeling**.
+2. Set identity, colors, and links using the fields below.
+3. Click **Save**. Refresh other open tabs to pick up changes.
 
-Organization white-labeling replaces the following visual elements:
+### Identity
 
-- **Sidebar logo and wordmark** — your uploaded images replace the Sim logo
-- **Brand name** — appears in the sidebar and select UI labels
-- **Primary and accent colors** — applied to buttons, active states, and highlights
-- **Support and legal links** — help prompts and footer links point to your URLs
+| Field | Use and limit |
+| --- | --- |
+| **Logo** | Square image in the collapsed sidebar. PNG, JPEG, SVG, or WebP; maximum 5 MiB. |
+| **Wordmark** | Wide image in the expanded sidebar and loading screens. Same formats and 5 MiB limit. |
+| **Brand name** | Sidebar and selected UI labels; maximum 64 characters. |
 
-Organization white-labeling applies only to members of your organization. Public-facing surfaces — the login modal, the PWA manifest, and public file-share pages — read the **instance-wide** branding described below instead, and are unaffected by organization settings.
+Loading screens use the wordmark rather than the square logo. Without a wordmark, they use the brand name; the default name Sim uses the built-in Sim wordmark.
 
----
+### Colors
 
-<FAQ items={[
-  {
-    question: "Who can configure white-labeling?",
-    answer: "Organization owners and admins can configure white-labeling. On Sim Cloud, you must be on the Enterprise plan."
-  },
-  {
-    question: "What image formats are supported?",
-    answer: "PNG, JPEG, SVG, and WebP. Maximum file size is 5 MB for both the logo and wordmark."
-  },
-  {
-    question: "What is the difference between the logo and the wordmark?",
-    answer: "The logo is a square image shown in the collapsed sidebar. The wordmark is a wide image shown in the expanded sidebar alongside member names and navigation items."
-  },
-  {
-    question: "Do members outside my organization see the custom branding?",
-    answer: "Organization white-labeling is scoped to your organization — members see it when signed in to your organization's workspace. Instance-wide branding is different: it needs no organization and applies to the whole deployment, including signed-out pages."
-  }
-]} />
+Use valid hex values, such as `#701ffc`.
 
----
+| Field | Use |
+| --- | --- |
+| **Primary color** | Buttons and active states. |
+| **Primary hover color** | Hover state for primary elements. |
+| **Accent color** | Highlights and secondary interactive elements. |
+| **Accent hover color** | Hover state for accent elements. |
 
-## Self-hosted setup
+### Links
 
-Self-hosted deployments use environment variables instead of the billing/plan check, and white-labeling is **already enabled** on one: it defaults on wherever billing is disabled. Configure branding through **Settings → Organization → White-labeling** the same way.
+| Field | Use |
+| --- | --- |
+| **Support email** | Help prompts; must be a valid email address. |
+| **Documentation URL** | Documentation link. |
+| **Terms of service URL** | Terms link. |
+| **Privacy policy URL** | Privacy link. |
 
-### Environment variables
+The URL fields require valid URLs. Check the collapsed and expanded sidebar, a loading screen, and the support/legal links after saving.
 
-To turn it off:
+## Scope and fallback
 
-```bash
-WHITELABELING_ENABLED=false
-NEXT_PUBLIC_WHITELABELING_ENABLED=false
-```
+Saved organization values override the instance baseline inside that organization's workspace. Clearing an organization value restores the corresponding instance or Sim default. The settings read requires organization membership; updates require an owner or admin. Workspace visitors receive branding through their authorized workspace context.
 
----
+Organization branding does not replace the signed-out login identity, PWA manifest, or public file-share identity. Those surfaces read instance settings. The manifest retains built-in icons; public file shares hide the Sim wordmark when an instance logo is configured rather than rendering a custom wordmark there.
 
 ## Instance-wide branding
 
-Instance-wide branding is a separate mechanism from the organization settings above. It is read from environment variables at every render, needs **no organization** and **no** `WHITELABELING_ENABLED`, and applies across the deployment, including surfaces organization settings never reach — though not uniformly. The PWA manifest keeps the built-in icons, and public file-share pages only hide the Sim wordmark rather than rendering yours. It covers the surfaces organization white-labeling never reaches: the login modal, the PWA manifest, and public file-share pages.
+Instance settings need no organization or `WHITELABELING_ENABLED`. They supply a deployment baseline and reach signed-out surfaces as well as workspace fallback values. Set the environment variables on your self-hosted app and apply them through your deployment's update process.
 
-Where both are set, an organization's saved settings take precedence for members of that organization; the instance-wide values are the deployment's baseline.
-
-### Identity
+### Identity variables
 
 ```bash
 NEXT_PUBLIC_BRAND_NAME=Acme
 NEXT_PUBLIC_BRAND_LOGO_URL=/branding/logo.png
 NEXT_PUBLIC_BRAND_WORDMARK_URL=/branding/wordmark.svg
 NEXT_PUBLIC_BRAND_FAVICON_URL=/branding/favicon.ico
-# The CSP's style-src allows only 'self' and fonts.googleapis.com, and takes
-# no configured hosts — in practice this means same-origin.
 NEXT_PUBLIC_CUSTOM_CSS_URL=/branding/custom.css
 ```
 
-`NEXT_PUBLIC_BRAND_FAVICON_URL` and `NEXT_PUBLIC_CUSTOM_CSS_URL` have no organization-level equivalent — these variables are the only way to set a favicon or inject custom CSS.
-
-### Colors
+Favicon and custom CSS have no organization-setting equivalent. Asset URLs reference files; they do not upload them. Custom CSS must be same-origin under the current `style-src` policy, which permits the app origin and Google Fonts rather than configurable external stylesheet hosts.
 
-All colors must be valid hex values.
+### Color variables
 
 ```bash
-NEXT_PUBLIC_BRAND_PRIMARY_COLOR=#701ffc
-NEXT_PUBLIC_BRAND_PRIMARY_HOVER_COLOR=#6518e6
-NEXT_PUBLIC_BRAND_ACCENT_COLOR=#9d54ff
-NEXT_PUBLIC_BRAND_ACCENT_HOVER_COLOR=#8c3dff
-# Not a background: this only tells Sim whether your brand ground is dark,
-# which it uses to pick contrasting text.
-NEXT_PUBLIC_BRAND_BACKGROUND_COLOR=#0c0c0c
+NEXT_PUBLIC_BRAND_PRIMARY_COLOR="#701ffc"
+NEXT_PUBLIC_BRAND_PRIMARY_HOVER_COLOR="#6518e6"
+NEXT_PUBLIC_BRAND_ACCENT_COLOR="#9d54ff"
+NEXT_PUBLIC_BRAND_ACCENT_HOVER_COLOR="#8c3dff"
+NEXT_PUBLIC_BRAND_BACKGROUND_COLOR="#0c0c0c"
 ```
 
-`NEXT_PUBLIC_BRAND_BACKGROUND_COLOR` likewise has no organization-level equivalent.
+`NEXT_PUBLIC_BRAND_BACKGROUND_COLOR` helps choose contrasting text for your brand's background. It does not paint the application background and has no organization equivalent.
 
-### Links
+### Link variables
 
 ```bash
 NEXT_PUBLIC_SUPPORT_EMAIL=support@acme.com
@@ -150,28 +88,30 @@ NEXT_PUBLIC_TERMS_URL=https://acme.com/terms
 NEXT_PUBLIC_PRIVACY_URL=https://acme.com/privacy
 ```
 
-Setting `NEXT_PUBLIC_BRAND_NAME`, `NEXT_PUBLIC_BRAND_LOGO_URL`, `NEXT_PUBLIC_BRAND_WORDMARK_URL`, or `NEXT_PUBLIC_BRAND_PRIMARY_COLOR` marks the deployment as branded; the remaining variables refine it.
+Setting the brand name, logo URL, wordmark URL, or primary color marks the deployment as branded. The other values refine its appearance and links.
 
-### Serving the assets on Kubernetes
+### Serve assets on Kubernetes
 
-The `NEXT_PUBLIC_BRAND_*_URL` variables point at files the app serves — they do not upload anything. On the Helm chart, supply those files through the branding ConfigMap, which is mounted into the app container:
+The Helm chart can mount branding files into the app's public directory:
 
 ```yaml
 branding:
   enabled: true
-  # Serving path for the mounted files
   mountPath: /app/apps/sim/public/branding
-  # Text files (CSS, JSON, SVG) as plain text
   files:
-    custom.css: |
-      .sidebar { background-color: #0c0c0c; }
     wordmark.svg: |
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 24"><text y="18">Acme</text></svg>
-  # Binary files (PNG, JPG, ICO) base64-encoded
-  # base64 -i logo.png | tr -d '\n'
   binaryFiles:
-    logo.png: "iVBORw0KGgoAAAANSUhEUgAA..."
-    favicon.ico: "AAABAAEAEBAAAAEAIABoBAAA..."
+    logo.png: "<base64-encoded PNG>"
+    favicon.ico: "<base64-encoded ICO>"
 ```
 
-With the default `mountPath`, a file named `logo.png` is served at `/branding/logo.png` — the value to give `NEXT_PUBLIC_BRAND_LOGO_URL`. Outside Helm, host the logo, wordmark, and favicon anywhere the browser can reach and point those variables at absolute URLs. `NEXT_PUBLIC_CUSTOM_CSS_URL` is the exception — the CSP's `style-src` takes no configured hosts, so in practice it must be same-origin.
+Use plain text for CSS, JSON, or SVG in `files`; use base64 for PNG, JPEG, or ICO in `binaryFiles`. Replace the example binary placeholders with the actual encodings. With the default mount path, `logo.png` is served at `/branding/logo.png`.
+
+Outside Helm, serve the assets yourself and use URLs reachable by your users' browsers and allowed by your deployment's content security policy. Keep custom CSS same-origin. Verify signed-out login and a public file share separately from the organization's workspace.
+
+## Related docs
+
+- [Self-hosted enterprise setup](/platform/enterprise/self-hosted)
+- [Kubernetes deployment](/platform/self-hosting/kubernetes)
+- [Self-hosting security](/platform/self-hosting/security)
diff --git a/apps/docs/content/docs/platform/meta.json b/apps/docs/content/docs/platform/meta.json
index 4e7ffeec952..6f64105d4b9 100644
--- a/apps/docs/content/docs/platform/meta.json
+++ b/apps/docs/content/docs/platform/meta.json
@@ -4,8 +4,8 @@
     "workspaces",
     "organization",
     "permissions",
-    "connected-accounts",
     "credentials",
+    "connected-accounts",
     "costs"
   ]
 }
diff --git a/apps/docs/content/docs/platform/organization.mdx b/apps/docs/content/docs/platform/organization.mdx
index 44eac34e676..c139846db4c 100644
--- a/apps/docs/content/docs/platform/organization.mdx
+++ b/apps/docs/content/docs/platform/organization.mdx
@@ -1,73 +1,58 @@
 ---
 title: Organizing a workspace
-description: Folders, colors, and naming conventions for keeping a growing workspace understandable.
+description: Group workflows with folders, nesting, ordering, and locks.
 ---
 
-import { Card, Cards } from 'fumadocs-ui/components/card'
+Folders group workflows in the sidebar. Use them to organize a workspace by team, customer, or purpose.
 
-Folders group workflows in the sidebar. Nest or reorder them to organize a [workspace](/platform/workspaces) by team, customer, or purpose.
+You need **Write** or **Admin** access to arrange unlocked folders. Only a workspace **Admin** can lock or unlock them.
 
-{/* VISUAL: before/after sidebar. Left: a flat list of ~20 workflows, no grouping. Right: the same workflows under 3-4 top-level color-coded folders ("Internal", "Customer-Facing", "Ops"), some expanded to show nested subfolders. */}
+## Name and nest folders
 
-## The parts of a folder
+Use category names for folders and action names for workflows. For example:
 
-Here's an example: a folder named **Customer Deployments**, colored red, holding five workflows and two subfolders.
+```text
+Customer operations
+  Customer A
+    Send weekly summary
+    Check overdue invoices
+  Customer B
+    Send weekly summary
+Internal
+  Update support metrics
+```
 
-### Name
+Choose **Create folder** from a folder's menu to add a subfolder. Choose **Rename** to change its name. Keep the hierarchy shallow enough that teammates can find a workflow without opening many levels.
 
-Choose category names such as `Internal`, `Customer-Facing`, or `Ops`. Use the same naming convention across your workspace.
+## Reorder and move folders
 
-{/* VISUAL: a single sidebar folder row showing the expand chevron, color dot, and name "Customer Deployments". */}
+Drag a folder up or down to change its order within a level. Drag it onto another folder to nest it there. Put frequently used folders near the top.
 
-### Color
+Folder names, nesting, and order organize navigation. They do not give different members access to different branches of the workspace.
 
-Folder colors appear as dots beside their names and default to gray (`#6B7280`). Change the color from the folder menu. Use color alongside clear names so the grouping is still understandable without color.
+## Lock a folder
 
-{/* VISUAL: a short vertical stack of folders with distinct color dots: red "Production", gray "Internal", another color for "Customer-Facing", showing color as the grouping signal. */}
+Choose **Lock** from the folder's menu to prevent editing. New folders are unlocked by default.
 
-### Nesting
+A folder lock applies to its workflows and subfolders. A child cannot clear a lock inherited from its parent; unlock the parent first. Otherwise authorized workflows can still run while locked.
 
-Nest folders when a category needs subgroups, for example `Production` → `Customer A` → `Deployments`. Keep the hierarchy shallow enough to scan.
+Use a lock to prevent accidental changes to production logic. Workspace roles and resource permissions still govern access and execution.
 
-{/* VISUAL: a three-level nested tree: "Production" (red, top level) > "Customer A" (yellow) > "Deployments" (purple), each row indented one step, showing the parent-to-child chain. */}
+## Delete and restore a folder
 
-### Order
+Deleting a folder also removes its contents from active lists. Check the affected workflows before choosing **Delete** and confirming the deletion.
 
-Folders display in a set **order**, top to bottom, that you control by dragging them in the sidebar. Drag a folder up or down to reorder it within its level, or drag it onto another folder to move it inside as a subfolder. Order is a convention too: put the folders a team touches daily at the top.
+Deleted items remain recoverable under **Settings → Recently deleted** until retention cleanup removes them. Restore them there when needed. Recovery is subject to the workspace's effective [data retention policy](/platform/enterprise/data-retention).
 
-### Locking
+A locked folder cannot be deleted until its lock is cleared.
 
-A **locked** folder is read-only: its workflows can be viewed but not edited. Locking is off by default. Lock a `Production` folder so members can open and run its workflows without changing them by accident. Locking a folder also locks everything inside it, so a locked parent protects its subfolders and their workflows in one move. Who can lock and unlock follows the workspace [roles and permissions](/platform/permissions).
+## Choose folders or another workspace
 
-{/* VISUAL: the folder context menu open on a folder row, showing the options: rename, change color, lock, duplicate, export, new subfolder, delete. */}
+Keep work in folders when it shares the same team, access rules, and settings. Create another workspace when it needs its own members, credentials, secrets, or resource ownership—for example, a separate customer project with different collaborators.
 
-### Archiving
+Use the same category names across related resources so a table, secret, and workflow are easy to associate. This is a naming convention, not an enforced relationship.
 
-**Archiving** a folder removes it from your active sidebar without deleting it. An archived folder drops out of the normal view, and you restore it when you need it again. Use archiving for cleanup: a finished customer engagement or a retired experiment leaves the sidebar but stays recoverable. There is no permanent hard-delete in the folder menu, so archiving is the safe way to get something out of the way.
+## Related docs
 
-## Conventions
-
-Naming conventions make the structure legible to someone who did not build it. Nothing here is enforced, so the value comes from applying one rule consistently across the workspace.
-
-- **Group by audience or function at the top level.** A common split is `Internal`, `Customer-Facing`, and `Ops`. Someone new can find the right branch from the top-level names alone.
-- **Name folders as categories, workflows as actions.** A folder is a noun (`Billing`); a workflow is a thing it does (`Send overdue reminder`). The folder path plus the workflow name should read as a sentence.
-- **Use color for the top level, names for everything below.** Color carries the coarse grouping; names carry the detail. Mixing both at every level turns into noise.
-- **Mirror the convention everywhere.** The same category words you use for folders are worth reusing for [tables](/platform/workspaces), [secrets](/platform/credentials), and [integrations](/integrations), so a team learns one vocabulary instead of three.
-
-## One workspace or several
-
-Folders organize workflows within a workspace. Use a separate workspace when the work needs its own members, settings, or resource ownership.
-
-- **Group in folders** when everything belongs to the same team and the same access rules, and you only want it easier to navigate.
-- **Split into workspaces** when a set of work needs its own members, its own integrations and secrets, or its own isolation. The classic case is one workspace per customer, where the workspace itself is the deliverable the customer owns.
-
-See [Workspace fundamentals](/platform/workspaces) for what the boundary scopes and [Roles and permissions](/platform/permissions) for how members and seats work across workspaces.
-
-## Next
-
-<Cards>
-  <Card title="Workspace fundamentals" href="/platform/workspaces" description="What a workspace holds and the boundary it scopes." />
-  <Card title="Roles and permissions" href="/platform/permissions" description="Permission levels, members, and seat rules." />
-  <Card title="Secrets" href="/platform/credentials" description="Workspace and personal API keys and variables." />
-  <Card title="Integrations" href="/integrations" description="Connect third-party accounts to a workspace." />
-</Cards>
+- [Workspace fundamentals](/platform/workspaces)
+- [Roles and permissions](/platform/permissions)
diff --git a/apps/docs/content/docs/platform/permissions.mdx b/apps/docs/content/docs/platform/permissions.mdx
index 2c8a14342a7..2a9d6ff86c4 100644
--- a/apps/docs/content/docs/platform/permissions.mdx
+++ b/apps/docs/content/docs/platform/permissions.mdx
@@ -1,258 +1,138 @@
 ---
 title: Roles and permissions
-description: How organization, workspace, and credential roles work together — and how they inherit.
+description: Understand organization roles, workspace access, credential grants, and invitations.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Video } from '@/components/ui/video'
-
-Access in Sim is organized into three nested levels — your **organization**, the **workspaces** inside it, and the **credentials** (connected accounts and secrets) inside those. Each level has its own roles, and roles **inherit downward**: an admin at one level is automatically an admin at the level below. Inheritance only ever *adds* access — it never takes access away from someone who already has it.
+Organization roles, workspace roles, and credential grants control different kinds of access. Administrator roles inherit downward, while resource grants and permission groups govern specific credentials and actions.
 
 ## How roles inherit
 
-Each level has its own set of roles:
-
-| Level | Roles |
-|-------|-------|
-| **Organization** | Owner, Admin, Member |
-| **Workspace** | Read, Write, Admin |
-| **Credentials** (shared connections and secrets) | Member, Admin |
-
-Higher roles flow down automatically:
-
-- An organization **Owner or Admin** is automatically an **Admin of every workspace** in the organization — no per-workspace invite required.
-- A workspace **Admin** is automatically an **Admin of every shared credential** in that workspace — OAuth connections, service accounts, and workspace secrets.
-
-Put together, an organization Owner or Admin can administer every workspace and every shared credential in the organization, top to bottom.
-
-Inherited roles are **automatic and locked**. In member lists they show greyed out with a short tooltip saying where the role comes from (for example, *"Organization admins are automatically workspace admins"*), and they can't be lowered there — you change them at the level they come from.
-
-<Callout type="info">
-**Personal secrets are the one exception.** A user's personal environment variables stay private to them and are never shared or inherited — not by workspace Admins, not by organization Owners or Admins, not by anyone.
-</Callout>
-
-## Workspaces and Organizations
-
-Sim has two kinds of workspaces:
-
-- **Personal workspaces** live under your individual account. The number you can create depends on your plan.
-- **Shared (organization) workspaces** live under an organization and are available on Team and Enterprise plans. Any organization Owner or Admin can create them. When you invite someone to a shared workspace you choose their **Membership**: **Member** or **Admin** makes them an internal member of the organization — they use a seat, and their own workspaces move in with them (see [Joining an organization](#joining-an-organization)) — while **External** gives them access to the selected workspaces only. Invitees who already belong to another organization always become external, because a Sim account belongs to at most one organization.
-
-### Workspace Limits by Plan
-
-| Plan | Personal Workspaces | Shared Workspaces |
-|------|---------------------|-------------------|
-| **Free** | 1 | — |
-| **Pro** | Up to 3 | — |
-| **Max** | Up to 10 | — |
-| **Team / Enterprise** | — | Unlimited (Owners and Admins) |
-
-On Team and Enterprise plans, every workspace you create belongs to the organization. Organization Owners and Admins can create unlimited shared workspaces; organization Members cannot create workspaces. Personal workspaces you owned before joining move into the organization when you accept the invite — see [Joining an organization](#joining-an-organization). Enterprise invites require an available seat at invite time; on Team plans, a seat is added automatically when the invitee accepts.
+| Level | Roles | What it governs |
+| --- | --- | --- |
+| Organization | Owner, Admin, Member | Organization membership, settings, billing, and workspace creation |
+| Workspace | Read, Write, Admin | Resources and actions inside one workspace |
+| Shared credential | Member, Admin | Use and management of an account connection or workspace secret |
 
-<Callout type="info">
-  When a Team or Enterprise subscription is cancelled or downgraded, existing shared workspaces stay accessible to current members. New invitations are blocked until the organization is upgraded again.
-</Callout>
+An organization **Owner** or **Admin** automatically has **Admin** access to every workspace in that organization. A workspace **Admin** automatically administers its shared credentials: OAuth connections, service accounts, and workspace secrets.
 
-## How to Invite Someone to a Workspace
+Inherited roles are locked in member lists. Their tooltip names the source, such as **Workspace owner** or **Organization admins are automatically workspace admins**. Change the role at its source; it cannot be lowered in a child resource's member list. Inheritance adds a role but does not bypass a permission-group restriction on an action.
 
-<div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="invitations.mp4" width={700} height={450} />
-</div>
+Personal secrets belong to their owner. Workspace and organization Admin roles do not grant access to them. Workflow resolution respects current credential grants; the current Secrets editor manages your own personal values and does not offer personal-secret sharing.
 
-One invite covers everything you give a person at once: enter their emails, select **one or more workspaces**, set the workspace access level, and choose their **Membership**. The same dialog opens from the workspace header and from organization settings.
+## Workspace permission levels
 
-Invites to the same person add up rather than stacking. If you invite someone to another workspace while their first invite is still pending, the new workspace is added to that invitation — they get one link that grants everything, and accept once.
+| Action | Read | Write | Admin |
+| --- | --- | --- | --- |
+| View workflows and available execution records | Yes | Yes | Yes |
+| Create, edit, or delete unlocked workflows | No | Yes | Yes |
+| Run a draft in the workflow builder | No | Yes | Yes |
+| Deploy workflows | No | No | Yes |
+| Create workspace secrets | No | Yes | Yes |
+| Manage an existing workspace secret | With that secret's Admin grant | With that secret's Admin grant | Yes |
+| Invite or remove workspace members; manage workspace settings | No | No | Yes |
+| Delete the workspace | No | No | Yes |
 
-Because one pending invite can span several workspaces, revoking is scoped to where you do it. Revoking from a workspace's **Teammates** list withdraws that workspace's access only and leaves the rest of the invitation pending; the invitation is cancelled outright when you remove its last workspace. To cancel the whole thing at once, revoke it from organization settings — that needs organization admin, or admin on every workspace the invite covers.
+Write and Admin members can collaborate on workflow editing in real time. Credential grants and permission-group controls still apply to the relevant action. Read access to a secret name does not mean its value can be revealed or used.
 
-## Workspace Permission Levels
+Authenticated execution of an already deployed workflow through the API has a **Read** workspace-role floor. The API credential must also satisfy the endpoint's credential policy and OAuth scope where applicable. Manual draft execution requires **Write** and a supported human credential. See [API authentication](/api-reference/authentication).
 
-When inviting someone to a workspace, you can assign one of three permission levels:
+### Workspace owner
 
-| Permission | What They Can Do |
-|------------|------------------|
-| **Read** | View workflows, see execution results, but cannot make any changes |
-| **Write** | Create and edit workflows, run workflows, manage environment variables |
-| **Admin** | Everything Write can do, plus invite/remove users and manage workspace settings |
+The workspace owner is an Admin with a fixed role, not another permission tier. Other Admins can manage the workspace and delete it.
 
-## Internal Members vs External Workspace Members
+Organization owners and admins cannot be removed through a workspace's member list; change their organization role or membership first. If a removable owner of an organization workspace is removed, ownership transfers to the workspace's protected billing account, normally the organization's owner. That account cannot be removed from the workspace. The owner of a personal workspace cannot remove themselves.
 
-Workspace permissions are separate from organization membership:
+## Organization roles
 
-- **Internal organization members** belong to your organization, appear in the organization roster, and count toward your seat total. Invite new teammates this way when they should be part of your company or team in Sim.
-- **External workspace members** have access only to the workspaces they are invited to. They are not part of your organization: they do not count toward your seats, their own workspaces stay theirs, and they appear in your roster with an **External** label so admins can always see and revoke their access. Use external access for clients, partners, and contractors.
+| Role | Access |
+| --- | --- |
+| **Owner** | Admin capabilities, plus transferring organization ownership; one owner per organization |
+| **Admin** | Manage members and roles, organization settings, billing and seats; inherit Admin access to every organization workspace |
+| **Member** | Work in workspaces they are granted; view the member directory when permitted; cannot administer the organization |
 
-You pick between the two with the **Membership** option when sending an invite. Three rules apply:
+On billing-enabled deployments, organization owners and admins create shared workspaces under an active team or Enterprise plan. On billing-disabled deployments, organization members may also create them, subject to deployment settings and permission-group restrictions.
 
-- **External is only available for people already on a paid Sim plan** — their own Pro or Max subscription, or membership in another organization that seats them. External collaborators do not use one of your seats, so they have to be paying for Sim somewhere else. Inviting someone on the free plan as External is rejected with a message telling you to invite them as a Member or Admin instead, which adds a seat.
-- **Invitees who already belong to another organization are always external**, whatever you pick, because an account belongs to at most one organization.
-- **Inviting someone as a Member to the organization itself always includes access to at least one workspace**, so every new member has somewhere to land.
+## Invite someone to a workspace
 
-Invitees see what they are agreeing to before they accept. The accept screen names every workspace they are being given, says whether they are joining as a member, an admin, or an external collaborator, says whether that uses one of your seats, and names any of their own workspaces that will move into the organization.
+Open **Invite teammates** from the workspace header. For an organization workspace:
 
-External workspace members still receive a workspace permission level — Read, Write, or Admin — and that permission controls what they can do inside the workspace.
+1. Enter the **Emails** to invite.
+2. Select one or more **Workspaces**.
+3. Choose **Workspace access**: **Read**, **Write**, or **Admin**.
+4. Choose **Organization membership**: **Member**, **Admin**, or **External**.
+5. Send the invitation.
 
-## Joining an organization
-
-Accepting an invite that makes you an **internal member** does more than grant access — it brings your work under the organization:
-
-- **Your workspaces move with you.** Every personal workspace you own, archived ones included, becomes an organization workspace. The accept screen names the workspaces that will move before you accept.
-- **You keep Admin on them.** You remain their administrator; organization Owners and Admins also gain Admin access through the normal [role inheritance](#how-roles-inherit), and usage in those workspaces is billed to the organization from then on.
-- **Your collaborators are not pulled in.** Anyone you had shared those workspaces with keeps their access as an **external member** — they never join the organization or consume a seat as a side effect of your joining.
-- **The workspaces stay if you leave.** If you later leave or are removed from the organization, workspaces you brought in remain with the organization.
-
-Accepting an **external** invite changes none of this: you get access to the invited workspace only, and everything you own stays yours.
+Only an organization owner or admin can grant organization Admin membership. A workspace Admin can grant workspace access without gaining organization billing authority.
 
-## What Each Permission Level Can Do
+For an internal builder, choose Member with Write workspace access. For an external stakeholder who only needs visibility, choose External with Read access, subject to the eligibility rules below.
 
-Here's a detailed breakdown of what users can do with each permission level:
+### Invite someone to the organization
 
-### Read Permission
+An organization-only invitation uses **Emails** and **Role**. It grants membership without selecting workspaces. Organization Members need a workspace grant to work there; Owners and Admins inherit workspace Admin access.
 
-**What they can do:**
-- View all workflows in the workspace
-- See workflow execution results and logs
-- Browse workflow configurations and settings
-- View environment variables (but not edit them)
+A Sim account can belong to at most one organization. An organization-only invitation to someone in another organization is rejected until they leave it. A workspace invitation can instead give them external access.
 
-**What they cannot do:**
-- Create, edit, or delete workflows
-- Run or deploy workflows
-- Change any workspace settings
-- Invite other users
+### Pending invitations and revocation
 
-### Write Permission
+Pending workspace invitations to the same person can combine selected workspaces into one invitation link. They accept the combined grants once.
 
-**What they can do:**
-- Everything Read users can do, plus:
-- Create, edit, and delete workflows
-- Run workflows
-- Add, edit, and delete workspace environment variables
-- Use all available tools and integrations
-- Collaborate in real-time on workflow editing
+Revoking from a workspace's **Teammates** list withdraws only that workspace's grant. Other grants remain pending; removing the last one cancels the invitation. Revoking from organization settings cancels the whole invitation and requires organization admin authority or Admin access to every workspace it covers.
 
-**What they cannot do:**
-- Invite or remove users from the workspace
-- Change workspace settings
-- Delete the workspace
+## Internal and external membership
 
-### Admin Permission
+**Internal members** belong to the organization and use seats on billing-enabled team plans. **External collaborators** have only the selected workspace grants. They do not join your organization, use one of its seats, or bring their own workspaces into it. They appear in the roster with an **External** label and still have Read, Write, or Admin workspace access.
 
-**What they can do:**
-- Everything Write users can do, plus:
-- Deploy workflows
-- Invite new users to the workspace with any permission level
-- Remove users from the workspace
-- Manage workspace settings and integrations
-- Administer every shared credential in the workspace (OAuth connections, service accounts, and workspace secrets)
-- Delete workflows created by other users
-- Delete the workspace
-
-**What they cannot do:**
-- Change a role that's inherited from a higher level — an organization admin's workspace role, or the owner's, is locked and managed where it comes from
-
----
+On Sim Cloud and other billing-enabled deployments:
 
-## Workspace Owner
+- An external collaborator must already have paid Sim access through their own Pro or Max plan or membership in another paid organization. Otherwise, invite them as Member or Admin to add a seat.
+- Someone already in another organization joins an invited workspace as external, rather than becoming an internal member of a second organization.
+- Enterprise invitations require available fixed seat capacity. Team plans add a seat when a new internal member accepts.
+- Inviting from a paid personal workspace can create an organization and convert the subscription to its team tier when the invitation is accepted.
+- Existing shared workspaces remain accessible to current members after the organization plan lapses. New invitations are blocked until an eligible plan is restored.
 
-Every workspace has one **Owner** — usually the person who created it. The Owner is simply an Admin whose role is fixed: in the member list it shows as a locked **Admin** (tooltip *"Workspace owner"*), so it can't be lowered. An Owner has no abilities a regular Admin lacks.
+Billing-disabled deployments do not require paid external access or paid seats. Workspace and organization authorization still applies.
 
-Any Admin — whether invited directly or an admin by way of their organization role — can manage members and settings and delete the workspace. On a shared workspace an Admin can also remove the Owner; ownership then passes to the organization's owner, so the workspace always has one. (The organization's owner is the one account that can't be removed this way — they're the final fallback.) On your personal workspace you are the Owner and can't be removed.
+See [Credits, billing and limits](/platform/costs) for credit pooling, spend controls, and current plan limits.
 
----
-
-## Common Scenarios
+## Joining an organization
 
-### Adding a New Developer to Your Team
-1. **Organization level**: Invite them as an **Organization Member**
-2. **Workspace level**: Give them **Write** permission so they can create and edit workflows
+The acceptance screen names the granted workspaces, membership role, seat consequence, and personal workspaces that will move. Review these before accepting an internal invitation:
 
-### Adding a Project Manager
-1. **Organization level**: Invite them as an **Organization Member** 
-2. **Workspace level**: Give them **Admin** permission so they can manage the team and see everything
+- Every personal workspace you own moves into the organization, including archived workspaces.
+- You keep Admin access to those workspaces. Organization Owners and Admins also gain Admin access through inheritance.
+- Usage in the moved workspaces is attributed to the organization.
+- Existing collaborators keep their workspace access as external collaborators; they do not join the organization or consume a seat as a side effect.
+- The moved workspaces remain with the organization if you later leave or are removed.
 
-### Adding a Stakeholder or Client
-1. **Membership**: If they should not join your organization, set Membership to **External** — this needs them to already be on a paid Sim plan, since external collaborators do not use one of your seats
-2. **Workspace level**: Give them **Read** permission so they can see progress but not make changes
+An external invitation grants only the invited workspace access. Your owned workspaces stay where they are.
 
----
+### Removal and credential effects
 
-## Environment Variables
+Removing an internal organization member revokes their organization workspace access and reassigns their workflows so deployed work can continue. Workspaces they brought into the organization remain there.
 
-Users can create two types of environment variables:
+Credentials backed by their personal identity, such as OAuth accounts and their personal environment keys, can stop resolving in those workspaces. The removal dialog identifies affected credentials before confirmation. Reconnect affected accounts with a remaining member, and move production secrets to workspace scope with appropriate grants.
 
-### Personal Environment Variables
-- Only visible to the individual user, and never shared or inherited — not even by workspace or organization admins
-- Available in all workflows they run
-- Managed in **Settings**, then go to **Secrets**
+Removing a member's last organization workspace grant can also remove their organization membership and seat. Organization owners and admins retain inherited workspace access until their organization role or membership changes.
 
-### Workspace Environment Variables
-- **Read**: see variable names (the values stay hidden unless you're an admin of that secret)
-- **Write**: add new variables, and edit or delete ones you created
-- **Admin**: add, edit, delete, and view the values of any workspace variable
-- Workspace variables are a kind of workspace credential, so they follow the [Credential Access](#credential-access) rules below — workspace Admins are admins of all of them
-- Available to all workspace members. If a workspace variable and a personal variable share the same name, the **workspace** value wins when a workflow runs
+## Credential access
 
----
+Shared OAuth connections, service accounts, and workspace secrets have two credential roles:
 
-## Credential Access
+| Role | Access |
+| --- | --- |
+| **Member** | Use the credential in authorized workflows |
+| **Admin** | Use, edit, delete, and share the credential |
 
-Workspace credentials — OAuth connections, service accounts, and workspace environment variables — have two roles of their own:
+Creators administer their credentials. Workspace Admins inherit Admin access to every shared credential; those inherited roles cannot be demoted in the credential's member list. Read and Write workspace members need an active credential grant to use a shared credential. Pending or revoked grants do not authorize use.
 
-- **Credential Member**: can use the credential in workflows.
-- **Credential Admin**: can use it and also edit, delete, and share it.
+For workspace secrets, Admin authority also allows revealing the value. A Credential Member can reveal it only when **Show value in logs and Chat** is enabled. Personal secrets do not inherit workspace Admin access. Among values the execution actor may use, a workspace secret takes precedence over a personal secret with the same name; an inaccessible workspace value does not shadow an authorized personal value.
 
-These roles follow your workspace role:
+See [Secrets](/platform/credentials) for management, runtime identity, and disclosure controls. [Credential Groups](/platform/connected-accounts) use separate organization account-pool grants.
 
-- **Workspace Admins are automatically Credential Admins** of every shared credential in the workspace (OAuth connections, service accounts, and workspace environment variables). Because organization Owners and Admins are workspace Admins everywhere, they are Credential Admins too. These automatic roles are fixed — they show greyed out with a tooltip in the credential's member list and cannot be changed.
-- **Read and Write members need an active credential grant** to use a shared credential. Credential Members have use access; Credential Admins can also edit, delete, and share it. You are an admin of credentials you create.
-- **Personal environment variables** are the exception: they stay private to their owner and are never shared with workspace admins.
+## Permission groups
 
-<Callout type="info">
-  A Credential Admin can both use and manage a credential, so a workspace Admin can run workflows that use any shared OAuth connection in the workspace — including one another member added.
-</Callout>
+Enterprise-entitled organizations can restrict model providers, integrations, individual tools, deployments, invitations, and other platform actions with [permission groups](/platform/enterprise/access-control). A group restricts access; it does not grant workspace membership or a credential role.
 
----
+Sim chooses one governing group for a person in each workspace: an explicit member group first, then an empty inheritance-mode group for that workspace, then the organization default. An empty explicit-membership group, including a SCIM-managed group, governs nobody. Removing the last member of an inheritance-mode group can broaden it to all workspace members.
 
-## Organization Roles
-
-An organization has three roles: **Owner**, **Admin**, and **Member**.
-
-### Organization Owner
-**What they can do:**
-- Everything an Admin can do
-- Transfer organization ownership to another user
-- Only one Owner exists per organization
-
-### Organization Admin
-**What they can do:**
-- Invite and remove team members from the organization
-- Create new shared workspaces under the organization
-- Manage billing, seat count, and subscription settings
-- Access every shared workspace in the organization as a workspace Admin automatically (no per-workspace invite), including administering the credentials inside them
-- Promote members to Admin or demote Admins to Member
-
-<Callout type="info">
-  Owners and Admins have the same day-to-day permissions. The only action reserved for the Owner is transferring ownership.
-</Callout>
-
-### Organization Member
-**What they can do:**
-- Access shared workspaces they've been specifically invited to
-- View the list of organization members
-- Cannot invite new people, create shared workspaces, or manage organization settings
-
-import { FAQ } from '@/components/ui/faq'
-
-<FAQ items={[
-  { question: "What is the difference between organization roles and workspace permissions?", answer: "Organization roles (Owner, Admin, or Member) control who can manage the organization itself, including inviting people, creating shared workspaces, and handling billing. Workspace permissions (Read, Write, Admin) control what a user can do within a specific workspace, such as viewing, editing, or managing workflows. Internal members need both an organization role and a workspace permission to work within a shared workspace. External workspace members do not have an organization role in your org; they only have workspace-level access." },
-  { question: "What happens to my personal workspaces when I join an organization?", answer: "They move into the organization when you accept the invite — archived workspaces included. The accept screen names the workspaces that will move before you accept. You stay their Admin, organization Owners and Admins gain Admin access through role inheritance, and usage in them is billed to the organization from then on. People you had shared them with keep access as external members. If you later leave the organization, those workspaces stay with it. Accepting an external invite never moves anything — everything you own stays yours." },
-  { question: "What happens when a member is removed from the organization?", answer: "Their workspace access is revoked and workflows they created are reassigned so deployed automations keep running. Credentials backed by their personal identity — OAuth connections and personal environment keys they own — stop working until another member reconnects them; the removal dialog names the affected credentials before you confirm. Workspaces they brought into the organization stay with the organization." },
-  { question: "What happens to my shared workspaces if I cancel or downgrade my Team plan?", answer: "Existing shared workspaces remain accessible to current members, but new invitations are disabled until you upgrade back to a Team or Enterprise plan. No workspaces or members are deleted — the organization is simply dormant until billing is re-enabled." },
-  { question: "Can I restrict which integrations or model providers a team member can use?", answer: "Yes, on Enterprise-entitled organizations. Any organization owner or admin can create permission groups with fine-grained controls, including restricting allowed integrations and allowed model providers to specific lists. You can also disable access to MCP tools, custom tools, skills, and various platform features like the knowledge base, API keys, or Copilot on a per-group basis. Permission groups are scoped to the organization and can govern either all workspaces or a specific subset — a user can belong to multiple groups but is governed by exactly one group in any given workspace." },
-  { question: "What happens when a personal environment variable has the same name as a workspace variable?", answer: "Among values the execution actor can use, the workspace variable takes precedence. An inaccessible workspace variable does not shadow an authorized personal value." },
-  { question: "Can an Admin remove the workspace owner?", answer: "On a shared (organization) workspace, yes — any Admin can remove the workspace Owner, and ownership passes to the organization's owner so the workspace always has one. The organization's owner is the single account that can't be removed this way, since they're the final fallback. On your personal workspace you are the Owner and can't remove yourself. The Owner is not a higher permission tier than Admin: every Admin — including those who inherit the role from their organization — can manage members and settings and delete the workspace." },
-  { question: "Who can manage a workspace's credentials and secrets?", answer: "Workspace Admins are automatically Credential Admins of the workspace's shared credentials — OAuth connections, service accounts, and workspace environment variables — so they can use, edit, delete, and share them, and run workflows that rely on them. Organization Owners and Admins get this too because they are workspace Admins everywhere. Read and Write members can use shared credentials when they have an active Credential Member or Credential Admin grant. Personal environment variables are never shared; they stay private to their owner." },
-  { question: "What are permission groups and how do they work?", answer: "Permission groups are an Enterprise access control feature that lets organization owners and admins define granular restrictions beyond the standard Read/Write/Admin roles. The organization's default group is org-wide; every other group targets specific workspaces and, by default, governs all members of those workspaces (including external members) — add members to restrict it to specific people. A user is governed by one group per workspace: a group they're an explicit member of takes precedence over an all-members group (one with no members) on that workspace, which takes precedence over the organization's default group. A permission group can hide UI sections (like trace spans, knowledge base, API keys, or deployment options), disable features (MCP tools, custom tools, skills, invitations), and restrict which integrations and model providers its members can access. Only one group per organization can be the default; it ignores members and governs everyone not covered by a workspace group, including external members. Restrictions are enforced based on the organization that owns the workflow's workspace, not on which workspace you're currently viewing." },
-  { question: "How should I set up permissions for a new team member?", answer: "Start with the lowest permission level they need. Invite them with Read workspace access if they only need visibility, Write if they need to create and run workflows, or Admin if they need to manage the workspace and its users, and leave Membership on Member. For clients, partners, and contractors, choose External so they collaborate without joining your organization or using a seat — this requires them to already be on a paid Sim plan, either their own Pro or Max subscription or another organization that seats them." },
-]} />
+These restrictions govern human principals, including personal API keys and OAuth credentials, in the resource's owning workspace. A workspace API key has no user's group; it follows its workspace scope, allowed endpoint policies, and role ceiling. Creating or managing that key remains an authorized action.
diff --git a/apps/docs/content/docs/platform/self-hosting/architecture.mdx b/apps/docs/content/docs/platform/self-hosting/architecture.mdx
index 7002b69976d..6d2eb34ba1f 100644
--- a/apps/docs/content/docs/platform/self-hosting/architecture.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/architecture.mdx
@@ -1,112 +1,116 @@
 ---
 title: Architecture
-description: Every service Sim runs, what it depends on, and where state lives
+description: Services, dependencies, request paths, and durable state in a self-hosted deployment
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { FAQ } from '@/components/ui/faq'
 
-Understanding what runs where makes every other operational decision — scaling, backup, network policy, upgrades — straightforward.
+Sim runs an app, a realtime server, PostgreSQL, Redis, and a scheduler. This page shows their dependencies and the state you need to preserve.
 
 ## Services
 
-| Service | Image | Port | Stateless | Required |
+| Service | Image | Port | State | Required |
 |---|---|---|---|---|
-| **app** | `ghcr.io/simstudioai/simstudio` | 3000 | Only with object storage configured | Yes |
-| **realtime** | `ghcr.io/simstudioai/realtime` | 3002 | Yes | Yes |
-| **migrations** | `ghcr.io/simstudioai/migrations` | — | Yes (runs once) | Yes |
-| **postgresql** | `pgvector/pgvector:pg17` | 5432 | **No** | Yes |
-| **redis** | `redis:7-alpine` | 6379 | Mostly | Yes past one replica; bundled by default |
-| **cron** | `ghcr.io/simstudioai/cron` (Compose) / `curlimages/curl` (CronJobs) | — | Yes | Yes, unless you disable scheduled jobs |
-| **pii** | `ghcr.io/simstudioai/pii` | 5001 | Yes | Optional |
-| **ollama** | `ollama/ollama` | 11434 | **No** (model cache) | Optional |
-| **telemetry** | `otel/opentelemetry-collector-contrib` | 4317/4318 | Yes | Optional |
+| **app** | `ghcr.io/simstudioai/simstudio` | 3000 | Local uploads unless shared storage is configured | Yes |
+| **realtime** | `ghcr.io/simstudioai/realtime` | 3002 | In-flight collaboration state | Yes |
+| **migrations** | `ghcr.io/simstudioai/migrations` | — | One-shot schema and data migrations | Yes |
+| **postgresql** | `pgvector/pgvector:pg17` | 5432 | Durable application data | Yes |
+| **redis** | `redis:7-alpine` | 6379 | Cache, coordination, and live events | Bundled by default; required across replicas |
+| **cron** | `ghcr.io/simstudioai/cron` (Compose) / `curlimages/curl` (Kubernetes) | — | None | Required for scheduled work |
+| **pii** | `ghcr.io/simstudioai/pii` | 5001 | None | Optional |
+| **ollama** | `ollama/ollama` | 11434 | Model cache | Optional |
+| **telemetry** | `otel/opentelemetry-collector-contrib` | 4317/4318 | None | Optional |
 
-### app
+### App
 
-The Next.js application: the editor UI, every API route, and the workflow execution engine. Workflow runs happen **inside the app process** by default, using an isolated-vm sandbox, which is why memory rather than CPU is the constraining resource. The chart requests 4 Gi and caps the app at 8 Gi; `docker-compose.prod.yml` sets only an 8 GB limit, with no reservation. Configuring a remote sandbox provider (E2B or Daytona) moves code execution out of the process; see [Security](/platform/self-hosting/security).
+The Next.js app serves the workflow builder, API routes, and workflow orchestration. Local JavaScript runs in Node child workers using isolated-vm inside the app container. The app and those workers share the container's memory budget. The Helm chart requests 4 GiB and limits the app to 8 GiB; `docker-compose.prod.yml` sets an 8 GB memory limit without a reservation.
 
-Any replica can serve any request **once object storage is configured**. Until then the app writes uploads to its own container filesystem, which makes it stateful — see [Where state lives](#where-state-lives). Scale it horizontally only after reading [Scaling & HA](/platform/self-hosting/scaling) for the Redis, storage, and connection-pool prerequisites.
+E2B or Daytona moves supported code execution to a remote sandbox. `TRIGGER_DEV_ENABLED` routes asynchronous jobs to Trigger.dev; the default deployment uses database-backed jobs. See [Sandboxes](/platform/self-hosting/sandboxes) for the provider and image requirements.
 
-### realtime
+Any replica can serve files once shared object storage is configured. Before adding replicas, configure storage, Redis, and database connection capacity as described in [Scaling and high availability](/platform/self-hosting/scaling).
 
-A Bun Socket.IO server handling collaborative editing, live execution updates, and collaborative documents. Clients connect at `/socket.io`.
+### Realtime
 
-It shares the database and `BETTER_AUTH_SECRET` with the app (Better Auth's shared-database-session pattern), so it authenticates the same users without a separate login.
+The Bun Socket.IO server carries collaborative editing, live execution updates, and collaborative documents. Clients connect at `/socket.io`.
+
+Realtime shares PostgreSQL and `BETTER_AUTH_SECRET` with the app, using Better Auth's shared-database-session pattern. It authenticates the same accounts without a separate login.
 
 <Callout type="warn">
-  Scaling realtime past one replica **requires** `REDIS_URL` — the Socket.IO Redis adapter is what carries events between pods. Without it, two users on different pods silently stop seeing each other's edits.
+  More than one realtime replica requires `REDIS_URL`. The Socket.IO Redis adapter carries events between replicas; without it, members connected to different pods do not see each other's edits.
 </Callout>
 
-### migrations
+A realtime server must exist for editing and live updates. Set `realtime.enabled: false` in Helm only when `app.env.SOCKET_SERVER_URL` points to a realtime instance you run separately.
 
-Applies Drizzle schema migrations, then exits. In Docker Compose it is a one-shot service; in Kubernetes it is an **init container on the app Deployment**, so migrations run before any app pod becomes ready and re-run (as a no-op) on every rollout.
+### Migrations
 
-Migrations are forward-only. See [Upgrades](/platform/self-hosting/upgrades).
+The migrator applies Drizzle SQL and registered data migrations, then exits. Compose runs it as a one-shot service. Helm runs it as an app init container, so migrations complete before that app pod starts. Later pods and rollouts run the migrator again; already-applied migrations are skipped.
 
-### postgresql
+Migrations are forward-only. See [Upgrades](/platform/self-hosting/upgrades) for backup and rollback procedures.
 
-PostgreSQL 17 with the **pgvector** extension, which is required — knowledge base embeddings are stored and searched as vectors. The `pgvector/pgvector:pg17` image ships it; a managed instance needs the extension enabled (Sim's migrations issue `CREATE EXTENSION` automatically where permissions allow).
+### PostgreSQL
 
-This holds essentially all durable state: workflows, runs, logs, users, organizations, credentials, knowledge base chunks and embeddings, and table data.
+Sim requires PostgreSQL with the pgvector extension for knowledge base embeddings. The bundled image uses PostgreSQL 17 and includes pgvector. On managed PostgreSQL, make the extension available; migrations issue `CREATE EXTENSION` where permissions allow.
 
-### redis
+PostgreSQL holds workflows, runs, logs, accounts, organizations, credentials, knowledge base chunks and embeddings, table data, and upload-session state.
 
-Backs pub/sub, the Socket.IO adapter, the idempotency store, execution progress markers, distributed execution limits, and the CLI-auth approval store. The idempotency store and execution progress markers fall back to Postgres or in-process state. The pairing-code approval store has no fallback, so API-key login through pairing requires Redis. OAuth login uses a separate path. Pub/sub falls back to a **process-local** emitter, which is fine on one replica and drops every cross-pod event on more than one. See [Redis](/platform/self-hosting/redis).
+### Redis
 
-### cron
+Redis carries live events and stores shared coordination state. Some stores fall back to PostgreSQL or process-local state, but cross-pod collaboration has no local fallback. CLI API-key pairing also requires Redis, even with one replica; OAuth login uses a separate path. See [Redis](/platform/self-hosting/redis) for the full fallback matrix.
 
-Scheduled jobs call internal endpoints — schedule execution, polling triggers, webhook-subscription renewal, connector syncs, outbox processing, data drains, workspace file-search dispatch, table row TTL cleanup, inbox-entitlement reconciliation, and sandbox-image cleanup. Kubernetes runs them as CronJobs; Docker Compose runs them from a single supercronic service. Same paths, same schedules. See [Background Jobs](/platform/self-hosting/background-jobs).
+### Scheduler
 
-## Where state lives
+Scheduled workflows, polling triggers, connector syncs, subscription renewal, and maintenance jobs call authenticated app endpoints. Helm provides CronJobs; Compose provides a supercronic service. See [Background jobs](/platform/self-hosting/background-jobs) for the shipped inventory and the additional upload-session cleanup schedule operators must configure.
+
+### Optional Chat service
 
-Three places once the deployment is configured for production. Everything else is disposable.
+The chart can also render the optional `copilot` service, its separate PostgreSQL database, and its migration job. These are separate from the app and workflow database. Enabling them requires the service's image, license, credentials, and database configuration; see the chart's `copilot` values and [reference architectures](/platform/self-hosting/reference-architectures).
+
+## Where state lives
 
 | Store | Contents | Backup |
 |---|---|---|
-| **PostgreSQL** | All application data | `pg_dump` / managed snapshots + PITR |
-| **Object storage** | Uploaded files, KB documents, execution outputs, avatars, logos | Bucket versioning + lifecycle |
-| **Secrets** | `ENCRYPTION_KEY`, `API_ENCRYPTION_KEY`, `BETTER_AUTH_SECRET`, `INTERNAL_API_SECRET`, `CRON_SECRET` | Secret manager |
+| **PostgreSQL** | Application data, including any separately enabled Chat-service database | `pg_dump`, managed snapshots, and point-in-time recovery |
+| **Object storage** | Files, knowledge base documents, execution outputs, avatars, and logos | Bucket versioning and lifecycle policies |
+| **Secrets** | `ENCRYPTION_KEY`, `API_ENCRYPTION_KEY`, `BETTER_AUTH_SECRET`, `INTERNAL_API_SECRET`, `CRON_SECRET` | Secret manager and separate recovery copies |
 
 <Callout type="error">
-  **Object storage is not configured by default, and the fallback is not durable.** Sim only uses S3, Azure Blob, or GCS when the corresponding variables are set (`S3_BUCKET_NAME` + `AWS_REGION`, `AZURE_STORAGE_CONTAINER_NAME` + credentials, or `GCS_BUCKET_NAME`). With none set it writes uploads to a directory inside the app container — and neither `docker-compose.prod.yml` nor the Helm chart mounts a volume there. Files are lost when the container is recreated and are invisible to other replicas. Configure [object storage](/platform/self-hosting/object-storage) before storing anything you care about, and before scaling past one replica.
+  Neither the production Compose file nor the Helm chart mounts a volume for local uploads. Without configured cloud storage or your own volume, recreating the app container loses those files. Local files are also invisible to other replicas. Configure [object storage](/platform/self-hosting/object-storage) before storing durable files or scaling.
 </Callout>
 
 <Callout type="error">
-  `ENCRYPTION_KEY` is not recoverable and not derivable. It encrypts workspace and personal environment variables, stored provider API keys, MCP OAuth credentials, and deployment/chat secrets at rest — a database restore paired with a *different* key yields a working app in which none of that can be decrypted. Back it up separately from the database, and never rotate it casually.
+  Back up `ENCRYPTION_KEY` separately from PostgreSQL. A database restore with a different key cannot decrypt workspace and personal environment variables, stored provider keys, MCP OAuth credentials, or deployment/chat secrets. Recovery requires the original key or re-encryption before rotation.
 </Callout>
 
-Redis is a cache and message bus. Losing it drops in-flight live updates; it does not lose committed data.
+Redis is a cache and message bus, not the owner of committed application data. Losing it interrupts in-flight coordination and live updates; completed data remains in PostgreSQL and object storage.
 
 ## Request paths
 
-**Editor / API** — browser → ingress/reverse proxy → app:3000 → Postgres, Redis, object storage.
-
-**Collaboration** — browser → ingress → realtime:3002 (`/socket.io`, WebSocket upgrade) → Redis pub/sub → other realtime pods. The proxy must pass upgrade headers and allow long-lived idle connections; see [Networking](/platform/self-hosting/networking).
+| Traffic | Path |
+|---|---|
+| Editor / API | Browser → ingress or reverse proxy → app:3000 → PostgreSQL, Redis, storage |
+| Collaboration | Browser → ingress → realtime:3002 (`/socket.io`, WebSocket upgrade) → Redis → other realtime pods |
+| Cloud upload | Browser → app opens upload session → signed transfer instructions → browser uploads directly to storage → app verifies completion and records metadata |
+| Local upload | Browser → app opens upload session → bytes stream through `/api/v2/uploads/...` to local disk |
+| Workflow execution | Manual, API, webhook, or schedule trigger → app enqueues or orchestrates run → local code workers or remote sandbox → results/logs to PostgreSQL, progress markers to Redis |
+| Background work | Scheduler → `Authorization: Bearer $CRON_SECRET` → internal app endpoint |
 
-**File upload (object storage configured)** — browser asks the app to open an upload session → app returns signed transfer instructions → browser sends the bytes **directly to object storage** (one `PUT` up to 50 MB, multipart parts above that) → browser tells the app the session is complete and the app records metadata. This is why buckets need a CORS policy naming your Sim origin. Downloads are proxied back through the app.
-
-**File upload (local disk)** — the same upload session opens, but the transfer instructions point back at the app's own `/api/v2/uploads/...` endpoints instead of a bucket, so the bytes stream through the app. No CORS configuration is involved, and no bucket is used.
-
-**Workflow execution** — trigger (manual, API, webhook, or schedule) → app enqueues or runs inline → isolated-vm sandbox → results and logs to Postgres, progress markers to Redis.
-
-**Background work** — CronJob → `Authorization: Bearer $CRON_SECRET` → app endpoint → same execution path.
+Cloud uploads use a single `PUT` through 50 MiB and multipart above that. Local uploads use a single `PUT` through 8 MiB and multipart above that. Cloud buckets need CORS for the Sim origin and must be reachable from browsers; downloads are proxied through the app. Local uploads need no bucket CORS configuration.
 
 ## Network boundaries
 
 | From | To | Purpose |
 |---|---|---|
-| Internet | app:3000, realtime:3002 | Users |
-| app, realtime | postgresql:5432 | Data |
-| app, realtime | redis:6379 | Pub/sub, cache |
-| app | Object storage endpoint | Files (server side) |
-| **Browser** | **Object storage endpoint** | Presigned uploads — must be publicly reachable |
-| app | Model provider APIs, integration APIs, SMTP/email provider | Outbound |
-| cron | app:3000 (internal Service / compose network) | Scheduled triggers |
-
-The chart's optional NetworkPolicy blocks cloud metadata endpoints (`169.254.169.254`) by default but allows ingress from any pod in the cluster unless you scope `networkPolicy.ingressFrom`. See [Security](/platform/self-hosting/security).
-
-<FAQ items={[
-  { question: "Can I run the app without the realtime service?", answer: "A realtime server must exist — it carries collaborative editing and live execution updates, and the editor degrades badly without one. You can set realtime.enabled=false in the chart, but only when pointing app.env.SOCKET_SERVER_URL at a realtime instance you run yourself."},
-  { question: "Does workflow execution run in a separate worker process?", answer: "By default, no — executions run inside the app process using an isolated-vm sandbox, which is why the app has an 8 Gi memory limit. Setting E2B_ENABLED or SANDBOX_PROVIDER=daytona moves user code to a remote sandbox, and TRIGGER_DEV_ENABLED routes async jobs to Trigger.dev; otherwise the database-backed job queue is used."},
-]} />
+| Internet | app:3000, realtime:3002 | Browser/API traffic |
+| App, realtime | PostgreSQL:5432, Redis:6379 | Data and coordination |
+| App | Object-storage endpoint | Storage operations and proxied downloads |
+| Browser | Object-storage endpoint | Signed uploads |
+| App | Model/integration APIs and email provider | Outbound calls |
+| Scheduler | Internal app:3000 | Scheduled work |
+
+The proxy must support WebSocket upgrades, streams, and long-lived connections. The chart's optional NetworkPolicy excludes cloud metadata addresses from broad egress, but its default ingress peer is broad. Configure the actual peers and managed-datastore paths before enabling it.
+
+## Related docs
+
+- [Reference architectures](/platform/self-hosting/reference-architectures)
+- [Networking](/platform/self-hosting/networking)
+- [Security and hardening](/platform/self-hosting/security)
diff --git a/apps/docs/content/docs/platform/self-hosting/authentication.mdx b/apps/docs/content/docs/platform/self-hosting/authentication.mdx
index c47590f6750..0303f0e92ff 100644
--- a/apps/docs/content/docs/platform/self-hosting/authentication.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/authentication.mdx
@@ -1,25 +1,27 @@
 ---
 title: Authentication
-description: Login providers, SSO, and controlling who can sign up
+description: Configure sign-in, registration, SSO, and Sim OAuth access
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
+Configure the deployment's public origin and shared session secret before choosing login providers or restricting registration.
+
 ## Required configuration
 
-```bash
+```text
 BETTER_AUTH_SECRET=<openssl rand -hex 32>
 BETTER_AUTH_URL=https://sim.yourdomain.com
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 ```
 
-<Callout type="warn">
-  `BETTER_AUTH_URL` and `NEXT_PUBLIC_APP_URL` must be your exact public origin — correct scheme, no trailing slash. Leaving either as `localhost` in a deployed instance breaks sign-in, and the failure looks like a redirect loop rather than a configuration error.
+Replace the secret placeholder with the output of `openssl rand -hex 32`. Use your exact public origin, including scheme, with no trailing slash. Production Compose derives `BETTER_AUTH_URL` from `NEXT_PUBLIC_APP_URL`; see [Docker](/platform/self-hosting/docker).
 
-  `BETTER_AUTH_SECRET` must be **identical** on the app and realtime services. They share sessions through the database; a mismatch means realtime rejects every authenticated socket connection.
+<Callout type="warn">
+  The app and realtime services must use the same `BETTER_AUTH_SECRET`. They share database sessions; a mismatch prevents authenticated socket connections. An incorrect public origin can cause rejected sign-in or redirect loops.
 </Callout>
 
-If users reach Sim from more than one origin — an apex and `www`, or an alias domain — list the extras:
+If the deployment serves additional origins, list them explicitly:
 
 ```bash
 TRUSTED_ORIGINS=https://www.example.com,https://app.example.com
@@ -27,27 +29,27 @@ TRUSTED_ORIGINS=https://www.example.com,https://app.example.com
 
 ## Email and password
 
-Enabled by default. Users sign up with an email address and password.
+Email/password sign-in and signup are enabled by default. To require email verification:
 
 ```bash
 EMAIL_VERIFICATION_ENABLED=true
 ```
 
-Requires a configured email provider — see [Email](/platform/self-hosting/email). Without one the mailer no-ops silently, so users can never verify and never sign in. Do not enable this before email works.
+Verification is enforced only when a mail provider is configured. Test [email delivery](/platform/self-hosting/email) before requiring verification: a configured provider that cannot deliver still prevents new accounts from completing verification. Without a provider, verification is not enforced and invitations and password-reset mail are not delivered.
 
 ## Social login
 
-Three providers are supported for signing in to Sim itself.
+These providers sign members in to Sim itself. Integration account connections use separate callback paths.
 
-| Provider | Variables | Callback URL |
-|---|---|---|
+| Provider | Variables | Login callback |
+| --- | --- | --- |
 | Google | `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | `https://<host>/api/auth/callback/google` |
 | GitHub | `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | `https://<host>/api/auth/callback/github` |
 | Microsoft | `MICROSOFT_CLIENT_ID` / `MICROSOFT_CLIENT_SECRET` | `https://<host>/api/auth/callback/microsoft` |
 
-A provider appears on the login page once its credentials are set. Microsoft additionally requires both variables to be present before it is registered at all.
+Set both credentials to make a provider available on the login page. Microsoft is registered only when both values are present.
 
-Turn one off without removing its credentials — useful when the same Google or Microsoft app powers integrations but you do not want it as a login method:
+To keep credentials for integrations while disabling the corresponding login method:
 
 ```bash
 DISABLE_GOOGLE_AUTH=true
@@ -55,65 +57,82 @@ DISABLE_GITHUB_AUTH=true
 DISABLE_MICROSOFT_AUTH=true
 ```
 
-<Callout type="info">
-  `GOOGLE_CLIENT_ID` and `MICROSOFT_CLIENT_ID` are shared with the integration connectors. One app registration can serve both login and integrations — register that provider's own login callback — `/api/auth/callback/google` for Google, `/api/auth/callback/microsoft` for Microsoft — alongside the connector callbacks (`/api/auth/oauth2/callback/google-email` and friends) on the same OAuth client. See [Integrations & OAuth](/platform/self-hosting/integrations-oauth).
+Google and Microsoft share their client credentials with integrations. Register their login callback alongside the integration callbacks on the same client; see [Integrations and OAuth](/platform/self-hosting/integrations-oauth).
+
+## Control registration and sign-in [#controlling-who-can-sign-up]
+
+| Variable | Effect |
+| --- | --- |
+| `DISABLE_REGISTRATION=true` | Blocks new email/password, email OTP, and social accounts. Existing accounts can sign in, including to accept workspace invitations. SSO registration is unaffected. |
+| `DISABLE_EMAIL_SIGNUP=true` | Blocks new email/password and email OTP registrations. Existing accounts can still sign in through those methods. |
+| `EMAIL_PASSWORD_SIGNUP_ENABLED=false` | Disables email/password and email OTP sign-in and signup, including for existing accounts. |
+| `ALLOWED_LOGIN_DOMAINS` | Comma-separated email domain allowlist, such as `acme.com,acme.co.uk`. Applies to email/password and email OTP sign-in as well as email signup. |
+| `ALLOWED_LOGIN_EMAILS` | Comma-separated address allowlist. An address or its domain may satisfy the allowlists. |
+| `BLOCKED_SIGNUP_DOMAINS` | Comma-separated blocked domains. Blocks signup, sign-in, and executions for addresses in those domains, including subdomains. |
+| `BLOCKED_EMAILS` | Comma-separated banned addresses. Blocks signup, sign-in, and executions. |
+| `SIGNUP_MX_VALIDATION_ENABLED=true` | Checks email/password signup for a domain with no MX record or a blocked mail backend. |
+| `BLOCKED_EMAIL_MX_HOSTS` | MX-host substrings to reject when MX validation is enabled. |
+
+<Callout type="warn">
+  Email allowlists do not filter first-time Google, GitHub, or Microsoft sign-in. To restrict social access, disable login providers you have not vetted or restrict membership through your identity provider and use SSO. MX validation applies only to email/password signup, not sign-in or email OTP. Registration-disabled and blocked-domain/address controls also cover social accounts.
 </Callout>
 
+For example, an installation using SSO while allowing existing company email accounts to sign in can set:
+
+```bash
+ALLOWED_LOGIN_DOMAINS=acme.com
+DISABLE_EMAIL_SIGNUP=true
+SSO_ENABLED=true
+NEXT_PUBLIC_SSO_ENABLED=true
+```
+
+This does not restrict enabled social providers to `acme.com`. Configure or disable those login methods separately.
+
 ## SSO (SAML and OIDC)
 
-SAML and OIDC single sign-on is an enterprise feature, available on self-hosted deployments through configuration rather than billing:
+For a standard billing-disabled self-hosted deployment, enable the enterprise suite:
 
 ```bash
 ENTERPRISE_ENABLED=true
 NEXT_PUBLIC_ENTERPRISE_ENABLED=true
 ```
 
-Or enable just SSO:
+Or enable SSO alone:
 
 ```bash
 SSO_ENABLED=true
 NEXT_PUBLIC_SSO_ENABLED=true
 ```
 
-Providers are then registered in the app under **Settings → Organization → SSO**. A provider can be scoped to an organization or registered without one. Most other enterprise features do read their settings from the organization that owns a workspace, so a deployment using them still needs an organization model — set `INSTANCE_ORG_NAME` to place every user in one shared organization, or provision organizations through the Admin API.
+Set both the server flag and its UI counterpart. Register providers under **Settings → Organization → Single sign-on**. A provider can belong to an organization or be registered without one.
+
+Most other enterprise features read settings from the organization that owns a workspace. Set `INSTANCE_ORG_NAME` to place new members in one organization, or provision organizations through the Admin API. See [SSO](/platform/enterprise/sso) and [Self-hosted enterprise features](/platform/enterprise/self-hosted) for provider setup, organization patterns, and billing-enabled behavior.
+
+## Behind a load balancer
+
+Tell Better Auth which forwarding hops to trust when resolving client IPs:
+
+```bash
+AUTH_TRUSTED_PROXIES=10.0.0.0/24,192.0.2.10
+```
 
-See the [SSO guide](/platform/enterprise/sso) for identity-provider setup and the [self-hosted enterprise guide](/platform/enterprise/self-hosted) for the organization patterns.
+Use your proxy addresses or CIDRs. Better Auth reads `X-Forwarded-For` from right to left, skips trusted proxies, and uses the first untrusted address for session records and IP checks. A range that also trusts client traffic defeats this boundary. See [Security](/platform/self-hosting/security).
 
 ## Sign in with Sim
 
-Your deployment acts as an OAuth 2.0 authorization server using authorization
-code with PKCE. OAuth sign-in is available whenever authentication is enabled;
-see [CLI authentication](/cli/authentication).
+Sim also acts as an OAuth 2.0 authorization server, using authorization code with PKCE. It supports API authorization rather than OpenID Connect identity: it does not issue ID tokens. See [CLI authentication](/cli/authentication).
 
-Apply database migrations before deploying a new app version. When upgrading
-from a version without the OAuth token-family lifecycle, drain older app
-instances before accepting OAuth traffic so every instance enforces the same
-refresh and revocation rules.
+Access tokens are opaque and last one hour. Refresh tokens rotate on use, and each login has a fixed thirty-day lifetime that refresh does not extend. Validation checks current grants: revoking access under **Settings → General → Authorized apps** stops the app on its next request. Scheduled token cleanup runs independently of sign-in activity.
 
-`DISABLE_AUTH=true` disables OAuth sign-in and discovery because authorization
-requires a real Better Auth user session. Older servers without OAuth support
-return 404 from `/.well-known/oauth-authorization-server`, and the CLI falls
-back to the pairing-code handoff.
+`DISABLE_AUTH=true` disables OAuth sign-in and discovery because these require a real member session. Older servers without OAuth support return `404` from `/.well-known/oauth-authorization-server`; the CLI can fall back to pairing-code login.
 
-Access tokens are opaque and last an hour; refresh tokens rotate on every use.
-Each login has a fixed thirty-day lifetime that refreshing does not extend.
-Token validation checks current grants, so revoking a grant under
-**Settings → General → Authorized apps** stops the app on its very next request.
-Scheduled OAuth token cleanup runs independently of sign-in activity.
+### Client registration [#registering-an-app]
 
-Organization admins can restrict **OAuth App Access** under **Credentials & Access**
-in [permission groups](/platform/enterprise/access-control). Workspace requests use
-the group governing that workspace. Authorizing apps, issuing and refreshing tokens,
-and account-level billing and audit reads use the organization's default group.
-**CLI Access** also applies to the Sim CLI. Members can still review and revoke
-existing grants when OAuth app access is restricted.
+MCP clients can use the public registration endpoint at `/api/auth/oauth2/register`. It accepts reviewed callback formats, requires PKCE, and accepts at most 10 redirect URIs in a JSON body capped at 32 KiB. Its per-IP bucket holds 20 registration tokens and refills 20 each minute. Registration grants no resource access by itself. Members must consent, and each MCP grant is narrowed to the API or Search resource it addresses.
 
-### Registering an app
+The available scopes are `offline_access`, `api:read`, `api:write`, and `search:read`. API and Search resource scope families remain distinct. Public registration permits HTTPS callbacks, loopback HTTP callbacks, and the explicitly supported Cursor native callback; it does not accept arbitrary custom URI schemes.
 
-Dynamic client registration is switched off, so clients are created by an
-operator. Both `db:migrate` and the development `db:push` command install the
-OAuth lifecycle triggers and register the Sim CLI. Repeating either command
-preserves existing grants and client customizations. Register other apps with:
+Operators create first-party and confidential clients. Both `db:migrate` and the development `db:push` command install OAuth lifecycle triggers and register the Sim CLI, preserving existing grants and client customizations on repeat runs. From a source checkout, register another app with:
 
 ```bash
 DATABASE_URL=… \
@@ -125,77 +144,44 @@ OAUTH_SCOPES=api:read \
 bun run apps/sim/scripts/create-oauth-client.ts
 ```
 
-Add `OAUTH_CLIENT_PUBLIC=true` for a native or CLI app that cannot keep a
-secret; it then authenticates with PKCE alone. The provider exposes
-`offline_access`, `api:read`, and `api:write` for API authorization; it does not
-expose OpenID Connect identity scopes or issue ID tokens. A confidential
-client's secret is printed once and cannot be read back. Confidential clients
-use `client_secret_basic`; the registration command prints the token
-authentication method alongside the client ID.
+Add `OAUTH_CLIENT_PUBLIC=true` for a native or CLI app that cannot keep a secret. Confidential clients use `client_secret_basic`; the command prints the authentication method and prints the client secret once. The secret cannot be read back.
 
-Redirect URIs must be `https`, or `http` on a loopback address, and are matched
-exactly — except a loopback URI, where any port matches, because a native app
-cannot know its port in advance.
+Operator-registered redirect URIs must use HTTPS or HTTP on a loopback address. They match exactly, except that loopback callbacks may use any port.
 
-## Controlling who can sign up
+### Authorization and upgrades
 
-| Variable | Effect |
-|---|---|
-| `DISABLE_REGISTRATION=true` | Blocks all new accounts — email/password, email OTP, and social sign-in. Only existing accounts can sign in, including to accept a workspace invitation. SSO is unaffected |
-| `DISABLE_EMAIL_SIGNUP=true` | Blocks new email/password registrations; existing email login keeps working |
-| `EMAIL_PASSWORD_SIGNUP_ENABLED=false` | Disables the whole email path — sign-in, signup, and email OTP — for existing users too. Use `DISABLE_EMAIL_SIGNUP` to block only new accounts |
-| `ALLOWED_LOGIN_DOMAINS` | Comma-separated domain allowlist, e.g. `acme.com,acme.co.uk`. Gates email sign-**in** as well as signup |
-| `ALLOWED_LOGIN_EMAILS` | Comma-separated address allowlist, applied the same way |
-| `BLOCKED_SIGNUP_DOMAINS` | Comma-separated domain blocklist |
-| `BLOCKED_EMAILS` | Comma-separated address blocklist. Bans the address from the platform outright — signup, sign-in, and workflow executions |
-| `SIGNUP_MX_VALIDATION_ENABLED=true` | Reject domains with no MX record or a denylisted mail backend |
-| `BLOCKED_EMAIL_MX_HOSTS` | MX-host substrings to block; used only with the above |
-
-<Callout type="warn">
-  `ALLOWED_LOGIN_DOMAINS`, `ALLOWED_LOGIN_EMAILS`, and `SIGNUP_MX_VALIDATION_ENABLED` gate the **email/password** path only — and `SIGNUP_MX_VALIDATION_ENABLED` narrower still, running on email signup alone, not on email sign-in or email OTP. A first-time sign-in through Google, GitHub, or Microsoft creates an account through the social provider and is not filtered by them. To restrict who may sign in through a social provider, disable the ones you have not vetted (`DISABLE_GOOGLE_AUTH`, `DISABLE_GITHUB_AUTH`, `DISABLE_MICROSOFT_AUTH`) or restrict membership at the identity provider and use SSO.
+Organization admins can restrict **OAuth App Access** under **Credentials & Access** in [permission groups](/platform/enterprise/access-control). Workspace requests use the group governing that workspace; authorization, issuance, refresh, and account-level billing/audit reads use the organization's default group. **CLI Access** also applies to the Sim CLI. Members can still inspect and revoke existing grants when OAuth app access is restricted.
 
-  `DISABLE_REGISTRATION` and `BLOCKED_SIGNUP_DOMAINS` apply to every path, social included.
-</Callout>
+Apply database migrations before a new app version. When upgrading from a version without the OAuth token-family lifecycle, drain older app instances before accepting OAuth traffic so all instances enforce the same refresh and revocation rules.
 
-For a company deployment, the usual pairing is domain-restricted signup plus SSO:
-
-```bash
-ALLOWED_LOGIN_DOMAINS=acme.com
-DISABLE_EMAIL_SIGNUP=true
-SSO_ENABLED=true
-NEXT_PUBLIC_SSO_ENABLED=true
-```
-
-Both SSO flags are needed: the server-side one grants access, and the `NEXT_PUBLIC_` one makes the login page render the SSO entry point.
-
-## Behind a load balancer
-
-Tell Better Auth which forwarding hops to trust when resolving the client IP:
-
-```bash
-AUTH_TRUSTED_PROXIES=10.0.0.0/24,192.0.2.10
-```
-
-Better Auth walks `X-Forwarded-For` right to left, skips these hops, and uses the first untrusted address as the client IP for session records and its own IP-based checks. Use your proxies' actual addresses — a broad private range that also covers client traffic defeats the purpose. See [Security](/platform/self-hosting/security).
-
-## Disabling authentication entirely
+## Disable authentication [#disabling-authentication-entirely]
 
 ```bash
 DISABLE_AUTH=true
 ```
 
-Bypasses authentication and creates an anonymous session for every request.
+Requests use a shared anonymous session.
 
 <Callout type="error">
-  Everyone who can reach the instance becomes a fully privileged user — including anything that can reach it through an SSRF bug elsewhere on your network. Use this only for a single-user instance on a private network, never behind an internet-facing ingress.
+  Anyone who can reach the instance can act through that session. Use this only for a single-user installation on a private network; do not expose it through an internet-facing ingress.
 </Callout>
 
 ## Other controls
 
 | Variable | Effect |
-|---|---|
-| `DISABLE_INVITATIONS=true` / `NEXT_PUBLIC_DISABLE_INVITATIONS=true` | Disable workspace invitations globally |
-| `DISABLE_PUBLIC_API=true` / `NEXT_PUBLIC_DISABLE_PUBLIC_API=true` | Disable the public API globally |
-| `ADMIN_API_KEY` | Enables the Admin API for GitOps operations and organization provisioning |
+| --- | --- |
+| `DISABLE_INVITATIONS=true` / `NEXT_PUBLIC_DISABLE_INVITATIONS=true` | Disable workspace invitations globally. |
+| `DISABLE_PUBLIC_API=true` / `NEXT_PUBLIC_DISABLE_PUBLIC_API=true` | Disable the public API globally. |
+| `ADMIN_API_KEY` | Enables Admin API GitOps operations and organization provisioning. |
+
+Set both server and `NEXT_PUBLIC_` flags where a pair is listed. The server flag enforces the restriction; its counterpart controls the UI.
+
+## Verify authentication
+
+Sign out and sign back in at the public origin, then open a workflow in two browser windows and confirm edits propagate. Test each enabled login method. If verification is required, create a test account and confirm the message arrives and the verification succeeds. Use [Verify your install](/platform/self-hosting/verify) for deployment checks.
+
+## Related docs
 
-The `NEXT_PUBLIC_` twin controls what the UI shows; the server-side variable enforces it. Set both.
+- [Email](/platform/self-hosting/email)
+- [Integrations and OAuth](/platform/self-hosting/integrations-oauth)
+- [Verified domains](/platform/enterprise/verified-domains)
diff --git a/apps/docs/content/docs/platform/self-hosting/background-jobs.mdx b/apps/docs/content/docs/platform/self-hosting/background-jobs.mdx
index d2807cdb3ec..2f38820dd4f 100644
--- a/apps/docs/content/docs/platform/self-hosting/background-jobs.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/background-jobs.mdx
@@ -1,13 +1,13 @@
 ---
-title: Background Jobs
+title: Background jobs
 description: Scheduled workflows, polling triggers, and the cron endpoints that drive them
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
-A large part of Sim runs on a schedule rather than in response to a user request: scheduled workflows, every polling trigger, connector syncs, the outbox, data drains, and retention. All of it is driven by **HTTP endpoints that something external must call on a timer**.
+Scheduled workflows, polling triggers, connector syncs, and maintenance jobs depend on authenticated HTTP endpoints called by an external scheduler.
 
-Both deployments ship a scheduler and enable it by default: Kubernetes as CronJobs, Docker Compose as a `cron` service. Both authenticate with `CRON_SECRET`, and both use the same schedules.
+Helm enables CronJobs by default; Docker Compose includes a `cron` service. Both use `CRON_SECRET` and the same shipped schedules. Upload-session cleanup needs an additional operator-configured job, described below.
 
 ## Authentication
 
@@ -26,59 +26,32 @@ openssl rand -hex 32
 ```
 
 <Callout type="warn">
-  `CRON_SECRET` is **required** whenever background jobs are enabled — which is the Helm chart's default. The chart refuses to render without it. If it is unset, the endpoints reject every call and all scheduled work silently stops.
+  Background jobs require `CRON_SECRET`. Helm rejects a missing inline value when CronJobs are enabled. With a pre-created Secret or External Secrets, supply the key in that Secret; otherwise cron pods cannot start. Endpoints reject calls without the matching secret.
 </Callout>
 
 Point cron at an **internal** address where possible (the in-cluster Service, or `localhost` on a single node). These endpoints should not be reachable from the internet; if they are, `CRON_SECRET` is the only thing protecting them.
 
-## The jobs
-
-| Job | Endpoint | Schedule | Drives |
-|---|---|---|---|
-| Schedule execution | `/api/schedules/execute` | `*/1 * * * *` | **Scheduled workflows** |
-| Gmail poll | `/api/webhooks/poll/gmail` | `*/1 * * * *` | Gmail trigger |
-| Outlook poll | `/api/webhooks/poll/outlook` | `*/1 * * * *` | Outlook trigger |
-| IMAP poll | `/api/webhooks/poll/imap` | `*/1 * * * *` | IMAP trigger |
-| RSS poll | `/api/webhooks/poll/rss` | `*/1 * * * *` | RSS trigger |
-| Google Sheets poll | `/api/webhooks/poll/google-sheets` | `*/1 * * * *` | Sheets trigger |
-| Google Drive poll | `/api/webhooks/poll/google-drive` | `*/1 * * * *` | Drive trigger |
-| Google Calendar poll | `/api/webhooks/poll/google-calendar` | `*/1 * * * *` | Calendar trigger |
-| HubSpot poll | `/api/webhooks/poll/hubspot` | `*/1 * * * *` | HubSpot trigger |
-| Time pause/resume | `/api/resume/poll` | `*/1 * * * *` | Workflows paused on a timer |
-| Outbox processing | `/api/webhooks/outbox/process` | `*/1 * * * *` | Transactional-outbox retries for billing, membership, enterprise issuance, and workflow-deployment side effects |
-| Workspace file search dispatch | `/api/cron/workspace-file-search-dispatch` | `*/1 * * * *` | Dispatches indexing work for workspace file search |
-| Knowledge projection | `/api/cron/knowledge-projection` | `*/1 * * * *` | Brings knowledge base search up to date with document, permission, and chunk changes |
-| Table row-change fold | `/api/cron/fold-table-row-changes` | `*/1 * * * *` | Folds the table row-change log into each table's stored row count and version |
-| Connector sync | `/api/knowledge/connectors/sync` | `*/5 * * * *` | Knowledge base connector syncs |
-| Connector member sync | `/api/knowledge/connectors/member-sync` | `*/5 * * * *` | Per-member content/access sync for indexed connectors; live Search sources are skipped |
-| Connector directory sync | `/api/knowledge/connectors/directory-sync` | `*/5 * * * *` | Refreshes stored groups for indexed administrator-mode connectors; live Search sources are skipped |
-| Workspace events poll | `/api/workspace-events/poll` | `*/15 * * * *` | Workspace event triggers |
-| Table row TTL cleanup | `/api/cron/cleanup-table-row-ttl` | `*/15 * * * *` | Deletes table rows whose TTL column has expired |
-| Stale execution cleanup | `/api/cron/cleanup-stale-executions` | `*/30 * * * *` | Fails runs whose worker died without finishing — workflow executions, background jobs, table jobs and table runs — so they stop showing as running |
-| OAuth token cleanup | `/api/cron/cleanup-oauth-tokens` | `0 * * * *` | Deletes access and refresh tokens after the retention tail |
-| SCIM reconciliation | `/api/cron/scim-reconcile` | `17 * * * *` | Re-applies directory group mappings |
-| Data drains | `/api/cron/run-data-drains` | `0 * * * *` | Enterprise data drains |
-| Renew subscriptions | `/api/cron/renew-subscriptions` | `0 */12 * * *` | Renews Microsoft Teams chat subscriptions (Graph caps them at ~3 days) |
-| Billing cycle close | `/api/cron/billing-cycle-close` | `0 */6 * * *` | Billing only — final overage collection and per-period tracker reset |
-| Reconcile billing seats | `/api/cron/reconcile-billing-seats` | `0 * * * *` | Billing only — safe to disable when self-hosted |
-| Reconcile inbox entitlement | `/api/cron/reconcile-inbox-entitlement` | `0 3 * * *` | Inbox access reconciliation |
-| Cleanup sandbox images | `/api/cron/cleanup-sandbox-images` | `30 4 * * *` | Reclaims sandbox images |
-| Idempotency key cleanup | `/api/webhooks/cleanup/idempotency` | `0 5 * * *` | Deletes deduplication records older than seven days |
-
-<Callout type="info">
-  **Subscription renewal** covers Microsoft Teams chat triggers, whose Microsoft Graph subscriptions are hard-capped at about three days. Without it, Teams triggers work for a couple of days and then quietly stop. Gmail, Outlook, Drive, Calendar, and Sheets triggers are **polled** instead — they depend on the per-minute poll jobs above, not on this one.
-</Callout>
-
 ## Kubernetes
 
-Enabled by default. Nothing to do beyond setting `CRON_SECRET`.
+CronJobs are enabled by default. Supply `CRON_SECRET` through the app Secret and ensure cron pods can reach the internal app Service.
 
 ```yaml
 cronjobs:
   enabled: true
 ```
 
-Each job runs a small `curlimages/curl` pod that calls the app's **in-cluster Service** (not the ingress), with `concurrencyPolicy: Forbid` so a slow run never overlaps itself. The Service load-balances that single call to one replica, so a job never fans out across pods. The chart keeps three completed and one failed Job per CronJob, but `ttlSecondsAfterFinished` defaults to 600, so a finished Job is deleted ten minutes after it ends — inspect a failure promptly or collect the logs. It sets no `backoffLimit`, so the Kubernetes default of six applies and the chart exposes no key to change it. `cronjobs.activeDeadlineSeconds` (default `300`) bounds the **whole Job** — retries and the controller's back-off included — so whichever limit is reached first ends the Job — six retries after the initial failure, up to seven attempts, or five minutes of attempts plus back-off. The same deadline cuts off a single hung request. One attempt is already several HTTP calls: the container retries three times, ten seconds apart, with `curl --retry 2` inside each.
+Each `curlimages/curl` pod calls the internal app Service, which routes the request to one replica. `concurrencyPolicy: Forbid` prevents overlapping Jobs for that CronJob; the app also handles overlap for detached work.
+
+| Setting | Shipped behavior |
+|---|---|
+| Completed/failed Job history | Three successful and one failed Job |
+| Finished-Job TTL | 600 seconds; collect logs before deletion |
+| Job deadline | 300 seconds by default; outbox uses 900, idempotency cleanup 360 |
+| Kubernetes retry limit | No chart `backoffLimit` key; Kubernetes defaults to six retries after the initial failure |
+| Request retries | Three shell attempts, ten seconds apart; each uses `curl --retry 2 --retry-delay 5` |
+| Request timeout | 60 seconds by default, with per-job overrides; outbox uses 810 seconds |
+
+The Job deadline includes attempts and controller backoff. It can end a Job before the retry limit is reached and also stops a hung request.
 
 Disable individual jobs you do not need — billing reconciliation is the obvious one on a self-hosted install:
 
@@ -96,24 +69,28 @@ Check they are running:
 ```bash
 kubectl get cronjobs -n simstudio
 kubectl get jobs -n simstudio --sort-by=.metadata.creationTimestamp | tail
-kubectl logs -n simstudio job/<job-name>
+kubectl logs -n simstudio 'job/<job-name>'
 ```
 
-A CronJob whose `LAST SCHEDULE` is stale, or whose jobs are failing, means the corresponding feature is dead. Alert on it — see [Observability](/platform/self-hosting/observability).
+Inspect stale schedules and failed Jobs. A stale `LAST SCHEDULE` points to controller, suspension, or deadline settings; a 401 in Job logs points to authentication. `Forbid` can skip a tick while an earlier Job remains active. Alert on successful completion as described in [Observability](/platform/self-hosting/observability).
 
 ## Docker Compose
 
-The `cron` service runs the same jobs on the same schedules, so nothing to configure beyond `CRON_SECRET`:
+Generate a secret, then save it as `CRON_SECRET` in the `.env` file next to your Compose file. Replace an existing value rather than adding a duplicate. The app and scheduler must receive the same value.
 
 ```bash
-CRON_SECRET=$(openssl rand -hex 32)
+openssl rand -hex 32
+```
+
+Recreate the services after updating `.env`:
+
+```bash
+docker compose -f docker-compose.prod.yml up -d
 ```
 
 Without it the `cron` service logs exactly what to set — including a freshly generated value — and exits, leaving the rest of the stack running. Schedules live in `docker/crontab` and mirror `helm/sim/values.yaml` `cronjobs.jobs` one-for-one.
 
-<Callout type="info">
-  Upgrading a deployment created before the scheduler existed? Your `.env` has no `CRON_SECRET`, so the stack comes up as before and `cron` exits with instructions. Add the value and re-run `up -d` to turn background jobs on.
-</Callout>
+An older install may lack `CRON_SECRET`; add it to `.env` and run `up -d` to enable the scheduler.
 
 The service runs [supercronic](https://github.com/aptible/supercronic) rather than the app image: it logs each job's output to the container log, forwards `SIGTERM` so `docker compose stop` is graceful, and will not start an iteration while the previous one is still running.
 
@@ -128,7 +105,48 @@ level=info msg=starting iteration=0 job.schedule="*/1 * * * *"
 level=info msg="job succeeded" iteration=0
 ```
 
-To drop a job you do not need, comment out its line in `docker/crontab` and restart the service.
+The published cron image contains its crontab. Editing the repository copy and restarting that image does not change its jobs. To customize them, copy `docker/crontab` to an operator-owned file, edit it, and mount it with a Compose override:
+
+```yaml
+# cron-custom.yml
+services:
+  cron:
+    volumes:
+      - ./sim-crontab:/etc/sim/crontab:ro
+```
+
+```bash
+docker compose -f docker-compose.prod.yml -f cron-custom.yml up -d cron
+```
+
+Alternatively, build a custom image from `docker/cron.Dockerfile` with your crontab and configure Compose to use it.
+
+## Schedule upload-session cleanup
+
+The cleanup endpoint exists, but neither shipped scheduler calls it. Configure your own authenticated schedule for `/api/cron/cleanup-tasks` to expire upload sessions and reclaim abandoned upload state. It also dispatches task-retention cleanup according to configured policy.
+
+For Helm, add an operator-owned job to your values file. This example runs hourly; choose a cadence and timeout for your workload:
+
+```yaml
+cronjobs:
+  jobs:
+    uploadSessionCleanup:
+      enabled: true
+      name: upload-session-cleanup
+      schedule: "0 * * * *"
+      path: /api/cron/cleanup-tasks
+      requestTimeoutSeconds: 300
+      activeDeadlineSeconds: 360
+      concurrencyPolicy: Forbid
+```
+
+For Compose, add this line to the mounted or custom-image crontab described above:
+
+```text
+0 * * * * curl -fsS -m 300 -o /dev/null -H "Authorization: Bearer $CRON_SECRET" "$SIM_URL/api/cron/cleanup-tasks"
+```
+
+Use the internal app address and the same `CRON_SECRET`. Check job logs for a successful response. Provider lifecycle rules remain a second layer for incomplete multipart state; see [Object storage](/platform/self-hosting/object-storage#configure-incomplete-multipart-cleanup).
 
 ## Verifying
 
@@ -138,16 +156,57 @@ Create a workflow with a Schedule trigger set to every minute, deploy it, and wa
 2. Confirm the app and the scheduler share the same `CRON_SECRET`. A mismatch shows up as `401` in the scheduler log.
 3. A `202` means the endpoint accepted the run; it does not confirm a schedule was due, so check the Logs view.
 
+## Shipped job reference
+
+| Job | Endpoint | Schedule | Drives |
+|---|---|---|---|
+| Schedule execution | `/api/schedules/execute` | `*/1 * * * *` | **Scheduled workflows** |
+| Gmail poll | `/api/webhooks/poll/gmail` | `*/1 * * * *` | Gmail trigger |
+| Outlook poll | `/api/webhooks/poll/outlook` | `*/1 * * * *` | Outlook trigger |
+| IMAP poll | `/api/webhooks/poll/imap` | `*/1 * * * *` | IMAP trigger |
+| RSS poll | `/api/webhooks/poll/rss` | `*/1 * * * *` | RSS trigger |
+| Google Sheets poll | `/api/webhooks/poll/google-sheets` | `*/1 * * * *` | Sheets trigger |
+| Google Drive poll | `/api/webhooks/poll/google-drive` | `*/1 * * * *` | Drive trigger |
+| Google Calendar poll | `/api/webhooks/poll/google-calendar` | `*/1 * * * *` | Calendar trigger |
+| HubSpot poll | `/api/webhooks/poll/hubspot` | `*/1 * * * *` | HubSpot trigger |
+| Time pause/resume | `/api/resume/poll` | `*/1 * * * *` | Workflows paused on a timer |
+| Outbox processing | `/api/webhooks/outbox/process` | `*/1 * * * *` | Transactional-outbox retries for billing, membership, enterprise issuance, and workflow-deployment side effects |
+| Workspace file search dispatch | `/api/cron/workspace-file-search-dispatch` | `*/1 * * * *` | Dispatches indexing work for workspace file search |
+| Knowledge projection | `/api/cron/knowledge-projection` | `*/1 * * * *` | Brings knowledge base search up to date with document, permission, and chunk changes |
+| Table row-change fold | `/api/cron/fold-table-row-changes` | `*/1 * * * *` | Folds the table row-change log into each table's stored row count and version |
+| Connector sync | `/api/knowledge/connectors/sync` | `*/5 * * * *` | Knowledge base connector syncs |
+| Connector member sync | `/api/knowledge/connectors/member-sync` | `*/5 * * * *` | Per-member content/access sync for indexed connectors; live Search sources are skipped |
+| Connector directory sync | `/api/knowledge/connectors/directory-sync` | `*/5 * * * *` | Refreshes stored groups for indexed administrator-mode connectors; live Search sources are skipped |
+| Workspace events poll | `/api/workspace-events/poll` | `*/15 * * * *` | Workspace event triggers |
+| Table row TTL cleanup | `/api/cron/cleanup-table-row-ttl` | `*/15 * * * *` | Deletes table rows whose TTL column has expired |
+| Stale execution cleanup | `/api/cron/cleanup-stale-executions` | `*/30 * * * *` | Fails runs whose worker died without finishing — workflow executions, background jobs, table jobs and table runs — so they stop showing as running |
+| OAuth token cleanup | `/api/cron/cleanup-oauth-tokens` | `0 * * * *` | Deletes access and refresh tokens after the retention tail |
+| SCIM reconciliation | `/api/cron/scim-reconcile` | `17 * * * *` | Re-applies directory group mappings |
+| Data drains | `/api/cron/run-data-drains` | `0 * * * *` | Enterprise data drains |
+| Renew subscriptions | `/api/cron/renew-subscriptions` | `0 */12 * * *` | Renews Microsoft Teams chat subscriptions (Graph caps them at ~3 days) |
+| Billing cycle close | `/api/cron/billing-cycle-close` | `0 */6 * * *` | Billing only — final overage collection and per-period tracker reset |
+| Reconcile billing seats | `/api/cron/reconcile-billing-seats` | `0 * * * *` | Billing only — safe to disable when self-hosted |
+| Reconcile inbox entitlement | `/api/cron/reconcile-inbox-entitlement` | `0 3 * * *` | Inbox access reconciliation |
+| Cleanup sandbox images | `/api/cron/cleanup-sandbox-images` | `30 4 * * *` | Reclaims sandbox images |
+| Idempotency key cleanup | `/api/webhooks/cleanup/idempotency` | `0 5 * * *` | Deletes deduplication records older than seven days |
+
+Subscription renewal covers Microsoft Teams chat triggers. Their Graph subscriptions last at most three days; rich notifications have a shorter limit. Gmail, Outlook, Drive, Calendar, and Sheets use the per-minute polling jobs instead. See [Microsoft Graph subscription lifetimes](https://learn.microsoft.com/en-us/graph/change-notifications-overview). SCIM reconciliation calls its authenticated endpoint directly each hour; it does not require Trigger.dev.
+
 ## Concurrency
 
-Scheduled execution volume is bounded per app instance by:
+On the default database-backed queue, scheduled execution capacity is shared across the deployment:
 
 | Variable | Default | Applies to |
 |---|---|---|
-| `SCHEDULE_EXECUTION_CONCURRENCY_LIMIT` | `30` | Scheduled workflows in flight, on every install |
+| `SCHEDULE_EXECUTION_CONCURRENCY_LIMIT` | `30` | Scheduled workflows in flight across the database-backed queue; also the schedule task limit on Trigger.dev |
 
 <Callout type="info">
   `WORKFLOW_EXECUTION_CONCURRENCY_LIMIT`, `WEBHOOK_EXECUTION_CONCURRENCY_LIMIT`, and `RESUME_EXECUTION_CONCURRENCY_LIMIT` are `concurrencyLimit` settings on Trigger.dev task definitions. They have **no effect** unless `TRIGGER_DEV_ENABLED` is set, and neither the Helm chart nor Docker Compose configures Trigger.dev — so on a default self-host they are inert.
 </Callout>
 
-Raise the schedule limit only alongside memory headroom: concurrent executions run in the app process, so throughput is bounded by the pod's memory before it is bounded by this number.
+Adding replicas does not multiply the database queue's schedule cap. Raise it only after measuring memory and database headroom. The app orchestrates runs; local JavaScript uses Node child workers inside its container.
+
+## Related docs
+
+- [Observability](/platform/self-hosting/observability)
+- [Upgrades](/platform/self-hosting/upgrades)
diff --git a/apps/docs/content/docs/platform/self-hosting/desktop.mdx b/apps/docs/content/docs/platform/self-hosting/desktop.mdx
index 43c153a16a3..45344d8c907 100644
--- a/apps/docs/content/docs/platform/self-hosting/desktop.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/desktop.mdx
@@ -1,170 +1,150 @@
 ---
-title: Desktop App on Your Deployment
-description: Point the macOS desktop app at your own Sim deployment
+title: Desktop app on your deployment
+description: Connect the macOS desktop app to a Sim deployment you operate
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 
-This page is about pointing the app at a deployment you run. For installing and using it, see [Sim Desktop](/desktop).
+Install the official Sim desktop app and connect it to your deployment. You do not need a custom build to change servers. The app is currently macOS-only; use the web app on other platforms. See [Sim Desktop](/desktop) for general installation and use.
 
-The Sim desktop app is a native macOS shell around a Sim deployment. It is **not** tied to sim.ai — the build bakes in only a *default* server, and every runtime boundary (navigation, content security policy, cookie storage, the update feed) is derived from the server you point it at.
+## Server prerequisites [#requirements-for-the-server-url]
 
-So self-hosting the desktop app takes no build of your own: install the same signed, notarized app everyone else installs, then point it at your deployment.
-
-<Callout>
-  The desktop app is macOS-only today. The web app works in any browser on any platform.
-</Callout>
-
-## Your deployment already serves the installer
-
-Every Sim deployment exposes two public endpoints:
-
-| Endpoint | What it does |
-|---|---|
-| `/api/desktop/update/download` | Redirects (302) to the newest installer for this deployment's release channel |
-| `/api/desktop/update/latest-mac.yml` | The update manifest installed apps poll |
-
-Both resolve against Sim's public GitHub releases, and the installers themselves are downloaded from GitHub. Nothing is built, signed, or hosted by you: your deployment decides *which* release its clients are offered and serves the manifest, so installed apps poll your server instead of sim.ai — but they cannot be served artifacts of your own from this path, and a self-updating stable build falls back to Sim's own feed if yours stops answering. To ship your own build, see [Building your own shell](#building-your-own-shell).
-
-Both endpoints cache their GitHub lookups for **5 minutes**, and both respond the same way when they cannot answer:
-
-| Status | Meaning |
-|---|---|
-| `302` | Success on `/download` — a redirect to the release asset. The update feed answers `200` with `text/yaml` instead |
-| `404` | GitHub answered, but this channel has no release |
-| `502` | GitHub could not be read — unreachable, rate-limited, or every candidate release lacked valid desktop artifacts |
-
-The Sim server needs outbound access to `api.github.com` and `github.com` for these to resolve. Unauthenticated GitHub API requests are capped at 60/hour per IP; set `GITHUB_TOKEN` on the Sim server to raise that to 5000/hour.
-
-### What an installed app does when the feed fails
-
-A `404` carries a header the shell reads as *no update available*, so the app reports it is up to date. Anything else — `502`, a timeout, a connection failure — means the feed is unavailable, and only a self-updating build (Developer ID, installed in `/Applications`) has anywhere else to go: on the stable channel it falls back to Sim's packaged GitHub feed, and on `dev` or `staging` it skips the check, since that fallback carries only stable artifacts their bundle identity cannot install. Every other build simply stops being offered updates until the feed answers again.
-
-Release selection is therefore yours only while the feed answers. With `APPCONFIG_ENVIRONMENT` unset both paths resolve the same release, so the fallback is invisible; it matters when your deployment serves a channel that disagrees with stable.
-
-### Which channel your deployment serves
-
-The channel is chosen by `APPCONFIG_ENVIRONMENT`, not by whether you are self-hosting:
-
-| `APPCONFIG_ENVIRONMENT` | Channel | Release repository |
-|---|---|---|
-| `dev` | `dev` | `simstudioai/sim-desktop-releases` |
-| `staging` | `staging` | `simstudioai/sim-desktop-releases` |
-| anything else, including unset | `latest` | `simstudioai/sim` |
+- Use the origin your server serves, including scheme, hostname, and port. Paths are ignored.
+- HTTPS is required except for `localhost`, `127.0.0.1`, and `::1`, which allow HTTP for local testing.
+- Do not include credentials in the URL.
+- Use a certificate trusted by macOS.
+- Allow your Sim server to reach `api.github.com` and `github.com` for official installer and update lookup.
 
 <Callout type="warn">
-  A self-hosted deployment that sets `APPCONFIG_ENVIRONMENT=dev` or `staging` — a reasonable thing to do for a non-production environment — serves its users **prereleases** from the desktop prerelease repository, silently and with no other symptom. Leave it unset on any deployment whose users install the desktop app.
+  Use the final served origin, not a redirecting alias. If `sim.example.com` redirects to `www.sim.example.com`, enter the `www` origin. The shell checks origins exactly; an alias can strand sign-in. Certificate errors are rejected without a “continue anyway” option. Install a private CA in the system trust store or use a publicly trusted certificate.
 </Callout>
 
 ## Install and connect
 
 <Steps>
-
 <Step>
 
-### Get the installer link
+### Resolve the installer
+
+From your installation directory:
 
 ```bash
-npx sim-setup desktop
+bunx sim-setup desktop
 ```
 
-This reads your deployment URL from your Compose and Helm configuration, resolves the installer, and prints the download link plus the server URL to enter. It then offers to open the download in your browser — pass `--no-open` to skip the prompt, for scripts and CI.
+The command reads Compose/Helm configuration, resolves the installer, and prints the download link and server URL. It offers to open the installer in your browser. Use `--no-open` to skip that prompt, or supply the public origin directly:
 
-The two probes are not weighted the same. **The installer probe is fatal**: if `/api/desktop/update/download` does not resolve, the command prints why and exits `1`. A failing update feed is only a warning — the command tells you the app will install but will not auto-update from this deployment, and still exits `0`. Read the output; do not rely on the exit code alone to prove the feed works.
+```bash
+bunx sim-setup desktop --url https://sim.example.com --no-open
+```
 
-Pass `--url https://sim.example.com` when running the CLI somewhere that reaches Sim at a different address. It also **skips discovery entirely**, which is worth using deliberately: discovery shells out to `docker compose` and `helm`, so it costs seconds that `--url` avoids.
+`--url` skips discovery. Without the CLI, open `https://<your-sim-origin>/api/desktop/update/download` in a browser.
 
-<Callout type="warn">
-  If the machine holds more than one Sim configuration naming different `NEXT_PUBLIC_APP_URL` values, the command does **not** prompt you to pick — it errors, lists what it found, and tells you to re-run with `--url`. There is no interactive picker.
+</Step>
+<Step>
 
-  In the opposite case, where no configuration sets `NEXT_PUBLIC_APP_URL` at all, it falls back to `http://localhost:3000` without saying so. If the printed deployment URL is `localhost` and you expected your real domain, that fallback is why.
-</Callout>
+### Install the app
 
-Without the CLI, open `https://your-sim-url/api/desktop/update/download` in a browser.
+Open the `.dmg` and drag Sim to **Applications**. Official installers are signed and notarized by Sim.
 
 </Step>
-
 <Step>
 
-### Install it
+### Connect to your server
 
-Open the `.dmg` and drag Sim to Applications. The build is signed and notarized by Sim, so Gatekeeper accepts it with no override.
+Launch Sim, choose **Sim → Server…**, enter your deployment origin, and select **Connect**. The app relaunches against that server and saves the setting across updates.
 
 </Step>
+</Steps>
 
-<Step>
+## What changes when you switch servers
 
-### Point it at your server
+Each server has its own cookie and storage partition. Switching clears deployment-scoped state before the new server loads:
 
-Launch Sim, then choose **Sim → Server…** in the menu bar. Enter your deployment URL and press **Connect**.
+| State | Result |
+| --- | --- |
+| Sign-in session | Sign in to the new deployment. |
+| Saved route | Open the workspace picker rather than the old deployment's workspace. |
+| Folder access | Grant directories again when needed. |
+| Built-in browser sessions | Sign in to sites again. |
 
-The app relaunches against your server and stays there — the setting persists across updates, and every later update is fetched from your deployment's feed.
+Window size, zoom, theme, notification preferences, tray, and launch-at-login settings remain. If deployment-scoped state cannot be cleared, the switch is refused; retry to complete it.
 
-Changing servers deliberately clears what the previous deployment was trusted with, so the new one cannot inherit it:
+## Recover a wrong server URL [#recovering-from-a-wrong-server-url]
 
-- **Your session.** Each server gets its own storage, so you sign in again.
-- **The saved route.** The app opens on the workspace picker, not the workspace the old server had open.
-- **Folder access.** Directories you let the agent read are forgotten; grant them again when you need them.
-- **Built-in browser sessions.** Sites you were signed into in the built-in browser are signed out.
+The **Can't connect** page reports a DNS, timeout, or TLS failure. Select **Change server** to open the picker with the current value prefilled. No filesystem change is needed to correct a typo.
 
-The last two are capabilities you granted to a *specific* Sim server, so carrying them across would hand the new deployment access it was never given — the same reasoning that clears them when you sign out.
+A private or self-signed certificate must be trusted by macOS; otherwise the app shows **Connection isn't secure**. A correct URL does not bypass certificate validation.
 
-Device settings are kept: window size, zoom, theme, notification preferences, tray, and launch-at-login.
+## Installer and update endpoints [#your-deployment-already-serves-the-installer]
 
-If something cannot be cleared, the change is refused and the app stays on your current server rather than switching with the old deployment's access still in place. Retrying finishes the job.
+Your deployment exposes two public endpoints:
 
-</Step>
+| Endpoint | Response |
+| --- | --- |
+| `/api/desktop/update/download` | `302` to the newest official installer for the deployment channel. |
+| `/api/desktop/update/latest-mac.yml` | `200` with a `text/yaml` update manifest. |
 
-</Steps>
+Both resolve official GitHub release assets and cache lookups for five minutes. They return `404` when the channel has no release and `502` when GitHub lookup fails or candidates lack valid desktop artifacts.
+
+The server serves release selection and the manifest; clients download installers from GitHub. These endpoints cannot distribute your custom artifacts. Set `GITHUB_TOKEN` on the Sim server if its shared egress IP reaches GitHub's unauthenticated 60-requests/hour limit; authenticated user-token requests typically allow 5,000/hour. See [GitHub rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api).
+
+### Deployment channel [#which-channel-your-deployment-serves]
+
+`APPCONFIG_ENVIRONMENT` selects the channel:
+
+| Value | Channel | Repository |
+| --- | --- | --- |
+| `dev` | `dev` | `simstudioai/sim-desktop-releases` |
+| `staging` | `staging` | `simstudioai/sim-desktop-releases` |
+| Anything else, including unset | `latest` | `simstudioai/sim` |
 
 <Callout type="warn">
-  Enter the origin your server actually **serves**, not one that redirects to it. If your load balancer redirects `sim.example.com` to `www.sim.example.com`, use the `www` form. The app compares origins exactly, so a redirecting origin leaves every page off-origin and strands sign-in.
+  A self-hosted deployment with `APPCONFIG_ENVIRONMENT=dev` or `staging` serves prerelease installers. Leave it unset when you intend to offer the stable desktop app.
 </Callout>
 
-## Requirements for the server URL
+### Unavailable update feed [#what-an-installed-app-does-when-the-feed-fails]
 
-- **HTTPS is required**, except for the loopback hosts `localhost`, `127.0.0.1`, and `::1`, which may use HTTP for local testing.
-- No credentials in the URL.
-- Paths are ignored — only scheme, host, and port are stored.
+A feed `404` with the no-release header means no update is available. For `502`, timeout, or connection failure:
 
-Each server gets its own isolated cookie and storage partition, so you can move between deployments without either one seeing the other's session.
+- A stable build eligible for self-update falls back to Sim's packaged GitHub feed.
+- A `dev` or `staging` build skips the check because the stable fallback cannot update its bundle identity.
+- Other builds receive no update offer until the deployment feed answers again.
 
-## Recovering from a wrong server URL
+Self-update requires a Developer ID build installed in **Applications**. Other packaged builds can offer manual downloads when the feed works. Release selection therefore follows your deployment only while its feed answers; an eligible stable app can use the fallback during an outage.
 
-If the app is pointed at a server it cannot reach, it shows its **Can't connect** page, which names the reason — a DNS failure, a timeout, or a TLS problem. That page has a **Change server** button that opens the same picker, pre-filled with the current value, so a typo is always recoverable without touching the filesystem.
+## CLI discovery and probe failures
 
-<Callout type="warn">
-  **Your TLS certificate must be trusted by the operating system.** The app rejects certificate errors outright and offers no "continue anyway" — a self-signed certificate or a private CA that is not in the system trust store shows `Connection isn't secure` and will not load, however correct the URL is. Install your CA in the system keychain, or use a publicly trusted certificate.
-</Callout>
+The installer probe is required: failure exits `1`. Update-feed failure is a warning and still exits `0` if the installer resolved, so read both results before relying on updates.
 
-## Building your own shell
+If detected configurations name different `NEXT_PUBLIC_APP_URL` origins, the command lists them and requires `--url`; there is no interactive selection. If none names an origin, it defaults to `http://localhost:3000`. `--url` also avoids the Docker/Helm discovery calls.
 
-You almost certainly do not need this. It is worth it only if you need your own bundle identity or your own signing identity — for example, to distribute through MDM under your organization's Developer ID.
+## Build a custom shell [#building-your-own-shell]
 
-Packaging needs **macOS with Xcode 26 or newer** — the app icon is an Icon Composer asset, and an older toolchain fails with `Failed to check actool version`.
+Use a custom build for a different bundle identity or signing identity, such as distribution through MDM with your organization's Developer ID. Start from a source checkout with dependencies installed. Packaging requires macOS with Xcode 26 or later for the Icon Composer asset.
 
 ```bash
 cd apps/desktop
 SIM_DESKTOP_DEFAULT_ORIGIN=https://sim.example.com bun run package:mac
 ```
 
-This bakes your origin in as the default for fresh installs, so nobody has to set the server by hand (the picker stays available in the menu). The mac target builds a single universal binary, so artifacts land in `apps/desktop/release/` as `Sim-<version>-universal.dmg` and `Sim-<version>-universal.zip`. Add `-c.appId=com.example.sim` if you want your own bundle identifier rather than Sim's.
+The default origin applies to fresh installs; the server picker remains available. The macOS target builds a universal binary. Output files are `apps/desktop/release/Sim-<version>-universal.dmg` and `.zip`. Pass `-c.appId=com.example.sim` to choose a bundle identifier.
 
-<Callout type="warn">
-  The origin you bake in also decides the app's **identity**. A loopback origin, or a `dev.sim.ai` / `staging.sim.ai` hostname, produces a differently named app with its own userData directory, and its own single-instance lock — deliberately, so those installs can sit alongside a production one. Any other origin, including your own domain, is treated as production and shares the plain `Sim` identity. Baking in `http://localhost:3000` to test therefore does not produce a build your users can later repoint; it produces a separate app.
-</Callout>
+The baked default determines the app's channel identity, userData directory, and single-instance lock. Loopback, `dev.sim.ai`, and `staging.sim.ai` defaults produce separate Local, Dev, and Staging app identities; other origins use the production Sim identity. A Local build can still be pointed at another HTTPS server, but changing servers does not turn it into a production build or change its update eligibility.
 
-`package:share` overrides both the output directory and the artifact name — builds land in `apps/desktop/release/<channel-slug>/` as `<channel-slug>-<version>-<arch>.<ext>`, not the names above.
+`package:share` instead writes `apps/desktop/release/<channel-slug>/<channel-slug>-<version>-<arch>.<ext>` and disables trusted timestamps. Use `package:mac` for notarized distribution.
 
-### Overriding the server at runtime
+<Callout type="warn">
+  Your custom build needs your own signing and notarization. Set `CSC_LINK` and `CSC_KEY_PASSWORD` for Developer ID signing. Set `APPLE_API_KEY` to the absolute path of the App Store Connect `.p8` file, plus `APPLE_API_KEY_ID`, `APPLE_API_ISSUER`, and `APPLE_TEAM_ID`. A leading `~` is not expanded. `package:share` passes `-c.mac.timestamp=none`; Apple notarization requires a secure timestamp, so that output cannot be notarized even with credentials configured.
+</Callout>
 
-`SIM_DESKTOP_ORIGIN` overrides the stored server for a single launch, which is useful for testing a build against another deployment without changing its saved setting. It is validated the same way the picker's input is; an invalid value is logged and ignored rather than applied.
+### Runtime override [#overriding-the-server-at-runtime]
 
-<Callout type="warn">
-  Signing and notarization become your responsibility with this route, and macOS quarantines anything downloaded that is not notarized.
+`SIM_DESKTOP_ORIGIN` overrides the saved server for one launch. It uses the same validation as the picker; an invalid value is logged and ignored. The override does not replace the saved server setting.
 
-  Supply your own Developer ID via `CSC_LINK` and `CSC_KEY_PASSWORD`. For notarization, save your App Store Connect key as a `.p8` file and point `APPLE_API_KEY` at its **absolute filesystem path** — it is a path, not the key itself, and a leading `~` is not expanded — then set `APPLE_API_KEY_ID`, `APPLE_API_ISSUER`, and `APPLE_TEAM_ID`.
+## Related docs
 
-  Use `package:mac` for this, **not** `package:share`. The share script is the "send someone a build to try" path: it passes `-c.mac.timestamp=none` to skip the per-file round trip to Apple's timestamp authority. Apple's notary service requires a secure timestamp, so a build made that way cannot be notarized however many credentials you supply.
-</Callout>
+- [Verify your install](/platform/self-hosting/verify)
+- [Networking](/platform/self-hosting/networking)
+- [Sim Desktop](/desktop)
diff --git a/apps/docs/content/docs/platform/self-hosting/docker.mdx b/apps/docs/content/docs/platform/self-hosting/docker.mdx
index 56cfe3a5027..4241c4acd8c 100644
--- a/apps/docs/content/docs/platform/self-hosting/docker.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/docker.mdx
@@ -1,88 +1,111 @@
 ---
 title: Docker
-description: Deploy Sim with Docker Compose
+description: Deploy Sim with Docker Compose and verify its services
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { FAQ } from '@/components/ui/faq'
 
-## Quick Start
+Use the production Compose stack for a single-node installation. It starts the app, realtime, PostgreSQL with pgvector, Redis, migrations, and the scheduler.
+
+## Prerequisites
+
+- Docker Engine or Docker Desktop, running.
+- Docker Compose 2.24.0 or later. The file uses optional `env_file` entries introduced in that version.
+- Bun for `bunx`, and Node.js 20 or later for the published `sim-setup` executable.
+- Available host ports 3000 and 3002, with enough resources for your workload. See [resource examples](/platform/self-hosting#requirements).
+- A public domain and TLS proxy for remote access.
+
+## Quick start
 
 ```bash
-npx sim-setup
+bunx sim-setup
 ```
 
-Open [http://localhost:3000](http://localhost:3000)
+The wizard creates `./sim` with a generated `.env` and production Compose file, then starts published container images. Pass `--dir <path>` for another directory. Open [http://localhost:3000](http://localhost:3000).
 
-The setup package creates `./sim` with a generated `.env` and the production Compose file, then
-starts published container images. Pass `--dir <path>` to choose another directory.
+For a manual installation, obtain the Compose file from a source checkout:
 
-## Production Setup
+```bash
+git clone https://github.com/simstudioai/sim.git
+cd sim
+```
 
-### 1. Configure Environment
+Then follow the configuration steps below.
 
-For a new installation, create the configuration below. If you already ran the quick start, edit its generated `.env` and retain the existing secret values; do not overwrite them with new keys.
+## Production setup
+
+### 1. Configure the environment
+
+For a new installation, create `.env` next to `docker-compose.prod.yml`:
 
 ```bash
+umask 077
 cat > .env << EOF
 BETTER_AUTH_SECRET=$(openssl rand -hex 32)
 ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 API_ENCRYPTION_KEY=$(openssl rand -hex 32)
 CRON_SECRET=$(openssl rand -hex 32)
-
-# Your public origin. BETTER_AUTH_URL is derived from this automatically.
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
-
-# Database credentials. DATABASE_URL is composed from these by the compose file.
 POSTGRES_USER=postgres
 POSTGRES_PASSWORD=$(openssl rand -hex 24)
 POSTGRES_DB=simstudio
 EOF
 ```
 
-<Callout type="info">
-  Do not set `DATABASE_URL` or `BETTER_AUTH_URL` in `.env` — `docker-compose.prod.yml` composes both on the service definition, and a value set here is ignored. Change `POSTGRES_*` and `NEXT_PUBLIC_APP_URL` instead.
+If you already ran the wizard or have an existing installation, edit that `.env` and retain its keys and database credentials. Do not rerun this creation command over it.
 
-  Because `DATABASE_URL` is composed from them, keep `POSTGRES_USER`, `POSTGRES_PASSWORD`, and `POSTGRES_DB` URL-safe — letters, digits, and `.` `_` `~` `-`. They are inserted into the connection string as written, so a value containing `@`, `/`, `?`, `#`, `%`, or a space can initialize the database while leaving the app and migrations unable to connect. `openssl rand -hex` output is always safe.
-</Callout>
+Compose derives `BETTER_AUTH_URL` from `NEXT_PUBLIC_APP_URL` and `DATABASE_URL` from `POSTGRES_*`. Setting either derived variable in `.env` does not override the service definition. To use an external database, maintain a Compose configuration that supplies the same external DSN to the app, realtime, and migrations and adjusts their bundled-database dependencies.
+
+Keep `POSTGRES_USER`, `POSTGRES_PASSWORD`, and `POSTGRES_DB` URL-safe: letters, digits, `.`, `_`, `~`, or `-`. Compose inserts them into the DSN without escaping; values containing `@`, `/`, `?`, `#`, `%`, or spaces can initialize PostgreSQL but prevent app connections. Hex output from `openssl` is safe.
 
 <Callout type="error">
-  Save `ENCRYPTION_KEY` and `API_ENCRYPTION_KEY` somewhere outside this server. `ENCRYPTION_KEY` encrypts workspace and personal environment variables, stored provider API keys, MCP OAuth credentials, and deployment/chat secrets; `API_ENCRYPTION_KEY` encrypts user-generated Sim API keys. Neither can be regenerated — a database restore paired with a different key leaves the data it protected permanently unreadable.
+  Back up `ENCRYPTION_KEY` and `API_ENCRYPTION_KEY` separately from the server. Restoring the database with different keys leaves encrypted values unreadable. `ENCRYPTION_KEY` protects environment variables, provider keys, MCP OAuth credentials, and deployment/Chat secrets. `API_ENCRYPTION_KEY` protects stored Sim API-key material; when absent, legacy API keys can be stored in plain text.
 </Callout>
 
-The compose file refuses to start if `BETTER_AUTH_SECRET`, `ENCRYPTION_KEY`, `INTERNAL_API_SECRET`, or `POSTGRES_PASSWORD` is missing, rather than booting with empty or well-known values. Postgres applies `POSTGRES_PASSWORD` only when it first creates the database volume — see [Postgres on Compose](/platform/self-hosting/security#postgres-on-compose) before changing it on an existing install. `CRON_SECRET` is treated more gently: without it the `cron` service prints what to set and exits, leaving the rest of the stack running — so upgrading from a compose file that predates the scheduler still works.
+Compose refuses startup without `BETTER_AUTH_SECRET`, `ENCRYPTION_KEY`, `INTERNAL_API_SECRET`, or `POSTGRES_PASSWORD`. PostgreSQL applies its credentials only when initializing a new volume; changing `.env` does not change an existing database password. See [Postgres on Compose](/platform/self-hosting/security#postgres-on-compose) before rotating it.
+
+Set `CRON_SECRET` for scheduled work. Without it, the cron service prints instructions and exits; the other services can still run. Images use `latest` unless you set `SIM_VERSION`; the separate scheduler image uses `SIM_CRON_VERSION`. Pin and upgrade deliberately using [Upgrades](/platform/self-hosting/upgrades).
 
-Images track `latest` unless you pin them. For production, see [Upgrades](/platform/self-hosting/upgrades).
+### 2. Configure durable uploads
 
-### 2. Start Services
+<Callout type="warn">
+  The production Compose file persists PostgreSQL but does not mount `/app/apps/sim/uploads`. Recreating the app container loses uploads stored there. Configure object storage or a persistent mount before saving files you need to retain.
+</Callout>
+
+Follow [Object storage](/platform/self-hosting/object-storage) for AWS S3, Azure Blob, Google Cloud Storage, or local-volume configuration. Local disk is not shared across app replicas.
+
+### 3. Start and verify services
 
 ```bash
 docker compose -f docker-compose.prod.yml up -d
+docker compose -f docker-compose.prod.yml ps -a
+docker compose -f docker-compose.prod.yml logs migrations
+curl -fsS http://localhost:3000/api/health
 ```
 
-Six services start:
-
-| Service | Port | Purpose |
-|---|---|---|
-| `simstudio` | 3000 | Main application (8 GB memory limit) |
-| `realtime` | 3002 | WebSocket server (1 GB memory limit) |
-| `db` | internal | PostgreSQL 17 with pgvector — not published to the host |
-| `redis` | internal | Pub/sub and shared cache — not published to the host |
-| `cron` | — | Runs the [background jobs](/platform/self-hosting/background-jobs) on a schedule |
-| `migrations` | — | Applies schema migrations once, then exits |
+| Service | Host port | Purpose |
+| --- | --- | --- |
+| `simstudio` | 3000 | App; 8G memory limit. |
+| `realtime` | 3002 | WebSocket service; 1G memory limit. |
+| `db` | Not published | PostgreSQL 17 with pgvector. |
+| `redis` | Not published | Shared coordination, pub/sub, and caches. |
+| `cron` | None | Calls background job endpoints. |
+| `migrations` | None | Applies migrations once, then exits. |
 
-Confirm the five long-running services are up and that `migrations` has exited cleanly (it is a one-shot job with no healthcheck):
+Expect five services running and `migrations` exited successfully. The migrator has no healthcheck because it is a one-shot job.
 
 ```bash
-docker compose -f docker-compose.prod.yml ps
+docker compose -f docker-compose.prod.yml logs -f cron
 ```
 
-### 3. Put it behind TLS
+Confirm the scheduler calls succeed, then run [Verify your install](/platform/self-hosting/verify).
 
-Caddy is the least-effort option — it obtains and renews certificates automatically.
+### 4. Serve the public origin over TLS
 
-```
+A host-installed Caddy proxy can obtain and renew certificates for your domain. For example:
+
+```text
 sim.yourdomain.com {
     request_body {
         max_size 250MB
@@ -98,115 +121,123 @@ sim.yourdomain.com {
 }
 ```
 
-Three things in that config are Sim-specific and easy to get wrong: `/socket.io` must reach the realtime service on 3002, `flush_interval -1` stops Caddy buffering streamed agent output into one delayed block, and `max_size` has to clear the chat endpoint's 220 MB limit.
+Route `/socket.io` to realtime on 3002 and other requests to the app on 3000. The 250 MB decimal Caddy limit clears the configured 220 MiB deployed-chat cap, but the app's current Next.js proxy buffer still limits matching requests to 10 MiB. See [Request size limits](/platform/self-hosting/networking#request-size-limits) before increasing payload sizes. `flush_interval -1` explicitly disables response buffering; Caddy already flushes SSE immediately. It also keeps the upstream request running if the client disconnects. See [Caddy streaming behavior](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy#streaming).
 
-For nginx, Traefik, or a cloud load balancer — and for the GKE websocket timeout — see [Networking](/platform/self-hosting/networking).
+This example assumes Caddy runs on the Docker host. A containerized proxy needs reachable Compose service addresses instead of its own `localhost`. For Nginx, Traefik, cloud load balancers, or separate socket hosts, see [Networking](/platform/self-hosting/networking).
 
 ## Ollama
 
-`docker-compose.ollama.yml` is a **development** stack, not a drop-in swap for `docker-compose.prod.yml`. It builds `simstudio`, `realtime`, and `migrations` from the source checkout instead of pulling published images, and it ships neither a `redis` service nor a `cron` service. Without an external Redis, pub/sub falls back to a process-local emitter and API-key login through the CLI pairing-code flow fails, since that approval store has no fallback; the idempotency store and execution progress markers do fall back to Postgres. And with no cron service, every [background job](/platform/self-hosting/background-jobs) is missing. For production with local models, keep `docker-compose.prod.yml` and point `OLLAMA_URL` at an Ollama instance, as under [External Ollama](#external-ollama) below.
+### External Ollama
 
-Always pass a server profile alongside `setup`. With `--profile setup` on its own no Ollama server starts and `model-setup` waits forever.
+For production, keep this Compose stack and point `OLLAMA_URL` at an Ollama server. If it runs on the Docker host, save the address in `.env` so later recreations retain it:
 
 ```bash
-# With GPU
-docker compose -f docker-compose.ollama.yml --profile gpu --profile setup up -d
-
-# CPU only
-docker compose -f docker-compose.ollama.yml --profile cpu --profile setup up -d
+OLLAMA_URL=http://host.docker.internal:11434
 ```
 
-The `setup` profile pulls `gemma3:4b` as a starter model. Pull additional models — the service name differs by profile:
-```bash
-# GPU profile
-docker compose -f docker-compose.ollama.yml exec ollama ollama pull llama3.2
+Production Compose maps `host.docker.internal` to the host gateway, including on Linux. You can instead use a reachable host IP. The Ollama server must listen on an interface reachable from the container.
 
-# CPU profile
-docker compose -f docker-compose.ollama.yml exec ollama-cpu ollama pull llama3.2
+```bash
+docker compose -f docker-compose.prod.yml up -d
 ```
 
-### External Ollama
+<Callout type="warn">
+  Container `localhost` is the container itself. The default `http://localhost:11434` does not reach an Ollama server on the host.
+</Callout>
+
+### Development Ollama stack
 
-If Ollama runs on your host machine (not in Docker):
+`docker-compose.ollama.yml` builds the app, realtime, and migrations from source. It does not bundle Redis or cron. Without Redis, pub/sub is process-local and CLI pairing approval has no fallback; idempotency and execution-progress storage can fall back to PostgreSQL. Without a scheduler, background jobs do not run.
 
-Set it in the `.env` next to your Compose file. A one-shot shell prefix satisfies the interpolation for that command only, so the next `up -d` silently reverts to the `http://localhost:11434` default and the container points at itself:
+Use a server profile together with `setup`; `setup` alone starts no Ollama server and the model setup waits:
 
 ```bash
-# .env — macOS/Windows
-OLLAMA_URL=http://host.docker.internal:11434
+# NVIDIA GPU
+docker compose -f docker-compose.ollama.yml --profile gpu --profile setup up -d
 
-# Linux - use your host IP
-# OLLAMA_URL=http://192.168.1.100:11434
+# CPU only
+docker compose -f docker-compose.ollama.yml --profile cpu --profile setup up -d
 ```
 
+Setup pulls `gemma3:4b`. To pull another model:
+
 ```bash
-docker compose -f docker-compose.prod.yml up -d
-```
+# GPU profile
+docker compose -f docker-compose.ollama.yml exec ollama ollama pull llama3.2
 
-<Callout type="warn">
-  Inside Docker, `localhost` refers to the container, not your host. Use `host.docker.internal` or your host's IP.
-</Callout>
+# CPU profile
+docker compose -f docker-compose.ollama.yml exec ollama-cpu ollama pull llama3.2
+```
 
 ## LM Studio
 
-[LM Studio exposes an OpenAI-compatible API](https://lmstudio.ai/docs/developer/openai-compat). Start its local server, load a model, and enable **Serve on Local Network** so the Docker container can reach it. [Enable API authentication](https://lmstudio.ai/docs/developer/core/authentication), then set the endpoint and token in the `.env` file next to your Compose file:
+Start [LM Studio's local server](https://lmstudio.ai/docs/developer/core/server), load a model, enable **Serve on Local Network**, and [configure API authentication](https://lmstudio.ai/docs/developer/core/authentication). Save these values beside your Compose file:
 
 ```bash
-# macOS/Windows
 VLLM_BASE_URL=http://host.docker.internal:1234
-
-# Linux - use your host IP instead
-# VLLM_BASE_URL=http://192.168.1.100:1234
-
 VLLM_API_KEY=your_lm_studio_api_token
 ```
 
-Both the server root shown above and a URL ending in `/v1` are accepted. After recreating the `simstudio` service, its models appear in the model picker with a `vllm/` prefix; Sim removes that prefix before sending the model identifier to LM Studio.
+Use a reachable host IP when needed. Sim accepts the server root or a `/v1` URL. Models appear with a `vllm/` prefix, which Sim removes before sending the model ID to LM Studio.
+
+Recreate the app using the file that started your installation:
 
 ```bash
-# Pick the file that started your install.
 COMPOSE_FILE=docker-compose.prod.yml
-# COMPOSE_FILE=docker-compose.local.yml
-# COMPOSE_FILE=docker-compose.ollama.yml
+# For a source-built stack, use docker-compose.local.yml or docker-compose.ollama.yml.
 docker compose -f "$COMPOSE_FILE" up -d --force-recreate simstudio
 ```
 
 ## The `sim-setup` CLI
 
-`npx sim-setup` also manages an existing install created from the production or local-development Compose files. It does not detect or manage an Ollama-stack install. Run `doctor`, `config`, and the wizard from the directory holding your `.env` and Compose file; the lifecycle commands find a running stack wherever it was started. The table drops the `npx` prefix for brevity — keep it unless you installed the package globally.
+Invoke commands as `bunx sim-setup <command>` unless the package is installed globally. Run `doctor`, `config`, and the wizard from the configuration directory. Lifecycle commands discover running production/local Compose stacks, source checkouts, and Helm releases; Ollama-stack installs are not managed.
+
+| Command | Behavior |
+| --- | --- |
+| `sim-setup` | Wizard. `--quick` uses defaults and asks essential questions; `--mode compose\|dev\|k8s` chooses the target. Dev and Kubernetes modes require a source checkout. |
+| `status` | Reports detected installations and health. |
+| `logs` | Follows Compose logs or the Kubernetes app deployment. In dev mode, prints container log commands; the app runs in your terminal. |
+| `start` / `stop` / `restart` | Starts, stops, or restarts Compose services. In dev mode, manages only PostgreSQL and Redis; start/stop the dev server yourself. For Kubernetes, prints port-forward or scale commands without applying them. |
+| `update` | Pulls or rebuilds Compose images and applies them. Refuses dev and Kubernetes installs, which use git and `helm upgrade`. |
+| `down` | Confirms before removing managed containers or uninstalling the Helm release. Compose/dev data volumes remain. |
+| `reset` | Confirms before archiving env files and removing managed Compose/dev data. On Helm it uninstalls the release; PostgreSQL StatefulSet PVCs remain and must be deleted separately to erase data. |
+| `config` | Reports configured capabilities and integrations. |
+| `doctor` | Checks env files and reachable services. `--fix` writes supported repairs; `--json` emits structured findings. |
+| `add <feature>` | Configures `email`, `storage`, `sandbox`, `jobs`, `cache`, `knowledge`, `knowledge-embeddings`, `chat`, `llm`, or `integration <slug>`. Requires one writable configuration; refuses ambiguous destinations and Helm releases. |
+| `desktop` | Prints this deployment's installer/server links. `--url <url>` skips discovery; `--no-open` skips the browser-opening prompt. |
+
+`--dir <path>` works with every command and scopes standalone lifecycle commands to that installation.
 
-| Command | What it does |
-|---|---|
-| `sim-setup` | The setup wizard. `--quick` takes the defaults and asks only the essential questions, `--mode compose\|dev\|k8s` picks the target (`dev` and `k8s` need a source checkout) |
-| `sim-setup status` | Show what is installed and healthy |
-| `sim-setup logs` | Follow logs. On Kubernetes it follows the app deployment only; on a source checkout it prints where the logs are — the dev server streams in its own terminal — rather than following a stream |
-| `sim-setup start` / `stop` / `restart` | Bring the install up, down, or cycle it. On a source checkout this covers only the managed Postgres and Redis containers — the dev server is yours to start and stop. On Kubernetes it acts on nothing: `stop` prints the `kubectl scale` equivalents, and `start` and `restart` print the port-forward commands for reaching the release |
-| `sim-setup update` | Pull or rebuild images and apply them. Compose installs only — it refuses on source checkouts and Kubernetes, which update through git and `helm upgrade` |
-| `sim-setup down` | After a confirmation prompt, remove containers and keep the data. On a source checkout it removes only the managed Postgres and Redis containers, keeping their volume. On Kubernetes it runs `helm uninstall` on the whole release |
-| `sim-setup reset` | After a confirmation prompt, archive the env files and wipe managed data. A Compose install archives the `.env` beside its Compose file; a source checkout, a Kubernetes install, and an invocation with no install detected all archive `apps/sim/.env`, `apps/realtime/.env`, `packages/db/.env`, and the root `.env`. On Kubernetes it runs `helm uninstall`, which leaves the Postgres volumes behind — they come from a StatefulSet's `volumeClaimTemplates`, which Kubernetes never deletes. Delete those PVCs yourself to reset the data |
-| `sim-setup config` | Show configured capabilities and integrations |
-| `sim-setup doctor` | Check the setup. `--fix` repairs what it can, `--json` prints machine-readable output |
-| `sim-setup add <feature>` | Configure one capability: `email`, `storage`, `sandbox`, `jobs`, `cache`, `knowledge`, `knowledge-embeddings`, `chat`, `llm`, or `integration <slug>`. Writes to the `.env` beside your Compose file — recreate the containers that read the value to apply it, which for `cache` means `realtime` as well as `simstudio`, since both take `REDIS_URL` — or to `apps/sim/.env` on a source checkout, where `apps/realtime/.env` needs the same value. It refuses when no configuration is writable, when more than one is, and for Helm releases |
-| `sim-setup desktop` | Resolve the desktop installer for this deployment. `--url <url>` skips discovery, and is required when several detected configurations name different `NEXT_PUBLIC_APP_URL` origins. `--no-open` skips the "Download it now?" prompt — the link is printed either way |
+For Compose, `reset` archives `.env` beside the Compose file. For dev, Kubernetes, or no detected install, it archives `apps/sim/.env`, `apps/realtime/.env`, `packages/db/.env`, and root `.env`. Preserve any backups before intentionally removing volumes.
 
-`--dir <path>` is accepted by every command, not just the wizard. On a standalone install it also scopes the lifecycle commands to that directory's install, which is how you disambiguate when more than one exists.
+`add` writes beside the Compose file or to `apps/sim/.env` on a source checkout. Recreate containers that read the change: `cache` changes `REDIS_URL` for both app and realtime. For a source checkout, mirror shared values into `apps/realtime/.env`. `restart` alone does not apply changed container environment. Desktop discovery refuses configurations naming different origins; pass `--url` to choose.
 
-## Commands
+## Back up and update [#commands]
+
+For the default database role/name:
 
 ```bash
-# Did migrations succeed?
-docker compose -f docker-compose.prod.yml logs migrations
+docker compose -f docker-compose.prod.yml exec -T db pg_dump -U postgres simstudio > backup.sql
+```
 
-# Is the scheduler firing?
-docker compose -f docker-compose.prod.yml logs -f cron
+Restore only to the intended database:
 
-# Upgrade: bump SIM_VERSION in .env when pinned, then
-npx sim-setup update
+```bash
+docker compose -f docker-compose.prod.yml exec -T db psql -U postgres simstudio < backup.sql
+```
+
+Use your configured role/database if you changed `POSTGRES_*`. `-T` disables TTY allocation for redirected input/output. Compose stores database data in the `postgres_data` volume; file uploads and encryption keys need separate backups.
+
+For an image update, change the pinned `SIM_VERSION` in `.env`, then:
+
+```bash
+bunx sim-setup update
 ```
 
-<FAQ items={[
-  { question: "Do scheduled workflows work on Docker Compose?", answer: "Yes. The cron service runs the same jobs the Helm chart schedules as Kubernetes CronJobs, using the schedules in docker/crontab. It needs CRON_SECRET — without it the service prints what to set and exits, and the rest of the stack keeps running."},
-  { question: "Why is there a Redis container?", answer: "Redis backs pub/sub for live Chat task status and table events, plus shared caches. Pub/sub has no fallback that works across processes, so live status would not stream without it. The port is deliberately not published so it cannot collide with a local Redis."},
-  { question: "How do I back up and restore the database?", answer: "Back up with: docker compose -f docker-compose.prod.yml exec -T db pg_dump -U postgres simstudio > backup.sql. The -T matters — without it exec allocates a TTY and corrupts the redirected dump. Restore with: docker compose -f docker-compose.prod.yml exec -T db psql -U postgres simstudio < backup.sql. The database data is persisted in a Docker volume named postgres_data."},
-  { question: "Can I customize the PostgreSQL credentials?", answer: "Yes. Set POSTGRES_USER (default: postgres) and POSTGRES_DB (default: simstudio) in .env before the first start. POSTGRES_PASSWORD has no default — the compose file will not start without it. Postgres applies all three only when it creates the database volume, so changing them later does not change the existing database; to rotate the password, see Postgres on Compose in the security guide." },
-]} />
+Read [Upgrades](/platform/self-hosting/upgrades) before updating or restoring an existing installation.
+
+## Related docs
+
+- [Environment variables](/platform/self-hosting/environment-variables)
+- [Background jobs](/platform/self-hosting/background-jobs)
+- [Security](/platform/self-hosting/security)
diff --git a/apps/docs/content/docs/platform/self-hosting/email.mdx b/apps/docs/content/docs/platform/self-hosting/email.mdx
index 91505212e2a..7b45e080f55 100644
--- a/apps/docs/content/docs/platform/self-hosting/email.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/email.mdx
@@ -1,105 +1,99 @@
 ---
 title: Email
-description: Configure transactional email for invitations, verification, and notifications
+description: Configure and verify transactional email delivery
 ---
 
-import { Tabs, Tab } from 'fumadocs-ui/components/tabs'
+import { Tabs, Tab } from '@/components/ui/tabs'
 import { Callout } from 'fumadocs-ui/components/callout'
 
-Sim sends workspace invitations, email verification, password resets, and notifications. Configure at least one provider.
+Configure a mail provider for workspace invitations, email verification, password resets, and notifications. Use a sender address the provider is authorized to send as.
 
 <Callout type="warn">
-  With no provider configured, nothing is sent and nothing errors — the mailer logs a single line with the recipient, subject, and sender, then reports success. On a production deployment that means workspace invitations silently never arrive. The message body is **not** logged, so an email missed this way cannot be recovered from the logs.
+  Without a mail provider, Sim skips delivery and reports success. At INFO log level it records recipient, subject, and sender, but not the message body. Invitations and password resets will not arrive; the message cannot be recovered from those logs. Email verification is enforced only when a provider is configured.
 </Callout>
 
 ## Provider selection
 
-There is no provider flag. Every provider whose variables are set becomes active, and the mailer tries them in this fixed order, falling through to the next one only when the previous **fails**:
+There is no provider-selection flag. Every configured, usable provider participates in this fallback order:
 
 **Resend → AWS SES → SMTP → Azure Communication Services → Gmail**
 
-So the earliest configured provider handles normal traffic, and any others act as automatic failover. Configuring one is the simple case; configuring two gives you a fallback path at the cost of mail occasionally leaving from a different sender.
+The first provider handles normal traffic. Later providers are tried only after a failure. Configure a single provider or verify the sender and permissions for every fallback you enable.
 
 ## Shared settings
 
-| Variable | Description |
-|---|---|
-| `FROM_EMAIL_ADDRESS` | Sender address, e.g. `Sim <noreply@example.com>` |
-| `EMAIL_DOMAIN` | Fallback domain when `FROM_EMAIL_ADDRESS` is unset — sends as `noreply@EMAIL_DOMAIN` |
-| `EMAIL_VERIFICATION_ENABLED` | Set `true` to require email verification at signup |
+| Variable | Behavior |
+| --- | --- |
+| `FROM_EMAIL_ADDRESS` | Sender, such as `Sim <noreply@example.com>`. |
+| `EMAIL_DOMAIN` | When the sender is unset, use `noreply@EMAIL_DOMAIN`. |
+| `EMAIL_VERIFICATION_ENABLED` | Set `true` to require signup verification when a mail provider is configured. |
 
-The sender address must be one your provider is authorized to send as. A mismatch is the most common cause of mail that is accepted by the provider and then silently dropped or spam-filtered downstream.
-
-## Providers
+## Configure a provider [#providers]
 
 <Tabs items={['Resend', 'AWS SES', 'SMTP', 'Azure ACS', 'Gmail']}>
-  <Tab value="Resend">
-
-Simplest option if you have no existing mail infrastructure.
+<Tab value="Resend">
 
 ```bash
 RESEND_API_KEY=re_...
 FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"
 ```
 
-Verify your sending domain in the Resend dashboard and add the DNS records it gives you before sending in production.
+Verify your sending domain and add Resend's DNS records before production delivery. See [Resend domain setup](https://resend.com/docs/dashboard/domains/introduction).
 
-  </Tab>
-  <Tab value="AWS SES">
+</Tab>
+<Tab value="AWS SES">
 
 ```bash
 AWS_SES_REGION=us-east-1
 FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"
 ```
 
-Credentials resolve through the standard AWS provider chain — environment variables, shared config, ECS/EKS task role (IRSA), EC2 instance profile, or SSO. On EKS, attach an IRSA role with `ses:SendEmail` and `ses:SendRawEmail` and set no keys at all.
+Credentials use the AWS default provider chain: environment/shared configuration, ECS/EKS roles, EC2 instance profile, or SSO. For EKS, an IRSA role can provide `ses:SendEmail` and `ses:SendRawEmail` without static keys. Verify your sending identity and configure DKIM in the chosen SES region.
 
 <Callout type="warn">
-  New SES accounts are in the **sandbox**, which only permits sending to verified addresses. Invitations to your team will fail until you request production access. Verify the sending domain and configure DKIM as well.
+  New SES accounts start in a region-specific sandbox and can send only to verified recipients or the mailbox simulator. Request production access before inviting unverified recipients. See [SES sandbox restrictions](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html).
 </Callout>
 
-  </Tab>
-  <Tab value="SMTP">
+</Tab>
+<Tab value="SMTP">
 
-Works with any relay — Postfix, SendGrid, Mailgun, Google Workspace SMTP relay, or MailHog for local testing.
+Use a reachable relay such as Postfix, SendGrid, Mailgun, Google Workspace SMTP relay, or a local test relay:
 
 ```bash
 SMTP_HOST=smtp.example.com
-SMTP_PORT=587          # 465 implicit TLS, 587 STARTTLS, 25 plain
-SMTP_USER=apikey       # omit for unauthenticated relays
-SMTP_PASS=...          # omit for unauthenticated relays
-# SMTP_SECURE=true     # only for implicit TLS. Leave unset on 587 — it is
-                       # automatic on 465, and forcing it on a STARTTLS port fails to connect
-# SMTP_EHLO_NAME=mail.yourdomain.com   # only if the relay expects an identity other
-                       # than the domain Sim is served from
+SMTP_PORT=587
+SMTP_USER=apikey
+SMTP_PASS=...
 FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"
 ```
 
-Sim greets the relay with the domain it is served from, derived from `NEXT_PUBLIC_APP_URL`, so `SMTP_EHLO_NAME` is rarely needed. Without that derivation the underlying mail library would fall back to the address literal `[127.0.0.1]` on Kubernetes, where pod hostnames have no dot — a greeting strict relays reject outright.
+Set both `SMTP_USER` and `SMTP_PASS` for authenticated relays, or omit both for an unauthenticated relay. Port 465 enables implicit TLS automatically. Leave `SMTP_SECURE` unset for port 587/STARTTLS; forcing implicit TLS there prevents connection. Port 25 uses a non-implicit-TLS connection.
 
-For Google Workspace without a service account:
+Sim derives its EHLO hostname from `NEXT_PUBLIC_APP_URL`. If the relay needs another identity, set `SMTP_EHLO_NAME` to a fully qualified hostname it accepts.
+
+For a Google Workspace IP-authorized relay:
 
 ```bash
 SMTP_HOST=smtp-relay.gmail.com
 SMTP_PORT=587
 ```
 
-The relay must be configured to accept mail from your deployment's egress IP in the Workspace admin console. It needs no service account and no domain-wide delegation, so prefer it over the Gmail API path unless you cannot allowlist a stable egress IP.
+Configure the relay in Workspace administration to accept the deployment's public egress IP and permitted senders. This path does not require a service-account key or domain-wide delegation. If a stable IP is unavailable, consider authenticated SMTP or the Gmail API path. See [Google SMTP relay settings](https://knowledge.workspace.google.com/admin/gmail/advanced/route-outgoing-smtp-relay-messages-through-google).
 
-  </Tab>
-  <Tab value="Azure ACS">
+</Tab>
+<Tab value="Azure ACS">
 
 ```bash
 AZURE_ACS_CONNECTION_STRING=endpoint=https://...;accesskey=...
 FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"
 ```
 
-Provision an Email Communication Service, connect a verified domain, then link it to the Communication Service resource. The sender address must belong to the linked domain.
+Provision an Email Communication Service, verify its sending domain, and link that domain to the Communication Service. Use a sender from the linked domain. See [Azure's email-domain connection guide](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/email/connect-email-communication-resource).
 
-  </Tab>
-  <Tab value="Gmail">
+</Tab>
+<Tab value="Gmail">
 
-GCP has no first-party transactional email service, so the Google-native path is the Gmail API with a Google Workspace sender.
+Use a service account to impersonate a Google Workspace sender:
 
 ```bash
 GMAIL_CREDENTIALS_JSON='{"type":"service_account",...}'
@@ -107,65 +101,93 @@ GMAIL_SENDER=noreply@yourdomain.com
 FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"
 ```
 
-Setup:
-
-1. Create a service account and download its JSON key.
-2. In the Workspace admin console → **Security → Access and data control → API controls → Domain-wide delegation → Add new**, add the service account's `client_id` with the scope `https://www.googleapis.com/auth/gmail.send`.
-3. Set `GMAIL_SENDER` to the Workspace user the service account impersonates.
+1. Enable Gmail API in the Google Cloud project.
+2. Create a service account, enable domain-wide delegation, and download its JSON key.
+3. In Workspace administration, open **Security → Access and data control → API controls → Domain-wide delegation → Add new**. Add the service account's numeric `client_id` with `https://www.googleapis.com/auth/gmail.send`.
+4. Set `GMAIL_SENDER` to the Workspace user to impersonate. See [Google service-account credentials](https://developers.google.com/workspace/guides/create-credentials).
 
 <Callout type="warn">
-  `FROM_EMAIL_ADDRESS` must match `GMAIL_SENDER` or one of its registered aliases. Gmail rewrites unrecognized From addresses, so a mismatch produces mail that sends successfully but arrives from the wrong address.
+  `FROM_EMAIL_ADDRESS` must match `GMAIL_SENDER` or a registered alias. Gmail can rewrite an unrecognized sender even when delivery succeeds.
 </Callout>
 
-<Callout type="info">
-  Gmail caps sending at roughly 2,000 messages per day per user — ample for invitations and verification on most deployments. If you need more, switch to the Workspace SMTP relay or Resend; both are configuration-only changes.
-</Callout>
+Paid Workspace accounts currently allow up to 2,000 messages per user over a rolling 24-hour period, with lower trial and separate recipient limits. Check [Google's sending limits](https://knowledge.workspace.google.com/admin/gmail/gmail-sending-limits-in-google-workspace) before choosing this path for your volume. SMTP relay has separate limits.
 
-Keep the JSON on one line when pasting it into a values file:
+For a single-line JSON secret:
 
 ```bash
 jq -c . service-account-key.json
 ```
 
-  </Tab>
+</Tab>
 </Tabs>
 
-## Kubernetes
+## Apply configuration
+
+For Compose, save provider settings in `.env` beside the Compose file and recreate the app:
+
+```bash
+docker compose -f docker-compose.prod.yml up -d --force-recreate simstudio
+```
+
+For a source checkout, save them in `apps/sim/.env` and restart the app.
 
-Email credentials are secrets. Supply them through your secret store rather than plain values:
+### Kubernetes
+
+Choose one of the chart's [secret strategies](/platform/self-hosting/kubernetes#secret-stores):
+
+- **Inline mode:** set credentials under `app.env`; Helm writes them to a Secret but also retains them in release values. Do not commit secret values to Git.
+- **Existing Secret:** add the provider keys to the pre-created app Secret. Credentials set explicitly under `app.env` in this mode are inlined into pod specs.
+- **ESO:** map each credential under `externalSecrets.remoteRefs.app`; the chart-managed inline Secret is disabled. Use `app.envDefaults` for non-secret sender settings.
+
+For example, merge this into a complete ESO configuration whose store and core secrets are already configured:
 
 ```yaml
 app:
-  env:
+  envDefaults:
     FROM_EMAIL_ADDRESS: "Sim <noreply@yourdomain.com>"
-    RESEND_API_KEY: "re_..."      # via External Secrets or an existing Secret
+externalSecrets:
+  remoteRefs:
+    app:
+      RESEND_API_KEY: "sim/app/resend-api-key"
 ```
 
-In the default and External Secrets modes, `app.env` keys are written into a chart-managed Secret and mounted via `envFrom`, so values do not appear in pod specs. A secret committed to `values.yaml` is still a secret in your git history — pass it through External Secrets or a pre-created Secret instead.
+Restart the affected app pods after the credentials have synchronized:
+
+```bash
+kubectl rollout restart deployment/sim-app -n simstudio
+```
 
-## Verifying
+## Verify delivery [#verifying]
 
-Invite a user to a workspace from workspace settings and watch the app logs:
+Invite a test member from workspace settings, confirm the message arrives, and accept it. If verification is required, also test a new account's verification message and a password reset.
+
+Set `LOG_LEVEL=INFO` and restart/recreate the app before using logs to diagnose skipped delivery. The production default is `ERROR`; log-level values are uppercase.
 
 ```bash
 kubectl logs -n simstudio -l app.kubernetes.io/component=app --tail=100 | grep -i mail
 ```
 
-| What you see | Meaning |
-|---|---|
-| A single log line with recipient, subject, and sender, and no delivery | No provider is configured — the mailer no-opped |
-| A provider API error | Credentials or sender address problem; the error names which |
-| Success, but nothing arrives | Delivered to the provider — check the provider's dashboard, then spam filtering, SPF, and DKIM |
-
-## Troubleshooting
+For Compose, use `docker compose -f docker-compose.prod.yml logs simstudio`.
 
-**"Delegation denied" / `unauthorized_client` (Gmail)** — the domain-wide delegation entry is missing or has the wrong client ID or scope. Re-check the admin console entry against the `client_id` in the service-account JSON, and confirm the scope is exactly `https://www.googleapis.com/auth/gmail.send`.
+| Signal | Diagnosis |
+| --- | --- |
+| No-provider log with recipient, subject, and sender | Sim skipped delivery. Configure a usable provider. |
+| Provider error | Check the named provider's credentials, sender, permissions, and quotas. Later configured providers may be tried. |
+| Provider acceptance but no message | Check delivery status in its dashboard, recipient filtering, SPF, DKIM, and DMARC. Acceptance does not prove inbox delivery. |
 
-**Mail rejected with a From-address error** — the sender is not authorized for the provider's verified domain. Align `FROM_EMAIL_ADDRESS` with the verified domain (and with `GMAIL_SENDER` on the Gmail path).
-
-**SES rejects recipients** — the account is still in the SES sandbox. Request production access.
+## Troubleshooting
 
-**Mail lands in spam** — configure SPF, DKIM, and DMARC for your sending domain. This is on your DNS, not on Sim.
+| Failure | Action |
+| --- | --- |
+| Gmail `unauthorized_client` or delegation denied | Match the JSON `client_id` to the Workspace delegation entry and confirm the exact `gmail.send` scope and impersonated user. |
+| Sender rejected or rewritten | Match the verified sender/domain; for Gmail, use the impersonated sender or its registered alias. |
+| SES rejects an unverified recipient | Request production access in the configured region. |
+| SMTP connection fails | Check host/port, reachability, matching username/password, and implicit TLS versus STARTTLS. |
+| SMTP rejects EHLO, such as `421-4.7.0` | Set `SMTP_EHLO_NAME` to a dotted hostname accepted by the relay. Older releases used `[127.0.0.1]` on Kubernetes; upgrade to use the public-domain derivation. |
+| Mail is filtered as spam | Verify sending-domain SPF, DKIM, and DMARC, then inspect provider delivery events. |
 
-**SMTP fails at the greeting with `421-4.7.0 Try again later, closing connection. (EHLO)`** — the relay rejected how the client identified itself, not your credentials or IP allowlist. Strict relays, Google Workspace's among them, refuse a greeting that is not a fully-qualified domain name. Sim greets with the domain it is served from, so this should not occur; if it does, set `SMTP_EHLO_NAME` to a dotted hostname the relay accepts. Older releases always greeted as `[127.0.0.1]` on Kubernetes — upgrade rather than working around it.
+## Related docs
 
+- [Authentication](/platform/self-hosting/authentication)
+- [Environment variables](/platform/self-hosting/environment-variables)
+- [Verify your install](/platform/self-hosting/verify)
diff --git a/apps/docs/content/docs/platform/self-hosting/environment-variables.mdx b/apps/docs/content/docs/platform/self-hosting/environment-variables.mdx
index f31b1d32246..8c1b71b8143 100644
--- a/apps/docs/content/docs/platform/self-hosting/environment-variables.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/environment-variables.mdx
@@ -1,10 +1,14 @@
 ---
-title: Environment Variables
-description: Configuration reference for Sim
+title: Environment variables
+description: Deployment configuration, feature prerequisites, and limits
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
+Configure variables in the env files or secret strategy for your deployment. Restart source processes or recreate containers/pods after changes; a running process does not reread credentials.
+
+Production Compose derives `DATABASE_URL` and `BETTER_AUTH_URL` on its service definitions, overriding values in `.env`. Use `POSTGRES_*` and `NEXT_PUBLIC_APP_URL` there. Helm constructs the database URL from its database values. See [Docker](/platform/self-hosting/docker) and [Kubernetes secret strategies](/platform/self-hosting/kubernetes#secret-stores).
+
 ## Required
 
 | Variable | Description |
@@ -16,28 +20,28 @@ import { Callout } from 'fumadocs-ui/components/callout'
 | `INTERNAL_API_SECRET` | Internal API secret, at least 32 characters: `openssl rand -hex 32` |
 | `NEXT_PUBLIC_APP_URL` | Public app URL |
 
-`openssl rand -hex 32` prints 64 hex characters. `ENCRYPTION_KEY` and `API_ENCRYPTION_KEY` must be exactly that — a value of any other shape throws the first time Sim encrypts or decrypts, not at startup. The rest are secrets of no fixed shape and only need 32 characters or more. The Sim app never checks — it runs its env schema with validation skipped — but the realtime service validates `BETTER_AUTH_SECRET` and `INTERNAL_API_SECRET` at boot and refuses to start if either is shorter.
+`openssl rand -hex 32` prints 64 hex characters. Encryption keys require that format. The app skips its env schema validation; individual consumers can reject invalid values when first used. Realtime validates `BETTER_AUTH_SECRET` and `INTERNAL_API_SECRET` at boot and rejects values shorter than 32 characters.
 
 <Callout type="error">
-  `ENCRYPTION_KEY` and `API_ENCRYPTION_KEY` cannot be rotated or recovered. Losing either makes the data it protects permanently unreadable — workspace and personal environment variables, stored provider API keys, MCP OAuth credentials, and deployment/chat secrets in the first case, user-generated Sim API keys in the second. Back them up separately from the database.
+  Retain `ENCRYPTION_KEY` and `API_ENCRYPTION_KEY` across upgrades and restores. There is no supported in-place key rotation procedure; losing a key makes values encrypted with it unreadable — workspace and personal environment variables, stored provider API keys, MCP OAuth credentials, and deployment/chat secrets in the first case, user-generated Sim API keys in the second. Back them up separately from the database.
 </Callout>
 
-## Strongly recommended
+## Feature prerequisites and coordination [#strongly-recommended]
 
 | Variable | Description |
 |----------|-------------|
-| `API_ENCRYPTION_KEY` | Encrypts user-generated Sim API keys at rest, exactly 64 hex characters (32 bytes): `openssl rand -hex 32`. **When unset, API keys are stored in plain text** — the app logs a warning each time it encrypts or decrypts one and keeps working |
-| `CRON_SECRET` | Bearer token for the background job endpoints: `openssl rand -hex 32`. **Required whenever background jobs are enabled** — the Helm chart's default, and the chart will not render without it, unless it comes from `app.secrets.existingSecret` or External Secrets. See [Background Jobs](/platform/self-hosting/background-jobs) |
-| `REDIS_URL` | Redis connection string. Optional on a single replica; **required** past one app or realtime replica — see [Redis](/platform/self-hosting/redis) |
+| `API_ENCRYPTION_KEY` | Encrypts stored Sim API-key material; use exactly 64 hex characters (`openssl rand -hex 32`). When unset, legacy API keys can be stored in plain text; the key getter logs a warning when called |
+| `CRON_SECRET` | Bearer token for the background job endpoints: `openssl rand -hex 32`. **Required whenever background jobs are enabled** — the Helm chart's default, and the chart will not render without it, unless it comes from `app.secrets.existingSecret` or External Secrets. See [Background jobs](/platform/self-hosting/background-jobs) |
+| `REDIS_URL` | Redis connection string. Required for cross-replica events and features with no fallback, such as CLI pairing approval. Some single-process storage paths can fall back to PostgreSQL or local state; see [Redis](/platform/self-hosting/redis) |
 | `REDIS_TLS_SERVERNAME` | TLS SNI override. Required when `REDIS_URL` uses `rediss://` with a bare IP, or the app throws the first time it opens a Redis connection |
-| `NEXT_PUBLIC_SOCKET_URL` | WebSocket URL — defaults to the page origin; set only if realtime is on a separate host |
+| `NEXT_PUBLIC_SOCKET_URL` | Public WebSocket URL. Proxied deployments default to the page origin; a localhost page uses port 3002. Set it for a separate realtime host. |
 | `TRUSTED_ORIGINS` | Comma-separated additional origins to trust for auth (apex + `www`, alias domains) |
 | `AUTH_TRUSTED_PROXIES` | Comma-separated reverse-proxy IPs/CIDRs so the client IP cannot be forged through `X-Forwarded-For` |
-| `INTERNAL_API_BASE_URL` | Internal URL for server-side self-calls, e.g. `http://sim-app.simstudio.svc.cluster.local:3000`. Optional — falls back to the public base URL. Deliberately ignored inside the Trigger.dev worker runtime, where a cluster-internal address resolves to the worker itself |
+| `INTERNAL_API_BASE_URL` | Internal URL for server-side self-calls, e.g. `http://sim-app.simstudio.svc.cluster.local:3000`. Defaults to the public base URL. The Trigger.dev worker ignores it and uses the public app URL. |
 | `SIM_MCP_URL` | Public URL of the [Sim MCP server](/mcp/overview) when you serve it on its own host, e.g. `https://mcp.example.com/mcp`. Point that host at the app; Sim serves only the MCP endpoint and its OAuth metadata there, and stops serving `/api/mcp` on the app host so clients use one URL. Optional — defaults to `<NEXT_PUBLIC_APP_URL>/api/mcp` |
 | `DATABASE_REPLICA_URL` | Read-replica connection string for log listing, audit logs, and dashboard aggregations. Falls back to the primary when unset |
 
-## AI Providers
+## AI providers
 
 | Variable | Provider |
 |----------|----------|
@@ -56,19 +60,13 @@ import { Callout } from 'fumadocs-ui/components/callout'
 | `OLLAMA_URL` | Ollama (default: `http://localhost:11434`) |
 | `VERTEX_PROJECT` / `VERTEX_LOCATION` | Google Vertex AI — GCP project ID and region (region defaults to `us-central1`) |
 
-<Callout type="warn">
-  **Knowledge bases need an embedding model, selected with `KB_EMBEDDING_MODEL`.** Hosted: `text-embedding-3-small` (default) and `text-embedding-3-large` on OpenAI or Azure OpenAI, and `gemini-embedding-001` on Gemini. Local: any embedding model on your own Ollama, named `ollama/<model>` (for example `ollama/nomic-embed-text`) with `OLLAMA_URL` set. Ollama serves embeddings only through this variable — embeddings never route through the configured chat model, so vLLM and LM Studio do not substitute.
-</Callout>
+Knowledge bases use an embedding model independent of the chat model. See [Knowledge bases](#knowledge-bases) for supported providers, local Ollama, and vector widths.
 
-<Callout type="info">
-  For load balancing, add multiple keys with `_1`, `_2`, `_3` suffixes (e.g., `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`). Works with OpenAI, Anthropic, Gemini, xAI, Kimi, Z.ai, Cohere, and Fireworks.
-</Callout>
+For provider-key rotation, configure `_1`, `_2`, and `_3` keys, such as `OPENAI_API_KEY_1` and `OPENAI_API_KEY_2`. OpenAI, Anthropic, Gemini, xAI, Kimi, Z.ai, Cohere, and Fireworks support numbered keys.
 
-<Callout type="info">
-  In Docker, use `OLLAMA_URL=http://host.docker.internal:11434` for host-machine Ollama.
-</Callout>
+For Ollama on the Docker host, use `OLLAMA_URL=http://host.docker.internal:11434` and ensure its server is reachable from the container.
 
-<Callout type="info">
+<Callout type="warn">
   **Agent tool-call depth.** An Agent block keeps calling tools until the model answers, with no round-trip limit by default. With billing disabled there is also no execution timeout unless `EXECUTION_TIMEOUT_FREE` (sync) or `EXECUTION_TIMEOUT_ASYNC_FREE` (async) is set, so a looping agent keeps making paid model calls. Set `MAX_TOOL_ITERATIONS` (for example `MAX_TOOL_ITERATIONS=50`) to cap the model round trips per block, or set those timeouts to bound the whole run.
 </Callout>
 
@@ -92,7 +90,7 @@ import { Callout } from 'fumadocs-ui/components/callout'
 |----------|-------------|
 | `AZURE_OPENAI_API_KEY` | Azure OpenAI API key |
 | `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint URL |
-| `AZURE_OPENAI_API_VERSION` | API version (e.g., `2024-02-15-preview`) |
+| `AZURE_OPENAI_API_VERSION` | API version supported by your Azure model/deployment; check the [API lifecycle](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/api-version-lifecycle) |
 | `KB_OPENAI_MODEL_NAME` | Azure deployment name serving the knowledge base embedding model. Optional — defaults to the model id, which is only correct when the deployment is named after the model |
 
 ### Azure Anthropic
@@ -121,94 +119,21 @@ import { Callout } from 'fumadocs-ui/components/callout'
 | `LITELLM_BASE_URL` | LiteLLM proxy base URL |
 | `LITELLM_API_KEY` | Optional bearer token for LiteLLM |
 
-## Login Providers
-
-Google, GitHub, and Microsoft sign-in, their callback URLs, and the `DISABLE_*_AUTH` switches are documented in [Authentication](/platform/self-hosting/authentication#social-login).
-
-## Integration Credentials
-
-<Callout type="warn">
-  OAuth integrations require a provider application and its credentials on a self-hosted deployment. API-key integrations use the keys supplied in their blocks. The full table, redirect-URI format, and setup steps are in [Integrations & OAuth](/platform/self-hosting/integrations-oauth).
-</Callout>
-
-## Access Control
-
-Who may sign up and sign in — the allowlists, blocklists, `DISABLE_REGISTRATION`, `DISABLE_INVITATIONS`, `DISABLE_PUBLIC_API`, and `DISABLE_AUTH` — is documented in [Authentication](/platform/self-hosting/authentication).
-
-## Code Execution
-
-| Variable | Description |
-|----------|-------------|
-| `SANDBOX_PROVIDER` | Remote sandbox provider: `e2b` (default) or `daytona` |
-| `E2B_ENABLED` / `E2B_API_KEY` | Enable E2B remote execution |
-| `DAYTONA_API_KEY` | Daytona API key (used when `SANDBOX_PROVIDER=daytona`) |
-| `E2B_FUNCTION_TEMPLATE_ID` | Immutable `<template>:<build-id>` ref for the Function base image. Required for E2B; a mutable tag is refused |
-| `E2B_FUNCTION_TEMPLATE_GENERATION` | Monotonic release generation printed by the same build. Required for E2B |
-| `DAYTONA_FUNCTION_SNAPSHOT_ID` | Immutable snapshot **ID** (not a name) for the Function base image. Required for Daytona |
-| `E2B_PI_TEMPLATE_ID` / `DAYTONA_PI_SNAPSHOT_ID` | The image Pi runs on. Separate from the Function base — configuring the provider and Function image alone leaves Pi failing closed |
-| `SANDBOXES_ENABLED` / `NEXT_PUBLIC_SANDBOXES_ENABLED` | Enable custom sandboxes on a self-hosted deployment, bypassing the hosted-plan requirement. Neither is sufficient on its own — a provider key **and** an immutable Function base must also be configured. Set the `NEXT_PUBLIC_` twin only after the server side works; it enables nothing by itself — it reveals the Function block's Sandbox selector, and on a Compose install or source checkout `npx sim-setup doctor` confirms it agrees with the selected provider's readiness |
-| `IVM_MAX_EXECUTIONS_PER_WORKER` | Executions before an isolated-vm worker is recycled |
-| `IVM_MAX_BROKERS_PER_EXECUTION` | Host-call brokers per execution |
-| `IVM_MAX_BROKER_ARGS_JSON_CHARS` | Max argument payload size |
-| `IVM_MAX_BROKER_RESULT_JSON_CHARS` | Max result payload size |
-
-Without a remote provider, user code runs in an in-process V8 isolate inside the app container. See [Sandboxes](/platform/self-hosting/sandboxes) for the base-image build and [Security](/platform/self-hosting/security) for the isolation comparison.
-
-## Networking & Limits
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `API_MAX_JSON_BODY_BYTES` | 50 MB | Max JSON body on contract-validated API routes |
-| `CHAT_MAX_REQUEST_BYTES` | 220 MB | Max body on the public deployed-chat endpoint |
-| `WEBHOOK_MAX_REQUEST_BYTES` | 10 MB | Max body on public webhook receiver endpoints |
-| `WORKFLOW_EXECUTION_CONCURRENCY_LIMIT` | `75` | Trigger.dev workflow task concurrency |
-| `WEBHOOK_EXECUTION_CONCURRENCY_LIMIT` | `75` | Trigger.dev webhook task concurrency |
-| `SCHEDULE_EXECUTION_CONCURRENCY_LIMIT` | `30` | Scheduled executions per app instance |
-| `RESUME_EXECUTION_CONCURRENCY_LIMIT` | `50` | Trigger.dev resume task concurrency |
-| `EGRESS_ALLOWED_HOSTS` | unset | Comma-separated hostnames outbound requests may reach on a private network. Leading wildcard allowed, e.g. `host.docker.internal,*.svc.cluster.local`. Not honored for URLs harvested from content or a third-party response, nor for an HTTP block's `proxyUrl` |
-| `EGRESS_ALLOWED_IP_RANGES` | unset | Comma-separated CIDRs or IPs outbound requests may reach on a private network, e.g. `10.0.0.0/8`. Same exclusions |
-| `ALLOW_PRIVATE_DATABASE_HOSTS` | unset | **Deprecated.** Vouches for the entire private address space, for database, cache, and mail connector hosts only. Replace it with the two settings above naming specific destinations |
-
-A malformed entry in either allowlist stops the app at startup with a message naming the setting. See [the SSRF boundary](/platform/self-hosting/security#the-ssrf-boundary) for the accepted syntax and for what the allowlist does and does not reach.
-
-Your reverse proxy's body-size limit must be at least as large as the app limits above. See [Networking](/platform/self-hosting/networking).
-
-## Observability
-
-| Variable | Description |
-|----------|-------------|
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint |
-| `OTEL_EXPORTER_OTLP_HEADERS` | Auth headers, `key=value` comma-separated |
-| `OTEL_TRACES_SAMPLER_ARG` | Trace sampling ratio |
-| `OTEL_DEPLOYMENT_ENVIRONMENT` | Environment label on emitted spans |
-| `TELEMETRY_SAMPLING_RATIO` | Application-level sampling ratio |
-| `TELEMETRY_ENDPOINT` | Where anonymous telemetry is sent. Defaults to `https://telemetry.simstudio.ai/v1/traces` — point it at your own collector to keep traces internal |
-| `NEXT_TELEMETRY_DISABLED` | Set to `1` to disable anonymous telemetry entirely |
-| `GRAFANA_OTLP_ENDPOINT` / `GRAFANA_OTLP_HEADERS` / `GRAFANA_DEPLOYMENT_ENVIRONMENT` | Grafana Cloud OTLP export |
-
-See [Observability](/platform/self-hosting/observability).
-
-## Knowledge Bases
+## Knowledge bases
 
 | Variable | Description |
 |----------|-------------|
-| `KB_IMAGE_EXTRACTION_MODEL` | Gemini model that reads Confluence image attachments into searchable text. Defaults to `gemini-3.8-flash`; a value that is not a Gemini 3 model in the catalog falls back to the default. Needs `GEMINI_API_KEY` (or a workspace Gemini key); without one, image attachments are left out of syncs |
+| `KB_IMAGE_EXTRACTION_MODEL` | Gemini model that reads Confluence image attachments into searchable text. Defaults to `gemini-3.8-flash`; a value that is not a Gemini 3 or later model in the catalog falls back to the default. Needs `GEMINI_API_KEY` (or a workspace Gemini key); without one, image attachments are left out of syncs |
 | `KB_IMAGE_EXTRACTIONS_PER_SYNC` | New or changed images one connector sync sends for reading, at least `1`. Defaults to `500`; the rest wait for the next sync, which reports as partial |
 | `KB_CONFIG_VISION_REQUESTS_PER_MINUTE` | Image reads per minute per Gemini key, shared by every sync on the deployment. Defaults to `300`; lower it to match a key with a smaller Gemini quota |
 | `KB_EMBEDDING_MODEL` | Embedding model for new knowledge bases. Defaults to `text-embedding-3-small`; use `ollama/<model>` for a model on your own Ollama. An unrecognised hosted model id falls back to the default, but an `ollama/` id is taken at face value — if that model is not on the server, knowledge-base creation fails rather than falling back |
-| `EMBEDDING_OUTPUT_DIMS` | Vector width new knowledge bases are stored at: `384`, `768`, `1024`, `1536` (default), or `3072`. It must be a width the chosen model can emit; anything else falls back to `1536` with a warning |
+| `EMBEDDING_OUTPUT_DIMS` | Stored vector width: `384`, `768`, `1024`, `1536`, or `3072`. Hosted models default to `1536` when supported, otherwise their largest storable width. Invalid hosted widths fall back with a warning; Ollama can infer its actual width when unset |
 | `OPENROUTER_API_KEY` | Fallback route for the OpenAI embedding models — used when it is set and `OPENAI_API_KEY` is not the chosen path |
 | `COHERE_API_KEY` | Enables the Knowledge block reranker |
 
-Both variables apply at creation time and are recorded on the knowledge base, so changing either
-affects new knowledge bases only. Existing ones keep the model and width they were built with, and
-knowledge bases with different settings cannot be searched together.
+`KB_EMBEDDING_MODEL` and `EMBEDDING_OUTPUT_DIMS` apply to new knowledge bases. Existing bases retain their recorded model and width, and bases with different settings cannot be searched together.
 
-Matching the width to the model is yours to get right for a hosted provider: Sim knows only the
-widths each one documents, so a width that model cannot emit falls back to `1536` with a warning.
-For Ollama it is checked — leave `EMBEDDING_OUTPUT_DIMS` unset and Sim reads the model's width from
-your server, refusing to create the knowledge base if it cannot; set it explicitly and a mismatch
-surfaces as a failed document instead. Common pairings:
+For hosted models, Sim checks catalog-supported widths and falls back to the model's default on invalid configuration. For Ollama, leave `EMBEDDING_OUTPUT_DIMS` unset to infer the model's width; creation fails if Sim cannot establish a supported width. If you set it explicitly, a mismatch can fail document processing. Example pairings:
 
 | `EMBEDDING_OUTPUT_DIMS` | Works with |
 |----------|-------------|
@@ -218,13 +143,7 @@ surfaces as a failed document instead. Common pairings:
 | `1536` | `text-embedding-3-small`, `text-embedding-3-large`, `gemini-embedding-001` |
 | `3072` | `text-embedding-3-large`, `gemini-embedding-001` |
 
-On a Compose install or source checkout, `sim-setup add knowledge-embeddings` walks through all of
-this — pick OpenAI, Azure OpenAI, OpenRouter, Gemini, or Ollama and it writes the variables that
-family needs. The three OpenAI-family transports share the same model and width prompts.
-`sim-setup config` then reports the one family your `KB_EMBEDDING_MODEL` actually selects, rather
-than every provider you happen to hold a key for. Helm releases set these values through your own
-chart values instead, and an Ollama server is yours to run either way — `sim-setup` configures Sim
-to reach one, never installs it.
+For Compose or a source checkout, run `bunx sim-setup add knowledge-embeddings` to choose OpenAI, Azure OpenAI, OpenRouter, Gemini, or Ollama and write its configuration. The three OpenAI-family transports share model/width choices. `bunx sim-setup config` reports the family selected by `KB_EMBEDDING_MODEL`. For Helm, set the variables through chart values or your secret strategy. Run Ollama yourself; the setup command configures a connection, not an Ollama installation.
 
 The Embeddings block reads the same `OLLAMA_URL`. It lists the models on that server that report an
 embedding capability, with the width each one emits where Ollama reports it, so a workflow can embed
@@ -232,26 +151,55 @@ locally without an API key. Ollama only began reporting capabilities in 0.5 —
 server nothing can be filtered, so the list includes chat models and labels none of them with a
 width. Check what you pick there, or upgrade Ollama.
 
-## Chat & PII
+## Login providers
+
+Google, GitHub, and Microsoft sign-in, their callback URLs, and the `DISABLE_*_AUTH` switches are documented in [Authentication](/platform/self-hosting/authentication#social-login).
+
+## Integration credentials
+
+OAuth integrations require a provider application and its credentials on a self-hosted deployment. API-key integrations use the keys supplied in their blocks. The full table, redirect-URI format, and setup steps are in [Integrations and OAuth](/platform/self-hosting/integrations-oauth).
+
+## Access control
+
+Who may sign up and sign in — the allowlists, blocklists, `DISABLE_REGISTRATION`, `DISABLE_INVITATIONS`, `DISABLE_PUBLIC_API`, and `DISABLE_AUTH` — is documented in [Authentication](/platform/self-hosting/authentication).
+
+## Code execution
 
 | Variable | Description |
 |----------|-------------|
-| `COPILOT_API_KEY` | API key for Chat. Without it the Sim Chat block, scheduled prompt jobs, and Inbox cannot run |
-| `NEXT_PUBLIC_CHAT_DISABLED` | Set to `true` to hide the Chat module: the workspace lands on your first workflow, with no chats list, scheduled tasks, or editor Chat panel. Chat is shown when unset; `npx sim-setup` sets it for you if you skip the chat key |
-| `PII_URL` | Base URL of the Presidio service backing PII detection and redaction. The Helm chart wires it to its own `pii` Service when `pii.enabled`; on Compose point it at the PII service on your network. The default `http://localhost:5001` exists only in local development, and leaving it makes redaction fail |
-| `ADMIN_API_KEY` | Admin API key for GitOps operations and organization provisioning |
+| `SANDBOX_PROVIDER` | Remote sandbox provider: `e2b` (default) or `daytona` |
+| `E2B_ENABLED` / `E2B_API_KEY` | Enable E2B remote execution |
+| `DAYTONA_API_KEY` | Daytona API key (used when `SANDBOX_PROVIDER=daytona`) |
+| `E2B_FUNCTION_TEMPLATE_ID` | Immutable `<template>:<build-id>` ref for the Function base image. Required for E2B; a mutable tag is refused |
+| `E2B_FUNCTION_TEMPLATE_GENERATION` | Monotonic release generation printed by the same build. Required for E2B |
+| `DAYTONA_FUNCTION_SNAPSHOT_ID` | Immutable snapshot **ID** (not a name) for the Function base image. Required for Daytona |
+| `E2B_PI_TEMPLATE_ID` / `DAYTONA_PI_SNAPSHOT_ID` | The image Pi runs on. Separate from the Function base — configuring the provider and Function image alone leaves Pi failing closed |
+| `SANDBOXES_ENABLED` / `NEXT_PUBLIC_SANDBOXES_ENABLED` | Enable custom sandbox entitlement through deployment configuration where supported; see the [enterprise guide](/platform/enterprise/self-hosted) for billing-mode requirements. Neither is sufficient on its own — a provider key **and** an immutable Function base must also be configured. Set the `NEXT_PUBLIC_` twin only after the server side works; it enables nothing by itself — it reveals the Function block's Sandbox selector, and on a Compose install or source checkout `bunx sim-setup doctor` confirms it agrees with the selected provider's readiness |
+| `IVM_MAX_EXECUTIONS_PER_WORKER` | Executions before an isolated-vm worker is recycled |
+| `IVM_MAX_BROKERS_PER_EXECUTION` | Host-call brokers per execution |
+| `IVM_MAX_BROKER_ARGS_JSON_CHARS` | Max argument payload size |
+| `IVM_MAX_BROKER_RESULT_JSON_CHARS` | Max result payload size |
 
-Tracked memory, table rows, knowledge content, and workspace files require valid secret provenance before entering a model or a trusted runtime. Records with a null provenance tracking marker retain legacy compatibility.
+Plain JavaScript without imports runs in isolated-vm within Node child workers in the app container. Python, Shell, imported JavaScript, sandbox/file-path execution, and Pi require the corresponding remote provider and image configuration. See [Sandboxes](/platform/self-hosting/sandboxes) for the base-image build and [Security](/platform/self-hosting/security) for the isolation comparison.
 
-## Enterprise Features
+## Chat and PII [#chat--pii]
 
-Enterprise features are unlocked by configuration rather than billing on self-hosted deployments. One switch turns on the full set; per-feature flags below it override the switch either way.
+| Variable | Description |
+|----------|-------------|
+| `COPILOT_API_KEY` | API key for the default Sim service. Required for Chat, the Sim Chat workflow block, and Inbox operations that use that service |
+| `NEXT_PUBLIC_CHAT_DISABLED` | Set to `true` to hide the Chat module: the workspace lands on your first workflow, with no chats list or editor Chat panel. Chat is shown when unset; `bunx sim-setup` sets it for you if you skip the chat key |
+| `PII_URL` | Base URL of the Presidio service backing PII detection and redaction. The Helm chart wires it to its own `pii` Service when `pii.enabled`; on Compose point it at the PII service on your network. Local development and the Helm fallback use `http://localhost:5001`; that address works only when the service is reachable there. Point production at a running service to use redaction |
+| `ADMIN_API_KEY` | Admin API key for GitOps operations and organization provisioning |
+
+## Enterprise features
+
+On standard billing-disabled self-hosted deployments, configuration enables enterprise features. Per-feature flags override the suite switch. Billing-enabled deployments also have plan/entitlement gates; see [Self-hosted enterprise features](/platform/enterprise/self-hosted).
 
 | Variable | Description |
 |----------|-------------|
 | `ENTERPRISE_ENABLED`, `NEXT_PUBLIC_ENTERPRISE_ENABLED` | Enable the whole enterprise feature set |
 | `SSO_ENABLED`, `NEXT_PUBLIC_SSO_ENABLED` | Enable SAML and OIDC single sign-on on its own. See [Authentication](/platform/self-hosting/authentication#sso-saml-and-oidc) |
-| `SSO_SKIP_DOMAIN_VERIFICATION` | Skip the DNS challenge when an administrator clicks Verify on a domain. Off by default; self-hosted only. Trusts administrator claims for SSO and SCIM across the instance. See [Verified Domains](/platform/enterprise/verified-domains#skip-dns-verification) |
+| `SSO_SKIP_DOMAIN_VERIFICATION` | Skip the DNS challenge when an administrator clicks Verify on a domain. Off by default; self-hosted only. Trusts administrator claims for SSO and SCIM across the instance. See [Verified domains](/platform/enterprise/verified-domains#skip-dns-verification) |
 | `SCIM_ENABLED`, `NEXT_PUBLIC_SCIM_ENABLED` | Enable directory provisioning on its own. Needs SSO. See [Directory provisioning](/platform/enterprise/scim) |
 | `INSTANCE_ORG_NAME` | Name of the organization every user joins automatically at signup |
 | `INSTANCE_ORG_SLUG` | Slug for that organization (derived from the name when omitted) |
@@ -259,9 +207,9 @@ Enterprise features are unlocked by configuration rather than billing on self-ho
 
 Most enterprise features read their settings from the organization that owns a workspace, so enabling the flags alone is not enough — the deployment also needs an organization model. See the [self-hosted enterprise guide](/platform/enterprise/self-hosted) for the per-feature flags, both organization patterns, and the Admin API.
 
-## File Storage
+## File storage
 
-By default Sim writes uploads to local disk. For production, point it at AWS S3, Azure Blob, or Google Cloud Storage. See [Object Storage](/platform/self-hosting/object-storage) for the full setup, bucket layout, and IAM policy.
+By default Sim writes uploads to local disk. Neither stock production Compose nor the default Helm chart mounts the upload directory, so configure cloud storage or a persistent local layout before retaining files. See [Object storage](/platform/self-hosting/object-storage) for the full setup, bucket layout, and IAM policy.
 
 | Variable | Description |
 |----------|-------------|
@@ -276,13 +224,34 @@ By default Sim writes uploads to local disk. For production, point it at AWS S3,
 | `GCS_PROJECT_ID` | GCP project ID. Omit to infer from credentials/ADC |
 | `GCS_CREDENTIALS_JSON` | Inline service-account JSON. Omit to use Application Default Credentials (Workload Identity, `GOOGLE_APPLICATION_CREDENTIALS`) |
 
-## Email Providers
+## Email providers
 
 Configure at least one. Every configured provider stays active and is tried in order — **Resend → AWS SES → SMTP → Azure Communication Services → Gmail** — falling through only on failure. With none configured, mail is silently not sent. The variables for each provider, plus setup, verification, and troubleshooting, are in [Email](/platform/self-hosting/email).
 
+## Networking and execution limits [#networking--limits]
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `API_MAX_JSON_BODY_BYTES` | 50 MiB | Configured JSON body cap; contract-validated routes clamp it to 10 MiB, or a lower route cap |
+| `CHAT_MAX_REQUEST_BYTES` | 220 MiB | Configured body cap on the public deployed-chat endpoint; the Next.js proxy buffer also applies |
+| `WEBHOOK_MAX_REQUEST_BYTES` | 10 MiB | Max body on public webhook receiver endpoints |
+| `WORKFLOW_EXECUTION_CONCURRENCY_LIMIT` | `75` | Trigger.dev workflow task concurrency |
+| `WEBHOOK_EXECUTION_CONCURRENCY_LIMIT` | `75` | Trigger.dev webhook task concurrency |
+| `SCHEDULE_EXECUTION_CONCURRENCY_LIMIT` | `30` | Deployment-wide active scheduled executions in the default database-backed mode; Trigger.dev uses a separate task queue |
+| `RESUME_EXECUTION_CONCURRENCY_LIMIT` | `50` | Trigger.dev resume task concurrency |
+| `EGRESS_ALLOWED_HOSTS` | unset | Comma-separated hostnames outbound requests may reach on a private network. Leading wildcard allowed, e.g. `host.docker.internal,*.svc.cluster.local`. Not honored for URLs harvested from content or a third-party response, nor for an HTTP block's `proxyUrl` |
+| `EGRESS_ALLOWED_IP_RANGES` | unset | Comma-separated CIDRs or IPs outbound requests may reach on a private network, e.g. `10.0.0.0/8`. Same exclusions |
+| `ALLOW_PRIVATE_DATABASE_HOSTS` | unset | **Deprecated.** Vouches for the entire private address space, for database, cache, and mail connector hosts only. Replace it with the two settings above naming specific destinations |
+
+A malformed entry in either allowlist stops the app at startup with a message naming the setting. See [the SSRF boundary](/platform/self-hosting/security#the-ssrf-boundary) for the accepted syntax and for what the allowlist does and does not reach.
+
+Most `/api` routes also pass through Next.js Proxy, which buffers only the first 10 MiB with the current app configuration. Raising these variables or an external proxy limit does not raise that buffer. See [Request size limits](/platform/self-hosting/networking#request-size-limits) for the layers to configure.
+
 ## Limits
 
-Self-hosted deployments (billing disabled) run without plan limits: no rate limits, no execution timeouts, no table or storage caps, and no retention-based data deletion. Each limit can be opted back in individually by explicitly setting its variable.
+With `BILLING_ENABLED` disabled, hosted-plan execution rates/timeouts and table/storage quotas are not enforced unless you set their free-tier variables. Independent protocol, body-size, concurrency, and security rate limits still apply. Billing-enabled deployments enforce their plan limits. Keep `BILLING_ENABLED` and `NEXT_PUBLIC_BILLING_ENABLED` consistent so enforcement and the UI agree.
+
+Retention cleanup is separately opt-in through `DATA_RETENTION_ENABLED` or the enterprise suite. A configured retention policy still applies without billing; see [Data retention](/platform/enterprise/data-retention).
 
 | Variable | Opts in | Suggested value |
 |----------|---------|-----------------|
@@ -293,19 +262,15 @@ Self-hosted deployments (billing disabled) run without plan limits: no rate limi
 | `EXECUTION_TIMEOUT_ASYNC_FREE` | Async execution timeout (seconds) | `5400` |
 | `FREE_TABLES_LIMIT` | Max user tables per workspace | `5` |
 | `FREE_TABLE_ROWS_LIMIT` | Max rows per user table | `50000` |
-| `FREE_STORAGE_LIMIT_GB` | File storage quota (GB) | `5` |
+| `FREE_STORAGE_LIMIT_GB` | File storage quota (GiB) | `5` |
 
-<Callout type="info">
-  Without billing, every account resolves to the free tier, so only the free-tier variables apply. Setting one variable enforces only that limit — the rest stay unlimited.
-</Callout>
+Without billing, accounts resolve to the free tier for these counters. Each explicit free-tier variable enables only its corresponding limit.
 
-<Callout type="warn">
-  Neither deployment presets these. The Helm chart previously did, which enforced hosted-plan caps on self-hosted installs; chart 1.5.0 removed the presets so Compose and Kubernetes behave identically.
-</Callout>
+Current stock Compose and Helm configuration do not preset these free-tier caps. Charts before 1.5.0 did; inherited values can still reach upgraded pods.
 
-### Removing a limit you already inherited
+### Remove an inherited limit [#removing-a-limit-you-already-inherited]
 
-If a limit is still enforced after upgrading — most often a `FREE_TABLES_LIMIT` or `FREE_TABLE_ROWS_LIMIT` carried forward from a chart older than 1.5.0, or copied into your own values file — the variable is still reaching the pod. On Helm, remove it by overriding it with `null`:
+If a limit remains after upgrading, inspect the pod's configuration for inherited values, such as `FREE_TABLES_LIMIT` or `FREE_TABLE_ROWS_LIMIT` from a chart older than 1.5.0 or your own values file. On Helm, remove the key by overriding it with `null`:
 
 ```yaml
 app:
@@ -319,16 +284,32 @@ Setting the variable to an empty string does **not** remove it: the chart reads
 Null the variable in every layer that sets it. If it appears in both `app.env` and `app.envDefaults`, nulling only the `app.env` entry lets the `envDefaults` value apply again and the limit stays in force. With External Secrets, also drop the key from `externalSecrets.remoteRefs.app`, which keeps syncing it independently. Confirm what the pod will actually receive before rolling out:
 
 ```bash
-helm template sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.5 -f values.yaml | grep -A1 FREE_TABLE   # expect no output
+helm template sim oci://ghcr.io/simstudioai/charts/sim --version 1.11.8 -f values.yaml | grep -A1 FREE_TABLE   # expect no output
 ```
 
 `null` deletion has no effect under `helm upgrade --reuse-values` — pass your full values with `-f`, or use `--reset-then-reuse-values` (Helm 3.14+). If you deploy with Argo CD, put the `null` in `valueFiles` or the `values` string rather than `valuesObject`, which strips nulls. On Docker Compose, delete the line from your `.env` file.
 
+## Observability
+
+| Variable | Description |
+|----------|-------------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Auth headers, `key=value` comma-separated |
+| `OTEL_TRACES_SAMPLER_ARG` | Trace sampling ratio |
+| `OTEL_DEPLOYMENT_ENVIRONMENT` | Environment label on emitted spans |
+| `TELEMETRY_SAMPLING_RATIO` | Application-level sampling ratio |
+| `TELEMETRY_ENDPOINT` | Where anonymous telemetry is sent. Defaults to `https://telemetry.simstudio.ai/v1/traces` — point it at your own collector to keep traces internal |
+| `NEXT_TELEMETRY_DISABLED` | Set to `1` to disable anonymous telemetry entirely |
+| `GRAFANA_OTLP_ENDPOINT` / `GRAFANA_OTLP_HEADERS` / `GRAFANA_DEPLOYMENT_ENVIRONMENT` | Grafana Cloud OTLP export |
+
+See [Observability](/platform/self-hosting/observability).
+
 ## Example .env
 
-```bash
-# Core
-DATABASE_URL=postgresql://postgres:postgres@db:5432/simstudio
+```text
+# App/source-checkout example: replace placeholders before use.
+# Production Compose derives its DSN from POSTGRES_* instead.
+DATABASE_URL=postgresql://<user>:<password>@<host>:5432/simstudio?sslmode=require
 NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
 BETTER_AUTH_URL=https://sim.yourdomain.com
 
@@ -353,4 +334,10 @@ FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"
 ALLOWED_LOGIN_DOMAINS=yourdomain.com
 ```
 
-See `apps/sim/.env.example` for all options.
+This is an app/source-checkout example, not a replacement for the [Compose setup](/platform/self-hosting/docker#production-setup) or [Helm values](/platform/self-hosting/kubernetes). See `apps/sim/.env.example` for additional options.
+
+## Related docs
+
+- [Authentication](/platform/self-hosting/authentication)
+- [Verify your install](/platform/self-hosting/verify)
+- [Security](/platform/self-hosting/security)
diff --git a/apps/docs/content/docs/platform/self-hosting/index.mdx b/apps/docs/content/docs/platform/self-hosting/index.mdx
index 82b013706f9..298f024f4f9 100644
--- a/apps/docs/content/docs/platform/self-hosting/index.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/index.mdx
@@ -1,116 +1,98 @@
 ---
-title: Self-Hosting
-description: Deploy Sim on your own infrastructure
+title: Self-hosting
+description: Deploy and operate Sim on your own infrastructure
 ---
 
 import { Card, Cards } from 'fumadocs-ui/components/card'
 import { Callout } from 'fumadocs-ui/components/callout'
 
-Deploy Sim on your own infrastructure with Docker or Kubernetes.
+Run Sim on your own infrastructure with Docker Compose or Kubernetes. Both run the same app, realtime service, database migrations, and background job endpoints.
 
-## Requirements
+## Choose a deployment
 
-| Resource | Small | Standard | Production |
-|----------|-------|----------|------------|
-| CPU | 2 cores | 4 cores | 8+ cores |
-| RAM | 12 GB | 16 GB | 32+ GB |
-| Storage | 20 GB SSD | 50 GB SSD | 100+ GB SSD |
-| Docker | 20.10+ | 20.10+ | Latest |
+<Cards>
+  <Card title="Docker" href="/platform/self-hosting/docker">
+    Start a single-node installation with published containers.
+  </Card>
+  <Card title="Kubernetes" href="/platform/self-hosting/kubernetes">
+    Install the Helm chart on a cluster you operate.
+  </Card>
+  <Card title="Cloud platforms" href="/platform/self-hosting/platforms">
+    Check provider-specific requirements for Railway, a VPS, or managed Kubernetes.
+  </Card>
+</Cards>
 
-**Small**: Development, testing, single user (1-5 users)
-**Standard**: Teams (5-50 users), moderate workloads
-**Production**: Large teams (50+ users), high availability, heavy workflow execution
+Compose bundles PostgreSQL, Redis, and a scheduler. The Helm chart bundles PostgreSQL and Redis and enables scheduled jobs by default. Kubernetes also exposes replica, autoscaling, disruption-budget, secret-store, and network-policy settings; configure these for your cluster before relying on high availability. See [Reference architectures](/platform/self-hosting/reference-architectures).
 
-<Callout type="info">
-Resource requirements are driven by workflow execution (isolated-vm sandboxing), file processing (in-memory document parsing), and vector operations (pgvector). Memory is typically the constraining factor rather than CPU. The Helm chart requests 4 Gi for the app and caps it at 8 Gi; `docker-compose.prod.yml` sets only an 8 GB limit, with no reservation.
-</Callout>
+## Quick start
 
-## Quick Start
+Install Bun, Node.js 20 or newer, Docker, and Docker Compose 2.24.0 or later, then run:
 
 ```bash
-git clone https://github.com/simstudioai/sim.git && cd sim
+bunx sim-setup
+```
 
-cat > .env << EOF
-BETTER_AUTH_SECRET=$(openssl rand -hex 32)
-ENCRYPTION_KEY=$(openssl rand -hex 32)
-INTERNAL_API_SECRET=$(openssl rand -hex 32)
-API_ENCRYPTION_KEY=$(openssl rand -hex 32)
-CRON_SECRET=$(openssl rand -hex 32)
-EOF
+The wizard creates a `./sim` directory with a production Compose file and generated `.env`, including `POSTGRES_PASSWORD`. It starts published container images. Open [http://localhost:3000](http://localhost:3000).
 
-docker compose -f docker-compose.prod.yml up -d
-```
+See [Docker](/platform/self-hosting/docker) for runtime prerequisites, manual setup, and production configuration. For a cluster, use [Kubernetes](/platform/self-hosting/kubernetes).
 
-Open [http://localhost:3000](http://localhost:3000)
+## Requirements
 
-<Callout type="info">
-  The `.env` step is not optional — the compose file refuses to start without the first three rather than booting with empty values. `CRON_SECRET` is what the scheduler uses; without it the `cron` service exits with instructions and everything else still runs. See [Docker](/platform/self-hosting/docker) for the full production setup.
-</Callout>
+Use these as starting resource examples, then size the deployment for concurrent executions, file processing, vector queries, and database growth. User counts alone do not predict capacity.
 
-## Deployment Options
+| Resource | Evaluation example | Team example | Larger workload example |
+| --- | --- | --- | --- |
+| CPU | 2 cores | 4 cores | 8+ cores |
+| RAM | 12 GiB | 16 GiB | 32+ GiB |
+| Storage | 20 GiB SSD | 50 GiB SSD | 100+ GiB SSD |
 
-<Cards>
-  <Card title="Docker" href="/platform/self-hosting/docker">
-    Deploy with Docker Compose on any server
-  </Card>
-  <Card title="Kubernetes" href="/platform/self-hosting/kubernetes">
-    Deploy with Helm on Kubernetes clusters
-  </Card>
-  <Card title="Cloud Platforms" href="/platform/self-hosting/platforms">
-    Railway, DigitalOcean, AWS, Azure, GCP guides
-  </Card>
-</Cards>
+These are sizing suggestions, not enforced minimums or capacity guarantees. The Helm chart requests 4 GiB and limits the app to 8 GiB by default. Production Compose sets an 8G app memory limit with no reservation. Memory-intensive executions and parsing can require more; see [Scaling](/platform/self-hosting/scaling).
 
-### Which one to pick
+## Before production use
 
-Docker Compose and Kubernetes run the same application; what differs is the operational envelope around it, which the table below sets out. Cloud Platforms covers provider-specific notes for either. Docker Compose is the fastest way to evaluate Sim and is fine for a single-node team install; Kubernetes is the path for high availability and managed secrets.
+- Set your public origin and route `/socket.io` to the realtime service. Configure TLS before remote sign-in.
+- Retain and back up `ENCRYPTION_KEY` and `API_ENCRYPTION_KEY` with the database. Generate keys only for a new installation.
+- Configure durable [object storage](/platform/self-hosting/object-storage) or a persistent local-storage layout. The production Compose file does not mount the app's upload directory.
+- Configure [email](/platform/self-hosting/email) for invitations, verification, and password resets.
+- Verify [background jobs](/platform/self-hosting/background-jobs), including the scheduler's `CRON_SECRET`.
 
-| Capability | Docker Compose | Kubernetes (Helm) |
-|---|---|---|
-| App, realtime, migrations, Postgres, Redis | Yes | Yes |
-| Scheduled workflows and polling triggers | Yes — `cron` service | Yes — CronJobs |
-| Horizontal scaling / HA | No (single node) | Yes (`replicaCount`, HPA, PDB) |
-| Managed secrets (Vault, ESO, cloud KMS) | Manual `.env` | Yes |
-| Network policy, Pod Security Standards | Host-level only | Yes |
-| PII redaction, OpenTelemetry collector | Not bundled | Optional components |
+<Callout type="warn">
+  Recreating an app container with unmounted local uploads loses those files. Losing an encryption key makes the data encrypted with it unreadable. A database backup does not replace file storage or key backups.
+</Callout>
 
-The remaining differences are inherent to the platform — Compose has no analogue of a HorizontalPodAutoscaler or a PodDisruptionBudget. Application behavior is the same on both.
+Run [Verify your install](/platform/self-hosting/verify) before opening the deployment to your team and after upgrades or restores.
 
-## Where to go next
+## External dependencies
 
-<Cards>
-  <Card title="Integrations & OAuth" href="/platform/self-hosting/integrations-oauth">
-    Configure OAuth applications for the services you use
-  </Card>
-  <Card title="Object Storage" href="/platform/self-hosting/object-storage">
-    Required before storing anything you care about
-  </Card>
-  <Card title="Verify Your Install" href="/platform/self-hosting/verify">
-    Ten-minute smoke test across every subsystem
-  </Card>
-</Cards>
+The editor and execution engine run within your deployment. Configure these dependencies for the features you use:
+
+| Feature | Dependency |
+| --- | --- |
+| Knowledge bases | An OpenAI, Azure OpenAI, OpenRouter, or Gemini embedding key, or your own Ollama server. `KB_EMBEDDING_MODEL` selects the model (`text-embedding-3-small` by default); `EMBEDDING_OUTPUT_DIMS` selects the stored vector width. Use `ollama/<model>` and `OLLAMA_URL` for local embeddings. |
+| Agent blocks | A model provider key or a self-hosted compatible endpoint such as Ollama, vLLM, LM Studio, or LiteLLM. |
+| Chat | `COPILOT_API_KEY` for the default Sim service. Set `NEXT_PUBLIC_CHAT_DISABLED=true` to hide Chat when it is not configured. |
+| OAuth integrations | Your provider app and credentials for each OAuth service you use. API-key integrations take keys in their blocks. |
+| Remote Function or Pi execution | An E2B or Daytona provider key and the appropriate immutable image. Function and Pi use separate images. |
 
-The sidebar covers the rest: architecture, email, Redis, authentication, background jobs, networking, security, scaling, observability, and upgrades.
+Plain JavaScript without `import` or `require` runs in isolated-vm within Node child workers in the app container. Python, Shell, imported JavaScript, custom Function Sandboxes, and file-path or sandbox execution require remote sandbox configuration. See [Sandboxes](/platform/self-hosting/sandboxes).
 
-## Enterprise Features
+## Enterprise features
 
-Organizations, SSO, permission groups, audit logs, whitelabeling, session policies, data retention, and data drains all run on a self-hosted deployment with no billing or subscription. Turn the set on with:
+In a standard billing-disabled self-hosted deployment, enterprise features are enabled through configuration:
 
 ```bash
 ENTERPRISE_ENABLED=true
 NEXT_PUBLIC_ENTERPRISE_ENABLED=true
 ```
 
-Your deployment also needs an organization model for most of them to apply. The [self-hosted enterprise guide](/platform/enterprise/self-hosted) covers both patterns, the per-feature flags, and troubleshooting.
+Organizations, SSO, permission groups, audit logs, whitelabeling, session policies, retention, and data drains also need their feature-specific configuration. Most read settings from the organization that owns a workspace. Enabling the suite can enable retention processing; review the configured policy before turning it on.
 
-## External dependencies to plan for
+See [Self-hosted enterprise features](/platform/enterprise/self-hosted) for organization setup, per-feature flags, and billing-enabled differences.
 
-Sim is self-contained for the core editor and execution engine. A few features reach outside the deployment:
+## Related docs
 
-| Feature | Requires | Notes |
-|---|---|---|
-| **Knowledge bases** | An OpenAI, Azure OpenAI, or Gemini API key, or an Ollama server | Embeddings are generated by the model named in `KB_EMBEDDING_MODEL` (`text-embedding-3-small` by default). Set it to `ollama/<model>` with `OLLAMA_URL` to embed locally instead. `EMBEDDING_OUTPUT_DIMS` sets the vector width. |
-| **Agent blocks** | An API key for at least one model provider | Or a self-hosted OpenAI-compatible endpoint: Ollama, vLLM, LM Studio, or LiteLLM. |
-| **Chat module** | `COPILOT_API_KEY` from sim.ai | Set `NEXT_PUBLIC_CHAT_DISABLED=true` to hide the module instead. |
-| **OAuth integrations** | Your own OAuth app per service | See [Integrations & OAuth](/platform/self-hosting/integrations-oauth). |
-| **Remote Function / Pi execution** | Optional E2B or Daytona key, plus a Function base image | Plain JavaScript — no `import` or `require` — runs in the in-process isolated VM with nothing configured. Everything else needs both a provider key and an immutable Function base image: Python, Shell, imported JavaScript, custom Function Sandboxes, and any block that selects a sandbox or references a file path. Pi uses a separate image again, pinned with `E2B_PI_TEMPLATE_ID` or `DAYTONA_PI_SNAPSHOT_ID`. See [Sandboxes](/platform/self-hosting/sandboxes). |
+- [Environment variables](/platform/self-hosting/environment-variables)
+- [Authentication](/platform/self-hosting/authentication)
+- [Integrations and OAuth](/platform/self-hosting/integrations-oauth)
+- [Security](/platform/self-hosting/security)
+- [Upgrades](/platform/self-hosting/upgrades)
diff --git a/apps/docs/content/docs/platform/self-hosting/integrations-oauth.mdx b/apps/docs/content/docs/platform/self-hosting/integrations-oauth.mdx
index 5623dd5bd8b..8c14f95828f 100644
--- a/apps/docs/content/docs/platform/self-hosting/integrations-oauth.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/integrations-oauth.mdx
@@ -1,132 +1,283 @@
 ---
-title: Integrations & OAuth
-description: Register OAuth apps so your users can connect Slack, Google, Jira, and every other integration
+title: Integrations and OAuth
+description: Configure provider apps, callbacks, and credentials for your deployment
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
-import { FAQ } from '@/components/ui/faq'
-import { Image } from '@/components/ui/image'
+import { Tabs, Tab } from '@/components/ui/tabs'
 
-<Callout type="warn">
-  **OAuth integrations need your own provider application on a self-hosted deployment.** Configure the OAuth services your team uses; API-key integrations can instead use keys supplied in their blocks. Users will see the connector in the UI, click "Connect", and get an error from the provider until the corresponding `*_CLIENT_ID` and `*_CLIENT_SECRET` are set.
-</Callout>
+Register provider apps for the OAuth integrations your team uses. API-key blocks take member-supplied keys; service-account connections have their own configuration. Sim login providers are separate from integration connections, even when they share client credentials.
 
-You only need to register the services your team actually uses. One OAuth app covers every Sim connector that shares its credential — a single Google app serves Gmail, Drive, Sheets, Calendar, Docs, Forms, BigQuery, and more.
+## Prerequisites
 
-## How it works
+- Serve Sim at a stable public origin and set `NEXT_PUBLIC_APP_URL` and `BETTER_AUTH_URL` to match.
+- Have permission to register an app and grant the required provider permissions.
+- Use the deployment's secret store or env files for client secrets.
+- For webhook triggers, make Sim reachable from the provider's servers. Polling triggers instead require the scheduler.
 
-Each connector has a **provider ID**. When a user connects an account, Sim redirects them to the provider, and the provider redirects back to:
+Each OAuth connector has a provider ID. Its callback is:
 
-```
+```text
 https://<your-sim-domain>/api/auth/oauth2/callback/<provider-id>
 ```
 
-That URL is derived from `NEXT_PUBLIC_APP_URL`, so set it correctly before registering anything — the redirect URI you register with the provider must match byte for byte, including scheme and the absence of a trailing slash.
+Register the exact scheme, hostname, port, and path. Use no trailing slash. A provider that permits several callbacks can share one app across connectors or environments; GitHub Search's installation setup requires a separate app per deployment origin.
 
-<Callout type="info">
-  Most providers let you register several redirect URIs on one app. Register your production URL and any staging URL together so one OAuth app serves both environments.
-</Callout>
+## Set up an OAuth client [#setup]
 
-## Setup
+1. Set your public origin:
 
-<Steps>
+   ```bash
+   NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
+   BETTER_AUTH_URL=https://sim.yourdomain.com
+   ```
 
-<Step>
+2. Register the provider app and each connector callback you need. Configure provider-side APIs, permissions, consent, and distribution using the sections below.
+3. Store the matching client ID/secret and restart the app. With Compose, recreate the app container after editing `.env`; a running process does not reread credentials.
+4. Connect an account from the integration and confirm it returns to Sim with the account listed. Test an operation using that connection.
 
-### Confirm your public URL
+For Kubernetes, use the configured [secret strategy](/platform/self-hosting/kubernetes#secret-stores): inline `app.env` becomes a chart-managed Secret; an existing Secret must contain the standard env keys; ESO requires `externalSecrets.remoteRefs.app` mappings and suppresses the inline Secret. Do not commit credentials to a values file. Explicit `app.env` credentials in existing-Secret mode are inlined into pod specs.
 
-```bash
-NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
-BETTER_AUTH_URL=https://sim.yourdomain.com
-```
+When changing an organization's saved OAuth provider configuration or scopes, an organization admin updates that configuration and affected members reconnect. Changing server variables alone does not replace an organization's saved provider settings.
 
-Both must be your real public origin. If these are wrong, every OAuth round-trip fails with a redirect-URI mismatch.
+## Provider reference
 
-</Step>
+Every provider ID below uses the callback format above unless its section specifies another flow. Integration references contain operation-specific requirements and their **OAuth Scopes** sections.
 
-<Step>
+### Google
 
-### Register an app with the provider
+Use one web OAuth client for the enabled Google services. The same client variables can also provide **Sign in with Google**; register `/api/auth/callback/google` separately if you use it.
 
-In the provider's developer console, create an OAuth 2.0 application. Register the redirect URI(s) for every Sim connector you want from that provider — one line per provider ID from the tables below.
+| Environment variables | Provider IDs |
+| --- | --- |
+| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | `google-email`, `google-drive`, `google-sheets`, `google-docs`, `google-calendar`, `google-contacts`, `google-forms`, `google-tasks`, `google-meet`, `google-groups`, `google-chat`, `google-ads`, `google-bigquery`, `google-vault`, `vertex-ai` |
 
-For a Google app covering Gmail and Drive, for example, you register both:
+1. Select your project in [Google Cloud Console](https://console.cloud.google.com/). Under **APIs & Services → Library**, enable the APIs for your services. Gmail, Drive, Calendar, and Meet use **Gmail API**, **Google Drive API**, **Google Calendar API**, and **Google Meet REST API**, respectively. For native Google Sheets reads through Drive, also enable the **Google Sheets API**; see [Google's API enablement instructions](https://developers.google.com/workspace/sheets/api/quickstart/nodejs#enable_the_api).
+2. Open **Google Auth platform → Branding** and enter the app name and contact details. Under **Audience**, choose **Internal** only for your Workspace organization; otherwise choose **External** and add test users while testing.
+3. Configure **Data Access → Add or remove scopes** for external use. Sensitive/restricted scopes can require provider verification. Follow [Google's consent guidance](https://developers.google.com/workspace/guides/configure-oauth-consent).
+4. Open **Google Auth platform → Clients → Create client**, select **Web application**, and add each enabled connector's callback under **Authorized redirect URIs**. Add callbacks to an existing client if the deployment already uses one. See [Google web credentials](https://developers.google.com/workspace/guides/create-credentials#web-application).
+5. Store `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`, restart Sim, and connect each service separately. Workspace administrators may need to approve the app.
 
-```
+For example, Gmail and Drive require both callbacks:
+
+```text
 https://sim.yourdomain.com/api/auth/oauth2/callback/google-email
 https://sim.yourdomain.com/api/auth/oauth2/callback/google-drive
 ```
 
-Scopes are requested by Sim at authorization time; you generally do not need to pre-declare them, but Google and Microsoft require you to enable the corresponding APIs on the project/app first (for example Gmail API, Drive API, Calendar API).
+#### Member-account scopes
 
-Each integration page ends with an **OAuth Scopes** section listing its redirect URI, environment variables, and every scope Sim requests, for example [Gmail](/integrations/gmail#oauth-scopes). Use it for providers that make you declare scopes on the app, such as Slack, and to confirm a connected account was granted everything Sim needs.
+These are the full Google member scope sets for the Search services below. Their connections also support workflow actions, so requested scopes can be broader than Search's read-only operations. The same Google identity does not imply the same grant for another service.
 
-</Step>
+<Tabs items={['Gmail', 'Drive', 'Calendar', 'Meet']}>
+<Tab value="Gmail">
 
-<Step>
+Callback: `/api/auth/oauth2/callback/google-email`.
+
+```text
+openid
+https://www.googleapis.com/auth/userinfo.email
+https://www.googleapis.com/auth/userinfo.profile
+https://www.googleapis.com/auth/gmail.send
+https://www.googleapis.com/auth/gmail.modify
+https://www.googleapis.com/auth/gmail.labels
+```
 
-### Set the credentials
+</Tab>
+<Tab value="Drive">
 
-Add the client ID and secret to the app's environment. In Kubernetes they go under `app.env` — the chart writes every key there into a chart-managed Secret — but supply the values through External Secrets or a pre-created Secret rather than committing them to a values file:
+Callback: `/api/auth/oauth2/callback/google-drive`.
 
-```yaml
-app:
-  env:
-    GOOGLE_CLIENT_ID: "..."
-    GOOGLE_CLIENT_SECRET: "..."
-    SLACK_CLIENT_ID: "..."
-    SLACK_CLIENT_SECRET: "..."
+```text
+openid
+https://www.googleapis.com/auth/userinfo.email
+https://www.googleapis.com/auth/userinfo.profile
+https://www.googleapis.com/auth/drive.file
+https://www.googleapis.com/auth/drive
 ```
 
-Restart the app. Credentials are read at startup — a running pod will not pick up new ones.
+</Tab>
+<Tab value="Calendar">
 
-</Step>
+Callback: `/api/auth/oauth2/callback/google-calendar`.
 
-<Step>
+```text
+openid
+https://www.googleapis.com/auth/userinfo.email
+https://www.googleapis.com/auth/userinfo.profile
+https://www.googleapis.com/auth/calendar
+```
 
-### Verify
+</Tab>
+<Tab value="Meet">
 
-Open a workflow, add the integration's block, and connect an account. A successful round-trip returns you to Sim with the account listed. A redirect-URI mismatch is the failure you will hit most; compare the registered URI against `NEXT_PUBLIC_APP_URL` character by character.
+Callback: `/api/auth/oauth2/callback/google-meet`.
 
-</Step>
+```text
+openid
+https://www.googleapis.com/auth/userinfo.email
+https://www.googleapis.com/auth/userinfo.profile
+https://www.googleapis.com/auth/meetings.space.created
+https://www.googleapis.com/auth/meetings.space.readonly
+```
 
-</Steps>
+</Tab>
+</Tabs>
 
-## Provider reference
+Other Google connectors declare their current scopes in their integration reference. Google Search service-account sources use separate domain-wide delegation scopes; those do not replace each member's OAuth connection. Configure delegation using the [Gmail](/search/gmail), [Drive](/search/google-drive), and [Calendar](/search/google-calendar) source guides. Meet member Search does not require a service account.
 
-Every provider ID below maps to the redirect URI `https://<your-domain>/api/auth/oauth2/callback/<provider-id>`.
-
-### Google
+### Microsoft
 
-One OAuth client in [Google Cloud Console](https://console.cloud.google.com/apis/credentials) covers all of these. Enable the matching API for each connector you use.
+Use one [Entra app registration](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) for the enabled Microsoft connectors:
 
 | Environment variables | Provider IDs |
-|---|---|
-| `GOOGLE_CLIENT_ID`<br />`GOOGLE_CLIENT_SECRET` | `google-email`, `google-drive`, `google-sheets`, `google-docs`, `google-calendar`, `google-contacts`, `google-forms`, `google-tasks`, `google-meet`, `google-groups`, `google-chat`, `google-ads`, `google-bigquery`, `google-vault`, `vertex-ai` |
+| --- | --- |
+| `MICROSOFT_CLIENT_ID` / `MICROSOFT_CLIENT_SECRET` | `outlook`, `onedrive`, `sharepoint`, `microsoft-teams`, `microsoft-excel`, `microsoft-word`, `microsoft-planner`, `microsoft-powerbi`, `microsoft-dataverse`, `microsoft-ad`, `microsoft-intune` |
 
-The same variables also power "Sign in with Google". See [Authentication](/platform/self-hosting/authentication).
+1. Create or select the app under **Entra ID → App registrations**. Choose the account types appropriate for the connectors you will use.
+2. Under **Authentication**, register each connector callback as a **Web** redirect URI. If using Sim login, also register `/api/auth/callback/microsoft`.
+3. Under **API permissions → Add a permission**, select the resource API and its **Delegated permissions**. Configure the scopes below; grant tenant admin consent when the permission requires it. These are member connections, not application/service-principal permissions. See [Microsoft API permissions](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-configure-app-access-web-apis).
+4. Create a client secret, store its value as `MICROSOFT_CLIENT_SECRET`, and store the application client ID as `MICROSOFT_CLIENT_ID`. Restart Sim and connect each service.
 
-### Microsoft
+Every connector below requests `openid`, `profile`, `email`, and `offline_access`, plus its resource scopes:
 
-One app registration in [Entra ID](https://entra.microsoft.com) covers all of these.
+| Provider ID | Additional delegated scopes |
+| --- | --- |
+| `outlook` | `Mail.ReadWrite`, `Mail.ReadBasic`, `Mail.Read`, `Mail.Send`, `Calendars.ReadWrite` |
+| `onedrive` | `Files.Read`, `Files.ReadWrite` |
+| `sharepoint` | `Sites.Read.All`, `Sites.ReadWrite.All`, `Sites.Manage.All` |
+| `microsoft-teams` | `User.Read`, `Chat.Read`, `Chat.ReadWrite`, `Chat.ReadBasic`, `ChatMessage.Send`, `Channel.ReadBasic.All`, `ChannelMessage.Send`, `ChannelMessage.Read.All`, `ChannelMessage.ReadWrite`, `ChannelMember.Read.All`, `Group.Read.All`, `Group.ReadWrite.All`, `Team.ReadBasic.All`, `TeamMember.Read.All`, `Files.Read`, `Sites.Read.All` |
+| `microsoft-excel` | `Files.Read`, `Files.ReadWrite` |
+| `microsoft-word` | `Files.Read`, `Files.ReadWrite`, `Files.Read.All`, `Files.ReadWrite.All` |
+| `microsoft-planner` | `Group.ReadWrite.All`, `Group.Read.All`, `Tasks.ReadWrite` |
+| `microsoft-powerbi` | `https://analysis.windows.net/powerbi/api/Workspace.Read.All`, `https://analysis.windows.net/powerbi/api/Report.Read.All`, `https://analysis.windows.net/powerbi/api/Dataset.ReadWrite.All` |
+| `microsoft-dataverse` | `https://dynamics.microsoft.com/user_impersonation` |
+| `microsoft-ad` | `User.ReadWrite.All`, `Group.ReadWrite.All`, `GroupMember.ReadWrite.All`, `LicenseAssignment.Read.All`, `LicenseAssignment.ReadWrite.All`, `UserAuthenticationMethod.ReadWrite.All`, `AuditLog.Read.All`, `Application.Read.All`, `AppRoleAssignment.ReadWrite.All`, `RoleManagement.ReadWrite.Directory`, `Device.Read.All`, `Policy.Read.All` |
+| `microsoft-intune` | `DeviceManagementManagedDevices.Read.All`, `DeviceManagementConfiguration.Read.All`, `DeviceManagementManagedDevices.PrivilegedOperations.All` |
 
-| Environment variables | Provider IDs |
-|---|---|
-| `MICROSOFT_CLIENT_ID`<br />`MICROSOFT_CLIENT_SECRET` | `outlook`, `onedrive`, `sharepoint`, `microsoft-teams`, `microsoft-excel`, `microsoft-word`, `microsoft-planner`, `microsoft-powerbi`, `microsoft-dataverse`, `microsoft-ad` |
+For Power BI, use its Web callback and organizational account from the home tenant. The `https://analysis.windows.net/powerbi/api/` prefix is part of the requested resource scopes. Power BI uses a separate connection from Microsoft Graph; Credential Groups and service-principal authentication are unsupported in this version. See [Power BI](/integrations/powerbi).
 
-The same variables also power "Sign in with Microsoft".
+For Dataverse/Dynamics 365, add **Dynamics CRM → Delegated permissions → user_impersonation**. The table shows the legacy Dynamics resource scope; environment-specific Dataverse connections request that environment's resource scope. Azure AD, Intune, Teams, and Planner permissions can require tenant-admin consent. Reconnect existing accounts after adding scopes.
 
-For Power BI, register `<NEXT_PUBLIC_APP_URL>/api/auth/oauth2/callback/microsoft-powerbi` as a **Web** redirect URI. Sim requests the delegated Power BI API scopes `Workspace.Read.All`, `Report.Read.All`, and `Dataset.ReadWrite.All` with the explicit `https://analysis.windows.net/powerbi/api/` resource prefix, plus identity and offline-access scopes. Connect an organizational account from its home tenant. Power BI uses a separate connection from Microsoft Graph integrations; Credential Groups and service-principal authentication are not supported in this version. See the [Power BI integration](/integrations/powerbi) for permissions and tenant settings.
+### Atlassian
+
+Configure Confluence and Jira with their respective OAuth credentials and callbacks. A personal/member OAuth app is separate from an Atlassian service-account credential used to restrict a Search source.
+
+| Service | Environment variables | Callback |
+| --- | --- | --- |
+| Confluence | `CONFLUENCE_CLIENT_ID` / `CONFLUENCE_CLIENT_SECRET` | `/api/auth/oauth2/callback/confluence` |
+| Jira | `JIRA_CLIENT_ID` / `JIRA_CLIENT_SECRET` | `/api/auth/oauth2/callback/jira` |
+
+1. In the [Atlassian developer console](https://developer.atlassian.com/console/myapps/), create or select an **OAuth 2.0 integration**.
+2. Under **Authorization → OAuth 2.0 (3LO)**, register the callback for the service using the exact Sim origin.
+3. Under **Permissions**, add the corresponding Confluence/Jira API scopes below, including **User Identity API → read:me**. Sim requests `offline_access` for refresh tokens.
+4. Enable sharing under **Distribution** so members other than the app owner can connect.
+5. Store the service's client ID/secret from **Settings**, restart Sim, and connect from **Integrations**, selecting the intended site. After changing client/scopes, update the organization's provider configuration and reconnect affected accounts.
+
+These are the full member connection scope sets. They include workflow writes; Search itself uses read operations. Jira's list includes Service Management and Assets permissions. Service-account read scopes from Search do not replace this app configuration. See [Confluence OAuth](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/) and [Jira OAuth](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/).
+
+<Tabs items={['Confluence', 'Jira']}>
+<Tab value="Confluence">
+
+```text
+read:confluence-content.all
+read:confluence-space.summary
+read:space:confluence
+write:confluence-content
+write:confluence-space
+write:confluence-file
+read:page:confluence
+write:page:confluence
+read:comment:confluence
+write:comment:confluence
+delete:comment:confluence
+delete:attachment:confluence
+delete:page:confluence
+read:label:confluence
+write:label:confluence
+read:attachment:confluence
+write:attachment:confluence
+search:confluence
+read:me
+offline_access
+read:hierarchical-content:confluence
+read:content.metadata:confluence
+read:user:confluence
+read:confluence-user
+read:group:confluence
+read:task:confluence
+write:task:confluence
+write:space:confluence
+delete:space:confluence
+read:blogpost:confluence
+write:blogpost:confluence
+delete:blogpost:confluence
+read:content.property:confluence
+write:content.property:confluence
+read:space.property:confluence
+write:space.property:confluence
+read:space.permission:confluence
+```
+
+</Tab>
+<Tab value="Jira">
+
+```text
+read:jira-user
+read:jira-work
+write:jira-work
+read:me
+offline_access
+read:issue.vote:jira
+read:user:jira
+delete:issue:jira
+delete:comment:jira
+delete:attachment:jira
+delete:issue-worklog:jira
+delete:issue-link:jira
+read:servicedesk-request
+write:servicedesk-request
+manage:servicedesk-customer
+read:servicedesk:jira-service-management
+read:requesttype:jira-service-management
+read:request:jira-service-management
+write:request:jira-service-management
+read:request.comment:jira-service-management
+write:request.comment:jira-service-management
+read:servicedesk.customer:jira-service-management
+write:servicedesk.customer:jira-service-management
+read:organization:jira-service-management
+write:organization:jira-service-management
+read:servicedesk.organization:jira-service-management
+write:servicedesk.organization:jira-service-management
+read:queue:jira-service-management
+read:request.sla:jira-service-management
+read:request.status:jira-service-management
+write:request.status:jira-service-management
+read:request.participant:jira-service-management
+write:request.participant:jira-service-management
+read:request.approval:jira-service-management
+write:request.approval:jira-service-management
+read:cmdb-object:jira
+write:cmdb-object:jira
+delete:cmdb-object:jira
+read:cmdb-schema:jira
+read:cmdb-type:jira
+read:cmdb-attribute:jira
+```
+
+</Tab>
+</Tabs>
 
 ### GitHub Search
 
+
 Self-hosted GitHub Search uses a GitHub App for personal account connections and optional organization repository boundaries. Register your own App and configure the server variables below. Sim Cloud users use the [GitHub Search setup flow](/search/github#add-a-repository) directly.
 
 <Steps>
 <Step>
 
-#### Register the App
+#### Register the app
 
 For a team, open **Your organizations → Settings** for the organization that will own the App. For a personal App, open your account's **Settings**. Then choose **Developer settings → GitHub Apps → New GitHub App**.
 
@@ -152,9 +303,9 @@ Replace `<NEXT_PUBLIC_APP_URL>` with your configured public origin, such as `htt
 
 Authorization starts from Sim so the callback can finish the pending connection. The **Setup URL** returns installation approval to that same setup attempt. Keep **Request user authorization (OAuth) during installation** disabled: Sim starts account authorization when it is needed, before installation. See GitHub's [Setup URL guide](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/about-the-setup-url).
 
-For an existing deployment, deploy the application with the setup callback before changing the App registration. Use a separate GitHub App for each deployment origin, such as staging and production, so installation approval returns to the instance that started it. Keep the existing user authorization callback above unchanged.
+Use a separate GitHub App per deployment origin so installation approval returns to the instance that started it. Before changing an existing App registration, deploy a Sim version that serves the setup callback; retain its user authorization callback.
 
-Live Search queries GitHub's API on demand and does not need a webhook. Ordinary knowledge-base connectors and explicitly restored legacy Search use their separate polling path.
+Live Search queries GitHub on demand and does not need a webhook. Ordinary GitHub knowledge-base connectors have their own polling/indexing path.
 
 </Step>
 <Step>
@@ -163,13 +314,11 @@ Live Search queries GitHub's API on demand and does not need a webhook. Ordinary
 
 Expand **Permissions → Repository permissions**. Set **Contents**, **Issues**, and **Pull requests** to **Read-only**; leave mandatory **Metadata** at **Read-only**. Contents supports code reads; Issues and Pull requests allow the connected member’s App user token to search and read private issues and pull requests.
 
-<Image className="mx-auto h-auto w-full max-w-md" src="/static/search/github-app-repository-permissions.jpg" alt="GitHub repository permissions with Contents set to Read-only and Metadata shown as mandatory Read-only" width={768} height={929} />
 
 Expand **Account permissions** and set **Email addresses → Access: Read-only**.
 
 Expand **Organization permissions** and set **Members → Access: Read-only**. Sim uses this to verify that the person connecting an organization installation is an organization owner. Existing installations must approve this permission update; repository read access alone cannot verify ownership.
 
-<Image className="mx-auto h-auto w-full max-w-md" src="/static/search/github-app-email-permission.jpg" alt="GitHub account permissions with only Email addresses selected for Read-only access" width={768} height={929} />
 
 | Permission area | Permission | Access |
 |---|---|---|
@@ -209,7 +358,7 @@ The private key must include its PEM header, footer, and contents. Sim accepts a
 
 Keep the private key and client secret in the deployment's server configuration; organization admins select installations in Sim without entering these secrets.
 
-The live Search application needs these five variables. If a worker also indexes ordinary GitHub knowledge bases, configure the variables in that worker’s matching environment too. Updating the app’s secret store does not update a separately configured worker. Live Search does not schedule a GitHub indexing worker.
+Configure all five variables on the app. If a separate worker indexes GitHub knowledge bases, configure its matching environment too; app secret changes do not update a separate worker. Live Search does not use an indexing worker.
 
 The **Client ID** is different from the numeric **App ID**. Use credentials from **Developer settings → GitHub Apps**. `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` belong to the separate GitHub sign-in integration and remain unchanged. Search does not read `GITHUB_REPO_CLIENT_ID` or `GITHUB_REPO_CLIENT_SECRET`.
 
@@ -217,7 +366,7 @@ Keep **Expire user authorization tokens** enabled so Sim receives the refresh to
 
 Complete the installation through [the GitHub Search source setup](/search/github#add-a-repository).
 
-If you replace a deployment's GitHub App, an organization admin selects **Settings → Credential Groups → Providers → Update configurations**. This applies the deployment's current App configuration to all existing providers while preserving their option IDs. Accounts whose App configuration changed must reconnect. Then reconnect personal GitHub accounts and connect an installation of the new App. Reconnecting alone cannot update the organization's saved App configuration.
+If you replace a deployment's GitHub App, an organization admin selects **Settings → Credential Groups → Integrations → Update configurations**. This applies the deployment's current App configuration to all existing providers while preserving their option IDs. Accounts whose App configuration changed must reconnect. Then reconnect personal GitHub accounts and connect an installation of the new App. Reconnecting alone cannot update the organization's saved App configuration.
 
 </Step>
 </Steps>
@@ -226,7 +375,8 @@ If GitHub rejects `redirect_uri`, compare the App's registered callback with `NE
 
 GitHub workflow blocks and knowledge-base token connections continue to use personal access tokens.
 
-### Everything else
+### Other providers [#everything-else]
+
 
 | Service | Environment variables | Provider ID |
 |---|---|---|
@@ -255,6 +405,7 @@ GitHub workflow blocks and knowledge-base token connections continue to use pers
 | WordPress | `WORDPRESS_CLIENT_ID` / `WORDPRESS_CLIENT_SECRET` | `wordpress` |
 | LinkedIn | `LINKEDIN_CLIENT_ID` / `LINKEDIN_CLIENT_SECRET` | `linkedin` |
 | X | `X_CLIENT_ID` / `X_CLIENT_SECRET` | `x` |
+| Ramp | `RAMP_CLIENT_ID` / `RAMP_CLIENT_SECRET` | `ramp` |
 | Reddit | `REDDIT_CLIENT_ID` / `REDDIT_CLIENT_SECRET` | `reddit` |
 | Spotify | `SPOTIFY_CLIENT_ID` / `SPOTIFY_CLIENT_SECRET` | `spotify` |
 | TikTok | `TIKTOK_CLIENT_ID` / `TIKTOK_CLIENT_SECRET` | `tiktok` |
@@ -284,16 +435,16 @@ Some providers need more setup than a client ID, secret, and redirect URI:
 | Service | Configuration | Notes |
 |---|---|---|
 | **Instagram** | `INSTAGRAM_CLIENT_ID` / `INSTAGRAM_CLIENT_SECRET` | Instagram App ID/Secret from the Meta App Dashboard (Instagram → API setup with Instagram login). Redirect URI: `/api/auth/oauth2/callback/instagram`. **Publishing requires cloud object storage** — Meta fetches a public HTTPS URL, so local-disk storage will not work. |
+| **QuickBooks** | Configure client ID, client secret, environment, and optional webhook verifier token on the connection/provider configuration | Callback: `/api/auth/oauth2/callback/quickbooks`. This uses per-connection app configuration rather than deployment-wide client env variables. |
 | **Shopify** | `SHOPIFY_CLIENT_ID` / `SHOPIFY_CLIENT_SECRET` | Redirect URI: `/api/auth/oauth2/callback/shopify`. Per-shop install flow. |
 | **Trello** | `TRELLO_API_KEY` | API-key based, not OAuth 2.0. Callback: `/api/auth/trello/callback`. Add your Sim origin (`NEXT_PUBLIC_APP_URL`) to the API key's allowed origins, or Trello will not redirect back. |
 
 ## Non-OAuth integration credentials
 
+
 Many blocks authenticate with an API key the user pastes into the block, and need nothing from you.
 
-<Callout type="warn">
-  Sim also has a "hosted key" mechanism, configured with the `{PREFIX}_API_KEY_COUNT` + `{PREFIX}_API_KEY_1..N` variables below, that lets the platform supply a key so users do not have to. **The injection path is gated on the deployment being Sim's hosted platform** (`isHosted`, derived from the app hostname), so on a self-hosted instance these variables do not remove the need for users to bring their own key. Set them only if you are running a fork that has adapted that gate.
-</Callout>
+Sim also has a "hosted key" mechanism, configured with the `{PREFIX}_API_KEY_COUNT` + `{PREFIX}_API_KEY_1..N` variables below, that lets the platform supply a key so users do not have to. **The injection path is gated on the deployment being Sim's hosted platform** (`isHosted`, derived from the app hostname), so on a self-hosted instance these variables do not remove the need for users to bring their own key. Treat these as hosted-platform configuration; they do not enable platform-supplied integration keys on a standard production self-hosted instance.
 
 The variables, for reference:
 
@@ -313,6 +464,7 @@ Providers that take a `_COUNT` plus numbered keys distribute requests round-robi
 
 ## Triggers that need extra configuration
 
+
 Webhook triggers receive callbacks from the provider and must be able to verify them:
 
 | Variable | Needed for |
@@ -324,9 +476,19 @@ When enabling the native Sim Slack trigger, configure all three variables togeth
 
 Your deployment must also be reachable from the provider's servers for webhook triggers to fire — a Sim instance on a private network can use polling triggers but not webhook triggers. Polling triggers additionally require the scheduler; see [Background Jobs](/platform/self-hosting/background-jobs).
 
-<FAQ items={[
-  { question: "Do I have to register an OAuth app for every integration?", answer: "Only for OAuth integrations your team uses. API-key integrations do not require an OAuth application. If an OAuth provider's credentials are unset, its connector cannot be connected. One Google app covers 15 connectors and one Microsoft app covers 10, so most deployments need only a handful of registrations."},
-  { question: "Users get a redirect_uri_mismatch error. What is wrong?", answer: "Almost always NEXT_PUBLIC_APP_URL does not match the URI registered with the provider. Check for http vs https, a trailing slash, an apex-vs-www difference, or a port. The URI Sim sends is built from NEXT_PUBLIC_APP_URL at request time."},
-  { question: "Can I use the same OAuth app for staging and production?", answer: "Yes, if the provider allows multiple redirect URIs on one app — register both hosts. Providers that allow only one URI need a separate app per environment."},
-  { question: "Why does the Instagram integration need cloud storage?", answer: "Meta fetches media from a public HTTPS URL rather than accepting an upload, so published files must live in S3, Azure Blob, or GCS. Local-disk storage cannot serve them. Gmail attachments and other integrations do not have this constraint." },
-]} />
+## Troubleshooting
+
+| Failure | Check |
+| --- | --- |
+| Callback/redirect URI mismatch | Compare scheme, hostname, port, and path with the callback derived from `NEXT_PUBLIC_APP_URL`. |
+| Only the provider app owner can connect | Check audience/test users, app distribution, and provider approval. |
+| A new scope is missing | Configure the provider permission, update saved organization provider configuration where applicable, then reconnect the account. |
+| Instagram publishing cannot fetch media | Configure cloud object storage with a publicly reachable HTTPS media URL. This is a publishing requirement; Gmail attachments do not have the same constraint. |
+| Polling trigger stays idle | Verify the scheduler and `CRON_SECRET`; a connected OAuth account does not prove scheduling works. |
+
+## Related docs
+
+- [Authentication](/platform/self-hosting/authentication)
+- [Connected accounts](/platform/connected-accounts)
+- [Search](/search)
+- [Background jobs](/platform/self-hosting/background-jobs)
diff --git a/apps/docs/content/docs/platform/self-hosting/kubernetes.mdx b/apps/docs/content/docs/platform/self-hosting/kubernetes.mdx
index 7d2953476c8..4275b6905f7 100644
--- a/apps/docs/content/docs/platform/self-hosting/kubernetes.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/kubernetes.mdx
@@ -1,160 +1,105 @@
 ---
 title: Kubernetes
-description: Deploy Sim with Helm
+description: Install the Sim Helm chart, configure public access, and verify the release
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { FAQ } from '@/components/ui/faq'
 
-<Callout type="info">
-  The chart's own [`helm/sim/README.md`](https://github.com/simstudioai/sim/tree/main/helm/sim) is the reference for every value, and goes deeper than this page on secret strategies, network policy, PII redaction, and per-error troubleshooting. This page covers the deployment path; read that alongside it.
-</Callout>
+Deploy Sim on a Kubernetes cluster you operate. The chart bundles PostgreSQL with pgvector and Redis, runs migrations before the app starts, and enables scheduled jobs by default.
+
+The examples pin published chart `1.11.8`, whose published app version is `v0.9.17`. This is a pinned example, not a claim about the newest release. Inspect the [chart values](https://github.com/simstudioai/sim/blob/v0.9.17/helm/sim/values.yaml) or run `helm show values oci://ghcr.io/simstudioai/charts/sim --version 1.11.8` for its configuration.
 
 ## Prerequisites
 
-- Kubernetes 1.25+
-- Helm 3.8+
-- PV provisioner support (a default StorageClass supporting `ReadWriteOnce`)
-- An ingress controller, if `ingress.enabled=true`
-- `metrics-server`, if you enable autoscaling
-- **Redis** — bundled by the chart (`redis.enabled: true`). To use your own, set `app.env.REDIS_URL`: a non-empty value overrides the bundled URL and suppresses its Deployment on its own. `redis.enabled: false` is the explicit opt-out. See [Redis](/platform/self-hosting/redis)
+- A maintained Kubernetes cluster. The chart's declared compatibility minimum is 1.25.
+- Helm 3.8 or later for OCI installation.
+- A default StorageClass supporting `ReadWriteOnce` for bundled PostgreSQL.
+- An installed ingress controller if you enable ingress, plus a certificate for public TLS.
+- `metrics-server` if you enable autoscaling.
+- External Secrets Operator and a configured SecretStore/ClusterSecretStore if you choose that secret strategy.
+
+Redis is bundled by default. A non-empty `app.env.REDIS_URL` overrides its URL and suppresses the bundled Redis Deployment. `redis.enabled=false` is the explicit opt-out; supply an external URL if you need cross-replica events. See [Redis](/platform/self-hosting/redis).
 
 ## Installation
 
-The chart is published to GitHub Container Registry as an OCI artifact at
-`oci://ghcr.io/simstudioai/charts/sim`. Install it directly — no clone required.
+### 1. Choose the secret strategy
+
+| Strategy | Configuration |
+| --- | --- |
+| Inline values | The chart writes `app.env`/`realtime.env` into a shared Kubernetes Secret. Values are also stored in Helm release data; do not commit credentials to Git. |
+| Existing Secret | Set `app.secrets.existingSecret.enabled=true` and its `name`. Prepare every required key using the standard env names. There is no key remapping. |
+| External Secrets Operator (ESO) | Set `externalSecrets.enabled=true` and map keys under `externalSecrets.remoteRefs.app`. ESO supplies the Secret; the chart does not create its inline app Secret. |
+
+In existing-Secret mode, non-empty `app.env` and `realtime.env` values are inlined into pod specs. Keep secret material in the pre-created Secret. In ESO mode, every non-empty key under those env maps must also have a remote reference; the chart rejects missing mappings. Put non-secret URL/configuration values in `envDefaults` instead.
+
+### 2. Prepare new-install secrets
 
-It is also available from a classic Helm repository at `https://charts.sim.ai`
-for tooling that expects one; see [Helm repository](#helm-repository) below.
-Prefer OCI where you can, since the signature and provenance are attached to the
-OCI artifact.
+The following installation uses inline values to demonstrate a local release. For an existing release, recover and retain its current values rather than generating replacements. For a secret-store installation, store the same required values there and use the [secret-store examples](#secret-stores).
 
 ```bash
-# Generate secrets
+CHART_VERSION=1.11.8
 BETTER_AUTH_SECRET=$(openssl rand -hex 32)
 ENCRYPTION_KEY=$(openssl rand -hex 32)
 INTERNAL_API_SECRET=$(openssl rand -hex 32)
 API_ENCRYPTION_KEY=$(openssl rand -hex 32)
 CRON_SECRET=$(openssl rand -hex 32)
 POSTGRES_PASSWORD=$(openssl rand -hex 24)
-
-# Install
-helm install sim oci://ghcr.io/simstudioai/charts/sim \
-  --version 1.9.5 \
-  --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
-  --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
-  --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
-  --set app.env.API_ENCRYPTION_KEY="$API_ENCRYPTION_KEY" \
-  --set app.env.CRON_SECRET="$CRON_SECRET" \
-  --set postgresql.auth.password="$POSTGRES_PASSWORD" \
-  --namespace simstudio --create-namespace
 ```
 
-<Callout type="warn">
-  Save all six values somewhere durable before moving on. `ENCRYPTION_KEY` in particular cannot be regenerated — losing it makes workspace environment variables and stored provider keys permanently unreadable.
-
-  `API_ENCRYPTION_KEY` is optional, and the failure mode is silent: leave it unset and Sim stores user-generated API keys **in plain text**, logging one warning and nothing else. Set it at install time — it must be a 64-character hex string, which is exactly what `openssl rand -hex 32` produces — and back it up like `ENCRYPTION_KEY`.
-
-  `CRON_SECRET` is required whenever background jobs are enabled, which is the chart's default: the chart will not render without it, unless it comes from `app.secrets.existingSecret` or External Secrets — in which case the key must be present there or every cron pod fails to start. Set `cronjobs.enabled=false` instead if you deliberately want no scheduled jobs.
-</Callout>
-
-<Callout type="info">
-  This installs the chart's default image tag. For production, **pin `app`, `realtime`, and `migrations` to the same explicit release tag** — see [Upgrades](/platform/self-hosting/upgrades).
+<Callout type="error">
+  Save the secrets durably before installing. `ENCRYPTION_KEY` and `API_ENCRYPTION_KEY` must be 64-character hex strings. Losing a key makes the values encrypted with it unreadable. Without `API_ENCRYPTION_KEY`, legacy Sim API keys can be stored in plain text; the app logs a warning when its key getter is called.
 </Callout>
 
-## Helm repository
+`CRON_SECRET` is required with the default `cronjobs.enabled=true`. The chart rejects an absent inline value. With an existing Secret, the key must be present there; with ESO, it must be mapped. Set `cronjobs.enabled=false` only if you intend to run no chart-scheduled jobs.
 
-For clusters or GitOps configs that consume `helm repo add` rather than OCI:
+### 3. Install the pinned chart
 
 ```bash
-helm repo add sim https://charts.sim.ai
-helm repo update
-
-helm install sim sim/sim --version 1.9.5 --namespace simstudio --create-namespace \
+helm install sim oci://ghcr.io/simstudioai/charts/sim \
+  --version "$CHART_VERSION" \
   --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
   --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
   --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
   --set app.env.API_ENCRYPTION_KEY="$API_ENCRYPTION_KEY" \
   --set app.env.CRON_SECRET="$CRON_SECRET" \
-  --set postgresql.auth.password="$POSTGRES_PASSWORD"
+  --set postgresql.auth.password="$POSTGRES_PASSWORD" \
+  --namespace simstudio --create-namespace
 ```
 
-It serves the same chart as the OCI registry. The signature and provenance below
-apply to the OCI artifact only.
-
-## Verifying the chart
-
-Every published version is signed with Sigstore keyless signing and carries a SLSA build-provenance attestation. Both live in the registry alongside the chart, so they survive a mirror into an internal registry.
+Ingress is disabled by default. For local access, forward the app and realtime ports in separate terminals:
 
 ```bash
-cosign verify oci://ghcr.io/simstudioai/charts/sim:1.9.5 \
-  --certificate-identity-regexp '^https://github.com/simstudioai/sim/' \
-  --certificate-oidc-issuer https://token.actions.githubusercontent.com
-
-gh attestation verify oci://ghcr.io/simstudioai/charts/sim:1.9.5 --repo simstudioai/sim
+kubectl port-forward deployment/sim-app 3000:3000 -n simstudio
 ```
 
-Signing is Sigstore-only — there is no GPG `.prov` file, so `helm install --verify` does not apply.
-
-<Callout type="warn">
-  Verification requires **cosign v3.0 or newer**. Signatures use the Sigstore protobuf bundle format, which cosign v3 writes by default and cosign v2 cannot read. cosign v3.1+ auto-detects both formats.
-</Callout>
-
-## Cloud-Specific Values
-
-These are cloud-tuned **alternatives** to the generic install above — pick one path, don't run both. The commands reuse the `$BETTER_AUTH_SECRET`, `$ENCRYPTION_KEY`, `$INTERNAL_API_SECRET`, `$API_ENCRYPTION_KEY`, `$CRON_SECRET`, and `$POSTGRES_PASSWORD` variables generated in [Installation](#installation) above, so run that block's `openssl` lines first in the same shell. They use `helm upgrade --install`, so they work whether or not a release exists yet. Two caveats when converting an existing generic install rather than starting fresh: (1) **reuse the original secret values** — recover them with `helm get values sim -n simstudio` if your shell no longer has them; supplying a newly generated `ENCRYPTION_KEY` makes every previously encrypted value (workspace environment variables, stored provider keys, MCP OAuth credentials) undecryptable. (2) The cloud values rename the bundled PostgreSQL database to `simstudio`, but Postgres only applies that setting on first initialization — add `--set postgresql.auth.database=sim` to keep your existing database. If you'd rather start clean, `helm uninstall sim -n simstudio`, delete its PVCs, and run the cloud command fresh.
-
 ```bash
-# The example values files are not part of the packaged chart, so fetch the one
-# you want at a release tag — pinning the chart but reading values off a moving
-# branch would still make this command produce different deployments over time.
-SIM_RELEASE=v0.8.24
-curl -fsSLO "https://raw.githubusercontent.com/simstudioai/sim/$SIM_RELEASE/helm/sim/examples/values-aws.yaml"
-
-helm upgrade --install sim oci://ghcr.io/simstudioai/charts/sim \
-  --version 1.9.5 \
-  --values values-aws.yaml \
-  --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
-  --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
-  --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
-  --set app.env.API_ENCRYPTION_KEY="$API_ENCRYPTION_KEY" \
-  --set app.env.CRON_SECRET="$CRON_SECRET" \
-  --set postgresql.auth.password="$POSTGRES_PASSWORD" \
-  --set app.env.NEXT_PUBLIC_APP_URL="https://sim.yourdomain.com" \
-  --set app.env.BETTER_AUTH_URL="https://sim.yourdomain.com" \
-  --set app.env.NEXT_PUBLIC_SOCKET_URL="https://sim-ws.yourdomain.com" \
-  --set realtime.env.ALLOWED_ORIGINS="https://sim.yourdomain.com" \
-  --set ingress.app.host="sim.yourdomain.com" \
-  --set ingress.realtime.host="sim-ws.yourdomain.com" \
-  --namespace simstudio --create-namespace
+kubectl port-forward deployment/sim-realtime 3002:3002 -n simstudio
 ```
 
-Every one of those overrides is required. The cloud values files hardcode a placeholder domain in all six places, and overriding only `NEXT_PUBLIC_APP_URL` leaves sign-in pointed at the placeholder, realtime rejecting every socket upgrade, and the Ingress serving the wrong host.
+Open [http://localhost:3000](http://localhost:3000). For public access, complete the topology below and apply it with the same secrets or secret-store configuration.
 
-Swap the `--values` file for your cloud: `values-aws.yaml` (EKS), `values-azure.yaml` (AKS), or `values-gcp.yaml` (GKE). Everything else is identical. Keep the downloaded file in your own config repo — the `--set` overrides above cover the six placeholder domains, but anything else you tune belongs in the file.
+## Public access [#key-configuration]
 
-## Key Configuration
+Configure a public app origin, realtime routing, allowed origins, and TLS together. This same-host example belongs in `public-values.yaml`; replace the ingress class with your installed controller's class:
 
 ```yaml
-# Custom values.yaml
 app:
-  replicaCount: 2
   image:
-    tag: "v1.2.3"  # a tag from the releases page
+    tag: "v0.9.17"
   env:
     NEXT_PUBLIC_APP_URL: "https://sim.yourdomain.com"
     BETTER_AUTH_URL: "https://sim.yourdomain.com"
-    OPENAI_API_KEY: "sk-..."
-    # Only needed when redis.enabled is false — the bundled Redis is injected otherwise
-    REDIS_URL: "redis://:<password>@redis.internal:6379"
+    NEXT_PUBLIC_SOCKET_URL: "https://sim.yourdomain.com"
 
 realtime:
   image:
-    tag: "v1.2.3"  # a tag from the releases page
+    tag: "v0.9.17"
+  env:
+    ALLOWED_ORIGINS: "https://sim.yourdomain.com"
 
 migrations:
   image:
-    tag: "v1.2.3"  # a tag from the releases page
+    tag: "v0.9.17"
 
 postgresql:
   persistence:
@@ -162,40 +107,55 @@ postgresql:
 
 ingress:
   enabled: true
-  className: nginx
-  tls:
-    enabled: true
+  className: "<your-ingress-class>"
+  annotations:
+    nginx.ingress.kubernetes.io/force-ssl-redirect: null
   app:
     host: sim.yourdomain.com
+  realtime:
+    host: sim.yourdomain.com
+    paths:
+      - path: /socket.io
+        pathType: Prefix
+  tls:
+    enabled: true
+    secretName: sim-tls
 ```
 
-<Callout type="error">
-  `NEXT_PUBLIC_APP_URL` and `BETTER_AUTH_URL` must both be your real public origin. Leaving either at `localhost` breaks sign-in.
-</Callout>
-
-<Callout type="info">
-  Keys set under `app.env` land on the realtime pod too — the chart writes them into one Secret that both Deployments consume via `envFrom`. Use `realtime.env` only for keys that must differ between the two, such as `ALLOWED_ORIGINS`.
-</Callout>
+The app and realtime consume shared app env values; `ALLOWED_ORIGINS` explicitly admits the public app origin. Matching ingress hosts lets the chart route `/socket.io` before the app's `/` path. Keep app, realtime, and migrations on the same image release.
 
-<Callout type="error">
-  The chart ships Redis (`redis.enabled: true`) and injects its `REDIS_URL` into both the app and realtime Deployments, so raising `replicaCount` works out of the box. The hazard is setting `redis.enabled: false` without supplying `app.env.REDIS_URL`: cross-pod events are then dropped with no error anywhere, silently breaking live collaboration and status updates. See [Redis](/platform/self-hosting/redis) and [Scaling & HA](/platform/self-hosting/scaling).
-</Callout>
+Create `sim-tls` in `simstudio` from your certificate and private key, or configure your certificate manager to populate that Secret:
 
-See `helm/sim/values.yaml` for all options, and the chart's [README](https://github.com/simstudioai/sim/tree/main/helm/sim) for the production checklist.
+```bash
+kubectl create secret tls sim-tls -n simstudio \
+  --cert=fullchain.pem --key=privkey.pem
+```
 
-## Background jobs
+For a fresh public installation, create the namespace before creating the Secret. Configure DNS and the controller's own HTTPS redirect, upload-size, WebSocket, timeout, and streaming settings. The `null` above removes the chart's legacy nginx redirect annotation; it does not configure another controller.
 
-The chart deploys CronJobs by default, driving scheduled workflows, polling triggers, connector syncs, OAuth token cleanup, data drains, and outbox processing. They require `CRON_SECRET`; set `cronjobs.enabled=false` to deploy none.
+For a separate realtime hostname, change all three fields together:
 
-```bash
-kubectl get cronjobs -n simstudio
+```yaml
+app:
+  env:
+    NEXT_PUBLIC_SOCKET_URL: "https://sim-ws.yourdomain.com"
+ingress:
+  realtime:
+    host: sim-ws.yourdomain.com
+    paths:
+      - path: /
+        pathType: Prefix
 ```
 
-A CronJob with a stale `LAST SCHEDULE` means the corresponding feature has stopped working. See [Background Jobs](/platform/self-hosting/background-jobs).
+Keep `ALLOWED_ORIGINS` set to the app origin, and use a TLS certificate covering both hosts. App/auth URLs remain on `sim.yourdomain.com`.
+
+Apply your complete values with `helm upgrade --install`, retaining the same secrets as installation. For inline mode, repeat the secret `--set` arguments from the install command and add `-f public-values.yaml`. For secret-store mode, use a complete values file defining that strategy.
 
 ## Ingress and TLS
 
-For nginx-style ingress controllers, raise the body-size and timeout limits — Sim's defaults allow large chat attachments and long-running executions:
+The chart defaults still name `nginx` and its annotations. Kubernetes ingress-nginx retired in March 2026 and no longer receives security fixes. Use a maintained controller supported by your cluster; the chart renders Ingress objects and does not provision a controller or Gateway API resources. See the [Kubernetes retirement announcement](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/).
+
+For an existing legacy ingress-nginx deployment, these settings describe the required body-size and streaming behavior:
 
 ```yaml
 ingress:
@@ -205,14 +165,144 @@ ingress:
     nginx.ingress.kubernetes.io/proxy-buffering: "off"
 ```
 
-On GKE, the load balancer's 30-second default backend timeout closes websockets and needs a `BackendConfig`, and the `ManagedCertificate` the chart references must be created by you. Both are covered in [Networking](/platform/self-hosting/networking).
+These annotations do not apply to other controllers. On GKE, configure a `BackendConfig` timeout for long-lived WebSockets and create the `ManagedCertificate` referenced by the values. See [Networking](/platform/self-hosting/networking).
 
-## External Database
+## Secret stores
+
+### Existing Secret
+
+Prepare an app Secret containing at least `BETTER_AUTH_SECRET`, `ENCRYPTION_KEY`, `INTERNAL_API_SECRET`, `API_ENCRYPTION_KEY`, and `CRON_SECRET`, plus any provider credentials you use. For bundled PostgreSQL, prepare its password Secret too:
 
 ```yaml
+app:
+  secrets:
+    existingSecret:
+      enabled: true
+      name: sim-app-secrets
 postgresql:
-  enabled: false
+  auth:
+    existingSecret:
+      enabled: true
+      name: sim-postgresql-secret
+      passwordKey: POSTGRES_PASSWORD
+```
 
+Use the public URL configuration above without putting credentials under `app.env`. Both Deployments consume the app Secret. See the [complete existing-Secret example](https://github.com/simstudioai/sim/blob/v0.9.17/helm/sim/examples/values-existing-secret.yaml).
+
+### External Secrets Operator
+
+Populate the remote keys and create the referenced store before installing. For a same-host public installation, move URL values from `app.env` and `realtime.env` into these `envDefaults` maps, then add the ingress/TLS configuration above:
+
+```yaml
+app:
+  envDefaults:
+    NEXT_PUBLIC_APP_URL: "https://sim.yourdomain.com"
+    BETTER_AUTH_URL: "https://sim.yourdomain.com"
+    NEXT_PUBLIC_SOCKET_URL: "https://sim.yourdomain.com"
+realtime:
+  envDefaults:
+    NEXT_PUBLIC_APP_URL: "https://sim.yourdomain.com"
+    BETTER_AUTH_URL: "https://sim.yourdomain.com"
+    ALLOWED_ORIGINS: "https://sim.yourdomain.com"
+externalSecrets:
+  enabled: true
+  apiVersion: "v1"
+  secretStoreRef:
+    name: sim-secret-store
+    kind: ClusterSecretStore
+  remoteRefs:
+    app:
+      BETTER_AUTH_SECRET: "sim/app/better-auth-secret"
+      ENCRYPTION_KEY: "sim/app/encryption-key"
+      INTERNAL_API_SECRET: "sim/app/internal-api-secret"
+      API_ENCRYPTION_KEY: "sim/app/api-encryption-key"
+      CRON_SECRET: "sim/app/cron-secret"
+    postgresql:
+      password: "sim/postgresql/password"
+```
+
+Map additional credentials, such as `RESEND_API_KEY`, under `remoteRefs.app`. Remote value changes do not themselves restart processes; recreate the affected pods after credentials change. See the [complete ESO example](https://github.com/simstudioai/sim/blob/v0.9.17/helm/sim/examples/values-external-secrets.yaml).
+
+Configure model provider keys, such as `OPENAI_API_KEY`, through the same selected secret strategy. A healthy release does not establish that a model provider is configured.
+
+## Cloud-specific values
+
+Use a cloud example as a starting file, not a complete install configuration. Fetch it from the release corresponding to the pinned chart example:
+
+```bash
+SIM_RELEASE=v0.9.17
+curl -fsSLO "https://raw.githubusercontent.com/simstudioai/sim/$SIM_RELEASE/helm/sim/examples/values-aws.yaml"
+```
+
+Choose `values-aws.yaml` for EKS, `values-azure.yaml` for AKS, or `values-gcp.yaml` for GKE. Review and replace provider-specific fields before installation:
+
+| Example | Required review |
+| --- | --- |
+| AWS | StorageClass, region/buckets, IAM role ARN, ACM certificate ARN, ALB controller, and network policy. |
+| Azure | StorageClass, Blob account/containers/credentials, certificate issuer, and legacy ingress-nginx settings. |
+| GCP | Project/buckets, Workload Identity, static IP, ManagedCertificate, backend timeout, and network policy. |
+
+Each file also has six placeholder public-address values. In inline mode, reuse your saved secrets and override those addresses together:
+
+```bash
+helm upgrade --install sim oci://ghcr.io/simstudioai/charts/sim \
+  --version 1.11.8 \
+  --values values-aws.yaml \
+  --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
+  --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
+  --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
+  --set app.env.API_ENCRYPTION_KEY="$API_ENCRYPTION_KEY" \
+  --set app.env.CRON_SECRET="$CRON_SECRET" \
+  --set postgresql.auth.password="$POSTGRES_PASSWORD" \
+  --set app.env.NEXT_PUBLIC_APP_URL="https://sim.yourdomain.com" \
+  --set app.env.BETTER_AUTH_URL="https://sim.yourdomain.com" \
+  --set app.env.NEXT_PUBLIC_SOCKET_URL="https://sim-ws.yourdomain.com" \
+  --set realtime.env.ALLOWED_ORIGINS="https://sim.yourdomain.com" \
+  --set ingress.app.host="sim.yourdomain.com" \
+  --set ingress.realtime.host="sim-ws.yourdomain.com" \
+  --namespace simstudio --create-namespace
+```
+
+Replace the file name for another cloud and keep your reviewed file in your configuration repository. With ESO, use its env/default and remote-reference rules rather than the inline-secret arguments.
+
+<Callout type="warn">
+  When converting an existing generic release, retain its original encryption secrets and database name. The generic chart initializes database `sim`; cloud examples use `simstudio`, and changing the value does not rename an existing database. Add `--set postgresql.auth.database=sim` when retaining that database. `helm uninstall` does not delete StatefulSet PVCs; deleting them to start fresh erases the stored data.
+</Callout>
+
+For an inline installation, `helm get values sim -n simstudio` can recover saved values. For external secret modes, use the existing secret store. Do not generate new encryption keys during conversion.
+
+## Verify the release
+
+```bash
+kubectl get pods -n simstudio
+kubectl logs -l app.kubernetes.io/component=app -n simstudio --tail=100
+kubectl get cronjobs -n simstudio
+curl -fsS https://sim.yourdomain.com/api/health
+```
+
+Scheduled jobs cover workflows, polling triggers, connector syncs, token cleanup, data drains, and outbox processing. Inspect failed job pods and endpoint responses, then run [Verify your install](/platform/self-hosting/verify).
+
+## Verify the chart [#verifying-the-chart]
+
+Published charts have Sigstore keyless signatures and build-provenance attestations in the source registry. Use cosign 3.0 or later for the bundle format; 3.1+ auto-detects old and new formats:
+
+```bash
+cosign verify ghcr.io/simstudioai/charts/sim:1.11.8 \
+  --certificate-identity-regexp '^https://github.com/simstudioai/sim/' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+
+gh attestation verify oci://ghcr.io/simstudioai/charts/sim:1.11.8 --repo simstudioai/sim
+```
+
+There is no GPG `.prov` file; `helm install --verify` does not verify these signatures. When mirroring charts, copy the associated signature and attestation artifacts as well as the chart. A chart-only copy does not preserve verification material.
+
+## External database
+
+Configure a database with pgvector and the required migration permissions. The chart constructs the shared app/realtime/migration DSN from:
+
+```yaml
+postgresql:
+  enabled: false
 externalDatabase:
   enabled: true
   host: "your-db-host"
@@ -223,22 +313,38 @@ externalDatabase:
   sslMode: "require"
 ```
 
-## Commands
+Replace the credentials or supply the chart's external-database Secret strategy. Inline passwords must use letters, digits, `.`, `_`, or `-` to pass chart DSN validation. See [Cloud platforms](/platform/self-hosting/platforms#managed-postgresql) and [Upgrades](/platform/self-hosting/upgrades) for extensions and direct migration connections.
+
+## Helm repository
+
+For tooling that requires a classic repository:
 
 ```bash
-# Port forward for local access
-kubectl port-forward deployment/sim-app 3000:3000 -n simstudio
+helm repo add sim https://charts.sim.ai
+helm repo update
+```
 
-# View logs
-kubectl logs -l app.kubernetes.io/component=app -n simstudio --tail=100
+Use `sim/sim` in place of the OCI URL in the install/upgrade command, preserving the version, complete values, namespace, and secret configuration. Signature/provenance verification above applies to the OCI artifact.
+
+## Operator commands [#commands]
+
+Upgrade with the full configuration and an explicitly chosen chart version:
+
+```bash
+helm upgrade sim oci://ghcr.io/simstudioai/charts/sim \
+  --version 1.11.8 --namespace simstudio --values values.yaml
+```
+
+Retain the original secrets. See [Upgrades](/platform/self-hosting/upgrades) before changing the target version.
 
-# Upgrade (always pin the target chart version)
-helm upgrade sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.5 --namespace simstudio
+Uninstall removes the release but leaves PostgreSQL StatefulSet PVCs:
 
-# Uninstall
+```bash
 helm uninstall sim --namespace simstudio
 ```
 
-<FAQ items={[
-  { question: "How do I manage secrets securely in Kubernetes?", answer: "The Helm chart supports pre-existing Kubernetes secrets via app.secrets.existingSecret. Set enabled to true and provide the secret name. This integrates with External Secrets Operator, HashiCorp Vault, Azure Key Vault, and similar tools. The secret must use the standard key names (BETTER_AUTH_SECRET, ENCRYPTION_KEY, INTERNAL_API_SECRET, API_ENCRYPTION_KEY, CRON_SECRET, ...) — it is consumed wholesale, so key remapping is not supported."},
-]} />
+## Related docs
+
+- [Environment variables](/platform/self-hosting/environment-variables)
+- [Object storage](/platform/self-hosting/object-storage)
+- [Scaling and high availability](/platform/self-hosting/scaling)
diff --git a/apps/docs/content/docs/platform/self-hosting/meta.json b/apps/docs/content/docs/platform/self-hosting/meta.json
index 856966682e4..5dd14c57752 100644
--- a/apps/docs/content/docs/platform/self-hosting/meta.json
+++ b/apps/docs/content/docs/platform/self-hosting/meta.json
@@ -1,5 +1,5 @@
 {
-  "title": "Self-Hosting",
+  "title": "Self-hosting",
   "pages": [
     "architecture",
     "---Install---",
@@ -9,15 +9,15 @@
     "platforms",
     "---Configure---",
     "environment-variables",
+    "authentication",
+    "integrations-oauth",
     "object-storage",
     "email",
     "redis",
-    "integrations-oauth",
-    "authentication",
+    "sandboxes",
     "background-jobs",
     "networking",
     "security",
-    "sandboxes",
     "verify",
     "desktop",
     "---Operate---",
diff --git a/apps/docs/content/docs/platform/self-hosting/networking.mdx b/apps/docs/content/docs/platform/self-hosting/networking.mdx
index 4502ea88979..05f4496b6de 100644
--- a/apps/docs/content/docs/platform/self-hosting/networking.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/networking.mdx
@@ -1,12 +1,12 @@
 ---
 title: Networking
-description: Reverse proxies, TLS, websockets, timeouts, and request size limits
+description: Reverse proxies, TLS, WebSockets, timeouts, and request size limits
 ---
 
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 import { Callout } from 'fumadocs-ui/components/callout'
 
-Sim has three traffic patterns that trip up default proxy configurations: **long-lived websockets**, **server-sent event streams**, and **large uploads**. Most "it works locally but not in production" reports come from one of the three.
+Configure ingress for long-lived WebSockets, server-sent event (SSE) streams, and large request bodies. Both the app and realtime service must be reachable from browsers.
 
 ## Topology
 
@@ -15,7 +15,7 @@ Two services need to be reachable. You can put them on one hostname or two.
 <Tabs items={['Single hostname', 'Two hostnames']}>
   <Tab value="Single hostname">
 
-Simplest. Route `/socket.io` to realtime and everything else to the app.
+Route `/socket.io` to realtime and everything else to the app.
 
 ```
 sim.yourdomain.com/           → app:3000
@@ -27,7 +27,7 @@ sim.yourdomain.com/socket.io  → realtime:3002
   </Tab>
   <Tab value="Two hostnames">
 
-Required by ingress controllers that cannot cleanly split paths across backends, and preferred on GKE's built-in load balancer.
+Use separate hostnames when your ingress setup cannot split paths across backends. GKE's example values use this layout.
 
 ```
 sim.yourdomain.com     → app:3000
@@ -55,52 +55,12 @@ Both hostnames need DNS records and TLS certificates.
   </Tab>
 </Tabs>
 
-## Second ingress and `copilot` routing
-
-The chart renders a second, independent Ingress from `ingressInternal` — its own class, hosts, TLS secret, and rules. Use it to publish the same Deployments on an internal-only hostname alongside the public one.
-
-```yaml
-ingressInternal:
-  enabled: true
-  className: nginx-internal
-  app:
-    host: sim.internal.example.com
-    paths:
-      - path: /
-        pathType: Prefix
-  realtime:
-    host: sim.internal.example.com
-    paths:
-      - path: /socket.io
-        pathType: Prefix
-  tls:
-    enabled: true
-    secretName: sim-internal-tls
-```
-
-When `realtime.host` equals `app.host`, the realtime paths are folded into the app host's rule ahead of the catch-all — which is why `/socket.io` must come first. Give realtime a different host and it gets a rule of its own.
-
-Both `ingress` and `ingressInternal` accept an optional `copilot` block, commented out in `values.yaml` because the `copilot` service is off by default. It follows the same host-sharing rule:
-
-```yaml
-# The route renders only when the service itself is enabled.
-copilot:
-  enabled: true
-
-ingress:
-  copilot:
-    host: sim.yourdomain.com
-    paths:
-      - path: /copilot
-        pathType: Prefix
-```
-
 ## Reverse proxy configuration
 
 <Tabs items={['Caddy', 'Nginx', 'Traefik']}>
   <Tab value="Caddy">
 
-Caddy handles certificates, websockets, and streaming correctly by default.
+Caddy handles certificates, WebSockets, and streaming correctly by default.
 
 ```
 sim.yourdomain.com {
@@ -130,7 +90,7 @@ server {
     listen 443 ssl http2;
     server_name sim.yourdomain.com;
 
-    # Large file uploads (chat attachments can reach ~220 MB)
+    # Clear the configured deployed-chat cap at this proxy layer.
     client_max_body_size 250M;
 
     location / {
@@ -167,7 +127,7 @@ server {
 }
 ```
 
-For ingress-nginx, the equivalents are annotations:
+For an existing **ingress-nginx** deployment, the equivalent annotations are below. The community controller [retired in March 2026](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/) and no longer receives security updates. For a new deployment, use a maintained controller supported by your cluster and apply that controller's equivalent settings. This retirement does not apply to the standalone Nginx example above.
 
 ```yaml
 ingress:
@@ -211,7 +171,7 @@ Traefik streams responses by default and needs no buffering override.
 ### GKE (GCE ingress)
 
 <Callout type="warn">
-  The GCE load balancer defaults to a **30-second backend timeout**, which closes every websocket every 30 seconds. Clients reconnect, so this degrades rather than breaks — but collaboration feels unreliable and reconnect storms add load. Fix it with a `BackendConfig` on the realtime Service.
+  The GCE load balancer defaults to a **30-second backend timeout**, which closes every WebSocket every 30 seconds. Clients reconnect, but repeated disconnects interrupt collaboration and add reconnect load. Fix it with a `BackendConfig` on the realtime Service.
 </Callout>
 
 ```yaml
@@ -229,8 +189,8 @@ spec:
 Then annotate the realtime Service so the load balancer picks it up. The chart renders no annotations on any Service, and `realtime.service` accepts only `type`, `port`, and `targetPort` — an annotations key there is silently dropped. Annotate the Service directly:
 
 ```bash
-kubectl annotate service -n <namespace> \
-  -l app.kubernetes.io/instance=<release>,app.kubernetes.io/component=realtime \
+kubectl annotate service -n '<namespace>' \
+  -l 'app.kubernetes.io/instance=<release>,app.kubernetes.io/component=realtime' \
   cloud.google.com/backend-config='{"default": "sim-realtime-backendconfig"}'
 ```
 
@@ -252,8 +212,9 @@ spec:
 
 ```yaml
 ingress:
-  className: gce
+  className: ""
   annotations:
+    kubernetes.io/ingress.class: "gce"
     kubernetes.io/ingress.global-static-ip-name: "sim-ip"
     networking.gke.io/managed-certificates: "simstudio-ssl-cert"
     kubernetes.io/ingress.allow-http: "false"
@@ -263,7 +224,7 @@ ingress:
     enabled: false
 ```
 
-The certificate provisions once DNS resolves, typically 15–30 minutes after the first deploy.
+GKE requires the `kubernetes.io/ingress.class: gce` annotation; it does not use `ingressClassName` for this controller. Certificate and load-balancer provisioning can take an hour or more. Check `kubectl describe managedcertificate -n simstudio simstudio-ssl-cert` for `CertificateStatus: Active`. See [Google's secure Ingress guide](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/secure-traffic-management).
 
 ### AWS (ALB ingress)
 
@@ -278,37 +239,35 @@ ingress:
     alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=3600
 ```
 
-The ALB's default 60-second idle timeout also closes websockets. Raise it as shown.
+ALB defaults to a 60-second **idle** timeout. Raise it for connections that can remain idle that long; it is not a fixed lifetime for WebSockets exchanging heartbeats. See [ALB attributes](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/edit-load-balancer-attributes.html).
 
-### Azure (Application Gateway / NGINX)
+### Azure (Application Gateway)
 
-Application Gateway's default request timeout is 30 seconds; raise it in the backend HTTP setting. Many AKS deployments use ingress-nginx instead — see the Nginx tab above.
+Application Gateway's backend request timeout defaults to **20 seconds**; raise it for long-running responses. This differs from connection idle timeout. See [Azure backend settings](https://learn.microsoft.com/en-us/azure/application-gateway/configuration-http-settings). For another AKS ingress controller, configure its corresponding stream, body-size, and timeout settings.
 
 ## Request size limits
 
-Sim enforces its own limits in addition to whatever your proxy allows. The proxy limit must be **at least** as large as the app limit, or the proxy rejects the request before Sim ever sees it.
+Requests must fit every layer: your reverse proxy, Next.js Proxy, and the route's body cap. Raising one layer does not raise the others.
 
 | Variable | Default | Applies to |
 |---|---|---|
-| `API_MAX_JSON_BODY_BYTES` | 50 MB | Contract-validated API routes |
-| `CHAT_MAX_REQUEST_BYTES` | 220 MB | The public deployed-chat endpoint (covers ~15 base64 file attachments) |
-| `WEBHOOK_MAX_REQUEST_BYTES` | 10 MB | Public webhook receiver endpoints |
+| `API_MAX_JSON_BODY_BYTES` | 50 MiB | Configured cap; contract-validated API routes clamp it to 10 MiB, or a lower route cap |
+| `CHAT_MAX_REQUEST_BYTES` | 220 MiB | Configured cap for the public deployed-chat endpoint |
+| `WEBHOOK_MAX_REQUEST_BYTES` | 10 MiB | Public webhook receiver endpoints |
 
-A proxy body limit of 250 MB accommodates all three defaults. If you lower the app limits, you can lower the proxy limit to match.
+A reverse-proxy limit of at least 250 MB clears these configured defaults; use the syntax and units your proxy accepts. You can lower it to match smaller app limits.
 
-<Callout type="info">
-  **With object storage configured**, regular file uploads do not flow through the proxy — the browser `PUT`s them directly to the bucket using a presigned URL, so the proxy limits matter only for chat attachments, API payloads, and webhook bodies. On the default local-disk storage there is no presigned path and every upload goes through the proxy, so its body limit applies to all of them.
-</Callout>
+Most `/api` requests also pass through Next.js Proxy. The current app configuration leaves its `proxyClientMaxBodySize` at 10 MiB. Larger bodies are truncated to that buffer rather than automatically rejected by Next.js; the route may then fail to parse them. Receiving larger custom-route bodies requires changing `experimental.proxyClientMaxBodySize` in the app build, which increases per-request memory use. The shared JSON parser separately clamps contract-validated bodies to 10 MiB, so raising the Next.js buffer alone does not increase their limit. See [Next.js proxy body buffering](https://nextjs.org/docs/app/api-reference/config/next-config-js/proxyClientMaxBodySize).
+
+**With object storage configured**, regular file uploads do not flow through the proxy — the browser `PUT`s them directly to the bucket using a presigned URL, so the proxy limits matter only for chat attachments, API payloads, and webhook bodies. On the default local-disk storage there is no presigned path and every upload goes through the proxy, so its body limit applies to all of them.
 
 ## Outbound connectivity
 
 The app makes outbound calls to model providers, integration APIs, your email provider, object storage, and your telemetry backend. Whether `HTTP_PROXY` / `HTTPS_PROXY` apply depends on which of those paths a call takes — there is no single answer, and no global setting that covers all of them.
 
-The server runs on Bun, and Bun's native `fetch` honors `$HTTP_PROXY`, `$HTTPS_PROXY`, and `$NO_PROXY`. Sim installs no global dispatcher, so every call that goes through the default `fetch` is proxied. The rest either build their own HTTP agent or speak a non-HTTP protocol.
+The server runs on Bun, and Bun's native `fetch` honors `$HTTP_PROXY`, `$HTTPS_PROXY`, and `$NO_PROXY`. Sim installs no global dispatcher. Default `fetch` uses the configured proxy unless `NO_PROXY` excludes the destination. The rest either build their own HTTP agent or speak a non-HTTP protocol.
 
-<Callout type="warn">
-  This depends on the runtime. The published images run Bun. If you build the standalone output and run it under Node instead, Node ignores these variables unless started with `NODE_USE_ENV_PROXY=1` (Node 22.21+ / 24.5+), and the `fetch`-based "Yes" rows stop being proxied — model providers, Resend, Gmail sending, the desktop update feed, and the telemetry relay. The Azure Blob, GCS and Azure Communication Services rows still hold: those SDKs read the proxy variables through their own agents rather than through `fetch`.
-</Callout>
+This depends on the runtime. The published images run Bun. If you build the standalone output and run it under Node instead, Node ignores these variables unless started with `NODE_USE_ENV_PROXY=1` (Node 22.21+ / 24.5+), and the `fetch`-based "Yes" rows stop being proxied — model providers, Resend, Gmail sending, the desktop update feed, and the telemetry relay. The Azure Blob, GCS and Azure Communication Services rows still hold: those SDKs read the proxy variables through their own agents rather than through `fetch`. See [Bun fetch](https://bun.sh/docs/runtime/networking/fetch) and [Node proxy configuration](https://nodejs.org/learn/http/enterprise-network-configuration).
 
 | Outbound path | Honors `HTTP_PROXY` / `HTTPS_PROXY` |
 |---|---|
@@ -327,10 +286,11 @@ The server runs on Bun, and Bun's native `fetch` honors `$HTTP_PROXY`, `$HTTPS_P
 
 The practical consequence: a mandatory-egress-proxy environment can route most LLM traffic, Resend mail, and Azure/GCS storage through the proxy, but guarded integration calls, S3, Bedrock, SMTP, telemetry, and datastore traffic still need a transparent proxy or NAT-based egress.
 
-<Callout type="info">
-  Set `NO_PROXY` for every destination that is not on the public internet, not just model endpoints. The app reaches the realtime server (`SOCKET_SERVER_URL`), the Presidio PII service (`PII_URL`), and itself (`INTERNAL_API_BASE_URL`) over the same default `fetch`, alongside self-hosted Ollama, LiteLLM, and vLLM — so a proxy that cannot reach your internal network breaks live updates and PII redaction, not only inference.
+### Internal destinations and `NO_PROXY`
 
-  Set it in the application environment, not your shell — under `app.env` on Helm, or the service's `environment:` on Compose. On Helm the suffixes alone are not enough: the chart wires `SOCKET_SERVER_URL`, `PII_URL`, and `OLLAMA_URL` to bare Service names, which no domain suffix matches. Add those names too — `helm template` prints the rendered ones, and the prefix is the release name unless it already contains `sim`, in which case it is the release name alone:
+Set `NO_PROXY` for every destination that is not on the public internet, not just model endpoints. The app reaches the realtime server (`SOCKET_SERVER_URL`), the Presidio PII service (`PII_URL`), and itself (`INTERNAL_API_BASE_URL`) over the same default `fetch`, alongside self-hosted Ollama, LiteLLM, and vLLM — so a proxy that cannot reach your internal network breaks live updates and PII redaction, not only inference.
+
+Set it in the application environment, not your shell — under `app.env` on Helm, or the service's `environment:` on Compose. On Helm the suffixes alone are not enough: the chart wires `SOCKET_SERVER_URL`, `PII_URL`, and `OLLAMA_URL` to bare Service names, which no domain suffix matches. Add those names too — `helm template` prints the rendered ones, and the prefix is the release name unless it already contains `sim`, in which case it is the release name alone:
 
   ```yaml
   # Helm — for a release named `acme`
@@ -347,12 +307,56 @@ The practical consequence: a mandatory-egress-proxy environment can route most L
         # Add any internal model service you run: ollama, litellm, vllm.
         - NO_PROXY=localhost,127.0.0.1,simstudio,realtime,ollama
   ```
-</Callout>
 
-### The per-request escape hatch
+### Per-request proxy
 
 The HTTP block's `proxyUrl` is honored per request by the SSRF guard, which builds a proxy agent for that call instead of pinning the target IP. It applies only to that path — connectors, content fetches, and MCP calls take a different guarded transport with no per-request proxy option.
 
 <Callout type="warn">
   `proxyUrl` must be an `http://` URL **and** must resolve to a public address. The guard validates the proxy host under a dedicated `proxy` profile that has no operator allowlist, so `EGRESS_ALLOWED_HOSTS` and `EGRESS_ALLOWED_IP_RANGES` do not reach it. A corporate proxy on an RFC 1918 address is refused even when that range is allowlisted for everything else. See [Security](/platform/self-hosting/security#the-ssrf-boundary).
 </Callout>
+
+## Additional ingress and Chat service routing
+
+The chart renders a second, independent Ingress from `ingressInternal` — its own class, hosts, TLS secret, and rules. Use it to expose the same Deployments on an internal-only hostname alongside the public one. Replace the example class with your controller's configured class.
+
+```yaml
+ingressInternal:
+  enabled: true
+  className: "your-internal-ingress-class"
+  app:
+    host: sim.internal.example.com
+    paths:
+      - path: /
+        pathType: Prefix
+  realtime:
+    host: sim.internal.example.com
+    paths:
+      - path: /socket.io
+        pathType: Prefix
+  tls:
+    enabled: true
+    secretName: sim-internal-tls
+```
+
+When `realtime.host` equals `app.host`, the realtime paths are folded into the app host's rule ahead of the catch-all — which is why `/socket.io` must come first. Give realtime a different host and it gets a rule of its own.
+
+Both `ingress` and `ingressInternal` accept an optional `copilot` block, commented out in `values.yaml` because the `copilot` service is off by default. It follows the same host-sharing rule:
+
+```yaml
+# The route renders only when the service itself is enabled.
+copilot:
+  enabled: true
+
+ingress:
+  copilot:
+    host: sim.yourdomain.com
+    paths:
+      - path: /copilot
+        pathType: Prefix
+```
+
+## Related docs
+
+- [Security and hardening](/platform/self-hosting/security)
+- [Object storage](/platform/self-hosting/object-storage)
diff --git a/apps/docs/content/docs/platform/self-hosting/object-storage.mdx b/apps/docs/content/docs/platform/self-hosting/object-storage.mdx
index 4509bdfdeca..ac5319b8de6 100644
--- a/apps/docs/content/docs/platform/self-hosting/object-storage.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/object-storage.mdx
@@ -1,13 +1,13 @@
 ---
-title: Object Storage
+title: Object storage
 description: Configure where Sim stores uploaded files — local disk, AWS S3, Azure Blob, or Google Cloud Storage
 ---
 
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 
-Sim stores every uploaded file — knowledge base documents, chat attachments, execution outputs, profile pictures, and more — in object storage. Four backends are supported:
+Configure file storage before uploading durable files or adding app replicas. Sim supports local disk, AWS S3, Azure Blob Storage, and Google Cloud Storage (GCS).
 
 | Backend | When to use |
 |---------|-------------|
@@ -24,14 +24,14 @@ Sim stores every uploaded file — knowledge base documents, chat attachments, e
 
 Set `STORAGE_PROVIDER` to `local`, `s3`, `azure`, or `gcs` to select a backend explicitly. When it is unset, Sim infers the backend from the configured environment variables in this order:
 
-1. **Azure Blob** — used if `AZURE_STORAGE_CONTAINER_NAME` is set **and** either (`AZURE_ACCOUNT_NAME` + `AZURE_ACCOUNT_KEY`) or `AZURE_CONNECTION_STRING` is set.
+1. **Azure Blob Storage** — used if `AZURE_STORAGE_CONTAINER_NAME` is set **and** either (`AZURE_ACCOUNT_NAME` + `AZURE_ACCOUNT_KEY`) or `AZURE_CONNECTION_STRING` is set.
 2. **AWS S3** — used if `S3_BUCKET_NAME` **and** `AWS_REGION` are set (and Azure is not configured).
 3. **Google Cloud Storage** — used if `GCS_BUCKET_NAME` is set (and neither Azure nor S3 is configured).
-4. **Local disk** — used only when no cloud backend has been activated. Setting any of a backend's keys activates it, including a dedicated bucket, `S3_ENDPOINT`, or an Azure credential — so a half-configured backend fails at startup rather than quietly falling back here.
+4. **Local disk** — the fallback when no cloud backend is activated. Azure activates from its main container or credentials; S3 activates from any of its bucket names or `S3_ENDPOINT`; GCS activates from `GCS_BUCKET_NAME`. Dedicated Azure container names or GCS bucket names alone do not activate those providers.
 
 If `STORAGE_PROVIDER` is unset, Sim uses the first backend whose configuration is complete, in that order. An explicit `STORAGE_PROVIDER` takes precedence and must be valid and complete.
 
-A partially configured backend is skipped, so a fully configured one later in the order still wins. A backend whose values are present but malformed is different: it stops startup immediately, and a later fully configured one does not take over. What it never does is fall back to local disk: if no other backend is complete, startup fails with `File storage is partially or incorrectly configured`. `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are checked as a pair — set both or neither.
+A partially configured backend is skipped, so a fully configured one later in the order still wins. A backend whose values are present but malformed is different: it stops startup immediately, and a later fully configured one does not take over. An activated but incomplete backend does not fall back to local disk: if no other backend is complete, startup fails with `File storage is partially or incorrectly configured`. `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are checked as a pair — set both or neither.
 
 ## Set up AWS S3
 
@@ -53,18 +53,20 @@ export SIM_BUCKETS="workspace-files knowledge-base execution-files chat-files
 
 # Create buckets (names must be globally unique — prefix with your org)
 for name in ${SIM_BUCKETS:?run the export above first}; do
-  aws s3api create-bucket \
-    --bucket "myorg-sim-$name" \
-    --region "$AWS_REGION" \
-    --create-bucket-configuration LocationConstraint="$AWS_REGION"
+  if [ "$AWS_REGION" = "us-east-1" ]; then
+    aws s3api create-bucket --bucket "myorg-sim-$name" --region "$AWS_REGION"
+  else
+    aws s3api create-bucket \
+      --bucket "myorg-sim-$name" \
+      --region "$AWS_REGION" \
+      --create-bucket-configuration LocationConstraint="$AWS_REGION"
+  fi
 done
 ```
 
-<Callout type="info">
-  In `us-east-1`, omit the `--create-bucket-configuration` flag — that region rejects an explicit `LocationConstraint`.
-</Callout>
+The command omits `LocationConstraint` in `us-east-1`, which requires that exception. See [AWS CreateBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html).
 
-Keep all buckets **private** (block public access). Sim serves files through short-lived presigned URLs, so the buckets never need public read access.
+Keep all buckets **private** (block public access). Uploads use short-lived signed URLs and downloads are proxied through the app. Buckets do not need public read access.
 
 </Step>
 
@@ -72,7 +74,7 @@ Keep all buckets **private** (block public access). Sim serves files through sho
 
 ### Configure CORS on every bucket
 
-Uploads are sent **directly from the browser** to S3 via presigned `PUT` requests, so each bucket needs a CORS policy that allows your Sim origin. Without this, every upload fails with a CORS error in the browser console even though the server-side configuration is correct.
+Uploads are sent **directly from the browser** to S3 via presigned `PUT` requests, so each bucket needs a CORS policy that allows your Sim origin. A missing or mismatched policy can block browser uploads even when server credentials work.
 
 ```bash
 cat > /tmp/cors.json <<'EOF'
@@ -171,7 +173,7 @@ S3_WORKSPACE_LOGOS_BUCKET_NAME=myorg-sim-workspace-logos
 | `AWS_SECRET_ACCESS_KEY` | Secret key | No (uses credential chain if unset) |
 | `S3_BUCKET_NAME` | General workspace files | **Yes** (enables S3) |
 | `S3_KB_BUCKET_NAME` | Knowledge base documents | **Yes**, to use knowledge bases (no fallback) |
-| `S3_EXECUTION_FILES_BUCKET_NAME` | Workflow execution files. Falls back to the literal name `sim-execution-files`, which you almost certainly do not own — always set this explicitly | Effectively yes — the fallback is a bucket you do not own |
+| `S3_EXECUTION_FILES_BUCKET_NAME` | Workflow execution files. Falls back to the literal name `sim-execution-files`, which may not exist or belong to you — set this explicitly | Set explicitly to your own bucket |
 | `S3_CHAT_BUCKET_NAME` | Deployed chat assets | **Yes**, to use deployed chats (no fallback) |
 | `S3_COPILOT_BUCKET_NAME` | Chat attachments | **Yes**, to attach files in Chat (no fallback) |
 | `S3_PROFILE_PICTURES_BUCKET_NAME` | User avatars | **Yes**, for avatar uploads (no fallback) |
@@ -180,49 +182,16 @@ S3_WORKSPACE_LOGOS_BUCKET_NAME=myorg-sim-workspace-logos
 | `S3_ENDPOINT` | Custom endpoint for S3-compatible storage (R2, MinIO, B2) | Optional (AWS S3 if unset) |
 | `S3_FORCE_PATH_STYLE` | `true` for path-style addressing (MinIO/Ceph) | Optional (defaults `false`) |
 
-## Apply the configuration
-
-<Tabs items={['Docker Compose', 'Kubernetes (Helm)']}>
-  <Tab value="Docker Compose">
+## Set up Azure Blob Storage
 
-Add the storage variables to the `.env` file used by `docker-compose.prod.yml`, then restart:
-
-```bash
-docker compose -f docker-compose.prod.yml up -d
-```
-
-New uploads now use S3. Preserve any existing local files until you have migrated them; changing the storage configuration does not copy their bytes.
-
-  </Tab>
-  <Tab value="Kubernetes (Helm)">
-
-Set the variables under `app.env` (non-secret, e.g. region and bucket names) and supply credentials through a secret. The chart ships a complete example at `helm/sim/examples/values-aws.yaml`:
-
-```yaml
-app:
-  env:
-    AWS_REGION: "us-east-1"
-    S3_BUCKET_NAME: "myorg-sim-workspace-files"
-    S3_KB_BUCKET_NAME: "myorg-sim-knowledge-base"
-    S3_EXECUTION_FILES_BUCKET_NAME: "myorg-sim-execution-files"
-    # ...remaining buckets
-```
-
-On EKS, prefer **IRSA**: attach the IAM policy to the service account's role and leave the access-key variables unset.
-
-  </Tab>
-</Tabs>
-
-## Set up Azure Blob
-
-Azure Blob uses one container per purpose, mirroring the S3 layout. Authenticate with either a connection string or an account name + key.
+Create one private container per purpose; Sim does not create them. Authenticate with either a connection string or an account name and key.
 
 ```bash
 # Credentials — provide ONE of these forms
 AZURE_ACCOUNT_NAME=mystorageaccount
 AZURE_ACCOUNT_KEY=...
 # or
-AZURE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net
+AZURE_CONNECTION_STRING='DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net'
 
 # Containers (per purpose)
 AZURE_STORAGE_CONTAINER_NAME=workspace-files
@@ -235,9 +204,25 @@ AZURE_STORAGE_OG_IMAGES_CONTAINER_NAME=og-images
 AZURE_STORAGE_WORKSPACE_LOGOS_CONTAINER_NAME=workspace-logos
 ```
 
-<Callout type="warn">
-  Set every container name. Like the S3 variables, the knowledge-base, chat, Chat-attachment, and profile-picture containers do not fall back to `AZURE_STORAGE_CONTAINER_NAME` — an unset one resolves to an empty container name and that file type fails to store. The OpenGraph and workspace-logo containers do fall back to it, and `AZURE_STORAGE_EXECUTION_FILES_CONTAINER_NAME` falls back to the literal name `sim-execution-files`.
-</Callout>
+Create all eight containers before applying the variables. For example, with account-name/key credentials:
+
+```bash
+for name in workspace-files knowledge-base execution-files chat-files copilot-files profile-pictures og-images workspace-logos; do
+  az storage container create \
+    --name "$name" \
+    --account-name "$AZURE_ACCOUNT_NAME" \
+    --account-key "$AZURE_ACCOUNT_KEY" \
+    --public-access off
+done
+```
+
+For connection-string credentials, replace the account options with `--connection-string "$AZURE_CONNECTION_STRING"`.
+
+| Container variable | Fallback when unset |
+|---|---|
+| `AZURE_STORAGE_KB_CONTAINER_NAME`, `AZURE_STORAGE_CHAT_CONTAINER_NAME`, `AZURE_STORAGE_COPILOT_CONTAINER_NAME`, `AZURE_STORAGE_PROFILE_PICTURES_CONTAINER_NAME` | None; that file type fails to store |
+| `AZURE_STORAGE_EXECUTION_FILES_CONTAINER_NAME` | Literal `sim-execution-files`; set your intended name explicitly |
+| `AZURE_STORAGE_OG_IMAGES_CONTAINER_NAME`, `AZURE_STORAGE_WORKSPACE_LOGOS_CONTAINER_NAME` | `AZURE_STORAGE_CONTAINER_NAME` |
 
 Direct browser uploads require a Blob service CORS rule on the storage account. Allow your exact
 Sim origin, `GET` and `PUT`, the `Content-Type` header, and the `x-ms-*` prefix used by signed blob
@@ -289,7 +274,7 @@ for name in ${SIM_BUCKETS:?run the export above first}; do
 done
 ```
 
-Keep all buckets **private** (no `allUsers` bindings). Sim serves files through short-lived V4 signed URLs, so the buckets never need public read access.
+Keep all buckets **private** (no `allUsers` bindings). Uploads use short-lived V4 signed URLs and downloads are proxied through the app. Buckets do not need public read access.
 
 Because uploads are sent **directly from the browser** via signed `PUT` requests, each bucket needs a CORS policy that allows your Sim origin:
 
@@ -299,11 +284,11 @@ cat > /tmp/cors.json <<'EOF'
   {
     "origin": ["https://your-sim-domain.com"],
     "method": ["GET", "PUT"],
-      "responseHeader": [
-        "Content-Type",
-        "ETag",
-        "x-goog-if-generation-match",
-        "x-goog-meta-uploadid",
+    "responseHeader": [
+      "Content-Type",
+      "ETag",
+      "x-goog-if-generation-match",
+      "x-goog-meta-uploadid",
       "x-goog-meta-originalname",
       "x-goog-meta-uploadedat",
       "x-goog-meta-purpose",
@@ -324,9 +309,7 @@ for name in ${SIM_BUCKETS:?run the export above first}; do
 done
 ```
 
-<Callout type="info">
-  Header names must be listed individually — GCS CORS matches `responseHeader` entries exactly and does not support wildcards like `x-goog-meta-*`. The example exposes `ETag`, although the current upload-session client does not need it: multipart completion reads provider-authoritative part state on the server. `x-goog-if-generation-match` is required by Sim's create-only signed uploads, which prevent a reused upload URL from replacing existing bytes.
-</Callout>
+Keep the explicit metadata and `x-goog-if-generation-match` headers in this policy: Sim signs create-only uploads, which prevent a reused URL from replacing existing bytes. Multipart completion reads provider-authoritative part state on the server; the browser does not need `ETag` for completion. See [GCS CORS configuration](https://docs.cloud.google.com/storage/docs/cross-origin).
 
 </Step>
 
@@ -404,19 +387,17 @@ GCS_WORKSPACE_LOGOS_BUCKET_NAME=myorg-sim-workspace-logos
 
 A full Helm example (Workload Identity, GKE) lives at `helm/sim/examples/values-gcp.yaml`.
 
-## Set up an S3-compatible provider (R2, MinIO, B2)
+## Set up S3-compatible storage
 
-Sim works with any S3-compatible store by pointing the S3 client at a custom endpoint. Configure it exactly like AWS S3 (buckets, access key, secret), then add `S3_ENDPOINT` — and `S3_FORCE_PATH_STYLE` where the provider requires path-style addressing. Verified with [Cloudflare R2](https://developers.cloudflare.com/r2/), [MinIO](https://min.io/), [Backblaze B2](https://www.backblaze.com/cloud-storage), and [RustFS](https://rustfs.com/).
+Sim works with any S3-compatible store by pointing the S3 client at a custom endpoint. Configure it exactly like AWS S3 (buckets, access key, secret), then add `S3_ENDPOINT` — and `S3_FORCE_PATH_STYLE` where the provider requires path-style addressing. The examples below cover [Cloudflare R2](https://developers.cloudflare.com/r2/), [MinIO](https://min.io/), and [RustFS](https://rustfs.com/). For other providers, including [Backblaze B2](https://www.backblaze.com/cloud-storage), verify signed uploads, multipart completion, and lifecycle behavior against that provider's current S3 support.
 
-<Callout type="info">
-  `S3_ENDPOINT` is trusted operator configuration, so it is used as-is — `http://` and private hosts are accepted (no SSRF/HTTPS gate). Don't wire it to untrusted input.
-</Callout>
+`S3_ENDPOINT` is trusted operator configuration. Sim accepts HTTP and private hosts without its outbound-request guard; do not derive it from untrusted input.
 
 <Callout type="warn">
   **The endpoint must be reachable from your users' browsers, and the bucket needs CORS.** Uploads use presigned `PUT` requests sent **directly from the browser** to `S3_ENDPOINT` (downloads are proxied back through the app, so they only need server-side reachability). This means:
 
   - A purely internal endpoint (e.g. `https://minio.internal:9000` that only the app pods can resolve) will let the server start cleanly but **uploads will fail in the browser**. Use an endpoint your users can reach.
-  - Configure a **CORS policy** on the bucket that allows your Sim origin with `PUT` and `GET`, and `AllowedHeaders: ["*"]`. With a custom endpoint, the browser sends the upload's metadata as signed `x-amz-meta-*` headers alongside `Content-Type` and `If-None-Match`, because many S3-compatible stores ignore metadata passed in the URL. If you list headers individually, include all of them. MinIO applies its own server-wide CORS and needs no bucket rule.
+  - Configure a **CORS policy** on the bucket that allows your Sim origin with `PUT` and `GET`, and `AllowedHeaders: ["*"]`. With a custom endpoint, the browser sends the upload's metadata as signed `x-amz-meta-*` headers alongside `Content-Type` and `If-None-Match`, because many S3-compatible stores ignore metadata passed in the URL. If you list headers individually, include all of them. On MinIO, check the server-wide origin settings and any reverse proxy as well as the bucket policy; do not assume CORS is already configured.
   - Sim adds the `S3_ENDPOINT` origin (and its bucket subdomains, unless `S3_FORCE_PATH_STYLE` is set) to its Content Security Policy, so the browser may upload there.
 </Callout>
 
@@ -428,8 +409,8 @@ Sim works with any S3-compatible store by pointing the S3 client at a custom end
 ```bash
 AWS_REGION=auto
 S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
-AWS_ACCESS_KEY_ID=<r2-access-key-id>
-AWS_SECRET_ACCESS_KEY=<r2-secret-access-key>
+AWS_ACCESS_KEY_ID='<r2-access-key-id>'
+AWS_SECRET_ACCESS_KEY='<r2-secret-access-key>'
 S3_BUCKET_NAME=myorg-sim-workspace-files
 # ...remaining S3_*_BUCKET_NAME vars, one R2 bucket each
 ```
@@ -439,14 +420,14 @@ Leave `S3_FORCE_PATH_STYLE` unset — R2 supports the default virtual-hosted add
   </Tab>
   <Tab value="MinIO">
 
-[MinIO](https://min.io/docs/minio/linux/index.html) (and [Ceph RGW](https://docs.ceph.com/en/latest/radosgw/)) need path-style addressing and accept any region string:
+For a [MinIO](https://min.io/docs/minio/linux/index.html) endpoint without bucket subdomain routing, use path-style addressing and the region configured by its operator. [Ceph RGW](https://docs.ceph.com/en/latest/radosgw/s3/commons/) supports both addressing styles when DNS is configured:
 
 ```bash
 AWS_REGION=us-east-1
 S3_ENDPOINT=https://minio.example.com   # must be reachable from users' browsers, not app-pods-only
 S3_FORCE_PATH_STYLE=true
-AWS_ACCESS_KEY_ID=<minio-access-key>
-AWS_SECRET_ACCESS_KEY=<minio-secret-key>
+AWS_ACCESS_KEY_ID='<minio-access-key>'
+AWS_SECRET_ACCESS_KEY='<minio-secret-key>'
 S3_BUCKET_NAME=myorg-sim-workspace-files
 # ...remaining S3_*_BUCKET_NAME vars, one bucket each
 ```
@@ -456,14 +437,14 @@ S3_BUCKET_NAME=myorg-sim-workspace-files
   </Tab>
   <Tab value="RustFS">
 
-[RustFS](https://rustfs.com/) is a Rust-based, S3-compatible store (a MinIO drop-in). Configure it exactly like MinIO — path-style, any region string, SigV4 access key/secret:
+For [RustFS](https://rustfs.com/), configure the endpoint, access key/secret, and region for your installation. This example uses path-style addressing:
 
 ```bash
 AWS_REGION=us-east-1
 S3_ENDPOINT=https://rustfs.example.com   # must be reachable from users' browsers
 S3_FORCE_PATH_STYLE=true
-AWS_ACCESS_KEY_ID=<rustfs-access-key>
-AWS_SECRET_ACCESS_KEY=<rustfs-secret-key>
+AWS_ACCESS_KEY_ID='<rustfs-access-key>'
+AWS_SECRET_ACCESS_KEY='<rustfs-secret-key>'
 S3_BUCKET_NAME=myorg-sim-workspace-files
 # ...remaining S3_*_BUCKET_NAME vars, one bucket each
 ```
@@ -473,12 +454,43 @@ The same browser-reachability and CORS requirements apply.
   </Tab>
 </Tabs>
 
+## Apply the configuration
+
+<Tabs items={['Docker Compose', 'Kubernetes (Helm)']}>
+  <Tab value="Docker Compose">
+
+Add the storage variables to the `.env` file used by `docker-compose.prod.yml`, then restart:
+
+```bash
+docker compose -f docker-compose.prod.yml up -d
+```
+
+New uploads now use the selected backend. Preserve any existing local files until you have migrated them; changing the storage configuration does not copy their bytes.
+
+  </Tab>
+  <Tab value="Kubernetes (Helm)">
+
+Set the variables under `app.env` (non-secret, e.g. region and bucket names) and supply credentials through a secret. The chart ships a complete example at `helm/sim/examples/values-aws.yaml`:
+
+```yaml
+app:
+  env:
+    AWS_REGION: "us-east-1"
+    S3_BUCKET_NAME: "myorg-sim-workspace-files"
+    S3_KB_BUCKET_NAME: "myorg-sim-knowledge-base"
+    S3_EXECUTION_FILES_BUCKET_NAME: "myorg-sim-execution-files"
+    # ...remaining buckets
+```
+
+On EKS, prefer **IRSA**: attach the IAM policy to the service account's role and leave the access-key variables unset.
+
+  </Tab>
+</Tabs>
+
 ## Configure incomplete multipart cleanup
 
 Sim uploads directly to a create-only final object key and keeps upload-session state in PostgreSQL.
-The cleanup cron claims expired sessions before deleting an uploaded object or aborting its provider
-multipart state. Configure provider lifecycle cleanup as a second line of defense for multipart
-state that outlives its database row:
+The `/api/cron/cleanup-tasks` endpoint claims expired sessions before deleting uploaded objects or aborting provider multipart state. **Neither shipped scheduler calls this endpoint.** Configure an authenticated operator-owned schedule as shown in [Background jobs](/platform/self-hosting/background-jobs#schedule-upload-session-cleanup). Provider lifecycle cleanup is a second layer for multipart state that outlives its database row:
 
 - On AWS S3 and Google Cloud Storage, abort incomplete multipart uploads after two days on every
   purpose-specific bucket.
@@ -494,7 +506,7 @@ can still recover. Do not add an object-expiration rule for final upload keys.
   the incomplete-multipart operation; expiring objects does not remove abandoned multipart parts.
 </Callout>
 
-## Verify it works
+## Verify storage
 
 After restarting with the new configuration:
 
@@ -503,3 +515,8 @@ After restarting with the new configuration:
 3. Reload the page — the file should still render (downloads stream back through the app at `/api/files/serve`).
 
 If uploads fail, check the app logs for credential or permission errors (see [Troubleshooting](/platform/self-hosting/troubleshooting)).
+
+## Related docs
+
+- [Background jobs](/platform/self-hosting/background-jobs)
+- [Troubleshooting](/platform/self-hosting/troubleshooting)
diff --git a/apps/docs/content/docs/platform/self-hosting/observability.mdx b/apps/docs/content/docs/platform/self-hosting/observability.mdx
index 0efa9db0588..0bc1c34471d 100644
--- a/apps/docs/content/docs/platform/self-hosting/observability.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/observability.mdx
@@ -5,6 +5,8 @@ description: Health checks, logs, tracing, and what to alert on
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
+Use health checks, container logs, and infrastructure metrics to monitor your deployment. Decide where telemetry is sent before enabling tracing or raising log verbosity.
+
 ## Health endpoints
 
 | Service | Endpoint | Returns |
@@ -60,23 +62,44 @@ docker compose -f docker-compose.prod.yml logs -f simstudio
 
 Every API request carries a request ID that appears in all log lines for that request — the fastest way to reconstruct a failing call.
 
-<Callout type="info">
-  Workflow execution logs are a separate, product-level surface stored in the database and visible in the Logs view of the app. They are not the same as container logs: use container logs for infrastructure problems and the Logs view for workflow behavior.
-</Callout>
+Workflow execution logs are stored in PostgreSQL and shown in the app's **Logs** view. Use them for workflow behavior and container logs for infrastructure failures.
 
 ### Redacting PII from logs
 
-Enable the PII service and log redaction if execution logs may contain sensitive data:
+Deploy the PII service, configure its internal network path, and enable the stored **Logs** redaction policy under **Settings → Organization → Data retention**. Deploying the service alone does not mask logs. Follow [Security's PII setup](/platform/self-hosting/security#pii-redaction) and [Data retention](/platform/enterprise/data-retention).
 
-```yaml
-pii:
-  enabled: true
-app:
-  env:
-    INTERNAL_API_BASE_URL: "http://sim-app.simstudio.svc.cluster.local:3000"
-```
+## Metrics
 
-See [Security](/platform/self-hosting/security) for the `INTERNAL_API_BASE_URL` requirement — the path fails closed without a cluster-reachable value.
+<Callout type="warn">
+  The default app and realtime images **do not expose a `/metrics` endpoint**. The chart's `monitoring.serviceMonitor` option exists for builds that do — enabling it against the stock images produces a ServiceMonitor that scrapes nothing.
+</Callout>
+
+Until an application metrics endpoint ships, build alerting from the signals that do exist:
+
+- **Kubernetes state** — pod restarts, `CrashLoopBackOff`, OOMKills, replica count vs desired, PVC utilization (kube-state-metrics). For a point-in-time read on resource pressure, `kubectl top pods -n simstudio` shows current CPU and memory usage — compare it against the limits from `kubectl describe pod`. It is the first thing to check when a pod is being OOMKilled.
+- **Ingress/load balancer** — request rate, 5xx rate, p99 latency, websocket connection count.
+- **PostgreSQL** — connection count vs `max_connections`, replication lag, disk usage, long-running queries.
+- **Redis** — memory usage, evictions, connected clients.
+- **CronJobs** — last successful completion per job.
+
+### CloudWatch metrics
+
+Sim's hosted-key metrics recorder arms itself whenever `AWS_ACCESS_KEY_ID` is present, but every call site is additionally gated on the deployment being Sim Cloud. A self-hosted deployment emits no `PutMetricData` calls, even with AWS credentials configured for S3. If you want defence in depth against that gate ever changing, deny `cloudwatch:PutMetricData` on the IAM identity behind those credentials.
+
+## What to alert on
+
+| Alert | Why it matters |
+|---|---|
+| App pod restart loop / OOMKilled | Memory is the constraining resource; OOMKills mean executions are dying mid-run |
+| A CronJob has not succeeded within its expected interval plus a chosen grace period | Scheduled workflows and polling triggers may have stopped. Choose a threshold for each job based on its schedule and expected runtime |
+| Ingress 5xx rate above baseline | Broad user impact |
+| Postgres connections above 80% of `max_connections` | Next replica or traffic spike will start failing |
+| Postgres disk above 80% | Knowledge base embeddings grow steadily |
+| Redis unreachable | Live collaboration and status updates can stop; inspect app and realtime connection errors |
+| Certificate expiry within 14 days | Especially with manually managed certs |
+| Object storage 4xx/5xx rate | Broken uploads usually show here first |
+
+Alert on `kube_cronjob_status_last_successful_time` with a threshold derived from each job's schedule and expected runtime. A successful HTTP call can mean work was accepted, not completed; also verify expected executions and outputs in the app.
 
 ## Telemetry
 
@@ -89,35 +112,30 @@ Telemetry has two halves that are decided at different times.
 | Server SDK | Runtime | **Off** on Helm (`app.envDefaults` sets `NEXT_TELEMETRY_DISABLED: "1"`); **on** for Docker Compose and source runs, which set nothing |
 | Browser | Server setting at page render, then browser preferences | Disabled when `NEXT_TELEMETRY_DISABLED=1`; otherwise waits for session resolution and the signed-in user's saved preference. Hosted Sim also requires the applicable analytics permission. |
 
-Neither half gates `POST /api/telemetry`, the relay that forwards browser events. See the warning below.
+Neither half gates `POST /api/telemetry`, the relay that forwards submitted browser events. Its destination is controlled separately by `TELEMETRY_ENDPOINT`; disabling collection does not disable this endpoint.
 
-When the server SDK runs it exports three OTLP signals to the same base endpoint: traces at `/v1/traces`, metrics at `/v1/metrics`, and application **log records** at `/v1/logs`. Sim's own telemetry is scoped to feature-usage statistics, error rates, performance metrics, and AI/LLM operation traces — not workflow content or outputs, API keys, or geolocation.
+When the server SDK runs it exports three OTLP signals to the same base endpoint: traces at `/v1/traces`, metrics at `/v1/metrics`, and application **log records** at `/v1/logs`. Default instrumentation records usage, performance, errors, and AI/LLM traces rather than raw workflow content. Error metadata and log records can still contain sensitive values; inspect the signals you send to your collector.
 
-The log stream is different in kind: it carries every line at or above `LOG_LEVEL` with its structured metadata, error messages and stack traces, which can include user ids, emails and URLs. That matters if you raise `LOG_LEVEL` as suggested above, and it is a reason to point the exporter at your own collector rather than leaving it at the default.
+Log records at or above `LOG_LEVEL` carry structured metadata, error messages, and stack traces, which can include account IDs, emails, and URLs. Raising `LOG_LEVEL` increases that stream. Configure your collector and retention policy accordingly.
 
-`NEXT_TELEMETRY_DISABLED=1` stops the server's OpenTelemetry SDK and disables browser collection on newly loaded pages. It does not affect Trigger.dev task telemetry, configured separately below. The **Settings → General → Privacy → Allow browser telemetry** toggle stops optional browser performance and error diagnostics, discards queued events, and remembers the choice. It does not stop server spans.
+`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` is **off by default**. Setting it to `true`, `1`, or `yes` enables Chat message capture, including prompts, assistant text, tool arguments, and previews. Treat it as an explicit content-sharing decision before enabling it.
 
-<Callout type="warn">
-  On Helm, `NEXT_TELEMETRY_DISABLED` is what you must **clear** before any tracing works — including tracing to your own collector. Override it with `null` to remove the key entirely.
-
-  ```yaml
-  app:
-    envDefaults:
-      NEXT_TELEMETRY_DISABLED: null
-  ```
-</Callout>
+`NEXT_TELEMETRY_DISABLED=1` stops the server's OpenTelemetry SDK and disables browser collection on newly loaded pages. It does not affect Trigger.dev task telemetry, configured separately below. The **Settings → General → Privacy → Allow browser telemetry** toggle stops optional browser performance and error diagnostics, discards queued events, and remembers the choice. It does not stop server spans.
 
 ## Tracing
 
-The chart can deploy an OpenTelemetry Collector for you:
+Enable both the collector and application tracing on Helm:
 
 ```yaml
 telemetry:
   enabled: true
+app:
+  envDefaults:
+    NEXT_TELEMETRY_DISABLED: null
 ```
 
 <Callout type="warn">
-  `telemetry.enabled: true` deploys the collector and injects `OTEL_EXPORTER_OTLP_ENDPOINT` pointing at it, but the app still has `NEXT_TELEMETRY_DISABLED: "1"` from `app.envDefaults`. The collector runs and receives nothing until you clear that key as shown above. Enabling telemetry is two changes, not one.
+  `telemetry.enabled` alone deploys a collector that receives no app signals while `NEXT_TELEMETRY_DISABLED=1`. Set the inherited key to `null` to remove it, as shown above. This also enables browser collection subject to the signed-in account's preference.
 </Callout>
 
 Or point the app at a collector you already run:
@@ -133,9 +151,7 @@ Or point the app at a collector you already run:
 
 The endpoint is resolved by precedence, first match wins: `OTEL_EXPORTER_OTLP_ENDPOINT`, then `TELEMETRY_ENDPOINT`, then the endpoint in `apps/sim/telemetry.config.ts`. This precedence governs the server SDK only — the `/api/telemetry` relay reads `TELEMETRY_ENDPOINT` and nothing else. Sampling resolves the same way: `TELEMETRY_SAMPLING_RATIO`, then `OTEL_TRACES_SAMPLER_ARG`, defaulting to 1.0. Editing `telemetry.config.ts` only changes the last fallback, so an environment variable set anywhere in your stack silently wins over it.
 
-<Callout type="info">
-  `OTEL_SERVICE_NAME` is not read. The chart sets it to `sim-app` when `telemetry.enabled` is true, but the app hardcodes its own service name, so spans arrive under the literal value `mothership`. Filter on that, not on `sim-app`.
-</Callout>
+The app does not read `OTEL_SERVICE_NAME`: server spans use the literal service name `mothership`, even when Helm sets `sim-app`. Use `mothership` in collector filters.
 
 If you enable the chart's Jaeger export, point `telemetry.jaeger.endpoint` at Jaeger's **OTLP gRPC port (4317)** — the collector exports over OTLP.
 
@@ -153,37 +169,7 @@ If you enable the chart's Jaeger export, point `telemetry.jaeger.endpoint` at Ja
   All three or none. Setting one or two throws at startup with a message naming them, so a partially configured worker will not boot.
 </Callout>
 
-## Metrics
-
-<Callout type="warn">
-  The default app and realtime images **do not expose a `/metrics` endpoint**. The chart's `monitoring.serviceMonitor` option exists for builds that do — enabling it against the stock images produces a ServiceMonitor that scrapes nothing.
-</Callout>
-
-Until an application metrics endpoint ships, build alerting from the signals that do exist:
-
-- **Kubernetes state** — pod restarts, `CrashLoopBackOff`, OOMKills, replica count vs desired, PVC utilization (kube-state-metrics). For a point-in-time read on resource pressure, `kubectl top pods -n simstudio` shows current CPU and memory usage — compare it against the limits from `kubectl describe pod`. It is the first thing to check when a pod is being OOMKilled.
-- **Ingress/load balancer** — request rate, 5xx rate, p99 latency, websocket connection count.
-- **PostgreSQL** — connection count vs `max_connections`, replication lag, disk usage, long-running queries.
-- **Redis** — memory usage, evictions, connected clients.
-- **CronJobs** — last successful completion per job.
-
-### CloudWatch metrics
-
-Sim's hosted-key metrics recorder arms itself whenever `AWS_ACCESS_KEY_ID` is present, but every call site is additionally gated on the deployment being Sim Cloud. A self-hosted deployment emits no `PutMetricData` calls, even with AWS credentials configured for S3. If you want defence in depth against that gate ever changing, deny `cloudwatch:PutMetricData` on the IAM identity behind those credentials.
-
-## What to alert on
-
-| Alert | Why it matters |
-|---|---|
-| App pod restart loop / OOMKilled | Memory is the constraining resource; OOMKills mean executions are dying mid-run |
-| A CronJob has not succeeded within its expected interval plus a chosen grace period | Scheduled workflows and polling triggers may have stopped. Choose a threshold for each job based on its schedule and expected runtime |
-| Ingress 5xx rate above baseline | Broad user impact |
-| Postgres connections above 80% of `max_connections` | Next replica or traffic spike will start failing |
-| Postgres disk above 80% | Knowledge base embeddings grow steadily |
-| Redis unreachable | Live collaboration and status updates stop, without app errors |
-| Certificate expiry within 14 days | Especially with manually managed certs |
-| Object storage 4xx/5xx rate | Broken uploads usually show here first |
+## Related docs
 
-<Callout type="warn">
-  The CronJob alert is the one most deployments lack and most need. Background job failures produce no user-visible error — schedules simply stop firing. Alert on `kube_cronjob_status_last_successful_time` lagging, with a per-job threshold derived from that job's schedule.
-</Callout>
+- [Background jobs](/platform/self-hosting/background-jobs)
+- [Verify your install](/platform/self-hosting/verify)
diff --git a/apps/docs/content/docs/platform/self-hosting/platforms.mdx b/apps/docs/content/docs/platform/self-hosting/platforms.mdx
index 1c00e330543..8abbe858c84 100644
--- a/apps/docs/content/docs/platform/self-hosting/platforms.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/platforms.mdx
@@ -1,51 +1,64 @@
 ---
-title: Cloud Platforms
-description: Provider-specific notes for running Sim on Railway, a VPS, or managed Kubernetes
+title: Cloud platforms
+description: Provider-specific requirements for Railway, a VPS, or managed Kubernetes
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
-This page covers what differs per provider. The deployment itself is the same everywhere — follow [Docker](/platform/self-hosting/docker) for a single node or [Kubernetes](/platform/self-hosting/kubernetes) for a cluster.
+Use [Docker](/platform/self-hosting/docker) for a single node or [Kubernetes](/platform/self-hosting/kubernetes) for a cluster. This page covers provider-specific prerequisites and configuration differences.
 
 ## Railway
 
-One-click deployment with automatic PostgreSQL provisioning.
+The [Sim deployment template](https://railway.com/new/template/sim-studio) provides a starting installation. Review its current services and variables before using it for production:
 
-[![Deploy on Railway](https://railway.app/button.svg)](https://railway.com/new/template/sim-studio)
-
-After deployment, set in the Railway dashboard:
-
-- `BETTER_AUTH_SECRET`, `ENCRYPTION_KEY`, `INTERNAL_API_SECRET` (auto-generated by the template)
-- An AI provider key such as `OPENAI_API_KEY`
-- Your custom domain under **Settings → Networking**, then `NEXT_PUBLIC_APP_URL` to match
+1. Confirm PostgreSQL has pgvector and that migrations complete.
+2. Confirm the app and realtime services share `BETTER_AUTH_SECRET` and `INTERNAL_API_SECRET`.
+3. Retain generated secrets, set `API_ENCRYPTION_KEY`, and configure durable storage.
+4. Configure your domain under **Settings → Networking**. Set `NEXT_PUBLIC_APP_URL` and `BETTER_AUTH_URL` to that app origin; match `NEXT_PUBLIC_SOCKET_URL` to the realtime endpoint.
+5. Add a model provider key such as `OPENAI_API_KEY` and configure email if needed.
+6. Check Redis and the scheduler rather than assuming the template includes them.
 
 <Callout type="warn">
-  The Railway template deploys the app services but not the `cron` service, so scheduled workflows and polling triggers stay idle. Add a Railway cron service calling the endpoints in [Background Jobs](/platform/self-hosting/background-jobs), or deploy with Docker Compose instead.
+  Railway Cron Jobs run no more often than every five minutes. They cannot reproduce Sim's bundled minute-level scheduler cadence. Use a continuously running Sim scheduler service or another scheduler supporting the schedules in [Background jobs](/platform/self-hosting/background-jobs). See [Railway's cron requirements](https://docs.railway.com/cron-jobs).
 </Callout>
 
 ## VPS
 
-DigitalOcean, EC2, Azure VM, Hetzner, or any Linux box. Size it from the [requirements table](/platform/self-hosting) — 16 GB RAM is the practical floor for a team install, because memory rather than CPU is what bounds concurrent workflow executions.
+Run Compose on a Linux server such as DigitalOcean, EC2, Azure VM, or Hetzner. Use the [resource examples](/platform/self-hosting#requirements) as a starting point, then size for your workload.
 
-Install Docker via [get.docker.com](https://get.docker.com), then follow the [Docker guide](/platform/self-hosting/docker), which covers secrets, the compose stack, and TLS.
+Install Docker Engine and the Compose plugin using [Docker's instructions for your operating system](https://docs.docker.com/engine/install/). The shipped file requires Compose 2.24.0 or later. Docker's `get.docker.com` convenience script is intended for development; use its package installation instructions for production.
+
+Follow [Docker](/platform/self-hosting/docker) for secrets, durable uploads, service startup, and TLS.
 
 ## Managed Kubernetes
 
-EKS, AKS, and GKE each have a tuned example values file in the chart. See [Kubernetes](/platform/self-hosting/kubernetes) for the install and [Networking](/platform/self-hosting/networking) for the load-balancer specifics — notably GKE's 30-second websocket timeout and its `ManagedCertificate` requirement.
+EKS, AKS, and GKE have example values files in the chart's source repository. They contain provider resources and placeholders you must review: storage classes, bucket names, workload identities, certificates, static addresses, and network policy.
+
+Use the pinned example in [Kubernetes](/platform/self-hosting/kubernetes), then follow [Networking](/platform/self-hosting/networking) for the provider's load balancer. GKE requires the referenced `ManagedCertificate` and an appropriate backend timeout for WebSockets. The AKS example retains legacy ingress-nginx settings; that controller retired in March 2026. Use a maintained controller already supported by your cluster and its own configuration.
 
 ## Managed PostgreSQL
 
-Recommended for any production deployment. The requirement is **pgvector**.
+An external database must support the `vector` extension and the migration permissions Sim needs. Availability does not mean the extension is enabled in your database.
 
-| Service | Notes |
-|---|---|
-| AWS RDS / Aurora | Enable the `vector` extension |
-| GCP Cloud SQL | Enable the `vector` extension |
-| Azure Database for PostgreSQL | Enable the `vector` extension |
-| Supabase / Neon | pgvector available by default |
+| Service | Setup |
+| --- | --- |
+| AWS RDS / Aurora PostgreSQL | Choose an engine version with pgvector support and enable `vector`. |
+| GCP Cloud SQL for PostgreSQL | Enable the supported `vector` extension. |
+| Azure Database for PostgreSQL Flexible Server | Allow `vector` in `azure.extensions`, then enable it in the database. |
+| Supabase / Neon | Enable `vector` in the database you use for Sim. |
+
+See [Cloud SQL extensions](https://docs.cloud.google.com/sql/docs/postgres/extensions), [Azure extension allowlisting](https://learn.microsoft.com/en-us/azure/postgresql/extensions/how-to-allow-extensions), and [Neon pgvector setup](https://neon.com/docs/extensions/pgvector) for provider requirements.
+
+An app or source checkout can use a connection string such as:
 
 ```bash
-DATABASE_URL="postgresql://user:pass@host:5432/simstudio?sslmode=require"
+DATABASE_URL="postgresql://<user>:<password>@<host>:5432/simstudio?sslmode=require"
 ```
 
-For the Helm chart, disable the bundled Postgres and use `externalDatabase` — see [Kubernetes](/platform/self-hosting/kubernetes#external-database).
+For Helm, disable bundled PostgreSQL and configure [`externalDatabase`](/platform/self-hosting/kubernetes#external-database). Production Compose overrides `DATABASE_URL` with its bundled database connection; changing `.env` alone does not switch it. An operator-owned Compose configuration must give the same external DSN to the app, realtime, and migrations and adjust their bundled-database dependencies. See [Docker configuration](/platform/self-hosting/docker#production-setup).
+
+## Related docs
+
+- [Reference architectures](/platform/self-hosting/reference-architectures)
+- [Verify your install](/platform/self-hosting/verify)
+- [Database upgrades and backups](/platform/self-hosting/upgrades)
diff --git a/apps/docs/content/docs/platform/self-hosting/redis.mdx b/apps/docs/content/docs/platform/self-hosting/redis.mdx
index f8739ec3d1e..60cd942cd08 100644
--- a/apps/docs/content/docs/platform/self-hosting/redis.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/redis.mdx
@@ -3,10 +3,10 @@ title: Redis
 description: When Redis is optional, when it is required, and how to configure it
 ---
 
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 import { Callout } from 'fumadocs-ui/components/callout'
 
-Sim uses Redis as a message bus and shared cache. Both deployments ship it by default — Docker Compose as a `redis` service, Helm as a `redis` Deployment — so this page is mostly about when to replace the bundled instance with a managed one, and what breaks if Redis is absent entirely.
+Configure Redis for shared coordination and live events. Compose and Helm bundle it by default; use this page to replace that instance or understand the fallback behavior.
 
 ## What it backs
 
@@ -21,7 +21,7 @@ Sim uses Redis as a message bus and shared cache. Both deployments ship it by de
 | Collaborative document store (realtime) | Falls back to in-process state |
 
 <Callout type="error">
-  With more than one app or realtime replica and no `REDIS_URL`, users on different pods stop seeing each other's edits and live status updates. Beyond one startup log line noting single-pod mode, nothing is logged — the app looks healthy and quietly loses events. Treat Redis as mandatory the moment `replicaCount` exceeds 1.
+  Configure Redis before running more than one app or realtime replica. Without it, process-local fallbacks cannot deliver edits and status across pods. A healthy HTTP response does not prove cross-pod collaboration works.
 </Callout>
 
 Everything Sim keeps in Redis is cache, coordination state, or an in-flight event — never committed data, which lives in PostgreSQL and object storage. Persistence is therefore not required. Losing or restarting the instance is not free, though: cancellation markers and the cross-pod half of execution streaming live here, so active runs stop streaming and a cancellation issued across the gap may not land. Completed work is unaffected.
@@ -36,17 +36,17 @@ REDIS_URL=rediss://:password@redis-host:6380
 
 Both the app and the realtime service need it — they use it for different things.
 
-<Tabs items={['Docker Compose', 'Kubernetes (Helm)', 'Managed Redis']}>
+<Tabs items={['Docker Compose', 'Kubernetes (Helm)']}>
   <Tab value="Docker Compose">
 
-`docker-compose.prod.yml` already includes a `redis:7-alpine` service and wires `REDIS_URL=redis://redis:6379` into both the app and realtime containers. Nothing to configure.
+`docker-compose.prod.yml` already includes a `redis:7-alpine` service and wires `REDIS_URL=redis://redis:6379` into both the app and realtime containers. No additional Redis URL is needed for that bundled instance.
 
 The port is deliberately not published to the host, so a Redis already running locally will not collide. Override `REDIS_URL` in `.env` to point at an external instance instead.
 
   </Tab>
   <Tab value="Kubernetes (Helm)">
 
-The chart deploys Redis by default, matching the Compose stack. Nothing to configure.
+The chart deploys Redis by default, matching the Compose stack. No additional Redis URL is needed for that bundled instance.
 
 For production, prefer a managed instance — disable the bundled one and supply a URL:
 
@@ -59,51 +59,58 @@ app:
     REDIS_URL: "rediss://:<password>@my-cache.internal:6380"
 ```
 
-`app.env.REDIS_URL` takes over whenever it is set, and the chart skips the bundled Deployment so you do not get a stray pod.
+`app.env.REDIS_URL` takes over whenever it is set, and the chart skips the bundled Deployment instead of deploying an unused instance.
 
 If the URL lives in a secret store instead — a pre-created Secret or one synced by External Secrets — it also wins, and there is nothing extra to configure. The bundled URL is delivered as a ConfigMap listed before the app Secret in `envFrom`, and Kubernetes lets the last source win for duplicate keys, so your value overrides it without the chart ever reading it.
 
-The bundled Redis is deliberately non-persistent (`--save ""`, `--appendonly no`) with a 512 MB cap: Sim stores coordination state and short-lived keys in it, so a restart costs in-flight live updates rather than committed data.
+The bundled Redis is deliberately non-persistent (`--save ""`, `--appendonly no`) with a 512 MiB cap: Sim stores coordination state and short-lived keys in it, so a restart costs in-flight live updates rather than committed data.
 
 If `networkPolicy.enabled=true`, egress to the bundled Redis is allowed automatically. An **external** Redis needs its own rule under `networkPolicy.egress` — the chart cannot know your host and port at render time.
 
   </Tab>
-  <Tab value="Managed Redis">
+</Tabs>
+
+### Managed Redis
 
-Managed services work and are the recommended production choice:
+A compatible managed service can provide availability and operational support. Options include:
 
 - **AWS** — ElastiCache for Redis or MemoryDB
 - **GCP** — Memorystore for Redis
-- **Azure** — Azure Cache for Redis
+- **Azure** — Azure Managed Redis. Azure Cache for Redis is retiring; use the [migration guidance](https://learn.microsoft.com/en-us/azure/azure-cache-for-redis/retirement-faq) for an existing Cache deployment. New Azure public-cloud customers cannot create the legacy service.
 
 Place the instance in the same VPC/VNet as the cluster and use its private endpoint. Enable TLS (`rediss://`) and auth.
 
-Sizing is modest: Sim uses Redis for coordination, not bulk storage. A 1–2 GB instance covers most deployments. Prefer a replicated/HA tier so a failover does not interrupt live collaboration.
+Sim uses single-endpoint Redis clients rather than OSS Cluster routing. Choose a compatible nonclustered or proxy-based service configuration and verify the required commands and pub/sub behavior. A managed service's default clustering policy is not automatically compatible.
 
-  </Tab>
-</Tabs>
+A 1–2 GiB instance is a starting estimate, not a capacity guarantee. Measure key memory, evictions, and client count for your workload. An HA tier reduces outage duration, but failover can still interrupt live events.
 
 ## TLS to an IP address
 
-If `REDIS_URL` uses `rediss://` and the host is a **bare IP** — common with AWS PrivateLink endpoints — TLS hostname verification cannot match an IP against the certificate. Sim throws rather than connecting insecurely, the first time it opens a Redis connection. Set the SNI override to the DNS name the certificate was issued for:
+Prefer a DNS hostname that matches the Redis certificate for both app and realtime. Certificates can contain IP addresses, but the app's IPv4-literal path requires an explicit TLS server-name override:
 
 ```bash
 REDIS_URL=rediss://:password@10.0.12.34:6379
 REDIS_TLS_SERVERNAME=my-cluster.abc123.ng.0001.use1.cache.amazonaws.com
 ```
 
-With a DNS hostname in `REDIS_URL`, default verification works and no override is needed.
+This override is read by the app's Redis client. It is not read by realtime, and the app's resolver applies it only to IPv4 literals. Setting it does not fix a shared IP-based URL for every service. Use a certificate-matching DNS URL for the deployment, especially for IPv6, or supply a separately valid realtime URL. The app checks this when it opens a Redis connection.
 
-## Verifying
+## Verify Redis
 
 ```bash
 # Kubernetes
-kubectl exec -n simstudio deploy/sim-app -- printenv REDIS_URL
+kubectl exec -n simstudio deploy/sim-app -- sh -c 'test -n "$REDIS_URL" && echo "REDIS_URL is set"'
+kubectl exec -n simstudio deploy/sim-realtime -- sh -c 'test -n "$REDIS_URL" && echo "REDIS_URL is set"'
 
 # Docker Compose
 docker compose -f docker-compose.prod.yml exec redis redis-cli ping   # PONG
 ```
 
-The functional test: open the same workflow in two browser windows served by different replicas and confirm edits appear in both. With a single replica this always passes, so scale to two before testing.
+The bundled `redis-cli ping` checks only that bundled instance; it does not test an external URL or the app's credentials. Review both service logs for connection errors. Then open the same workflow in browser sessions served by different replicas and confirm edits appear in both. A single-replica check does not verify cross-pod delivery.
 
 Watch the app logs at startup for `Redis` connection errors — a wrong password or unreachable host is logged there.
+
+## Related docs
+
+- [Scaling and high availability](/platform/self-hosting/scaling)
+- [Security and hardening](/platform/self-hosting/security)
diff --git a/apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx b/apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx
index 8df1ba75150..1e8fad6fad6 100644
--- a/apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/reference-architectures.mdx
@@ -1,20 +1,18 @@
 ---
-title: Reference Architectures
+title: Reference architectures
 description: What you provision and what the chart provisions, per cloud, before you run helm install
 ---
 
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 import { Callout } from 'fumadocs-ui/components/callout'
 
-Sim ships a Helm chart, not infrastructure-as-code. You bring a Kubernetes cluster and, in production, managed Postgres and object storage; the chart installs Sim on top. This page draws that line precisely so you can map it onto whatever Terraform, Bicep, or CloudFormation you already run, and decide what to provision before you reach [Kubernetes](/platform/self-hosting/kubernetes).
+Provision a Kubernetes cluster, durable database storage, object storage, networking, and secrets before installing Sim. The Helm chart installs application workloads on that infrastructure; it does not provision cloud resources.
 
-<Callout type="info">
-  There is no official Terraform module or CloudFormation template. The chart is the deployment interface, and it is what your own IaC should call — `helm_release` in Terraform, or a Helm task in your pipeline. Everything below describes the inputs that chart expects.
-</Callout>
+There is no official Terraform module or CloudFormation template. Call the chart from your infrastructure as code (IaC), for example with Terraform's `helm_release` or a Helm pipeline task.
 
 ## The boundary
 
-Everything the chart can run itself, it runs by default. That is convenient for evaluation and wrong for production, because two of those defaults keep state.
+The chart bundles PostgreSQL and Redis for evaluation. For production, decide how each stateful dependency is backed up, restored, and made available.
 
 | Component | Chart default | Production |
 |---|---|---|
@@ -25,7 +23,7 @@ Everything the chart can run itself, it runs by default. That is convenient for
 | Object storage | None — local disk | **Required.** S3, Azure Blob, or GCS. Local disk is lost when a container is recreated and is not shared across replicas |
 | Ingress | Off | You install the controller; the chart renders the Ingress |
 | TLS certificates | Off | You provision them |
-| Remote sandbox | Off | Required for Python, Shell, and imported JavaScript — a provider **and** an immutable Function image. See [Security](/platform/self-hosting/security) |
+| Remote sandbox | Off | Required for Python, Shell, and imported JavaScript — a provider **and** an immutable Function image. See [Sandboxes](/platform/self-hosting/sandboxes) |
 | Pi execution | Off | A separate image from the Function one, set with `E2B_PI_TEMPLATE_ID` (a template name, an alias, or an immutable `<template>:<build-id>` ref) or `DAYTONA_PI_SNAPSHOT_ID`. Unlike the Function base these are not format-validated, but execution still fails closed when unset |
 | PII redaction, Ollama, telemetry collector | Off | Optional, off unless you enable them |
 
@@ -35,16 +33,6 @@ The bundled Postgres uses a 10 Gi `ReadWriteOnce` volume and is intended for eva
   The AWS and GCP example values set `networkPolicy.enabled: true`, and the chart's default egress allows the bundled pods, DNS, and TCP 443 (minus the cloud metadata CIDRs). Moving Postgres or Redis outside the cluster without opening a path leaves them unreachable — add the rules to `networkPolicy.egress`, or set `networkPolicy.allowExternalEgress: true`, in the same change that points the app at the managed instance.
 </Callout>
 
-## Sizing
-
-| Component | Requests | Limits |
-|---|---|---|
-| app | 4 Gi / 1000m | 8 Gi / 2000m |
-| realtime | 512 Mi / 250m | 1 Gi / 500m |
-| PostgreSQL (bundled) | 1 Gi / 500m | 2 Gi (no CPU limit) |
-
-These are the chart defaults. Memory is the constraint rather than CPU, and the app's real ceiling depends on your execution load — see [Scaling](/platform/self-hosting/scaling) for the observed steady and peak figures, when to raise `app.resources.limits.memory`, and how to size replicas and connection pooling. Size nodes so a single app pod fits with headroom rather than packing them.
-
 ## Per-cloud requirements
 
 <Tabs items={['AWS (EKS)', 'Azure (AKS)', 'GCP (GKE)']}>
@@ -56,9 +44,9 @@ Use `helm/sim/examples/values-aws.yaml` as a starting point. It configures EBS G
 
 | Resource | Notes |
 |---|---|
-| EKS cluster | Kubernetes 1.25 or newer |
-| EBS CSI driver add-on | `aws eks create-addon --addon-name aws-ebs-csi-driver`. Without it, PersistentVolumeClaims never bind |
-| gp3 StorageClass | EKS ships only `gp2`. The example values set `storageClass: gp3`, so create it — or change the value — before installing |
+| EKS cluster | A supported cloud-provider Kubernetes release compatible with the chart's `>=1.25` minimum |
+| EBS CSI driver add-on | For a standard EKS cluster using the EBS CSI provisioner, install `aws-ebs-csi-driver` with the cluster name and region. Match the StorageClass provisioner to the cluster's storage mode |
+| gp3 StorageClass | The example selects `gp3`. Confirm that StorageClass exists and uses the provisioner installed in your cluster; create it or select an existing class before installing |
 | AWS Load Balancer Controller | Required for ALB ingress |
 | ACM certificate | ALB discovers it from the ingress hosts, or pin it with `alb.ingress.kubernetes.io/certificate-arn` |
 | RDS PostgreSQL | With the `vector` extension available. Reachable from the cluster subnets |
@@ -66,7 +54,7 @@ Use `helm/sim/examples/values-aws.yaml` as a starting point. It configures EBS G
 | ElastiCache | Optional; the bundled Redis is a supported alternative |
 
 <Callout type="warn">
-  cert-manager does not work with ALB. ALB cannot serve a Kubernetes TLS Secret, so certificates must come from ACM. This is the most common first-deploy failure on EKS.
+  ALB does not consume a Kubernetes TLS Secret directly. Supply an ACM certificate or a supported certificate-discovery configuration. A cert-manager-created Secret alone is not sufficient.
 </Callout>
 
 **Identity.** Bind an IAM role to the ServiceAccount with IRSA rather than issuing static keys. The role needs S3 access to the buckets you configured; grant nothing else unless you have enabled a feature that needs it.
@@ -76,18 +64,18 @@ Use `helm/sim/examples/values-aws.yaml` as a starting point. It configures EBS G
   </Tab>
   <Tab value="Azure (AKS)">
 
-Use `helm/sim/examples/values-azure.yaml` as a starting point. It configures `managed-csi` / `managed-csi-premium` storage, NGINX ingress, role-based node targeting, and NVIDIA GPU node pool tolerations for Ollama.
+The Azure example provides `managed-csi` / `managed-csi-premium` storage, node targeting, and GPU tolerations. Its ingress-nginx configuration is legacy: that community controller [retired in March 2026](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/). For a new deployment, configure a maintained ingress controller supported by your AKS environment; [Networking](/platform/self-hosting/networking) describes the required behavior.
 
 **You provision**
 
 | Resource | Notes |
 |---|---|
-| AKS cluster | Kubernetes 1.25 or newer |
-| NGINX ingress controller | The example values assume it |
-| cert-manager with a ClusterIssuer | Issues the ingress TLS secret |
+| AKS cluster | A supported cloud-provider Kubernetes release compatible with the chart's `>=1.25` minimum |
+| Ingress controller | A maintained controller supported by your cluster; adapt the legacy example's annotations |
+| TLS certificate mechanism | Match your selected ingress controller. For one that consumes TLS Secrets, cert-manager with a ClusterIssuer can issue the Secret |
 | Azure Database for PostgreSQL | With `pgvector` enabled |
 | Azure Blob Storage containers | One per file purpose |
-| Azure Cache for Redis | Optional |
+| Managed Redis | Optional; select a configuration compatible with Sim's single-endpoint clients. Existing Azure Cache for Redis deployments need [retirement/migration planning](https://learn.microsoft.com/en-us/azure/azure-cache-for-redis/retirement-faq) |
 | GPU node pool | Only for Ollama. Taint it `sku=gpu:NoSchedule` to match the example tolerations |
 
 **Identity.** Azure Blob authenticates with a storage account key or connection string — Sim has no Azure workload-identity path for Blob. Keep the key out of `app.env` by supplying `AZURE_ACCOUNT_KEY` or `AZURE_CONNECTION_STRING` through `app.secrets.existingSecret` or External Secrets.
@@ -101,7 +89,7 @@ Use `helm/sim/examples/values-gcp.yaml` as a starting point. It configures Persi
 
 | Resource | Notes |
 |---|---|
-| GKE cluster | Kubernetes 1.25 or newer |
+| GKE cluster | A supported cloud-provider Kubernetes release compatible with the chart's `>=1.25` minimum |
 | Workload Identity | Must be enabled for the IAM-bound ServiceAccount |
 | Global static IP | Reserved before install. The example annotates `kubernetes.io/ingress.global-static-ip-name: simstudio-ip`; nothing in the chart creates it |
 | ManagedCertificate | Created before the first deploy — nothing in the chart creates it. The example values reference `simstudio-ssl-cert`; match whatever name your ingress annotation uses |
@@ -110,7 +98,7 @@ Use `helm/sim/examples/values-gcp.yaml` as a starting point. It configures Persi
 | Memorystore | Optional |
 
 <Callout type="warn">
-  With a ManagedCertificate, keep `ingress.tls.enabled: false`. Leaving chart TLS on points the ingress at a Secret nothing creates, and the GKE controller reports sync errors for it. GCE Ingress *can* terminate TLS from a Secret you provision — including one cert-manager issues — so that is a supported alternative to a ManagedCertificate; what does not work is enabling both.
+  When using only a ManagedCertificate, keep `ingress.tls.enabled: false` so the chart does not reference a missing Secret. GCE Ingress also supports provisioned TLS Secrets and can retain self-managed certificates while a managed certificate becomes active. If you enable chart TLS, create the referenced Secret. See [Google's certificate setup and migration guide](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/secure-traffic-management).
 </Callout>
 
 **Identity.** Workload Identity binds the ServiceAccount to a Google service account. Grant it object access to your buckets — and, because there is no private key in that mode, `roles/iam.serviceAccountTokenCreator` **on itself**, or signed upload and download URLs cannot be generated. Setting `GCS_CREDENTIALS_JSON` instead signs locally and needs no extra role. See [Object storage](/platform/self-hosting/object-storage).
@@ -130,13 +118,23 @@ The chart offers three strategies. Pick one before you write any IaC, because it
 | `app.secrets.existingSecret.enabled` + `.name` | A Kubernetes Secret carrying **every** key the app needs, under the standard key names — it is consumed wholesale via `envFrom`, so key remapping is not supported | You already manage secrets out of band |
 | External Secrets Operator | The operator itself, a `ClusterSecretStore` or `SecretStore` named in `externalSecrets.secretStoreRef.name`, entries in your cloud's secret manager, and `externalSecrets.remoteRefs.app.<KEY>` mappings | Most production deployments |
 
-The two non-inline modes fail in opposite directions, which is worth knowing before you pick one:
+Non-inline modes handle missing keys differently:
 
 - **`existingSecret` fails quietly.** The chart renders no Secret of its own, so a key absent from yours and from `app.env` is simply empty at runtime. A key you also set in `app.env` is inlined onto the pod spec, where it shadows the Secret — so the Secret is not always the source of truth.
 - **External Secrets fails loudly.** The chart refuses to render when a key is set in `app.env` but not mapped, on the grounds that a silently empty secret is worse than a failed install.
 
 See [Security](/platform/self-hosting/security) for the full secret inventory, which keys are unrecoverable if lost, and what to back up.
 
+## Sizing
+
+| Component | Requests | Limits |
+|---|---|---|
+| app | 4 Gi / 1000m | 8 Gi / 2000m |
+| realtime | 512 Mi / 250m | 1 Gi / 500m |
+| PostgreSQL (bundled) | 1 Gi / 500m | 2 Gi (no CPU limit) |
+
+These are chart defaults, not capacity benchmarks. Measure memory, CPU, execution concurrency, and database connections with representative workloads. See [Scaling](/platform/self-hosting/scaling) for pool budgets and sizing estimates. A node must fit an app pod plus system overhead.
+
 ## Calling the chart from Terraform
 
 If you already run Terraform, the chart is the resource to wrap — not something to reimplement. Point `repository` at the OCI registry and pin `version`; there is no need to vendor the repo.
@@ -152,7 +150,7 @@ resource "helm_release" "sim" {
   # release with new migrations.
   repository = "oci://ghcr.io/simstudioai/charts"
   chart      = "sim"
-  version    = "1.9.5"
+  version    = "1.11.8"
 
   # Or the classic repository, if your tooling does not speak OCI:
   #   repository = "https://charts.sim.ai"
@@ -179,6 +177,10 @@ resource "helm_release" "sim" {
   The example values files ship literal placeholders such as `your-secure-production-auth-secret-here`. That includes `postgresql.auth.password`. The chart only rejects empty values and its own `CHANGE-ME` strings, so a deployment that inherits those placeholders installs cleanly with a publicly known session-signing secret and database password. Override every secret, or use External Secrets and set none of them inline.
 </Callout>
 
-Pin `version` above, and pin the image tags separately — the chart version and the application version move independently, so pinning one does not pin the other. See [Upgrades](/platform/self-hosting/upgrades).
+Pin `version` above. Empty image tags use the selected chart's `appVersion`, so a pinned chart also selects that default app version. Explicit image tags or digests override it; pin them separately when you need that control, and keep app, realtime, and migrations aligned. Chart `1.11.8` was published with app version `v0.9.17`; local checkout metadata can differ. See [Upgrades](/platform/self-hosting/upgrades).
+
+## Related docs
 
-Once the infrastructure exists, follow [Kubernetes](/platform/self-hosting/kubernetes) for the install itself, then the [pre-launch checklist](/platform/self-hosting/security) and the [verification checklist](/platform/self-hosting/verify).
+- [Install with Kubernetes](/platform/self-hosting/kubernetes)
+- [Pre-launch checklist](/platform/self-hosting/security#pre-launch-checklist)
+- [Verify your install](/platform/self-hosting/verify)
diff --git a/apps/docs/content/docs/platform/self-hosting/sandboxes.mdx b/apps/docs/content/docs/platform/self-hosting/sandboxes.mdx
index 753a23120c6..23ffa30ba9c 100644
--- a/apps/docs/content/docs/platform/self-hosting/sandboxes.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/sandboxes.mdx
@@ -1,27 +1,27 @@
 ---
 title: Sandboxes
-description: Configure the remote execution provider and Function base image that Python, Shell, and imported JavaScript run on
+description: Build and verify remote Function images for Python, Shell, and imported JavaScript
 ---
 
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 import { Callout } from 'fumadocs-ui/components/callout'
 
-Function blocks run in one of two places. JavaScript with no `import` or `require` runs in a local isolated VM and needs nothing configured — unless the block selects a sandbox, or references a file path from another block or a sandbox output path. Selecting a sandbox with no provider configured is refused with a **503**; the file-path cases need the sandbox filesystem and are refused with a **422**. Failing user code is also 422, so a 503 always means the deployment rather than the code. Python, Shell, JavaScript that imports, and custom workspace sandboxes run on a remote provider, and that provider needs both credentials and a dedicated Function base image.
+Configure a remote provider and a dedicated Function base image to run Python, Shell, JavaScript imports, or custom workspace sandboxes. Plain JavaScript can run in a local isolated-vm Node worker inside the app container.
 
-Until the base image is configured, those languages fail with an explicit configuration error rather than falling back. A saved Python block is never silently serialized or executed as JavaScript.
+## Choose the execution path
 
-## Flags
+| Code or block setting | Runtime requirement |
+|---|---|
+| JavaScript without `import` or `require`, no selected sandbox or sandbox file-path reference | Local worker; no remote provider required |
+| Python, Shell, JavaScript imports | Remote provider credentials and immutable Function image |
+| Selected workspace sandbox | Remote provider, Function base, and sandbox access |
+| File path from another block or sandbox output path | Remote sandbox filesystem |
 
-| Variable | Purpose |
-| --- | --- |
-| `SANDBOXES_ENABLED` | Grants the server-side self-hosted entitlement |
-| `NEXT_PUBLIC_SANDBOXES_ENABLED` | Browser gate for the Function block's Sandbox selector. An assertion of provider readiness, not a check; on a Compose install or source checkout, `npx sim-setup doctor` compares it with the selected provider's readiness |
+Selecting a sandbox without a configured provider is refused with 503. File-path cases that cannot use the sandbox filesystem are refused with 422. Failing user code can also return 422; inspect the error message to distinguish the cause. A saved Python block is never silently executed as JavaScript.
 
-Shell follows the server: a workspace offers it only when the Sandbox entitlement resolves on — `SANDBOXES_ENABLED=true`, or the `ENTERPRISE_ENABLED` master switch with `SANDBOXES_ENABLED` left unset — and the server has verified the provider credentials and an immutable Function base. **Settings → Sandboxes** stays in the sidebar either way, but shows an upgrade notice instead of the sandbox list until that check passes. `NEXT_PUBLIC_SANDBOXES_ENABLED` is a browser gate for one control, the Function block's Sandbox selector. Whether Python or a selected sandbox actually runs depends on the server-side provider and Function image, so set it only after those work, or you surface a selector for sandboxes that cannot run.
+## Build and verify the Function base
 
-## Building the Function base
-
-Build the base image before enabling the UI. Custom workspace sandboxes layer their packages on top of it.
+Run these repository scripts from a checkout with dependencies installed (`bun install` at the repository root). Supply provider credentials to the build environment. Custom workspace sandboxes layer their packages on this base.
 
 <Tabs items={['E2B', 'Daytona']}>
   <Tab value="E2B">
@@ -32,95 +32,114 @@ E2B_API_KEY=... \
   --name sim-function
 ```
 
-The builder uses E2B's maintained `code-interpreter-v1` base, assigns a fresh release generation, and prints both runtime values:
+The builder uses E2B's maintained `code-interpreter-v1` base and assigns a release generation. It prints the immutable template/build reference and generation. `--generation` supports release automation; `--base-template` accepts an immutable base override.
+
+Set the exact values printed by that build, then verify and capture its package/runtime manifest:
 
 ```bash
-SANDBOX_PROVIDER=e2b
-E2B_ENABLED=true
-E2B_API_KEY=...
-E2B_FUNCTION_TEMPLATE_ID=<sim-function-template>:<sim-function-build-id>
-E2B_FUNCTION_TEMPLATE_GENERATION=<release-epoch-ms>
-SANDBOXES_ENABLED=true
-NEXT_PUBLIC_SANDBOXES_ENABLED=true
+SANDBOX_PROVIDER=e2b \
+E2B_ENABLED=true \
+E2B_API_KEY=... \
+E2B_FUNCTION_TEMPLATE_ID='<template>:<build-id>' \
+E2B_FUNCTION_TEMPLATE_GENERATION='<release-epoch-ms>' \
+SANDBOX_PARITY_MANIFEST_OUT=/tmp/function-sandbox-manifest.json \
+  bun run apps/sim/scripts/verify-sandbox-parity.ts
 ```
 
-`--generation` remains available for release automation, and `--base-template` accepts an immutable base override when a deployment deliberately owns one.
+Replace the placeholders before running. Setting `SANDBOX_PROVIDER=e2b` explicitly prevents an exported Daytona selection from changing this verification step.
 
   </Tab>
   <Tab value="Daytona">
 
-The API key needs `write:snapshots` to build and `write:sandboxes` to execute.
-
-The builder pins Daytona's packages to an accepted E2B manifest, so build the E2B template first and capture its manifest with the verification step under [Promoting a build](#promoting-a-build) — `--parity-manifest` expects that file to exist.
+The API key needs `write:snapshots` to build and `write:sandboxes` to execute. The builder reconstructs packages from an accepted E2B manifest: complete the E2B build and verification first, even when Daytona is your runtime provider.
 
 ```bash
 DAYTONA_API_KEY=... \
   bun run apps/sim/scripts/build-function-daytona-snapshot.ts \
-  --name sim-function-2026-08-03 \
+  --name "sim-function-<release>" \
   --parity-manifest /tmp/function-sandbox-manifest.json
 ```
 
-Use the immutable snapshot ID the builder prints:
+Use the snapshot ID printed by the builder and verify it against the accepted E2B baseline:
 
 ```bash
-SANDBOX_PROVIDER=daytona
-DAYTONA_API_KEY=...
-DAYTONA_FUNCTION_SNAPSHOT_ID=<snapshot-uuid>
-SANDBOXES_ENABLED=true
-NEXT_PUBLIC_SANDBOXES_ENABLED=true
+SANDBOX_PROVIDER=daytona \
+DAYTONA_API_KEY=... \
+DAYTONA_FUNCTION_SNAPSHOT_ID='<snapshot-uuid>' \
+SANDBOX_PARITY_MANIFEST_BASELINE=/tmp/function-sandbox-manifest.json \
+  bun run apps/sim/scripts/verify-sandbox-parity.ts
 ```
 
+Replace the placeholders before running.
+
   </Tab>
 </Tabs>
 
 <Callout type="warn">
-  `E2B_FUNCTION_TEMPLATE_ID` and `DAYTONA_FUNCTION_SNAPSHOT_ID` fail closed when unset or mutable. The E2B value must be an exact `<template>:<build-id>` ref, and `E2B_FUNCTION_TEMPLATE_GENERATION` must be the monotonic value printed by the same build. The Daytona value must be a snapshot ID, not a name.
+  Function images must be immutable. `E2B_FUNCTION_TEMPLATE_ID` requires an exact `<template>:<build-id>` reference with a UUID build ID, plus the positive `E2B_FUNCTION_TEMPLATE_GENERATION` printed by that build. `DAYTONA_FUNCTION_SNAPSHOT_ID` requires a snapshot UUID, not a mutable name. Missing or invalid values do not fall back to a shell image.
 </Callout>
 
-## Promoting a build
+## Configure the deployment
 
-Use E2B as the release baseline before building or promoting Daytona.
+Apply the verified runtime values through the deployment's environment or secret mechanism:
 
-```bash
-# 1. Verify the exact E2B Function build and capture its accepted package/runtime surface.
-# SANDBOX_PROVIDER is set explicitly: an exported `daytona` would otherwise make
-# this step select Daytona and exit before writing the manifest.
-SANDBOX_PROVIDER=e2b \
-E2B_ENABLED=true \
-E2B_API_KEY=... \
-E2B_FUNCTION_TEMPLATE_ID=<sim-function-template>:<sim-function-build-id> \
-E2B_FUNCTION_TEMPLATE_GENERATION=<release-epoch-ms> \
-SANDBOX_PARITY_MANIFEST_OUT=/tmp/function-sandbox-manifest.json \
-  bun run apps/sim/scripts/verify-sandbox-parity.ts
+<Tabs items={['E2B', 'Daytona']}>
+  <Tab value="E2B">
 
-# 2. Pin Daytona's reconstructed packages to that accepted E2B manifest.
-DAYTONA_API_KEY=... \
-  bun run apps/sim/scripts/build-function-daytona-snapshot.ts \
-  --name sim-function-2026-08-03 \
-  --parity-manifest /tmp/function-sandbox-manifest.json
+```dotenv
+SANDBOX_PROVIDER=e2b
+E2B_ENABLED=true
+E2B_API_KEY=...
+E2B_FUNCTION_TEMPLATE_ID=<template>:<build-id>
+E2B_FUNCTION_TEMPLATE_GENERATION=<release-epoch-ms>
+```
 
-# 3. Verify the immutable Daytona snapshot against the same baseline before promotion.
-SANDBOX_PROVIDER=daytona \
-DAYTONA_API_KEY=... \
-DAYTONA_FUNCTION_SNAPSHOT_ID=<snapshot-uuid> \
-SANDBOX_PARITY_MANIFEST_BASELINE=/tmp/function-sandbox-manifest.json \
-  bun run apps/sim/scripts/verify-sandbox-parity.ts
+  </Tab>
+  <Tab value="Daytona">
+
+```dotenv
+SANDBOX_PROVIDER=daytona
+DAYTONA_API_KEY=...
+DAYTONA_FUNCTION_SNAPSHOT_ID=<snapshot-uuid>
 ```
 
-<Callout type="info">
-  Assign every promoted E2B Function base a generation greater than every prior deployment. A rollback is a new promotion and therefore also needs a new, higher generation — do not reuse the generation from the older release.
+  </Tab>
+</Tabs>
+
+### Enable sandbox access and controls
+
+| Variable | Effect |
+|---|---|
+| `SANDBOXES_ENABLED=true` | Grants the server-side sandbox entitlement on a billing-disabled self-hosted deployment |
+| `NEXT_PUBLIC_SANDBOXES_ENABLED=true` | Reveals the Function block's **Sandbox** selector; asserts readiness rather than checking it |
+
+On a billing-disabled deployment, `ENTERPRISE_ENABLED=true` also grants the entitlement when `SANDBOXES_ENABLED` is unset. The server must verify provider credentials and the immutable Function base before offering Shell and the sandbox list. **Settings → Sandboxes** remains in the sidebar but shows an upgrade notice until access/readiness resolves. Python remains selectable; execution still requires the remote configuration.
+
+Set the browser flag only after provider verification succeeds. On Compose or a source checkout, `bunx sim-setup doctor` compares the public flag with selected-provider readiness.
+
+## Promote or roll back a build
+
+Use the accepted E2B manifest as the release baseline. Verify the exact E2B build and any Daytona reconstruction before updating the deployment variables above.
+
+<Callout type="warn">
+  Every promoted E2B Function base needs a generation greater than every prior deployment. A rollback is a new promotion: assign a higher generation to the older build instead of reusing its old generation.
 </Callout>
 
-## Code tools in Chat
+## Configure other code images
 
-Chat's public `run_function` and `run_code` tools use a separate shell image, including for JavaScript without imports. The workflow-internal `function_execute` path uses the Function image instead. If your deployment uses those tools, configure that image for the selected provider as well:
+Chat's public `run_function` and `run_code` tools use a separate shell image, including plain JavaScript. The workflow-internal `function_execute` path uses the Function image.
 
-```bash
-# E2B
+```dotenv
+# E2B shell image
 MOTHERSHIP_E2B_TEMPLATE_ID=<shell-template-ref>
 
-# Daytona
+# Daytona shell image
 DAYTONA_SHELL_SNAPSHOT_ID=<shell-snapshot-ref>
 ```
 
-These values are selected only for code-tool calls. They never replace or act as a fallback for `E2B_FUNCTION_TEMPLATE_ID` or `DAYTONA_FUNCTION_SNAPSHOT_ID` — the shell, Function, document, and Pi images have separate package contracts and release cadences.
+These values do not replace `E2B_FUNCTION_TEMPLATE_ID` or `DAYTONA_FUNCTION_SNAPSHOT_ID`. Shell, Function, document, and Pi images have separate package contracts and release cadences. Pi also needs `E2B_PI_TEMPLATE_ID` or `DAYTONA_PI_SNAPSHOT_ID`; revealing a Pi mode with `NEXT_PUBLIC_E2B_ENABLED` does not supply that image.
+
+## Related docs
+
+- [Environment variables](/platform/self-hosting/environment-variables)
+- [Security and hardening](/platform/self-hosting/security)
diff --git a/apps/docs/content/docs/platform/self-hosting/scaling.mdx b/apps/docs/content/docs/platform/self-hosting/scaling.mdx
index 9ed0b608de0..10c09fbdd12 100644
--- a/apps/docs/content/docs/platform/self-hosting/scaling.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/scaling.mdx
@@ -1,10 +1,20 @@
 ---
-title: Scaling & High Availability
+title: Scaling and high availability
 description: Replicas, connection pooling, autoscaling, and where the limits actually are
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
+Configure shared storage, Redis, and database capacity before adding replicas. Measure your execution workload before choosing memory limits or autoscaling targets.
+
+## Prerequisites before scaling past one replica
+
+<Callout type="error">
+  Verify Redis connectivity before raising `replicaCount`. If you disable or remove bundled Redis, supply a working `REDIS_URL` for app and realtime. Process-local fallbacks do not deliver cross-pod events; see [Redis](/platform/self-hosting/redis).
+</Callout>
+
+You also need shared object storage — local-disk storage is per-pod, so a file uploaded through one replica is invisible to the others. See [Object Storage](/platform/self-hosting/object-storage).
+
 ## What scales how
 
 | Component | Scaling | Notes |
@@ -15,14 +25,6 @@ import { Callout } from 'fumadocs-ui/components/callout'
 | **redis** | Vertical / HA pair | Coordination only; small |
 | **cronjobs** | Fixed | One call per tick regardless of replica count |
 
-## Prerequisites before scaling past one replica
-
-<Callout type="error">
-  Redis must be reachable before you raise `replicaCount`. Both deployments ship it by default, so this is already satisfied unless you set `redis.enabled: false` (Helm) or removed the `redis` service (Compose) without supplying `REDIS_URL`. Without Redis, pub/sub falls back to a process-local emitter and the Socket.IO adapter has no cross-pod transport — realtime logs one line at startup noting single-pod mode, then drops cross-pod events silently. See [Redis](/platform/self-hosting/redis).
-</Callout>
-
-You also need shared object storage — local-disk storage is per-pod, so a file uploaded through one replica is invisible to the others. See [Object Storage](/platform/self-hosting/object-storage).
-
 ## Scaling the app
 
 ```yaml
@@ -39,7 +41,9 @@ app:
 
 The `resources` block above is the chart's default — it is shown so the numbers are visible, not because it changes anything. Only `replicaCount` needs setting unless you are raising the ceiling.
 
-**Memory is the constraint, not CPU.** Workflow executions run inside the app process in isolated-vm sandboxes, and file parsing happens in memory. Production telemetry shows 4–8 GB steady with peaks to 12 GB under heavy execution load. Under-provision memory and you get OOMKills that terminate in-flight workflow runs — so raise `limits.memory` above the 8 Gi default if your workload shows those peaks.
+The app orchestrates workflows, and local JavaScript runs in Node child workers inside its container. Those workers and in-memory file parsing share the pod's memory limit. OOMKills can terminate in-flight runs.
+
+Measure steady and peak memory with representative files, execution concurrency, and sandbox providers. The chart's 4 GiB request and 8 GiB limit are defaults, not measured capacity guarantees. Raise the limit or reduce concurrent work when your workload exceeds it; also measure CPU rather than assuming memory is always the bottleneck.
 
 A PodDisruptionBudget is created automatically once `replicaCount > 1`, or once `autoscaling.enabled` with `minReplicas > 1` (`maxUnavailable: 25%`). The app and realtime each consider their own `replicaCount`, but the autoscaling term is shared: `minReplicas > 1` creates both PDBs, including realtime's when `autoscaling.realtime.enabled` is false and no realtime HPA exists. Tighten it with `podDisruptionBudget.minAvailable` if you need to.
 
@@ -70,15 +74,24 @@ autoscaling:
 
 ## Database
 
-Postgres is where scaling eventually stops being about replicas.
+Database connection and storage capacity must support all app and realtime replicas.
 
 ### Connections
 
-Each app replica opens a pool. Total connections grow with replica count, and Postgres has a hard `max_connections`. A deployment that works at 2 replicas can exhaust connections at 6.
+Each process can open more than one database pool. Budget the sum of active pools across replicas and workers against PostgreSQL's `max_connections`, with headroom for migrations and administration.
 
-Budget it: `replicas × pool size + realtime + cronjobs + migrations + headroom` must stay under `max_connections`.
+| Pool | Default primary ceiling | Replica ceiling | Use |
+|---|---|---|---|
+| `web` | 10 | 4 | Main app pool |
+| `realtime` | 5 | 3 | Realtime process |
+| `trigger` | 5 | 2 | Trigger.dev worker process |
+| `exec` | 10 | 4 | Execution subpool profile; current `dbFor` client opens a primary pool |
+| `cleanup` | 5 | 2 | Cleanup subpool profile; current `dbFor` client opens a primary pool |
+| `search` | 5 | 0 | File-search subpool |
 
-For anything beyond a handful of replicas, put **PgBouncer** in transaction pooling mode in front of the database and point the chart at it with `externalDatabase.enabled: true`, `externalDatabase.host`, and `externalDatabase.port`, alongside `postgresql.enabled: false`. Both halves are required — with `postgresql.enabled: false` and `externalDatabase.enabled` still false the chart renders an empty `DATABASE_URL`. Setting `app.env.DATABASE_URL` does nothing — the chart computes `DATABASE_URL` itself and inlines it on the container, where it overrides anything from the Secret. This is the single highest-leverage change for a large deployment — it decouples app replica count from database connection count.
+App subpools are created lazily, so a web process using all three can open up to 30 primary connections in addition to its configured read-replica pool. Count the actual pools and URLs used by each process. CronJob pods make HTTP calls to the app; they do not open their own PostgreSQL pools.
+
+A pooler such as **PgBouncer** can separate app replica count from database connection count. Before using transaction pooling, verify the application's session-lock requirements and give the migrator a [direct, non-pooled connection](/platform/self-hosting/upgrades#migration-environment). Point the chart at the chosen endpoint with `externalDatabase.enabled: true`, `externalDatabase.host`, and `externalDatabase.port`, alongside `postgresql.enabled: false`. Both halves are required — with `postgresql.enabled: false` and `externalDatabase.enabled` still false the chart renders an empty `DATABASE_URL`. Setting `app.env.DATABASE_URL` does nothing — the chart computes `DATABASE_URL` itself and inlines it on the container, where it overrides anything from the Secret. Set the pooler's server-connection budget for your database and verify the resulting workload before increasing replicas.
 
 ### Read replicas
 
@@ -97,35 +110,35 @@ Reads fall back to the primary when unset. Per-role overrides exist if different
 | `DATABASE_REPLICA_URL_REALTIME` | The realtime service |
 | `DATABASE_REPLICA_URL_TRIGGER` | Trigger.dev workers |
 
-<Callout type="info">
-  Replicas lag. Sim routes only latency-tolerant reads to them, but if your replica lags badly, recently written logs may briefly not appear. Monitor replication lag.
-</Callout>
+Read replicas can lag. Recently written logs may briefly be absent from reads routed to a replica. Monitor replication lag and use the primary where immediate visibility is required.
 
 ### Sizing
 
-| Deployment | Instance | Storage |
+These are starting estimates for a managed database, not workload benchmarks:
+
+| Example deployment | Instance | Storage |
 |---|---|---|
-| Small (1–5 users) | 2 vCPU / 8 GB | 50 GB |
-| Standard (5–50 users) | 4 vCPU / 16 GB | 100 GB+ |
-| Large (50+ users) | 8+ vCPU / 32 GB+ | 250 GB+, auto-grow |
+| Small (1–5 users) | 2 vCPU / 8 GiB | 50 GiB |
+| Standard (5–50 users) | 4 vCPU / 16 GiB | 100 GiB+ |
+| Large (50+ users) | 8+ vCPU / 32 GiB+ | 250 GiB+, auto-grow |
 
-Knowledge base embeddings are the main growth driver — vector storage scales with document volume, not user count. Enable storage auto-increase.
+Embeddings, logs, and table data grow with usage and retention, not just member count. Measure query latency and data growth; configure storage growth and alerts for the selected database service.
 
 ## Execution concurrency
 
-`SCHEDULE_EXECUTION_CONCURRENCY_LIMIT` (default `30`) bounds scheduled executions per app instance. The other three `*_EXECUTION_CONCURRENCY_LIMIT` variables apply only to Trigger.dev and are inert on a default self-host — see [Background Jobs](/platform/self-hosting/background-jobs#concurrency).
+`SCHEDULE_EXECUTION_CONCURRENCY_LIMIT` (default `30`) bounds scheduled executions across the default database-backed queue. The other three `*_EXECUTION_CONCURRENCY_LIMIT` variables apply only to Trigger.dev and are inert on a default self-host — see [Background Jobs](/platform/self-hosting/background-jobs#concurrency).
 
-When executions queue but memory is fine, raise the limit; when memory is the ceiling, add replicas instead.
+Adding replicas does not multiply this shared cap. If the queue is full, consider raising it only with memory and database headroom. If memory is exhausted, reduce concurrency or add capacity before raising the limit.
 
 ## Rate limits and quotas
 
-Self-hosted deployments run **without plan limits by default** — no rate limits, execution timeouts, or table and storage caps. Each can be opted back in individually; the variable list and suggested values are in [Environment Variables](/platform/self-hosting/environment-variables#limits).
+Billing-disabled self-hosted deployments run **without plan limits by default**. Plan rate limits, execution timeouts, and table/storage caps can be opted back in individually. Fixed security, request-size, and admission controls still apply; the variable list and suggested values are in [Environment Variables](/platform/self-hosting/environment-variables#limits).
 
 An execution timeout is worth setting even on an otherwise unlimited deployment — it is what stops a runaway workflow from holding a sandbox indefinitely.
 
 ## Reference topology
 
-A production deployment serving ~100 active users:
+An illustrative topology with three minimum app replicas, two static realtime replicas, and a shared database pooler follows. It is not a throughput guarantee. With the shared HPA enabled, realtime also uses `minReplicas: 3` unless you set `autoscaling.realtime.enabled: false`.
 
 ```yaml
 app:
@@ -167,3 +180,8 @@ podDisruptionBudget:
 ```
 
 Plus: managed Postgres with PITR, managed Redis in an HA tier, object storage with versioning, and images pinned to an explicit tag.
+
+## Related docs
+
+- [Observability](/platform/self-hosting/observability)
+- [Upgrades](/platform/self-hosting/upgrades)
diff --git a/apps/docs/content/docs/platform/self-hosting/security.mdx b/apps/docs/content/docs/platform/self-hosting/security.mdx
index a60da61710a..e6d9a2cea50 100644
--- a/apps/docs/content/docs/platform/self-hosting/security.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/security.mdx
@@ -1,10 +1,38 @@
 ---
-title: Security & Hardening
+title: Security and hardening
 description: Secrets, network boundaries, code sandboxing, and the settings to review before going live
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { FAQ } from '@/components/ui/faq'
+
+Review access, secrets, networking, and code execution before exposing a self-hosted deployment. Use the checklist first, then follow the setup details below.
+
+## Pre-launch checklist
+
+- All five secrets generated fresh, stored in a secret manager, and **`ENCRYPTION_KEY` backed up separately**
+- `BETTER_AUTH_SECRET` identical on app and realtime
+- Images pinned to an explicit tag or digest on app, realtime, and migrations
+- TLS terminating at the ingress; HTTP redirected or disabled
+- `NEXT_PUBLIC_APP_URL` and `BETTER_AUTH_URL` set to the real public origin
+- `AUTH_TRUSTED_PROXIES` set if behind a load balancer
+- Signup restricted (`DISABLE_REGISTRATION` or `ALLOWED_LOGIN_DOMAINS`)
+- `DISABLE_AUTH` **not** set
+- NetworkPolicy enabled and `ingressFrom` scoped to the ingress controller
+- Namespace labelled `pod-security.kubernetes.io/enforce=restricted`, with the GPU device-plugin exception reviewed if GPU Ollama is enabled
+- Object storage buckets private, with CORS limited to your Sim origin
+- Database reachable only from the deployment — on Compose, no host `ports:` mapping on the `db` service, or one bound to `127.0.0.1` — with a generated `POSTGRES_PASSWORD`
+- TLS enforced (`sslMode: require`) on an externally managed database, or on the bundled one once you have configured it for TLS — the shipped Compose database does not enable it
+- Backups configured **and a restore rehearsed**
+- Sandbox strategy and required immutable images configured for user code
+- Stored PII policy and internal masking path verified if redaction is required
+
+## Restricting who can use the instance
+
+Signup allowlists and blocklists, social-login toggles, SSO, and the `DISABLE_AUTH` escape hatch are all covered in [Authentication](/platform/self-hosting/authentication). Restrict signup before exposing the instance, and never set `DISABLE_AUTH=true` behind an internet-facing ingress.
+
+## Client IP and forwarded headers
+
+Behind a load balancer, `X-Forwarded-For` is client-controllable. Set `AUTH_TRUSTED_PROXIES` to your proxies' actual addresses so Better Auth resolves the real client IP, and `TRUSTED_ORIGINS` if users reach Sim from more than one origin. Both are covered in [Authentication](/platform/self-hosting/authentication#behind-a-load-balancer).
 
 ## Secrets
 
@@ -14,25 +42,33 @@ Five secrets drive the security of a deployment. Generate each with `openssl ran
 |---|---|---|
 | `BETTER_AUTH_SECRET` | Session tokens | Yes — invalidates all sessions |
 | `ENCRYPTION_KEY` | Workspace env vars, stored provider keys, MCP OAuth credentials, deployment/chat secrets | **No** — see below |
-| `API_ENCRYPTION_KEY` | Reversible stored copy of user-generated API keys | **No** — existing keys keep authenticating, but their stored copy can no longer be displayed |
+| `API_ENCRYPTION_KEY` | Encrypted stored API-key material when configured | Rotation needs re-encryption; existing hash-based authentication continues, but old encrypted material cannot be decrypted with a new key |
 | `INTERNAL_API_SECRET` | Service-to-service calls | Yes — roll app and realtime together |
 | `CRON_SECRET` | Background job endpoints | Yes — roll app and cron together |
 
 <Callout type="error">
-  `ENCRYPTION_KEY` cannot be rotated without re-encrypting the data it protects, and cannot be recovered if lost. Changing it renders all of that data permanently unreadable. Back it up independently of the database.
+  Changing `ENCRYPTION_KEY` without re-encrypting existing data makes that data unreadable until the original key is restored. Losing the original key makes the data unrecoverable. Back it up independently of the database.
 </Callout>
 
 `BETTER_AUTH_SECRET` must be **identical** on the app and realtime services — they share sessions through the database, and a mismatch means realtime rejects every authenticated socket.
 
 ### Storing them
 
-In increasing order of production-readiness:
+Choose how to supply secrets:
 
 1. **`--set` on the command line** — dev only. Values appear in `helm get values` output and shell history.
 2. **A pre-created Kubernetes Secret** — set `app.secrets.existingSecret.enabled: true` and the secret name. Works with Sealed Secrets and SOPS. The secret is consumed wholesale and must use the standard key names.
 3. **External Secrets Operator** — sync from Vault, AWS Secrets Manager, Azure Key Vault, or GCP Secret Manager. Recommended.
 
-In the default mode the chart writes every key under `app.env` and `realtime.env` into a chart-managed Secret mounted via `envFrom`, so no value is inlined into a pod spec. Under External Secrets the chart renders no Secret of its own: a Secret of the same name is populated by the operator from `externalSecrets.remoteRefs.app`, and a non-empty `app.env` key that is not mapped there fails the render. (In `existingSecret` mode the pre-created Secret is the source of truth and any `app.env` values you still pass are rendered inline — supply everything through the Secret in that mode.) Either way, a secret committed to `values.yaml` is a secret in your git history.
+The delivery mode changes how values reach pods:
+
+| Mode | Behavior |
+|---|---|
+| Default | `app.env` and `realtime.env` keys go into a chart-managed Secret consumed through `envFrom` |
+| External Secrets | The operator populates the app Secret from `externalSecrets.remoteRefs.app`; an unmapped non-empty `app.env` key fails rendering |
+| `existingSecret` | The pre-created Secret supplies values. Non-empty `app.env` overrides are inlined on the pod and shadow Secret values; supply secrets through the Secret in this mode |
+
+A secret committed to `values.yaml` remains in Git history.
 
 ## Network boundaries
 
@@ -52,18 +88,18 @@ networkPolicy:
 ```
 
 <Callout type="warn">
-  `networkPolicy.ingressFrom` defaults to `[{}]` — an empty peer selector that allows ingress from **any pod in the cluster**. On a shared or multi-tenant cluster, scope it to your ingress controller:
+  With chart ingress enabled, `networkPolicy.ingressFrom` defaults to `[{}]`, which permits **any source** on the app and realtime ingress ports. Scope it to your ingress controller, especially on a shared or multi-tenant cluster. Replace `ingress-system` below with its actual namespace:
 
   ```yaml
   networkPolicy:
     ingressFrom:
       - namespaceSelector:
           matchLabels:
-            kubernetes.io/metadata.name: ingress-nginx
+            kubernetes.io/metadata.name: ingress-system
   ```
 </Callout>
 
-The policy already allows HTTPS (443) egress to everything except the metadata CIDRs, which covers model provider APIs, integration APIs, and cloud object-storage endpoints. It also allows the bundled Postgres and Redis by pod selector.
+The policy allows HTTPS (443) egress to everything except the metadata CIDRs, which covers model provider APIs, integration APIs, and cloud object-storage endpoints. It also allows the bundled Postgres and Redis by pod selector.
 
 What it does **not** cover is any datastore you run outside the chart — a managed Postgres or Redis on a non-443 port. Add a rule for each:
 
@@ -93,26 +129,26 @@ networkPolicy:
   allowExternalEgress: true
 ```
 
-This defaults to `false` because Sim's chart is deliberately stricter than the common chart default, which permits unrestricted egress.
+`allowExternalEgress` defaults to `false`. Enabling it removes the broad egress port restriction while retaining the configured metadata-address exclusions.
 
 ### Cloud metadata endpoints are blocked at two layers
 
-They are not equally firm, and it is worth knowing which is which.
+The pod policy and guarded application requests enforce different boundaries. Instance metadata endpoints can expose cloud credentials.
 
 | Layer | What it blocks | Can an operator lift it? |
 |---|---|---|
 | NetworkPolicy | The CIDRs in `networkPolicy.egressExceptCidrs`, defaulting to `169.254.169.254/32` and `169.254.170.2/32`, are excluded from the broad egress rule | **Yes** — it is an ordinary value. Setting it to `[]` keeps the defaults (Helm's `default` treats an empty list as unset), but supplying your own non-empty list without those two entries silently drops them |
 | Application | AWS/Azure/GCP IMDS, ECS task metadata, Alibaba, Oracle, the Azure WireServer, and IMDS over IPv6 | **No** — refused in code regardless of `EGRESS_ALLOWED_HOSTS` or `EGRESS_ALLOWED_IP_RANGES`, so allowlisting a broad range such as `169.254.0.0/16` cannot re-expose them |
 
-So a workflow can never reach instance metadata, but the pod-level block is only as good as the value you leave in place. If you override `egressExceptCidrs` to add your cluster's API server CIDR, keep both defaults in the list.
+Guarded application requests refuse these metadata destinations regardless of the allowlist. Remote sandbox networking has its own boundary; this is not a guarantee for arbitrary Python or Shell traffic. The pod-level block depends on the policy you configure. If you override `egressExceptCidrs` to add your cluster's API server CIDR, keep both defaults in the list.
 
-### The `copilot` deployment ships no NetworkPolicy
+### Optional Chat service NetworkPolicy
 
 The `copilot` and `copilot-postgresql` workloads deliberately have no policy of their own, and neither do the CronJob pods — nothing in the chart's policies selects them, so they are unisolated whenever `networkPolicy.enabled: true`. The `copilot` service requires `REDIS_URL` on a non-443 port, and the chart cannot know your Redis host at render time — a default egress rule would block Redis on most installs. If you run `networkPolicy.enabled: true` with `copilot.enabled: true`, those two pods are unisolated until you write dedicated NetworkPolicies for them. The chart-level `networkPolicy.egress` list does not reach them — it is only rendered into the policies the chart creates, and it creates none for these workloads.
 
 ### Pod Security Standards
 
-All workloads set `runAsNonRoot`, drop all Linux capabilities, disable privilege escalation, and use `seccompProfile: RuntimeDefault` — the four controls the `restricted` profile requires — with one exception. The NVIDIA device-plugin DaemonSet the chart renders when `ollama.gpu.enabled: true` sets only `allowPrivilegeEscalation` and `capabilities.drop`, and mounts three `hostPath` volumes that `restricted` forbids outright. Enforce it at the namespace level only when GPU Ollama is off, or exempt that DaemonSet. Label the namespace to enforce it:
+Chart workloads set `runAsNonRoot`, drop Linux capabilities, disable privilege escalation, and use `seccompProfile: RuntimeDefault`. Review the full Kubernetes `restricted` requirements and any extra volumes you add. The GPU device plugin is an exception: The NVIDIA device-plugin DaemonSet the chart renders when `ollama.gpu.enabled: true` sets only `allowPrivilegeEscalation` and `capabilities.drop`, and mounts three `hostPath` volumes that `restricted` forbids outright. Enforce it at the namespace level only when GPU Ollama is off, or exempt that DaemonSet. Label the namespace to enforce it:
 
 ```bash
 kubectl label namespace simstudio pod-security.kubernetes.io/enforce=restricted
@@ -126,8 +162,8 @@ Workflows can execute user-authored JavaScript and Python. Know which sandbox yo
 
 | Mode | Configuration | Isolation |
 |---|---|---|
-| **isolated-vm** (default) | none | In-process V8 isolate inside the app container. No network namespace or filesystem separation from the app process — isolation is at the JS-engine level. JavaScript only. |
-| **E2B** | `E2B_ENABLED=true`, `E2B_API_KEY`, `E2B_FUNCTION_TEMPLATE_ID`, `E2B_FUNCTION_TEMPLATE_GENERATION` | Remote sandbox per execution. Strongest isolation; requires outbound access to E2B. |
+| **isolated-vm** (default) | none | V8 isolate in a Node child worker inside the app container. The worker shares the container's network namespace and OS/filesystem context. JavaScript only. |
+| **E2B** | `E2B_ENABLED=true`, `E2B_API_KEY`, `E2B_FUNCTION_TEMPLATE_ID`, `E2B_FUNCTION_TEMPLATE_GENERATION` | Remote sandbox per execution; requires outbound access to E2B. Review the provider's isolation and network configuration. |
 | **Daytona** | `SANDBOX_PROVIDER=daytona`, `DAYTONA_API_KEY`, `DAYTONA_FUNCTION_SNAPSHOT_ID` | Remote sandbox per execution. |
 
 Python, Shell, JavaScript with external imports, and tooling-dependent blocks
@@ -136,7 +172,7 @@ Function base are not sufficient on their own: `SANDBOXES_ENABLED` grants the
 server-side entitlement (so does the `ENTERPRISE_ENABLED` master switch when `SANDBOXES_ENABLED`
 is left unset), and without that entitlement a workspace offers no Shell language and the
 Sandboxes settings page shows an upgrade notice even when the provider is configured correctly. JavaScript without `import` or `require`
-continues to run in the in-process isolate when no remote provider is configured.
+continues to run in the local isolate when no remote provider is configured.
 
 <Callout type="warn">
   **The credential alone does not enable a remote sandbox.** Each provider also needs an *immutable* reference to the dedicated Function image, and Sim validates the format before it will use it — an old shell template or snapshot name is deliberately not accepted as a fallback:
@@ -145,23 +181,23 @@ continues to run in the in-process isolate when no remote provider is configured
   - `E2B_FUNCTION_TEMPLATE_GENERATION` must be a positive integer release generation.
   - `DAYTONA_FUNCTION_SNAPSHOT_ID` must be the snapshot **ID** (a UUID), not the snapshot name — Daytona accepts a name anywhere it accepts an ID, and only the ID is immutable.
 
-  Set any of these wrong or leave one out and the deployment starts cleanly with the remote sandbox silently disabled.
+  Without valid provider credentials and the required Function image, code that needs a remote sandbox fails with a configuration error. Verify readiness before enabling its browser controls.
 </Callout>
 
-Two browser-side variables project server state into the UI, and neither is derived automatically:
+Two browser-side variables assert readiness in the UI; neither is derived automatically:
 
 | Variable | Effect when unset |
 |---|---|
 | `NEXT_PUBLIC_SANDBOXES_ENABLED` | The Function block's Sandbox selector stays hidden, even with a working provider. Shell and **Settings → Sandboxes** are unaffected — Shell appears, and the settings page swaps its upgrade notice for the sandbox list, from the server's own readiness check. Python stays selectable; whether it runs depends on the server-side provider and Function image, not on this flag |
 | `NEXT_PUBLIC_E2B_ENABLED` | The E2B-backed Pi block modes stay hidden; `sim-setup doctor` reports it as a mismatch against `E2B_ENABLED`. Revealing them is not enough to make them run — Pi executes on its own image, pinned with `E2B_PI_TEMPLATE_ID` or `DAYTONA_PI_SNAPSHOT_ID`, and fails closed without it |
 
-Set the public values only **after** the server-side configuration above is complete — they are assertions about readiness, not switches, and the server-side check has its own conditions beyond them. See [Sandboxes](/platform/self-hosting/sandboxes) for the base-image build and promotion procedure. `npx sim-setup doctor` reports a mismatch in either direction.
+Set the public values only **after** the server-side configuration above is complete — they are assertions about readiness, not switches, and the server-side check has its own conditions beyond them. See [Sandboxes](/platform/self-hosting/sandboxes) for the base-image build and promotion procedure. `bunx sim-setup doctor` reports a mismatch in either direction.
 
 <Callout type="warn">
-  With the default in-process sandbox, treat everyone who can author a workflow as someone running code in your app container's security context. If your Sim instance is open to a wide or partly-trusted audience, use a remote sandbox provider and enable the NetworkPolicy egress restrictions.
+  With the default local sandbox, treat everyone who can author a workflow as someone running code in your app container's security context. If your Sim instance is open to a wide or partly-trusted audience, use a remote sandbox provider and enable the NetworkPolicy egress restrictions.
 </Callout>
 
-Resource ceilings for the in-process path:
+Resource ceilings for the local-worker path:
 
 | Variable | Controls |
 |---|---|
@@ -172,7 +208,12 @@ Resource ceilings for the in-process path:
 
 ## The SSRF boundary
 
-By default Sim blocks outbound requests to private, reserved, and loopback addresses. This stops a workflow from being used to scan your internal network. Two things soften it on a self-hosted deployment: the provenances marked **Yes** below reach whatever you allowlist, and a configured endpoint, self-hosted service, or request target written as `localhost` or a loopback literal is reachable without any allowlist at all — a local Ollama or Jupyter is the ordinary case. That second carve-out stops short in two places: it does not lift the blocked-port list, and it does not extend to a database, cache, or mail connector on `localhost` — loopback is where Sim's own database and Redis listen, so reaching them has to be asked for. Neither softening applies on Sim Cloud. Every outbound request is classified by where its URL came from:
+Sim's outbound guard limits server-side request forgery (SSRF) by checking the destination and the source of a URL. Private, reserved, and loopback addresses are blocked except for the scoped self-hosted cases below.
+
+- The classes marked **Yes** can reach private destinations named in the operator allowlist.
+- Off Sim Cloud, a configured endpoint, self-hosted service, or request target written as `localhost` or a loopback literal is reachable without an allowlist. This supports local Ollama or Jupyter. It does not lift blocked ports or extend to a database, cache, or mail connector host.
+
+These exceptions do not apply on Sim Cloud. They describe guarded Sim requests, not every connection a remote sandbox or external SDK may make. The guard classifies each request by where its URL came from:
 
 | Provenance | Examples | Reaches allowlisted private destinations |
 |---|---|---|
@@ -183,7 +224,7 @@ By default Sim blocks outbound requests to private, reserved, and loopback addre
 | Content fetch | An image URL, a file imported by URL, a link from a third-party API response | **No** |
 | Proxy | The outbound HTTP proxy itself | **No** |
 
-Content fetches never reach a private destination, allowlist or not — that is the class where SSRF is actually exploited. Nor does the proxy: it is the component deciding where everything else may go, so it is held to public destinations regardless of what the allowlist says.
+Content fetches and proxy URLs do not use the private-destination allowlist. Their destinations must be publicly routable.
 
 Deployments frequently need to reach an internal service by name or address. Name the destinations:
 
@@ -192,9 +233,12 @@ EGRESS_ALLOWED_HOSTS=host.docker.internal,vllm.ai.svc.cluster.local
 EGRESS_ALLOWED_IP_RANGES=10.4.2.17/32,10.4.9.0/24
 ```
 
-A wildcard (`*.svc.cluster.local`) and a broad range (`10.0.0.0/8`) are accepted, but they hand every workflow author the whole namespace or network. Name the hosts you actually use.
+Wildcards such as `*.svc.cluster.local` and broad ranges such as `10.0.0.0/8` are accepted. They grant every workflow author access to the matching destinations; prefer specific hosts and narrow ranges.
+
+Both lists are validated at startup. A malformed entry stops Sim with an error naming the setting.
 
-Both lists are validated when Sim starts, and a malformed entry stops it with a message naming the setting. `EGRESS_ALLOWED_HOSTS` takes hostnames only — a URL or a CIDR is rejected — and a wildcard has to be a leading `*.` covering at least two labels, so `*.local` is refused and `*.svc.cluster.local` matches `vllm.ai.svc.cluster.local` but not the bare `svc.cluster.local`. `EGRESS_ALLOWED_IP_RANGES` takes CIDRs and bare addresses; a range shorter than `/8` (such as `0.0.0.0/1`) is refused as a near-catch-all, so `10.0.0.0/8` is the broadest a single entry can name.
+- `EGRESS_ALLOWED_HOSTS` accepts hostnames, not URLs or CIDRs. A wildcard must start with `*.` and cover at least two labels. `*.local` is refused; `*.svc.cluster.local` matches `vllm.ai.svc.cluster.local` but not bare `svc.cluster.local`.
+- `EGRESS_ALLOWED_IP_RANGES` accepts CIDRs and bare addresses. Prefixes shorter than `/8`, such as `0.0.0.0/1`, are refused as near-catch-alls. `10.0.0.0/8` is the broadest single accepted entry.
 
 On Sim Cloud, plain HTTP is refused for every provenance, self-hosted services included — nothing is vouched there, so a credential would cross the wire in the clear. The only exception is the proxy, whose scheme is fixed by protocol.
 
@@ -212,7 +256,7 @@ EGRESS_ALLOWED_HOSTS=host.docker.internal
 
 ### Upgrading from an earlier release
 
-The allowlist replaces four separate escape hatches, so a few deployments that worked before now need a destination named:
+Review these compatibility cases when upgrading:
 
 - **`ALLOW_PRIVATE_DATABASE_HOSTS`** still works, but it is deprecated and logs a warning at startup. It vouches for the whole private address space, loopback included, for database, cache, and mail connector hosts. Replace it with `EGRESS_ALLOWED_HOSTS` or `EGRESS_ALLOWED_IP_RANGES` naming the hosts you actually use.
 - **1Password Connect** on a private, non-loopback address, and an **MCP server** on a private address or reached through a DNS name that points at loopback, are no longer reachable implicitly. Name them.
@@ -226,21 +270,15 @@ The allowlist replaces four separate escape hatches, so a few deployments that w
 
 ### Response size cap
 
-Every response on the one-shot guarded fetch path is bounded. The pinned fetch that provider SDKs use sets no cap. A caller that does not set its own limit gets the default of **100 MB**; exceeding it rejects the request with a payload-size error and destroys the socket rather than buffering the rest.
-
-This is an easily misread cause of "a large download from an integration fails" — the failure looks like a broken connection to the third-party service rather than a limit Sim imposed. It applies to the guarded provenances above, not to the presigned object-storage upload path, and not to MCP's standalone SSE stream, which is deliberately unbounded so a long-lived stream is not cut off.
+Every response on the one-shot guarded fetch path is bounded. The pinned fetch that provider SDKs use sets no cap. A caller that does not set its own limit gets the default of **100 MiB**; exceeding it rejects the request with a payload-size error and destroys the socket rather than buffering the rest.
 
-## Client IP and forwarded headers
-
-Behind a load balancer, `X-Forwarded-For` is client-controllable. Set `AUTH_TRUSTED_PROXIES` to your proxies' actual addresses so Better Auth resolves the real client IP, and `TRUSTED_ORIGINS` if users reach Sim from more than one origin. Both are covered in [Authentication](/platform/self-hosting/authentication#behind-a-load-balancer).
-
-## Restricting who can use the instance
-
-Signup allowlists and blocklists, social-login toggles, SSO, and the `DISABLE_AUTH` escape hatch are all covered in [Authentication](/platform/self-hosting/authentication). The security-relevant summary: restrict signup before exposing the instance, and never set `DISABLE_AUTH=true` behind an internet-facing ingress.
+A large integration download can fail at this cap even when the provider is healthy. It applies to one-shot guarded fetches, not signed object-storage uploads or MCP's standalone SSE stream. That long-lived stream is deliberately unbounded.
 
 ## PII redaction
 
-The optional Presidio-based service supports the Guardrails PII block and, when enabled, automatic redaction of PII from workflow logs:
+The optional Presidio service supports the Guardrails PII block and configured workflow-data masking. Deploying it does not enable log redaction by itself.
+
+1. Enable the service and configure an internal app URL:
 
 ```yaml
 pii:
@@ -253,10 +291,20 @@ app:
 
 `INTERNAL_API_BASE_URL` must be the **in-cluster** Service URL. The redaction path calls the app's own API, and a public ingress URL is usually not hairpin-reachable from inside the cluster. Without a reachable value the path fails closed — affected fields are scrubbed to `[REDACTION_FAILED]` rather than leaking, but redaction does not actually run.
 
-With `networkPolicy.enabled: true` that self-call is blocked: the chart's app policy permits Postgres, Redis, realtime, Ollama, PII, telemetry, DNS, and TCP 443, but has no app-to-app rule. Add one, or set `networkPolicy.allowExternalEgress: true`:
+2. With `networkPolicy.enabled: true`, allow the app self-call in **both directions**. The chart has no app-to-app egress rule; after scoping `ingressFrom`, its inbound rules also omit app peers. Add matching rules, substituting your release name:
 
 ```yaml
 networkPolicy:
+  ingress:
+    - from:
+        - podSelector:
+            matchLabels:
+              app.kubernetes.io/name: sim
+              app.kubernetes.io/instance: <release>
+              app.kubernetes.io/component: app
+      ports:
+        - protocol: TCP
+          port: 3000
   egress:
     - to:
         - podSelector:
@@ -269,11 +317,14 @@ networkPolicy:
           port: 3000
 ```
 
-The service bundles ~2.2 GB of spaCy models, so first start takes around three minutes and it needs at least 4 GB of memory.
+3. Open **Settings → Organization → Data retention** and enable the **Logs** PII-redaction stage in the organization default or workspace override. Configure the entities and language to mask. See [Data retention](/platform/enterprise/data-retention) for policy inheritance and the separate input/block-output stages.
+4. Run a workflow with a sample sensitive value and inspect its stored log. Confirm the intended field is masked. `[REDACTION_FAILED]` indicates masking failed after policy was enabled; it is not a successful PII result.
+
+The service bundles about 2.2 GB of spaCy models. The chart requests 4 GiB and limits it to 8 GiB; allow for the model-loading cold start and measure startup time on your hardware. Multiple PII workers each load their own models.
 
 ## Postgres on Compose
 
-The Compose files do not publish the `db` service to the host: `simstudio`, `realtime`, and `migrations` reach it over the Compose network as `db:5432`, and nothing outside the stack can. `docker-compose.prod.yml` also refuses to start without `POSTGRES_PASSWORD`, the same way it refuses to start without `BETTER_AUTH_SECRET`.
+The Compose files do not publish `db` on a host port. `simstudio`, `realtime`, and `migrations` reach it over the Compose network as `db:5432`. `docker-compose.prod.yml` also refuses to start without `POSTGRES_PASSWORD`, the same way it refuses to start without `BETTER_AUTH_SECRET`.
 
 <Callout type="error">
   Installs created from an earlier Compose file published the database on every interface of the host (`5432:5432`), and a `POSTGRES_PASSWORD` left unset fell back to `postgres`. A Docker `ports:` mapping writes its own iptables rules, so a host firewall that looks like it blocks 5432 usually does not. Update the Compose file, then check what your database was created with:
@@ -281,7 +332,7 @@ The Compose files do not publish the `db` service to the host: `simstudio`, `rea
   - **You set `POSTGRES_PASSWORD` before the first start.** Nothing else to do — updating the file closes the port.
   - **You never set it.** Postgres applies `POSTGRES_PASSWORD` only when it creates the data volume, so the database still uses `postgres`. Set `POSTGRES_PASSWORD=postgres` in `.env` so the stack starts, then rotate it: run `docker compose -f docker-compose.prod.yml exec db psql -U postgres -c "ALTER ROLE CURRENT_USER PASSWORD '<new password>'"` (with your `POSTGRES_USER` in place of `postgres` if you set one), set `POSTGRES_PASSWORD` to the same value, and run `docker compose -f docker-compose.prod.yml up -d`. Setting a new value in `.env` alone does not change the database's password and locks the app out.
 
-  `npx sim-setup start` and `npx sim-setup update` write the right value for you and print the rotation steps.
+  `bunx sim-setup start` and `bunx sim-setup update` write the right value for you and print the rotation steps.
 </Callout>
 
 To reach the database from the host — `psql`, a desktop client, a backup job — use `docker compose -f docker-compose.prod.yml exec db psql -U postgres simstudio`, or pass a second Compose file that publishes it on loopback only and connect over an SSH tunnel:
@@ -294,26 +345,8 @@ services:
       - '127.0.0.1:5432:5432'
 ```
 
-## Pre-launch checklist
-
-- All five secrets generated fresh, stored in a secret manager, and **`ENCRYPTION_KEY` backed up separately**
-- `BETTER_AUTH_SECRET` identical on app and realtime
-- Images pinned to an explicit tag or digest on app, realtime, and migrations
-- TLS terminating at the ingress; HTTP redirected or disabled
-- `NEXT_PUBLIC_APP_URL` and `BETTER_AUTH_URL` set to the real public origin
-- `AUTH_TRUSTED_PROXIES` set if behind a load balancer
-- Signup restricted (`DISABLE_REGISTRATION` or `ALLOWED_LOGIN_DOMAINS`)
-- `DISABLE_AUTH` **not** set
-- NetworkPolicy enabled and `ingressFrom` scoped to the ingress controller
-- Namespace labelled `pod-security.kubernetes.io/enforce=restricted`
-- Object storage buckets private, with CORS limited to your Sim origin
-- Database reachable only from the deployment — on Compose, no host `ports:` mapping on the `db` service, or one bound to `127.0.0.1` — with a generated `POSTGRES_PASSWORD`
-- TLS enforced (`sslMode: require`) on an externally managed database, or on the bundled one once you have configured it for TLS — the shipped Compose database does not enable it
-- Backups configured **and a restore rehearsed**
-- Sandbox strategy decided for user code
+## Related docs
 
-<FAQ items={[
-  { question: "Can I rotate ENCRYPTION_KEY?", answer: "Not without re-encrypting everything it protects. Changing it makes workspace environment variables, stored provider API keys, MCP OAuth credentials, and deployment secrets permanently unreadable. Treat it as a permanent, backed-up value rather than a rotating secret."},
-  { question: "Where does user-authored code run?", answer: "By default in an in-process V8 isolate inside the app container, which isolates at the JS-engine level but shares the container's network and filesystem context. For untrusted authors, or to run Python at all, use E2B or Daytona so each execution runs in a remote sandbox."},
-  { question: "Why does the chart's NetworkPolicy allow traffic from any pod?", answer: "networkPolicy.ingressFrom defaults to an empty peer selector as a simple default that works on any cluster. On a shared cluster you should scope it to your ingress controller's namespace."},
-]} />
+- [Authentication](/platform/self-hosting/authentication)
+- [Sandboxes](/platform/self-hosting/sandboxes)
+- [Verify your install](/platform/self-hosting/verify)
diff --git a/apps/docs/content/docs/platform/self-hosting/troubleshooting.mdx b/apps/docs/content/docs/platform/self-hosting/troubleshooting.mdx
index 1bfa5e25130..8630a836884 100644
--- a/apps/docs/content/docs/platform/self-hosting/troubleshooting.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/troubleshooting.mdx
@@ -1,19 +1,31 @@
 ---
 title: Troubleshooting
-description: Common issues and solutions
+description: Diagnose deployment, network, storage, model, and scheduler failures
 ---
 
-## Start here: `sim-setup doctor`
+Start with the checks for your deployment type, then follow the symptom below.
 
-On a production or local-development Compose install, or a source checkout, run the built-in checker first. It does not detect the Ollama stack. It catches most failures without you having to guess which subsystem is broken. It reads env files, so it is not a Kubernetes tool — on Helm, skip to the checks below.
+## Run `sim-setup doctor`
+
+On a production or local-development Compose install, or a source checkout, run the built-in checker first. It does not detect the Ollama stack. It checks configuration and common dependency failures. It reads env files, so it is not a Kubernetes tool — on Helm, skip to the checks below.
 
 ```bash
-npx sim-setup doctor
-npx sim-setup doctor --fix     # repair what it safely can
-npx sim-setup doctor --json    # machine-readable, for CI
+bunx sim-setup doctor
+bunx sim-setup doctor --fix     # repair what it safely can
+bunx sim-setup doctor --json    # machine-readable, for CI
 ```
 
-On a standalone Compose install, run it from the directory holding your `.env` and Compose file. From a source checkout, run it there — it resolves the per-application env files itself and needs no root `.env`. It exits `1` if anything failed, so it drops straight into a script. See [Verify Your Install](/platform/self-hosting/verify#sim-setup-doctor) for what each group of checks covers.
+On a standalone Compose install, run it from the directory holding your `.env` and Compose file. From a source checkout, run it there — it resolves the per-application env files itself and needs no root `.env`. It exits `1` when any check fails, so scripts can use the exit status. See [Verify Your Install](/platform/self-hosting/verify#sim-setup-doctor) for what each group of checks covers.
+
+## 502 Bad Gateway
+
+```bash
+# Check app is running — use the file that started your install
+docker compose -f docker-compose.prod.yml ps simstudio
+docker compose -f docker-compose.prod.yml logs simstudio
+
+# Common causes: out of memory, database not ready
+```
 
 ## Database connection failed
 
@@ -31,103 +43,97 @@ docker compose -f "$COMPOSE_FILE" exec db psql -U postgres -c "SELECT 1"
 
 Verify `DATABASE_URL` format: `postgresql://user:pass@host:5432/database`
 
-## Ollama models not showing
+## Migration errors
 
-Inside Docker, `localhost` = the container, not your host machine.
+Migrations run in their own `migrations` service and image — the app image does not contain the migration tooling.
 
 ```bash
-# For host-machine Ollama, use:
-OLLAMA_URL=http://host.docker.internal:11434  # macOS/Windows
-OLLAMA_URL=http://192.168.1.x:11434           # Linux (use actual IP)
+# View migration logs
+docker compose -f docker-compose.prod.yml logs migrations
+
+# Re-run them
+docker compose -f docker-compose.prod.yml up --force-recreate migrations
 ```
 
-## A workflow cannot reach a service on your network
+On Kubernetes, migrations are an init container on the app pod:
 
-Outbound requests to private, reserved, and loopback addresses are blocked by default, so a workflow pointed at your Docker host, a LAN service, or a Kubernetes service name fails with a message naming the blocker — the private or loopback address it resolved to, a blocked port, or `must use https:// to a public destination` when the URL is plain HTTP — and pointing at the allowlist variables.
+```bash
+kubectl logs -n simstudio deploy/sim-app -c migrations --tail=200
+```
 
-Name the destination:
+## pgvector not found
 
-```bash
-EGRESS_ALLOWED_HOSTS=host.docker.internal,*.svc.cluster.local
-EGRESS_ALLOWED_IP_RANGES=10.0.0.0/8
+Use the correct PostgreSQL image:
+```yaml
+image: pgvector/pgvector:pg17  # NOT postgres:17
 ```
 
-What naming a destination does and does not grant — plain HTTP, the blocked-port list, database hosts, cloud metadata, Sim Cloud — is covered once in [Security](/platform/self-hosting/security#the-ssrf-boundary).
+## Kubernetes app pods never become ready
 
-Two things this does not cover:
+Check the migrations init container first — a failed migration deliberately blocks the rollout:
 
-- Inside a container `localhost` is the container itself, so it will never reach a service on your host. Use `host.docker.internal` (the Compose files map it) and name it above.
-- URLs harvested from content or from a third-party API response — an image URL, a file imported by URL, an MCP OAuth endpoint on a different origin than the MCP server itself — never reach a private network, allowlist or not. Nor does an HTTP block's `proxyUrl`.
+```bash
+kubectl logs -n simstudio deploy/sim-app -c migrations --tail=200
+kubectl describe pod -n simstudio '<pod>'
+```
 
-## LM Studio requests route to Ollama
+Common causes: `DATABASE_URL` unreachable, the database user lacking rights to create the `vector` extension, or an OOMKill from insufficient memory. See [Upgrades](/platform/self-hosting/upgrades) for migration-failure recovery.
 
-Sim identifies dynamically discovered LM Studio and vLLM models by their `vllm/` prefix. If the endpoint is unavailable and you manually enter the raw LM Studio model identifier, Sim treats that unknown identifier as an Ollama model.
+## Kubernetes `ImagePullBackOff`
 
-1. Set `VLLM_BASE_URL`, and `VLLM_API_KEY` too if you enabled LM Studio's API authentication — without the key, discovery requests omit the bearer token and fail. No Compose file sets either for you — `docker-compose.ollama.yml` only sets `OLLAMA_URL` — so add them to the `.env` file next to your Compose file — `simstudio` declares `env_file: .env` in every shipped file — then recreate the service and confirm it landed:
+Either the tag does not exist in the registry (`helm get values sim` and check), or you are pulling from a private registry without `global.imagePullSecrets`. When mirroring into a private registry, set `global.useRegistryForAllImages: true` — otherwise third-party images still point at Docker Hub.
 
-   Use the Compose file that started your installation — `docker-compose.prod.yml` for the documented production setup, `docker-compose.local.yml` for a source-built stack, or `docker-compose.ollama.yml` if you started from the Ollama stack:
+## Kubernetes PostgreSQL pod pending
 
-   ```bash
-   COMPOSE_FILE=docker-compose.prod.yml   # or docker-compose.local.yml, docker-compose.ollama.yml
-   docker compose -f "$COMPOSE_FILE" up -d --force-recreate simstudio
-   docker compose -f "$COMPOSE_FILE" exec simstudio printenv VLLM_BASE_URL
-   ```
+```bash
+kubectl describe pvc -n simstudio
+```
 
-   An empty result means the variable never reached the container, and model discovery cannot run.
+Common causes are no default StorageClass, no PV provisioner, or a StorageClass that does not support `ReadWriteOnce`. Set `global.storageClass` to pick a specific one.
 
-2. In LM Studio, enable **Serve on Local Network** and API authentication so the container can connect safely.
-3. From Docker on macOS or Windows, use `http://host.docker.internal:1234` rather than `localhost`. On Linux, use the host IP.
-4. The server root and a URL ending in `/v1` are both accepted.
-5. Reload the workspace and select the discovered `vllm/<model-id>` option from the model picker.
+## Blank page after login
+
+1. Check browser console for errors
+2. Verify `NEXT_PUBLIC_APP_URL` matches your actual domain
+3. After collecting the error, try a fresh browser session to distinguish a stale session from a deployment failure
+4. Check that all services are running: `docker compose -f docker-compose.prod.yml ps`
 
 ## WebSocket and realtime not working
 
 1. Verify reverse proxy routes `/socket.io` to the realtime service (default port 3002). `NEXT_PUBLIC_SOCKET_URL` is only needed if realtime is on a separate host.
 2. Verify realtime service is running: `docker compose -f docker-compose.prod.yml ps realtime`
-3. Ensure reverse proxy passes WebSocket upgrades (see [Docker guide](/platform/self-hosting/docker))
-
-## 502 Bad Gateway
-
-```bash
-# Check app is running — use the file that started your install
-docker compose -f docker-compose.prod.yml ps simstudio
-docker compose -f docker-compose.prod.yml logs simstudio
+3. Ensure the proxy passes WebSocket upgrades (see [Networking](/platform/self-hosting/networking))
 
-# Common causes: out of memory, database not ready
-```
+## WebSockets disconnect every 30 seconds
 
-## Migration errors
+The load balancer's backend timeout is closing them. On GKE, attach a `BackendConfig` with `timeoutSec: 3600` to the realtime Service; on AWS, raise the ALB `idle_timeout`. Clients may reconnect; repeated disconnects still interrupt collaboration. See [Networking](/platform/self-hosting/networking).
 
-Migrations run in their own `migrations` service and image — the app image does not contain the migration tooling.
+## Agent output arrives all at once
 
-```bash
-# View migration logs
-docker compose -f docker-compose.prod.yml logs migrations
+Your reverse proxy is buffering the response stream. Set `proxy_buffering off` (Nginx) or `flush_interval -1` (Caddy). See [Networking](/platform/self-hosting/networking).
 
-# Re-run them
-docker compose -f docker-compose.prod.yml up --force-recreate migrations
-```
+## Collaboration breaks with multiple replicas
 
-On Kubernetes, migrations are an init container on the app pod:
+If members on different replicas do not see edits or live status, check Redis configuration and connectivity in both services. Pub/sub and the Socket.IO adapter have no cross-pod local fallback:
 
 ```bash
-kubectl logs -n simstudio deploy/sim-app -c migrations --tail=200
+kubectl exec -n simstudio deploy/sim-app -- sh -c 'test -n "$REDIS_URL" && echo "REDIS_URL is set"'
+kubectl exec -n simstudio deploy/sim-realtime -- sh -c 'test -n "$REDIS_URL" && echo "REDIS_URL is set"'
 ```
 
-## pgvector not found
+Both pods must have `REDIS_URL`. On Helm they share one Secret, so setting it under `app.env` covers both. See [Redis](/platform/self-hosting/redis).
 
-Use the correct PostgreSQL image:
-```yaml
-image: pgvector/pgvector:pg17  # NOT postgres:17
-```
+## App crashes at startup with a REDIS_TLS_SERVERNAME error
+
+The app requires `REDIS_TLS_SERVERNAME` for an IPv4-literal `rediss://` URL. That override is not read by realtime and does not cover IPv6 literals. Prefer a DNS hostname matching the certificate for the shared deployment; see [Redis](/platform/self-hosting/redis#tls-to-an-ip-address).
 
 ## Certificate errors (CERT_HAS_EXPIRED)
 
 Rule out expiry and clock drift first: the endpoint's certificate may genuinely have expired, or the host's clock may have drifted far enough to put a valid certificate outside its window. Check the certificate dates and the host date before changing any trust configuration — no CA bundle fixes either.
 
-That leaves two cases a bundle does address: the endpoint is signed by a private CA — a corporate TLS-inspecting proxy, or an internal service — or it serves an incomplete chain, omitting an intermediate. Adding the private root to `NODE_EXTRA_CA_CERTS` resolves the first. An incomplete chain is different: Node still fails with `UNABLE_TO_GET_ISSUER_CERT` because the missing intermediate has to be served by the endpoint, so repair the server's chain rather than expecting a bundle to cover it.
+For a private certificate authority (CA), such as a corporate TLS-inspecting proxy or an internal service, mount the trusted CA certificates and configure `NODE_EXTRA_CA_CERTS`. For `UNABLE_TO_GET_ISSUER_CERT`, check whether the endpoint omits an intermediate certificate and repair its served chain. A trusted bundle can contain multiple certificates, but adding a root alone does not supply a missing intermediate.
 
-For the private-CA case, the image already ships current CA certificates and runs as a non-root user, so installing packages inside it is not the fix. Mount your CA bundle and point Node at it — an incomplete chain is not fixed here, only on the server:
+The image ships CA certificates and runs as a non-root account. Mount your corporate CA bundle and set the runtime variable; do not disable verification. Verify the affected transport, because a client with explicit TLS `ca` settings may use its own trust configuration:
 
 ```yaml
 # docker-compose.prod.yml
@@ -156,32 +162,69 @@ app:
 
 `NODE_TLS_REJECT_UNAUTHORIZED=0` disables certificate verification entirely and should never be used outside a throwaway test.
 
-## Blank page after login
-
-1. Check browser console for errors
-2. Verify `NEXT_PUBLIC_APP_URL` matches your actual domain
-3. Clear browser cookies and local storage
-4. Check that all services are running: `docker compose -f docker-compose.prod.yml ps`
-
-## Windows-specific issues
+## A workflow cannot reach a service on your network
 
-These apply to running Sim **from source** for development, not to the Docker or Kubernetes deployments, which are unaffected by the host OS.
+Guarded requests to private and reserved addresses are blocked unless a supported self-hosted exception or allowlist applies. Loopback exceptions are scoped by URL provenance and port, so a workflow pointed at your Docker host, a LAN service, or a Kubernetes service name fails with a message naming the blocker — the private or loopback address it resolved to, a blocked port, or `must use https:// to a public destination` when the URL is plain HTTP — and pointing at the allowlist variables.
 
-**Turbopack errors on Windows:** use WSL2.
+Name the destination:
 
 ```bash
-wsl --install
+EGRESS_ALLOWED_HOSTS=host.docker.internal,vllm.ai.svc.cluster.local
+EGRESS_ALLOWED_IP_RANGES=10.4.2.17/32,10.4.9.0/24
 ```
 
-**Line ending issues:**
+What naming a destination does and does not grant — plain HTTP, the blocked-port list, database hosts, cloud metadata, Sim Cloud — is covered once in [Security](/platform/self-hosting/security#the-ssrf-boundary).
+
+Two things this does not cover:
+
+- Inside a container `localhost` is the container itself, so it will never reach a service on your host. Use `host.docker.internal` (the Compose files map it) and name it above.
+- URLs harvested from content or from a third-party API response — an image URL, a file imported by URL, an MCP OAuth endpoint on a different origin than the MCP server itself — never reach a private network, allowlist or not. Nor does an HTTP block's `proxyUrl`.
+
+## Ollama models not showing
+
+Inside Docker, `localhost` = the container, not your host machine.
+
 ```bash
-# Configure git to use LF
-git config --global core.autocrlf input
+# For host-machine Ollama, use:
+OLLAMA_URL=http://host.docker.internal:11434
 ```
 
+## LM Studio requests route to Ollama
+
+Sim identifies dynamically discovered LM Studio and vLLM models by their `vllm/` prefix. If the endpoint is unavailable and you manually enter the raw LM Studio model identifier, Sim treats that unknown identifier as an Ollama model.
+
+1. Set `VLLM_BASE_URL`, and `VLLM_API_KEY` too if you enabled LM Studio's API authentication — without the key, discovery requests omit the bearer token and fail. No Compose file sets either for you — `docker-compose.ollama.yml` only sets `OLLAMA_URL` — so add them to the `.env` file next to your Compose file — `simstudio` declares `env_file: .env` in every shipped file — then recreate the service and confirm it landed:
+
+   Use the Compose file that started your installation — `docker-compose.prod.yml` for the documented production setup, `docker-compose.local.yml` for a source-built stack, or `docker-compose.ollama.yml` if you started from the Ollama stack:
+
+   ```bash
+   COMPOSE_FILE=docker-compose.prod.yml   # or docker-compose.local.yml, docker-compose.ollama.yml
+   docker compose -f "$COMPOSE_FILE" up -d --force-recreate simstudio
+   docker compose -f "$COMPOSE_FILE" exec simstudio printenv VLLM_BASE_URL
+   ```
+
+   An empty result means the variable never reached the container, and model discovery cannot run.
+
+2. In LM Studio, enable **Serve on Local Network** and API authentication so the container can connect safely.
+3. With the shipped Compose host alias, use `http://host.docker.internal:1234` rather than `localhost`, including on Linux. If you use a custom container setup without that alias, configure it or use a reachable host IP.
+4. The server root and a URL ending in `/v1` are both accepted.
+5. Reload the workspace and select the discovered `vllm/<model-id>` option from the model picker.
+
+## File uploads fail with a CORS error
+
+The bucket's CORS policy does not allow your Sim origin. Uploads go directly from the browser to object storage via presigned `PUT`, so server-side configuration being correct is not enough.
+
+If small uploads succeed but cloud uploads over 50 MiB fail during completion, check the app logs for the provider's part-listing request. The server completes multipart uploads from provider-authoritative state; for S3, its identity needs `s3:ListMultipartUploadParts`. See [Object Storage](/platform/self-hosting/object-storage).
+
+## Knowledge base upload fails
+
+Embeddings need a provider — set `OPENAI_API_KEY`, configure Azure OpenAI, set `KB_EMBEDDING_MODEL=gemini-embedding-001` with a Gemini key, or set `KB_EMBEDDING_MODEL=ollama/<model>` with `OLLAMA_URL` to embed on your own Ollama. On a self-hosted deployment `OPENROUTER_API_KEY` also serves the OpenAI-family models on its own, as a fallback behind any OpenAI or Azure credentials you have. If one is configured, verify pgvector is installed on the database.
+
+A document that fails with `vector 0 has N unexpected dimensions` means `EMBEDDING_OUTPUT_DIMS` does not match what the model actually emits. The message names both widths. If the width the model returned is one of `384`, `768`, `1024`, `1536`, or `3072`, set the variable to it and recreate the knowledge base. If it is anything else, no column can store it — choose a model that emits one of those five instead, since setting an unstorable width silently falls back to `1536` and the next document fails the same way. Existing knowledge bases keep the width they were created with.
+
 ## Scheduled workflows never run
 
-The most common self-hosting surprise.
+Scheduled workflows need the scheduler and a deployed Schedule trigger.
 
 **Docker Compose** — check the `cron` service is running and read its logs:
 
@@ -198,7 +241,7 @@ kubectl get cronjobs -n simstudio
 kubectl get jobs -n simstudio --sort-by=.metadata.creationTimestamp | tail
 ```
 
-A stale `LAST SCHEDULE` or failing jobs usually means `CRON_SECRET` is missing or does not match between the cron pods and the app. Call the endpoint by hand to see the status code:
+For stale `LAST SCHEDULE`, inspect CronJob suspension, controller events, active Jobs, and scheduling deadlines. `Forbid` can skip a tick while an earlier Job is active. For a failed Job, inspect its logs; a 401 indicates authentication. Call the endpoint by hand to distinguish those cases:
 
 ```bash
 kubectl exec -n simstudio deploy/sim-app -- sh -c \
@@ -217,71 +260,27 @@ These are **polling** triggers, driven by the per-minute `/api/webhooks/poll/*`
 
 Microsoft Teams chat triggers are the different case: they use a Microsoft Graph subscription capped at about three days, renewed by the twice-daily `renew-subscriptions` job. If Teams triggers work for a couple of days and then stop, that job is not running. See [Background Jobs](/platform/self-hosting/background-jobs).
 
-## Collaboration breaks with multiple replicas
-
-Two users editing the same workflow stop seeing each other, or live status never updates — with no error anywhere.
-
-This is Redis. Pub/sub and the Socket.IO adapter have no cross-pod fallback:
-
-```bash
-kubectl exec -n simstudio deploy/sim-app -- printenv REDIS_URL
-kubectl exec -n simstudio deploy/sim-realtime -- printenv REDIS_URL
-```
-
-Both pods must have `REDIS_URL`. On Helm they share one Secret, so setting it under `app.env` covers both. See [Redis](/platform/self-hosting/redis).
-
-## App crashes at startup with a REDIS_TLS_SERVERNAME error
-
-`REDIS_URL` uses `rediss://` pointed at a bare IP address. TLS certificates cannot be verified against an IP, so set `REDIS_TLS_SERVERNAME` to the DNS name the certificate was issued for — or use a DNS hostname in the URL instead.
-
-## File uploads fail with a CORS error
-
-The bucket's CORS policy does not allow your Sim origin. Uploads go directly from the browser to object storage via presigned `PUT`, so server-side configuration being correct is not enough.
-
-If small uploads succeed but files over 50 MB fail during completion, check the app logs for the provider's part-listing request. The server completes multipart uploads from provider-authoritative state; for S3, its identity needs `s3:ListMultipartUploadParts`. See [Object Storage](/platform/self-hosting/object-storage).
-
-## Agent output arrives all at once
-
-Your reverse proxy is buffering the response stream. Set `proxy_buffering off` (Nginx) or `flush_interval -1` (Caddy). See [Networking](/platform/self-hosting/networking).
-
-## Websockets disconnect every 30 seconds
-
-The load balancer's backend timeout is closing them. On GKE, attach a `BackendConfig` with `timeoutSec: 3600` to the realtime Service; on AWS, raise the ALB `idle_timeout`. Clients reconnect, so this degrades rather than breaks. See [Networking](/platform/self-hosting/networking).
-
-## Knowledge base upload fails
-
-Embeddings need a provider — set `OPENAI_API_KEY`, configure Azure OpenAI, set `KB_EMBEDDING_MODEL=gemini-embedding-001` with a Gemini key, or set `KB_EMBEDDING_MODEL=ollama/<model>` with `OLLAMA_URL` to embed on your own Ollama. On a self-hosted deployment `OPENROUTER_API_KEY` also serves the OpenAI-family models on its own, as a fallback behind any OpenAI or Azure credentials you have. If one is configured, verify pgvector is installed on the database.
-
-A document that fails with `vector 0 has N unexpected dimensions` means `EMBEDDING_OUTPUT_DIMS` does not match what the model actually emits. The message names both widths. If the width the model returned is one of `384`, `768`, `1024`, `1536`, or `3072`, set the variable to it and recreate the knowledge base. If it is anything else, no column can store it — choose a model that emits one of those five instead, since setting an unstorable width silently falls back to `1536` and the next document fails the same way. Existing knowledge bases keep the width they were created with.
+## Credentials unreadable after a restore
 
-## Credentials Unreadable After a Restore
+Integrations show as connected but fail, or provider keys error on decrypt. `ENCRYPTION_KEY` does not match the value in use when the backup was taken. Restore the original key. A different key cannot decrypt that stored data.
 
-Integrations show as connected but fail, or provider keys error on decrypt. `ENCRYPTION_KEY` does not match the value in use when the backup was taken. There is no recovery — the original key must be restored.
+## Windows-specific issues
 
-## Kubernetes: App Pods Never Become Ready
+These apply to running Sim **from source** for development, not to the Docker or Kubernetes deployments, which are unaffected by the host OS.
 
-Check the migrations init container first — a failed migration deliberately blocks the rollout:
+**Turbopack errors on Windows:** run the source development environment in WSL2.
 
 ```bash
-kubectl logs -n simstudio deploy/sim-app -c migrations --tail=200
-kubectl describe pod -n simstudio <pod>
+wsl --install
 ```
 
-Common causes: `DATABASE_URL` unreachable, the database user lacking rights to create the `vector` extension, or an OOMKill from insufficient memory. See [Upgrades](/platform/self-hosting/upgrades) for migration-failure recovery.
-
-## Kubernetes: ImagePullBackOff
-
-Either the tag does not exist in the registry (`helm get values sim` and check), or you are pulling from a private registry without `global.imagePullSecrets`. When mirroring into a private registry, set `global.useRegistryForAllImages: true` — otherwise third-party images still point at Docker Hub.
-
-## Kubernetes: Postgres Pod Pending
-
+**Line ending issues:**
 ```bash
-kubectl describe pvc -n simstudio
+# Configure git to use LF
+git config --global core.autocrlf input
 ```
 
-Almost always no default StorageClass, no PV provisioner installed, or a StorageClass that does not support `ReadWriteOnce`. Set `global.storageClass` to pick a specific one.
-
-## Getting Help
+## Get help
 
 - [GitHub Issues](https://github.com/simstudioai/sim/issues)
 - [Slack](https://join.slack.com/t/sim-ott9864/shared_invite/zt-43lp8tc5v-0qrrqHGBKUsvQlpoouH~TA)
diff --git a/apps/docs/content/docs/platform/self-hosting/upgrades.mdx b/apps/docs/content/docs/platform/self-hosting/upgrades.mdx
index 1006325ae40..ebfc1e225e2 100644
--- a/apps/docs/content/docs/platform/self-hosting/upgrades.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/upgrades.mdx
@@ -3,14 +3,16 @@ title: Upgrades
 description: Pinning versions, running migrations safely, and rolling back
 ---
 
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Step, Steps } from 'fumadocs-ui/components/steps'
 
+Choose and pin a release, back up the database, and rehearse the migration before upgrading. Schema migrations are forward-only, so some rollbacks require a database restore and lose writes made after the backup.
+
 ## Pin your version
 
 <Callout type="warn">
-  Never run `:latest` in production. An unpinned tag means an unplanned restart can pull a new version with new migrations at an arbitrary time.
+  Pin a release tag or digest for production. `latest` can change between pulls; restarting with a pull policy that refreshes it can introduce an unplanned version and migration.
 </Callout>
 
 Sim publishes images to GHCR, tagged by release alongside `latest`:
@@ -22,7 +24,7 @@ ghcr.io/simstudioai/migrations
 ```
 
 <Callout type="error">
-  **Pin `app`, `realtime`, and `migrations` to the same tag.** They share a database schema. An app newer than its migrations runs against a schema missing columns it expects; an app older than its migrations runs against a schema it does not understand. Mismatched tags is the most common self-inflicted upgrade failure.
+  Keep `app`, `realtime`, and `migrations` on the same release. They share a schema; mismatched versions can expect missing columns or incompatible behavior. An application-only rollback needs verified compatibility with the migrated schema.
 </Callout>
 
 <Tabs items={['Kubernetes (Helm)', 'Docker Compose']}>
@@ -31,16 +33,16 @@ ghcr.io/simstudioai/migrations
 ```yaml
 app:
   image:
-    tag: "v1.2.3"  # a tag from the releases page
+    tag: "v0.9.17"  # a tag from the releases page
 realtime:
   image:
-    tag: "v1.2.3"  # a tag from the releases page
+    tag: "v0.9.17"  # a tag from the releases page
 migrations:
   image:
-    tag: "v1.2.3"  # a tag from the releases page
+    tag: "v0.9.17"  # a tag from the releases page
 ```
 
-When `image.tag` is unset it defaults to the chart's `appVersion`, which moves when you upgrade the chart. Setting it explicitly decouples the two. For maximum determinism, pin `image.digest` instead:
+When `image.tag` is unset it uses the selected chart's `appVersion`. Published chart `1.11.8` uses `v0.9.17`; local checkout metadata can differ. Setting tags explicitly decouples image selection from chart upgrades. For maximum determinism, pin `image.digest` instead:
 
 ```yaml
 app:
@@ -55,7 +57,7 @@ Images track `latest` by default. To pin, set `SIM_VERSION` in `.env` to a tag f
 
 ```bash
 # .env
-SIM_VERSION=v1.2.3
+SIM_VERSION=v0.9.17
 ```
 
 One variable drives all three schema-coupled images, so they cannot drift apart. The `cron` service is deliberately excluded — it only makes HTTP calls and shares no schema, so it tracks `latest` unless you pin `SIM_CRON_VERSION`.
@@ -63,54 +65,10 @@ One variable drives all three schema-coupled images, so they cannot drift apart.
   </Tab>
 </Tabs>
 
-## How migrations run
-
-Migrations are Drizzle SQL files plus registered script (data) migrations, applied by a dedicated image in one locked session. A failure in either stage fails the migration container.
-
-- **Kubernetes** — an **init container on the app Deployment**. Every app pod waits for migrations to complete before it starts, so a failed migration blocks the rollout instead of starting an app against a mismatched schema.
-- **Docker Compose** — a one-shot `migrations` service with `restart: no` that runs before the app.
-
-Migrations are **forward-only**. There are no down-migrations, which is why the pre-upgrade backup below is not optional.
-
-Migrations apply in sequence, so skipping several releases at once generally works mechanically. It is riskier — those combinations get less testing, and you take several releases' worth of behavior changes in one step. Upgrade in smaller increments where you can.
-
-### How concurrent replicas are handled
-
-Every app replica runs the full migrator — there is no leader. They are serialized by a **Postgres session advisory lock**, taken with a bounded try-lock loop rather than a blocking wait:
-
-1. One runner takes the lock and applies the pending files. The rest retry every 5 seconds.
-2. The applied files are journaled, so the runners that follow find nothing to do and exit.
-3. A runner that cannot get the lock within **30 minutes** fails with a message naming the deadline.
-
-Replicas racing each other is therefore not an exposure. The operator-visible failure mode is different and worth recognizing: **one wedged runner stalls everything behind it.** Every other replica sits waiting for up to 30 minutes and then fails, so a rollout can look hung for half an hour before producing an error — and the error surfaces on the replicas that were only waiting, not on the one actually stuck. Read the *earliest* migration container's logs, not the loudest.
-
-### Migration environment
-
-These control the migrator and are set on the `migrations` container, not the app.
-
-| Variable | Purpose |
-|---|---|
-| `MIGRATION_DATABASE_URL` | A **direct, non-pooled** DSN. Falls back to `DATABASE_URL`. Setting it also arms the backend-pid check that aborts the run if the session — and with it the advisory lock — is silently recycled mid-migration; with only `DATABASE_URL` set, that check is skipped |
-
-<Callout type="warn">
-  Set `MIGRATION_DATABASE_URL` if anything sits between Sim and Postgres. Session advisory locks and session-level `SET`s do not survive PgBouncer transaction pooling — the lock silently does not hold, and consecutive statements can land on different backends. Point it at the database directly, bypassing the pooler.
-
-  The chart has no values key for it: the migrations init container builds `DATABASE_URL` itself and reads only the database Secret, so setting it under `app.env` does not reach the migrator. On Helm the init container reads only the database Secret, and the chart's own Secret templates carry just the password — there is no supported key for this. Supply your own Secret through `postgresql.auth.existingSecret` (bundled) or `externalDatabase.existingSecret` (external) with the variable included, or run the migration image yourself against the direct DSN before upgrading. Compose is the same: its `migrations` service declares an explicit `environment:` list, so a value in `.env` alone does not reach it — add it to that service.
-</Callout>
-
-Behavior that is fixed in the migrator and not configurable, but that explains what you see in the logs:
-
-| Behavior | Value |
-|---|---|
-| Advisory-lock acquire deadline | 30 minutes, retried every 5s |
-| `lock_timeout` on the migration session | 5 seconds for ordinary DDL — a statement that waits longer fails with SQLSTATE `55P03`. An individual migration can set it to `0` for statements that must not be interrupted, such as `CREATE INDEX CONCURRENTLY`. `statement_timeout` is `0` on the same session by default, so a long migration is not cut off once it holds its locks — though a migration can narrow it for its own statements, as `0076_damp_vector.sql` does with a 180-second local setting |
-| SQL migration retry attempts | 8, with exponential backoff and jitter, and only for a lock timeout (`55P03`). Script (data) migrations run once — a failure there exits immediately. They also run with `lock_timeout = 0` and `statement_timeout = 0`, so one blocked on an app-held lock waits indefinitely: a stuck script migration looks like a hung migration container, not a `55P03` |
-| Connection attempts at startup | 10, for transient failures — `53300` (`too_many_connections`), `53400`, the `08xxx` connection-exception class, and socket-level errors such as `ECONNREFUSED`, `ECONNRESET`, `ETIMEDOUT`, `EHOSTUNREACH`, and `ENOTFOUND`. A database that is simply down is retried with backoff, not failed immediately |
-
-The `lock_timeout` deliberately trades a table-wide stall for a failed migration: without it, DDL waiting on an `AccessExclusiveLock` queues every other query on that table behind it for the whole wait.
-
 ## Upgrade procedure
 
+Before applying an upgrade, configure a direct, non-pooled `MIGRATION_DATABASE_URL` on the migrator if the app uses a pooler. Session advisory locks do not survive transaction pooling. Pass the URL through the migrator's database Secret on Helm or its explicit environment on Compose; `app.env` or `.env` alone does not reach it. See [Migration environment](#migration-environment) for the exact setup.
+
 <Steps>
 
 <Step>
@@ -157,15 +115,15 @@ Migration surprises are usually data-shaped rather than schema-shaped, so a stag
 
 ```bash
 helm upgrade sim oci://ghcr.io/simstudioai/charts/sim \
-  --version 1.9.5 \
+  --version 1.11.8 \
   --namespace simstudio \
   --values my-values.yaml
 ```
 
-Preview first if the chart version changed:
+Preview changed chart values before applying. The following command requires the `helm-diff` plugin:
 
 ```bash
-helm diff upgrade sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.5 -n simstudio --values my-values.yaml
+helm diff upgrade sim oci://ghcr.io/simstudioai/charts/sim --version 1.11.8 -n simstudio --values my-values.yaml
 ```
 
 Then watch the rollout:
@@ -179,7 +137,7 @@ kubectl logs -n simstudio deploy/sim-app -c migrations --tail=100
   <Tab value="Docker Compose">
 
 ```bash
-npx sim-setup update
+bunx sim-setup update
 # The file that started your install. The Ollama stack is not managed by
 # the CLI at all — see below.
 COMPOSE_FILE=docker-compose.prod.yml
@@ -187,7 +145,7 @@ COMPOSE_FILE=docker-compose.prod.yml
 docker compose -f "$COMPOSE_FILE" logs migrations
 ```
 
-`npx sim-setup update` obtains the new images, then brings the stack up with
+`bunx sim-setup update` obtains the new images, then brings the stack up with
 `docker compose up -d`, keeping data volumes. What it runs depends on which Compose file the
 install uses:
 
@@ -196,9 +154,11 @@ install uses:
 | `docker-compose.prod.yml` | Refreshes its managed copy of the Compose file, writes `POSTGRES_PASSWORD` to `.env` if it is missing, then `docker compose pull` — the versions configured by `SIM_VERSION`, or `latest` when unset |
 | `docker-compose.local.yml` | `docker compose build --pull` — rebuilds from source against refreshed base images, no pull of published images |
 
-Inspect the result with `npx sim-setup logs`, which targets whichever Compose file the install uses.
+Inspect the result with `bunx sim-setup logs`, which targets whichever Compose file the install uses.
 
-`docker-compose.prod.yml` requires `POSTGRES_PASSWORD`. If you manage the file yourself and Compose stops with `required variable POSTGRES_PASSWORD is missing a value`, your database was created with the password `postgres` — set exactly that in `.env`, not a new value, then see [Postgres on Compose](/platform/self-hosting/security#postgres-on-compose) to rotate it.
+`docker-compose.prod.yml` requires `POSTGRES_PASSWORD`. If you manage the file yourself and Compose stops with `required variable POSTGRES_PASSWORD is missing a value`, confirm which password initialized the existing database volume. If it was never set, the old default was `postgres`; restore that value first, then see [Postgres on Compose](/platform/self-hosting/security#postgres-on-compose) to rotate it.
+
+Before updating a pinned production install, replace `SIM_VERSION` in `.env` with the chosen release tag. The update command pulls that configured tag; it does not automatically advance a pin.
 
 The CLI detects only those two files. An install started from `docker-compose.ollama.yml` is invisible to it: `update`, `logs`, and `status` report no install, or — in a source checkout that also carries per-application env files — report that checkout's dev install instead. Upgrade that stack directly:
 
@@ -222,7 +182,7 @@ docker compose -f docker-compose.ollama.yml --profile "$PROFILE" up -d
   On a standalone `docker-compose.prod.yml` install it also refuses to overwrite its managed Compose file if you have edited it by hand, comparing the file against the hash it recorded in `.sim-setup.json`: preserve or remove your customizations first.
 </Callout>
 
-There is a short window where the app is unavailable while containers restart. Compose has no rolling-update mechanism — plan a maintenance window, or run Kubernetes if you need zero-downtime upgrades.
+Compose does not provide rolling updates. Plan a maintenance window while containers restart. Kubernetes supports rolling deployments, but database compatibility and in-flight execution behavior still need a rehearsal.
 
   </Tab>
 </Tabs>
@@ -239,6 +199,43 @@ Run the [verification checklist](/platform/self-hosting/verify). At minimum: sig
 
 </Steps>
 
+## Rolling back
+
+**Application-only rollback** is possible when no migrations ran, or when you have verified the previous app is compatible with the migrated schema. Additive migrations alone do not prove compatibility:
+
+```bash
+helm rollback sim -n simstudio
+```
+
+```bash
+# Production Compose — set SIM_VERSION in .env so the pin persists, replacing
+# any existing line rather than appending a second one. Substitute the previous
+# release tag from the releases page.
+docker compose -f docker-compose.prod.yml up -d
+```
+
+The local and Ollama stacks build the app from source and ignore `SIM_VERSION`, so roll those back by checking out the previous tag and rebuilding with the file — and, for the Ollama stack, the profile — that started the install:
+
+```bash
+git checkout "<previous-release-tag>"
+
+# Local stack
+docker compose -f docker-compose.local.yml up -d --build
+
+# Ollama stack — the profile you installed with
+PROFILE=gpu  # or cpu
+docker compose -f docker-compose.ollama.yml --profile "$PROFILE" up -d --build
+```
+
+**Rollback after an incompatible schema change** requires restoring the pre-upgrade database backup. This loses writes made since the snapshot. Stop all writers before restoring:
+
+1. Stop traffic and all processes that can write to the database, including the app, realtime service, scheduled jobs, and any background workers.
+2. Restore the pre-upgrade database snapshot.
+3. Redeploy the previous image tag on the app, realtime, and migrations services, then resume the matching background workers and scheduler.
+4. Verify.
+
+Run the verification checklist before reopening traffic. Preserve the original encryption secrets with the restored database.
+
 ## When a migration fails
 
 The app pods will not become ready — this is by design.
@@ -264,39 +261,60 @@ Common causes:
 
 Do not manually edit the migrations table to skip a failed migration — the schema and Sim's expectations will diverge in ways that surface much later.
 
-## Rolling back
+## Migration reference
 
-**Application-only rollback** (no migrations ran, or the new migrations are additive):
+Migrations are Drizzle SQL files plus registered script (data) migrations, applied by a dedicated image in one locked session. A failure in either stage fails the migration container.
 
-```bash
-helm rollback sim -n simstudio
-```
+- **Kubernetes** — an **init container on the app Deployment**. Every app pod waits for migrations to complete before it starts, so a failed migration blocks the rollout instead of starting an app against a mismatched schema.
+- **Docker Compose** — a one-shot `migrations` service with `restart: no` that runs before the app.
 
-```bash
-# Production Compose — set SIM_VERSION in .env so the pin persists, replacing
-# any existing line rather than appending a second one. Substitute the previous
-# release tag from the releases page.
-docker compose -f docker-compose.prod.yml up -d
-```
+Migrations are **forward-only**. Take the backup described in the upgrade procedure before applying them; there are no down-migrations.
 
-The local and Ollama stacks build the app from source and ignore `SIM_VERSION`, so roll those back by checking out the previous tag and rebuilding with the file — and, for the Ollama stack, the profile — that started the install:
+Migrations apply in sequence, so skipping several releases at once generally works mechanically. It is riskier — those combinations get less testing, and you take several releases' worth of behavior changes in one step. Upgrade in smaller increments where you can.
 
-```bash
-git checkout <previous-release-tag>
+### How concurrent replicas are handled
 
-# Local stack
-docker compose -f docker-compose.local.yml up -d --build
+Every app replica runs the full migrator — there is no leader. They are serialized by a **Postgres session advisory lock**, taken with a bounded try-lock loop rather than a blocking wait:
 
-# Ollama stack — the profile you installed with
-PROFILE=gpu  # or cpu
-docker compose -f docker-compose.ollama.yml --profile "$PROFILE" up -d --build
-```
+1. One runner takes the lock and applies the pending files. The rest retry every 5 seconds.
+2. The applied files are journaled, so the runners that follow find nothing to do and exit.
+3. A runner that cannot get the lock within **30 minutes** fails with a message naming the deadline.
 
-**Rollback after a schema change** requires restoring the database to the pre-upgrade backup, because migrations are forward-only:
+A stuck runner holds up later replicas until their 30-minute lock-acquisition deadline. Inspect the earliest migration container's logs to find the holder; a later timeout may come from a runner that was only waiting.
 
-1. Stop traffic and all processes that can write to the database, including the app, realtime service, scheduled jobs, and any background workers.
-2. Restore the pre-upgrade database snapshot.
-3. Redeploy the previous image tag on the app, realtime, and migrations services, then resume the matching background workers and scheduler.
-4. Verify.
+### Migration environment
+
+These control the migrator and are set on the `migrations` container, not the app.
+
+| Variable | Purpose |
+|---|---|
+| `MIGRATION_DATABASE_URL` | A **direct, non-pooled** database connection URL (DSN). Falls back to `DATABASE_URL`. Setting it also arms the backend-pid check that aborts the run if the session — and with it the advisory lock — is silently recycled mid-migration; with only `DATABASE_URL` set, that check is skipped |
+
+<Callout type="warn">
+  Set `MIGRATION_DATABASE_URL` if anything sits between Sim and Postgres. Session advisory locks and session-level `SET`s do not survive PgBouncer transaction pooling — the lock silently does not hold, and consecutive statements can land on different backends. Point it at the database directly, bypassing the pooler.
+
+</Callout>
+
+Supply the migration URL separately from the app URL:
+
+| Deployment | How to pass `MIGRATION_DATABASE_URL` |
+|---|---|
+| Helm | The init container reads only the database Secret. Include the key in a Secret supplied through `postgresql.auth.existingSecret` or `externalDatabase.existingSecret`; `app.env` does not reach it. The chart-managed database Secret carries only the password, and there is no dedicated values key for the migration URL |
+| Compose | Add the variable to the `migrations` service's explicit `environment:` list. Setting it in `.env` alone does not pass it to that service |
+| Separate migration run | Run the migration image yourself with a direct DSN before upgrading |
+
+Behavior that is fixed in the migrator and not configurable, but that explains what you see in the logs:
+
+| Behavior | Value |
+|---|---|
+| Advisory-lock acquire deadline | 30 minutes, retried every 5s |
+| `lock_timeout` on the migration session | 5 seconds for ordinary DDL — a statement that waits longer fails with SQLSTATE `55P03`. An individual migration can set it to `0` for statements that must not be interrupted, such as `CREATE INDEX CONCURRENTLY`. `statement_timeout` is `0` on the same session by default, so a long migration is not cut off once it holds its locks — though a migration can narrow it for its own statements, as `0076_damp_vector.sql` does with a 180-second local setting |
+| SQL migration retry budget | 20 minutes, with exponential backoff and jitter, and only for a lock timeout (`55P03`). Script (data) migrations run once — a failure there exits immediately. They also run with `lock_timeout = 0` and `statement_timeout = 0`, so one blocked on an app-held lock waits indefinitely: a stuck script migration looks like a hung migration container, not a `55P03` |
+| Connection attempts at startup | 10, for transient failures — `53300` (`too_many_connections`), `53400`, the `08xxx` connection-exception class, and socket-level errors such as `ECONNREFUSED`, `ECONNRESET`, `ETIMEDOUT`, `EHOSTUNREACH`, and `ENOTFOUND`. A database that is simply down is retried with backoff, not failed immediately |
+
+The `lock_timeout` deliberately trades a table-wide stall for a failed migration: without it, DDL waiting on an `AccessExclusiveLock` queues every other query on that table behind it for the whole wait.
+
+## Related docs
 
-This loses everything written since the snapshot. It is why the pre-upgrade backup and a staging rehearsal matter more here than in most systems.
+- [Verify your install](/platform/self-hosting/verify)
+- [Security and hardening](/platform/self-hosting/security)
diff --git a/apps/docs/content/docs/platform/self-hosting/verify.mdx b/apps/docs/content/docs/platform/self-hosting/verify.mdx
index 254e18dc334..cb91fa4a538 100644
--- a/apps/docs/content/docs/platform/self-hosting/verify.mdx
+++ b/apps/docs/content/docs/platform/self-hosting/verify.mdx
@@ -1,117 +1,134 @@
 ---
-title: Verify Your Install
-description: Smoke-test the app, authentication, workflows, storage, and scheduled jobs
+title: Verify your install
+description: Check authentication, collaboration, execution, storage, and scheduled jobs
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
-Run this after a first install, an upgrade, or a restore. These checks cover the core deployment; also verify any optional features you enabled, such as SSO, SCIM, data drains, and remote sandboxes.
+Run these checks after installation, an upgrade, or a restore. Use a test workspace and the providers you configured. Also test optional features you enabled, such as SSO, SCIM, data drains, and remote sandboxes.
 
-## `sim-setup doctor`
+## Run doctor [#sim-setup-doctor]
 
-Run this first. It is the fastest signal you have, and it catches most bad installs before you open a browser.
+For Compose or a source checkout, run from the directory holding your env files:
 
 ```bash
-npx sim-setup doctor
+bunx sim-setup doctor
 ```
 
-Run it from the directory holding your `.env` and Compose file, or from a source checkout. It reports five groups:
+Doctor reports these groups:
 
-| Group | What it checks |
-|---|---|
-| **Env files** | Every `.env` the layout requires exists. `--fix` seeds a missing one from the example plus the values already in `apps/sim/.env` |
-| **Schema** | **Required** keys are present, are not still the example placeholder, are valid URLs where they should be, and have a usable shape — `ENCRYPTION_KEY` is checked as exactly 64 hex characters, the rest as a minimum length. Optional secrets are not shape-checked, so a malformed `API_ENCRYPTION_KEY` passes here and fails later at encrypt time. `--fix` generates missing or placeholder secrets |
-| **Consistency** | The same key agrees across files — `BETTER_AUTH_SECRET` between the app and realtime, and `DATABASE_URL` between the app and `packages/db` (a mismatch there means migrations ran against a different database). `--fix` mirrors the `apps/sim/.env` value |
-| **Coherence** | Configuration that is individually valid but jointly wrong: a feature flag whose dependency is unset, a storage provider that is half-configured, and a server flag whose `NEXT_PUBLIC_` twin disagrees with it |
-| **Live** | Postgres is reachable, pgvector is available, migrations are applied — on a standalone `npx sim-setup` install the published package carries no migration journal, so it can confirm what has been applied but not that it is current — Redis answers, and the running services respond on their ports. Doctor reads env files, so on the production Compose layout — where those values live inside the containers rather than in `.env` — the Postgres, migration, and Redis probes are skipped and only the HTTP health checks run |
+| Group | Checks and limits |
+| --- | --- |
+| Env files | Required env files exist. `--fix` seeds missing files from examples and values already in `apps/sim/.env`. |
+| Schema | Required keys are present, no longer placeholders, and have usable formats. `ENCRYPTION_KEY` is checked as 64 hex characters; other required secrets have minimum lengths. Optional secrets are not shape-checked, so an invalid `API_ENCRYPTION_KEY` can pass this group. |
+| Consistency | Shared secrets agree between app and realtime; the app and migrator point to the same database. `--fix` mirrors the app's value across split files. |
+| Coherence | Feature flags agree with dependencies, storage configuration is complete, and server flags agree with their UI counterparts. |
+| Live | Checks database reachability, pgvector, applied migrations, Redis, and HTTP health when their configuration is available. |
+
+Doctor reads env files, not live container configuration. Production Compose derives `DATABASE_URL` and Redis settings in the service definition, so those probes can be skipped when the keys are absent from `.env`. A standalone published package has no migration journal: it can report applied migrations, but cannot establish that they match a current checkout. Read the skipped findings and continue with the checks below.
+
+`--json` prints structured findings; the command exits `1` when a check fails. `--fix` writes env-file repairs and reruns the checks. Review those changes and recreate the affected services to apply them; retain existing encryption secrets on upgrades and restores.
 
 <Callout type="warn">
-  The check worth knowing about before you hit it: if `NEXT_PUBLIC_APP_URL` points at `sim.ai` or any subdomain of it, Sim treats the deployment as Sim's own hosted platform (`isHosted=true`) and disables self-host overrides. Doctor flags this. Use your own domain.
+  Use your own domain. A `NEXT_PUBLIC_APP_URL` on `sim.ai` or a subdomain identifies the instance as Sim Cloud and disables self-hosted overrides. Doctor flags this configuration.
 </Callout>
 
-Two flags matter:
+Doctor is not a Helm runtime diagnostic. For Kubernetes, use the infrastructure commands below. See [Setup commands](/platform/self-hosting/docker#the-sim-setup-cli) for the supported layouts and commands.
+
+## Core checks [#checklist]
 
-- `--fix` applies the safe repairs above and re-runs the checks. It never touches anything it cannot repair deterministically.
-- `--json` prints the findings as structured JSON instead of the report, so CI can gate on it. The command exits `1` when anything failed.
+| # | Action | Expected result | If it fails |
+| --- | --- | --- | --- |
+| 1 | Open the public URL and create an account. If registration is disabled, use a provisioned account. | App, database, TLS, and migrations work. | Read app and migrations logs. |
+| 2 | Sign out and sign back in. | Session handling works at the configured origin. | Compare `NEXT_PUBLIC_APP_URL`, `BETTER_AUTH_URL`, and the browser origin. |
+| 3 | Open a workflow, add blocks, and confirm the browser establishes its socket connection. | Realtime is reachable. | Check browser socket errors and proxy routing. |
+| 4 | Open that workflow in a second browser window and edit it. | Edits propagate between clients. | Check realtime and Redis configuration. |
+| 5 | Save a model API key in settings and run a two-block workflow. | Credential encryption, execution, and provider egress work. | Check app logs, `ENCRYPTION_KEY`, and outbound connectivity. |
+| 6 | Upload and download a small file in Files. | Storage works end to end. | Check signed-URL/CORS settings for cloud storage, or app/proxy logs for local storage. |
+| 7 | Upload a file larger than 50 MiB and confirm completion. | Multipart upload works on cloud or local storage. | Read part-upload and completion errors in app logs. |
 
-The full command list is in the [Docker guide](/platform/self-hosting/docker#the-sim-setup-cli). Doctor reads env files, so it covers Compose installs and source checkouts — it is not a Kubernetes tool. On Helm, use the infrastructure checks below.
+Two windows verify collaboration between clients. To establish cross-replica operation, also confirm their socket connections reach different realtime pods. A load balancer can send both windows to one process. Multi-replica operation requires `REDIS_URL` on the app and realtime services.
 
-## Checklist
+Cloud uploads use multipart above 50 MiB; local uploads use it above 8 MiB. Local parts pass through Sim, while cloud parts use signed provider URLs. See [Object storage](/platform/self-hosting/object-storage).
 
-| # | Do this | Proves | If it fails |
-|---|---|---|---|
-| 1 | Open your Sim URL and create an account | App, database, TLS, migrations | `kubectl logs deploy/sim-app` — and check the `migrations` init container |
-| 2 | Sign out and sign back in | Session handling, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL` | URLs must match your real origin exactly |
-| 3 | Open a workflow and drag two blocks into the editor | Realtime websocket connection | Browser console for socket errors; see [Networking](/platform/self-hosting/networking) |
-| 4 | Open the same workflow in a second browser window and edit | Cross-replica collaboration | With >1 replica this needs [Redis](/platform/self-hosting/redis) |
-| 5 | Paste a model API key in settings and run a two-block workflow | Execution engine, credential encryption, outbound network | App logs; check `ENCRYPTION_KEY` is set and outbound egress is allowed |
-| 6 | Upload a small file in Files | File storage end to end | With object storage configured: presigned URL + bucket CORS. On local disk: the upload proxies through the app |
-| 7 | Upload a file larger than 50 MB | Multipart upload path (object storage only) | Check app logs for provider part-listing or completion errors |
-| 8 | Create a knowledge base and upload a PDF | Document parsing, embeddings, pgvector | Needs an embedding provider — see below |
-| 9 | Invite a teammate from workspace settings | Email delivery | App logs for the mailer; see [Email](/platform/self-hosting/email) |
-| 10 | Connect an integration account | OAuth configuration | Redirect URI mismatch → see [Integrations & OAuth](/platform/self-hosting/integrations-oauth) |
-| 11 | Create a workflow with a Schedule trigger set to every minute, deploy it, wait 2 minutes | **Background jobs** | Check the scheduler's logs — see [Background Jobs](/platform/self-hosting/background-jobs) |
-| 12 | Trigger a workflow via the API with an API key | Public API and API-key auth | Check the key was created successfully in settings |
+## Feature checks
+
+Run the checks for each feature you intend to use:
+
+| # | Action | Expected result | Prerequisite or diagnosis |
+| --- | --- | --- | --- |
+| 8 | Create a knowledge base and upload a PDF. | Parsing, embeddings, and vector storage complete. | Configure an embedding provider and enable pgvector. |
+| 9 | Invite a teammate from workspace settings. | The invitation arrives and can be accepted. | Configure and verify email delivery. |
+| 10 | Connect an OAuth integration account. | The provider returns to Sim and the account is listed. | Match registered callbacks to the public origin. |
+| 11 | Deploy a workflow with a Schedule trigger set to every minute, then wait two minutes. | The workflow runs on schedule. | Confirm the scheduler is running and its `CRON_SECRET` matches the app. |
+| 12 | Use a Sim API key to trigger a workflow through the public API. | API-key authentication and execution work. | Enable the public API and use the intended key scope. |
 
 <Callout type="warn">
-  Step 11 is the one most people skip and most often discover broken weeks later. Scheduled workflows and every polling trigger depend on the scheduler, and a wrong or missing `CRON_SECRET` makes it fail silently from the app's side.
+  A healthy app does not prove scheduled work is running. Scheduled workflows and polling triggers depend on the scheduler; verify an actual run and inspect scheduler responses.
 </Callout>
 
+Knowledge bases can use OpenAI, Azure OpenAI, OpenRouter, or Gemini embeddings, or an Ollama model selected by `KB_EMBEDDING_MODEL=ollama/<model>` with `OLLAMA_URL`. See [Environment variables](/platform/self-hosting/environment-variables#knowledge-bases).
+
 ## Infrastructure checks
 
-After the checklist, confirm the deployment itself is healthy.
+For the Helm example release `sim` in namespace `simstudio`:
 
 ```bash
-# Everything running?
 kubectl get pods -n simstudio
-
-# Migrations completed
 kubectl logs -n simstudio deploy/sim-app -c migrations --tail=50
-
-# Health endpoints
 curl -fsS https://sim.yourdomain.com/api/health
-
-# Background jobs scheduled
 kubectl get cronjobs -n simstudio
-
-# Redis configured (multi-replica deployments) — confirms the variable is set,
-# not that Redis answers. Checklist steps 3 and 4 above are the real reachability test.
-kubectl exec -n simstudio deploy/sim-app -- printenv REDIS_URL
-```
-
-```bash
-# Docker Compose
-docker compose -f docker-compose.prod.yml ps
-docker compose -f docker-compose.prod.yml logs migrations
-curl -fsS http://localhost:3000/api/health
 ```
 
-All six should be present on Compose: `simstudio`, `realtime`, `db`, `redis`, `cron`, and a completed `migrations`.
+The migrations init container must complete before the app starts. Inspect failed CronJob pods and their logs; the presence of a schedule alone does not prove the endpoint call succeeded.
 
-## Reading the failures
+To check whether Redis is configured without printing the connection string:
 
-**Step 1 fails — app will not load.** Almost always migrations or database connectivity. Check the migrations init container first; a failed migration deliberately blocks the rollout.
-
-**Step 2 fails — login loops or rejects.** `NEXT_PUBLIC_APP_URL` or `BETTER_AUTH_URL` does not match the origin you are browsing. Both must be the exact public URL, with scheme and no trailing slash.
+```bash
+kubectl exec -n simstudio deploy/sim-app -- sh -c 'test -n "$REDIS_URL"'
+```
 
-**Step 3 fails — no live updates.** The reverse proxy is not passing websocket upgrades, or `/socket.io` is not routed to the realtime service. If realtime is on a separate hostname, `NEXT_PUBLIC_SOCKET_URL` must point at it and realtime's `ALLOWED_ORIGINS` must include the app origin.
+A zero exit status only confirms a non-empty variable. It does not prove Redis answers or that cross-pod events propagate; use the collaboration check above.
 
-**Step 4 fails — edits do not sync between windows.** With more than one replica, this is Redis. Confirm `REDIS_URL` is present on both pods.
+For Compose:
 
-**Step 5 fails — execution errors.** Check outbound connectivity to the model provider, then the app logs. If the error is about decrypting a credential, `ENCRYPTION_KEY` differs from the one that encrypted it.
+```bash
+docker compose -f docker-compose.prod.yml ps -a
+docker compose -f docker-compose.prod.yml logs migrations
+docker compose -f docker-compose.prod.yml logs cron
+curl -fsS http://localhost:3000/api/health
+```
 
-**Step 6 or 7 fails.** With object storage configured, a CORS error in the browser console means the bucket policy does not allow your Sim origin or the signed upload headers. If step 7 fails only during completion, check the app logs and verify the server identity can list multipart parts (for S3, `s3:ListMultipartUploadParts`). On local-disk storage there is no CORS involved — uploads proxy through the app, so look at the app logs and the proxy body-size limit instead.
+Expect `simstudio`, `realtime`, `db`, `redis`, and `cron` to be running, with `migrations` completed successfully. Without `CRON_SECRET`, the cron service exits instead of running schedules.
 
-**Step 8 fails — knowledge base upload errors.** Knowledge bases need an embedding provider: OpenAI, Azure OpenAI, or Gemini with an API key, or a model on your own Ollama via `KB_EMBEDDING_MODEL=ollama/<model>` and `OLLAMA_URL`. If one is configured, check pgvector is installed on the database.
+## Read failures [#reading-the-failures]
 
-**Step 9 fails — no email arrives.** With no provider configured the mailer no-ops: it records the recipient, subject, and sender at `info` and reports success, never the message body. Raise `LOG_LEVEL` to `INFO` to see that line — the variable is uppercase-only, and at the production default of `ERROR` nothing is logged at all.
+| Failure | Check |
+| --- | --- |
+| App does not load | Database connectivity and migration logs. On Helm, failed migrations block the app init sequence. On Compose, the app waits for successful migrations. |
+| Sign-in loops or is rejected | Public app/auth origins, scheme, and trusted origins. Confirm the app and realtime use the same `BETTER_AUTH_SECRET`. |
+| Socket is unavailable | WebSocket upgrades and `/socket.io` routing. For a separate realtime host, set `NEXT_PUBLIC_SOCKET_URL` and include the app origin in realtime's `ALLOWED_ORIGINS`. |
+| Edits do not propagate | Realtime connectivity and Redis on every replica; verify which pods hold the connections. |
+| Workflow execution fails | Provider egress, saved credentials, and app logs. A decryption error can mean the current `ENCRYPTION_KEY` differs from the key that encrypted the credential. |
+| Cloud upload fails | Bucket CORS for the Sim origin and signed headers; server permissions to complete multipart uploads. S3 completion needs `s3:ListMultipartUploadParts`. |
+| Local upload fails | App logs, writable persistent upload storage, and proxy/body limits. Bucket CORS does not apply. |
+| Knowledge upload fails | Embedding credentials/model/width, parsing errors, and `vector` availability. |
+| Email never arrives | Provider configuration and delivery dashboard. Without a provider, Sim reports success without delivery; it logs only recipient, subject, and sender at INFO. |
+| OAuth connection fails | Exact callback URI, client credentials, requested scopes, and provider approval. |
+| Schedule does not run | Cron service or CronJob pod logs. `401` means scheduler authentication failed; compare `CRON_SECRET`. |
 
-**Step 11 fails — schedule never fires.** Read the scheduler's logs (`docker compose -f docker-compose.prod.yml logs cron`, or `kubectl get cronjobs -n simstudio`). A `401` there means the app and the scheduler disagree on `CRON_SECRET`.
+Set `LOG_LEVEL=INFO` and restart/recreate the app to see email no-op logs. Log-level values are uppercase; the production default is `ERROR`, which hides those INFO messages. Message bodies are not logged and cannot be recovered from that no-op entry.
 
 ## After an upgrade
 
-Re-run steps 1, 3, 5, 6, and 11 at minimum. Those cover the app, realtime, execution, storage, and background jobs — the five things a bad upgrade breaks.
+Repeat app sign-in, realtime collaboration, workflow execution, file upload/download, and scheduled-run checks at minimum. Also test each optional feature affected by the release.
 
 ## After a restore
 
-Run the whole list, and pay special attention to **step 5 with an OAuth-backed integration**. That is what proves `ENCRYPTION_KEY` matches the backup. An app that loads and logs in but cannot decrypt credentials looks healthy right up until someone runs a real workflow.
+Run all applicable checks. Run a workflow using a previously saved provider key and an OAuth-backed integration to confirm the restored database and `ENCRYPTION_KEY` still match. An app can load and sign in while stored credentials remain unreadable.
+
+## Related docs
+
+- [Background jobs](/platform/self-hosting/background-jobs)
+- [Networking](/platform/self-hosting/networking)
+- [Troubleshooting](/platform/self-hosting/troubleshooting)
diff --git a/apps/docs/content/docs/platform/workspaces.mdx b/apps/docs/content/docs/platform/workspaces.mdx
index 418d63c6e5e..4af2ba60f7d 100644
--- a/apps/docs/content/docs/platform/workspaces.mdx
+++ b/apps/docs/content/docs/platform/workspaces.mdx
@@ -1,81 +1,58 @@
 ---
 title: Workspace fundamentals
-description: A workspace holds your workflows and resources and decides who can access them.
+description: Understand the resources, ownership, and access a workspace scopes.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Card, Cards } from 'fumadocs-ui/components/card'
+A **workspace** holds workflows and the resources they use. Its members, settings, and resource permissions determine who can build, run, and manage that work.
 
-A **workspace** groups workflows and the resources they use, including tables, files, knowledge bases, integrations, and secrets. Workspace roles control access, with additional permissions for resources such as credentials. Deployments and explicit sharing can expose selected resources outside the workspace.
+Use folders to organize work for the same team. Use another workspace when it needs different members, settings, or resource ownership.
 
-{/* VISUAL: nesting diagram. Outer ring: user or organization. Middle ring: workspace. Inside: workflows, tables, files, knowledge bases, integrations, secrets. Members with permission levels attached at the workspace ring. */}
+## Resources in a workspace
 
-## What a workspace contains
+| Resource | Purpose |
+| --- | --- |
+| [Workflows](/workflows) | Saved procedures made of blocks, with an editable draft and deployed versions |
+| [Tables](/tables) | Structured data that workflows read and update |
+| [Files](/files) | Documents and other files stored and organized for the team |
+| [Knowledge bases](/knowledgebase) | Documents and structured data agents search for context |
+| [Integrations](/integrations) | Tools for third-party services, using connected accounts or other credentials |
+| [Secrets](/platform/credentials) | API keys and variables referenced by name at runtime |
+| [Logs](/logs-debugging) | Execution records showing triggers, block inputs and outputs, errors, and costs |
 
-The sidebar is the map of a workspace. Each section is one kind of resource:
+An integration can have several account connections. Each credential has its own access rules; workspace membership alone does not grant use of every connected account or secret.
 
-{/* VISUAL: the workspace sidebar with sections labeled: Workflows, Tables, Files, Knowledge Base, Scheduled Tasks, Logs, Settings. Each row shows one example item. */}
+## Roles and resource access
 
-### Workflows
+Members have **Read**, **Write**, or **Admin** workspace access:
 
-A **workflow** is a saved, repeatable procedure made of blocks: the primary resource in a workspace. You edit it, deploy it to surfaces like an API or a chat, and version it. See [Workflows](/workflows) for the full model.
+- **Read** can inspect workflows and available execution records.
+- **Write** can create and edit workflows and run drafts in the workflow builder.
+- **Admin** can also manage members, settings, and deployments.
 
-### Tables
+The workspace owner has a fixed **Admin** role. Organization owners and admins inherit Admin access to the organization's workspaces. Credential grants and [permission groups](/platform/enterprise/access-control) add controls for particular resources and actions. See [Roles and permissions](/platform/permissions) for API execution, sharing, and inherited-role rules.
 
-A **table** is structured data in the workspace, used as a source or an output inside workflows.
+Workspace secrets require current use access. Personal secrets belong to their owner; workspace and organization Admin roles do not grant access to them. Runtime resolution respects current credential grants.
 
-### Files
+Switch to another workspace to edit resources you can access there. Moving or copying a workflow changes where it lives; it does not grant access to the destination.
 
-A **file** is a document or binary stored in the workspace, readable by workflows and organized into folders.
+## Drafts, deployments, and sharing
 
-### Knowledge bases
+A deployment serves a version of a workflow through an API, chat, or MCP server. Editing the draft does not change the active deployment until you promote the new version. To roll back, promote an earlier version. See [Deployments](/workflows/deployment).
 
-A **knowledge base** is a collection of documents or structured data that workflows search to give a model context at run time.
+Deployments and explicit sharing can make selected resources available outside normal workspace membership. They have their own access rules; they do not expose the whole workspace.
 
-### Integrations
+## Personal and organization ownership
 
-An **integration** is a connected account for a third-party service (Gmail, Slack, GitHub, and so on). Each carries its own access control, so a team shares one connection. See [Integrations](/integrations).
+A **personal workspace** belongs to an individual account. On Sim Cloud, the account's plan controls workspace creation limits.
 
-### Secrets
+An **organization workspace** belongs to an organization. On billing-enabled deployments, an active team or Enterprise plan allows organization owners and admins to create shared workspaces. Internal members join the organization; external collaborators receive selected workspace access without joining it.
 
-A **secret** is an API key or environment variable stored securely in the workspace. Secrets come in two scopes: **Workspace** secrets are shared with the workspace, and **Personal** secrets are private to you. See [Secrets](/platform/credentials).
+When you accept an invitation as an internal organization member, personal workspaces you own move into the organization, including archived workspaces. The acceptance screen names them before you accept. An external invitation does not move your workspaces. Read the [joining consequences](/platform/permissions#joining-an-organization) before accepting.
 
-### Logs
+Billing-disabled deployments have no plan-based workspace creation cap, and organization members may create organization workspaces subject to deployment and permission settings. See [Credits, billing and limits](/platform/costs) for Cloud limits and [Self-hosting](/platform/self-hosting) for deployment configuration.
 
-A **log** is the execution trace of one workflow run: the trigger, the blocks that ran, and each block's input, output, and error. Logs are how you verify what happened.
+## Related docs
 
-<Callout type="info">
-**Deployments** are not a sidebar section. A deployment is a versioned snapshot of one workflow, published for outside use through an API, chat, or MCP server. Editing a workflow does not change a live deployment until you promote the new version, and rollback means promoting an earlier one. See [Deployments](/workflows/deployment).
-</Callout>
-
-## Access and isolation
-
-Everything is scoped to the workspace, so access, settings, and isolation work the same way:
-
-- **Access.** Workspace roles determine what members can do. Credential grants and permission groups can restrict particular resources or features.
-- **Settings.** Each workspace has its own configuration: integrations, secrets, access control, API keys, and more. The Settings page lists the full menu.
-- **Ownership.** Workflows, tables, files, and knowledge bases belong to a workspace. To edit a workflow in another workspace, move or copy it there; deployments and sharing determine how others can use it.
-
-Members join with one of three **permission levels**: **Read**, **Write**, or **Admin** (the creator is **Owner**). Read can view, Write can build and run, Admin can also manage members and settings. See [Roles and permissions](/platform/permissions) for the full breakdown.
-
-
-## Personal and organization workspaces
-
-Most workspaces are one of two kinds.
-
-A **personal workspace** lives under your own account. Use it for experimentation and individual work. Your plan sets how many you can create. When you join an organization as an internal member, personal workspaces you own move into it — the accept screen names them before you accept.
-
-An **organization workspace** (also called a shared workspace) lives under an organization, available on Team and Enterprise plans. You invite people to one or more workspaces at a time, each with a permission level, and choose whether they join as members or as external collaborators. Internal members join the organization, count toward its seat total, and bring their own workspaces with them. External members stay outside the organization — no seat, and everything they own stays theirs — that's how partners and clients get access, and it requires them to already be on a paid Sim plan. For agencies and enterprises, this is the workspace you hand to the customer: the app they use, own, and maintain.
-
-<Callout type="info">
-Plan limits, seat counts, and the internal-versus-external distinction live in [Roles and permissions](/platform/permissions). This page covers what a workspace is, not how billing works.
-</Callout>
-
-## Next
-
-<Cards>
-  <Card title="Roles and permissions" href="/platform/permissions" description="Permission levels, members, and seat rules." />
-  <Card title="Workspace organization" href="/platform/organization" description="Folders and patterns for structuring a workspace." />
-  <Card title="Secrets" href="/platform/credentials" description="Workspace and personal API keys and variables." />
-  <Card title="Integrations" href="/integrations" description="Connect third-party accounts to a workspace." />
-</Cards>
+- [Organizing a workspace](/platform/organization)
+- [Roles and permissions](/platform/permissions)
+- [Credential Groups](/platform/connected-accounts)
diff --git a/apps/docs/content/docs/quick-reference/index.mdx b/apps/docs/content/docs/quick-reference/index.mdx
index b7127035a70..2c998af369c 100644
--- a/apps/docs/content/docs/quick-reference/index.mdx
+++ b/apps/docs/content/docs/quick-reference/index.mdx
@@ -1,382 +1,118 @@
 ---
-title: Quick Reference
-description: Essential actions for navigating and using the Sim workflow editor
+title: Quick reference
+description: Look up workspace and workflow builder actions.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { ActionImage, ActionVideo } from '@/components/ui/action-media'
+Look up an action by task, or use your browser's find command to search this page. `Mod` means `Cmd` on macOS and `Ctrl` on Windows and Linux. See [Keyboard shortcuts](/keyboard-shortcuts) for the full shortcut reference.
 
-A quick lookup for everyday actions in the Sim workflow editor. For keyboard shortcuts, see [Keyboard Shortcuts](/keyboard-shortcuts).
-
-<Callout type="info">
-  **Mod** refers to `Cmd` on macOS and `Ctrl` on Windows/Linux.
-</Callout>
+Edit permissions, Admin permissions, and resource locks determine which controls are available.
 
 ## Workspaces
 
-<table>
-  <thead>
-    <tr><th>Action</th><th>How</th><th>Preview</th></tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>Create a workspace</td>
-      <td>Click workspace dropdown → **New Workspace**</td>
-      <td><ActionVideo src="quick-reference/create-workspace.mp4" alt="Create workspace" /></td>
-    </tr>
-    <tr>
-      <td>Switch workspaces</td>
-      <td>Click workspace dropdown → Select workspace</td>
-      <td><ActionVideo src="quick-reference/switch-workspace.mp4" alt="Switch workspaces" /></td>
-    </tr>
-    <tr>
-      <td>Invite team members</td>
-      <td>Sidebar → **Invite**. Internal invites join the organization; external workspace members get workspace access only.</td>
-      <td><ActionVideo src="quick-reference/invite.mp4" alt="Invite team members" /></td>
-    </tr>
-    <tr>
-      <td>Rename a workspace</td>
-      <td>Right-click workspace → **Rename**</td>
-      <td rowSpan={2}><ActionImage src="/static/quick-reference/workspace-context-menu.png" alt="Workspace context menu" /></td>
-    </tr>
-    <tr>
-      <td>Delete a workspace</td>
-      <td>Right-click workspace → **Delete**</td>
-    </tr>
-  </tbody>
-</table>
-
-## Workflows
-
-<table>
-  <thead>
-    <tr><th>Action</th><th>How</th><th>Preview</th></tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>Create a workflow</td>
-      <td>Click **+** button in sidebar</td>
-      <td><ActionImage src="/static/quick-reference/create-workflow.png" alt="Create workflow" /></td>
-    </tr>
-    <tr>
-      <td>Reorder / move workflows</td>
-      <td>Drag workflow up/down or onto a folder</td>
-      <td><ActionVideo src="quick-reference/reordering.mp4" alt="Reorder workflows" /></td>
-    </tr>
-    <tr>
-      <td>Import a workflow</td>
-      <td>Click import button in sidebar → Select file</td>
-      <td><ActionImage src="/static/quick-reference/import-workflow.png" alt="Import workflow" /></td>
-    </tr>
-    <tr>
-      <td>Multi-select workflows</td>
-      <td>`Mod+Click` or `Shift+Click` workflows in sidebar</td>
-      <td><ActionVideo src="quick-reference/multiselect.mp4" alt="Multi-select workflows" /></td>
-    </tr>
-    <tr>
-      <td>Open in new tab</td>
-      <td>Right-click workflow → **Open in New Tab**</td>
-      <td rowSpan={5}><ActionImage src="/static/quick-reference/workflow-context-menu.png" alt="Workflow context menu" /></td>
-    </tr>
-    <tr>
-      <td>Rename a workflow</td>
-      <td>Right-click workflow → **Rename**</td>
-    </tr>
-    <tr>
-      <td>Duplicate a workflow</td>
-      <td>Right-click workflow → **Duplicate**</td>
-    </tr>
-    <tr>
-      <td>Export a workflow</td>
-      <td>Right-click workflow → **Export**</td>
-    </tr>
-    <tr>
-      <td>Delete a workflow</td>
-      <td>Right-click workflow → **Delete**</td>
-    </tr>
-    <tr>
-      <td>Rename a folder</td>
-      <td>Right-click folder → **Rename**</td>
-      <td rowSpan={6}><ActionImage src="/static/quick-reference/folder-context-menu.png" alt="Folder context menu" /></td>
-    </tr>
-    <tr>
-      <td>Create workflow in folder</td>
-      <td>Right-click folder → **Create workflow**</td>
-    </tr>
-    <tr>
-      <td>Create folder in folder</td>
-      <td>Right-click folder → **Create folder**</td>
-    </tr>
-    <tr>
-      <td>Duplicate a folder</td>
-      <td>Right-click folder → **Duplicate**</td>
-    </tr>
-    <tr>
-      <td>Export a folder</td>
-      <td>Right-click folder → **Export**</td>
-    </tr>
-    <tr>
-      <td>Delete a folder</td>
-      <td>Right-click folder → **Delete**</td>
-    </tr>
-  </tbody>
-</table>
+| Task | How |
+| --- | --- |
+| Create a workspace | Open the workspace dropdown → **New workspace**. |
+| Switch workspaces | Open the workspace dropdown and select a workspace. |
+| Invite teammates | Workspace dropdown → **Invite teammates**. Workspace Admin permission is required. Internal invites join the organization; external members receive workspace access only. See [Permissions](/platform/permissions). |
+| Rename a workspace | In the workspace dropdown, right-click the workspace → **Rename**. |
+| Delete a workspace | In the workspace dropdown, right-click the workspace → **Delete**, then review the confirmation. |
+
+## Workflows and folders
+
+| Task | How |
+| --- | --- |
+| Create a workflow | Click **+** beside **Workflows**. |
+| Reorder or move workflows | Drag a workflow within the list or onto a folder. |
+| Import a workflow | **Workflows → More actions → Import workflow**, then select the exported file. |
+| Select multiple workflows | `Mod` + click toggles selection; `Shift` + click selects a range. |
+| Open a workflow in a new tab | Right-click the workflow → **Open in new tab**. |
+| Rename a workflow | Right-click the workflow → **Rename**. |
+| Duplicate a workflow | Right-click the workflow → **Duplicate**. |
+| Export a workflow | Right-click the workflow → **Export**. Inspect literal values and configuration before sharing the export. |
+| Delete a workflow | Right-click the workflow → **Delete**, then review the confirmation. Its deployments become unavailable. |
+| Rename a folder | Right-click the folder → **Rename**. |
+| Create a workflow in a folder | Right-click the folder → **Create workflow**. |
+| Create a folder inside a folder | Right-click the folder → **Create folder**. |
+| Duplicate a folder | Right-click the folder → **Duplicate**. |
+| Export a folder | Right-click the folder → **Export**. Inspect the included workflows before sharing. |
+| Delete a folder | Right-click the folder → **Delete**, then review the confirmation. |
 
 ## Blocks
 
-<table>
-  <thead>
-    <tr><th>Action</th><th>How</th><th>Preview</th></tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>Add a block</td>
-      <td>Drag from Toolbar panel, or right-click canvas → **Add Block**</td>
-      <td><ActionVideo src="quick-reference/add-block.mp4" alt="Add a block" /></td>
-    </tr>
-    <tr>
-      <td>Select multiple blocks</td>
-      <td>Left-drag on empty canvas (or Shift-drag in hand mode). `Mod`/`Shift` + click adds to the selection.</td>
-      <td><ActionVideo src="quick-reference/multiselect-blocks.mp4" alt="Multi-select blocks" /></td>
-    </tr>
-    <tr>
-      <td>Copy blocks</td>
-      <td>`Mod+C` with blocks selected</td>
-      <td rowSpan={2}><ActionVideo src="quick-reference/copy-paste.mp4" alt="Copy and paste blocks" /></td>
-    </tr>
-    <tr>
-      <td>Paste blocks</td>
-      <td>`Mod+V` to paste copied blocks</td>
-    </tr>
-    <tr>
-      <td>Duplicate blocks</td>
-      <td>Right-click → **Duplicate**</td>
-      <td><ActionVideo src="quick-reference/duplicate-block.mp4" alt="Duplicate blocks" /></td>
-    </tr>
-    <tr>
-      <td>Delete blocks</td>
-      <td>`Delete` or `Backspace` key, or right-click → **Delete**</td>
-      <td><ActionImage src="/static/quick-reference/delete-block.png" alt="Delete block" /></td>
-    </tr>
-    <tr>
-      <td>Rename a block</td>
-      <td>Click block name in header, or edit in the Editor panel</td>
-      <td><ActionVideo src="quick-reference/rename-block.mp4" alt="Rename a block" /></td>
-    </tr>
-    <tr>
-      <td>Enable/Disable a block</td>
-      <td>Right-click → **Enable/Disable**</td>
-      <td><ActionImage src="/static/quick-reference/disable-block.png" alt="Disable block" /></td>
-    </tr>
-    <tr>
-      <td>Lock/Unlock a block</td>
-      <td>Hover block → Click lock icon (Admin only)</td>
-      <td><ActionImage src="/static/quick-reference/lock-block.png" alt="Lock block" /></td>
-    </tr>
-    <tr>
-      <td>Toggle handle orientation</td>
-      <td>Right-click → **Toggle Handles**</td>
-      <td><ActionVideo src="quick-reference/toggle-handles.mp4" alt="Toggle handle orientation" /></td>
-    </tr>
-    <tr>
-      <td>Configure a block</td>
-      <td>Select block → use Editor panel on right</td>
-      <td><ActionVideo src="quick-reference/configure-block.mp4" alt="Configure a block" /></td>
-    </tr>
-  </tbody>
-</table>
+| Task | How |
+| --- | --- |
+| Add a block | Drag it from **Toolbar** into the builder, or right-click empty space → **Add Block**. |
+| Select multiple blocks | Drag over empty space in Select mode, or `Shift` + drag in Hand mode. `Mod` or `Shift` + click adds blocks to the selection. |
+| Copy blocks | Select the blocks → `Mod` + `C`. |
+| Paste blocks | `Mod` + `V`. Singleton blocks such as Start and Response cannot be duplicated into the same workflow. |
+| Duplicate blocks | Right-click the selection → **Duplicate**. The action is unavailable for singleton blocks. |
+| Delete blocks | Select them → `Delete` or `Backspace`, or right-click → **Delete**. |
+| Rename a block | Right-click → **Rename**, or double-click its name in **Editor**. |
+| Enable or disable a block | Right-click → **Enable** or **Disable**, depending on its current state. |
+| Lock or unlock a block | Hover the block and click **Lock** or **Unlock**, or use its context menu. Workspace Admin permission is required. |
+| Configure a block | Select it and edit its fields in **Editor**. |
 
 ## Connections
 
-<table>
-  <thead>
-    <tr><th>Action</th><th>How</th><th>Preview</th></tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>Create a connection</td>
-      <td>Drag from output handle to input handle</td>
-      <td><ActionVideo src="quick-reference/connect-blocks.mp4" alt="Connect blocks" /></td>
-    </tr>
-    <tr>
-      <td>Delete a connection</td>
-      <td>Click edge to select → `Delete` key</td>
-      <td><ActionVideo src="quick-reference/delete-connection.mp4" alt="Delete connection" /></td>
-    </tr>
-    <tr>
-      <td>Use output in another block</td>
-      <td>Drag connection tag into input field</td>
-      <td><ActionVideo src="quick-reference/connection-tag.mp4" alt="Use connection tag" /></td>
-    </tr>
-  </tbody>
-</table>
+| Task | How |
+| --- | --- |
+| Create a connection | Drag from the upstream block's output handle to the downstream block's input handle. |
+| Delete a connection | Select the edge → `Delete` or `Backspace`, or click **Delete connection** on the selected edge. |
+| Use an output in another block | In the downstream block's **Editor → Connections**, drag the upstream output field into the input. You can also insert its [reference](/workflows/connections). |
+
+## Panels and views
+
+| Task | How |
+| --- | --- |
+| Search Toolbar | `Mod` + `Alt` + `F` opens **Toolbar** and focuses its search. |
+| Search workspace resources and commands | `Mod` + `K` opens search. |
+| Enter a manual selector ID | Where offered, choose **Switch to manual ID**. Choose **Switch to selector** to return to the option list. |
+| Collapse or expand the sidebar | Click **Toggle sidebar**, or press `Mod` + `B` outside an editable field. |
+
+## Run and inspect
+
+Workflow test chat runs the current workflow. The panel's **Chat** tab is where you ask Sim to help build it.
+
+| Task | How |
+| --- | --- |
+| Run a workflow | Click **Run**, or `Mod` + `Enter` outside an editable field. |
+| Stop a running workflow | Click **Stop**, or `Mod` + `Enter` while it runs. |
+| Test with chat | Click **Open chat** beside the workflow's More actions menu to open the test chat. |
+| Select outputs to display | In workflow test chat, open **Outputs** and choose the block and output fields. |
+| Clear test chat history | Workflow test chat → **Chat actions** (three dots) → **Clear**. |
+| Run from a block | Hover and click its run control, or right-click → **Run from block**. Run upstream blocks first to supply required outputs. Unavailable for notes and blocks inside subflows. |
+| Run until a block | Right-click → **Run until block**. Unavailable for triggers, notes, and blocks inside subflows. |
+| View execution logs | Expand **Logs** at the bottom, then select a block row to inspect its input and output. `Mod` + `L` opens the full Logs page. |
+| Filter logs | Use the workflow Logs filters, or right-click a row → **Filter by Block** or **Filter by Status**. |
+| Search a block's output | Select its log row → **Search in output**, or right-click inside the output → **Search**. |
+| Copy a block's output | Select its log row → **Copy output**, or right-click inside the output → **Copy Selection** or **Copy All**. |
+| Clear the workflow console | Click **Clear console**, or `Mod` + `D` outside an editable field. This clears the builder's console, not persisted run logs. |
 
-## Panels & Views
-
-<table>
-  <thead>
-    <tr><th>Action</th><th>How</th><th>Preview</th></tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>Search toolbar</td>
-      <td>`Mod+Alt+F`</td>
-      <td><ActionVideo src="quick-reference/search-toolbar.mp4" alt="Search toolbar" /></td>
-    </tr>
-    <tr>
-      <td>Search everything</td>
-      <td>`Mod+K`</td>
-      <td><ActionImage src="/static/quick-reference/search-everything.png" alt="Search everything" /></td>
-    </tr>
-    <tr>
-      <td>Toggle manual mode</td>
-      <td>Click toggle button to switch between manual and selector</td>
-      <td><ActionImage src="/static/quick-reference/toggle-manual-mode.png" alt="Toggle manual mode" /></td>
-    </tr>
-    <tr>
-      <td>Collapse/expand sidebar</td>
-      <td>Click collapse button on sidebar</td>
-      <td><ActionVideo src="quick-reference/collapse-sidebar.mp4" alt="Collapse sidebar" /></td>
-    </tr>
-  </tbody>
-</table>
+## Deployment
 
-## Running & Testing
+Deploying and changing the live version require workspace Admin permission. Draft edits do not change an existing deployment until you update it.
 
-<table>
-  <thead>
-    <tr><th>Action</th><th>How</th><th>Preview</th></tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>Run workflow</td>
-      <td>Click Run Workflow button or `Mod+Enter`</td>
-      <td><ActionImage src="/static/quick-reference/run-workflow.png" alt="Run workflow" /></td>
-    </tr>
-    <tr>
-      <td>Stop workflow</td>
-      <td>Click Stop button or `Mod+Enter` while running</td>
-      <td><ActionImage src="/static/quick-reference/stop-workflow.png" alt="Stop workflow" /></td>
-    </tr>
-    <tr>
-      <td>Test with chat</td>
-      <td>Open the workflow test chat (the Chat overlay with the output dropdown), not the Chat tab in the panel.</td>
-      <td><ActionImage src="/static/quick-reference/test-chat.png" alt="Test with chat" /></td>
-    </tr>
-    <tr>
-      <td>Select output to view</td>
-      <td>Click dropdown in Chat panel → Select block output</td>
-      <td><ActionImage src="/static/quick-reference/output-select.png" alt="Select output to view" /></td>
-    </tr>
-    <tr>
-      <td>Clear chat history</td>
-      <td>Click clear button in Chat panel</td>
-      <td><ActionImage src="/static/quick-reference/clear-chat.png" alt="Clear chat history" /></td>
-    </tr>
-    <tr>
-      <td>Run from block</td>
-      <td>Hover block → Click play button, or right-click → **Run from block**</td>
-      <td><ActionImage src="/static/quick-reference/run-from-block.png" alt="Run from block" /></td>
-    </tr>
-    <tr>
-      <td>Run until block</td>
-      <td>Right-click block → **Run until block**</td>
-      <td><ActionImage src="/static/quick-reference/run-until-block.png" alt="Run until block" /></td>
-    </tr>
-    <tr>
-      <td>View execution logs</td>
-      <td>Open the terminal panel at the bottom (`Mod+L` opens the Logs page).</td>
-      <td><ActionImage src="/static/quick-reference/terminal.png" alt="Execution logs terminal" /></td>
-    </tr>
-    <tr>
-      <td>Filter logs</td>
-      <td>Click filter icon in terminal → Filter by block or status</td>
-      <td><ActionImage src="/static/quick-reference/filter-block.png" alt="Filter logs by block" /></td>
-    </tr>
-    <tr>
-      <td>Search logs</td>
-      <td>Use search field in terminal or right-click log entry → **Search**</td>
-      <td><ActionImage src="/static/quick-reference/terminal-search.png" alt="Search logs" /></td>
-    </tr>
-    <tr>
-      <td>Copy log entry</td>
-      <td>Clipboard Icon or Right-click log entry → **Copy**</td>
-      <td><ActionImage src="/static/quick-reference/copy-log.png" alt="Copy log entry" /></td>
-    </tr>
-    <tr>
-      <td>Clear terminal</td>
-      <td>Trash icon or `Mod+D`</td>
-      <td><ActionImage src="/static/quick-reference/clear-terminal.png" alt="Clear terminal" /></td>
-    </tr>
-  </tbody>
-</table>
+| Task | How |
+| --- | --- |
+| Deploy a workflow | Click **Deploy** at the top of the workflow panel. |
+| Update a deployment | Click **Update** after changing the draft and deploy the new version. |
+| View deployment status | The top chip reads **Deploy**, **Update**, or **Live**. Open it for deployment details. |
+| Restore an earlier live version | Deployment → **General → Versions → Version actions → Promote to live**, then confirm. **Load deployment** instead loads that version into the draft. |
+| Add a version description | **General → Versions → Add description** or **Edit description**. Enter text or choose **Generate**. |
+| Copy an API request example | Deployment → **API** → choose **cURL**, then copy the request sample. Keep its authentication headers and required inputs. |
 
-## Deployment
+## Variables and secrets
 
-<table>
-  <thead>
-    <tr><th>Action</th><th>How</th><th>Preview</th></tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>Deploy a workflow</td>
-      <td>Click **Deploy** button in panel</td>
-      <td><ActionImage src="/static/quick-reference/deploy.png" alt="Deploy workflow" /></td>
-    </tr>
-    <tr>
-      <td>Update deployment</td>
-      <td>Click **Update** when changes are detected</td>
-      <td><ActionImage src="/static/quick-reference/update-deployment.png" alt="Update deployment" /></td>
-    </tr>
-    <tr>
-      <td>View deployment status</td>
-      <td>Check status indicator (Live/Update/Deploy) in Deploy modal</td>
-      <td><ActionImage src="/static/quick-reference/view-deployment.png" alt="View deployment status" /></td>
-    </tr>
-    <tr>
-      <td>Revert deployment</td>
-      <td>Access previous versions in Deploy modal → **Promote to live**</td>
-      <td><ActionImage src="/static/quick-reference/promote-deployment.png" alt="Promote deployment to live" /></td>
-    </tr>
-    <tr>
-      <td>Add version description</td>
-      <td>Deploy modal → Click description icon → Add or generate description</td>
-      <td><ActionVideo src="quick-reference/deployment-description.mp4" alt="Add deployment version description" /></td>
-    </tr>
-    <tr>
-      <td>Copy API endpoint</td>
-      <td>Deploy modal → **API** → Copy API cURL</td>
-      <td><ActionImage src="/static/quick-reference/copy-api.png" alt="Copy API endpoint" /></td>
-    </tr>
-  </tbody>
-</table>
+| Task | How |
+| --- | --- |
+| Add, edit, or delete a workflow variable | Workflow More actions menu → **Variables**. Click **+** to add, edit **Name**, **Type**, and **Value**, or use the variable's delete control. |
+| Add an environment variable | **Settings → Workspace → Secrets**. Enter a name and value in a workspace or personal row, then **Save**. See [Variables](/workflows/variables) for scope and overrides. |
+| Reference a workflow variable | Use `<variable.name>` in a block input. |
+| Reference an environment variable | Use `{{ENV_VAR}}` in a block input. |
 
-## Variables
+## Related docs
 
-<table>
-  <thead>
-    <tr><th>Action</th><th>How</th><th>Preview</th></tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>Add / Edit / Delete workflow variable</td>
-      <td>⋯ menu → **Variables** → **Add Variable**, click to edit, or delete icon</td>
-      <td><ActionImage src="/static/quick-reference/variables.png" alt="Variables panel" /></td>
-    </tr>
-    <tr>
-      <td>Add environment variable</td>
-      <td>Settings → **Secrets** → **Add**</td>
-      <td><ActionImage src="/static/quick-reference/add-env-variable.png" alt="Add environment variable" /></td>
-    </tr>
-    <tr>
-      <td>Reference a workflow variable</td>
-      <td>Use `<variable.name>` syntax in block inputs</td>
-      <td><ActionImage src="/static/quick-reference/variable-reference.png" alt="Reference workflow variable" /></td>
-    </tr>
-    <tr>
-      <td>Reference an environment variable</td>
-      <td>Use `{{ENV_VAR}}` syntax in block inputs</td>
-      <td><ActionImage src="/static/quick-reference/env-variable-reference.png" alt="Reference environment variable" /></td>
-    </tr>
-  </tbody>
-</table>
+- [Keyboard shortcuts](/keyboard-shortcuts)
+- [Connections](/workflows/connections)
+- [Logs and debugging](/logs-debugging)
+- [Deployment](/workflows/deployment)
diff --git a/apps/docs/content/docs/search/coda.mdx b/apps/docs/content/docs/search/coda.mdx
index 493b5cc7dfa..4cd10b17d14 100644
--- a/apps/docs/content/docs/search/coda.mdx
+++ b/apps/docs/content/docs/search/coda.mdx
@@ -1,50 +1,55 @@
 ---
 title: Coda
-description: Search pages and table rows through your personal Coda MCP connection
+description: Search Coda pages and table rows with your personal MCP connection
 ---
 
-Coda supports **Member accounts** and **Service account**. The preferred personal connection uses Coda MCP OAuth. Every reader connects their own Coda account, including when an administrator configures a service source.
+Connect Coda to search page and table-row content. **Member accounts** and **Service account** modes both require each reader's personal Coda connection. A service source also restricts the allowed parent documents.
 
-## Connect member accounts
+## Connect
 
-1. An admin adds **Coda** under **Settings → Sources** and chooses **Member accounts**.
-2. Each teammate opens **Integrations → Coda → Connect** and completes Coda authorization.
-3. Search for text in a page or table row the connected account can access.
+1. An admin adds **Coda** in **Settings → Sources** and selects **Member accounts**, or configures the service source below.
+2. Each teammate opens **Integrations → Coda → Connect** and authorizes their account.
+3. Search text in a page or row that account can access, then read a result.
 
-Coda may send you to Superhuman sign-in: [Coda now uses Superhuman's identity service](https://help.coda.io/en/articles/5473507-reset-your-password).
+The managed Coda MCP provider must be configured before **Connect** is available. Members authorize that provider rather than choosing an arbitrary server URL. Coda may use [Superhuman sign-in](https://help.coda.io/en/articles/5473507-reset-your-password).
 
-Coda's managed MCP provider must be configured before Connect is available. The member authorizes that provider; they do not choose an arbitrary MCP server URL during Search.
+## Search and read
 
-## Add a service boundary
+Use a focused phrase from a page or table row. A native query can target a document URI such as `superhuman://docs/DOC_ID`; older `coda://docs/DOC_ID` references also work.
 
-Choose **Service account** in Sources, then **Add connection** or an existing Coda source.
+Date-bounded queries without terms can use the provider's recency listing. Coda does not accept these exact date bounds directly, so Sim checks returned timestamps and reports limited coverage. Results and reads are bounded; continuation is used where the server advertises it.
 
-1. Add a Coda REST API token owned by an account that can read the allowed documents. Use the source form's **Service account → Add API token** action. The source token is distinct from each reader's MCP OAuth connection.
-2. Select **Documents**, or use the paired document-ID field for documents absent from the picker. The picker lists documents the token owner has opened. Leaving the selection empty does not bypass the token's access checks.
-3. Optionally set an **Enterprise organization ID**. This requires an Enterprise organization administrator token; ordinary workspace-admin access is insufficient.
-4. Save and select the source connection. Members still connect personally in Integrations.
+Sim validates the advertised schemas and uses only `search`, `url_convert`, `content_read`, `document_outline`, and `table_rows_read`, with the member's current grant. Search cannot invoke Coda write tools or use another server URL.
 
-A standard REST token is needed for the service boundary. Do not substitute an MCP-restricted token in that field. To rotate it, add the replacement credential and update the source.
+Existing personal REST-token connections can still search document titles. This compatibility path requires Coda's reported account email to match the reader's verified Sim email and does not provide MCP page or table-row content search.
 
-## How search and reads work
+## Add a service boundary
 
-Sim proxies Coda's advertised MCP `search` tool using the member's current managed grant. Text search covers pages and table rows. A query can target a document URI such as `superhuman://docs/DOC_ID` (or an older `coda://docs/DOC_ID` URI); date-bounded requests without terms can use Coda's recency listing. Coda does not accept these date bounds directly, so Sim checks returned timestamps and reports limited coverage.
+A service boundary needs a standard Coda REST API token, separate from each reader's MCP OAuth grant. Do not use an MCP-restricted token for it.
 
-Reads use a fixed read-only tool allowlist: `url_convert`, `content_read`, `document_outline`, and `table_rows_read`, alongside `search`. Sim discovers and validates the server's tool schemas and reloads the member's current grant before calls. Search cannot invoke Coda write tools or choose a different server URL.
+1. Choose **Service account** in Sources, then **Add connection** or an existing Coda source.
+2. Use **Service account → Add API token** for a token owned by an account that can read the allowed documents.
+3. Select **Documents**. The picker shows documents the token owner has opened; use the paired document-ID field for others.
+4. Optionally set **Enterprise organization ID**. This requires an Enterprise organization administrator token; workspace-admin access is insufficient.
+5. Save and select the source connection. Members still connect personally in **Integrations**.
 
-In service mode, each result's parent document must be in the selected document scope and currently readable by the service token. With an Enterprise organization ID, Sim also verifies that exact document against the configured organization's Admin API. The member's MCP access remains necessary. There is no background document ACL or directory build for live Coda Search.
+Each result's parent document must be within the selected scope and currently readable by the service token. An empty selection does not bypass token access checks. With an Enterprise organization ID, the Admin API must verify the exact document in that organization. The member's MCP access remains required on search and read.
 
-An existing personal REST-token connection can search document titles as a compatibility path. This legacy personal-token path requires Coda’s reported account email to match the reader’s verified Sim email. It does not provide MCP's page and table-row full-content search. Provider results and reads are bounded and support continuation where advertised.
+To rotate the service token, add the replacement credential and update the source.
 
 ## Troubleshooting
 
-| Problem | Next step |
+| Problem | Check |
 | --- | --- |
-| Coda shows Not configured | Ask an admin to configure the managed Coda MCP provider. |
-| Only document titles match | Check that your connection uses personal Coda MCP OAuth rather than a legacy REST token. |
-| Service picker omits a document | Open it with the token owner or use its document ID. |
-| Member search finds nothing | Confirm the member's Coda access and, in service mode, the selected document scope and service token's access. |
-| Enterprise source fails | Check the exact organization ID, Enterprise org-admin role, and token validity. |
-| MCP schema or authorization changed | Reconnect or update the managed provider; Search reports the failure instead of invoking unknown tools. |
-
-See the [Coda public API](https://coda.io/developers/apis/v1) and [Enterprise Admin API](https://coda.io/developers/apis/admin/v1). Ordinary [knowledge-base connectors](/knowledgebase/connectors) still use their separate REST ingestion path.
+| `Not configured` | Ask an admin to configure the managed Coda MCP provider. |
+| Only document titles match | Use personal MCP OAuth instead of a legacy REST token. |
+| Document missing from service picker | Open it with the token owner or enter its document ID. |
+| No results | Check member access, selected documents, and service-token access. |
+| Enterprise verification fails | Check the exact organization ID, org-admin role, and token validity. |
+| MCP schema or authorization changed | Reconnect or update the managed provider. Search reports unsupported tools instead of invoking them. |
+
+## Related docs
+
+- [Coda public API](https://coda.io/developers/apis/v1)
+- [Enterprise Admin API](https://coda.io/developers/apis/admin/v1)
+- [Knowledge-base connectors](/knowledgebase/connectors) — separate REST ingestion
diff --git a/apps/docs/content/docs/search/confluence.mdx b/apps/docs/content/docs/search/confluence.mdx
index eab0b72f020..0ffad5250f8 100644
--- a/apps/docs/content/docs/search/confluence.mdx
+++ b/apps/docs/content/docs/search/confluence.mdx
@@ -1,32 +1,23 @@
 ---
 title: Confluence
-description: Search Confluence Cloud with member access and optional service-source restrictions
+description: Search Confluence Cloud pages and blog posts with your current access
 ---
 
-Confluence supports **Member accounts** and **Service account**. Each reader connects their own Confluence account in both modes. Search queries Confluence Cloud directly; Server and Data Center are not supported by this adapter.
+Search Confluence Cloud with your own account. **Member accounts** uses your provider permissions; **Service account** also limits results by site, spaces, content type, and labels. Both modes require each reader's personal connection. This adapter does not support Server or Data Center.
 
-## Member accounts
+## Connect member accounts
 
-1. An admin adds **Confluence** under **Settings → Sources** and selects **Member accounts**.
-2. Each teammate opens **Integrations → Confluence → Connect** and authorizes the appropriate Atlassian account.
-3. Search content that account can access. Member mode has no admin space or label configuration.
+1. An admin adds **Confluence** in **Settings → Sources** and selects **Member accounts**, or configures the service source below.
+2. Each teammate opens **Integrations → Confluence → Connect** and authorizes their Atlassian account.
+3. Search a page or blog post that account can access, then read a result.
 
-The default search includes pages and blog posts. The assistant can use CQL to narrow the content type or target a space. Site selection and permissions come from the connected account.
-
-## Set up a central source
-
-1. Add Confluence in Sources, choose **Service account**, and use **Add connection**, or select an existing connection.
-2. In **Connect Confluence site**, choose or add the service credential, enter its site, and select **Spaces**. The picker and manual space-key input set the same boundary. **All** includes spaces currently accessible to the service account.
-3. Choose the content type and optional label filter, then save the connection. Choose that connection as the integration's service source.
-4. Each reader connects their personal Confluence account under **Integrations**.
-
-The source can select pages, blog posts, or both. Multiple labels are alternatives: matching any selected label satisfies that filter. A missing required space selection does not broaden access.
+Member mode has no admin space or label filters. The default search covers pages and blog posts; ask Sim to use Confluence Query Language (CQL) to narrow a query by content type or space. Site access comes from your connected account.
 
 ## Using a service account
 
-Use an Atlassian service account with access to the configured site, spaces, and restricted content. Admin status does not bypass page restrictions. Create a scoped API token in **Atlassian Administration → Directory → Service accounts**.
+The service credential must have access to the configured site, spaces, and restricted content. Admin status does not bypass page restrictions.
 
-The shared service credential and connector validation use these read scopes:
+Create a scoped API token in **Atlassian Administration → Directory → Service accounts** with the shared service-credential read scopes:
 
 ```text
 read:confluence-content.all
@@ -44,34 +35,47 @@ read:user:confluence
 read:group:confluence
 ```
 
-In the source form, select **Service account → Add service account**, paste the token, and supply the matching site hostname. This is separate from the shared OAuth app that members authorize. See [Atlassian's service account token instructions](https://support.atlassian.com/user-management/docs/manage-api-tokens-for-service-accounts/).
+See [Atlassian's token instructions](https://support.atlassian.com/user-management/docs/manage-api-tokens-for-service-accounts/). This token is separate from the shared OAuth app that members authorize.
+
+## Set up a central source
+
+1. Add Confluence in Sources, choose **Service account**, then **Add connection** or an existing connection.
+2. In **Connect Confluence site**, use **Service account → Add service account**, paste the token, and enter its matching site hostname; or select an existing service credential.
+3. Select **Spaces** with the picker or manual space keys. **All** includes spaces currently accessible to the service account.
+4. Choose pages, blog posts, or both, and an optional label filter. Save and select the connection as the service source.
+5. Each reader connects Confluence personally in **Integrations**.
+
+Multiple labels are alternatives: any selected label satisfies the filter. Missing required space selection does not broaden access.
 
-## How filtering works
+## Search boundaries and reads
 
-Search sends the member's query through their OAuth grant. In service mode, it incorporates the source's content type, space, and label restrictions where supported. Before returning a candidate, Sim uses the source credential to confirm its site, current status, space, type, labels, and readability. The member must also be able to read it.
+Search sends your query through your OAuth grant and incorporates service filters where supported. Before returning a result, Sim verifies its current site, status, space, content type, labels, and readability with the service credential. Reads use your account and repeat those checks.
 
-Reading the document uses the member's connection and repeats the service-boundary checks. Sim does not build a background mirror of Confluence groups or page ACLs for this live path. It returns the page or blog-post content exposed by the current API; it does not perform the old attachment ingestion and OCR pipeline.
+For a plain query without date sorting, Sim uses Confluence relevance search when more pages match every word than fit on one page. That result is partial and has no continuation cursor; narrow the query or use native CQL for pagination. If relevance ranking fails, Sim keeps the original all-terms page and its cursor, marked partial. Native CQL and date-sorted queries keep their provider ordering.
 
-Search visits up to four accessible Atlassian sites by default. Native CQL can target a specific cloud site ID and follow its continuation cursor. Confluence's own search freshness and limits still apply.
+Reads return page or blog-post content exposed by the API. Live Search does not ingest attachments or run OCR. It checks up to four accessible Atlassian sites by default; a native CQL query can select a cloud site ID and follow its continuation cursor. Confluence search freshness and limits still apply.
 
 ## Troubleshooting
 
-| Problem | What to check |
+| Problem | Check |
 | --- | --- |
-| Spaces picker is empty | Check the service credential's site, space access, and scopes. Manual space keys remain available. |
-| Service account fails validation | Check expiry, site, Confluence app access, and the credential's required read scopes. |
-| Member sees no results | Connect their personal account; confirm both that account and the selected service credential can open the content. |
-| Blog posts or a labeled page are absent | Check content type, labels, selected spaces, and Confluence's own search results. |
-| Results disappear after changing a source | Verify the new boundary and credential; access is checked again on every search and read. |
+| Empty spaces picker | Check site, access, and scopes, or enter space keys manually. |
+| Service validation fails | Check token expiry, site, app access, and required read scopes. |
+| No results | Confirm both the personal account and service credential can open the content. |
+| Blog post or labeled page missing | Check content type, labels, spaces, and Confluence's own search. |
+| Results changed after source settings changed | Review the new boundary and credential; later searches and reads use it. |
 
 ## Self-hosted operator setup
 
-Configure one shared Confluence OAuth app for teammates' connections:
+Follow [Atlassian OAuth setup](/platform/self-hosting/integrations-oauth#atlassian) for the shared member app, full current Confluence scopes, **User Identity API → read:me**, `offline_access`, and distribution settings. Set `CONFLUENCE_CLIENT_ID` and `CONFLUENCE_CLIENT_SECRET`, verify `NEXT_PUBLIC_APP_URL`, and register:
+
+```text
+https://<your-sim-domain>/api/auth/oauth2/callback/confluence
+```
+
+The callback must match scheme, hostname, port, and path. If only the app owner can connect, check **Distribution**. After client or scope changes, update the organization's saved provider configuration and reconnect affected members. Service-token scopes above do not replace member OAuth scopes.
 
-1. In the [Atlassian developer console](https://developer.atlassian.com/console/myapps/), select or create the deployment's **OAuth 2.0 integration**.
-2. Under **Authorization → OAuth 2.0 (3LO)**, add `https://<your-sim-domain>/api/auth/oauth2/callback/confluence` as a callback.
-3. Under **Permissions**, add the Confluence API and its full `confluence` scope list from [Sim's OAuth configuration](https://github.com/simstudioai/sim/blob/staging/apps/sim/lib/oauth/oauth.ts), including `read:group:confluence`. Add **User Identity API → read:me**. Sim requests `offline_access` for refresh tokens; the service-account list above does not replace this shared OAuth scope set.
-4. Enable sharing under **Distribution**. Set `CONFLUENCE_CLIENT_ID` and `CONFLUENCE_CLIENT_SECRET` from the app's **Settings**, verify `NEXT_PUBLIC_APP_URL`, and restart Sim.
-5. Connect from **Integrations** and select the configured site. After changing the OAuth client or requested scopes, update the organization’s provider configuration and have affected teammates reconnect.
+## Related docs
 
-The callback must match Sim's scheme, hostname, port, and path exactly. If only the app owner can connect, check **Distribution**. See the [Atlassian OAuth guide](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/) and [Sim deployment reference](/platform/self-hosting/integrations-oauth).
+- [Connect your account](/search/connect-your-account)
+- [Atlassian OAuth guide](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/)
diff --git a/apps/docs/content/docs/search/connect-your-account.mdx b/apps/docs/content/docs/search/connect-your-account.mdx
index 808db3f1231..3a15f12be86 100644
--- a/apps/docs/content/docs/search/connect-your-account.mdx
+++ b/apps/docs/content/docs/search/connect-your-account.mdx
@@ -1,48 +1,53 @@
 ---
 title: Connect your account
-description: Connect your own provider accounts for live Search
+description: Authorize your provider accounts and manage their Search connections
 ---
 
-Your admin adds integrations under **Settings → Sources**. You connect your own accounts under **Integrations** in the main sidebar, including when you are the admin.
+After your admin adds a source in **Settings → Sources**, connect your own account in **Integrations**. This applies to admins too. A service source usually still requires your personal connection.
 
-## Connect and search
+## Connect and verify
 
-1. Join the Sim organization through its invitation or SSO. Use the verified email required by your organization's provider connection.
+1. Join the Sim organization through its invitation or SSO. Use the verified email required by the provider connection.
 2. Open **Integrations**, find the provider, and select **Connect**.
-3. Complete the provider's authorization in the new tab. If a popup is blocked, allow it and start Connect again.
-4. Return to Sim and open **Search** or **Home**. Your account is usable after authorization completes; there is no initial indexing run.
+3. Complete authorization in the new tab. If the popup is blocked, allow it and select **Connect** again.
+4. Return to **Search** or **Home** and search for content your account can open. Read a result and follow its source link.
 
-If a provider is missing, ask an organization admin to add it in Sources. If it shows **Not configured**, the provider's app or deployment setup needs an admin's attention before you can connect.
+The connection is usable when authorization completes; no initial indexing run is required. If a provider is missing, ask an admin to add it in **Sources**. `Not configured` means its app or deployment setup needs an admin's attention.
 
-You do not select repositories, channels, labels, or an indexing method while connecting. Member mode searches content your account can access. In service mode, the administrator's source settings further restrict the results.
+You do not choose repositories, channels, labels, or an indexing method during personal authorization. Member mode uses your provider access; service mode further restricts results with the admin's source settings.
 
-## Which accounts do I need?
+## Provider exceptions
 
 | Source setup | Personal connection |
 | --- | --- |
-| Member accounts | Connect your own provider account. |
-| GitHub App | Connect your GitHub account once. Each selected repository must be readable by both you and the installation. |
-| Google service account (Gmail, Calendar, Drive) | Connect the corresponding Google service. The source verifies your connected identity and resource access through delegation. |
-| Confluence service account | Connect your own Confluence account. Both connections must be able to read the selected content. |
-| Coda | Connect your personal Coda MCP account. In service mode, the source token also verifies the parent document. |
-| GitLab | No personal connection. Your verified Sim email must match current GitLab identity and permissions, or the administrator's CSV mapping and project grant. |
-| [Generic Secrets in Member mode](/search/generic-secrets) | Open the source in Integrations and save your own secrets. These are available to Build and Plan, not document search. |
+| **Member accounts** | Connect your own provider account. |
+| **GitHub App** | Connect GitHub once per Sim organization. Each selected repository must be readable by you and the installation. |
+| Google service account: Gmail, Calendar, Drive | Connect each corresponding Google service. The source verifies your identity and resource access through delegation. |
+| Confluence service account | Connect Confluence. Both your account and the service connection must read the selected content. |
+| Coda | Connect personal Coda MCP. Service mode also verifies the parent document with its REST token. |
+| GitLab | No personal connection. Your verified Sim email must match current GitLab identity and permissions, or the admin's CSV mapping and project grant. |
+| [Generic Secrets, Member mode](/search/generic-secrets) | Select **Manage secrets** in Integrations and save your own values for Build and Plan. |
 
-Gmail, Calendar, and Drive are separate connections. Connecting one does not authorize the others. A service account is a resource boundary, not a replacement for your personal connection, except for GitLab's explicit permission model.
+Gmail, Calendar, and Drive have separate grants. Connecting one does not authorize the others. Except for GitLab's permission model, a service account restricts resources rather than replacing your personal connection.
 
-## Manage connections
+## Reconnect or disconnect
 
-Use **Reconnect** when the provider's grant expires, is revoked, or needs additional scopes. A temporarily unavailable provider does not necessarily require reconnecting.
+Use **Reconnect** when a grant expires, is revoked, or needs more scopes. A temporary provider outage does not necessarily require reconnecting.
 
-Disconnecting an account stops future use of that grant. Shared credential-group connections can also be used by workflows, so review the connection's confirmation before removing it. It does not remove your Sim organization membership.
+Disconnecting stops future use of the grant and can affect workflows sharing the account. Review the confirmation before removing it. Disconnecting does not remove your Sim membership.
 
-If you received an account-connection request, sign in as the verified Sim user associated with the requested email and authorize the provider. A connection request does not invite you into the organization. You still need organization membership and Search access to search its sources.
+For an account-connection request, sign in as the verified Sim user associated with the requested email, then authorize the provider. The request does not invite you into the organization; membership and Search access are still required.
 
-## If results are missing
+## Find missing results
 
-- Confirm the account is connected and can open the original document.
-- Check the source's service-account filters with an admin, when that mode is selected.
-- Check provider scope errors, rate limits, and any incomplete-coverage status returned by Search.
-- Try the same query in the provider's own search. Provider search limitations still apply.
+- Confirm the connected account can open the original content.
+- Ask an admin to check service-source filters when that mode is selected.
+- Check scope errors, rate limits, and incomplete-coverage status.
+- Try the query in the provider's search; its limitations still apply.
 
-Do not wait for a Sim sync or retry document indexing: live Search calls the provider for each request. [Workspace knowledge bases](/knowledgebase/connectors) have a separate indexing workflow.
+Live Search calls the provider for each request. Waiting for a Sim sync or retrying document indexing will not resolve a live Search failure.
+
+## Related docs
+
+- [Search access and freshness](/search#access-and-freshness)
+- [Knowledge-base connectors](/knowledgebase/connectors)
diff --git a/apps/docs/content/docs/search/fireflies.mdx b/apps/docs/content/docs/search/fireflies.mdx
index 4e0701b5568..8b3bc83b0c5 100644
--- a/apps/docs/content/docs/search/fireflies.mdx
+++ b/apps/docs/content/docs/search/fireflies.mdx
@@ -1,32 +1,33 @@
 ---
 title: Fireflies
-description: Search meeting titles and spoken transcripts with each member’s Fireflies account
+description: Search meeting titles and spoken transcripts with your Fireflies account
 ---
 
-Fireflies live Search uses **Member accounts**. Each person authorizes their own Fireflies account through the managed MCP connection. Search can read only meetings that account can access now.
+Fireflies Search uses **Member accounts** and the official managed MCP connection. It searches meeting titles and spoken transcripts that your connected account can currently access.
 
 ## Connect
 
-1. An admin enables **Fireflies** under **Settings → Sources**, using **Member accounts**.
-2. Each teammate opens **Integrations → Fireflies → Connect** and completes Fireflies authorization.
-3. Search for a topic, phrase, or name mentioned in a meeting.
+1. An admin adds **Fireflies** in **Settings → Sources**, using **Member accounts**.
+2. Each teammate opens **Integrations → Fireflies → Connect** and authorizes their account.
+3. Search a phrase such as `security approval` or `customer onboarding`, then read a result.
 
-The managed Fireflies provider must be configured before Connect is available. Live Search uses the fixed official endpoint `https://api.fireflies.ai/mcp`. The API-key connection used by the Fireflies knowledge-base connector is a separate ingestion path and does not authorize member live Search.
+The managed provider must be configured before **Connect** is available. It uses `https://api.fireflies.ai/mcp`. The API key for the Fireflies knowledge-base connector is a separate ingestion connection and cannot authorize member Search.
 
-## Query guidance
+## Queries and dates
 
-Use concise words or a phrase, such as `security approval`, `customer onboarding`, or `September launch`. Fireflies accepts a maximum of 255 characters in the search term. Sim explicitly searches both meeting titles and spoken transcript sentences.
+Use plain words or a phrase, up to 255 characters. Gmail operators, GitHub qualifiers, and Fireflies' experimental query grammar do not apply to this adapter.
 
-Supply meeting dates through `startDate` and `endDate`, with an exclusive end bound. Sim widens native date-only bounds to cover the requested instants, then checks the actual returned meeting date. Fireflies does not expose a transcript modification time; modification-date filters cannot establish matching transcripts.
+Use `startDate` and `endDate` for meeting dates; the upper bound is exclusive. Sim widens the provider's date-only bounds, then checks each actual meeting date. Fireflies exposes no transcript modification time, so modification-date filters cannot establish matching transcripts.
 
-Do not use Gmail operators, GitHub qualifiers, or Fireflies’ experimental search mini-grammar in the query. Sim uses the stable `fireflies_get_transcripts` tool with JSON output, adding `scope: "all"` when the query contains a keyword. Date-only listings omit keyword scope. Continue with the returned numeric cursor on the same account and query. Each page returns up to 49 meetings, reserving one provider result to confirm that another page exists.
+The adapter calls `fireflies_get_transcripts` with JSON output and `scope: "all"` for keyword searches; date-only listings omit keyword scope. Each page returns up to 49 meetings, with one extra provider result used to detect continuation. Continue the numeric cursor with the same account and query.
 
-## Evidence and reads
+## Transcript evidence and limits
 
-Search results contain meeting metadata and AI-generated summaries. A summary is not a verbatim quote. Read a result to obtain the transcript’s speaker names and timestamps, together with a separately labeled summary. Ongoing meetings return a snapshot of speech recorded so far. Very large transcripts are bounded and visibly marked when truncated.
+Search previews can contain AI summaries. Read the meeting for speaker names and timestamps before quoting speech; summaries are labeled separately. An ongoing meeting returns speech recorded so far. Large transcripts are bounded and marked when truncated.
 
-Every operation rechecks the member’s current grant, provider configuration, and organization/workspace access. Search uses a fixed allowlist of read tools, validates their advertised schemas, and cannot invoke sharing, deletion, or other write operations.
+Sim rechecks the current grant, provider setup, and Sim scope on every operation. Its fixed read-tool allowlist excludes sharing, deletion, and other writes. Schema changes, unsupported formats, provider failures, quotas, plan limits, and meeting permissions can affect retrieval; failures do not appear as complete searches with no matches.
 
-Provider quotas, meeting permissions, and the Fireflies plan still apply. A provider failure or unsupported response format is reported explicitly rather than appearing as a complete search with no matches.
+## Related docs
 
-See [Fireflies MCP tools](https://docs.fireflies.ai/mcp-tools/overview) for the current tool and plan capabilities.
+- [Fireflies MCP tools](https://docs.fireflies.ai/mcp-tools/overview)
+- [Connect your account](/search/connect-your-account)
diff --git a/apps/docs/content/docs/search/generic-secrets.mdx b/apps/docs/content/docs/search/generic-secrets.mdx
index b73e5b7b8a7..eaa76e570ba 100644
--- a/apps/docs/content/docs/search/generic-secrets.mdx
+++ b/apps/docs/content/docs/search/generic-secrets.mdx
@@ -1,25 +1,35 @@
 ---
 title: Generic Secrets
-description: Share organization secrets or let each member keep their own for Build and Plan
+description: Store shared or personal secrets for Build and Plan
 ---
 
-Generic Secrets is a source for values that Build and Plan can use in code and requests. It does not add documents to Search, connect an external account, or start an indexing job. The editor is the same [secrets editor used in workspaces](/platform/credentials).
+Generic Secrets stores values that Build and Plan can use in code and requests. It uses the same [secrets editor as workspaces](/platform/credentials) and does not connect an external account or add searchable documents.
 
 ## Add the source
 
-An organization admin opens **Settings → Sources → Add source → Generic Secrets** and chooses one mode:
+An organization admin opens **Settings → Sources → Add source → Generic Secrets** and chooses a mode:
 
-| Mode | Who manages the values | Who can use them in Build and Plan |
+| Mode | Manage values | Use in Build and Plan |
 | --- | --- | --- |
-| **Organization** | Organization admins open **Secrets** from the source in Settings. | Organization members with Build access use the shared values. Members cannot open the editor to view them. |
-| **Member** | Each person opens **Integrations → Generic Secrets → Manage secrets**. | That person uses only their own values in the organization. |
+| **Organization** | Admins open **Secrets** from the source in Settings. | Members with Build access use shared values. Members cannot open the editor to view them. |
+| **Member** | Each person opens **Integrations → Generic Secrets → Manage secrets**. | Each person uses only their own values in the organization. |
 
-Only the selected mode is active. The admin can change it through **Configure** on the source. Removing the source deletes its organization and member secrets, so review the confirmation before doing so.
+Only the selected mode is active. To change it, select **Configure** on the source.
 
-## Use a secret in Build or Plan
+## Use a secret
 
-Save a name and value in the editor, then ask Build or Plan to run code that needs it. These modes can see available **names** and mount only the names needed by `run_code` or `run_function`. The values become environment variables for that code, so it can use them in a request such as `curl` without putting the value in the prompt.
+1. Save a name and value in the editor.
+2. Ask Build or Plan to run code that needs that secret.
+3. The mode sees available names and mounts the names needed by `run_code` or `run_function` as environment variables. Code can use them in requests such as `curl` without putting values in the prompt.
 
-In an organization Build or Plan conversation targeting a workspace, an organization secret with the same name takes precedence over a workspace secret. In Member mode, the source resolves the current member's values; it does not read another member's secrets.
+In an organization conversation targeting a workspace, an organization secret takes precedence over a workspace secret with the same name. Member mode resolves the current member's values and cannot use another member's secrets.
 
-Generic Secrets are available **only in Build and Plan modes**. Search, the Search assistant, Search MCP, and Sim Search in Slack cannot mount them. Workspace secrets remain a separate resource.
+Generic Secrets is available only in **Build** and **Plan**. Search mode, Search MCP, and Sim Search in Slack cannot mount these values. Workspace secrets remain a separate resource.
+
+## Remove the source
+
+Removing the source deletes its organization and member secrets. Review the confirmation before removing it.
+
+## Related docs
+
+- [Workspace credentials and secrets](/platform/credentials)
diff --git a/apps/docs/content/docs/search/github.mdx b/apps/docs/content/docs/search/github.mdx
index 3d9e6a70d36..637c52ad9e7 100644
--- a/apps/docs/content/docs/search/github.mdx
+++ b/apps/docs/content/docs/search/github.mdx
@@ -1,70 +1,69 @@
 ---
 title: GitHub
-description: Search GitHub with member accounts or an App restricted to selected repositories
+description: Search GitHub with your account and optional repository restrictions
 ---
 
-GitHub supports **Member accounts** and **GitHub App**. Each person connects their own GitHub account in both modes. Live Search calls GitHub's APIs for issues, pull requests, code, repositories, and commits on `github.com`.
+GitHub Search reads repositories, code, issues, pull request discussions, and commits on `github.com`. **Member accounts** uses your access; **GitHub App** limits Search to repositories your admin adds. Both modes require your personal GitHub connection. GitHub Enterprise Server and `ghe.com` hosts are not supported.
 
-## Member accounts
+## Connect member accounts
 
-An admin adds GitHub in **Settings → Sources**, selects **Member accounts**, and saves. Each member connects GitHub from **Integrations**. There is no admin repository selection in this mode: the member's provider access determines what they can search.
+An admin adds **GitHub** in **Settings → Sources**, chooses **Member accounts**, and saves. Each member connects GitHub in **Integrations**. There is no admin repository selection in this mode.
 
-Native GitHub qualifiers such as `repo:`, `org:`, and `user:` can narrow an individual search. Without an explicit scope, discovery is bounded to the connected account's first 100 affiliated repositories. Provider search and pagination limits still apply.
+Search a known issue or file, read the result, and follow its GitHub link. Native qualifiers such as `repo:`, `org:`, and `user:` narrow a query. Without explicit scope, discovery is bounded to the account's first 100 affiliated repositories. Search and pagination limits still apply.
 
 ## Add a repository
 
-For an organization-selected repository boundary, use **GitHub App**:
+Use **GitHub App** for an organization-selected repository boundary:
 
 1. Open **Settings → Sources → Add source → GitHub**, choose **GitHub App**, and select **Add repository**.
-2. Connect the GitHub App installation. Choose the account or organization and approve its repository access. An organization owner may need to approve or perform installation.
-3. Choose one repository from the searchable **Repository** picker. Installing on all repositories does not automatically add them all to Search.
-4. Optionally set **Path Filter** and **File Extensions** for code results, then save.
-5. Use **Add repository** again for every additional repository.
-6. Each teammate opens **Integrations → GitHub → Connect** and authorizes their own account.
+2. Connect the App installation and approve repository access for its account or organization. An organization owner may need to approve or perform installation.
+3. Select one repository in **Repository**. Installing on all repositories does not add them all to Search.
+4. Optionally set **Path Filter** and **File Extensions**, then save.
+5. Use **Add repository** for each additional repository.
+6. Each teammate connects their own GitHub account in **Integrations**.
 
-The App installation and personal authorization are separate. A member connects once per Sim organization; adding another repository reuses that connection. The member never receives the installer's permissions.
+A member connects once per Sim organization; additional repositories reuse that connection. The installation does not give members the installer's permissions.
 
-GitHub's live code search uses the default branch, so the live source form does not offer a branch setting. Path and extension filters apply to code; they do not narrow issue text by file path.
+Code search uses the default branch, so the source form has no branch setting. Path and extension filters affect code results, not issue text.
 
-## How access and filtering work
+## Search pull request discussions
 
-Search queries GitHub using the member's connected token. In App mode, Sim scopes the query to configured repositories. For each result, it checks the installation's current repository access, obtains a repository-scoped read token, verifies stable repository and owner identities under both tokens, and applies the source's code filters.
+Use native kind `issues` for issues and pull requests:
 
-Document reads use the member token and repeat the same boundary checks. A personal repository outside the selected sources is excluded even when the member can read it. Removing a repository from the App or revoking the member's access blocks later requests once GitHub reflects the change.
-
-There is no content crawl, PDF/Office extraction, embedding, or indexed-document retry in live GitHub Search. Provider search freshness, API limits, and supported search types determine coverage. Code search is not a complete inventory of every file.
-
-## Pull requests, comments, and reviews
+| Find | Example query |
+| --- | --- |
+| Migration discussion | `repo:org/repo is:pr migration in:comments` |
+| PRs needing changes | `repo:org/repo is:pr review:changes_requested` |
+| PRs reviewed by someone | `repo:org/repo is:pr reviewed-by:octocat` |
+| PRs awaiting someone's review | `repo:org/repo is:pr review-requested:octocat` |
 
-Reading an issue includes its conversation comments. Reading a pull request also includes submitted review events and inline review comments. Each entry retains its author, timestamp, and GitHub link; inline comments include file/line context, review and reply identifiers, and the relevant diff excerpt. Review states describe individual historical events, so an earlier approval does not establish the current merge approval status.
+Without `in:`, GitHub searches titles, bodies, and conversation comments. Previews use matching passages where provided. Issue search is not exhaustive across inline reviews: first locate the PR by repository, title, participant, or review state, then read it. Commits require native kind `commits`.
 
-Use native searches with **kind `issues`** for both issues and pull requests:
+Issue reads include comments. PR reads also include submitted reviews and inline comments, preserving authors, timestamps, links, file/line context, review and reply IDs, and diff excerpts. A historical approval is not the current merge approval status.
 
-| Question | Example query |
-| --- | --- |
-| Where was a migration discussed? | `repo:org/repo is:pr migration in:comments` |
-| Which PRs need changes? | `repo:org/repo is:pr review:changes_requested` |
-| Which PRs did someone review? | `repo:org/repo is:pr reviewed-by:octocat` |
-| Which PRs are awaiting someone's review? | `repo:org/repo is:pr review-requested:octocat` |
+Each discussion category is limited to three pages of 50 entries and 120,000 characters, in provider order. Failed endpoints or reached limits produce an incomplete-coverage notice while preserving available content. Follow returned document offsets for more read windows; open GitHub for remaining history.
 
-GitHub searches title, body, and conversation comments when `in:` is omitted. Search previews use matching passages when GitHub supplies them, including comment matches. Inline review text is available when reading a matching PR; do not treat issue search as an exhaustive search across inline reviews. First locate the PR by repository, title, participant, or review state, then read its discussion.
+## Access and source changes
 
-Reads retrieve up to three pages of 50 entries for each GitHub discussion category, in provider order, with a 120,000-character limit per category. When an endpoint fails or a limit is reached, the document starts with an incomplete-coverage notice while retaining the available content. Open the GitHub source for remaining history. Large reads can also require continuing through the returned document offsets.
+Search and reads use your connected token. App mode also checks the installation's current repository access, verifies repository and owner identities under both tokens, and applies code filters. Personal repositories outside the selected sources are excluded. Revoking member access or removing installation access blocks later requests once GitHub reflects the change.
 
-## Manage repositories
+Open **Settings → Sources → GitHub** to edit repositories. A replacement connection must access the same configured repository; use **Add repository** for another. Removing a source stops later access through it.
 
-Open **Settings → Sources → GitHub** to add repositories or change their settings. Replace a connection only with one that can access the same configured repository; use **Add repository** for another repository. Removing a source stops subsequent Search access through that source.
+Provider freshness, API limits, and supported search types determine coverage. Live code search is not an inventory of every file and does not run a crawl, Office/PDF extraction, or embedding job.
 
 ## Troubleshooting
 
-| Problem | Next step |
+| Problem | Check |
 | --- | --- |
-| GitHub is unavailable | Add the source and check the deployment's GitHub Search App configuration. |
-| Repository missing from the picker | Confirm the installation includes it and that the selected account can read it. |
-| Member cannot find an allowed repository | Confirm both personal access and App installation access. Check GitHub SSO and app policies. |
-| The wrong account is connected | Disconnect or reconnect with the intended GitHub account. |
-| A file does not appear in search | Check the default branch, path/extensions, GitHub code-search behavior, and provider limits. |
-| Installation does not return to Sim | Check the App setup URL and Redirect on update settings. |
-| Reconnect appears | Renew the member grant; changing App permissions may require renewed approval. |
-
-Self-hosted Sim operators configure the App using [GitHub Search setup](/platform/self-hosting/integrations-oauth#github-search). This adapter does not support GitHub Enterprise Server or `ghe.com` hosts. Ordinary GitHub knowledge-base connectors retain their separate indexing behavior.
+| GitHub unavailable | Add the source and check the deployment's GitHub Search App setup. |
+| Repository missing from picker | Check installation access and the selected account's access. |
+| Allowed repository missing | Check personal access, installation access, GitHub SSO, and app policies. |
+| Wrong account connected | Disconnect or reconnect with the intended account. |
+| File missing | Check default branch, path/extensions, code-search behavior, and limits. |
+| Installation does not return to Sim | Check App setup URL and **Redirect on update**. |
+| **Reconnect** needed | Renew the member grant; App permission changes may require approval. |
+
+## Related docs
+
+- [Self-hosted GitHub Search setup](/platform/self-hosting/integrations-oauth#github-search)
+- [Knowledge-base connectors](/knowledgebase/connectors) — separate indexing behavior
diff --git a/apps/docs/content/docs/search/gitlab.mdx b/apps/docs/content/docs/search/gitlab.mdx
index 7b3024175b1..03a9eeb9634 100644
--- a/apps/docs/content/docs/search/gitlab.mdx
+++ b/apps/docs/content/docs/search/gitlab.mdx
@@ -1,53 +1,53 @@
 ---
 title: GitLab
-description: Search self-managed GitLab projects with current administrator checks or CSV permissions
+description: Search self-managed projects with live administrator checks or CSV grants
 ---
 
-GitLab uses **Service account** mode only. Add one self-managed project per source. Teammates do not connect personal GitLab accounts; Sim matches their verified identity to the project's permission strategy on every search and read.
+GitLab Search uses **Service account** mode, with one self-managed project per source. Teammates do not connect personal GitLab accounts. Sim matches their verified identity to the source's permission strategy on each search and read.
 
-## Choose a token path
+## Choose a permission strategy
 
-| | Administrator token | Non-admin token |
+| Requirement | Administrator token | Non-admin token |
 | --- | --- | --- |
-| Token identity | Active instance administrator | Identity that can read the configured project's content |
-| PAT scopes | `read_api`; also `admin_mode` when Admin Mode is enabled | `read_api` |
-| Reader permissions | Current GitLab identity, project/group membership, roles, and supported restrictions | Administrator-uploaded user mapping and project grants |
-| Membership changes | Checked from GitLab during the request | Admin must update the CSV files |
-| Confidential issues | Returned only when supported GitLab permissions allow that reader | Always excluded |
+| Token owner | Active instance administrator | Account that can read the project's content |
+| PAT scopes | `read_api`; `admin_mode` when Admin Mode is enabled | `read_api` |
+| Reader authorization | Current GitLab identity, membership, roles, and supported restrictions | Admin-uploaded email mapping and project grants |
+| Membership changes | Checked during the request | Admin updates the CSV files |
+| Confidential issues | Only when supported permissions allow the reader | Always excluded |
 
-The administrator path requires a supported self-managed GitLab instance (17.4 or later) and access to its administrator identity/settings APIs. A project Maintainer or group Owner is not an instance administrator. A non-admin source does not require those administrator APIs.
+The administrator path requires self-managed GitLab 17.4 or later and its administrator identity/settings APIs. A project Maintainer or group Owner is not an instance administrator. Non-admin mode does not require those administrator APIs.
 
-The instance must be reachable from the Sim server and pass its configured outbound-request protections. Use the actual self-managed host, not `gitlab.com`, for the source. Each saved source binds its host and project identity; a search query cannot redirect its token to another instance or project.
+The instance must be reachable from the Sim server and pass outbound-request protections. Use the self-managed host, not `gitlab.com`. Each source binds its host and project; a query cannot redirect the token elsewhere.
 
 ## Add a project
 
-1. Create a read-only PAT in the chosen GitLab account, with the scopes above and an appropriate expiry.
-2. Open **Settings → Sources → Add source → GitLab**, then **Add project**. For another project, open GitLab's source page and use **Add project** again.
+1. Create a read-only PAT with the chosen scopes and an appropriate expiry.
+2. Open **Settings → Sources → Add source → GitLab → Add project**.
 3. Choose **Administrator token** or **Non-admin token**.
 4. Enter the token, self-managed **Host**, and exact **Project** path or numeric ID.
-5. Choose the content scope and any filters. In non-admin mode, upload both CSV files below.
-6. Save the source. Have a permitted teammate search and read known content, then repeat as a teammate without a grant.
+5. Choose content and filters. Non-admin mode requires both CSV files below.
+6. Save, then have a permitted teammate search and read known content. Repeat with a teammate who has no grant.
 
-There is no initial content sync. Organization membership and a matching verified email are required, but membership alone does not authorize project content.
+Use **Add project** again for another project. There is no initial sync. Organization membership and a matching verified email are required, but membership alone does not grant project access.
 
 ## Resource settings
 
 | Setting | Effect |
 | --- | --- |
 | Content | **Wiki & Issues** by default; the broader choice includes code and merge requests. |
-| Branch / tag | Code search and reads use the selected ref; blank uses the project's default branch. |
+| Branch / tag | Code uses the selected ref; blank uses the default branch. |
 | Path prefix / file extensions | Restrict code results. |
-| Issue state | Restricts matching issues. |
+| Issue state | Restricts issues. |
 | Issue labels | Every configured label must match. |
 | Milestone | Exact issue milestone title. |
 
-Search requests are scoped to the configured project. Sim checks returned content against these restrictions rather than trusting a provider query alone. API search support can depend on the GitLab version and enabled search capabilities; unsupported or unavailable searches are reported instead of falling back to an old index.
+Sim checks returned content against these restrictions independently of the query. Available search APIs depend on the GitLab version and enabled search capabilities. Unsupported searches are reported explicitly.
 
 ## Non-admin CSV permissions
 
-Use **Download template** beside each field, replace the example rows, and upload both files.
+Use **Download template** beside each field, replace the examples, and upload both files.
 
-**User mapping** maps numeric GitLab user IDs to verified Sim email addresses:
+**User mapping** maps numeric GitLab user IDs to verified Sim emails:
 
 ```csv
 user_id,email
@@ -55,7 +55,7 @@ user_id,email
 456,bob@example.com
 ```
 
-**Project permissions** grants each mapped user access to the named project:
+**Project permissions** grants mapped users access to the project:
 
 ```csv
 project_path,user_id
@@ -63,41 +63,40 @@ engineering/platform,123
 engineering/platform,456
 ```
 
-Use the full namespace path even when the Project field contains a numeric ID. Inherited members must be included explicitly when they should have access. A grant without a corresponding email mapping grants nothing.
+Use the full namespace path even if **Project** contains a numeric ID. Include inherited members explicitly. A grant without an email mapping grants nothing; rows for other projects cannot expand this source.
 
-- Each file has exactly two columns in the shown order and at least one data row. Exact template headers or headerless data are accepted.
-- Use UTF-8 CSV, at most 4 MiB and 100,000 data rows per file; the complete request must fit the 10 MiB request limit.
+- Each file has exactly two columns in the shown order and at least one data row. Template headers or headerless data are accepted.
+- Use UTF-8 CSV, at most 4 MiB and 100,000 data rows per file. The full request must fit 10 MiB.
 - Identical rows are deduplicated. Conflicting user-ID/email mappings and malformed rows are rejected.
-- Rows for another project do not expand this source's boundary.
 
-CSV grants are administrator-managed authorization. Each granted reader may search the source's allowed non-confidential content; Sim does not infer that person's actual GitLab role, feature restrictions, or membership from a non-admin token. Keep these files accurate when access changes.
+These grants are admin-managed authorization. A granted reader can search allowed non-confidential content; Sim does not infer that person's actual GitLab role, restrictions, or membership from the non-admin token. Update both files when access changes.
 
-## How access is enforced
+## Access checks
 
-The configured token searches and reads the project. Unlike other service-account providers, GitLab does not obtain a personal reader token.
+The source token retrieves content. Administrator mode proves the reader's current GitLab identity from verified Sim email, then checks project/group membership and policy during the request. Unsupported restrictions fail closed.
 
-With an administrator token, Sim proves the reader's current GitLab identity from their verified Sim email, loads current membership and relevant project/group policy, and constructs permission evidence within that request. This is not a scheduled ACL build or a stored directory snapshot. Unsupported restrictions fail closed.
+Non-admin mode uses saved source-local CSV grants and revalidates the token's current host/project identity. Confidential issues are excluded, including issues that became confidential after search.
 
-With a non-admin token, Sim uses the saved source-local CSV mappings and revalidates the token's current host/project identity. Confidential issues are excluded, including when fresh read metadata shows an issue became confidential after search.
+Reads recheck current settings, permissions, and metadata. A reference from another member, account, organization, project, or host cannot authorize a read. Live Search does not use a stored content or permission index.
 
-Reads recheck current settings, permission evidence, and content metadata before returning text. Sim does not allow a document reference from another member, account, organization, project, or host to authorize a read.
+## Update permissions or rotate the token
 
-## Change permissions or rotate the token
+In project settings, replace either CSV file, retaining the other when appropriate. Sim validates the resulting pair before saving. Invalid or stale updates preserve saved grants. Removed readers lose access on the next operation.
 
-Open the project's settings and replace either CSV file, retaining the other when appropriate. Sim validates the resulting pair before saving. Invalid or stale updates preserve the saved grants. Removed users lose access on the next operation; there is no crawl or re-embedding step.
-
-To rotate a PAT, supply the replacement in the source's settings. Leaving the token blank keeps the saved token. Changing project, host, or permission strategy requires a valid configuration for the new identity; old indexed ACL state is not used to authorize live requests.
+To rotate the PAT, supply its replacement in source settings. A blank token retains the saved token. Changing host, project, or permission strategy requires valid configuration for the new identity.
 
 ## Troubleshooting
 
-| Problem | Next step |
+| Problem | Check |
 | --- | --- |
-| Administrator token required | Use an instance-admin PAT, or choose Non-admin token and supply both CSVs. |
-| Host or project cannot be reached | Check the saved host, server connectivity/outbound rules, project identity, and token access. |
-| Member sees no results | Check their verified Sim email, Sim membership, current GitLab identity/role or CSV grant, content scope, and query. |
-| Confidential issue is missing | Expected in CSV mode; in admin mode, check the reader's supported GitLab permissions. |
-| CSV upload fails | Correct the reported rows and size limits; the previous saved grants remain in effect. |
-| Source permissions cannot be verified | Check the reported GitLab restriction. Do not broaden access to bypass failed verification. |
-| Search type is unavailable | Check your instance's search capabilities and version. A connected project does not guarantee every search endpoint is enabled. |
-
-Ordinary GitLab [knowledge-base connectors](/knowledgebase/connectors), and explicitly restored legacy Search, retain their own indexing and permission-maintenance behavior.
+| Administrator token required | Use an instance-admin PAT, or select **Non-admin token** and upload both CSVs. |
+| Host/project unreachable | Check host, server connectivity/outbound rules, project identity, and token access. |
+| No results | Check verified Sim email, membership, GitLab identity/role or CSV grant, content scope, and query. |
+| Confidential issue missing | Expected in CSV mode; otherwise check the reader's supported permissions. |
+| CSV upload fails | Correct reported rows and size limits; saved grants remain in effect. |
+| Permissions cannot be verified | Check the reported restriction. Do not broaden access to bypass verification. |
+| Search type unavailable | Check instance version and capabilities; connection alone does not enable every endpoint. |
+
+## Related docs
+
+- [Knowledge-base connectors](/knowledgebase/connectors) — separate ingestion and permission maintenance
diff --git a/apps/docs/content/docs/search/gmail.mdx b/apps/docs/content/docs/search/gmail.mdx
index 523ceedb93f..b2c6bdd1888 100644
--- a/apps/docs/content/docs/search/gmail.mdx
+++ b/apps/docs/content/docs/search/gmail.mdx
@@ -1,94 +1,77 @@
 ---
 title: Gmail
-description: Search your connected mailbox with optional service-account label and date restrictions
+description: Search your mailbox and read authorized conversation context
 ---
 
-Gmail supports **Member accounts** and **Service account**. Each person connects Gmail in Integrations in either mode. Search reads matching messages from that connected mailbox through the Gmail API; connecting an account does not start indexing.
+Gmail Search finds matching messages in your connected mailbox. **Member accounts** uses your access and Gmail query syntax. **Service account** adds mailbox, label, date, and query restrictions. Each reader connects Gmail in both modes.
 
-## Member accounts
+## Connect member accounts
 
-An admin adds **Gmail** under **Settings → Sources**, chooses **Member accounts**, and saves. Members then select **Integrations → Gmail → Connect**. Member mode has no admin label, date, category, or mailbox filters. Gmail search syntax and the connected account determine matches.
+An admin adds **Gmail** in **Settings → Sources**, chooses **Member accounts**, and saves. Members select **Integrations → Gmail → Connect**, then search for a known message and read it.
 
-Search reads email; it does not send or modify messages. The personal account connection is shared with workflow capabilities, so its authorization can include broader scopes.
+Member mode has no admin label, date, category, or mailbox filters. Search does not send or modify messages, though the shared personal connection may request broader workflow scopes.
 
 ## Set up a central service account
 
-1. In Google Cloud, enable **Gmail API** and **Admin SDK API**, create a service account, and download its JSON key.
-2. In Google Workspace Admin, authorize domain-wide delegation for that service account's numeric client ID with these scopes:
+1. Enable **Gmail API** and **Admin SDK API** in Google Cloud. Create a service account and download its JSON key.
+2. In Google Workspace Admin, authorize domain-wide delegation for its numeric client ID with:
 
-```text
-https://www.googleapis.com/auth/gmail.readonly
-https://www.googleapis.com/auth/admin.directory.user.readonly
-```
+   ```text
+   https://www.googleapis.com/auth/gmail.readonly
+   https://www.googleapis.com/auth/admin.directory.user.readonly
+   ```
 
-3. In **Settings → Sources → Gmail**, choose **Service account** and **Add connection**. Add or select the Google service credential.
-4. Set **Delegated administrator** to an active Workspace administrator who can read Directory users. Set any selected **Users**, labels, date range, exclusions, and search filter, then save.
-5. Select the saved connection as Gmail's service source. Every reader still connects their personal Gmail account in Integrations.
+3. In **Settings → Sources → Gmail**, choose **Service account → Add connection** and add or select the Google service credential.
+4. Set **Delegated administrator** to an active Workspace administrator with Directory user-read access. Configure **Users**, labels, date range, exclusions, or search filter, then save.
+5. Select the connection as Gmail's service source. Every reader still connects Gmail personally in **Integrations**.
 
-Use primary Workspace email addresses for selected users. Leaving **Users** empty permits eligible connected mailboxes in the same Workspace customer; it does not search everyone else's mailbox. Gmail delegation always targets the connected member's verified provider identity.
-
-For a shared key, see [one service account for all three Google sources](/search/google-drive#one-service-account-for-drive-gmail-and-calendar).
+Selected users must use primary Workspace email addresses. An empty **Users** selection allows eligible connected mailboxes in the same Workspace customer, not other people's mailboxes. Delegation always targets the connected member's verified provider identity.
 
 ## Service-source settings
 
 | Setting | Effect |
 | --- | --- |
-| Users | Optional allowed primary Workspace mailboxes. A member outside the selection gets no matches through this source. |
-| Labels | Selected labels are alternatives. The picker browses the delegated administrator's mailbox and saves label names, since custom label IDs differ by mailbox. |
-| Date Range | A rolling window checked against each message. |
-| Search Filter | A Gmail query that matching messages must also satisfy. |
-| Exclude Promotions / Social | Additional category exclusions; the existing service-source defaults exclude both. |
+| **Users** | Optional allowed primary Workspace mailboxes. Other members get no matches through the source. |
+| **Labels** | Alternatives: any selected label can match. The picker uses the delegated administrator's mailbox and saves names, because custom label IDs differ between mailboxes. |
+| **Date Range** | Rolling window checked against each message. |
+| **Search Filter** | Gmail query that each message must also satisfy. |
+| **Exclude Promotions / Social** | Category exclusions; existing service-source defaults exclude both. |
 
-These settings apply only to service mode. They do not appear as member-account configuration.
+These settings apply only to service mode.
 
 ## How INBOX filtering works
 
-For **Labels = INBOX**, a connected member's search follows these steps:
+With **Labels = INBOX**, Sim verifies the connected Gmail identity, active Workspace user, and customer match. Gmail searches that person's mailbox with the query, INBOX restriction, and category exclusions. Sim then uses the service account delegated to that same mailbox to check each candidate's current labels, rolling date window, and custom query.
+
+Custom labels are resolved in the member's mailbox. Custom queries are checked against the exact candidate message. A message outside INBOX is excluded even when the member can read it.
 
-1. Sim verifies the connected Gmail identity and the source's active Workspace user/customer match.
-2. Gmail searches that member's mailbox with their query, the INBOX restriction, and the configured category exclusions.
-3. Sim uses the service account delegated to that same mailbox to fetch each candidate's current metadata.
-4. It checks current label IDs, the source's rolling date range, and any custom query. Custom labels are resolved within that member's mailbox. Custom queries are verified against the exact candidate message.
-5. Only allowed messages are returned. Reading a result fetches that individual message through the member's connection and repeats the source checks.
+A read includes the matching message and up to seven recent messages from its conversation, in chronological order. Every included message must independently pass the source's current restrictions before its body is fetched and again before content is returned. One allowed message cannot authorize the rest of a thread.
 
-A message the member can read but that is outside INBOX does not pass. Search does not substitute the administrator's mailbox or expose another message from the same thread merely because one message matched.
+Conversation content preserves sender, date, subject, and source link. Each message is limited to 24,000 characters. Omitted, truncated, or preview-only context is labeled; open Gmail for the remaining conversation. Reads exclude named attachments and bound MIME traversal to 32 levels and 256 parts.
 
-Gmail API matching is message-based and differs from Gmail's UI for some thread-wide and alias searches. See [Google's filtering guide](https://developers.google.com/workspace/gmail/api/guides/filtering). Attachment search operators can select a message; Search does not separately ingest attachment contents.
+Gmail API search is message-based and differs from the UI's thread-wide matching and alias expansion. Attachment operators can find a message, but Search does not ingest attachment contents. [Google's filtering guide](https://developers.google.com/workspace/gmail/api/guides/filtering).
 
 ## Troubleshooting
 
-| Problem | Next step |
+| Problem | Check |
 | --- | --- |
-| Google rejects delegation | Check the numeric client ID, delegated scopes, pending Workspace approval, and JSON key. |
-| Directory user is unavailable | Use an active primary Workspace user in the source's customer and an administrator with user-read access. |
-| Connected member sees no results | Check their mailbox, selected Users, labels, date range, exclusions, and custom query. |
-| Custom label is missing | Confirm that label exists in the member's mailbox; administrator and member label IDs need not match. |
-| Provider is rate limited or coverage is incomplete | Retry as directed or narrow the query; there is no document-indexing retry. |
+| Delegation rejected | Check numeric client ID, approved scopes, pending Workspace approval, and key. |
+| Directory user unavailable | Use an active primary user in the source's customer and an administrator with user-read access. |
+| No results | Check connected mailbox, Users, labels, date range, exclusions, and custom query. |
+| Custom label missing | Confirm the label exists in the member's mailbox; IDs need not match the admin's labels. |
+| Rate limit or incomplete coverage | Retry as directed or narrow the query. There is no indexing retry. |
 
-## Self-hosted operator setup
+## Self-hosted member OAuth
 
-Configure the deployment’s Google OAuth client for every member’s personal connection, including members using a service-account source. This is separate from domain-wide delegation.
-
-1. In [Google Cloud Console](https://console.cloud.google.com/), select your project. Open **APIs & Services → Library**, find **Gmail API**, and enable it.
-2. Open **Google Auth platform → Branding**. Select **Get started** if needed, then enter the app name, support email, and contact email. Under **Audience**, use **Internal** only for an app limited to your Google Workspace organization; otherwise use **External** and add test users while testing. Review the app's permissions under **Data Access → Add or remove scopes**, using the current Sim scopes below. Follow Google's [consent and verification guidance](https://developers.google.com/workspace/guides/configure-oauth-consent) for your audience.
-3. Open **Google Auth platform → Clients → Create client**. Choose **Web application**, give the client a name, and add the URI below under **Authorized redirect URIs**. If this instance already has a Google client, add this URI to that client instead. See [Google's credential setup](https://developers.google.com/workspace/guides/create-credentials#web-application).
-4. Save the client ID and secret as `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`. Set `NEXT_PUBLIC_APP_URL` to the same Sim origin used in the callback, then restart Sim. See [Integrations & OAuth](/platform/self-hosting/integrations-oauth). If you change an existing deployment's OAuth client or scopes, an organization admin updates the provider configuration and affected teammates reconnect.
+Follow [Google OAuth setup](/platform/self-hosting/integrations-oauth#google) for **Gmail API**, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, consent, and full member scopes. Set `NEXT_PUBLIC_APP_URL` to the callback origin and register:
 
 ```text
 https://<your-sim-domain>/api/auth/oauth2/callback/google-email
 ```
 
-One OAuth client can register callbacks for all three Google services. Use your exact Sim origin and add only the callbacks for services you enable.
-
-The member-account OAuth connection uses these scopes:
+This personal grant also supports workflows and uses Gmail modify/send/labels scopes. It is separate from the read-only delegation scopes above, and remains required in service mode. One OAuth client can register each enabled Google service's callback. After changing the client or scopes, update saved organization provider configuration and reconnect affected members.
 
-```text
-openid
-https://www.googleapis.com/auth/userinfo.email
-https://www.googleapis.com/auth/userinfo.profile
-https://www.googleapis.com/auth/gmail.modify
-https://www.googleapis.com/auth/gmail.send
-https://www.googleapis.com/auth/gmail.labels
-```
+## Related docs
 
-The personal OAuth connection also supports workflow actions, so its declared scopes can be broader than Search’s read-only requests. The service credential uses the separate delegation scopes above.
+- [One service account for Drive, Gmail, and Calendar](/search/google-drive#one-service-account-for-drive-gmail-and-calendar)
+- [Connect your account](/search/connect-your-account)
diff --git a/apps/docs/content/docs/search/google-calendar.mdx b/apps/docs/content/docs/search/google-calendar.mdx
index adc08458fc4..4666349b38d 100644
--- a/apps/docs/content/docs/search/google-calendar.mdx
+++ b/apps/docs/content/docs/search/google-calendar.mdx
@@ -1,77 +1,66 @@
 ---
 title: Google Calendar
-description: Search events live with each member's calendar access
+description: Search events and agendas using your Calendar account
 ---
 
-Google Calendar supports **Member accounts** and **Service account**. Every reader connects Google Calendar in Integrations. Search queries event APIs with the connected member's account, preserving the details Google permits that person to see.
+Search event text or request an agenda for a date range. Sim uses your Google Calendar account and preserves the details Google permits you to see. **Service account** mode adds calendar, user, and date-window restrictions; both modes require a personal connection.
 
-## Member accounts
+## Connect member accounts
 
-Add **Google Calendar** under **Settings → Sources**, choose **Member accounts**, and save. Members authorize **Google Calendar** under **Integrations**. There are no organization calendar or date-window filters in member mode. A query can target a calendar or request an agenda for a date range.
+An admin adds **Google Calendar** in **Settings → Sources**, chooses **Member accounts**, and saves. Members connect Google Calendar in **Integrations**. Search for a known event and read the result.
 
-Connecting does not ingest events or build permission records. Changes appear according to Google's API responses.
+Member mode has no organization calendar or date-window filters. A query can select a calendar or dates. Connecting does not ingest events or build permission records; availability follows Google's API responses.
 
 ## Set up a central service account
 
-1. Enable **Google Calendar API** and **Admin SDK API** in Google Cloud. Create a service account and download its JSON key.
-2. Authorize domain-wide delegation for its numeric client ID in Google Workspace Admin with all three scopes:
+1. Enable **Google Calendar API** and **Admin SDK API**. Create a Google service account and download its JSON key.
+2. Authorize domain-wide delegation in Workspace Admin for its numeric client ID with:
 
-```text
-https://www.googleapis.com/auth/calendar.events.readonly
-https://www.googleapis.com/auth/calendar.readonly
-https://www.googleapis.com/auth/admin.directory.user.readonly
-```
+   ```text
+   https://www.googleapis.com/auth/calendar.events.readonly
+   https://www.googleapis.com/auth/calendar.readonly
+   https://www.googleapis.com/auth/admin.directory.user.readonly
+   ```
 
-Search reads events with `calendar.events.readonly`. The calendar picker also needs `calendar.readonly` to list the delegated administrator's calendars. See [CalendarList authorization](https://developers.google.com/workspace/calendar/api/v3/reference/calendarList/list).
+3. In **Settings → Sources → Google Calendar**, choose **Service account → Add connection**. Add or select the credential and set **Delegated administrator** to an active Workspace administrator with Directory user-read access.
+4. Choose calendars, users, date range, and optional event-text and attendee settings. Save and select the connection as the service source.
+5. Each member connects Calendar personally in **Integrations**.
 
-3. In **Settings → Sources → Google Calendar**, choose **Service account**, then **Add connection**. Add or select the Google credential and set **Delegated administrator** to an active Workspace administrator with Directory user-read access.
-4. Select calendars, users, a date range, and optional event-text and attendee settings. Save and select this connection as the service source.
-5. Members connect their personal Calendar accounts in **Integrations**.
+Event reads use `calendar.events.readonly`; the picker also needs `calendar.readonly` to list the administrator's calendars. [CalendarList authorization](https://developers.google.com/workspace/calendar/api/v3/reference/calendarList/list).
 
-The picker browses the delegated administrator's calendars. The `primary` choice is saved as an alias for each connected member's primary calendar. A specific shared-calendar ID must be accessible to the member and through the source's delegation.
+The picker uses the delegated administrator's calendar list. `primary` means each connected member's primary calendar. A specific shared-calendar ID must be accessible to that member and through the source's delegation.
 
-## How filtering works
+## Source restrictions and event details
 
-Sim verifies the connected account's primary-calendar identity and its active Directory identity in the source's Workspace customer. If Users is selected, that member must be included. The service credential then delegates to that same member, not to another user's calendar view.
+Sim checks the account's primary-calendar identity, active Directory identity, Workspace customer, and any selected **Users**. Delegation targets that member's view.
 
-Search incorporates selected calendars and date bounds into the provider request. Each result must still exist through the delegated source credential, belong to an allowed calendar, be non-cancelled, and overlap the configured rolling window. The default source window is 30 days before and after the request. A source text query is independently verified against the exact event.
+Search applies selected calendars and date bounds. Each event must also exist through the delegated credential, belong to an allowed calendar, be non-cancelled, and overlap the source's rolling window. The default service-source window is 30 days before and after the request. A source text query is verified against the exact event.
 
-Recurring events expand within the search window. All-day events use the calendar's timezone. `Include Attendees` controls attendee details, and the member's provider access still limits private event details. Reads repeat these checks.
+Recurring events expand within the search window. All-day events use the calendar's timezone. **Include Attendees** controls attendee details; private event details remain limited by the member's access. Reads repeat these checks.
 
-Sim does not copy the organizer's richer event details into an attendee's view or separately ingest attachments, recordings, or transcripts. Provider limits and bounded calendar traversal can produce incomplete coverage.
+Sim does not substitute the organizer's richer view or ingest event attachments, recordings, or transcripts. Member retrieval visits up to 20 calendars; provider paging and bounded traversal can limit coverage.
 
 ## Troubleshooting
 
-| Problem | Next step |
+| Problem | Check |
 | --- | --- |
-| Calendar picker fails | Include `calendar.readonly` in delegation, along with the other scopes above. |
-| A member gets no matches | Check their personal connection, primary Workspace identity, Users selection, calendars, and source date window. |
-| Shared calendar is missing | Confirm both the member and delegated source identity can access that calendar ID. |
-| Event is outside the configured range | Adjust the service source's range or narrow the user's query to its allowed window. |
-| Google rejects delegation | Verify client ID, key, Directory administrator access, and Workspace approval. |
-
-## Self-hosted operator setup
+| Calendar picker fails | Include `calendar.readonly` along with event and Directory delegation scopes. |
+| No matches | Check personal connection, primary Workspace identity, Users, calendars, and source window. |
+| Shared calendar missing | Confirm member and delegated source access to that calendar ID. |
+| Event outside allowed range | Adjust the service window or search within it. |
+| Delegation rejected | Check client ID, key, administrator access, and Workspace approval. |
 
-Configure the deployment’s Google OAuth client for every member’s personal connection, including members using a service-account source. This is separate from domain-wide delegation.
+## Self-hosted member OAuth
 
-1. In [Google Cloud Console](https://console.cloud.google.com/), select your project. Open **APIs & Services → Library**, find **Google Calendar API**, and enable it.
-2. Open **Google Auth platform → Branding** and configure the app name and contact details. Under **Audience**, choose **Internal** for your Google Workspace organization only, or **External** for other users. Add test users while an external app is testing. Review **Data Access → Add or remove scopes** using the current Sim scopes below. See Google's [consent and verification guidance](https://developers.google.com/workspace/guides/configure-oauth-consent).
-3. Open **Google Auth platform → Clients → Create client**, choose **Web application**, and add the URI below under **Authorized redirect URIs**. Add it to the existing Google client if the instance already uses one. See [Google's credential setup](https://developers.google.com/workspace/guides/create-credentials#web-application).
-4. Save the client ID and secret as `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`. Set `NEXT_PUBLIC_APP_URL` to the same Sim origin used in the callback, then restart Sim. See [Integrations & OAuth](/platform/self-hosting/integrations-oauth). If you change an existing deployment's OAuth client or scopes, an organization admin updates the provider configuration and affected teammates reconnect.
+Follow [Google OAuth setup](/platform/self-hosting/integrations-oauth#google) for **Google Calendar API**, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, consent, and full member scopes. Match `NEXT_PUBLIC_APP_URL` to the callback origin and register:
 
 ```text
 https://<your-sim-domain>/api/auth/oauth2/callback/google-calendar
 ```
 
-One OAuth client can register callbacks for all three Google services. Use your exact Sim origin and add only the callbacks for services you enable.
+The personal grant uses the broader `calendar` scope for workflows and is separate from service delegation. It remains required in service mode. One OAuth client can register each enabled Google service's callback. Client or scope changes require updating saved organization provider configuration and reconnecting affected members.
 
-The member-account OAuth connection uses these scopes:
-
-```text
-openid
-https://www.googleapis.com/auth/userinfo.email
-https://www.googleapis.com/auth/userinfo.profile
-https://www.googleapis.com/auth/calendar
-```
+## Related docs
 
-The personal OAuth connection also supports workflow actions, so its declared scopes can be broader than Search’s read-only requests. The service credential uses the separate delegation scopes above.
+- [Google Meet transcripts](/search/google-meet)
+- [Shared Google service account](/search/google-drive#one-service-account-for-drive-gmail-and-calendar)
diff --git a/apps/docs/content/docs/search/google-drive.mdx b/apps/docs/content/docs/search/google-drive.mdx
index e0180ff9558..7ee7c62deed 100644
--- a/apps/docs/content/docs/search/google-drive.mdx
+++ b/apps/docs/content/docs/search/google-drive.mdx
@@ -1,59 +1,67 @@
 ---
 title: Google Drive
-description: Search Drive files through member accounts with optional service-source restrictions
+description: Find Drive files and read supported content with your current access
 ---
 
-Google Drive supports **Member accounts** and **Service account**. Each reader connects their own Drive account in Integrations. Google Docs, Sheets, and Slides are discovered through Drive rather than separate Search sources.
+Google Drive Search finds files your account can access, including Google Docs, Sheets, and Slides. **Member accounts** uses your grant; **Service account** adds user, folder, and file-type restrictions. Both modes require your personal Drive connection.
 
-## Member accounts
+## Connect and search
 
-An admin adds **Google Drive** under **Settings → Sources**, chooses **Member accounts**, and saves. Members select **Integrations → Google Drive → Connect** and authorize their own accounts.
+1. An admin adds **Google Drive** in **Settings → Sources** and chooses **Member accounts**, or configures the service source below.
+2. Each teammate selects **Integrations → Google Drive → Connect** and authorizes their account.
+3. Search a known file, read the result, and follow its source link.
 
-Search calls Drive with that member's grant. No organization folder, file-type, or user selection applies in member mode. Provider permissions and native Drive search determine what can match.
+Member mode has no organization folder, file-type, or user selection. Native Drive queries can narrow a search. For example, `name contains 'Roadmap' and 'person@example.com' in owners` finds candidate files by name and owner.
 
-## Set up a central service account
+## Readable content and limits
 
-1. Enable **Google Drive API** and **Admin SDK API** in Google Cloud. Create a service account and download its JSON key.
-2. Authorize domain-wide delegation in Google Workspace Admin for the key's numeric client ID. The shared Drive service-credential configuration declares these scopes:
+| File type | Read behavior |
+| --- | --- |
+| Google Docs and Slides | Text export |
+| Google Sheets | Formatted values from up to 20 sheets, 1,000 rows, and 52 columns per sheet |
+| Supported text and JSON | Direct content read |
+| Text-bearing PDF and DOCX | Download and complete text extraction within the limits below |
+| Other binary formats | Metadata and a source link |
 
-```text
-https://www.googleapis.com/auth/drive.readonly
-https://www.googleapis.com/auth/admin.directory.user.readonly
-https://www.googleapis.com/auth/admin.directory.group.readonly
-https://www.googleapis.com/auth/admin.directory.domain.readonly
-```
+PDF/DOCX reads require the member's download permission. Downloads are capped at 4 MiB and extracted text at 1 MiB. PDFs are limited to 100 pages. DOCX archives are limited to 10 MiB total expanded data and 4 MiB per entry. Password-protected, malformed, mismatched, or oversized files fail explicitly. Image-only scans need OCR; live Search does not perform it.
 
-The live verifier checks active users through Directory and reads file metadata through delegated Drive tokens. It does not run the legacy group/domain ACL indexing process. Retain the configured credential scopes when using the shared connector or the legacy backend.
+A file read also retrieves comments and replies through the reader's connection. It preserves authors, creation/update times, quoted file context, resolved state, resolve/reopen actions, and comment IDs. Deleted comments and replies are omitted.
 
-3. In **Settings → Sources → Google Drive**, choose **Service account**, then **Add connection**. Add or select the Google service credential.
-4. Set **Delegated administrator** to an active Workspace administrator with the required Directory access. Optionally choose **Users**, folders, and a file type. Save and select the connection as Drive's service source.
-5. Every reader connects their own Google Drive account under **Integrations**.
+Discussion reads cover up to three pages of 20 comments and their reply lists, capped at 120,000 characters and the provider response-size limit. Failures or reached limits add an incomplete-coverage notice without discarding readable file content. Follow returned document offsets for more windows; open Drive for remaining history.
 
-The folder picker uses the source credential; the paired folder-ID field remains available. Selected folders and accessible descendants define the boundary. Leaving folders empty removes that folder restriction, but never removes provider access checks.
+Comments enrich a file read rather than forming a global search index. First find the file by name, owner, folder, or content. A phrase appearing only in comments cannot reliably discover every matching file.
 
-## How filtering works
+## Set up a central service account
 
-Sim searches with the member's OAuth token. In service mode, it narrows retrieval to the source's folder scope where possible, then verifies each candidate's current source-side visibility, folder ancestry, shared-drive identity, and file type as applicable. The member must also be able to read the file.
+1. Enable **Google Drive API** and **Admin SDK API** in Google Cloud. Enable **Google Sheets API** in the member OAuth project for Sheet reads. Create a service account and download its JSON key.
+2. Authorize domain-wide delegation in Workspace Admin for the key's numeric client ID. The shared service-credential configuration declares:
 
-For an explicit source Users list, verification tries up to six selected users through domain-wide delegation. With no list, it verifies the connected member's active identity in the same Workspace customer and delegates to that user. If an external connected reader cannot be delegated in that customer, source verification can use the verified source administrator and report incomplete coverage. It does not enumerate every employee's private Drive.
+   ```text
+   https://www.googleapis.com/auth/drive.readonly
+   https://www.googleapis.com/auth/admin.directory.user.readonly
+   https://www.googleapis.com/auth/admin.directory.group.readonly
+   https://www.googleapis.com/auth/admin.directory.domain.readonly
+   ```
 
-A member's personal file outside the source boundary is excluded even when their token can read it. Folder traversal, provider pagination, and verification budgets are bounded. Reads resolve current grants and repeat the source checks.
+3. In **Settings → Sources → Google Drive**, choose **Service account → Add connection** and add or select the credential.
+4. Set **Delegated administrator** to an active Workspace administrator with Directory access. Optionally choose **Users**, folders, and a file type. Save and select this service source.
+5. Each reader still connects Drive personally in **Integrations**.
 
-## Content and limits
+The live verifier checks active Directory users and delegated Drive metadata. It does not run group/domain permission indexing; keep the scopes declared by the shared credential configuration when using that credential.
 
-Drive search discovers matching files. Reads export Google Docs and Slides as text, read supported text/JSON files directly, and read formatted Sheet values from up to 20 sheets, 1,000 rows, and 52 columns per sheet. Other file types return metadata and a source link. Live Search does not run background attachment parsing or OCR.
+The folder picker uses the source credential; the paired folder-ID field is also available. Selected folders and accessible descendants define the boundary. Empty folders remove that restriction, not provider access checks.
 
-Reading a file also retrieves its comments and replies using the reader's existing Drive connection. Discussion text includes author names, creation and update times, quoted file context, resolved state, and resolve/reopen actions. Deleted comments and replies are omitted. The source file link and comment identifiers let you locate the discussion in Drive.
+## Service-source access
 
-Comments enrich the file read; they are not a separate global search index. Locate the file by its name, owner, folder, or content, then read it for discussion context. For example, `name contains 'Roadmap' and 'person@example.com' in owners` finds candidate files. Do not assume a phrase that appears only in a comment will discover every matching file.
+Sim searches with your OAuth grant and verifies each candidate against current source visibility, folder ancestry, shared-drive identity, and file type. Your account must also read the file. Reads repeat the source checks.
 
-Discussion reads follow up to three pages of 20 comments, including each comment's full reply list, with a 120,000-character discussion limit and the provider response-size limit. A document begins with an incomplete-coverage notice if comments cannot be retrieved or a limit is reached. Available file content is preserved; open the source for the remaining discussion. Continue through the returned document offsets when the available content spans more than one read window.
+With an explicit **Users** list, source verification tries up to six selected users through delegation. Without a list, it checks the connected member's active identity in the same Workspace customer and delegates to that user. For an external reader who cannot be delegated, it can use the verified source administrator and report incomplete coverage. It does not enumerate every employee's private Drive.
 
-Google's own search freshness, export limits, and access settings determine availability. Link sharing alone does not make a file an unrestricted Search result; the current member and configured service boundary must authorize it.
+Personal files outside the configured boundary are excluded. Folder traversal, paging, and verification budgets are bounded. Google search freshness, export limits, and sharing settings still apply; link sharing alone does not authorize a result.
 
 ## One service account for Drive, Gmail, and Calendar
 
-One JSON key can be used for all three service sources. Enable Drive, Gmail, Calendar, and Admin SDK APIs, then authorize the union of the configured scopes:
+One JSON key can serve all three sources. Enable Drive, Gmail, Calendar, and Admin SDK APIs; enable Sheets API in the member OAuth project for Sheet reads. Authorize the union of the shared credential's configured delegation scopes:
 
 ```text
 https://www.googleapis.com/auth/drive.readonly
@@ -65,49 +73,41 @@ https://www.googleapis.com/auth/admin.directory.group.readonly
 https://www.googleapis.com/auth/admin.directory.domain.readonly
 ```
 
-Use comma-separated values in the Workspace delegation form. Each source still needs its own configuration, and each member still connects each Google service separately. Delegation does not replace those personal grants.
-
-## Troubleshooting
-
-| Problem | Next step |
-| --- | --- |
-| Delegation is rejected | Verify the numeric client ID, JSON key, approved scopes, and any pending Workspace approval. |
-| Directory identity is unavailable | Check the administrator's access and that selected primary users are active in the same Workspace customer. |
-| Member can open a file but Search excludes it | Check source folders, selected users, file type, and whether the delegated source identity can read the file. |
-| Coverage is incomplete | Narrow the folder or query scope; bounded user and folder verification does not imply that missing files are absent. |
-| File cannot be read as text | Open the original file. Live Search does not run the knowledge-base attachment parser or OCR retry flow. |
+Use comma-separated values in Workspace Admin. Each source needs its own configuration, and each member connects each Google service separately. Delegation does not replace personal grants.
 
-## Self-hosted OAuth configuration
+## Meet transcripts and notes
 
-Configure the deployment’s Google OAuth client for every member’s personal connection, including members using a service-account source. This is separate from domain-wide delegation.
-
-1. In [Google Cloud Console](https://console.cloud.google.com/), select your project and enable **Google Drive API** under **APIs & Services → Library**.
-2. Open **Google Auth platform → Branding** and configure the app name and contact details. Under **Audience**, choose **Internal** for your Google Workspace organization only, or **External** for other users, adding test users while testing. Review **Data Access → Add or remove scopes** using the current Sim scopes below. See Google's [consent guidance](https://developers.google.com/workspace/guides/configure-oauth-consent).
-3. Open **Google Auth platform → Clients → Create client**, choose **Web application**, and add this URI under **Authorized redirect URIs**. Add it to the existing Google client if your instance already uses one.
+Meet stores generated transcripts and smart notes as Google Docs in the organizer's Drive. Search them when shared with you, including documents retained beyond Meet's conference API window. For example:
 
 ```text
-https://<your-sim-domain>/api/auth/oauth2/callback/google-drive
+fullText contains 'rollback' and mimeType = 'application/vnd.google-apps.document'
 ```
 
+Drive dates mean file modification time. Use [Google Meet](/search/google-meet) for recent transcripts with meeting dates and [Google Calendar](/search/google-calendar) for scheduled events. Transcription or note-taking must have been enabled during the meeting; Search cannot reconstruct missing artifacts.
 
-One OAuth client can register callbacks for all three Google services. Use your exact Sim origin and add only the callbacks for services you enable.
+## Troubleshooting
+
+| Problem | Check |
+| --- | --- |
+| Delegation rejected | Check numeric client ID, key, approved scopes, and pending Workspace approval. |
+| Directory identity unavailable | Check administrator access and active primary users in the same customer. |
+| Readable file excluded | Check folders, Users, file type, and delegated source access. |
+| Incomplete coverage | Narrow folders or query; missing files are not proof of absence. |
+| PDF/DOCX text unavailable | Check download permission, size, password protection, format, and extractable text. For scans, provide a searchable copy or open the original. |
+| Sheet read fails | Check Sheets API enablement in the project used by the member OAuth grant. |
 
-Save the client ID and secret as `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`. Set `NEXT_PUBLIC_APP_URL` to the same Sim origin used in the callback, then restart Sim. See [Integrations & OAuth](/platform/self-hosting/integrations-oauth). If you change an existing deployment's OAuth client or scopes, an organization admin updates the provider configuration and affected teammates reconnect.
+## Self-hosted member OAuth
 
-The current Sim Drive OAuth connection uses these scopes:
+Follow [Google OAuth setup](/platform/self-hosting/integrations-oauth#google) for the shared client, consent, full Drive member scopes, `GOOGLE_CLIENT_ID`, and `GOOGLE_CLIENT_SECRET`. Enable **Google Drive API** and **Google Sheets API** for these reads. Match `NEXT_PUBLIC_APP_URL` to the callback origin and register:
 
 ```text
-openid
-https://www.googleapis.com/auth/userinfo.email
-https://www.googleapis.com/auth/userinfo.profile
-https://www.googleapis.com/auth/drive
-https://www.googleapis.com/auth/drive.file
+https://<your-sim-domain>/api/auth/oauth2/callback/google-drive
 ```
 
-The personal OAuth connection also supports workflow actions, so its declared scopes can be broader than Search’s read-only requests. The service credential uses the separate delegation scopes above.
-
-## Google Meet transcripts and notes
+The personal grant includes `drive` and `drive.file` for workflow actions and is separate from service delegation. It remains required in service mode. One client can register each enabled Google callback. After changing client/scopes, update saved organization provider configuration and reconnect affected members.
 
-Meet saves generated transcripts and smart notes as Google Docs in the organizer's Drive. Connect Drive to search and read these documents when you have access, including older artifacts that remain after Meet's conference API retention window. For example, use `fullText contains 'rollback' and mimeType = 'application/vnd.google-apps.document'`.
+## Related docs
 
-Drive date filters use the file's modification time, not the meeting's start. Use [Google Meet](/search/google-meet) for recent conference transcripts with meeting dates and [Google Calendar](/search/google-calendar) for scheduled events. Transcription or note-taking must have been enabled during the meeting; Search cannot reconstruct a missing artifact.
+- [Gmail](/search/gmail)
+- [Google Calendar](/search/google-calendar)
+- [Google Sheets API setup](https://developers.google.com/workspace/sheets/api/quickstart/nodejs#enable_the_api)
diff --git a/apps/docs/content/docs/search/google-meet.mdx b/apps/docs/content/docs/search/google-meet.mdx
index 4f977b23db7..190c8bb9355 100644
--- a/apps/docs/content/docs/search/google-meet.mdx
+++ b/apps/docs/content/docs/search/google-meet.mdx
@@ -1,44 +1,65 @@
 ---
 title: Google Meet
-description: Search recent conference transcripts and find generated meeting notes
+description: Find recent transcripts and generated-note links from Meet conferences
 ---
 
+Google Meet Search finds recent finalized transcripts and generated-note links. It uses **Member accounts** and your Meet permissions. Use Drive for saved note bodies and older documents; use Calendar for scheduled meetings.
+
 ## Connect
 
-An administrator enables **Google Meet → Member accounts** under **Settings → Sources**. In **Integrations**, click **Connect** beside Google Meet, sign in to your Google account, and approve the requested access. Return to Sim and confirm your account appears on the row. Sim uses the existing Google OAuth client and your Meet permissions. No service account is required.
+1. An admin adds **Google Meet → Member accounts** in **Settings → Sources**.
+2. In **Integrations**, select **Connect** beside Google Meet and authorize your Google account. Your Workspace administrator may need to approve the app.
+3. Return to Sim, confirm the account appears, then search a phrase from a recent meeting and read the result.
 
-For self-hosted deployments, enable the **Google Meet REST API** in the Google Cloud project used by Sim, configure `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`, and register:
+No service account is required. Search only reads conference records and artifacts, using the connection's `meetings.space.readonly` scope. Its `meetings.space.created` scope supports workflow actions.
 
-```text
-https://<your-sim-domain>/api/auth/oauth2/callback/google-meet
-```
+## Search recent meetings
 
-The existing Google Meet connection includes `meetings.space.readonly`, which authorizes these reads, and `meetings.space.created` for workflow actions. Search only reads conference records and artifacts. Google Workspace administrators may need to approve the app.
+Use plain words or a phrase with optional meeting start dates. Native queries support:
 
-These existing Meet scopes are [sensitive](https://developers.google.com/workspace/meet/api/guides/authenticate-authorize). A self-hosted OAuth app serving external users may need Google verification.
+| Field | Behavior |
+| --- | --- |
+| `kind: transcript` | Searches finalized speech and participant names. |
+| `kind: smart_notes` | Finds generated-note metadata and a Google Docs link, without searching or returning the note body. |
+| No kind | Searches both artifact types. |
+| `project` | Known `spaces/ID` or meeting code. |
 
-## Recent transcripts and notes
+Meet has no title or full-text search endpoint. Sim matches terms locally within at most three recent conferences and five finalized artifacts per call, reporting bounded coverage. Narrow dates or supply a known space; missing results do not establish absence.
 
-Use plain words or a phrase, optionally with meeting start dates. `kind: transcript` searches finalized transcript text and participant names. `kind: smart_notes` finds generated-note metadata and a Google Docs link; it does not search or return the note body. Omit the kind to search both. `project` can narrow to a known `spaces/ID` or meeting code.
+Dates use actual conference start, with an exclusive upper bound. Boolean operators, ownership filters, and modification-date filters are unsupported.
 
-Meet has no title or full-text search endpoint. Sim matches terms locally within at most 3 recent conferences and 5 finalized artifacts per call. Results explicitly report bounded coverage. Use a narrow date range or known meeting space; missing results do not establish that a meeting or phrase is absent. Boolean operators, ownership filters and modification-date filters are unsupported. Dates use the actual conference start; the upper bound is exclusive.
+## Read transcripts and saved documents
 
-Reads retrieve complete finalized transcripts within the request, entry and byte limits. Speech stays attributed to the participant and timestamp. Sim rejects incomplete reads instead of presenting truncated text as a complete transcript.
+Reads retrieve complete finalized transcripts within request, entry, and byte limits. Speaker attribution and timestamps are preserved. Incomplete reads are rejected rather than presented as complete transcripts. Sim does not process recording audio or generate missing artifacts.
 
-[Meet conference records](https://developers.google.com/workspace/meet/api/reference/rest/v2/conferenceRecords) and [transcript entries](https://developers.google.com/workspace/meet/api/guides/artifacts) expire 30 days after the conference ends. Transcription or note-taking must have been enabled during the meeting. Sim does not generate a missing transcript or process recording audio.
+Conference records and transcript entries expire 30 days after the conference ends. Transcription or note-taking must have been enabled. [Meet conference records](https://developers.google.com/workspace/meet/api/reference/rest/v2/conferenceRecords), [artifact retention](https://developers.google.com/workspace/meet/api/guides/artifacts).
 
-## Saved documents and scheduled meetings
+Connect **Google Drive** to read saved transcripts and note bodies, including older shared documents remaining in the organizer's Drive. Use a Drive query such as `fullText contains 'rollback' and mimeType = 'application/vnd.google-apps.document'`. Drive dates mean modification time, not meeting dates; document sharing and retention still apply.
 
-Connect **Google Drive** to read saved meeting notes and transcripts, including older documents that remain in the organizer's Drive. Use Drive's native query syntax, such as `fullText contains 'rollback' and mimeType = 'application/vnd.google-apps.document'`, then read the result. Drive dates mean file modification time, not the meeting date. Normal document sharing and retention rules apply.
-
-Use **Google Calendar** to search scheduled meetings and invitations. An event on the calendar does not establish that a Meet transcript or recording exists.
+Connect **Google Calendar** for scheduled meetings and invitations. A calendar event does not prove a transcript or recording exists.
 
 ## Disconnect and troubleshoot
 
-To disconnect, open **Integrations**, use the **…** menu beside Google Meet, choose **Disconnect** for your account, and confirm. Any workflows using that connection also lose access. This does not delete transcripts or notes from Google Drive.
+Disconnect through the **…** menu beside Google Meet in **Integrations** and confirm. Workflows using the connection lose access too. This does not delete Drive transcripts or notes.
+
+| Problem | Check |
+| --- | --- |
+| Connect unavailable or permission denied | Ask an admin to enable the source and complete Google OAuth setup; Workspace app approval may also be needed. |
+| **Reconnect** needed | Authorize the account again. |
+| Transcript missing | Check meeting dates/space, transcription settings, and the 30-day API window. Use Drive for older saved documents and note bodies. |
+
+## Self-hosted operator setup
+
+Follow [Google OAuth setup](/platform/self-hosting/integrations-oauth#google), enable **Google Meet REST API**, and configure `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`. Register:
+
+```text
+https://<your-sim-domain>/api/auth/oauth2/callback/google-meet
+```
+
+The Meet scopes are sensitive. External OAuth apps may require Google verification; see [Meet authorization](https://developers.google.com/workspace/meet/api/guides/authenticate-authorize). The canonical setup guide contains the full member scope list and consent steps.
 
-- **Connect is unavailable or permission is denied:** ask your Sim administrator to enable the source and finish Google OAuth setup. Your Google Workspace administrator may need to approve the app.
-- **Reconnect needed:** use **Reconnect** beside Google Meet and authorize the account again.
-- **No matching transcript:** narrow to the meeting's dates or space, confirm transcription was enabled, and check whether the conference is within the API's 30-day window. Use Google Drive for saved or older documents and the bodies of smart notes.
+## Related docs
 
-For help, contact [help@sim.ai](mailto:help@sim.ai).
+- [Google Drive](/search/google-drive)
+- [Google Calendar](/search/google-calendar)
+- [Contact support](mailto:help@sim.ai)
diff --git a/apps/docs/content/docs/search/granola.mdx b/apps/docs/content/docs/search/granola.mdx
index 13fb82db3cc..af22d0515bf 100644
--- a/apps/docs/content/docs/search/granola.mdx
+++ b/apps/docs/content/docs/search/granola.mdx
@@ -1,34 +1,37 @@
 ---
 title: Granola
-description: Find meeting notes and read source transcripts with each member’s Granola account
+description: Find meeting notes and read available transcripts from Granola
 ---
 
-Granola live Search uses **Member accounts** through Granola’s official MCP service. Results are limited to the connected person’s current access and their **active Granola workspace**.
+Granola Search uses **Member accounts** through the official MCP service. It searches content your account can access in your active Granola workspace.
 
 ## Connect
 
-1. An admin enables **Granola** under **Settings → Sources**, using **Member accounts**.
-2. Each teammate opens **Integrations → Granola → Connect** and completes Granola authorization.
-3. Search with a focused natural-language question about a meeting topic.
+1. An admin adds **Granola → Member accounts** in **Settings → Sources**.
+2. Each teammate opens **Integrations → Granola → Connect** and authorizes their account.
+3. Ask a focused question such as `What did we decide about the enterprise launch?`, then read a result.
 
-Sim uses the fixed endpoint `https://mcp.granola.ai/mcp` and each member’s managed OAuth grant. A shared API key cannot substitute for this personal connection.
+Sim uses `https://mcp.granola.ai/mcp` with each member's managed OAuth grant. A shared API key cannot replace this connection. If meetings are missing, check the account and switch to the intended workspace in Granola; MCP follows the active workspace.
 
-## Query guidance
+## Queries and dates
 
-Ask focused questions, such as `What decisions did we make about the enterprise launch?` or `Which customer meetings discussed audit logs?`. Granola uses semantic meeting queries; GitHub qualifiers and Gmail search operators do not apply.
+Granola uses semantic meeting queries. Ask about one topic, such as `Which customer meetings discussed audit logs?`, without Gmail operators or GitHub qualifiers.
 
-Use `startDate` and `endDate` for a meeting-date range. A query without terms uses Granola’s meeting listing. When the server offers only preset ranges, Sim lists the **last 30 days** and applies the exact date filters to those meetings. Older meetings are outside that listing window; use a focused question to look for them, subject to your plan and access. If the server advertises custom date-range parameters, Sim uses them instead. An explicit native `project` can contain a meeting UUID to narrow a question to that meeting when Granola advertises this capability.
+Use `startDate` and `endDate` for meeting dates. Without terms, Sim uses a meeting listing. When the server offers only preset ranges, it lists the last 30 days and filters those meetings to the requested dates. Older meetings need a focused question, subject to plan and access. If custom ranges are advertised, Sim uses them. Native `project` can scope a question to a meeting UUID when the server exposes that capability.
 
-There is no verified continuation cursor. Narrow the topic or meeting dates for additional coverage. Date ranges describe meetings, not note modification times. Sim does not invent modification timestamps when Granola omits them.
+There is no verified continuation cursor. Narrow the topic or dates for more coverage. Meeting dates are not note modification times; Sim does not invent missing timestamps.
 
-## Source quality and coverage
+## Notes and transcript evidence
 
-Granola’s query tool can return a generated answer. Sim uses that answer only to locate explicit meeting references, then fetches those meetings’ source notes before returning passages. Generated answers without verifiable references are reported as limited coverage with no source evidence. Each search hydrates at most 10 meetings and reports that the selection is not exhaustive.
+Granola can return a generated answer. Sim uses it to locate explicit meeting references, then fetches the source notes. Answers without verifiable references return limited coverage with no source evidence. Each search retrieves source notes for at most ten meetings and is not exhaustive.
 
-Notes can contain AI-generated summaries and private notes. Read a result to request the underlying transcript before quoting spoken words. If transcripts are unavailable, the result says so; it does not present notes as verbatim speech. Large notes and transcripts are visibly marked when truncated.
+Notes can contain AI summaries and private notes. Read the underlying transcript before quoting speech. If a transcript is unavailable, the result says so. Large notes and transcripts are bounded and marked when truncated.
 
-Granola’s plan and workspace controls apply. The Basic plan limits note access to the last 30 days; transcript access requires a paid plan and may be disabled by an Enterprise administrator. MCP follows the active Granola workspace, so switch workspaces in Granola if expected meetings are missing.
+Basic plan note access is limited to the last 30 days. Transcripts require a paid plan and can be disabled by an Enterprise administrator. Workspace controls and provider quotas still apply. [Granola's current access rules](https://docs.granola.ai/help-center/sharing/integrations/mcp).
 
-Sim discovers and validates the current MCP tool schemas, permits only fixed read operations, and rechecks the member’s grant before each call. Unexpected response formats fail visibly. Exact tool capabilities can change; an authenticated connection is required to inspect the current server’s schemas.
+Sim permits fixed read operations, validates advertised schemas, and rechecks the current grant before calls. Unexpected formats fail explicitly; exact capabilities depend on the authenticated server's current tools.
 
-See the [Granola MCP guide](https://docs.granola.ai/help-center/sharing/integrations/mcp) for current access and plan details.
+## Related docs
+
+- [Connect your account](/search/connect-your-account)
+- [Granola MCP guide](https://docs.granola.ai/help-center/sharing/integrations/mcp)
diff --git a/apps/docs/content/docs/search/hubspot.mdx b/apps/docs/content/docs/search/hubspot.mdx
index de8b464db5d..26377ca6aec 100644
--- a/apps/docs/content/docs/search/hubspot.mdx
+++ b/apps/docs/content/docs/search/hubspot.mdx
@@ -1,22 +1,37 @@
 ---
 title: HubSpot
-description: Search contacts, companies, deals, and tickets with your HubSpot permissions
+description: Find CRM records with your current HubSpot permissions
 ---
 
-HubSpot live Search uses **Member accounts** through HubSpot's official MCP service. An administrator enables HubSpot under **Settings → Sources**, then each person selects **Connect** under **Integrations** and signs in to HubSpot. Allow read access to contacts, companies, deals, and tickets. Write access is not needed.
+HubSpot Search finds contacts, companies, deals, and tickets through the official MCP service. It uses **Member accounts** and your current HubSpot permissions.
 
-## What you can search
+## Connect
 
-Search names, domains, email addresses, deal names, and ticket subjects using concise keywords. Select a CRM kind to focus on contacts, companies, deals, or tickets; an unrestricted search checks all four. HubSpot searches each object's default searchable properties. It is lexical search, so a long natural-language question may need shorter keywords.
+An admin adds **HubSpot** in **Settings → Sources**. Each person then selects **Integrations → HubSpot → Connect** and signs in. Grant read access to contacts, companies, deals, and tickets; write access is not needed. Search a known name, email, or domain, then read the record.
 
-Read a result to see its returned CRM properties, including available custom properties. Links open the verified record in HubSpot. Reads do not include activity histories, notes, or associated records.
+## Search and read records
 
-Dates and date sorting use the record's last modification time. To list records without keywords, select newest/oldest sorting or a date range. Continue an individual CRM kind with the returned cursor and the same query and filters. Searches are bounded and do not establish aggregate totals or revenue. Ownership, pipeline, lifecycle-stage filters, and custom object types are not supported; “my deals” is not treated as “all visible deals.”
+Use concise keywords such as names, domains, email addresses, deal names, or ticket subjects. Native kinds are `contacts`, `companies`, `deals`, and `tickets`; a query without a kind searches all four. The provider searches default searchable properties lexically, so shorten long natural-language questions.
 
-## Access and setup
+Reads return available CRM properties, including custom properties, with a verified HubSpot record link. They do not include activity histories, notes, or associated records.
 
-Every request uses the connected person's current HubSpot permissions. Search uses a fixed read-only tool allowlist and cannot create or change CRM records. Account permissions, subscription restrictions, and HubSpot request limits still apply.
+Dates and sorting use last modification time. For a queryless listing, use newest/oldest sorting or a date range. Continue one CRM kind with its cursor and the same query and filters. Bounded results cannot establish aggregate totals or revenue.
 
-The deployment configures one HubSpot MCP OAuth app; teammates only sign in. This is separate from the ordinary HubSpot OAuth app used by workflow integrations. For a self-hosted deployment, register an MCP app in HubSpot, set `HUBSPOT_MCP_CLIENT_ID` and `HUBSPOT_MCP_CLIENT_SECRET`, and register the exact callback `<your Sim app URL>/api/mcp/oauth/callback`. Sim uses `https://mcp.hubspot.com` and handles HubSpot's regional redirect. Replacing the shared registration requires people to reconnect.
+Ownership, pipeline, lifecycle-stage filters, and custom object types are unsupported. “My deals” is not interpreted as all visible deals. Subscription restrictions, user permissions, and request limits still apply. Search only uses read tools and cannot create or change records.
 
-If HubSpot is unavailable in the source picker, ask the deployment administrator to configure the MCP app. If read access is missing, reconnect with the needed read permissions. See [HubSpot's remote MCP server documentation](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server).
+## Self-hosted setup and recovery
+
+Configure a dedicated HubSpot MCP OAuth app, separate from the ordinary workflow OAuth app. Register an MCP app in HubSpot, set `HUBSPOT_MCP_CLIENT_ID` and `HUBSPOT_MCP_CLIENT_SECRET`, and register the exact callback:
+
+```text
+https://<your-sim-domain>/api/mcp/oauth/callback
+```
+
+Sim uses `https://mcp.hubspot.com` and handles its regional redirect. Replacing the shared registration requires members to reconnect.
+
+If HubSpot is unavailable in the source picker, ask the deployment admin to configure the MCP app. If read permissions are missing, reconnect with the required grants.
+
+## Related docs
+
+- [HubSpot remote MCP setup](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server)
+- [Connect your account](/search/connect-your-account)
diff --git a/apps/docs/content/docs/search/index.mdx b/apps/docs/content/docs/search/index.mdx
index 59c23f27f13..9fe4d694a37 100644
--- a/apps/docs/content/docs/search/index.mdx
+++ b/apps/docs/content/docs/search/index.mdx
@@ -1,85 +1,76 @@
 ---
 title: Search
-description: Search connected sources live with each person's current access
+description: Find content in connected sources with your current account access
 ---
 
-Search queries your connected providers when you ask a question. It does not copy their documents into a Sim vector index or wait for a background sync.
+Search queries your connected sources when you ask. Results reflect your account's current access and your organization's source settings. Search does not copy documents into a Sim vector index or wait for a background sync.
 
-An organization admin adds sources under **Settings → Sources**. Teammates connect their provider accounts under **Integrations** in the main sidebar. Credential Groups remain a separate feature for sharing account connections with workflows.
+Use **Search** to find documents directly, or ask Sim on **Home** for an answer with sources. [Sim Search in Slack](/search/slack) and [Search MCP](/search/mcp) use the same retrieval and access rules. Search mode can search and read sources; it does not expose arbitrary integration actions.
 
 ## Add your first source
 
-1. Open **Settings → Sources → Add source** and choose a provider or Generic Secrets.
-2. For a searchable provider, choose **Member accounts** or, when supported, **Service account**. GitHub calls the second mode **GitHub App**. Slack and Jira use member accounts; GitLab uses a service account. [Generic Secrets](/search/generic-secrets) instead offers **Organization** and **Member**.
-3. For provider member mode, save the source. For service mode, add or select a connection and configure its resources. GitHub uses **Add repository** for each repository; GitLab uses **Add project** for each project.
-4. For provider sources, open **Integrations** and connect your personal account, including when you are the admin. GitLab is the exception: its configured project permissions identify readers without a personal connection. Generic Secrets uses its built-in editor and needs no provider authorization.
-5. For a provider source, open **Search** or ask the assistant on **Home** about a document you can access. For Generic Secrets, use [Build or Plan](/search/generic-secrets).
+1. An organization admin opens **Settings → Sources → Add source** and chooses a provider.
+2. Choose **Member accounts**, or a service mode supported by that provider. Save the source; service modes also require a connection and resource settings.
+3. Each reader opens **Integrations** and connects their own provider account, including admins. GitLab uses configured project permissions instead of personal connections.
+4. Search for a distinctive phrase in content that account can open. Read the result and follow its source link.
 
-Adding a member-account provider source makes that integration available for members to connect. A provider that needs deployment or app configuration must have that configuration completed before account authorization can succeed.
+Adding a member source makes the integration available for members to connect. Provider app or deployment setup must be complete before authorization succeeds. [Connect your account](/search/connect-your-account) explains connection status and recovery.
 
-## Choose the right connection method
+## Choose a connection mode
 
-| Mode | Admin configuration | How a search is restricted |
+| Mode | Admin setup | Search boundary |
 | --- | --- | --- |
-| **Member accounts** | Add the integration. There are no organization resource filters in this mode. | The provider searches what the connected member's account can access. |
-| **Service account** | Select a service connection and its resources, such as folders, labels, spaces, or documents. | The member's provider results must also be readable by the service connection and match its current resource settings. |
-| **GitHub App** | Connect an installation and add repositories individually. | Each repository must be allowed by both the App installation and the member's connected GitHub account. |
-| **GitLab service account** | Add a self-managed project with an administrator token, or a non-admin token and CSV permissions. | The configured token retrieves content; Sim separately verifies the reader against current GitLab permissions or the uploaded grants. |
+| **Member accounts** | Add the integration; no organization resource filters. | Content the connected member can access through the provider. |
+| **Service account** | Select a service connection and its folders, labels, spaces, or documents. | Content readable by the member and the service connection, within the source's current settings. |
+| **GitHub App** | Connect an installation and add each repository with **Add repository**. | Repositories allowed by both the installation and the member's GitHub account. |
+| **GitLab service account** | Add each self-managed project with **Add project**. Use an administrator token, or a non-admin token with CSV permissions. | Content retrieved by the source token and authorized for the reader by current GitLab checks or saved CSV grants. No personal connection. |
 
-A service account limits the searchable resources; it does not grant members access they lack. For example, a Gmail source limited to **INBOX** returns only matching messages from the connected member's own mailbox. A personal message outside that source's settings remains excluded. See the [Gmail example](/search/gmail#how-inbox-filtering-works).
+A service source restricts resources; it does not grant access the member lacks. For example, a Gmail source limited to **INBOX** searches only allowed messages in the connected member's own mailbox. See [how INBOX filtering works](/search/gmail#how-inbox-filtering-works).
 
-In Sources, open an integration to manage its connection and resource settings. Removing a source stops it from authorizing subsequent Search requests. Account connections and source configuration are distinct: connecting an account does not create additional resource selections or start indexing.
+Open a provider in **Sources** to manage its connection and resource settings. Removing a source stops it from authorizing later Search requests. Connecting an account does not add resource selections or start indexing. Credential Groups separately share account connections with workflows.
 
-## Connector guides
+## Supported sources
 
-These providers support live Search. Google Docs, Sheets, and Slides are accessed through Drive. Other [knowledge-base connectors](/knowledgebase/connectors) do not automatically become Search integrations.
+Availability depends on deployment configuration and organization policy. Google Docs, Sheets, and Slides use the Drive source. Knowledge-base connectors do not automatically become Search sources.
 
-| Source | Search path | Modes |
+| Source | Searchable content | Modes |
 | --- | --- | --- |
-| [Coda](/search/coda) | Personal Coda MCP; legacy REST connections search document titles | Member or service |
-| [Confluence](/search/confluence) | Confluence Cloud CQL and content APIs | Member or service |
+| [Coda](/search/coda) | Pages and table rows through personal MCP; legacy REST connections search document titles | Member or service |
+| [Confluence](/search/confluence) | Confluence Cloud pages and blog posts | Member or service |
 | [Fireflies](/search/fireflies) | Meeting titles and spoken transcripts | Member only |
-| [GitHub](/search/github) | Repositories, code, issues and pull request discussions | Member or GitHub App |
-| [GitLab](/search/gitlab) | Configured self-managed project's search and read APIs | Service only; admin or CSV permissions |
-| [Gmail](/search/gmail) | Message search and conversation reads | Member or service |
-| [Google Calendar](/search/google-calendar) | Calendar lists and event APIs | Member or service |
-| [Google Drive](/search/google-drive) | File search, supported document reads and comments | Member or service |
+| [GitHub](/search/github) | Repositories, code, issues, pull request discussions, and commits | Member or GitHub App |
+| [GitLab](/search/gitlab) | Configured self-managed projects | Service only; admin or CSV permissions |
+| [Gmail](/search/gmail) | Messages and authorized conversation context | Member or service |
+| [Google Calendar](/search/google-calendar) | Calendar events | Member or service |
+| [Google Drive](/search/google-drive) | Files, supported document content, and comments on reads | Member or service |
 | [Google Meet](/search/google-meet) | Recent conference transcripts and generated-note links | Member only |
-| [Granola](/search/granola) | Semantic meeting search with source notes and transcript reads | Member only |
-| [HubSpot](/search/hubspot) | Contacts, companies, deals and tickets | Member only |
-| [Jira](/search/jira) | Jira Cloud JQL and issue APIs | Member only |
+| [Granola](/search/granola) | Meeting notes and transcripts | Member only |
+| [HubSpot](/search/hubspot) | Contacts, companies, deals, and tickets | Member only |
+| [Jira](/search/jira) | Jira Cloud issues and available comments | Member only |
 | [Linear](/search/linear) | Issues and their comment discussions | Member only |
 | [Lucid](/search/lucid) | Lucidchart diagrams and Lucidspark boards | Member only |
-| [Notion](/search/notion) | Page and database content through Notion MCP | Member only |
-| [Slack](/search/slack) | Slack real-time search with the member's user token | Member only |
-| [Zoom](/search/zoom) | Past meetings with available transcripts, notes and summaries | Member only |
+| [Notion](/search/notion) | Notion pages and databases through personal MCP | Member only |
+| [Slack](/search/slack) | Accessible messages and files through real-time search | Member only |
+| [Zoom](/search/zoom) | Past meetings and available artifacts; requires organization enablement | Member only |
 
-[Generic Secrets](/search/generic-secrets) is also available as a source, but does not add searchable documents. Organization mode makes its secrets available across the organization; Member mode lets each person manage their own secrets in Integrations. Build and Plan can use these secrets for requests; Search cannot mount them.
+**Generic Secrets** is also offered in Sources. Its **Organization** and **Member** modes store secrets for Build and Plan; they do not add searchable content. See [Generic Secrets](/search/generic-secrets).
 
 ## Access and freshness
 
-Search authorizes your current Sim membership, resolves your current provider connection, and applies the current source policy on each request. Document reads repeat those checks. Source admins follow the same reader rules as other members.
+Search checks current Sim membership, provider connections, and source settings on every request and document read. Admins follow the same reader rules as other members. GitLab administrator sources check permissions during the request; non-admin sources use saved CSV grants, which admins must update when access changes.
 
-There is no background per-document ACL index to build for live Search. Providers enforce normal member access directly. Service sources add live resource checks. GitLab administrator sources reconstruct the required permission evidence during the request; non-admin sources use the administrator's saved CSV grants. Update CSV grants when membership changes.
+Provider search freshness, supported content, pagination, rate limits, and bounded permission checks affect coverage. An empty result does not prove content is absent. Follow returned continuation cursors or narrow the query when coverage is incomplete; there is no Search indexing job to retry.
 
-Results follow the provider's search behavior. A provider can delay visibility of newly edited content, limit search types, or return only a page of matches. Rate limits and bounded permission checks can produce incomplete coverage. An empty result is not proof that a document does not exist, and an unavailable provider is not an indexing failure.
+To verify a service boundary, search for content inside and outside its configured scope. Repeat as a teammate with different access. After revoking provider access or updating GitLab CSV grants, repeat both search and read; provider changes must be reflected by the provider API.
 
-## Search, Assistant, Slack, and MCP
+Conversations remain private to their author. An external account connection does not grant Sim organization membership. Invite teammates through **Settings → Members** or your organization's SSO.
 
-Organization **Search** finds documents directly. The assistant on **Home**, [Sim Search in Slack](/search/slack), and [Search MCP](/search/mcp) use the same live retrieval and access rules. The Search assistant can search and read; it does not expose arbitrary integration tools.
+## Search and knowledge bases
 
-Conversations remain private to their author. Connecting an external account does not grant Sim organization membership: invite teammates through **Settings → Members** or your organization's SSO.
+Workspace knowledge bases ingest, chunk, and index documents. Their connectors, processing status, and access settings are separate from live Search sources.
 
-## Check that it works
+## Related docs
 
-1. Connect an account and search for a distinctive phrase in a supported document that account can open.
-2. Read the result and follow its source link.
-3. Repeat as a teammate with different access; private content must remain private.
-4. For a service source, search for content both inside and outside its configured boundary.
-5. Revoke access at the provider, or update GitLab CSV permissions, and repeat the search and read. There is no Sim content sync to wait for.
-
-## Legacy indexing and workspace knowledge bases
-
-Enterprise Search uses live provider queries. Search sources do not run content indexing or stored permission maintenance; ordinary knowledge-base connectors retain their indexing behavior.
-
-Ordinary workspace [knowledge bases](/knowledgebase) still ingest, chunk, and index documents for their own features. Their connector setup, processing status, and access settings remain separate.
+- [Connect your account](/search/connect-your-account)
+- [Search MCP](/search/mcp)
+- [Knowledge-base connectors](/knowledgebase/connectors)
diff --git a/apps/docs/content/docs/search/jira.mdx b/apps/docs/content/docs/search/jira.mdx
index adbe9096e83..e1abbd43125 100644
--- a/apps/docs/content/docs/search/jira.mdx
+++ b/apps/docs/content/docs/search/jira.mdx
@@ -1,47 +1,48 @@
 ---
 title: Jira
-description: Search Jira Cloud issues through each member's account
+description: Search Jira Cloud issues using your own account
 ---
 
-Jira uses **Member accounts**. Each person connects their own Jira Cloud account, and Search calls Jira with that person's OAuth grant. There is no Jira service-account mode or admin project filter in live Search.
+Jira Search finds Cloud issues with your personal OAuth grant. It uses **Member accounts**, with no service mode or admin project filter. Jira Server and Data Center are not supported by this adapter.
 
-## Set up Jira
+## Connect
 
-1. An organization admin opens **Settings → Sources → Add source → Jira** and adds it.
-2. Each teammate opens **Integrations → Jira → Connect** and authorizes their own Atlassian account.
-3. Search for a known issue or ask the assistant a question about it. There is no project-setup or indexing step after authorization.
+1. An admin adds **Jira** in **Settings → Sources → Add source**.
+2. Each teammate selects **Integrations → Jira → Connect** and authorizes their Atlassian account.
+3. Search a known issue, or ask Sim about it. Read the result and follow its Jira link.
 
-Hosted Sim supplies the OAuth app. Self-hosted deployments must configure the app below. Use Jira Cloud; Jira Server and Data Center are not supported by this live adapter.
+No project setup or indexing is needed after authorization. Sim Cloud supplies the OAuth app where available; self-hosted deployments configure their app below.
 
-## What Search does
+## Queries and issue reads
 
-Sim resolves the connected account's accessible Atlassian sites, sends JQL to Jira's search API, and returns issue summaries and descriptions. Reading a result fetches the issue and the comments returned by Jira with the same account. Jira enforces project permissions, issue security, and app-access restrictions on these requests.
+Sim resolves your accessible Atlassian sites and sends Jira Query Language (JQL) to the search API. Ask Sim to narrow a query by project, status, dates, or another supported field. These are per-query filters, not source settings.
 
-The assistant can use JQL to narrow a question to a project, status, date, or other supported field. This is a per-query filter, not an organization source configuration. Search checks up to four accessible sites by default. A native query can select a specific cloud site ID and follow its continuation cursor.
+Search returns summaries and descriptions. Reads fetch the issue and available comments with the same account. Jira enforces project permissions, issue security, and app-access restrictions. Bounded responses may omit comments; open Jira for the full discussion.
 
-Changes become visible when Jira's own search reflects them. Sim does not crawl issue attachments or retain an indexed copy of issue content. Bounded API responses may omit additional comments; open the source for the full issue.
+Search checks up to four accessible sites by default. A native query can select a cloud site ID and follow its continuation cursor. Changes follow Jira's search freshness. Live Search does not crawl attachments or retain an indexed issue copy, and does not edit issues. The shared account connection can request broader workflow permissions.
 
 ## Troubleshooting
 
-| Problem | What to check |
+| Problem | Check |
 | --- | --- |
-| Jira is missing | Ask an organization admin to add Jira in Sources. |
-| Connected, but no issue | Open it with the connected Jira account; check issue security, project permissions, site selection, and the JQL query. |
-| Project is visible but its issues are unavailable | Check Atlassian app-access or data-security restrictions. Seeing a project does not guarantee the app can read its issues. |
-| Reconnect | Authorize the appropriate account and grant the requested scopes. |
-| OAuth popup does not open | Allow popups for Sim and retry Connect. |
-| Invalid callback | Check the deployment OAuth app and exact scheme, host, port, and callback path. |
-
-Search does not edit issues. Sim's shared account connection may request additional permissions for workflow actions.
+| Jira missing | Ask an admin to add it in **Sources**. |
+| Issue missing | Check the connected account's access, issue security, project permissions, site, and JQL. |
+| Project visible, issues unavailable | Check app-access/data-security restrictions; project visibility does not grant issue access. |
+| **Reconnect** needed | Authorize the intended account with requested scopes. |
+| Popup blocked | Allow popups and retry **Connect**. |
+| Invalid callback | Check the deployment app and exact callback scheme, host, port, and path. |
 
 ## Self-hosted operator setup
 
-Configure one shared Jira OAuth app for the deployment:
+Follow [Atlassian OAuth setup](/platform/self-hosting/integrations-oauth#atlassian) for the full Jira scope set, including Service Management, Assets, **User Identity API → read:me**, `offline_access`, and **Distribution**. Set `JIRA_CLIENT_ID` and `JIRA_CLIENT_SECRET`, verify `NEXT_PUBLIC_APP_URL`, and register:
+
+```text
+https://<your-sim-domain>/api/auth/oauth2/callback/jira
+```
+
+Search reads only, but the shared app also supports workflows. If only the app owner can connect, check **Distribution**. After client/scope changes, update the organization's saved provider configuration and reconnect affected members.
 
-1. In the [Atlassian developer console](https://developer.atlassian.com/console/myapps/), select or create an **OAuth 2.0 integration**.
-2. Under **Authorization → OAuth 2.0 (3LO)**, add `https://<your-sim-domain>/api/auth/oauth2/callback/jira` as a callback.
-3. Under **Permissions**, add **Jira API** and configure the full `jira` scope list from [Sim's OAuth configuration](https://github.com/simstudioai/sim/blob/staging/apps/sim/lib/oauth/oauth.ts), including its Jira Service Management and Assets scopes. Add **User Identity API → read:me**. Sim requests `offline_access` for refresh tokens; Search uses only read operations, but this shared app also supports workflow actions.
-4. Enable sharing under **Distribution**. Set `JIRA_CLIENT_ID` and `JIRA_CLIENT_SECRET` from the app's **Settings**, verify `NEXT_PUBLIC_APP_URL`, and restart Sim.
-5. Connect from **Integrations** and select the configured site. After changing the OAuth client or requested scopes, update the organization’s provider configuration and have affected teammates reconnect.
+## Related docs
 
-The callback must match Sim's scheme, hostname, port, and path exactly. If only the app owner can connect, check **Distribution**. See the [Atlassian OAuth guide](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) and [Sim deployment reference](/platform/self-hosting/integrations-oauth).
+- [Atlassian OAuth guide](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)
+- [Connect your account](/search/connect-your-account)
diff --git a/apps/docs/content/docs/search/linear.mdx b/apps/docs/content/docs/search/linear.mdx
index 3d36ecd506a..c07e7c809d3 100644
--- a/apps/docs/content/docs/search/linear.mdx
+++ b/apps/docs/content/docs/search/linear.mdx
@@ -1,20 +1,28 @@
 ---
 title: Linear
-description: Search issues and their discussions using your own Linear account
+description: Find issues and comment discussions with your Linear account
 ---
 
-Linear supports **Member accounts**. An administrator enables Linear under **Settings → Sources**, then each teammate connects their own Linear account under **Integrations**. The connection needs Linear's `read` permission. Search and reads use that member's current access; there is no background content index.
+Linear Search finds issues and their comments using your own account. It uses **Member accounts** and needs Linear's `read` permission.
 
-## Search effectively
+## Connect and search
 
-Use a short issue description, distinctive phrase, or issue key such as `ENG-42`. Linear's native search combines full-text and vector retrieval. Sim includes **issue comments and archived issues** in searches, so a discussion can match even when the issue title does not contain your terms. GitHub qualifiers such as `repo:` and `is:pr` are not Linear query syntax.
+An admin adds **Linear** in **Settings → Sources**, then each member connects Linear in **Integrations**. Search an issue key such as `ENG-42`, a distinctive phrase, or a short issue description. Read the result and follow its Linear link.
 
-The assistant can narrow a native query to a **project UUID**. Use the project's ID, rather than its name or a team ID. Date bounds apply to the issue's modification time. Relevance is the default; newest and oldest sorting use modification time. Date-only requests list issues in the requested range. Continue a returned cursor with the same query and account.
+Linear combines full-text and vector retrieval. Sim includes comments and archived issues, so a discussion can match without the terms appearing in the title. GitHub qualifiers such as `repo:` and `is:pr` do not apply.
 
-## Read results
+## Projects, dates, and pagination
 
-Opening a result retrieves the issue description, state, assignee, project, and up to **150 comments**, bounded to 120,000 discussion characters. Comments preserve author names, timestamps, direct source links, and reply relationships. If more comments exist or pagination cannot continue, the response explicitly says the discussion is incomplete.
+Ask Sim to narrow a native query to a project UUID, rather than a project name or team ID. Date filters use issue modification time. Relevance is the default; newest/oldest sorting also uses modification time. Date-only queries list issues in the requested range. Continue a returned cursor with the same query and account.
 
-Search currently covers issues and their comments. It does not search standalone project documents or project updates. An empty result is not proof that no relevant work exists: try a shorter phrase, another issue key, or a different project scope.
+## Issue discussions and limits
 
-Linear currently limits its issue-search operation to 30 requests per minute. Sim reports quota or access failures rather than presenting them as empty results. See the [official GraphQL schema](https://github.com/linear/linear/blob/master/packages/sdk/src/schema.graphql), [filtering](https://linear.app/developers/filtering), and [pagination](https://linear.app/developers/pagination).
+Reads include description, state, assignee, project, and up to 150 comments, capped at 120,000 discussion characters. Authors, timestamps, direct links, and reply relationships are preserved. More comments or failed pagination produce an incomplete-discussion notice.
+
+Standalone project documents and updates are not searchable through this adapter. For weak results, shorten the phrase, try an issue key, or change project scope. Linear's `searchIssues` operation currently has a 30-request-per-minute quota, alongside other API limits. Quota and access failures are reported explicitly.
+
+## Related docs
+
+- [Linear GraphQL schema](https://github.com/linear/linear/blob/master/packages/sdk/src/schema.graphql)
+- [Filtering](https://linear.app/developers/filtering)
+- [Pagination](https://linear.app/developers/pagination)
diff --git a/apps/docs/content/docs/search/lucid.mdx b/apps/docs/content/docs/search/lucid.mdx
index 71efecc0972..67568c06eb2 100644
--- a/apps/docs/content/docs/search/lucid.mdx
+++ b/apps/docs/content/docs/search/lucid.mdx
@@ -1,30 +1,37 @@
 ---
 title: Lucid
-description: Search Lucidchart diagrams and Lucidspark boards with your own Lucid account
+description: Find Lucidchart diagrams and Lucidspark boards with your account
 ---
 
+Lucid Search finds Lucidchart diagrams and Lucidspark boards through the official read-only MCP server. It uses **Member accounts**, with no developer app, API key, or additional Sim environment variables required.
+
 ## Connect
 
-An administrator enables **Lucid → Member accounts** in **Settings → Sources**. Each person then connects Lucid in **Integrations** and approves access with their own Lucid account.
+An admin adds **Lucid → Member accounts** in **Settings → Sources**. Each person then connects Lucid in **Integrations** and authorizes their account.
+
+The server supports Free, Individual, Team, and Enterprise plans, excluding FedRAMP accounts. Team/Enterprise admins may need to enable MCP. Documents owned outside the Lucid account boundary are excluded even when shared with you. [Lucid access rules](https://help.lucid.co/hc/en-us/articles/53780064823188-For-admins-Lucid-MCP-server-security-and-authorization).
+
+## Find documents or text
 
-Sim uses [Lucid’s official read-only MCP server](https://help.lucid.co/hc/en-us/articles/51290793390740-View-and-search-Lucid-content-with-AI-tools-using-the-Lucid-read-only-MCP-server), available on Free, Individual, Team and Enterprise plans; FedRAMP accounts are not supported. No developer app, API key or additional Sim environment variables are needed. Team and Enterprise administrators may need to enable MCP access in Lucid. Lucid excludes documents owned outside the connected account, even when shared with you.
+Start with a short title query such as `deployment architecture`. Title search requires terms even with date filters. Results rank by relevance and need not match the title literally. Native kinds `lucidchart` and `lucidspark` narrow the product; omit the kind to search both.
 
-## Search
+For text inside a known document, set native `project` to its UUID or Lucid URL and search a literal phrase such as `API Gateway`. Matching is case-insensitive across shape labels and sticky notes, excluding notes, tags, links, and comments.
 
-Title search requires terms, even when filtering by date. Results are ranked for relevance and may not match the title literally. Start with a short document-title query, such as `deployment architecture`. Select `lucidchart` or `lucidspark` to narrow the product, or search both. Read a result to inspect its diagram or board structure.
+Title queries allow 400 characters; document-text queries allow 200. Boolean and field operators are unsupported. Document search has no continuation and verifies at most ten candidates. Dates use modification time; sorting those candidates does not establish the globally newest or oldest document.
 
-To find text inside a known document, use its UUID or Lucid URL as the native query’s `project` and enter a literal phrase such as `API Gateway`. This matches shape labels and sticky-note text, case-insensitively. It does not search notes, tags, links or comments.
+## Browse folders
 
-Title queries allow up to 400 characters; document-scoped text queries allow 200. Boolean and field operators are unsupported. Document search has no continuation and verifies at most 10 candidates. Dates use modification time; filtering and sorting the returned candidates cannot establish the newest or oldest document across the entire account.
+Ask Sim to browse Lucid folders without search terms. It can list the root or a selected child folder. Each request returns one page of direct children; folder entries are navigation references, not document content. Follow continuation for the same folder or select a child folder.
 
-## Browse documents
+Browsing uses the same connection. It does not recursively scan the account or follow shortcuts. Date filters and sorting apply to the current page's document metadata, not all folders.
 
-Ask to browse your Lucid folders when you do not have a title or topic. The assistant can list the root folder or a selected child folder without guessing search terms. Each request returns one page of direct children; child folders are navigation references, not document content. Follow the continuation for more items in the same folder, or select a child folder to explore it.
+## Read diagram content
 
-Browsing uses the same personal readonly connection. It does not recursively scan the account, follow shortcuts, or guarantee the newest or oldest document across folders. Date filters and sorting apply to the current page’s document metadata.
+Reads preserve structured pages, nodes, connections, and properties, with source links. Large content can be read through successive windows of the same version. Incomplete, changed, or oversized reads are rejected rather than presented as complete graphs.
 
-## Diagram content
+A complete read is limited to eight page regions and 512 KiB. Images and external links remain references. This Sim adapter does not include rendered diagrams, OCR, comments, or Lucidscale, even when the provider offers additional read-only tools.
 
-Reads preserve Lucid’s structured pages, nodes, connections and properties, with links back to the source. Large responses can be read in successive windows of the same document version. Sim rejects incomplete or changed documents rather than treating a partial graph as complete.
+## Related docs
 
-A complete read is limited to 8 page regions and 512 KiB. Images and external links remain references; rendered diagrams, OCR, comments and Lucidscale are not included. See [Lucid’s MCP access rules](https://help.lucid.co/hc/en-us/articles/53780064823188-For-admins-Lucid-MCP-server-security-and-authorization) for account restrictions.
+- [Lucid read-only MCP server](https://help.lucid.co/hc/en-us/articles/51290793390740-View-and-search-Lucid-content-with-AI-tools-using-the-Lucid-read-only-MCP-server)
+- [Connect your account](/search/connect-your-account)
diff --git a/apps/docs/content/docs/search/mcp.mdx b/apps/docs/content/docs/search/mcp.mdx
index 0e838e09fca..a17d8844a7f 100644
--- a/apps/docs/content/docs/search/mcp.mdx
+++ b/apps/docs/content/docs/search/mcp.mdx
@@ -1,57 +1,75 @@
 ---
 title: Search MCP
-description: Search your organization's sources from Claude, Codex, Cursor, and other MCP apps
+description: Search organization sources from apps that support remote MCP
 ---
 
-Use Sim Search from another app to search and read your organization's sources through their live APIs, or ask the Sim Assistant for cited answers. Your current Sim membership, provider access, and source restrictions apply.
+Search MCP lets apps such as Claude, Codex, and Cursor search your organization's sources and read results. MCP (Model Context Protocol) connects an app to tools. Each person signs in to Sim; their current membership, provider access, and source restrictions apply.
 
 ## Connect an app
 
-1. Confirm you can find a document in the organization's **Search**. [Connect your source account](/search/connect-your-account) first if required.
-2. Open **Settings → Search MCP** in the organization view. Select your **App** and copy the displayed URL, command, or configuration.
-3. Follow the steps for your app below, sign in to Sim, and approve Search access. Each teammate signs in separately; no API key is needed for this flow.
+First confirm you can find a document in the organization's **Search**. [Connect your source account](/search/connect-your-account) if required.
+
+1. Open **Settings → Search MCP** in the organization view.
+2. Select your **App** and copy its displayed URL, command, or configuration.
+3. Add it in your app using the instructions below, sign in to Sim, and approve Search access. Each teammate signs in separately; this flow needs no API key.
+
+These are common client setups. Use the instructions displayed in Sim for other listed apps.
 
 | App | Finish setup |
 | --- | --- |
-| **Claude** | Add the copied **Server URL** as a custom connector, then connect it. For Team or Enterprise, an owner first adds it under **Organization settings → Connectors**; members then connect individually. See [Claude's custom connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). |
-| **Codex** | Run the copied **Terminal command** and complete browser sign-in. If authentication is needed again, run `codex mcp login sim-search`. |
-| **Claude Code** | Run the copied **Terminal command**, then open `/mcp` in Claude Code and authenticate. See [Claude Code's MCP instructions](https://code.claude.com/docs/en/mcp). |
-| **Cursor** | Add the copied `sim-search` entry to `mcpServers` in `~/.cursor/mcp.json`, preserving your other entries. Enable the server in Cursor and sign in to Sim. See [Cursor's MCP instructions](https://cursor.com/docs/mcp). |
-| **Other** | Add the **Server URL** to a client that supports remote MCP with OAuth. Choose **Streamable HTTP** if asked. |
+| **Claude** | Add the **Server URL** as a custom connector, then connect it. On Team or Enterprise, an authorized owner/admin first adds it under **Organization settings → Connectors**, then members connect individually. [Claude setup](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). |
+| **Codex** | Run the copied **Terminal command**, then `codex mcp login sim-search` to complete browser sign-in or reconnect. [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). |
+| **Claude Code** | Run the copied **Terminal command**, then open `/mcp` and authenticate. [Claude Code setup](https://code.claude.com/docs/en/mcp). |
+| **Cursor** | Add the copied `sim-search` entry to `mcpServers` in `~/.cursor/mcp.json`, preserving other entries. Enable it and sign in. [Cursor setup](https://cursor.com/docs/mcp). |
+| **Other** | Use a client supporting remote MCP with OAuth. Choose **Streamable HTTP** if asked. |
 
-For Claude's hosted custom connectors, your Sim deployment must be reachable from Claude's servers; a localhost URL will not work. See [Claude's network requirements](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
+Claude's hosted connectors reach Sim from Anthropic's servers. Your deployment must be publicly reachable from those servers; a localhost URL will not work. [Claude network requirements](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
 
-## Use the tools
+## Search and read
 
-Ask your app: “Use Sim Search to find our launch checklist, read the relevant document, and cite the source.” The app can use three tools:
+Ask your app: “Use Sim Search to find our launch checklist, read it, and cite the source.” It can use these tools:
 
 | Tool | Behavior |
 | --- | --- |
-| `search` | Searches the live providers. Use `source`, date filters, or `documentIds` to narrow results. `nativeQueries` supports provider syntax and pagination. Inspect `live.accounts` for provider status and cursors, and `live.guidance` for syntax. |
-| `read_document` | Reads fresh content using the exact opaque `documentId` returned by Search. When `hasMore` is true, pass the returned `next.startChunkIndex` and `next.startOffset` into the next read. It does not accept an arbitrary URL. |
-| `chat` | Asks the Sim Assistant a question using accessible sources and returns an answer with citations. Each call creates a new private Sim conversation. It accepts shared source and date filters; provider-native queries belong to `search`. |
+| `search` | Searches live providers. Narrow with `source`, dates, or `documentIds`. Use `nativeQueries` for provider syntax, pagination, Lucid folder browsing, or Notion sidebar lists. `live.accounts` reports status and cursors; `live.guidance` describes supported syntax. |
+| `read_document` | Reads one exact `documentId` returned by Search, or 1–10 IDs in `documentIds`. It does not accept arbitrary URLs. Continue an individual read using its returned `next.startChunkIndex` and `next.startOffset` when `hasMore` is true. |
+| `chat` | Asks Sim to research a question and return an answer with citations. Each call starts a private Sim conversation. Shared source/date filters apply; provider-native queries belong to `search`. |
 
-Cite the returned `citationUrl` when one is available. Keep `documentId` unchanged: it binds the result to your account, source, and organization. A title or a provider's raw document ID is not a substitute.
-The tools do not edit source content. Assistant policy and usage limits apply to `chat`.
+Keep each opaque `documentId` unchanged: it binds the result to the reader, account, source, and organization. Titles and raw provider IDs are not substitutes. Cite the returned `citationUrl` when available.
 
-## Access and limits
+Batch reads start each document at the beginning. Use `documentId` with the returned offsets to continue one document; batch `documentIds` cannot include offsets. An unreadable document returns its own error while other reads can succeed. Each document counts separately against read rate limits.
 
-The connection applies to the organization whose URL you copied. Sim checks current membership, source settings, and provider access on search and read. Connecting MCP does not add sources, connect provider accounts, or grant extra permissions. Live results do not depend on a Sim content or permission sync.
+The tools do not edit source content. Sim policy and usage limits apply to `chat`.
 
-`search` returns up to 20 results by default, with `topK` from 1 to 50. Its query allows up to 2,000 characters. A query may be empty when a date bound is supplied. Provider limits and filtering can return fewer results. Use a provider's returned continuation cursor with the same query and account; an empty page does not establish complete coverage.
+## Limits
 
-`read_document` accepts `limit` from 1 to 8 (default 3). The live backend returns bounded text pages and may return fewer chunks. Follow its `next` object rather than calculating offsets yourself. Live document IDs may be up to 4,000 characters. There is no pending-index metadata state.
+| Input or output | Limit |
+| --- | --- |
+| `search.topK` | 20 results by default; 1–50 allowed |
+| Search query | 2,000 characters |
+| `nativeQueries` | Up to four per provider account in one call |
+| Live document ID | 4,000 characters |
+| `read_document.limit` | 3 chunks by default; up to 8, with larger requests capped |
+| Batched `documentIds` | 1–10 documents; no continuation offsets |
+| `chat` question | 8,192 characters |
+| Tool response | 1 MiB |
 
-`chat` accepts questions up to 8,192 characters. Tool responses are limited to 1 MiB. API rate limits apply; follow any retry delay. Provider failures or incomplete retrieval are reported explicitly, and the tools do not fall back to an old index when a live provider is unavailable.
+A search query can be empty with date bounds, newest/oldest sorting where supported, or an explicit native browse mode. Provider filtering and limits may return fewer matches or chunks. Continue with the provider's cursor on the same query and account; for multiple native queries, match the status's `queryIndex` to the query being continued. An empty page does not prove complete coverage. Follow the read's `next` object instead of calculating offsets.
 
-These are the Search MCP schemas. Refresh tool discovery in clients that previously connected to the retired indexed backend.
+API rate limits apply; follow the returned retry delay. Provider failures and incomplete retrieval are explicit. The tools do not fall back to a stored index when a provider is unavailable.
 
 ## Reconnect or revoke access
 
-If sign-in expires or access is revoked, reconnect in your app. To withdraw its Sim authorization, open **Settings → General → Authorized apps**, find the app, and revoke it. This stops future requests; it does not remove content already returned to that app.
+The connection applies to the organization whose URL you copied. It does not add sources, connect provider accounts, or grant extra access. Search and reads recheck membership, settings, and provider permissions.
+
+If sign-in expires, reconnect in your app. To revoke its Sim authorization, open **Settings → General → Authorized apps**, find the app, and revoke it. This blocks future requests but does not remove content already returned to the app.
+
+If MCP is unavailable, ask an admin to check Search availability and MCP policy. For missing results, check the same query in Sim Search, your provider connection, and source settings.
 
-If Search MCP is unavailable, ask an organization admin to check the organization's Search availability and MCP policy. If results are missing, check the same query in Sim Search, your provider connection, and the current source settings first.
+## Related docs
 
-## Workspace MCP is separate
+- [Connect your account](/search/connect-your-account)
+- [Workspace MCP tools](/agents/mcp) — connect external servers to Sim agents
+- [Workflow MCP deployment](/workflows/deployment/mcp) — expose workflows as tools
 
-Organization Search MCP searches organization sources. [Workspace MCP tools](/agents/mcp) connect external servers to Sim agents; [MCP deployment](/workflows/deployment/mcp) exposes workflows as tools. Neither setup automatically adds workspace content to organization Search.
+Workspace and workflow MCP setups do not automatically add workspace content to organization Search.
diff --git a/apps/docs/content/docs/search/meta.json b/apps/docs/content/docs/search/meta.json
index 44cafa1b8ad..39fbea68eb7 100644
--- a/apps/docs/content/docs/search/meta.json
+++ b/apps/docs/content/docs/search/meta.json
@@ -2,8 +2,6 @@
   "title": "Search",
   "pages": [
     "connect-your-account",
-    "generic-secrets",
-    "mcp",
     "coda",
     "confluence",
     "fireflies",
@@ -20,6 +18,8 @@
     "lucid",
     "notion",
     "slack",
-    "zoom"
+    "zoom",
+    "mcp",
+    "generic-secrets"
   ]
 }
diff --git a/apps/docs/content/docs/search/notion.mdx b/apps/docs/content/docs/search/notion.mdx
index cd326cf5c60..81cf94cc42f 100644
--- a/apps/docs/content/docs/search/notion.mdx
+++ b/apps/docs/content/docs/search/notion.mdx
@@ -1,32 +1,39 @@
 ---
 title: Notion
-description: Search Notion page content through your personal Notion MCP connection
+description: Find Notion pages and databases through your personal MCP connection
 ---
 
-Notion supports **Member accounts** through its official hosted MCP service. An administrator enables Notion under **Settings → Sources**, then each teammate connects their own Notion account under **Integrations** and authorizes a workspace. Search uses the connected member's current permissions.
+Notion Search finds pages and databases through the official hosted MCP service. It uses **Member accounts** and the connected person's current workspace permissions.
 
-The ordinary Notion OAuth connection used by workflow blocks and knowledge-base ingestion is separate. Live Search uses personal MCP OAuth for content search; the REST API's title-only search is not used as a fallback.
+## Connect and search
 
-## Search effectively
+An admin adds **Notion** in **Settings → Sources**. Each teammate connects Notion in **Integrations** and authorizes a workspace. Search short keywords such as `launch rollback` or one focused question such as `Why did we postpone the migration?`. Read important matches before drawing conclusions.
 
-Use short, distinctive keywords such as `launch rollback` or a concise question such as `Why did we postpone the migration?`. Prefer one focused concept per query; shorten or rephrase a query that returns weak results. Read important matches before drawing conclusions.
+Personal MCP OAuth is separate from the ordinary Notion OAuth grant for workflow blocks and knowledge-base ingestion. Search does not fall back to REST title-only search.
 
-Sim checks the connection's current tool access before searching. When available, it uses Notion AI search; otherwise it uses the advertised keyword-search route. Workspace plans and enabled MCP tools determine availability. Notion can return results from connected applications, but Sim's Notion provider returns only Notion pages and databases. Search Slack, Gmail, or Drive through their own providers for those sources.
+## Queries and available tools
 
-The assistant can scope a query to a Notion page URL or ID when the server advertises page-scoped search. A server without that option reports the limitation. When the connection’s plan and tool schema allow it, Sim sends modification-date filters and newest sorting to Notion. It then checks exact timestamps from up to 10 current page reads. Other connections use local date filtering for keyword searches; date-only searches report the missing plan capability. These bounded results do not establish exhaustive date coverage or the oldest page in the workspace. Sim never substitutes the search time for a missing page date.
+Sim checks the connection's current tool access and advertised schemas. It uses AI search when exposed and available, or the advertised keyword route. Workspace plan, admin settings, and selected MCP tools affect availability. Notion may search connected apps, but Sim returns only Notion pages and databases; use the separate Slack, Gmail, or Drive source for those apps.
 
-## Browse pages
+Page-scoped native queries accept a Notion page URL or ID when the server advertises the supported page-scope field. Otherwise, Sim reports the limitation. Modification-date filters and newest sorting are sent only when the connection's plan and schema allow them. Sim checks exact timestamps from at most ten fresh page reads; other keyword searches use local date filtering. Date-only queries report unavailable plan capabilities.
 
-Ask for your private, shared, favorite, or recently viewed pages to browse without inventing keywords. Private and shared lists reflect the corresponding sidebar sections; they do not enumerate the whole workspace. Recently viewed pages are ranked by visits and frequency, not modification time. Follow the returned continuation to see more entries in the same list, and read a page for its contents.
+Bounded results do not establish exhaustive date coverage or the oldest page. Sim does not replace a missing page timestamp with search time. Capabilities can change with the authenticated server; [Notion's tool documentation](https://developers.notion.com/guides/mcp/mcp-supported-tools) describes current provider behavior.
 
-List availability is checked against the connected account’s current tools and access. Browsing keeps the same personal OAuth connection and requires no additional credentials.
+## Browse sidebar pages
 
-## Coverage and reads
+Ask Sim to browse private, shared, favorite, or recently viewed pages without keywords. Private/shared lists match sidebar sections, not the whole workspace. Recent pages rank by visits and frequency, not modification time. Follow continuation in the same list and read a page for content.
 
-Search returns a bounded, ranked selection. Pagination is used only when both the advertised tool and response support it. If results are capped, external results are dropped, or Notion reports plan restrictions, Sim marks the coverage as partial and suggests refining the query.
+List availability depends on current tools and access. Browsing uses the same personal connection without additional credentials.
 
-Reads fetch the exact page or database through the same member connection. Large pages can omit subtrees; Sim preserves that limitation in the returned content. Open the original page when the result says its content is incomplete.
+## Reads and coverage
 
-Search is limited to a fixed read-only allowlist: tool-access inspection, search, AI search, sidebar lists, and fetch. It cannot create or edit Notion pages. The server URL is fixed to Notion's official endpoint, and every call is validated against the current advertised tool schema.
+Search returns a bounded ranked selection. Pagination is used only when the advertised tool and response support it. Capped results, omitted external results, or plan restrictions produce partial-coverage guidance.
 
-See [Notion MCP setup](https://developers.notion.com/guides/mcp/get-started-with-mcp) and the [supported tools and plan behavior](https://developers.notion.com/guides/mcp/mcp-supported-tools).
+Reads fetch the exact page or database with the member's connection. Large pages may omit subtrees; the read preserves that notice. Open Notion when content is incomplete.
+
+Sim permits only tool-access inspection, search, sidebar lists, and fetch through a fixed read-only allowlist. It cannot create/edit pages or select another server URL.
+
+## Related docs
+
+- [Notion MCP setup](https://developers.notion.com/guides/mcp/get-started-with-mcp)
+- [Connect your account](/search/connect-your-account)
diff --git a/apps/docs/content/docs/search/slack.mdx b/apps/docs/content/docs/search/slack.mdx
index fbbcb7efb44..2edb75ca9e7 100644
--- a/apps/docs/content/docs/search/slack.mdx
+++ b/apps/docs/content/docs/search/slack.mdx
@@ -1,47 +1,47 @@
 ---
 title: Slack
-description: Search Slack live with your own account and use Sim Search from Slack
+description: Search your Slack messages and ask Sim questions from Slack
 ---
 
-Slack uses **Member accounts**. Search calls Slack's real-time search API with the connected member's user token. There is no live Slack service-account mode, admin channel selection, or background message indexing.
+Connect Slack as a source to search messages and files your account can access. Install **Sim Search** separately to ask questions from Slack. Installing the bot does not connect each person's source accounts or add Sim organization members.
 
-The Slack source and the Sim Search bot are separate connections: the source grants access to a person's messages; the bot lets that person ask Sim questions from Slack.
+Slack Search uses **Member accounts** and the member's real-time user token. There is no service mode, admin channel selection, or background message indexing.
 
 ## Add Slack as a source
 
-1. An organization admin adds **Slack** in **Settings → Sources**.
-2. Complete the organization's Slack app configuration if required. Use the official Sim Search app when available, or a custom app configured for this Sim deployment.
-3. Each member opens **Integrations → Slack → Connect** and authorizes their own Slack account.
-4. Search for a message that account can access. There is no channel setup or initial sync after authorization.
+1. An admin adds **Slack** in **Settings → Sources**.
+2. Complete the organization's app setup if needed. Use the official Sim Search app when available, or the deployment's custom app.
+3. Each member selects **Integrations → Slack → Connect** and authorizes their account.
+4. Search a known message, read it, and follow its Slack link. No channel setup or initial sync is needed.
 
-Slack app installation does not add people to your Sim organization or authorize their personal accounts. Invite teammates through **Settings → Members** or SSO when needed. App and workspace approval policies still apply.
+Members need a Sim invitation or SSO membership separately. Provider app/workspace approval policies still apply.
 
-## How search and reads work
+## Search messages and files
 
-Sim sends the query to `assistant.search.context` with the member's user token. Public channels, private channels, DMs, group DMs, and files are available only to the extent permitted by that account and its granted scopes. Member mode does not add an organization filter to those permissions.
+Sim calls `assistant.search.context` with your user token. Public/private channels, DMs, group DMs, and files follow that account's access and scopes, without an additional organization filter.
 
-A question can use Slack search modifiers to narrow its scope. Relevance search can use Slack's semantic matching where available; date ordering uses keyword retrieval and timestamp ordering. The adapter follows provider continuation cursors and reports rate-limit, scope, and retrieval failures.
+Slack search modifiers can narrow the query. Relevance can use semantic matching where available; date ordering uses keyword retrieval and timestamp order. Continue returned provider cursors on the same query and account. Scope, rate-limit, and retrieval failures are reported explicitly.
 
-Reading a message uses the same member's thread access. File reads return Slack's available preview and a link to the source, not an unrestricted download of every attachment. Retention, provider search freshness, and API limits affect coverage.
+Message reads use your thread access. File reads return available previews and source links, not unrestricted attachment downloads. Retention, search freshness, and API limits affect coverage.
 
 ## Use Sim Search in Slack
 
-An admin opens **Settings → Sim Search in Slack** and installs or connects the bot for the target workspace. Members still connect their source accounts in Integrations. The bot uses the same live Search assistant and authorization as the web experience and Search MCP.
+An admin opens **Settings → Sim Search in Slack** and installs or connects the bot for the target workspace. Members still connect sources in **Integrations**. Answers use the same Search retrieval and authorization as Sim and Search MCP.
 
 - DM **Sim Search**, or mention it in a channel it has joined.
-- Use **/query [question]** to start a private DM thread. Channel invocations keep personalized answers and account details in DMs.
-- Use **/connect [provider]**, or **Home → Connect sources**, to open your personal Integrations in Sim. OAuth starts when you select Connect there.
-- Follow the returned source links. Use Slack's Stop control to cancel an active answer and queued follow-ups.
+- Where the installed app exposes slash commands, use `/query [question]` to start a private DM thread. Channel invocations keep personalized answers and account details in DMs.
+- Use `/connect [provider]` where available, or **Home → Connect sources**, to open personal Integrations. Select **Connect** there to start OAuth.
+- Follow source links. Slack's **Stop** control cancels an active answer and queued follow-ups.
 
-Installing the bot alone does not give it every employee's source access. Removing a bot binding is separate from disconnecting the personal Slack source.
+Removing the bot binding is separate from disconnecting your Slack source.
 
 ## Custom app and self-hosted setup
 
-Use the setup flow's generated manifest for your deployment. Keep its OAuth callbacks, events, interactivity URL, and required bot/user permissions together; do not copy credentials from a different environment. Slack must be able to reach the app's HTTPS event endpoint. Local browser flows can run on localhost, but inbound Slack events need a publicly reachable callback.
+Use the generated manifest from the setup flow. Keep its OAuth callbacks, events, interactivity URL, and full bot/user permissions together. Slack must reach the HTTPS event endpoint; localhost browser authorization does not make inbound events reachable.
 
-The organization uses one configured Slack app and workspace for member connections. Changing the app or required scopes requires affected members to reconnect. Slack's real-time search capability must be available to that app, such as an eligible internal or approved app.
+The organization uses one configured app and workspace for member connections. App or scope changes require reconnecting affected members. Real-time search must be available to the app, such as an eligible internal or approved app; bot installation alone does not establish eligibility.
 
-The live user grant includes these real-time search scopes:
+The live user grant includes:
 
 ```text
 search:read.public
@@ -52,9 +52,9 @@ search:read.files
 files:read
 ```
 
-The shared configuration also retains identity and conversation-read scopes used to identify the connected account and read message threads. Bot permissions are separate and let Sim receive and answer Slack questions. Use the generated manifest rather than replacing its full scope set with only this live-search subset.
+Shared configuration also includes identity and conversation-read scopes. Bot permissions separately receive and answer questions. Do not replace the manifest's full scope set with only this subset or copy another environment's credentials.
 
-The configured redirect URLs use your Sim origin:
+Register the generated URLs on your exact Sim origin:
 
 ```text
 https://<your-sim-domain>/api/knowledge/slack/oauth/callback
@@ -62,16 +62,19 @@ https://<your-sim-domain>/api/credential-groups/slack-managed-users/callback
 https://<your-sim-domain>/api/credential-groups/oauth/slack/callback
 ```
 
-See Slack's [real-time search method](https://docs.slack.dev/reference/methods/assistant.search.context/) and [app manifest reference](https://docs.slack.dev/reference/app-manifest/).
-
 ## Troubleshooting
 
-| Problem | Next step |
+| Problem | Check |
 | --- | --- |
-| Integrations shows Not configured | An admin must finish the organization's Slack app configuration. |
-| Missing real-time search scope | Update the app's user permissions, obtain approval/reinstall as Slack requires, and reconnect the member. |
-| Real-time search is unavailable to the app | Check Slack's app eligibility; a working bot installation alone does not establish search access. |
-| Private channel or DM is absent | Confirm the connected member can access it and granted the required scope. |
-| Bot cannot answer | Check its organization binding, the member's Sim membership, and their source connections. |
-| Localhost receives no bot events | Slack cannot reach a private localhost event endpoint; use the deployment's reachable callback. |
-| Results are incomplete | Check provider limits and retention, narrow the query, or continue the provider page. There is no Sim indexing status to clear. |
+| `Not configured` | Ask an admin to finish organization app setup. |
+| Real-time scope missing | Update user permissions, approve/reinstall as Slack requires, then reconnect. |
+| Real-time search unavailable | Check app eligibility; a working bot does not prove search access. |
+| Private channel or DM missing | Check member access and required scope. |
+| Bot cannot answer | Check organization binding, Sim membership, and personal source connections. |
+| No localhost bot events | Use a deployment callback reachable by Slack. |
+| Incomplete results | Check provider limits/retention, narrow the query, or continue the provider page. |
+
+## Related docs
+
+- [Slack real-time search](https://docs.slack.dev/reference/methods/assistant.search.context/)
+- [Slack app manifests](https://docs.slack.dev/reference/app-manifest/)
diff --git a/apps/docs/content/docs/search/zoom.mdx b/apps/docs/content/docs/search/zoom.mdx
index 01ad72daec6..b2c0374e027 100644
--- a/apps/docs/content/docs/search/zoom.mdx
+++ b/apps/docs/content/docs/search/zoom.mdx
@@ -1,55 +1,61 @@
 ---
 title: Zoom
-description: Search past meetings, transcripts, personal notes and AI summaries with your Zoom account
+description: Find past meetings and read available transcripts, notes, and summaries
 ---
 
+When Zoom Search is enabled for your organization, connect your own account to find past meetings and read available artifacts. It uses **Member accounts** and the official Zoom Meetings MCP server, separately from workflow OAuth connections.
+
 ## Connect
 
-An administrator enables **Zoom → Member accounts** under **Settings → Sources**. Then each person connects their own account:
+Zoom Search requires deployment enablement and organization access before setup or retrieval is available. Ask your admin about availability if Zoom is missing.
 
-1. Open **Integrations** in Sim and click **Connect** beside Zoom.
-2. Sign in to Zoom, review the requested read permissions, and authorize the app. Your Zoom administrator may need to approve it first.
-3. Return to Sim and confirm your account appears on the Zoom row. Current Zoom permissions determine which meetings and artifacts you can read.
+1. An admin adds **Zoom → Member accounts** in **Settings → Sources**.
+2. Each person selects **Integrations → Zoom → Connect**, signs in, and authorizes the read permissions. Zoom account-admin approval may be needed.
+3. Return to Sim, confirm the account appears, and search a known meeting. Read the result and follow its source link.
 
-If connection fails, see [Troubleshooting](#troubleshooting).
+A workflow Zoom connection does not authorize Search. Its dedicated app registration prevents Search reauthorization from replacing or narrowing a workflow app's grant.
 
-Sim uses the official [Zoom Meetings MCP server](https://developers.zoom.us/docs/mcp/zoom-meetings-mcp-server/). Search uses a separate General OAuth app registration from workflow actions. Zoom reauthorization can replace or narrow an existing user/app grant, so sharing the workflow client would risk disconnecting existing workflows. A Zoom workflow connection does not authorize Search.
+## Search and read meetings
 
-For self-hosted deployments, configure `ZOOM_MCP_CLIENT_ID` and `ZOOM_MCP_CLIENT_SECRET` from a separate General, User-managed Search app. In the [Zoom app](https://developers.zoom.us/docs/mcp/servers/connect-to-zoom-mcp-servers/), enable `meeting:read:search` and `meeting:read:assets` and register the exact callback below in both the redirect field and OAuth allow list:
+Ask Sim on **Home**: “Search Zoom for deployment rollback decisions last week and cite the transcript.” Use short plain keywords such as `deployment rollback`. Zoom matches topics, agendas, and available meeting content.
 
-```text
-https://<your-sim-domain>/api/mcp/oauth/callback
-```
+Results identify past occurrences by UUID rather than recurring meeting number. Use native kind `meeting` when sending multiple queries to one account. `startDate` and `endDate` use actual start time, with an exclusive end. Continue `nextCursor` with the same account, query, and filters; rerun an expired continuation. [Zoom's Meetings API](https://developers.zoom.us/docs/api/meetings/) documents a 15-minute page-token lifetime; restart Search if the MCP continuation expires.
 
-An internal app works only for users in its Zoom account. Connecting users from other Zoom accounts requires [approved external distribution](https://developers.zoom.us/docs/build-flow/before-you-build/), including for unlisted production apps. Limited external beta testing uses Zoom's separate [sharing approval](https://developers.zoom.us/docs/distribute/sharing-private-and-beta-apps/).
+Each page verifies at most ten candidates. Sorting that page does not establish the globally newest or oldest match. Boolean/field operators, project selection, ownership, and modification-date filters are unsupported.
 
-The OAuth exchange uses PKCE and `client_secret_basic`. Search requests only those two read scopes, even when Zoom discovery advertises write tools. The fixed endpoint is `https://mcp.zoom.us/mcp/meeting/streamable`; Sim allows only `search_meetings` and `get_meeting_assets`.
+Reads return available timestamped transcripts, personal notes, and separately labeled AI summaries. Notes and summaries are not verbatim speech. Sim does not download recordings or transcribe audio. Recording, transcription, AI Companion settings, licenses, processing state, and sharing permissions determine which artifacts exist.
 
-## Search and read
+Missing artifacts do not prove a discussion never happened. Oversized or malformed reads fail explicitly; provider failures do not appear as complete searches with no matches.
 
-On **Home**, ask a question such as “What did we decide about deployment rollback last week? Search Zoom and cite the transcript.” Follow a result’s source link to open it in Zoom.
+## Self-hosted operator setup
 
-Use short plain keywords such as `deployment rollback`. Zoom matches meeting topics, agendas and available meeting content. Results identify past meeting occurrences by UUID, rather than the recurring meeting number. Use `kind: meeting` when sending multiple native queries to one account.
+Zoom Search is disabled by default. Enable it with `ZOOM_SEARCH=true` for otherwise eligible organization scopes on a self-hosted deployment. Organization-targeted deployments can use the `zoom-search` AppConfig feature flag instead. Availability does not grant membership or provider access. Disabling the rollout blocks later Search setup and retrieval while retaining saved grants and conversations; members can still disconnect.
 
-`startDate` and `endDate` filter actual meeting start time. The end is exclusive. Continue with `nextCursor` using the same account, query and filters; Zoom's page token expires after 15 minutes. Each page verifies at most 10 candidates. Sorting the returned candidates does not establish the globally newest or oldest match.
+Configure a separate General, User-managed Search app with `ZOOM_MCP_CLIENT_ID` and `ZOOM_MCP_CLIENT_SECRET`. Enable `meeting:read:search` and `meeting:read:assets`. Register this exact callback in both the redirect field and OAuth allow list:
 
-Read a result for available timestamped transcripts, personal notes and separately labeled AI-generated summaries. Generated summaries and notes are not verbatim speech. Sim does not download recordings or transcribe audio. Recording, transcription and AI Companion settings, licenses, processing state and sharing permissions determine which artifacts exist.
+```text
+https://<your-sim-domain>/api/mcp/oauth/callback
+```
 
-Boolean/field operators, project selection, ownership filters and modification-date filters are unsupported. An absent artifact does not prove a meeting had no discussion. Oversized or malformed reads fail explicitly; provider failures do not appear as a successful search with no matches.
+An internal app supports only its Zoom account. Other accounts require approved external distribution, including unlisted production apps; beta sharing has a separate approval process. Follow [Zoom's MCP app setup](https://developers.zoom.us/docs/mcp/servers/connect-to-zoom-mcp-servers/), [production distribution](https://developers.zoom.us/docs/build-flow/before-you-build/), and [beta sharing guidance](https://developers.zoom.us/docs/distribute/sharing-private-and-beta-apps/).
 
-## Disconnect
+The connection uses PKCE and `client_secret_basic`. Sim requests only those two read scopes and permits `search_meetings` and `get_meeting_assets`, even if discovery includes writes. Its fixed endpoint is `https://mcp.zoom.us/mcp/meeting/streamable`.
 
-In Sim **Integrations**, open the **…** menu beside Zoom, choose **Disconnect** for your account, and confirm. This stops that connection from being used in this organization. Any workflows using the same connection also lose access; other people's connections are unaffected.
+## Disconnect and troubleshoot
 
-To remove the authorization from Zoom too, open **Zoom App Marketplace → My Library**, find the Sim app you authorized for Search, open its **More** menu, and choose **Remove**, then confirm. See [Zoom's removal instructions](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0062865); your Zoom administrator may control app removal.
+In **Integrations**, open Zoom's **…** menu, select **Disconnect** for the account, and confirm. This stops use in the organization. Workflows using that same connection lose access; other members' connections are unaffected.
 
-Disconnecting does not delete meetings or recordings in Zoom or erase existing Sim conversations. See [Sim's Privacy Policy](https://www.sim.ai/privacy) for data handling and deletion requests.
+To remove Zoom authorization too, open **Zoom App Marketplace → My Library**, find the Search app, and select **More → Remove**. Account admins may control removal. Disconnecting does not delete meetings/recordings or existing Sim conversations. [Zoom removal instructions](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0062865).
 
-## Troubleshooting
+| Problem | Check |
+| --- | --- |
+| Connect unavailable | Check organization enablement, source setup, dedicated OAuth app, and Zoom app approval. |
+| **Reconnect** needed | Authorize the same account again. |
+| Meeting or text missing | Check Zoom access, topic/dates, recording/transcript/summary settings, and processing state. |
+| Expired cursor or changed content | Search again before continuing. |
 
-- **Connect is unavailable:** ask your Sim administrator to enable the source and finish the Zoom app configuration. Ask your Zoom administrator about app approval if authorization is blocked.
-- **Reconnect needed:** use **Reconnect** on the Zoom row in Integrations and authorize the same account again.
-- **Missing meeting or text:** confirm you can open it in Zoom, try a distinctive topic and date range, and check whether recording, transcription or AI summary processing has finished. Available content depends on the meeting's settings and your permissions.
-- **Expired cursor or changed content:** run the search again before continuing the result. Zoom page tokens expire after 15 minutes.
+## Related docs
 
-For help, contact [help@sim.ai](mailto:help@sim.ai).
+- [Zoom Meetings MCP server](https://developers.zoom.us/docs/mcp/zoom-meetings-mcp-server/)
+- [Sim Privacy Policy](https://www.sim.ai/privacy) — data handling and deletion requests
+- [Contact support](mailto:help@sim.ai)
diff --git a/apps/docs/content/docs/tables/index.mdx b/apps/docs/content/docs/tables/index.mdx
index c97fc25b19b..a8aab55bbf6 100644
--- a/apps/docs/content/docs/tables/index.mdx
+++ b/apps/docs/content/docs/tables/index.mdx
@@ -1,55 +1,63 @@
 ---
 title: Tables
-description: A grid of typed columns and rows in your workspace, for data your workflows read and write.
+description: Store typed records that your workflows and agents read and write.
 ---
 
 import { Image } from '@/components/ui/image'
-import { Card, Cards } from 'fumadocs-ui/components/card'
-import { FAQ } from '@/components/ui/faq'
 
-A **table** is a grid of typed columns in your workspace, like a spreadsheet with a schema. Use one to hold reference data, collect what your workflows produce, or store the structured records your agents read and write.
+A table stores rows of typed data in your workspace. Use one for reference data, workflow results, or records that an agent processes.
 
-<div className="mx-auto w-full overflow-hidden rounded-lg my-6">
-  <Image src="/static/tables/tables-overview.png" alt="The current table editor showing typed position, driver, nationality, team, wins, and points columns" width={1064} height={850} />
-</div>
+## Create and edit a table
+
+1. Open **Tables** in the sidebar and select **New table**.
+2. Use **New column** to define your columns and their types.
+3. Enter values in cells, paste rows from a spreadsheet, or use **Import** to load data.
+4. Use the toolbar to filter and sort the view without changing stored values. See [Keyboard shortcuts](/keyboard-shortcuts) for editing and navigation.
+
+<Image
+  src="/static/tables/tables-overview.png"
+  alt="Example table with typed columns and controls for filtering, sorting, importing, and exporting"
+  width={1064}
+  height={850}
+/>
 
 ## Column types
 
-Every column has a type, which decides how its values are stored and validated.
+The type determines how a column stores and displays values.
 
 | Type | Holds | Example |
 | --- | --- | --- |
-| **Text** | A free-form string | `"Acme Corp"` |
+| **Text** | A string | `"Acme Corp"` |
 | **Number** | A numeric value | `42` |
-| **Currency** | An amount in a currency you pick per column | `$1,234.56` |
+| **Currency** | A number displayed in the column's selected currency | `$1,234.56` |
 | **Boolean** | `true` or `false` | `true` |
-| **Date** | A date | `2026-03-16` |
-| **JSON** | An object or array | `{ "tier": "pro" }` |
-| **Select** | One of a fixed set of options, or several | `Pro` |
+| **Date** | A date, or date and time | `2026-03-16` |
+| **Expiration** | A deletion timestamp with `Z` or an explicit UTC offset | `2026-12-01T00:00:00Z` |
+| **JSON** | Any JSON value | `{ "tier": "pro" }` |
+| **Select** | One or several configured options | `Pro` |
+
+Safe conversions are accepted, such as a numeric string into a Number column. Unsupported optional values can become empty in the editor or workflow writes; the public v2 API rejects invalid writes. Produce typed values and inspect the saved result.
+
+Currency stores the number itself, which filters, sorts, and exports use. Changing the selected currency relabels existing amounts; it does not convert them.
+
+### Expiration
 
-Types are enforced as you enter values, so a Number column only takes numbers.
+A table can have one Expiration column. Rows with a timestamp at or before the cleanup time are eligible for scheduled deletion; blank values do not expire. Shipped Compose and Helm schedules check every 15 minutes, so deletion is not immediate at the timestamp. Delete locks can prevent cleanup. Set this column only when scheduled removal is intended.
 
-A Currency column stores a plain number and renders it in the currency you choose for that column, so filters, sorts, and exports all see the amount itself. Changing a column's currency relabels it — it does not convert the amounts.
+## Use tables in workflows
 
-## Editing a table
+A [Table block](/tables/using-in-workflows) reads and writes rows within a workflow. A [workflow column](/tables/workflow-columns) runs per-row work and writes selected outputs beside the source data. Use a Function or Agent block for calculations; tables do not evaluate spreadsheet formulas. Tables are also available through the [API](/api-reference/getting-started).
 
-Open the **Tables** section in the sidebar and click **New table** to create one. Add columns from the column header, type into a cell to edit it, and paste rows from a spreadsheet to bulk-load. Filter and sort from the toolbar without changing the underlying data. The editor has full keyboard support; see [keyboard shortcuts](/keyboard-shortcuts).
+## Limits and behavior
 
-## Tables in workflows
+Row and table counts depend on the plan and deployment configuration. The maximum row-data size defaults to 400 KiB and is configurable per deployment. Tables have a fixed ceiling of 1,000 columns. Query pages have a default 5 MiB row-data budget, which can be configured for bounded pages. A query requesting all matches has a fixed 5 MiB budget. Use pagination for large reads.
 
-A [Table block](/tables/using-in-workflows) reads and writes rows from inside a workflow: query rows for reference data, write results back, or process a batch. A [workflow column](/tables/workflow-columns) goes a step further and runs a workflow against each row on its own. Everything in a table is also available over the [REST API](/api-reference/getting-started).
+Individual row writes are atomic, but a workflow's read → process → write sequence is not one transaction. Concurrent workflows can operate on the same table and affect the same records.
 
-## Next
+In the editor, `Cmd/Ctrl+Z` undoes recent cell edits, row insertions, and row deletions. That history clears when you leave the editor and does not include changes made through the API.
 
-<Cards>
-  <Card title="Using tables in workflows" href="/tables/using-in-workflows" description="Read, write, and update rows with the Table block." />
-  <Card title="Workflow columns" href="/tables/workflow-columns" description="Run a workflow against each row of a table." />
-  <Card title="Keyboard shortcuts" href="/keyboard-shortcuts" description="Navigate and edit a table from the keyboard." />
-</Cards>
+## Related docs
 
-<FAQ items={[
-  { question: "Is there a row limit per table?", answer: "Yes. Row and table counts depend on the plan and deployment configuration. By default, a row may contain up to 400 KB of data and a table up to 1,000 columns. Use pagination for large reads; query responses have a 5 MB row-data budget." },
-  { question: "Do tables support formulas?", answer: "No. Tables store raw data. Use workflow logic (a Function or Agent block) to compute values and write them back." },
-  { question: "Can multiple workflows write to the same table?", answer: "Yes. Writes are atomic at the row level, so multiple workflows can write to the same table at once." },
-  { question: "Can I undo changes?", answer: "In the table editor, Cmd/Ctrl+Z undoes recent cell edits, row insertions, and row deletions. Changes made through the API are not part of the editor's undo history." },
-]} />
+- [Using tables in workflows](/tables/using-in-workflows) for Table block operations and pagination
+- [Workflow columns](/tables/workflow-columns) for per-row enrichments and workflows
+- [Keyboard shortcuts](/keyboard-shortcuts) for table editing
diff --git a/apps/docs/content/docs/tables/using-in-workflows.mdx b/apps/docs/content/docs/tables/using-in-workflows.mdx
index 1b9d01b54eb..71693f3e1a9 100644
--- a/apps/docs/content/docs/tables/using-in-workflows.mdx
+++ b/apps/docs/content/docs/tables/using-in-workflows.mdx
@@ -1,44 +1,60 @@
 ---
 title: Using tables in workflows
-description: How a workflow reads, writes, and updates table rows with the Table block.
+description: Query rows, process their data, and write results with the Table block.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
 import { WorkflowPreview, OutputBundle, TABLE_ENRICH_WORKFLOW } from '@/components/workflow-preview'
 
-A [table](/tables) is a resource: structured rows your workflows read and write. A [Table block](/integrations/table) is the step that does the reading and writing inside a workflow. You pick an operation on the block (query rows, insert a row, update rows), point it at a table, and its result is remembered under the block's name for later blocks to use.
+Use a [Table block](/integrations/table) for a read or write within a workflow. Use [workflow columns](/tables/workflow-columns) when the table should run the same work separately for each row.
 
-A workflow uses whichever Table operations its task needs. It might read rows to work on, write rows produced elsewhere, update rows in place, or just look something up mid-run. This page covers the operations and shows a few ways to combine them.
+## Classify and update rows
 
-Throughout this page the running example is a `leads` table with columns `company`, `email`, `description`, `status`, `category`, and `score`. The goal is to find unprocessed leads, have an Agent classify each one, and write the category back.
+Create a `leads` table with `company`, `email`, `description`, `status`, `category`, and `score` columns. Use Number for `score` and Text for the other fields. Then build this sequence:
 
-<WorkflowPreview workflow={TABLE_ENRICH_WORKFLOW} height={300} />
-
-## The Table block
-
-A **Table block** performs one operation against one table. The **Operation** dropdown picks the action; the **Table** selector picks the target. The fields below those two change based on the operation you choose.
+1. Set a Table block's **Operation** to **Query Rows**, choose the table, and filter for `status` equal to `unprocessed`.
+2. Add a **For Each** [Loop](/workflows/blocks/loop) over `<table1.rows>`, replacing `table1` with your query block's name.
+3. Inside the loop, configure an Agent to classify `<loop.currentItem.data.description>`. Request `category` and `score` using a valid [response-format schema](/workflows/blocks/agent).
+4. Add **Update Row by ID** inside the loop. Use `<loop.currentItem.id>` as **Row ID** and valid JSON for **Row Data**:
 
-{/* VISUAL: Table block UI showing the Operation dropdown open, plus the conditional fields that appear for Query Rows (Filter, Order, Columns to Return, Limit, Cursor). */}
-
-The operations fall into three groups:
+```json
+{
+  "category": "<agent.category>",
+  "score": "<agent.score>",
+  "status": "qualified"
+}
+```
 
-- **Read:** Query Rows, Get Row by ID, Get Schema.
-- **Write:** Insert Row, Batch Insert Rows, Upsert Row.
-- **Update and delete:** Update Row by ID, Update Rows by Filter, Delete Row by ID, Delete Rows by Filter.
+The references use your block names. Table writes can safely convert a numeric score string; still inspect the result if the Agent fails to produce the requested structure.
 
-Every row carries three built-in columns alongside your own: `id` (the row's unique identifier), `createdAt`, and `updatedAt`. Sim manages these for you, so you never include them when inserting. You can still filter and sort on them.
+<WorkflowPreview workflow={TABLE_ENRICH_WORKFLOW} height={300} />
 
-## Reading rows
+The status change keeps later runs from selecting completed rows. It does not claim a row atomically: overlapping workflow runs can query the same unprocessed row before either writes its result.
 
-**Query Rows** retrieves rows from a table, with optional filtering, sorting, and pagination. It's how a workflow gets its input from a table.
+## Read rows
 
-For our example, the block queries `leads` where `status` equals `unprocessed`. Its output holds the matching rows plus counts:
+Choose **Operation** and **Table** on each Table block. **Query Rows** returns an array whose cells are nested under each row's `data`:
 
-```
-{ success: true, rows: [ { id: "row_...", company: "Acme", ... } ], rowCount: 5, totalCount: 42 }
+```json
+{
+  "success": true,
+  "rows": [
+    {
+      "id": "row_8f2c",
+      "data": { "company": "Acme", "status": "unprocessed" },
+      "executions": {},
+      "position": 0,
+      "createdAt": "2026-06-01T09:00:00Z",
+      "updatedAt": "2026-06-01T09:00:00Z"
+    }
+  ],
+  "rowCount": 1,
+  "totalCount": 42,
+  "limit": 1,
+  "nextCursor": "cursor_from_the_query"
+}
 ```
 
-Later blocks read these by name: `<table1.rows>` is the array, `<table1.rowCount>` is how many came back, `<table1.totalCount>` is how many matched the filter before the limit. (For more on reading outputs by reference, see [how blocks pass data](/workflows/data-flow).)
+Read `<table1.rows[0].data.company>` for a cell or `<table1.rows[0].id>` for its row ID. `rowCount` counts rows in this response. `totalCount` counts all matches on the first page and may be `null` on subsequent cursor pages.
 
 <OutputBundle
   blockName="table1"
@@ -48,93 +64,88 @@ Later blocks read these by name: `<table1.rows>` is the array, `<table1.rowCount
   values={[
     {
       key: 'rows', type: 'array', highlight: true,
-      children: [
-        {
-          key: '0', type: 'object',
-          children: [
-            { key: 'id', type: 'string', expanded: false },
+      children: [{
+        key: '0', type: 'object',
+        children: [
+          { key: 'id', type: 'string', value: '"row_8f2c"' },
+          { key: 'data', type: 'object', children: [
             { key: 'company', type: 'string', value: '"Acme"' },
             { key: 'status', type: 'string', value: '"unprocessed"' },
-          ],
-        },
-      ],
+          ] },
+        ],
+      }],
     },
-    { key: 'rowCount', type: 'number', value: '5' },
+    { key: 'rowCount', type: 'number', value: '1' },
     { key: 'totalCount', type: 'number', value: '42' },
   ]}
 />
 
-**Filter** narrows the result. You can build rules visually - pick a column, an operator, and a value - or write the filter directly as a predicate. One condition names a field, an operator, and a value:
-
-```
-{"field": "status", "op": "eq", "value": "unprocessed"}
-```
+### Filter, order, and projection
 
-Combine conditions with `all` (AND) or `any` (OR), and nest the groups for mixed logic:
+Build **Filter** rules visually or supply a predicate. A condition names a field, operator, and value:
 
+```json
+{ "field": "status", "op": "eq", "value": "unprocessed" }
 ```
-{"all": [
-  {"field": "status", "op": "eq", "value": "unprocessed"},
-  {"field": "createdAt", "op": "gte", "value": "2026-06-01"}
-]}
-```
-
-**Order** sorts the result as a list of column/direction pairs, for example `[{"field": "createdAt", "direction": "desc"}]`. **Columns to Return** narrows each row to the fields a downstream step actually needs. **Limit** caps how many rows come back per page, and **Cursor** continues a previous page - see [Paginate large reads](#variations) below.
-
-{/* VISUAL: Filter and Order builders, showing a status = unprocessed rule and a createdAt descending sort, with the equivalent predicate JSON beside them. */}
 
-For a one-off point lookup, use **Get Row by ID** with a single `Row ID`. **Get Schema** returns the table's column definitions, useful when a workflow needs to inspect structure before writing. The full operator list lives in the [Table block reference](/integrations/table).
+Combine conditions with `all` (AND) or `any` (OR), nesting groups for mixed logic:
 
-## Writing rows
-
-**Insert Row** adds one row. Its **Row Data** is an object whose keys match your column names:
-
-```
-{ company: "Acme", email: "deals@acme.com", description: "...", status: "unprocessed" }
+```json
+{
+  "all": [
+    { "field": "status", "op": "eq", "value": "unprocessed" },
+    { "field": "createdAt", "op": "gte", "value": "2026-06-01" }
+  ]
+}
 ```
 
-The output is the inserted row, including the `id` and timestamps Sim generated for it.
+**Order** accepts a list of field/direction pairs, such as `[{"field":"createdAt","direction":"desc"}]`. **Columns to Return** selects the cells you need. Built-in `id`, `createdAt`, and `updatedAt` fields are managed by Sim and can be used for filtering and sorting.
 
-**Batch Insert Rows** adds many rows in one operation (up to 1000) from a **Rows Data** array. Use it instead of looping Insert Row when you have a set of results to load at once. Its output reports `insertedCount`.
+Use **Get Row by ID** for a point lookup and **Get Schema** for column definitions. See the [Table block reference](/integrations/table) for all operators.
 
-**Upsert Row** inserts a row, or updates the existing one if it matches a unique column. Its output includes an `operation` field set to `insert` or `update`, so a later block can tell which happened.
+## Write and update rows
 
-<Callout type="info">
-Row data must match the table's columns and types. A `number` column rejects `"twenty"`; a `boolean` column wants `true`, not `"true"`. If an Agent produces the value, give it a [structured output](/workflows/blocks/agent) so the shape is predictable before it reaches the table.
-</Callout>
+| Operation | Behavior |
+| --- | --- |
+| **Insert Row** | Adds one row and returns its generated ID and timestamps. |
+| **Batch Insert Rows** | Adds up to 1,000 rows from **Rows Data** and reports `insertedCount`. |
+| **Upsert Row** | Inserts or updates a match on a unique column; `operation` is `insert` or `update`. |
+| **Update Row by ID** | Patches only the supplied fields for one **Row ID**. |
+| **Update Rows by Filter** | Applies one patch to matching rows; reports `updatedCount` and `updatedRowIds`. |
+| **Delete Row by ID** | Removes the specified row and reports `deletedCount`. |
+| **Delete Rows by Filter** | Removes matching rows and reports `deletedCount`. |
 
-## Updating rows
+**Row Data** must be JSON with keys matching your column names. Do not include built-in IDs or timestamps on insert:
 
-To change an existing row you either name it or filter for it.
-
-**Update Row by ID** modifies one row. It takes a `Row ID`, often `<table1.rows[0].id>` from an earlier query, and **Row Data** with only the fields you want to change. Unlisted fields stay as they were.
-
-**Update Rows by Filter** applies the same update to every matching row. Use it for a bulk change, such as marking a selected batch for review. For a different classification per lead, iterate over the queried rows and use **Update Row by ID** for each result. The filter operation reports `updatedCount` and `updatedRowIds`.
-
-{/* VISUAL: before/after of the leads table. Left shows rows with status "unprocessed" and an empty category column; right shows the same rows with category filled in and status "qualified". */}
-
-**Delete Row by ID** and **Delete Rows by Filter** remove rows the same two ways, by ID or by filter, and report a `deletedCount`. Deletes are mostly for cleanup, not part of the everyday read-process-write loop.
+```json
+{
+  "company": "Acme",
+  "email": "deals@acme.com",
+  "description": "Enterprise software buyer",
+  "status": "unprocessed"
+}
+```
 
-## Example: enriching rows
+Upsert requires a unique column. If the table has several, select **Conflict Column** to choose the match target. Unlisted fields remain unchanged in a partial update.
 
-One way to combine the operations is to query rows, process them, and write the results back. Here, the workflow classifies unprocessed leads:
+For different results per row, use a sequential Loop and **Update Row by ID**. A filter update applies the same values to every match; with no **Limit**, it walks all matches in batches. The 1,000 maximum applies to an explicitly supplied update limit, not the total for an unlimited filtered update.
 
-1. **Table (Query Rows)** reads `leads` where `status` is `unprocessed`.
-2. Add a **For Each** [Loop](/workflows/blocks/loop) over the returned `rows` array.
-3. Inside the loop, an **Agent** reads the current row and returns a [structured output](/workflows/blocks/agent), such as `{ category: "enterprise", score: 0.9 }`.
-4. **Table (Update Row by ID)** uses the current row's ID to write that result and update its status.
+Stored values follow the column types. Safe conversions are accepted, but unsupported optional values can become empty in workflow writes; public v2 API writes reject invalid values. Inspect writes rather than relying on every bad value producing an error. Deleting rows removes their data; API changes are outside the editor's undo history.
 
-After the run, the table holds the enriched rows. The next run queries them again, and the `status` column keeps the workflow from reprocessing what it already handled. So the table serves as both the queue the workflow pulls from and the record of what it has already done.
+## Paginate large reads
 
+Set **Limit** for a bounded page. A page can end at that count or early when its row data reaches the byte budget, 5 MiB by default for bounded pages. Pass the returned `nextCursor` into **Cursor** until it is `null`. A short page does not establish completion.
 
-## Variations
+Without **Limit**, the Table block requests all matches in one response and rejects results over the fixed 5 MiB row-data budget. Narrow the filter or paginate. This block behavior differs from the public API's default page size.
 
-**Lookup mid-run.** A Table block doesn't have to be the first or last step. Place a Query Rows in the middle to fetch reference data while processing: query a `pricing` table by the order's currency, then let the Agent use the result to compute a total.
+## Inspect a run
 
-**Iterate row by row.** Wrap a Query → process → update cycle in a [Loop block](/workflows/blocks/loop) to handle one row at a time. This runs sequentially, slower than a batch update but useful when each row needs its own multi-step logic. Inside the loop the Agent reads the current row and an Update Row by ID writes its result.
+Use [Logs](/logs-debugging) to inspect the submitted filter, order, row data, returned rows, and affected counts when those details are available. If a query is empty or a write changes nothing, compare its resolved inputs with the table schema and stored values.
 
-**Paginate large reads.** Omit **Limit** to get every matching row in one response; the query fails if the result exceeds 5MB, so narrow with a filter rather than guessing a limit. With a **Limit**, a page can end at the limit *or* early once its rows reach the 5MB budget — so a short page does not mean the end. Pass the returned `nextCursor` back as **Cursor** and keep going while it is non-null. Stop only when `nextCursor` is null; never infer completion from the row count.
+For a lookup during other work, query reference data mid-workflow—for example, a `pricing` table filtered by currency—then pass the result to the next step.
 
-## Inspecting reads and writes
+## Related docs
 
-Every Table block's input and output is recorded in [logs](/logs-debugging). For a Query block, the log shows the filter and order it sent and the rows it received. For an Update or Insert, it shows the row data written and the count affected. When a write does nothing or a query comes back empty, the log is where you check the filter and the data shape before looking anywhere else.
+- [Table block reference](/integrations/table) for operation fields and filter operators
+- [Data flow](/workflows/data-flow) for output references
+- [Workflow columns](/tables/workflow-columns) for work started per row
diff --git a/apps/docs/content/docs/tables/workflow-columns.mdx b/apps/docs/content/docs/tables/workflow-columns.mdx
index 86b9c8c44f4..391602ddcd2 100644
--- a/apps/docs/content/docs/tables/workflow-columns.mdx
+++ b/apps/docs/content/docs/tables/workflow-columns.mdx
@@ -1,155 +1,96 @@
 ---
 title: Workflow columns
-description: A column backed by a workflow that runs once per row, reading chosen columns as inputs and writing its results back into result columns.
+description: Configure per-row enrichments or deployed workflows and write selected results into table columns.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Image } from '@/components/ui/image'
+A workflow group runs a deployed workflow for each eligible row and writes selected outputs into columns on that row. Use it for classification, lead scoring, or other work that has the same shape for each record. A group can fill several columns in one run.
 
-A [table](/tables) is a grid of typed columns. Usually you type a column's values in. A **workflow column** is different: its values come from a [workflow](/workflows) that runs once per row. For each row, the workflow reads the columns you choose as input, runs its blocks, and writes its results back into columns on that same row.
+## Choose an enrichment or workflow
 
-This is what makes a table active. Instead of running a workflow by hand and pasting the results in, you attach the workflow to the table and it fills each row on its own — a bit like a spreadsheet macro that runs on every row, except each step is a full workflow.
+| Group | Use it for | Setup |
+| --- | --- | --- |
+| **Enrichment** | A built-in lookup maintained by Sim | Select it in **Enrichments**, map its inputs, and name its output columns. |
+| **Workflow** | Per-row logic you build | Create and deploy a workflow, then configure its inputs and outputs on the table. |
 
-The running example is a table of AI startups, `ai_startup_customers`. The company is typed in; three workflow groups fill everything else:
+Enrichments try available data providers in order. **Not found** means the lookup completed without a match; it does not mean every provider error is a no-match result.
 
-<Image
-  src="/static/tables/workflow-columns/table-groups.png"
-  alt="The ai_startup_customers table with three workflow groups — Company Domain, Company Info, and Lead Score Enrichment — filling their output columns per row, 21 rows running"
-  width={900}
-  height={467}
-/>
+For aggregation across many rows, a one-off transform, or a decision tied to an incoming request, use a [standalone workflow](/workflows). To read table data during that work, see [Using tables in workflows](/tables/using-in-workflows).
 
-- **Company Domain** finds each company's `domain`.
-- **Company Info** reads the domain and fills `employee_count` and `description`.
-- **Lead Score Enrichment** runs the lead-scoring workflow and writes `lead_score`, `priority`, and `score_reasoning`.
+## Configure a workflow group
 
-Each group's header spans the columns it owns, every row has a run button (▷), and the toolbar shows the work in flight: here, **21 running**, with **Stop all** beside it.
+1. Build a workflow with the [Start input fields](/workflows/triggers/start) it needs, then deploy it. The picker uses deployed workflows and their output definitions.
+2. In the table, select **New column → Workflow**.
+3. In **Configure workflow**, select **Workflow**, then choose **Output columns**. A single group can write several selected outputs.
+4. Open **Show additional fields → Workflow inputs**. Expand each Start field and choose its source **Column**.
+5. Leave **Auto-run workflow** off for manual runs, or enable it and select at least one **Run after** column.
+6. Select **Save**. Rename the created output columns if needed.
 
-```
-domain            │ employee_count │ lead_score │ priority
-──────────────────┼────────────────┼────────────┼─────────
-openai.com        │ 5K-10K         │ 75         │ Warm
-gominimal.ai      │ Not found      │ 92         │ Hot
-genspark.net      │ 51-250         │ 20         │ Cold
-```
-
-## Two kinds of groups
-
-The unit you configure is a **group**: something that runs once per row, fed by input columns, writing output columns. There are two kinds, and the **+ New column** menu offers both — **Enrichments** above the plain column types, **Workflow** below them. They share all the run machinery that follows.
-
-<Image
-  src="/static/tables/workflow-columns/new-column-menu.png"
-  alt="The New column menu: Enrichments at the top, the plain column types, and Workflow at the bottom"
-  width={340}
-  height={351}
-  className="mx-auto h-auto w-full max-w-[340px]"
-/>
-
-### Enrichments
-
-An **enrichment** is a built-in lookup that Sim provides and maintains — browse the **Enrichments** panel for what's available. Pick one, bind its inputs to columns, and name the columns its outputs should fill; there's no workflow to build. Under the hood an enrichment tries a cascade of data providers in order, which is why a cell can come back **Not found**: none of the available providers returned a match.
-
-### Workflow groups
-
-A **workflow group** runs one of your own [workflows](/workflows) per row — use it when the per-row work is something you've built, like the lead scorer. Its **Configure workflow** panel holds everything that defines it, with a preview of the workflow it will run:
+Mapped column values populate the named Start fields. The workflow also receives row context: the row's other non-own-output cells, headers, row ID, table ID/name, and timestamp. When no input mappings are configured, non-own-output columns also supply the input values. Mappings do not restrict which row data the workflow can read.
 
-<Image
-  src="/static/tables/workflow-columns/configure-workflow.png"
-  alt="The Configure workflow panel for Lead Score Enrichment: a preview of the LeadScorer workflow, the workflow picker, three output columns selected, Auto-run on, and six Run after dependencies"
-  width={400}
-  height={634}
-  className="mx-auto h-auto w-full max-w-[360px]"
-/>
+The group writes selected outputs automatically; unselected outputs are not added as group result columns. Table blocks inside the workflow can make additional changes to rows.
 
-- **Workflow** picks which workflow runs per row; here, *Lead Score Enrichment*.
-- **Add column inputs** maps columns to the workflow's inputs, which arrive at its [Start](/workflows/triggers/start) trigger.
-- **Output columns** picks which workflow outputs to write back; here, 3 are selected.
-- **Auto-run workflow** and **Run after** control when rows run (both below).
+### Dependencies
 
-One group can produce several result columns from a single run per row: Lead Score Enrichment fills `lead_score`, `priority`, and `score_reasoning` together.
+**Run after** offers upstream columns to the group's left. It governs automatic runs and manual runs when **Auto-run workflow** is enabled. With auto-run off, manual runs bypass dependency checks.
 
-## How groups run
+When dependencies are enforced, values must be nonempty: `null`, missing values, empty strings, and empty arrays are unmet. A Boolean dependency must be `true`; `false` leaves the group waiting.
 
-Everything from here applies to both kinds. A group's configuration is a set of bindings: each input is bound to a column, and each output is bound to the column name it writes. Here, Company Info's required `Company domain` input reads the `domain` column, and its outputs write `employee_count_0` and `description`:
+Dependencies can be ordinary columns or another group's output. For example:
 
-<Image
-  src="/static/tables/workflow-columns/column-mapping.png"
-  alt="A group's bindings: the required Company domain input bound to the domain column, and the employee count and description outputs bound to their column names"
-  width={380}
-  height={499}
-  className="mx-auto h-auto w-full max-w-[380px]"
-/>
-
-When a group runs a row, the bound column values become its inputs; it only sees the columns you mapped, the rest of the row is untouched, and inputs are read-only during the run. Every output you selected is written to its column, and outputs you didn't select are discarded.
+```text
+Company Domain → domain
+Company Info waits for domain → employee_count, description
+Lead Score waits for required company information → lead_score, priority, score_reasoning
+```
 
-### Run after
+Each row becomes eligible independently. When dependencies are enforced, an enrichment with no match for a required column leaves its downstream group **Waiting** until the required values or dependencies change.
 
-**Run after** is the set of columns that must be filled before the group runs on a row. Company Info runs after `domain`: a row with an empty `domain` waits, and the moment Company Domain fills it, that row becomes eligible. Lead Score Enrichment runs after the info columns, the six dependencies in the panel above.
+## Run rows
 
-A dependency can be a typed column or another group's output column. That second case is what makes cascades work (below). At least one dependency is required when auto-run is on.
+New groups have auto-run off. With it enabled, eligible rows run without a manual action.
 
-### Auto-run
+For one row, use the row or cell's run control. The group header's run menu offers:
 
-**Auto-run** decides whether a group fires on its own. With auto-run on, a group runs a row as soon as that row's Run-after columns are filled, no click needed; that's how 21 rows end up running at once in the example. With it off, you trigger it yourself.
+| Control | Scope |
+| --- | --- |
+| **Run N selected rows** | The explicitly selected rows. |
+| **Run empty rows** | Unrun or failed/incomplete work eligible for the selected run mode. |
+| **Run 10 empty rows** / **Run 1,000 empty rows** | A smaller batch of eligible incomplete rows. |
+| **Run all rows** | All rows in scope, including completed work. |
 
-You trigger a group by hand from its column header menu:
+Table-wide controls honor the active filter and use **filtered rows** in their labels when a filter applies. **Run empty rows** does not necessarily rerun a completed row just because its result is blank: use **Run all rows** or **Re-run cell** for completed no-match or no-output work.
 
-- **Run this row** runs the one row.
-- **Run all rows** runs every row, and re-runs rows that already finished.
-- **Run empty rows** runs only rows whose output columns are still empty.
-- **Run selected rows** runs the rows you've checked.
+### Automatic reruns
 
-Auto-run only ever runs rows it hasn't attempted yet. To re-run a single row, use **Re-run cell** from the cell's menu; to re-run everything, use **Run all rows**.
+Auto-run initially skips completed, errored, or cancelled attempts; errors do not retry continuously without a change. Changing a satisfied dependency or clearing an output can re-arm automatic work downstream. Changes during execution can cancel or restart dependent work and incur additional run cost.
 
-### Execution status
+Normal table-run coordination avoids overlapping group work on the same row, but it is not a guarantee against edits, independent workflow writes, or degraded coordination. Do not use the run controls as an atomic row-claim mechanism.
 
-While a group works a row, its output cells show their state instead of a value:
+## Execution states
 
 | State | Meaning |
 | --- | --- |
-| **Pending** | Waiting on a Run-after column that isn't filled yet. |
-| **Queued** | Eligible and waiting to start. |
-| **Running** | The workflow is executing for this row. |
-| **Error** | A block failed. The cell links to which block and why. |
-| **Cancelled** | The run was stopped before it finished. |
-| **Not found** | An enrichment finished but matched nothing for this row. |
-
-When a value arrives, it replaces the badge, and cells that finish stay filled even while other columns on the row are still running. You can see this in the example table: most rows are fully scored, while a few show **Not found** where an enrichment came up empty. The lead scorer still ran on those rows, working with what it had.
-
-<Callout type="info">
-On error, the row stays in the **Error** state. Auto-run skips errored rows, so a failure doesn't loop. To retry, fix the input and re-run the cell. A row is only ever worked by one run at a time, so re-running doesn't race.
-</Callout>
-
-### Inspecting a row's run
-
-Every value in a workflow column comes from a real workflow run, and each one is inspectable. Open a cell's menu to act on that row:
-
-<Image
-  src="/static/tables/workflow-columns/cell-menu.png"
-  alt="A lead_score cell's menu: View execution, Re-run cell, insert and duplicate row actions, and Delete row"
-  width={800}
-  height={369}
-  className="mx-auto h-auto w-full max-w-xl"
-/>
-
-**View execution** opens the run's trace: each block with its status, timing, and credit cost, the same view as the [Logs](/logs-debugging) page. Here, the row's score came from a 1.86s run of the LeadScorer workflow:
+| **Waiting** | Required dependencies are unmet. |
+| **Pending** | Waiting for earlier workflow work or paused input. |
+| **Queued** | Eligible and waiting for an execution slot. |
+| **Running** | The current block or group is executing. |
+| **Error** | Execution failed; inspect the run for its error. |
+| **Cancelled** | The run stopped before completing. |
+| **Not found** | An enrichment completed without a match. |
+| **No output** | Workflow work completed without a value for this output. |
 
-<Image
-  src="/static/tables/workflow-columns/row-trace.png"
-  alt="The Log Details trace for one row's run: Workflow Execution at 1.86s with Start and LeadScorer spans, marked Success"
-  width={650}
-  height={386}
-  className="mx-auto h-auto w-full max-w-xl"
-/>
+A produced value replaces its status badge. Completed output cells can remain filled while other steps on the row are still running.
 
-**Re-run cell** runs the group again for just that row, replacing its values when the run finishes.
+The running-count control shows active work. Select **Stop all** to cancel active table runs, including work outside the current filter; completed values remain.
 
-## Cascades
+## Inspect and retry a run
 
-Because a group can run after another group's output column, you can chain groups across the table — enrichments and workflow groups freely mixed. The example is a three-stage **cascade**: Company Domain fills `domain` from the company name, Company Info runs after `domain` and fills the info columns, and the Lead Score workflow group runs after those and writes the score. Each row advances through the stages independently: the moment its own Run-after columns are filled, it becomes eligible for the next group. That's why some rows in the screenshot are fully scored while others are still mid-pipeline.
+Open a cell's menu and select **View execution** to inspect available block inputs, outputs, timing, status, and costs in its [run trace](/logs-debugging). On an error, check the resolved inputs and the failing step, then correct the configuration or data.
 
-## When to use a workflow column
+Select **Re-run cell** to run the group again for that row. Its selected outputs update as results arrive. For a wider retry, choose the appropriate group-header action and check its filter and row scope before starting.
 
-Reach for a workflow column when you have a row-by-row job: enrich each record, classify each entry, score each lead. The work is the same shape on every row, and you want the results to live next to the source data.
+## Related docs
 
-Use a [workflow on its own](/workflows) instead when the job isn't per-row: a one-off transform, an aggregation across many rows, or a real-time decision tied to a single request. To pull table data into a workflow rather than push workflow results into a table, see [using tables in workflows](/tables/using-in-workflows).
+- [Using tables in workflows](/tables/using-in-workflows) for Table block operations
+- [Start trigger](/workflows/triggers/start) for input fields
+- [Logs](/logs-debugging) for tracing a failed row run
diff --git a/apps/docs/content/docs/workflows/blocks/agent.mdx b/apps/docs/content/docs/workflows/blocks/agent.mdx
index c7a98cd9863..154f29e2492 100644
--- a/apps/docs/content/docs/workflows/blocks/agent.mdx
+++ b/apps/docs/content/docs/workflows/blocks/agent.mdx
@@ -1,17 +1,24 @@
 ---
 title: Agent
-description: The Agent block runs a model over your inputs to reason, call tools, and return text or structured output.
+description: Run a model with context and tools, then return text or structured fields.
 ---
 
 import { BlockPreview, WorkflowPreview, CLASSIFY_WORKFLOW } from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
 
-The **Agent block** runs a model inside a workflow. You give it instructions, context, and tools; the model reasons over the input, calls tools as needed, and returns plain text or structured JSON that later blocks read by reference. Most workflows are built around one or more Agent blocks.
+The **Agent block** runs a model inside a workflow. You give it instructions, context, and tools; the model reasons over the input, calls tools as needed, and returns plain text or structured JSON that later blocks read by reference.
 
-An *agent* and an *Agent block* are related but distinct. An agent is a whole workflow that reasons and acts on its own; an Agent block is one reasoning step inside it. The simplest agent is a single Agent block with tools, and larger ones wire several together with other blocks. See [Agents](/agents).
+An *agent* and an *Agent block* are related but distinct. A workflow agent is a workflow that reasons and acts on its own; an Agent block is one reasoning step inside it. The simplest agent is a single Agent block with tools, and larger ones wire several together with other blocks. See [Agents](/agents).
 
 <BlockPreview type="agent" />
 
+## Classify a message
+
+A workflow that reads an incoming customer message and classifies it:
+
+<WorkflowPreview workflow={CLASSIFY_WORKFLOW} />
+
+The Agent reads the message from Start with `<start.input>` and requests structured category and urgency fields that later blocks read as `<agent.category>` and `<agent.urgency>`.
+
 ## Configuration
 
 ### Messages
@@ -25,19 +32,19 @@ Answer in two sentences, cite the doc you used, and never guess a price.
 
 ### Model
 
-The model that runs the step. Defaults to `claude-sonnet-5-5`. Type or pick any model from OpenAI, Anthropic, Google, xAI, Groq, Cerebras, DeepSeek, Azure, AWS Bedrock, Google Vertex, or OpenRouter, or a local model through Ollama or VLLM.
+The model that runs the step. Defaults to `claude-sonnet-5-5`. Type or pick any model from OpenAI, Anthropic, Google, xAI, Groq, Cerebras, DeepSeek, Azure, AWS Bedrock, Google Vertex, or OpenRouter, or a local model through Ollama or vLLM.
 
 For a custom cloud deployment, enter its provider prefix and model ID: `azure/my-deployment`, `azure-anthropic/my-deployment`, `bedrock/my-inference-profile`, or `vertex/my-gemini-model`. The prefix selects the provider and shows its credential fields even when the ID is absent from the catalog. Bedrock accepts full inference profile ARNs after `bedrock/`; Vertex uses the Gemini API and accepts Google model resource names. The deployment must support the selected provider's API. Custom IDs have no catalog pricing or token limits.
 
 Ollama Cloud, OpenRouter, Fireworks, Together AI, Baseten, Ollama, vLLM, and LiteLLM load their available models from the configured provider. New models appear through that discovery without a Sim catalog release. You can also enter a namespaced ID directly, such as `ollama-cloud/deepseek-v4.1-flash`, `openrouter/provider/model`, or `ollama/my-local-model`. Provider prefixes are case-insensitive; the model ID after the prefix keeps its original casing.
 
-### Nebius Token Factory
+#### Nebius Token Factory
 
 Select a model beginning with `nebius/` to run an open model through Nebius Token Factory. Sim includes DeepSeek, Kimi, Qwen, and other models in the [Nebius catalog](https://www.sim.ai/models/nebius).
 
 Bring your own Nebius Token Factory API key. On Sim Cloud, a workspace admin can add it under **Workspace settings → BYOK → Nebius**. On self-hosted Sim, provide the key in the Agent block's **API Key** field, using a [secret reference](/platform/credentials). Model features such as image input and structured outputs depend on the selected model.
 
-### Jev evaluation models
+#### Jev evaluation models
 
 Select `jev-latest` from TypeSafe in the Agent model selector. Hosted Sim supplies a key and bills model usage through the normal credit system; workspace or organization BYOK keys override the hosted key without model charges. Self-hosted users enter their TypeSafe key in the block. Use `jev-1.13.0` to pin a version or `jev-preview` to follow preview releases. These models use **State** and **Questions** in place of conversational messages. State accepts text or a reference to a JSON object or array. Questions is a JSON object keyed by the answer names you want:
 
@@ -63,14 +70,14 @@ Jev evaluates the supplied state in one request. Chat messages, files, tools, sk
 
 ### Files
 
-Files for the model to read: images for a vision-capable model, or documents for text. Upload them on the block, or pass a file from an earlier block, such as an upload trigger or an [API](/workflows/blocks/api) response, with a connection tag.
+Files for the model to read: images for a vision-capable model, or documents for text. Upload them on the block, or pass a file from an earlier block, such as an upload trigger or a file-producing integration, with a connection tag.
 
 ### Tools
 
 Capabilities the agent can call while it runs: search a knowledge base, send a Slack message, run a [Function](/workflows/blocks/function), call any of the [integrations](/integrations), or use a [custom tool](/agents/custom-tools) or [MCP server](/agents/mcp) you've added. The model decides which to call and when. (For where tools come from and when to reach for which, see [Agents](/agents).) Expand a tool to set its **Permission Mode**:
 
 - **Auto.** The model calls it when the context warrants.
-- **Force.** The model must call it on every run.
+- **Force.** Request a tool call on models that support forced tool use. This does not guarantee that the tool succeeds; use a fixed workflow step when an action must be attempted on that path.
 - **None.** The tool is hidden from the model, which disables it without removing it from the block.
 
 To pick the mode when the workflow runs, use the switch next to Permission Mode to change it to a variable, then enter a reference such as `<start.toolMode>`. The value must resolve to `auto`, `force`, or `none`. Any other value stops the run before the model is called.
@@ -108,9 +115,13 @@ With durable tool history enabled, retries and fallback models continue the same
 
 A recorded terminal outcome is kept even when its stored details become unavailable; the Agent does not repeat that action merely to recover the missing details. A call whose outcome was not recorded can execute again, including when an external action succeeded just before a failure. Use tools that safely handle repeated requests for actions that must not happen twice. If durable history is disabled or persistence is unavailable, saved-progress recovery is not guaranteed. This does not restart crashed workflows, override cancellation, or retry failures marked nonretryable. A failure after streaming output has started is not restarted on another model.
 
-### Response Format
+### Response format
+
+Set **Response Format** to a JSON Schema when later blocks need named fields. Native schema enforcement depends on the provider; other models receive schema instructions. A successfully parsed structured result exposes fields directly, such as `<agent.sentiment>`. Without a response format, read plain text from `<agent.content>`.
+
+Malformed JSON can fall back to plain text with `_responseFormatWarning`. Sim does not perform a general post-parse schema check on every provider result, so validate fields downstream before consequential actions.
 
-Give the agent a JSON Schema to force structured output. The response is constrained to match the schema, and each field becomes its own output you read by name, like `<agent.sentiment>`. Without a response format, the agent returns plain text in `content`.
+Avoid schema fields named `model`, `tokens`, `toolCalls`, `providerTiming`, or `cost`. Sim's standard metadata overwrites those fields after parsing, even when a metadata value is absent.
 
 ```json
 {
@@ -121,24 +132,25 @@ Give the agent a JSON Schema to force structured output. The response is constra
       "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
       "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
     },
-    "required": ["sentiment", "confidence"]
+    "required": ["sentiment", "confidence"],
+    "additionalProperties": false
   }
 }
 ```
 
-### Advanced
+### Advanced settings
 
 Some settings live under advanced, or appear only for models that support them:
 
-- **Temperature.** How varied the output is. Stay low (0–0.3) when you need accuracy and repeatability, middle (around 0.5) for everyday work, higher (0.7+) when you want creative variety.
+- **Temperature.** Controls variation on models that support it. Lower values tend to reduce variation; test accuracy on representative inputs rather than treating temperature as a factuality guarantee.
 - **Max output tokens.** Caps the response length. Defaults to the model's full limit.
-- **Reasoning effort / Thinking level.** For models with extended reasoning, how much the model thinks before answering. Higher is more thorough but slower and costs more tokens.
-- **Prompt caching.** For Anthropic Claude models, reuses the system prompt and tool definitions between runs instead of re-reading them every time. Cached input costs a tenth of the normal rate, but writing the cache costs 1.25x, so leave it off for one-off runs and turn it on when the same agent runs repeatedly. The cache covers a prefix only if it reaches 1,024 tokens (2,048 on Haiku) — below that Anthropic ignores it and nothing changes. Entries expire after five minutes of no use.
+- **Reasoning effort / Thinking level.** Controls supported models' reasoning budget. Higher settings can increase latency and token use; evaluate the result on your task.
+- **Prompt caching.** Reuses a stable system prompt and tool definitions on supported Claude models. Sim uses a five-minute cache. Cache-write pricing, read discounts, and minimum prefix length depend on the model; check [Anthropic's current requirements](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations). Enable it for repeated runs sharing a prefix; a one-off run can pay a write premium without a later cache hit.
 - **API key.** Your key for the chosen provider. Hidden when hosted Sim supplies a key for the selected model, including Jev.
 - **Fallback models.** An ordered list of up to five models to try when the request to the selected model fails, whether the provider is overloaded, rate-limited, or down. Sim tries the 2nd choice, then the 3rd, and so on, once each, and `<agent.model>` reports the model that answered. On hosted Sim, hosted models use your workspace's BYOK or platform credentials; local and self-hosted installations may still require a key. A model that needs its own key takes it from a workspace environment variable you pick on the row; a model on the same provider as the selected model reuses the block's key. A stored row key stops applying when its key field is hidden. Providers that require family-specific credentials, such as Vertex, can only be fallbacks for a selected model of the same family. The Auto model cannot be a fallback. A fallback runs with the selected model's settings where its provider accepts them: temperature and max output tokens are clamped to the fallback's limits, and when the fallback has a reasoning effort, thinking level, or verbosity setting that the selected model's value does not fit, the row shows that field so you can pick a value for it; leave it empty and the provider's default applies.
 - **Retry on fail.** Retries the selected model after a failure, up to a maximum number of tries with a wait between them. When its tries run out, the fallback models are tried in order, once each, with no wait before the first of them. A fallback is never retried. See [Retries and fallbacks](#retries-and-fallbacks) for how recorded tool results are reused and when a tool can execute again.
 
-OpenAI and Gemini cache automatically at no extra cost and need no setting; their discount is already reflected in what you are charged.
+Eligible OpenAI and Gemini models can cache repeated input without a Sim setting. Eligibility, minimum input length, and read/write pricing depend on the model; automatic caching does not always mean free cache writes. See [OpenAI prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching) and [Gemini context caching](https://ai.google.dev/gemini-api/docs/caching).
 
 ## Outputs
 
@@ -146,17 +158,21 @@ After the agent runs, later blocks read its result by name:
 
 | Output | What it is |
 | --- | --- |
-| `<agent.content>` | The response: text, or the structured object when a response format is set |
+| `<agent.content>` | Plain-text response without Response Format; do not rely on it containing the parsed structured object |
 | `<agent.tokens>` | Token usage, an object `{ input, output, total }` |
 | `<agent.toolCalls>` | The tools the agent called, with their inputs and results |
 | `<agent.model>` | The model that ran the step |
-| `<agent.cost>` | Estimated cost of the call |
+| `<agent.cost>` | Estimated cost in USD, as an object with `input`, `output`, and `total`; read `<agent.cost.total>` for the total |
 
-When a response format is set, its fields are readable directly, like `<agent.sentiment>`.
+The cost object can include additional fields such as tool costs or pricing. The Logs UI and run-resource API use credits. See [Costs](/platform/costs) for units and billing behavior.
+
+Response-format fields are readable directly, like `<agent.sentiment>`, subject to the [metadata naming guidance](#response-format).
 
 ## Streamed thinking and tool calls
 
-While an agent runs, Sim can stream its thinking and tool lifecycle live — the canvas terminal always shows them, and a [deployed chat](/workflows/deployment/agent-events) shows them when its **Include thinking** setting and the client's protocol opt-in agree. What actually streams depends on the model: models marked with full deltas or summaries stream thinking when a Thinking level or Reasoning effort is set (DeepSeek reasoner models always reason); a model marked "Not streamed" thinks internally but its provider withholds the text.
+While an agent runs, Sim can stream thinking and tool lifecycle events to the workflow builder terminal. In a [deployed chat](/workflows/deployment/agent-events), thinking requires **Include thinking**, tool events require **Include tool calls**, and each requires the client's protocol opt-in. The policies are independent.
+
+What actually streams depends on the model: models marked with full deltas or summaries stream thinking when a Thinking level or Reasoning effort is set (DeepSeek reasoner models always reason); a model marked "Not streamed" thinks internally but its provider withholds the text.
 
 {/* agent-stream-capabilities:begin — generated by `bun run generate:agent-stream-docs`; do not edit between markers */}
 
@@ -182,23 +198,13 @@ Live tool-call chips stream for **OpenAI, Anthropic, Azure Anthropic, Google, Ve
 
 {/* agent-stream-capabilities:end */}
 
-## Example
-
-A workflow that reads an incoming customer message and classifies it:
-
-<WorkflowPreview workflow={CLASSIFY_WORKFLOW} />
-
-The Agent reads the message from Start with `<start.input>` and returns a result that later blocks read as `<agent.content>`.
+## Provider and failure details
 
-## Best Practices
+Anthropic models use their catalog max output token limit when no override is set. Large non-streaming requests can use internal streaming to avoid SDK timeouts; this does not turn the client response into a streamed run. Custom Ollama/vLLM models need a compatible configured endpoint. Fallback logs show which model answered and which choices failed.
 
-- **Write a clear system message.** Define the agent's role, tone, and limits. Specific instructions produce more reliable output than a vague prompt.
-- **Match the model and temperature to the task.** Use a stronger model and lower temperature (0–0.3) for accuracy; raise temperature for creative or varied output.
-- **Give the agent only the tools it needs.** Too many tools dilute its choices. For jobs that don't overlap, use a second Agent block instead of overloading one.
-- **Use a response format when a downstream block needs specific fields.** It guarantees the shape, and you read each field as `<agent.field>`.
+## Related docs
 
-<FAQ items={[
-  { question: "How does max output tokens work with Anthropic models?", answer: "The Agent block uses each Anthropic model's full max output token limit by default (for example, 64,000 tokens). You can override this with the Max Output Tokens setting. For non-streaming requests that exceed the SDK's internal threshold, the provider automatically uses internal streaming to avoid timeouts." },
-  { question: "Can I use the Agent block with a custom or self-hosted model?", answer: "Yes. Use any Ollama or VLLM-compatible model by typing the model name directly into the model combobox, as long as it exposes a compatible API endpoint." },
-  { question: "What happens when my model's provider is down?", answer: "Add fallback models under Additional fields. When the request to the selected model fails, Sim tries the 2nd choice, then the 3rd, in order, and the block succeeds if any of them answers. The log detail shows the model that answered and the models it fell back from. Turn on Retry on fail as well to give the selected model a few tries first; the fallbacks are tried once each after its last try fails." },
-]} />
+- [Agents](/agents)
+- [Agent skills](/agents/skills)
+- [Workflow streaming](/workflows/deployment/agent-events)
+- [Condition](/workflows/blocks/condition)
diff --git a/apps/docs/content/docs/workflows/blocks/api.mdx b/apps/docs/content/docs/workflows/blocks/api.mdx
index c8bde046c97..a2fcbe36f31 100644
--- a/apps/docs/content/docs/workflows/blocks/api.mdx
+++ b/apps/docs/content/docs/workflows/blocks/api.mdx
@@ -1,76 +1,67 @@
 ---
 title: API
-description: The API block makes an HTTP request to an external service and returns the response.
+description: Send an HTTP request and use its response in later steps.
 ---
 
+import { Callout } from 'fumadocs-ui/components/callout'
 import { BlockPreview, WorkflowPreview, API_FETCH_WORKFLOW } from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
 
-The **API block** makes an HTTP request to a URL and returns the response. Use it to call any REST API: fetch data, create a record, or trigger an external endpoint.
+The **API block** calls an HTTP endpoint. Use it to fetch data, create a record, or invoke an external service.
 
 <BlockPreview type="api" />
 
-## Configuration
-
-### URL
-
-The endpoint to call. Type a static URL, or insert a [connection tag](/workflows/connections) to build it from an earlier output, like `https://api.example.com/users/<start.userId>`.
-
-### Method
+## Fetch and summarize data
 
-The HTTP method: **GET**, **POST**, **PUT**, **DELETE**, or **PATCH**. Defaults to GET.
-
-### Query Params
-
-Key-value pairs appended to the URL as a query string. `apiKey` and `limit` become `?apiKey=…&limit=10`.
+<WorkflowPreview workflow={API_FETCH_WORKFLOW} />
 
-### Headers
+Set **URL** to `https://api.example.com/users/<start.input>` and **Method** to **GET**. The next Agent reads `<api.data>`. Replace the example endpoint and supply its required authentication.
 
-Key-value request headers, such as `Content-Type: application/json` or `Authorization: Bearer <secret>`. Standard headers like `User-Agent` and `Accept` are added automatically, and your values override them.
+## Configuration
 
-### Body
+| Field | Behavior |
+| --- | --- |
+| **URL** | Static URL or a URL containing [references](/workflows/connections), such as `https://api.example.com/users/<start.userId>`. |
+| **Method** | **GET** (default), **POST**, **PUT**, **DELETE**, or **PATCH**. |
+| **Query Params** | Key-value pairs appended as URL query parameters. |
+| **Headers** | Request headers, such as `Authorization: Bearer {{API_KEY}}`. Your values override automatic User-Agent, Accept, Cache-Control, and other defaults. |
+| **Body** | Request payload. JSON is the default for POST, PUT, and PATCH; other supported Content-Type values can change body encoding. |
 
-The request payload for POST, PUT, and PATCH, sent as JSON. Type it directly, or pull it from an earlier output with a connection tag.
+Keep keys and proxy credentials in [secrets](/platform/credentials), referenced with `{{NAME}}`.
 
-### Advanced
+### Advanced settings
 
-- **Timeout (ms).** How long to wait before giving up. Defaults to 300000 (5 minutes), up to 600000 (10 minutes).
-- **Retries.** Number of retry attempts on timeouts, `429` responses, and `5xx` errors. Defaults to 0.
-- **Retry delay / Max retry delay (ms).** The exponential-backoff bounds used between retries.
-- **Retry non-idempotent methods.** Off by default, so POST and PATCH are not retried, which avoids duplicate writes. Turn it on only when a repeated request is safe.
-- **Proxy URL.** Optional `http://` proxy the request egresses through, such as a residential proxy for targets that block datacenter IPs. The proxy host must be publicly reachable, and only the `http://` scheme is supported (an `https://` target still tunnels through it securely). Keep proxy credentials in an environment variable and reference it as `{{PROXY_URL}}` rather than typing them into the field.
+| Field | Default and limit |
+| --- | --- |
+| **Timeout (ms)** | 300,000 ms (5 minutes); maximum 600,000 ms (10 minutes). |
+| **Retries** | `0`. When enabled, retry network failures, timeouts, `429`, and `5xx` responses; not ordinary `400` or `404` errors. |
+| **Retry delay (ms)** | `500`; exponential backoff starts here. |
+| **Max retry delay (ms)** | `30,000`; caps the backoff delay. |
+| **Retry non-idempotent methods** | Off. Enable POST/PATCH retries only when repeated requests are safe. |
+| **Send credentials on cross-origin redirects** | On by default for compatibility. Disable it when a redirect to a different scheme, host, or port should not receive the same credential-bearing headers. |
+| **Proxy URL** | Optional publicly reachable `http://` proxy, such as `{{PROXY_URL}}`. An HTTPS target still uses a secure tunnel through the HTTP proxy. |
+
+<Callout type="warn">
+Retries can repeat an external write. Use idempotency support from the destination API before enabling retries for POST or PATCH.
+</Callout>
 
 ## Outputs
 
-After the request completes, later blocks read its result by name:
-
-| Output | What it is |
+| Reference | Value |
 | --- | --- |
-| `<api.data>` | The response body, parsed as an object for JSON or returned as text otherwise |
-| `<api.status>` | The HTTP status code, like `200` or `404` |
-| `<api.headers>` | The response headers, as an object |
-
-Branch on the result by reading `<api.status>` in a [Condition](/workflows/blocks/condition) block.
+| `<api.data>` | Response body: parsed JSON, or text for other content types |
+| `<api.status>` | HTTP status code on a successful response |
+| `<api.headers>` | Response headers |
 
-## Example
-
-A workflow that calls an HTTP endpoint and summarizes the response:
-
-<WorkflowPreview workflow={API_FETCH_WORKFLOW} />
+Use narrow references such as `<api.data.id>` when a later step needs only one field. The HTTP response itself is limited to 10 MiB; selecting a narrow field does not bypass that fetch-time limit.
 
-The API block builds its URL from the Start input, fetches the data, and the Agent reads the response as `<api.data>`.
+## Handle failures
 
-## Best Practices
+Non-2xx responses, network failures, and timeouts fail the API block. Connect its error port to handle them. Without an error path, an unhandled failure stops the run.
 
-{/* Keep the error-path guidance below prominent: fewer than 1% of deployed workflows connect an error port (platform data, 2026-06) — under-adopted, not under-needed. */}
+A normal downstream Condition on `<api.status>` can distinguish successful responses, such as `200` and `201`; it does not receive a failed `404` response on the normal path.
 
-- **Keep secrets in environment variables.** Reference them with `{{VAR}}` in the URL or headers; never hardcode keys.
-- **Handle failures.** Read `<api.status>` and branch on it with a [Condition](/workflows/blocks/condition), or connect the error path for network failures and timeouts.
-- **Set retries for flaky endpoints.** Use the Advanced retry settings for idempotent calls. Leave POST and PATCH off unless a repeated request is safe.
-- **Reference only the field you need.** Pull `<api.data.id>` rather than the whole `<api.data>` when the response is large.
+## Related docs
 
-<FAQ items={[
-  { question: "Which HTTP errors trigger automatic retries?", answer: "Retries are attempted for network and connection failures, timeouts, rate-limit responses (HTTP 429), and server errors (5xx). Client errors like 400 or 404 are not retried." },
-  { question: "How does retry backoff work?", answer: "Retries use exponential backoff starting from the configured retry delay (default 500ms). Each subsequent retry doubles the delay, up to the maximum retry delay (default 30,000ms)." },
-  { question: "What headers are included automatically?", answer: "Standard headers such as User-Agent, Accept, and Cache-Control are added automatically. Any custom headers you configure are merged with these defaults, and your values override automatic headers with the same name." },
-]} />
+- [Connections and error paths](/workflows/connections)
+- [Webhook](/workflows/blocks/webhook)
+- [Condition](/workflows/blocks/condition)
diff --git a/apps/docs/content/docs/workflows/blocks/condition.mdx b/apps/docs/content/docs/workflows/blocks/condition.mdx
index b55989992a9..5e7c5405281 100644
--- a/apps/docs/content/docs/workflows/blocks/condition.mdx
+++ b/apps/docs/content/docs/workflows/blocks/condition.mdx
@@ -1,29 +1,24 @@
 ---
 title: Condition
-description: The Condition block branches a workflow on boolean expressions, with no model call.
+description: Choose a branch by evaluating JavaScript boolean expressions.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import {
-  BlockPreview,
-  WorkflowPreview,
-  CONDITION_MODERATE_WORKFLOW,
-  CONDITION_ONBOARD_WORKFLOW,
-  CONDITION_ROUTE_WORKFLOW,
-} from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
+import { BlockPreview, WorkflowPreview, CONDITION_ROUTE_WORKFLOW, CONDITION_MODERATE_WORKFLOW } from '@/components/workflow-preview'
 
-The **Condition block** branches a workflow on boolean expressions. It checks each branch in order and runs the path of the first one that is true, with no model call. When you want a model to decide the route, use a [Router](/workflows/blocks/router) instead.
+The **Condition block** checks branches in order and follows the first true expression. It makes no model call. Use a [Router](/workflows/blocks/router) when the decision depends on understanding intent or unstructured text.
 
 <BlockPreview type="condition" />
 
-## Configuration
+## Route by priority
+
+<WorkflowPreview workflow={CONDITION_ROUTE_WORKFLOW} />
 
-### Conditions
+Check `<start.priority> === 'high'` in the **if** branch. Connect that port to escalation and **else** to a standard reply.
 
-A list of branches: an **if**, any number of **else if** rows, and a final **else**. Each branch holds a JavaScript expression that evaluates to true or false, and connects to its own path. Sim checks them top to bottom and takes the first branch that is true; the **else** branch runs when none match.
+## Configuration
 
-Reference an earlier output inside an expression with a [connection tag](/workflows/connections):
+**Conditions** contains an **if** branch, optional **else if** branches, and **else**. Each expression uses JavaScript operators and methods and connects to its own path. Put specific checks before general ones: the first match wins.
 
 ```javascript
 <agent.score> > 75
@@ -31,7 +26,9 @@ Reference an earlier output inside an expression with a [connection tag](/workfl
 <user.email>.endsWith('@company.com') && <user.plan> === 'pro'
 ```
 
-Read an [environment variable](/workflows/variables#environment-variables) with `{{KEY}}`:
+Comparisons, logical operators, string/array methods, math, and Date comparisons work in expressions. Move lengthy logic to a [Function](/workflows/blocks/function) and branch on its result.
+
+[Environment variables](/workflows/variables#environment-variables) use `{{KEY}}`:
 
 ```javascript
 {{MAX_RETRIES}} === 3
@@ -39,48 +36,34 @@ Read an [environment variable](/workflows/variables#environment-variables) with
 {{TIER}} === 'pro'
 ```
 
-Numbers, booleans, and `null` compare as literals. Every other value is bound as a string, so an apostrophe, quote, or newline inside a secret cannot change what the expression means.
-
-<Callout type="info">
-If an expression throws, for example because it reads a field that is not there, the block errors and the run follows the [error path](/workflows/connections) if one is connected. Guard missing values with optional chaining (`?.`) or a null check.
-</Callout>
+Numbers, booleans, and `null` compare as literals here. Other environment values are bound as strings, so quotes or newlines inside a secret cannot become expression code. This differs from [Function placeholders](/workflows/blocks/function#placeholders-are-always-strings), which always remain strings.
 
 ## Outputs
 
-| Output | What it is |
+| Reference | Value |
 | --- | --- |
-| `<condition.conditionResult>` | The boolean result of the branch that matched |
-| `<condition.selectedOption>` | The id of the matched branch |
-| `<condition.selectedPath>` | The destination block the workflow routed to |
+| `<condition.conditionResult>` | `true` for a matching expression; `false` when else is selected or no branch matches |
+| `<condition.selectedOption>` | Selected branch ID, or `null` if none |
+| `<condition.selectedPath>` | Destination object containing `blockId`, `blockType`, and `blockTitle`, or `null` when no destination is connected |
 
-## Examples
+Only the chosen path runs. A reference to a known block on a skipped path has no output.
 
-### Route a support ticket by priority
+## Errors and unmatched input
 
-<WorkflowPreview workflow={CONDITION_ROUTE_WORKFLOW} />
+Connect **else** to handle input that matches no expression. An unconnected else path ends without an error. A final `true` expression is another catch-all when you deliberately omit else.
 
-The Condition checks `<start.priority>` and runs one downstream path. The other does not run, so a reference to a block on the path that did not run comes back empty.
+<Callout type="warn">
+An expression that throws fails the block. Guard missing values with optional chaining (`?.`) or a null check, and connect the error port when the workflow should recover.
+</Callout>
 
-### Moderate content by score
+## Gate on a model score
 
 <WorkflowPreview workflow={CONDITION_MODERATE_WORKFLOW} />
 
-An Agent scores the content, and the Condition publishes it or blocks it on `<moderate.toxicity>`.
-
-### Branch onboarding by account tier
-
-<WorkflowPreview workflow={CONDITION_ONBOARD_WORKFLOW} />
-
-A Function reads the account, and the Condition sends enterprise accounts through guided setup and everyone else through the quick start.
-
-## Best Practices
+Give the Agent a Response Format containing numeric `toxicity`, then check `<moderate.toxicity> > 0.7`. The high-score branch blocks the content; else sends it to the publishing endpoint. The same pattern can route accounts by a structured `tier` field.
 
-- **Order branches from specific to general.** The first true branch wins, so put narrow checks before catch-alls.
-- **Always give unmatched runs a path.** Connect the **else** branch, or make the last condition `true`, so nothing dead-ends silently.
-- **Keep expressions simple.** Short boolean checks are easy to read and debug. Do heavy logic in a [Function](/workflows/blocks/function) block first and branch on its result.
-- **Guard missing values.** Use optional chaining (`?.`) or a null check so an absent field does not throw.
+## Related docs
 
-<FAQ items={[
-  { question: "What happens if no condition matches?", answer: "The workflow follows the else branch. If the else branch is not connected to a downstream block, that path ends gracefully without an error. Add a final condition of simply true to guarantee a match." },
-  { question: "What JavaScript features can I use in condition expressions?", answer: "Standard operators and methods: comparisons (===, !==, >, <), logical operators (&&, ||, !), string methods (.includes(), .endsWith(), .toLowerCase()), array methods (.includes(), .length), math, and Date comparisons. Reference block outputs with <blockName.output> syntax." },
-]} />
+- [Router](/workflows/blocks/router)
+- [Function](/workflows/blocks/function)
+- [Connections](/workflows/connections)
diff --git a/apps/docs/content/docs/workflows/blocks/credential.mdx b/apps/docs/content/docs/workflows/blocks/credential.mdx
index 951fa1ab00b..9e8622e8c4e 100644
--- a/apps/docs/content/docs/workflows/blocks/credential.mdx
+++ b/apps/docs/content/docs/workflows/blocks/credential.mdx
@@ -1,207 +1,137 @@
 ---
 title: Credential
-description: Select workspace OAuth credentials or find organization OAuth and MCP account references for downstream blocks.
+description: Select OAuth or managed MCP account references for downstream actions.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { Image } from '@/components/ui/image'
-import {
-  BlockPreview,
-  WorkflowPreview,
-  CREDENTIAL_ROUTE_WORKFLOW,
-  CREDENTIAL_SHARE_WORKFLOW,
-} from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
-
-The **Credential block** passes account references to downstream blocks without exposing tokens. **Select Credential** and **List Credentials** use workspace OAuth credentials. When [organization connected accounts](/platform/connected-accounts) is enabled and shared with the workflow's workspace, the organization operations find or list contributed OAuth accounts and managed MCP connections.
+import { BlockPreview, WorkflowPreview, CREDENTIAL_SHARE_WORKFLOW, CREDENTIAL_ROUTE_WORKFLOW } from '@/components/workflow-preview'
 
-<BlockPreview type="credential" />
-
-<Callout>
-  The Credential block outputs credential **ID references**, not secrets. Downstream blocks receive the ID and resolve the actual OAuth token securely during their own execution.
-</Callout>
-
-## Configuration
-
-### Operation
-
-| Value | Description |
-|---|---|
-| **Select Credential** | Pick one OAuth credential and output its reference — use this to wire a single credential into downstream blocks |
-| **List Credentials** | Return all OAuth credentials in the workspace as an array — use this with a ForEach loop |
-| **Find Organization Account** | Find exactly one active OAuth contribution by invitation email and provider |
-| **List Organization Accounts** | Return a page of active OAuth contributions, optionally filtered by email and providers |
-| **Find Organization MCP Connection** | Find exactly one active managed MCP connection by invitation email and MCP provider |
-| **List Organization MCP Connections** | Return a page of active managed MCP connections, optionally filtered by email and provider |
-
-### Credential (Select operation)
+The **Credential block** returns account references without exposing tokens. Select workspace OAuth credentials, or discover organization OAuth contributions and managed Model Context Protocol (MCP) connections shared with the workspace.
 
-Select an OAuth credential from your workspace. The dropdown shows all connected OAuth accounts (Google, GitHub, Slack, etc.).
-
-In advanced mode, paste a credential ID directly. You can copy a credential ID from your workspace's Credentials settings page.
+<BlockPreview type="credential" />
 
-### Provider (List operation)
+## Reuse a credential
 
-Filter the returned OAuth credentials by provider. Select one or more providers from the dropdown — only providers you have credentials for will appear. Leave empty to return all OAuth credentials.
+<WorkflowPreview workflow={CREDENTIAL_SHARE_WORKFLOW} />
 
-| Example | Returns |
-|---|---|
-| Gmail | Gmail credentials only |
-| Slack | Slack credentials only |
-| Gmail + Slack | Gmail and Slack credentials |
+Select a Slack credential once. In each downstream Slack block, switch its credential field to advanced mode and enter `<credential.credentialId>`. Changing the selection updates those bindings in one place.
 
-## Outputs
+<Callout type="info">
+A credential ID is a reference, not a token. The downstream block resolves and authorizes the credential when it runs. It still needs a compatible service and the required scopes; the same Google email address does not make one Gmail OAuth credential usable for Drive or Calendar.
+</Callout>
 
-<Tabs items={['Select Credential', 'List Credentials']}>
-  <Tab>
-    | Output | Type | Description |
-    |---|---|---|
-    | `credentialId` | `string` | The credential ID — pipe this into other blocks' credential fields |
-    | `displayName` | `string` | Human-readable name (e.g. "waleed@company.com") |
-    | `providerId` | `string` | OAuth provider ID (e.g. `google-email`, `slack`) |
-  </Tab>
-  <Tab>
-    | Output | Type | Description |
-    |---|---|---|
-    | `credentials` | `json` | Array of OAuth credential objects (see shape below) |
-    | `count` | `number` | Number of credentials returned |
+## Operations
 
-    Each object in the `credentials` array:
+| Operation | Behavior |
+| --- | --- |
+| **Select Credential** | Return one workspace OAuth credential reference. |
+| **List Credentials** | Return workspace OAuth credential references, optionally filtered by providers. |
+| **Find Organization Account** | Find exactly one active OAuth contribution by invitation email and provider. |
+| **List Organization Accounts** | Page through active OAuth contributions, optionally filtered by email and providers. |
+| **Find Organization MCP Connection** | Find exactly one active managed MCP connection by invitation email and MCP provider. |
+| **List Organization MCP Connections** | Page through active managed MCP connections, optionally filtered by email and provider. |
 
-    | Field | Type | Description |
-    |---|---|---|
-    | `credentialId` | `string` | The credential ID |
-    | `displayName` | `string` | Human-readable name |
-    | `providerId` | `string` | OAuth provider ID |
-  </Tab>
-</Tabs>
+These operations do not select secrets or service accounts. Function can read a returned ID string, but does not automatically resolve it to a token.
 
-## Organization accounts
+## Configuration
 
-An organization owner or admin must first [set up connected accounts](/platform/connected-accounts) and allow this workflow's workspace. The block uses the organization that owns the workspace; there is no credential group or organization selector.
+### Workspace credentials
 
-Every authorized workflow in an allowed workspace can discover active contributions for the integrations allowed in that workspace. Results are not restricted to the running user's own accounts, and no separate per-workflow grant is required. Normal workflow permissions still apply. Workspace and integration access are checked again on every page.
+For **Select Credential**, choose **Credential** from the workspace's connected OAuth accounts. Advanced mode accepts a **Credential ID** copied from Credentials settings or resolved from an earlier output.
 
-### Discover accounts by provider
+For **List Credentials**, optionally select one or more **Provider** values. The picker shows providers with connected credentials; leave it empty for all workspace OAuth credentials.
 
-1. Choose **List Organization Accounts**.
-2. Select a provider such as **Gmail** in **Providers**. Leave it empty to list all allowed providers.
-3. Leave **Email** blank. You do not need to know an account's email to discover it.
-4. Read **emails** for the provider account addresses, or **credentials** for the corresponding account references.
-5. While **hasMore** is true, pass **nextCursor** as **Cursor** with the same filters to read the next page.
+### Organization accounts [#organization-accounts]
 
-Multiple accounts are returned separately, including accounts contributed by the same person. Disconnected accounts, accounts needing reconnection, and revoked invitations are excluded. Listing never chooses an account automatically for a downstream block.
+An organization owner or admin must enable [connected accounts](/platform/connected-accounts) and allow the workflow's workspace. Personal workspaces cannot use an organization pool. The block uses the organization owning the workspace; there is no organization or credential-group selector.
 
-### Inputs
+Authorized workflows in an allowed workspace can discover active contributions for its allowed integrations. Results are not limited to the acting person's own accounts, and there is no separate per-workflow discovery grant. Workspace/integration access is checked on each page; normal workflow permissions still apply.
 
-| Operation | Required fields | Optional fields |
+| Operation | Required | Optional |
 | --- | --- | --- |
-| **Find Organization Account** | Email, Provider | — |
-| **List Organization Accounts** | — | Email, Providers, Limit, Cursor |
-| **Find Organization MCP Connection** | Email, MCP provider | — |
-| **List Organization MCP Connections** | — | Email, MCP provider, Limit, Cursor |
+| Find Organization Account | **Email**, **Provider** | — |
+| List Organization Accounts | — | **Email**, **Providers**, **Limit**, **Cursor** |
+| Find Organization MCP Connection | **Email**, **MCP provider** | — |
+| List Organization MCP Connections | — | **Email**, **MCP provider**, **Limit**, **Cursor** |
 
-For list operations, **Limit** accepts 1–100 and defaults to 100. **Cursor** accepts the previous page's `nextCursor`.
+**Email** means the invitation address associated with the person's verified Sim account. It can differ from the OAuth provider's account email. See [email association](/platform/connected-accounts#how-the-email-is-associated-with-a-sim-user).
 
-**Email** refers to the address used for the person's invitation. Sim associates that invitation with their verified Sim user. See [email association](/platform/connected-accounts#how-the-email-is-associated-with-a-sim-user) for how OAuth and managed MCP identity checks differ.
+List **Limit** defaults to 100 and accepts 1–100. **Cursor** accepts the previous page's `nextCursor` with the same filters. The block does not fetch all pages automatically.
 
-Find operations fail unless there is exactly one active matching connection. List operations return an empty array when there are no matches and omit inactive or revoked connections.
+Find fails unless exactly one active connection matches. List returns empty results when none match. Disconnected accounts, revoked invitations, and accounts needing reconnection are excluded; multiple accounts contributed by one person stay separate.
 
-### OAuth outputs
-
-**Find Organization Account** returns `credentialId`, `displayName`, `providerId`, and the invitation `email`. Pass `credentialId` into the corresponding integration block's credential field in advanced mode.
-
-**List Organization Accounts** returns these account references in `credentials`, with an additional `accountEmail` field containing the email verified by the OAuth provider. The existing `email` field remains the person's invitation address, which can differ from their provider account address. An optional **Email** input continues to filter by that exact invitation address.
+## Outputs
 
-The list also returns `emails`, `count`, `hasMore`, and `nextCursor`. `emails` contains the provider account addresses on this page in the same order as `credentials`; it preserves separate accounts even when addresses repeat. `count` is the number of accounts returned on this page. Feed `credentials` into a ForEach loop and use `<loop.currentItem.credentialId>` inside the loop. To process additional pages, pass `nextCursor` into another call with the same filters while `hasMore` is true; the block does not fetch all pages automatically.
+### Workspace OAuth
 
-For example, name a Credential block **account**, choose **Find Organization Account**, set **Email** to `alex@example.com`, and select **Gmail**. Reference `<account.credentialId>` in a Gmail block to act using Alex's contribution.
+| Operation | Outputs |
+| --- | --- |
+| Select Credential | `credentialId`, `displayName`, `providerId` |
+| List Credentials | `credentials`: array of those objects; `count`: number returned |
 
-### Managed MCP outputs
+Pass `<credential.credentialId>` to compatible credential fields. A deleted credential causes Select to fail; List omits it. Update the selection before rerunning.
 
-**Find Organization MCP Connection** returns:
+### Organization OAuth
 
-| Output | Type | Description |
-| --- | --- | --- |
-| `credentialId` | `string` | The person's managed MCP connection ID; use this connection for MCP calls |
-| `email` | `string` | Invitation email used to find the connection |
-| `displayName` | `string` | Connection display name |
-| `mcpServerId` | `string` | Shared MCP configuration ID |
-| `mcpServerName` | `string` | Configured MCP server name |
-| `toolNames` | `json` | Tool names available to this connection |
+**Find Organization Account** returns `credentialId`, `displayName`, `providerId`, and invitation `email`.
 
-**List Organization MCP Connections** returns these objects in `mcpConnections`, plus `count`, `hasMore`, and `nextCursor`. Pagination works the same way as for organization OAuth accounts; `nextCursor` is `null` on the last page.
+**List Organization Accounts** returns `credentials` with those fields plus `accountEmail` verified by the OAuth provider. It also returns:
 
-<Callout>
-For a managed MCP account, use the returned **`credentialId`** to select the person's connection in the MCP Tool block. **`mcpServerId`** identifies the shared provider configuration; it does not identify a person's authorization. No OAuth token or client secret is returned by the Credential block.
-</Callout>
+| Output | Meaning |
+| --- | --- |
+| `emails` | Provider account addresses on this page, in credential order; duplicates are preserved |
+| `count` | Accounts on this page |
+| `hasMore` | Whether another page is available |
+| `nextCursor` | Cursor for the next page, or `null` on the last page |
 
-## Connection-event triggers
+For example, name the block **Account**, choose Find Organization Account, set Email to `alex@example.com`, and select Gmail. Use `<account.credentialId>` in a Gmail block to act with that contribution.
 
-Switch the Credential block to trigger mode to start a workflow when an account connects or a connection form is submitted. Select an **Event** and deploy the workflow in an allowed workspace.
+### Managed MCP
 
-| Event | When it runs |
+| Field | Meaning |
 | --- | --- |
-| **Credential Added** | A person adds a new account contribution |
-| **Credential Reconnected** | A person reconnects an existing contribution |
-| **Account Connections Submitted** | A person submits the connection form |
+| `credentialId` | Person's managed MCP connection ID |
+| `email` | Invitation email |
+| `displayName` | Connection display name |
+| `mcpServerId` | Shared MCP configuration ID |
+| `mcpServerName` | Configured server name |
+| `toolNames` | Tools available through that connection |
 
-Events include `event`, `timestamp`, `email`, `enrollmentId`, `enrollmentStatus`, `credentialGroupId`, and `credentialGroupName`. Added and reconnected events also include account details such as `credentialId`, `provider`, and `displayName`; `mcpServerId` identifies shared configuration for an MCP connection and is `null` for an OAuth account.
+Find returns one object. List returns objects in `mcpConnections` plus `count`, `hasMore`, and `nextCursor`.
 
-Each deployed workflow that selects the event in an allowed workspace can receive it. Removing workspace access stops subsequent event delivery. Legacy **Credential Group** blocks must be replaced with the Credential block; they are not automatically converted.
+Use `credentialId` to select the person's connection in an MCP Tool block. `mcpServerId` identifies shared configuration, not the person's authorization. No OAuth token or client secret is returned.
 
-## Examples
+## List accounts and process each one
 
-### Share one credential across blocks
+1. Name the Credential block **Accounts**. Select **List Credentials** and filter **Provider** to Gmail, or use **List Organization Accounts** and filter **Providers** to Gmail.
+2. Pass `<accounts.credentials>` into a For Each loop.
+3. Inside the loop, set the Gmail credential to `<loop.currentItem.credentialId>`.
+4. For organization lists, repeat with `nextCursor` while `hasMore` is true, preserving filters.
 
-<WorkflowPreview workflow={CREDENTIAL_SHARE_WORKFLOW} />
-
-Select a Google account once, then reference `<credential.credentialId>` in the Gmail, Drive, and Calendar blocks. Change the account in one place and every block follows.
+Leave organization Email blank to discover accounts without knowing invitation addresses. Listing does not select a downstream account automatically.
 
-### Route to a different account by logic
+## Choose an account by a rule
 
 <WorkflowPreview workflow={CREDENTIAL_ROUTE_WORKFLOW} />
 
-A Condition picks the production or staging credential from a workflow variable, and the downstream Slack block posts with whichever one ran.
-
-### List all accounts and fan out
-
-```
-Credential (List, Provider: Gmail) → ForEach Loop → Gmail (Send) using <loop.currentItem.credentialId>
-```
+A Condition reads `<variable.env>` and selects a production or staging Slack credential. Each chosen branch passes its credential reference to a compatible Slack action.
 
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/credential-loop.png"
-    alt="Credential List wired into a ForEach Loop"
-    width={900}
-    height={373}
-    className="my-6"
-  />
-</div>
-
-## How to wire a Credential block
+## Connection-event triggers
 
-### Select Credential
+Switch the block to trigger mode, select an **Event**, and deploy in an allowed workspace:
 
-1. Drop a **Credential** block and select your OAuth credential from the picker
-2. In the downstream block, switch to **advanced mode** on its credential field
-3. Enter `<credentialBlockName.credentialId>` as the value
+| Event | Trigger |
+| --- | --- |
+| Credential Added | New account contribution |
+| Credential Reconnected | Existing contribution reconnected |
+| Account Connections Submitted | Connection form submitted |
 
-The same reference works for any OAuth block. In a Gmail or Slack block's credential field (advanced mode), enter `<myCredential.credentialId>`.
+Events include `event`, `timestamp`, `email`, `enrollmentId`, `enrollmentStatus`, `credentialGroupId`, and `credentialGroupName`. Added/reconnected events also include account details such as `credentialId`, `provider`, and `displayName`; `mcpServerId` identifies shared MCP configuration and is null for OAuth accounts.
 
-### List Credentials
+Every deployed workflow selecting that event in an allowed workspace can receive it. Removing workspace access stops later delivery. Replace legacy Credential Group blocks with Credential; they are not automatically converted.
 
-1. Drop a **Credential** block, set Operation to **List Credentials**
-2. Optionally select one or more **Providers** to narrow results (only your connected providers appear)
-3. Wire `<credentialBlockName.credentials>` into a **ForEach Loop** as the items source
-4. Inside the loop, reference `<loop.currentItem.credentialId>` in downstream blocks' credential fields
+## Related docs
 
-<FAQ items={[
-  { question: "What credential types does it support?", answer: "Workspace OAuth credentials, organization OAuth contributions, and organization managed MCP connections. Secrets and service accounts are not selected through these operations." },
-  { question: "Why are the organization operations missing?", answer: "Connected accounts must be enabled for the organization, and the workflow's workspace must be allowed in Organization settings → Connected accounts → Workspace access. Personal workspaces cannot use an organization pool." },
-  { question: "How is Select different from just copying a credential ID into advanced mode?", answer: "Functionally identical — both pass the same credential ID to the downstream block. The Credential block adds value when you need to use one credential in many blocks (change it once), or when you want to select between credentials dynamically using a Condition block." },
-  { question: "Can I use a Credential block output in a Function block?", answer: "Yes. Reference <credential.credentialId> in your Function block's code. The function receives the ID string. It does not automatically resolve credential IDs to tokens; use a compatible integration or MCP block to perform an authenticated action." },
-  { question: "What happens if the credential is deleted?", answer: "The Select operation will throw an error at execution time: 'Credential not found'. The List operation will simply omit the deleted credential from the results. Update the Credential block to select a valid credential before re-running." },
-]} />
+- [Connected accounts](/platform/connected-accounts)
+- [Credentials](/platform/credentials)
+- [Loop](/workflows/blocks/loop)
diff --git a/apps/docs/content/docs/workflows/blocks/evaluator.mdx b/apps/docs/content/docs/workflows/blocks/evaluator.mdx
index f99593a0800..eb7d64b7936 100644
--- a/apps/docs/content/docs/workflows/blocks/evaluator.mdx
+++ b/apps/docs/content/docs/workflows/blocks/evaluator.mdx
@@ -1,78 +1,66 @@
 ---
 title: Evaluator
-description: The Evaluator block uses a model to score content against metrics you define.
+description: Use a model to score text against named metrics.
 ---
 
 import { BlockPreview, WorkflowPreview, EVALUATOR_GATE_WORKFLOW } from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
 
-The **Evaluator block** uses a model to score content against metrics you define, returning a number per metric. Use it for quality gates, comparing variations, and quality control on AI output.
+The **Evaluator block** asks a model for numeric scores against metrics you define. Use the scores to compare drafts or choose a quality-review path.
 
 <BlockPreview type="evaluator" />
 
+## Gate a draft
+
+<WorkflowPreview workflow={EVALUATOR_GATE_WORKFLOW} />
+
+Define **Accuracy** with a 1–5 range, score `<draft.content>`, then check `<evaluator.accuracy> >= 4` in a Condition. Connect the passing branch to the next action and the other to review or revision.
+
 ## Configuration
 
-### Evaluation Metrics
+### Evaluation metrics
 
-The metrics to score against. Each metric has a **name**, a **description** of what it measures, and a numeric **range**:
+Each metric has a **name**, **description**, and numeric **range**:
 
-```
-Accuracy (1-5): How factually accurate is the content?
-Clarity  (1-5): How clear and understandable is it?
-Relevance(1-5): How relevant is it to the original query?
-```
+| Name | Range | Description |
+| --- | --- | --- |
+| Accuracy | 1–5 | Are the claims supported by the supplied source material? |
+| Clarity | 1–5 | Can a reader understand the answer without rereading it? |
+| Relevance | 1–5 | Does the answer address the original question? |
 
-The model scores the content on each metric and returns the numbers. Metrics missing a name or range are skipped.
+Complete every metric's name and range. Unnamed metrics are skipped. A missing range can leave a named score without a rubric; it is not a reliable way to disable a metric.
 
-### Content
+The range guides the model, but Sim does not clamp every returned score to it. Validate bounds downstream if they are required for an action. Compare sample scores with human judgments before relying on a quality gate.
 
-The content to score. Usually an earlier output like `<agent.content>`. Structured data is formatted to text before scoring; the evaluation is text-based, so it can't score images or audio directly.
+### Content and model
 
-### Model
+**Content** is the text to score, usually `<agent.content>`. Structured data is formatted as text. Images and audio are not scored directly.
 
-The model that does the scoring, defaulting to `claude-sonnet-5-5`. Stronger reasoning models give more consistent scores. Type or pick any supported model. **Temperature** and a **System Prompt** are available under advanced, and on hosted Sim the API key is supplied for you.
+**Model** defaults to `claude-sonnet-5-5`. Select a supported model and evaluate its scores on representative content. **Temperature** and **System Prompt** are available in advanced fields. Sim Cloud supplies credentials for supported hosted models; other models and self-hosted deployments can require your own credentials.
 
 ### Fallback models
 
-Under **Additional fields**, add up to five models to try in order when a model request fails. With **Retry on fail** enabled, the selected model exhausts its tries first; each fallback is then tried once. Every attempt uses the same content, metrics, and response schema. `<evaluator.model>` reports the model that answered.
+Under **Additional fields**, add up to five fallbacks. **Retry on fail** exhausts the selected model's attempts first; each fallback is then tried once. Attempts use the same content, metrics, and response schema.
 
-Hosted models on hosted Sim use workspace BYOK or platform credentials. On local or self-hosted installations, a fallback on another provider may need a secret selected on its row; same-provider fallbacks reuse the selected model's key. The picker shows supported tuning fields when the selected model's settings cannot be inherited. Auto cannot be a fallback.
+Hosted models use workspace BYOK or platform credentials where available. Same-provider fallbacks reuse the selected key; another provider can need a secret selected on its row. Supported tuning fields appear when settings cannot be inherited. Auto cannot be a fallback.
 
 ## Outputs
 
-The Evaluator returns a number for each metric, read by the metric's lowercase name:
-
-| Output | What it is |
+| Reference | Value |
 | --- | --- |
-| `<evaluator.accuracy>` | The score for a metric (one output per metric you define) |
-| `<evaluator.content>` | The original content that was evaluated |
-| `<evaluator.model>` | The model that scored |
-| `<evaluator.tokens>` | Token usage |
-| `<evaluator.cost>` | Estimated cost of the call |
-
-The block enforces a JSON Schema built from your metrics, so the model returns only the metric scores as numbers, no extra text.
-
-## Examples
-
-### Gate on a quality score
-
-<WorkflowPreview workflow={EVALUATOR_GATE_WORKFLOW} />
+| `<evaluator.accuracy>` | Score for Accuracy; each metric exposes its lowercase name, subject to the fallback behavior below |
+| `<evaluator.content>` | Original evaluated content |
+| `<evaluator.model>` | Model that answered |
+| `<evaluator.tokens>` | Model token usage |
+| `<evaluator.cost>` | Estimated cost in USD, as an object with `input`, `output`, and `total`; read `<evaluator.cost.total>` for the total |
 
-The Evaluator scores the draft, and a [Condition](/workflows/blocks/condition) gates on `<evaluator.accuracy>` — publishing a strong draft or sending a weak one back to revise.
+The Logs UI and run-resource API use credits. See [Costs](/platform/costs) for units and billing behavior.
 
-The same shape covers other quality work: score several [parallel](/workflows/blocks/parallel) variations and pick the best, or score every support reply and flag the low ones for review.
+The requested JSON Schema has numeric fields and no extra text. Its field types do not enforce the metric ranges. Keep the same metrics and rubric when comparing variations.
 
-## Best Practices
+A missing score or unparseable response can produce `0` without failing the block. Zero alone does not prove that the model assessed the content. Present scores are converted with `Number()` without a finite-number check, so malformed values can produce `NaN` before serialization. Validate that scores are finite and within the required bounds before using them to authorize an action, especially when a low score permits it.
 
-- **Write specific metric descriptions.** A clear definition of what each metric measures produces more consistent scores.
-- **Choose a sensible range.** Enough granularity to act on (1–5 or 0–10), without splitting hairs.
-- **Score Agent output and loop back.** Pair an Evaluator with a Condition to gate on a threshold and route weak output back for another pass.
-- **Keep metrics consistent.** For comparing variations, use the same metrics across each evaluation.
+## Related docs
 
-<FAQ items={[
-  { question: "What format does the Evaluator return scores in?", answer: "A JSON object where each key is the lowercase metric name and the value is the numeric score within the range you defined. A metric named 'Accuracy' with range 1-5 appears as { \"accuracy\": 4 }, read downstream as <evaluator.accuracy>." },
-  { question: "Can I evaluate non-text content?", answer: "The content field takes any string. JSON or structured data is detected and formatted before scoring, but the evaluation is text-based, so it can't directly score images or audio." },
-  { question: "What happens if a metric is incomplete?", answer: "Metrics missing a name or a range are skipped. The Evaluator only scores metrics that have both a name and a defined min/max range." },
-  { question: "Does the Evaluator use structured output?", answer: "Yes. It builds a JSON Schema from your metrics and requests strict structured output for the metric scores." },
-  { question: "How are evaluation costs calculated?", answer: "From the underlying model call's token usage. The outputs include token counts and a cost breakdown so you can track spend per evaluation." },
-]} />
+- [Condition](/workflows/blocks/condition)
+- [Agent](/workflows/blocks/agent)
+- [Parallel](/workflows/blocks/parallel)
diff --git a/apps/docs/content/docs/workflows/blocks/function.mdx b/apps/docs/content/docs/workflows/blocks/function.mdx
index 50dda68f46c..12055d783db 100644
--- a/apps/docs/content/docs/workflows/blocks/function.mdx
+++ b/apps/docs/content/docs/workflows/blocks/function.mdx
@@ -1,17 +1,67 @@
 ---
 title: Function
-description: The Function block runs your JavaScript, Python, or Shell code as a step and returns what it produces.
+description: Run JavaScript, Python, or Shell code and return values or files.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 import { BlockPreview, WorkflowPreview, FUNCTION_RESHAPE_WORKFLOW, FUNCTION_VALIDATE_WORKFLOW } from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
 
 The **Function block** runs your own JavaScript, Python, or Shell code as one step of a workflow. Use it to reshape a value, run a calculation, call a CLI, or add logic no other block covers.
 
 <BlockPreview type="function" />
 
+## Reshape an API response
+
+<WorkflowPreview workflow={FUNCTION_RESHAPE_WORKFLOW} />
+
+Fetch a response with an `items` array of user records, then return only active IDs:
+
+```javascript
+const data = <api.data>;
+return data.items.filter((item) => item.active).map((item) => item.id);
+```
+
+Later blocks read `<extract.result>` for a Function named **Extract**.
+
+## Language and runtime
+
+JavaScript without imports runs in the local isolated VM unless a special file-path reference requires a remote mount. JavaScript with `import` or `require`, Python, and Shell run in the configured remote provider. Local VM workers run within the Sim app container on self-hosted deployments.
+
+| Feature | JavaScript | Python | Shell |
+| --- | --- | --- | --- |
+| **Execution** | Local without imports or file-path mounts; remote otherwise | Always remote | Always remote |
+| **Return a value** | `return { … }` | Assign `__sim_result__ = { … }` | Print `__SIM_RESULT__={…}` |
+| **HTTP requests** | `fetch()` built in | `requests` or `httpx` | `curl` or an installed CLI |
+| **Best for** | quick transforms and JSON | scripts, data science, charts, complex math | CLI workflows and system utilities |
+
+Python and Shell require a remote sandbox. They are enabled by default on sim.ai;
+on a self-hosted instance, build and configure the provider's dedicated
+[Function base](/platform/enterprise/self-hosted) first. Python can return plots as images; you can also write image files under `/tmp/sim/outputs`.
+
+If no remote provider is configured, JavaScript without `import` or `require`
+continues to run in Sim's local isolated VM. Missing E2B or Daytona configuration
+does not disable that path. Remote-only code fails with an explicit configuration
+error; Sim does not reinterpret Python or Shell as JavaScript.
+
+The dedicated Function base has the same runtime and universal package contract
+on E2B and Daytona. It includes this data-science stack; use a workspace sandbox
+when another dependency must be present:
+
+- **Data and graphs:** `pandas`, `numpy`, `scipy`, `xarray`, `numba`, `networkx`
+- **ML and NLP:** `scikit-learn`, `gensim`, `nltk`, `spacy`, `textblob`
+- **Plots and images:** `matplotlib`, `seaborn`, `plotly`, `bokeh`, `kaleido`, `pillow`, `opencv-python`, `scikit-image`, `imageio`, `tifffile`
+- **Audio:** `librosa`, `soundfile`
+- **Web, parsing, and files:** `requests`, `beautifulsoup4`, `lxml`, `openpyxl`, `xlrd`, `python-docx`, `xmltodict`, `PyYAML`, `tomlkit`, `simplejson`, `orjson`, `SQLAlchemy`
+- **Math:** `sympy`
+- **Application helpers:** `rich`, `typer`, `click`, `tqdm`, `Jinja2`, `pydantic`, `python-dateutil`, `pytz`, `psutil`, `filetype`, `python-slugify`, `parsedatetime`, `pytimeparse`
+- **Generic CLIs:** `jq`, `yq`, `csvkit`, `zx`, `xmlstarlet`, `httpie`, `ripgrep`, `fd`, `bat`, `sqlite3`, `tar`, `gzip`, `bzip2`, ZIP/XZ/7z, media/image tools, and standard network utilities
+
+Vendor and service clients such as AWS CLI and GitHub CLI are not part of the
+universal base. Add them through the managed catalog. Database clients such as
+PostgreSQL, MySQL, and Redis can be added as system packages when available from
+the configured Debian repositories.
+
 ## Configuration
 
 ### Code
@@ -101,12 +151,16 @@ Sim supplies the rendered heredoc privately while preserving the quoted delimite
 | Output | What it is |
 | --- | --- |
 | `<function.result>` | The value your code returns (object, array, string, number, …) |
-| `<function.stdout>` | Anything printed with `console.log()` or `print()` |
+| `<function.stdout>` | Captured `console.log()`, `print()`, or Shell output, subject to the diagnostic limits below |
 | `<function.files>` | Files your code wrote to `/tmp/sim/outputs`, ready to attach or upload |
 
+Local JavaScript stdout is truncated after 200,000 characters by default, with a `[stdout truncated]` marker. Operators can change that default with `IVM_MAX_STDOUT_CHARS`.
+
+Remote execution has a separate 10 MiB combined process-output budget for stdout, stderr, result text, and structured error text. Exceeding it fails the block. Export large remote results as files under `/tmp/sim/outputs`; the separate 20-file and 50 MiB export limits still apply.
+
 ## Files
 
-**Reading.** Reference a file's `path` and it is mounted for you:
+**Reading.** Use an indexed file reference ending in `.path` to mount the file under `/tmp/sim/inputs`:
 
 ```python
 import pandas as pd
@@ -115,7 +169,7 @@ frame = pd.read_csv(<gmail.attachments[0].path>)
 frame.describe().to_csv('/tmp/sim/outputs/summary.csv')
 ```
 
-`.path` resolves to the file's location on the sandbox filesystem, so any language
+`.path` is a special Function reference, not a field stored on the file object. It resolves to the file's location on the sandbox filesystem, so any language
 can open it — pandas, ffmpeg, a CLI. It is the counterpart to `.base64`, which
 inlines the contents instead and works only in JavaScript. Both appear in the
 reference dropdown next to `.name` and `.size`.
@@ -125,70 +179,21 @@ reference dropdown next to `.name` and `.size`.
 attach them to an email, upload them to storage, or save them to the workspace with
 the File block. There is nothing to turn on.
 
-The one exception is a call that names an explicit `outputSandboxPath`. That asks
-for particular paths to be exported and answers with that export's own result, so
-the output directory is not harvested alongside it — choose one or the other rather
-than expecting both in the same run.
+The separate Function tool supports explicit `outputSandboxPath` exports. That tool option exports only the named paths and disables automatic directory harvesting for the call; it is not a field on the Function block.
 
-<Callout type="info">
 Referencing `.path` runs the block in the remote sandbox, since the local
 JavaScript VM has no filesystem — expect the slower start of a remote run even for
 plain JavaScript. Referencing the file itself (`<gmail.attachments[0]>`, `.name`,
-`.url`) does not, and stays local. Up to 20 files come back per run, 50MB total,
+`.url`) does not, and stays local. Up to 20 files come back per run, 50 MiB total,
 nested no more than 11 directories deep; a run that exceeds any of these fails
 rather than returning part of what your code wrote.
-</Callout>
 
 <Callout type="warn">
 Returned files live with the execution rather than in your workspace, and a text
 file containing a resolved secret value is refused rather than returned — there is
-nowhere on an execution file to record that it carries one. Write such a file to a
-workspace path instead, or keep the secret out of the output.
-</Callout>
-
-## Language
-
-JavaScript without imports runs in a fast local sandbox. JavaScript with `import` or `require`, Python, and Shell run in the configured remote sandbox provider.
-
-| Feature | JavaScript | Python | Shell |
-| --- | --- | --- | --- |
-| **Execution** | Local when there are no imports; remote with imports | Always remote | Always remote |
-| **Return a value** | `return { … }` | Assign `__sim_result__ = { … }` | Print `__SIM_RESULT__={…}` |
-| **HTTP requests** | `fetch()` built in | `requests` or `httpx` | `curl` or an installed CLI |
-| **Best for** | quick transforms and JSON | scripts, data science, charts, complex math | CLI workflows and system utilities |
-
-<Callout type="info">
-Python and Shell require a remote sandbox. They are enabled by default on sim.ai;
-on a self-hosted instance, build and configure the provider's dedicated
-[Function base](/platform/enterprise/self-hosted) first. Any Python figures you
-generate are captured as images automatically.
+nowhere on an execution file to record that it carries one. Keep secrets out of execution-file exports. For an explicitly authorized persistent destination, use a compatible workspace File action; the separate Function tool also has workspace output controls.
 </Callout>
 
-<Callout type="info">
-If no remote provider is configured, JavaScript without `import` or `require`
-continues to run in Sim's local isolated VM. Missing E2B or Daytona configuration
-does not disable that path. Remote-only code fails with an explicit configuration
-error; Sim does not reinterpret Python or Shell as JavaScript.
-</Callout>
-
-The dedicated Function base has the same runtime and universal package contract
-on E2B and Daytona. It includes this data-science stack; use a workspace sandbox
-when another dependency must be present:
-
-- **Data and graphs:** `pandas`, `numpy`, `scipy`, `xarray`, `numba`, `networkx`
-- **ML and NLP:** `scikit-learn`, `gensim`, `nltk`, `spacy`, `textblob`
-- **Plots and images:** `matplotlib`, `seaborn`, `plotly`, `bokeh`, `kaleido`, `pillow`, `opencv-python`, `scikit-image`, `imageio`, `tifffile`
-- **Audio:** `librosa`, `soundfile`
-- **Web, parsing, and files:** `requests`, `beautifulsoup4`, `lxml`, `openpyxl`, `xlrd`, `python-docx`, `xmltodict`, `PyYAML`, `tomlkit`, `simplejson`, `orjson`, `SQLAlchemy`
-- **Math:** `sympy`
-- **Application helpers:** `rich`, `typer`, `click`, `tqdm`, `Jinja2`, `pydantic`, `python-dateutil`, `pytz`, `psutil`, `filetype`, `python-slugify`, `parsedatetime`, `pytimeparse`
-- **Generic CLIs:** `jq`, `yq`, `csvkit`, `zx`, `xmlstarlet`, `httpie`, `ripgrep`, `fd`, `bat`, `sqlite3`, `tar`, `gzip`, `bzip2`, ZIP/XZ/7z, media/image tools, and standard network utilities
-
-Vendor and service clients such as AWS CLI and GitHub CLI are not part of the
-universal base. Add them through the managed catalog. Database clients such as
-PostgreSQL, MySQL, and Redis can be added as system packages when available from
-the configured Debian repositories.
-
 ## Sandboxes
 
 A sandbox is a named environment your workspace maintains: a language, a list of
@@ -236,8 +241,7 @@ Then open the block's advanced options and choose the sandbox under **Sandbox**.
 
 The default and custom behavior is intentionally explicit:
 
-- **JavaScript without imports** stays in the local isolated runtime for speed and
-  ignores the sandbox selection.
+- **JavaScript without imports or file-path mounts** stays in the local isolated runtime and ignores the sandbox selection.
 - **JavaScript with `import` or `require`** runs remotely. With no selection it
   uses the Function base; with a sandbox it gets that sandbox's npm packages and
   system packages and managed CLI tools.
@@ -249,12 +253,10 @@ When a Function block next loads its sandbox options, a successful lookup that
 confirms its selected sandbox was deleted clears that selection. Fetch or auth
 failures leave the workflow unchanged.
 
-<Callout type="info">
 Two sandboxes with the same language, dependency list, system packages, and managed
 CLI tools share one build, so duplicating a set costs nothing. Editing any part of
 that install specification starts a new build. Runs already in flight keep using
 the old one. Deleting a sandbox frees its build once nothing else uses it.
-</Callout>
 
 ### Build status
 
@@ -298,8 +300,8 @@ and adds to its execution time:
 
 ```bash
 set -euo pipefail
-python -m pip install --quiet csvkit
-csvcut -n /tmp/input.csv
+python -m pip install --quiet humanize
+python -c "import humanize; print(humanize.intcomma(1234567))"
 ```
 
 Use a custom sandbox instead when reproducibility or startup time matters. Put
@@ -307,7 +309,7 @@ ordinary Debian utilities in **System packages**; use the managed selector only
 for one of its specialized installers. Arbitrary install commands are not saved
 in a sandbox specification.
 
-### What is allowed
+### Dependency restrictions
 
 Dependency fields accept package names and version specifiers only. URLs, `git+`
 references, `-e`, local paths, `--index-url`, and npm aliases are rejected, with
@@ -318,20 +320,23 @@ System packages use Debian coordinates in the form
 shell syntax are rejected. A sandbox may declare up to 50 dependencies, 50 system
 packages, and 10 managed CLI tools.
 
-## Scoping secrets for agent tools
+## Secret access for Agent tools
 
-When a Function block is used as an Agent tool, its code can read every workspace
-secret by default — both `{{MY_SECRET}}` and `environmentVariables['MY_SECRET']`.
-Prefer `{{MY_SECRET}}` when the value may appear in execution logs. A successful
-double-brace substitution always activates
-[execution-trace masking](/platform/credentials#execution-log-protection). A direct
+When a Function block is used as an Agent tool, **All secrets** lets its code read
+all secrets available in that run's resolved environment, using either
+`{{MY_SECRET}}` or `environmentVariables['MY_SECRET']`. The execution's identity,
+workspace access, and secret grants determine which secrets are available.
+Prefer `{{MY_SECRET}}` when the value may appear in execution logs. For protected secrets, a successful
+double-brace substitution activates
+[execution-trace masking](/platform/credentials#execution-log-protection). A recognized direct
 `environmentVariables['MY_SECRET']` read activates it too, but only when Sim can
 recognize the read in the code beforehand — a name built at runtime, or a file that
 reassigns `environmentVariables` itself, is not recognized. See
 [the recognition limits](/platform/credentials#execution-log-protection).
 
-To narrow that, set **Secret access** to *Selected secrets* in the block's
-tool configuration and pick the names the code may read. Two things change:
+To narrow that, set **Secret access** to **Selected secrets** in the block's
+tool configuration and pick the names the code may read. Selecting a name does
+not grant access to an otherwise unavailable secret. Two things change:
 
 - Only those secrets are injected. `{{OTHER_SECRET}}` no longer resolves either.
 - The selected **names** are added to the tool's description, so the model knows
@@ -340,29 +345,27 @@ tool configuration and pick the names the code may read. Two things change:
   exact secret value, the Agent model receives `{{NAME}}` in its place. The raw
   runtime result and local side effects are not rewritten.
 
-Leaving the default (*All secrets*) resolves the list at run time, so a secret
-added next month is included automatically.
-
-## Examples
-
-### Reshape an API response
+Secrets marked **Unredacted** follow their configured visibility policy. See the credentials reference before changing it.
 
-<WorkflowPreview workflow={FUNCTION_RESHAPE_WORKFLOW} />
+Leaving the default (**All secrets**) resolves the available list at run time, so
+a newly added secret is included when the execution has access to it.
 
-The Function reads `<api.data>`, returns just the field the rest of the workflow needs, and exposes it as `<extract.result>`.
+## Examples
 
-### Validate input before writing
+### Normalize input before writing
 
 <WorkflowPreview workflow={FUNCTION_VALIDATE_WORKFLOW} />
 
-The Function sanitizes the form input and returns the clean value, which the API block sends as its body.
+The Function trims the name and email, lowercases the email, and returns the object that the API block sends as its body. Add validation before the write when the destination requires a particular format.
 
-### A worked example: loyalty score
+### Calculate a loyalty score
+
+The Start input `customer` is an object containing `name`, `purchaseHistory` (records with `amount`), `accountAge` in days, and `supportTickets` with `total` and `resolved`.
 
 <Tabs items={['JavaScript', 'Python']}>
   <Tab value="JavaScript">
 ```javascript title="loyalty-calculator.js"
-const { purchaseHistory, accountAge, supportTickets } = <agent>;
+const { purchaseHistory, accountAge, supportTickets } = <start.customer>;
 
 const totalSpent = purchaseHistory.reduce((sum, p) => sum + p.amount, 0);
 const purchaseFrequency = accountAge > 0 ? purchaseHistory.length / (accountAge / 365) : 0;
@@ -374,7 +377,7 @@ const supportScore = ticketRatio * 30;
 const loyaltyScore = Math.round(spendScore + frequencyScore + supportScore);
 
 return {
-  customer: <agent.name>,
+  customer: <start.customer.name>,
   loyaltyScore,
   loyaltyTier: loyaltyScore >= 80 ? 'Platinum' : loyaltyScore >= 60 ? 'Gold' : 'Silver',
 };
@@ -403,9 +406,8 @@ def calculate_loyalty(data):
         "loyaltyTier": tier,
     }
 
-
 if __name__ == "__main__":
-    __sim_result__ = calculate_loyalty(<agent>)
+    __sim_result__ = calculate_loyalty(<start.customer>)
 ```
   </Tab>
 </Tabs>
@@ -425,21 +427,18 @@ const chunk = await sim.files.readTextChunk(file, { offset: 0, length: 1024 * 10
 const bytes = await sim.files.readBase64Chunk(file, { offset: 0, length: 1024 * 1024 });
 ```
 
-`sim.files.readText`, `readBase64`, and the `…Chunk` variants stream from execution storage under memory caps. `sim.values.read(ref)` and `sim.values.readArray(ref)` read large value and array references. Chunk `offset` and `length` are byte-based, so for exact Unicode parsing prefer smaller structured references. For large generated data, write the result to a file or table with `outputPath`, `outputSandboxPath`, or `outputTable` instead of returning the whole payload inline.
+`sim.files.readText`, `readBase64`, and the `…Chunk` variants stream from execution storage under memory caps. `sim.values.read(ref)` and `sim.values.readArray(ref)` read large value and array references. Chunk `offset` and `length` are byte-based, so for exact Unicode parsing prefer smaller structured references. For large generated data in a remote Function block, write files under `/tmp/sim/outputs` and pass them to a compatible File or Table action. The separate Function tool exposes `outputPath`, `outputSandboxPath`, and `outputTable` for explicit persistence; those are not builder fields.
 
-<Callout type="warn">
 The lazy `sim.files` and `sim.values` helpers are available only in JavaScript functions without imports. JavaScript with imports, Python, and Shell do not support them yet.
-</Callout>
 
-## Best Practices
+## Errors and timeout
+
+An uncaught error follows the connected error port or fails the run. Catch an error only when your code can return a meaningful recovery result. `console.log()`, `print()`, and ordinary Shell output appear in `stdout` and the run logs.
 
-{/* Keep the error-path guidance below prominent: fewer than 1% of deployed workflows connect an error port (platform data, 2026-06) — under-adopted, not under-needed. */}
+Function uses the workflow's remaining execution time when a deadline exists. Without a workflow deadline, it still has a fallback timeout of 300,000 ms (5 minutes) by default, configurable through `EXECUTION_TIMEOUT_FREE`. An explicit internal timeout can replace that fallback or shorten the workflow budget; it cannot extend the workflow deadline. There is no separate timeout field in the current block editor. Exceeding the budget terminates execution and reports a block error.
 
-- **Keep each function focused.** One transform per block is easier to read, test, and debug.
-- **Handle errors.** Wrap risky code in `try`/`catch` and return a clear message, or let it throw to the error path.
-- **Reference only what you need.** Pull a narrow field rather than a whole large object to keep values out of the request body.
-- **Use stdout to debug.** `console.log()`, `print()`, and ordinary shell output land in `<function.stdout>` and the run logs.
+## Related docs
 
-<FAQ items={[
-  { question: "Is there a timeout for Function block execution?", answer: "Yes, a configurable execution timeout. If your code exceeds it, the run is terminated and the block reports an error. Keep this in mind for external calls or heavy processing." },
-]} />
+- [Passing files](/files/passing-files)
+- [Sandbox setup](/platform/self-hosting/sandboxes)
+- [Credentials and execution-log protection](/platform/credentials#execution-log-protection)
diff --git a/apps/docs/content/docs/workflows/blocks/guardrails.mdx b/apps/docs/content/docs/workflows/blocks/guardrails.mdx
index cbd9bd2c352..26ebb92993a 100644
--- a/apps/docs/content/docs/workflows/blocks/guardrails.mdx
+++ b/apps/docs/content/docs/workflows/blocks/guardrails.mdx
@@ -1,138 +1,111 @@
 ---
 title: Guardrails
-description: The Guardrails block checks content against a validation type before it moves through the workflow.
+description: Validate JSON, match a pattern, assess grounding, or detect PII.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Image } from '@/components/ui/image'
-import {
-  BlockPreview,
-  WorkflowPreview,
-  GUARDRAILS_JSON_WORKFLOW,
-  GUARDRAILS_HALLUCINATION_WORKFLOW,
-  GUARDRAILS_PII_WORKFLOW,
-} from '@/components/workflow-preview'
-import { Video } from '@/components/ui/video'
-import { FAQ } from '@/components/ui/faq'
-
-The **Guardrails block** checks content against one validation type and reports whether it passed. Use it to catch malformed JSON, off-pattern text, ungrounded answers, or PII before the content moves on. Each block runs one check; chain several to apply more than one.
+import { BlockPreview, WorkflowPreview, GUARDRAILS_JSON_WORKFLOW, GUARDRAILS_HALLUCINATION_WORKFLOW, GUARDRAILS_PII_WORKFLOW } from '@/components/workflow-preview'
 
-<BlockPreview type="guardrails" />
-
-## Validation Types
-
-### Valid JSON
+The **Guardrails block** checks content and returns a result. Each block runs one validation type; chain blocks for multiple checks. Validation alone does not choose the next path—connect a Condition to act on it.
 
-Checks that the content parses as valid JSON. Use it before a [Function](/workflows/blocks/function) or downstream block reads a model's structured output.
+<BlockPreview type="guardrails" />
 
-- `<guardrails.passed>` — `true` if the content is valid JSON
-- `<guardrails.error>` — the parse error when it isn't, like `Invalid JSON: Unexpected token`
+## Validate before parsing
 
-### Regex Match
+<WorkflowPreview workflow={GUARDRAILS_JSON_WORKFLOW} />
 
-Checks the content against a regular expression — an email, a phone number, a URL, or any pattern you define.
+Select **Valid JSON**, check `<agent.content>`, and branch on `<guardrails.passed>` before parsing it in Function. This checks JSON syntax, not a schema's required fields or types.
 
-- **Regex Pattern** — the expression to match, like `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$` for an email
-- `<guardrails.passed>` — `true` if the content matches; `<guardrails.error>` otherwise
+## Configuration
 
-### Hallucination Check
+Set **Content to Validate** to text or an earlier output, then select **Validation Type**.
 
-Scores how well AI output is grounded in a knowledge base. The block retrieves relevant context, sends it to a model with the output, and the model returns a confidence score from **0** (completely ungrounded) to **10** (fully supported). Validation passes when the score meets the threshold.
+### Valid JSON
 
-- **Knowledge Base** — the knowledge base to check against
-- **Model** — the model that scores grounding. There is no default; pick a strong reasoning model. The API key is supplied for you on hosted Sim
-- **Confidence** — the minimum score to pass, from 0 to 10 (default 3)
-- **Top K** (advanced) — how many knowledge base chunks to retrieve (default 5)
+Passes when the content parses as JSON. Invalid content returns `passed: false` and a parse error. Use a Function after this check if you also need schema validation.
 
-Outputs `<guardrails.score>` (0–10) and `<guardrails.reasoning>` (why the model scored it that way) alongside `passed`.
+### Regex match
 
-### PII Detection
+Enter **Regex Pattern**, for example an email pattern:
 
-Detects personally identifiable information with [Microsoft Presidio](https://microsoft.github.io/presidio/) — over 30 entity types across several countries and languages.
+```text
+^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
+```
 
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/guardrails-2.png"
-    alt="PII Detection Configuration"
-    width={700}
-    height={335}
-    className="my-6"
-  />
-</div>
+Patterns use RE2's linear-time engine. Lookahead, lookbehind, and backreferences are unsupported and fail validation. To require that content does not contain a pattern, match the pattern and invert `passed` in a Condition.
 
-<div className="mx-auto w-3/5 overflow-hidden rounded-lg">
-  <Video src="guardrails.mp4" width={500} height={350} />
-</div>
+### Hallucination check
 
-- **PII Types to Detect** — pick the entity types from the modal, grouped by region:
-  - **Common** — person name, email, phone, credit card, IP address, and more
-  - **USA** — SSN, driver's license, passport, bank account, ITIN
-  - **UK** — NHS number, national insurance number
-  - **Spain** — NIF, NIE · **Italy** — fiscal code, driver's license, identity card, passport · **Poland** — PESEL · **Singapore** — NRIC/FIN
-  - **Australia** — ABN, ACN, TFN, Medicare · **India** — Aadhaar, PAN, vehicle registration, voter number, passport
-- **Action** — **Block** fails validation when any selected type is found (default); **Mask** also replaces the PII with masked values
-- **Language** — the detection language (default English)
+Select **Knowledge Base** and **Model**. There is no default model. The block retrieves relevant chunks and asks the model how well they support the answer.
 
-Outputs `<guardrails.detectedEntities>` (each with type, location, and confidence) and, in Mask mode, `<guardrails.maskedText>`. `passed` is `false` when any selected PII is found.
+| Field | Behavior |
+| --- | --- |
+| **Confidence** | Minimum passing score from 0 to 10; default 3. |
+| **Top K** | Advanced number of retrieved chunks; default 5, maximum 20. More chunks add context, latency, and tokens. |
 
-## Configuration
+The scale runs from 0 (ungrounded) to 10 (fully supported according to the model). It is a model judgment, not proof that every claim is correct. No relevant retrieved context fails the check. Sim Cloud supplies credentials for supported hosted models; other models or deployments can require your own.
 
-### Content to Validate
+### PII detection
 
-The input to check. Usually an earlier output like `<agent.content>`, `<function.result>`, or an [API](/workflows/blocks/api) response.
+Detect personally identifiable information with [Microsoft Presidio](https://microsoft.github.io/presidio/). Choose the **PII Types to Detect**, **Action**, and **Language**.
 
-### Validation Type
+- **Common** includes names, email, phone, credit cards, IP addresses, and other identifiers.
+- **Language** defaults to English. English, Spanish, Italian, Polish, and Finnish have configured NLP models; choose the language matching the input. Entity availability can vary by language.
+- **Custom Patterns** adds Name, Pattern, and Replacement rows for identifiers not covered by the built-in selection. These PII recognizers use a different engine from Regex Match; do not assume their pattern support is identical.
 
-Which of the four checks to run: Valid JSON, Regex Match, Hallucination Check, or PII Detection.
+With no selected built-in types and no custom patterns, detection uses the analyzer's supported types.
 
-## Outputs
+The picker groups these regional identifiers. Availability depends on the selected language.
 
-Every validation type returns:
-
-| Output | What it is |
+| Region | Identifiers |
 | --- | --- |
-| `<guardrails.passed>` | Whether the check passed |
-| `<guardrails.validationType>` | The check that ran |
-| `<guardrails.input>` | The content that was checked |
-| `<guardrails.error>` | The failure message, when there is one |
-
-Hallucination adds `<guardrails.score>` and `<guardrails.reasoning>`; PII adds `<guardrails.detectedEntities>` and `<guardrails.maskedText>`.
+| United States | Social Security Number (SSN), driver's license, passport, bank account, Individual Taxpayer Identification Number (ITIN) |
+| United Kingdom | NHS number, National Insurance Number |
+| Spain | NIF and NIE numbers |
+| Italy | Fiscal code, driver's license, VAT code, passport, identity card |
+| Poland | PESEL number |
+| Singapore | NRIC/FIN, Unique Entity Number (UEN) |
+| Australia | Business Number (ABN), Company Number (ACN), Tax File Number (TFN), Medicare number |
+| India | Permanent Account Number (PAN), Aadhaar number, vehicle registration, voter ID, passport |
+| Finland | Personal Identity Code |
+
+| Action | Result when PII is found |
+| --- | --- |
+| **Block Request** (default) | `passed: false`, detected entities, and an error summary |
+| **Mask PII** | Replaced text in `maskedText`; `passed: true` when masking succeeds |
 
-## Examples
+With no PII found, Mask returns the original text. Read `detectedEntities` to distinguish no detection from successful masking.
 
-### Validate JSON before parsing
+<Callout type="warn">
+Use `<guardrails.maskedText>` downstream in Mask mode. The original content is still available as `<guardrails.input>`; masking does not replace it everywhere in the run.
+</Callout>
 
-<WorkflowPreview workflow={GUARDRAILS_JSON_WORKFLOW} />
+## Outputs
 
-Check the Agent's output is valid JSON, then branch on `<guardrails.passed>` before a Function parses it.
+| Reference | Value |
+| --- | --- |
+| `<guardrails.passed>` | Validation outcome; for Mask, whether masking succeeded |
+| `<guardrails.validationType>` | Check that ran |
+| `<guardrails.input>` | Original checked content |
+| `<guardrails.error>` | Failure message, when present |
+| `<guardrails.score>` / `<guardrails.reasoning>` | Grounding score and explanation for Hallucination Check |
+| `<guardrails.detectedEntities>` | PII entities with type, location, detected text, and confidence |
+| `<guardrails.maskedText>` | Masked text in Mask mode |
 
-### Check answer grounding
+## Check grounding
 
 <WorkflowPreview workflow={GUARDRAILS_HALLUCINATION_WORKFLOW} />
 
-Score the answer against a knowledge base, then gate on `<guardrails.score>` to send a grounded answer or flag a weak one.
+Use `passed` for the configured threshold, or `score` for an explicit downstream comparison. Hallucination checks run synchronously; choose the model and chunk count according to the latency your workflow allows.
 
-### Block PII in user input
+## Block PII in input
 
 <WorkflowPreview workflow={GUARDRAILS_PII_WORKFLOW} />
 
-Detect PII in the input and branch on `<guardrails.passed>` to process clean input or reject it.
-
-## Best Practices
+Branch on `passed` to process clean input or reject detected PII. Selecting only the types relevant to your task keeps the check focused.
 
-- **Branch on the result.** Read `<guardrails.passed>` in a [Condition](/workflows/blocks/condition) to route valid and invalid content down different paths.
-- **Validate JSON before you parse it.** A check upstream is cheaper than a parse error in a Function block.
-- **Pick only the PII types you need.** Selecting fewer entity types keeps detection fast and focused.
-- **Tune the hallucination threshold.** Raise the confidence floor for stricter grounding, lower it to allow more latitude.
-- **Use the masked output downstream.** In Mask mode, pass `<guardrails.maskedText>` to downstream storage or messaging. The original content remains available separately as `<guardrails.input>`.
-- **Chain checks.** One block runs one type, so place several in sequence to validate format and then scan for PII.
-
-<Callout type="info">
-Guardrails runs synchronously in the workflow. For hallucination checks where latency matters, choose a faster model.
-</Callout>
+## Related docs
 
-<FAQ items={[
-  { question: "How many knowledge base chunks are retrieved for hallucination detection?", answer: "Five by default. You can raise it up to 20 in Advanced settings. More chunks give broader context but add latency and tokens." },
-  { question: "Which languages does PII detection support?", answer: "English, Spanish, Italian, Polish, and Finnish. The language setting selects the NLP models used for entity recognition, so matching it to your content improves accuracy." },
-  { question: "Does JSON validation check schema structure or just syntax?", answer: "Just syntax — it confirms the content parses as valid JSON, not that it matches a particular schema. For schema validation, use a Function block after the check." },
-]} />
+- [Condition](/workflows/blocks/condition)
+- [Function](/workflows/blocks/function)
+- [Credentials and execution-log protection](/platform/credentials)
diff --git a/apps/docs/content/docs/workflows/blocks/human-in-the-loop.mdx b/apps/docs/content/docs/workflows/blocks/human-in-the-loop.mdx
index 262678abf5e..9a0f8386188 100644
--- a/apps/docs/content/docs/workflows/blocks/human-in-the-loop.mdx
+++ b/apps/docs/content/docs/workflows/blocks/human-in-the-loop.mdx
@@ -1,270 +1,151 @@
 ---
-title: Human in the Loop
-description: The Human in the Loop block pauses a run for human approval, then resumes with their input.
+title: Human in the loop
+description: Pause a run for human input, then route on the submitted decision.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { Image } from '@/components/ui/image'
-import {
-  BlockPreview,
-  WorkflowPreview,
-  HITL_APPROVAL_WORKFLOW,
-  HITL_MULTISTAGE_WORKFLOW,
-  HITL_VALIDATE_WORKFLOW,
-} from '@/components/workflow-preview'
-import { Video } from '@/components/ui/video'
-
-The **Human in the Loop block** pauses a run and waits for a person before it continues. Use it for approval gates, to collect feedback, or to gather input at a decision point. The run stays paused — with no timeout — until someone responds through the approval portal, the API, or a webhook.
+import { BlockPreview, WorkflowPreview, HITL_APPROVAL_WORKFLOW, HITL_MULTISTAGE_WORKFLOW, HITL_VALIDATE_WORKFLOW } from '@/components/workflow-preview'
+
+The **Human** block pauses a run until a person submits input. Use it for approvals, feedback, or correcting extracted data. The pause has no automatic response timeout; it remains pending until resumed or cancelled.
 
 <BlockPreview type="human_in_the_loop" />
 
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/hitl-2.png"
-    alt="Human in the Loop Approval Portal"
-    width={700}
-    height={467}
-    className="my-6"
-  />
-</div>
+## Approve before an action
+
+<WorkflowPreview workflow={HITL_APPROVAL_WORKFLOW} />
+
+Name the Human block **Approval** and add a boolean `approved` field. After submission, a Condition checks `<approval.approved> === true`. Only its passing branch sends the content to the publishing API; the other branch handles rejection.
+
+<Callout type="warn">
+Resuming a Human block does not itself approve the action. Check the submitted decision before sending an email, publishing content, or making another consequential change.
+</Callout>
 
 ## Configuration
 
-### Display Data
+### Display data
 
-What the approver sees — the context shown in the portal to help them decide. Build it field by field or as JSON, referencing earlier outputs with `<blockName.output>`.
+**Display Data** is the context shown in the portal. Build fields using earlier outputs:
 
 ```json
 {
-  "customerName": "<agent1.content.name>",
-  "proposedAction": "<router1.selectedPath>",
-  "confidenceScore": "<evaluator1.score>",
-  "generatedEmail": "<agent2.content>"
+  "customerName": "<agent.name>",
+  "proposedAction": "Send the drafted email",
+  "accuracy": "<evaluator.accuracy>",
+  "generatedEmail": "<draft.content>"
 }
 ```
 
+Define the matching Agent response fields and Evaluator metric before using their references.
+
 ### Notification
 
-How approvers are alerted that a decision is waiting. Include the approval URL (`<blockId.url>`) in the message so they can open the portal. Available channels:
+**Notification (Send URL)** configures tools that alert approvers. Include `<approval.url>` in the message. Supported tool choices include Slack, Gmail, Microsoft Teams, Twilio SMS, and Webhook, using their configured credentials.
+
+A notification Webhook sends the approval request to another system; that system must use the resume API to submit a decision. Sending a notification is separate from resuming the workflow.
+
+### Resume form
+
+**Resume Form** defines fields to submit, such as:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `approved` | boolean | Approve or reject the action |
+| `comments` | string | Feedback or explanation |
+
+After resumption, read them with the Human block's name: `<approval.approved>` and `<approval.comments>`.
+
+## Outputs
+
+| Reference | Value |
+| --- | --- |
+| `<approval.url>` | Approval portal URL |
+| `<approval.resumeEndpoint>` | Resume API endpoint containing the pause context ID |
+| `<approval.response>` | Display data |
+| `<approval.submission>` | Form submission |
+| `<approval.resumeInput>` | Raw submitted resume input |
+| `<approval.submittedAt>` | ISO submission timestamp |
+| `<approval.fieldName>` | A configured Resume Form field after resumption |
+
+Use the block's reference name, not a literal `<blockId>` placeholder, in workflow fields. The paused API response also exposes a `_resume` object containing resume URLs and `contextId`.
+
+## Use the approval portal
+
+Open the generated URL to review the display data, fill in the resume form, and submit it. Share that URL through the configured notification tool. Portal access remains subject to the workflow's authorization requirements.
 
-- **Slack** — a message to a channel or DM
-- **Gmail** — an email with the approval link
-- **Microsoft Teams** — a channel notification
-- **SMS** — a text alert via Twilio
-- **Webhook** — a request to your own notification system
+HITL blocks are excluded from the selected-output picker because pause data is included automatically in the paused response.
 
-### Resume Form
+## Resume with the v2 API
 
-The fields the approver fills in when responding. Each becomes available to downstream blocks once the run resumes.
+A v2 execute call can return `data.status: "paused"`. Read `contextId` from `data.output.data._resume` and the paused run's ID from `data.runId`:
+
+```bash
+curl -X POST 'https://www.sim.ai/api/v2/workflows/WORKFLOW_ID/runs/RUN_ID/resume' \
+  -H 'X-API-Key: YOUR_API_KEY' \
+  -H 'Content-Type: application/json' \
+  -d '{"contextId":"CONTEXT_ID","input":{"approved":true,"comments":"Ready to send"}}'
+```
+
+Replace the IDs, host, and key. Do not send a raw approval boolean instead of the `input` object.
+
+### Synchronous resumption
+
+For an originally synchronous run, the response waits for the resumed execution and returns a v2 run envelope. For example:
 
 ```json
 {
-  "approved": {
-    "type": "boolean",
-    "description": "Approve or reject this request"
-  },
-  "comments": {
-    "type": "string",
-    "description": "Optional feedback or explanation"
+  "data": {
+    "runId": "RESUME_RUN_ID",
+    "workflowId": "WORKFLOW_ID",
+    "status": "completed",
+    "output": { "message": "Sent" },
+    "blockOutputs": null,
+    "error": null,
+    "startedAt": "2026-10-13T10:00:00.000Z",
+    "endedAt": "2026-10-13T10:00:01.234Z",
+    "durationMs": 1234
   }
 }
 ```
 
-Access resume data in downstream blocks using `<blockId.fieldName>`. 
-
-## Approval Methods
-
-<Tabs items={['Approval Portal', 'API', 'Webhook']}>
-  <Tab>
-    ### Approval Portal
-    
-    Every block generates a unique portal URL (`<blockId.url>`) with a visual interface showing all paused output data and form fields for resume input. Mobile-responsive and secure.
-    
-    Share this URL in notifications for approvers to review and respond.
-  </Tab>
-  <Tab>
-    ### REST API
-    
-    Programmatically resume workflows through the v2 run resource. The `contextId` is available from the block's `resumeEndpoint` output or from the `_resume` object in the paused run response.
-    
-    ```bash
-    POST /api/v2/workflows/{workflowId}/runs/{runId}/resume
-    Content-Type: application/json
-    X-API-Key: your-api-key
-    
-    {
-      "contextId": "<contextId>",
-      "input": {
-        "approved": true,
-        "comments": "Looks good to proceed"
-      }
-    }
-    ```
-    
-    The resume endpoint automatically respects the execution mode used in the original execute call:
-    
-    - **Sync mode** (default) — The response waits for the remaining workflow to complete and returns the full result:
-    
-    ```json
-    {
-      "data": {
-        "runId": "<resumeRunId>",
-        "workflowId": "<workflowId>",
-        "status": "completed",
-        "output": { ... },
-        "error": null,
-        "startedAt": "...",
-        "endedAt": "...",
-        "durationMs": 1234
-      }
-    }
-    ```
-    
-    If the resumed workflow hits another HITL block, the response returns `"status": "paused"` with new `_resume` URLs in the output.
-    
-    - **Stream mode** (`stream: true` on the original execute call) — The resume response streams SSE events with `selectedOutputs` chunks, just like the initial execution.
-    
-    - **Async mode** (`async: true` on the original v2 execute call) — The resume dispatches the run to a background worker and returns immediately with `202`, including the resume attempt's `runId` and v2 `statusUrl` for polling:
-    
-    ```json
-    {
-      "data": {
-        "runId": "<resumeRunId>",
-        "statusUrl": "/api/v2/workflows/<workflowId>/runs/<resumeRunId>"
-      }
-    }
-    ```
-    
-    #### Polling run status
-    
-    Poll the `statusUrl` from the async response to check when the resume completes:
-    
-    ```bash
-    GET /api/v2/workflows/{workflowId}/runs/{resumeRunId}?includeOutput=true
-    X-API-Key: your-api-key
-    ```
-    
-    Returns the run status and, when completed, the full workflow output.
-
-    The legacy endpoint remains available without behavior changes for existing integrations:
-
-    ```bash
-    POST /api/resume/{workflowId}/{executionId}/{contextId}
-    ```
-
-    Its async response continues to expose `jobId` and the legacy `/api/jobs/{jobId}` polling URL.
-    
-    To check on a paused execution's pause points and resume links:
-    
-    ```bash
-    GET /api/resume/{workflowId}/{executionId}
-    X-API-Key: your-api-key
-    ```
-    
-    Returns the paused execution detail with all pause points, their statuses, and resume links. Returns `404` when the execution has completed and is no longer paused.
-  </Tab>
-  <Tab>
-    ### Webhook
-    
-    Add a webhook tool to the Notification section to send approval requests to external systems. Integrate with ticketing systems like Jira or ServiceNow.
-  </Tab>
-</Tabs>
-
-## API Execute Behavior
-
-When triggering a workflow through `POST /api/v2/workflows/{workflowId}/execute`, HITL blocks cause the execution to pause and return the `_resume` data in the v2 response envelope. The legacy `POST /api/workflows/{id}/execute` endpoint remains available for existing integrations.
-
-<Tabs items={['Sync (JSON)', 'Stream (SSE)', 'Async']}>
-  <Tab>
-    The response includes the full pause data with resume URLs:
-    
-    ```json
-    {
-      "data": {
-        "runId": "<runId>",
-        "workflowId": "<workflowId>",
-        "status": "paused",
-        "output": {
-          "data": {
-            "operation": "human",
-            "_resume": {
-              "apiUrl": "/api/resume/{workflowId}/{executionId}/{contextId}",
-              "uiUrl": "/resume/{workflowId}/{executionId}",
-              "contextId": "<contextId>",
-              "executionId": "<executionId>",
-              "workflowId": "<workflowId>"
-            }
-          }
-        },
-        "error": null
-      }
-    }
-    ```
-  </Tab>
-  <Tab>
-    Blocks before the HITL stream their `selectedOutputs` normally. When execution pauses, the final SSE event includes `status: "paused"` and the `_resume` data:
-    
-    ```
-    data: {"blockId":"agent1","chunk":"streamed content..."}
-    data: {"event":"final","data":{"success":true,"output":{...,"_resume":{...}},"status":"paused"}}
-    data: "[DONE]"
-    ```
-    
-    On resume, blocks after the HITL stream their `selectedOutputs` the same way.
-    
-    <Callout type="info">
-      HITL blocks are automatically excluded from the `selectedOutputs` dropdown since their data is always included in the pause response.
-    </Callout>
-  </Tab>
-  <Tab>
-    Returns `202` immediately. Use the polling endpoint to check when the execution pauses.
-  </Tab>
-</Tabs>
-
-## Examples
-
-### Approve content before it ships
+A later Human block can pause the resumed run again, returning new pause data. The resumed attempt has its own `runId`.
 
-<WorkflowPreview workflow={HITL_APPROVAL_WORKFLOW} />
+### Asynchronous and originally streaming runs
 
-The run pauses at the Human in the Loop block until someone approves; on resume, the API publishes. The same gate works before any action, like sending a customer email.
+The v2 resume endpoint returns JSON, not SSE. An originally asynchronous run resumes in the background. An originally streaming run also resumes asynchronously through v2. Both return `202` with a receipt:
 
-### Chain multiple approvals
+```json
+{
+  "data": {
+    "runId": "RESUME_RUN_ID",
+    "statusUrl": "https://www.sim.ai/api/v2/workflows/WORKFLOW_ID/runs/RESUME_RUN_ID"
+  }
+}
+```
 
-<WorkflowPreview workflow={HITL_MULTISTAGE_WORKFLOW} />
+Poll the returned status URL with the same authentication and `includeOutput=true` to read the result. A queued response can also include `queuePosition`.
 
-For a high-stakes change, chain two approval steps — a manager, then a director — before the workflow executes.
+## Legacy resume compatibility
 
-### Verify extracted data
+Existing callers can continue using `POST /api/resume/{workflowId}/{executionId}/{contextId}`. Its asynchronous receipt uses `jobId` and `/api/jobs/{jobId}`; its streaming path preserves legacy SSE behavior from the original execute call. See [workflow streaming](/workflows/deployment/agent-events) for the protocol distinction.
 
-<WorkflowPreview workflow={HITL_VALIDATE_WORKFLOW} />
+The legacy `GET /api/resume/{workflowId}/{executionId}` lists a paused execution's pause points, statuses, and resume links. It returns `404` after the execution is no longer paused.
 
-A reviewer checks the data an Agent extracted before a Function processes it.
+Original streaming execution can stream selected outputs before the pause. A legacy streaming resume can stream the remaining selected outputs. This does not change v2 resume's JSON/async behavior.
 
-## Outputs
+## Multiple approval steps
 
-| Output | What it is |
-| --- | --- |
-| `url` | The approval portal URL |
-| `resumeEndpoint` | The resume API endpoint |
-| `response` | The display data shown to the approver |
-| `submission` | The approver's form submission |
-| `submittedAt` | ISO timestamp of when the run resumed |
-| `<fieldName>` | Each Resume Form field, by name, after the run resumes |
+<WorkflowPreview workflow={HITL_MULTISTAGE_WORKFLOW} />
 
-Read them downstream as `<blockName.output>` — for a block named `approval`, that's `<approval.approved>`.
+Check the manager's decision before asking the director, and check the director's decision before the final action. Earlier workflow steps have already run; only the remaining action is gated.
 
-## The approval portal
+## Review extracted data
 
-The example below shows an approval portal as seen by an approver after the workflow is paused. Approvers can review the data and provide inputs as a part of the workflow resumption. The approval portal can be accessed directly via the unique URL, `<blockId.url>`.
+<WorkflowPreview workflow={HITL_VALIDATE_WORKFLOW} />
 
-<div className="mx-auto w-full overflow-hidden rounded-lg my-6">
-  <Video src="hitl-resume.mp4" width={700} height={450} />
-</div>
+Show the Agent's extracted fields and let a reviewer correct them through Resume Form before Function processes the submitted values.
 
-## Related Blocks
+## Related docs
 
-- **[Condition](/workflows/blocks/condition)** - Branch based on approval decisions
-- **[Variables](/workflows/blocks/variables)** - Store approval history and metadata
-- **[Response](/workflows/blocks/response)** - Return workflow results to API callers
+- [Condition](/workflows/blocks/condition)
+- [Workflow streaming](/workflows/deployment/agent-events)
+- [API deployment](/workflows/deployment/api)
diff --git a/apps/docs/content/docs/workflows/blocks/logs.mdx b/apps/docs/content/docs/workflows/blocks/logs.mdx
index 8d0d47ad8f3..6d12b0a3fb3 100644
--- a/apps/docs/content/docs/workflows/blocks/logs.mdx
+++ b/apps/docs/content/docs/workflows/blocks/logs.mdx
@@ -1,58 +1,59 @@
 ---
 title: Logs
+description: Query run IDs and read protected run details in the current workspace.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { FAQ } from '@/components/ui/faq'
-
-The Logs block queries workflow run logs in the current workspace and fetches full details for individual runs — the same data you see on the Logs page, available to your workflows.
-
-## Operations
-
-<Tabs items={['Query Logs', 'Get Run Details']}>
-  <Tab>
-    <p>Find runs matching a set of filters. Returns only the matching <strong>run IDs</strong>, ordered newest-first by default.</p>
-    <ul className="list-disc space-y-1 pl-6">
-      <li><strong>Workflows</strong>: select specific workflows, or leave empty for all (comma-separated IDs in advanced mode)</li>
-      <li><strong>Status</strong>: info, error, running, pending, cancelled (empty for all)</li>
-      <li><strong>Time Range</strong>: presets from the past 30 minutes to the past 30 days, or explicit ISO start/end dates in advanced mode</li>
-      <li><strong>Cost</strong>: compare run cost against a credit threshold (e.g. ≥ 10 credits)</li>
-      <li><strong>Duration</strong>: compare run duration against a millisecond threshold</li>
-      <li><strong>Limit</strong>: maximum run IDs to return (default 100, max 200)</li>
-    </ul>
-  </Tab>
-  <Tab>
-    <p>Fetch everything about a single run by its run ID:</p>
-    <ul className="list-disc space-y-1 pl-6">
-      <li><strong>runId</strong>, <strong>workflowId</strong>, <strong>workflowName</strong></li>
-      <li><strong>status</strong>, <strong>trigger</strong>, <strong>startedAt</strong>, <strong>durationMs</strong></li>
-      <li><strong>cost</strong>: run cost in credits</li>
-      <li><strong>traceSpans</strong>: the full trace — per-block inputs, outputs, timings, and tool calls</li>
-      <li><strong>finalOutput</strong>: the run's final output</li>
-    </ul>
-  </Tab>
-</Tabs>
-
-## Typical Pattern
-
-Query for the runs you care about, then loop over the returned IDs and fetch details for each:
-
-1. **Query Logs** with `Status: error` and `Time Range: Past 24 hours` → `<logs1.runIds>`
-2. Loop over the IDs and call **Get Run Details** → inspect `<logs2.traceSpans>` to find the failing block
-3. Act on it — post a summary to Slack, file a ticket, or feed the trace to an Agent block for diagnosis
-
-This pairs naturally with the [Sim trigger](/workflows/triggers/sim): the trigger hands you the `runId` that fired the event, and Get Run Details gives you the full trace.
-
-<Callout type="info">
-  The block always operates on the current workspace. Costs are denominated in credits, both for
-  the cost filter and the cost output. **Get Run Details** is a log-read path, so both `traceSpans`
-  and `finalOutput` come from the protected log-facing projection described under
-  [Execution log protection](/platform/credentials#execution-log-protection). The underlying runtime
-  result remains unchanged.
-</Callout>
-
-<FAQ items={[
-  { question: "Why does Query Logs only return run IDs?", answer: "To keep payloads small and predictable. Run summaries can be large — fetch only the runs you actually need with Get Run Details." },
-  { question: "How far back can I query?", answer: "As far as your plan's log retention. Free plans retain logs for 7 days; paid plans retain them indefinitely." },
-]} />
+The **Logs block** finds workflow runs in the current workspace and reads their details. Use it to investigate failures or summarize runs without loading every trace at once.
+
+## Find failed runs
+
+Name the query block **Find Runs** and the detail block **Details** so the references below match.
+
+1. Set **Operation** to **Query Logs**, **Status** to `error`, and **Time Range** to **Past 24 hours**.
+2. Pass `<findruns.runIds>` to a ForEach Loop.
+3. Inside the loop, use **Get Run Details** with `<loop.currentItem>` as **Run ID**.
+4. Inspect `<details.traceSpans>` or pass the protected trace to an Agent for diagnosis.
+
+A [Sim trigger](/workflows/triggers/sim) can supply a `runId` directly, so you can skip the query when handling a specific run event.
+
+## Configuration
+
+### Query logs
+
+Returns matching run IDs. Newest first is the default order.
+
+| Field | Behavior |
+| --- | --- |
+| **Workflows** | Select workflows, or leave empty for all. Advanced mode accepts comma-separated IDs. |
+| **Status** | Filter by `info`, `error`, `running`, `pending`, or `cancelled`; leave empty for all. |
+| **Triggers** | Select trigger types, or leave empty for all. Advanced mode accepts comma-separated types such as `api`, `schedule`, or `slack`. |
+| **Time Range** | All time or a preset from 30 minutes to 30 days. Advanced **Start Date** and **End Date** accept ISO timestamps. |
+| **Cost** | Compare cost with a credit threshold, such as at least 10 credits. |
+| **Duration** | Compare duration with a threshold in milliseconds. |
+| **Limit** | Maximum IDs returned: default 100, maximum 200. |
+| **Sort By** / **Sort Order** | Advanced sorting by date, duration, cost, or status, ascending or descending. |
+
+### Get run details
+
+Enter one **Run ID** to fetch its protected trace, final output, and run metadata.
+
+## Outputs
+
+| Operation | Outputs |
+| --- | --- |
+| **Query Logs** | `runIds`: matching IDs; `count`: IDs returned |
+| **Get Run Details** | `runId`, `workflowId`, `workflowName`, `status`, `trigger`, `startedAt`, `durationMs`, `cost`, `traceSpans`, `finalOutput` |
+
+Read a block named **Details** with references such as `<details.traceSpans>` and `<details.finalOutput>`. Costs use credits in both filters and outputs.
+
+`traceSpans` and `finalOutput` use the protected log-facing projection described in [execution log protection](/platform/credentials#execution-log-protection). They do not expose every internal runtime value or change the workflow's runtime result.
+
+## Retention
+
+Queries can only return retained logs. On Sim Cloud, Free's default log retention is 30 days; paid plans have no default expiry. Organization and workspace policies can change effective retention. Billing-disabled self-hosted deployments have no plan-based default expiry, but configured retention still applies. See [data retention](/platform/enterprise/data-retention).
+
+## Related docs
+
+- [Logs](/logs-debugging)
+- [Loop](/workflows/blocks/loop)
+- [Sim trigger](/workflows/triggers/sim)
diff --git a/apps/docs/content/docs/workflows/blocks/loop.mdx b/apps/docs/content/docs/workflows/blocks/loop.mdx
index 918cefd71d8..fe9b8a3ba29 100644
--- a/apps/docs/content/docs/workflows/blocks/loop.mdx
+++ b/apps/docs/content/docs/workflows/blocks/loop.mdx
@@ -1,118 +1,78 @@
 ---
 title: Loop
-description: The Loop block is a container that runs the blocks inside it repeatedly — over a collection, a count, or while a condition holds.
+description: Run blocks sequentially over a collection, a count, or a condition.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { Image } from '@/components/ui/image'
 import { WorkflowPreview, LOOP_WORKFLOW } from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
 
-The **Loop block** is a container that runs the blocks inside it repeatedly — over each item in a collection, a fixed number of times, or while a condition holds. Drop blocks inside it, and they run once per iteration. Iterations run **one after another**; for concurrent work, use a [Parallel](/workflows/blocks/parallel) block.
+The **Loop** container runs its blocks one iteration after another. Use [Parallel](/workflows/blocks/parallel) for independent work that can run concurrently.
 
-## Loop Types
+## Process a collection
 
-<Tabs items={['For', 'ForEach', 'While', 'Do-While']}>
-  <Tab>
-    A **For** loop runs a fixed number of times. Set the iteration count.
-
-    <div className="flex justify-center">
-      <Image src="/static/blocks/loop-1.png" alt="For loop with iterations" width={500} height={267} className="my-6" />
-    </div>
-  </Tab>
-  <Tab>
-    A **ForEach** loop runs once per item in an array or object, exposing the current item as `<loop.currentItem>`.
-
-    <div className="flex justify-center">
-      <Image src="/static/blocks/loop-2.png" alt="ForEach loop with a collection" width={500} height={273} className="my-6" />
-    </div>
-  </Tab>
-  <Tab>
-    A **While** loop runs as long as a condition is true. The condition is checked **before** each iteration, so the body may run zero times.
+<WorkflowPreview workflow={LOOP_WORKFLOW} height={340} />
 
-    <div className="flex justify-center">
-      <Image src="/static/blocks/loop-3.png" alt="While loop with a condition" width={500} height={213} className="my-6" />
-    </div>
-  </Tab>
-  <Tab>
-    A **Do-While** loop runs the body once, then repeats while a condition is true. The condition is checked **after** each iteration, so the body always runs at least once.
+Name the container **Process Reviews**, select **For Each**, and set **Collection Items** to your reviews array. Inside, the Agent reads `<loop.currentItem>`. After it finishes, the summary reads `<processreviews.results>`.
 
-    <div className="flex justify-center">
-      <Image src="/static/blocks/loop-4.png" alt="Do-While loop with a condition" width={500} height={210} className="my-6" />
-    </div>
-  </Tab>
-</Tabs>
+## Loop types and settings
 
-## Configuration
+| Type | Setting | Behavior |
+| --- | --- | --- |
+| **For Loop** | **Loop Iterations** | Run a fixed count. |
+| **For Each** | **Collection Items** | Run once per item in an array or object. |
+| **While Loop** | **While Condition** | Check before each iteration; the body can run zero times. |
+| **Do While Loop** | **While Condition** | Run once, then check whether to repeat. Without a condition, saved fixed-count configuration is used. |
 
-Set the loop type, then the value it needs:
+While conditions are boolean expressions. Calculate updates with Function and assign them with Variables when maintaining a counter:
 
-- **Iterations** — how many times to run (For loops)
-- **Collection** — the array or object to iterate (ForEach loops)
-- **Condition** — the boolean expression to check (While and Do-While loops)
+```javascript
+return <variable.i> + 1;
+```
 
-## Referencing loop data
+Set `i` to that Function's result before the next condition check. A Variables field does not evaluate `i + 1` itself.
 
-References differ inside the loop and after it.
+## References and outputs
 
-<Tabs items={['Inside loop', 'After loop']}>
-  <Tab>
-    Inside the loop, read the current iteration with `<loop.*>`:
+Inside a loop, generic references select the current loop context:
 
-    - `<loop.index>` — the iteration number, starting at 0
-    - `<loop.currentItem>` — the current item (ForEach only)
-    - `<loop.items>` — the full collection (ForEach only)
+| Reference | Value |
+| --- | --- |
+| `<loop.index>` | Iteration index, starting at 0 |
+| `<loop.currentItem>` | Current item, for For Each |
+| `<loop.items>` | Full collection, for For Each |
 
-    ```javascript
-    const idx = <loop.index>;        // 0, 1, 2, ...
-    const item = <loop.currentItem>; // the current item
-    ```
+Arrays yield their values as `currentItem`. Objects yield `[key, value]` pairs: `{ "a": 10 }` produces `currentItem` equal to `["a", 10]`. Read the key with `<loop.currentItem[0]>` and the value with `<loop.currentItem[1]>`.
 
-    <Callout type="info">
-      These are only available to blocks inside the loop container.
-    </Callout>
-  </Tab>
-  <Tab>
-    After the loop, read the collected results by the loop block's name — not `<loop.*>`:
+After the loop, reference its normalized block name, such as `<processreviews.results>`. Generic `<loop.*>` references require an enclosing loop and do not select a completed container by its display name. Names are lowercased with whitespace and periods removed; `loop`, `parallel`, and `variable` are reserved names for new blocks.
 
-    ```javascript
-    // a loop named "Process Items"
-    const all = <processitems.results>; // [result1, result2, ...]
-    ```
+Results group the inner block outputs by iteration. For a single Agent in each iteration, an abbreviated result is:
 
-    <Callout type="info">
-      The name is normalized — lowercase, no spaces. `<loop.*>` only works inside.
-    </Callout>
-  </Tab>
-</Tabs>
+```json
+[
+  [{ "content": "First review score" }],
+  [{ "content": "Second review score" }]
+]
+```
 
-## Examples
+Use `<processreviews.results[0][0].content>` for the first iteration's first block result. Additional blocks can contribute additional outputs per iteration.
 
-<WorkflowPreview workflow={LOOP_WORKFLOW} height={340} />
+## Behavior and limits
 
-A ForEach loop scores each review and collects the results; after the loop finishes, an Agent summarizes `<loop.results>`. The same container holds the blocks for any loop type:
+For uses the configured count; For Each uses the collection length. `1,000` is an execution default for some saved count configurations, not a hard ceiling. Overall workflow execution limits still apply.
 
-- **Process API results** — `API (Fetch) → Loop (ForEach) → Agent (Analyze) → Function (Store)`
-- **Generate variations** — `Loop (5×) → Agent (Generate) → Evaluator (Score) → Function (Select best)`
-- **Counter with While** — `Variables (i=0) → Loop (While i<10) → Agent (Process) → Variables (i++)`
+An empty array skips the body and returns empty results. Missing, null, or empty-string collection configuration is an error rather than an empty iteration set.
 
-## Nesting and limits
+While and conditional Do While have no fixed iteration ceiling. Ensure the condition eventually becomes false. Iterations add sequential execution time; connect error paths inside the loop when an item failure should be handled.
 
-<Callout type="info">
-  Containers nest. You can place loops inside loops, parallels inside loops, and any combination, to build multi-dimensional workflows.
-</Callout>
+Loops and Parallel containers can nest in either direction. Use the reference picker for the appropriate container scope in a nested flow.
 
-For and ForEach loops are capped at **1,000 iterations**. While and Do-While loops run until their condition is false, with no hard cap — make sure the condition eventually becomes false so the loop ends.
+## Other patterns
 
-## Best Practices
+- Fetch API results, process each item, then summarize the collected results.
+- Generate a fixed number of variations and evaluate each one.
+- Repeat a polling step while a status is incomplete, with a Wait between checks.
 
-- **Use ForEach for collections.** When you have an array or object, ForEach is clearer than a For loop with manual indexing.
-- **Keep iteration counts reasonable.** Each iteration adds to total run time, since the loop runs sequentially.
-- **Reach for Parallel when order doesn't matter.** Independent work over a collection runs faster in a [Parallel](/workflows/blocks/parallel) block.
-- **Guarantee an exit.** For While and Do-While loops, make sure the condition will become false.
+## Related docs
 
-<FAQ items={[
-  { question: "What is the maximum number of iterations a loop can run?", answer: "For and ForEach loops are capped at 1,000 iterations. While and Do-While loops with a condition have no hard cap — they run until the condition is false. A Do-While without a condition falls back to a fixed count, also capped at 1,000. Always ensure While/Do-While conditions eventually become false to avoid infinite loops." },
-  { question: "What happens if a ForEach loop receives an empty collection?", answer: "The body is skipped and the loop outputs an empty results array. The workflow continues to whatever is connected after the loop." },
-]} />
+- [Parallel](/workflows/blocks/parallel)
+- [Variables](/workflows/blocks/variables)
+- [Connections](/workflows/connections)
diff --git a/apps/docs/content/docs/workflows/blocks/meta.json b/apps/docs/content/docs/workflows/blocks/meta.json
index 8b5cd58012a..30122a9e47c 100644
--- a/apps/docs/content/docs/workflows/blocks/meta.json
+++ b/apps/docs/content/docs/workflows/blocks/meta.json
@@ -1,5 +1,5 @@
 {
-  "title": "Core Blocks",
+  "title": "Core blocks",
   "pages": [
     "agent",
     "api",
diff --git a/apps/docs/content/docs/workflows/blocks/parallel.mdx b/apps/docs/content/docs/workflows/blocks/parallel.mdx
index 0a2e0c613d2..39d8afdd2df 100644
--- a/apps/docs/content/docs/workflows/blocks/parallel.mdx
+++ b/apps/docs/content/docs/workflows/blocks/parallel.mdx
@@ -1,102 +1,68 @@
 ---
 title: Parallel
-description: The Parallel block is a container that runs the block inside it concurrently — once per item or a fixed number of times.
+description: Run copies of a contained flow concurrently, in bounded batches.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { Image } from '@/components/ui/image'
 import { WorkflowPreview, PARALLEL_WORKFLOW } from '@/components/workflow-preview'
 
-The **Parallel block** is a container that runs the block inside it concurrently — once per item in a collection, or a fixed number of times. It is the concurrent counterpart to a [Loop](/workflows/blocks/loop): reach for it when the work is independent and order doesn't matter.
+The **Parallel** container runs its blocks for multiple items or instances concurrently. Use it when the work is independent; use [Loop](/workflows/blocks/loop) when iterations must run in sequence.
 
-## Parallel Types
+## Process tasks in batches
 
-<Tabs items={['Count-based', 'Collection-based']}>
-  <Tab>
-    Runs a fixed number of identical instances at once. If the count is larger than the batch size, Sim runs serial batches and preserves the original result order.
-
-    <div className="flex justify-center">
-      <Image src="/static/blocks/parallel-1.png" alt="Count-based parallel execution" width={500} height={231} className="my-6" />
-    </div>
-  </Tab>
-  <Tab>
-    Distributes a collection across instances — each one processes a single item as `<parallel.currentItem>`. Large collections run in serial batches, preserving each item's index.
+<WorkflowPreview workflow={PARALLEL_WORKFLOW} height={340} />
 
-    <div className="flex justify-center">
-      <Image src="/static/blocks/parallel-2.png" alt="Collection-based parallel execution" width={500} height={220} className="my-6" />
-    </div>
-  </Tab>
-</Tabs>
+Name the container **Process Tasks** and distribute a task array. The inner API reads `<parallel.currentItem>`. After every batch finishes, the Function reads `<processtasks.results>`.
 
 ## Configuration
 
-Set the parallel type, then the value it needs:
-
-- **Count** — how many instances to run (count-based)
-- **Collection** — the array or object to distribute (collection-based)
-- **Batch size** — how many branches run at once, from 1 to 20 (default 20). Lower it to ease off rate-limited APIs
+| Setting | Behavior |
+| --- | --- |
+| **Parallel Count** | Run a configured number of copies of the contained flow. |
+| **Parallel Each** | Distribute an array or object across instances. |
+| **Parallel Batch Size** | Concurrent branches, from 1 to 20; default 20. |
 
-## Referencing parallel data
+Counts or collections larger than Parallel Batch Size run in serial batches. Lower Parallel Batch Size for rate-limited APIs. A Wait within each branch spaces that branch's work, but does not impose a global request rate across all branches or runs.
 
-References differ inside the parallel and after it.
+## References and outputs
 
-<Tabs items={['Inside parallel', 'After parallel']}>
-  <Tab>
-    Inside, read this instance's context with `<parallel.*>`:
+Inside the container:
 
-    - `<parallel.index>` — the instance number, starting at 0
-    - `<parallel.currentItem>` — this instance's item (collection-based only)
-    - `<parallel.items>` — the full collection (collection-based only)
+| Reference | Value |
+| --- | --- |
+| `<parallel.index>` | Instance index, starting at 0 |
+| `<parallel.currentItem>` | Current item, for collection-based execution |
+| `<parallel.items>` | Full collection, for collection-based execution |
 
-    <Callout type="info">
-      These are only available to blocks inside the parallel container.
-    </Callout>
-  </Tab>
-  <Tab>
-    After it finishes, read the collected results by the block's name — not `<parallel.*>`:
+Arrays yield their values as `currentItem`. Objects yield `[key, value]` pairs, so `<parallel.currentItem[0]>` is the key and `<parallel.currentItem[1]>` is its value.
 
-    ```javascript
-    // a parallel named "Process Tasks"
-    const all = <processtasks.results>; // [result1, result2, ...]
-    ```
+After completion, use the container's normalized name: `<processtasks.results>`. Generic `<parallel.*>` references select an enclosing parallel context, not a completed container outside it.
 
-    For large result sets, reference just the entry or field you need, like `<processtasks.results[10][0].id>` — Sim keeps results indexable and hydrates oversized entries only when an indexed path is referenced.
-  </Tab>
-</Tabs>
+Results retain input/instance order, even when branches finish out of order. Each entry contains that branch's block outputs. For a single API per branch, read a field with `<processtasks.results[10][0].data.id>`. Indexed paths hydrate oversized entries only when needed.
 
-Each instance runs in isolation: a separate variable scope, no shared state, and a failure in one instance doesn't stop the others.
+## State and failures
 
-## Examples
-
-<WorkflowPreview workflow={PARALLEL_WORKFLOW} height={340} />
+Each branch has its own item, index, and block outputs. Workflow variables are shared across branches; they are not an isolated per-branch store.
 
-A collection-based Parallel calls an endpoint for each task at the same time, and a Function aggregates `<parallel.results>` after they finish. The same container holds the block for either type:
+<Callout type="warn">
+Avoid concurrent writes to the same workflow variable. An unhandled branch error fails the run and stops new work from starting, though already-running branches may finish. Connect an error path inside the container when other items should continue.
+</Callout>
 
-- **Batch API processing** — `Parallel (Collection) → API (Call Endpoint) → Function (Aggregate)`
-- **Multi-model processing** — `Parallel (["model-a", "model-b", "model-c"]) → Agent → Evaluator (Select best)`
+An empty collection skips the body and returns empty results. Parallel and Loop containers can nest in either direction; use the reference picker to select the intended scope.
 
-## Parallel vs Loop
+## Parallel or Loop
 
-| Feature | Parallel | Loop |
+| Behavior | Parallel | Loop |
 | --- | --- | --- |
-| **Execution** | Concurrent | Sequential |
-| **Completion order** | Not guaranteed | Sequential |
-| **Result order** | Input/instance order | Iteration order |
-| **Best for** | Independent work | Dependent steps |
-| **Resource use** | Higher | Lower |
-
-## Nesting and limits
-
-<Callout type="info">
-  Containers nest. You can place parallels inside parallels, loops inside parallels, and any combination, to build multi-dimensional workflows.
-</Callout>
+| Execution | Concurrent within each batch | Sequential |
+| Completion order | Can differ from input order | Iteration order |
+| Result order | Input/instance order | Iteration order |
+| Use when | Each item can stand alone | Later iterations depend on earlier work |
 
-A Parallel runs up to **20 branches at a time**. Larger counts or collections run in serial batches once the current batch finishes. Because instances run concurrently, watch for API rate limits and memory use on large datasets.
+A Parallel can compare the same prompt across several models or call an API for each record. Bound concurrency and collection size according to provider limits and the workflow's execution budget.
 
-## Best Practices
+## Related docs
 
-- **Use it for independent work only.** Instances can't share state, so each one must stand alone.
-- **Mind rate limits.** Lower the batch size, or add a [Wait](/workflows/blocks/wait), for API-heavy work.
-- **Handle errors per instance.** One failure won't stop the others, so each instance should handle its own.
-- **Separate result order from completion order.** Results retain input/instance order even when branches finish out of order. Use Loop when the work itself must happen sequentially.
+- [Loop](/workflows/blocks/loop)
+- [Wait](/workflows/blocks/wait)
+- [Variables](/workflows/blocks/variables)
diff --git a/apps/docs/content/docs/workflows/blocks/pi.mdx b/apps/docs/content/docs/workflows/blocks/pi.mdx
index 0e833112eff..3a2c1876034 100644
--- a/apps/docs/content/docs/workflows/blocks/pi.mdx
+++ b/apps/docs/content/docs/workflows/blocks/pi.mdx
@@ -1,16 +1,16 @@
 ---
-title: Pi Coding Agent
-description: The Pi Coding Agent block runs an autonomous coding agent on a real repository — creating or updating a pull request, reviewing a PR, or editing files over SSH.
+title: Pi coding agent
+description: Plan repository changes, create or update a PR, review code, or edit over SSH.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { BlockPreview } from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
 
-The **Pi Coding Agent block** runs the [Pi](https://github.com/earendil-works/pi-mono) coding harness against a real repository. You give it a task and a model; it creates or updates a pull request, posts a PR review, or changes your files in place. Create PR and Update PR can optionally babysit their pull request. Create PR, Update PR, and Local Dev can reuse your [skills](/agents/skills) and multi-turn [memory](#memory-create-pr--update-pr--local-dev). Review Code deliberately loads neither.
+The **Pi Coding Agent block** runs the [Pi](https://github.com/earendil-works/pi-mono) coding harness against a real repository. You give it a task and a model; it creates or updates a pull request, posts a PR review, or changes your files in place. Create PR and Update PR can optionally babysit their pull request. Plan, Create PR, Update PR, and Local Dev can reuse your [skills](/agents/skills) and multi-turn [memory](#memory-create-pr--update-pr--local-dev). Review Code deliberately loads neither.
 
-It has four modes that decide *where* it runs and *how* its work lands:
+It has five modes that decide *where* it runs and *how* its work lands:
 
+- **Plan** — explores a disposable repository checkout and returns a Markdown implementation plan without pushing changes or writing to GitHub.
 - **Create PR** — spins up an isolated sandbox, edits the repository, and opens a **pull request**. Its optional **Babysit Mode** requests bot reviews and works through trusted feedback and checks in bounded rounds.
 - **Update PR** — checks out an existing branch in an isolated sandbox, edits it, pushes a new commit back to that branch, then creates or updates its pull request. Its optional **Babysit Mode** continues that PR.
 - **Review Code** — checks out an existing PR in a sandbox, analyzes it with bounded read-only access across the repository, and posts a **GitHub review** (summary + optional inline comments).
@@ -18,10 +18,24 @@ It has four modes that decide *where* it runs and *how* its work lands:
 
 <BlockPreview type="pi" />
 
+## Start with a plan
+
+Select **Plan**, enter the repository owner/name and a task such as “Identify the files and steps needed to validate signup input,” then supply the GitHub and model credentials described below. Read `<pi.content>` after the run. This is a planning checkout, not an approval to merge or deploy changes.
+
 ## Modes
 
 Pick the mode with the **Mode** dropdown. The fields below it change to match.
 
+### Plan
+
+Plan clones the repository into a disposable sandbox and removes its authenticated remote. Pi can read/search, run commands or tests, and make scratch edits, but the mode has no commit/push/PR/review phase. The final Markdown plan covers the approach, relevant files, implementation steps, tests, and open risks.
+
+- Requires sandbox execution and your own provider key (BYOK), as for Create PR.
+- Needs a GitHub token with **Contents: Read** for the selected repository.
+- **Base Branch** selects the checkout; blank uses the default branch.
+- Supports selected skills, memory, and optional Internet Search.
+- Read the plan from `<pi.content>`; it does not return a PR or persisted file changes.
+
 ### Create PR
 
 Create PR runs entirely inside a disposable sandbox, so it never touches your machine. It clones the repo, lets the agent work with full read/shell/edit/git, pushes a branch, and opens a PR you review and merge.
@@ -31,7 +45,7 @@ Create PR runs entirely inside a disposable sandbox, so it never touches your ma
 - Needs a **GitHub token** with permission to clone, push, and open a PR (see [Setup](#setup-cloud-pr)).
 - The deliverable is a **pull request** — nothing is committed to your default branch directly.
 
-#### Babysit Mode
+#### Babysit mode
 
 When enabled, both modes ensure the branch has a ready-for-review PR before posting every required **Reviewer Mention** as its own issue comment and starting a second, strict sandbox against that PR. Update PR uses the exact open same-repository PR whose head is the target branch, or creates it when missing. They repeat this bounded host-controlled lifecycle:
 
@@ -65,23 +79,23 @@ Update PR uses the same disposable authoring sandbox and host-controlled PR oper
 - A no-change authoring pass still creates or updates the PR. A rejected initial push stops the run before any PR mutation or Babysit continuation.
 - The deliverable is the updated branch and its PR — read `prUrl`, `branch`, `changedFiles`, and `diff`.
 
-### Review Code
+### Review code
 
 Review Code uses a disposable sandbox for the repository, but the Pi harness and model credential stay in Sim. It pins the PR base and head commits, gives the agent only bounded read/search tools, and validates inline coordinates against that exact local diff. Sim then submits one GitHub review with a summary body and optional inline line comments.
 
-- Requires sandbox execution. The provider key stays in Sim, so hosted keys and BYOK are both supported.
+- Requires sandbox execution. The provider key stays in Sim, so supported hosted keys and BYOK can both be used.
 - Needs a **GitHub token** that can clone the repo and submit reviews (see [Setup](#setup-cloud-code-review)).
 - Needs the **Pull Request Number** to review.
 - Does not load skills or memory, and never exposes shell, write, or edit tools to the reviewer. Its only network access is [Internet Search](#internet-search), and only when you select a provider.
 - Rechecks the PR immediately before submission and pins the review to the exact checked-out head commit.
 - The deliverable is a **submitted review** — read `reviewUrl` and `commentsPosted`.
 
-### Local Dev
+### Local dev
 
 Local Dev runs the agent against a repository on a machine you control, reached over SSH. Changes are written **in place** — there's no PR; you review them as normal git changes on that machine.
 
 - The machine must be reachable on a **public hostname** — `localhost` and LAN/private addresses are blocked. Expose it with a tunnel (see [Setup](#setup-local)).
-- The agent's file and shell tools are confined to the **Repository Path** you configure.
+- File-tool paths are checked against **Repository Path**. Shell commands start there and run with the SSH account's permissions; they are not confined to that directory.
 - You can also expose **Sim tools** (Gmail, Slack, Exa, …) to the agent so it can act beyond the repo while it works.
 
 ## Configuration
@@ -94,18 +108,18 @@ What the agent should do, in plain language — for example *"Add input validati
 
 The model that drives the agent. Defaults to `claude-sonnet-4-6`. The dropdown contains the intersection of models available in Sim and exact provider-relative entries in the installed Pi catalog.
 
-### API Key
+### API key
 
-Your key for the chosen provider. On hosted Sim it is optional for Local Dev and Review Code runs (a hosted key is used and metered to your workspace). **Create PR and Update PR require your own key** because their model client runs in the sandbox, including during a Babysit continuation. When the provider supports workspace BYOK, you can store the key in **Settings → BYOK** instead of entering it on the block.
+Your key for the chosen provider. On hosted Sim it is optional for Local Dev and Review Code runs (a hosted key is used and metered to your workspace). **Plan, Create PR, and Update PR require your own key** because their model client runs in the sandbox, including during a Babysit continuation. When the provider supports workspace BYOK, you can store the key in **Settings → BYOK** instead of entering it on the block.
 
-### Internet Search
+### Internet search
 
-Off by default. Pick a provider — **Exa**, **Serper**, **Parallel AI**, or **Firecrawl** — and the agent gains a single `web_search` tool that returns a handful of results, each with a title, URL, snippet, and (where the provider reports one) a publication date. It works the same way in all four modes, and it is the agent's only network access in Review Code. The tool accepts at most 20 calls **per block execution**, which bounds accidental tool loops. A Pi block inside a Loop or Parallel gets that allowance again on every iteration, so bound the iteration count too if you care about what a single workflow run can spend.
+Off by default. Pick a provider — **Exa**, **Serper**, **Parallel AI**, or **Firecrawl** — and the agent gains a single `web_search` tool that returns a handful of results, each with a title, URL, snippet, and (where the provider reports one) a publication date. It works the same way in all five modes, and it is the agent's only network access in Review Code. The tool accepts at most 20 calls **per block execution**, which bounds accidental tool loops. A Pi block inside a Loop or Parallel gets that allowance again on every iteration, so bound the iteration count too if you care about what a single workflow run can spend.
 
 Search always uses **your own key** for the selected provider, entered in the block's **Search API Key** field. That field is the only source: there is no workspace BYOK fallback and Sim never supplies a hosted search key, so unlike the model key this field appears on every deployment. Leave it empty and the run fails with a setup error before any sandbox is created. Changing the provider in the editor clears the field, so re-enter the key that belongs to the provider you picked — a workflow you import, fork, or update through the API keeps whatever key was saved, so check it there.
 
 <Callout type="warn">
-  **Create PR exposes both keys to the agent.** Create PR runs the model client and the search client *inside* the sandbox, so the model key and the search key reach it as environment variables — and Pi copies its own environment into every shell command it runs. Your prompt, or instructions injected through the contents of the cloned repository, can therefore read either key and write it anywhere the agent can reach, including into the pull request itself. Sim strips verbatim key text out of run output, but that does not stop an agent that encodes the value first. Babysit Mode's continuation sandbox carries both keys the same way.
+  **Plan, Create PR, and Update PR expose keys to the sandbox.** These modes run the model client and the search client *inside* the sandbox, so the model key and the search key reach it as environment variables — and Pi copies its own environment into every shell command it runs. Your prompt, or instructions injected through the contents of the cloned repository, can therefore read either key and write it anywhere the agent can reach, including into the pull request itself. Sim strips verbatim key text out of run output, but that does not stop an agent that encodes the value first. Babysit Mode's continuation sandbox carries both keys the same way.
 
   This is why the search key has no **Settings → BYOK** fallback. Workspace BYOK keys belong to the workspace rather than to you — Sim only ever displays them masked, and only workspace admins can add or remove them — so resolving one here would let anyone who can run a Pi block read a credential they cannot otherwise see. Requiring the key on the block keeps the exposure to a key its author already holds. Scope it to something you are willing to rotate.
 </Callout>
@@ -114,7 +128,7 @@ Results are third-party data. The agent is instructed to treat them as quoted ev
 
 Traffic goes both ways: the agent writes its own queries after reading the repository, so leave search on **None** in Review Code when the pull request comes from an untrusted fork of a private repo. Injected instructions in a diff could otherwise put repository text into a query sent to the provider.
 
-### Repository (Create PR / Update PR / Review Code)
+### Repository (Plan / Create PR / Update PR / Review Code)
 
 - **Repository Owner / Repository Name** — the GitHub repo (for example `your-org` / `your-repo`).
 - **GitHub Token** — a personal access token used for GitHub access. Permissions differ by mode; see [Create PR setup](#setup-cloud-pr), [Update PR setup](#setup-cloud-branch), or [Review Code setup](#setup-cloud-code-review).
@@ -137,34 +151,34 @@ Traffic goes both ways: the agent writes its own queries after reading the repos
 - **PR State** *(advanced)* — preserves an existing PR's draft state, converts it to draft, or marks it ready for review. A missing PR opens as a draft for **Leave unchanged** or **Draft**, and ready for **Ready for review**. Hidden during Babysit because Babysit always requires a ready PR.
 - **PR Title / PR Body** *(advanced)* — update an existing PR only when set. For a missing PR, blank values are generated from the task and run summary.
 
-### Review Code fields
+### Review code fields
 
 - **Pull Request Number** — the PR to review (for example `42`).
 - **Review Outcome** — the GitHub review action to submit: `Comment` (default) or `Request changes`. Review Code intentionally does not submit approvals.
 
-### Connection (Local Dev)
+### SSH connection
 
 - **Host** — the public hostname or tunnel for the target machine (for example `2.tcp.ngrok.io`). Not `localhost` or a LAN address.
 - **Username** — the SSH user (for example `ubuntu`, `root`, or your macOS account).
 - **Authentication Method** — `Password` or `Private Key`.
 - **Password / Private Key** — the credential for that method. Use a key where you can.
-- **Repository Path** — the absolute path to the repo on the target machine (for example `/home/user/my-repo`). The agent's tools are confined to this directory.
+- **Repository Path** — the absolute path to the repo on the target machine (for example `/home/user/my-repo`). File-tool paths are checked against this directory. Shell commands start here with the SSH account's permissions.
 - **Port** *(advanced)* — the SSH port. Defaults to `22`; set this to your tunnel's port if it differs.
 - **Passphrase** *(advanced)* — for an encrypted private key.
 
-### Tools (Local Dev)
+### Tools for Local Dev
 
 Sim tools the agent can call while it works — search a knowledge base, send a Slack message, call any of the [integrations](/integrations). They run through Sim with your connected credentials, exactly like the [Agent block](/workflows/blocks/agent). MCP and custom tools aren't supported here yet (they appear greyed out).
 
-### Skills (Create PR / Update PR / Local Dev)
+### Skills (Plan / Create PR / Update PR / Local Dev)
 
 [Agent skills](/agents/skills) the agent can use — reusable instruction packages like a coding standard or a review playbook. They're shared with the Agent block. Create PR and Update PR pass explicitly selected Sim skills to their Babysit continuation, while repository skills, Pi extensions, prompt templates, and project trust remain disabled there.
 
-### Thinking Level
+### Thinking level
 
-For models with extended reasoning, how much the model thinks before acting. Higher is more thorough but slower and costs more tokens. Defaults to `medium`.
+For models with extended reasoning, how much the model thinks before acting. Higher settings can increase latency and token use; evaluate them on your task. Defaults to `medium`.
 
-### Memory (Create PR / Update PR / Local Dev)
+### Memory (Plan / Create PR / Update PR / Local Dev) [#memory-create-pr--update-pr--local-dev]
 
 Multi-turn memory keyed by a conversation ID, shared with the [Agent block](/workflows/blocks/agent):
 
@@ -177,12 +191,12 @@ Reuse the same **Conversation ID** across runs to continue a thread. Each turn s
 
 ### Context limits
 
-For Create PR, Update PR, and Local Dev, memory is folded into the agent's first prompt, and two layers keep it within the model's context window:
+For Plan, Create PR, Update PR, and Local Dev, memory is folded into the agent's first prompt, and two layers keep it within the model's context window:
 
 - **Sim trims before the run.** The selected memory type bounds what's injected: **Conversation** is automatically capped to a fraction of the model's context window (for models in Sim's catalog), **Sliding window (messages)** keeps the last N messages, and **Sliding window (tokens)** keeps history up to an explicit token budget.
 - **Pi compacts during the run.** As the agent works (reading files, running commands), Pi automatically summarizes older turns to stay under the window — in all modes, on by default. You don't need to configure anything for context growth mid-run.
 
-The one case neither layer can rescue is a *first* prompt that already exceeds the window — Pi can only compact once there are older turns to summarize. This is only reachable with **Conversation** memory plus a model typed in manually (not in Sim's catalog), where the automatic cap can't look up a context window. For long histories — and whenever you use a manually entered model — choose **Sliding window (tokens)**: its budget applies regardless of the model. Leave room for the task prompt, tool definitions, and generated output.
+The one case neither layer can rescue is a *first* prompt that already exceeds the window — Pi can only compact once there are older turns to summarize. A large task or selected skills can exceed the first-prompt budget too. Manually entered models without a catalog context window also lack Conversation's model-based cap. For long histories — and whenever you use a manually entered model — choose **Sliding window (tokens)**: its budget applies regardless of the model. Leave room for the task prompt, tool definitions, and generated output.
 
 ## Outputs
 
@@ -203,20 +217,28 @@ The one case neither layer can rescue is a *first* prompt that already exceeds t
 | `<pi.stopReason>` | Why the Babysit continuation stopped, including partial-success outcomes *(authoring + Babysit Mode)* |
 | `<pi.model>` | The model that ran |
 | `<pi.tokens>` | Token usage, an object `{ input, output, total }` |
-| `<pi.cost>` | Estimated cost of the run |
+| `<pi.cost>` | Estimated cost in USD, as an object with `input`, `output`, and `total`; read `<pi.cost.total>` for the total |
 | `<pi.providerTiming>` | Timing, an object `{ startTime, endTime, duration }` |
 
+Pi's total can include sandbox cost in addition to model usage. The Logs UI and run-resource API use credits. See [Costs](/platform/costs) for units and billing behavior.
+
 ## Setup
 
+### Plan
+
+Enable the Pi sandbox as below and supply a provider BYOK key. For private repositories, use a GitHub token with **Contents: Read**; no pull-request write permission is needed for Plan. The model and optional search keys enter the sandbox, so use appropriately scoped keys.
+
 ### Create PR [#setup-cloud-pr]
 
 Create PR runs in a sandbox image with the Pi CLI, Git, Node.js, and Bun baked in. Repository dependencies are not preinstalled; Pi can run `bun install` when a repository needs them.
 
-1. **Enable sandbox execution.** On self-hosted Sim, set `E2B_ENABLED=true`, `E2B_API_KEY`, `E2B_PI_TEMPLATE_ID` (the Pi template id), and `NEXT_PUBLIC_E2B_ENABLED=true` (this reveals Create PR, Update PR, and Review Code in the UI). Build the template with `bun run apps/sim/scripts/build-pi-e2b-template.ts`. These modes stay hidden until `NEXT_PUBLIC_E2B_ENABLED` is set.
+1. **Enable sandbox execution.** On self-hosted Sim, set `E2B_ENABLED=true`, `E2B_API_KEY`, `E2B_PI_TEMPLATE_ID` (the Pi template id), and `NEXT_PUBLIC_E2B_ENABLED=true` (this reveals Plan, Create PR, Update PR, and Review Code in the UI). Build the template with `bun run apps/sim/scripts/build-pi-e2b-template.ts`. These modes stay hidden until `NEXT_PUBLIC_E2B_ENABLED` is set.
+
+   The repository template requests **4 vCPU and 8 GiB of RAM**. Confirm your account’s build and session limits against [E2B pricing](https://e2b.dev/pricing); account limits can be lower than Sim’s requested lifetime. Sizing is fixed when the template is built — E2B has no per-sandbox override — so changing it means rebuilding the template, not restarting Sim. Sandboxes are billed per second against the resources they are allocated, not the ones they use. Both numbers live in `apps/sim/scripts/pi-sandbox-packages.ts` and are shared with the Daytona snapshot so the failover image cannot drift from the primary.
 
-   The template requests **4 vCPU and 8 GB of RAM** (within the per-build maximum on every E2B plan). Sizing is fixed when the template is built — E2B has no per-sandbox override — so changing it means rebuilding the template, not restarting Sim. Sandboxes are billed per second against the resources they are allocated, not the ones they use. Both numbers live in `apps/sim/scripts/pi-sandbox-packages.ts` and are shared with the Daytona snapshot so the failover image cannot drift from the primary.
+   When a run has an execution deadline, Sim caps the requested sandbox lifetime at its remaining time. Without a known deadline, it uses the selected provider's configured ceiling. Sim imposes a 24-hour ceiling on one E2B Pi sandbox even when an Enterprise workflow policy is longer; your E2B account can impose a shorter limit. `PI_SANDBOX_LIFETIME_MS` can lower the configured ceiling but has a **31-minute minimum**; lower overrides are raised to that minimum before the run's remaining time is applied. Both adapters enforce an absolute lifetime: E2B uses milliseconds, while Daytona rounds its TTL up to a whole minute.
 
-   Sim sizes each Pi sandbox to **the execution's own remaining time**, so a run never holds a sandbox longer than the platform would let it run. E2B also imposes a 24-hour continuous-sandbox ceiling on the Professional plan, so one Pi sandbox is capped there even when an Enterprise workflow policy is longer. `PI_SANDBOX_LIFETIME_MS` may lower that ceiling but has a **31-minute minimum**; lower values are raised to the minimum. A run that outlives the sandbox loses its work before the push, and an orphaned sandbox — one whose Sim process died mid-run — bills until the lifetime expires, which is why that lifetime tracks the deadline. Babysit Mode uses a second sequential sandbox after the creation sandbox has been destroyed; it is billed while polling checks and reviews. Daytona remains unchanged because its auto-stop setting is inactivity-based rather than an absolute lifetime.
+   A sandbox that expires before the push can lose uncommitted work. Normal completion destroys it; an orphan whose Sim process died mid-run can bill until its lifetime expires. Babysit Mode uses a second sequential sandbox after the creation sandbox has been destroyed and is billed while polling checks and reviews.
 2. **Bring your own model key.** Set the provider API key in the block's API Key field, or store it in **Settings → BYOK** when the provider supports workspace BYOK.
 3. **Create a GitHub token** with permission to clone, push, and open a PR:
    - *Fine-grained:* select the repo, then **Contents: Read and write** + **Pull requests: Read and write**.
@@ -248,28 +270,27 @@ The target branch must already exist. GitHub branch protection remains authorita
 
 Update PR accepts one exact open same-repository PR for the target branch, creates one when none exists, and fails if the match is ambiguous. It does not support fork PRs. With **Babysit Mode**, the token also needs the Issues, Actions, commit-status, and check permissions listed above.
 
-### Review Code [#setup-cloud-code-review]
+### Review code [#setup-cloud-code-review]
 
 Enable sandbox execution as for Create PR. BYOK is optional because the model credential remains in Sim. The GitHub token needs enough access to clone the repo and submit a review — push permission is not required:
 
 - *Fine-grained:* select the repo, then **Contents: Read** + **Pull requests: Read and write**.
 - *Classic:* the **`repo`** scope (or a narrower token that can read contents and write pull-request reviews). For org repos, authorize the token for SSO.
 
-### Local Dev [#setup-local]
+### Local dev [#setup-local]
 
 1. **Enable SSH** on the target machine (on macOS: System Settings → General → Sharing → Remote Login).
 2. **Expose it on a public host.** Sim blocks `localhost`/LAN, so use a TCP tunnel — for example `ngrok tcp 22`, which gives a `host:port` to put in **Host** and **Port**.
 3. **Use a model your provider supports** (for example a Claude model with an Anthropic key). Set the credential method and **Repository Path**, then run.
 
-## Best Practices
+## Model and SSH constraints
+
+The model selector offers the intersection of Sim's catalog and exact provider-relative entries in the installed Pi catalog. Providers needing richer configuration, OAuth-only model authentication, or a supplied base URL are not offered.
+
+Local Dev requires a public hostname: localhost, LAN, private, and reserved addresses—including Tailscale's private 100.x addresses—are blocked. Use key authentication and a dedicated SSH account with only the access the task needs, and stop public tunnels after the run.
 
-- **Scope the task.** A specific instruction ("fix the failing `auth` test and add a regression case") produces far better results than a vague one.
-- **Match the mode to the deliverable.** Create PR for a new reviewable branch, Update PR for continuing existing remote work and managing its PR, Review Code for feedback on a PR, and Local Dev for a repo you already have checked out.
-- **Use Babysit Mode for automated review follow-through.** Run it asynchronously and expect partial success; a pushed fix followed by `awaiting_checks` is normal.
-- **Prefer key auth and tear down tunnels.** A public SSH tunnel is a real attack surface — use a private key and stop the tunnel when you're done.
-- **Reuse a Conversation ID for Create PR, Update PR, or Local Dev follow-ups.** It carries the prior task and outcome into the next run so the agent can build on its own work.
+## Related docs
 
-<FAQ items={[
-  { question: "Which models can I use?", answer: "The model dropdown contains models that are both available in Sim and present under the exact provider in the installed Pi catalog. Providers that need richer configuration, OAuth-only authentication, or a user-supplied base URL aren't offered." },
-  { question: "Why does Local Dev need a public hostname?", answer: "Sim connects over raw SSH and blocks localhost, LAN, and private/reserved addresses for safety. Expose the machine with a TCP tunnel such as `ngrok tcp 22` and use the tunnel's host and port. Tailscale's private 100.x addresses won't work for the same reason." },
-]} />
+- [Agent skills](/agents/skills)
+- [Sandbox setup](/platform/self-hosting/sandboxes)
+- [Credentials](/platform/credentials)
diff --git a/apps/docs/content/docs/workflows/blocks/response.mdx b/apps/docs/content/docs/workflows/blocks/response.mdx
index db61bfb17fb..2ffcda9462f 100644
--- a/apps/docs/content/docs/workflows/blocks/response.mdx
+++ b/apps/docs/content/docs/workflows/blocks/response.mdx
@@ -1,34 +1,26 @@
 ---
 title: Response
-description: The Response block ends an API-triggered workflow and returns a structured HTTP response.
+description: End a run with a selected response body, status, and headers.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import {
-  BlockPreview,
-  WorkflowPreview,
-  RESPONSE_API_WORKFLOW,
-  RESPONSE_ERROR_WORKFLOW,
-  RESPONSE_WEBHOOK_WORKFLOW,
-} from '@/components/workflow-preview'
+import { BlockPreview, WorkflowPreview, RESPONSE_API_WORKFLOW, RESPONSE_ERROR_WORKFLOW } from '@/components/workflow-preview'
 
-The **Response block** ends a workflow and returns a structured HTTP response to the caller. Use it with an [API deployment](/workflows/deployment/api) to control the exact body, status code, and headers that come back.
+The **Response block** ends a workflow with a response you define. It controls the custom HTTP response on API surfaces that support block-defined responses; the v2 API keeps its own run-result envelope and HTTP contract.
 
 <BlockPreview type="response" />
 
-<Callout type="info">
-A Response block is an **exit point**. When one runs, the workflow ends and the HTTP response is sent immediately. You can place several on different branches (after a [Router](/workflows/blocks/router) or [Condition](/workflows/blocks/condition)); the first to run determines the response.
-</Callout>
+## Return an answer
 
-## Configuration
+<WorkflowPreview workflow={RESPONSE_API_WORKFLOW} />
 
-### Response Data Mode
+Set the response body to include `<agent.content>` and status to `200`. See [API deployment](/workflows/deployment/api) for the response format of the endpoint you call.
 
-**Builder** lays out the response body field by field with types; **Editor** is a raw JSON code editor. Builder fits most cases.
+## Configuration
 
-### Response Data
+### Response data mode
 
-The body sent back, as JSON. Reference any earlier value: a block output like `<agent.content>` with a [connection tag](/workflows/connections), or a [workflow variable](/workflows/variables) like `<variable.userId>`. Nest objects and arrays freely.
+**Builder** defines typed fields in **Response Structure**. **Editor** uses **Response Data**, a JSON editor. Both can reference earlier block outputs and workflow variables:
 
 ```json
 {
@@ -38,51 +30,34 @@ The body sent back, as JSON. Reference any earlier value: a block output like `<
 }
 ```
 
-### Status Code
-
-Any valid HTTP status code; defaults to `200`. Set `4xx` or `5xx` on error branches (`201` created, `400` bad request, `404` not found, `500` server error).
+Nested objects and arrays are supported. Build branch-specific responses from values produced on that branch; a known block that did not run has no output.
 
-### Response Headers
+### Status code and headers
 
-Extra response headers, as key-value pairs:
+**Status Code** defaults to `200`. Use success or error statuses that match the outcome, such as `201`, `400`, `404`, or `500`.
 
-| Key | Value |
-| --- | --- |
-| Content-Type | application/json |
-| Cache-Control | no-cache |
-| X-API-Version | 1.0 |
+**Response Headers** accepts key-value pairs, for example `Cache-Control: no-cache` or `X-API-Version: 1.0`.
 
-HTTP responses always use `Content-Type: application/json` and `X-Content-Type-Options: nosniff`. Headers that set cookies, redirect the browser, change security or CORS policies, or control the HTTP transport are ignored. Ordinary custom headers and cache directives are preserved.
+Custom HTTP responses are serialized as JSON with `Content-Type: application/json` and `X-Content-Type-Options: nosniff`. Cookie, redirect, security-policy, CORS, and transport headers are ignored. Ordinary custom headers and cache directives are preserved. The selected API surface can apply additional response rules.
 
-## Outputs
+## Terminal behavior
 
-A Response block is a terminal block, so nothing reads from it. Its `data`, `status`, and `headers` become the HTTP response itself. A workflow with no Response block returns its last block's output by default; add a Response block when you need exact HTTP control.
+The first Response block to run fixes the final output and ends the workflow. Its `data`, `status`, and `headers` describe the selected response; no downstream block runs after it. Without a Response block, terminal block output determines the final result. Multiple terminal branches can finish in different orders, so use a Response when the API needs an explicit result.
 
 <Callout type="warn">
-Don't place a Response block in [parallel](/workflows/blocks/parallel) with blocks that have important side effects. Order across parallel branches is non-deterministic, so the Response may fire before or after them on any given run.
+Avoid Response on a parallel branch alongside important side effects. Other branches may already have run, still be running, or never start when the response ends the run.
 </Callout>
 
-## Examples
-
-### Return data from an API endpoint
-
-<WorkflowPreview workflow={RESPONSE_API_WORKFLOW} />
-
-The Response block reads `<agent.content>` into its body and returns `200` to the API caller.
-
-<Callout type="info">
-A [Webhook trigger](/workflows/triggers/webhook) acknowledges the request after queueing the run. Configure that trigger's response to customize the acknowledgement; a downstream Response block does not change it.
-</Callout>
+A [Webhook trigger](/workflows/triggers/webhook) acknowledges its request after queueing the run. Configure the trigger's response to change that acknowledgement; a downstream Response block does not change it.
 
-### Return a different status per branch
+## Return a status for each outcome
 
 <WorkflowPreview workflow={RESPONSE_ERROR_WORKFLOW} />
 
-A Condition routes valid requests to a `200` Response and invalid ones to a `400`. The first Response to run determines what the caller gets.
+Connect a Condition's valid branch to a `200` response and invalid branch to a `400` response. Keep a consistent body shape across both outcomes.
 
-## Best Practices
+## Related docs
 
-- **Use accurate status codes.** `2xx` for success, `4xx`/`5xx` for errors, set per branch.
-- **Keep a consistent response shape** across your endpoints so callers can rely on it.
-- **Return a different response per outcome.** Put a Response on each branch after a Condition or Router.
-- **Check your references resolve.** A connection tag pointing at a block that did not run comes back empty, so set fields on the branch that produces them.
+- [API deployment](/workflows/deployment/api)
+- [Condition](/workflows/blocks/condition)
+- [Router](/workflows/blocks/router)
diff --git a/apps/docs/content/docs/workflows/blocks/router.mdx b/apps/docs/content/docs/workflows/blocks/router.mdx
index 926a9e62799..1dd6bfe41e9 100644
--- a/apps/docs/content/docs/workflows/blocks/router.mdx
+++ b/apps/docs/content/docs/workflows/blocks/router.mdx
@@ -1,90 +1,73 @@
 ---
 title: Router
-description: The Router block uses a model to pick one of several paths based on the content it reads.
+description: Use a model to select one route from descriptions you define.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import {
-  BlockPreview,
-  WorkflowPreview,
-  ROUTER_CLASSIFY_WORKFLOW,
-  ROUTER_LEAD_WORKFLOW,
-  ROUTER_TRIAGE_WORKFLOW,
-} from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
+import { BlockPreview, WorkflowPreview, ROUTER_TRIAGE_WORKFLOW, ROUTER_CLASSIFY_WORKFLOW } from '@/components/workflow-preview'
 
-The **Router block** uses a model to choose one of several paths based on the content it reads. Each route you define adds its own output port, and the model picks the route whose description best fits. Use it when the decision needs to understand intent or unstructured text. When the decision is a plain rule, use a [Condition](/workflows/blocks/condition) instead.
+The **Router block** selects a path by matching context to route descriptions. Use it for intent or unstructured text. Use [Condition](/workflows/blocks/condition) for an exact boolean rule that needs no model tokens.
 
 <BlockPreview type="router" />
 
-<Callout type="info">
-**Router vs Condition.** A Router reads context with a model and picks a route by meaning, so it suits intent-based routing ("send this ticket to the right team") and varying text. A Condition evaluates boolean expressions with no model, so it suits structured data and exact rules. The Router costs tokens per run; the Condition is free and faster.
-</Callout>
-
-## Configuration
+## Triage a request
 
-### Context
+<WorkflowPreview workflow={ROUTER_TRIAGE_WORKFLOW} />
 
-The text the Router analyzes to decide. Usually an earlier output, like `<start.input>` or `<agent.content>`.
+Pass `<start.input>` as Context, describe Sales, Support, and Billing routes, and connect each port to its handler. Also connect the error port for requests that fit no route.
 
-### Routes
+## Configuration
 
-Each route is a **title** and a **description** of when to choose it ("Route here for pricing and purchasing questions"). Every route adds a separate output port on the block; connect each to the path for that route. The model reads the context and selects the route whose description fits best.
+| Field | Behavior |
+| --- | --- |
+| **Context** | Text to analyze, often `<start.input>` or `<agent.content>`. |
+| **Routes** | Each route has a title and a description of when to choose it. It adds a separate output port. |
+| **Model** | Defaults to `claude-sonnet-5-5`. Select a supported model, including a compatible local Ollama or vLLM model. |
 
-### Model
+Make descriptions specific and distinguishable. For example, “Payments, invoices, and refunds” separates Billing from general product support. Test the routes on representative requests rather than assuming a larger model always routes more accurately.
 
-The model that makes the decision, defaulting to `claude-sonnet-5-5`. Stronger reasoning models route more accurately; a faster, cheaper model is fine when the routes are clearly distinct. Type or pick any supported model, or a local one through Ollama or VLLM. On hosted Sim the API key is supplied for you.
+Sim Cloud supplies credentials for supported hosted models. Other models and self-hosted deployments can require your own credentials.
 
 ### Fallback models
 
-Under **Additional fields**, add up to five models to try in order when a model request fails. With **Retry on fail** enabled, the selected model exhausts its tries first; each fallback is then tried once. Every attempt uses the same context and route definitions. `<router.model>` reports the model that answered. This also works for existing legacy Router blocks.
+Under **Additional fields**, add up to five fallbacks. **Retry on fail** exhausts the selected model's attempts first; each fallback is then tried once using the same context and routes. This behavior also applies to legacy Router blocks.
 
-Hosted models on hosted Sim use workspace BYOK or platform credentials. On local or self-hosted installations, a fallback on another provider may need a secret selected on its row; same-provider fallbacks reuse the selected model's key. Auto cannot be a fallback. A completed `NO_MATCH` decision still takes the error path; it does not trigger another model request.
+Hosted models use workspace BYOK or platform credentials where available. Same-provider fallbacks reuse the selected model's key; a different provider can need a secret selected on its row. Auto cannot be a fallback. A completed `NO_MATCH` decision does not trigger another model request.
 
 ## Outputs
 
-| Output | What it is |
+| Reference | Value |
 | --- | --- |
-| `<router.selectedRoute>` | The id of the route the model chose |
-| `<router.reasoning>` | A short explanation of why it chose that route |
-| `<router.context>` | The context that was analyzed |
-| `<router.model>` | The model that decided |
+| `<router.selectedRoute>` | Selected route ID |
+| `<router.reasoning>` | Explanation of the decision |
+| `<router.context>` | Analyzed context |
+| `<router.model>` | Model that answered |
 | `<router.tokens>` | Token usage |
-| `<router.cost>` | Estimated cost of the call |
-| `<router.selectedPath>` | The destination block the workflow routed to |
-
-<Callout type="warn">
-When no route fits the context, the Router returns `NO_MATCH` and takes the [error path](/workflows/connections) rather than guessing. Connect the error path for a fallback.
-</Callout>
-
-## Examples
+| `<router.cost>` | Estimated cost in USD, as an object with `input`, `output`, and `total`; read `<router.cost.total>` for the total |
+| `<router.selectedPath>` | Destination object with `blockId`, `blockType`, and `blockTitle` |
 
-### Triage a support ticket
-
-<WorkflowPreview workflow={ROUTER_TRIAGE_WORKFLOW} />
+An unconnected route returns `selectedPath` with `blockId: ""`, `blockType: "unknown"`, and `blockTitle` set to the chosen route's title.
 
-The Router reads `<start.input>`, picks the route whose description matches, and runs only that path.
+The Logs UI and run-resource API use credits. See [Costs](/platform/costs) for units and billing behavior.
 
-### Classify feedback
+Only the selected path runs. There is no fixed route-count limit, but overlapping descriptions become harder to distinguish as routes grow.
 
-<WorkflowPreview workflow={ROUTER_CLASSIFY_WORKFLOW} />
+## Handle unmatched requests
 
-The Router sorts incoming feedback into product feedback or a bug report, each handled by its own child [Workflow](/workflows/blocks/workflow) block.
+<Callout type="warn">
+If no route fits, the model's `NO_MATCH` decision raises a routing error. Connect the error port to a fallback handler; it is not a normal successful route output.
+</Callout>
 
-### Qualify a lead
+The model is instructed to prefer a fitting route and use NO_MATCH when all routes are unrelated. This remains a model judgment, so validate routes before using them for consequential actions.
 
-<WorkflowPreview workflow={ROUTER_LEAD_WORKFLOW} />
+## Route to child workflows
 
-The Router sends enterprise leads to a sales agent and everyone else into a self-serve onboarding workflow.
+<WorkflowPreview workflow={ROUTER_CLASSIFY_WORKFLOW} />
 
-## Best Practices
+A Product route can call a product-intake workflow while Bug report calls bug triage. The same structure can separate enterprise leads from self-service onboarding.
 
-- **Write clear, specific route descriptions.** The description is what the model matches on, so make the criteria explicit.
-- **Keep routes mutually exclusive.** Overlapping descriptions make the choice ambiguous and the routing less reliable.
-- **Connect the error path.** Handle `NO_MATCH` instead of letting the run fail silently.
-- **Reach for Condition when you can.** If the decision is a boolean check on structured data, the [Condition](/workflows/blocks/condition) block is free, faster, and deterministic.
+## Related docs
 
-<FAQ items={[
-  { question: "How does the Router decide which route to take?", answer: "It sends your context and every route description to a model, which selects the route whose description best matches. The model is prompted to prefer choosing a route over returning nothing, and only returns NO_MATCH when the context is unrelated to every route." },
-  { question: "How many routes can I define?", answer: "There is no hard limit, and each route adds its own output port. Keep in mind that more routes with overlapping descriptions are harder for the model to distinguish, so aim for clear, mutually exclusive routes." },
-]} />
+- [Condition](/workflows/blocks/condition)
+- [Workflow](/workflows/blocks/workflow)
+- [Connections](/workflows/connections)
diff --git a/apps/docs/content/docs/workflows/blocks/variables.mdx b/apps/docs/content/docs/workflows/blocks/variables.mdx
index adcf1b13aa6..c68e3e7e5ee 100644
--- a/apps/docs/content/docs/workflows/blocks/variables.mdx
+++ b/apps/docs/content/docs/workflows/blocks/variables.mdx
@@ -1,55 +1,52 @@
 ---
 title: Variables
-description: The Variables block updates workflow variables during a run, read from any block by name.
+description: Update typed workflow variables during a run.
 ---
 
 import { BlockPreview, WorkflowPreview, VARIABLES_RETRY_WORKFLOW, VARIABLES_CONFIG_WORKFLOW } from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
 
-The **Variables block** updates workflow variables while a run is in progress. Variables are workflow-scoped state you create once in the workflow's Variables panel; this block changes their values as the run proceeds. Read a variable from any block with `<variable.name>`.
+The **Variables block** updates variables created in the workflow's **Variables** panel. Read their current values with `<variable.name>`. Each run starts from the panel's initial values.
 
 <BlockPreview type="variables" />
 
-## Configuration
+## Update a counter
 
-### Variable Assignments
+Create a number variable `retryCount` with initial value `0`. In the retry pattern below, failed requests increment it until the While condition becomes false; a successful request sets it to `3` to end retries.
 
-A list of assignments, run in order. The right side is an expression that can reference earlier outputs and the variable's own current value:
+Calculate the next value in a Function block named **Increment**:
 
-```
-customerEmail = <api.email>
-retryCount     = <variable.retryCount> + 1
-currentStatus  = "processing"
+```javascript
+return <variable.retryCount> + 1;
 ```
 
-The variables must already exist in the workflow's **Variables** panel, where you set their initial values.
+Then select `retryCount` in a Variables block and set its value to `<increment.result>`.
 
-## Outputs
+<WorkflowPreview workflow={VARIABLES_RETRY_WORKFLOW} height={440} />
 
-Variables are global rather than block outputs: read them anywhere with `<variable.name>`, like `<variable.retryCount>`. Each variable you assign is also exposed on this block as `<variables.name>` if you want to reference it from the block directly.
+## Configuration
 
-## Examples
+**Variable Assignments** contains the variables to update and their new values. Select an existing variable, then enter a literal value or an earlier output, such as `<api.data.email>`.
 
-### Count retries
+The block converts each value to the selected variable's type. It does not evaluate JavaScript arithmetic. Use a Function for calculations, then assign its result.
 
-<WorkflowPreview workflow={VARIABLES_RETRY_WORKFLOW} />
+Assignments are written in order, but all references are resolved before the assignments run. A later row in the same block does not read a value just written by an earlier row.
 
-Each attempt bumps `retryCount`, and a Condition stops the loop after a few tries.
+## Outputs and scope
 
-### Hold config for the run
+Read variables from any block with `<variable.name>`, such as `<variable.retryCount>`. Assigned values are also available on the Variables block, for example `<update.retryCount>` for a block named **Update**.
 
-<WorkflowPreview workflow={VARIABLES_CONFIG_WORKFLOW} />
+Variables last for one execution. Multiple Variables blocks share the workflow's variable namespace, and a later assignment can overwrite an earlier value. Parallel branches share that namespace too; avoid concurrent writes to the same variable.
 
-Profile fields are stored once, then read by later blocks with `<variable.userTier>` without fetching again.
+References ignore case, whitespace, and periods. Avoid names that normalize to the same value, such as `retryCount` and `Retry Count`.
+
+## Store configuration for later steps
+
+<WorkflowPreview workflow={VARIABLES_CONFIG_WORKFLOW} />
 
-## Best Practices
+Create `userId` and `userTier` variables in the Variables panel. Assign their values from the API response once, then read them later with `<variable.userTier>`.
 
-- **Initialize variables first.** Create them in the workflow's Variables panel before a Variables block sets them.
-- **Track state across steps.** Variables suit counters and status that several blocks read and update, including inside a [Loop](/workflows/blocks/loop).
-- **Name them clearly.** References ignore case and spaces, so avoid variable names that normalize to the same value, such as `retryCount` and `RetryCount`.
-- **Assign from earlier outputs.** Set a variable from any block output, like `customerEmail = <api.email>`.
+## Related docs
 
-<FAQ items={[
-  { question: "Do variables persist between workflow executions?", answer: "No. Variables are workflow-scoped and persist only for a single run. Each new run starts from the initial values defined in the workflow's Variables panel." },
-  { question: "Can multiple Variables blocks update the same variable?", answer: "Yes. All Variables blocks share one namespace, so a later block can overwrite a value set by an earlier one by using the same name." },
-]} />
+- [Workflow variables](/workflows/variables)
+- [Function](/workflows/blocks/function)
+- [Loop](/workflows/blocks/loop)
diff --git a/apps/docs/content/docs/workflows/blocks/wait.mdx b/apps/docs/content/docs/workflows/blocks/wait.mdx
index a077c9b2cc9..e01d971ac22 100644
--- a/apps/docs/content/docs/workflows/blocks/wait.mdx
+++ b/apps/docs/content/docs/workflows/blocks/wait.mdx
@@ -1,52 +1,47 @@
 ---
 title: Wait
-description: The Wait block pauses a workflow for a set time before continuing.
+description: Pause a run for a duration, or suspend it until a scheduled resume time.
 ---
 
 import { BlockPreview, WorkflowPreview, WAIT_RATELIMIT_WORKFLOW, WAIT_FOLLOWUP_WORKFLOW } from '@/components/workflow-preview'
 
-The **Wait block** pauses a workflow for a set time, then continues. Use it to space out actions, respect API rate limits, or give an external system time to finish. A short wait runs in line; a long one suspends the run and resumes later.
+The **Wait block** delays the next step. Choose an inline wait for seconds or a few minutes, or enable **Async** to suspend the run and resume later.
 
 <BlockPreview type="wait" />
 
-## Configuration
-
-### Wait Amount
+## Space out requests
 
-The duration to pause, as a positive number.
+<WorkflowPreview workflow={WAIT_RATELIMIT_WORKFLOW} />
 
-### Unit
+A two-second wait spaces the two API requests apart. It can also sit between polling attempts. Account for other branches and workflow runs when calculating an API's rate limit.
 
-The time unit. For a short, in-line wait, choose **Seconds** or **Minutes**. With **Async** on, choose **Minutes**, **Hours**, or **Days**.
+## Configuration
 
-### Async
+| Field | Behavior |
+| --- | --- |
+| **Wait Amount** | Positive duration. Defaults to `10`. |
+| **Unit** | **Seconds** or **Minutes** with Async off; **Minutes**, **Hours**, or **Days** with Async on. |
+| **Async** | Off: wait in the running execution, up to 5 minutes. On: suspend and schedule resumption, up to 30 days. |
 
-Off, the run sleeps in line for the duration (up to 5 minutes). On, the run **suspends** and resumes after the delay, which is what lets a wait run for hours or days without holding the execution open. A suspended wait records when it will resume in `<wait.resumeAt>`.
+Async always suspends the run, even for a short duration. The resume poller picks it up after the scheduled time, so `resumeAt` is not an exact execution-time guarantee. Self-hosted deployments need their [resume scheduler](/platform/self-hosting/background-jobs) configured for automatic resumption.
 
 ## Outputs
 
-| Output | What it is |
+| Reference | Value |
 | --- | --- |
-| `<wait.status>` | `waiting`, `completed`, or `cancelled` |
-| `<wait.waitDuration>` | The wait duration, in milliseconds |
-| `<wait.resumeAt>` | ISO timestamp a suspended (async) wait resumes at |
-
-## Examples
-
-### Space out API calls
-
-<WorkflowPreview workflow={WAIT_RATELIMIT_WORKFLOW} />
+| `<wait.status>` | `waiting` for a suspended wait, `completed` for a finished inline wait, or `cancelled` when an inline wait is interrupted |
+| `<wait.waitDuration>` | Requested duration in milliseconds |
+| `<wait.resumeAt>` | Scheduled ISO resume timestamp for an async wait |
 
-A short wait between two calls keeps the workflow under an API's rate limit. The same shape works for polling: wait, then re-check an external job.
+Stopping a run cancels an active wait. A delay extends the workflow's wall-clock completion time; log duration and resumed execution records describe execution separately.
 
-### Send a delayed follow-up
+## Send a delayed follow-up
 
 <WorkflowPreview workflow={WAIT_FOLLOWUP_WORKFLOW} />
 
-With Async on, the run suspends for two days and resumes to send the follow-up, without holding the execution open in between.
+Enable Async and select two days to suspend the run before the follow-up step. Configure that step's messaging tool to send the notification.
 
-## Best Practices
+## Related docs
 
-- **Use a short in-line wait for seconds to a few minutes.** Turn on Async for hours or days so the run doesn't stay open the whole time.
-- **Remember waits extend the run.** The wait counts toward total duration, which shows in the logs.
-- **A wait is cancellable.** Stopping the run cancels an active wait, and `status` reports `cancelled`.
+- [API](/workflows/blocks/api)
+- [Human in the loop](/workflows/blocks/human-in-the-loop)
diff --git a/apps/docs/content/docs/workflows/blocks/webhook.mdx b/apps/docs/content/docs/workflows/blocks/webhook.mdx
index 904cdaf866a..8772bb1fd40 100644
--- a/apps/docs/content/docs/workflows/blocks/webhook.mdx
+++ b/apps/docs/content/docs/workflows/blocks/webhook.mdx
@@ -1,82 +1,72 @@
 ---
 title: Webhook
-description: The Webhook block sends an HTTP POST to an external endpoint, with automatic headers and optional signing.
+description: Send an outbound HTTP POST with optional HMAC signing.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
 import { BlockPreview, WorkflowPreview, WEBHOOK_NOTIFY_WORKFLOW, WEBHOOK_TRIGGER_WORKFLOW } from '@/components/workflow-preview'
 
-The Webhook block sends HTTP POST requests to external webhook endpoints with automatic webhook headers and optional HMAC signing.
+The **Webhook block** sends an HTTP POST to an external endpoint. It is an outbound action; the [Webhook trigger](/workflows/triggers/webhook) receives requests that start a run.
 
 <BlockPreview type="webhook" />
 
-## Configuration
+## Notify an external service
 
-### Webhook URL
+<WorkflowPreview workflow={WEBHOOK_NOTIFY_WORKFLOW} />
 
-The destination endpoint for your webhook request. Supports both static URLs and dynamic values from other blocks.
+Send the Agent's result as a JSON payload to a Slack incoming webhook or your own endpoint. Use the payload format required by that endpoint.
 
-### Payload
+## Configuration
 
-JSON data to send in the request body. Use the AI wand to generate payloads or reference workflow variables:
+| Field | Behavior |
+| --- | --- |
+| **Webhook URL** | Static endpoint URL or a value assembled from earlier outputs. |
+| **Payload** | JSON request body. The AI wand can help generate it. |
+| **Signing Secret** | Optional `{{WEBHOOK_SECRET}}` or another secret reference for HMAC-SHA256 signing. |
+| **Additional Headers** | Key-value headers merged over the automatic headers. |
 
 ```json
 {
   "event": "workflow.completed",
   "data": {
-    "result": "<agent.content>",
-    "timestamp": "<function.result>"
+    "result": "<agent.content>"
   }
 }
 ```
 
-### Signing Secret
-
-Optional secret for HMAC-SHA256 payload signing. When provided, adds an `X-Webhook-Signature` header:
-
-```
-X-Webhook-Signature: t=1704067200000,v1=5d41402abc4b2a76b9719d911017c592...
-```
-
-To verify signatures, compute `HMAC-SHA256(secret, "${timestamp}.${body}")` and compare with the `v1` value.
+### Automatic headers and signing
 
-### Additional Headers
-
-Custom key-value headers to include with the request. These override any automatic headers with the same name.
-
-## Automatic Headers
-
-Every request includes these headers automatically:
-
-| Header | Description |
-|--------|-------------|
+| Header | Value |
+| --- | --- |
 | `Content-Type` | `application/json` |
 | `X-Webhook-Timestamp` | Unix timestamp in milliseconds |
-| `X-Delivery-ID` | Unique UUID for this delivery |
-| `Idempotency-Key` | Same as `X-Delivery-ID` for deduplication |
+| `X-Delivery-ID` | UUID for this request |
+| `Idempotency-Key` | Same UUID as X-Delivery-ID |
+| `X-Webhook-Signature` | When a secret is supplied: `t=<timestamp>,v1=<signature>` |
 
-## Outputs
+The signature is the hexadecimal `HMAC-SHA256(secret, "${timestamp}.${body}")`, using the exact request body. Verify that value against `v1` at the destination.
 
-| Output | Type | Description |
-|--------|------|-------------|
-| `data` | json | Response body from the endpoint |
-| `status` | number | HTTP status code |
-| `headers` | object | Response headers |
+Custom headers can override these defaults. Overriding signing or timestamp headers can break verification. A new request gets a new delivery ID; the key does not deduplicate separate workflow executions automatically.
 
-## Examples
+## Outputs and failures
 
-### Notify an external service
+| Reference | Value |
+| --- | --- |
+| `<webhook.data>` | Endpoint response body |
+| `<webhook.status>` | Successful response's HTTP status |
+| `<webhook.headers>` | Response headers |
 
-<WorkflowPreview workflow={WEBHOOK_NOTIFY_WORKFLOW} />
-
-Format the result, then POST it to a Slack, Discord, or custom endpoint.
+Non-2xx responses and request failures use the block's error path. Connect the error port when the workflow should recover.
 
-### Fire an external process on a check
+## Send only when a condition passes
 
 <WorkflowPreview workflow={WEBHOOK_TRIGGER_WORKFLOW} />
 
-When the Condition passes, the Webhook starts a process in another system.
+Connect the Condition's **if** port to the Webhook to start an external process only for the matching event.
+
+The Webhook block always uses POST. Use [API](/workflows/blocks/api) for another HTTP method, retry controls, or proxy configuration.
+
+## Related docs
 
-<Callout>
-The Webhook block always uses POST. For other HTTP methods or more control, use the [API block](/workflows/blocks/api).
-</Callout>
+- [Webhook trigger](/workflows/triggers/webhook)
+- [API](/workflows/blocks/api)
+- [Credentials and secrets](/platform/credentials)
diff --git a/apps/docs/content/docs/workflows/blocks/workflow.mdx b/apps/docs/content/docs/workflows/blocks/workflow.mdx
index a94f885dfc1..86fe217d12a 100644
--- a/apps/docs/content/docs/workflows/blocks/workflow.mdx
+++ b/apps/docs/content/docs/workflows/blocks/workflow.mdx
@@ -1,71 +1,64 @@
 ---
-title: Workflow Block
-description: Run another workflow inside the current flow
+title: Workflow
+description: Run a child workflow, wait for it, and read its result.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Image } from '@/components/ui/image'
 import { BlockPreview, WorkflowPreview, WORKFLOW_CALL_WORKFLOW } from '@/components/workflow-preview'
 
-## What It Does
+The **Workflow block** calls another workflow in the same workspace and waits for it to finish. Editor runs use the child's draft; deployed parent runs use its active deployment.
 
 <BlockPreview type="workflow" />
 
-Drop a Workflow block when you want to call a child workflow as part of a larger flow. The block waits for the child to finish before continuing. An editor run uses the child's draft; a deployed parent run uses the child's active deployment.
+## Call a child workflow
 
-## Configure It
+<WorkflowPreview workflow={WORKFLOW_CALL_WORKFLOW} />
 
-1. **Pick a workflow** from the dropdown (self-references are blocked to prevent loops).
-2. **Map inputs**: The child workflow's Start fields appear in **Input Mapping**. Map parent values to them; the child reads each named field as `<start.fieldName>`.
+In the child `enrich-lead`, define a Start field named `input`. Select that workflow in the parent and map **Inputs → input** to `<start.input>`. Read the result downstream as `<workflow.result>`.
 
-<div className='flex justify-center my-6'>
-  <Image
-    src='/static/blocks/workflow-2.png'
-    alt='Workflow block with input mapping example'
-    width={700}
-    height={287}
-    className='rounded-xl border border-border shadow-sm'
-  />
-</div>
+## Configuration
 
-3. **Outputs**: After the child finishes, the block exposes:
-   - `result` – the child workflow's final response
-   - `success` – whether it ran without errors
-   - `error` – message when the run fails
-   - `childWorkflowName` – the name of the child workflow (string)
-   - `childWorkflowId` – the ID of the child workflow (string)
+| Field | Behavior |
+| --- | --- |
+| **Select Workflow** | Pick the child. The selector excludes the current workflow. |
+| **Workflow ID** | Advanced alternative for entering an ID or reference. The child still must be authorized in the same workspace. |
+| **Inputs** | Map each field defined in the child's Start schema to a literal or parent output. The child reads a field named `lead` with `<start.lead>`. |
 
-## Example
+When Workflow is attached as an Agent tool, configure the named child inputs in its tool configuration.
 
-<WorkflowPreview workflow={WORKFLOW_CALL_WORKFLOW} />
+Older workflows can contain the legacy Workflow block, which shows **Input Variable** instead of **Inputs**. That value reaches the child as `<start.input>`. Its separate **Workflow Inputs** mapper appears only when that legacy block is attached as an Agent tool. New blocks use the child's named Start schema.
+
+Child workflows use their own configured blocks and tools. Workspace credentials and environment access remain subject to the execution's authorization context; the parent's tool list is not copied into the child.
 
-The parent passes its input to the child workflow `enrich-lead`, waits for it to finish, and reads the result downstream as `<workflow.result>`.
+## Outputs
 
-## Deployment Status Badge
+| Reference | Value |
+| --- | --- |
+| `<workflow.result>` | Child's final workflow output |
+| `<workflow.success>` | Whether the child completed successfully |
+| `<workflow.error>` | Failure information when present |
+| `<workflow.childWorkflowName>` | Child workflow name |
+| `<workflow.childWorkflowId>` | Child workflow ID |
 
-The Workflow block displays a deployment status badge to help you track whether the child workflow is ready to execute:
+A child failure raises an error in the parent. Connect the Workflow block's error port to recover; a normal downstream step is not a failure handler.
 
-- **Deployed** – The child workflow has been deployed and is ready to use. The block will execute the current deployed version.
-- **Undeployed** – The child has no active deployment. Deploy it before invoking it from a deployed parent; editor runs can use its draft.
-- **Redeploy** – Changes have been detected in the child workflow since the last deployment. Click the badge to redeploy the child workflow with the latest changes.
+## Drafts and deployments
+
+| Badge | Meaning |
+| --- | --- |
+| **Deployed** | The child has an active deployment. A deployed parent uses it; an editor parent still uses the draft. |
+| **Undeployed** | No active deployment. Editor runs can use the draft; deployed parent runs require a deployment. |
+| **Redeploy** | The child's draft changed since deployment. Redeploy to make those changes available to deployed parent runs. |
 
 <Callout type="warn">
-Before deploying the parent, deploy the child. Redeploy the child after editing it for deployed parent runs to pick up those changes.
+Deploy the child before deploying its parent. Editing a child draft does not update the version used by deployed parents until the child is redeployed.
 </Callout>
 
-## Execution Notes
-
-- Child workflows run in the same workspace context, so environment variables and tools carry over.
-- Child workflows inherit the parent's execution context: editor runs use the child draft; deployed runs use its active snapshot.
-- If the child fails, the block raises an error unless you handle it downstream.
+## Nested calls
 
-<Callout>
-Keep child workflows focused. Small, reusable flows make it easier to combine them without creating deep nesting.
-</Callout>
+The selector blocks direct self-selection, and Sim tracks nested calls with the internal `X-Sim-Via` chain. The maximum call-chain depth is 25 hops; a request that exceeds it is rejected with `409`. Keep reusable child workflows focused and avoid cycles.
 
-import { FAQ } from '@/components/ui/faq'
+## Related docs
 
-<FAQ items={[
-  { question: "Can a workflow call itself recursively?", answer: "No. The workflow selector blocks self-references to prevent infinite loops. Additionally, Sim tracks the call chain across nested executions using an internal header and enforces a maximum call chain depth of 25 hops. If the limit is exceeded, the execution is rejected with a 409 error." },
-  { question: "What happens if the child workflow fails?", answer: "The Workflow block raises an error that propagates to the parent workflow. If you need to handle failures gracefully, connect an error path from the Workflow block to a downstream block that processes the error." },
-]} />
+- [API deployment](/workflows/deployment/api)
+- [Connections and error paths](/workflows/connections)
diff --git a/apps/docs/content/docs/workflows/connections.mdx b/apps/docs/content/docs/workflows/connections.mdx
index 2a9437d3741..397f9bc13ea 100644
--- a/apps/docs/content/docs/workflows/connections.mdx
+++ b/apps/docs/content/docs/workflows/connections.mdx
@@ -1,110 +1,97 @@
 ---
 title: Connections
-description: The syntax for referencing an earlier block's output and the shape of common block outputs.
+description: Reference block outputs with normalized names, nested fields, and array indices.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 import { Video } from '@/components/ui/video'
 
-A **connection** wires one block to the next and sets the order they run in. [How blocks pass data](/workflows/data-flow) covers the concept: once a block runs, its output is remembered under the block's name, and any later block reads it by reference. This page is the reference for the **connection tag** syntax and the output shapes you'll reach into.
-
-<div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="connections.mp4" />
-</div>
+Connections determine when blocks run. **Connection tags** read values from blocks that have already run. This page covers tag syntax and common output shapes; [data flow](/workflows/data-flow) explains how those values become available.
 
 ## Tag syntax
 
-A connection tag references a value from an earlier block's output:
-
-```
+```text
 <blockName.path.to.data>
 ```
 
-- `blockName` is the name of the source block. Block names are normalized before matching, so they're lowercased and spaces are removed. `<My Agent.content>` and `<myagent.content>` resolve to the same block.
-- `path.to.data` is the path to the value inside that block's output. The field path is case-sensitive.
+- `blockName` is the source block's name. Matching ignores case, whitespace, and periods: a block named My Agent resolves through `<myagent.content>`.
+- The field path is case-sensitive.
+- `variable`, `loop`, and `parallel` are reserved prefixes for [workflow variables](/workflows/variables) and container context.
 
-The same angle-bracket syntax also reads [workflow variables](/workflows/variables) (`<variable.name>`) and loop or parallel context (`<loop.index>`); a connection tag is specifically the block-output case.
+Type `<` in a supported field to open the reference picker, or drag an available output into the field:
 
-You rarely type a tag by hand. In any input field, type `<` to open a dropdown of the values available from earlier blocks and pick one, or drag a value from a connected block straight into the field.
+<Video src="connections.mp4" />
 
 ## Nested and array fields
 
-Chain dot notation to reach into objects, and use bracket indices for arrays. Both combine in a single path:
+Use dots for object fields and brackets for array indices:
 
-```
-<agent1.tokens.total>
-<api1.data.results[0].id>
-<api2.data.users[0].name>
+```text
+<agent.tokens.total>
+<api.data.results[0].id>
+<api.data.users[0].name>
 ```
 
-The resolver walks the path at runtime and substitutes the value. Multiple levels of indexing like `items[0][1]` work too.
+Multiple array indices, such as `items[0][1]`, are supported. Check the output panel for the actual structure; a path depends on what the source block produced.
 
 ## Using tags in text and code
 
-Tags resolve at runtime and can sit anywhere in a field, mixed with static text:
+Text fields can combine a reference with static text:
 
-```javascript
-// In text
-"The user's name is <userBlock.name>"
-
-// In JSON
-{
-  "userName": "<userBlock.name>",
-  "orderTotal": <apiBlock.data.total>
-}
-
-// In a Function block
-const greeting = `Hello, ${"<userBlock.name>"}!`
-const total = <apiBlock.data.total> * 1.1
+```text
+Customer <start.customerId> requested: <start.message>
 ```
 
-Values are formatted to fit their context. In a [Function](/workflows/blocks/function) block, a resolved value becomes a code literal, so strings are quoted, objects are JSON, and `null` stays `null`, ready to drop into JavaScript or Python. In other blocks, objects are JSON-stringified and primitives become plain strings.
+In a Function block, use referenced values in code:
 
-<Callout type="warning">
-In a numeric context, confirm the referenced value is actually a number. A tag that resolves to text will not behave as a number.
-</Callout>
+```javascript
+const name = <start.name>
+const total = <api.data.total>
+return { greeting: `Hello, ${name}!`, totalWithTax: total * 1.1 }
+```
 
-When a referenced block didn't run on the current path, for example a block on an unselected branch, its tag resolves to an empty value. In most blocks that's an empty string; in Function blocks it's `null`.
+Function references preserve value types for JavaScript or Python: strings remain strings, objects remain objects, and `null` remains null. In ordinary text fields, objects are JSON-stringified and primitives become text. Confirm a value is numeric before calculating with it; convert numeric text explicitly when needed.
+
+When a known source block did not run on the selected path, its reference resolves empty: usually `""`, or `null` in Function code. An unknown block name can remain unsubstituted, while an invalid field can fail resolution. These are different problems; inspect the source output and the run's active path.
 
 ## Common block outputs
 
-A tag's path depends on what the source block produced. These are the standard shapes for the blocks you'll reference most. The output panel shows the live structure for any block.
+These abbreviated examples use blocks named Agent, API, Function, Condition, Router, and Evaluator. Replace that name with your source block's normalized name. Additional and optional fields depend on the block and runtime.
 
 <Tabs items={['Agent', 'API', 'Function', 'Condition', 'Router', 'Evaluator']}>
   <Tab>
     ```json
     {
-      "content": "The generated text response",
-      "model": "claude-sonnet-4-6",
+      "content": "The generated response",
+      "model": "claude-sonnet-5-5",
       "tokens": { "input": 120, "output": 85, "total": 205 },
-      "toolCalls": []
+      "toolCalls": { "list": [], "count": 0 }
     }
     ```
 
-    `content` is the main response. `tokens` is an object of usage counts. `toolCalls` lists the tools the agent called, with their inputs and results. With a response format configured, your schema's fields appear as their own outputs instead.
+    Read text with `<agent.content>` and tool activity with `<agent.toolCalls.list>` or `<agent.toolCalls.count>`. A successful structured response exposes its fields at the top level, except names overwritten by standard metadata. See [Agent response format](/workflows/blocks/agent#response-format) for naming guidance, provider support, and malformed-output behavior.
   </Tab>
   <Tab>
     ```json
     {
-      "data": "Response body",
+      "data": { "message": "Response body" },
       "status": 200,
       "headers": { "content-type": "application/json" }
     }
     ```
 
-    `data` is the response body and can be any type. `status` is the HTTP status code. `headers` holds the response headers.
+    `data` can be any response-body type. These normal outputs describe a successful request. Non-2xx responses, network failures, and timeouts use the [API block's error path](/workflows/blocks/api).
   </Tab>
   <Tab>
     ```json
     {
       "result": "Function return value",
-      "stdout": "Console output",
+      "stdout": "Code output",
       "files": []
     }
     ```
 
-    `result` is whatever your function returned and can be any type. `stdout` captures anything the code logged.
+    `result` can be any return-value type. `stdout` contains bounded diagnostic output; see [Function output limits](/workflows/blocks/function#outputs). Remote execution includes `files` metadata; local JavaScript can omit that field.
   </Tab>
   <Tab>
     ```json
@@ -119,14 +106,16 @@ A tag's path depends on what the source block produced. These are the standard s
     }
     ```
 
-    `conditionResult` is the boolean result. `selectedPath` describes the next block. `selectedOption` is the ID of the matched condition.
+    `conditionResult` reports the rule result. `selectedOption` identifies the selected branch; `selectedPath` describes its next block and can be null when no destination is connected.
   </Tab>
   <Tab>
     ```json
     {
-      "content": "Routing decision",
-      "model": "claude-sonnet-4-6",
+      "context": "I need help resetting my password",
+      "model": "claude-sonnet-5-5",
       "tokens": { "input": 120, "output": 85, "total": 205 },
+      "selectedRoute": "customer-service",
+      "reasoning": "The request needs account support",
       "selectedPath": {
         "blockId": "2acd9007-27e8-4510-a487-73d3b825e7c1",
         "blockType": "agent",
@@ -135,21 +124,25 @@ A tag's path depends on what the source block produced. These are the standard s
     }
     ```
 
-    `content` is the routing decision text. `selectedPath` describes the chosen destination block.
+    `context` is the analyzed input, `selectedRoute` identifies the chosen route, and `reasoning` explains the decision. `selectedPath` describes the destination. A no-match routing error uses Router's error behavior.
   </Tab>
   <Tab>
     ```json
     {
       "content": "The original content being evaluated",
-      "model": "claude-sonnet-4-6",
+      "model": "claude-sonnet-5-5",
       "tokens": { "input": 120, "output": 85, "total": 205 },
       "metric1": 8.5,
       "metric2": 7.2
     }
     ```
 
-    `content` contains the original input that was evaluated. Each metric you defined appears as its own field with a numeric score.
+    `content` is the evaluated input. Metric names are lowercased. Missing scores or an unparseable response can produce `0`; see [Evaluator outputs](/workflows/blocks/evaluator#outputs) for numeric coercion and validation guidance.
   </Tab>
 </Tabs>
 
-A Function's `result`, an API's `data`, and an Agent with a response format all return whatever your code, the remote service, or your schema produced, so check the output panel during development to confirm the path you're referencing.
+## Related docs
+
+- [How blocks pass data](/workflows/data-flow)
+- [Variables](/workflows/variables)
+- [Function](/workflows/blocks/function)
diff --git a/apps/docs/content/docs/workflows/data-flow.mdx b/apps/docs/content/docs/workflows/data-flow.mdx
index 9e233893bfc..2d87d6ae9b7 100644
--- a/apps/docs/content/docs/workflows/data-flow.mdx
+++ b/apps/docs/content/docs/workflows/data-flow.mdx
@@ -1,22 +1,19 @@
 ---
 title: How blocks pass data
-description: What a block's output is, how blocks reference earlier outputs, and the data types you'll work with.
+description: Read earlier block outputs by name and choose the values a workflow returns.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
 import { WorkflowPreview, OutputBundle, CLASSIFY_REPLY_WORKFLOW } from '@/components/workflow-preview'
 
-Most blocks need a value that an earlier block produced. A block gets it by referencing that block's output by name.
+Blocks read earlier results through references. A connection determines when a block runs; a reference determines which value it reads.
 
 <WorkflowPreview workflow={CLASSIFY_REPLY_WORKFLOW} height={180} />
 
-In this workflow, Classify reads the message from Start, and Reply reads the classification from Classify.
+Classify reads `<start.input>`. Reply reads `<classify.content>` after Classify finishes.
 
 ## What an output is
 
-When a block runs, Sim keeps its result under the block's name for the rest of the run. That stored result is the block's **output**, and any later block can read it.
-
-An output is usually a set of named values, not a single thing. You read one by its key: `<classify.content>` is the `content` value of the block named `classify`.
+Sim stores each block's result for the run. An output usually contains several named values; `<classify.content>` reads the `content` field from the block named Classify.
 
 <OutputBundle
   blockName="classify"
@@ -25,7 +22,7 @@ An output is usually a set of named values, not a single thing. You read one by
   duration="2.1s"
   values={[
     { key: 'content', type: 'string', value: '"Billing · high urgency"', highlight: true },
-    { key: 'model', type: 'string', value: '"claude-sonnet-4-6"', expanded: false },
+    { key: 'model', type: 'string', value: '"claude-sonnet-5-5"', expanded: false },
     {
       key: 'tokens', type: 'object',
       children: [
@@ -37,33 +34,45 @@ An output is usually a set of named values, not a single thing. You read one by
   ]}
 />
 
-Different blocks produce different values. An [Agent](/workflows/blocks/agent) keeps its `content`; an [API](/workflows/blocks/api) keeps the `data` it received; a Table block keeps a `rowCount` and the rows it read, reached with `<table1.rowCount>`.
-
-<Callout type="info">
-A block's output is not the same as the **workflow's** output. Every block has its own, kept under its own name. By default, the workflow returns its last block's output. A [Response block](/workflows/blocks/response) or a deployment's selected outputs can shape what the caller receives.
-</Callout>
+Different blocks produce different fields. An [API](/workflows/blocks/api) returns its successful response body under `data`; a [Function](/workflows/blocks/function) returns its value under `result`; a Table query returns rows and `rowCount`.
 
 ## How a block references an output
 
-A block's inputs are its **parameters**: the fields you fill in, like an Agent's model and prompt. In any parameter you can insert a **connection tag** to pull in an earlier output instead of typing a fixed value. The `<start.input>` in Classify's prompt means "use whatever Start received here."
+Insert a **connection tag** into a supported input field, such as an Agent message or API request body. Type `<` to browse available references, or drag an output into the field.
+
+A referenced output must exist when the receiving block runs. A connection from the source ensures that dependency; when several sources feed one block, it waits for their active paths. A block on an unselected branch produces no output.
 
-<WorkflowPreview workflow={CLASSIFY_REPLY_WORKFLOW} height={180} highlightBlock="reply" />
+For a known block that did not run, references resolve empty: usually an empty string, or `null` in Function code. An unknown name can remain unsubstituted, while an invalid field can fail resolution. Inspect the source output rather than assuming every reference failure has the same result.
 
-A block can reference any output that already exists by the time it runs, meaning any block before it on its path (see [how workflows run](/workflows/how-it-runs)). You rarely type a tag by hand: wherever a parameter accepts one, the builder lists the available outputs and you pick the value you want.
+See [connection syntax](/workflows/connections) for name normalization, nested fields, and arrays.
 
 ## Data types
 
-Each value inside an output has a type, shown next to it in the output panel. The type tells you what you can do with the value: index into an array, read a field from an object, compare a number.
+The output panel shows each value's type:
 
-| Type | What it is | Example |
+| Type | Example | How to use it |
 | --- | --- | --- |
-| `string` | Text | `"Billing issue"` |
-| `number` | A numeric value | `248` |
-| `boolean` | `true` or `false` | `true` |
-| `object` | A set of named fields | `{ category: "billing", urgency: "high" }` |
-| `array` | An ordered list of values | `["billing", "urgent"]` |
-| `null` | No value | `null` |
+| `string` | `"Billing issue"` | Include text in a prompt or message |
+| `number` | `248` | Calculate or compare |
+| `boolean` | `true` | Check a condition |
+| `object` | `{ "category": "billing" }` | Read named fields |
+| `array` | `["billing", "urgent"]` | Index or iterate |
+| `null` | `null` | Handle an absent value |
+
+Files appear as metadata objects, including their name and URL. Table row cells are nested under each row's `data`. Check the actual output before choosing a path.
+
+Use a Function block to reshape or convert a value, then reference its `result` downstream. Text fields stringify objects; Function code can use the referenced value as its original type.
+
+## Choose the workflow result
+
+Block output and workflow output are different. A simple chain returns its last block's output. With several terminal branches, the last terminal block to finish supplies the default result, so its identity can vary between runs.
+
+Join branches into one final block or add a [Response block](/workflows/blocks/response) when a caller needs a deliberate result. Chat deployments and table workflow columns select the fields they consume. API `selectedOutputs` projects block values separately from the default result; synchronous v2 calls expose that projection in `data.blockOutputs`.
+
+The v2 API returns the workflow result in `data.output`. A Response block does not replace that API's HTTP status, headers, or envelope.
 
-A file shows up as an `object` carrying the file's details, like its name and URL. When a value isn't the type the next step needs, reshape it in a [Function](/workflows/blocks/function) block, which runs a short snippet of code and stores the result as its own output.
+## Related docs
 
-See [connection tags](/workflows/connections) for reference syntax, and [Logs](/logs-debugging) to inspect the values a block received.
+- [How workflows run](/workflows/how-it-runs)
+- [Connection syntax](/workflows/connections)
+- [Logs](/logs-debugging)
diff --git a/apps/docs/content/docs/workflows/deployment/agent-events.mdx b/apps/docs/content/docs/workflows/deployment/agent-events.mdx
index 56b222dbd65..d3c03efc8c2 100644
--- a/apps/docs/content/docs/workflows/deployment/agent-events.mdx
+++ b/apps/docs/content/docs/workflows/deployment/agent-events.mdx
@@ -1,193 +1,213 @@
 ---
 title: Agent stream events
-description: Protocol for streaming thinking and tool lifecycle from Agent blocks
+description: Consume answer text, provider reasoning, and tool lifecycle events over a negotiated SSE protocol.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 
-Agent blocks can emit more than answer text while they run: **provider-exposed thinking** (or reasoning summaries) and a **tool-call lifecycle** (name + status). Sim delivers those as typed events on an opt-in stream protocol.
-
-<Callout type="info">
-Sim does **not** invent thinking for providers that do not stream it. Bedrock Converse, many OpenAI-compat models, and non-reasoning chat models stay text-only (plus tools when a live tool loop is wired).
-</Callout>
+Agent blocks can stream answer text, provider-exposed thinking or reasoning summaries, and tool lifecycle events. A client declares the protocol it understands; separate policies decide whether thinking and tool events are exposed.
 
 ## Two independent switches
 
-Agent events are governed by two things that do not depend on each other.
-
-**Policy decides which frames exist.** `includeThinking` turns on `thinking` frames, `includeToolCalls` turns on `tool` frames, and both default to **off**.
-
-| Surface | Policy source |
-|---------|---------------|
-| Deployed chat (`/api/chat/{identifier}`) | The chat deployment's **Thinking** and **Tool calls** toggles |
-| Workflow API (`/api/v2/workflows/{id}/execute`) | Per-request `includeThinking` / `includeToolCalls` in the body |
-
-**The header declares the protocol version.** Sending it says the client understands v1 framing:
+Send this header for live answer text and the `agent-events-v1` frame vocabulary:
 
 ```http
 X-Sim-Stream-Protocol: agent-events-v1
 ```
 
-It does two things. It switches answer text to live token-by-token `chunk` frames that `chunk_reset` can retract, and it is **required** for any `thinking` or `tool` frame — a client that never declared a version has no contract for their shape, so it keeps the text-only stream it already understands.
+The response echoes the negotiated protocol. The header enables live `chunk` frames and the `chunk_reset` event that retracts an intermediate tool-calling turn. It does not, by itself, expose thinking or tools.
 
-When both event flags are false, you can omit the header to receive settled final-turn text without agent-event frames. The response echoes the header back when the protocol was negotiated.
+| Surface | Thinking and tool policies |
+| --- | --- |
+| Workflow API | Request-body `includeThinking` and `includeToolCalls` |
+| Deployed chat | Deployment **Include thinking** and **Include tool calls** settings |
 
-The header alone exposes nothing, so a chat with both policies off still streams token by token.
+Both policies default off. Either can be enabled independently, but its frames also require the header. Without the header, answer text arrives as settled final-turn chunks rather than provisional live tokens.
 
 <Callout type="warn">
-On the workflow API, setting `includeThinking` or `includeToolCalls` **without** the header is rejected with `400`. The flags would otherwise be a silent no-op, which is the failure mode this protocol exists to avoid. Deployed chat degrades instead of rejecting, because there the policy comes from the deployment rather than the request.
+The workflow API rejects `includeThinking` or `includeToolCalls` without `stream: true` and the protocol header. Deployed chat instead omits those events when its client has not negotiated the protocol, because its policies come from deployment settings.
 </Callout>
 
 ### Workflow API
 
+This example selects `content` from a block named Agent:
+
 ```bash
-curl -N https://www.sim.ai/api/v2/workflows/{id}/execute \
+curl -N -X POST 'https://www.sim.ai/api/v2/workflows/{workflow-id}/execute' \
   -H "X-API-Key: $SIM_API_KEY" \
-  -H "Content-Type: application/json" \
-  -H "X-Sim-Stream-Protocol: agent-events-v1" \
-  -d '{
-    "stream": true,
-    "selectedOutputs": ["agent_1.content"],
-    "includeThinking": true,
-    "includeToolCalls": true
-  }'
+  -H 'Content-Type: application/json' \
+  -H 'X-Sim-Stream-Protocol: agent-events-v1' \
+  -d '{"input":{"message":"Research this topic"},"stream":true,"selectedOutputs":["agent.content"],"includeThinking":true,"includeToolCalls":true}'
 ```
 
-Both flags default to `false`, so an existing integration receives exactly the frames it does today. The header is required whenever either flag is set; omit it and the request is rejected with `400` rather than silently downgraded.
+Tool frames contain names and lifecycle status, not arguments or results. The authenticated workflow API's terminal envelope can contain full tool arguments and results. Public deployed chat removes those payloads from its own tool-call metadata.
 
-Two differences from deployed chat are worth knowing. Tool frames carry the name and status only on both surfaces, but the API's terminal `final` envelope keeps tool **arguments and results** — public chat redacts them. And thinking is delivered only as `thinking` frames; it is stripped from `providerTiming.timeSegments` in the envelope on every surface, so enabling the policy is the only way to receive it.
+Thinking is delivered through `thinking` frames when supported and enabled. It is removed from `providerTiming.timeSegments` in terminal envelopes, so timing metadata is not an alternative route to reasoning content.
 
 ## Simple SSE frame shapes
 
-Answer text stays on `chunk`. Thinking and tools never reuse `chunk` (so older clients that append every `chunk` into the answer cannot leak thinking).
+Each frame is one JSON value in an SSE `data:` line:
+
+| Example | Meaning |
+| --- | --- |
+| `{"blockId":"agent-id","chunk":"Hello"}` | Answer text; no `event` discriminator |
+| `{"blockId":"agent-id","event":"chunk_reset"}` | Clear provisional answer text for this block |
+| `{"blockId":"agent-id","event":"thinking","data":"..."}` | Provider thinking or reasoning-summary delta |
+| `{"blockId":"agent-id","event":"tool","phase":"start","id":"call-id","name":"search"}` | Tool started |
+| `{"blockId":"agent-id","event":"tool","phase":"end","id":"call-id","name":"search","status":"success"}` | Tool ended; status distinguishes its outcome |
+| `{"event":"final","data":{"success":true,"output":{}}}` | Settled execution envelope; a workflow failure can have `success: false` and `error` |
+| `{"event":"error","error":"Execution timed out"}` | Terminal stream failure; no `final` follows |
+| `{"event":"stream_error","blockId":"agent-id","error":"..."}` | Non-terminal read issue; execution can continue |
+
+The stream closes with the JSON-encoded sentinel:
+
+```text
+data: "[DONE]"
+```
 
-| Frame | Meaning |
-|-------|---------|
-| `{ "blockId", "chunk": "…" }` | Answer text. Legacy clients receive settled final-turn text in one piece; opted-in clients receive it live as the model generates (see below) |
-| `{ "blockId", "event": "chunk_reset" }` | Opted-in only: discard the block’s streamed answer text — it belonged to a turn that resolved to tool calls |
-| `{ "blockId", "event": "thinking", "data": "…" }` | Thinking / reasoning summary delta |
-| `{ "blockId", "event": "tool", "phase": "start"\|"end", "id", "name", "status?" }` | Tool lifecycle (no args / results) |
-| `{ "event": "final", "data": … }` | Terminal result envelope for a settled execution. `data.success` may be `false` with `data.error` when the workflow itself failed |
-| `{ "event": "error", "error": "…" }` | Terminal stream failure (timeout, client abort, processing error) — followed by `[DONE]`, never by `final` |
-| `{ "event": "stream_error", "blockId?", "error" }` | Non-terminal mid-block read issue; the stream keeps going |
-| `data: "[DONE]"` | Stream closed (JSON-encoded sentinel; always follows the terminal `final` or `error` frame) |
+Exactly one terminal `final` or `error` frame precedes it. Unknown event types should be ignored, allowing the protocol to add frames without breaking clients.
 
 ### Live answer text and intermediate turns
 
-During a live tool loop, the model can’t be classified mid-turn: text it emits may turn out to be the final answer or preamble before a tool call (the stop reason arrives only at turn end).
+A model turn can emit text before deciding to call a tool. An opted-in client receives that provisional text live; if the turn resolves to tool calls, `chunk_reset` tells it to clear the accumulated answer for that block. The final turn streams after the tools settle.
 
-- **Clients sending the protocol header** (no event policy required) receive answer text as `chunk` frames **live**, token by token. If the turn then resolves to tool calls, a `chunk_reset` frame tells the client to discard that block’s streamed text — the final turn re-streams live after tools settle. Append `chunk`, honor `chunk_reset`, and the displayed answer always converges to the block’s final content.
-- **Clients without the header** never see provisional text: only settled final-turn text is emitted as `chunk`, delivered in one piece when the turn completes. Honoring `chunk_reset` is what buys live cadence, so send the header if you want it.
+Append `chunk` values per `blockId` and honor resets. Frames from several blocks can interleave. Clients without the header receive only settled final-turn text and do not need to handle provisional turns.
 
-The block's `content` output and plain-message memory view contain the final response text. With [durable tool history](/workflows/blocks/agent#memory) enabled, internal memory also preserves complete assistant messages that lead to tool calls and their results. It records completed provider messages, not individual streamed text deltas, and does not add these internal exchanges to the Memory API's `data` response.
+The block's `content` and plain-message memory view contain its final response. With [durable tool history](/workflows/blocks/agent#memory), internal memory also preserves completed assistant tool-call messages and results, not individual token deltas. Those internal exchanges are not added to the Memory API's `data` response.
 
 ### Abort
 
-Client disconnect or Stop aborts the provider stream. In-flight tools settle as `cancelled`. Cancel is distinct from execution timeout.
+Client disconnect or **Stop** aborts the provider stream. In-flight tools settle as `cancelled`; cancellation is distinct from execution timeout.
 
 ### Reconnect
 
-Canvas execution-events `stream:chunk`, `stream:chunk_reset`, `stream:thinking`, and `stream:tool` are **live-only** (not buffered for reconnect replay), same as answer chunks. Guaranteed `seq` replay is out of scope.
+Editor execution-events `stream:chunk`, `stream:chunk_reset`, `stream:thinking`, and `stream:tool` are live-only. They are not buffered for reconnect replay; the protocol does not guarantee `seq` replay.
 
-## Canvas (draft Run)
+## Editor runs [#canvas-draft-run]
 
-When you click **Run** in the builder, the execution-events SSE path forwards the same sink. The canvas is always opted in — it does not send (or need) the `X-Sim-Stream-Protocol` header, and the policy switches do not apply to it:
+The workflow builder's execution-events stream forwards:
 
-- `stream:thinking` — `{ blockId, text }`
-- `stream:tool` — `{ blockId, phase, id, name, status? }`
-- `stream:chunk` — answer text, live on agent-events runs
-- `stream:chunk_reset` — `{ blockId }`; discard the block’s streamed text (intermediate turn)
+| Event | Data |
+| --- | --- |
+| `stream:chunk` | Live answer text |
+| `stream:chunk_reset` | `{ blockId }` |
+| `stream:thinking` | `{ blockId, text }` |
+| `stream:tool` | `{ blockId, phase, id, name, status? }` |
 
-The terminal output panel shows Thinking / Tools chrome above the block output when those events arrive. PII redaction on block output still disables live forwarding (executor rule).
+Draft **Run** is opted in without the public protocol header or deployment policy switches. The terminal output panel shows thinking and tool activity when available. Block-output PII redaction disables live forwarding.
 
 ## Chat deployment toggles
 
-In **Deploy → Chat**, enable **Include thinking** for provider-exposed thinking and **Include tool calls** for tool names and lifecycle status. The switches are independent of each other, and both still require the client to send the protocol header. Neither switch affects answer-text cadence.
+In **Deploy → Chat**, enable **Include thinking** and **Include tool calls** as needed. They do not change answer-text cadence. The hosted chat UI sends the protocol header; a custom client must send it itself.
+
+Public chat reduces its own tool-call metadata to names and lifecycle status in both streamed fields and the terminal envelope. Do not use a workflow's arbitrary output fields as a way to expose private tool arguments or results.
+
+After changing the workflow's models or tools, deploy an updated workflow snapshot. Save chat settings when changing its event policies.
 
-Tool arguments and results are never exposed to a public chat — not in lifecycle frames, and not through the terminal `final` envelope, where the block's own tool calls are reduced to the same name-and-lifecycle shape. The authenticated workflow API still returns full tool results. Redeploy or update the chat after changing Agent models or tools.
+### Structured chat outputs
+
+The hosted chat also negotiates `chat-outputs-v1` for selected non-text outputs, including file metadata:
+
+```http
+X-Sim-Stream-Protocol: agent-events-v1, chat-outputs-v1
+```
+
+That additional capability can emit `{"blockId":"block-id","event":"output","data":{}}`. Treat `data` as a structured selected value, not answer text. `chat-outputs-v1` is separate from the thinking/tool policies.
 
 ## Provider support
 
-Per-model support is generated from the model registry on the [Agent block page](/workflows/blocks/agent#streamed-thinking-and-tool-calls); the table below summarizes by provider family.
+Sim forwards provider-exposed reasoning; it does not invent thinking for text-only models. Support depends on the selected model and its reasoning settings. See the generated [Agent support table](/workflows/blocks/agent#streamed-thinking-and-tool-calls).
 
-| Family | Thinking | Live tools |
-|--------|----------|------------|
-| Anthropic / Azure Anthropic | Yes (incl. redacted blocks in traces). The newest Claude generations omit full thinking; Sim requests summarized thinking for them on streaming runs | Yes |
-| Gemini / Vertex | Yes when a thinking level is set (thought summaries requested on agent-events runs) | Yes |
-| OpenAI Responses | Reasoning **summaries** when streamed (requires OpenAI organization verification; unverified orgs fall back to no summaries) | Yes |
-| OpenAI-compat (Groq, DeepSeek, …) | Only if vendor streams `reasoning` / `reasoning_content` | Live loop where wired (e.g. Groq, DeepSeek) |
-| Bedrock | Not invented | Yes when streaming tool loop is used |
+Claude generations can expose full or summarized thinking. Gemini/Vertex can expose thought summaries with a configured thinking level. OpenAI Responses uses reasoning summaries and can fall back without summaries when organization verification is unavailable. OpenAI-compatible providers expose reasoning only when their stream supplies it; live tools require a wired tool loop. Bedrock does not gain invented reasoning when only text/tools are available.
 
 ## Consuming the stream
 
-A conforming client owes the stream four things:
+A client must:
 
-1. **Discriminate before appending.** Only a frame with **no** `event` field is answer text. Checking `event === undefined` rather than "has a `chunk` field" is what keeps future frame types from leaking into the answer.
-2. **Accumulate per `blockId`.** A workflow can stream more than one block; frames interleave.
-3. **Honor `chunk_reset`** if you sent the protocol header. Clear that block's accumulated text — it belonged to a turn that resolved to tool calls, and the final turn re-streams.
-4. **Stop at the terminal frame.** Exactly one of `final` or `error` arrives, followed by the literal `"[DONE]"` sentinel. `stream_error` is *not* terminal.
+1. Append only frames with no `event` and a string `chunk`.
+2. Accumulate text per `blockId`.
+3. Clear that block's answer on `chunk_reset`.
+4. Handle `final` and `error` as terminal; `stream_error` is non-terminal.
+5. Handle negotiated `output` frames separately and ignore unknown events.
 
 ### Reference client
 
-```ts
+This parser consumes Sim's single-line JSON data frames. It returns the final envelope, keeping answer and thinking buffers separate:
+
+```typescript
 type Frame = Record<string, unknown>
 
-async function consume(response: Response, renderToolChip: (frame: Frame) => void) {
-  const reader = response.body!.getReader()
+async function consume(
+  response: Response,
+  onTool: (frame: Frame) => void,
+  onOutput: (frame: Frame) => void,
+  onIssue: (frame: Frame) => void
+) {
+  if (!response.ok) throw new Error(`HTTP ${response.status}`)
+  if (!response.body) throw new Error('Response body is missing')
+
+  const reader = response.body.getReader()
   const decoder = new TextDecoder()
   const answers = new Map<string, string>()
   const thinking = new Map<string, string>()
   let buffer = ''
 
-  while (true) {
-    const { done, value } = await reader.read()
-    if (done) break
-    buffer += decoder.decode(value, { stream: true })
-
-    // SSE frames are newline-delimited; keep the trailing partial line.
-    const lines = buffer.split('\n')
-    buffer = lines.pop() ?? ''
-
-    for (const line of lines) {
-      if (!line.startsWith('data: ')) continue
-      const payload = line.slice(6)
-
-      const frame = JSON.parse(payload) as Frame | string
-      if (frame === '[DONE]') return { answers, thinking }
-      if (typeof frame === 'string') continue
-
-      const { blockId, event } = frame as { blockId?: string; event?: string }
-
-      if (event === undefined && typeof frame.chunk === 'string') {
-        answers.set(blockId!, (answers.get(blockId!) ?? '') + frame.chunk)
-      } else if (event === 'chunk_reset') {
-        answers.set(blockId!, '')
-      } else if (event === 'thinking') {
-        thinking.set(blockId!, (thinking.get(blockId!) ?? '') + String(frame.data))
-      } else if (event === 'tool') {
-        // frame.phase is 'start' | 'end'; frame.status is set on 'end'.
-        renderToolChip(frame)
-      } else if (event === 'final') {
-        // Terminal. frame.data.success may be false with frame.data.error.
-      } else if (event === 'error') {
-        throw new Error(String(frame.error))
-      } else if (event === 'stream_error') {
-        // Non-terminal: log and keep reading.
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) throw new Error('Stream ended before a terminal frame')
+      buffer += decoder.decode(value, { stream: true })
+      const lines = buffer.split('\n')
+      buffer = lines.pop() ?? ''
+
+      for (const line of lines) {
+        if (!line.startsWith('data: ')) continue
+        const frame = JSON.parse(line.slice(6)) as Frame | string
+        if (typeof frame !== 'object' || frame === null) continue
+
+        const { blockId, event } = frame
+        if (event === 'error') throw new Error(String(frame.error))
+        if (event === 'final') {
+          return { answers, thinking, result: frame.data }
+        }
+        if (event === 'stream_error') {
+          onIssue(frame)
+          continue
+        }
+        if (typeof blockId !== 'string') continue
+
+        if (event === undefined && typeof frame.chunk === 'string') {
+          answers.set(blockId, (answers.get(blockId) ?? '') + frame.chunk)
+        } else if (event === 'chunk_reset') {
+          answers.set(blockId, '')
+        } else if (event === 'thinking' && typeof frame.data === 'string') {
+          thinking.set(blockId, (thinking.get(blockId) ?? '') + frame.data)
+        } else if (event === 'tool') {
+          onTool(frame)
+        } else if (event === 'output') {
+          onOutput(frame)
+        }
       }
     }
+  } finally {
+    await reader.cancel()
+    reader.releaseLock()
   }
 }
 ```
 
-Unknown `event` values should be ignored rather than treated as errors — that is what lets new frame types ship without breaking existing clients.
+Inspect the returned envelope's `success` and `error`: receiving `final` means execution settled, not that the workflow succeeded. The parser stops on a terminal frame rather than waiting for the closing sentinel.
 
-## Example (public chat)
+## Example public chat [#example-public-chat]
 
 ```bash
-curl -N -X POST 'http://localhost:3000/api/chat/your-slug' \
+curl -N -X POST 'https://www.sim.ai/api/chat/your-slug' \
   -H 'Content-Type: application/json' \
   -H 'X-Sim-Stream-Protocol: agent-events-v1' \
   -d '{"input":"Think briefly, then say hi"}'
 ```
 
-See also [Chat deployment](/workflows/deployment/chat) for access control and the event settings.
+## Related docs
+
+- [Chat deployment](/workflows/deployment/chat) for access control and event settings
+- [API deployment](/workflows/deployment/api) for execution modes
diff --git a/apps/docs/content/docs/workflows/deployment/api.mdx b/apps/docs/content/docs/workflows/deployment/api.mdx
index 8489a641af0..4eac887febb 100644
--- a/apps/docs/content/docs/workflows/deployment/api.mdx
+++ b/apps/docs/content/docs/workflows/deployment/api.mdx
@@ -1,302 +1,203 @@
 ---
 title: API deployment
+description: Call a workflow through the v2 API with synchronous, streaming, or asynchronous execution.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { Image } from '@/components/ui/image'
-import { FAQ } from '@/components/ui/faq'
+import { Tab, Tabs } from '@/components/ui/tabs'
 
-Deploy your workflow as a REST API endpoint that any application can call directly. Supports synchronous, streaming, and asynchronous execution modes.
+Call a deployed workflow at `POST /api/v2/workflows/{workflow-id}/execute`. Choose a complete JSON result, an SSE stream, or an async run receipt.
 
-## Deploying a Workflow
+## Deploy the workflow [#deploying-a-workflow]
 
-Open your workflow and click **Deploy**. The **General** tab opens first and shows you the current deployment state:
+You need workspace **Admin** access and the applicable deployment permission. Test with **Run**, then open **Deploy → General** and click **Deploy** or **Update**. [Deployment](/workflows/deployment) covers versions, comparison, rollback, and undeploying.
 
-<Image src="/static/api-deployment/api-versions.png" alt="General tab of the Workflow Deployment modal showing a live workflow preview, a Versions table with v2 (live) and v1, and Undeploy / Update buttons" width={800} height={597} className="mx-auto h-auto w-full max-w-xl" />
+Ordinary API calls use the active snapshot. Editing the draft does not change that version. Deploy an update before expecting a normal API call to use your changes.
 
-The **General** tab contains:
+## Authentication
 
-- **Live Workflow** — a read-only minimap of the workflow snapshot that is currently deployed
-- **Versions** — a table of every deployment you've published, showing version number, who deployed it, and when
-- **Deploy / Update / Undeploy** — action buttons at the bottom right
+Send a valid Sim API key in `X-API-Key`, or use a supported OAuth access token. Deployed workflow execution requires access to the workflow's workspace; OAuth callers also need the operation's `api:write` scope. See [API authentication](/api-reference/authentication).
 
-Click **Deploy** to publish your workflow for the first time, or **Update** to push a new snapshot after making changes. The green dot next to a version indicates it is the currently live version.
+Generate keys in **Settings → Sim API keys** or **Deploy → API → Generate API Key**. Keep the key available to your application as `SIM_API_KEY`.
 
-Once deployed, your workflow is available at:
+### API info and public access
 
-```
-POST https://www.sim.ai/api/v2/workflows/{workflow-id}/execute
-```
+Open **Deploy → API → Edit API Info** to set a description and choose **API Key** or **Public** access. API-key access is the default.
 
-<Callout type="info">
-  API executions always run against the active deployment snapshot. After changing your workflow on the canvas, click **Update** to publish a new version.
+<Callout type="warn">
+A public endpoint lets an anonymous caller run the deployed workflow. Restrict what input can do and what output reveals before enabling it. Public access is subject to deployment and organization policy; anonymous callers cannot start async or manual draft runs.
 </Callout>
 
-### Keeping Track of Changes
-
-When you modify the workflow canvas after deploying, an **Update deployment** badge appears at the bottom of the screen as a reminder that your live version is out of date:
-
-<Image src="/static/api-deployment/api-update-button.png" alt="Canvas toolbar showing the Update and Run buttons with an Update deployment tooltip" width={400} height={186} className="mx-auto h-auto w-full max-w-[240px]" />
-
-You can click the **Update** button directly from the canvas toolbar — you don't need to open the Deploy modal every time.
-
-## Version Control
-
-Every time you deploy or update, a new version is recorded in the Versions table. You can manage past versions using the context menu (⋮) next to any row:
-
-<Image src="/static/api-deployment/api-versions-menu.png" alt="Versions table showing v2 (live) and v1 with a context menu open offering Rename, Add description, Promote to live, and Load deployment options" width={800} height={346} className="mx-auto h-auto w-full max-w-xl" />
-
-| Action | Description |
-|--------|-------------|
-| **Rename** | Give the version a human-readable name (e.g., "Added memory") |
-| **Add description** | Attach a note describing what changed in this version |
-| **Promote to live** | Make this older version the active one without re-deploying |
-| **Load deployment** | Load the workflow snapshot from this version back onto your canvas |
-
-**Promote to live** is useful for rolling back — if a new deployment has an issue, promote the previous version to restore the last known-good state instantly.
-
-## Managing Deployments via the API
-
-Everything above can also be done programmatically. The v1 API exposes deploy, undeploy, and rollback endpoints — useful for CI/CD pipelines that ship a workflow after tests pass, or for reverting to the last known-good version from an incident script. All three require an API key with admin permission on the workflow's workspace.
-
-```bash
-# Deploy the current draft as a new version (body is optional)
-curl -X POST https://www.sim.ai/api/v1/workflows/{workflow-id}/deploy \
-  -H "Content-Type: application/json" \
-  -H "x-api-key: $SIM_API_KEY" \
-  -d '{ "name": "Release 4", "description": "Fixes the agent prompt" }'
-
-# Undeploy — take the workflow offline
-curl -X DELETE https://www.sim.ai/api/v1/workflows/{workflow-id}/deploy \
-  -H "x-api-key: $SIM_API_KEY"
-
-# Roll back to the previous version (or pass { "version": N } for a specific one)
-curl -X POST https://www.sim.ai/api/v1/workflows/{workflow-id}/rollback \
-  -H "x-api-key: $SIM_API_KEY"
-```
-
-Rollback re-activates an existing deployment version — the same operation as **Promote to live** — and leaves your canvas draft untouched. See the API reference for full request and response details: [Deploy Workflow](/api-reference/workflows/deployWorkflow), [Undeploy Workflow](/api-reference/workflows/undeployWorkflow), and [Rollback Workflow](/api-reference/workflows/rollbackWorkflow).
-
-## Making API Calls
-
-Switch to the **API** tab in the Deploy modal to see ready-to-use code for all three execution modes:
-
-<Image src="/static/api-deployment/api-tab.png" alt="API tab showing cURL, Python, JavaScript, and TypeScript language options, with Run workflow, Run workflow (stream response), and Run workflow (async) code sections" width={800} height={653} className="mx-auto h-auto w-full max-w-xl" />
-
-The language selector at the top lets you switch between **cURL**, **Python**, **JavaScript**, and **TypeScript**. Each mode — synchronous, streaming, and async — has its own code block that you can copy directly. The code is pre-filled with your workflow ID and a masked version of your API key.
-
-At the bottom of the tab, two buttons give you quick access to key settings:
-
-- **Edit API Info** — set a description and choose between API key auth or public access
-- **Generate API Key** — create a new API key scoped to your workspace
-
-## Authentication
+## Make a call [#making-api-calls]
 
-By default, API endpoints require an API key passed in the `x-api-key` header. Generate keys in **Settings → Sim Keys** or via the **Generate API Key** button in the API tab.
+Put named [Start inputs](/workflows/triggers/start) inside the request's `input` value. For a field named `message`:
 
 ```bash
-curl -X POST https://www.sim.ai/api/v2/workflows/{workflow-id}/execute \
-  -H "Content-Type: application/json" \
-  -H "x-api-key: $SIM_API_KEY" \
-  -d '{ "input": { "message": "Hello" } }'
+curl -X POST 'https://www.sim.ai/api/v2/workflows/{workflow-id}/execute' \
+  -H "X-API-Key: $SIM_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":{"message":"Summarize this article"}}'
 ```
 
-### API Info and Public Access
+The **API** tab offers cURL, Python, JavaScript, and TypeScript examples. Replace example identifiers and supply your own key before calling them.
 
-Click **Edit API Info** to add a description and change the access mode:
-
-<Image src="/static/api-deployment/api-info.png" alt="Edit API Info modal with a Description textarea and an Access section toggling between API Key and Public modes" width={800} height={439} className="mx-auto h-auto w-full max-w-md" />
-
-| Access Mode | Description |
-|-------------|-------------|
-| **API Key** (default) | Requires a valid API key in the `x-api-key` header |
-| **Public** | No authentication required — anyone with the URL can call the endpoint |
-
-The **Description** field documents what the workflow API does. This is useful for teams, or when exposing the workflow to tools and services that surface API metadata.
-
-<Callout type="warn">
-  Public endpoints can be called by anyone with the URL. Only use this for workflows that don't expose sensitive data or perform sensitive actions.
-</Callout>
-
-## Execution Modes
+## Execution modes
 
 ### Synchronous
 
-The default mode. Send a request and wait for the complete response:
+The default mode waits for the run to settle:
 
 <Tabs items={['cURL', 'Python', 'TypeScript']}>
   <Tab value="cURL">
-```bash
-curl -X POST https://www.sim.ai/api/v2/workflows/{workflow-id}/execute \
-  -H "Content-Type: application/json" \
-  -H "x-api-key: $SIM_API_KEY" \
-  -d '{ "input": { "message": "Summarize this article" } }'
-```
+    ```bash
+    curl -X POST 'https://www.sim.ai/api/v2/workflows/{workflow-id}/execute' \
+      -H "X-API-Key: $SIM_API_KEY" \
+      -H 'Content-Type: application/json' \
+      -d '{"input":{"message":"Summarize this article"}}'
+    ```
   </Tab>
   <Tab value="Python">
-```python
-import requests, os
-
-response = requests.post(
-    "https://www.sim.ai/api/v2/workflows/{workflow-id}/execute",
-    headers={
-        "Content-Type": "application/json",
-        "x-api-key": os.environ["SIM_API_KEY"]
-    },
-    json={"input": {"message": "Summarize this article"}}
-)
-print(response.json())
-```
+    ```python
+    import os
+    import requests
+
+    response = requests.post(
+        "https://www.sim.ai/api/v2/workflows/{workflow-id}/execute",
+        headers={"X-API-Key": os.environ["SIM_API_KEY"]},
+        json={"input": {"message": "Summarize this article"}},
+    )
+    response.raise_for_status()
+    print(response.json())
+    ```
   </Tab>
   <Tab value="TypeScript">
-```typescript
-const response = await fetch('https://www.sim.ai/api/v2/workflows/{workflow-id}/execute', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'x-api-key': process.env.SIM_API_KEY!
-  },
-  body: JSON.stringify({ input: { message: 'Summarize this article' } })
-});
-console.log(await response.json());
-```
+    ```typescript
+    const apiKey = process.env.SIM_API_KEY
+    if (!apiKey) throw new Error('Set SIM_API_KEY')
+
+    const response = await fetch('https://www.sim.ai/api/v2/workflows/{workflow-id}/execute', {
+      method: 'POST',
+      headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ input: { message: 'Summarize this article' } })
+    })
+    if (!response.ok) throw new Error(`HTTP ${response.status}`)
+    const result = await response.json()
+    process.stdout.write(JSON.stringify(result))
+    ```
   </Tab>
 </Tabs>
 
-### Streaming
+V2 returns a run resource in `data`, including `runId`, `workflowId`, `status`, `output`, `blockOutputs`, `error`, and timing fields. Check `data.status`: a workflow that ran and failed can return HTTP `200` with `status: "failed"`. An HTTP error instead describes a rejected request or a service failure.
 
-Stream the response token-by-token as it is generated. Add `"stream": true` to your request body and specify which block output fields to stream using `selectedOutputs`.
+A [Response block](/workflows/blocks/response) selects the workflow result, which remains inside `data.output`. It cannot override the v2 endpoint's HTTP status, headers, or envelope.
 
-Use the **Select outputs** dropdown in the API tab to choose which fields to stream:
+A synchronous caller can request `Accept: application/x-ndjson` to receive heartbeat frames while waiting, followed by a `type: "final"` frame containing the same run resource. This is distinct from Agent token streaming with `stream: true`.
 
-<Image src="/static/api-deployment/api-select-outputs.png" alt="Select outputs dropdown open showing Agent 1 block with selectable output fields: content, model, tokens, toolCalls, providerTiming, cost" width={800} height={677} className="mx-auto h-auto w-full max-w-xl" />
+### Streaming
 
-The dropdown groups available outputs by block. The most common choice is `content` from an Agent block, which streams the generated text. You can select fields from multiple blocks simultaneously.
+Set `stream: true` and use `selectedOutputs` to select fields. **Select outputs** in the API tab groups fields by block; `content` from an Agent is a common choice.
 
-The `selectedOutputs` values in the request body follow the format `blockName.field` (e.g., `agent_1.content`).
+Selectors use a stable block ID or normalized block name followed by a field path, such as `agent.content` for a block named Agent. Nested paths and reachable child-workflow selectors are also supported; see [Execute workflow](/api-reference/workflows/executeWorkflowV2).
+
+For live answer tokens, send `X-Sim-Stream-Protocol: agent-events-v1` and handle `chunk_reset`. Without that header, answer text arrives after a final model turn settles. The header alone does not expose thinking or tool events.
 
 <Tabs items={['cURL', 'Python', 'TypeScript']}>
   <Tab value="cURL">
-```bash
-curl -X POST https://www.sim.ai/api/v2/workflows/{workflow-id}/execute \
-  -H "Content-Type: application/json" \
-  -H "x-api-key: $SIM_API_KEY" \
-  -d '{
-    "input": { "prompt": "Write a long essay" },
-    "stream": true,
-    "selectedOutputs": ["agent_1.content"]
-  }'
-```
+    ```bash
+    curl -N -X POST 'https://www.sim.ai/api/v2/workflows/{workflow-id}/execute' \
+      -H "X-API-Key: $SIM_API_KEY" \
+      -H 'Content-Type: application/json' \
+      -H 'X-Sim-Stream-Protocol: agent-events-v1' \
+      -d '{"input":{"message":"Write a long essay"},"stream":true,"selectedOutputs":["agent.content"]}'
+    ```
   </Tab>
   <Tab value="Python">
-```python
-import requests, os
-
-response = requests.post(
-    "https://www.sim.ai/api/v2/workflows/{workflow-id}/execute",
-    headers={
-        "Content-Type": "application/json",
-        "x-api-key": os.environ["SIM_API_KEY"]
-    },
-    json={
-        "input": {"prompt": "Write a long essay"},
-        "stream": True,
-        "selectedOutputs": ["agent_1.content"]
-    },
-    stream=True
-)
-for line in response.iter_lines():
-    if line:
-        print(line.decode())
-```
+    ```python
+    import os
+    import requests
+
+    with requests.post(
+        "https://www.sim.ai/api/v2/workflows/{workflow-id}/execute",
+        headers={
+            "X-API-Key": os.environ["SIM_API_KEY"],
+            "X-Sim-Stream-Protocol": "agent-events-v1",
+        },
+        json={
+            "input": {"message": "Write a long essay"},
+            "stream": True,
+            "selectedOutputs": ["agent.content"],
+        },
+        stream=True,
+    ) as response:
+        response.raise_for_status()
+        for line in response.iter_lines():
+            if line:
+                print(line.decode())
+    ```
   </Tab>
   <Tab value="TypeScript">
-```typescript
-const response = await fetch('https://www.sim.ai/api/v2/workflows/{workflow-id}/execute', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'x-api-key': process.env.SIM_API_KEY!
-  },
-  body: JSON.stringify({
-    input: { prompt: 'Write a long essay' },
-    stream: true,
-    selectedOutputs: ['agent_1.content']
-  })
-});
-
-const reader = response.body!.getReader();
-const decoder = new TextDecoder();
-while (true) {
-  const { done, value } = await reader.read();
-  if (done) break;
-  console.log(decoder.decode(value));
-}
-```
+    ```typescript
+    const apiKey = process.env.SIM_API_KEY
+    if (!apiKey) throw new Error('Set SIM_API_KEY')
+
+    const response = await fetch('https://www.sim.ai/api/v2/workflows/{workflow-id}/execute', {
+      method: 'POST',
+      headers: {
+        'X-API-Key': apiKey,
+        'Content-Type': 'application/json',
+        'X-Sim-Stream-Protocol': 'agent-events-v1'
+      },
+      body: JSON.stringify({
+        input: { message: 'Write a long essay' },
+        stream: true,
+        selectedOutputs: ['agent.content']
+      })
+    })
+    if (!response.ok) throw new Error(`HTTP ${response.status}`)
+    if (!response.body) throw new Error('Response body is missing')
+
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        process.stdout.write(decoder.decode(value, { stream: true }))
+      }
+    } finally {
+      reader.releaseLock()
+    }
+    ```
   </Tab>
 </Tabs>
 
+These examples print raw SSE for inspection. For an application, parse frames, accumulate answers per `blockId`, and honor resets and terminal errors using the [stream reference client](/workflows/deployment/agent-events#reference-client).
+
 #### Streaming agent thinking and tool calls
 
-By default a streaming run carries answer text only. To also receive the Agent block's reasoning and its tool-call lifecycle, set `includeThinking` / `includeToolCalls`:
+Add independent `includeThinking` and `includeToolCalls` flags:
 
 ```bash
-curl -N -X POST https://www.sim.ai/api/v2/workflows/{workflow-id}/execute \
-  -H "Content-Type: application/json" \
-  -H "x-api-key: $SIM_API_KEY" \
-  -H "X-Sim-Stream-Protocol: agent-events-v1" \
-  -d '{
-    "input": { "prompt": "Research this topic" },
-    "stream": true,
-    "selectedOutputs": ["agent_1.content"],
-    "includeThinking": true,
-    "includeToolCalls": true
-  }'
+curl -N -X POST 'https://www.sim.ai/api/v2/workflows/{workflow-id}/execute' \
+  -H "X-API-Key: $SIM_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -H 'X-Sim-Stream-Protocol: agent-events-v1' \
+  -d '{"input":{"message":"Research this topic"},"stream":true,"selectedOutputs":["agent.content"],"includeThinking":true,"includeToolCalls":true}'
 ```
 
-The `X-Sim-Stream-Protocol` header is **required** whenever either flag is set — it declares that your client understands agent-event framing. Setting a flag without it returns `400` rather than silently ignoring the flag. The header also switches answer text to live token-by-token delivery that `chunk_reset` can retract.
-
-Both flags default to `false` and the header is optional on its own, so existing integrations keep the exact frames they receive today. Tool frames carry the tool name and status only; arguments and results arrive in the terminal `final` envelope. Not every model exposes thinking. See [Agent stream events](/workflows/deployment/agent-events) for the frame shapes, a reference client, and per-provider support.
-
-#### Oversized outputs
-
-Workflow execution responses are capped by platform request and response limits. When an internal output, log field, streamed field, or async status payload contains a value that is too large to inline, Sim may replace that nested value with a versioned reference:
-
-```json
-{
-  "__simLargeValueRef": true,
-  "version": 1,
-  "id": "lv_abc123DEF456",
-  "kind": "array",
-  "size": 12582912,
-  "key": "execution/workspace-id/workflow-id/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74/large-value-lv_abc123DEF456.json",
-  "executionId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
-  "preview": { "length": 25000 }
-}
-```
-
-The `version` field is part of the external API contract. Treat the reference as an opaque placeholder for a value that could not be safely embedded in the response. `id`, `key`, and `executionId` are not fetch URLs; `key` points to execution-scoped server storage. Use `selectedOutputs` to request a smaller nested field, reduce the data passed between blocks, or return the data from a Response block when your workflow intentionally owns the HTTP response body. File outputs are metadata-first; request `.base64` only when you need inline file content. JavaScript Function blocks can explicitly read large files, value refs, and manifest-backed arrays with the `sim.files` and `sim.values` helpers under memory caps.
+Both flags default false. Enabling either without `stream: true` and the protocol header returns `400`. Tool lifecycle frames contain names and status; full tool arguments/results can appear in the authenticated API's terminal envelope. Thinking support varies by model. See [Agent stream events](/workflows/deployment/agent-events) for the contract.
 
 ### Asynchronous
 
-For long-running workflows, async mode returns a run ID immediately so you don't need to hold the connection open. Set `"async": true` in the v2 request body. The API returns HTTP 202 with a run ID and v2 status URL. Poll that run resource until it completes.
-
-To stop an individual async request sooner than the workspace policy, set `executionTimeoutSeconds`
-to an integer from `1` to `604800` (seven days) in the v2 request body. The effective limit is the
-smaller of this request value and the account's configured workflow execution timeout. This field
-is rejected unless `async` is `true`; your HTTP client's timeout remains separate.
+Set `async: true` to receive HTTP `202` with a run ID and status URL instead of holding the connection open:
 
-<Tabs items={['Start Execution', 'Check Status']}>
-  <Tab value="Start Execution">
 ```bash
-curl -X POST https://www.sim.ai/api/v2/workflows/{workflow-id}/execute \
-  -H "Content-Type: application/json" \
-  -H "x-api-key: $SIM_API_KEY" \
-  -d '{ "input": { "task": "Process this large dataset" }, "async": true, "executionTimeoutSeconds": 3600 }'
+curl -X POST 'https://www.sim.ai/api/v2/workflows/{workflow-id}/execute' \
+  -H "X-API-Key: $SIM_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":{"message":"Process this dataset"},"async":true,"executionTimeoutSeconds":3600}'
 ```
 
-**Response** (HTTP 202):
 ```json
 {
   "data": {
@@ -305,103 +206,114 @@ curl -X POST https://www.sim.ai/api/v2/workflows/{workflow-id}/execute \
   }
 }
 ```
-  </Tab>
-  <Tab value="Check Status">
+
+Async execution requires an API key or OAuth token and uses the deployed version. It cannot be combined with `stream`, manual draft execution, partial-run options, or streaming/output-shaping options such as `selectedOutputs` and `includeThinking`.
+
+`executionTimeoutSeconds` accepts an integer from `1` to `604800` and is supported only with `async: true`. The effective limit is the smaller of that value and the account policy; it cannot extend the policy. Your HTTP client's timeout is separate.
+
+Poll the returned run URL, requesting output when needed:
+
 ```bash
-curl "https://www.sim.ai/api/v2/workflows/{workflow-id}/runs/{runId}?includeOutput=true" \
-  -H "x-api-key: $SIM_API_KEY"
+curl 'https://www.sim.ai/api/v2/workflows/{workflow-id}/runs/{runId}?includeOutput=true' \
+  -H "X-API-Key: $SIM_API_KEY"
 ```
 
-**While processing:**
+A completed response includes the result when requested:
+
 ```json
 {
   "data": {
     "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
     "workflowId": "{workflow-id}",
-    "status": "running",
-    "startedAt": "2025-09-10T12:00:01.000Z",
-    "endedAt": null,
-    "durationMs": null,
-    "output": null
+    "status": "completed",
+    "startedAt": "2026-10-13T12:00:01.000Z",
+    "endedAt": "2026-10-13T12:00:05.000Z",
+    "durationMs": 4000,
+    "output": { "result": "..." }
   }
 }
 ```
 
-**When completed:**
+#### Execution status values
+
+| Status | Meaning |
+| --- | --- |
+| `queued` | Waiting to be picked up |
+| `pending` | Durable record exists; execution has not started |
+| `running` | Executing |
+| `paused` | Waiting for a resume condition or submitted input |
+| `redacting` | Finished execution; output is still being scrubbed |
+| `completed` | Finished successfully |
+| `failed` | Failed; inspect `error` |
+| `cancelled` | Cancelled |
+
+Stop polling on `completed`, `failed`, or `cancelled`. A paused Human run requires submitted input; a time pause can resume automatically. See [Human](/workflows/blocks/human-in-the-loop) and [Wait](/workflows/blocks/wait). Resuming an originally streaming run through the v2 resume endpoint returns an async receipt, not an SSE continuation.
+
+## Select outputs and handle large values [#oversized-outputs]
+
+`selectedOutputs` can project smaller fields. For a synchronous v2 call, selected values appear in `data.blockOutputs`, separately from `data.output`.
+
+Oversized nested values in outputs, logs, streamed fields, or async status payloads may be replaced with a versioned reference:
+
 ```json
 {
-  "data": {
-    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
-    "workflowId": "{workflow-id}",
-    "status": "completed",
-    "startedAt": "2025-09-10T12:00:01.000Z",
-    "endedAt": "2025-09-10T12:00:05.000Z",
-    "durationMs": 4000,
-    "output": { "result": "..." }
-  }
+  "__simLargeValueRef": true,
+  "version": 1,
+  "id": "lv_abc123DEF456",
+  "kind": "array",
+  "size": 12582912,
+  "key": "execution/workspace-id/workflow-id/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74/large-value-lv_abc123DEF456.json",
+  "executionId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
+  "preview": { "length": 25000 }
 }
 ```
-  </Tab>
-</Tabs>
 
-#### Execution Status Values
+Treat this as an opaque placeholder. `version` is part of the contract; `id`, `key`, and `executionId` are not fetch URLs. Reduce the payload or select a smaller field. A Response block remains subject to the v2 response contract and size limits.
+
+File outputs contain metadata by default; request inline base64 only when needed. JavaScript Function code can read large files, value references, and manifest-backed arrays with `sim.files` and `sim.values` under memory caps. See [Function](/workflows/blocks/function).
+
+## Manual draft execution
 
-| Status | Description |
-|--------|-------------|
-| `queued` | Execution is waiting to be picked up |
-| `pending` | The durable execution record exists but has not started |
-| `running` | Workflow is actively executing |
-| `paused` | Workflow is waiting for a resume condition or input |
-| `completed` | Finished successfully — `output` is populated when requested |
-| `failed` | Execution failed — `error` field contains the message |
-| `cancelled` | Execution was cancelled |
+V2 supports explicit `run.source: "manual"` for a personal API-key or OAuth caller with Write access. Workspace keys and anonymous callers cannot use it. Choose `run.entry.blockId` when several triggers are runnable; mock payloads and explicit input cannot be combined.
 
-Poll the `statusUrl` from the initial response until the status is `completed`, `failed`, or `cancelled`. A `paused` run is waiting to be resumed.
+Manual mode uses the saved draft and supports sync or streaming, not async. Run-from-block and stop-after options have additional validation. See [Execute workflow](/api-reference/workflows/executeWorkflowV2) for the full request.
 
-#### Execution Time Limits
+## Limits and recovery
 
-| Plan | Sync Limit | Async Limit |
-|------|-----------|-------------|
-| **Community** | 5 minutes | 90 minutes |
-| **Pro / Max / Team** | 50 minutes | 90 minutes |
-| **Enterprise** | 50 minutes | 90 minutes by default; configurable up to 7 days |
+### Execution time limits
 
-If an execution exceeds its time limit it is automatically marked as `failed`. An async API request may use `executionTimeoutSeconds` to shorten its account policy, but never to extend it.
+See [run duration](/workflows/how-it-runs#how-long-a-run-can-take) for current billing-enabled defaults and self-hosted configuration. Async callers can shorten, but never extend, the account policy.
 
-#### Execution Retention
+### Execution retention
 
-Completed and failed runs are read from execution logs and follow the workspace's execution-log retention policy.
+Completed and failed runs are read from execution logs and follow the effective [data retention policy](/platform/enterprise/data-retention).
 
-#### Capacity Limits
+### Capacity limits
 
-If the execution queue is full, the API returns `503`:
+A request rejected for rate or capacity limits can return `429` or `503`. V2 uses a structured error envelope, for example:
 
 ```json
 {
-  "error": "Service temporarily at capacity",
-  "retryAfterSeconds": 10
+  "error": {
+    "code": "RATE_LIMITED",
+    "message": "Server is at capacity. Please retry shortly."
+  }
 }
 ```
 
-<Callout type="info">
-  Async mode always runs against the deployed version. It does not support draft state, block overrides, or partial execution options like `runFromBlock` or `stopAfterBlockId`.
-</Callout>
-
-## API Key Management
+Use the HTTP status and `Retry-After` header for retry timing. If an async enqueue outcome is uncertain and the error includes a run ID, reconcile that run before repeating a request. `X-Run-Id` claims are one-shot identifiers, not cached-response replay keys; a conflict or missing run does not prove the first call had no effects.
 
-Generate and manage API keys in **Settings → Sim Keys**:
+### Rate limits
 
-- **Create** new keys for different applications or environments
-- **Revoke** keys that are no longer needed
-- Keys are scoped to your workspace
+Plan and deployment policy govern rate and concurrent execution limits. `X-RateLimit-*` headers describe the applicable request limit. Async mode remains subject to admission and execution limits; it does not bypass them.
 
-## Rate Limits
+### API key management
 
-API calls are subject to rate limits based on your plan. Rate limit details are returned in response headers (`X-RateLimit-*`) and in the response body. Use async mode for high-volume or long-running workloads.
+Revoke a compromised key in **Settings → Sim API keys**, create a replacement, and update callers. Use separate keys for applications or environments and the appropriate personal/workspace scope. See [authentication](/api-reference/authentication) for key lifecycle and access.
 
-For detailed rate limit information and the logs/webhooks API, see [External API](/api-reference/getting-started).
+## Related docs
 
-<FAQ items={[
-  { question: "Can I deploy the same workflow as both an API and a chat?", answer: "Yes. A workflow can be simultaneously deployed as an API, chat, MCP tool, and more. Each deployment type runs against the same active snapshot." },
-  { question: "What happens if my API key is compromised?", answer: "Revoke the key immediately in Settings → Sim Keys and generate a new one. Revoked keys stop working instantly." },
-]} />
+- [Deployment versions](/workflows/deployment) for tracking changes, promotion, and API deployment management
+- [Agent stream events](/workflows/deployment/agent-events)
+- [Execute workflow](/api-reference/workflows/executeWorkflowV2)
+- [API getting started](/api-reference/getting-started)
diff --git a/apps/docs/content/docs/workflows/deployment/chat.mdx b/apps/docs/content/docs/workflows/deployment/chat.mdx
index 3238706fce6..58c625e2145 100644
--- a/apps/docs/content/docs/workflows/deployment/chat.mdx
+++ b/apps/docs/content/docs/workflows/deployment/chat.mdx
@@ -1,71 +1,74 @@
 ---
 title: Chat deployment
+description: Share a workflow as a chat with selected outputs, attachments, and access controls.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+import { Tab, Tabs } from '@/components/ui/tabs'
 import { Image } from '@/components/ui/image'
-import { FAQ } from '@/components/ui/faq'
 
-Deploy your workflow as a conversational chat interface that users can interact with via a shareable link or embedded widget. Chat supports multi-turn conversations, file uploads, and voice input.
+Deploy a workflow as a chat page, then share its link or embed it in your site. Each message starts a fresh workflow run using the active deployment.
 
-<Image src="/static/chat/chat-live.png" alt="A deployed chat interface showing a conversation with Friendly Assistant" width={800} height={462} />
+You need workspace **Admin** access and permission to deploy chats. Configure a [Start block](/workflows/triggers/start) for the message and attachments. To retain earlier conversation context, configure [Agent Memory](/workflows/blocks/agent#memory) and use `<start.conversationId>` as the conversation ID. The chat sends the latest `input`, `conversationId`, and current `files`; it does not automatically pass the whole conversation history to every block.
 
-Every chat message triggers a fresh workflow execution, with the full conversation history passed in as context. Responses stream back to the user in real time.
+## Create a chat [#creating-a-chat]
 
-<Callout type="info">
-Chat executions run against your workflow's active deployment snapshot. Publish a new deployment after making canvas changes so the chat uses the updated version.
-</Callout>
-
-## Creating a Chat
+1. Open **Deploy → Chat**.
+2. Set a unique **URL** and **Title**.
+3. Choose at least one field in **Output**. For an Agent answer, select `content` from the block that produces it.
+4. Choose **Access control** and complete its settings.
+5. Set a **Welcome message** and optional event policies, then click **Launch Chat**.
+6. Open the chat link, submit a message, and verify the response and recorded run in [Logs](/logs-debugging).
 
-Open your workflow, click **Deploy**, and select the **Chat** tab. You'll see the chat configuration panel:
+| Setting | Meaning |
+| --- | --- |
+| **URL** | Unique slug across workspaces, using lowercase letters, numbers, and hyphens |
+| **Title** | Name shown in the chat header |
+| **Output** | Selected block fields returned to the chat; at least one is required |
+| **Welcome message** | Initial greeting; defaults to `Hi there! How can I help you today?` |
+| **Access control** | Public, password, email, or supported SSO access |
+| **Include thinking** | Provider-exposed reasoning, off by default |
+| **Include tool calls** | Tool names and lifecycle status, off by default |
 
-<Image src="/static/chat/chat-deploy-config.png" alt="Chat deployment configuration panel showing URL, Title, Output, Access control, and Welcome message fields" width={800} height={597} className="mx-auto h-auto w-full max-w-xl" />
+The event policies are independent. Custom clients need `X-Sim-Stream-Protocol: agent-events-v1` to receive their frames; the hosted UI sends it. Public chat removes tool arguments and results from its tool-call metadata. See [Agent stream events](/workflows/deployment/agent-events).
 
-Configure the following fields, then click **Launch Chat**:
+### Output selection
 
-| Field | Description |
-|-------|-------------|
-| **URL** | Slug that forms the public URL, e.g. `https://www.sim.ai/chat/your-slug`. Lowercase letters, numbers, and hyphens only. Must be unique across all workspaces. |
-| **Title** | Display name shown in the chat header. |
-| **Output** | Output fields from your workflow blocks returned as the chat response. At least one must be selected. |
-| **Welcome Message** | Greeting shown before the user sends their first message. Defaults to `"Hi there! How can I help you today?"`. |
-| **Access Control** | Controls who can access the chat. See [Access Control](#access-control) below. |
-| **Include thinking** | When enabled, the hosted chat can show provider-exposed thinking. Requires the chat client to send `X-Sim-Stream-Protocol: agent-events-v1` (the hosted UI always does). Default is off. See [Agent stream events](/workflows/deployment/agent-events). |
-| **Include tool calls** | When enabled, the hosted chat can show tool names and lifecycle status independently of thinking. Tool arguments and results are never exposed. Requires the same stream protocol header and defaults to off. |
+The picker groups fields by block. Agent fields include `content`, `model`, `tokens`, `toolCalls`, `providerTiming`, and `cost`; a successful structured response can expose different fields. Choose the values your chat should show, rather than every available field.
 
-### Output Selection
+The hosted client also negotiates structured output frames for non-text values such as file metadata. That is separate from the thinking/tool policies.
 
-<Image src="/static/chat/chat-deploy-output.png" alt="Output dropdown showing Agent 1 block with selectable fields: content, model, tokens, toolCalls, providerTiming, cost" width={800} height={358} className="mx-auto h-auto w-full max-w-md" />
+## Access control
 
-The output dropdown groups available fields by block. For an Agent block, you can choose from `content`, `model`, `tokens`, `toolCalls`, `providerTiming`, and `cost`. In most cases, selecting `content` from the final Agent block is all you need — it streams the agent's text response directly to the user.
+| Mode | Requirement |
+| --- | --- |
+| **Public** | Anyone with the link can submit messages |
+| **Password** | The caller supplies the configured password |
+| **Email** | Allowed addresses/domains verify with a six-digit email OTP |
+| **SSO** | OIDC single sign-on with configured identity provider and allowed email scope; requires the deployment's enterprise SSO capability |
 
-## Access Control
-
-<Image src="/static/chat/chat-deploy-access-email.png" alt="Access control section with Email tab selected, showing an Allowed emails field with @sim.ai domain added" width={800} height={386} className="mx-auto h-auto w-full max-w-sm" />
+<Callout type="warn">
+Public access allows anonymous people to run the workflow. Review what its input can trigger and what its selected outputs reveal before sharing the link.
+</Callout>
 
-| Mode | Description |
-|------|-------------|
-| **Public** | Anyone with the link can chat — no authentication required |
-| **Password** | Users must enter a password before they can start chatting |
-| **Email** | Only specific email addresses or domains can access. Users verify with a 6-digit OTP sent to their email |
-| **SSO** | OIDC-based single sign-on (enterprise only) |
+For **Password**, set and share the password with intended callers. For **Email**, add individual addresses such as `user@example.com` or domains such as `@example.com` to **Allowed emails**:
 
-**Email access:** Add individual addresses (`user@example.com`) or entire domains (`@example.com`) to the **Allowed emails** field. Users receive a one-time 6-digit OTP to their inbox — once verified, they can chat for the duration of their session.
+<Image src="/static/chat/chat-deploy-access-email.png" alt="Email access control with an allowed domain entered" width={800} height={386} className="mx-auto h-auto w-full max-w-sm" />
 
-**Password access:** A password field appears when this mode is selected. Share the password with users directly; they enter it before the conversation begins.
+OTP codes expire after 15 minutes. The hosted UI uses a 30-second resend countdown; server request limits still apply. Verification creates an authentication cookie for subsequent chat requests.
 
-**SSO:** Uses OIDC to authenticate users through your identity provider. Available on enterprise plans.
+For **SSO**, configure the identity provider and allowed addresses/domains. See [SSO](/platform/enterprise/sso) for setup and capability requirements.
 
 ## Sharing
 
-### Direct Link
+### Direct link
 
-```
+```text
 https://www.sim.ai/chat/your-slug
 ```
 
+Use your deployment's origin instead of `www.sim.ai` when self-hosting.
+
 ### Iframe
 
 ```html
@@ -73,110 +76,112 @@ https://www.sim.ai/chat/your-slug
   src="https://www.sim.ai/chat/your-slug"
   width="100%"
   height="600"
-  frameborder="0"
   title="Chat"
 ></iframe>
 ```
 
-## API Submission
+Your site's Content Security Policy must permit the chat origin in `frame-src`. Protected chats still require authentication; the browser's cookie policy can affect authentication inside an iframe.
 
-You can also send messages to a chat programmatically. Responses are streamed using server-sent events (SSE).
+## API submission
+
+`POST /api/chat/{identifier}` returns SSE. Reuse a `conversationId` across messages when the workflow uses Agent Memory. For live answer tokens, send the protocol header and handle resets:
 
 <Tabs items={['cURL', 'TypeScript']}>
   <Tab value="cURL">
-```bash
-curl -X POST https://www.sim.ai/api/chat/your-slug \
-  -H "Content-Type: application/json" \
-  -d '{
-    "input": "Hello, I need help with my order",
-    "conversationId": "optional-conversation-id"
-  }'
-```
+    ```bash
+    curl -N -X POST 'https://www.sim.ai/api/chat/your-slug' \
+      -H 'Content-Type: application/json' \
+      -H 'X-Sim-Stream-Protocol: agent-events-v1' \
+      -d '{"input":"I need help with my order","conversationId":"order-4821"}'
+    ```
   </Tab>
   <Tab value="TypeScript">
-```typescript
-const response = await fetch('https://www.sim.ai/api/chat/your-slug', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    input: 'Hello, I need help with my order',
-    conversationId: 'optional-conversation-id'
-  })
-});
-
-// Response is an SSE stream
-const reader = response.body?.getReader();
-const decoder = new TextDecoder();
-
-while (true) {
-  const { done, value } = await reader!.read();
-  if (done) break;
-  console.log(decoder.decode(value, { stream: true }));
-}
-```
+    ```typescript
+    const response = await fetch('https://www.sim.ai/api/chat/your-slug', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Sim-Stream-Protocol': 'agent-events-v1'
+      },
+      body: JSON.stringify({
+        input: 'I need help with my order',
+        conversationId: 'order-4821'
+      })
+    })
+    if (!response.ok) throw new Error(`HTTP ${response.status}`)
+    if (!response.body) throw new Error('Response body is missing')
+
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let rawSse = ''
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        rawSse += decoder.decode(value, { stream: true })
+      }
+    } finally {
+      reader.releaseLock()
+    }
+    ```
   </Tab>
 </Tabs>
 
-### With File Uploads
+The TypeScript example collects raw SSE for inspection. Use the [reference parser](/workflows/deployment/agent-events#reference-client) to render answer text, honor `chunk_reset`, and handle terminal results/errors. Without the protocol header, answer chunks contain settled final-turn text.
+
+### With file uploads
+
+Send file metadata and a base64 data URL:
 
 ```bash
-curl -X POST https://www.sim.ai/api/chat/your-slug \
-  -H "Content-Type: application/json" \
-  -d '{
-    "input": "What does this document say?",
-    "files": [{
-      "name": "report.pdf",
-      "type": "application/pdf",
-      "size": 1048576,
-      "data": "data:application/pdf;base64,..."
-    }]
-  }'
+curl -N -X POST 'https://www.sim.ai/api/chat/your-slug' \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"What does this document say?","files":[{"name":"report.pdf","type":"application/pdf","size":1048576,"data":"data:application/pdf;base64,..."}]}'
 ```
 
-### Protected Chats
+Replace the illustrative data URL with the actual file contents. A request accepts at most 15 files, and each file's encoded `data` field is limited to 14,680,064 characters. The selected model and upload policy can impose additional limits.
 
-For password-protected chats, include the password in the request body:
+### Protected chats
+
+A password-protected request includes `password`:
 
 ```bash
-curl -X POST https://www.sim.ai/api/chat/your-slug \
-  -H "Content-Type: application/json" \
-  -d '{ "password": "secret", "input": "Hello" }'
+curl -N -X POST 'https://www.sim.ai/api/chat/your-slug' \
+  -H 'Content-Type: application/json' \
+  -d '{"password":"your-chat-password","input":"Hello"}'
 ```
 
-For email-protected chats, authenticate with OTP first:
+For email access, request and verify the OTP before sending messages:
 
 ```bash
-# Step 1: Request OTP — sends a 6-digit code to the email address
-curl -X POST https://www.sim.ai/api/chat/your-slug/otp \
-  -H "Content-Type: application/json" \
-  -d '{ "email": "allowed@example.com" }'
-
-# Step 2: Verify OTP — save the Set-Cookie header for subsequent requests
-curl -X PUT https://www.sim.ai/api/chat/your-slug/otp \
-  -H "Content-Type: application/json" \
+curl -X POST 'https://www.sim.ai/api/chat/your-slug/otp' \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"allowed@example.com"}'
+
+curl -X PUT 'https://www.sim.ai/api/chat/your-slug/otp' \
+  -H 'Content-Type: application/json' \
   -c cookies.txt \
-  -d '{ "email": "allowed@example.com", "otp": "123456" }'
+  -d '{"email":"allowed@example.com","otp":"123456"}'
 
-# Step 3: Send messages using the auth cookie from Step 2
-curl -X POST https://www.sim.ai/api/chat/your-slug \
-  -H "Content-Type: application/json" \
+curl -N -X POST 'https://www.sim.ai/api/chat/your-slug' \
+  -H 'Content-Type: application/json' \
   -b cookies.txt \
-  -d '{ "input": "Hello" }'
+  -d '{"input":"Hello","conversationId":"order-4821"}'
 ```
 
-## Troubleshooting
-
-**Chat returns 403** — The deployment is inactive. Open the Deploy modal and re-deploy the workflow.
-
-**"At least one output block is required"** — No output field is selected in the Output dropdown. Open the Deploy modal, go to the Chat tab, and select at least one output from a block.
+Use the real code from the email. Protect `cookies.txt`, which holds the verified session cookie. SSO clients must complete the deployment's SSO authentication flow instead.
 
-**OTP email not arriving** — Confirm the email address is on the allowed list and check spam folders. OTP codes expire after 15 minutes and can be resent after a 30-second cooldown.
+## Limits and troubleshooting
 
-**Chat not loading in iframe** — Check your site's Content Security Policy allows iframes from `sim.ai`.
+- **403:** inspect the response message. The chat may be inactive, or the caller may not meet its access control. Check both before redeploying.
+- **At least one output block is required:** select an output field in **Deploy → Chat**.
+- **OTP missing:** check the allowed address/domain, spam folder, and server mail setup; wait for resend limits before requesting another code.
+- **Iframe unavailable:** check your site's `frame-src` and the browser's authentication-cookie policy.
+- **Old workflow response:** deploy **Update** after changing the draft. Chat uses the active snapshot.
+- **Message too long:** the chat API accepts at most 1,000,000 characters. The model's context window can be smaller; configured memory also contributes to context.
 
-**Responses not updating after workflow changes** — Chat uses the active deployment snapshot. Publish a new deployment from the Deploy modal to pick up your latest changes.
+## Related docs
 
-<FAQ items={[
-  { question: "How does email OTP authentication work?", answer: "When a user opens an email-protected chat, they enter their email address. If it matches the allowed list, Sim sends a 6-digit OTP to that address. The user enters the code, and a session cookie is set for the duration of their visit." },
-  { question: "Is there a message length limit?", answer: "The chat API accepts up to 1,000,000 characters in a message. The selected model's context window may impose a smaller practical limit." },
-]} />
+- [Deployment](/workflows/deployment)
+- [Start](/workflows/triggers/start)
+- [Agent stream events](/workflows/deployment/agent-events)
diff --git a/apps/docs/content/docs/workflows/deployment/index.mdx b/apps/docs/content/docs/workflows/deployment/index.mdx
index f46e7c43fb8..542aed87682 100644
--- a/apps/docs/content/docs/workflows/deployment/index.mdx
+++ b/apps/docs/content/docs/workflows/deployment/index.mdx
@@ -1,64 +1,114 @@
 ---
-title: Deploy Workflows
-description: How a workflow becomes an operational system that outside callers can run, with versioned snapshots and rollback.
+title: Deploy workflows
+description: Create a live workflow snapshot, update it, and restore earlier versions.
 ---
 
 import { Card, Cards } from 'fumadocs-ui/components/card'
 import { Image } from '@/components/ui/image'
 
-A deployment is a published version of a [workflow](/workflows) that outside callers can run. While you build, a workflow lives on your canvas as a draft you can run from the editor. Deploying publishes a fixed copy of that draft and gives it an address: a REST endpoint, a chat page, or a set of [MCP](/workflows/deployment/mcp) tools. Each is a **surface**, a channel callers reach the same published workflow through.
+Deploy a workflow when API callers, chat clients, MCP tools, or automatic triggers need to run it. Deployment captures a version of the workflow; later draft edits do not reach live callers until you update it.
 
-## The deployment model
+You need workspace **Admin** access to deploy or change live versions. Organization permission groups can also restrict API, chat, or MCP deployment.
+
+## Deploy and update [#the-deployment-model]
+
+1. Test the draft with **Run** in the workflow builder.
+2. Open **Deploy → General**.
+3. Click **Deploy** for the first version, or **Update** to deploy your current draft.
+4. Confirm **Live Workflow** and the live version in the **Versions** table. Check deployment status or errors before assuming the change is live.
 
 ### Snapshot
 
-A **snapshot** is an immutable copy of your workflow taken at the moment you deploy. It is frozen: editing the canvas afterward changes your draft, not the snapshot. Every call to your deployment runs against the snapshot, so a half-finished edit on the canvas never reaches a live caller. Publishing again takes a fresh snapshot of the current draft.
+A snapshot freezes the workflow definition at deploy time. Editing blocks or connections changes the draft, not that snapshot. Referenced tables, files, secrets, and external services remain separate resources; deployment does not freeze their contents.
 
 ### Version
 
-Each snapshot is recorded as a numbered **version** (v1, v2, and so on) in the Versions table, tagged with who deployed it and when. Versions are independent: one is live at a time, marked with a green dot, and the rest stay available to rename, describe, load back to the canvas, or promote. You publish v1 with **Deploy** and every later **Update** adds the next version.
-
-<Image src="/static/api-deployment/api-versions-menu.png" alt="Versions table with v2 live and the v1 menu open on Promote to live" width={700} height={303} className="mx-auto h-auto w-full max-w-xl" />
+Each deployment records a numbered version, who deployed it, and when. **Update** creates the next snapshot; earlier versions remain available for comparison, naming, descriptions, restoring the draft, or promotion.
 
 ### Live version
 
-The **live version** is the one snapshot currently exposed through every surface. The General tab shows it as **Live Workflow**, a read-only minimap of exactly what callers run. Only one version is live at a time. Promoting a different version, or updating to a new one, swaps which snapshot is live without affecting the others.
+One version is live at a time. **Live Workflow** shows the deployed snapshot in a read-only preview. API, chat, MCP, and automatic triggers use deployed configuration rather than unfinished draft edits.
 
 ### Update
 
-After you change the canvas on a deployed workflow, an **Update deployment** badge appears in the toolbar to flag that your live version is behind your draft. Clicking **Update** takes a new snapshot, records it as the next version, and makes it live, all without reopening the deploy modal.
+When the draft differs from its deployed version, **Update** appears in the workflow builder toolbar. Click it to deploy an updated snapshot without reopening the modal:
 
-### Promote to live
+<Image src="/static/api-deployment/api-update-button.png" alt="Update button beside Run with an Update deployment tooltip" width={400} height={186} className="mx-auto h-auto w-full max-w-[240px]" />
 
-**Promote to live** makes an earlier version the live one again. It is the fast path for rollback: if a new deployment misbehaves, promote the last known-good version to restore it instantly. Promoting reuses an existing snapshot, so it does not create a new version.
+Redeploy after changing automatic trigger settings or the workflow inputs used by an MCP tool.
 
+## Manage versions
 
+Use a version's **⋮** menu:
 
-## The surfaces
+| Action | Effect |
+| --- | --- |
+| **Rename** | Give the version a descriptive name |
+| **Add description** / **Edit description** | Record what changed |
+| **Compare** | Compare workflow versions |
+| **Promote to live** | Activate an existing snapshot |
+| **Load deployment** | Replace the draft with that snapshot |
+
+**Load deployment** changes your draft. Preserve draft work you need before loading another version; it does not itself make that version live.
+
+### Promote to live
+
+Promote a previous version to restore its deployed definition. Promotion reuses the snapshot and does not create a new version or replace the draft. Confirm the active version after the operation succeeds.
+
+## Undeploy
+
+**Undeploy** takes the workflow's deployment offline and removes its automatic schedule registrations. New callers and triggers can no longer start runs through that deployment. Runs already executing are distinct from new or queued work; undeploying is not a substitute for cancelling a run.
 
-Every surface runs the same live snapshot. You manage them from the tabs of the deploy modal.
+## Manage deployment through the API
 
-The most common surface is the **API**. Once deployed, your workflow answers at:
+The legacy v1 API supports deploying the current draft, undeploying, and rolling back. It requires an API-key caller with Admin access to the workflow's workspace and the deployment capability; a workspace API key cannot satisfy the Admin requirement.
 
+```bash
+curl -X POST 'https://www.sim.ai/api/v1/workflows/{workflow-id}/deploy' \
+  -H "X-API-Key: $SIM_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Release 4","description":"Fixes the agent prompt"}'
 ```
-POST https://www.sim.ai/api/v2/workflows/{workflow-id}/execute
+
+The deploy body is optional. To undeploy:
+
+```bash
+curl -X DELETE 'https://www.sim.ai/api/v1/workflows/{workflow-id}/deploy' \
+  -H "X-API-Key: $SIM_API_KEY"
 ```
 
-Send the workflow's [Input Format](/workflows/triggers/start) as the request body's `input` value. The response includes workflow output and execution metadata; see [API deployment](/workflows/deployment/api) for response modes.
+To activate the previous version, or pass `{"version": N}` for a specific version:
 
 ```bash
-curl -X POST https://www.sim.ai/api/v2/workflows/{workflow-id}/execute \
-  -H "X-API-Key: $SIM_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{ "input": { "message": "Refund request from customer #4821" } }'
+curl -X POST 'https://www.sim.ai/api/v1/workflows/{workflow-id}/rollback' \
+  -H "X-API-Key: $SIM_API_KEY"
 ```
 
-{/* VISUAL: deploy modal tab bar. General · API · MCP · Chat. */}
+See [Deploy Workflow](/api-reference/workflows/deployWorkflow), [Undeploy Workflow](/api-reference/workflows/undeployWorkflow), and [Rollback Workflow](/api-reference/workflows/rollbackWorkflow) for full contracts and deployment status.
+
+## The surfaces
+
+A workflow can be available through several surfaces at once:
 
 <Cards>
-  <Card title="API" href="/workflows/deployment/api" description="A REST endpoint any application can call, with sync, streaming, and async modes." />
-  <Card title="Chat" href="/workflows/deployment/chat" description="A shareable conversational page that keeps conversation history." />
-  <Card title="MCP" href="/workflows/deployment/mcp" description="Expose the workflow as tools an external AI assistant can call." />
+  <Card title="API" href="/workflows/deployment/api" description="Call a deployed workflow with sync, SSE, or async execution." />
+  <Card title="Chat" href="/workflows/deployment/chat" description="Share a conversational interface; configure Agent Memory for multi-turn context." />
+  <Card title="MCP" href="/workflows/deployment/mcp" description="Expose a workflow as a tool an external assistant can call." />
 </Cards>
 
-Open [Logs](/logs-debugging) to confirm which deployment version a run used.
+A basic v2 API call sends named Start inputs inside `input`:
+
+```bash
+curl -X POST 'https://www.sim.ai/api/v2/workflows/{workflow-id}/execute' \
+  -H "X-API-Key: $SIM_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"input":{"message":"Refund request from customer #4821"}}'
+```
+
+Ordinary calls use the deployed snapshot. V2 also has an explicit manual draft mode for authorized personal API-key or OAuth callers with Write access; it does not support async execution. See [API deployment](/workflows/deployment/api) for modes and result envelopes.
+
+## Related docs
+
+- [API deployment](/workflows/deployment/api)
+- [Start inputs](/workflows/triggers/start)
+- [Logs](/logs-debugging) to verify the version a recorded run used
diff --git a/apps/docs/content/docs/workflows/deployment/mcp.mdx b/apps/docs/content/docs/workflows/deployment/mcp.mdx
index 45429ab3c20..dc4a56760ae 100644
--- a/apps/docs/content/docs/workflows/deployment/mcp.mdx
+++ b/apps/docs/content/docs/workflows/deployment/mcp.mdx
@@ -1,149 +1,83 @@
 ---
 title: MCP deployment
-description: Expose your workflows as MCP tools for external AI assistants and applications
+description: Expose deployed workflows as tools for external MCP clients.
 ---
 
-import { Image } from '@/components/ui/image'
-import { Video } from '@/components/ui/video'
 import { Callout } from 'fumadocs-ui/components/callout'
 
-Deploy your workflows as MCP tools to make them accessible to external AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients.
-
-## Creating and Managing MCP Servers
-
-MCP servers group your workflow tools together. Create and manage them in workspace settings:
-
-<div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="mcp/mcp-server.mp4" width={700} height={450} />
-</div>
-
-1. Navigate to **Settings → MCP Servers**
-
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/mcp-servers-settings.png"
-    alt="MCP Servers settings page"
-    width={700}
-    height={303}
-    className="my-6"
-  />
-</div>
-
-2. Click **Add**
-3. Enter a name and optional description
-4. Choose access: **API Key** (private, requires `X-API-Key` header) or **Public** (no authentication)
-5. Optionally select deployed workflows to add as tools immediately
-
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/mcp-server-add-modal.png"
-    alt="Add New MCP Server modal"
-    width={550}
-    height={371}
-    className="my-6 mx-auto h-auto w-full max-w-md"
-  />
-</div>
-
-6. Click **Add Server**
-7. Click **Details** to view the MCP server
-
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/mcp-server-details.png"
-    alt="MCP Server details view"
-    width={700}
-    height={491}
-    className="my-6 mx-auto h-auto w-full max-w-xl"
-  />
-</div>
-
-8. Copy the server URL for use in your MCP clients
-9. View and manage all tools added to the server
-
-## Adding a Workflow as a Tool
-
-Once your workflow is deployed, you can expose it as an MCP tool:
-
-<div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="mcp/mcp-deploy-tool.mp4" width={700} height={450} />
-</div>
-
-1. Open your deployed workflow
-2. Click **Deploy** and go to the **MCP** tab
-
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/mcp-deploy-modal.png"
-    alt="Workflow Deployment MCP tab"
-    width={380}
-    height={487}
-    className="my-6"
-  />
-</div>
-
-3. Configure the tool name and description (the description defaults to the workflow's description)
-4. Review the parameter descriptions (prefilled from your Start block inputs) and override any per tool
-5. Select which MCP servers to add it to
-6. Click **Save Tool**
-
-<Callout type="info">
-The workflow must be deployed before it can be added as an MCP tool.
+Model Context Protocol (MCP) lets an assistant discover and call tools. A Sim workflow MCP server groups deployed workflows into tools an external client can invoke.
+
+You need workspace **Admin** access to create or change workflow MCP servers and add or remove workflow tools. Organization permission groups can also restrict MCP deployment. Read access lets members view servers.
+
+## Create an MCP server [#creating-and-managing-mcp-servers]
+
+1. Open **Settings → MCP Servers** and click **Add**.
+2. Enter a name and optional description.
+3. Choose **API Key** or **Public** access.
+4. Optionally select already-deployed workflows to add immediately.
+5. Click **Add Server**, then open **Details** and copy its URL.
+
+Private clients send `X-API-Key` when connecting. For public servers, omit that header.
+
+<Callout type="warn">
+A public server exposes its configured workflow tools without authentication. Review the actions and outputs of every tool on the server before enabling public access.
 </Callout>
 
-## Tool Configuration
+## Add a workflow as a tool [#adding-a-workflow-as-a-tool]
+
+Deploy the workflow before adding it to a server:
+
+1. Open the workflow's **Deploy → MCP** tab.
+2. Enter the tool name and description.
+3. Review the parameters derived from the deployed Start inputs.
+4. Select the MCP servers that should expose the tool.
+5. Click **Save Tool**.
+6. Connect a client and confirm that it lists and can call the tool. Check the run in [Logs](/logs-debugging).
 
-### Tool Name
-Use lowercase letters, numbers, and underscores. The name should be descriptive and follow MCP naming conventions (e.g., `search_documents`, `send_email`).
+Tools execute the workflow's active deployment, like ordinary API calls. Deploy an update after changing workflow logic or inputs.
+
+## Tool configuration
+
+### Tool name
+
+Use lowercase letters, numbers, and underscores, such as `search_documents`. Choose a name that distinguishes the action from other tools on the server.
 
 ### Description
-Write a clear description of what the tool does. This helps AI assistants understand when to use the tool. If you leave it blank, the tool falls back to the workflow's description.
+
+Describe what the workflow does and when it should be called. A blank description falls back to the workflow's description when available.
 
 ### Parameters
-Your workflow's input format fields become tool parameters. Each parameter's description defaults to the description set on that input in the Start block; edit it here to override it for this tool (the Start block stays the default source). Descriptions help AI assistants provide correct values.
 
-<Callout type="info">
-Parameter descriptions live on your Start block inputs. A deployed tool picks up Start block changes the next time you redeploy the workflow; use a per-tool override only when a tool needs a different description than the default.
-</Callout>
+The workflow's deployed input fields become tool parameters. Their descriptions default to the descriptions on Start's **Inputs**. Set a per-tool override only when that tool needs different wording; it does not edit Start.
 
-## Connecting MCP Clients
+Redeploy to make changes to Start fields and default descriptions available to the tool. Preserve meaningful descriptions so the client knows what values to supply.
 
-Sim generates a ready-to-paste configuration for every supported client. To get it:
+## Connect an MCP client [#connecting-mcp-clients]
 
-1. Navigate to **Settings → MCP Servers**
-2. Click **Details** on your server
-3. Under **MCP Client**, select your client — **Cursor**, **Codex**, **Claude Code**, **Claude Desktop**, **VS Code**, or **Sim**
-4. Copy the configuration and follow the authentication note below it
+Open your server's **Details**, copy its URL, and choose a client under **MCP Client**. The UI offers client presets, but check the current client documentation when its configuration differs from a generated example.
 
-<div className="flex justify-center">
-  <Image
-    src="/static/blocks/mcp-client-config.png"
-    alt="MCP client configuration panel"
-    width={700}
-    height={517}
-    className="my-6 mx-auto h-auto w-full max-w-xl"
-  />
-</div>
+The examples below connect directly over HTTP. Replace `YOUR_SERVER_URL`; private servers also require a valid Sim API key. For public servers, remove the authentication header settings.
 
 ### Cursor
 
-Cursor supports direct URL configuration. Add to your Cursor MCP settings (`.cursor/mcp.json`):
+In `.cursor/mcp.json`, use Cursor's environment interpolation syntax:
 
 ```json
 {
   "mcpServers": {
     "my-sim-workflows": {
       "url": "YOUR_SERVER_URL",
-      "headers": { "X-API-Key": "$SIM_API_KEY" }
+      "headers": { "X-API-Key": "${env:SIM_API_KEY}" }
     }
   }
 }
 ```
 
-Cursor also provides a one-click install button in the server detail view.
+Make `SIM_API_KEY` available to the Cursor process. Cursor also has a one-click install link in Sim's server details. See [Cursor's MCP configuration](https://cursor.com/docs/mcp#config-interpolation).
 
 ### Codex
 
-Add this to your Codex configuration (`~/.codex/config.toml`):
+In `~/.codex/config.toml`:
 
 ```toml
 [mcp_servers."my-sim-workflows"]
@@ -151,72 +85,72 @@ url = "YOUR_SERVER_URL"
 env_http_headers = { "X-API-Key" = "SIM_API_KEY" }
 ```
 
-Set the `SIM_API_KEY` environment variable before starting Codex.
+Set `SIM_API_KEY` in the environment before starting Codex. `env_http_headers` maps a header name to an environment-variable name; it does not contain the key itself. See [official OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).
 
 ### Claude Code
 
-Run this command in your terminal:
-
 ```bash
-claude mcp add "my-sim-workflows" --url "YOUR_SERVER_URL" --header "X-API-Key:$SIM_API_KEY"
+claude mcp add --transport http my-sim-workflows 'YOUR_SERVER_URL' \
+  --header "X-API-Key: $SIM_API_KEY"
 ```
 
+The shell expands the variable in this command. Follow [Claude Code's MCP instructions](https://code.claude.com/docs/en/mcp#option-1-add-a-remote-http-server) for configuration scope and authentication.
+
 ### Claude Desktop
 
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+Add a remote custom connector with the server URL. For a private server, add `X-API-Key` and its value under **Request headers**. For a public server, use the no-sign-in configuration without a key.
 
-```json
-{
-  "mcpServers": {
-    "my-sim-workflows": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "YOUR_SERVER_URL", "--header", "X-API-Key:$SIM_API_KEY"]
-    }
-  }
-}
-```
+Remote connectors reach the server from Anthropic's infrastructure, even when used in Claude Desktop. The server must be reachable from that service; a URL reachable only on your computer is insufficient. Team/Enterprise connector administration also has its own Claude-side permissions. See [Claude's current custom-connector setup](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
 
 ### VS Code
 
-Add to your VS Code MCP settings (`.vscode/mcp.json`):
+Use direct HTTP in `.vscode/mcp.json`. An input prompt keeps the key out of the checked-in configuration:
 
 ```json
 {
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "sim-api-key",
+      "description": "Sim API key",
+      "password": true
+    }
+  ],
   "servers": {
     "my-sim-workflows": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "YOUR_SERVER_URL", "--header", "X-API-Key:$SIM_API_KEY"]
+      "type": "http",
+      "url": "YOUR_SERVER_URL",
+      "headers": { "X-API-Key": "${input:sim-api-key}" }
     }
   }
 }
 ```
 
-<Callout type="info">
-For public servers, omit the `X-API-Key` header and `--header` arguments. Public servers don't require authentication.
-</Callout>
+For a public server, remove `headers` and the unused input. See [VS Code's MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).
 
-<Callout type="warn">
-`$SIM_API_KEY` is a placeholder. For Claude Desktop and VS Code configs, replace it with your actual API key since these clients don't expand environment variables in JSON config files. Codex reads `SIM_API_KEY` from the environment, while Claude Code and Cursor handle variable expansion natively.
-</Callout>
+### Sim
+
+Choose **Sim** in the server's client picker to use the supported Sim connection flow. [Using MCP tools](/agents/mcp) explains connected server tools in Agent blocks.
+
+## Server management
+
+From **Settings → MCP Servers**, open the server to view its URL and tools, add deployed workflows, or remove tools. Removing a tool removes that exposure; it does not delete the workflow.
 
-## Server Management
+Deleting a server removes the server and its configured tools. Disconnect clients that used its URL, or point them at a replacement server.
 
-From the server detail view in **Settings → MCP Servers**, you can:
+### Permission requirements
 
-- **View tools**: See all workflows added to a server
-- **Copy URL**: Get the server URL for MCP clients
-- **Add workflows**: Add more deployed workflows as tools
-- **Remove tools**: Remove workflows from the server
-- **Delete server**: Remove the entire server and all its tools
+| Action | Required workspace role |
+| --- | --- |
+| View workflow MCP servers | Read, Write, or Admin |
+| Create, update, or delete workflow MCP servers | Admin |
+| Add or remove workflow tools | Admin |
 
-MCP tools execute the workflow's active deployment, just like API calls.
+These management operations do not accept workspace API keys. Invoking a private server is a separate authenticated operation with its own key/OAuth access and scope requirements.
 
-## Permission Requirements
+## Related docs
 
-| Action | Required Permission |
-|--------|-------------------|
-| Create MCP servers | **Write** or **Admin** |
-| Add workflows to servers | **Write** or **Admin** |
-| View MCP servers | **Read**, **Write**, or **Admin** |
-| Delete MCP servers | **Admin** |
+- [Deployment](/workflows/deployment)
+- [Start inputs](/workflows/triggers/start)
+- [Using MCP tools](/agents/mcp)
+- [Workflow MCP server API](/api-reference/mcp-servers/listWorkflowMcpServers)
diff --git a/apps/docs/content/docs/workflows/deployment/meta.json b/apps/docs/content/docs/workflows/deployment/meta.json
index dc71f9ac69d..99eb2d3323a 100644
--- a/apps/docs/content/docs/workflows/deployment/meta.json
+++ b/apps/docs/content/docs/workflows/deployment/meta.json
@@ -1,4 +1,4 @@
 {
   "title": "Deployment",
-  "pages": ["api", "chat", "agent-events", "mcp"]
+  "pages": ["api", "chat", "mcp", "agent-events"]
 }
diff --git a/apps/docs/content/docs/workflows/how-it-runs.mdx b/apps/docs/content/docs/workflows/how-it-runs.mdx
index ef3e1915b6f..bf0c43bb0b2 100644
--- a/apps/docs/content/docs/workflows/how-it-runs.mdx
+++ b/apps/docs/content/docs/workflows/how-it-runs.mdx
@@ -1,6 +1,6 @@
 ---
 title: How workflows run
-description: How Sim orders the blocks, runs independent ones in parallel, and follows branches.
+description: Understand dependency order, concurrent branches, errors, and execution duration.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
@@ -12,50 +12,74 @@ import {
   WorkflowPreview,
 } from '@/components/workflow-preview'
 
-When you run a workflow, Sim works out the order from the [connections](/workflows/connections): a block runs as soon as the blocks it depends on have finished.
+Sim orders a run from its connections. A block becomes ready when the active upstream blocks it depends on have finished.
 
 ## Blocks run as soon as they can
 
-Multiple blocks in a workflow can be executing at the same time. A block starts the moment its dependencies finish, and it waits on nothing else.
+Independent blocks can execute at the same time:
 
 <WorkflowPreview workflow={CONCURRENCY_WORKFLOW} height={220} />
 
-Here the Customer Support and Deep Researcher agents each depend only on Start, so neither waits for the other.
+Customer Support and Deep Researcher each depend only on Start, so neither waits for the other.
 
 ## A block waits for all its inputs
 
-When several blocks feed into one, that block waits for every feeder that is going to run, then runs once with each of their outputs available to read. A feeder on a branch that wasn't taken doesn't hold it up. You don't merge the outputs yourself.
+When several blocks feed one block, it waits for every feeder on an active path, then runs once with their outputs available. An unselected branch does not hold up the join.
 
 <WorkflowPreview workflow={COMBINATION_WORKFLOW} height={220} />
 
-The Function block here runs after both agents complete, with both of their outputs ready.
+Combine runs after both agents finish. It reads each output by name; you do not need a separate merge operation to make those outputs available.
+
+If several branches end without joining, the last terminal block to finish supplies the default workflow result. Use a final block or [Response](/workflows/blocks/response) to choose the result explicitly.
 
 ## Branches follow one path
 
-A workflow can split. A [Condition](/workflows/blocks/condition) block branches on an explicit rule; a [Router](/workflows/blocks/router) block lets a model choose the path. Only the branch that is taken runs. A block on a branch that didn't run produces no output, which is why a [connection tag](/workflows/connections) pointing at it comes back empty.
+[Condition](/workflows/blocks/condition) selects a branch using a rule. [Router](/workflows/blocks/router) lets a model choose a route. Only the selected path runs:
 
 <WorkflowPreview workflow={ROUTING_WORKFLOW} height={400} />
 
-To repeat work, a [Loop](/workflows/blocks/loop) block runs its inner blocks over a list, a count, or while a condition holds, and a [Parallel](/workflows/blocks/parallel) block runs them for several items at once.
+A skipped block produces no output. A reference to that known block resolves empty; see [connection syntax](/workflows/connections).
+
+[Loop](/workflows/blocks/loop) repeats its inner blocks over a collection, a count, or a condition. [Parallel](/workflows/blocks/parallel) runs inner blocks for several items at once. Their item/index context and block outputs are scoped to the iteration or branch, but workflow variables are shared across the run. Avoid concurrent writes to the same variable.
 
 <Callout type="info">
-A workflow can call other workflows, through a Workflow block, an MCP tool, or an API block. Sim tracks the call chain and stops a run that exceeds 25 hops, so workflows that call each other can't loop forever.
+Sim tracks calls between workflows through Workflow blocks, MCP tools, and API blocks. It rejects a call chain at the 25-hop limit, preventing unbounded recursion through those paths.
 </Callout>
 
 ## When a block fails
 
-A block that errors fails the run: blocks already running finish, and nothing new starts. To handle the failure instead, connect the block's **error port** — the run follows the [error path](/workflows/connections) and continues.
+An unhandled block error fails the run. Already-running blocks may finish, but no new work starts. Connect the block's **error port** to handle the failure and continue along an error path:
 
 <WorkflowPreview workflow={ERROR_PATH_WORKFLOW} height={260} />
 
-Here `throwError` fails, so the run leaves through its red error port to `handleError`; `handleSuccess` on the normal path never runs.
+When throwError fails, handleError runs through the red error port; handleSuccess is skipped. A handled error can appear in the trace without failing the whole run.
 
-{/* Why this section exists: run timeouts are the only hard-error class provable at scale in platform logs (2,415 five-minute timeouts in 14 days, 2026-06). Limits verified in lib/core/execution-limits/types.ts; env-overridable. */}
+For an API block, non-2xx HTTP responses, network failures, and timeouts follow its error behavior. Do not expect a normal downstream status check to catch an unsuccessful request.
 
 ## How long a run can take
 
-A synchronous run is capped at **5 minutes on the free plan** and **50 minutes on paid plans**. Async runs get **90 minutes** by default; Enterprise administrators can configure their workflow policy up to **7 days**. Direct async API callers may shorten that policy for an individual request, but cannot extend it. A run that hits the ceiling fails with "Execution timed out." The usual causes are a loop over a large list or a slow agent or API call — split the work, or run it async. Self-hosted deployments can configure these limits.
+Current billing-enabled defaults are:
+
+| Plan | Synchronous run | Asynchronous run |
+| --- | --- | --- |
+| Community | 5 minutes | 90 minutes |
+| Pro / Max / Team | 50 minutes | 90 minutes |
+| Enterprise | 50 minutes | 90 minutes; configurable up to 7 days |
+
+The effective policy and deployment configuration determine the limit. An async API caller can shorten the account policy with `executionTimeoutSeconds`, but cannot extend it. A timeout fails the run with `Execution timed out`.
+
+Large loops and slow model or API calls can use up the budget. Batch a large collection or use [async API execution](/workflows/deployment/api#asynchronous) when appropriate. Async runs still have a limit.
+
+Billing-disabled self-hosted deployments run without a plan-based timeout by default. Operators can set execution timeout environment variables; see [self-hosted limits](/platform/self-hosting/environment-variables#limits).
 
 ## Watching a run
 
-While a workflow runs, the editor shows each block's state live: queued, running, done, or errored. Every run is recorded, so you can open the [logs](/logs-debugging) to see what each block received and returned after it finishes.
+The workflow builder shows live block states while an editor run executes. Open [Logs](/logs-debugging) to inspect recorded inputs, outputs, and errors. Available history depends on access and retention; a request rejected before a run starts may not have an execution log.
+
+Editor runs use the draft. API, chat, MCP, and automatic trigger runs normally use a deployed snapshot; [deployment](/workflows/deployment) explains updates and the v2 API's explicit manual draft mode.
+
+## Related docs
+
+- [How blocks pass data](/workflows/data-flow)
+- [Deployment](/workflows/deployment)
+- [Logs](/logs-debugging)
diff --git a/apps/docs/content/docs/workflows/index.mdx b/apps/docs/content/docs/workflows/index.mdx
index 0549aee0ac4..c1bba93219a 100644
--- a/apps/docs/content/docs/workflows/index.mdx
+++ b/apps/docs/content/docs/workflows/index.mdx
@@ -1,18 +1,14 @@
 ---
 title: Workflows
-description: A workflow is a visual program made of blocks, a saved procedure your AI systems run.
+description: Connect blocks into reusable agent logic, then run a draft or deploy a version for callers and triggers.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
 import { Card, Cards } from 'fumadocs-ui/components/card'
 import { WorkflowPreview, CLASSIFY_WORKFLOW } from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
 
-Your Sim workspace is where your AI systems live. A system is made of two things. **Workflows** are the procedures it runs. **Resources** are the data those procedures work with: tables, knowledge bases, and files.
+A workflow connects blocks into a reusable procedure. A trigger supplies the input, blocks perform the work, and connections determine when each block runs.
 
-A workflow is a visual program made of blocks. Like a recipe, it's a fixed set of steps you write once and run again and again, each time with new input. Each block does one step of work, and connections set the order the blocks run in.
-
-Here's a simple one. It takes an incoming customer message, classifies its category and urgency, and returns the result:
+This example classifies a customer message by category and urgency. Its Agent requests structured output through **Response Format**:
 
 <WorkflowPreview workflow={CLASSIFY_WORKFLOW} />
 
@@ -20,74 +16,65 @@ Here's a simple one. It takes an incoming customer message, classifies its categ
 
 ### Trigger
 
-A **trigger** is where a workflow begins and what it hands in. A workflow can have multiple triggers, but each run starts from one. The [Start](/workflows/triggers/start) trigger takes input directly — from the editor while you build, and from an API call or a chat once deployed. For runs that should start on an event or a timer, you swap in a [webhook](/workflows/triggers/webhook) or [schedule](/workflows/triggers/schedule) trigger, and the downstream blocks don't change.
-
-<WorkflowPreview workflow={CLASSIFY_WORKFLOW} height={170} highlightBlock="start" />
+A **trigger** starts a run and supplies its input. A workflow can have several triggers, but each run enters through one.
 
-In our example, the Start trigger receives the customer message. Later blocks read it by name, as `<start.input>`.
+[Start](/workflows/triggers/start) accepts editor, API, and chat input. Event and timer triggers start runs automatically after deployment.
 
 ### Block
 
-A **block** is a single step, and each does one thing: an [Agent](/workflows/blocks/agent) reasons with a model, a [Function](/workflows/blocks/function) runs code, a [Condition](/workflows/blocks/condition) branches, a [Loop](/workflows/blocks/loop) repeats. Some blocks are deterministic (Function, Condition); others are model-driven (Agent) and can vary run to run. That difference is the first thing to know when debugging.
+A **block** performs a step. An [Agent](/workflows/blocks/agent) calls a model and can use tools; a [Function](/workflows/blocks/function) runs code; a [Condition](/workflows/blocks/condition) chooses a branch.
 
-<WorkflowPreview workflow={CLASSIFY_WORKFLOW} height={170} highlightBlock="agent" />
+A **tool** is an action an Agent can call within its step, such as searching a knowledge base or sending a Slack message. The block fixes that step's place in the workflow; the Agent chooses when to call its configured tools.
 
-Our example has one Agent block, configured with a model and a prompt, that reads the message and returns a classification.
-
-<Callout type="info">
-A block is not the same as a tool. A **tool** is a capability an agent can call during a step: send a Slack message, search a knowledge base, run a snippet of code. An [Agent](/workflows/blocks/agent) block decides which tools to call and when. Blocks are the workflow's steps; tools are the actions an agent takes inside one.
-</Callout>
+Function and Condition behavior is determined by the code or rule you supply. Model-driven blocks can produce different answers across runs.
 
 ### Connection
 
-A **connection** wires one block to the next and sets the execution order: the block at the arrow's head runs after the one at its tail. Once a block has run, the blocks after it can read its output by reference.
-
-<WorkflowPreview workflow={CLASSIFY_WORKFLOW} height={170} highlightEdge="start-agent" />
+A **connection** sets execution order. A block becomes ready when its active upstream dependencies have finished; independent branches can run at the same time.
 
-You read an earlier output with a **connection tag**, written `<blockName.field>`: name the block, then the value you want. The Agent's prompt reads the message with `<start.input>`; a later block could read the Agent's answer with `<agent.content>`.
-
-Most workflow issues are data issues, not crashed blocks: a reference points at a value that isn't there, or a block on the path didn't run. See [how blocks pass data](/workflows/data-flow) for outputs, references, and types.
+Read an earlier output with a **connection tag**, such as `<start.input>` or `<agent.content>`. The tag's first segment is the block's name, not its type. See [how blocks pass data](/workflows/data-flow) and [connection syntax](/workflows/connections).
 
 ### Output
 
-An **output** is what a block produces; later blocks read it through connection tags. By default the workflow's output is its **last block's** output. In our example that's the Agent's `{ category, urgency }`. There's no separate return step.
+Each block produces its own output. A successful structured response in this example exposes `<agent.category>` and `<agent.urgency>`; ordinary Agent text appears in `content`. Check the output panel to confirm the actual shape.
 
-<WorkflowPreview workflow={CLASSIFY_WORKFLOW} height={170} highlightBlock="agent" />
+In a simple chain, the workflow returns its last block's output. If several branches end independently, the last terminal block to finish supplies the default result. Join the branches into a final block or use [Response](/workflows/blocks/response) to choose a deliberate result.
 
-On reuse, the consumer picks which outputs it wants by name: a [chat deployment](/workflows/deployment/chat), a [table column](/tables/workflow-columns), or an [API call](/workflows/deployment/api) each select block outputs individually. It's the same idea as connection tags, applied at the workflow's edge. (For precise HTTP control, add a [Response block](/workflows/blocks/response).)
+Callers can select individual block fields for chat responses, table workflow columns, or API output projection. The v2 API keeps its run-resource envelope: a Response block's result appears inside `data.output`, without changing the endpoint's HTTP status or headers.
 
 ## Kinds of blocks [#blocks]
 
-Core blocks come in three kinds: blocks that **do work** ([Agent](/workflows/blocks/agent), [Function](/workflows/blocks/function), [API](/workflows/blocks/api)), blocks that **direct the flow** ([Condition](/workflows/blocks/condition), [Router](/workflows/blocks/router), [Loop](/workflows/blocks/loop), [Parallel](/workflows/blocks/parallel)), and blocks that **shape the run** ([Response](/workflows/blocks/response), [Guardrails](/workflows/blocks/guardrails), [Wait](/workflows/blocks/wait), and more).
-
-Two larger families do more specific jobs:
+- **Work:** [Agent](/workflows/blocks/agent), [Function](/workflows/blocks/function), [API](/workflows/blocks/api), and [integrations](/integrations).
+- **Control flow:** [Condition](/workflows/blocks/condition), [Router](/workflows/blocks/router), [Loop](/workflows/blocks/loop), and [Parallel](/workflows/blocks/parallel).
+- **Run behavior:** [Response](/workflows/blocks/response), [Guardrails](/workflows/blocks/guardrails), [Wait](/workflows/blocks/wait), and other core blocks.
 
-- **[Integrations](/integrations)** connect to an external service — Gmail, Slack, Notion, a database — with hundreds available. An agent can also call them as tools.
-- **Triggers** are the blocks that start a workflow.
+An output can feed several downstream blocks without duplicating the source block.
 
 ## How a workflow starts [#triggers]
 
-A trigger decides what starts the run and what input it receives. **Native triggers** need no connected account: [Start](/workflows/triggers/start) (manual, API, or chat), [Schedule](/workflows/triggers/schedule) (a timer), [Webhook](/workflows/triggers/webhook) (any inbound HTTP request), [RSS](/workflows/triggers/rss) (a new feed item), and [Table](/workflows/triggers/table) (a row change in a Sim table). **Integration triggers** fire on an event in a connected service — a GitHub push, a new email — and hand it to the workflow.
+| Trigger | Starts a run from |
+| --- | --- |
+| [Start](/workflows/triggers/start) | Editor input, an API call, or a chat message |
+| [Schedule](/workflows/triggers/schedule) | A configured timer or cron expression |
+| [Webhook](/workflows/triggers/webhook) | An accepted HTTP request to its generated URL |
+| [RSS](/workflows/triggers/rss) | An unseen RSS or Atom feed item |
+| [Table](/workflows/triggers/table) | A row insert, update, or delete in a Sim table |
+| [Sim Workspace Events](/workflows/triggers/sim) | Run events, deployments, or workspace alert conditions |
+| Integration trigger | An event in a connected service, such as a GitHub push or new email |
 
-<Callout type="info">
-Automatic trigger runs use the active [deployment](/workflows/deployment), so redeploy after changing a workflow for those runs to pick up the new version. Editor runs use the draft.
-</Callout>
+Editor runs use the draft. Automatic triggers use deployed configuration, so deploy an updated version after changing their blocks, connections, or settings.
 
-## How it runs
+## Run and deploy [#how-it-runs]
 
-When a workflow runs, blocks execute in dependency order: a block runs as soon as the blocks it depends on have finished, so independent branches run in parallel. Conditions, loops, and parallel blocks change the path data takes.
+Use **Run** in the workflow builder to test a draft and inspect its block outputs. Open [Logs](/logs-debugging) to inspect recorded runs.
 
-<Card title="How workflows run" href="/workflows/how-it-runs" description="Execution order, concurrency, branches, and loops." />
+[Deploy](/workflows/deployment) creates a versioned snapshot for API, chat, MCP, and automatic trigger runs. Editing the draft does not change the live version; **Update** deploys a new snapshot.
 
-## Next
+## Related docs [#next]
 
 <Cards>
-  <Card title="How blocks pass data" href="/workflows/data-flow" description="Outputs, references, and the data types you'll work with." />
-  <Card title="Agent" href="/workflows/blocks/agent" description="The most common block: reason with a model and call tools." />
-  <Card title="Start" href="/workflows/triggers/start" description="The default trigger — run from the editor, an API, or chat." />
-  <Card title="How workflows run" href="/workflows/how-it-runs" description="Execution order, concurrency, and control flow." />
+  <Card title="How blocks pass data" href="/workflows/data-flow" description="Read outputs, references, and data types." />
+  <Card title="How workflows run" href="/workflows/how-it-runs" description="Dependency order, branches, failures, and duration." />
+  <Card title="Start" href="/workflows/triggers/start" description="Define inputs for editor, API, and chat runs." />
+  <Card title="Deploy workflows" href="/workflows/deployment" description="Manage live versions and caller access." />
 </Cards>
-
-<FAQ items={[
-  { question: "Can one block's output connect to multiple blocks?", answer: "Yes. A single output can feed several blocks, so you can fan data out from one step to multiple paths without duplicating the block." },
-]} />
diff --git a/apps/docs/content/docs/workflows/meta.json b/apps/docs/content/docs/workflows/meta.json
index 676b70039b6..52b29c39787 100644
--- a/apps/docs/content/docs/workflows/meta.json
+++ b/apps/docs/content/docs/workflows/meta.json
@@ -1,8 +1,8 @@
 {
   "title": "Workflows",
   "pages": [
-    "how-it-runs",
     "data-flow",
+    "how-it-runs",
     "connections",
     "variables",
     "deployment",
diff --git a/apps/docs/content/docs/workflows/triggers/meta.json b/apps/docs/content/docs/workflows/triggers/meta.json
index b7a0faa0f2d..1ee9e31e4bd 100644
--- a/apps/docs/content/docs/workflows/triggers/meta.json
+++ b/apps/docs/content/docs/workflows/triggers/meta.json
@@ -1,4 +1,4 @@
 {
-  "title": "Core Triggers",
+  "title": "Core triggers",
   "pages": ["start", "schedule", "webhook", "rss", "table", "sim"]
 }
diff --git a/apps/docs/content/docs/workflows/triggers/rss.mdx b/apps/docs/content/docs/workflows/triggers/rss.mdx
index 77b28fb01de..c06d06cc447 100644
--- a/apps/docs/content/docs/workflows/triggers/rss.mdx
+++ b/apps/docs/content/docs/workflows/triggers/rss.mdx
@@ -1,49 +1,58 @@
 ---
-title: RSS Feed
-description: The RSS trigger runs a workflow when a new item is published to an RSS or Atom feed.
+title: RSS feed
+description: Start a workflow for unseen items in an RSS or Atom feed.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
 import { BlockPreview } from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
 
-The **RSS trigger** watches an RSS or Atom feed and runs a workflow when a new item is published. There's no account to connect — just a feed URL.
+The **RSS trigger** polls an RSS or Atom feed and starts a run for each selected unseen item. It needs a feed URL, with no connected account.
 
 <BlockPreview type="rss" />
 
 ## Configuration
 
-1. Add the RSS trigger as the workflow's entry point.
-2. Paste any RSS or Atom feed URL.
-3. Deploy the workflow to start polling.
+1. Add an RSS trigger and enter **Feed URL**.
+2. Connect the blocks that should process each item.
+3. Deploy the workflow to register the trigger.
+4. Confirm new item runs in [Logs](/logs-debugging).
 
-Once deployed, Sim checks the feed every minute and runs the workflow for each new item.
+Polling normally occurs once a minute. Self-hosted deployments need the RSS polling job configured; see [background jobs](/platform/self-hosting/background-jobs).
 
 ## Outputs
 
-| Output | What it is |
+These examples use a trigger named RSS. Use your block's normalized name if different.
+
+| Reference | Value |
 | --- | --- |
-| `<rss.title>` | The item title |
-| `<rss.link>` | The item link |
-| `<rss.pubDate>` | The publication date |
-| `<rss.item>` | The raw item, with every field (`guid`, `author`, `content`, and more) |
-| `<rss.feed>` | The feed metadata (title, link, description) |
-
-Read a mapped field directly, or reach into the raw objects for anything else — `<rss.item.author>`, `<rss.feed.language>`.
-
-## Use Cases
-
-- **Content monitoring** — blogs, news sites, or competitor updates
-- **Release tracking** — GitHub releases, changelogs, or product updates
-- **Podcast automation** — run a workflow when a new episode drops
-
-<Callout>
-RSS triggers only fire for items published after you save the trigger. Existing feed items are not processed.
-</Callout>
-
-<FAQ items={[
-  { question: "How does the poller avoid processing the same item twice?", answer: "It tracks up to 100 recent item GUIDs and the last checked timestamp. An item is new only if its GUID hasn't been seen and its publication date is after the last check. An idempotency layer also prevents duplicate runs for the same item." },
-  { question: "Is there a limit on how many new items are processed per poll?", answer: "Yes — at most 25 new items per poll, newest first. If a feed publishes more than 25 between polls, only the 25 most recent run." },
-  { question: "What output fields are available from the RSS trigger?", answer: "title, link, and pubDate as top-level convenience fields, plus a full item object (guid, summary, content, contentSnippet, author, categories, enclosure, isoDate), a feed object (title, link, description), and a processed timestamp." },
-  { question: "What happens if the RSS feed is temporarily unreachable?", answer: "A failed fetch increments the consecutive-failure counter. After 100 consecutive failures the trigger auto-disables; any successful poll resets the counter to zero." },
-]} />
+| `<rss.title>` | Item title |
+| `<rss.link>` | Item link |
+| `<rss.pubDate>` | Publication date |
+| `<rss.item>` | Parsed item with its available fields |
+| `<rss.feed>` | Feed `title`, `link`, and `description` |
+| `<rss.timestamp>` | Processing timestamp |
+
+Read fields such as `<rss.item.author>` or `<rss.feed.description>`. Item fields can include `guid`, `summary`, `content`, `contentSnippet`, `author`, `categories`, `enclosure`, and `isoDate`, depending on the feed. Feed metadata is a limited projection, not every field in the original feed.
+
+## Polling and deduplication
+
+Sim remembers up to 500 recent item identifiers. It uses the item's GUID, link, or title/publication-date combination when available, and an idempotency layer prevents repeated runs for the same identified item.
+
+Dated items at or before the subscription's creation time are excluded. Items without a usable date cannot be filtered by that historical boundary and may run even if they were already present in the feed. The last poll time is not the exclusion boundary, so a cached feed can reveal an unseen item later.
+
+Each poll selects at most 25 unseen items, newest first. Remaining unseen items stay eligible on later polls while they remain in the feed. Items left unattempted after an execution-admission refusal are also eligible later. This does not guarantee replay of an item that disappears from the feed before processing.
+
+## Fetch failures
+
+An unreachable feed or unsuccessful fetch counts as a failed poll and introduces backoff. The retry delay grows up to an hour, or longer when the source's `Retry-After` asks for it; skipped backoff polls do not count as failures.
+
+After 100 consecutive failed polls, the trigger disables itself. A successful poll resets the failure counter. Check the feed URL, reachability, and trigger status before reactivating it. Feed responses are bounded to 10 MiB.
+
+## Use a feed item [#use-cases]
+
+For release tracking, pass `<rss.title>` and `<rss.link>` to an Agent for a summary, then send that summary through an integration block. The trigger starts a separate run for each selected release item.
+
+## Related docs
+
+- [Deployment](/workflows/deployment)
+- [Connection syntax](/workflows/connections)
+- [Logs](/logs-debugging)
diff --git a/apps/docs/content/docs/workflows/triggers/schedule.mdx b/apps/docs/content/docs/workflows/triggers/schedule.mdx
index a5cbf538c27..604dd291dd0 100644
--- a/apps/docs/content/docs/workflows/triggers/schedule.mdx
+++ b/apps/docs/content/docs/workflows/triggers/schedule.mdx
@@ -1,65 +1,59 @@
 ---
 title: Schedule
-description: The Schedule trigger runs a workflow on a timer — a simple interval or a cron expression.
+description: Start workflow runs with a configured frequency or cron expression.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { Image } from '@/components/ui/image'
 import { BlockPreview } from '@/components/workflow-preview'
-import { FAQ } from '@/components/ui/faq'
 
-The **Schedule trigger** runs a workflow on a timer, on its own with no input — on a simple interval or a cron expression.
+The **Schedule trigger** starts runs on a configured timer. It is an entry point with no incoming connections or caller input.
 
 <BlockPreview type="schedule" />
 
 ## Schedule
 
-Pick how often it runs:
+Choose **Run frequency**, then fill in its fields:
 
-<Tabs items={['Simple intervals', 'Cron expressions']}>
-  <Tab>
-    - **Every X minutes** — a minute interval (1–1440)
-    - **Hourly** — a set minute each hour
-    - **Daily** — a set time each day
-    - **Weekly** — a set day and time each week
-    - **Monthly** — a set day and time each month
-  </Tab>
-  <Tab>
-    For finer control, use a cron expression:
+| Frequency | Configuration |
+| --- | --- |
+| **Every X Minutes** | **Interval (minutes)**; use a valid minute step such as `1`, `5`, `15`, or `30` |
+| **Hourly** | **Minute**, from `0` to `59` |
+| **Daily** | **Time** |
+| **Weekly** | **Day of week** and **Time** |
+| **Monthly** | **Day of month** and **Time** |
+| **Custom (Cron)** | **Cron expression** |
 
-    - `0 9 * * 1-5` — weekdays at 9 AM
-    - `*/15 * * * *` — every 15 minutes
-    - `0 0 1 * *` — the first of each month
+Minute frequency uses a cron minute-field step, not a continuously elapsed timer. The minute step must fit within an hour; do not use values above `60`. Prefer Hourly, Daily, or a custom expression for longer cadences.
 
-    Cron expressions and intervals are evaluated in the configured timezone, which defaults to UTC.
-  </Tab>
-</Tabs>
+For Daily, Weekly, Monthly, and Cron, confirm **Timezone**. New blocks preselect the browser's timezone; if no timezone is stored, execution falls back to UTC. Minute/hourly modes do not show a timezone selector.
+
+Common five-field cron expressions:
+
+| Expression | Schedule in the configured timezone |
+| --- | --- |
+| `0 9 * * 1-5` | Weekdays at 9 AM |
+| `*/15 * * * *` | Every quarter-hour |
+| `0 0 1 * *` | First day of each month at midnight |
 
 ## Activation
 
-A schedule is tied to [deployment](/workflows/deployment):
+1. Configure the Schedule trigger and connect its downstream blocks.
+2. Deploy the workflow.
+3. Check its next run information and confirm executions in [Logs](/logs-debugging).
 
-- **Deploy** — the schedule becomes active and starts running
-- **Undeploy** — the schedule is removed
-- **Redeploy** — the schedule is recreated from the current configuration
+Each Schedule block receives a separate schedule record with its own expression and failure counter. A workflow can have several Schedule triggers.
 
+Deployment starts the configured schedules. Updating deployment uses the new schedule configuration; undeploying removes the schedule registrations. A queued job checks the registration before starting, while an already-executing run is separate from new starts.
 
+Self-hosted deployments need an external scheduler calling the authenticated schedule endpoint. See [background jobs](/platform/self-hosting/background-jobs) for setup and verification.
 
 ## Automatic disabling
 
-A schedule disables itself after **100 consecutive failures**, to stop runaway errors. A warning badge appears on the block and it stops running; click the badge to reactivate it. The counter resets to zero on any successful run.
+A schedule disables after 100 consecutive failures. A successful run resets the counter. The block shows a disabled badge; fix the cause, then use the badge to reactivate it.
 
-<div className="flex justify-center">
-  <Image src="/static/blocks/schedule-3.png" alt="A disabled schedule" width={500} height={310} className="my-6" />
-</div>
+When execution admission is rate-limited with HTTP `429`, the schedule defers the attempt for five minutes without counting it as a workflow failure. Other failure classes, including repeated usage-limit refusals, can contribute to automatic disabling. Scheduled runs remain subject to the deployment's execution policy.
 
-<Callout>
-A Schedule trigger is an entry point only — it can't receive incoming connections.
-</Callout>
+## Related docs
 
-<FAQ items={[
-  { question: "What happens if my scheduled workflow is rate-limited?", answer: "If a run hits a rate limit (HTTP 429), the schedule retries after a 5-minute delay rather than counting it as a failure." },
-  { question: "Can I have multiple schedule blocks in one workflow?", answer: "Yes. Deployment creates a separate schedule record for each schedule block, and each runs independently with its own expression and failure counter." },
-  { question: "What happens if the workflow is undeployed while a scheduled run is in progress?", answer: "The running workflow completes, but no new runs are triggered. Before each fire, the schedule checks that the workflow is still deployed and the schedule record still exists." },
-]} />
+- [How workflows run](/workflows/how-it-runs)
+- [Deployment](/workflows/deployment)
+- [Self-hosted background jobs](/platform/self-hosting/background-jobs)
diff --git a/apps/docs/content/docs/workflows/triggers/sim.mdx b/apps/docs/content/docs/workflows/triggers/sim.mdx
index 47947f235a6..3ec58cee407 100644
--- a/apps/docs/content/docs/workflows/triggers/sim.mdx
+++ b/apps/docs/content/docs/workflows/triggers/sim.mdx
@@ -1,79 +1,99 @@
 ---
 title: Sim Workspace Events
+description: Start a deployed workflow from workspace run events, deployment changes, or alert conditions.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 
-The Sim Workspace Events trigger runs a workflow when events happen in your workspace: another workflow's run fails or succeeds, a workflow is deployed, or an alert condition like a latency spike or cost threshold is met. Use it to build side-effect workflows — alerting, escalation, auto-remediation — composed from any blocks (Slack, email, webhooks, custom logic).
+**Sim Workspace Events** starts a workflow when another workflow runs, changes deployment, or meets an alert condition. Use it to send an alert, escalate a failure, or run follow-up logic.
+
+## Configure the trigger
+
+1. Add Sim Workspace Events and choose **Event**. The default is **Run Error**.
+2. Optionally select **Workflows** to watch.
+3. For an alert condition, set its threshold and any time window.
+4. Connect the follow-up blocks and deploy the workflow.
+5. Produce the watched event and confirm the follow-up run in [Logs](/logs-debugging).
 
 ## Events
 
-Pick one event per Sim Workspace Events trigger block:
+Plain events fire for each matching occurrence:
+
+| Event | Trigger |
+| --- | --- |
+| **Run Error** | A watched workflow's run fails |
+| **Run Success** | A watched workflow's run succeeds |
+| **Workflow Deployed** | Deployment, update, or activation of another version |
+| **Workflow Undeployed** | The watched workflow is undeployed |
 
-**Plain events** — fire on every occurrence:
+Run-backed alert conditions are evaluated when runs complete. Failure-based conditions evaluate on failed runs:
 
-<ul className="list-disc space-y-1 pl-6">
-  <li><strong>Run Error</strong>: a watched workflow's run failed</li>
-  <li><strong>Run Success</strong>: a watched workflow's run completed successfully</li>
-  <li><strong>Workflow Deployed</strong>: a watched workflow was deployed (including redeploys and version rollbacks)</li>
-  <li><strong>Workflow Undeployed</strong>: a watched workflow was taken offline</li>
-</ul>
+| Condition | Rule | Default configuration |
+| --- | --- | --- |
+| **Consecutive Failures** | Last N runs failed | 3 failures |
+| **Failure Rate** | Failure percentage meets or exceeds the threshold; at least 5 runs required | 50% over 24 hours |
+| **Latency Threshold** | A run exceeds a duration | 30,000 ms |
+| **Latency Spike** | A run exceeds the recent average by a percentage; at least 5 runs required | 100% above average over 24 hours |
+| **Cost Threshold** | A run exceeds a credit amount | 200 credits |
+| **Error Count** | At least N errors occur in the window | 10 errors over 24 hours |
 
-**Alert conditions** — evaluated as runs complete (failure-based conditions evaluate on failed runs), with a cooldown so they fire at most once per cooldown window:
+**No Activity** is checked by a separate poller, not by completed runs. It watches deployed workflows for an absence of recorded non-Sim-trigger runs in the configured **Inactivity Window (hours)**, default 24 hours. A watched workflow with no runs can fire on the first eligible poll.
 
-<ul className="list-disc space-y-1 pl-6">
-  <li><strong>Consecutive Failures</strong>: the last N runs all failed</li>
-  <li><strong>Failure Rate</strong>: failure rate meets or exceeds a percentage over a time window (minimum 5 runs)</li>
-  <li><strong>Latency Threshold</strong>: a run took longer than a fixed duration</li>
-  <li><strong>Latency Spike</strong>: a run was a configurable percentage slower than the recent average (minimum 5 runs)</li>
-  <li><strong>Cost Threshold</strong>: a run cost more than a credit threshold</li>
-  <li><strong>Error Count</strong>: N or more errors occurred within a time window</li>
-  <li><strong>No Activity</strong>: a watched workflow had no runs for a configurable number of hours</li>
-</ul>
+For self-hosted deployments, configure the workspace-events polling job; see [background jobs](/platform/self-hosting/background-jobs).
 
-## Workflow Scope
+## Workflow scope
 
-By default the trigger watches every workflow in the workspace. Select specific workflows to narrow it. The workflow containing the trigger is always excluded — it never receives events about itself.
+Leave **Workflows** empty to watch the workspace, or select workflows to narrow it. The workflow containing this trigger is always excluded. No Activity watches only deployed, unarchived workflows.
 
 ## Outputs
 
-All events include `event`, `timestamp`, `workflowId`, and `workflowName` (the source workflow). Additional fields depend on the event type:
-
-<Tabs items={['Run Events', 'Alert Conditions', 'Workflow Deployed']}>
-  <Tab>
-    <ul className="list-disc space-y-1 pl-6">
-      <li><strong>runId</strong>: the run that completed</li>
-      <li><strong>durationMs</strong>: run duration in milliseconds</li>
-      <li><strong>cost</strong>: run cost in credits</li>
-      <li><strong>finalOutput</strong>: the run's final output (truncated when large)</li>
-    </ul>
-  </Tab>
-  <Tab>
-    <p>Run-backed conditions nest the run that tripped them under <code>triggeringRun</code>:</p>
-    <ul className="list-disc space-y-1 pl-6">
-      <li><strong>triggeringRun.runId</strong>, <strong>triggeringRun.durationMs</strong>, <strong>triggeringRun.cost</strong>, <strong>triggeringRun.finalOutput</strong></li>
-    </ul>
-    <p>No Activity has no triggering run, so it carries only the base fields.</p>
-  </Tab>
-  <Tab>
-    <ul className="list-disc space-y-1 pl-6">
-      <li><strong>version</strong>: the deployment version number that was activated</li>
-    </ul>
-    <p>Workflow Undeployed carries only the base fields.</p>
-  </Tab>
-</Tabs>
+All payloads identify the source workflow with `event`, `timestamp`, `workflowId`, and `workflowName`. The `event` is a wire value such as `execution_error`, rather than the display label Run Error.
+
+| Event class | Additional values |
+| --- | --- |
+| Run Error / Run Success | `runId`, `durationMs`, `cost` in credits, bounded `finalOutput` |
+| Run-backed alert | Run summary nested under `triggeringRun` |
+| Workflow Deployed | Activated deployment `version` |
+| Workflow Undeployed / No Activity | No additional event-specific values |
+
+Fields that do not apply are present as `null`. Large `finalOutput` values are truncated; the event payload is not a replacement for the full run log.
+
+For a trigger named Sim Events, read `<simevents.event>` or `<simevents.triggeringRun.runId>`. A run-backed alert payload has this shape:
+
+```json
+{
+  "event": "latency_threshold",
+  "timestamp": "2026-10-13T12:00:05.000Z",
+  "workflowId": "source-workflow-id",
+  "workflowName": "Customer support",
+  "runId": null,
+  "durationMs": null,
+  "cost": null,
+  "finalOutput": null,
+  "triggeringRun": {
+    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
+    "durationMs": 35000,
+    "cost": 4,
+    "finalOutput": { "answer": "..." }
+  },
+  "version": null
+}
+```
+
+For plain run events, those summary values are top-level and `triggeringRun` is null. Workflow Undeployed and No Activity leave all run/version fields null.
 
 ## Behavior
 
-<ul className="list-disc space-y-1 pl-6">
-  <li>The workflow containing the Sim Workspace Events trigger must be <strong>deployed</strong> for events to fire.</li>
-  <li>Runs started by a Sim Workspace Events trigger never emit workspace events, so side-effect workflows cannot chain or loop.</li>
-  <li>Alert conditions fire at most once per cooldown window (one hour, or the inactivity window for No Activity).</li>
-  <li>Event delivery is fire-and-forget: side-effect runs are billed like any other run and are subject to workspace rate limits.</li>
-</ul>
+- Trigger configuration is captured at deployment. Deploy an update after changing the event, watched workflows, or thresholds.
+- Run-backed alerts fire at most once per hour for a trigger subscription. No Activity has a per-watched-workflow cooldown of at least one hour or the inactivity window, whichever is longer.
+- Delivery is fire-and-forget. Follow-up runs are billed like other runs and remain subject to workspace rate limits; a dispatch failure does not fail the source run.
 
 <Callout type="info">
-  Trigger configuration is snapshotted at deploy time. After changing the event type, workflow
-  scope, or thresholds, redeploy the workflow for the changes to take effect.
+Runs started by Sim Workspace Events do not emit workspace events and are excluded from alert statistics. Follow-up workflows cannot chain workspace-event triggers into a recursive loop.
 </Callout>
+
+## Related docs
+
+- [Deployment](/workflows/deployment)
+- [Logs](/logs-debugging)
+- [Schedule](/workflows/triggers/schedule)
diff --git a/apps/docs/content/docs/workflows/triggers/start.mdx b/apps/docs/content/docs/workflows/triggers/start.mdx
index 8736fea28e7..0755798be9b 100644
--- a/apps/docs/content/docs/workflows/triggers/start.mdx
+++ b/apps/docs/content/docs/workflows/triggers/start.mdx
@@ -1,61 +1,81 @@
 ---
-title: Start Trigger
-description: The Start block is the default trigger — it collects typed inputs and runs the workflow from the editor, an API call, or chat.
+title: Start trigger
+description: Define typed inputs for editor, API, and deployed chat runs.
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
-import { Image } from '@/components/ui/image'
+import { Tab, Tabs } from '@/components/ui/tabs'
 
-The **Start block** is the default trigger for a workflow. It defines the inputs the workflow takes and runs it from three surfaces with the same shape: a manual run in the editor, an [API deployment](/workflows/deployment/api), and a [chat deployment](/workflows/deployment/chat).
+**Start** is the default entry point on a new workflow. It accepts editor input, API input, and deployed chat messages. Keep it when those callers should share the same downstream logic; add other triggers for events or schedules.
 
-<div className="flex justify-center">
-  <Image src="/static/start.png" alt="Start block with Input Format fields" width={500} height={209} className="my-6" />
-</div>
+## Input format
 
-<Callout type="info">
-Every workflow starts with a Start block in the trigger slot. Keep it when one entry point should serve editor, API, and chat runs. Swap in a [Webhook](/workflows/triggers/webhook) or [Schedule](/workflows/triggers/schedule) trigger when the workflow should only run on an event or a timer.
-</Callout>
+Open Start's **Inputs** and add fields. Each field has a name, type, description, and optional default value.
 
-## Input Format
-
-Define the fields the workflow accepts. Each field has a name and a type — `string`, `number`, `boolean`, `object`, `array`, or `files` — and becomes available downstream as `<start.fieldName>`. A `customerId` field reads as `<start.customerId>`.
-
-- Give a field a **default value** to prefill the manual-run form and supply a fallback when the caller omits it or sends `null`. A supplied value, including an empty string, overrides the default.
-- **File** fields accept uploads from both chat and API callers.
-- Reorder fields to control how they appear in the editor form.
-
-## Outputs
-
-The fields you define, plus conversation context when the workflow runs from chat:
-
-| Output | What it is |
+| Setting | Behavior |
 | --- | --- |
-| `<start.fieldName>` | Each Input Format field, by name |
-| `<start.input>` | The latest user message (chat only) |
-| `<start.conversationId>` | The active session id (chat only) |
-| `<start.files>` | Chat attachments (chat only) |
+| Name | Downstream reference, such as `<start.customerId>` |
+| Type | `string`, `number`, `boolean`, `object`, `array`, or a file field (`file[]` / `files`) |
+| Description | Explains the input; also supplies the default MCP parameter description |
+| Default value | Prefills editor runs and supplies a fallback when input is omitted or `null` |
+| Order | Controls the editor form's field order |
+
+A supplied value overrides the default, including an empty string. Sim coerces supported primitive values; an invalid declared number or boolean can fail the run at input validation. Add an early Condition when your workflow needs stricter validation, such as a nonempty customer ID.
 
 ## Per entry point
 
 <Tabs items={['Editor run', 'API', 'Chat']}>
   <Tab>
-    **Run** renders the Input Format as a form, prefilled with any default values, so you can retest without retyping. Submitting runs the workflow, and the values land on `<start.fieldName>`. File fields upload straight into `<start.fieldName>`.
+    Click **Run** to fill the form created from Inputs. Defaults prefill it; submitting sends those values to `<start.fieldName>`. File fields accept uploads into their named output.
   </Tab>
   <Tab>
-    The Input Format becomes the JSON request body. Each field is part of the body, and Sim coerces primitive types on the way in. File fields expect objects that reference uploaded files, so upload first, then invoke the workflow.
+    Put fields inside the API request's `input` value:
+
+    ```json
+    {
+      "input": {
+        "customerId": 4821,
+        "message": "Please check my order"
+      }
+    }
+    ```
+
+    These values are available as `<start.customerId>` and `<start.message>`. File fields use uploaded-file metadata: upload the file first, then invoke the workflow. See [API deployment](/workflows/deployment/api).
   </Tab>
   <Tab>
-    The Start block binds to the active conversation: the latest message fills `<start.input>`, the session id is `<start.conversationId>`, and attachments appear on `<start.files>`, alongside any Input Format fields. Extra structured context passed in at launch merges into the matching `<start.fieldName>` outputs.
+    Deployed chat supplies the latest message in `<start.input>`, the conversation ID in `<start.conversationId>`, and attachments in `<start.files>`. Custom fields use their declared defaults unless the execution surface supplies a matching value.
+
+    The public chat POST accepts `input`, `conversationId`, and `files`, plus its authentication fields; it is not a general structured-input launch API. Configure [Agent Memory](/workflows/blocks/agent#memory) if later messages should use prior conversation context.
   </Tab>
 </Tabs>
 
+## Outputs
+
+These examples use a block named Start:
+
+| Reference | Value |
+| --- | --- |
+| `<start.fieldName>` | A named input field |
+| `<start.input>` | Built-in input, including the latest message for Chat |
+| `<start.conversationId>` | Supplied conversation ID, commonly from Chat |
+| `<start.files>` | Supplied attachments normalized for the run |
+
+The built-in fields are not restricted to Chat; they are populated when the caller or configured input supplies them. Start also passes through supported additional runtime fields. Check the output panel rather than assuming a missing field is populated.
+
+### Run metadata
+
+In advanced mode, enable **Add run metadata** to expose trusted server-built identity and run context under `<start.metadata>`: `subject`, `workspaceId`, `workflowId`, `executionId`, `executionType`, `executionMode`, and `startTime`.
+
+The subject identifies the authenticated Sim user, chat email, or supported external identity without exposing credentials. When enabled, `metadata` is reserved; a caller cannot replace it with its own value. Execution-control field names are also reserved and rejected as Start outputs.
+
 ## Multiple triggers
 
-A workflow can have more than one trigger. When you click **Run** in the editor, Sim runs the highest-priority one: the **Start** trigger first, then a [Schedule](/workflows/triggers/schedule), then external triggers (webhooks and integrations). So a workflow with both a Start and a Webhook runs from Start when you click Run. Running an external trigger by hand instead generates a mock payload from its expected shape, so downstream blocks can resolve their references while you test.
+A workflow can have several trigger blocks. When the editor chooses among alternatives on the same path, Start takes priority, followed by Schedule and external triggers. Choose an external trigger explicitly when testing that entry point; its expected output shape can supply a mock payload.
+
+The v2 manual API requires `run.entry.blockId` when several triggers are runnable. If you request a mock payload, do not also supply `input`. Each execution begins at its selected trigger; deployment is required for automatic events, while editor runs test the draft.
 
-## Best Practices
+## Related docs
 
-- **Use Start as the single entry point** when one workflow serves both API and chat callers.
-- **Prefer named fields over raw JSON.** Typed Input Format fields are coerced automatically and read by name downstream.
-- **Validate early.** Add a [Condition](/workflows/blocks/condition) right after Start when certain fields are required for the run to succeed.
+- [API deployment](/workflows/deployment/api)
+- [Chat deployment](/workflows/deployment/chat)
+- [Webhook](/workflows/triggers/webhook)
+- [Schedule](/workflows/triggers/schedule)
diff --git a/apps/docs/content/docs/workflows/triggers/table.mdx b/apps/docs/content/docs/workflows/triggers/table.mdx
index 92612212dcd..440939e389f 100644
--- a/apps/docs/content/docs/workflows/triggers/table.mdx
+++ b/apps/docs/content/docs/workflows/triggers/table.mdx
@@ -1,31 +1,48 @@
 ---
 title: Table
-description: The Table trigger runs a workflow when a row is inserted or updated in a Sim table.
+description: Start a workflow when a row is inserted, updated, or deleted in a Sim table.
 ---
 
 import { BlockPreview } from '@/components/workflow-preview'
 
-The **Table trigger** runs a workflow when a row is inserted or updated in a [Sim table](/tables). Use it to react to data changes — enrich a row when it's added, or send a follow-up when a status column flips.
+The **Table trigger** reacts to committed row inserts, updates, or deletes in a [Sim table](/tables). For example, start enrichment when a row is added or send a notification when a watched status changes.
 
 <BlockPreview type="table_v2" />
 
 ## Configuration
 
-- **Table** — the table to watch.
-- **Event type** — what to fire on: a row insert, a row update, or either.
-- **Watch columns** — fire only when these columns change. Leave empty to fire on any update.
-- **Include headers** — return each row as a key-value object keyed by column name.
+1. Select **Table**, or enter **Table ID** in advanced mode. Choose a table in the workflow's workspace.
+2. Choose **Event**: **Row Inserted**, **Row Updated**, or **Row Deleted**. The default is Row Inserted.
+3. For updates, optionally select **Watch Columns**. Leave it empty to react to any update.
+4. Choose **Map Row Values to Headers**, on by default, then connect the downstream blocks.
+5. Deploy the workflow and make the corresponding row change. Verify the run in [Logs](/logs-debugging).
+
+One trigger watches one event type. Use separate trigger blocks to handle several event types.
 
 ## Outputs
 
-| Output | What it is |
+These examples use a trigger named Table:
+
+| Reference | Value |
 | --- | --- |
-| `<table.row>` | The row mapped to column names (when Include headers is on) |
-| `<table.rawRow>` | The raw row object |
-| `<table.previousRow>` | The row before the update (`null` for inserts) |
-| `<table.changedColumns>` | The columns that changed (empty for inserts) |
-| `<table.rowId>` | The row's unique id |
-| `<table.headers>` | The table's column names |
-| `<table.tableId>` | The table id |
-| `<table.tableName>` | The table name |
-| `<table.timestamp>` | The event time, in ISO format |
+| `<table.row>` | Name-keyed row with missing schema columns filled, when header mapping is on; otherwise `null` |
+| `<table.rawRow>` | Row values projected to column names, including select option names |
+| `<table.previousRow>` | Previous row for an update, deleted row data for a delete, or `null` for an insert |
+| `<table.changedColumns>` | Changed column names for an update; empty for inserts and deletes |
+| `<table.rowId>` | Row ID |
+| `<table.headers>` | Table column names |
+| `<table.tableId>` | Table ID |
+| `<table.tableName>` | Table name |
+| `<table.timestamp>` | Event time in ISO format |
+
+Watch Columns applies only to updates. If none of the watched columns changed, that update does not start a run.
+
+## Delivery behavior
+
+Table events fire directly after the row mutation rather than waiting for a poll. Workflow dispatch is fire-and-forget: a workflow failure does not undo the committed table change. Runs use the deployed trigger configuration, so deploy an update after changing its event or watched columns.
+
+## Related docs
+
+- [Tables](/tables)
+- [Deployment](/workflows/deployment)
+- [Connection syntax](/workflows/connections)
diff --git a/apps/docs/content/docs/workflows/triggers/webhook.mdx b/apps/docs/content/docs/workflows/triggers/webhook.mdx
index e318fc49d58..812a784191c 100644
--- a/apps/docs/content/docs/workflows/triggers/webhook.mdx
+++ b/apps/docs/content/docs/workflows/triggers/webhook.mdx
@@ -1,75 +1,104 @@
 ---
 title: Webhook
-description: The Webhook trigger runs a workflow on any inbound HTTP request to a URL Sim generates.
+description: Start a deployed workflow from an authenticated HTTP delivery to its generated URL.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
 import { BlockPreview } from '@/components/workflow-preview'
-import { Video } from '@/components/ui/video'
-import { FAQ } from '@/components/ui/faq'
 
-The **Webhook trigger** runs a workflow whenever an inbound HTTP request reaches a URL Sim generates for it. Use it to start a workflow from any external service or custom app that can send an HTTP request — when no dedicated [integration trigger](/workflows#triggers) exists.
+The **Webhook trigger** starts a run from an accepted request to its generated URL. Use it when an external service or application has no suitable [integration trigger](/integrations). This is inbound; the [Webhook block](/workflows/blocks/webhook) sends outbound requests.
 
 <BlockPreview type="webhook_trigger" />
 
 ## How it works
 
-1. Add the Webhook trigger as the workflow's entry point.
-2. Copy the unique webhook URL Sim generates.
-3. Point your external service at it with a `POST`.
-4. Every request to the URL runs the workflow, with the request payload available downstream.
+1. Add the Webhook trigger and connect the blocks that should receive its payload.
+2. Configure authentication and optional input fields.
+3. Deploy the workflow, then copy **Webhook URL**.
+4. Send a request and verify its run in [Logs](/logs-debugging).
+
+Normal deliveries require the deployed trigger. The URL does not execute an undeployed workflow; provider or explicitly enabled setup-verification responses are separate from execution.
 
 ## Configuration
 
-### Input Format
+### Input format
 
-Optionally define the JSON shape you expect. The fields are documented on the block and read downstream by name. Use a `file[]` field for uploads.
+Optionally define expected body fields in **Input Format** to document their shape. Use `file[]` for supported file inputs. Generic payload fields are passed through by name; the definition does not replace the need for downstream validation.
 
 ### Authentication
 
-Turn on **Require Authentication** and set a token. Callers send it as a Bearer token in the `Authorization` header, or you name a custom header (like `X-Secret-Key`) and the token is matched against that instead.
+**Require Authentication** defaults on for new triggers, with a generated **Authentication Token**. Leave **Secret Header Name (Optional)** blank to require:
 
-### Response
+```http
+Authorization: Bearer YOUR_WEBHOOK_TOKEN
+```
 
-By default the endpoint acknowledges receipt. Switch to a custom response to return your own status code and JSON body to the caller.
+If you set a custom secret header, send the token in that header instead. Only the configured authentication method is accepted; setting a custom header does not also permit Bearer authentication.
 
-## Outputs
+<Callout type="warn">
+Keep authentication enabled for workflows that access private data or perform actions. A plain browser link cannot supply the required token header. Validate payload fields before using them to select resources or perform side effects.
+</Callout>
 
-The request is parsed and made available to the rest of the workflow — the body's fields by name (a `userId` in the body reads as `<webhook.userId>`), plus the request headers and query parameters. Common fields like `event`, `id`, and `data` are pulled out of the payload when present.
+### HTTP methods and request headers
 
-## Behavior
+POST starts runs by default. Enable **Accept Other HTTP Methods** to accept GET, PUT, PATCH, and DELETE as deliveries too. Unsupported methods return `405`; provider-specific GET verification challenges are separate.
 
-- **Deduplication** — idempotency checks prevent duplicate runs from repeated identical requests.
-- **Rate limiting** — built-in protection against abuse.
-- **Deploy required** — the URL only fires once the workflow is deployed; otherwise it returns not-found.
-- **No auto-disable** — unlike polling triggers (RSS, Gmail, IMAP), a push webhook processes each request independently and doesn't disable itself after failed runs.
+**Expose Request Headers** defaults off. When enabled, it adds a filtered `headers` object. Authorization, cookies, known credential headers, the configured secret header, and matching token values are withheld.
 
-<Callout type="warn">
-Validate and sanitize incoming webhook data before you use it downstream.
-</Callout>
+### Deduplication
+
+Send a stable `Idempotency-Key` for each event, or set **Deduplication Field (Optional)** to a scalar payload path such as `event.id`. Reuse that value for retries of the same event. Duplicate delivery identifiers are skipped within the deduplication window, currently seven days.
+
+Without an identifier, repeated identical payloads can start separate runs. A field containing an object is not a scalar delivery identifier.
+
+### Acknowledgement [#response]
+
+**Acknowledgement → Default** returns a receipt after the run is queued. **Custom** lets you set **Response Status Code** and **Response Body**; a JSON body returns JSON, while other text returns plain text.
+
+This acknowledges delivery, not workflow completion. A downstream Response block does not change the acknowledgement. Use [workflow API execution](/workflows/deployment/api) when a caller needs the completed workflow result.
+
+Enable **Verify Test Events** only when the sender needs a setup-time validation response. It does not make an undeployed workflow runnable.
+
+## Outputs
+
+These examples use a trigger named Webhook:
+
+| Reference | Value |
+| --- | --- |
+| `<webhook.userId>` | `userId` from the body, when present |
+| `<webhook.data>` | The body's `data` field, when present |
+| `<webhook.query.id>` | URL query parameter, when supplied |
+| `<webhook.method>` | HTTP method, when accepting other methods is enabled |
+| `<webhook.headers.x-event-name>` | Filtered request header, when header exposure is enabled |
+
+Body fields take precedence when they already contain `query`, `method`, or `headers`. Metadata is merged only into object bodies. The generic trigger does not manufacture `event`, `id`, or `data` if the sender omitted them.
 
 ## Test it
 
-Send a request to the webhook URL with `curl` (or Postman) and watch the run appear in [Logs](/logs-debugging):
+This example uses the default Bearer authentication and a stable event identifier:
 
 ```bash
-curl -X POST "<your webhook URL>" \
-  -H "Content-Type: application/json" \
-  -d '{"event": "test", "userId": "123"}'
+curl -X POST 'YOUR_WEBHOOK_URL' \
+  -H 'Content-Type: application/json' \
+  -H "Authorization: Bearer $WEBHOOK_TOKEN" \
+  -H 'Idempotency-Key: webhook-test-4821' \
+  -d '{"event":"test","userId":"123"}'
 ```
 
-Open the run to confirm the payload landed the way downstream blocks expect — that `<webhook.userId>` resolves, and that authentication rejects a request without the token if you turned it on.
+Confirm `<webhook.userId>` in the run output. Send the request again with the same identifier to check deduplication, and omit the token to check authentication rejection. Use a new identifier for a new test event.
 
-## Service triggers
+## Behavior
 
-Many integrations can act as triggers too: toggle **Use as Trigger** on a service block (Slack, GitHub, Stripe, and more) to register a service-specific webhook with event filtering and structured data — no generic endpoint to wire up.
+Accepted deliveries are rate-limited and can be deduplicated or refused before execution. Receipt does not guarantee the downstream run succeeds; inspect its log.
+
+Push webhooks do not auto-disable after failed runs. Polling triggers such as RSS have separate failure counters and disabling behavior.
+
+## Service triggers
 
-<div className="mx-auto w-full overflow-hidden rounded-lg">
-  <Video src="slack-trigger.mp4" width={700} height={450} />
-</div>
+For a service-specific trigger, enable **Use as Trigger** on a supported integration block and follow that integration's setup. Provider registration, verification, event filtering, and authentication vary by service. See [integrations](/integrations) for the supported trigger configuration.
 
-See [Triggers](/workflows#triggers) for every service that supports this.
+## Related docs
 
-<FAQ items={[
-  { question: "What HTTP methods does the webhook endpoint accept?", answer: "POST triggers workflows. GET is used only for provider-specific verification challenges (such as Microsoft Graph or WhatsApp). Other methods return 405 Method Not Allowed." },
-]} />
+- [API deployment](/workflows/deployment/api)
+- [Outbound Webhook block](/workflows/blocks/webhook)
+- [Start](/workflows/triggers/start)
diff --git a/apps/docs/content/docs/workflows/variables.mdx b/apps/docs/content/docs/workflows/variables.mdx
index 98f997bbf68..df7d3a4124d 100644
--- a/apps/docs/content/docs/workflows/variables.mdx
+++ b/apps/docs/content/docs/workflows/variables.mdx
@@ -1,98 +1,85 @@
 ---
 title: Variables
-description: Define reusable workflow variables referenced with angle brackets and environment variables referenced with double curly braces.
+description: Reuse run-scoped workflow values and resolve saved secrets by name.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout'
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 
-A **variable** is a value you set yourself and reuse across a workflow. Sim has two kinds. **Workflow variables** hold data during a run, like a counter or a config object, and you reference them with `<variable.name>`. **Environment variables** hold secrets and configuration, like API keys, and you reference them with `{{KEY}}`.
+Workflow variables hold values during a run, such as a counter or configuration object. Environment variables resolve saved secrets and configuration, such as API keys.
 
-## One syntax, named sources
+## Workflow variables
 
-Everything in angle brackets is the same mechanism: `<name.path>` reads a value by name at run time. The first segment says where the value comes from. **`variable` is literal** — every workflow variable is read through it. A [connection tag](/workflows/connections) starts with the block's own name instead, and inside a container, `loop` and `parallel` are reserved for its context. `{{KEY}}` is the one different syntax, for environment variables.
+1. Open **⋯ → Variables** in the top-right of the workflow builder.
+2. Add a name, type, and initial value.
+3. Type `<` in a supported block input and select the variable, or enter `<variable.name>`.
 
-| Syntax | Reads | Example |
-|--------|-------|---------|
-| `<loop.index>`, `<parallel.index>` | The current [Loop](/workflows/blocks/loop) iteration or [Parallel](/workflows/blocks/parallel) instance, inside that container | `<loop.currentItem>` |
-| `<variable.name>` | A workflow variable | `<variable.counter>` |
-| `{{KEY}}` | An environment variable | `{{OPENAI_API_KEY}}` |
-| `<blockname.field>` | A block's output — a connection tag, not a variable | `<agent.content>` |
+For example, `<variable.config.timeout>` reads the `timeout` field of an object variable named `config`.
 
-The table is in resolution order: when an angle-bracket reference could match more than one source — say a block named `variable` — loop and parallel context win, then workflow variables, then block outputs. (`{{KEY}}` can't collide; it's a different syntax.) If nothing matches, the raw reference is left in place unsubstituted, which usually breaks the block that reads it — so give variables and blocks distinct names.
+### Types
 
-Type `<` in any block text field to open the picker and browse everything you can reference.
+| Type | Initial value example | Use |
+| --- | --- | --- |
+| **Plain** | `Hello` | Text |
+| **Number** | `42` | Calculations and comparisons |
+| **Boolean** | `true` | A true/false flag |
+| **Object** | `{ "timeout": 30 }` | Named fields |
+| **Array** | `[1, 2, 3]` | An ordered collection |
 
-## Workflow variables
+Name matching ignores case and whitespace. `My Counter` resolves as `<variable.mycounter>`. Avoid periods in variable names: everything after the variable segment is interpreted as a path into its value.
 
-Workflow variables are a global store any block can read or update during a run. Open the panel with **⋯ → Variables** in the top-right of the editor. Each variable has a **name**, a **type**, and a **value**.
+### Scope
 
-Reference one anywhere a field accepts input. For an object or array variable, use dot notation to reach a nested value, like `<variable.config.timeout>`. Name matching ignores case and spaces, so a variable named `My Counter` resolves from `<variable.mycounter>` — but a name can't contain a period: everything after the first dot is read as a path into the value, so `<variable.config.timeout>` always means the `timeout` field of `config`, never a variable named `config.timeout`. Consistent names like `camelCase` are the clearest.
+Each run starts with the saved initial values. The [Variables block](/workflows/blocks/variables) changes values for that run; it does not update the saved values used by later runs.
 
-### Types
+Workflow variables are shared across all branches, including Parallel instances. Item/index context and block outputs are branch-specific. Avoid writing the same variable concurrently; collect branch outputs and combine them after Parallel instead.
 
-<Tabs items={['Plain', 'Number', 'Boolean', 'Object', 'Array']}>
-  <Tab>
-    ```
-    "Hello, World!"
-    ```
-    Text, for messages, names, and other strings.
-  </Tab>
-  <Tab>
-    ```
-    42
-    ```
-    A numeric value for calculations or comparisons.
-  </Tab>
-  <Tab>
-    ```
-    true
-    ```
-    A `true`/`false` flag.
-  </Tab>
-  <Tab>
-    ```json
-    { "name": "John", "age": 30 }
-    ```
-    Structured data with named fields, reached with dot notation.
-  </Tab>
-  <Tab>
-    ```json
-    [1, 2, 3, "four", "five"]
-    ```
-    An ordered list of values.
-  </Tab>
-</Tabs>
+Variables assigns typed values and references. To increment a counter or perform another calculation, use Function first, then assign its result in Variables.
 
-### Scope
+## Reference sources [#one-syntax-named-sources]
 
-Use the [Variables block](/workflows/blocks/variables) to update a value mid-run. Parallel instances have separate variable scopes.
+| Syntax | Reads | Example |
+| --- | --- | --- |
+| `<variable.name>` | A workflow variable | `<variable.counter>` |
+| `<blockname.field>` | A block's output | `<agent.content>` |
+| `<loop.field>` | Current enclosing Loop context | `<loop.currentItem>` |
+| `<parallel.field>` | Current enclosing Parallel context | `<parallel.index>` |
+| `{{KEY}}` | A saved environment variable | `{{OPENAI_API_KEY}}` |
 
-Each run starts fresh from the values defined in the panel. A change made during a run is visible to later blocks in that same run, but it never alters the saved initial value for future runs.
+`variable`, `loop`, and `parallel` are reserved prefixes; a new block cannot use one as its normalized name. Loop and Parallel context resolve before workflow variables and block outputs. Environment variables use a separate syntax and cannot collide with angle-bracket references.
 
-## Environment variables
+An unknown reference can remain unsubstituted. A reference to a known block that did not run resolves empty; see [connection syntax](/workflows/connections) for the distinction.
 
-Environment variables let you keep sensitive values like API keys and tokens out of your saved workflow configuration. Create them under **Settings → Secrets** by adding a key-value pair.
+## Environment variables
 
-Reference them with double curly braces in any block field, including Agent system prompts and Function block code. Most fields resolve the reference before the block runs. Function and Custom Tool code preserve `{{KEY}}` until their shared compiler runs at the execution boundary, where the value is bound separately from the source. This keeps its exact string contents out of saved and executed source code. When a saved secret is successfully resolved through `{{KEY}}`, exact occurrences of that value are masked in the live block-log display and stored execution trace without changing the runtime value. Exact secret values are also projected back to placeholders before content is sent to a model. See [Execution log protection](/platform/credentials#execution-log-protection) for the exact scope and limitations.
+Create key-value pairs under **Settings → Secrets**, then type `{{` in a supported input to choose an available key:
 
-```
+```text
 {{API_KEY}}
 ```
 
-<Callout type="info">
-  Environment variable names must start with a letter or underscore and contain only letters, numbers, and underscores, like `MY_API_KEY`.
-</Callout>
+Names can contain only letters, numbers, and underscores. The Settings editor also requires the first character to be a letter or underscore.
 
-Inside Function and Custom Tool code, `{{KEY}}` always evaluates to a **string** — the value is bound, never parsed as source. Use `Number()`, a `=== 'true'` comparison, or `JSON.parse()` when you need another type. See [secret placeholders in code](/workflows/blocks/function#placeholders-are-always-strings).
+Most fields resolve secrets before their block runs. Function and Custom Tool code bind secret values separately at execution, preserving their exact string contents without inserting them into saved source code. Inside that code, `{{KEY}}` evaluates to a **string**: use `Number()`, compare with `'true'`, or use `JSON.parse()` when another type is needed. See [secret placeholders in code](/workflows/blocks/function#placeholders-are-always-strings).
 
 ### Personal vs. workspace
 
-| Scope | Visible to | Use for |
-|-------|-----------|---------|
-| **Workspace** | All workspace members, including external members | Shared API keys, team configuration |
-| **Personal** | Only you | Your personal tokens, dev credentials |
+| Scope | Ownership and access |
+| --- | --- |
+| **Workspace** | Workspace-owned; available according to secret grants and workspace Admin access |
+| **Personal** | Owned by a person; workspace Admin access alone does not grant access to another person's personal secret |
+
+Existing explicit personal-secret grants can be honored during workflow resolution. This does not mean the current personal-secret UI offers a sharing action. See [Secrets](/platform/credentials) for current ownership and access controls.
+
+When an accessible workspace key and personal key share a name, the workspace value wins. The acting principal and execution surface determine which values may resolve.
+
+<Callout type="warn">
+Protected secrets successfully resolved through `{{KEY}}` have exact-value masking in live block logs and stored traces, and exact values are projected back to placeholders before model input. Workspace secrets marked **Unredacted** opt out of that protection. This is not a general filter for sensitive data or transformed secret values; read [execution log protection](/platform/credentials#execution-log-protection) for its scope.
+</Callout>
+
+Use a secret for a raw API key or configuration value. Use a [connected account](/platform/connected-accounts) or supported credential for OAuth and managed token refresh.
 
-When a workspace and a personal variable share a key, the workspace value wins.
+## Related docs
 
-Use an environment variable for a raw API key or config value. When a service needs OAuth or managed token refresh (Slack, GitHub, Google), use a [credential](/platform/credentials) instead, selected from a dropdown in the block's config.
+- [Variables block](/workflows/blocks/variables)
+- [Secrets](/platform/credentials)
+- [Connection syntax](/workflows/connections)
diff --git a/apps/docs/lib/navigation.ts b/apps/docs/lib/navigation.ts
new file mode 100644
index 00000000000..7cc9509be5a
--- /dev/null
+++ b/apps/docs/lib/navigation.ts
@@ -0,0 +1,17 @@
+export const DOCS_SECTIONS = [
+  { slug: 'docs', label: 'Documentation', compactLabel: 'Docs', href: '/introduction' },
+  {
+    slug: 'api-reference',
+    label: 'API reference',
+    compactLabel: 'API reference',
+    href: '/api-reference/getting-started',
+  },
+  { slug: 'cli', label: 'CLI', compactLabel: 'CLI', href: '/cli' },
+  { slug: 'mcp', label: 'MCP', compactLabel: 'MCP', href: '/mcp/overview' },
+] as const
+
+/** Matches the first path segment so integration names cannot select a reference section. */
+export function getDocsSection(pathname: string) {
+  const segment = pathname.split('/')[1]
+  return DOCS_SECTIONS.find((section) => section.slug === segment)?.slug ?? 'docs'
+}
diff --git a/apps/docs/lib/source.ts b/apps/docs/lib/source.ts
index 8fb22c4197a..d09403c6bf8 100644
--- a/apps/docs/lib/source.ts
+++ b/apps/docs/lib/source.ts
@@ -24,6 +24,10 @@ function openapiPluginBadgeLeft() {
     name: 'fumadocs:openapi-badge-left',
     enforce: 'pre' as const,
     transformPageTree: {
+      folder(node: { name: React.ReactNode }) {
+        if (node.name === 'Mcp servers') node.name = 'MCP servers'
+        return node
+      },
       file(
         this: {
           storage: {
diff --git a/apps/docs/openapi-v2-billing.json b/apps/docs/openapi-v2-billing.json
index 7869df5c9bf..f4085cb198c 100644
--- a/apps/docs/openapi-v2-billing.json
+++ b/apps/docs/openapi-v2-billing.json
@@ -1,7 +1,7 @@
 {
   "openapi": "3.1.0",
   "info": {
-    "title": "Sim API v2 — Billing",
+    "title": "Sim API v2 — billing",
     "description": "Version 2 of the Sim REST API for billing standing, credit allowance, storage quota, and cursor-paginated usage history.",
     "version": "2.0.0",
     "contact": {
@@ -38,8 +38,8 @@
     "/api/v2/billing/status": {
       "get": {
         "operationId": "getBillingStatus",
-        "summary": "Get Billing Status",
-        "description": "Get the current plan, billing standing, credit allowance, and storage quota. Pooled `credits` and `storage` are visible only to callers who can manage the payer's billing; workspace API keys receive null for both. Use List Billing Logs for credit history.\n\nOAuth scope: `api:read`.",
+        "summary": "Get billing status",
+        "description": "Get the current plan, billing standing, credit allowance, and storage quota. Pooled `credits` and `storage` are visible only to callers who can manage the payer's billing; workspace API keys receive null for both. Use List billing logs for credit history.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "billing.status.read",
         "x-oauth-scope": "api:read",
         "tags": ["Billing"],
@@ -48,9 +48,9 @@
             "name": "workspaceId",
             "in": "query",
             "required": false,
-            "description": "Workspace whose payer should be resolved. A workspace API key is pinned to its own workspace: any other id answers `404 Workspace not found`, which is also what an id that does not exist answers.",
+            "description": "Workspace whose payer to report. A workspace API key is bound to its own workspace; a different or unknown ID returns `404 Workspace not found`. Omit for account billing when using a personal API key or OAuth token.",
             "schema": {
-              "description": "Workspace whose payer should be resolved. A workspace API key is pinned to its own workspace: any other id answers `404 Workspace not found`, which is also what an id that does not exist answers.",
+              "description": "Workspace whose payer to report. A workspace API key is bound to its own workspace; a different or unknown ID returns `404 Workspace not found`. Omit for account billing when using a personal API key or OAuth token.",
               "type": "string",
               "minLength": 1,
               "maxLength": 128
@@ -75,6 +75,32 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2BillingStatusResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "workspaceId": null,
+                        "period": {
+                          "start": "2026-07-01T00:00:00.000Z",
+                          "end": "2026-08-01T00:00:00.000Z"
+                        },
+                        "plan": "pro",
+                        "status": "active",
+                        "credits": {
+                          "used": 512,
+                          "limit": 20000,
+                          "remaining": 19488
+                        },
+                        "storage": {
+                          "usedBytes": 5242880,
+                          "limitBytes": 1073741824,
+                          "percentUsed": 0.48828125
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -106,7 +132,7 @@
     "/api/v2/billing/logs": {
       "get": {
         "operationId": "listBillingLogs",
-        "summary": "List Billing Logs",
+        "summary": "List billing logs",
         "description": "List credit usage with source filtering and cursor pagination. The default `period` is `30d`; pagination covers only the selected time window. An inverted custom window returns `400`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "billing.logs.list",
         "x-oauth-scope": "api:read",
@@ -162,24 +188,24 @@
             "name": "startDate",
             "in": "query",
             "required": false,
-            "description": "Only include usage events recorded at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. Requires `period=custom`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.",
+            "description": "Include events at or after this UTC ISO 8601 timestamp, for example `2026-08-06T00:00:00Z`. Required with `period=custom`. Date-only values, UTC offsets instead of `Z`, and year `0000` are rejected.",
             "schema": {
               "type": "string",
               "format": "date-time",
               "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
-              "description": "Only include usage events recorded at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. Requires `period=custom`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant."
+              "description": "Include events at or after this UTC ISO 8601 timestamp, for example `2026-08-06T00:00:00Z`. Required with `period=custom`. Date-only values, UTC offsets instead of `Z`, and year `0000` are rejected."
             }
           },
           {
             "name": "endDate",
             "in": "query",
             "required": false,
-            "description": "Only include usage events recorded at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. Requires `period=custom`, and defaults to now when omitted. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.",
+            "description": "Include events at or before this UTC ISO 8601 timestamp, for example `2026-08-06T00:00:00Z`. Allowed only with `period=custom`; omission defaults to now. Date-only values, UTC offsets instead of `Z`, and year `0000` are rejected.",
             "schema": {
               "type": "string",
               "format": "date-time",
               "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
-              "description": "Only include usage events recorded at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. Requires `period=custom`, and defaults to now when omitted. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant."
+              "description": "Include events at or before this UTC ISO 8601 timestamp, for example `2026-08-06T00:00:00Z`. Allowed only with `period=custom`; omission defaults to now. Date-only values, UTC offsets instead of `Z`, and year `0000` are rejected."
             }
           },
           {
@@ -225,6 +251,26 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2BillingLogListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "log_1",
+                          "createdAt": "2026-07-29T18:04:11.000Z",
+                          "source": "sim-chat",
+                          "workspaceId": "ws_1",
+                          "workflow": null,
+                          "runId": null,
+                          "creditCost": 12
+                        }
+                      ],
+                      "nextCursor": null,
+                      "scope": "workspace"
+                    }
+                  }
                 }
               }
             }
@@ -429,7 +475,7 @@
         }
       },
       "ServiceUnavailable": {
-        "description": "A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, because the run may already have started — reconcile against the returned run id instead of retrying.",
+        "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
         "headers": {
           "Retry-After": {
             "$ref": "#/components/headers/Retry-After"
@@ -573,7 +619,7 @@
             },
             "required": ["start", "end"],
             "additionalProperties": false,
-            "description": "Current billing period. Only a Stripe subscription defines a real period; without one — notably on the free plan — this is the open interval 1970-01-01 to 9999-12-31 and must not be read as a monthly window."
+            "description": "Current subscription billing period. Without a Stripe subscription, including on Free, the bounds are 1970-01-01 to 9999-12-31; they do not represent a monthly window."
           },
           "plan": {
             "type": "string",
@@ -591,7 +637,7 @@
                 "properties": {
                   "used": {
                     "type": "number",
-                    "description": "Credits consumed so far. The counter is reset by Stripe invoice webhooks, so on a paid plan it covers the current billing period; on the free plan nothing resets it and the value is lifetime consumption."
+                    "description": "Credits consumed during the current billing period on a paid plan, or over the account’s lifetime on Free."
                   },
                   "limit": {
                     "type": "number",
@@ -609,7 +655,7 @@
                 "type": "null"
               }
             ],
-            "description": "The payer's credit usage and allowance — periodic on a paid plan, lifetime on the free plan, where the counter never resets. Null when the caller cannot manage that payer's billing. Always null for a workspace API key."
+            "description": "The payer’s credit usage and allowance: per billing period on paid plans, lifetime on Free. Null when the caller cannot manage the payer’s billing, including every workspace API key."
           },
           "storage": {
             "anyOf": [
@@ -709,7 +755,7 @@
               "voice-output",
               "api-tool"
             ],
-            "description": "Product surface that consumed the credits."
+            "description": "Product surface that consumed credits. The legacy `mothership_block` value identifies the Agent block; `sim-chat` identifies Sim Chat."
           },
           "workspaceId": {
             "anyOf": [
@@ -792,7 +838,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           },
           "scope": {
             "type": "string",
diff --git a/apps/docs/openapi-v2-files-audit.json b/apps/docs/openapi-v2-files-audit.json
index 9e96b13c639..654c859650c 100644
--- a/apps/docs/openapi-v2-files-audit.json
+++ b/apps/docs/openapi-v2-files-audit.json
@@ -42,7 +42,7 @@
     "/api/v2/files": {
       "get": {
         "operationId": "listFiles",
-        "summary": "List Files",
+        "summary": "List files",
         "description": "List active workspace files with folder filtering, search, sorting, and cursor pagination. Use `scope=archived` to find files available for restoration. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.list",
         "x-oauth-scope": "api:read",
@@ -122,10 +122,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "uploadedAt",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "size", "uploadedAt", "updatedAt"]
             }
@@ -183,6 +183,29 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2FileListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "wf_V1StGXR8z5jdHi6BmyT91",
+                          "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/files/wf_V1StGXR8z5jdHi6BmyT91",
+                          "name": "data.csv",
+                          "size": 1024,
+                          "type": "text/csv",
+                          "key": "workspace/example/data.csv",
+                          "folderPath": "/Engineering",
+                          "uploadedByEmail": "jane@example.com",
+                          "uploadedAt": "2026-01-15T10:30:00Z",
+                          "updatedAt": "2026-01-15T10:30:00Z",
+                          "deletedAt": null
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -215,7 +238,7 @@
       },
       "post": {
         "operationId": "createFile",
-        "summary": "Create File",
+        "summary": "Create file",
         "description": "Create a workspace file from inline UTF-8 or base64 content. Use an upload session for streamed or larger files.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.create",
         "x-oauth-scope": "api:write",
@@ -227,6 +250,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateFileRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "notes.md",
+                    "content": "# Notes"
+                  }
+                }
               }
             }
           }
@@ -249,6 +282,26 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2CreatedFileResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "wf_V1StGXR8z5jdHi6BmyT91",
+                        "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/files/wf_V1StGXR8z5jdHi6BmyT91",
+                        "name": "data.csv",
+                        "size": 1024,
+                        "type": "text/csv",
+                        "key": "workspace/example/data.csv",
+                        "folderPath": "/Engineering",
+                        "uploadedByEmail": "jane@example.com",
+                        "uploadedAt": "2026-01-15T10:30:00Z",
+                        "updatedAt": "2026-01-15T10:30:00Z",
+                        "deletedAt": null
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -289,7 +342,7 @@
     "/api/v2/files/uploads": {
       "post": {
         "operationId": "createFileUpload",
-        "summary": "Create File Upload",
+        "summary": "Create file upload",
         "description": "Create a resumable upload session and receive either a signed PUT URL or multipart instructions.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.upload.create",
         "x-oauth-scope": "api:write",
@@ -301,6 +354,17 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateFileUploadRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "archive.zip",
+                    "contentType": "application/zip",
+                    "size": 1048576
+                  }
+                }
               }
             }
           }
@@ -360,7 +424,7 @@
     "/api/v2/files/uploads/{uploadId}": {
       "get": {
         "operationId": "getFileUpload",
-        "summary": "Get File Upload",
+        "summary": "Get file upload",
         "description": "Get an upload session's state to determine whether an interrupted transfer can resume. Requires the signed upload token and current workspace access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.upload.read",
         "x-oauth-scope": "api:read",
@@ -448,7 +512,7 @@
       },
       "delete": {
         "operationId": "abortFileUpload",
-        "summary": "Abort File Upload",
+        "summary": "Abort file upload",
         "description": "Abort an incomplete upload session and discard its uploaded data. Completed uploads cannot be aborted.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.upload.cancel",
         "x-oauth-scope": "api:write",
@@ -541,7 +605,7 @@
     "/api/v2/files/uploads/{uploadId}/parts": {
       "post": {
         "operationId": "createFileUploadPartUrls",
-        "summary": "Create File Upload Part URLs",
+        "summary": "Create file upload part URLs",
         "description": "Create signed URLs for a bounded set of multipart upload part numbers.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.upload.parts",
         "x-oauth-scope": "api:write",
@@ -589,6 +653,14 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateFileUploadPartUrlsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "partNumbers": [1, 2]
+                  }
+                }
               }
             }
           }
@@ -651,7 +723,7 @@
     "/api/v2/files/uploads/{uploadId}/complete": {
       "post": {
         "operationId": "completeFileUpload",
-        "summary": "Complete File Upload",
+        "summary": "Complete file upload",
         "description": "Finalize an upload and register its workspace file. Repeating a completed upload returns the existing file.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.upload.complete",
         "x-oauth-scope": "api:write",
@@ -744,8 +816,8 @@
     "/api/v2/files/{fileId}/text": {
       "get": {
         "operationId": "readFileText",
-        "summary": "Read File Text",
-        "description": "Extract text without changing the file. Accepts its ID or canonical path (`files/<folder>/<name>` or `uploads/<name>` for an unlisted chat upload); the response echoes the read path. Use Unzip File to unpack archives or Download File for original bytes. Unsupported types return `400`, compiling documents return `409`, and oversized files return `413`. `degraded: true` indicates incomplete or synthesized text, such as the legacy `.pptx` fallback; `truncated: true` indicates a parser limit.\n\nOAuth scope: `api:read`.",
+        "summary": "Read file text",
+        "description": "Extract text without changing the file. Accepts its ID or canonical path (`files/<folder>/<name>` or `uploads/<name>` for an unlisted chat upload); the response echoes the read path. Use Unzip file to unpack archives or Download file for original bytes. Unsupported types return `400`, compiling documents return `409`, and oversized files return `413`. `degraded: true` indicates incomplete or synthesized text, such as the legacy `.pptx` fallback; `truncated: true` indicates a parser limit.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.read_content",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -866,7 +938,7 @@
     "/api/v2/files/{fileId}/versions": {
       "get": {
         "operationId": "listFileVersions",
-        "summary": "List File Versions",
+        "summary": "List file versions",
         "description": "List the versions of a file, newest first by default. Each write that changes the bytes records one; identical rewrites do not. Collaborative edits, and repeated workflow writes by one author, fold into a version under ten minutes old and written in the last five. Renames and moves are not versions. Retention removes older versions by age and plan but keeps the newest ten, so numbers can have gaps.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.versions.list",
         "x-oauth-scope": "api:read",
@@ -964,6 +1036,34 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2FileVersionListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "fileId": "wf_V1StGXR8z5jdHi6BmyT91",
+                          "version": 3,
+                          "isCurrent": true,
+                          "size": 1024,
+                          "contentType": "text/csv",
+                          "source": "api",
+                          "authors": [
+                            {
+                              "id": "usr_4kJ9mN2pQ7rS",
+                              "email": "jane@example.com"
+                            }
+                          ],
+                          "restoredFromVersion": null,
+                          "createdAt": "2026-01-15T10:30:00Z",
+                          "updatedAt": "2026-01-15T10:30:00Z",
+                          "supersededAt": null
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -995,7 +1095,7 @@
     "/api/v2/files/{fileId}/versions/{version}": {
       "get": {
         "operationId": "getFileVersion",
-        "summary": "Get File Version",
+        "summary": "Get file version",
         "description": "Get one version of a file. A version removed by retention, or one that never existed, returns `404`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.versions.read",
         "x-oauth-scope": "api:read",
@@ -1057,6 +1157,31 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2FileVersionResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "fileId": "wf_V1StGXR8z5jdHi6BmyT91",
+                        "version": 3,
+                        "isCurrent": true,
+                        "size": 1024,
+                        "contentType": "text/csv",
+                        "source": "api",
+                        "authors": [
+                          {
+                            "id": "usr_4kJ9mN2pQ7rS",
+                            "email": "jane@example.com"
+                          }
+                        ],
+                        "restoredFromVersion": null,
+                        "createdAt": "2026-01-15T10:30:00Z",
+                        "updatedAt": "2026-01-15T10:30:00Z",
+                        "supersededAt": null
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1086,8 +1211,8 @@
       },
       "delete": {
         "operationId": "deleteFileVersion",
-        "summary": "Delete File Version",
-        "description": "Permanently delete one earlier version and its stored content, for example to purge a leaked value from history before retention removes it. The current version returns `409`; revert to another version first. A version that does not exist returns `404`.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete file version",
+        "description": "Permanently remove an earlier version from history and schedule deletion of its stored content. Storage cleanup may retry in the background. The current version returns `409`; revert to another version first. A version that does not exist returns `404`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.versions.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -1148,6 +1273,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2FileVersionDeleteResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "fileId": "wf_V1StGXR8z5jdHi6BmyT91",
+                        "version": 2,
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1182,8 +1319,8 @@
     "/api/v2/files/{fileId}/versions/{version}/text": {
       "get": {
         "operationId": "readFileVersionText",
-        "summary": "Read File Version Text",
-        "description": "Extract the text of one version, exactly as Read File Text extracts the current content. Unsupported types return `400`, compiling documents return `409`, and oversized versions return `413`.\n\nOAuth scope: `api:read`.",
+        "summary": "Read file version text",
+        "description": "Extract the text of one version, exactly as Read file text extracts the current content. Unsupported types return `400`, compiling documents return `409`, and oversized versions return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.versions.read_content",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -1317,8 +1454,8 @@
     "/api/v2/files/{fileId}/versions/{version}/content": {
       "get": {
         "operationId": "downloadFileVersion",
-        "summary": "Download File Version",
-        "description": "Download the bytes of one version, served exactly as Download File serves the current bytes. Generated documents use compiled artifacts, returning `409` while compiling and `413` above the rendered-size ceiling. Downloading records an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` omits `Content-Length`; use file metadata to size downloads.\n\nOAuth scope: `api:read`.",
+        "summary": "Download file version",
+        "description": "Download the bytes of one version, served exactly as Download file serves the current bytes. Generated documents use compiled artifacts, returning `409` while compiling and `413` above the rendered-size ceiling. Downloading records an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` omits `Content-Length` and cannot determine the download size.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.versions.download",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -1426,8 +1563,8 @@
     "/api/v2/files/{fileId}/versions/{version}/revert": {
       "post": {
         "operationId": "revertFileVersion",
-        "summary": "Revert File Version",
-        "description": "Make the content of a version current again by writing it as a new `revert` version, so the revert can itself be reverted. Open editors receive the change. Reverting to the current version writes nothing and returns `reverted: false`. A concurrent write, or an `expectedCurrentVersion` that is no longer current, returns `409`; a version above 100 MB returns `413`.\n\nOAuth scope: `api:write`.",
+        "summary": "Revert file version",
+        "description": "Make the content of a version current again by writing it as a new `revert` version, so the revert can itself be reverted. Open editors receive the change. Reverting to the current version writes nothing and returns `reverted: false`. A concurrent write, or an `expectedCurrentVersion` that is no longer current, returns `409`; a version above 100 MiB returns `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.versions.revert",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -1465,6 +1602,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RevertFileVersionRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "expectedCurrentVersion": 4
+                  }
+                }
               }
             }
           }
@@ -1487,6 +1633,48 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2FileVersionRevertResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "reverted": true,
+                        "file": {
+                          "id": "wf_V1StGXR8z5jdHi6BmyT91",
+                          "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/files/wf_V1StGXR8z5jdHi6BmyT91",
+                          "name": "data.csv",
+                          "size": 1024,
+                          "type": "text/csv",
+                          "key": "workspace/example/data.csv",
+                          "folderPath": "/Engineering",
+                          "uploadedByEmail": "jane@example.com",
+                          "uploadedAt": "2026-01-15T10:30:00Z",
+                          "updatedAt": "2026-01-15T10:30:00Z",
+                          "deletedAt": null
+                        },
+                        "version": {
+                          "fileId": "wf_V1StGXR8z5jdHi6BmyT91",
+                          "version": 5,
+                          "isCurrent": true,
+                          "size": 1024,
+                          "contentType": "text/csv",
+                          "source": "revert",
+                          "authors": [
+                            {
+                              "id": "usr_4kJ9mN2pQ7rS",
+                              "email": "jane@example.com"
+                            }
+                          ],
+                          "restoredFromVersion": 3,
+                          "createdAt": "2026-01-15T10:30:00Z",
+                          "updatedAt": "2026-01-15T10:30:00Z",
+                          "supersededAt": null
+                        },
+                        "revision": "d2ZfVjFTdEdYUjh6NWpkSGk2Qm15VDkxOjIwMjYtMDEtMTVUMTA6MzA6MDAuMDAwWg"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1527,8 +1715,8 @@
     "/api/v2/files/bulk-download": {
       "get": {
         "operationId": "bulkDownloadFiles",
-        "summary": "Bulk Download Files",
-        "description": "Stream selected files and recursive folder contents as a ZIP archive. Each selection parameter and the resolved set allow 100 entries; unmatched paths or excess entries return `400`. Total bytes are bounded. Downloads record an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` omits `Content-Length`; use file metadata to size downloads.\n\nOAuth scope: `api:read`.",
+        "summary": "Bulk download files",
+        "description": "Stream selected files and recursive folder contents as a ZIP archive. Each selection parameter and the resolved set allow 100 entries; unmatched paths or excess entries return `400`. Total bytes are bounded. Downloads record an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` omits `Content-Length` and cannot determine the download size.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.download",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -1625,8 +1813,8 @@
     "/api/v2/files/{fileId}/unzip": {
       "post": {
         "operationId": "unzipFile",
-        "summary": "Unzip File",
-        "description": "Extract a ZIP archive into a new sibling folder and return counts and the destination path. Use List Files to inspect its contents. Large archives can take minutes; concurrent extraction of the same archive returns `409`. Size or processing-time limits return `413`.\n\nOAuth scope: `api:write`.",
+        "summary": "Unzip file",
+        "description": "Extract a ZIP archive into a new sibling folder and return counts and the destination path. Use List files to inspect its contents. Large archives can take minutes; concurrent extraction of the same archive returns `409`. Size or processing-time limits return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.extract_archive",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -1714,8 +1902,8 @@
     "/api/v2/files/{fileId}": {
       "get": {
         "operationId": "downloadFile",
-        "summary": "Download File",
-        "description": "Download current file bytes. Generated documents use compiled artifacts, returning `409` while compiling and `413` above the rendered-size ceiling. Downloading records an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` omits `Content-Length`; use file metadata to size downloads.\n\nOAuth scope: `api:read`.",
+        "summary": "Download file",
+        "description": "Download current file bytes. Generated documents use compiled artifacts, returning `409` while compiling and `413` above the rendered-size ceiling. Downloading records an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` omits `Content-Length` and cannot determine the download size.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.download",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -1809,8 +1997,8 @@
       },
       "delete": {
         "operationId": "deleteFile",
-        "summary": "Delete File",
-        "description": "Archive a workspace file, retaining its stored bytes and removing API read access. List Files with `scope=archived` finds it; Restore File recovers it. Archiving an already archived file returns `404`.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete file",
+        "description": "Archive a workspace file, retaining its stored bytes and removing API read access. List files with `scope=archived` finds it; Restore file recovers it. Archiving an already archived file returns `404`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -1888,7 +2076,7 @@
       },
       "patch": {
         "operationId": "renameFile",
-        "summary": "Rename File",
+        "summary": "Rename file",
         "description": "Rename a workspace file without changing its containing folder.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.rename",
         "x-oauth-scope": "api:write",
@@ -1915,6 +2103,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RenameFileRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "renamed.csv"
+                  }
+                }
               }
             }
           }
@@ -1937,6 +2134,26 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2FileResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "wf_V1StGXR8z5jdHi6BmyT91",
+                        "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/files/wf_V1StGXR8z5jdHi6BmyT91",
+                        "name": "data.csv",
+                        "size": 1024,
+                        "type": "text/csv",
+                        "key": "workspace/example/data.csv",
+                        "folderPath": "/Engineering",
+                        "uploadedByEmail": "jane@example.com",
+                        "uploadedAt": "2026-01-15T10:30:00Z",
+                        "updatedAt": "2026-01-15T10:30:00Z",
+                        "deletedAt": null
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1977,7 +2194,7 @@
     "/api/v2/files/{fileId}/restore": {
       "post": {
         "operationId": "restoreFile",
-        "summary": "Restore File",
+        "summary": "Restore file",
         "description": "Restore a soft-deleted file to its original folder, or the workspace root if that folder was archived. Name collisions add a `_restored` suffix; read `folderPath` and `name` from the response. Already-active files return unchanged, making retries safe. An archived workspace returns `400`; an unresolved name collision returns `409`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.restore",
         "x-oauth-scope": "api:write",
@@ -2004,6 +2221,14 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RestoreFileRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64"
+                  }
+                }
               }
             }
           }
@@ -2026,6 +2251,26 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2RestoreFileResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "wf_V1StGXR8z5jdHi6BmyT91",
+                        "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/files/wf_V1StGXR8z5jdHi6BmyT91",
+                        "name": "data_restored.csv",
+                        "size": 1024,
+                        "type": "text/csv",
+                        "key": "workspace/example/data.csv",
+                        "folderPath": "/",
+                        "uploadedByEmail": "jane@example.com",
+                        "uploadedAt": "2026-01-15T10:30:00Z",
+                        "updatedAt": "2026-01-15T10:30:00Z",
+                        "deletedAt": null
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2066,8 +2311,8 @@
     "/api/v2/files/{fileId}/metadata": {
       "get": {
         "operationId": "getFile",
-        "summary": "Get File Metadata",
-        "description": "Get file metadata, its public-share configuration, and the version number of its current content. The `share` field is null when the file has never been shared. `currentVersion` identifies the content in List File Versions and is the precondition Revert File Version accepts.\n\nOAuth scope: `api:read`.",
+        "summary": "Get file metadata",
+        "description": "Get file metadata, its public-share configuration, and the version number of its current content. The `share` field is null when the file has never been shared. `currentVersion` identifies the content in List file versions and is the precondition Revert file version accepts.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.read_metadata",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -2128,6 +2373,60 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2FileMetadataResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "wf_V1StGXR8z5jdHi6BmyT91",
+                        "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/files/wf_V1StGXR8z5jdHi6BmyT91",
+                        "name": "data.csv",
+                        "size": 1024,
+                        "type": "text/csv",
+                        "key": "workspace/example/data.csv",
+                        "folderPath": "/Engineering",
+                        "uploadedByEmail": "jane@example.com",
+                        "uploadedAt": "2026-01-15T10:30:00Z",
+                        "updatedAt": "2026-01-15T10:30:00Z",
+                        "deletedAt": null,
+                        "share": null,
+                        "currentVersion": 1,
+                        "revision": "d2ZfVjFTdEdYUjh6NWpkSGk2Qm15VDkxOjIwMjYtMDEtMTVUMTA6MzA6MDAuMDAwWg"
+                      }
+                    }
+                  },
+                  "example2": {
+                    "summary": "Response example 2",
+                    "value": {
+                      "data": {
+                        "id": "wf_V1StGXR8z5jdHi6BmyT91",
+                        "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/files/wf_V1StGXR8z5jdHi6BmyT91",
+                        "name": "data.csv",
+                        "size": 1024,
+                        "type": "text/csv",
+                        "key": "workspace/example/data.csv",
+                        "folderPath": "/Engineering",
+                        "uploadedByEmail": "jane@example.com",
+                        "uploadedAt": "2026-01-15T10:30:00Z",
+                        "updatedAt": "2026-01-16T09:12:00Z",
+                        "deletedAt": null,
+                        "share": {
+                          "id": "shr_8Hf3kL9wQ2mNpXr6Tz1Vb",
+                          "token": "share-token-example",
+                          "url": "https://www.sim.ai/f/share-token-example",
+                          "isActive": true,
+                          "resourceType": "file",
+                          "resourceId": "wf_V1StGXR8z5jdHi6BmyT91",
+                          "authType": "public",
+                          "hasPassword": false,
+                          "allowedEmails": []
+                        },
+                        "currentVersion": 3,
+                        "revision": "d2ZfVjFTdEdYUjh6NWpkSGk2Qm15VDkxOjIwMjYtMDEtMTZUMDk6MTI6MDAuMDAwWg"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2159,7 +2458,7 @@
     "/api/v2/audit-logs": {
       "get": {
         "operationId": "listAuditLogs",
-        "summary": "List Audit Logs",
+        "summary": "List audit logs",
         "description": "List an organization audit trail with filters and opaque cursor pagination. Requires an Enterprise subscription and organization admin or owner access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "audit_logs.list",
         "x-oauth-scope": "api:read",
@@ -2211,24 +2510,24 @@
             "name": "startDate",
             "in": "query",
             "required": false,
-            "description": "Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.",
+            "description": "Include audit entries created at or after this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected.",
             "schema": {
+              "description": "Include audit entries created at or after this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected.",
               "type": "string",
               "format": "date-time",
-              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
-              "description": "Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant."
+              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
             }
           },
           {
             "name": "endDate",
             "in": "query",
             "required": false,
-            "description": "Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.",
+            "description": "Include audit entries created at or before this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected.",
             "schema": {
+              "description": "Include audit entries created at or before this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected.",
               "type": "string",
               "format": "date-time",
-              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
-              "description": "Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant."
+              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
             }
           },
           {
@@ -2307,6 +2606,32 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2AuditLogListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "audit_2c3d4e5f6g",
+                          "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                          "actorName": "Jane Smith",
+                          "actorEmail": "jane@example.com",
+                          "action": "file.uploaded",
+                          "resourceType": "file",
+                          "resourceId": "wf_V1StGXR8z5jdHi6BmyT91",
+                          "resourceName": "data.csv",
+                          "description": "Uploaded file \"data.csv\" via API",
+                          "metadata": {
+                            "fileSize": 1024,
+                            "fileType": "text/csv"
+                          },
+                          "createdAt": "2026-01-15T10:30:00Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -2335,7 +2660,7 @@
     "/api/v2/audit-logs/{auditLogId}": {
       "get": {
         "operationId": "getAuditLog",
-        "summary": "Get Audit Log",
+        "summary": "Get audit log",
         "description": "Get one organization audit-log entry. Requires an Enterprise subscription and organization admin or owner access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "audit_logs.read_detail",
         "x-oauth-scope": "api:read",
@@ -2382,6 +2707,29 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2AuditLogResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "audit_2c3d4e5f6g",
+                        "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                        "actorName": "Jane Smith",
+                        "actorEmail": "jane@example.com",
+                        "action": "file.uploaded",
+                        "resourceType": "file",
+                        "resourceId": "wf_V1StGXR8z5jdHi6BmyT91",
+                        "resourceName": "data.csv",
+                        "description": "Uploaded file \"data.csv\" via API",
+                        "metadata": {
+                          "fileSize": 1024,
+                          "fileType": "text/csv"
+                        },
+                        "createdAt": "2026-01-15T10:30:00Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2413,7 +2761,7 @@
     "/api/v2/files/move": {
       "post": {
         "operationId": "moveFileItems",
-        "summary": "Move Files",
+        "summary": "Move files",
         "description": "Move up to 1,000 files to a folder path or the workspace root.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.move",
         "x-oauth-scope": "api:write",
@@ -2425,6 +2773,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/MoveFileItemsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "fileIds": ["wf_V1StGXR8z5jdHi6BmyT91"],
+                    "targetFolderPath": "/Archive"
+                  }
+                }
               }
             }
           }
@@ -2447,6 +2805,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2MoveFileItemsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "movedItems": {
+                          "files": 1
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2487,7 +2857,7 @@
     "/api/v2/files/{fileId}/share": {
       "get": {
         "operationId": "getFileShare",
-        "summary": "Get File Share",
+        "summary": "Get file share",
         "description": "Get a file's public-share configuration. An unshared file returns `data: null`; a disabled share returns its configuration with `isActive: false`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.share.read",
         "x-oauth-scope": "api:read",
@@ -2537,6 +2907,30 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2GetFileShareResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "shr_8Hf3kL9wQ2mNpXr6Tz1Vb",
+                        "token": "share-token-example",
+                        "url": "https://www.sim.ai/f/share-token-example",
+                        "isActive": true,
+                        "resourceType": "file",
+                        "resourceId": "wf_V1StGXR8z5jdHi6BmyT91",
+                        "authType": "public",
+                        "hasPassword": false,
+                        "allowedEmails": []
+                      }
+                    }
+                  },
+                  "example2": {
+                    "summary": "Response example 2",
+                    "value": {
+                      "data": null
+                    }
+                  }
                 }
               }
             }
@@ -2566,7 +2960,7 @@
       },
       "patch": {
         "operationId": "upsertFileShare",
-        "summary": "Enable or Disable File Share",
+        "summary": "Enable or disable file share",
         "description": "Create or update a file's public share. `isActive` is required; other fields describe their behavior when access modes change. Enabling a protected mode on a previously unshared file requires its credential in the same request. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.share.update",
         "x-oauth-scope": "api:write",
@@ -2593,6 +2987,23 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpsertFileShareRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "isActive": true,
+                    "authType": "public"
+                  }
+                },
+                "example2": {
+                  "summary": "Request example 2",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "isActive": false
+                  }
+                }
               }
             }
           }
@@ -2615,6 +3026,24 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2UpsertFileShareResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "shr_8Hf3kL9wQ2mNpXr6Tz1Vb",
+                        "token": "share-token-example",
+                        "url": "https://www.sim.ai/f/share-token-example",
+                        "isActive": true,
+                        "resourceType": "file",
+                        "resourceId": "wf_V1StGXR8z5jdHi6BmyT91",
+                        "authType": "public",
+                        "hasPassword": false,
+                        "allowedEmails": []
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2652,8 +3081,8 @@
     "/api/v2/files/{fileId}/content": {
       "patch": {
         "operationId": "editFileContent",
-        "summary": "Edit File Content",
-        "description": "Edit part of a UTF-8 file; use Replace File Content to replace it entirely. Search-and-replace requires one exact match unless `replaceAll` is true. Anchored modes match trimmed complete lines; their input descriptions specify boundary handling. Non-UTF-8 files return `400`. Concurrent writes return `409`; re-read before retrying.\n\nOAuth scope: `api:write`.",
+        "summary": "Edit file content",
+        "description": "Edit part of a UTF-8 file; use Replace file content to replace it entirely. Search-and-replace requires one exact match unless `replaceAll` is true. Anchored modes match trimmed complete lines; their input descriptions specify boundary handling. Non-UTF-8 files return `400`. Concurrent writes return `409`; re-read before retrying.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.update_content",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -2679,6 +3108,30 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/EditFileContentRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "edit": {
+                      "mode": "search_replace",
+                      "search": "- based in NYC",
+                      "content": "- based in SF"
+                    }
+                  }
+                },
+                "example2": {
+                  "summary": "Request example 2",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "edit": {
+                      "mode": "insert_after",
+                      "anchor": "## Preferences",
+                      "content": "- prefers async updates"
+                    }
+                  }
+                }
               }
             }
           }
@@ -2701,6 +3154,29 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2EditedFileResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "file": {
+                          "id": "wf_V1StGXR8z5jdHi6BmyT91",
+                          "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/files/wf_V1StGXR8z5jdHi6BmyT91",
+                          "name": "data.csv",
+                          "size": 1024,
+                          "type": "text/csv",
+                          "key": "workspace/example/data.csv",
+                          "folderPath": "/Engineering",
+                          "uploadedByEmail": "jane@example.com",
+                          "uploadedAt": "2026-01-15T10:30:00Z",
+                          "updatedAt": "2026-01-15T10:30:00Z",
+                          "deletedAt": null
+                        },
+                        "lineCount": 5
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2742,7 +3218,7 @@
       },
       "put": {
         "operationId": "updateFileContent",
-        "summary": "Replace File Content",
+        "summary": "Replace file content",
         "description": "Replace the complete contents of an existing file from UTF-8 or base64 input. A stale `expectedRevision`, or a write that raced this one, returns `409`; re-read before retrying.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.update_content",
         "x-oauth-scope": "api:write",
@@ -2769,6 +3245,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateFileContentRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "content": "replacement text"
+                  }
+                }
               }
             }
           }
@@ -2791,6 +3276,27 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2WrittenFileResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "wf_V1StGXR8z5jdHi6BmyT91",
+                        "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/files/wf_V1StGXR8z5jdHi6BmyT91",
+                        "name": "data.csv",
+                        "size": 1024,
+                        "type": "text/csv",
+                        "key": "workspace/example/data.csv",
+                        "folderPath": "/Engineering",
+                        "uploadedByEmail": "jane@example.com",
+                        "uploadedAt": "2026-01-15T10:30:00Z",
+                        "updatedAt": "2026-01-15T10:30:00Z",
+                        "deletedAt": null,
+                        "revision": "d2ZfVjFTdEdYUjh6NWpkSGk2Qm15VDkxOjIwMjYtMDEtMTVUMTA6MzA6MDAuMDAwWg"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2831,7 +3337,7 @@
     "/api/v2/files/search": {
       "get": {
         "operationId": "searchFileContent",
-        "summary": "Search File Content",
+        "summary": "Search file content",
         "description": "Search indexed text in active workspace files and return matching lines with file IDs and line numbers. `folderPaths` limits both results and reported coverage. Missing matches are inconclusive if `complete` is false or `indexStatus.skippedFiles` or `indexStatus.partialFiles` is nonzero. `truncated` means additional matches exist beyond `maxResults`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.search_content",
         "x-oauth-scope": "api:read",
@@ -2939,6 +3445,32 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2FileSearchResultsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "results": [
+                          {
+                            "fileId": "wf_V1StGXR8z5jdHi6BmyT91",
+                            "lineNumber": 4,
+                            "text": "- based in NYC"
+                          }
+                        ],
+                        "count": 1,
+                        "truncated": false,
+                        "complete": true,
+                        "indexStatus": {
+                          "readyFiles": 12,
+                          "pendingFiles": 0,
+                          "failedFiles": 0,
+                          "skippedFiles": 0,
+                          "partialFiles": 0
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2973,8 +3505,8 @@
     "/api/v2/files/bulk-delete": {
       "post": {
         "operationId": "bulkDeleteFiles",
-        "summary": "Delete Files",
-        "description": "Archive up to 1,000 workspace files while retaining their stored bytes. Use Restore File to recover each file.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete files",
+        "description": "Archive up to 1,000 workspace files while retaining their stored bytes. Use Restore file to recover each file.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -2985,6 +3517,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/BulkDeleteFilesRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "fileIds": ["wf_V1StGXR8z5jdHi6BmyT91"]
+                  }
+                }
               }
             }
           }
@@ -3007,6 +3548,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/BulkDeleteFilesResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "deletedItems": {
+                          "files": 1
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3044,8 +3597,8 @@
     "/api/v2/files/folders": {
       "get": {
         "operationId": "listFilesFolders",
-        "summary": "List Folders",
-        "description": "List workspace file folders with parent-path filtering and sorting. Use `scope=archived` to find paths accepted by Restore Folder. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
+        "summary": "List folders",
+        "description": "List workspace file folders with parent-path filtering and sorting. Use `scope=archived` to find paths accepted by Restore folder. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "files.folders.list",
         "x-oauth-scope": "api:read",
         "tags": ["Files"],
@@ -3088,10 +3641,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "name",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -3204,7 +3757,7 @@
       },
       "post": {
         "operationId": "createFilesFolder",
-        "summary": "Create Folder",
+        "summary": "Create folder",
         "description": "Create a folder at the supplied workspace path.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.folders.create",
         "x-oauth-scope": "api:write",
@@ -3216,6 +3769,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateFileFolderRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "path": "/Engineering"
+                  }
+                }
               }
             }
           }
@@ -3276,7 +3838,7 @@
       },
       "patch": {
         "operationId": "relocateFilesFolder",
-        "summary": "Rename or Move Folder",
+        "summary": "Rename or move folder",
         "description": "Rename or move a folder and atomically update all descendant paths.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.folders.update",
         "x-oauth-scope": "api:write",
@@ -3288,6 +3850,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RelocateFileFolderRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "path": "/Engineering",
+                    "destinationPath": "/Archive/Engineering"
+                  }
+                }
               }
             }
           }
@@ -3348,8 +3920,8 @@
       },
       "delete": {
         "operationId": "deleteFilesFolder",
-        "summary": "Delete Folder",
-        "description": "Archive an empty folder, or set `recursive=true` to archive its files and subfolders. Use Restore Folder to recover the archived contents.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete folder",
+        "description": "Archive an empty folder, or set `recursive=true` to archive its files and subfolders. Use Restore folder to recover the archived contents.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.folders.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -3380,9 +3952,9 @@
             "name": "recursive",
             "in": "query",
             "required": false,
-            "description": "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+            "description": "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
             "schema": {
-              "description": "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+              "description": "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
               "enum": [
                 "true",
                 "1",
@@ -3454,8 +4026,8 @@
     "/api/v2/files/folders/restore": {
       "post": {
         "operationId": "restoreFilesFolder",
-        "summary": "Restore Folder",
-        "description": "Restore a folder and the files and subfolders archived with it. Use the path from List Folders with `scope=archived`. A path that is not archived returns `404`.\n\nOAuth scope: `api:write`.",
+        "summary": "Restore folder",
+        "description": "Restore a folder and the files and subfolders archived with it. Use the path from List folders with `scope=archived`. A path that is not archived returns `404`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "files.folders.restore",
         "x-oauth-scope": "api:write",
         "tags": ["Files"],
@@ -3790,7 +4362,7 @@
         }
       },
       "ServiceUnavailable": {
-        "description": "A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, because the run may already have started — reconcile against the returned run id instead of retrying.",
+        "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
         "headers": {
           "Retry-After": {
             "$ref": "#/components/headers/Retry-After"
@@ -4019,7 +4591,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -4198,7 +4770,7 @@
           },
           "content": {
             "default": "",
-            "description": "Initial file content. Omit or send an empty string for a zero-byte file. The 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`. Use an upload session for anything larger.",
+            "description": "Initial file content. Omit or send an empty string for a zero-byte file. The complete JSON request is capped at 10 MiB, including UTF-8 encoding, escaping, base64, and the envelope. The separate decoded-file limit is 50 MiB. Use an upload session for larger payloads.",
             "type": "string",
             "maxLength": 70000000
           },
@@ -4780,7 +5352,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -4864,7 +5436,7 @@
           "deleted": {
             "type": "boolean",
             "const": true,
-            "description": "Always true: the version and its stored content are gone."
+            "description": "True when the version was removed from history. Stored-content deletion may finish through a background retry."
           }
         },
         "required": ["fileId", "version", "deleted"],
@@ -5110,7 +5682,7 @@
             "maximum": 2147483647
           },
           "expectedRevision": {
-            "description": "Revert only while the file still holds the content this revision names, as returned by Get File Metadata or an earlier write; otherwise the request fails with `409`. Unlike a version number, it also catches edits that folded into the current version.",
+            "description": "Revert only while the file still holds the content this revision names, as returned by Get file metadata or an earlier write; otherwise the request fails with `409`. Unlike a version number, it also catches edits that folded into the current version.",
             "type": "string",
             "minLength": 1
           }
@@ -5280,7 +5852,7 @@
         "required": ["data"],
         "additionalProperties": false,
         "title": "Restore file response",
-        "description": "The restored workspace file, at the root and under its post-restore name.",
+        "description": "The restored file, with its resulting folderPath and name.",
         "examples": [
           {
             "data": {
@@ -5474,7 +6046,7 @@
             "type": "integer",
             "minimum": 1,
             "maximum": 2147483647,
-            "description": "Version number of the current content. List File Versions returns the history; pass this as `expectedCurrentVersion` to revert only if nothing changed since."
+            "description": "Current version number. List file versions returns the history. Pass this as `expectedCurrentVersion` to require that version to remain current; use `expectedRevision` to detect edits folded into the same version."
           }
         },
         "required": [
@@ -5689,7 +6261,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -6127,7 +6699,7 @@
             "description": "One exact or anchor-based edit: search_replace, replace_between, insert_after, or delete_between."
           },
           "expectedRevision": {
-            "description": "Revision from Get File Metadata or an earlier write; the request is refused with `409` when the content moved on.",
+            "description": "Revision from Get file metadata or an earlier write; the request is refused with `409` when the content moved on.",
             "type": "string",
             "minLength": 1
           }
@@ -6423,7 +6995,7 @@
           "content": {
             "type": "string",
             "maxLength": 70000000,
-            "description": "Complete replacement content for the file. The 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`."
+            "description": "Complete replacement content for the file. The complete JSON request is capped at 10 MiB, including UTF-8 encoding, escaping, base64, and the envelope. The separate decoded-file limit is 50 MiB. Small patches can edit a larger stored text file without sending its full content."
           },
           "encoding": {
             "default": "utf-8",
@@ -6432,7 +7004,7 @@
             "enum": ["utf-8", "base64"]
           },
           "expectedRevision": {
-            "description": "Revision from Get File Metadata or an earlier write; the request is refused with `409` when the content moved on.",
+            "description": "Revision from Get file metadata or an earlier write; the request is refused with `409` when the content moved on.",
             "type": "string",
             "minLength": 1
           }
@@ -6578,7 +7150,7 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           }
         },
         "required": ["data", "nextCursor"],
diff --git a/apps/docs/openapi-v2-knowledge.json b/apps/docs/openapi-v2-knowledge.json
index d54d703a883..9ff5d28c0ed 100644
--- a/apps/docs/openapi-v2-knowledge.json
+++ b/apps/docs/openapi-v2-knowledge.json
@@ -38,7 +38,7 @@
     "/api/v2/knowledge": {
       "get": {
         "operationId": "listKnowledgeBases",
-        "summary": "List Knowledge Bases",
+        "summary": "List knowledge bases",
         "description": "List active knowledge bases in a workspace with folder filtering, search, sorting, and cursor pagination. Use `scope=archived` to find knowledge bases available for restoration. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.list",
         "x-oauth-scope": "api:read",
@@ -60,10 +60,10 @@
             "name": "scope",
             "in": "query",
             "required": false,
-            "description": "Lifecycle scope: active or archived knowledge bases. Use Restore Knowledge Base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.",
+            "description": "Lifecycle scope: active or archived knowledge bases. Use Restore knowledge base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.",
             "schema": {
               "default": "active",
-              "description": "Lifecycle scope: active or archived knowledge bases. Use Restore Knowledge Base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.",
+              "description": "Lifecycle scope: active or archived knowledge bases. Use Restore knowledge base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.",
               "type": "string",
               "enum": ["active", "archived"]
             }
@@ -94,10 +94,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "createdAt",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -189,7 +189,7 @@
       },
       "post": {
         "operationId": "createKnowledgeBase",
-        "summary": "Create Knowledge Base",
+        "summary": "Create knowledge base",
         "description": "Create a knowledge base in a workspace with optional folder placement and chunking configuration. An unknown `folderPath` returns `404`. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.create",
         "x-oauth-scope": "api:write",
@@ -201,6 +201,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateKnowledgeBaseRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "Product Documentation",
+                    "folderPath": "/Product"
+                  }
+                }
               }
             }
           }
@@ -263,7 +273,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}": {
       "get": {
         "operationId": "getKnowledgeBase",
-        "summary": "Get Knowledge Base",
+        "summary": "Get knowledge base",
         "description": "Get a knowledge base's metadata and document counts. Inaccessible knowledge bases return `404`. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.read",
         "x-oauth-scope": "api:read",
@@ -342,7 +352,7 @@
       },
       "patch": {
         "operationId": "updateKnowledgeBase",
-        "summary": "Update Knowledge Base",
+        "summary": "Update knowledge base",
         "description": "Update a knowledge base's name, description, chunking configuration, or folder placement. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.update",
         "x-oauth-scope": "api:write",
@@ -367,6 +377,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateKnowledgeBaseRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "Updated Product Documentation"
+                  }
+                }
               }
             }
           }
@@ -427,8 +446,8 @@
       },
       "delete": {
         "operationId": "deleteKnowledgeBase",
-        "summary": "Delete Knowledge Base",
-        "description": "Archive a knowledge base, its documents, and its connectors, pausing synchronization. Use List Knowledge Bases with `scope=archived` to find it and Restore Knowledge Base to recover it.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete knowledge base",
+        "description": "Archive a knowledge base, its documents, and its connectors, pausing synchronization. Use List knowledge bases with `scope=archived` to find it and Restore knowledge base to recover it.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -505,8 +524,8 @@
     "/api/v2/knowledge/{knowledgeBaseId}/export": {
       "get": {
         "operationId": "exportKnowledgeBase",
-        "summary": "Export Knowledge Base",
-        "description": "Stream a knowledge base as a bundle archive: its configuration, tag definitions, each workspace-visible document's file and chunk text, and optionally chunk vectors. Access-control lists, connector links, and credentials never leave. More than 2000 documents returns `413`. Exports record an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` omits `Content-Length`; use file metadata to size downloads.\n\nOAuth scope: `api:read`.",
+        "summary": "Export knowledge base",
+        "description": "Stream a knowledge base as a bundle archive: its configuration, tag definitions, each workspace-visible document's file and chunk text, and optionally chunk vectors. Access-control lists, connector links, and credentials never leave. More than 2000 documents returns `413`. Exports record an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` omits `Content-Length` and cannot determine the download size.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.export",
         "x-oauth-scope": "api:read",
         "tags": ["Knowledge Bases"],
@@ -604,7 +623,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/connectors": {
       "get": {
         "operationId": "listKnowledgeConnectors",
-        "summary": "List Knowledge Connectors",
+        "summary": "List knowledge connectors",
         "description": "List external sources connected to a knowledge base with cursor pagination. Stored API keys are never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.connectors.list",
         "x-oauth-scope": "api:read",
@@ -700,6 +719,35 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2KnowledgeConnectorListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "kc-9f8e7d6c",
+                          "knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+                          "connectorType": "notion",
+                          "credentialId": "cred-4b3a2c1d",
+                          "sourceConfig": {
+                            "pageIds": ["page-123"]
+                          },
+                          "syncMode": "full",
+                          "syncIntervalMinutes": 1440,
+                          "status": "active",
+                          "lastSyncAt": "2026-06-20T14:02:11.000Z",
+                          "lastSyncError": null,
+                          "lastSyncDocCount": 42,
+                          "nextSyncAt": "2026-06-21T14:02:11.000Z",
+                          "consecutiveFailures": 0,
+                          "createdAt": "2026-06-01T09:14:00.000Z",
+                          "updatedAt": "2026-06-20T14:02:11.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -729,7 +777,7 @@
       },
       "post": {
         "operationId": "createKnowledgeConnector",
-        "summary": "Create Knowledge Connector",
+        "summary": "Create knowledge connector",
         "description": "Validate and connect an external source, then queue its initial synchronization. The `apiKey` field is never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.connectors.create",
         "x-oauth-scope": "api:write",
@@ -754,6 +802,20 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateKnowledgeConnectorRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "connectorType": "notion",
+                    "credentialId": "cred-4b3a2c1d",
+                    "sourceConfig": {
+                      "pageIds": ["page-123"]
+                    },
+                    "syncIntervalMinutes": 1440
+                  }
+                }
               }
             }
           }
@@ -776,6 +838,32 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2KnowledgeConnectorResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "kc-9f8e7d6c",
+                        "knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+                        "connectorType": "notion",
+                        "credentialId": "cred-4b3a2c1d",
+                        "sourceConfig": {
+                          "pageIds": ["page-123"]
+                        },
+                        "syncMode": "full",
+                        "syncIntervalMinutes": 1440,
+                        "status": "active",
+                        "lastSyncAt": "2026-06-20T14:02:11.000Z",
+                        "lastSyncError": null,
+                        "lastSyncDocCount": 42,
+                        "nextSyncAt": "2026-06-21T14:02:11.000Z",
+                        "consecutiveFailures": 0,
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -816,7 +904,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}": {
       "get": {
         "operationId": "getKnowledgeConnector",
-        "summary": "Get Knowledge Connector",
+        "summary": "Get knowledge connector",
         "description": "Get one connector and its ten most recent synchronization attempts. Stored API keys are never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.connectors.read",
         "x-oauth-scope": "api:read",
@@ -875,6 +963,33 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2KnowledgeConnectorDetailResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "kc-9f8e7d6c",
+                        "knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+                        "connectorType": "notion",
+                        "credentialId": "cred-4b3a2c1d",
+                        "sourceConfig": {
+                          "pageIds": ["page-123"]
+                        },
+                        "syncMode": "full",
+                        "syncIntervalMinutes": 1440,
+                        "status": "active",
+                        "lastSyncAt": "2026-06-20T14:02:11.000Z",
+                        "lastSyncError": null,
+                        "lastSyncDocCount": 42,
+                        "nextSyncAt": "2026-06-21T14:02:11.000Z",
+                        "consecutiveFailures": 0,
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z",
+                        "syncLogs": []
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -904,7 +1019,7 @@
       },
       "patch": {
         "operationId": "updateKnowledgeConnector",
-        "summary": "Update Knowledge Connector",
+        "summary": "Update knowledge connector",
         "description": "Update connector source configuration, schedule, or active state. Replacing source configuration on a runnable connector queues an immediate synchronization; paused connectors retain the change without synchronizing until resumed. Source configuration cannot be replaced while synchronization is already in progress. Authentication material cannot be changed through this operation. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.connectors.update",
         "x-oauth-scope": "api:write",
@@ -940,6 +1055,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateKnowledgeConnectorRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "status": "paused"
+                  }
+                }
               }
             }
           }
@@ -961,7 +1085,33 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/V2KnowledgeConnectorResponse"
+                  "$ref": "#/components/schemas/UpdateKnowledgeConnectorResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "kc-9f8e7d6c",
+                        "knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+                        "connectorType": "notion",
+                        "credentialId": "cred-4b3a2c1d",
+                        "sourceConfig": {
+                          "pageIds": ["page-123"]
+                        },
+                        "syncMode": "full",
+                        "syncIntervalMinutes": 1440,
+                        "status": "paused",
+                        "lastSyncAt": "2026-06-20T14:02:11.000Z",
+                        "lastSyncError": null,
+                        "lastSyncDocCount": 42,
+                        "nextSyncAt": "2026-06-21T14:02:11.000Z",
+                        "consecutiveFailures": 0,
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:03:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1000,7 +1150,7 @@
       },
       "delete": {
         "operationId": "deleteKnowledgeConnector",
-        "summary": "Delete Knowledge Connector",
+        "summary": "Delete knowledge connector",
         "description": "Delete a connector and optionally its synchronized documents. Documents are retained by default. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.connectors.delete",
         "x-oauth-scope": "api:write",
@@ -1069,6 +1219,19 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2KnowledgeConnectorDeleteResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "kc-9f8e7d6c",
+                        "deleted": true,
+                        "documentsDeleted": 0,
+                        "documentsKept": 42
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1100,7 +1263,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/sync": {
       "post": {
         "operationId": "syncKnowledgeConnector",
-        "summary": "Sync Knowledge Connector",
+        "summary": "Sync knowledge connector",
         "description": "Queue a connector synchronization. Rehydration forces existing documents to be fetched and indexed again. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.connectors.sync",
         "x-oauth-scope": "api:write",
@@ -1136,6 +1299,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/SyncKnowledgeConnectorRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "rehydrate": false
+                  }
+                }
               }
             }
           }
@@ -1158,6 +1330,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2KnowledgeConnectorSyncResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "kc-9f8e7d6c",
+                        "syncTriggered": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1198,7 +1381,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}/documents": {
       "get": {
         "operationId": "listKnowledgeConnectorDocuments",
-        "summary": "List Knowledge Connector Documents",
+        "summary": "List knowledge connector documents",
         "description": "List documents produced by one connector with opaque cursor pagination. Excluded documents are omitted unless explicitly requested. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.connectors.documents.list",
         "x-oauth-scope": "api:read",
@@ -1291,6 +1474,26 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2KnowledgeConnectorDocumentListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "doc-8a7b6c5d",
+                          "filename": "Product requirements",
+                          "externalId": "page-123",
+                          "sourceUrl": "https://www.notion.so/page-123",
+                          "enabled": true,
+                          "userExcluded": false,
+                          "createdAt": "2026-06-01T09:15:00.000Z",
+                          "processingStatus": "completed"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -1320,7 +1523,7 @@
       },
       "patch": {
         "operationId": "updateKnowledgeConnectorDocuments",
-        "summary": "Update Knowledge Connector Documents",
+        "summary": "Update knowledge connector documents",
         "description": "Exclude connector documents from knowledge search or restore previously excluded documents. Only documents produced by the selected connector can change. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.connectors.documents.update",
         "x-oauth-scope": "api:write",
@@ -1356,6 +1559,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateKnowledgeConnectorDocumentsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "operation": "exclude",
+                    "documentIds": ["doc-8a7b6c5d"]
+                  }
+                }
               }
             }
           }
@@ -1378,6 +1591,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2KnowledgeConnectorDocumentsUpdateResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "operation": "exclude",
+                        "updatedCount": 1,
+                        "documentIds": ["doc-8a7b6c5d"]
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1415,7 +1640,7 @@
     "/api/v2/knowledge/search": {
       "post": {
         "operationId": "searchKnowledge",
-        "summary": "Search Knowledge",
+        "summary": "Search knowledge",
         "description": "Search one or more knowledge bases with semantic vector retrieval, optional hybrid full-text retrieval, and structured tag filters. Every result names the `knowledgeBaseId` it came from. A request body over 2 MiB is a `413`. Reranking returns `409` when the stored results cannot pass secret-provenance enforcement.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.search",
         "x-oauth-scope": "api:read",
@@ -1427,6 +1652,17 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/SearchKnowledgeRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "knowledgeBaseIds": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"],
+                    "query": "How do I reset my password?",
+                    "topK": 10
+                  }
+                }
               }
             }
           }
@@ -1492,8 +1728,8 @@
     "/api/v2/knowledge/{knowledgeBaseId}/tags": {
       "get": {
         "operationId": "listKnowledgeTags",
-        "summary": "List Tags",
-        "description": "List the knowledge base's tag definitions with display names, write slots, and field types. Filters and document reads use display names; document writes use slots. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
+        "summary": "List tags",
+        "description": "List the knowledge base's tag definitions with display names, write slots, and field types. Filters and document reads use display names; document writes use slots. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.tags.list",
         "x-oauth-scope": "api:read",
         "tags": ["Knowledge Bases"],
@@ -1568,8 +1804,8 @@
       },
       "post": {
         "operationId": "createKnowledgeTag",
-        "summary": "Create Tag",
-        "description": "Create a tag definition. Write document values by `tagSlot` and filter by `displayName`. Omitting `tagSlot` selects a free slot; exhaustion returns `400`. An occupied slot or duplicate name returns `409`. Use Bulk Save Tag Definitions for multiple definitions. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create tag",
+        "description": "Create a tag definition. Write document values by `tagSlot` and filter by `displayName`. Omitting `tagSlot` selects a free slot; exhaustion returns `400`. An occupied slot or duplicate name returns `409`. Use Bulk save tag definitions for multiple definitions. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.tags.create",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -1593,6 +1829,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateKnowledgeTagRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "displayName": "category",
+                    "fieldType": "text"
+                  }
+                }
               }
             }
           }
@@ -1653,8 +1899,8 @@
       },
       "put": {
         "operationId": "bulkSaveKnowledgeTagDefinitions",
-        "summary": "Bulk Save Tag Definitions",
-        "description": "Create or update tag definitions, preserving unspecified slots. Updates require `originalDisplayName`; other entries create tags. Slot and name conflicts appear in per-definition `errors` with HTTP `200`, leaving conflicting values unchanged. Use Update Document to set tag values. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Bulk save tag definitions",
+        "description": "Create or update tag definitions, preserving unspecified slots. Updates require `originalDisplayName`; other entries create tags. Slot and name conflicts appear in per-definition `errors` with HTTP `200`, leaving conflicting values unchanged. Use Update document to set tag values. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.tags.bulk_save",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -1678,6 +1924,21 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/BulkSaveKnowledgeTagDefinitionsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "definitions": [
+                      {
+                        "tagSlot": "tag1",
+                        "displayName": "category",
+                        "fieldType": "text"
+                      }
+                    ]
+                  }
+                }
               }
             }
           }
@@ -1735,8 +1996,8 @@
       },
       "delete": {
         "operationId": "deleteKnowledgeTagDefinitions",
-        "summary": "Delete Tag Definitions",
-        "description": "Delete unused tag definitions by default. With `unused=false`, permanently delete all definitions and their values from documents and chunks. Use Delete Tag to remove one definition. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete tag definitions",
+        "description": "Delete unused tag definitions by default. With `unused=false`, permanently delete all definitions and their values from documents and chunks. Use Delete tag to remove one definition. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.tags.cleanup",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -1824,8 +2085,8 @@
     "/api/v2/knowledge/{knowledgeBaseId}/documents": {
       "get": {
         "operationId": "listKnowledgeDocuments",
-        "summary": "List Documents",
-        "description": "List documents with filename search, state and tag filters, sorting, and cursor pagination. Tag values use display names; use List Tags to resolve the slots required for writes.\n\nOAuth scope: `api:read`.",
+        "summary": "List documents",
+        "description": "List documents with filename search, state and tag filters, sorting, and cursor pagination. Tag values use display names; use List tags to resolve the slots required for writes.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.documents.list",
         "x-oauth-scope": "api:read",
         "tags": ["Knowledge Bases"],
@@ -1893,10 +2154,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `filename` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `filename`.",
             "schema": {
               "default": "uploadedAt",
-              "description": "Field used to sort the result. Sorting by `filename` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `filename`.",
               "type": "string",
               "enum": [
                 "filename",
@@ -1993,8 +2254,8 @@
       },
       "patch": {
         "operationId": "bulkUpdateKnowledgeDocuments",
-        "summary": "Bulk Enable or Disable Documents",
-        "description": "Enable or disable selected documents, or use `selectAll` for the entire knowledge base. Use Delete Document to remove documents individually. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Bulk enable or disable documents",
+        "description": "Enable or disable selected documents, or use `selectAll` for the entire knowledge base. Use Delete document to remove documents individually. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.documents.bulk",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -2018,6 +2279,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/BulkUpdateKnowledgeDocumentsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "operation": "disable",
+                    "documentIds": ["b2d4f8a0-1c3e-4a5b-9d7c-2e6f0a8b4c12"]
+                  }
+                }
               }
             }
           }
@@ -2075,7 +2346,7 @@
       },
       "post": {
         "operationId": "uploadKnowledgeDocument",
-        "summary": "Upload Document",
+        "summary": "Upload document",
         "description": "Upload one document as multipart form data. Processing continues asynchronously after the document is accepted.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.documents.upload",
         "x-oauth-scope": "api:write",
@@ -2174,7 +2445,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/documents/uploads": {
       "post": {
         "operationId": "createKnowledgeDocumentUpload",
-        "summary": "Create Document Upload",
+        "summary": "Create document upload",
         "description": "Create a resumable upload session and receive direct PUT or multipart transfer instructions.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.documents.upload.create",
         "x-oauth-scope": "api:write",
@@ -2199,6 +2470,17 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateKnowledgeDocumentUploadRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "getting-started.pdf",
+                    "contentType": "application/pdf",
+                    "size": 248913
+                  }
+                }
               }
             }
           }
@@ -2261,7 +2543,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}": {
       "delete": {
         "operationId": "abortKnowledgeDocumentUpload",
-        "summary": "Abort Document Upload",
+        "summary": "Abort document upload",
         "description": "Abort an incomplete upload session and discard its uploaded data. Completed uploads cannot be aborted.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.documents.upload.cancel",
         "x-oauth-scope": "api:write",
@@ -2365,7 +2647,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}/parts": {
       "post": {
         "operationId": "createKnowledgeDocumentUploadPartUrls",
-        "summary": "Create Document Upload Part URLs",
+        "summary": "Create document upload part URLs",
         "description": "Create short-lived signed PUT URLs for up to 100 multipart part numbers.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.documents.upload.parts",
         "x-oauth-scope": "api:write",
@@ -2424,6 +2706,14 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateKnowledgeDocumentUploadPartUrlsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "partNumbers": [1, 2, 3]
+                  }
+                }
               }
             }
           }
@@ -2486,7 +2776,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/documents/uploads/{uploadId}/complete": {
       "post": {
         "operationId": "completeKnowledgeDocumentUpload",
-        "summary": "Complete Document Upload",
+        "summary": "Complete document upload",
         "description": "Verify a direct upload or assemble multipart parts, create the knowledge document, and queue asynchronous processing.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.documents.upload.complete",
         "x-oauth-scope": "api:write",
@@ -2590,7 +2880,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}": {
       "get": {
         "operationId": "getKnowledgeDocument",
-        "summary": "Get Document",
+        "summary": "Get document",
         "description": "Get document metadata, processing status, and source connector details.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.documents.read",
         "x-oauth-scope": "api:read",
@@ -2677,8 +2967,8 @@
       },
       "patch": {
         "operationId": "updateKnowledgeDocument",
-        "summary": "Update Document",
-        "description": "Rename a document, change search availability, update tag slots, or requeue processing. Omitted fields remain unchanged; indexing state is read-only. Use List Tags to resolve names to slots and Get Document for source connector details, which this response omits. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update document",
+        "description": "Rename a document, change search availability, update tag slots, or requeue processing. Omitted fields remain unchanged; indexing state is read-only. Use List tags to resolve names to slots and Get document for source connector details, which this response omits. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.documents.update",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -2713,6 +3003,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateKnowledgeDocumentRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "enabled": false,
+                    "tag1": "billing"
+                  }
+                }
               }
             }
           }
@@ -2770,7 +3070,7 @@
       },
       "delete": {
         "operationId": "deleteKnowledgeDocument",
-        "summary": "Delete Document",
+        "summary": "Delete document",
         "description": "Remove a document from listings and search. Uploaded documents and their chunks are deleted. Connector documents are excluded while retaining their stored data; later synchronization does not re-add them.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.documents.delete",
         "x-oauth-scope": "api:write",
@@ -2859,8 +3159,8 @@
     "/api/v2/knowledge/folders": {
       "get": {
         "operationId": "listKnowledgeFolders",
-        "summary": "List Folders",
-        "description": "List folders in the knowledge-base folder tree with filtering and sorting. Returns the complete set in one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "summary": "List folders",
+        "description": "List folders in the knowledge-base folder tree with filtering and sorting. Returns one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.folders.list",
         "x-oauth-scope": "api:read",
         "tags": ["Knowledge Bases"],
@@ -2903,10 +3203,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "name",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -2974,7 +3274,7 @@
       },
       "post": {
         "operationId": "createKnowledgeFolder",
-        "summary": "Create Folder",
+        "summary": "Create folder",
         "description": "Create a folder in the knowledge-base folder tree. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.folders.create",
         "x-oauth-scope": "api:write",
@@ -2986,6 +3286,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateKnowledgeFolderRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "path": "/Product"
+                  }
+                }
               }
             }
           }
@@ -3046,7 +3355,7 @@
       },
       "patch": {
         "operationId": "relocateKnowledgeFolder",
-        "summary": "Rename or Move Folder",
+        "summary": "Rename or move folder",
         "description": "Rename or move a folder and atomically rewrite descendant paths. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.folders.relocate",
         "x-oauth-scope": "api:write",
@@ -3058,6 +3367,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RelocateKnowledgeFolderRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "path": "/Product",
+                    "destinationPath": "/Archive/Product"
+                  }
+                }
               }
             }
           }
@@ -3118,8 +3437,8 @@
       },
       "delete": {
         "operationId": "deleteKnowledgeFolder",
-        "summary": "Delete Folder",
-        "description": "Archive an empty folder, or set `recursive=true` to archive its subfolders and knowledge bases. Use Restore Knowledge Base to recover knowledge bases.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete folder",
+        "description": "Archive an empty folder, or set `recursive=true` to archive its subfolders and knowledge bases. Use Restore knowledge base to recover knowledge bases.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.folders.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -3150,9 +3469,9 @@
             "name": "recursive",
             "in": "query",
             "required": false,
-            "description": "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+            "description": "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
             "schema": {
-              "description": "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+              "description": "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
               "enum": [
                 "true",
                 "1",
@@ -3227,7 +3546,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/restore": {
       "post": {
         "operationId": "restoreKnowledgeBase",
-        "summary": "Restore Knowledge Base",
+        "summary": "Restore knowledge base",
         "description": "Restore a knowledge base and the documents and connectors archived with it. Active knowledge bases return unchanged without a new audit event. An archived workspace returns `409`; an archived containing folder moves the restored knowledge base to the workspace root. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.restore",
         "x-oauth-scope": "api:write",
@@ -3252,6 +3571,14 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RestoreKnowledgeBaseRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64"
+                  }
+                }
               }
             }
           }
@@ -3314,8 +3641,8 @@
     "/api/v2/knowledge/{knowledgeBaseId}/documents/from-workspace-files": {
       "post": {
         "operationId": "addWorkspaceFilesToKnowledgeBase",
-        "summary": "Index Workspace Files",
-        "description": "Queue stored workspace files for indexing without re-uploading bytes. Unreadable, unsupported, or over-100 MB files appear in `failed`; valid files are queued. Partial success returns `200`. Use Get Document to poll processing after receiving document IDs. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Index workspace files",
+        "description": "Queue stored workspace files for indexing without re-uploading bytes. Unreadable, unsupported, or over-100 MiB files appear in `failed`; valid files are queued. Partial success returns `200`. Use Get document to poll processing after receiving document IDs. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.documents.add_workspace_files",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -3339,6 +3666,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/AddWorkspaceFilesToKnowledgeBaseRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "fileReferences": ["handbook.pdf"]
+                  }
+                }
               }
             }
           }
@@ -3401,8 +3737,8 @@
     "/api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks": {
       "get": {
         "operationId": "listKnowledgeChunks",
-        "summary": "List Chunks",
-        "description": "List document chunks with content search, enabled filtering, sorting, and cursor pagination. Tags use slots; use List Tags to resolve display names. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List chunks",
+        "description": "List document chunks with content search, enabled filtering, sorting, and cursor pagination. Tags use slots; use List tags to resolve display names. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.chunks.list",
         "x-oauth-scope": "api:read",
         "tags": ["Knowledge Bases"],
@@ -3564,8 +3900,8 @@
       },
       "post": {
         "operationId": "createKnowledgeChunk",
-        "summary": "Create Chunk",
-        "description": "Append a chunk, embedding it before the response so it is immediately searchable. It inherits the document's tags and next `chunkIndex`. Connector-synced chunks are read-only and return `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"`; change the source and re-sync, or exclude the document. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create chunk",
+        "description": "Append a chunk and embed it before returning. It inherits the document's tags and next `chunkIndex`. Search includes it when the chunk and document are enabled and the document has completed processing. Connector-synced chunks are read-only and return `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"`; change the source and re-sync, or exclude the document. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.chunks.create",
         "x-oauth-scope": "api:write",
         "tags": ["Knowledge Bases"],
@@ -3600,6 +3936,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateKnowledgeChunkRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "content": "To reset your password, open Settings and choose Security."
+                  }
+                }
               }
             }
           }
@@ -3657,7 +4002,7 @@
       },
       "patch": {
         "operationId": "bulkUpdateKnowledgeChunks",
-        "summary": "Bulk Update Chunks",
+        "summary": "Bulk update chunks",
         "description": "Enable, disable, or delete multiple chunks in one best-effort request. Unknown chunk IDs appear in `errors` without failing the request; `processed` counts matched chunks, not changes. Connector-synced chunks are read-only and return `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"`; change the source and re-sync, or exclude the document. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.chunks.bulk",
         "x-oauth-scope": "api:write",
@@ -3693,6 +4038,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/BulkUpdateKnowledgeChunksRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "operation": "disable",
+                    "chunkIds": ["4c1f9e77-2b3a-4f8d-9e10-6a2c8d4b1e05"]
+                  }
+                }
               }
             }
           }
@@ -3752,7 +4107,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}": {
       "get": {
         "operationId": "getKnowledgeChunk",
-        "summary": "Get Chunk",
+        "summary": "Get chunk",
         "description": "Get one chunk of a document, including the exact text that was embedded. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.chunks.read",
         "x-oauth-scope": "api:read",
@@ -3854,7 +4209,7 @@
       },
       "patch": {
         "operationId": "updateKnowledgeChunk",
-        "summary": "Update Chunk",
+        "summary": "Update chunk",
         "description": "Correct chunk text or disable it from search. Changing `content` re-embeds immediately and recalculates document token and character counts; disabling retains the index. Connector-synced chunks are read-only and return `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"`; change the source and re-sync, or exclude the document. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.chunks.update",
         "x-oauth-scope": "api:write",
@@ -3901,6 +4256,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateKnowledgeChunkRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "enabled": false
+                  }
+                }
               }
             }
           }
@@ -3961,7 +4325,7 @@
       },
       "delete": {
         "operationId": "deleteKnowledgeChunk",
-        "summary": "Delete Chunk",
+        "summary": "Delete chunk",
         "description": "Permanently remove one chunk and subtract it from document counts. Remaining `chunkIndex` values stay stable and may become non-contiguous. Connector-synced chunks are read-only and return `403` with `error.details.code: \"CONNECTOR_MANAGED_RESOURCE_READ_ONLY\"`; change the source and re-sync, or exclude the document. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.chunks.delete",
         "x-oauth-scope": "api:write",
@@ -4065,7 +4429,7 @@
     "/api/v2/knowledge/{knowledgeBaseId}/tags/{tagId}": {
       "patch": {
         "operationId": "updateKnowledgeTag",
-        "summary": "Update Tag",
+        "summary": "Update tag",
         "description": "Rename a tag or change its slot-compatible `fieldType`. Renaming changes read and filter names without moving the slot or its values. Slots are fixed for a tag's lifetime; an incompatible type returns `400` and requires creating a new tag. A duplicate display name returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.tags.update",
         "x-oauth-scope": "api:write",
@@ -4101,6 +4465,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateKnowledgeTagRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "displayName": "topic"
+                  }
+                }
               }
             }
           }
@@ -4161,7 +4534,7 @@
       },
       "delete": {
         "operationId": "deleteKnowledgeTag",
-        "summary": "Delete Tag",
+        "summary": "Delete tag",
         "description": "Permanently delete a tag definition and its values from every document and chunk in the knowledge base. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "knowledge.tags.delete",
         "x-oauth-scope": "api:write",
@@ -4254,8 +4627,8 @@
     "/api/v2/knowledge/{knowledgeBaseId}/tags/next-slot": {
       "get": {
         "operationId": "getNextKnowledgeTagSlot",
-        "summary": "Get Next Tag Slot",
-        "description": "Get the next available slot and remaining capacity for a field type. This does not reserve a slot. Create Tag selects a free slot when `tagSlot` is omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get next tag slot",
+        "description": "Get the next available slot and remaining capacity for a field type. This does not reserve a slot. Create tag selects a free slot when `tagSlot` is omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.tags.read_next_slot",
         "x-oauth-scope": "api:read",
         "tags": ["Knowledge Bases"],
@@ -4345,8 +4718,8 @@
     "/api/v2/knowledge/{knowledgeBaseId}/tags/usage": {
       "get": {
         "operationId": "listKnowledgeTagUsage",
-        "summary": "List Tag Usage",
-        "description": "Count the documents and chunks with a value for each defined tag. Returns the complete set in one page; `nextCursor` is always null. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List tag usage",
+        "description": "Count the documents and chunks with a value for each defined tag. Returns one page; `nextCursor` is always null. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "knowledge.tags.read_usage",
         "x-oauth-scope": "api:read",
         "tags": ["Knowledge Bases"],
@@ -4607,7 +4980,7 @@
             "example": {
               "error": {
                 "code": "CONFLICT",
-                "message": "Upload has already been completed"
+                "message": "The request conflicts with current knowledge resource state"
               }
             }
           }
@@ -4686,7 +5059,7 @@
         }
       },
       "ServiceUnavailable": {
-        "description": "A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, because the run may already have started — reconcile against the returned run id instead of retrying.",
+        "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
         "headers": {
           "Retry-After": {
             "$ref": "#/components/headers/Retry-After"
@@ -4904,7 +5277,7 @@
                 "type": "null"
               }
             ],
-            "description": "ISO 8601 archive timestamp, or null while active. Use List Knowledge Bases with `scope=archived` to find archived knowledge bases.",
+            "description": "ISO 8601 archive timestamp, or null while active. Use List knowledge bases with `scope=archived` to find archived knowledge bases.",
             "format": "date-time",
             "examples": ["2026-01-16T09:00:00Z"]
           }
@@ -4943,7 +5316,7 @@
           },
           "overlap": {
             "type": "number",
-            "description": "Number of overlapping characters between adjacent chunks.",
+            "description": "Requested overlap in tokens between adjacent chunks.",
             "examples": [200]
           },
           "strategy": {
@@ -5006,7 +5379,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -5048,7 +5421,7 @@
           },
           "overlap": {
             "default": 200,
-            "description": "Number of overlapping characters between adjacent chunks.",
+            "description": "Requested overlap in tokens between adjacent chunks.",
             "examples": [200],
             "type": "number",
             "minimum": 0,
@@ -5366,7 +5739,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -5790,6 +6163,42 @@
           }
         ]
       },
+      "UpdateKnowledgeConnectorResponse": {
+        "type": "object",
+        "properties": {
+          "data": {
+            "description": "Response data.",
+            "$ref": "#/components/schemas/V2KnowledgeConnector"
+          }
+        },
+        "required": ["data"],
+        "additionalProperties": false,
+        "title": "Update knowledge connector response",
+        "description": "A single connector without secret material.",
+        "examples": [
+          {
+            "data": {
+              "id": "kc-9f8e7d6c",
+              "knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+              "connectorType": "notion",
+              "credentialId": "cred-4b3a2c1d",
+              "sourceConfig": {
+                "pageIds": ["page-123"]
+              },
+              "syncMode": "full",
+              "syncIntervalMinutes": 1440,
+              "status": "paused",
+              "lastSyncAt": "2026-06-20T14:02:11.000Z",
+              "lastSyncError": null,
+              "lastSyncDocCount": 42,
+              "nextSyncAt": "2026-06-21T14:02:11.000Z",
+              "consecutiveFailures": 0,
+              "createdAt": "2026-06-01T09:14:00.000Z",
+              "updatedAt": "2026-06-20T14:03:00.000Z"
+            }
+          }
+        ]
+      },
       "UpdateKnowledgeConnectorRequest": {
         "type": "object",
         "properties": {
@@ -6039,7 +6448,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -6294,7 +6703,7 @@
           "rerankerStatus": {
             "type": "string",
             "enum": ["not_requested", "skipped", "unavailable", "applied"],
-            "description": "What the reranker did on this search. `applied` means it ordered the results, which carry `rerankerScore`. `unavailable` means it was attempted but could not complete, so results are in vector order with no `rerankerScore` — the search still succeeded, and is worth retrying. `skipped` means there was nothing to rank. `not_requested` means `rerankerEnabled` was absent or false.",
+            "description": "Reranking outcome. `applied` means results carry `rerankerScore` and follow that score. `unavailable` means reranking could not produce a usable order; the search succeeded in retrieval order without `rerankerScore`. Retry if reranking is needed. `skipped` means there was nothing to rank. `not_requested` means `rerankerEnabled` was absent or false.",
             "examples": ["applied"]
           }
         },
@@ -6412,7 +6821,7 @@
                 }
               }
             ],
-            "description": "One knowledge base identifier or an array of up to 20 identifiers.",
+            "description": "One knowledge base ID or an array of up to 20 IDs. Query searches require the same embedding model and dimensions across all selected bases; search incompatible bases separately. Tag-only searches do not require this.",
             "examples": [["7c9e6679-7425-40de-944b-e07fc1f90ae7"]]
           },
           "query": {
@@ -6437,7 +6846,7 @@
             }
           },
           "searchMode": {
-            "description": "Retrieval strategy: vector is semantic-only, while hybrid also runs full-text search.",
+            "description": "Retrieval strategy: `vector` uses semantic search; `hybrid` also runs full-text search. Omit to use the workspace policy.",
             "anyOf": [
               {
                 "type": "string",
@@ -6449,7 +6858,7 @@
             ]
           },
           "rerankerEnabled": {
-            "description": "Re-order retrieved chunks with a reranking model before truncating to `topK`. Ignored for a tag-only search, and billed as an additional search unit. Reranking is best-effort — a provider failure falls back to vector ordering, so check `rerankerStatus` on the response.",
+            "description": "Reorder retrieved chunks with a reranking model before truncating to `topK`. Ignored for tag-only searches. A completed reranking call adds a search unit. If reranking is unavailable, results keep their retrieval order; check `rerankerStatus`.",
             "type": "boolean"
           },
           "rerankerModel": {
@@ -6475,7 +6884,7 @@
         "properties": {
           "id": {
             "type": "string",
-            "description": "Tag definition ID used by Update Tag and Delete Tag."
+            "description": "Tag definition ID used by Update tag and Delete tag."
           },
           "displayName": {
             "type": "string",
@@ -6484,7 +6893,7 @@
           },
           "tagSlot": {
             "type": "string",
-            "description": "Storage slot the tag occupies. Document writes set tag values by slot (`tag1`..`tag7`).",
+            "description": "Slot used by document updates: `tag1`–`tag7`, `number1`–`number5`, `date1`–`date2`, or `boolean1`–`boolean3`. Upload creation accepts text slots; use Update document for other types.",
             "examples": ["tag1"]
           },
           "fieldType": {
@@ -6517,7 +6926,7 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           }
         },
         "required": ["data", "nextCursor"],
@@ -6614,7 +7023,7 @@
               ],
               "description": "Tag value; dates are ISO 8601 strings and an unset tag is null."
             },
-            "description": "Document tag values keyed by display name. Writes use slots such as `tag1`; use List Tags to map names to slots.",
+            "description": "Document tag values keyed by display name. Writes use slots such as `tag1`; use List tags to map names to slots.",
             "examples": [
               {
                 "category": "billing",
@@ -6660,7 +7069,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -6862,7 +7271,7 @@
             "format": "binary",
             "contentEncoding": "binary",
             "maxLength": 104857600,
-            "description": "Document file to upload; the maximum size is 100 MB."
+            "description": "Document file to upload; the maximum size is 100 MiB."
           }
         },
         "required": ["file"],
@@ -7351,7 +7760,7 @@
               ],
               "description": "Tag value; dates are ISO 8601 strings and an unset tag is null."
             },
-            "description": "Document tag values keyed by display name. Writes use slots such as `tag1`; use List Tags to map names to slots.",
+            "description": "Document tag values keyed by display name. Writes use slots such as `tag1`; use List tags to map names to slots.",
             "examples": [
               {
                 "category": "billing",
@@ -7683,7 +8092,7 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           }
         },
         "required": ["data", "nextCursor"],
@@ -7909,7 +8318,7 @@
               "type": "string",
               "minLength": 1
             },
-            "description": "Workspace file identifiers or storage keys to index. Duplicates resolving to the same file are indexed once."
+            "description": "Workspace file IDs or paths to index. Prefer IDs or canonical `files/<folder>/<name>` paths. Duplicates resolving to the same file are indexed once."
           }
         },
         "required": ["workspaceId", "fileReferences"],
@@ -8105,7 +8514,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -8139,7 +8548,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 10000,
-            "description": "Text to embed. It is embedded on write, so the chunk is searchable immediately."
+            "description": "Text embedded before the response. Search includes it when the chunk and document are enabled and the document has completed processing."
           },
           "enabled": {
             "default": true,
@@ -8530,7 +8939,7 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           }
         },
         "required": ["data", "nextCursor"],
diff --git a/apps/docs/openapi-v2-logs.json b/apps/docs/openapi-v2-logs.json
index 2279e818cfc..39e5b6bbd92 100644
--- a/apps/docs/openapi-v2-logs.json
+++ b/apps/docs/openapi-v2-logs.json
@@ -38,8 +38,8 @@
     "/api/v2/logs": {
       "get": {
         "operationId": "listLogs",
-        "summary": "List Logs",
-        "description": "List logs with filters, selectable detail, sorting, and cursor pagination. `includeJobRuns=true` includes chat and Sim-agent jobs only with `sortBy=startedAt`, because other orderings are unsupported. `files` contains only run-produced files; use the files API for input attachments. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "summary": "List logs",
+        "description": "List logs with filters, selectable detail, sorting, and cursor pagination. `includeJobRuns=true` includes chat and Sim-agent jobs only with `sortBy=startedAt`, because other orderings are unsupported. `files` contains only run-produced files; use the files API for input attachments. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "logs.list",
         "x-oauth-scope": "api:read",
         "tags": ["Logs"],
@@ -331,6 +331,41 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2LogListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "kind": "workflow",
+                          "runId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
+                          "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                          "deploymentVersionId": "dep_2c4e6a8b0d1f",
+                          "status": "completed",
+                          "level": "info",
+                          "trigger": "api",
+                          "startedAt": "2026-01-15T10:30:00.000Z",
+                          "endedAt": "2026-01-15T10:30:01.250Z",
+                          "totalDurationMs": 1250,
+                          "cost": {
+                            "total": 0.0072
+                          },
+                          "hasHandledErrors": false,
+                          "files": [
+                            {
+                              "id": "f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04",
+                              "name": "summary.pdf",
+                              "size": 18422,
+                              "type": "application/pdf",
+                              "downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13/files/f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04"
+                            }
+                          ]
+                        }
+                      ],
+                      "nextCursor": "eyJzdGFydGVkQXQiOiIyMDI2LTAxLTE1VDEwOjMwOjAwMFoifQ=="
+                    }
+                  }
                 }
               }
             }
@@ -365,8 +400,8 @@
     "/api/v2/logs/{runId}": {
       "get": {
         "operationId": "getLog",
-        "summary": "Get Log",
-        "description": "Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty `traceSpans` array does not prove none were recorded. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "summary": "Get log",
+        "description": "Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty `traceSpans` array does not prove none were recorded. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "logs.read_detail",
         "x-oauth-scope": "api:read",
         "tags": ["Logs"],
@@ -413,6 +448,74 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2LogDetailResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "runId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
+                        "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "deploymentVersionId": "dep_2c4e6a8b0d1f",
+                        "status": "completed",
+                        "level": "info",
+                        "trigger": "api",
+                        "startedAt": "2026-01-15T10:30:00.000Z",
+                        "endedAt": "2026-01-15T10:30:01.250Z",
+                        "totalDurationMs": 1250,
+                        "files": [
+                          {
+                            "id": "f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04",
+                            "name": "summary.pdf",
+                            "size": 18422,
+                            "type": "application/pdf",
+                            "downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13/files/f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04"
+                          }
+                        ],
+                        "executedByEmail": "billing@example.com",
+                        "workflow": {
+                          "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                          "name": "Customer Support Agent",
+                          "description": "Routes incoming support tickets and drafts responses",
+                          "folderPath": "/",
+                          "ownerEmail": "jane@example.com",
+                          "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                          "createdAt": "2025-01-10T09:00:00.000Z",
+                          "updatedAt": "2025-06-18T16:45:00.000Z",
+                          "deleted": false
+                        },
+                        "workflowState": {
+                          "blocks": {},
+                          "edges": []
+                        },
+                        "traceSpans": [],
+                        "finalOutput": {
+                          "result": "Hello, world!"
+                        },
+                        "cost": {
+                          "total": 0.0072,
+                          "items": [
+                            {
+                              "category": "fixed",
+                              "description": "Base execution charge",
+                              "cost": 0.005
+                            },
+                            {
+                              "category": "model",
+                              "description": "gpt-5",
+                              "cost": 0.0022,
+                              "inputTokens": 1840,
+                              "outputTokens": 260
+                            }
+                          ]
+                        },
+                        "workflowInput": {
+                          "ticketId": "T-4821"
+                        },
+                        "createdAt": "2026-01-15T10:30:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -447,8 +550,8 @@
     "/api/v2/logs/stats": {
       "get": {
         "operationId": "getLogStats",
-        "summary": "Get Log Statistics",
-        "description": "Get bucketed run counts, success rate, errors, and mean latency for the workspace and individual workflows. Query fields describe window selection and bucketing. Folder filters cover subtrees. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "summary": "Get log statistics",
+        "description": "Get bucketed run counts, success rate, errors, and mean latency for the workspace and individual workflows. Query fields describe window selection and bucketing. Folder filters cover subtrees. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "logs.read_stats",
         "x-oauth-scope": "api:read",
         "tags": ["Logs"],
@@ -559,7 +662,7 @@
             "required": false,
             "description": "Whether buckets with no runs are included in every series. Off by default, so each series carries only the buckets that hold at least one run; set it to publish exactly `segmentCount` buckets per series, empty ones included. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
             "schema": {
-              "default": false,
+              "default": "false",
               "description": "Whether buckets with no runs are included in every series. Off by default, so each series carries only the buckets that hold at least one run; set it to publish exactly `segmentCount` buckets per series, empty ones included. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
               "enum": [
                 "true",
@@ -597,6 +700,49 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2LogStatsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "workflows": [
+                          {
+                            "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                            "workflowName": "Customer Support Agent",
+                            "segments": [
+                              {
+                                "timestamp": "2026-01-15T10:00:00.000Z",
+                                "totalExecutions": 40,
+                                "successfulExecutions": 38,
+                                "avgDurationMs": 1180
+                              }
+                            ],
+                            "totalExecutions": 40,
+                            "totalSuccessful": 38,
+                            "overallSuccessRate": 95
+                          }
+                        ],
+                        "workflowsTruncated": false,
+                        "aggregateSegments": [
+                          {
+                            "timestamp": "2026-01-15T10:00:00.000Z",
+                            "totalExecutions": 40,
+                            "successfulExecutions": 38,
+                            "avgDurationMs": 1180
+                          }
+                        ],
+                        "totalRuns": 40,
+                        "totalErrors": 2,
+                        "avgLatency": 1180,
+                        "timeBounds": {
+                          "start": "2026-01-15T10:00:00.000Z",
+                          "end": "2026-01-15T22:00:00.000Z"
+                        },
+                        "segmentMs": 600000
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -820,7 +966,7 @@
         }
       },
       "ServiceUnavailable": {
-        "description": "A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, because the run may already have started — reconcile against the returned run id instead of retrying.",
+        "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
         "headers": {
           "Retry-After": {
             "$ref": "#/components/headers/Retry-After"
@@ -1342,7 +1488,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -1364,7 +1510,7 @@
                 "endedAt": "2026-01-15T10:30:01.250Z",
                 "totalDurationMs": 1250,
                 "cost": {
-                  "total": 0.0032
+                  "total": 0.0072
                 },
                 "hasHandledErrors": false,
                 "files": [
@@ -1760,7 +1906,15 @@
               "startedAt": "2026-01-15T10:30:00.000Z",
               "endedAt": "2026-01-15T10:30:01.250Z",
               "totalDurationMs": 1250,
-              "files": null,
+              "files": [
+                {
+                  "id": "f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04",
+                  "name": "summary.pdf",
+                  "size": 18422,
+                  "type": "application/pdf",
+                  "downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13/files/f1c3a7d0-4b52-4a8e-9f61-2d7c8b3e5a04"
+                }
+              ],
               "executedByEmail": "billing@example.com",
               "workflow": {
                 "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
@@ -1782,12 +1936,12 @@
                 "result": "Hello, world!"
               },
               "cost": {
-                "total": 0.0032,
+                "total": 0.0072,
                 "items": [
                   {
                     "category": "fixed",
                     "description": "Base execution charge",
-                    "cost": 0.001
+                    "cost": 0.005
                   },
                   {
                     "category": "model",
diff --git a/apps/docs/openapi-v2-resources.json b/apps/docs/openapi-v2-resources.json
index dc8999e8f76..38c516345aa 100644
--- a/apps/docs/openapi-v2-resources.json
+++ b/apps/docs/openapi-v2-resources.json
@@ -1,7 +1,7 @@
 {
   "openapi": "3.1.0",
   "info": {
-    "title": "Sim API v2 — Resources",
+    "title": "Sim API v2 — resources",
     "description": "Version 2 of the Sim REST API for workspace metadata, members, MCP servers, skills, custom tools, sandboxes, credentials, write-only secrets, organization permission groups, and the block, tool, and connector-type catalogs.",
     "version": "2.0.0",
     "contact": {
@@ -35,7 +35,7 @@
     },
     {
       "name": "Meta",
-      "description": "Discover what the calling API credential can reach."
+      "description": "Read API availability and the calling credential’s type and expiry."
     },
     {
       "name": "Workspaces",
@@ -63,11 +63,11 @@
     },
     {
       "name": "Secrets",
-      "description": "Set and manage write-only workspace and personal secret values."
+      "description": "Manage workspace and personal secrets; writes return metadata, and visible workspace values may appear in lists."
     },
     {
       "name": "Catalog",
-      "description": "Discover the blocks, tools, and connector types this workspace can build with."
+      "description": "Inspect workflow blocks, built-in tools, and knowledge-base connector types."
     }
   ],
   "security": [
@@ -82,8 +82,8 @@
     "/api/v2/workspaces": {
       "get": {
         "operationId": "listWorkspaces",
-        "summary": "List Workspaces",
-        "description": "List active workspaces available to the calling credential with opaque cursor pagination. A personal API key or OAuth token sees accessible workspaces that permit user-held API credentials; a workspace API key sees only its bound workspace.\n\nOAuth scope: `api:read`.",
+        "summary": "List workspaces",
+        "description": "List active workspaces available to the calling credential. Personal API keys and OAuth tokens see accessible workspaces that permit user-held API credentials; a workspace API key sees only its bound workspace. Results use cursor pagination.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workspaces.list_public",
         "x-oauth-scope": "api:read",
         "tags": ["Workspaces"],
@@ -92,10 +92,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "createdAt",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -139,7 +139,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Public metadata for workspaces available to the credential.",
+            "description": "Metadata for workspaces available to the credential.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -155,6 +155,25 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListWorkspacesResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                          "name": "Engineering",
+                          "color": "#33C482",
+                          "logoUrl": null,
+                          "memberCount": 14,
+                          "createdAt": "2026-01-15T10:30:00.000Z",
+                          "updatedAt": "2026-06-20T14:02:11.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -186,8 +205,8 @@
     "/api/v2/workspaces/{workspaceId}": {
       "get": {
         "operationId": "getWorkspace",
-        "summary": "Get Workspace",
-        "description": "Get metadata for an accessible workspace.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workspace",
+        "description": "Get metadata for a workspace the calling credential can access. Requires workspace read access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workspaces.read_public_detail",
         "x-oauth-scope": "api:read",
         "tags": ["Workspaces"],
@@ -207,7 +226,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Public workspace metadata.",
+            "description": "Workspace metadata.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -223,6 +242,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetWorkspaceResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                        "name": "Engineering",
+                        "color": "#33C482",
+                        "logoUrl": null,
+                        "memberCount": 14,
+                        "createdAt": "2026-01-15T10:30:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -254,8 +289,8 @@
     "/api/v2/workspaces/{workspaceId}/members": {
       "get": {
         "operationId": "listWorkspaceMembers",
-        "summary": "List Workspace Members",
-        "description": "List workspace members by email, including explicit grants and inherited organization admin access. Each member includes a stable user ID for member administration.\n\nOAuth scope: `api:read`.",
+        "summary": "List workspace members",
+        "description": "List effective workspace members, ordered by email, including explicit grants and inherited organization Admin access. Use each member’s `userId` for member administration. Requires workspace read access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workspaces.members.list_public",
         "x-oauth-scope": "api:read",
         "tags": ["Workspaces"],
@@ -315,6 +350,25 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListWorkspaceMembersResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "userId": "user-123",
+                          "email": "jane@example.com",
+                          "name": "Jane Smith",
+                          "image": null,
+                          "role": "admin",
+                          "isExternal": false,
+                          "joinedAt": "2026-01-15T10:30:00.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -346,8 +400,8 @@
     "/api/v2/mcp-servers": {
       "get": {
         "operationId": "listMcpServers",
-        "summary": "List MCP Servers",
-        "description": "List MCP servers registered in a workspace, excluding request-header values and OAuth secrets. Connection metadata remains at registration defaults until List MCP Server Tools performs discovery.\n\nOAuth scope: `api:read`.",
+        "summary": "List MCP servers",
+        "description": "List external MCP servers registered in the workspace. Request-header values and OAuth secrets are omitted. Connection metadata remains at registration defaults until List MCP server tools performs discovery. Requires workspace read access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "mcp_servers.list",
         "x-oauth-scope": "api:read",
         "tags": ["MCP Servers"],
@@ -380,10 +434,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "createdAt",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -443,6 +497,37 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListMcpServersResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "mcp-3f7a9c21",
+                          "name": "Docs server",
+                          "description": "Internal documentation tools",
+                          "transport": "streamable-http",
+                          "authType": "headers",
+                          "url": "https://mcp.example.com/sse",
+                          "timeout": 30000,
+                          "retries": 3,
+                          "enabled": true,
+                          "connectionStatus": "connected",
+                          "lastError": null,
+                          "toolCount": 7,
+                          "lastToolsRefresh": "2026-06-20T14:02:11.000Z",
+                          "lastConnected": "2026-06-20T14:02:11.000Z",
+                          "createdAt": "2026-06-01T09:14:00.000Z",
+                          "updatedAt": "2026-06-20T14:02:11.000Z",
+                          "hasHeaders": true,
+                          "headerNames": ["Authorization"],
+                          "hasOauthClientSecret": false
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -472,8 +557,8 @@
       },
       "post": {
         "operationId": "createMcpServer",
-        "summary": "Create MCP Server",
-        "description": "Register an external MCP server without connecting to it. A duplicate URL returns `409`; use Update MCP Server to change the existing registration. The server remains disconnected until List MCP Server Tools succeeds.\n\nOAuth scope: `api:write`.",
+        "summary": "Create MCP server",
+        "description": "Register an external MCP server without establishing a tool connection; registration may probe its authentication method. A duplicate URL returns `409`; use Update MCP server to change the registration. It stays disconnected until List MCP server tools succeeds. Requires workspace write access.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "mcp_servers.create",
         "x-oauth-scope": "api:write",
         "tags": ["MCP Servers"],
@@ -484,6 +569,20 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateMcpServerRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "Docs server",
+                    "url": "https://mcp.example.com/sse",
+                    "authType": "headers",
+                    "headers": {
+                      "Authorization": "Bearer YOUR_TOKEN"
+                    }
+                  }
+                }
               }
             }
           }
@@ -506,6 +605,32 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateMcpServerResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "mcp-3f7a9c21",
+                        "name": "Docs server",
+                        "description": "Internal documentation tools",
+                        "transport": "streamable-http",
+                        "authType": "headers",
+                        "url": "https://mcp.example.com/sse",
+                        "timeout": 30000,
+                        "retries": 3,
+                        "enabled": true,
+                        "connectionStatus": "disconnected",
+                        "lastError": null,
+                        "toolCount": 0,
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z",
+                        "hasHeaders": true,
+                        "headerNames": ["Authorization"],
+                        "hasOauthClientSecret": false
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -546,8 +671,8 @@
     "/api/v2/mcp-servers/{mcpServerId}": {
       "get": {
         "operationId": "getMcpServer",
-        "summary": "Get MCP Server",
-        "description": "Get one MCP server by identifier. Request-header values and OAuth client secrets are never returned.\n\nOAuth scope: `api:read`.",
+        "summary": "Get MCP server",
+        "description": "Get a registered external MCP server. Request-header values and OAuth client secrets are omitted. Requires workspace read access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "mcp_servers.read",
         "x-oauth-scope": "api:read",
         "tags": ["MCP Servers"],
@@ -594,6 +719,34 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetMcpServerResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "mcp-3f7a9c21",
+                        "name": "Docs server",
+                        "description": "Internal documentation tools",
+                        "transport": "streamable-http",
+                        "authType": "headers",
+                        "url": "https://mcp.example.com/sse",
+                        "timeout": 30000,
+                        "retries": 3,
+                        "enabled": true,
+                        "connectionStatus": "connected",
+                        "lastError": null,
+                        "toolCount": 7,
+                        "lastToolsRefresh": "2026-06-20T14:02:11.000Z",
+                        "lastConnected": "2026-06-20T14:02:11.000Z",
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z",
+                        "hasHeaders": true,
+                        "headerNames": ["Authorization"],
+                        "hasOauthClientSecret": false
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -623,8 +776,8 @@
       },
       "patch": {
         "operationId": "updateMcpServer",
-        "summary": "Update MCP Server",
-        "description": "Update an MCP server's supplied fields. Omitted fields remain unchanged unless the field specifies otherwise. Authentication changes revoke the stored OAuth grant and reset connection metadata. Use List MCP Server Tools to reconnect.\n\nOAuth scope: `api:write`.",
+        "summary": "Update MCP server",
+        "description": "Update an external MCP server. Omitted fields remain unchanged unless a field specifies otherwise. Authentication changes revoke its stored OAuth grant and reset connection metadata; use List MCP server tools to reconnect. The endpoint URL is immutable. Requires workspace write access.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "mcp_servers.update",
         "x-oauth-scope": "api:write",
         "tags": ["MCP Servers"],
@@ -648,6 +801,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateMcpServerRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "enabled": false
+                  }
+                }
               }
             }
           }
@@ -670,6 +832,34 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateMcpServerResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "mcp-3f7a9c21",
+                        "name": "Docs server",
+                        "description": "Internal documentation tools",
+                        "transport": "streamable-http",
+                        "authType": "headers",
+                        "url": "https://mcp.example.com/sse",
+                        "timeout": 30000,
+                        "retries": 3,
+                        "enabled": false,
+                        "connectionStatus": "connected",
+                        "lastError": null,
+                        "toolCount": 7,
+                        "lastToolsRefresh": "2026-06-20T14:02:11.000Z",
+                        "lastConnected": "2026-06-20T14:02:11.000Z",
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z",
+                        "hasHeaders": true,
+                        "headerNames": ["Authorization"],
+                        "hasOauthClientSecret": false
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -705,8 +895,8 @@
       },
       "delete": {
         "operationId": "deleteMcpServer",
-        "summary": "Delete MCP Server",
-        "description": "Remove an MCP server and revoke its OAuth tokens. Workflows retain blocks that referenced the server's tools, but those tools can no longer be called.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete MCP server",
+        "description": "Remove an external MCP server and revoke its OAuth tokens. Workflow blocks retain references to its tools, but those tools can no longer be called. Requires workspace write access.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "mcp_servers.delete",
         "x-oauth-scope": "api:write",
         "tags": ["MCP Servers"],
@@ -753,6 +943,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeleteMcpServerResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "mcp-3f7a9c21",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -784,8 +985,8 @@
     "/api/v2/mcp-servers/{mcpServerId}/tools": {
       "get": {
         "operationId": "listMcpServerTools",
-        "summary": "List MCP Server Tools",
-        "description": "Discover up to 1,000 tools within 5 MB, connect to the server, and update connection metadata. Results are unpaginated. Invalid OAuth returns `409` with `MCP_SERVER_REAUTHORIZATION_REQUIRED`; reauthorize through the browser. Unavailable servers return `503`. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "List MCP server tools",
+        "description": "Discover tools on an enabled external MCP server and update connection metadata. Discovery is bounded by 1,000 tools, 5 MiB, 50 upstream pages, and 60 seconds; limits or later-page failures can return an unmarked partial inventory. Results are unpaginated and may be cached; `refresh=true` requests fresh discovery. Invalid OAuth returns `409` with `MCP_SERVER_REAUTHORIZATION_REQUIRED`; reauthorize in the browser. Disabled servers and servers requiring a managed Credential Group connection return `409`; unavailable servers return `503`. Requires workspace read access. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "mcp_servers.tools.discover",
         "x-oauth-scope": "api:write",
         "tags": ["MCP Servers"],
@@ -826,7 +1027,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Tools exposed by the MCP server.",
+            "description": "Tools discovered so far. Limits or later-page failures can leave the inventory incomplete; the response has no truncation indicator or pagination.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -842,6 +1043,32 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListMcpServerToolsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "name": "search_docs",
+                          "description": "Search the internal documentation",
+                          "inputSchema": {
+                            "type": "object",
+                            "properties": {
+                              "query": {
+                                "type": "string",
+                                "description": "Search terms"
+                              }
+                            },
+                            "required": ["query"]
+                          },
+                          "serverId": "mcp-3f7a9c21",
+                          "serverName": "Docs server"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -876,8 +1103,8 @@
     "/api/v2/skills": {
       "get": {
         "operationId": "listSkills",
-        "summary": "List Skills",
-        "description": "List workspace and built-in skills with cursor pagination. Built-in skills are read-only. The list omits skill bodies; use Get Skill to read content.\n\nOAuth scope: `api:read`.",
+        "summary": "List skills",
+        "description": "List workspace and built-in skills with cursor pagination. Built-in skills are read-only. Skill bodies are omitted; use Get skill to read content. Requires workspace read access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "skills.list",
         "x-oauth-scope": "api:read",
         "tags": ["Skills"],
@@ -910,10 +1137,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "createdAt",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -973,6 +1200,24 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListSkillsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "V1StGXR8Z5jdHi6BmyT",
+                          "name": "refund-policy",
+                          "description": "How support should handle refund requests",
+                          "readOnly": false,
+                          "createdAt": "2026-06-01T09:14:00.000Z",
+                          "updatedAt": "2026-06-20T14:02:11.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -1002,8 +1247,8 @@
       },
       "post": {
         "operationId": "createSkill",
-        "summary": "Create Skill",
-        "description": "Create one skill in a workspace. Its kebab-case name must be unique and cannot be reserved by a built-in skill. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create skill",
+        "description": "Create a workspace skill with a unique kebab-case name that is not reserved by a built-in skill. Requires workspace write access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "skills.create",
         "x-oauth-scope": "api:write",
         "tags": ["Skills"],
@@ -1014,6 +1259,17 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateSkillRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "refund-policy",
+                    "description": "How support should handle refund requests",
+                    "content": "# Refund policy\n\nAlways check the order date first."
+                  }
+                }
               }
             }
           }
@@ -1036,6 +1292,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateSkillResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "name": "refund-policy",
+                        "description": "How support should handle refund requests",
+                        "readOnly": false,
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z",
+                        "content": "# Refund policy\n\nAlways check the order date first."
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1076,8 +1348,8 @@
     "/api/v2/skills/{skillId}": {
       "get": {
         "operationId": "getSkill",
-        "summary": "Get Skill",
-        "description": "Get one workspace or built-in skill, including its full content. Built-in skills are marked read-only.\n\nOAuth scope: `api:read`.",
+        "summary": "Get skill",
+        "description": "Get a workspace or built-in skill, including its full instructions. Built-in skills are read-only. Requires workspace read access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "skills.read",
         "x-oauth-scope": "api:read",
         "tags": ["Skills"],
@@ -1124,6 +1396,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetSkillResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "name": "refund-policy",
+                        "description": "How support should handle refund requests",
+                        "readOnly": false,
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z",
+                        "content": "# Refund policy\n\nAlways check the order date first."
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1153,8 +1441,8 @@
       },
       "patch": {
         "operationId": "updateSkill",
-        "summary": "Update Skill",
-        "description": "Update a workspace skill. Omitted fields remain unchanged. Built-in skills are read-only. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update skill",
+        "description": "Update a workspace skill. Omitted fields remain unchanged. Requires skill editor or workspace Admin access; workspace write access alone does not grant editor access. Built-in skills cannot be changed. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "skills.update",
         "x-oauth-scope": "api:write",
         "tags": ["Skills"],
@@ -1178,6 +1466,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateSkillRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "description": "Updated refund guidance"
+                  }
+                }
               }
             }
           }
@@ -1200,6 +1497,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateSkillResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "name": "refund-policy",
+                        "description": "Updated refund guidance",
+                        "readOnly": false,
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z",
+                        "content": "# Refund policy\n\nAlways check the order date first."
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1238,8 +1551,8 @@
       },
       "delete": {
         "operationId": "deleteSkill",
-        "summary": "Delete Skill",
-        "description": "Delete a workspace skill. Built-in skills are read-only and cannot be deleted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete skill",
+        "description": "Delete a workspace skill. Requires skill editor or workspace Admin access. Built-in skills cannot be deleted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "skills.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Skills"],
@@ -1286,6 +1599,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeleteSkillResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1317,8 +1641,8 @@
     "/api/v2/skills/{skillId}/editors": {
       "get": {
         "operationId": "listSkillEditors",
-        "summary": "List Skill Editors",
-        "description": "List skill editors and workspace administrators with cursor pagination.\n\nOAuth scope: `api:read`.",
+        "summary": "List skill editors",
+        "description": "List explicit skill editors and workspace Admins with cursor pagination. Built-in skills return an empty list. Requires workspace read access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "skills.editors.list",
         "x-oauth-scope": "api:read",
         "tags": ["Skills"],
@@ -1350,10 +1674,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "email",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["email", "name"]
             }
@@ -1413,6 +1737,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListSkillEditorsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "email": "jane@example.com",
+                          "name": "Jane Smith",
+                          "image": null,
+                          "isWorkspaceAdmin": false
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -1442,8 +1782,8 @@
       },
       "post": {
         "operationId": "grantSkillEditor",
-        "summary": "Grant Skill Editor",
-        "description": "Grant skill editor access to a workspace member by email. Requires an existing editor or workspace admin; admins already have access and cannot receive explicit grants. Existing grants return `200`; new grants return `201`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Grant skill editor",
+        "description": "Grant skill editor access to a current workspace member by email. Requires an existing skill editor or workspace Admin. Workspace Admins already have derived access and cannot receive explicit grants. Existing grants return `200`; new grants return `201`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "skills.editors.grant",
         "x-oauth-scope": "api:write",
         "tags": ["Skills"],
@@ -1467,6 +1807,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/GrantSkillEditorRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "email": "jane@example.com"
+                  }
+                }
               }
             }
           }
@@ -1489,6 +1838,19 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GrantSkillEditorResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "email": "jane@example.com",
+                        "name": "Jane Smith",
+                        "image": null,
+                        "isWorkspaceAdmin": false
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1510,6 +1872,19 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GrantSkillEditorResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "email": "jane@example.com",
+                        "name": "Jane Smith",
+                        "image": null,
+                        "isWorkspaceAdmin": false
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1545,8 +1920,8 @@
       },
       "delete": {
         "operationId": "revokeSkillEditor",
-        "summary": "Revoke Skill Editor",
-        "description": "Revoke an explicit editor grant by email. The caller must already be a skill editor or workspace administrator. Workspace administrators have derived access that cannot be revoked. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Revoke skill editor",
+        "description": "Revoke an explicit skill editor grant by email. Requires an existing skill editor or workspace Admin. Workspace Admins have derived access that cannot be revoked. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "skills.editors.revoke",
         "x-oauth-scope": "api:write",
         "tags": ["Skills"],
@@ -1605,6 +1980,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RevokeSkillEditorResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "email": "jane@example.com",
+                        "revoked": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1636,8 +2022,8 @@
     "/api/v2/custom-tools": {
       "get": {
         "operationId": "listCustomTools",
-        "summary": "List Custom Tools",
-        "description": "List code-backed custom tools in a workspace with cursor pagination.\n\nOAuth scope: `api:read`.",
+        "summary": "List custom tools",
+        "description": "List code-backed custom tools in the workspace with cursor pagination. Each entry includes its declaration and implementation. Requires workspace read access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "custom_tools.list",
         "x-oauth-scope": "api:read",
         "tags": ["Custom Tools"],
@@ -1733,6 +2119,39 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListCustomToolsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "V1StGXR8Z5jdHi6BmyT",
+                          "title": "lookup_order",
+                          "schema": {
+                            "type": "function",
+                            "function": {
+                              "name": "lookup_order",
+                              "description": "Look up an order by id",
+                              "parameters": {
+                                "type": "object",
+                                "properties": {
+                                  "orderId": {
+                                    "type": "string"
+                                  }
+                                },
+                                "required": ["orderId"]
+                              }
+                            }
+                          },
+                          "code": "return { ok: true }",
+                          "createdAt": "2026-06-01T09:14:00.000Z",
+                          "updatedAt": "2026-06-20T14:02:11.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -1762,8 +2181,8 @@
       },
       "post": {
         "operationId": "createCustomTool",
-        "summary": "Create Custom Tool",
-        "description": "Create a code-backed custom tool in a workspace. Its title must be unique because tools resolve by title at call time.\n\nOAuth scope: `api:write`.",
+        "summary": "Create custom tool",
+        "description": "Create a code-backed custom tool. Its title must be unique within the workspace because tools resolve by title at call time. Requires workspace write access.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "custom_tools.create",
         "x-oauth-scope": "api:write",
         "tags": ["Custom Tools"],
@@ -1774,6 +2193,32 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateCustomToolRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "title": "lookup_order",
+                    "schema": {
+                      "type": "function",
+                      "function": {
+                        "name": "lookup_order",
+                        "description": "Look up an order by id",
+                        "parameters": {
+                          "type": "object",
+                          "properties": {
+                            "orderId": {
+                              "type": "string"
+                            }
+                          },
+                          "required": ["orderId"]
+                        }
+                      }
+                    },
+                    "code": "return { ok: true }"
+                  }
+                }
               }
             }
           }
@@ -1796,6 +2241,36 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateCustomToolResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "title": "lookup_order",
+                        "schema": {
+                          "type": "function",
+                          "function": {
+                            "name": "lookup_order",
+                            "description": "Look up an order by id",
+                            "parameters": {
+                              "type": "object",
+                              "properties": {
+                                "orderId": {
+                                  "type": "string"
+                                }
+                              },
+                              "required": ["orderId"]
+                            }
+                          }
+                        },
+                        "code": "return { ok: true }",
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1836,8 +2311,8 @@
     "/api/v2/custom-tools/{customToolId}": {
       "get": {
         "operationId": "getCustomTool",
-        "summary": "Get Custom Tool",
-        "description": "Get one custom tool by identifier, scoped to its workspace.\n\nOAuth scope: `api:read`.",
+        "summary": "Get custom tool",
+        "description": "Get a custom tool’s declaration and code by identifier, scoped to its workspace. Requires workspace read access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "custom_tools.read",
         "x-oauth-scope": "api:read",
         "tags": ["Custom Tools"],
@@ -1884,6 +2359,36 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetCustomToolResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "title": "lookup_order",
+                        "schema": {
+                          "type": "function",
+                          "function": {
+                            "name": "lookup_order",
+                            "description": "Look up an order by id",
+                            "parameters": {
+                              "type": "object",
+                              "properties": {
+                                "orderId": {
+                                  "type": "string"
+                                }
+                              },
+                              "required": ["orderId"]
+                            }
+                          }
+                        },
+                        "code": "return { ok: true }",
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1913,8 +2418,8 @@
       },
       "patch": {
         "operationId": "updateCustomTool",
-        "summary": "Update Custom Tool",
-        "description": "Update a custom tool. Omitted fields remain unchanged; titles must remain unique within the workspace.\n\nOAuth scope: `api:write`.",
+        "summary": "Update custom tool",
+        "description": "Update a custom tool. Omitted fields remain unchanged; supplied schemas and code replace the stored versions. Titles must remain unique within the workspace. Requires workspace write access.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "custom_tools.update",
         "x-oauth-scope": "api:write",
         "tags": ["Custom Tools"],
@@ -1938,6 +2443,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateCustomToolRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "code": "return { ok: false }"
+                  }
+                }
               }
             }
           }
@@ -1960,6 +2474,36 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateCustomToolResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "title": "lookup_order",
+                        "schema": {
+                          "type": "function",
+                          "function": {
+                            "name": "lookup_order",
+                            "description": "Look up an order by id",
+                            "parameters": {
+                              "type": "object",
+                              "properties": {
+                                "orderId": {
+                                  "type": "string"
+                                }
+                              },
+                              "required": ["orderId"]
+                            }
+                          }
+                        },
+                        "code": "return { ok: false }",
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1998,8 +2542,8 @@
       },
       "delete": {
         "operationId": "deleteCustomTool",
-        "summary": "Delete Custom Tool",
-        "description": "Delete a custom tool. Agent blocks retain their configuration but can no longer call the deleted tool.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete custom tool",
+        "description": "Delete a custom tool. Agent blocks retain their configuration but can no longer call the deleted tool. Requires workspace write access.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "custom_tools.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Custom Tools"],
@@ -2046,6 +2590,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeleteCustomToolResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2077,8 +2632,8 @@
     "/api/v2/sandboxes": {
       "get": {
         "operationId": "listSandboxes",
-        "summary": "List Sandboxes",
-        "description": "List reusable dependency environments for Function blocks, including language packages, managed CLIs, and system packages. Sandboxes remain visible after a plan downgrade.\n\nOAuth scope: `api:read`.",
+        "summary": "List sandboxes",
+        "description": "List reusable dependency environments for Function blocks, including language packages, managed CLIs, and system packages. Requires workspace read access. Existing sandboxes remain visible after a plan downgrade.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "sandboxes.list",
         "x-oauth-scope": "api:read",
         "tags": ["Sandboxes"],
@@ -2111,10 +2666,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "name",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -2174,6 +2729,31 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListSandboxesResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "V1StGXR8Z5jdHi6BmyT",
+                          "name": "data-tools",
+                          "language": "python",
+                          "dependencies": ["pandas==2.2.2", "requests"],
+                          "cliTools": [],
+                          "systemPackages": ["graphviz"],
+                          "buildStatus": "ready",
+                          "errorCode": null,
+                          "errorMessage": null,
+                          "errorDetail": null,
+                          "builtAt": "2026-06-20T14:05:40.000Z",
+                          "createdAt": "2026-06-01T09:14:00.000Z",
+                          "updatedAt": "2026-06-20T14:02:11.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -2203,8 +2783,8 @@
       },
       "post": {
         "operationId": "createSandbox",
-        "summary": "Create Sandbox",
-        "description": "Create a uniquely named dependency environment. If a build is needed, track readiness with `buildStatus`; null means no build is required. Invalid dependencies return `400` with field details. Requires workspace admin access on Max or Enterprise. Creates and updates share a rate limit; respect `Retry-After`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create sandbox",
+        "description": "Create a uniquely named dependency environment. Requires workspace Admin access and a configured remote Function runtime. With billing enabled, Max or Enterprise is required unless deployment entitlement overrides it; billing-disabled deployments require sandbox entitlement. Poll Get sandbox for `buildStatus`; `null` means no image build is needed. Invalid dependencies return `400` with field details. Creates and updates share a rate limit; respect `Retry-After`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "sandboxes.create",
         "x-oauth-scope": "api:write",
         "tags": ["Sandboxes"],
@@ -2215,6 +2795,18 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateSandboxRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "data-tools",
+                    "language": "python",
+                    "dependencies": ["pandas==2.2.2", "requests"],
+                    "systemPackages": ["graphviz"]
+                  }
+                }
               }
             }
           }
@@ -2237,6 +2829,28 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateSandboxResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "name": "data-tools",
+                        "language": "python",
+                        "dependencies": ["pandas==2.2.2", "requests"],
+                        "cliTools": [],
+                        "systemPackages": ["graphviz"],
+                        "buildStatus": "pending",
+                        "errorCode": null,
+                        "errorMessage": null,
+                        "errorDetail": null,
+                        "builtAt": null,
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2277,8 +2891,8 @@
     "/api/v2/sandboxes/{sandboxId}": {
       "get": {
         "operationId": "getSandbox",
-        "summary": "Get Sandbox",
-        "description": "Get one sandbox by identifier, scoped to its workspace, including its current build state and any build failure.\n\nOAuth scope: `api:read`.",
+        "summary": "Get sandbox",
+        "description": "Get a sandbox’s dependency configuration, current build state, and any build failure. Requires workspace read access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "sandboxes.read",
         "x-oauth-scope": "api:read",
         "tags": ["Sandboxes"],
@@ -2325,6 +2939,28 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetSandboxResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "name": "data-tools",
+                        "language": "python",
+                        "dependencies": ["pandas==2.2.2", "requests"],
+                        "cliTools": [],
+                        "systemPackages": ["graphviz"],
+                        "buildStatus": "ready",
+                        "errorCode": null,
+                        "errorMessage": null,
+                        "errorDetail": null,
+                        "builtAt": "2026-06-20T14:05:40.000Z",
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2354,8 +2990,8 @@
       },
       "patch": {
         "operationId": "updateSandbox",
-        "summary": "Update Sandbox",
-        "description": "Update a sandbox, preserving omitted fields and replacing supplied lists. Dependency changes may start a build; resending a failed specification retries its build. `buildStatus: null` means no build is required. Requires workspace admin access on Max or Enterprise. Creates and updates share a rate limit; respect `Retry-After`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update sandbox",
+        "description": "Update a sandbox; omitted fields stay unchanged and supplied lists replace their contents. Dependency changes may start a build; resending a failed specification retries it. `buildStatus: null` means no image build is needed. Requires workspace Admin access and a configured remote Function runtime. With billing enabled, Max or Enterprise is required unless deployment entitlement overrides it; billing-disabled deployments require sandbox entitlement. Creates and updates share a rate limit; respect `Retry-After`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "sandboxes.update",
         "x-oauth-scope": "api:write",
         "tags": ["Sandboxes"],
@@ -2379,6 +3015,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateSandboxRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "dependencies": ["pandas==2.2.2", "requests", "pyarrow"]
+                  }
+                }
               }
             }
           }
@@ -2401,6 +3046,28 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateSandboxResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "name": "data-tools",
+                        "language": "python",
+                        "dependencies": ["pandas==2.2.2", "requests", "pyarrow"],
+                        "cliTools": [],
+                        "systemPackages": ["graphviz"],
+                        "buildStatus": "pending",
+                        "errorCode": null,
+                        "errorMessage": null,
+                        "errorDetail": null,
+                        "builtAt": null,
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2439,8 +3106,8 @@
       },
       "delete": {
         "operationId": "deleteSandbox",
-        "summary": "Delete Sandbox",
-        "description": "Delete a sandbox. Function blocks using it fail until reconfigured. Requires workspace admin access on Max or Enterprise. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete sandbox",
+        "description": "Delete a sandbox. Function blocks using it fail until reconfigured. Requires workspace Admin access and sandbox entitlement: with billing enabled, Max or Enterprise is required unless deployment entitlement overrides it; billing-disabled deployments require sandbox entitlement. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "sandboxes.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Sandboxes"],
@@ -2487,6 +3154,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeleteSandboxResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "V1StGXR8Z5jdHi6BmyT",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2518,8 +3196,8 @@
     "/api/v2/credentials": {
       "get": {
         "operationId": "listCredentials",
-        "summary": "List Credentials",
-        "description": "List OAuth and service-account connections visible to the caller. Secret material is never returned.\n\nOAuth scope: `api:read`.",
+        "summary": "List credentials",
+        "description": "List OAuth and service-account connections visible to the caller. Requires workspace read access. Stored tokens, keys, and service-account payloads are omitted.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "credentials.connections.list",
         "x-oauth-scope": "api:read",
         "tags": ["Credentials"],
@@ -2637,6 +3315,28 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListCredentialsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+                          "type": "service_account",
+                          "displayName": "Zoom service account",
+                          "description": null,
+                          "providerId": "zoom-service-account",
+                          "accountId": null,
+                          "hasServiceAccountKey": true,
+                          "role": "admin",
+                          "createdAt": "2026-06-01T09:14:00.000Z",
+                          "updatedAt": "2026-06-20T14:02:11.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -2666,8 +3366,8 @@
       },
       "post": {
         "operationId": "createServiceAccountCredential",
-        "summary": "Create Service-Account Credential",
-        "description": "Verify and store a service-account credential using the fields from List Credential Providers, encoded as a JSON object string in `credentials`. Secrets are never returned. A matching source returns the existing credential with `200`; creation returns `201`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create service-account credential",
+        "description": "Verify and store a service-account credential. Use the fields from List credential providers, encoded as a JSON object string in `credentials`. Requires workspace write access. A matching source returns the existing credential with `200`; creation returns `201`. Stored secrets are omitted from the response. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "credentials.service_accounts.create",
         "x-oauth-scope": "api:write",
         "tags": ["Credentials"],
@@ -2678,6 +3378,18 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateServiceAccountCredentialRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "type": "service_account",
+                    "providerId": "zoom-service-account",
+                    "displayName": "Zoom automation",
+                    "credentials": "{\"clientId\":\"YOUR_CLIENT_ID\",\"clientSecret\":\"YOUR_CLIENT_SECRET\",\"orgId\":\"YOUR_ACCOUNT_ID\"}"
+                  }
+                }
               }
             }
           }
@@ -2700,6 +3412,25 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateServiceAccountCredentialResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+                        "type": "service_account",
+                        "displayName": "Zoom service account",
+                        "description": null,
+                        "providerId": "zoom-service-account",
+                        "accountId": null,
+                        "hasServiceAccountKey": true,
+                        "role": "admin",
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2721,6 +3452,25 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateServiceAccountCredentialResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+                        "type": "service_account",
+                        "displayName": "Zoom service account",
+                        "description": null,
+                        "providerId": "zoom-service-account",
+                        "accountId": null,
+                        "hasServiceAccountKey": true,
+                        "role": "admin",
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2761,8 +3511,8 @@
     "/api/v2/credentials/providers": {
       "get": {
         "operationId": "listCredentialProviders",
-        "summary": "List Credential Providers",
-        "description": "List OAuth and service-account connection methods and their availability. OAuth options provide provider IDs for browser connections; service-account methods declare required fields and write-only secrets. Supports provider-name search. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
+        "summary": "List credential providers",
+        "description": "List OAuth and service-account connection methods and their availability. OAuth options provide provider IDs for browser connections; service-account methods declare required fields and write-only secrets. Supports provider-name search. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "credentials.providers.list",
         "x-oauth-scope": "api:read",
         "tags": ["Credentials"],
@@ -2810,6 +3560,73 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListCredentialProvidersResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "type": "oauth",
+                          "serviceId": "salesforce",
+                          "name": "Salesforce",
+                          "description": "Connect to Salesforce CRM data and operations.",
+                          "providerFamily": "salesforce",
+                          "available": true,
+                          "supportsReconnect": true,
+                          "fields": [],
+                          "authorizationOptions": [
+                            {
+                              "providerId": "salesforce",
+                              "label": "Production"
+                            },
+                            {
+                              "providerId": "salesforce-sandbox",
+                              "label": "Sandbox"
+                            }
+                          ]
+                        },
+                        {
+                          "type": "service_account",
+                          "serviceId": "zoom-service-account",
+                          "providerId": "zoom-service-account",
+                          "name": "Zoom server-to-server app",
+                          "description": "Connect Zoom with a server-to-server app.",
+                          "providerFamily": "zoom",
+                          "available": true,
+                          "docsUrl": "https://docs.sim.ai/integrations/zoom-service-account",
+                          "requiresClientGeneratedCredentialId": false,
+                          "fields": [
+                            {
+                              "id": "clientId",
+                              "label": "Client ID",
+                              "placeholder": "Paste the client ID",
+                              "required": true,
+                              "secret": false,
+                              "multiline": false
+                            },
+                            {
+                              "id": "clientSecret",
+                              "label": "Client secret",
+                              "placeholder": "Paste the client secret",
+                              "required": true,
+                              "secret": true,
+                              "multiline": false
+                            },
+                            {
+                              "id": "orgId",
+                              "label": "Account ID",
+                              "placeholder": "Paste the account ID",
+                              "required": true,
+                              "secret": false,
+                              "multiline": false
+                            }
+                          ]
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -2841,18 +3658,49 @@
     "/api/v2/credentials/connections": {
       "post": {
         "operationId": "createCredentialConnection",
-        "summary": "Create Credential Connection",
-        "description": "Create a short-lived browser URL for connecting an OAuth provider or reconnecting an existing OAuth credential. Open the URL, sign in as the authenticated user, complete provider authorization, then refresh the credentials list. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create credential connection",
+        "description": "Create a short-lived browser URL to connect an OAuth provider or reconnect a credential. Requires workspace write access; reconnecting also requires credential Admin access. Open the URL, sign in as the acting user, complete provider authorization, then refresh List credentials. QuickBooks requires caller-managed `oauthClientConfig` for either flow. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "credentials.connections.create",
         "x-oauth-scope": "api:write",
         "tags": ["Credentials"],
         "requestBody": {
           "required": true,
-          "description": "For a new connection, provide providerId and displayName. For a reconnect, provide only credentialId; the existing display name is preserved.",
+          "description": "Provide workspaceId for every flow. For a new connection, send providerId and displayName; for a reconnect, send credentialId and retain the existing name. QuickBooks also requires oauthClientConfig for either flow; omit it for other providers.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateCredentialConnectionBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "providerId": "slack",
+                    "displayName": "Support Slack"
+                  }
+                },
+                "example2": {
+                  "summary": "Request example 2",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "credentialId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
+                  }
+                },
+                "example3": {
+                  "summary": "Request example 3",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "providerId": "quickbooks",
+                    "displayName": "Accounting",
+                    "oauthClientConfig": {
+                      "clientId": "YOUR_INTUIT_CLIENT_ID",
+                      "clientSecret": "YOUR_INTUIT_CLIENT_SECRET",
+                      "environment": "sandbox",
+                      "webhookVerifierToken": "YOUR_WEBHOOK_VERIFIER_TOKEN"
+                    }
+                  }
+                }
               }
             }
           }
@@ -2875,6 +3723,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateCredentialConnectionResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize?draftId=draft-123",
+                        "expiresAt": "2026-06-20T14:17:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2915,8 +3774,8 @@
     "/api/v2/credentials/{credentialId}": {
       "delete": {
         "operationId": "deleteCredential",
-        "summary": "Disconnect Credential",
-        "description": "Disconnect an OAuth or service-account credential and clear its stored workflow, deployment, paused-run, knowledge-connector, and webhook references. Credential admin access is required. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Disconnect credential",
+        "description": "Disconnect an OAuth or service-account credential and clear its stored workflow, deployment, paused-run, knowledge-connector, and webhook references. Requires credential Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "credentials.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Credentials"],
@@ -2964,6 +3823,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeleteCredentialResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2993,8 +3863,8 @@
       },
       "patch": {
         "operationId": "updateCredential",
-        "summary": "Update Credential",
-        "description": "Rename a service-account credential or rotate its secret fields, preserving omitted values and the credential ID. Requires credential admin access. Provider rejection preserves the old secret and returns `400` with `providerErrorCode`; outages return `503`. Fields for a different credential type return `400`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update credential",
+        "description": "Rename an OAuth or service-account credential, change its description, or rotate a service-account secret. Omitted metadata remains unchanged. Rotation requires the provider’s required secret fields to be resubmitted; it replaces the verified secret while retaining the credential ID. Requires credential Admin access. Provider rejection keeps the old secret and returns `400` with `providerErrorCode`; outages return `503`. Secret fields sent for an OAuth credential return `400`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "credentials.update",
         "x-oauth-scope": "api:write",
         "tags": ["Credentials"],
@@ -3026,11 +3896,27 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Replacement display metadata and the write-only fields declared by provider discovery.",
+          "description": "Metadata fields to change, or the complete required fields for a service-account secret rotation. Use List credential providers for the selected provider’s fields.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateCredentialRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "displayName": "Billing automation"
+                  }
+                },
+                "example2": {
+                  "summary": "Request example 2",
+                  "value": {
+                    "clientId": "YOUR_CLIENT_ID",
+                    "clientSecret": "YOUR_ROTATED_CLIENT_SECRET",
+                    "orgId": "YOUR_ACCOUNT_ID"
+                  }
+                }
               }
             }
           }
@@ -3053,6 +3939,25 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateCredentialResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+                        "type": "service_account",
+                        "displayName": "Zoom service account",
+                        "description": null,
+                        "providerId": "zoom-service-account",
+                        "accountId": null,
+                        "hasServiceAccountKey": true,
+                        "role": "admin",
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3093,8 +3998,8 @@
     "/api/v2/secrets": {
       "get": {
         "operationId": "listSecrets",
-        "summary": "List Secrets",
-        "description": "List workspace and caller-owned personal secrets with cursor pagination. Only workspace secrets marked `unredacted` include values; all other entries contain metadata only. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List secrets",
+        "description": "List workspace secrets visible to the caller and caller-owned personal secrets. Only workspace secrets marked `unredacted` can include values; every other entry contains metadata only. Requires workspace read access. Personal secrets belong to the caller across workspaces. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "secrets.list",
         "x-oauth-scope": "api:read",
         "tags": ["Secrets"],
@@ -3138,10 +4043,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "name",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -3201,6 +4106,35 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListSecretsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "name": "STRIPE_API_KEY",
+                          "scope": "workspace",
+                          "description": "Production billing key — rotate quarterly.",
+                          "unredacted": false,
+                          "role": "admin",
+                          "createdAt": "2026-06-01T09:14:00.000Z",
+                          "updatedAt": "2026-06-20T14:02:11.000Z"
+                        },
+                        {
+                          "name": "STAGING_BASE_URL",
+                          "scope": "workspace",
+                          "description": "Staging environment base URL.",
+                          "unredacted": true,
+                          "role": "member",
+                          "createdAt": "2026-06-03T11:30:00.000Z",
+                          "updatedAt": "2026-06-21T08:45:09.000Z",
+                          "value": "https://staging.example.com"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -3232,8 +4166,8 @@
     "/api/v2/secrets/{name}": {
       "put": {
         "operationId": "setSecret",
-        "summary": "Set Secret",
-        "description": "Create or replace a workspace or personal secret without returning its value. For existing workspace secrets, omit `value` to update metadata only; this returns `404` if absent. Personal secrets always require `value`. List Secrets can reveal workspace values marked `unredacted`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Set secret",
+        "description": "Create or replace a workspace or caller-owned personal secret. New workspace secrets require workspace write access; existing ones require workspace Admin or secret Admin access. Omit `value` to update an existing workspace secret’s metadata; a missing secret returns `404`. Personal secrets always require `value`. This operation returns metadata only; List secrets can reveal permitted workspace values marked `unredacted`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "secrets.set",
         "x-oauth-scope": "api:write",
         "tags": ["Secrets"],
@@ -3259,6 +4193,24 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/SetSecretRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "scope": "workspace",
+                    "value": "YOUR_SECRET_VALUE"
+                  }
+                },
+                "example2": {
+                  "summary": "Request example 2",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "scope": "workspace",
+                    "unredacted": false
+                  }
+                }
               }
             }
           }
@@ -3281,6 +4233,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/SetSecretResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "name": "STRIPE_API_KEY",
+                        "scope": "workspace",
+                        "description": "Production billing key — rotate quarterly.",
+                        "unredacted": false,
+                        "role": "admin",
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3302,6 +4270,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/SetSecretResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "name": "STRIPE_API_KEY",
+                        "scope": "workspace",
+                        "description": "Production billing key — rotate quarterly.",
+                        "unredacted": false,
+                        "role": "admin",
+                        "createdAt": "2026-06-01T09:14:00.000Z",
+                        "updatedAt": "2026-06-20T14:02:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3337,8 +4321,8 @@
       },
       "delete": {
         "operationId": "deleteSecret",
-        "summary": "Delete Secret",
-        "description": "Delete a workspace or caller-owned personal secret without reading or returning its stored value. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete secret",
+        "description": "Delete a workspace or caller-owned personal secret without returning its value. Workspace secrets require workspace Admin or secret Admin access. Deleting a personal secret removes it for the caller across all workspaces. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "secrets.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Secrets"],
@@ -3398,6 +4382,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeleteSecretResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "name": "STRIPE_API_KEY",
+                        "scope": "workspace",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3429,8 +4425,8 @@
     "/api/v2/meta": {
       "get": {
         "operationId": "getApiMeta",
-        "summary": "Get API Capabilities",
-        "description": "Get whether v2 is available, what kind of API credential is calling, and when it expires. Requires a valid API key or OAuth access token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get API status",
+        "description": "Get the calling credential’s type and expiry. Requires a valid API key or OAuth access token. `v2Enabled` is true whenever this endpoint is served; the response does not enumerate resource permissions.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "meta.capabilities.read",
         "x-oauth-scope": "api:read",
         "tags": ["Meta"],
@@ -3452,6 +4448,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetApiMetaResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "v2Enabled": true,
+                        "keyType": "personal",
+                        "expiresAt": null
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3477,8 +4485,8 @@
     "/api/v2/workflow-mcp-servers": {
       "get": {
         "operationId": "listWorkflowMcpServers",
-        "summary": "List Workflow MCP Servers",
-        "description": "List MCP servers that expose deployed workflows to external clients. Use List MCP Servers for external servers Sim calls. Tool names share a 2,000-name page limit; inspect `toolNamesTruncated` and use List Workflow MCP Tools for a server's inventory. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List workflow MCP servers",
+        "description": "List MCP servers that expose deployed workflows to external clients. Use List MCP servers for external servers Sim calls. Requires workspace read access. Tool names share a 2,000-name page limit; when `toolNamesTruncated` is true, `toolCount` and `toolNames` may be incomplete. Use List workflow MCP tools for a server’s bounded inventory. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "mcp_servers.workflow_deployments.list",
         "x-oauth-scope": "api:read",
         "tags": ["MCP Servers"],
@@ -3487,22 +4495,22 @@
             "name": "workspaceId",
             "in": "query",
             "required": true,
-            "description": "Workspace whose published MCP servers to list.",
+            "description": "Workspace whose workflow MCP servers to list.",
             "schema": {
               "type": "string",
               "minLength": 1,
               "maxLength": 128,
-              "description": "Workspace whose published MCP servers to list."
+              "description": "Workspace whose workflow MCP servers to list."
             }
           },
           {
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "createdAt",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -3546,7 +4554,7 @@
         ],
         "responses": {
           "200": {
-            "description": "A page of published MCP servers.",
+            "description": "A page of workflow MCP servers.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -3562,6 +4570,28 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListWorkflowMcpServersResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                          "name": "Support agents",
+                          "description": "Ticket triage and escalation workflows.",
+                          "isPublic": false,
+                          "mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                          "createdAt": "2026-06-12T10:30:00.000Z",
+                          "updatedAt": "2026-06-12T10:30:00.000Z",
+                          "toolCount": 1,
+                          "toolNames": ["triage_ticket"]
+                        }
+                      ],
+                      "nextCursor": null,
+                      "toolNamesTruncated": false
+                    }
+                  }
                 }
               }
             }
@@ -3591,25 +4621,35 @@
       },
       "post": {
         "operationId": "createWorkflowMcpServer",
-        "summary": "Create Workflow MCP Server",
-        "description": "Create an MCP server that exposes deployed workflows as tools. Every supplied workflow must already be deployed. With `isPublic: true`, anyone with the server URL can execute its workflows without a Sim API key. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create workflow MCP server",
+        "description": "Create an MCP server exposing deployed workflows as tools. Every supplied workflow must already be deployed. With `isPublic: true`, anyone holding the server URL can execute its workflows without a Sim API key. Requires workspace Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "mcp_servers.workflow_deployments.create_server",
         "x-oauth-scope": "api:write",
         "tags": ["MCP Servers"],
         "requestBody": {
           "required": true,
-          "description": "A new workspace-published MCP server and the workflows it exposes.",
+          "description": "A new workflow MCP server and deployed workflows to expose as tools.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateWorkflowMcpServerRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+                    "name": "Support agents",
+                    "workflowIds": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"]
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "201": {
-            "description": "The published MCP server.",
+            "description": "The workflow MCP server.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -3625,6 +4665,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateWorkflowMcpServerResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "name": "Support agents",
+                        "description": "Ticket triage and escalation workflows.",
+                        "isPublic": false,
+                        "mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "createdAt": "2026-06-12T10:30:00.000Z",
+                        "updatedAt": "2026-06-12T10:30:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3665,8 +4721,8 @@
     "/api/v2/workflow-mcp-servers/{serverId}": {
       "get": {
         "operationId": "getWorkflowMcpServer",
-        "summary": "Get Workflow MCP Server",
-        "description": "Get a published workflow MCP server's metadata and client endpoint. Use List Workflow MCP Tools for its tool inventory. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workflow MCP server",
+        "description": "Get a workflow MCP server’s metadata and client endpoint. Use List workflow MCP tools for its inventory. Requires workspace read access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "mcp_servers.workflow_deployments.read_server",
         "x-oauth-scope": "api:read",
         "tags": ["MCP Servers"],
@@ -3701,6 +4757,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetWorkflowMcpServerResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "name": "Support agents",
+                        "description": "Ticket triage and escalation workflows.",
+                        "isPublic": false,
+                        "mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "createdAt": "2026-06-12T10:30:00.000Z",
+                        "updatedAt": "2026-06-12T10:30:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3730,8 +4802,8 @@
       },
       "patch": {
         "operationId": "updateWorkflowMcpServer",
-        "summary": "Update Workflow MCP Server",
-        "description": "Update a workflow MCP server's name, description, or public access. Omitted fields remain unchanged; `description: null` clears the description. Publish or unpublish tools separately. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update workflow MCP server",
+        "description": "Update a workflow MCP server’s name, description, or public access. Omitted fields stay unchanged; `description: null` clears the description. With `isPublic: true`, anyone holding its URL can execute its tools without a Sim API key. Deploy or undeploy tools separately. Requires workspace Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "mcp_servers.workflow_deployments.update_server",
         "x-oauth-scope": "api:write",
         "tags": ["MCP Servers"],
@@ -3750,11 +4822,19 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Merge-patch body for a published MCP server.",
+          "description": "Server fields to change. Omitted fields remain unchanged; `description: null` clears the description.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateWorkflowMcpServerRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "isPublic": true
+                  }
+                }
               }
             }
           }
@@ -3777,6 +4857,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateWorkflowMcpServerResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "name": "Support agents",
+                        "description": "Ticket triage and escalation workflows.",
+                        "isPublic": true,
+                        "mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "createdAt": "2026-06-12T10:30:00.000Z",
+                        "updatedAt": "2026-06-12T10:30:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3815,8 +4911,8 @@
       },
       "delete": {
         "operationId": "deleteWorkflowMcpServer",
-        "summary": "Delete Workflow MCP Server",
-        "description": "Delete a workflow MCP server and stop serving its tools. The underlying workflows remain deployed and executable through the workflow API. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete workflow MCP server",
+        "description": "Delete a workflow MCP server and stop serving its tools. Its workflows remain deployed and executable through the workflow API. Requires workspace Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "mcp_servers.workflow_deployments.delete_server",
         "x-oauth-scope": "api:write",
         "tags": ["MCP Servers"],
@@ -3835,7 +4931,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The MCP server was unpublished.",
+            "description": "The workflow MCP server was deleted.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -3851,6 +4947,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeleteWorkflowMcpServerResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3885,8 +4992,8 @@
     "/api/v2/workflow-mcp-servers/{serverId}/tools": {
       "get": {
         "operationId": "listWorkflowMcpTools",
-        "summary": "List Workflow MCP Tools",
-        "description": "List published tools ordered by name, including the `workflowId` used to delete each registration. Undeploying a workflow makes its registrations `inactive`; redeploying reactivates them. Results are capped at 2,000 tools: `nextCursor` is always null, and `truncated` marks an incomplete inventory that cannot be paginated. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List workflow MCP tools",
+        "description": "List tool registrations ordered by name, including the `workflowId` used to remove each registration. Undeploying a workflow makes its registrations `inactive`; redeploying reactivates them. Results are capped at 2,000 tools: `nextCursor` is always null, and `truncated` marks an incomplete inventory that cannot be paginated. Requires workspace read access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "mcp_servers.workflow_deployments.list_tools",
         "x-oauth-scope": "api:read",
         "tags": ["MCP Servers"],
@@ -3905,7 +5012,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The tools this server publishes.",
+            "description": "Tool registrations on this server, including inactive registrations.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -3921,6 +5028,29 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListWorkflowMcpToolsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "wfmcptool_01J8ZK3QW4M6X2R9T7B5C0V3",
+                          "serverId": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                          "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                          "toolName": "triage_ticket",
+                          "toolDescription": "Execute Ticket triage workflow",
+                          "mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                          "apiEndpoint": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute",
+                          "createdAt": "2026-06-12T10:30:00.000Z",
+                          "updatedAt": "2026-06-12T10:30:00.000Z",
+                          "status": "active"
+                        }
+                      ],
+                      "nextCursor": null,
+                      "truncated": false
+                    }
+                  }
                 }
               }
             }
@@ -3950,8 +5080,8 @@
       },
       "post": {
         "operationId": "deployWorkflowMcpTool",
-        "summary": "Publish Workflow As MCP Tool",
-        "description": "Publish a deployed workflow as an MCP tool using its deployed input schema. Each server has at most one tool per workflow; repeating the call replaces that tool and returns `200` with `updated: true`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Deploy workflow as MCP tool",
+        "description": "Deploy a workflow as an MCP tool using its deployed input schema. The workflow must already be deployed. Each server has at most one tool per workflow; repeating the call replaces the tool and returns `200` with `updated: true`. Requires workspace Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "mcp_servers.workflow_deployments.deploy_tool",
         "x-oauth-scope": "api:write",
         "tags": ["MCP Servers"],
@@ -3970,18 +5100,27 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "The workflow to publish and the tool metadata MCP clients see.",
+          "description": "The deployed workflow and tool metadata presented to MCP clients.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/DeployWorkflowMcpToolRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                    "toolName": "triage_ticket"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "The published tool.",
+            "description": "The deployed MCP tool registration.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -3997,6 +5136,25 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeployWorkflowMcpToolResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "wfmcptool_01J8ZK3QW4M6X2R9T7B5C0V3",
+                        "serverId": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "toolName": "triage_ticket",
+                        "toolDescription": "Execute Ticket triage workflow",
+                        "mcpServerUrl": "https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "apiEndpoint": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute",
+                        "updated": false,
+                        "createdAt": "2026-06-12T10:30:00.000Z",
+                        "updatedAt": "2026-06-12T10:30:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -4037,8 +5195,8 @@
     "/api/v2/workflow-mcp-servers/{serverId}/tools/{workflowId}": {
       "delete": {
         "operationId": "undeployWorkflowMcpTool",
-        "summary": "Unpublish Workflow MCP Tool",
-        "description": "Unpublish an MCP tool by its workflow ID. The workflow's API deployment remains active. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Undeploy workflow MCP tool",
+        "description": "Remove an MCP tool registration by its workflow ID. The workflow’s API deployment remains active. Requires workspace Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "mcp_servers.workflow_deployments.undeploy_tool",
         "x-oauth-scope": "api:write",
         "tags": ["MCP Servers"],
@@ -4058,11 +5216,11 @@
             "name": "workflowId",
             "in": "path",
             "required": true,
-            "description": "Workflow published as a tool on this server.",
+            "description": "Workflow registered as an MCP tool on this server.",
             "schema": {
               "type": "string",
               "minLength": 1,
-              "description": "Workflow published as a tool on this server."
+              "description": "Workflow registered as an MCP tool on this server."
             }
           }
         ],
@@ -4084,6 +5242,19 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UndeployWorkflowMcpToolResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "wfmcptool_01J8ZK3QW4M6X2R9T7B5C0V3",
+                        "serverId": "wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -4118,8 +5289,8 @@
     "/api/v2/blocks": {
       "get": {
         "operationId": "listBlocks",
-        "summary": "List Blocks",
-        "description": "List built-in and workspace-deployed blocks visible to the caller. Integration allowlists and preview visibility restrict results. Use `capability=trigger` for workflow starters and Get Block or Get Tool to resolve operation and tool IDs.\n\nOAuth scope: `api:read`.",
+        "summary": "List blocks",
+        "description": "List built-in and workspace-deployed blocks visible to the caller. Integration allowlists and preview visibility restrict results. Use `capability=trigger` for workflow starters and Get block or Get tool to resolve operation and tool IDs.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "catalog.blocks.list",
         "x-oauth-scope": "api:read",
         "tags": ["Catalog"],
@@ -4195,10 +5366,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "id",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["id", "name", "category"]
             }
@@ -4258,6 +5429,33 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListBlocksResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "slack",
+                          "name": "Slack",
+                          "description": "Send messages and read channels in Slack.",
+                          "category": "tools",
+                          "integrationType": "communication",
+                          "source": "builtin",
+                          "authMode": "oauth",
+                          "triggerAllowed": true,
+                          "triggerCapable": true,
+                          "triggerIds": ["slack_webhook"],
+                          "toolIds": ["slack_message", "slack_canvas_read"],
+                          "operationIds": ["send", "read"],
+                          "preview": false,
+                          "docsLink": "https://docs.sim.ai/tools/slack",
+                          "tags": ["messaging"]
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -4289,7 +5487,7 @@
     "/api/v2/blocks/{blockId}": {
       "get": {
         "operationId": "getBlock",
-        "summary": "Get Block",
+        "summary": "Get block",
         "description": "Get a block's fields, conditions, operations, tool schemas, and triggers. Unversioned types resolve to the newest visible version; the returned `id` identifies that version. Hidden or missing blocks return `404`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "catalog.blocks.read",
         "x-oauth-scope": "api:read",
@@ -4299,12 +5497,12 @@
             "name": "blockId",
             "in": "path",
             "required": true,
-            "description": "Block type identifier. An unversioned base type resolves to the newest version, and the response echoes the resolved id.",
+            "description": "Block type identifier. An unversioned base type resolves to the newest visible version. The response echoes the resolved ID.",
             "schema": {
               "type": "string",
               "minLength": 1,
               "maxLength": 255,
-              "description": "Block type identifier. An unversioned base type resolves to the newest version, and the response echoes the resolved id."
+              "description": "Block type identifier. An unversioned base type resolves to the newest visible version. The response echoes the resolved ID."
             }
           },
           {
@@ -4338,6 +5536,143 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetBlockResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "slack",
+                        "name": "Slack",
+                        "description": "Send messages and read channels in Slack.",
+                        "category": "tools",
+                        "integrationType": "communication",
+                        "source": "builtin",
+                        "authMode": "oauth",
+                        "triggerAllowed": true,
+                        "triggerCapable": true,
+                        "triggerIds": ["slack_webhook"],
+                        "toolIds": ["slack_message", "slack_canvas_read"],
+                        "operationIds": ["send", "read"],
+                        "preview": false,
+                        "docsLink": "https://docs.sim.ai/tools/slack",
+                        "tags": ["messaging"],
+                        "inputSchema": [
+                          {
+                            "id": "operation",
+                            "type": "dropdown",
+                            "title": "Operation",
+                            "required": true,
+                            "options": [
+                              {
+                                "id": "send",
+                                "label": "Send message"
+                              },
+                              {
+                                "id": "read",
+                                "label": "Read messages"
+                              }
+                            ]
+                          }
+                        ],
+                        "operationInputSchema": {
+                          "send": [
+                            {
+                              "id": "text",
+                              "type": "long-input",
+                              "title": "Message",
+                              "required": true
+                            }
+                          ]
+                        },
+                        "inputDefinitions": {
+                          "channel": {
+                            "type": "string",
+                            "description": "Channel to post into."
+                          }
+                        },
+                        "operations": {
+                          "send": {
+                            "toolId": "slack_message",
+                            "toolName": "Slack Send Message",
+                            "description": "Send a message to a Slack channel.",
+                            "inputs": {
+                              "text": {
+                                "type": "string",
+                                "required": true,
+                                "description": "Message body."
+                              }
+                            },
+                            "outputs": {
+                              "ts": {
+                                "type": "string",
+                                "description": "Message timestamp."
+                              }
+                            },
+                            "inputSchema": [
+                              {
+                                "id": "text",
+                                "type": "long-input",
+                                "title": "Message",
+                                "required": true
+                              }
+                            ]
+                          }
+                        },
+                        "tools": [
+                          {
+                            "id": "slack_message",
+                            "name": "Slack Send Message",
+                            "description": "Send a message to a Slack channel.",
+                            "version": "1.0.0",
+                            "hostedApiKey": "none",
+                            "oauth": {
+                              "required": true,
+                              "provider": "slack",
+                              "requiredScopes": ["chat:write"]
+                            },
+                            "params": {
+                              "text": {
+                                "type": "string",
+                                "required": true,
+                                "description": "Message body."
+                              }
+                            },
+                            "outputs": {
+                              "ts": {
+                                "type": "string",
+                                "description": "Message timestamp."
+                              }
+                            }
+                          }
+                        ],
+                        "triggers": [
+                          {
+                            "id": "slack_webhook",
+                            "outputs": {
+                              "text": {
+                                "type": "string",
+                                "description": "Message text."
+                              }
+                            },
+                            "configFields": {
+                              "channels": {
+                                "type": "short-input",
+                                "required": false,
+                                "title": "Channels"
+                              }
+                            }
+                          }
+                        ],
+                        "outputs": {
+                          "ts": {
+                            "type": "string",
+                            "description": "Message timestamp."
+                          }
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -4369,8 +5704,8 @@
     "/api/v2/tools": {
       "get": {
         "operationId": "listTools",
-        "summary": "List Tools",
-        "description": "List built-in tools exposed by blocks visible to the caller. Use List MCP Server Tools for an external server's tools and List Custom Tools for workspace code-backed tools.\n\nOAuth scope: `api:read`.",
+        "summary": "List tools",
+        "description": "List built-in tools exposed by blocks visible to the caller. Use List MCP server tools for an external server's tools and List custom tools for workspace code-backed tools.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "catalog.tools.list",
         "x-oauth-scope": "api:read",
         "tags": ["Catalog"],
@@ -4426,10 +5761,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "id",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["id", "name"]
             }
@@ -4489,6 +5824,28 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListToolsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "slack_message",
+                          "name": "Slack Send Message",
+                          "description": "Send a message to a Slack channel.",
+                          "version": "1.0.0",
+                          "hostedApiKey": "none",
+                          "oauth": {
+                            "required": true,
+                            "provider": "slack",
+                            "requiredScopes": ["chat:write"]
+                          }
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -4520,8 +5877,8 @@
     "/api/v2/tools/{toolId}": {
       "get": {
         "operationId": "getTool",
-        "summary": "Get Tool",
-        "description": "Get a built-in tool's parameters and outputs. Registered IDs resolve exactly; other names resolve to the newest family version. The returned `id` identifies the resolved tool. Hidden or missing tools return `404`.\n\nOAuth scope: `api:read`.",
+        "summary": "Get tool",
+        "description": "Get a built-in tool’s parameters and outputs. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The returned `id` identifies that tool. Hidden or missing tools return `404`. Requires workspace read access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "catalog.tools.read",
         "x-oauth-scope": "api:read",
         "tags": ["Catalog"],
@@ -4530,12 +5887,12 @@
             "name": "toolId",
             "in": "path",
             "required": true,
-            "description": "Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id.",
+            "description": "Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID.",
             "schema": {
               "type": "string",
               "minLength": 1,
               "maxLength": 255,
-              "description": "Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id."
+              "description": "Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID."
             }
           },
           {
@@ -4569,6 +5926,43 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetToolResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "slack_message",
+                        "name": "Slack Send Message",
+                        "description": "Send a message to a Slack channel.",
+                        "version": "1.0.0",
+                        "hostedApiKey": "none",
+                        "oauth": {
+                          "required": true,
+                          "provider": "slack",
+                          "requiredScopes": ["chat:write"]
+                        },
+                        "params": {
+                          "channel": {
+                            "type": "string",
+                            "required": true,
+                            "description": "Channel ID to post into."
+                          },
+                          "text": {
+                            "type": "string",
+                            "required": true,
+                            "description": "Message body."
+                          }
+                        },
+                        "outputs": {
+                          "ts": {
+                            "type": "string",
+                            "description": "Message timestamp."
+                          }
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -4600,8 +5994,8 @@
     "/api/v2/tools/{toolId}/execute": {
       "post": {
         "operationId": "executeTool",
-        "summary": "Run Tool",
-        "description": "Run a built-in tool using published parameter IDs. Sim resolves `credentialId`, hosted keys, and whole-value `{{VAR_NAME}}` references for `user-only` parameters; other values pass through verbatim. Third-party refusal returns `200` with `status: \"failed\"`; the error envelope covers API failures. Hidden or missing tools return `404`; disallowed integrations return `403` with `error.details.code: INTEGRATION_NOT_ALLOWED`. Hosted-key use is billed to the workspace; a call that would use a hosted key from a workspace over its usage or billing limits returns `402`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Run tool",
+        "description": "Run a built-in tool using published parameter IDs. Requires workspace read access. Sim resolves `credentialId`, hosted keys, and whole-value `{{VAR_NAME}}` references in `user-only` parameters; other values pass through unchanged. Send connected credentials as top-level `credentialId`, not inside `input`. Third-party refusal returns `200` with `status: \"failed\"`; API failures use the error envelope. Hidden or missing tools return `404`; disallowed integrations return `403` with `error.details.code: INTEGRATION_NOT_ALLOWED`. Hosted-key usage is billed to the workspace. A call that would use a hosted key returns `402` when the workspace exceeds usage or billing limits. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tools.execute",
         "x-oauth-scope": "api:write",
         "tags": ["Catalog"],
@@ -4610,22 +6004,35 @@
             "name": "toolId",
             "in": "path",
             "required": true,
-            "description": "Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id.",
+            "description": "Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID.",
             "schema": {
               "type": "string",
               "minLength": 1,
               "maxLength": 255,
-              "description": "Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id."
+              "description": "Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID."
             }
           }
         ],
         "requestBody": {
           "required": true,
-          "description": "Workspace, arguments, and the credential to authenticate with.",
+          "description": "Workspace, accepted tool arguments, and optional connected credential. Hidden fields and credential aliases inside input are rejected.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ExecuteToolRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "input": {
+                      "channel": "C0123456789",
+                      "text": "Deploy finished."
+                    },
+                    "credentialId": "cred_01J8ZK3QW4M6X2R9T7B5C0V2"
+                  }
+                }
               }
             }
           }
@@ -4648,6 +6055,21 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ExecuteToolResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "toolId": "slack_message",
+                        "status": "succeeded",
+                        "output": {
+                          "ts": "1718191234.004500"
+                        },
+                        "error": null
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -4688,8 +6110,8 @@
     "/api/v2/connector-types": {
       "get": {
         "operationId": "listConnectorTypes",
-        "summary": "List Connector Types",
-        "description": "List knowledge-base connector types with opaque cursors, defaulting to 25 summaries per page: identifier, name, description, and auth mode. `detail=full` adds accepted source configuration fields. Fields with `multi: true` accept `string[]` instead of `string`. A `canonicalParamId` pairs a picker with manual entry for the same configuration key: send exactly one value, keyed by `canonicalParamId` rather than the field’s `id`.\n\nOAuth scope: `api:read`.",
+        "summary": "List connector types",
+        "description": "List connector types from the deployment’s knowledge-base connector registry. Requires workspace read access and Knowledge Base access; workspace integration allowlists and revealed preview blocks do not filter this catalog. Results default to 25 summaries per page. `detail=full` adds configuration fields. Fields with `multi: true` accept `string[]`. For picker/manual-entry pairs, send one value under `canonicalParamId`, not the field’s `id`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "catalog.connector_types.list",
         "x-oauth-scope": "api:read",
         "tags": ["Catalog"],
@@ -4698,12 +6120,12 @@
             "name": "workspaceId",
             "in": "query",
             "required": true,
-            "description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains.",
+            "description": "Workspace used to authorize Knowledge Base access to the deployment’s connector-type registry. Workspace integration allowlists and revealed preview blocks do not filter this catalog.",
             "schema": {
               "type": "string",
               "minLength": 1,
               "maxLength": 128,
-              "description": "Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains."
+              "description": "Workspace used to authorize Knowledge Base access to the deployment’s connector-type registry. Workspace integration allowlists and revealed preview blocks do not filter this catalog."
             }
           },
           {
@@ -4773,6 +6195,166 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListConnectorTypesResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "connectorType": "google_drive",
+                          "name": "Google Drive",
+                          "description": "Sync documents from Google Drive",
+                          "auth": {
+                            "mode": "oauth"
+                          }
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  },
+                  "example2": {
+                    "summary": "Response example 2",
+                    "value": {
+                      "data": [
+                        {
+                          "connectorType": "google_drive",
+                          "name": "Google Drive",
+                          "description": "Sync documents from Google Drive",
+                          "version": "1.0.0",
+                          "auth": {
+                            "mode": "oauth",
+                            "provider": "google-drive",
+                            "requiredScopes": ["https://www.googleapis.com/auth/drive"]
+                          },
+                          "configFields": [
+                            {
+                              "id": "adminEmail",
+                              "title": "Crawl as",
+                              "type": "short-input",
+                              "placeholder": "admin@yourcompany.com",
+                              "required": false,
+                              "description": "The Google Workspace user this service account acts as when fetching content for connected members."
+                            },
+                            {
+                              "id": "userEmails",
+                              "title": "Users",
+                              "type": "short-input",
+                              "placeholder": "All active Google Workspace users",
+                              "required": false,
+                              "description": "Optional primary email addresses, separated by commas (up to 100). Leave blank to index all active users across this Google Workspace customer.",
+                              "multi": true
+                            },
+                            {
+                              "id": "openSharing",
+                              "title": "Openly shared files",
+                              "type": "dropdown",
+                              "placeholder": "Keep out of search",
+                              "required": false,
+                              "description": "Files shared beyond named people and groups. Kept out of search by default, because a domain-wide or public share is more often an accident than an intention. Never applies to link-only shares, which stay unsearchable.",
+                              "options": [
+                                {
+                                  "label": "Keep out of search",
+                                  "id": "none"
+                                },
+                                {
+                                  "label": "Anyone in the domain can find",
+                                  "id": "domain"
+                                },
+                                {
+                                  "label": "Anyone can find",
+                                  "id": "anyone"
+                                }
+                              ]
+                            },
+                            {
+                              "id": "folderSelector",
+                              "title": "Folders",
+                              "type": "selector",
+                              "placeholder": "Select one or more folders (optional)",
+                              "required": false,
+                              "description": "Includes files in each selected folder and its accessible subfolders.",
+                              "selectorKey": "google.drive",
+                              "mimeType": "application/vnd.google-apps.folder",
+                              "mode": "basic",
+                              "canonicalParamId": "folderId",
+                              "multi": true
+                            },
+                            {
+                              "id": "folderId",
+                              "title": "Folder IDs",
+                              "type": "short-input",
+                              "placeholder": "e.g. 1aBcDeFg…, 2cDeFgHi… (comma-separated for multiple)",
+                              "required": false,
+                              "description": "Includes files in each selected folder and its accessible subfolders.",
+                              "mode": "advanced",
+                              "canonicalParamId": "folderId",
+                              "multi": true
+                            },
+                            {
+                              "id": "fileType",
+                              "title": "File Type",
+                              "type": "dropdown",
+                              "required": false,
+                              "options": [
+                                {
+                                  "label": "All supported files",
+                                  "id": "all"
+                                },
+                                {
+                                  "label": "Google Docs only",
+                                  "id": "documents"
+                                },
+                                {
+                                  "label": "Google Sheets only",
+                                  "id": "spreadsheets"
+                                },
+                                {
+                                  "label": "Google Slides only",
+                                  "id": "presentations"
+                                },
+                                {
+                                  "label": "Plain text files only",
+                                  "id": "text"
+                                }
+                              ]
+                            },
+                            {
+                              "id": "maxFiles",
+                              "title": "Max Files",
+                              "type": "short-input",
+                              "placeholder": "e.g. 500 (default: unlimited)",
+                              "required": false
+                            }
+                          ],
+                          "supportsIncrementalSync": false,
+                          "tagDefinitions": [
+                            {
+                              "id": "owners",
+                              "displayName": "Owner",
+                              "fieldType": "text"
+                            },
+                            {
+                              "id": "fileType",
+                              "displayName": "File Type",
+                              "fieldType": "text"
+                            },
+                            {
+                              "id": "lastModified",
+                              "displayName": "Last Modified",
+                              "fieldType": "date"
+                            },
+                            {
+                              "id": "starred",
+                              "displayName": "Starred",
+                              "fieldType": "boolean"
+                            }
+                          ]
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -4804,8 +6386,8 @@
     "/api/v2/organizations/{organizationId}/permission-groups": {
       "get": {
         "operationId": "listPermissionGroups",
-        "summary": "List Permission Groups",
-        "description": "List permission groups in an organization with cursor pagination. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List permission groups",
+        "description": "List permission groups in an organization with cursor pagination. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "permission_groups.list",
         "x-oauth-scope": "api:read",
         "tags": ["Permission Groups"],
@@ -4837,10 +6419,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "createdAt",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -4884,7 +6466,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List Permission Groups result.",
+            "description": "A page of permission groups with resolved settings.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -4900,6 +6482,74 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListPermissionGroupsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "group-123",
+                          "organizationId": "org-123",
+                          "name": "Restricted",
+                          "description": null,
+                          "config": {
+                            "allowedIntegrations": null,
+                            "allowedModelProviders": null,
+                            "deniedModels": [],
+                            "deniedTools": [],
+                            "hideTraceSpans": false,
+                            "hideKnowledgeBaseTab": false,
+                            "hideTablesTab": false,
+                            "hideCopilot": false,
+                            "hideIntegrationsTab": false,
+                            "hideSecretsTab": false,
+                            "hideApiKeysTab": false,
+                            "hideInboxTab": false,
+                            "hideFilesTab": false,
+                            "disableMcpTools": false,
+                            "disableCustomTools": false,
+                            "disableSkills": false,
+                            "disableInvitations": false,
+                            "disablePublicApi": false,
+                            "disablePublicFileSharing": false,
+                            "allowedFileShareAuthTypes": null,
+                            "hideDeployApi": false,
+                            "hideDeployMcp": false,
+                            "hideDeployChatbot": false,
+                            "allowedChatDeployAuthTypes": null,
+                            "disablePersonalApiKeys": false,
+                            "disableLogExport": false,
+                            "hideCostInfo": false,
+                            "disableKnowledgeBaseCreation": false,
+                            "disableKnowledgeBaseFileUpload": false,
+                            "allowedKnowledgeConnectors": null,
+                            "disableTableCreation": false,
+                            "disableTableExport": false,
+                            "disableBulkFileDownload": false,
+                            "disablePersonalCredentials": false,
+                            "disableWorkspaceCreation": false,
+                            "hideOrgMemberDirectory": false,
+                            "disableCliAccess": false,
+                            "disableWebhookTriggers": false,
+                            "disableToolAutoApproval": false,
+                            "hideSandboxesTab": false,
+                            "disableOAuthAppAccess": false,
+                            "disableKnowledgeBaseExport": false,
+                            "deniedPartialAccessProjectIssues": [],
+                            "defaultAgentModel": null
+                          },
+                          "isDefault": false,
+                          "membershipMode": "inherit",
+                          "workspaceIds": ["workspace-123"],
+                          "createdBy": "admin-123",
+                          "createdAt": "2026-06-01T09:00:00.000Z",
+                          "updatedAt": "2026-06-01T09:00:00.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -4929,8 +6579,8 @@
       },
       "post": {
         "operationId": "createPermissionGroup",
-        "summary": "Create Permission Group",
-        "description": "Create a permission group. A non-default group requires workspaces and initially governs everyone in them. Creating a default group demotes the previous default to an inactive group until it is assigned workspaces. Overlapping all-member scopes conflict. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create permission group",
+        "description": "Create a permission group. A non-default group requires workspaces and initially governs everyone in them. Creating a default group demotes the previous default to an inactive group until it is assigned workspaces. Overlapping all-member scopes conflict. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "permission_groups.create",
         "x-oauth-scope": "api:write",
         "tags": ["Permission Groups"],
@@ -4949,18 +6599,27 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Create Permission Group inputs.",
+          "description": "Group name, initial restrictions, and default or workspace-specific scope.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreatePermissionGroupRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "name": "Restricted",
+                    "workspaceIds": ["workspace-123"]
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "201": {
-            "description": "Create Permission Group result.",
+            "description": "The created group, its resolved settings, and workspace scope.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -4976,6 +6635,71 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreatePermissionGroupResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "group-123",
+                        "organizationId": "org-123",
+                        "name": "Restricted",
+                        "description": null,
+                        "config": {
+                          "allowedIntegrations": null,
+                          "allowedModelProviders": null,
+                          "deniedModels": [],
+                          "deniedTools": [],
+                          "hideTraceSpans": false,
+                          "hideKnowledgeBaseTab": false,
+                          "hideTablesTab": false,
+                          "hideCopilot": false,
+                          "hideIntegrationsTab": false,
+                          "hideSecretsTab": false,
+                          "hideApiKeysTab": false,
+                          "hideInboxTab": false,
+                          "hideFilesTab": false,
+                          "disableMcpTools": false,
+                          "disableCustomTools": false,
+                          "disableSkills": false,
+                          "disableInvitations": false,
+                          "disablePublicApi": false,
+                          "disablePublicFileSharing": false,
+                          "allowedFileShareAuthTypes": null,
+                          "hideDeployApi": false,
+                          "hideDeployMcp": false,
+                          "hideDeployChatbot": false,
+                          "allowedChatDeployAuthTypes": null,
+                          "disablePersonalApiKeys": false,
+                          "disableLogExport": false,
+                          "hideCostInfo": false,
+                          "disableKnowledgeBaseCreation": false,
+                          "disableKnowledgeBaseFileUpload": false,
+                          "allowedKnowledgeConnectors": null,
+                          "disableTableCreation": false,
+                          "disableTableExport": false,
+                          "disableBulkFileDownload": false,
+                          "disablePersonalCredentials": false,
+                          "disableWorkspaceCreation": false,
+                          "hideOrgMemberDirectory": false,
+                          "disableCliAccess": false,
+                          "disableWebhookTriggers": false,
+                          "disableToolAutoApproval": false,
+                          "hideSandboxesTab": false,
+                          "disableOAuthAppAccess": false,
+                          "disableKnowledgeBaseExport": false,
+                          "deniedPartialAccessProjectIssues": [],
+                          "defaultAgentModel": null
+                        },
+                        "isDefault": false,
+                        "membershipMode": "inherit",
+                        "workspaceIds": ["workspace-123"],
+                        "createdBy": "admin-123",
+                        "createdAt": "2026-06-01T09:00:00.000Z",
+                        "updatedAt": "2026-06-01T09:00:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -5016,8 +6740,8 @@
     "/api/v2/organizations/{organizationId}/permission-groups/{groupId}": {
       "get": {
         "operationId": "getPermissionGroup",
-        "summary": "Get Permission Group",
-        "description": "Get a permission group and its resolved settings. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get permission group",
+        "description": "Get a permission group and its resolved settings. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "permission_groups.read",
         "x-oauth-scope": "api:read",
         "tags": ["Permission Groups"],
@@ -5047,7 +6771,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Get Permission Group result.",
+            "description": "The group, its resolved settings, and workspace scope.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -5063,6 +6787,71 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetPermissionGroupResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "group-123",
+                        "organizationId": "org-123",
+                        "name": "Restricted",
+                        "description": null,
+                        "config": {
+                          "allowedIntegrations": null,
+                          "allowedModelProviders": null,
+                          "deniedModels": [],
+                          "deniedTools": [],
+                          "hideTraceSpans": false,
+                          "hideKnowledgeBaseTab": false,
+                          "hideTablesTab": false,
+                          "hideCopilot": false,
+                          "hideIntegrationsTab": false,
+                          "hideSecretsTab": false,
+                          "hideApiKeysTab": false,
+                          "hideInboxTab": false,
+                          "hideFilesTab": false,
+                          "disableMcpTools": false,
+                          "disableCustomTools": false,
+                          "disableSkills": false,
+                          "disableInvitations": false,
+                          "disablePublicApi": false,
+                          "disablePublicFileSharing": false,
+                          "allowedFileShareAuthTypes": null,
+                          "hideDeployApi": false,
+                          "hideDeployMcp": false,
+                          "hideDeployChatbot": false,
+                          "allowedChatDeployAuthTypes": null,
+                          "disablePersonalApiKeys": false,
+                          "disableLogExport": false,
+                          "hideCostInfo": false,
+                          "disableKnowledgeBaseCreation": false,
+                          "disableKnowledgeBaseFileUpload": false,
+                          "allowedKnowledgeConnectors": null,
+                          "disableTableCreation": false,
+                          "disableTableExport": false,
+                          "disableBulkFileDownload": false,
+                          "disablePersonalCredentials": false,
+                          "disableWorkspaceCreation": false,
+                          "hideOrgMemberDirectory": false,
+                          "disableCliAccess": false,
+                          "disableWebhookTriggers": false,
+                          "disableToolAutoApproval": false,
+                          "hideSandboxesTab": false,
+                          "disableOAuthAppAccess": false,
+                          "disableKnowledgeBaseExport": false,
+                          "deniedPartialAccessProjectIssues": [],
+                          "defaultAgentModel": null
+                        },
+                        "isDefault": false,
+                        "membershipMode": "inherit",
+                        "workspaceIds": ["workspace-123"],
+                        "createdBy": "admin-123",
+                        "createdAt": "2026-06-01T09:00:00.000Z",
+                        "updatedAt": "2026-06-01T09:00:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -5092,8 +6881,8 @@
       },
       "patch": {
         "operationId": "updatePermissionGroup",
-        "summary": "Update Permission Group",
-        "description": "Update a permission group. Omitted fields remain unchanged; config keys are patched and supplied arrays replace their lists. Promoting a group to default demotes the previous default; demoting without workspaceIds leaves it inactive. Overlapping member or all-member scopes conflict. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update permission group",
+        "description": "Update a permission group. Omitted fields remain unchanged; config keys are patched and supplied arrays replace their lists. Promoting a group to default demotes the previous default; demoting without workspaceIds leaves it inactive. Overlapping member or all-member scopes conflict. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "permission_groups.update",
         "x-oauth-scope": "api:write",
         "tags": ["Permission Groups"],
@@ -5123,18 +6912,26 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Update Permission Group inputs.",
+          "description": "Group fields and restriction keys to change; supplied lists replace their contents.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdatePermissionGroupRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "description": "Restricted workspace access"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Update Permission Group result.",
+            "description": "The updated group with resolved settings and workspace scope.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -5150,6 +6947,71 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdatePermissionGroupResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "group-123",
+                        "organizationId": "org-123",
+                        "name": "Restricted",
+                        "description": null,
+                        "config": {
+                          "allowedIntegrations": null,
+                          "allowedModelProviders": null,
+                          "deniedModels": [],
+                          "deniedTools": [],
+                          "hideTraceSpans": false,
+                          "hideKnowledgeBaseTab": false,
+                          "hideTablesTab": false,
+                          "hideCopilot": false,
+                          "hideIntegrationsTab": false,
+                          "hideSecretsTab": false,
+                          "hideApiKeysTab": false,
+                          "hideInboxTab": false,
+                          "hideFilesTab": false,
+                          "disableMcpTools": false,
+                          "disableCustomTools": false,
+                          "disableSkills": false,
+                          "disableInvitations": false,
+                          "disablePublicApi": false,
+                          "disablePublicFileSharing": false,
+                          "allowedFileShareAuthTypes": null,
+                          "hideDeployApi": false,
+                          "hideDeployMcp": false,
+                          "hideDeployChatbot": false,
+                          "allowedChatDeployAuthTypes": null,
+                          "disablePersonalApiKeys": false,
+                          "disableLogExport": false,
+                          "hideCostInfo": false,
+                          "disableKnowledgeBaseCreation": false,
+                          "disableKnowledgeBaseFileUpload": false,
+                          "allowedKnowledgeConnectors": null,
+                          "disableTableCreation": false,
+                          "disableTableExport": false,
+                          "disableBulkFileDownload": false,
+                          "disablePersonalCredentials": false,
+                          "disableWorkspaceCreation": false,
+                          "hideOrgMemberDirectory": false,
+                          "disableCliAccess": false,
+                          "disableWebhookTriggers": false,
+                          "disableToolAutoApproval": false,
+                          "hideSandboxesTab": false,
+                          "disableOAuthAppAccess": false,
+                          "disableKnowledgeBaseExport": false,
+                          "deniedPartialAccessProjectIssues": [],
+                          "defaultAgentModel": null
+                        },
+                        "isDefault": false,
+                        "membershipMode": "inherit",
+                        "workspaceIds": ["workspace-123"],
+                        "createdBy": "admin-123",
+                        "createdAt": "2026-06-01T09:00:00.000Z",
+                        "updatedAt": "2026-06-01T09:00:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -5188,8 +7050,8 @@
       },
       "delete": {
         "operationId": "deletePermissionGroup",
-        "summary": "Delete Permission Group",
-        "description": "Permanently delete a permission group and its membership assignments. Members then inherit any other applicable restrictions. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete permission group",
+        "description": "Permanently delete a permission group and its membership assignments. Members then inherit any other applicable restrictions. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "permission_groups.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Permission Groups"],
@@ -5219,7 +7081,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Delete Permission Group result.",
+            "description": "Acknowledgement that the group and its assignments were deleted.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -5235,6 +7097,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeletePermissionGroupResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "group-123",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -5266,8 +7139,8 @@
     "/api/v2/organizations/{organizationId}/permission-groups/{groupId}/members": {
       "get": {
         "operationId": "listPermissionGroupMembers",
-        "summary": "List Permission Group Members",
-        "description": "List explicit membership assignments in a permission group with cursor pagination. An empty inherit group applies to everyone in its workspaces. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List permission group members",
+        "description": "List explicit membership assignments in a permission group with cursor pagination. An empty inherit group applies to everyone in its workspaces. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "permission_groups.members.list",
         "x-oauth-scope": "api:read",
         "tags": ["Permission Groups"],
@@ -5345,7 +7218,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List Permission Group Members result.",
+            "description": "A page of explicit group membership assignments.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -5361,6 +7234,24 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListPermissionGroupMembersResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "assignment-123",
+                          "userId": "user-123",
+                          "assignedAt": "2026-06-01T09:00:00.000Z",
+                          "userName": "Example Member",
+                          "userEmail": "member@example.com",
+                          "userImage": null
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -5390,8 +7281,8 @@
       },
       "post": {
         "operationId": "addPermissionGroupMember",
-        "summary": "Add Permission Group Member",
-        "description": "Assign an organization member to a permission group. An existing assignment or membership in another group targeting the same workspace returns a conflict. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Add permission group member",
+        "description": "Assign an organization member to a permission group. An existing assignment or membership in another group targeting the same workspace returns a conflict. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "permission_groups.members.add",
         "x-oauth-scope": "api:write",
         "tags": ["Permission Groups"],
@@ -5421,18 +7312,26 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Add Permission Group Member inputs.",
+          "description": "The organization member to assign to this group.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/AddPermissionGroupMemberRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "userId": "user-123"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "201": {
-            "description": "Add Permission Group Member result.",
+            "description": "The new explicit membership assignment.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -5448,6 +7347,21 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/AddPermissionGroupMemberResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "assignment-123",
+                        "permissionGroupId": "group-123",
+                        "organizationId": "org-123",
+                        "userId": "user-123",
+                        "assignedBy": "admin-123",
+                        "assignedAt": "2026-06-01T09:00:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -5488,8 +7402,8 @@
     "/api/v2/organizations/{organizationId}/permission-groups/{groupId}/members/{userId}": {
       "delete": {
         "operationId": "removePermissionGroupMember",
-        "summary": "Remove Permission Group Member",
-        "description": "Remove a member by user identifier. Removing the last member from an inherit group makes it govern everyone in its workspaces; a conflicting all-member group prevents the removal. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Remove permission group member",
+        "description": "Remove a member by user identifier. Removing the last member from an inherit group makes it govern everyone in its workspaces; a conflicting all-member group prevents the removal. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "permission_groups.members.remove",
         "x-oauth-scope": "api:write",
         "tags": ["Permission Groups"],
@@ -5530,7 +7444,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Remove Permission Group Member result.",
+            "description": "Acknowledgement that the explicit assignment was removed.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -5546,6 +7460,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RemovePermissionGroupMemberResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "userId": "user-123",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -5580,8 +7505,8 @@
     "/api/v2/organizations/{organizationId}/permission-groups/{groupId}/members/bulk": {
       "post": {
         "operationId": "bulkAddPermissionGroupMembers",
-        "summary": "Bulk Add Permission Group Members",
-        "description": "Assign up to 1000 selected organization members, or the entire organization roster, atomically. Existing assignments are skipped and users outside the organization are ignored. Any overlapping membership conflict rejects the entire batch. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Bulk add permission group members",
+        "description": "Assign up to 1000 selected organization members, or the entire organization roster, atomically. Existing assignments are skipped and users outside the organization are ignored. Any overlapping membership conflict rejects the entire batch. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "permission_groups.members.bulk_add",
         "x-oauth-scope": "api:write",
         "tags": ["Permission Groups"],
@@ -5611,18 +7536,26 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Bulk Add Permission Group Members inputs.",
+          "description": "Selected organization members or the entire current organization roster.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/BulkAddPermissionGroupMembersRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "userIds": ["user-123"]
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Bulk Add Permission Group Members result.",
+            "description": "Counts of added members and existing assignments skipped.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -5638,6 +7571,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/BulkAddPermissionGroupMembersResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "added": 1,
+                        "skipped": 0
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -5678,7 +7622,7 @@
     "/api/v2/organizations": {
       "get": {
         "operationId": "listOrganizations",
-        "summary": "List Organizations",
+        "summary": "List organizations",
         "description": "List organizations the acting user belongs to. Organizations that disallow the calling credential are omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organizations.list",
         "x-oauth-scope": "api:read",
@@ -5700,10 +7644,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "name",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt"]
             }
@@ -5747,7 +7691,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List Organizations result.",
+            "description": "A page of organizations and the acting user’s role in each.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -5763,6 +7707,24 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListOrganizationsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "org-123",
+                          "name": "Example Organization",
+                          "slug": "example",
+                          "logo": null,
+                          "role": "admin",
+                          "createdAt": "2026-06-01T09:00:00.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -5794,7 +7756,7 @@
     "/api/v2/organizations/{organizationId}": {
       "get": {
         "operationId": "getOrganization",
-        "summary": "Get Organization",
+        "summary": "Get organization",
         "description": "Get organization metadata and the acting user’s organization role. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organizations.read",
         "x-oauth-scope": "api:read",
@@ -5814,7 +7776,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Get Organization result.",
+            "description": "Organization metadata and the acting user’s role.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -5830,6 +7792,21 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetOrganizationResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "org-123",
+                        "name": "Example Organization",
+                        "slug": "example",
+                        "logo": null,
+                        "role": "admin",
+                        "createdAt": "2026-06-01T09:00:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -5861,8 +7838,8 @@
     "/api/v2/organizations/{organizationId}/workspaces": {
       "get": {
         "operationId": "listOrganizationWorkspaces",
-        "summary": "List Organization Workspaces",
-        "description": "List active workspaces owned by the organization. Requires organization administrator access; does not require Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List organization workspaces",
+        "description": "List active workspaces owned by the organization. Requires organization Admin access; does not require Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organizations.workspaces.list",
         "x-oauth-scope": "api:read",
         "tags": ["Organizations"],
@@ -5894,10 +7871,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "name",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "id"]
             }
@@ -5941,7 +7918,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List Organization Workspaces result.",
+            "description": "A page of active workspaces owned by the organization.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -5957,6 +7934,20 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListOrganizationWorkspacesResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "workspace-123",
+                          "name": "Engineering"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -5988,7 +7979,7 @@
     "/api/v2/organizations/{organizationId}/members": {
       "get": {
         "operationId": "listOrganizationMembers",
-        "summary": "List Organization Members",
+        "summary": "List organization members",
         "description": "List organization members by name or email. Ordinary members must have access to the member directory; organization administrators retain access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organizations.members.list",
         "x-oauth-scope": "api:read",
@@ -6021,10 +8012,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "name",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "email", "joinedAt"]
             }
@@ -6068,7 +8059,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List Organization Members result.",
+            "description": "A page of organization members and their organization roles.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -6084,6 +8075,23 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListOrganizationMembersResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "userId": "user-123",
+                          "name": "Example Member",
+                          "email": "member@example.com",
+                          "role": "member",
+                          "joinedAt": "2026-06-01T09:00:00.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -6115,8 +8123,8 @@
     "/api/v2/organizations/{organizationId}/members/{userId}": {
       "patch": {
         "operationId": "updateOrganizationMember",
-        "summary": "Update Organization Member",
-        "description": "Change a member’s organization role. Requires organization administrator access. The owner’s role and memberships managed by an identity provider cannot be changed here. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update organization member",
+        "description": "Change a member’s organization role. Requires organization Admin access. The owner’s role and memberships managed by an identity provider cannot be changed here. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organizations.members.update",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -6146,18 +8154,26 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Update Organization Member input.",
+          "description": "The new organization role for this member.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateOrganizationMemberBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "role": "admin"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Update Organization Member result.",
+            "description": "The member with the updated organization role.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -6173,6 +8189,20 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateOrganizationMemberResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "userId": "user-123",
+                        "name": "Example Member",
+                        "email": "member@example.com",
+                        "role": "admin",
+                        "joinedAt": "2026-06-01T09:00:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -6211,7 +8241,7 @@
       },
       "delete": {
         "operationId": "removeOrganizationMember",
-        "summary": "Remove Organization Member",
+        "summary": "Remove organization member",
         "description": "Remove a member and revoke their access to organization workspaces. Administrators may remove members; members may remove themselves. The organization owner cannot be removed. Owned organization resources are reassigned and the departing member’s sessions end. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organizations.members.remove",
         "x-oauth-scope": "api:write",
@@ -6242,7 +8272,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Remove Organization Member result.",
+            "description": "Acknowledgement that organization access was removed.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -6258,6 +8288,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RemoveOrganizationMemberResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "userId": "user-123",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -6292,8 +8333,8 @@
     "/api/v2/organizations/{organizationId}/invitations": {
       "get": {
         "operationId": "listOrganizationInvitations",
-        "summary": "List Organization Invitations",
-        "description": "List invitations owned by the organization, including invitations with workspace grants. Requires organization administrator access. Expired invitations are reported without modifying them. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List organization invitations",
+        "description": "List invitations owned by the organization, including invitations with workspace grants. Requires organization Admin access. Expired invitations are reported without modifying them. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organizations.invitations.list",
         "x-oauth-scope": "api:read",
         "tags": ["Organizations"],
@@ -6383,7 +8424,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List Organization Invitations result.",
+            "description": "A page of invitations, including their current status.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -6399,6 +8440,27 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListOrganizationInvitationsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "invitation-123",
+                          "organizationId": "org-123",
+                          "email": "member@example.com",
+                          "role": "member",
+                          "kind": "organization",
+                          "membershipIntent": "internal",
+                          "status": "pending",
+                          "createdAt": "2026-06-01T09:00:00.000Z",
+                          "expiresAt": "2026-06-08T09:00:00.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -6428,8 +8490,8 @@
       },
       "post": {
         "operationId": "createOrganizationInvitation",
-        "summary": "Create Organization Invitation",
-        "description": "Email an invitation to join the organization as a member or administrator. Requires organization administrator access, invitations enabled, and an available seat on an eligible plan. This grants no workspace-specific permissions. An unexpired pending invitation for the email conflicts; use Resend Organization Invitation to send it again. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create organization invitation",
+        "description": "Email an invitation to join the organization as a member or Admin. Requires organization Admin access and invitations enabled; an eligible plan and available seat are required when billing is enabled. It grants no workspace-specific permissions. Existing organization membership or an unexpired pending invitation for the email returns `409`. Use Resend organization invitation to send a pending invitation again. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organizations.invitations.create",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -6448,18 +8510,27 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Create Organization Invitation input.",
+          "description": "Invitee email and organization role to offer.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateOrganizationInvitationBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "email": "member@example.com",
+                    "role": "member"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "201": {
-            "description": "Create Organization Invitation result.",
+            "description": "The pending organization invitation.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -6475,6 +8546,24 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateOrganizationInvitationResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "invitation-123",
+                        "organizationId": "org-123",
+                        "email": "member@example.com",
+                        "role": "member",
+                        "kind": "organization",
+                        "membershipIntent": "internal",
+                        "status": "pending",
+                        "createdAt": "2026-06-01T09:00:00.000Z",
+                        "expiresAt": "2026-06-08T09:00:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -6515,8 +8604,8 @@
     "/api/v2/organizations/{organizationId}/invitations/{invitationId}": {
       "get": {
         "operationId": "getOrganizationInvitation",
-        "summary": "Get Organization Invitation",
-        "description": "Get an invitation owned by the organization. Requires organization administrator access. Use List Organization Invitation Workspaces to inspect its workspace grants. The response excludes the acceptance token. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get organization invitation",
+        "description": "Get an invitation owned by the organization. Requires organization Admin access. Use List organization invitation workspaces to inspect its workspace grants. The response excludes the acceptance token. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organizations.invitations.read",
         "x-oauth-scope": "api:read",
         "tags": ["Organizations"],
@@ -6546,7 +8635,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Get Organization Invitation result.",
+            "description": "Invitation metadata without its acceptance token.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -6562,6 +8651,24 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetOrganizationInvitationResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "invitation-123",
+                        "organizationId": "org-123",
+                        "email": "member@example.com",
+                        "role": "member",
+                        "kind": "organization",
+                        "membershipIntent": "internal",
+                        "status": "pending",
+                        "createdAt": "2026-06-01T09:00:00.000Z",
+                        "expiresAt": "2026-06-08T09:00:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -6591,8 +8698,8 @@
       },
       "delete": {
         "operationId": "revokeOrganizationInvitation",
-        "summary": "Revoke Organization Invitation",
-        "description": "Cancel an unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization administrator access. This does not remove a person who already accepted; use Remove Organization Member for that. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Revoke organization invitation",
+        "description": "Cancel an unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization Admin access. This does not remove a person who already accepted; use Remove organization member for that. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "invitations.revoke",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -6622,7 +8729,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Revoke Organization Invitation result.",
+            "description": "Acknowledgement that the pending invitation was cancelled.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -6638,6 +8745,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RevokeOrganizationInvitationResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "invitation-123",
+                        "status": "cancelled"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -6672,8 +8790,8 @@
     "/api/v2/organizations/{organizationId}/invitations/{invitationId}/workspaces": {
       "get": {
         "operationId": "listOrganizationInvitationWorkspaces",
-        "summary": "List Organization Invitation Workspaces",
-        "description": "List workspace grants attached to an invitation of any status. Includes archived workspaces still owned by the organization; workspaces moved to another organization are omitted. Requires organization administrator access. These grants describe the invitation, not the invitee's current access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List organization invitation workspaces",
+        "description": "List workspace grants attached to an invitation of any status. Includes archived workspaces still owned by the organization; workspaces moved to another organization are omitted. Requires organization Admin access. These grants describe the invitation, not the invitee's current access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organizations.invitations.workspaces.list",
         "x-oauth-scope": "api:read",
         "tags": ["Organizations"],
@@ -6716,10 +8834,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "name",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "id"]
             }
@@ -6779,6 +8897,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListOrganizationInvitationWorkspacesResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "workspace-123",
+                          "name": "Engineering",
+                          "permission": "write",
+                          "archivedAt": null
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -6810,8 +8944,8 @@
     "/api/v2/organizations/{organizationId}/invitations/{invitationId}/resend": {
       "post": {
         "operationId": "resendOrganizationInvitation",
-        "summary": "Resend Organization Invitation",
-        "description": "Email an unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization administrator access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Resend organization invitation",
+        "description": "Email an unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization Admin access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "invitations.resend",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -6841,18 +8975,24 @@
         ],
         "requestBody": {
           "required": false,
-          "description": "Resend Organization Invitation input.",
+          "description": "An empty JSON object; the pending invitation supplies the recipient and role.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ResendOrganizationInvitationBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {}
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Resend Organization Invitation result.",
+            "description": "The pending invitation with its renewed expiry.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -6868,6 +9008,24 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ResendOrganizationInvitationResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "invitation-123",
+                        "organizationId": "org-123",
+                        "email": "member@example.com",
+                        "role": "member",
+                        "kind": "organization",
+                        "membershipIntent": "internal",
+                        "status": "pending",
+                        "createdAt": "2026-06-01T09:00:00.000Z",
+                        "expiresAt": "2026-06-08T09:00:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -6908,8 +9066,8 @@
     "/api/v2/organizations/{organizationId}/sso/providers": {
       "get": {
         "operationId": "listSsoProviders",
-        "summary": "List SSO Providers",
-        "description": "List identity providers owned by the organization. Requires organization administrator access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List SSO providers",
+        "description": "List identity providers owned by the organization. Requires organization Admin access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organization.sso.providers.list",
         "x-oauth-scope": "api:read",
         "tags": ["Organizations"],
@@ -6976,7 +9134,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List SSO Providers result.",
+            "description": "A page of identity providers with redacted configuration.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7024,8 +9182,8 @@
       },
       "post": {
         "operationId": "saveSsoProvider",
-        "summary": "Save SSO Provider",
-        "description": "Create or update an organization identity provider’s configuration on a verified domain. Requires organization administrator access and SSO entitlement. Existing providers return 200; creation returns 201. Omission behavior is field-specific; OIDC’s redacted secret marker preserves the saved secret. Identity changes with linked accounts conflict. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Save SSO provider",
+        "description": "Create or update an organization identity provider’s configuration on a verified domain. Requires organization Admin access and SSO entitlement. Existing providers return 200; creation returns 201. Omission behavior is field-specific; OIDC’s redacted secret marker preserves the saved secret. Identity changes with linked accounts conflict. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organization.sso.providers.save",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -7044,7 +9202,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Configuration accepted by Save SSO Provider.",
+          "description": "Provider protocol, verified domain, and identity-provider configuration. Omission behavior is field-specific.",
           "content": {
             "application/json": {
               "schema": {
@@ -7055,7 +9213,7 @@
         },
         "responses": {
           "200": {
-            "description": "Save SSO Provider result.",
+            "description": "The saved provider ID, protocol, and whether it was created.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7076,7 +9234,7 @@
             }
           },
           "201": {
-            "description": "Save SSO Provider result.",
+            "description": "The saved provider ID, protocol, and whether it was created.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7132,8 +9290,8 @@
     "/api/v2/organizations/{organizationId}/sso/providers/{providerId}": {
       "get": {
         "operationId": "getSsoProvider",
-        "summary": "Get SSO Provider",
-        "description": "Get an identity provider owned by the organization. Requires organization administrator access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get SSO provider",
+        "description": "Get an identity provider owned by the organization. Requires organization Admin access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organization.sso.providers.list",
         "x-oauth-scope": "api:read",
         "tags": ["Organizations"],
@@ -7164,7 +9322,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Get SSO Provider result.",
+            "description": "The identity provider with redacted configuration.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7212,8 +9370,8 @@
       },
       "delete": {
         "operationId": "deleteSsoProvider",
-        "summary": "Delete SSO Provider",
-        "description": "Remove an identity provider and clear its primary selection. Requires organization administrator access. Existing accounts, memberships, and sessions remain; sign-in falls back to another verified provider on the domain. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete SSO provider",
+        "description": "Remove an identity provider and clear its primary selection. Requires organization Admin access. Existing accounts, memberships, and sessions remain. Domain sign-in falls back to another verified provider if one remains; use Get SSO policy to inspect whether SSO is still enforced. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organization.sso.providers.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -7244,7 +9402,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Delete SSO Provider result.",
+            "description": "Acknowledgement that the identity provider was removed.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7294,8 +9452,8 @@
     "/api/v2/organizations/{organizationId}/sso/providers/{providerId}/primary": {
       "post": {
         "operationId": "setPrimarySsoProvider",
-        "summary": "Set Primary SSO Provider",
-        "description": "Make a verified organization provider handle sign-in for its domain. Requires organization administrator access. Other providers remain available for testing and later switching. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Set primary SSO provider",
+        "description": "Make a verified organization provider handle sign-in for its domain. Requires organization Admin access. Other providers remain available for testing and later switching. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organization.sso.set_primary_provider",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -7326,7 +9484,7 @@
         ],
         "requestBody": {
           "required": false,
-          "description": "Configuration accepted by Set Primary SSO Provider.",
+          "description": "An empty JSON object; the path identifies the provider to make primary.",
           "content": {
             "application/json": {
               "schema": {
@@ -7337,7 +9495,7 @@
         },
         "responses": {
           "200": {
-            "description": "Set Primary SSO Provider result.",
+            "description": "The provider selected for its verified domain.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7393,7 +9551,7 @@
     "/api/v2/organizations/{organizationId}/sso/policy": {
       "get": {
         "operationId": "getSsoPolicy",
-        "summary": "Get SSO Policy",
+        "summary": "Get SSO policy",
         "description": "Get the stored organization SSO requirement and whether it is currently enforced. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organization.sso.read_requirement",
         "x-oauth-scope": "api:read",
@@ -7413,7 +9571,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Get SSO Policy result.",
+            "description": "The stored SSO requirement and its effective enforcement state.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7461,8 +9619,8 @@
       },
       "patch": {
         "operationId": "updateSsoPolicy",
-        "summary": "Update SSO Policy",
-        "description": "Require or stop requiring SSO on future sign-ins. Requires organization administrator access. Enabling requires SSO entitlement and a verified provider; disabling remains available after entitlement is lost. Existing sessions remain active. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update SSO policy",
+        "description": "Require or stop requiring SSO on future sign-ins. Requires organization Admin access. Enabling requires SSO entitlement and a verified provider; disabling remains available after entitlement is lost. Existing sessions remain active. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organization.sso.set_requirement",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -7481,7 +9639,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Configuration accepted by Update SSO Policy.",
+          "description": "Whether future sign-ins must use SSO.",
           "content": {
             "application/json": {
               "schema": {
@@ -7492,7 +9650,7 @@
         },
         "responses": {
           "200": {
-            "description": "Update SSO Policy result.",
+            "description": "The saved SSO requirement and its effective enforcement state.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7548,7 +9706,7 @@
     "/api/v2/organizations/{organizationId}/domains": {
       "get": {
         "operationId": "listOrganizationDomains",
-        "summary": "List Organization Domains",
+        "summary": "List organization domains",
         "description": "List the organization’s domain claims with cursor pagination. Requires organization membership. Pending DNS challenge values are returned only to administrators using their own credentials. Organizations without Enterprise domain entitlement return an empty list. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organizations.domains.list",
         "x-oauth-scope": "api:read",
@@ -7616,7 +9774,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List Organization Domains result.",
+            "description": "A page of domain claims; pending challenges are limited to Admins.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7664,8 +9822,8 @@
       },
       "post": {
         "operationId": "addOrganizationDomain",
-        "summary": "Add Organization Domain",
-        "description": "Claim a domain and receive its DNS TXT challenge. Requires organization administrator access and Enterprise domain entitlement. An existing claim returns 200; a new claim returns 201. A domain verified by another organization conflicts. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Add organization domain",
+        "description": "Claim a domain and receive its DNS TXT challenge. Requires organization Admin access and, when billing is enabled, Enterprise domain entitlement. An organization can claim at most 25 domains. Existing claims return `200`; new claims return `201`. A domain verified by another organization returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organizations.domains.add",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -7684,7 +9842,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Configuration accepted by Add Organization Domain.",
+          "description": "The domain to claim and verify.",
           "content": {
             "application/json": {
               "schema": {
@@ -7695,7 +9853,7 @@
         },
         "responses": {
           "200": {
-            "description": "Add Organization Domain result.",
+            "description": "The domain claim and its pending DNS challenge, when applicable.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7716,7 +9874,7 @@
             }
           },
           "201": {
-            "description": "Add Organization Domain result.",
+            "description": "The domain claim and its pending DNS challenge, when applicable.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7772,8 +9930,8 @@
     "/api/v2/organizations/{organizationId}/domains/{domainId}/verify": {
       "post": {
         "operationId": "verifyOrganizationDomain",
-        "summary": "Verify Organization Domain",
-        "description": "Verify domain ownership through the published DNS TXT challenge and grant domain trust to matching organization providers. Requires organization administrator access and Enterprise domain entitlement. An already-verified domain is returned unchanged. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Verify organization domain",
+        "description": "Verify domain ownership through its DNS TXT challenge and grant domain trust to matching organization providers. Requires organization Admin access and, when billing is enabled, Enterprise domain entitlement. Billing-disabled self-hosted deployments may configure operator verification. An already-verified domain is returned unchanged. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organizations.domains.verify",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -7804,7 +9962,7 @@
         ],
         "requestBody": {
           "required": false,
-          "description": "Configuration accepted by Verify Organization Domain.",
+          "description": "An empty JSON object; verification uses the claim’s current DNS challenge.",
           "content": {
             "application/json": {
               "schema": {
@@ -7815,7 +9973,7 @@
         },
         "responses": {
           "200": {
-            "description": "Verify Organization Domain result.",
+            "description": "The domain claim after ownership verification.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7871,8 +10029,8 @@
     "/api/v2/organizations/{organizationId}/domains/{domainId}": {
       "delete": {
         "operationId": "removeOrganizationDomain",
-        "summary": "Remove Organization Domain",
-        "description": "Remove a domain claim and revoke verified sign-in authority from matching organization providers. Requires organization administrator access and Enterprise domain entitlement. Existing accounts and memberships remain. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Remove organization domain",
+        "description": "Remove a domain claim and revoke verified sign-in authority from matching organization providers. Requires organization Admin access and, when billing is enabled, Enterprise domain entitlement. Existing accounts and memberships remain. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organizations.domains.remove",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -7903,7 +10061,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Remove Organization Domain result.",
+            "description": "Acknowledgement that the domain claim was removed.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -7953,8 +10111,8 @@
     "/api/v2/credentials/{credentialId}/members": {
       "get": {
         "operationId": "listCredentialMembers",
-        "summary": "List Credential Members",
-        "description": "List explicit credential grants, including revoked grants, and inherited workspace administrator access. Requires workspace read access and the integrations.manage capability. Personal API keys and OAuth tokens can access OAuth or service-account credentials; sessions can also access workspace environment credentials. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List credential members",
+        "description": "List explicit credential grants, including revoked grants, and inherited workspace Admin access. Personal API keys and OAuth access tokens can list grants for OAuth or service-account credentials. Requires workspace read access and the `integrations.manage` capability. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "credentials.members.list",
         "x-oauth-scope": "api:read",
         "tags": ["Credentials"],
@@ -8011,10 +10169,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "email",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["email", "name"]
             }
@@ -8034,7 +10192,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List Credential Members result.",
+            "description": "A page of explicit and inherited credential grants.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -8079,8 +10237,8 @@
       },
       "post": {
         "operationId": "upsertCredentialMember",
-        "summary": "Upsert Credential Member",
-        "description": "Grant or change an existing workspace member’s credential role. Requires credential administrator access and the integrations.manage capability. Revoked grants become active again; inherited administrators cannot be demoted. A new grant returns 201; an existing grant returns 200. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Upsert credential member",
+        "description": "Grant or change a current workspace member’s credential role. Requires credential Admin access and the `integrations.manage` capability. Revoked grants become active again; inherited workspace Admins cannot be demoted. A new grant returns `201`; an existing grant returns `200`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "credentials.members.upsert",
         "x-oauth-scope": "api:write",
         "tags": ["Credentials"],
@@ -8112,7 +10270,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Configuration accepted by Upsert Credential Member.",
+          "description": "The current workspace member and credential role to grant.",
           "content": {
             "application/json": {
               "schema": {
@@ -8123,7 +10281,7 @@
         },
         "responses": {
           "200": {
-            "description": "Upsert Credential Member result.",
+            "description": "The saved credential role and whether a grant was created.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -8144,7 +10302,7 @@
             }
           },
           "201": {
-            "description": "Upsert Credential Member result.",
+            "description": "The saved credential role and whether a grant was created.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -8197,8 +10355,8 @@
     "/api/v2/credentials/{credentialId}/members/{userId}": {
       "delete": {
         "operationId": "removeCredentialMember",
-        "summary": "Remove Credential Member",
-        "description": "Revoke an active explicit credential grant. Requires credential administrator access and the integrations.manage capability. Inherited workspace administrators cannot be removed; an absent or already-revoked grant returns 404. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Remove credential member",
+        "description": "Revoke an active explicit credential grant. Requires credential Admin access and the `integrations.manage` capability. Inherited workspace Admins cannot be removed; an absent or already-revoked grant returns `404`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "credentials.members.remove",
         "x-oauth-scope": "api:write",
         "tags": ["Credentials"],
@@ -8242,7 +10400,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Remove Credential Member result.",
+            "description": "Acknowledgement that the explicit credential grant was revoked.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -8289,7 +10447,7 @@
     "/api/v2/workspaces/{workspaceId}/permission-config": {
       "get": {
         "operationId": "getWorkspacePermissionConfig",
-        "summary": "Get Workspace Permission Config",
+        "summary": "Get workspace permission config",
         "description": "Get the acting user's governing permission group and configuration for a workspace they can access. This describes permission-group restrictions, not the user's workspace role. Group and config are null when no group governs the caller; entitled indicates whether organization permission governance is active. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "permission_groups.read_user_config",
         "x-oauth-scope": "api:read",
@@ -8326,6 +10484,21 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetWorkspacePermissionConfigResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "permissionGroupId": null,
+                        "groupName": null,
+                        "config": null,
+                        "entitled": false,
+                        "organizationId": null,
+                        "isOrgAdmin": false
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -8357,8 +10530,8 @@
     "/api/v2/workspaces/{workspaceId}/invitations": {
       "post": {
         "operationId": "createWorkspaceInvitations",
-        "summary": "Create Workspace Invitations",
-        "description": "Invite people to a workspace or grant access immediately to existing organization members. Requires workspace administrator access and current invitation eligibility; organization administrator invitations also require organization administrator access. Recipients are processed independently: inspect failed even after HTTP 200, and inspect invitation status before retrying a delivery failure. Existing access is preserved. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create workspace invitations",
+        "description": "Invite people to a workspace or grant access immediately to existing organization members. Requires workspace Admin access and current invitation eligibility; invitations offering organization Admin membership also require organization Admin access. Recipients are processed independently: inspect `failed` even after HTTP `200`, and inspect invitation status before retrying a delivery failure. Existing access is preserved. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspace_invitations.send_batch",
         "x-oauth-scope": "api:write",
         "tags": ["Workspaces"],
@@ -8383,6 +10556,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateWorkspaceInvitationsBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "emails": ["member@example.com"],
+                    "permission": "write",
+                    "membership": "member"
+                  }
+                }
               }
             }
           }
@@ -8405,6 +10588,28 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateWorkspaceInvitationsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "success": true,
+                        "successful": ["member@example.com"],
+                        "added": [],
+                        "failed": [],
+                        "invitations": [
+                          {
+                            "id": "invitation-123",
+                            "email": "member@example.com",
+                            "workspaceIds": ["workspace-123"],
+                            "permission": "write",
+                            "membershipIntent": "internal"
+                          }
+                        ]
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -8445,8 +10650,8 @@
     "/api/v2/organizations/{organizationId}/members/{userId}/usage-limit": {
       "get": {
         "operationId": "getOrganizationMemberUsageLimit",
-        "summary": "Get Organization Member Credit Limit",
-        "description": "Read a person’s credit cap and credits consumed in the organization billing period. Hosted only. The userId identifies an organization member or external collaborator with workspace access in this organization; it is not a membership record ID. Null means no per-person cap, while organization limits still apply. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get organization member credit limit",
+        "description": "Read a person’s credit cap and credits consumed in the organization billing period. Hosted deployments only. The `userId` identifies an organization member or external collaborator with workspace access in this organization; it is not a membership record ID. Null means no per-person cap, while organization limits still apply. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organization_member_usage_limits.read",
         "x-oauth-scope": "api:read",
         "tags": ["Organizations"],
@@ -8476,7 +10681,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Get Organization Member Credit Limit result.",
+            "description": "The person’s current credit cap and billing-period consumption.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -8492,6 +10697,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetOrganizationMemberUsageLimitResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "creditsUsed": 200,
+                        "creditLimit": 10000,
+                        "billingInterval": "month"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -8521,8 +10738,8 @@
       },
       "patch": {
         "operationId": "updateOrganizationMemberUsageLimit",
-        "summary": "Update Organization Member Credit Limit",
-        "description": "Set or clear a person’s credit cap. Hosted only. The userId must identify an organization member or external collaborator with workspace access in this organization. The cap is a nonnegative whole number of credits, not dollars: 0 prevents further credit-consuming usage; null removes the per-person cap. Organization limits continue to apply. Retrying the same value is safe. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update organization member credit limit",
+        "description": "Set or clear a person’s credit cap. Hosted deployments only. The `userId` must identify an organization member or external collaborator with workspace access in this organization. The cap is a nonnegative whole number of credits, not dollars: `0` prevents further credit-consuming usage; `null` removes the per-person cap. Organization limits continue to apply. Retrying the same value is safe. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "organization_member_usage_limits.update",
         "x-oauth-scope": "api:write",
         "tags": ["Organizations"],
@@ -8557,13 +10774,27 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateOrganizationMemberUsageLimitBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "creditLimit": 10000
+                  }
+                },
+                "example2": {
+                  "summary": "Request example 2",
+                  "value": {
+                    "creditLimit": null
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Update Organization Member Credit Limit result.",
+            "description": "The saved credit cap, or null when the cap was cleared.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -8579,6 +10810,16 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateOrganizationMemberUsageLimitResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "creditLimit": 10000
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -8616,8 +10857,8 @@
     "/api/v2/organizations/{organizationId}/usage/summary": {
       "get": {
         "operationId": "getOrganizationUsageSummary",
-        "summary": "Get Organization Usage Summary",
-        "description": "Read pooled credits, a usage series, and an exact previous-period comparison when available. Requires organization administrator access and Usage Monitoring (Enterprise on hosted; enabled on self-hosted). Defaults to 30 days. Custom dates include both dates in the selected timezone and cannot exceed 92 days. Billing windows exceeding 366 days are rejected. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get organization usage summary",
+        "description": "Read pooled credits, a usage series, and an exact previous-period comparison when available. Requires organization Admin access and Usage Monitoring: Enterprise when billing is enabled, or deployment enablement when billing is disabled. Defaults to 30 days. Custom dates include both dates in the selected timezone and cannot exceed 92 days. Billing windows exceeding 366 days are rejected. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organization_usage.summary.read",
         "x-oauth-scope": "api:read",
         "tags": ["Organizations"],
@@ -8696,7 +10937,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Get Organization Usage Summary result.",
+            "description": "Reporting bounds, pooled credits, and chronological usage buckets.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -8712,6 +10953,32 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetOrganizationUsageSummaryResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "window": {
+                          "start": "2026-06-01T00:00:00.000Z",
+                          "end": "2026-07-01T00:00:00.000Z",
+                          "source": "range"
+                        },
+                        "bucket": "day",
+                        "totals": {
+                          "credits": 200
+                        },
+                        "previousTotals": null,
+                        "series": [
+                          {
+                            "timestamp": "2026-06-01T00:00:00.000Z",
+                            "credits": 200,
+                            "events": 1
+                          }
+                        ]
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -8743,8 +11010,8 @@
     "/api/v2/organizations/{organizationId}/usage/breakdown": {
       "get": {
         "operationId": "getOrganizationUsageBreakdown",
-        "summary": "Get Organization Usage Breakdown",
-        "description": "Read ranked organization usage by member, workspace, workflow, model, BYOK provider, or source. Requires organization administrator access and Usage Monitoring. Omitted usage is summarized in other. BYOK ranks tokens; other dimensions rank cost. More than 10,000 underlying groups returns 413; narrow the window or workspace. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get organization usage breakdown",
+        "description": "Read ranked usage by member, workspace, workflow, model, BYOK provider, or source. Requires organization Admin access and Usage Monitoring. `other` summarizes groups omitted by the limit. BYOK ranks tokens; other dimensions rank cost. More than 10,000 underlying groups returns `413`; narrow the window or workspace. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organization_usage.breakdown.read",
         "x-oauth-scope": "api:read",
         "tags": ["Organizations"],
@@ -8847,7 +11114,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Get Organization Usage Breakdown result.",
+            "description": "Ranked usage groups and the combined remainder.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -8863,6 +11130,32 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetOrganizationUsageBreakdownResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "dimension": "member",
+                        "rows": [
+                          {
+                            "id": "user-123",
+                            "label": "Example Member",
+                            "credits": 200,
+                            "events": 1,
+                            "share": 1
+                          }
+                        ],
+                        "other": {
+                          "credits": 0,
+                          "events": 0,
+                          "rowCount": 0,
+                          "tokens": 0
+                        },
+                        "totalCredits": 200
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -8897,8 +11190,8 @@
     "/api/v2/organizations/{organizationId}/usage/events": {
       "get": {
         "operationId": "listOrganizationUsageEvents",
-        "summary": "List Organization Usage Events",
-        "description": "Page through usage events, including zero-cost reporting. Requires organization administrator access and Usage Monitoring. Defaults to 30 days. Cursors retain the initial reporting window; keep filters and sort unchanged while paging. The sim-chat source covers both chat surfaces. Per-event rounding can produce credits=0 with hasCost=true. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List organization usage events",
+        "description": "List usage events, including zero-cost activity. Requires organization Admin access and Usage Monitoring. Defaults to 30 days. Cursors retain the initial reporting window; keep filters and sort unchanged while paging. `sim-chat` covers both chat surfaces. Per-event rounding can yield `credits: 0` with `hasCost: true`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "organization_usage.events.list",
         "x-oauth-scope": "api:read",
         "tags": ["Organizations"],
@@ -9035,7 +11328,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List Organization Usage Events result.",
+            "description": "A page of usage events, including zero-cost activity.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -9051,6 +11344,25 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListOrganizationUsageEventsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "event-123",
+                          "createdAt": "2026-06-01T09:00:00.000Z",
+                          "source": "sim-chat",
+                          "description": "Model usage",
+                          "workflowName": null,
+                          "credits": 200,
+                          "hasCost": true
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -9082,7 +11394,7 @@
     "/api/v2/workspaces/{workspaceId}/access-requests/discovery": {
       "get": {
         "operationId": "discoverWorkspaceAccessRequests",
-        "summary": "Discover Workspace Access Requests",
+        "summary": "Discover workspace access requests",
         "description": "Discover the acting user’s access to features, integrations, models, tools, authentication methods, and member credit limits. Returns an empty list while requests are disabled. Requires access to the workspace; external collaborators use their workspace grant. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "access_requests.discover",
         "x-oauth-scope": "api:read",
@@ -9195,7 +11507,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Discover Workspace Access Requests result.",
+            "description": "A page of access targets and the acting user’s current access state.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -9211,6 +11523,26 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DiscoverWorkspaceAccessRequestsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "target": {
+                            "kind": "feature",
+                            "configKey": "hideTablesTab"
+                          },
+                          "label": "Tables",
+                          "state": "requestable",
+                          "reason": null,
+                          "pendingRequestId": null
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -9245,7 +11577,7 @@
     "/api/v2/workspaces/{workspaceId}/access-requests": {
       "get": {
         "operationId": "listMyWorkspaceAccessRequests",
-        "summary": "List My Workspace Access Requests",
+        "summary": "List my workspace access requests",
         "description": "List only the acting user’s requests in this workspace, including resolved history and organization-wide member credit-limit requests. History remains available while requests are disabled. Requires access to the workspace; external collaborators use their workspace grant. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "access_requests.list_mine",
         "x-oauth-scope": "api:read",
@@ -9325,7 +11657,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List My Workspace Access Requests result.",
+            "description": "A page of the acting user’s workspace and member-credit requests.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -9341,6 +11673,37 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListMyWorkspaceAccessRequestsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "request-123",
+                          "organizationId": "org-123",
+                          "workspaceId": "workspace-123",
+                          "target": {
+                            "kind": "feature",
+                            "configKey": "hideTablesTab"
+                          },
+                          "targetLabel": "Tables",
+                          "reason": "Maintain team data",
+                          "status": "pending",
+                          "decisionReason": null,
+                          "createdAt": "2026-06-01T09:00:00.000Z",
+                          "decidedAt": null,
+                          "groupName": "Engineering",
+                          "requester": {
+                            "id": "user-123",
+                            "name": "Alex Example",
+                            "email": "alex@example.com"
+                          }
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -9373,8 +11736,8 @@
       },
       "post": {
         "operationId": "createWorkspaceAccessRequest",
-        "summary": "Create Workspace Access Request",
-        "description": "Request access for the acting user using a target from discovery. Returns an existing matching pending request when applicable; the result may be closed if access is already available. Permission approvals change the governing group for all affected members. Requires access to the workspace; external collaborators use their workspace grant. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create workspace access request",
+        "description": "Request access using a target from Discover workspace access requests. Requires access to an organization-owned workspace with requests enabled; external collaborators use their workspace grant. Each requester can have 100 pending requests and submit 100 in 24 hours within the organization. Matching pending requests are reused; an existing request may be closed if access is already available. Permission approvals change the governing group for all affected members. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "access_requests.create",
         "x-oauth-scope": "api:write",
         "tags": ["Access Requests"],
@@ -9394,18 +11757,30 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Inputs for this operation.",
+          "description": "A discovered access target and an optional reason for the request.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateWorkspaceAccessRequestBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "target": {
+                      "kind": "feature",
+                      "configKey": "hideTablesTab"
+                    },
+                    "reason": "Maintain team data"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Create Workspace Access Request result.",
+            "description": "The new request, matching pending request, or existing request closed because access became available.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -9421,6 +11796,34 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateWorkspaceAccessRequestResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "request-123",
+                        "organizationId": "org-123",
+                        "workspaceId": "workspace-123",
+                        "target": {
+                          "kind": "feature",
+                          "configKey": "hideTablesTab"
+                        },
+                        "targetLabel": "Tables",
+                        "reason": "Maintain team data",
+                        "status": "pending",
+                        "decisionReason": null,
+                        "createdAt": "2026-06-01T09:00:00.000Z",
+                        "decidedAt": null,
+                        "groupName": "Engineering",
+                        "requester": {
+                          "id": "user-123",
+                          "name": "Alex Example",
+                          "email": "alex@example.com"
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -9461,7 +11864,7 @@
     "/api/v2/workspaces/{workspaceId}/access-requests/{requestId}/cancel": {
       "post": {
         "operationId": "cancelWorkspaceAccessRequest",
-        "summary": "Cancel Workspace Access Request",
+        "summary": "Cancel workspace access request",
         "description": "Cancel the acting user’s pending request in this scope, including an organization-wide member credit-limit request. Already resolved requests are returned unchanged. Cancellation remains available while requests are disabled. Requires access to the workspace; external collaborators use their workspace grant. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "access_requests.cancel",
         "x-oauth-scope": "api:write",
@@ -9494,7 +11897,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Cancel Workspace Access Request result.",
+            "description": "The cancelled request, or the unchanged request if already resolved.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -9510,6 +11913,34 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CancelWorkspaceAccessRequestResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "request-123",
+                        "organizationId": "org-123",
+                        "workspaceId": "workspace-123",
+                        "target": {
+                          "kind": "feature",
+                          "configKey": "hideTablesTab"
+                        },
+                        "targetLabel": "Tables",
+                        "reason": "Maintain team data",
+                        "status": "cancelled",
+                        "decisionReason": null,
+                        "createdAt": "2026-06-01T09:00:00.000Z",
+                        "decidedAt": "2026-06-01T10:00:00.000Z",
+                        "groupName": "Engineering",
+                        "requester": {
+                          "id": "user-123",
+                          "name": "Alex Example",
+                          "email": "alex@example.com"
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -9544,7 +11975,7 @@
     "/api/v2/organizations/{organizationId}/access-requests/discovery": {
       "get": {
         "operationId": "discoverOrganizationAccessRequests",
-        "summary": "Discover Organization Access Requests",
+        "summary": "Discover organization access requests",
         "description": "Discover the acting user’s access to features, integrations, models, tools, authentication methods, and member credit limits. Returns an empty list while requests are disabled. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "access_requests.discover",
         "x-oauth-scope": "api:read",
@@ -9656,7 +12087,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Discover Organization Access Requests result.",
+            "description": "A page of access targets and the acting user’s current access state.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -9672,6 +12103,26 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DiscoverOrganizationAccessRequestsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "target": {
+                            "kind": "feature",
+                            "configKey": "hideTablesTab"
+                          },
+                          "label": "Tables",
+                          "state": "requestable",
+                          "reason": null,
+                          "pendingRequestId": null
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -9706,8 +12157,8 @@
     "/api/v2/organizations/{organizationId}/access-requests/mine": {
       "get": {
         "operationId": "listMyOrganizationAccessRequests",
-        "summary": "List My Organization Access Requests",
-        "description": "List the acting user’s organization-level requests and member credit-limit requests, including resolved history. For workspace-scoped requests, use List My Workspace Access Requests. History remains available while requests are disabled. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List my organization access requests",
+        "description": "List the acting user’s organization-level requests and member credit-limit requests, including resolved history. For workspace-scoped requests, use List my workspace access requests. History remains available while requests are disabled. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "access_requests.list_mine",
         "x-oauth-scope": "api:read",
         "tags": ["Access Requests"],
@@ -9785,7 +12236,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List My Organization Access Requests result.",
+            "description": "A page of the acting user’s organization and member-credit requests.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -9801,6 +12252,37 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListMyOrganizationAccessRequestsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "request-123",
+                          "organizationId": "org-123",
+                          "workspaceId": null,
+                          "target": {
+                            "kind": "feature",
+                            "configKey": "hideTablesTab"
+                          },
+                          "targetLabel": "Tables",
+                          "reason": "Maintain team data",
+                          "status": "pending",
+                          "decisionReason": null,
+                          "createdAt": "2026-06-01T09:00:00.000Z",
+                          "decidedAt": null,
+                          "groupName": "Engineering",
+                          "requester": {
+                            "id": "user-123",
+                            "name": "Alex Example",
+                            "email": "alex@example.com"
+                          }
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -9835,8 +12317,8 @@
     "/api/v2/organizations/{organizationId}/access-requests": {
       "post": {
         "operationId": "createOrganizationAccessRequest",
-        "summary": "Create Organization Access Request",
-        "description": "Request access for the acting user using a target from discovery. Returns an existing matching pending request when applicable; the result may be closed if access is already available. Permission approvals change the governing group for all affected members. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create organization access request",
+        "description": "Request access using a target from Discover organization access requests. Requires organization membership and requests enabled. Each requester can have 100 pending requests and submit 100 in 24 hours within the organization. Matching pending requests are reused; an existing request may be closed if access is already available. Permission approvals change the governing group for all affected members. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "access_requests.create",
         "x-oauth-scope": "api:write",
         "tags": ["Access Requests"],
@@ -9855,18 +12337,30 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Inputs for this operation.",
+          "description": "A discovered access target and an optional reason for the request.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateOrganizationAccessRequestBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "target": {
+                      "kind": "feature",
+                      "configKey": "hideTablesTab"
+                    },
+                    "reason": "Maintain team data"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Create Organization Access Request result.",
+            "description": "The new request, matching pending request, or existing request closed because access became available.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -9882,6 +12376,34 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateOrganizationAccessRequestResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "request-123",
+                        "organizationId": "org-123",
+                        "workspaceId": null,
+                        "target": {
+                          "kind": "feature",
+                          "configKey": "hideTablesTab"
+                        },
+                        "targetLabel": "Tables",
+                        "reason": "Maintain team data",
+                        "status": "pending",
+                        "decisionReason": null,
+                        "createdAt": "2026-06-01T09:00:00.000Z",
+                        "decidedAt": null,
+                        "groupName": "Engineering",
+                        "requester": {
+                          "id": "user-123",
+                          "name": "Alex Example",
+                          "email": "alex@example.com"
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -9920,8 +12442,8 @@
       },
       "get": {
         "operationId": "listOrganizationAccessRequests",
-        "summary": "List Organization Access Requests",
-        "description": "List requests across the organization for administrator review. Includes requests from organization members and external workspace collaborators; history remains available while requests are disabled. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List organization access requests",
+        "description": "List requests across the organization for administrator review. Includes requests from organization members and external workspace collaborators; history remains available while requests are disabled. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "access_requests.list_organization",
         "x-oauth-scope": "api:read",
         "tags": ["Access Requests"],
@@ -10011,7 +12533,7 @@
         ],
         "responses": {
           "200": {
-            "description": "List Organization Access Requests result.",
+            "description": "A page of requests across the organization for Admin review.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -10027,6 +12549,37 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ListOrganizationAccessRequestsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "request-123",
+                          "organizationId": "org-123",
+                          "workspaceId": "workspace-123",
+                          "target": {
+                            "kind": "feature",
+                            "configKey": "hideTablesTab"
+                          },
+                          "targetLabel": "Tables",
+                          "reason": "Maintain team data",
+                          "status": "pending",
+                          "decisionReason": null,
+                          "createdAt": "2026-06-01T09:00:00.000Z",
+                          "decidedAt": null,
+                          "groupName": "Engineering",
+                          "requester": {
+                            "id": "user-123",
+                            "name": "Alex Example",
+                            "email": "alex@example.com"
+                          }
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -10061,7 +12614,7 @@
     "/api/v2/organizations/{organizationId}/access-requests/{requestId}/cancel": {
       "post": {
         "operationId": "cancelOrganizationAccessRequest",
-        "summary": "Cancel Organization Access Request",
+        "summary": "Cancel organization access request",
         "description": "Cancel the acting user’s pending request in this scope, including an organization-wide member credit-limit request. Already resolved requests are returned unchanged. Cancellation remains available while requests are disabled. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "access_requests.cancel",
         "x-oauth-scope": "api:write",
@@ -10093,7 +12646,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Cancel Organization Access Request result.",
+            "description": "The cancelled request, or the unchanged request if already resolved.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -10109,6 +12662,34 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CancelOrganizationAccessRequestResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "request-123",
+                        "organizationId": "org-123",
+                        "workspaceId": null,
+                        "target": {
+                          "kind": "feature",
+                          "configKey": "hideTablesTab"
+                        },
+                        "targetLabel": "Tables",
+                        "reason": "Maintain team data",
+                        "status": "cancelled",
+                        "decisionReason": null,
+                        "createdAt": "2026-06-01T09:00:00.000Z",
+                        "decidedAt": "2026-06-01T10:00:00.000Z",
+                        "groupName": "Engineering",
+                        "requester": {
+                          "id": "user-123",
+                          "name": "Alex Example",
+                          "email": "alex@example.com"
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -10143,8 +12724,8 @@
     "/api/v2/organizations/{organizationId}/access-requests/{requestId}/preview": {
       "get": {
         "operationId": "previewOrganizationAccessRequest",
-        "summary": "Preview Organization Access Request",
-        "description": "Preview the current permission changes, affected group and audience, or member credit cap. Review canApply, changes, impact, and fingerprint before resolving. Permission changes affect the entire governing group, not only the requester. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Preview organization access request",
+        "description": "Preview the current permission changes, affected group and audience, or member credit cap. Review `canApply`, `changes`, `impact`, and `fingerprint` before resolving. Permission changes affect the entire governing group, not only the requester. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "access_requests.preview",
         "x-oauth-scope": "api:read",
         "tags": ["Access Requests"],
@@ -10175,7 +12756,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Preview Organization Access Request result.",
+            "description": "The proposed group or credit-cap change, affected audience, and fingerprint.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -10191,6 +12772,60 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/PreviewOrganizationAccessRequestResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "resolutionKind": "permission",
+                        "request": {
+                          "id": "request-123",
+                          "organizationId": "org-123",
+                          "workspaceId": "workspace-123",
+                          "target": {
+                            "kind": "feature",
+                            "configKey": "hideTablesTab"
+                          },
+                          "targetLabel": "Tables",
+                          "reason": "Maintain team data",
+                          "status": "pending",
+                          "decisionReason": null,
+                          "createdAt": "2026-06-01T09:00:00.000Z",
+                          "decidedAt": null,
+                          "groupName": "Engineering",
+                          "requester": {
+                            "id": "user-123",
+                            "name": "Alex Example",
+                            "email": "alex@example.com"
+                          }
+                        },
+                        "group": {
+                          "id": "group-123",
+                          "name": "Engineering"
+                        },
+                        "changes": [
+                          {
+                            "configKey": "hideTablesTab",
+                            "label": "Tables",
+                            "before": true,
+                            "after": false
+                          }
+                        ],
+                        "impact": {
+                          "memberCount": 2,
+                          "workspaceCount": 1,
+                          "workspaceNames": ["Engineering"],
+                          "truncated": false
+                        },
+                        "fingerprint": "current-preview-fingerprint",
+                        "canApply": true,
+                        "unavailableReason": null,
+                        "currentLimitCredits": null,
+                        "newLimitCredits": null
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -10225,8 +12860,8 @@
     "/api/v2/organizations/{organizationId}/access-requests/{requestId}/resolve": {
       "post": {
         "operationId": "resolveOrganizationAccessRequest",
-        "summary": "Resolve Organization Access Request",
-        "description": "Apply a reviewed request or decline it with a reason. Applying requires the preview fingerprint; changed policy or membership returns a conflict. Credit requests also require a higher newLimitCredits. Already resolved requests are returned unchanged. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Resolve organization access request",
+        "description": "Apply a reviewed request or decline it with a reason. Applying requires the preview fingerprint; changed policy or membership returns a conflict. Credit requests also require a higher `newLimitCredits`. Already resolved requests are returned unchanged. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "access_requests.resolve",
         "x-oauth-scope": "api:write",
         "tags": ["Access Requests"],
@@ -10257,18 +12892,27 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Inputs for this operation.",
+          "description": "Apply the reviewed fingerprint, with a higher credit cap when applicable, or decline with a reason.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ResolveOrganizationAccessRequestBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "action": "apply",
+                    "expectedFingerprint": "current-preview-fingerprint"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Resolve Organization Access Request result.",
+            "description": "The applied or declined request, or its unchanged resolved state.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -10284,6 +12928,34 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ResolveOrganizationAccessRequestResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "request-123",
+                        "organizationId": "org-123",
+                        "workspaceId": "workspace-123",
+                        "target": {
+                          "kind": "feature",
+                          "configKey": "hideTablesTab"
+                        },
+                        "targetLabel": "Tables",
+                        "reason": "Maintain team data",
+                        "status": "fulfilled",
+                        "decisionReason": null,
+                        "createdAt": "2026-06-01T09:00:00.000Z",
+                        "decidedAt": "2026-06-01T10:00:00.000Z",
+                        "groupName": "Engineering",
+                        "requester": {
+                          "id": "user-123",
+                          "name": "Alex Example",
+                          "email": "alex@example.com"
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -10324,8 +12996,8 @@
     "/api/v2/organizations/{organizationId}/access-requests/settings": {
       "get": {
         "operationId": "getOrganizationAccessRequestSettings",
-        "summary": "Get Organization Access Request Settings",
-        "description": "Get whether the organization allows new access requests and approvals. This preference does not enable features unavailable in the deployment or subscription. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get organization access request settings",
+        "description": "Get whether the organization allows new access requests and approvals. This preference does not enable features unavailable in the deployment or subscription. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "access_requests.get_settings",
         "x-oauth-scope": "api:read",
         "tags": ["Access Requests"],
@@ -10344,7 +13016,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Get Organization Access Request Settings result.",
+            "description": "Whether new requests and approvals are allowed.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -10360,6 +13032,16 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetOrganizationAccessRequestSettingsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "allowRequests": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -10392,8 +13074,8 @@
       },
       "patch": {
         "operationId": "updateOrganizationAccessRequestSettings",
-        "summary": "Update Organization Access Request Settings",
-        "description": "Allow or pause new access requests and approvals. Pausing preserves history, cancellation, and decline, and does not revoke previously granted access. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update organization access request settings",
+        "description": "Allow or pause new access requests and approvals. Pausing preserves history, cancellation, and decline, and does not revoke previously granted access. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "access_requests.update_settings",
         "x-oauth-scope": "api:write",
         "tags": ["Access Requests"],
@@ -10412,18 +13094,26 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Inputs for this operation.",
+          "description": "Whether new requests and approvals are allowed.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateOrganizationAccessRequestSettingsBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "allowRequests": false
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Update Organization Access Request Settings result.",
+            "description": "The saved setting for new requests and approvals.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -10439,6 +13129,16 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateOrganizationAccessRequestSettingsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "allowRequests": false
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -10716,7 +13416,7 @@
         }
       },
       "ServiceUnavailable": {
-        "description": "A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, because the run may already have started — reconcile against the returned run id instead of retrying.",
+        "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
         "headers": {
           "Retry-After": {
             "$ref": "#/components/headers/Retry-After"
@@ -10901,13 +13601,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
         "title": "List workspaces response",
-        "description": "Public metadata for workspaces available to the credential.",
+        "description": "Metadata for workspaces available to the credential.",
         "examples": [
           {
             "data": [
@@ -10936,7 +13636,7 @@
         "required": ["data"],
         "additionalProperties": false,
         "title": "Get workspace response",
-        "description": "Public metadata for one workspace.",
+        "description": "Metadata for one workspace.",
         "examples": [
           {
             "data": {
@@ -11019,7 +13719,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -11086,12 +13786,12 @@
             "description": "Whether the server tools are available to workflows."
           },
           "connectionStatus": {
-            "description": "Result of the most recent connection attempt. Registration and re-registration establish no connection — the auth-type probe they may send does not count as one — so a server begins, and returns to, `disconnected` until a tool discovery runs.",
+            "description": "Result of the most recent tool connection attempt. New registrations start `disconnected`; re-registration resets this state only when connection inputs change. Authentication probes do not establish a tool connection. Tool discovery updates this state.",
             "type": "string",
             "enum": ["connected", "disconnected", "error"]
           },
           "lastError": {
-            "description": "Message from the most recent failed connection, or null when absent. A re-registration clears it, since the configuration it described no longer applies.",
+            "description": "Message from the most recent failed tool connection, or null when absent. Successful discovery or re-registration with changed connection inputs clears it.",
             "anyOf": [
               {
                 "type": "string"
@@ -11112,7 +13812,7 @@
             "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
           },
           "lastConnected": {
-            "description": "ISO 8601 timestamp of the most recent successful connection. Absent until the server completes one; registering a server does not set it.",
+            "description": "ISO 8601 timestamp of the most recent successful tool connection. Absent until one succeeds, or after re-registration changes connection inputs.",
             "type": "string",
             "format": "date-time",
             "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
@@ -11184,7 +13884,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -11289,7 +13989,7 @@
             "description": "Absolute HTTP or HTTPS endpoint URL without `{{ENV_VAR}}` references. It determines server identity and is immutable: delete and recreate the server to change endpoints."
           },
           "authType": {
-            "description": "Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server does not advertise OAuth. A server publishing RFC 9728 metadata is therefore stored as `oauth`, and headers configured afterwards will not authenticate — send this field explicitly to pin the method.",
+            "description": "Authentication method. On creation, omission without `headers` probes once: an OAuth challenge selects `oauth`, an unauthenticated success selects `none`, and other outcomes fall back to `headers`. An OAuth client ID selects `oauth` when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method.",
             "type": "string",
             "enum": ["none", "headers", "oauth"]
           },
@@ -11476,7 +14176,7 @@
             "maxLength": 2048
           },
           "authType": {
-            "description": "Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server does not advertise OAuth. A server publishing RFC 9728 metadata is therefore stored as `oauth`, and headers configured afterwards will not authenticate — send this field explicitly to pin the method.",
+            "description": "Authentication method. On creation, omission without `headers` probes once: an OAuth challenge selects `oauth`, an unauthenticated success selects `none`, and other outcomes fall back to `headers`. An OAuth client ID selects `oauth` when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method.",
             "type": "string",
             "enum": ["none", "headers", "oauth"]
           },
@@ -11665,13 +14365,13 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
         "title": "List MCP server tools response",
-        "description": "Tools exposed by the MCP server.",
+        "description": "Tools discovered so far. Limits or later-page failures can leave the inventory incomplete; the response has no truncation indicator or pagination.",
         "examples": [
           {
             "data": [
@@ -11752,7 +14452,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -12075,13 +14775,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
         "title": "List skill editors response",
-        "description": "Public identity fields for users who can edit the skill.",
+        "description": "Identity fields for users who can edit the skill.",
         "examples": [
           {
             "data": [
@@ -12107,7 +14807,7 @@
         "required": ["data"],
         "additionalProperties": false,
         "title": "Grant skill editor response",
-        "description": "Public identity fields for the editor.",
+        "description": "Identity fields for the editor.",
         "examples": [
           {
             "data": {
@@ -12304,7 +15004,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -12884,7 +15584,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -13329,7 +16029,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -13679,7 +16379,7 @@
             "additionalProperties": false
           }
         ],
-        "title": "Credential Provider",
+        "title": "Credential provider",
         "description": "An OAuth or service-account connection method available to a workspace."
       },
       "ListCredentialProvidersResponse": {
@@ -13701,7 +16401,7 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           }
         },
         "required": ["data", "nextCursor"],
@@ -13869,7 +16569,7 @@
         },
         "required": ["authorizationUrl", "expiresAt"],
         "additionalProperties": false,
-        "title": "Credential Connection Authorization",
+        "title": "Credential connection authorization",
         "description": "A short-lived browser entrypoint for an OAuth connection flow."
       },
       "CreateCredentialConnectionResponse": {
@@ -14096,7 +16796,29 @@
           }
         ],
         "title": "Create credential connection body",
-        "description": "For a new connection, provide providerId and displayName. For a reconnect, provide only credentialId; the existing display name is preserved."
+        "description": "Provide workspaceId for every flow. For a new connection, send providerId and displayName; for a reconnect, send credentialId and retain the existing name. QuickBooks also requires oauthClientConfig for either flow; omit it for other providers.",
+        "examples": [
+          {
+            "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+            "providerId": "slack",
+            "displayName": "Support Slack"
+          },
+          {
+            "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+            "credentialId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
+          },
+          {
+            "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+            "providerId": "quickbooks",
+            "displayName": "Accounting",
+            "oauthClientConfig": {
+              "clientId": "YOUR_INTUIT_CLIENT_ID",
+              "clientSecret": "YOUR_INTUIT_CLIENT_SECRET",
+              "environment": "sandbox",
+              "webhookVerifierToken": "YOUR_WEBHOOK_VERIFIER_TOKEN"
+            }
+          }
+        ]
       },
       "V2CredentialDeleteData": {
         "type": "object",
@@ -14222,7 +16944,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -14315,7 +17037,7 @@
         ],
         "additionalProperties": false,
         "title": "Secret metadata",
-        "description": "Public secret metadata without the stored secret value."
+        "description": "Secret metadata without the stored value."
       },
       "SetSecretResponse": {
         "type": "object",
@@ -14358,7 +17080,7 @@
             "description": "Whether the secret belongs to the workspace or to the caller. A personal secret belongs to the caller across every workspace, not to one workspace."
           },
           "value": {
-            "description": "Write-only secret value. It is never returned. Omit it on a workspace secret to change description or unredacted alone, leaving the stored value untouched; the secret must already exist. Always required for a personal secret, which carries no other writable field.",
+            "description": "Secret value, omitted from the Set secret response. For an existing workspace secret, omit it to change only `description` or `unredacted`. Personal secrets always require a value and accept no writable metadata.",
             "writeOnly": true,
             "type": "string",
             "minLength": 1,
@@ -14456,7 +17178,7 @@
           "keyType": {
             "type": "string",
             "enum": ["personal", "workspace", "oauth_access_token"],
-            "description": "Whether the calling credential is a personal API key carrying the full authority of its owner across their workspaces, a key scoped to one workspace, or an OAuth access token acting for its user within the scopes it was granted."
+            "description": "Calling credential kind: a personal API key acting for its owner, a key bound to one workspace, or an OAuth access token acting for its user within granted scopes. Resource permissions and credential policies still apply."
           },
           "expiresAt": {
             "anyOf": [
@@ -14474,7 +17196,7 @@
         },
         "required": ["v2Enabled", "keyType", "expiresAt"],
         "additionalProperties": false,
-        "title": "API capabilities",
+        "title": "API status",
         "description": "API availability and lifecycle facts about the calling credential."
       },
       "GetApiMetaResponse": {
@@ -14487,7 +17209,7 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "API capabilities response",
+        "title": "API status response",
         "description": "API availability, credential type, and expiry for the caller.",
         "examples": [
           {
@@ -14527,7 +17249,7 @@
           },
           "mcpServerUrl": {
             "type": "string",
-            "description": "Endpoint an MCP client connects to. Published here so callers never build it.",
+            "description": "MCP client endpoint. Use this returned URL instead of constructing one.",
             "examples": ["https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2"]
           },
           "createdAt": {
@@ -14544,14 +17266,14 @@
             "type": "integer",
             "minimum": 0,
             "maximum": 9007199254740991,
-            "description": "Number of workflows published as tools."
+            "description": "Number of returned tool names for this server. It may undercount registrations when the page’s `toolNamesTruncated` flag is true."
           },
           "toolNames": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Tool names this server publishes, alphabetically ordered."
+            "description": "Returned registered tool names, ordered alphabetically. The list may be incomplete when toolNamesTruncated is true."
           }
         },
         "required": [
@@ -14567,7 +17289,7 @@
         ],
         "additionalProperties": false,
         "title": "Workflow MCP server list item",
-        "description": "A published MCP server together with the tool names it exposes."
+        "description": "A workflow MCP server and its bounded tool-name inventory."
       },
       "ListWorkflowMcpServersResponse": {
         "type": "object",
@@ -14588,17 +17310,17 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           },
           "toolNamesTruncated": {
             "type": "boolean",
-            "description": "Whether the page-wide tool-name limit left some inventories incomplete. Use List Workflow MCP Tools for one server and check its `truncated` flag before treating the inventory as complete. `nextCursor` paginates servers, not tool names."
+            "description": "Whether the page-wide tool-name limit left some inventories incomplete. Use List workflow MCP tools for one server and check its `truncated` flag before treating the inventory as complete. `nextCursor` paginates servers, not tool names."
           }
         },
         "required": ["data", "nextCursor", "toolNamesTruncated"],
         "additionalProperties": false,
         "title": "List workflow MCP servers response",
-        "description": "A cursor-paginated page of published MCP servers.",
+        "description": "A page of workflow MCP servers with bounded tool-name inventories.",
         "examples": [
           {
             "data": [
@@ -14647,7 +17369,7 @@
           },
           "mcpServerUrl": {
             "type": "string",
-            "description": "Endpoint an MCP client connects to. Published here so callers never build it.",
+            "description": "MCP client endpoint. Use this returned URL instead of constructing one.",
             "examples": ["https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2"]
           },
           "createdAt": {
@@ -14672,7 +17394,7 @@
         ],
         "additionalProperties": false,
         "title": "Workflow MCP server",
-        "description": "A workspace-published MCP server exposing deployed workflows as tools."
+        "description": "A workflow MCP server exposing deployed workflows as tools."
       },
       "CreateWorkflowMcpServerResponse": {
         "type": "object",
@@ -14685,7 +17407,7 @@
         "required": ["data"],
         "additionalProperties": false,
         "title": "Create workflow MCP server response",
-        "description": "The published MCP server.",
+        "description": "The workflow MCP server.",
         "examples": [
           {
             "data": {
@@ -14707,7 +17429,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
-            "description": "Workspace in which to publish the server."
+            "description": "Workspace in which to create the workflow MCP server."
           },
           "name": {
             "type": "string",
@@ -14721,12 +17443,12 @@
             "maxLength": 2000
           },
           "isPublic": {
-            "description": "Whether the server answers MCP clients without a Sim API key. Defaults to false — a public server executes the workflows it publishes for anyone holding its URL.",
+            "description": "Whether the server accepts MCP clients without a Sim API key. Defaults to false; a public server lets anyone holding its URL execute the workflows it exposes.",
             "default": false,
             "type": "boolean"
           },
           "workflowIds": {
-            "description": "Deployed workflows to publish as tools on the new server.",
+            "description": "Deployed workflows to expose as MCP tools on the new server.",
             "maxItems": 100,
             "type": "array",
             "items": {
@@ -14738,7 +17460,7 @@
         "required": ["workspaceId", "name"],
         "additionalProperties": false,
         "title": "Create workflow MCP server request",
-        "description": "A new workspace-published MCP server and the workflows it exposes.",
+        "description": "A new workflow MCP server and deployed workflows to expose as tools.",
         "examples": [
           {
             "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
@@ -14758,7 +17480,7 @@
         "required": ["data"],
         "additionalProperties": false,
         "title": "Get workflow MCP server response",
-        "description": "A single published MCP server.",
+        "description": "One workflow MCP server and its client endpoint.",
         "examples": [
           {
             "data": {
@@ -14782,7 +17504,7 @@
           },
           "serverId": {
             "type": "string",
-            "description": "Server that publishes this tool."
+            "description": "Server exposing this MCP tool."
           },
           "workflowId": {
             "type": "string",
@@ -14824,7 +17546,7 @@
           "status": {
             "type": "string",
             "enum": ["active", "inactive"],
-            "description": "Whether MCP clients can call the tool. `inactive` is a registration that undeploying its workflow archived: it is not callable and its name stays reserved on the server, and the next deploy of the workflow makes it `active` again. Unpublishing an inactive tool removes it for good."
+            "description": "Whether MCP clients can call the tool. Undeploying its workflow archives the registration as `inactive`; it cannot be called and its name stays reserved. Redeploying the workflow makes it `active` again. Undeploying an inactive MCP tool permanently removes its registration."
           }
         },
         "required": [
@@ -14841,7 +17563,7 @@
         ],
         "additionalProperties": false,
         "title": "Workflow MCP tool list item",
-        "description": "A tool a server publishes, as returned by a read. Archived registrations are included with `status: \"inactive\"`."
+        "description": "A tool registration on a workflow MCP server. Archived registrations are included with `status: \"inactive\"`."
       },
       "ListWorkflowMcpToolsResponse": {
         "type": "object",
@@ -14862,17 +17584,17 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           },
           "truncated": {
             "type": "boolean",
-            "description": "Whether the tool limit left this inventory incomplete. The list is unpaginated and `nextCursor` remains null even when truncated. Do not treat a truncated inventory as the complete set of published tools."
+            "description": "Whether the tool limit left this inventory incomplete. The list is unpaginated and nextCursor remains null even when truncated; an incomplete inventory does not represent every registration."
           }
         },
         "required": ["data", "nextCursor", "truncated"],
         "additionalProperties": false,
         "title": "List workflow MCP tools response",
-        "description": "The tools a published MCP server exposes.",
+        "description": "A bounded inventory of tool registrations on the workflow MCP server.",
         "examples": [
           {
             "data": [
@@ -14948,7 +17670,7 @@
         },
         "additionalProperties": false,
         "title": "Update workflow MCP server request",
-        "description": "Merge-patch body for a published MCP server.",
+        "description": "Server fields to change. Omitted fields remain unchanged; `description: null` clears the description.",
         "examples": [
           {
             "isPublic": true
@@ -14960,18 +17682,18 @@
         "properties": {
           "id": {
             "type": "string",
-            "description": "Identifier of the unpublished server."
+            "description": "Identifier of the deleted workflow MCP server."
           },
           "deleted": {
             "type": "boolean",
             "const": true,
-            "description": "Whether the server was unpublished."
+            "description": "Whether the workflow MCP server was deleted."
           }
         },
         "required": ["id", "deleted"],
         "additionalProperties": false,
         "title": "Delete workflow MCP server result",
-        "description": "Unpublish acknowledgement."
+        "description": "Workflow MCP server deletion acknowledgement."
       },
       "DeleteWorkflowMcpServerResponse": {
         "type": "object",
@@ -14984,7 +17706,7 @@
         "required": ["data"],
         "additionalProperties": false,
         "title": "Delete workflow MCP server response",
-        "description": "Acknowledgement that the MCP server was unpublished.",
+        "description": "Acknowledgement that the workflow MCP server was deleted.",
         "examples": [
           {
             "data": {
@@ -15003,7 +17725,7 @@
           },
           "serverId": {
             "type": "string",
-            "description": "Server that publishes this tool."
+            "description": "Server exposing this MCP tool."
           },
           "workflowId": {
             "type": "string",
@@ -15034,7 +17756,7 @@
           },
           "updated": {
             "type": "boolean",
-            "description": "False when the workflow was newly published on this server, true when an existing tool was replaced. Publishing is idempotent per workflow, so a repeat call answers 200 with true rather than conflicting."
+            "description": "False for a new registration, true when an existing registration for this workflow was replaced. Repeating the operation returns 200 with true instead of a duplicate conflict."
           },
           "createdAt": {
             "type": "string",
@@ -15061,7 +17783,7 @@
         ],
         "additionalProperties": false,
         "title": "Workflow MCP tool",
-        "description": "A deployed workflow published as a tool on a workflow-MCP server."
+        "description": "A deployed workflow exposed as a tool on a workflow MCP server."
       },
       "DeployWorkflowMcpToolResponse": {
         "type": "object",
@@ -15073,8 +17795,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Publish workflow as MCP tool response",
-        "description": "The published tool.",
+        "title": "Deploy workflow as MCP tool response",
+        "description": "The deployed MCP tool registration.",
         "examples": [
           {
             "data": {
@@ -15098,7 +17820,7 @@
           "workflowId": {
             "type": "string",
             "minLength": 1,
-            "description": "Deployed workflow to publish. The workflow must already be deployed."
+            "description": "Workflow to expose as an MCP tool. It must already be deployed."
           },
           "toolName": {
             "description": "Name MCP clients call. Normalized to the MCP tool-name grammar, and derived from the workflow name when omitted.",
@@ -15137,8 +17859,8 @@
         },
         "required": ["workflowId"],
         "additionalProperties": false,
-        "title": "Publish workflow as MCP tool request",
-        "description": "The workflow to publish and the tool metadata MCP clients see.",
+        "title": "Deploy workflow as MCP tool request",
+        "description": "The deployed workflow and tool metadata presented to MCP clients.",
         "examples": [
           {
             "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
@@ -15159,7 +17881,7 @@
           },
           "workflowId": {
             "type": "string",
-            "description": "Workflow that is no longer published."
+            "description": "Workflow whose MCP tool registration was removed."
           },
           "deleted": {
             "type": "boolean",
@@ -15169,7 +17891,7 @@
         },
         "required": ["id", "serverId", "workflowId", "deleted"],
         "additionalProperties": false,
-        "title": "Unpublish workflow MCP tool result",
+        "title": "Undeploy workflow MCP tool result",
         "description": "Tool removal acknowledgement."
       },
       "UndeployWorkflowMcpToolResponse": {
@@ -15182,7 +17904,7 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Unpublish workflow MCP tool response",
+        "title": "Undeploy workflow MCP tool response",
         "description": "Acknowledgement that the tool was removed.",
         "examples": [
           {
@@ -15373,10 +18095,15 @@
         },
         "additionalProperties": false,
         "title": "Update credential request",
-        "description": "Replacement display metadata and the write-only fields declared by provider discovery.",
+        "description": "Metadata fields to change, or the complete required fields for a service-account secret rotation. Use List credential providers for the selected provider’s fields.",
         "examples": [
           {
-            "clientSecret": "YOUR_ROTATED_CLIENT_SECRET"
+            "displayName": "Billing automation"
+          },
+          {
+            "clientId": "YOUR_CLIENT_ID",
+            "clientSecret": "YOUR_ROTATED_CLIENT_SECRET",
+            "orgId": "YOUR_ACCOUNT_ID"
           }
         ]
       },
@@ -15515,7 +18242,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -15910,7 +18637,7 @@
             "type": "boolean"
           },
           "visibility": {
-            "description": "Who may supply the value: `user-or-llm`, `user-only`, `llm-only`, or `hidden`.",
+            "description": "Source of the value in a workflow or Agent block: `user-or-llm`, `user-only`, `llm-only`, or `hidden`. A direct Run tool caller may supply non-hidden parameters; Sim supplies hidden ones.",
             "type": "string"
           },
           "description": {
@@ -16030,7 +18757,7 @@
           "hostedApiKey": {
             "type": "string",
             "enum": ["always", "conditional", "none"],
-            "description": "Whether Sim supplies the API key on THIS deployment: `always`, `conditional` (only for some parameter combinations), or `none` (bring your own). Self-hosted deployments supply no hosted keys, so every tool reports `none` there regardless of what it declares."
+            "description": "API-key hosting on this deployment: `always`, `conditional` for some parameter combinations, or `none` when Sim does not supply a key. Supply your own key only if the tool requires one. Self-hosted deployments report `none` for every tool."
           },
           "oauth": {
             "description": "OAuth requirement, when the tool has one.",
@@ -16093,7 +18820,7 @@
             "type": "boolean"
           },
           "visibility": {
-            "description": "Who may supply the value: `user-or-llm`, `user-only`, `llm-only`, or `hidden`.",
+            "description": "Source of the value in a workflow or Agent block: `user-or-llm`, `user-only`, `llm-only`, or `hidden`. A direct Run tool caller may supply non-hidden parameters; Sim supplies hidden ones.",
             "type": "string"
           },
           "description": {
@@ -16672,7 +19399,7 @@
           "hostedApiKey": {
             "type": "string",
             "enum": ["always", "conditional", "none"],
-            "description": "Whether Sim supplies the API key on THIS deployment: `always`, `conditional` (only for some parameter combinations), or `none` (bring your own). Self-hosted deployments supply no hosted keys, so every tool reports `none` there regardless of what it declares."
+            "description": "API-key hosting on this deployment: `always`, `conditional` for some parameter combinations, or `none` when Sim does not supply a key. Supply your own key only if the tool requires one. Self-hosted deployments report `none` for every tool."
           },
           "oauth": {
             "description": "OAuth requirement, when the tool has one.",
@@ -16722,7 +19449,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -16872,7 +19599,7 @@
           },
           "input": {
             "default": {},
-            "description": "Tool arguments keyed by published parameter IDs. For `user-only` parameters, a whole-value `{{VAR_NAME}}` reference resolves a workspace environment variable. Other values pass through unchanged.",
+            "description": "Arguments keyed by published parameter IDs. Hidden and undeclared fields are rejected. Send connected credentials as top-level `credentialId`, not `input.credential`, `input.credentialId`, or `input.oauthCredential`. Whole-value `{{VAR_NAME}}` references resolve environment variables only for `user-only` parameters; other values pass through unchanged.",
             "type": "object",
             "propertyNames": {
               "type": "string"
@@ -16882,13 +19609,13 @@
             }
           },
           "credentialId": {
-            "description": "Credential to authenticate with. Required when the tool declares an OAuth requirement; the workspace credentials list names the candidates.",
+            "description": "Connected credential to authenticate with. Required for tools declaring required OAuth or a required credential-selector parameter. Use List credentials to find candidates; do not send credential aliases inside `input`.",
             "type": "string",
             "minLength": 1,
             "maxLength": 255
           },
           "timeoutSeconds": {
-            "description": "How long to wait for the tool before abandoning the call.",
+            "description": "Maximum wait time in seconds; defaults to 120 and cannot exceed 300. Timeout does not guarantee that a third-party side effect was cancelled.",
             "type": "integer",
             "minimum": 1,
             "maximum": 300
@@ -16897,7 +19624,7 @@
         "required": ["workspaceId"],
         "additionalProperties": false,
         "title": "Run tool request",
-        "description": "Workspace, arguments, and the credential to authenticate with.",
+        "description": "Workspace, accepted tool arguments, and optional connected credential. Hidden fields and credential aliases inside input are rejected.",
         "examples": [
           {
             "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
@@ -17195,7 +19922,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -17208,7 +19935,7 @@
               {
                 "connectorType": "google_drive",
                 "name": "Google Drive",
-                "description": "Sync documents from a Google Drive folder.",
+                "description": "Sync documents from Google Drive",
                 "auth": {
                   "mode": "oauth"
                 }
@@ -17221,39 +19948,134 @@
               {
                 "connectorType": "google_drive",
                 "name": "Google Drive",
-                "description": "Sync documents from a Google Drive folder.",
+                "description": "Sync documents from Google Drive",
                 "version": "1.0.0",
                 "auth": {
                   "mode": "oauth",
                   "provider": "google-drive",
-                  "requiredScopes": ["https://www.googleapis.com/auth/drive.readonly"]
+                  "requiredScopes": ["https://www.googleapis.com/auth/drive"]
                 },
                 "configFields": [
+                  {
+                    "id": "adminEmail",
+                    "title": "Crawl as",
+                    "type": "short-input",
+                    "placeholder": "admin@yourcompany.com",
+                    "required": false,
+                    "description": "The Google Workspace user this service account acts as when fetching content for connected members."
+                  },
+                  {
+                    "id": "userEmails",
+                    "title": "Users",
+                    "type": "short-input",
+                    "placeholder": "All active Google Workspace users",
+                    "required": false,
+                    "description": "Optional primary email addresses, separated by commas (up to 100). Leave blank to index all active users across this Google Workspace customer.",
+                    "multi": true
+                  },
+                  {
+                    "id": "openSharing",
+                    "title": "Openly shared files",
+                    "type": "dropdown",
+                    "placeholder": "Keep out of search",
+                    "required": false,
+                    "description": "Files shared beyond named people and groups. Kept out of search by default, because a domain-wide or public share is more often an accident than an intention. Never applies to link-only shares, which stay unsearchable.",
+                    "options": [
+                      {
+                        "label": "Keep out of search",
+                        "id": "none"
+                      },
+                      {
+                        "label": "Anyone in the domain can find",
+                        "id": "domain"
+                      },
+                      {
+                        "label": "Anyone can find",
+                        "id": "anyone"
+                      }
+                    ]
+                  },
                   {
                     "id": "folderSelector",
-                    "title": "Folder",
+                    "title": "Folders",
                     "type": "selector",
-                    "selectorKey": "google-drive-folder",
+                    "placeholder": "Select one or more folders (optional)",
+                    "required": false,
+                    "description": "Includes files in each selected folder and its accessible subfolders.",
+                    "selectorKey": "google.drive",
                     "mimeType": "application/vnd.google-apps.folder",
                     "mode": "basic",
                     "canonicalParamId": "folderId",
-                    "required": true
+                    "multi": true
                   },
                   {
-                    "id": "manualFolderId",
-                    "title": "Folder ID",
+                    "id": "folderId",
+                    "title": "Folder IDs",
                     "type": "short-input",
-                    "placeholder": "Enter the folder ID",
+                    "placeholder": "e.g. 1aBcDeFg…, 2cDeFgHi… (comma-separated for multiple)",
+                    "required": false,
+                    "description": "Includes files in each selected folder and its accessible subfolders.",
                     "mode": "advanced",
-                    "canonicalParamId": "folderId"
+                    "canonicalParamId": "folderId",
+                    "multi": true
+                  },
+                  {
+                    "id": "fileType",
+                    "title": "File Type",
+                    "type": "dropdown",
+                    "required": false,
+                    "options": [
+                      {
+                        "label": "All supported files",
+                        "id": "all"
+                      },
+                      {
+                        "label": "Google Docs only",
+                        "id": "documents"
+                      },
+                      {
+                        "label": "Google Sheets only",
+                        "id": "spreadsheets"
+                      },
+                      {
+                        "label": "Google Slides only",
+                        "id": "presentations"
+                      },
+                      {
+                        "label": "Plain text files only",
+                        "id": "text"
+                      }
+                    ]
+                  },
+                  {
+                    "id": "maxFiles",
+                    "title": "Max Files",
+                    "type": "short-input",
+                    "placeholder": "e.g. 500 (default: unlimited)",
+                    "required": false
                   }
                 ],
-                "supportsIncrementalSync": true,
+                "supportsIncrementalSync": false,
                 "tagDefinitions": [
                   {
-                    "id": "owner",
+                    "id": "owners",
                     "displayName": "Owner",
                     "fieldType": "text"
+                  },
+                  {
+                    "id": "fileType",
+                    "displayName": "File Type",
+                    "fieldType": "text"
+                  },
+                  {
+                    "id": "lastModified",
+                    "displayName": "Last Modified",
+                    "fieldType": "date"
+                  },
+                  {
+                    "id": "starred",
+                    "displayName": "Starred",
+                    "fieldType": "boolean"
                   }
                 ]
               }
@@ -17420,7 +20242,7 @@
               },
               "hideDeployChatbot": {
                 "type": "boolean",
-                "description": "Prevent publishing a workflow as a chat."
+                "description": "Prevent deploying a workflow as a chat."
               },
               "allowedChatDeployAuthTypes": {
                 "anyOf": [
@@ -17594,11 +20416,11 @@
           },
           "isDefault": {
             "type": "boolean",
-            "description": "Whether this is the organization default, which applies to everyone across all its workspaces regardless of member assignments."
+            "description": "Whether this is the organization fallback group. It governs a human caller with no applicable workspace-specific group; its own membership assignments do not limit its audience. Organization-level actions use the default group."
           },
           "membershipMode": {
             "type": "string",
-            "description": "An empty inherit group governs everyone in its workspaces; an empty explicit group governs nobody."
+            "description": "When no explicit assignments exist, an `inherit` group governs every member in its targeted workspaces. An empty `explicit` group, including a SCIM-managed group, governs nobody."
           },
           "workspaceIds": {
             "type": "array",
@@ -17639,7 +20461,7 @@
         ],
         "additionalProperties": false,
         "title": "Permission group",
-        "description": "An organization permission group and its resolved settings."
+        "description": "An organization permission group and its resolved settings for human callers. Workspace API keys use their workspace role and operation policy without a user permission group."
       },
       "ListPermissionGroupsResponse": {
         "type": "object",
@@ -17660,13 +20482,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List Permission Groups response",
-        "description": "List Permission Groups result.",
+        "title": "List permission groups response",
+        "description": "A page of permission groups with resolved settings.",
         "examples": [
           {
             "data": [
@@ -17743,8 +20565,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Create Permission Group response",
-        "description": "Create Permission Group result.",
+        "title": "Create permission group response",
+        "description": "The created group, its resolved settings, and workspace scope.",
         "examples": [
           {
             "data": {
@@ -17952,7 +20774,7 @@
               },
               "hideDeployChatbot": {
                 "type": "boolean",
-                "description": "Prevent publishing a workflow as a chat."
+                "description": "Prevent deploying a workflow as a chat."
               },
               "allowedChatDeployAuthTypes": {
                 "anyOf": [
@@ -18092,8 +20914,8 @@
         },
         "required": ["name"],
         "additionalProperties": false,
-        "title": "Create Permission Group request",
-        "description": "Create Permission Group inputs.",
+        "title": "Create permission group request",
+        "description": "Group name, initial restrictions, and default or workspace-specific scope.",
         "examples": [
           {
             "name": "Restricted",
@@ -18111,8 +20933,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Get Permission Group response",
-        "description": "Get Permission Group result.",
+        "title": "Get permission group response",
+        "description": "The group, its resolved settings, and workspace scope.",
         "examples": [
           {
             "data": {
@@ -18186,8 +21008,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Update Permission Group response",
-        "description": "Update Permission Group result.",
+        "title": "Update permission group response",
+        "description": "The updated group with resolved settings and workspace scope.",
         "examples": [
           {
             "data": {
@@ -18402,7 +21224,7 @@
               },
               "hideDeployChatbot": {
                 "type": "boolean",
-                "description": "Prevent publishing a workflow as a chat."
+                "description": "Prevent deploying a workflow as a chat."
               },
               "allowedChatDeployAuthTypes": {
                 "anyOf": [
@@ -18541,8 +21363,8 @@
           }
         },
         "additionalProperties": false,
-        "title": "Update Permission Group request",
-        "description": "Update Permission Group inputs.",
+        "title": "Update permission group request",
+        "description": "Group fields and restriction keys to change; supplied lists replace their contents.",
         "examples": [
           {
             "description": "Restricted workspace access"
@@ -18577,8 +21399,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Delete Permission Group response",
-        "description": "Delete Permission Group result.",
+        "title": "Delete permission group response",
+        "description": "Acknowledgement that the group and its assignments were deleted.",
         "examples": [
           {
             "data": {
@@ -18663,13 +21485,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List Permission Group Members response",
-        "description": "List Permission Group Members result.",
+        "title": "List permission group members response",
+        "description": "A page of explicit group membership assignments.",
         "examples": [
           {
             "data": [
@@ -18738,8 +21560,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Add Permission Group Member response",
-        "description": "Add Permission Group Member result.",
+        "title": "Add permission group member response",
+        "description": "The new explicit membership assignment.",
         "examples": [
           {
             "data": {
@@ -18764,8 +21586,8 @@
         },
         "required": ["userId"],
         "additionalProperties": false,
-        "title": "Add Permission Group Member request",
-        "description": "Add Permission Group Member inputs.",
+        "title": "Add permission group member request",
+        "description": "The organization member to assign to this group.",
         "examples": [
           {
             "userId": "user-123"
@@ -18800,8 +21622,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Remove Permission Group Member response",
-        "description": "Remove Permission Group Member result.",
+        "title": "Remove permission group member response",
+        "description": "Acknowledgement that the explicit assignment was removed.",
         "examples": [
           {
             "data": {
@@ -18838,8 +21660,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Bulk Add Permission Group Members response",
-        "description": "Bulk Add Permission Group Members result.",
+        "title": "Bulk add permission group members response",
+        "description": "Counts of added members and existing assignments skipped.",
         "examples": [
           {
             "data": {
@@ -18868,8 +21690,8 @@
           }
         },
         "additionalProperties": false,
-        "title": "Bulk Add Permission Group Members request",
-        "description": "Bulk Add Permission Group Members inputs.",
+        "title": "Bulk add permission group members request",
+        "description": "Selected organization members or the entire current organization roster.",
         "examples": [
           {
             "userIds": ["user-123"]
@@ -18938,13 +21760,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List Organizations response",
-        "description": "List Organizations result.",
+        "title": "List organizations response",
+        "description": "A page of organizations and the acting user’s role in each.",
         "examples": [
           {
             "data": [
@@ -18971,8 +21793,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Get Organization response",
-        "description": "Get Organization result.",
+        "title": "Get organization response",
+        "description": "Organization metadata and the acting user’s role.",
         "examples": [
           {
             "data": {
@@ -19022,13 +21844,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List Organization Workspaces response",
-        "description": "List Organization Workspaces result.",
+        "title": "List organization workspaces response",
+        "description": "A page of active workspaces owned by the organization.",
         "examples": [
           {
             "data": [
@@ -19092,13 +21914,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List Organization Members response",
-        "description": "List Organization Members result.",
+        "title": "List organization members response",
+        "description": "A page of organization members and their organization roles.",
         "examples": [
           {
             "data": [
@@ -19124,8 +21946,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Update Organization Member response",
-        "description": "Update Organization Member result.",
+        "title": "Update organization member response",
+        "description": "The member with the updated organization role.",
         "examples": [
           {
             "data": {
@@ -19149,8 +21971,8 @@
         },
         "required": ["role"],
         "additionalProperties": false,
-        "title": "Update Organization Member body",
-        "description": "Update Organization Member input.",
+        "title": "Update organization member body",
+        "description": "The new organization role for this member.",
         "examples": [
           {
             "role": "admin"
@@ -19185,8 +22007,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Remove Organization Member response",
-        "description": "Remove Organization Member result.",
+        "title": "Remove organization member response",
+        "description": "Acknowledgement that organization access was removed.",
         "examples": [
           {
             "data": {
@@ -19278,13 +22100,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List Organization Invitations response",
-        "description": "List Organization Invitations result.",
+        "title": "List organization invitations response",
+        "description": "A page of invitations, including their current status.",
         "examples": [
           {
             "data": [
@@ -19314,8 +22136,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Create Organization Invitation response",
-        "description": "Create Organization Invitation result.",
+        "title": "Create organization invitation response",
+        "description": "The pending organization invitation.",
         "examples": [
           {
             "data": {
@@ -19352,8 +22174,8 @@
         },
         "required": ["email"],
         "additionalProperties": false,
-        "title": "Create Organization Invitation body",
-        "description": "Create Organization Invitation input.",
+        "title": "Create organization invitation body",
+        "description": "Invitee email and organization role to offer.",
         "examples": [
           {
             "email": "member@example.com",
@@ -19371,8 +22193,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Get Organization Invitation response",
-        "description": "Get Organization Invitation result.",
+        "title": "Get organization invitation response",
+        "description": "Invitation metadata without its acceptance token.",
         "examples": [
           {
             "data": {
@@ -19443,12 +22265,12 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List Organization Invitation Workspaces response",
+        "title": "List organization invitation workspaces response",
         "description": "Workspace grants retained on an invitation.",
         "examples": [
           {
@@ -19474,8 +22296,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Resend Organization Invitation response",
-        "description": "Resend Organization Invitation result.",
+        "title": "Resend organization invitation response",
+        "description": "The pending invitation with its renewed expiry.",
         "examples": [
           {
             "data": {
@@ -19494,8 +22316,8 @@
       },
       "ResendOrganizationInvitationBody": {
         "default": {},
-        "title": "Resend Organization Invitation body",
-        "description": "Resend Organization Invitation input.",
+        "title": "Resend organization invitation body",
+        "description": "An empty JSON object; the pending invitation supplies the recipient and role.",
         "examples": [{}],
         "type": "object",
         "properties": {},
@@ -19529,8 +22351,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Revoke Organization Invitation response",
-        "description": "Revoke Organization Invitation result.",
+        "title": "Revoke organization invitation response",
+        "description": "Acknowledgement that the pending invitation was cancelled.",
         "examples": [
           {
             "data": {
@@ -19636,13 +22458,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List SSO Providers response",
-        "description": "List SSO Providers result."
+        "title": "List SSO providers response",
+        "description": "A page of identity providers with redacted configuration."
       },
       "GetSsoProviderResponse": {
         "type": "object",
@@ -19731,8 +22553,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Get SSO Provider response",
-        "description": "Get SSO Provider result."
+        "title": "Get SSO provider response",
+        "description": "The identity provider with redacted configuration."
       },
       "SaveSsoProviderResponse": {
         "type": "object",
@@ -19762,8 +22584,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Save SSO Provider response",
-        "description": "Save SSO Provider result."
+        "title": "Save SSO provider response",
+        "description": "The saved provider ID, protocol, and whether it was created."
       },
       "SaveSsoProviderBody": {
         "oneOf": [
@@ -20032,8 +22854,8 @@
             "additionalProperties": false
           }
         ],
-        "title": "Save SSO Provider body",
-        "description": "Configuration accepted by Save SSO Provider."
+        "title": "Save SSO provider body",
+        "description": "Provider protocol, verified domain, and identity-provider configuration. Omission behavior is field-specific."
       },
       "DeleteSsoProviderResponse": {
         "type": "object",
@@ -20059,8 +22881,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Delete SSO Provider response",
-        "description": "Delete SSO Provider result."
+        "title": "Delete SSO provider response",
+        "description": "Acknowledgement that the identity provider was removed."
       },
       "SetPrimarySsoProviderResponse": {
         "type": "object",
@@ -20085,13 +22907,13 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Set Primary SSO Provider response",
-        "description": "Set Primary SSO Provider result."
+        "title": "Set primary SSO provider response",
+        "description": "The provider selected for its verified domain."
       },
       "SetPrimarySsoProviderBody": {
         "default": {},
-        "title": "Set Primary SSO Provider body",
-        "description": "Configuration accepted by Set Primary SSO Provider.",
+        "title": "Set primary SSO provider body",
+        "description": "An empty JSON object; the path identifies the provider to make primary.",
         "type": "object",
         "properties": {},
         "additionalProperties": false
@@ -20122,8 +22944,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Get SSO Policy response",
-        "description": "Get SSO Policy result."
+        "title": "Get SSO policy response",
+        "description": "The stored SSO requirement and its effective enforcement state."
       },
       "UpdateSsoPolicyResponse": {
         "type": "object",
@@ -20151,8 +22973,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Update SSO Policy response",
-        "description": "Update SSO Policy result."
+        "title": "Update SSO policy response",
+        "description": "The saved SSO requirement and its effective enforcement state."
       },
       "UpdateSsoPolicyBody": {
         "type": "object",
@@ -20164,8 +22986,8 @@
         },
         "required": ["requireSso"],
         "additionalProperties": false,
-        "title": "Update SSO Policy body",
-        "description": "Configuration accepted by Update SSO Policy."
+        "title": "Update SSO policy body",
+        "description": "Whether future sign-ins must use SSO."
       },
       "ListOrganizationDomainsResponse": {
         "type": "object",
@@ -20239,13 +23061,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List Organization Domains response",
-        "description": "List Organization Domains result."
+        "title": "List organization domains response",
+        "description": "A page of domain claims; pending challenges are limited to Admins."
       },
       "AddOrganizationDomainResponse": {
         "type": "object",
@@ -20303,8 +23125,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Add Organization Domain response",
-        "description": "Add Organization Domain result."
+        "title": "Add organization domain response",
+        "description": "The domain claim and its pending DNS challenge, when applicable."
       },
       "AddOrganizationDomainBody": {
         "type": "object",
@@ -20318,8 +23140,8 @@
         },
         "required": ["domain"],
         "additionalProperties": false,
-        "title": "Add Organization Domain body",
-        "description": "Configuration accepted by Add Organization Domain."
+        "title": "Add organization domain body",
+        "description": "The domain to claim and verify."
       },
       "VerifyOrganizationDomainResponse": {
         "type": "object",
@@ -20377,13 +23199,13 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Verify Organization Domain response",
-        "description": "Verify Organization Domain result."
+        "title": "Verify organization domain response",
+        "description": "The domain claim after ownership verification."
       },
       "VerifyOrganizationDomainBody": {
         "default": {},
-        "title": "Verify Organization Domain body",
-        "description": "Configuration accepted by Verify Organization Domain.",
+        "title": "Verify organization domain body",
+        "description": "An empty JSON object; verification uses the claim’s current DNS challenge.",
         "type": "object",
         "properties": {},
         "additionalProperties": false
@@ -20412,8 +23234,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Remove Organization Domain response",
-        "description": "Remove Organization Domain result."
+        "title": "Remove organization domain response",
+        "description": "Acknowledgement that the domain claim was removed."
       },
       "ListCredentialMembersResponse": {
         "type": "object",
@@ -20519,13 +23341,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List Credential Members response",
-        "description": "List Credential Members result."
+        "title": "List credential members response",
+        "description": "A page of explicit and inherited credential grants."
       },
       "UpsertCredentialMemberResponse": {
         "type": "object",
@@ -20555,8 +23377,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Upsert Credential Member response",
-        "description": "Upsert Credential Member result."
+        "title": "Upsert credential member response",
+        "description": "The saved credential role and whether a grant was created."
       },
       "UpsertCredentialMemberBody": {
         "type": "object",
@@ -20575,8 +23397,8 @@
         },
         "required": ["userId", "role"],
         "additionalProperties": false,
-        "title": "Upsert Credential Member body",
-        "description": "Configuration accepted by Upsert Credential Member."
+        "title": "Upsert credential member body",
+        "description": "The current workspace member and credential role to grant."
       },
       "RemoveCredentialMemberResponse": {
         "type": "object",
@@ -20602,8 +23424,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Remove Credential Member response",
-        "description": "Remove Credential Member result."
+        "title": "Remove credential member response",
+        "description": "Acknowledgement that the explicit credential grant was revoked."
       },
       "V2WorkspacePermissionConfig": {
         "type": "object",
@@ -20764,7 +23586,7 @@
                   },
                   "hideDeployChatbot": {
                     "type": "boolean",
-                    "description": "Prevent publishing a workflow as a chat."
+                    "description": "Prevent deploying a workflow as a chat."
                   },
                   "allowedChatDeployAuthTypes": {
                     "anyOf": [
@@ -20981,7 +23803,7 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Get Workspace Permission Config response",
+        "title": "Get workspace permission config response",
         "description": "Configuration for the acting caller only.",
         "examples": [
           {
@@ -21095,7 +23917,7 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Create Workspace Invitations response",
+        "title": "Create workspace invitations response",
         "description": "Successful recipients remain committed when later recipients fail.",
         "examples": [
           {
@@ -21147,7 +23969,7 @@
         },
         "required": ["emails"],
         "additionalProperties": false,
-        "title": "Create Workspace Invitations body",
+        "title": "Create workspace invitations body",
         "description": "Recipients and the access to grant.",
         "examples": [
           {
@@ -21194,8 +24016,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Get Organization Member Credit Limit response",
-        "description": "Get Organization Member Credit Limit result.",
+        "title": "Get organization member credit limit response",
+        "description": "The person’s current credit cap and billing-period consumption.",
         "examples": [
           {
             "data": {
@@ -21236,8 +24058,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Update Organization Member Credit Limit response",
-        "description": "Update Organization Member Credit Limit result.",
+        "title": "Update organization member credit limit response",
+        "description": "The saved credit cap, or null when the cap was cleared.",
         "examples": [
           {
             "data": {
@@ -21265,7 +24087,7 @@
         },
         "required": ["creditLimit"],
         "additionalProperties": false,
-        "title": "Update Organization Member Credit Limit body",
+        "title": "Update organization member credit limit body",
         "description": "Credit cap in whole credits; null clears the cap.",
         "examples": [
           {
@@ -21381,8 +24203,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Get Organization Usage Summary response",
-        "description": "Get Organization Usage Summary result.",
+        "title": "Get organization usage summary response",
+        "description": "Reporting bounds, pooled credits, and chronological usage buckets.",
         "examples": [
           {
             "data": {
@@ -21508,8 +24330,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Get Organization Usage Breakdown response",
-        "description": "Get Organization Usage Breakdown result.",
+        "title": "Get organization usage breakdown response",
+        "description": "Ranked usage groups and the combined remainder.",
         "examples": [
           {
             "data": {
@@ -21617,13 +24439,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List Organization Usage Events response",
-        "description": "List Organization Usage Events result.",
+        "title": "List organization usage events response",
+        "description": "A page of usage events, including zero-cost activity.",
         "examples": [
           {
             "data": [
@@ -21903,13 +24725,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "Discover Workspace Access Requests response",
-        "description": "Discover Workspace Access Requests result.",
+        "title": "Discover workspace access requests response",
+        "description": "A page of access targets and the acting user’s current access state.",
         "examples": [
           {
             "data": [
@@ -22279,13 +25101,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List My Workspace Access Requests response",
-        "description": "List My Workspace Access Requests result.",
+        "title": "List my workspace access requests response",
+        "description": "A page of the acting user’s workspace and member-credit requests.",
         "examples": [
           {
             "data": [
@@ -22325,8 +25147,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Create Workspace Access Request response",
-        "description": "Create Workspace Access Request result.",
+        "title": "Create workspace access request response",
+        "description": "The new request, matching pending request, or existing request closed because access became available.",
         "examples": [
           {
             "data": {
@@ -22564,8 +25386,8 @@
         },
         "required": ["target"],
         "additionalProperties": false,
-        "title": "Create Workspace Access Request body",
-        "description": "Inputs for this operation.",
+        "title": "Create workspace access request body",
+        "description": "A discovered access target and an optional reason for the request.",
         "examples": [
           {
             "target": {
@@ -22586,8 +25408,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Cancel Workspace Access Request response",
-        "description": "Cancel Workspace Access Request result.",
+        "title": "Cancel workspace access request response",
+        "description": "The cancelled request, or the unchanged request if already resolved.",
         "examples": [
           {
             "data": {
@@ -22633,13 +25455,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "Discover Organization Access Requests response",
-        "description": "Discover Organization Access Requests result.",
+        "title": "Discover organization access requests response",
+        "description": "A page of access targets and the acting user’s current access state.",
         "examples": [
           {
             "data": [
@@ -22677,13 +25499,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List My Organization Access Requests response",
-        "description": "List My Organization Access Requests result.",
+        "title": "List my organization access requests response",
+        "description": "A page of the acting user’s organization and member-credit requests.",
         "examples": [
           {
             "data": [
@@ -22723,8 +25545,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Create Organization Access Request response",
-        "description": "Create Organization Access Request result.",
+        "title": "Create organization access request response",
+        "description": "The new request, matching pending request, or existing request closed because access became available.",
         "examples": [
           {
             "data": {
@@ -22962,8 +25784,8 @@
         },
         "required": ["target"],
         "additionalProperties": false,
-        "title": "Create Organization Access Request body",
-        "description": "Inputs for this operation.",
+        "title": "Create organization access request body",
+        "description": "A discovered access target and an optional reason for the request.",
         "examples": [
           {
             "target": {
@@ -22984,8 +25806,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Cancel Organization Access Request response",
-        "description": "Cancel Organization Access Request result.",
+        "title": "Cancel organization access request response",
+        "description": "The cancelled request, or the unchanged request if already resolved.",
         "examples": [
           {
             "data": {
@@ -23031,13 +25853,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "List Organization Access Requests response",
-        "description": "List Organization Access Requests result.",
+        "title": "List organization access requests response",
+        "description": "A page of requests across the organization for Admin review.",
         "examples": [
           {
             "data": [
@@ -24196,8 +27018,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Preview Organization Access Request response",
-        "description": "Preview Organization Access Request result.",
+        "title": "Preview organization access request response",
+        "description": "The proposed group or credit-cap change, affected audience, and fingerprint.",
         "examples": [
           {
             "data": {
@@ -24260,8 +27082,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Resolve Organization Access Request response",
-        "description": "Resolve Organization Access Request result.",
+        "title": "Resolve organization access request response",
+        "description": "The applied or declined request, or its unchanged resolved state.",
         "examples": [
           {
             "data": {
@@ -24333,8 +27155,8 @@
             "additionalProperties": false
           }
         ],
-        "title": "Resolve Organization Access Request body",
-        "description": "Inputs for this operation.",
+        "title": "Resolve organization access request body",
+        "description": "Apply the reviewed fingerprint, with a higher credit cap when applicable, or decline with a reason.",
         "examples": [
           {
             "action": "apply",
@@ -24363,8 +27185,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Get Organization Access Request Settings response",
-        "description": "Get Organization Access Request Settings result.",
+        "title": "Get organization access request settings response",
+        "description": "Whether new requests and approvals are allowed.",
         "examples": [
           {
             "data": {
@@ -24383,8 +27205,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "Update Organization Access Request Settings response",
-        "description": "Update Organization Access Request Settings result.",
+        "title": "Update organization access request settings response",
+        "description": "The saved setting for new requests and approvals.",
         "examples": [
           {
             "data": {
@@ -24403,8 +27225,8 @@
         },
         "required": ["allowRequests"],
         "additionalProperties": false,
-        "title": "Update Organization Access Request Settings body",
-        "description": "Inputs for this operation.",
+        "title": "Update organization access request settings body",
+        "description": "Whether new requests and approvals are allowed.",
         "examples": [
           {
             "allowRequests": false
diff --git a/apps/docs/openapi-v2-tables.json b/apps/docs/openapi-v2-tables.json
index 00a5cdccb61..3fd0ea14c17 100644
--- a/apps/docs/openapi-v2-tables.json
+++ b/apps/docs/openapi-v2-tables.json
@@ -38,7 +38,7 @@
     "/api/v2/tables": {
       "get": {
         "operationId": "listTables",
-        "summary": "List Tables",
+        "summary": "List tables",
         "description": "List active tables with folder filtering, search, sorting, and cursor pagination. Use `scope=archived` to find tables available for restoration. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.list",
         "x-oauth-scope": "api:read",
@@ -94,10 +94,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "createdAt",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -187,7 +187,7 @@
       },
       "post": {
         "operationId": "createTable",
-        "summary": "Create Table",
+        "summary": "Create table",
         "description": "Create a table with a typed column schema and optional folder placement.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.create",
         "x-oauth-scope": "api:write",
@@ -199,6 +199,29 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateTableRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "Customers",
+                    "description": "Customer accounts and lifecycle state.",
+                    "schema": {
+                      "columns": [
+                        {
+                          "name": "email",
+                          "type": "string",
+                          "unique": true
+                        },
+                        {
+                          "name": "status",
+                          "type": "string"
+                        }
+                      ]
+                    }
+                  }
+                }
               }
             }
           }
@@ -261,7 +284,7 @@
     "/api/v2/tables/{tableId}": {
       "get": {
         "operationId": "getTable",
-        "summary": "Get Table",
+        "summary": "Get table",
         "description": "Get a table with its metadata, column schema, locks, and current job. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.read",
         "x-oauth-scope": "api:read",
@@ -340,8 +363,8 @@
       },
       "delete": {
         "operationId": "deleteTable",
-        "summary": "Delete Table",
-        "description": "Archive a table while retaining its rows. Use List Tables with `scope=archived` to find it and Restore Table to recover it.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete table",
+        "description": "Archive a table while retaining its rows. Use List tables with `scope=archived` to find it and Restore table to recover it.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Tables"],
@@ -419,7 +442,7 @@
       },
       "patch": {
         "operationId": "updateTable",
-        "summary": "Update Table",
+        "summary": "Update table",
         "description": "Rename a table, edit its description, or move it to a folder. Fields are saved independently: a failed request may leave partial changes. `error.details.applied` lists saved fields; retry only the remaining fields. If absent, nothing changed. Lock flags are read-only. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.update",
         "x-oauth-scope": "api:write",
@@ -444,6 +467,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateTableRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "EnterpriseCustomers",
+                    "folderPath": "/Sales"
+                  }
+                }
               }
             }
           }
@@ -506,7 +539,7 @@
     "/api/v2/tables/{tableId}/columns": {
       "post": {
         "operationId": "addTableColumn",
-        "summary": "Add Column",
+        "summary": "Add column",
         "description": "Add a typed column and return the complete resulting table schema.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.columns.add",
         "x-oauth-scope": "api:write",
@@ -531,6 +564,18 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/AddTableColumnRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "column": {
+                      "name": "plan",
+                      "type": "string"
+                    }
+                  }
+                }
               }
             }
           }
@@ -591,7 +636,7 @@
       },
       "patch": {
         "operationId": "updateTableColumn",
-        "summary": "Update Column",
+        "summary": "Update column",
         "description": "Update a column by name and return the complete schema. Renames update rows, views, and workflow-group references keyed by column ID. Workflow Table blocks keep their authored `filter`, `order`, and `data` JSON unchanged. Bound blocks still referencing the old name appear in `unmigrated`; edit them with Apply Workflow Operations to prevent failures on their next run.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.columns.update",
         "x-oauth-scope": "api:write",
@@ -616,6 +661,18 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateTableColumnRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "columnName": "plan",
+                    "updates": {
+                      "name": "subscriptionPlan"
+                    }
+                  }
+                }
               }
             }
           }
@@ -638,6 +695,40 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2UpdateTableColumnResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "columns": [
+                          {
+                            "id": "col_name",
+                            "name": "name",
+                            "type": "string",
+                            "required": true,
+                            "unique": false
+                          },
+                          {
+                            "id": "col_plan",
+                            "name": "subscriptionPlan",
+                            "type": "string",
+                            "required": false,
+                            "unique": false
+                          }
+                        ],
+                        "unmigrated": [
+                          {
+                            "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                            "workflowName": "Weekly digest",
+                            "blockId": "blk_9c1d3f5a7e2b4068a0c2e4f6b8d0f193",
+                            "blockName": "Query plans",
+                            "fields": ["filter"]
+                          }
+                        ]
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -676,7 +767,7 @@
       },
       "delete": {
         "operationId": "deleteTableColumn",
-        "summary": "Delete Column",
+        "summary": "Delete column",
         "description": "Delete a column by name while preserving at least one table column.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.columns.delete",
         "x-oauth-scope": "api:write",
@@ -701,6 +792,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/DeleteTableColumnRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "columnName": "legacyStatus"
+                  }
+                }
               }
             }
           }
@@ -763,8 +863,8 @@
     "/api/v2/tables/{tableId}/rows": {
       "get": {
         "operationId": "listTableRows",
-        "summary": "List Rows",
-        "description": "List rows in default order with cursor pagination. Pages default to a 5 MB limit and may contain fewer rows than requested; continue until `nextCursor` is null. Use Query Rows for filtering and sorting. `includeRunState=true` adds per-group run outcomes and reduces the row limit.\n\nOAuth scope: `api:read`.",
+        "summary": "List rows",
+        "description": "List rows in default order with cursor pagination. Pages default to a 5 MiB limit and may contain fewer rows than requested; continue until `nextCursor` is null. Use Query rows for filtering and sorting. `includeRunState=true` adds per-group run outcomes and reduces the row limit.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.rows.list",
         "x-oauth-scope": "api:read",
         "tags": ["Tables"],
@@ -820,9 +920,9 @@
             "name": "includeRunState",
             "in": "query",
             "required": false,
-            "description": "Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it only when asked. Caps `limit` at 200.",
+            "description": "Include per-workflow-group run outcomes on every row. Off by default. Caps `limit` at 200. Run state above 2 MiB returns `413`; request fewer rows or omit run state.",
             "schema": {
-              "description": "Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it only when asked. Caps `limit` at 200.",
+              "description": "Include per-workflow-group run outcomes on every row. Off by default. Caps `limit` at 200. Run state above 2 MiB returns `413`; request fewer rows or omit run state.",
               "type": "boolean"
             }
           }
@@ -861,6 +961,9 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "413": {
+            "$ref": "#/components/responses/PayloadTooLarge"
+          },
           "429": {
             "$ref": "#/components/responses/RateLimited"
           },
@@ -874,7 +977,7 @@
       },
       "post": {
         "operationId": "createTableRows",
-        "summary": "Create Rows",
+        "summary": "Create rows",
         "description": "Insert one row with a data object or insert a bounded batch with a rows array. Cell keys are column names.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.rows.create",
         "x-oauth-scope": "api:write",
@@ -899,6 +1002,18 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateTableRowsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "data": {
+                      "email": "jane@example.com",
+                      "status": "active"
+                    }
+                  }
+                }
               }
             }
           }
@@ -959,7 +1074,7 @@
       },
       "patch": {
         "operationId": "updateTableRows",
-        "summary": "Update Rows by Filter",
+        "summary": "Update rows by filter",
         "description": "Apply the same partial data patch to every row matching a non-empty predicate.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.rows.update_many",
         "x-oauth-scope": "api:write",
@@ -984,6 +1099,26 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateTableRowsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "filter": {
+                      "all": [
+                        {
+                          "field": "status",
+                          "op": "eq",
+                          "value": "trial"
+                        }
+                      ]
+                    },
+                    "data": {
+                      "status": "active"
+                    }
+                  }
+                }
               }
             }
           }
@@ -1044,7 +1179,7 @@
       },
       "delete": {
         "operationId": "deleteTableRows",
-        "summary": "Delete Rows",
+        "summary": "Delete rows",
         "description": "Delete rows by a non-empty predicate or an explicit bounded list of row identifiers.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.rows.delete_many",
         "x-oauth-scope": "api:write",
@@ -1069,6 +1204,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/DeleteTableRowsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "rowIds": ["row_1f3e5d7c9b8a4c2d806e4a6b8d0f2e93"]
+                  }
+                }
               }
             }
           }
@@ -1131,7 +1275,7 @@
     "/api/v2/tables/{tableId}/rows/{rowId}": {
       "get": {
         "operationId": "getTableRow",
-        "summary": "Get Row",
+        "summary": "Get row",
         "description": "Get one row by identifier. Set `includeRunState=true` to attach the row's per-workflow-group run outcomes.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.rows.read",
         "x-oauth-scope": "api:read",
@@ -1174,9 +1318,9 @@
             "name": "includeRunState",
             "in": "query",
             "required": false,
-            "description": "Include per-workflow-group run state on the returned row. Off by default.",
+            "description": "Include per-workflow-group run outcomes on the row. Off by default. Run state above 2 MiB returns `413`; omit this option to read the row without run state.",
             "schema": {
-              "description": "Include per-workflow-group run state on the returned row. Off by default.",
+              "description": "Include per-workflow-group run outcomes on the row. Off by default. Run state above 2 MiB returns `413`; omit this option to read the row without run state.",
               "type": "boolean"
             }
           }
@@ -1215,6 +1359,9 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "413": {
+            "$ref": "#/components/responses/PayloadTooLarge"
+          },
           "429": {
             "$ref": "#/components/responses/RateLimited"
           },
@@ -1228,7 +1375,7 @@
       },
       "patch": {
         "operationId": "updateTableRow",
-        "summary": "Update Row",
+        "summary": "Update row",
         "description": "Merge a partial data patch into one row by identifier.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.rows.update",
         "x-oauth-scope": "api:write",
@@ -1264,6 +1411,17 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateTableRowRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "data": {
+                      "status": "active"
+                    }
+                  }
+                }
               }
             }
           }
@@ -1324,7 +1482,7 @@
       },
       "delete": {
         "operationId": "deleteTableRow",
-        "summary": "Delete Row",
+        "summary": "Delete row",
         "description": "Delete one row by identifier.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.rows.delete",
         "x-oauth-scope": "api:write",
@@ -1416,8 +1574,8 @@
     "/api/v2/tables/{tableId}/rows/upsert": {
       "post": {
         "operationId": "upsertTableRow",
-        "summary": "Upsert Row",
-        "description": "Insert a row or replace the row matching a selected unique column. On replacement, omitted columns are cleared; send the complete row. Use Update Row for a partial patch.\n\nOAuth scope: `api:write`.",
+        "summary": "Upsert row",
+        "description": "Insert a row or replace the row matching a selected unique column. On replacement, omitted columns are cleared; send the complete row. Use Update row for a partial patch.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.rows.upsert",
         "x-oauth-scope": "api:write",
         "tags": ["Tables"],
@@ -1441,6 +1599,19 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpsertTableRowRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "data": {
+                      "email": "jane@example.com",
+                      "status": "active"
+                    },
+                    "conflictTarget": "email"
+                  }
+                }
               }
             }
           }
@@ -1503,8 +1674,8 @@
     "/api/v2/tables/{tableId}/query": {
       "post": {
         "operationId": "queryTableRows",
-        "summary": "Query Rows",
-        "description": "Query rows with typed predicates, sorting, and cursor pagination. Omit the predicate to match all rows. Pages default to a 5 MB limit; continue until `nextCursor` is null. Oversized predicates return `413`. `includeRunState` adds per-group outcomes and reduces the row limit. Counts are read separately and can differ from paged results if rows change.\n\nOAuth scope: `api:read`.",
+        "summary": "Query rows",
+        "description": "Query rows with typed predicates, sorting, and cursor pagination. Omit the predicate to match all rows. Pages default to a 5 MiB limit; continue until `nextCursor` is null. Oversized predicates return `413`. `includeRunState` adds per-group outcomes and reduces the row limit. Counts are read separately and can differ from paged results if rows change.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.rows.query",
         "x-oauth-scope": "api:read",
         "tags": ["Tables"],
@@ -1528,6 +1699,53 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/QueryTableRowsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "limit": 100
+                  }
+                },
+                "example2": {
+                  "summary": "Request example 2",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "predicate": {
+                      "field": "status",
+                      "op": "eq",
+                      "value": "active"
+                    },
+                    "sort": [
+                      {
+                        "field": "createdAt",
+                        "direction": "desc"
+                      }
+                    ],
+                    "limit": 100
+                  }
+                },
+                "example3": {
+                  "summary": "Request example 3",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "predicate": {
+                      "all": [
+                        {
+                          "field": "status",
+                          "op": "eq",
+                          "value": "active"
+                        },
+                        {
+                          "field": "score",
+                          "op": "gte",
+                          "value": 80
+                        }
+                      ]
+                    }
+                  }
+                }
               }
             }
           }
@@ -1587,7 +1805,7 @@
     "/api/v2/tables/{tableId}/query/count": {
       "post": {
         "operationId": "countTableRows",
-        "summary": "Count Rows",
+        "summary": "Count rows",
         "description": "Count rows matching a typed predicate, or omit the predicate to count all rows. The count is read separately from row pages and can change between requests. Oversized predicates return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.rows.query",
         "x-oauth-scope": "api:read",
@@ -1612,6 +1830,19 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CountTableRowsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "predicate": {
+                      "field": "status",
+                      "op": "eq",
+                      "value": "active"
+                    }
+                  }
+                }
               }
             }
           }
@@ -1671,8 +1902,8 @@
     "/api/v2/tables/{tableId}/views": {
       "get": {
         "operationId": "listTableViews",
-        "summary": "List Views",
-        "description": "List saved table views, omitting references to removed columns. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
+        "summary": "List views",
+        "description": "List saved table views, omitting references to removed columns. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.views.list",
         "x-oauth-scope": "api:read",
         "tags": ["Tables"],
@@ -1747,7 +1978,7 @@
       },
       "post": {
         "operationId": "createTableView",
-        "summary": "Create View",
+        "summary": "Create view",
         "description": "Save a filter, sort, and column layout as a named presentation of a table.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.views.create",
         "x-oauth-scope": "api:write",
@@ -1772,6 +2003,32 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateTableViewRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "Active customers",
+                    "config": {
+                      "filter": {
+                        "all": [
+                          {
+                            "field": "status",
+                            "op": "eq",
+                            "value": "active"
+                          }
+                        ]
+                      },
+                      "sort": [
+                        {
+                          "field": "createdAt",
+                          "direction": "desc"
+                        }
+                      ]
+                    }
+                  }
+                }
               }
             }
           }
@@ -1831,7 +2088,7 @@
     "/api/v2/tables/{tableId}/views/{viewId}": {
       "get": {
         "operationId": "getTableView",
-        "summary": "Get View",
+        "summary": "Get view",
         "description": "Get one saved table view by identifier.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.views.read",
         "x-oauth-scope": "api:read",
@@ -1918,7 +2175,7 @@
       },
       "patch": {
         "operationId": "updateTableView",
-        "summary": "Update View",
+        "summary": "Update view",
         "description": "Rename a view, replace or shallow-merge its configuration, or promote it to the table default.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.views.update",
         "x-oauth-scope": "api:write",
@@ -1954,6 +2211,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateTableViewRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "Priority customers",
+                    "isDefault": true
+                  }
+                }
               }
             }
           }
@@ -2011,7 +2278,7 @@
       },
       "delete": {
         "operationId": "deleteTableView",
-        "summary": "Delete View",
+        "summary": "Delete view",
         "description": "Delete a saved presentation without changing any table rows.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.views.delete",
         "x-oauth-scope": "api:write",
@@ -2100,8 +2367,8 @@
     "/api/v2/tables/{tableId}/groups": {
       "get": {
         "operationId": "listTableWorkflowGroups",
-        "summary": "List Workflow Groups",
-        "description": "List the workflow and enrichment groups that can be dispatched for a table. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
+        "summary": "List workflow groups",
+        "description": "List the workflow and enrichment groups that can be dispatched for a table. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.groups.list",
         "x-oauth-scope": "api:read",
         "tags": ["Tables"],
@@ -2176,7 +2443,7 @@
       },
       "post": {
         "operationId": "addTableWorkflowGroup",
-        "summary": "Add Workflow Group",
+        "summary": "Add workflow group",
         "description": "Bind a workflow or enrichment to the table and create the columns populated by its outputs. An output whose column the table already has attaches that column to the group instead of creating it, so `outputColumns` may be omitted when every output lands in an existing column.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.groups.create",
         "x-oauth-scope": "api:write",
@@ -2201,6 +2468,31 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/AddTableWorkflowGroupRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "group": {
+                      "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                      "name": "Enrich company",
+                      "outputs": [
+                        {
+                          "blockId": "block_lookup",
+                          "path": "output.revenue",
+                          "columnName": "revenue"
+                        }
+                      ]
+                    },
+                    "outputColumns": [
+                      {
+                        "name": "revenue",
+                        "type": "number"
+                      }
+                    ]
+                  }
+                }
               }
             }
           }
@@ -2261,7 +2553,7 @@
       },
       "patch": {
         "operationId": "updateTableWorkflowGroup",
-        "summary": "Update Workflow Group",
+        "summary": "Update workflow group",
         "description": "Restructure a workflow group, its producer, outputs, or execution behavior. Repointing the group at a different workflow concurrently invalidates the resolved output types and returns `409` — retry the update.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.groups.update",
         "x-oauth-scope": "api:write",
@@ -2286,6 +2578,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateTableWorkflowGroupRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "groupId": "grp_5d8b2f0a6c1e4739a8b3d5f7e9c1a204",
+                    "name": "Company profile enrichment"
+                  }
+                }
               }
             }
           }
@@ -2349,7 +2651,7 @@
       },
       "delete": {
         "operationId": "deleteTableWorkflowGroup",
-        "summary": "Delete Workflow Group",
+        "summary": "Delete workflow group",
         "description": "Delete a workflow group and every table column populated by that group.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.groups.delete",
         "x-oauth-scope": "api:write",
@@ -2374,6 +2676,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/DeleteTableWorkflowGroupRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "groupId": "grp_5d8b2f0a6c1e4739a8b3d5f7e9c1a204"
+                  }
+                }
               }
             }
           }
@@ -2436,8 +2747,8 @@
     "/api/v2/tables/{tableId}/dispatches": {
       "post": {
         "operationId": "createTableDispatch",
-        "summary": "Create Run Dispatch",
-        "description": "Start workflow or enrichment groups across all rows or selected rows. Poll Get Run Dispatch until `complete` or `canceled`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`. Use Cancel Run Dispatch to stop further scheduling.\n\nOAuth scope: `api:write`.",
+        "summary": "Create run dispatch",
+        "description": "Start workflow or enrichment groups across all rows or selected rows. Poll Get run dispatch until `complete` or `canceled`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`. Use Cancel run dispatch to stop further scheduling.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.runs.start",
         "x-oauth-scope": "api:write",
         "tags": ["Tables"],
@@ -2461,6 +2772,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateTableDispatchRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "groupIds": ["grp_5d8b2f0a6c1e4739a8b3d5f7e9c1a204"]
+                  }
+                }
               }
             }
           }
@@ -2518,7 +2838,7 @@
       },
       "get": {
         "operationId": "listTableDispatches",
-        "summary": "List Run Dispatches",
+        "summary": "List run dispatches",
         "description": "List the run dispatches on one table, most recent first — settled dispatches (`complete`, `canceled`) alongside the ones still in flight, so a run that finished between two polls is still visible next to the `dispatchId` its create returned. Capped at the 100 most recent, so this list is unpaginated and `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.runs.read",
         "x-oauth-scope": "api:read",
@@ -2596,8 +2916,8 @@
     "/api/v2/tables/{tableId}/rows/{rowId}/enrichment/{groupId}": {
       "post": {
         "operationId": "runRowEnrichment",
-        "summary": "Run Enrichment For One Row",
-        "description": "Start one workflow or enrichment group for a table row. Poll Get Run Dispatch using the returned `dispatchId`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`.\n\nOAuth scope: `api:write`.",
+        "summary": "Run enrichment for one row",
+        "description": "Start one workflow or enrichment group for a table row. Poll Get run dispatch using the returned `dispatchId`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.runs.start",
         "x-oauth-scope": "api:write",
         "tags": ["Tables"],
@@ -2643,6 +2963,14 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RunRowEnrichmentRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64"
+                  }
+                }
               }
             }
           }
@@ -2700,8 +3028,8 @@
       },
       "get": {
         "operationId": "getRowEnrichment",
-        "summary": "Get Row Group Run",
-        "description": "Read a workflow or enrichment group’s outcome for one row: `runState` (as exposed by `includeRunState`), output cells keyed by column name, and enrichment providers in cascade order with status, hosted-key cost, duration, and the matching provider. Existing rows always answer: `runState: null` means never run; `cascade: null` means no breakdown recorded. Missing tables, rows, or groups return `404`.\n\nOAuth scope: `api:read`.",
+        "summary": "Get row group run",
+        "description": "Read one row’s workflow or enrichment-group outcome: run state, output cells keyed by column name, and providers in cascade order with status, hosted-key cost, duration, and the matching provider. `runState: null` means never run; `cascade: null` means no breakdown was recorded. Missing tables, rows, or groups return `404`. Run state above 2 MiB returns `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.rows.read",
         "x-oauth-scope": "api:read",
         "tags": ["Tables"],
@@ -2785,6 +3113,9 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "413": {
+            "$ref": "#/components/responses/PayloadTooLarge"
+          },
           "429": {
             "$ref": "#/components/responses/RateLimited"
           },
@@ -2800,8 +3131,8 @@
     "/api/v2/tables/{tableId}/rows/search": {
       "post": {
         "operationId": "searchTableRows",
-        "summary": "Search Rows",
-        "description": "Search cell text for a case-insensitive substring within an optional filtered and sorted view. Returns cell coordinates, not row data; `ordinal` matches the view used by Query Rows. Results are unpaginated and capped at 1000. If `truncated` is true, narrow the search or predicate.\n\nOAuth scope: `api:read`.",
+        "summary": "Search rows",
+        "description": "Search cell text for a case-insensitive substring within an optional filtered and sorted view. Returns cell coordinates, not row data; `ordinal` matches the view used by Query rows. Results are unpaginated and capped at 1000. If `truncated` is true, narrow the search or predicate.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.rows.search",
         "x-oauth-scope": "api:read",
         "tags": ["Tables"],
@@ -2825,6 +3156,24 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/SearchTableRowsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "q": "acme",
+                    "predicate": {
+                      "all": [
+                        {
+                          "field": "status",
+                          "op": "eq",
+                          "value": "active"
+                        }
+                      ]
+                    }
+                  }
+                }
               }
             }
           }
@@ -2884,7 +3233,7 @@
     "/api/v2/tables/imports": {
       "post": {
         "operationId": "createTableImport",
-        "summary": "Create Table Import",
+        "summary": "Create table import",
         "description": "Create a CSV import. Upload sources receive signed transfer instructions; workspace-file sources start processing directly.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.imports.create",
         "x-oauth-scope": "api:write",
@@ -2896,6 +3245,26 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateTableImportRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "source": {
+                      "type": "upload",
+                      "name": "customers.csv",
+                      "contentType": "text/csv",
+                      "size": 2048
+                    },
+                    "target": {
+                      "type": "new",
+                      "name": "ImportedCustomers",
+                      "folderPath": "/Imports"
+                    },
+                    "timezone": "America/Los_Angeles"
+                  }
+                }
               }
             }
           }
@@ -2961,7 +3330,7 @@
     "/api/v2/tables/imports/{importId}": {
       "get": {
         "operationId": "getTableImport",
-        "summary": "Get Table Import",
+        "summary": "Get table import",
         "description": "Get an import's progress and status. During `uploading`, the signed upload token is required; omitting it returns `404`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.imports.read",
         "x-oauth-scope": "api:read",
@@ -3049,7 +3418,7 @@
       },
       "delete": {
         "operationId": "cancelTableImport",
-        "summary": "Cancel Table Import",
+        "summary": "Cancel table import",
         "description": "Cancel an upload or processing import. Committed row batches remain. Non-cancelable states, including `expired`, return `409`; unknown or purged imports return `404`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.imports.cancel",
         "x-oauth-scope": "api:write",
@@ -3142,7 +3511,7 @@
     "/api/v2/tables/imports/{importId}/parts": {
       "post": {
         "operationId": "createTableImportPartUrls",
-        "summary": "Create Table Import Part URLs",
+        "summary": "Create table import part URLs",
         "description": "Create signed URLs for multipart upload parts. Requires the `uploading` state; other states return `409`. Unknown or purged imports return `404`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.imports.create_parts",
         "x-oauth-scope": "api:write",
@@ -3190,6 +3559,14 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateTableImportPartUrlsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "partNumbers": [1, 2, 3]
+                  }
+                }
               }
             }
           }
@@ -3252,7 +3629,7 @@
     "/api/v2/tables/imports/{importId}/complete": {
       "post": {
         "operationId": "completeTableImportUpload",
-        "summary": "Complete Table Import Upload",
+        "summary": "Complete table import upload",
         "description": "Verify or assemble uploaded CSV bytes and start processing under the same import ID. Requires an import awaiting upload completion; other states return `409`. Unknown or purged imports return `404`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.imports.complete",
         "x-oauth-scope": "api:write",
@@ -3348,7 +3725,7 @@
     "/api/v2/tables/{tableId}/exports": {
       "post": {
         "operationId": "createTableExport",
-        "summary": "Create Table Export",
+        "summary": "Create table export",
         "description": "Create a CSV or JSON export. Exports of small tables finish during the request; larger exports run asynchronously.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.exports.create",
         "x-oauth-scope": "api:write",
@@ -3373,6 +3750,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateTableExportRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "format": "csv"
+                  }
+                }
               }
             }
           }
@@ -3435,7 +3821,7 @@
     "/api/v2/tables/{tableId}/exports/{exportId}": {
       "get": {
         "operationId": "getTableExport",
-        "summary": "Get Table Export",
+        "summary": "Get table export",
         "description": "Get a table export's progress and status.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.exports.read",
         "x-oauth-scope": "api:read",
@@ -3523,7 +3909,7 @@
       },
       "delete": {
         "operationId": "cancelTableExport",
-        "summary": "Cancel Table Export",
+        "summary": "Cancel table export",
         "description": "Cancel an export that is still in progress.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.exports.cancel",
         "x-oauth-scope": "api:write",
@@ -3616,7 +4002,7 @@
     "/api/v2/tables/{tableId}/exports/{exportId}/download": {
       "get": {
         "operationId": "downloadTableExport",
-        "summary": "Download Table Export",
+        "summary": "Download table export",
         "description": "Get a short-lived signed download URL for a completed export. Other states return `409`; an unavailable export file returns `404`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.exports.download",
         "x-oauth-scope": "api:read",
@@ -3709,7 +4095,7 @@
     "/api/v2/tables/{tableId}/cancel-runs": {
       "post": {
         "operationId": "cancelTableRuns",
-        "summary": "Cancel Column Runs",
+        "summary": "Cancel column runs",
         "description": "Stop in-flight and pending workflow or enrichment cell runs across the table or one selected row.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.runs.cancel",
         "x-oauth-scope": "api:write",
@@ -3729,11 +4115,21 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "Workspace scope, cancellation scope, and optional predicate or producer groups.",
+          "description": "Workspace scope, row or all-table cancellation, and optional row predicate or exclusions.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CancelTableRunsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "scope": "row",
+                    "rowId": "row_1f3e5d7c9b8a4c2d806e4a6b8d0f2e93"
+                  }
+                }
               }
             }
           }
@@ -3793,8 +4189,8 @@
     "/api/v2/tables/folders": {
       "get": {
         "operationId": "listTablesFolders",
-        "summary": "List Folders",
-        "description": "List table folders, optionally limiting results to direct children of a parent path. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
+        "summary": "List folders",
+        "description": "List table folders, optionally limiting results to direct children of a parent path. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.folders.list",
         "x-oauth-scope": "api:read",
         "tags": ["Tables"],
@@ -3837,10 +4233,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "name",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -3908,7 +4304,7 @@
       },
       "post": {
         "operationId": "createTablesFolder",
-        "summary": "Create Folder",
+        "summary": "Create folder",
         "description": "Create one table-folder leaf whose parent path already exists.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.folders.create",
         "x-oauth-scope": "api:write",
@@ -3920,6 +4316,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateTableFolderRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "path": "/Sales/Enterprise"
+                  }
+                }
               }
             }
           }
@@ -3980,7 +4385,7 @@
       },
       "patch": {
         "operationId": "relocateTablesFolder",
-        "summary": "Rename or Move Folder",
+        "summary": "Rename or move folder",
         "description": "Rename or move a table folder and update all descendant paths.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.folders.update",
         "x-oauth-scope": "api:write",
@@ -3992,6 +4397,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RelocateTableFolderRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "path": "/Sales/Enterprise",
+                    "destinationPath": "/Revenue/Enterprise"
+                  }
+                }
               }
             }
           }
@@ -4052,8 +4467,8 @@
       },
       "delete": {
         "operationId": "deleteTablesFolder",
-        "summary": "Delete Folder",
-        "description": "Archive an empty folder, or set `recursive=true` to archive its tables and subfolders. Use Restore Folder to recover the archived contents.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete folder",
+        "description": "Archive an empty folder, or set `recursive=true` to archive its tables and subfolders. Use Restore folder to recover the archived contents.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.folders.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Tables"],
@@ -4084,9 +4499,9 @@
             "name": "recursive",
             "in": "query",
             "required": false,
-            "description": "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+            "description": "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
             "schema": {
-              "description": "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+              "description": "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
               "enum": [
                 "true",
                 "1",
@@ -4164,8 +4579,8 @@
     "/api/v2/tables/folders/restore": {
       "post": {
         "operationId": "restoreTablesFolder",
-        "summary": "Restore Folder",
-        "description": "Restore an archived table folder, its descendants, and tables using its former path. An archived parent moves it to the root; name conflicts may change the returned `path`. Non-archived paths return `404`. Save the path from Delete Folder, because List Folders does not include archived table folders.\n\nOAuth scope: `api:write`.",
+        "summary": "Restore folder",
+        "description": "Restore an archived table folder, its descendants, and tables using its former path. An archived parent moves it to the root; name conflicts may change the returned `path`. Non-archived paths return `404`. Save the path from Delete folder, because List folders does not include archived table folders.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.folders.restore",
         "x-oauth-scope": "api:write",
         "tags": ["Tables"],
@@ -4176,6 +4591,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RestoreTableFolderRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "path": "/Sales/Enterprise"
+                  }
+                }
               }
             }
           }
@@ -4238,8 +4662,8 @@
     "/api/v2/tables/{tableId}/restore": {
       "post": {
         "operationId": "restoreTable",
-        "summary": "Restore Table",
-        "description": "Restore a table and its archived rows, views, and workflow groups. Active tables return unchanged without a new audit event. Name conflicts may change the returned `name`. Find archived tables with List Tables and `scope=archived`.\n\nOAuth scope: `api:write`.",
+        "summary": "Restore table",
+        "description": "Restore a table and its archived rows, views, and workflow groups. Active tables return unchanged without a new audit event. Name conflicts may change the returned `name`. Find archived tables with List tables and `scope=archived`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.restore",
         "x-oauth-scope": "api:write",
         "tags": ["Tables"],
@@ -4263,6 +4687,14 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RestoreTableRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64"
+                  }
+                }
               }
             }
           }
@@ -4325,8 +4757,8 @@
     "/api/v2/tables/{tableId}/rows/bulk-update": {
       "post": {
         "operationId": "bulkUpdateTableRows",
-        "summary": "Bulk Update Rows",
-        "description": "Apply separate partial patches to up to 1,000 rows, preserving omitted columns. A row outside the table rejects the entire request with `400` and lists missing IDs. Use Update Rows by Filter to apply one patch to every matching row.\n\nOAuth scope: `api:write`.",
+        "summary": "Bulk update rows",
+        "description": "Apply separate partial patches to up to 1,000 rows, preserving omitted columns. A row outside the table rejects the entire request with `400` and lists missing IDs. Use Update rows by filter to apply one patch to every matching row.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.rows.update_many",
         "x-oauth-scope": "api:write",
         "tags": ["Tables"],
@@ -4350,6 +4782,28 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/BulkUpdateTableRowsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "updates": [
+                      {
+                        "rowId": "row_1f3e5d7c9b8a4c2d806e4a6b8d0f2e93",
+                        "data": {
+                          "status": "active"
+                        }
+                      },
+                      {
+                        "rowId": "row_2b4d6f8a0c1e3759b8d0f2a4c6e80193",
+                        "data": {
+                          "status": "churned"
+                        }
+                      }
+                    ]
+                  }
+                }
               }
             }
           }
@@ -4412,7 +4866,7 @@
     "/api/v2/tables/{tableId}/dispatches/{dispatchId}": {
       "get": {
         "operationId": "getTableDispatch",
-        "summary": "Get Run Dispatch",
+        "summary": "Get run dispatch",
         "description": "Get a dispatch's current state. Poll until `complete` or `canceled`; use row reads with `includeRunState` for per-cell outcomes.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "tables.runs.read",
         "x-oauth-scope": "api:read",
@@ -4500,8 +4954,8 @@
       },
       "delete": {
         "operationId": "cancelTableDispatch",
-        "summary": "Cancel Run Dispatch",
-        "description": "Stop a dispatch from scheduling more cells. Already queued or running cells continue; use Cancel Column Runs to stop them. Completed or canceled dispatches return unchanged.\n\nOAuth scope: `api:write`.",
+        "summary": "Cancel run dispatch",
+        "description": "Stop a dispatch from scheduling more cells. Already queued or running cells continue; use Cancel column runs to stop them. Completed or canceled dispatches return unchanged.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.runs.cancel",
         "x-oauth-scope": "api:write",
         "tags": ["Tables"],
@@ -4590,7 +5044,7 @@
     "/api/v2/tables/move": {
       "post": {
         "operationId": "moveTables",
-        "summary": "Move Tables and Folders",
+        "summary": "Move tables and folders",
         "description": "Move up to 100 tables and folders to one destination. Items succeed or fail independently: covered tables are `skipped`, missing items are `notFound`, and lock or cycle failures include reasons in `failed`. An invalid destination rejects the request before any move.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.bulk_move",
         "x-oauth-scope": "api:write",
@@ -4602,6 +5056,17 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/BulkMoveTablesRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "tableIds": ["tbl_7c9e6679742540de944be07fc1f90ae7"],
+                    "folderPaths": ["/Sales/Enterprise"],
+                    "targetFolderPath": "/Revenue"
+                  }
+                }
               }
             }
           }
@@ -4661,8 +5126,8 @@
     "/api/v2/tables/bulk-delete": {
       "post": {
         "operationId": "bulkDeleteTables",
-        "summary": "Bulk Delete Tables and Folders",
-        "description": "Archive up to 100 selected tables and folders, including folder contents. Items succeed or fail independently, with `skipped`, `notFound`, and `failed` outcomes. `deletedItems` includes all descendants. Use Restore Table or Restore Folder to recover archived items.\n\nOAuth scope: `api:write`.",
+        "summary": "Bulk delete tables and folders",
+        "description": "Archive up to 100 selected tables and folders, including folder contents. Items succeed or fail independently, with `skipped`, `notFound`, and `failed` outcomes. `deletedItems` includes all descendants. Use Restore table or Restore folder to recover archived items.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "tables.bulk_delete",
         "x-oauth-scope": "api:write",
         "tags": ["Tables"],
@@ -4673,6 +5138,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/BulkDeleteTablesRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "tableIds": ["tbl_7c9e6679742540de944be07fc1f90ae7"],
+                    "folderPaths": ["/Sales/Archive"]
+                  }
+                }
               }
             }
           }
@@ -4695,6 +5170,34 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/V2BulkDeleteTablesResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "deleted": [
+                          {
+                            "kind": "table",
+                            "id": "tbl_7c9e6679742540de944be07fc1f90ae7",
+                            "name": "Leads"
+                          },
+                          {
+                            "kind": "folder",
+                            "id": "/Sales/Archive",
+                            "name": "/Sales/Archive"
+                          }
+                        ],
+                        "skipped": [],
+                        "notFound": [],
+                        "failed": [],
+                        "deletedItems": {
+                          "tables": 1,
+                          "folders": 1
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -4877,7 +5380,7 @@
             "example": {
               "error": {
                 "code": "CONFLICT",
-                "message": "A table named \"Orders\" already exists in this workspace"
+                "message": "The request conflicts with current table state"
               }
             }
           }
@@ -4925,7 +5428,7 @@
             "example": {
               "error": {
                 "code": "LOCKED",
-                "message": "This table is insert-locked: new rows cannot be added.",
+                "message": "A table lock prevents this operation.",
                 "details": {
                   "lock": "insert"
                 }
@@ -4975,7 +5478,7 @@
         }
       },
       "ServiceUnavailable": {
-        "description": "A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, because the run may already have started — reconcile against the returned run id instead of retrying.",
+        "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
         "headers": {
           "Retry-After": {
             "$ref": "#/components/headers/Retry-After"
@@ -5363,7 +5866,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -6212,7 +6715,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -6818,7 +7321,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -6862,7 +7365,7 @@
             }
           },
           "limit": {
-            "description": "Maximum rows to return; zero requests an unbounded result.",
+            "description": "Maximum rows per page. `0` requests all matches, subject to a 5 MiB row-data ceiling; larger results return `400` with `TABLE_QUERY_RESULT_TOO_LARGE`. Use paged queries or an export for larger results.",
             "type": "integer",
             "minimum": 0,
             "maximum": 1000
@@ -6874,7 +7377,7 @@
           },
           "includeRunState": {
             "default": false,
-            "description": "Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it only when asked. Incompatible with `limit: 0`, and caps `limit` at 200.",
+            "description": "Include per-workflow-group run outcomes on every row. Off by default. Incompatible with `limit: 0`; caps `limit` at 200. Run state above 2 MiB returns `413`; request fewer rows or omit run state.",
             "type": "boolean"
           }
         },
@@ -7092,7 +7595,7 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           }
         },
         "required": ["data", "nextCursor"],
@@ -7557,7 +8060,7 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           }
         },
         "required": ["data", "nextCursor"],
@@ -9576,7 +10079,7 @@
         "required": ["workspaceId", "scope"],
         "additionalProperties": false,
         "title": "Cancel table runs request",
-        "description": "Workspace scope, cancellation scope, and optional predicate or producer groups."
+        "description": "Workspace scope, row or all-table cancellation, and optional row predicate or exclusions."
       },
       "V2Folder": {
         "type": "object",
@@ -9632,7 +10135,7 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           }
         },
         "required": ["data", "nextCursor"],
@@ -10315,7 +10818,7 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           }
         },
         "required": ["data", "nextCursor"],
diff --git a/apps/docs/openapi-v2-workflows.json b/apps/docs/openapi-v2-workflows.json
index 31383bc19fb..8b62ce56def 100644
--- a/apps/docs/openapi-v2-workflows.json
+++ b/apps/docs/openapi-v2-workflows.json
@@ -46,8 +46,8 @@
     "/api/v2/workflows": {
       "get": {
         "operationId": "listWorkflows",
-        "summary": "List Workflows",
-        "description": "List active workflows in a workspace. Use `scope=archived` to find workflows available for restoration. Supports folder and deployment filters, search, sorting, and cursor pagination. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "summary": "List workflows",
+        "description": "List active workflows in a workspace with workspace read access. Use `scope=archived` to find workflows available for restoration. Filter by folder, deployment, or name; sort and page with the returned cursor. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.list",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -136,10 +136,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "position",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["position", "name", "createdAt", "updatedAt", "runCount"]
             }
@@ -175,6 +175,30 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/WorkflowListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                          "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                          "name": "Customer support triage",
+                          "description": "Routes incoming support requests to the right team.",
+                          "folderPath": "/Operations",
+                          "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                          "isDeployed": true,
+                          "deployedAt": "2026-06-12T10:30:00.000Z",
+                          "runCount": 42,
+                          "lastRunAt": "2026-08-09T18:04:11.000Z",
+                          "createdAt": "2026-05-01T09:00:00.000Z",
+                          "updatedAt": "2026-08-09T18:04:11.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -207,8 +231,8 @@
       },
       "post": {
         "operationId": "createWorkflowV2",
-        "summary": "Create Workflow",
-        "description": "Create a workflow at the workspace root or in a workflow folder. The response includes seeded blocks and their IDs for attaching edges. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+        "summary": "Create workflow",
+        "description": "Create an undeployed workflow at the workspace root or in a workflow folder. Requires workspace write access. The response includes the seeded start block and its ID for connecting other blocks. A name already used in the destination folder returns `409`. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.create",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -219,6 +243,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateWorkflowRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "Customer support triage",
+                    "folderPath": "/Operations"
+                  }
+                }
               }
             }
           }
@@ -241,6 +275,34 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateWorkflowResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "name": "Customer support triage",
+                        "description": "Routes incoming support requests to the right team.",
+                        "folderPath": "/Operations",
+                        "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                        "isDeployed": false,
+                        "deployedAt": null,
+                        "runCount": 0,
+                        "lastRunAt": null,
+                        "createdAt": "2026-05-01T09:00:00.000Z",
+                        "updatedAt": "2026-08-09T18:04:11.000Z",
+                        "blocks": [
+                          {
+                            "id": "start-1",
+                            "type": "starter",
+                            "name": "Start"
+                          }
+                        ]
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -284,8 +346,8 @@
     "/api/v2/workflows/{workflowId}/state": {
       "get": {
         "operationId": "getWorkflowState",
-        "summary": "Get Workflow State",
-        "description": "Get the editable draft graph, including blocks, edges, loop and parallel containers, and variables. Use this state with Replace Workflow State to preserve workspace bindings; Export Workflow removes those bindings for portability. This read records no audit event, and `HEAD` mirrors `GET`.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workflow state",
+        "description": "Read the saved editable draft, including blocks, edges, loop and parallel containers, and variables. Requires workspace read access. Configured values are included; use this state with Replace workflow state for same-workspace editing, or Export workflow for portable data with registered credential fields cleared. This read records no audit event; `HEAD` mirrors `GET`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.read",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -321,6 +383,20 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/WorkflowStateResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "blocks": {},
+                        "edges": [],
+                        "loops": {},
+                        "parallels": {},
+                        "variables": {}
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -350,8 +426,8 @@
       },
       "put": {
         "operationId": "replaceWorkflowState",
-        "summary": "Replace Workflow State",
-        "description": "Atomically replace the draft graph; row-locked concurrent writes are last-write-wins. Block, edge, or subflow IDs owned by another workflow return `409`. Deployments remain immutable snapshots; schedules and webhook registrations are unchanged. Deploy to publish edits. Lint is advisory. Use `dryRun=true` to validate without writing. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Replace workflow state",
+        "description": "Replace the draft graph in one write. Requires workspace write access. Concurrent row-locked writes are last-write-wins; IDs owned by another workflow return `409`. Deployments, schedules, and webhook registrations are unchanged. Deploy to serve the edits.\n\nLint is advisory. Use `dryRun=true` to validate without saving, auditing, or notifying collaborators. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.state.replace",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -386,6 +462,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ReplaceWorkflowStateRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "blocks": {},
+                    "edges": []
+                  }
+                }
               }
             }
           }
@@ -408,6 +493,31 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ReplaceWorkflowStateResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "warnings": [],
+                        "needsRedeployment": true,
+                        "dryRun": false,
+                        "lint": {
+                          "sources": [],
+                          "sinks": [],
+                          "orphanBlocks": [],
+                          "emptyOutgoingPorts": [],
+                          "invalidBranchPorts": [],
+                          "invalidConnectionTargets": [],
+                          "fieldIssues": [],
+                          "unresolvedReferences": [],
+                          "tableFieldIssues": [],
+                          "notes": []
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -451,8 +561,8 @@
     "/api/v2/workflows/{workflowId}/operations": {
       "post": {
         "operationId": "applyWorkflowOperations",
-        "summary": "Apply Workflow Operations",
-        "description": "Edit the draft graph and block enablement in one write. Inspect `skipped` for failures; do not retry `deferred` edges. With `atomic=true`, skipped operations or dropped inputs return `409` (`OPERATIONS_NOT_APPLIED`) without saving. `mintedBlockIds` maps labels to generated IDs. Lint is advisory; `dryRun=true` validates without saving, auditing, or notifying. The live deployment is unchanged. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Apply workflow operations",
+        "description": "Apply draft edits and block enablement changes in one write. Requires workspace write access. The live deployment is unchanged; lint is advisory.\n\nInspect `skipped` and `inputValidationErrors` for edits that did not apply. Deferred edges apply when their targets exist; do not resubmit them. With `atomic=true`, declined operations or dropped inputs return `409` (`OPERATIONS_NOT_APPLIED`) without saving. Use returned `mintedBlockIds` in later requests. `dryRun=true` evaluates without saving, auditing, or notifying. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.operations.apply",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -487,6 +597,33 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ApplyWorkflowOperationsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "operations": [
+                      {
+                        "operation_type": "add",
+                        "block_id": "agent-1",
+                        "params": {
+                          "type": "agent",
+                          "name": "Triage",
+                          "inputs": {
+                            "tools": [
+                              {
+                                "type": "cloudwatch",
+                                "operation": "describe_alarm_history",
+                                "usageControl": "auto",
+                                "params": {}
+                              }
+                            ]
+                          }
+                        }
+                      }
+                    ]
+                  }
+                }
               }
             }
           }
@@ -509,6 +646,46 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ApplyWorkflowOperationsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "applied": 1,
+                        "skipped": [],
+                        "deferred": [],
+                        "inputValidationErrors": [],
+                        "mintedBlockIds": {
+                          "agent-1": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77"
+                        },
+                        "lint": {
+                          "sources": [],
+                          "sinks": [],
+                          "orphanBlocks": [],
+                          "emptyOutgoingPorts": [],
+                          "invalidBranchPorts": [],
+                          "invalidConnectionTargets": [],
+                          "fieldIssues": [
+                            {
+                              "blockId": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77",
+                              "blockName": "Triage",
+                              "blockType": "agent",
+                              "missingRequiredFields": ["systemPrompt"],
+                              "inactiveModeValues": []
+                            }
+                          ],
+                          "unresolvedReferences": [],
+                          "tableFieldIssues": [],
+                          "notes": []
+                        },
+                        "warnings": [],
+                        "needsRedeployment": true,
+                        "dryRun": false
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -552,8 +729,8 @@
     "/api/v2/workflows/{workflowId}/variables": {
       "patch": {
         "operationId": "applyWorkflowVariables",
-        "summary": "Update Workflow Variables",
-        "description": "Add, edit, or delete variables by name, applying operations in order. Values are coerced to their declared type when possible; otherwise they are stored as supplied. A batch with no changes returns `200` with `changed: false`. Read current variables with Get Workflow.\n\nOAuth scope: `api:write`.",
+        "summary": "Update workflow variables",
+        "description": "Add, edit, or delete variables by name with workspace write access. Operations run in order. Values are coerced to their declared type when possible and otherwise stored as supplied. A no-op batch returns `changed: false`; read current values with Get workflow.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.variables.apply_operations",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -600,6 +777,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ApplyWorkflowVariablesResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "variableCount": 3,
+                        "changed": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -643,8 +832,8 @@
     "/api/v2/workflows/{workflowId}/duplicate": {
       "post": {
         "operationId": "duplicateWorkflow",
-        "summary": "Duplicate Workflow",
-        "description": "Copy a workflow's graph and variables into the same workspace. Omit `name` to reuse the source name; name collisions in the destination folder are resolved automatically. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+        "summary": "Duplicate workflow",
+        "description": "Create an undeployed copy of a workflow's graph and variables in the same workspace. Requires workspace write access. The destination folder and name default to the source; name collisions in the destination are resolved automatically. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.duplicate",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -669,6 +858,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/DuplicateWorkflowRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "name": "Customer support triage (copy)",
+                    "folderPath": "/Operations"
+                  }
+                }
               }
             }
           }
@@ -691,6 +889,27 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DuplicateWorkflowResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "name": "Customer support triage (copy)",
+                        "description": "Routes incoming support requests to the right team.",
+                        "folderPath": "/Operations",
+                        "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                        "isDeployed": false,
+                        "deployedAt": null,
+                        "runCount": 0,
+                        "lastRunAt": null,
+                        "createdAt": "2026-05-01T09:00:00.000Z",
+                        "updatedAt": "2026-08-09T18:04:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -734,8 +953,8 @@
     "/api/v2/workflows/{workflowId}/restore": {
       "post": {
         "operationId": "restoreWorkflow",
-        "summary": "Restore Workflow",
-        "description": "Restore an archived workflow and the schedules, webhooks, MCP tools, and chats archived with it. An active workflow returns `409`. If its folder is archived, the workflow returns to the workspace root. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+        "summary": "Restore workflow",
+        "description": "Restore an archived workflow and its archived schedules, webhooks, MCP tools, and hosted chat. Requires workspace write access. An active workflow returns `409`. If its folder is archived, the workflow returns to the workspace root. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.restore",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -771,6 +990,27 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RestoreWorkflowResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "name": "Customer support triage",
+                        "description": "Routes incoming support requests to the right team.",
+                        "folderPath": "/Operations",
+                        "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                        "isDeployed": true,
+                        "deployedAt": "2026-06-12T10:30:00.000Z",
+                        "runCount": 42,
+                        "lastRunAt": "2026-08-09T18:04:11.000Z",
+                        "createdAt": "2026-05-01T09:00:00.000Z",
+                        "updatedAt": "2026-08-09T18:04:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -811,8 +1051,8 @@
     "/api/v2/workflows/move": {
       "post": {
         "operationId": "moveWorkflows",
-        "summary": "Move Workflows",
-        "description": "Move up to 100 workflows into one folder. Moves succeed or fail independently; missing, archived, or locked workflows appear in `failed`. Duplicate IDs are ignored. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+        "summary": "Move workflows",
+        "description": "Move up to 100 workflows to one folder with workspace write access. Each move succeeds or fails independently; missing, archived, or locked workflows appear in `failed`. Duplicate IDs are ignored. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.bulk.move",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -823,6 +1063,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/MoveWorkflowsRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "workflowIds": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"],
+                    "folderPath": "/Operations"
+                  }
+                }
               }
             }
           }
@@ -845,6 +1095,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/MoveWorkflowsResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "moved": ["3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36"],
+                        "failed": [],
+                        "folderPath": "/Operations"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -882,8 +1144,8 @@
     "/api/v2/workflows/{workflowId}": {
       "get": {
         "operationId": "getWorkflow",
-        "summary": "Get Workflow",
-        "description": "Get a workflow with its variables and deployed API-trigger inputs. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workflow",
+        "description": "Get workflow metadata, variables, and trigger input fields from the saved draft. Requires workspace read access. Input fields may differ from the live deployment. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.read",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -919,6 +1181,29 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/WorkflowDetailResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "name": "Customer support triage",
+                        "description": "Routes incoming support requests to the right team.",
+                        "folderPath": "/Operations",
+                        "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                        "isDeployed": true,
+                        "deployedAt": "2026-06-12T10:30:00.000Z",
+                        "runCount": 42,
+                        "lastRunAt": "2026-08-09T18:04:11.000Z",
+                        "createdAt": "2026-05-01T09:00:00.000Z",
+                        "updatedAt": "2026-08-09T18:04:11.000Z",
+                        "variables": {},
+                        "inputs": []
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -951,8 +1236,8 @@
       },
       "patch": {
         "operationId": "updateWorkflowV2",
-        "summary": "Update Workflow",
-        "description": "Update a workflow's name, description, or folder path. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+        "summary": "Update workflow",
+        "description": "Update a workflow's name, description, or folder path with workspace write access. Omitted fields remain unchanged; `description: null` clears the description. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.update",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -977,6 +1262,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateWorkflowRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "name": "Customer support and escalation",
+                    "folderPath": "/Operations"
+                  }
+                }
               }
             }
           }
@@ -999,6 +1293,27 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateWorkflowResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "webUrl": "https://www.sim.ai/workspace/a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64/w/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "name": "Customer support triage",
+                        "description": "Routes incoming support requests to the right team.",
+                        "folderPath": "/Operations",
+                        "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                        "isDeployed": true,
+                        "deployedAt": "2026-06-12T10:30:00.000Z",
+                        "runCount": 42,
+                        "lastRunAt": "2026-08-09T18:04:11.000Z",
+                        "createdAt": "2026-05-01T09:00:00.000Z",
+                        "updatedAt": "2026-08-09T18:04:11.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1040,8 +1355,8 @@
       },
       "delete": {
         "operationId": "deleteWorkflowV2",
-        "summary": "Delete Workflow",
-        "description": "Archive a workflow and stop its schedules, webhooks, MCP tools, and chats. Use List Workflows with `scope=archived` to find it and Restore Workflow to recover it and its archived resources. Both `deleted` and `archived` acknowledge archival.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete workflow",
+        "description": "Archive a workflow and stop its schedules, webhooks, MCP tools, and hosted chat. Requires workspace write access. Find it with List workflows (`scope=archived`) and recover it with Restore workflow. Both `deleted` and `archived` acknowledge archival.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -1077,6 +1392,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeleteWorkflowResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "deleted": true,
+                        "archived": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1111,8 +1438,8 @@
     "/api/v2/workflows/{workflowId}/versions": {
       "get": {
         "operationId": "listWorkflowVersionsV2",
-        "summary": "List Workflow Versions",
-        "description": "List immutable deployment versions of a workflow, newest first.\n\nOAuth scope: `api:read`.",
+        "summary": "List workflow versions",
+        "description": "List saved deployment versions, newest first, with workspace read access. Each version pins an immutable graph; its name and release note can be updated.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.versions.list",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -1172,6 +1499,26 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/WorkflowVersionListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "version_3",
+                          "version": 3,
+                          "name": "Escalation routing",
+                          "description": "Adds the priority escalation branch.",
+                          "isActive": true,
+                          "createdAt": "2026-06-12T10:30:00.000Z",
+                          "deployedBy": "Jane Smith",
+                          "latestOperationStatus": "active"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -1203,8 +1550,8 @@
     "/api/v2/workflows/{workflowId}/versions/compare": {
       "get": {
         "operationId": "compareWorkflowVersionsV2",
-        "summary": "Compare Workflow Versions",
-        "description": "Compare two deployment versions of the same workflow. Reports semantic changes, excluding canvas layout; credential-bearing values are withheld while their changes remain visible. Connections include stable block and port identifiers. The combined snapshots and the comparison result must each fit within 16 MiB.\n\nOAuth scope: `api:read`.",
+        "summary": "Compare workflow versions",
+        "description": "Compare two deployment versions of the same workflow with workspace read access. The comparison excludes layout changes and withholds credential-bearing values while reporting their changes. Connections include stable block and port IDs. The combined snapshots and the comparison result must each fit within 16 MiB.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.versions.compare",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -1264,6 +1611,49 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/WorkflowVersionComparisonResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "base": 1,
+                        "target": 2,
+                        "diff": {
+                          "addedBlocks": [],
+                          "removedBlocks": [],
+                          "modifiedBlocks": [],
+                          "edgeChanges": {
+                            "added": 0,
+                            "removed": 0,
+                            "addedDetails": [],
+                            "removedDetails": []
+                          },
+                          "loopChanges": {
+                            "added": 0,
+                            "removed": 0,
+                            "modified": 0
+                          },
+                          "parallelChanges": {
+                            "added": 0,
+                            "removed": 0,
+                            "modified": 0
+                          },
+                          "containerChanges": [],
+                          "variableChanges": {
+                            "added": 0,
+                            "removed": 0,
+                            "modified": 0,
+                            "addedNames": [],
+                            "removedNames": [],
+                            "modifiedNames": []
+                          },
+                          "hasChanges": false
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1298,8 +1688,8 @@
     "/api/v2/workflows/{workflowId}/versions/{version}": {
       "get": {
         "operationId": "getWorkflowVersionV2",
-        "summary": "Get Workflow Version",
-        "description": "Get an immutable deployment version and its pinned workflow graph snapshot.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workflow version",
+        "description": "Get a deployment version and its pinned graph with workspace read access. Registered credential fields and opaque table/tool values are cleared. Environment references and ordinary workflow variables remain included; review other configuration before sharing.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.versions.read",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -1347,6 +1737,25 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/WorkflowVersionDetailResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "version_3",
+                        "version": 3,
+                        "name": "Escalation routing",
+                        "description": "Adds the priority escalation branch.",
+                        "isActive": true,
+                        "createdAt": "2026-06-12T10:30:00.000Z",
+                        "state": {
+                          "blocks": {},
+                          "edges": []
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1376,8 +1785,8 @@
       },
       "patch": {
         "operationId": "updateWorkflowVersionV2",
-        "summary": "Update Workflow Version",
-        "description": "Update a deployment version's name or release note. Omitted fields remain unchanged; `description: null` clears the note. The graph and live version remain unchanged. Use Activate Workflow Version to make this version live.\n\nOAuth scope: `api:write`.",
+        "summary": "Update workflow version",
+        "description": "Update a deployment version's name or release note with workspace write access. Omitted fields remain unchanged; `description: null` clears the note. The graph and live version are unchanged. Use Activate workflow version to serve it.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.versions.update",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -1414,6 +1823,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateWorkflowVersionRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "name": "Escalation routing",
+                    "description": "Adds the priority escalation branch."
+                  }
+                }
               }
             }
           }
@@ -1436,6 +1854,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateWorkflowVersionResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "version": 3,
+                        "name": "Escalation routing",
+                        "description": "Adds the priority escalation branch."
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1473,8 +1903,8 @@
     "/api/v2/workflows/{workflowId}/versions/{version}/activate": {
       "post": {
         "operationId": "activateWorkflowVersion",
-        "summary": "Activate Workflow Version",
-        "description": "Asynchronously activate a specific deployment version, including when the workflow is not currently deployed. The draft remains unchanged. Read Get Workflow Deployment for `isDeployed` and `latestDeploymentAttempt`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Activate workflow version",
+        "description": "Activate a specific deployment version asynchronously. Requires workspace Admin access and works when the workflow is undeployed. The draft is unchanged. Poll Get workflow deployment for the accepted `latestDeploymentAttempt`; `isDeployed` alone can describe an older live version. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.versions.activate",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -1511,6 +1941,12 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ActivateWorkflowVersionRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {}
+                }
               }
             }
           }
@@ -1533,6 +1969,37 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ActivateWorkflowVersionResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "isDeployed": false,
+                        "deployedAt": null,
+                        "warnings": [],
+                        "activeDeployment": null,
+                        "latestDeploymentAttempt": {
+                          "id": "depop_01J8ZK4RX5N7Y3S0U8D6E1W2",
+                          "deploymentVersionId": "depver_01J8ZK4RX5N7Y3S0U8D6E1W3",
+                          "version": 3,
+                          "action": "activate",
+                          "status": "activating",
+                          "isCurrent": true,
+                          "readiness": {
+                            "webhooks": "ready",
+                            "schedules": "ready",
+                            "mcp": "not_applicable"
+                          },
+                          "requestedAt": "2026-06-12T10:30:00.000Z",
+                          "activatedAt": null,
+                          "error": null
+                        },
+                        "version": 3
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1576,8 +2043,8 @@
     "/api/v2/workflows/{workflowId}/versions/{version}/revert": {
       "post": {
         "operationId": "revertWorkflowVersion",
-        "summary": "Revert Workflow To Version",
-        "description": "Replace the editable draft with a deployment version, discarding current draft edits. Use `active` for the live version. The live deployment remains unchanged; Activate Workflow Version or Rollback Workflow changes it. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Revert workflow to version",
+        "description": "Overwrite the editable draft with a deployment version, discarding current draft edits. Requires workspace Admin access. Use `active` for the live version. The live deployment is unchanged; use Activate workflow version or Rollback workflow to change it. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.versions.revert",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -1622,6 +2089,12 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RevertWorkflowVersionRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {}
+                }
               }
             }
           }
@@ -1644,6 +2117,18 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RevertWorkflowVersionResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "version": 3,
+                        "lastSaved": 1765535400000
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1687,8 +2172,8 @@
     "/api/v2/workflows/{workflowId}/deployment": {
       "get": {
         "operationId": "getWorkflowDeployment",
-        "summary": "Get Workflow Deployment",
-        "description": "Read live status, deployment time, latest attempt readiness and failure, draft divergence (`needsRedeployment`), anonymous execution access (`isPublicApi`), and registered webhook URLs. This read exposes public API access and webhook URLs; see their field descriptions for security and delivery details.\n\n`/workflows/{workflowId}/deployment` controls overall API executability; `/deployments/chat` controls only the hosted-chat surface. A workflow can remain deployed without a chat.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workflow deployment",
+        "description": "Read live deployment status, the latest attempt's readiness or failure, and draft divergence (`needsRedeployment`). Requires workspace read access. `isPublicApi` reports anonymous billed execution; `webhooks` lists registered delivery URLs.\n\n`/workflows/{workflowId}/deployment` controls overall API executability; `/deployments/chat` controls only the hosted-chat surface. A workflow can remain deployed without a chat.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.read",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -1724,6 +2209,49 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/WorkflowDeploymentResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "isDeployed": true,
+                        "needsRedeployment": true,
+                        "isPublicApi": false,
+                        "deployedAt": "2026-06-12T10:30:00.000Z",
+                        "warnings": [],
+                        "activeDeployment": {
+                          "deploymentVersionId": "depver_01J8ZK3QW4M6X2R9T7B5C0V2",
+                          "version": 3,
+                          "deployedAt": "2026-06-12T10:30:00.000Z"
+                        },
+                        "latestDeploymentAttempt": {
+                          "id": "depop_01J8ZK3QW4M6X2R9T7B5C0V1",
+                          "deploymentVersionId": "depver_01J8ZK3QW4M6X2R9T7B5C0V2",
+                          "version": 3,
+                          "action": "deploy",
+                          "status": "active",
+                          "isCurrent": true,
+                          "readiness": {
+                            "webhooks": "ready",
+                            "schedules": "ready",
+                            "mcp": "not_applicable"
+                          },
+                          "requestedAt": "2026-06-12T10:29:58.000Z",
+                          "activatedAt": "2026-06-12T10:30:00.000Z",
+                          "error": null
+                        },
+                        "webhooks": [
+                          {
+                            "blockId": "blk_01J8ZK3QW4M6X2R9T7B5C0V3",
+                            "provider": "generic",
+                            "url": "https://www.sim.ai/api/webhooks/trigger/leads"
+                          }
+                        ]
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1753,8 +2281,8 @@
       },
       "patch": {
         "operationId": "updateWorkflowPublicApi",
-        "summary": "Update Workflow Public API Access",
-        "description": "Enable or disable unauthenticated execution of the deployed workflow. Enabling allows anyone with the execution URL to consume billed usage. Organization sharing restrictions return `403` with `PUBLIC_SHARING_NOT_ALLOWED`. Hosted chat is managed separately. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update workflow public API access",
+        "description": "Enable or disable unauthenticated execution of the deployed workflow. Requires workspace Admin access. Enabling lets anyone with the execution URL consume billed usage. Organization sharing restrictions return `403` with `PUBLIC_SHARING_NOT_ALLOWED`. Hosted chat is managed separately. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.public_api.update",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -1779,6 +2307,14 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/UpdateWorkflowPublicApiRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "isPublicApi": true
+                  }
+                }
               }
             }
           }
@@ -1801,6 +2337,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UpdateWorkflowPublicApiResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "isPublicApi": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1841,8 +2388,8 @@
     "/api/v2/workflows/{workflowId}/deploy": {
       "post": {
         "operationId": "deployWorkflow",
-        "summary": "Deploy Workflow",
-        "description": "Create and asynchronously activate a deployment version. Every call creates a new version; retrying after a timeout can create a duplicate. Read Get Workflow Deployment to check activation. `lint` reports advisory findings for the published version; they never block the deploy. A conflicting webhook path returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Deploy workflow",
+        "description": "Create a deployment version and activate it asynchronously. Requires workspace Admin access. Each accepted deploy creates a new version; retrying after a timeout can create a duplicate. Poll Get workflow deployment for the accepted `latestDeploymentAttempt` before treating the version as live.\n\n`lint` reports advisory findings for this version and never blocks deployment. A conflicting webhook path returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.deploy",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -1867,6 +2414,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/DeployWorkflowRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "name": "Escalation routing",
+                    "description": "Adds the priority escalation branch."
+                  }
+                }
               }
             }
           }
@@ -1889,6 +2445,49 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeployWorkflowResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "isDeployed": false,
+                        "deployedAt": null,
+                        "warnings": [],
+                        "activeDeployment": null,
+                        "latestDeploymentAttempt": {
+                          "id": "depop_01J8ZK3QW4M6X2R9T7B5C0V1",
+                          "deploymentVersionId": "depver_01J8ZK3QW4M6X2R9T7B5C0V2",
+                          "version": 3,
+                          "action": "deploy",
+                          "status": "preparing",
+                          "isCurrent": true,
+                          "readiness": {
+                            "webhooks": "pending",
+                            "schedules": "ready",
+                            "mcp": "not_applicable"
+                          },
+                          "requestedAt": "2026-06-12T10:30:00.000Z",
+                          "activatedAt": null,
+                          "error": null
+                        },
+                        "version": 3,
+                        "lint": {
+                          "sources": [],
+                          "sinks": [],
+                          "orphanBlocks": [],
+                          "emptyOutgoingPorts": [],
+                          "invalidBranchPorts": [],
+                          "invalidConnectionTargets": [],
+                          "fieldIssues": [],
+                          "unresolvedReferences": [],
+                          "tableFieldIssues": [],
+                          "notes": []
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1930,8 +2529,8 @@
       },
       "delete": {
         "operationId": "undeployWorkflow",
-        "summary": "Undeploy Workflow",
-        "description": "Deactivate the currently serving workflow version. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Undeploy workflow",
+        "description": "Deactivate the live workflow version and stop its scheduled and webhook triggers. Requires workspace Admin access and a deployed workflow. Deployed MCP tools become inactive; `archivedMcpTools` identifies them. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.undeploy",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -1967,6 +2566,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/UndeployWorkflowResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "isDeployed": false,
+                        "deployedAt": null,
+                        "warnings": [],
+                        "activeDeployment": null,
+                        "latestDeploymentAttempt": null,
+                        "archivedMcpTools": []
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2001,8 +2616,8 @@
     "/api/v2/workflows/{workflowId}/rollback": {
       "post": {
         "operationId": "rollbackWorkflow",
-        "summary": "Rollback Workflow",
-        "description": "Asynchronously activate a previous deployment version, defaulting to the preceding active version. Requires a deployed workflow and leaves the draft unchanged. Use Activate Workflow Version to select a version when the workflow is undeployed. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Rollback workflow",
+        "description": "Activate a previous deployment version asynchronously, defaulting to the preceding active version. Requires workspace Admin access and a deployed workflow. The draft is unchanged. Poll the accepted `latestDeploymentAttempt`. To select a version while undeployed, use Activate workflow version. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.versions.activate",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -2027,6 +2642,14 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RollbackWorkflowRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "version": 2
+                  }
+                }
               }
             }
           }
@@ -2049,6 +2672,37 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RollbackWorkflowResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "isDeployed": false,
+                        "deployedAt": null,
+                        "warnings": [],
+                        "activeDeployment": null,
+                        "latestDeploymentAttempt": {
+                          "id": "depop_01J8ZK4RX5N7Y3S0U8D6E1W2",
+                          "deploymentVersionId": "depver_01J8ZK4RX5N7Y3S0U8D6E1W3",
+                          "version": 2,
+                          "action": "activate",
+                          "status": "activating",
+                          "isCurrent": true,
+                          "readiness": {
+                            "webhooks": "ready",
+                            "schedules": "ready",
+                            "mcp": "not_applicable"
+                          },
+                          "requestedAt": "2026-06-12T10:30:00.000Z",
+                          "activatedAt": null,
+                          "error": null
+                        },
+                        "version": 2
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2092,8 +2746,8 @@
     "/api/v2/workflows/{workflowId}/export": {
       "get": {
         "operationId": "exportWorkflow",
-        "summary": "Export Workflow",
-        "description": "Export a portable, secret-sanitized workflow. Use includeReferences=true for non-secret source identities and field occurrences used by mapped imports. Use includeWorkspaceBindings=true to retain non-secret workspace bindings for a same-workspace round trip; default exports clear those bindings. Credentials and secrets are cleared either way. Exporting records an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "summary": "Export workflow",
+        "description": "Export the saved draft as portable workflow data with workspace read access. Registered credential fields and opaque table/tool values are cleared; environment references and ordinary workflow variables remain included. Review other configuration before sharing.\n\nDefault exports clear workspace bindings. Use `includeWorkspaceBindings=true` to retain non-secret bindings for a same-workspace import, or `includeReferences=true` for source identities and field occurrences used by mapped imports. Exporting records an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.export",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -2124,9 +2778,9 @@
             "name": "includeWorkspaceBindings",
             "in": "query",
             "required": false,
-            "description": "Whether to keep workspace-scoped bindings — table, knowledge base, document, folder, channel, and other resource selectors — in the exported state. Defaults to false, the sharing-safe export in which those ids are cleared because they resolve nowhere else. Send true for a same-workspace round trip so the re-imported workflow can run without re-selecting them. Credentials, passwords, and table sub-block values are cleared either way.",
+            "description": "Keep non-secret table, knowledge base, document, folder, channel, and other workspace bindings for a same-workspace import. Defaults to false, which clears these IDs. Registered credential fields and opaque table/tool values are cleared either way; environment references and ordinary workflow variables remain included.",
             "schema": {
-              "description": "Whether to keep workspace-scoped bindings — table, knowledge base, document, folder, channel, and other resource selectors — in the exported state. Defaults to false, the sharing-safe export in which those ids are cleared because they resolve nowhere else. Send true for a same-workspace round trip so the re-imported workflow can run without re-selecting them. Credentials, passwords, and table sub-block values are cleared either way.",
+              "description": "Keep non-secret table, knowledge base, document, folder, channel, and other workspace bindings for a same-workspace import. Defaults to false, which clears these IDs. Registered credential fields and opaque table/tool values are cleared either way; environment references and ordinary workflow variables remain included.",
               "type": "boolean"
             }
           }
@@ -2149,6 +2803,28 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ExportWorkflowResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "version": "1.0",
+                        "exportedAt": "2026-08-09T18:04:11.000Z",
+                        "workflow": {
+                          "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                          "name": "Customer support triage",
+                          "description": "Routes incoming support requests to the right team.",
+                          "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                          "folderPath": "/Operations"
+                        },
+                        "state": {
+                          "blocks": {},
+                          "edges": []
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2183,18 +2859,31 @@
     "/api/v2/workflows/import": {
       "post": {
         "operationId": "importWorkflow",
-        "summary": "Import Workflow",
-        "description": "Create an undeployed workflow from a portable export object, bare state, or JSON string. Mapping options require a preview fingerprint and stable request ID; unresolved required configuration creates nothing. Mapped imports return source-to-imported block IDs and an operation receipt. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+        "summary": "Import workflow",
+        "description": "Create an undeployed workflow from a portable export object, bare draft state, or JSON string. Requires workspace write access. The empty-state example creates a draft that needs runnable blocks before execution.\n\nMapped imports require a preview with the same choices, its `previewFingerprint`, and a stable `requestId`. Unresolved required configuration creates nothing. Identical retries return the committed result; reusing the ID with changed inputs returns `409`. The result includes regenerated graph IDs and an operation receipt. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.import",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
         "requestBody": {
           "required": true,
-          "description": "Workflow document, destination, and optional reviewed mappings.",
+          "description": "Workflow document, destination, and optional reviewed mappings. This example creates an empty draft.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ImportWorkflowBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "name": "Support draft",
+                    "workflow": {
+                      "blocks": {},
+                      "edges": []
+                    }
+                  }
+                }
               }
             }
           }
@@ -2217,6 +2906,42 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ImportWorkflowResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "name": "Customer support triage",
+                        "description": "Routes incoming support requests to the right team.",
+                        "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                        "folderPath": "/Operations",
+                        "createdAt": "2026-05-01T09:00:00.000Z",
+                        "updatedAt": "2026-08-09T18:04:11.000Z",
+                        "blocks": [
+                          {
+                            "id": "block_start",
+                            "type": "starter",
+                            "name": "Start"
+                          },
+                          {
+                            "id": "block_triage",
+                            "type": "agent",
+                            "name": "Triage"
+                          },
+                          {
+                            "id": "block_reply",
+                            "type": "response",
+                            "name": "Reply"
+                          }
+                        ],
+                        "warnings": [
+                          "Triage: knowledgeBaseId was stripped by export; set it before running"
+                        ]
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2260,8 +2985,8 @@
     "/api/v2/chat-deployments": {
       "get": {
         "operationId": "listChatDeployments",
-        "summary": "List Chat Deployments",
-        "description": "List hosted chats and their public URLs with cursor pagination. Filter by `workflowId` for one workflow's chat. The list requires workspace read access; Get Workflow Chat Deployment requires admin access and includes visitor access settings and customizations. Passwords are never returned.\n\nOAuth scope: `api:read`.",
+        "summary": "List chat deployments",
+        "description": "List hosted chats and their URLs with workspace read access and cursor pagination. Filter by `workflowId` for one workflow's chat. The admin-only detail read also includes visitor access settings and customizations. Passwords are never returned; organization permission groups can restrict chat deployment access.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "chat_deployments.list",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -2366,6 +3091,37 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ChatDeploymentListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "id": "chat_01J8ZK3QW4M6X2R9T7B5C0V2",
+                          "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                          "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+                          "identifier": "support",
+                          "url": "https://sim.ai/chat/support",
+                          "title": "Support chat",
+                          "description": "Ask about billing, onboarding, or outages.",
+                          "isActive": true,
+                          "authType": "public",
+                          "outputConfigs": [
+                            {
+                              "blockId": "block_01J8ZK3QW4M6X2R9T7B5C0V4",
+                              "path": "content"
+                            }
+                          ],
+                          "includeThinking": false,
+                          "includeToolCalls": false,
+                          "createdAt": "2026-06-12T10:30:00.000Z",
+                          "updatedAt": "2026-06-12T10:30:00.000Z"
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -2397,8 +3153,8 @@
     "/api/v2/workflows/{workflowId}/deployments/chat": {
       "get": {
         "operationId": "getWorkflowChatDeployment",
-        "summary": "Get Workflow Chat Deployment",
-        "description": "Get a workflow's hosted chat and visitor access settings. Requires workspace admin access; a missing chat returns `404`. Passwords are never returned; `hasPassword` indicates whether one is set. Hosted chat and workflow API deployment are managed separately. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workflow chat deployment",
+        "description": "Get a workflow's hosted chat and visitor access settings with workspace Admin access. A missing chat returns `404`. Passwords are never returned; `hasPassword` reports whether one is set. Hosted chat and workflow API deployment are managed separately. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "chat_deployments.read",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -2434,6 +3190,40 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/GetWorkflowChatDeploymentResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "chat_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+                        "identifier": "support",
+                        "url": "https://sim.ai/chat/support",
+                        "title": "Support chat",
+                        "description": "Ask about billing, onboarding, or outages.",
+                        "isActive": true,
+                        "authType": "public",
+                        "hasPassword": false,
+                        "allowedEmails": [],
+                        "customizations": {
+                          "primaryColor": "#6F3DFA",
+                          "welcomeMessage": "Hi there! How can I help?"
+                        },
+                        "outputConfigs": [
+                          {
+                            "blockId": "block_01J8ZK3QW4M6X2R9T7B5C0V4",
+                            "path": "content"
+                          }
+                        ],
+                        "includeThinking": false,
+                        "includeToolCalls": false,
+                        "createdAt": "2026-06-12T10:30:00.000Z",
+                        "updatedAt": "2026-06-12T10:30:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2463,8 +3253,8 @@
       },
       "put": {
         "operationId": "replaceWorkflowChatDeployment",
-        "summary": "Create or Replace Workflow Chat Deployment",
-        "description": "Create or replace a workflow's hosted chat and deploy its draft. Omitted fields reset to defaults except per-field customizations. Password authentication requires `password`; email or SSO requires non-empty `allowedEmails`. Public authentication allows anyone with the chat URL to use it. A duplicate identifier or pending deployment returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Create or replace workflow chat deployment",
+        "description": "Create or replace a workflow's hosted chat and deploy its saved draft. Requires workspace Admin access. Omitted fields use defaults; customization exceptions are described on their fields.\n\nPassword authentication requires `password`; email or SSO requires non-empty `allowedEmails`. Public authentication lets anyone with the chat URL run it. A duplicate identifier or pending deployment returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "chat_deployments.replace",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -2489,13 +3279,22 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ReplaceChatDeploymentRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "identifier": "support",
+                    "title": "Support chat"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "The published chat deployment.",
+            "description": "The saved chat deployment.",
             "headers": {
               "X-RateLimit-Limit": {
                 "$ref": "#/components/headers/X-RateLimit-Limit"
@@ -2511,6 +3310,40 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ReplaceWorkflowChatDeploymentResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "chat_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+                        "identifier": "support",
+                        "url": "https://sim.ai/chat/support",
+                        "title": "Support chat",
+                        "description": "Ask about billing, onboarding, or outages.",
+                        "isActive": true,
+                        "authType": "public",
+                        "hasPassword": false,
+                        "allowedEmails": [],
+                        "customizations": {
+                          "primaryColor": "#6F3DFA",
+                          "welcomeMessage": "Hi there! How can I help?"
+                        },
+                        "outputConfigs": [
+                          {
+                            "blockId": "block_01J8ZK3QW4M6X2R9T7B5C0V4",
+                            "path": "content"
+                          }
+                        ],
+                        "includeThinking": false,
+                        "includeToolCalls": false,
+                        "createdAt": "2026-06-12T10:30:00.000Z",
+                        "updatedAt": "2026-06-12T10:30:00.000Z"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2552,8 +3385,8 @@
       },
       "delete": {
         "operationId": "deleteWorkflowChatDeployment",
-        "summary": "Delete Workflow Chat Deployment",
-        "description": "Remove a workflow's hosted chat and release its URL identifier. The workflow API deployment remains active; use Undeploy Workflow to stop it. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete workflow chat deployment",
+        "description": "Remove the hosted chat and release its URL identifier with workspace Admin access. The workflow API deployment remains active; use Undeploy workflow to stop it. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "chat_deployments.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -2589,6 +3422,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeleteWorkflowChatDeploymentResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "id": "chat_01J8ZK3QW4M6X2R9T7B5C0V2",
+                        "deleted": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2620,8 +3464,8 @@
     "/api/v2/workflows/{workflowId}/execute": {
       "post": {
         "operationId": "executeWorkflowV2",
-        "summary": "Execute Workflow",
-        "description": "Execute a deployment or use `run.source: \"manual\"` for the draft. Manual runs require personal or OAuth write access and reject async. Public deployments allow anonymous sync or streaming. Request `application/x-ndjson` for heartbeats and the final result. Timeouts return `200` with failed status and `TIMEOUT`. Supply `X-Run-Id` to prevent duplicate execution; reuse returns `409`, never a replay. Input descriptions specify compatible modes; invalid combinations return `400`.\n\nOAuth scope: `api:write`.",
+        "summary": "Execute workflow",
+        "description": "Run the active deployment, or set `run.source: \"manual\"` to run the saved draft. Deployed execution requires workspace read access and OAuth `api:write` scope or an API key; public deployments also allow anonymous synchronous or streamed runs. Manual runs require personal-key or OAuth write access and cannot be async.\n\nUse `async: true` for a queue receipt, or `stream: true` for SSE. For a synchronous run with both flags false, send `Accept: application/x-ndjson` for heartbeat frames and a final frame containing `data`. Timeouts return `200` with `status: \"failed\"` and `error.code: \"TIMEOUT\"`; inspect run status. See [Streaming](/workflows/deployment/api#streaming) for event formats. Input descriptions specify compatible modes; invalid combinations return `400`.\n\nSupply `X-Run-Id` to prevent duplicate execution. Reuse returns `409`, without replaying results. A `503` with `error.details.code: \"ASYNC_ENQUEUE_AMBIGUOUS\"` omits `Retry-After` because the run may already have started. Reconcile using the returned run ID; do not start another run with a new or omitted ID.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.execute",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -2651,9 +3495,9 @@
             "name": "x-run-id",
             "in": "header",
             "required": false,
-            "description": "Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get Workflow Run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.",
+            "description": "Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get workflow run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.",
             "schema": {
-              "description": "Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get Workflow Run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.",
+              "description": "Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get workflow run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.",
               "type": "string",
               "minLength": 1,
               "maxLength": 128,
@@ -2679,6 +3523,69 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ExecuteWorkflowRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "input": {
+                      "ticketId": "ticket_123"
+                    }
+                  }
+                },
+                "example2": {
+                  "summary": "Request example 2",
+                  "value": {
+                    "input": {
+                      "ticketId": "ticket_123"
+                    },
+                    "async": true
+                  }
+                },
+                "example3": {
+                  "summary": "Request example 3",
+                  "value": {
+                    "input": {
+                      "ticketId": "ticket_123"
+                    },
+                    "stream": true
+                  }
+                },
+                "example4": {
+                  "summary": "Request example 4",
+                  "value": {
+                    "run": {
+                      "source": "manual"
+                    }
+                  }
+                },
+                "example5": {
+                  "summary": "Request example 5",
+                  "value": {
+                    "run": {
+                      "source": "manual",
+                      "entry": {
+                        "type": "block",
+                        "blockId": "block_123",
+                        "sourceRunId": "run_123"
+                      }
+                    }
+                  }
+                },
+                "example6": {
+                  "summary": "Request example 6",
+                  "value": {
+                    "run": {
+                      "source": "manual",
+                      "entry": {
+                        "type": "block",
+                        "blockId": "block_123",
+                        "sourceRunId": "run_123"
+                      },
+                      "stopAfterBlockId": "block_123"
+                    }
+                  }
+                }
               }
             }
           }
@@ -2704,6 +3611,26 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ExecuteWorkflowSyncResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "runId": "run_8f14e45f-ceea-467f-a",
+                        "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "status": "completed",
+                        "output": {
+                          "result": "Ticket routed to Support"
+                        },
+                        "blockOutputs": null,
+                        "error": null,
+                        "startedAt": "2026-08-09T18:04:10.000Z",
+                        "endedAt": "2026-08-09T18:04:11.000Z",
+                        "durationMs": 1000
+                      }
+                    }
+                  }
                 }
               },
               "application/x-ndjson": {
@@ -2738,6 +3665,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ExecuteWorkflowQueuedResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "runId": "run_8f14e45f-ceea-467f-a",
+                        "statusUrl": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -2784,8 +3722,8 @@
     "/api/v2/workflows/{workflowId}/runs": {
       "get": {
         "operationId": "listWorkflowRunsV2",
-        "summary": "List Workflow Runs",
-        "description": "List recorded runs of a workflow with filtering and opaque cursor pagination. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides.\n\nOAuth scope: `api:read`.",
+        "summary": "List workflow runs",
+        "description": "List recorded workflow runs with workspace read access, filters, and cursor pagination. Cost can be hidden by organization permission groups. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.runs.list",
         "x-oauth-scope": "api:read",
         "tags": ["Workflow Runs"],
@@ -2903,6 +3841,28 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/WorkflowRunListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "runId": "run_8f14e45f-ceea-467f-a",
+                          "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                          "status": "completed",
+                          "trigger": "api",
+                          "startedAt": "2026-08-09T18:04:10.000Z",
+                          "endedAt": "2026-08-09T18:04:11.000Z",
+                          "durationMs": 1000,
+                          "cost": {
+                            "total": 12
+                          }
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -2934,8 +3894,8 @@
     "/api/v2/workflows/{workflowId}/runs/{runId}": {
       "get": {
         "operationId": "getWorkflowRunV2",
-        "summary": "Get Workflow Run",
-        "description": "Get current run state with optional final and block outputs. With `includeOutput`, `files` includes download paths; `includeFileBase64` inlines file bytes and returns `413` with the download path when one file or the total exceeds 16 MiB. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workflow run",
+        "description": "Read current run state with workspace read access. Request final output and files with `includeOutput`, or block outputs with `selectedOutputs`. Organization permission groups can hide output, files, or cost.\n\n`includeFileBase64` inlines file bytes. A file or the total above 16 MiB returns `413` naming a download path; download large files individually. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.runs.read",
         "x-oauth-scope": "api:read",
         "tags": ["Workflow Runs"],
@@ -3026,6 +3986,41 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/WorkflowRunStatusResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "runId": "run_8f14e45f-ceea-467f-a",
+                        "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "status": "completed",
+                        "trigger": "api",
+                        "startedAt": "2026-08-09T18:04:10.000Z",
+                        "endedAt": "2026-08-09T18:04:11.000Z",
+                        "durationMs": 1000,
+                        "paused": null,
+                        "cost": {
+                          "total": 12
+                        },
+                        "error": null,
+                        "output": {
+                          "result": "Ticket routed to Support"
+                        },
+                        "blockOutputs": null,
+                        "files": [
+                          {
+                            "id": "file_1a2b3c",
+                            "name": "summary.pdf",
+                            "size": 20480,
+                            "type": "application/pdf",
+                            "downloadPath": "/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a/files/file_1a2b3c",
+                            "base64": null
+                          }
+                        ]
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3063,8 +4058,8 @@
     "/api/v2/workflows/{workflowId}/runs/{runId}/files/{fileId}": {
       "get": {
         "operationId": "downloadWorkflowRunFileV2",
-        "summary": "Download Workflow Run File",
-        "description": "Download one run-produced file by ID. Downloads record an audit event. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` omits `Content-Length`; use file metadata to size downloads.\n\nOAuth scope: `api:read`.",
+        "summary": "Download workflow run file",
+        "description": "Download one run-produced file by its reported ID with workspace read access. Downloads record an audit event. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. `HEAD` does not provide byte length; use the file's size in Get workflow run when available.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.download_run_file",
         "x-oauth-scope": "api:read",
         "tags": ["Workflow Runs"],
@@ -3169,8 +4164,8 @@
     "/api/v2/workflows/{workflowId}/runs/{runId}/resume": {
       "post": {
         "operationId": "resumeWorkflowRunV2",
-        "summary": "Resume Workflow Run",
-        "description": "Resume one human-in-the-loop pause. The resumed attempt receives a new run ID and returns either a synchronous result or a queue receipt.\n\nOAuth scope: `api:write`.",
+        "summary": "Resume workflow run",
+        "description": "Resume one human-in-the-loop pause with workspace write access. The resumed attempt receives a new run ID and returns a synchronous result or queue receipt. A run that originally streamed resumes asynchronously through v2; this endpoint returns no SSE stream.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.runs.resume",
         "x-oauth-scope": "api:write",
         "tags": ["Workflow Runs"],
@@ -3208,6 +4203,17 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ResumeWorkflowRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "contextId": "ctx_123",
+                    "input": {
+                      "approved": true
+                    }
+                  }
+                }
               }
             }
           }
@@ -3233,6 +4239,26 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ResumeWorkflowSyncResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "runId": "run_8f14e45f-ceea-467f-a",
+                        "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
+                        "status": "completed",
+                        "output": {
+                          "result": "Ticket routed to Support"
+                        },
+                        "blockOutputs": null,
+                        "error": null,
+                        "startedAt": "2026-08-09T18:04:10.000Z",
+                        "endedAt": "2026-08-09T18:04:11.000Z",
+                        "durationMs": 1000
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3257,6 +4283,17 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ResumeWorkflowQueuedResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "runId": "run_8f14e45f-ceea-467f-a",
+                        "statusUrl": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3300,8 +4337,8 @@
     "/api/v2/workflows/{workflowId}/runs/{runId}/cancel": {
       "post": {
         "operationId": "cancelRunV2",
-        "summary": "Cancel Workflow Run",
-        "description": "Request cancellation of a running, queued, or paused workflow run. Cancelling a run already in a terminal state is a `200` no-op answered with `success: false` and an `already_*` reason. A run produced by a table workflow group is a `409` when its cell can no longer accept the cancellation.\n\nOAuth scope: `api:write`.",
+        "summary": "Cancel workflow run",
+        "description": "Request cancellation of a running, queued, or paused workflow run with workspace write access. Cancellation is best effort; inspect the outcome flags and `reason`. A terminal run returns `200` with `success: false` and an `already_*` reason. A table workflow-group run returns `409` when its cell can no longer accept cancellation.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.runs.cancel",
         "x-oauth-scope": "api:write",
         "tags": ["Workflow Runs"],
@@ -3350,6 +4387,22 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CancelWorkflowRunResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "success": true,
+                        "runId": "run_8f14e45f-ceea-467f-a",
+                        "redisAvailable": true,
+                        "durablyRecorded": true,
+                        "locallyAborted": true,
+                        "pausedCancelled": false,
+                        "reason": "recorded"
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3384,8 +4437,8 @@
     "/api/v2/workflows/folders": {
       "get": {
         "operationId": "listWorkflowsFolders",
-        "summary": "List Workflow Folders",
-        "description": "List workflow folders in a workspace. Returns the complete set in one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+        "summary": "List workflow folders",
+        "description": "List workflow folders with workspace read access, optional parent/name filters, and sorting. Returns one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workflows.folders.list",
         "x-oauth-scope": "api:read",
         "tags": ["Workflows"],
@@ -3428,10 +4481,10 @@
             "name": "sortBy",
             "in": "query",
             "required": false,
-            "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+            "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
             "schema": {
               "default": "name",
-              "description": "Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.",
+              "description": "Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.",
               "type": "string",
               "enum": ["name", "createdAt", "updatedAt"]
             }
@@ -3467,6 +4520,24 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/WorkflowFolderListResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": [
+                        {
+                          "name": "Operations",
+                          "path": "/Operations",
+                          "parentPath": "/",
+                          "createdAt": "2026-05-01T09:00:00.000Z",
+                          "updatedAt": "2026-05-01T09:00:00.000Z",
+                          "locked": false
+                        }
+                      ],
+                      "nextCursor": null
+                    }
+                  }
                 }
               }
             }
@@ -3499,8 +4570,8 @@
       },
       "post": {
         "operationId": "createWorkflowsFolder",
-        "summary": "Create Workflow Folder",
-        "description": "Create a workflow folder in a workspace. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+        "summary": "Create workflow folder",
+        "description": "Create a workflow folder at a non-root path with workspace write access. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.folders.create",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -3511,6 +4582,15 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/CreateWorkflowFolderRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "path": "/Operations"
+                  }
+                }
               }
             }
           }
@@ -3533,6 +4613,21 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateWorkflowFolderResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "name": "Operations",
+                        "path": "/Operations",
+                        "parentPath": "/",
+                        "createdAt": "2026-05-01T09:00:00.000Z",
+                        "updatedAt": "2026-05-01T09:00:00.000Z",
+                        "locked": false
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3574,8 +4669,8 @@
       },
       "patch": {
         "operationId": "relocateWorkflowsFolder",
-        "summary": "Rename or Move Workflow Folder",
-        "description": "Rename or move a workflow folder and update all descendant paths. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+        "summary": "Rename or move workflow folder",
+        "description": "Rename or move a workflow folder and update descendant paths with workspace write access. An existing destination receives the folder as a child; otherwise the destination is its new full path. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.folders.relocate",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -3586,6 +4681,16 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/RelocateWorkflowFolderRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "path": "/Operations",
+                    "destinationPath": "/Support"
+                  }
+                }
               }
             }
           }
@@ -3608,6 +4713,21 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/RelocateWorkflowFolderResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "name": "Support",
+                        "path": "/Support",
+                        "parentPath": "/",
+                        "createdAt": "2026-05-01T09:00:00.000Z",
+                        "updatedAt": "2026-05-01T09:00:00.000Z",
+                        "locked": false
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3649,8 +4769,8 @@
       },
       "delete": {
         "operationId": "deleteWorkflowsFolder",
-        "summary": "Delete Workflow Folder",
-        "description": "Archive an empty workflow folder, or set `recursive=true` to archive its subfolders and workflows. Use Restore Workflow to recover workflows.\n\nOAuth scope: `api:write`.",
+        "summary": "Delete workflow folder",
+        "description": "Archive an empty workflow folder with workspace write access. `recursive=true` also archives its subfolders and workflows, stopping the archived workflows' triggers and hosted surfaces. Use Restore workflow to recover workflows.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.folders.delete",
         "x-oauth-scope": "api:write",
         "tags": ["Workflows"],
@@ -3681,9 +4801,9 @@
             "name": "recursive",
             "in": "query",
             "required": false,
-            "description": "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+            "description": "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
             "schema": {
-              "description": "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+              "description": "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
               "enum": [
                 "true",
                 "1",
@@ -3721,6 +4841,21 @@
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/DeleteWorkflowFolderResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "path": "/Operations",
+                        "deleted": true,
+                        "deletedItems": {
+                          "folders": 1,
+                          "workflows": 0
+                        }
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3761,8 +4896,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/preview": {
       "post": {
         "operationId": "previewWorkspaceFork",
-        "summary": "Preview Workspace Fork",
-        "description": "Preview the deployed workflows and explicitly selected resources that a new workspace fork would copy. The result is read-only and supplies the fingerprint required by Fork Workspace. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Preview workspace fork",
+        "description": "Preview deployed workflows and explicitly selected resources for a new child workspace. Requires source workspace Admin access and permission to create a workspace in its organization. The read-only result supplies the fingerprint for Fork workspace with the same choices. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.fork.preview",
         "x-oauth-scope": "api:write",
         "tags": ["Workspace Sync"],
@@ -3782,7 +4917,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Optional child name and explicitly selected resource copies.",
           "content": {
             "application/json": {
               "schema": {
@@ -3793,7 +4928,7 @@
         },
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Deployed source workflows, selected-copy count, and a preview fingerprint.",
             "content": {
               "application/json": {
                 "schema": {
@@ -3835,8 +4970,8 @@
     "/api/v2/workspaces/{workspaceId}/fork": {
       "post": {
         "operationId": "forkWorkspace",
-        "summary": "Fork Workspace",
-        "description": "Create a child workspace with undeployed workflow drafts. Requires the reviewed preview fingerprint and a stable request ID. Identical retries return the same operation; reuse with different inputs returns 409. Poll Get Workspace Operation until selected resource copies complete. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Fork workspace",
+        "description": "Create a child workspace with undeployed drafts of the source's deployed workflows. Requires source workspace Admin access and permission to create a workspace in its organization. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`.\n\nFirst preview the same name and copy choices, then send the returned fingerprint and a stable request ID. The example fingerprint is illustrative. Identical retries return the same committed operation; changed inputs with that ID return `409`. Poll Get workspace operation until selected resource copies finish. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.fork.create",
         "x-oauth-scope": "api:write",
         "tags": ["Workspace Sync"],
@@ -3856,22 +4991,49 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Child name and copy choices, with the actual preview fingerprint and a stable request ID.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ForkWorkspaceBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "name": "Support sandbox",
+                    "requestId": "fork-support-2026-10-13",
+                    "previewFingerprint": "c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a"
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Committed fork receipt and resource-copy progress.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/ForkWorkspaceResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "operationId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
+                        "requestId": "fork-support-2026-10-13",
+                        "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+                        "kind": "workspace_fork",
+                        "applied": true,
+                        "status": "processing",
+                        "resourceIds": ["destination_workflow_id"],
+                        "issues": []
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -3909,8 +5071,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/push/preview": {
       "post": {
         "operationId": "previewWorkspacePush",
-        "summary": "Preview Workspace Push",
-        "description": "Preview deployed source workflows replacing mapped targets along a direct fork edge. Push sends the current workspace to the other; pull brings the other into the current workspace. Proposed mappings are not saved. Dependent choices use source workflow, block, and field identities. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Preview workspace push",
+        "description": "Preview changes from this workspace into the other workspace along a direct fork edge. Requires Admin access to both workspaces. The plan lists workflows to create, replace, or archive; replacements overwrite target drafts with the source deployment. Proposed mappings are not saved. Dependent choices use source workflow, block, and field IDs. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.fork.sync.preview",
         "x-oauth-scope": "api:write",
         "tags": ["Workspace Sync"],
@@ -3930,7 +5092,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Other workspace and proposed source-to-target sync choices.",
           "content": {
             "application/json": {
               "schema": {
@@ -3941,7 +5103,7 @@
         },
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Current-to-other workflow actions, required choices, and preview fingerprint.",
             "content": {
               "application/json": {
                 "schema": {
@@ -3983,8 +5145,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/push": {
       "post": {
         "operationId": "pushWorkspace",
-        "summary": "Push Workspace",
-        "description": "Apply a reviewed push or pull with inline mappings in one transaction. Requires confirmation, the preview fingerprint, and a stable request ID. Unresolved or changed plans return 409 without applying. The receipt distinguishes committed changes from copy and deployment readiness; poll Get Workspace Operation before treating the target as ready. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Push workspace",
+        "description": "Apply a reviewed sync from this workspace into the other workspace along a direct fork edge. Requires Admin access to both workspaces. Creates unmatched deployed workflows, overwrites mapped target drafts, and archives mapped targets whose sources were deleted or archived. Undeployed sources alone do not archive targets. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`.\n\nSend `confirm: true`, the fingerprint from a preview with identical choices, and a stable request ID. The example hash is illustrative. Changed or unresolved plans return `409` without applying. Identical retries return the committed operation; changed inputs with that ID return `409`. Copies and deployment activation can finish after the transaction commits. Poll Get workspace operation before treating the target as ready. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.fork.sync",
         "x-oauth-scope": "api:write",
         "tags": ["Workspace Sync"],
@@ -4004,22 +5166,50 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Confirmed current-to-other choices, actual preview fingerprint, and stable request ID.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/PushWorkspaceBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "otherWorkspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+                    "requestId": "push-support-2026-10-13",
+                    "previewFingerprint": "c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a",
+                    "confirm": true
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Committed push receipt with copy and deployment readiness.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/PushWorkspaceResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "operationId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
+                        "requestId": "push-support-2026-10-13",
+                        "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+                        "kind": "workspace_push",
+                        "applied": true,
+                        "status": "processing",
+                        "resourceIds": ["destination_workflow_id"],
+                        "issues": []
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -4057,8 +5247,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/pull/preview": {
       "post": {
         "operationId": "previewWorkspacePull",
-        "summary": "Preview Workspace Pull",
-        "description": "Preview deployed source workflows replacing mapped targets along a direct fork edge. Push sends the current workspace to the other; pull brings the other into the current workspace. Proposed mappings are not saved. Dependent choices use source workflow, block, and field identities. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Preview workspace pull",
+        "description": "Preview changes from the other workspace into this workspace along a direct fork edge. Requires Admin access to both workspaces. The plan lists workflows to create, replace, or archive; replacements overwrite target drafts with the source deployment. Proposed mappings are not saved. Dependent choices use source workflow, block, and field IDs. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.fork.sync.preview",
         "x-oauth-scope": "api:write",
         "tags": ["Workspace Sync"],
@@ -4078,7 +5268,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Other workspace and proposed source-to-target sync choices.",
           "content": {
             "application/json": {
               "schema": {
@@ -4089,7 +5279,7 @@
         },
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Other-to-current workflow actions, required choices, and preview fingerprint.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4131,8 +5321,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/pull": {
       "post": {
         "operationId": "pullWorkspace",
-        "summary": "Pull Workspace",
-        "description": "Apply a reviewed push or pull with inline mappings in one transaction. Requires confirmation, the preview fingerprint, and a stable request ID. Unresolved or changed plans return 409 without applying. The receipt distinguishes committed changes from copy and deployment readiness; poll Get Workspace Operation before treating the target as ready. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Pull workspace",
+        "description": "Apply a reviewed sync from the other workspace into this workspace along a direct fork edge. Requires Admin access to both workspaces. Creates unmatched deployed workflows, overwrites mapped target drafts, and archives mapped targets whose sources were deleted or archived. Undeployed sources alone do not archive targets. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`.\n\nSend `confirm: true`, the fingerprint from a preview with identical choices, and a stable request ID. The example hash is illustrative. Changed or unresolved plans return `409` without applying. Identical retries return the committed operation; changed inputs with that ID return `409`. Copies and deployment activation can finish after the transaction commits. Poll Get workspace operation before treating the target as ready. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.fork.sync",
         "x-oauth-scope": "api:write",
         "tags": ["Workspace Sync"],
@@ -4152,22 +5342,50 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Confirmed other-to-current choices, actual preview fingerprint, and stable request ID.",
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/PullWorkspaceBody"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "otherWorkspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+                    "requestId": "pull-support-2026-10-13",
+                    "previewFingerprint": "c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a",
+                    "confirm": true
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Committed pull receipt with copy and deployment readiness.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/PullWorkspaceResponse"
+                },
+                "examples": {
+                  "example1": {
+                    "summary": "Response example 1",
+                    "value": {
+                      "data": {
+                        "operationId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
+                        "requestId": "pull-support-2026-10-13",
+                        "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+                        "kind": "workspace_pull",
+                        "applied": true,
+                        "status": "processing",
+                        "resourceIds": ["destination_workflow_id"],
+                        "issues": []
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -4205,8 +5423,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/availability": {
       "get": {
         "operationId": "getWorkspaceForkAvailability",
-        "summary": "Get Workspace Fork Availability",
-        "description": "Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workspace fork availability",
+        "description": "Check whether workspace forking is enabled for this deployment and workspace plan. Requires workspace Admin access. Returns `available: false` when the feature gate is unmet. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workspaces.fork.discover",
         "x-oauth-scope": "api:read",
         "tags": ["Workspace Sync"],
@@ -4226,7 +5444,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Whether forking is enabled for this deployment and workspace plan.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4268,8 +5486,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/lineage": {
       "get": {
         "operationId": "getWorkspaceForkLineage",
-        "summary": "Get Workspace Fork Lineage",
-        "description": "Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workspace fork lineage",
+        "description": "Read this workspace and its direct parent, or `parent: null` when it has no active parent. Requires workspace Admin access. The relationship does not grant access to the parent. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workspaces.fork.discover",
         "x-oauth-scope": "api:read",
         "tags": ["Workspace Sync"],
@@ -4289,7 +5507,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Current workspace and its active direct parent, when present.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4331,8 +5549,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/children": {
       "get": {
         "operationId": "listWorkspaceForkChildren",
-        "summary": "List Workspace Fork Children",
-        "description": "Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List workspace fork children",
+        "description": "List this workspace's active direct children, newest first, with cursor pagination. Requires workspace Admin access. A fork relationship does not grant access to a child workspace. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workspaces.fork.discover",
         "x-oauth-scope": "api:read",
         "tags": ["Workspace Sync"],
@@ -4400,7 +5618,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "A page of active direct child workspaces.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4442,8 +5660,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/resources": {
       "get": {
         "operationId": "listWorkspaceForkResources",
-        "summary": "List Workspace Fork Resources",
-        "description": "Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List workspace fork resources",
+        "description": "List copyable resources of one kind in this workspace with cursor pagination. Requires workspace Admin access. Fork creation uses file IDs; sync copy choices use file storage keys from source references or file resource reads. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workspaces.fork.discover",
         "x-oauth-scope": "api:read",
         "tags": ["Workspace Sync"],
@@ -4488,7 +5706,7 @@
             "name": "kind",
             "in": "query",
             "required": true,
-            "description": "Resource or operation kind.",
+            "description": "Kind of source resource to list for copy selection.",
             "schema": {
               "type": "string",
               "enum": [
@@ -4500,7 +5718,7 @@
                 "mcpServers",
                 "workflowMcpServers"
               ],
-              "description": "Resource or operation kind."
+              "description": "Kind of source resource to list for copy selection."
             }
           },
           {
@@ -4530,7 +5748,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "A page of copyable resource candidates.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4572,8 +5790,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/mappings": {
       "get": {
         "operationId": "getWorkspaceForkMappings",
-        "summary": "Get Workspace Fork Mappings",
-        "description": "Read persisted mappings in the requested source-to-target direction. Candidate discovery uses the destination resource and selector listing operations. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workspace fork mappings",
+        "description": "Read persisted resource mappings in the requested source-to-target direction along a direct fork edge. Requires Admin access to both workspaces. Discover candidates with destination resource reads and selector operations. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workspaces.fork.mappings.read",
         "x-oauth-scope": "api:read",
         "tags": ["Workspace Sync"],
@@ -4664,7 +5882,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "A page of persisted source-to-target mapping entries.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4704,8 +5922,8 @@
       },
       "put": {
         "operationId": "updateWorkspaceForkMappings",
-        "summary": "Update Workspace Fork Mappings",
-        "description": "Update edge mappings after validating destination resource membership and credential provider compatibility. Push addresses current-to-other mappings; pull addresses other-to-current mappings. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update workspace fork mappings",
+        "description": "Update mappings along a direct fork edge with Admin access to both workspaces. Destination resource membership and credential provider compatibility are validated. Push maps current-to-other; pull maps other-to-current. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.fork.mappings.update",
         "x-oauth-scope": "api:write",
         "tags": ["Workspace Sync"],
@@ -4725,7 +5943,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Other workspace, direction, and mapping entries to update.",
           "content": {
             "application/json": {
               "schema": {
@@ -4736,7 +5954,7 @@
         },
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Number of mapping records changed.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4778,8 +5996,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/rollback": {
       "post": {
         "operationId": "rollbackWorkspaceFork",
-        "summary": "Rollback Workspace Fork",
-        "description": "Restore the latest sync into this workspace using its prior deployed versions. Requires target admin. It does not restore arbitrary drafts or remove every copied resource. Pending activations are reported. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Rollback workspace fork",
+        "description": "Restore the latest sync into this workspace from the named other workspace using prior deployed versions. Requires target workspace Admin access. A newer sync from another fork edge returns `409`. Arbitrary draft edits and copied resources are not restored or removed. Inspect `pendingActivations`; retry rollback if activation remains unfinished. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.fork.rollback",
         "x-oauth-scope": "api:write",
         "tags": ["Workspace Sync"],
@@ -4799,7 +6017,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Other workspace whose latest inbound sync should be undone.",
           "content": {
             "application/json": {
               "schema": {
@@ -4810,7 +6028,7 @@
         },
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Restored, archived, skipped, and still-activating workflow counts.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4852,8 +6070,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/unlink": {
       "post": {
         "operationId": "unlinkWorkspaceFork",
-        "summary": "Unlink Workspace Fork",
-        "description": "Remove the direct fork relationship and its mappings. Requires admin on the acting workspace. Existing workflow and resource content remains available. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Unlink workspace fork",
+        "description": "Remove the direct fork relationship and its mappings with Admin access to the acting workspace. Existing workflows and resources remain available. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.fork.unlink",
         "x-oauth-scope": "api:write",
         "tags": ["Workspace Sync"],
@@ -4873,7 +6091,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Other workspace on the direct fork edge to remove.",
           "content": {
             "application/json": {
               "schema": {
@@ -4884,7 +6102,7 @@
         },
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Confirmation that the relationship was removed.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4926,8 +6144,8 @@
     "/api/v2/workspaces/{workspaceId}/fork/exclusions": {
       "put": {
         "operationId": "updateWorkspaceForkExclusions",
-        "summary": "Update Workspace Fork Exclusions",
-        "description": "Include or exclude selected workflows from fork sync. Excluded workflows are skipped as sources and targets. Missing, archived, and unchanged workflow IDs are skipped. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "summary": "Update workspace fork exclusions",
+        "description": "Include or exclude selected workflows from fork sync with workspace Admin access. Excluded workflows are skipped as sources and targets. Missing, archived, and unchanged workflow IDs are skipped. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.fork.exclusions",
         "x-oauth-scope": "api:write",
         "tags": ["Workspace Sync"],
@@ -4947,7 +6165,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Workflow IDs and whether to exclude them from sync.",
           "content": {
             "application/json": {
               "schema": {
@@ -4958,7 +6176,7 @@
         },
         "responses": {
           "200": {
-            "description": "The workspace operation result.",
+            "description": "Number of workflow exclusion flags changed.",
             "content": {
               "application/json": {
                 "schema": {
@@ -5000,8 +6218,8 @@
     "/api/v2/workflows/import/preview": {
       "post": {
         "operationId": "previewWorkflowImport",
-        "summary": "Preview Workflow Import",
-        "description": "Validate destination mappings and dependent choices without creating a workflow. Returns unresolved fields, discovery instructions, and a fingerprint required by mapped import. No source workspace is queried from imported provenance.\n\nOAuth scope: `api:write`.",
+        "summary": "Preview workflow import",
+        "description": "Validate destination mappings and configuration with workspace write access, without creating a workflow. The result reports readiness, unresolved fields, discovery instructions, and a fingerprint for mapped import with the same choices. Imported provenance never authorizes or queries a source workspace.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workflows.import.preview",
         "x-oauth-scope": "api:write",
         "tags": ["Workspace Sync"],
@@ -5012,13 +6230,26 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/ImportWorkflowRequest"
+              },
+              "examples": {
+                "example1": {
+                  "summary": "Request example 1",
+                  "value": {
+                    "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
+                    "folderPath": "/Operations",
+                    "workflow": {
+                      "blocks": {},
+                      "edges": []
+                    }
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "The operation result.",
+            "description": "Import readiness, unresolved bindings, and destination discovery instructions.",
             "content": {
               "application/json": {
                 "schema": {
@@ -5060,14 +6291,14 @@
     "/api/v2/selectors/list": {
       "post": {
         "operationId": "listSelector",
-        "summary": "List Selector Options",
-        "description": "List workspace-scoped configuration choices using the selector key and dependencies from an import or sync preview. Missing OAuth connections require human authorization before provider choices can be discovered. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "List selector options",
+        "description": "List authorized workspace configuration choices using the selector key and context from an import or sync preview. Requires workspace read access. Missing OAuth connections require human authorization. Keep workspace, selector, context, and search unchanged while paging; a changed provider page returns `409` and requires restarting without a cursor. Provider pages above 8 MiB return `413`; narrow the search. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "selectors.execute",
         "x-oauth-scope": "api:read",
         "tags": ["Workspace Sync"],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Workspace, registered selector key, context, and optional search/cursor.",
           "content": {
             "application/json": {
               "schema": {
@@ -5078,7 +6309,7 @@
         },
         "responses": {
           "200": {
-            "description": "The operation result.",
+            "description": "A page of authorized options, continuation cursor, and truncation status.",
             "content": {
               "application/json": {
                 "schema": {
@@ -5120,14 +6351,14 @@
     "/api/v2/selectors/get": {
       "post": {
         "operationId": "getSelector",
-        "summary": "Get Selector Option",
-        "description": "Resolve a workspace configuration option by its provider identifier and declared dependencies. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+        "summary": "Get selector option",
+        "description": "Get an authorized configuration choice by provider ID and declared context with workspace read access. Returns `data: null` when the option is absent from complete results. Truncated results or pagination limits that prevent verification return `413`; a list-only lookup checks at most 100 pages or 10,000 options. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "selectors.execute",
         "x-oauth-scope": "api:read",
         "tags": ["Workspace Sync"],
         "requestBody": {
           "required": true,
-          "description": "The body for this operation.",
+          "description": "Workspace, registered selector key, context, and provider option ID.",
           "content": {
             "application/json": {
               "schema": {
@@ -5138,7 +6369,7 @@
         },
         "responses": {
           "200": {
-            "description": "The operation result.",
+            "description": "The authorized option, or data:null when absent from complete results.",
             "content": {
               "application/json": {
                 "schema": {
@@ -5180,8 +6411,8 @@
     "/api/v2/workspaces/{workspaceId}/operations/{operationId}": {
       "get": {
         "operationId": "getWorkspaceOperation",
-        "summary": "Get Workspace Operation",
-        "description": "Read a committed operation, copy progress, exact deployment readiness, and structured issues. A failed follow-up does not mean the business transaction was rolled back.\n\nOAuth scope: `api:read`.",
+        "summary": "Get workspace operation",
+        "description": "Read a committed operation and refresh its copy progress, exact admitted deployment readiness, and structured issues with workspace read access. `applied: true` means the transaction committed even if follow-up work failed. This read does not require the fork-specific Admin role or feature gate.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workspaces.operations.read",
         "x-oauth-scope": "api:read",
         "tags": ["Workspace Sync"],
@@ -5213,7 +6444,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The operation result.",
+            "description": "Refreshed commit, copy progress, and exact deployment readiness.",
             "content": {
               "application/json": {
                 "schema": {
@@ -5255,8 +6486,8 @@
     "/api/v2/workspaces/{workspaceId}/operations": {
       "get": {
         "operationId": "listWorkspaceOperations",
-        "summary": "List Workspace Operations",
-        "description": "Page committed operations newest first. Filter by the original request ID to reconcile an uncertain mutation response.\n\nOAuth scope: `api:read`.",
+        "summary": "List workspace operations",
+        "description": "List stored operation receipts newest first with workspace read access. Filter by the original `requestId` to reconcile an uncertain mutation response. Read an individual operation to refresh its copy and deployment readiness. This list does not require the fork-specific Admin role or feature gate.\n\nOAuth scope: `api:read`.",
         "x-sim-operation": "workspaces.operations.read",
         "x-oauth-scope": "api:read",
         "tags": ["Workspace Sync"],
@@ -5301,9 +6532,9 @@
             "name": "requestId",
             "in": "query",
             "required": false,
-            "description": "Stable client request ID for reconciliation and identical retries.",
+            "description": "Find an uncertain mutation by the original client request ID; keep the same filter while paging.",
             "schema": {
-              "description": "Stable client request ID for reconciliation and identical retries.",
+              "description": "Find an uncertain mutation by the original client request ID; keep the same filter while paging.",
               "type": "string",
               "minLength": 1,
               "maxLength": 128
@@ -5312,7 +6543,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The operation result.",
+            "description": "A page of stored operation receipts.",
             "content": {
               "application/json": {
                 "schema": {
@@ -5537,7 +6768,7 @@
             "example": {
               "error": {
                 "code": "CONFLICT",
-                "message": "Webhook path already in use"
+                "message": "The request conflicts with current resource state"
               }
             }
           }
@@ -5676,7 +6907,7 @@
         }
       },
       "ServiceUnavailable": {
-        "description": "A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, because the run may already have started — reconcile against the returned run id instead of retrying.",
+        "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
         "headers": {
           "Retry-After": {
             "$ref": "#/components/headers/Retry-After"
@@ -5856,7 +7087,7 @@
             "type": "integer",
             "minimum": 0,
             "maximum": 9007199254740991,
-            "description": "Settled runs — completed, failed, or cancelled — counted as each one finishes; a paused run is counted once it settles. The counter is never reduced when a run ages out of log retention, so it can exceed the results returned by List Workflow Runs."
+            "description": "Settled runs — completed, failed, or cancelled — counted as each one finishes; a paused run is counted once it settles. The counter is never reduced when a run ages out of log retention, so it can exceed the results returned by List workflow runs."
           },
           "lastRunAt": {
             "anyOf": [
@@ -5918,7 +7149,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -6028,7 +7259,7 @@
             "type": "integer",
             "minimum": 0,
             "maximum": 9007199254740991,
-            "description": "Settled runs — completed, failed, or cancelled — counted as each one finishes; a paused run is counted once it settles. The counter is never reduced when a run ages out of log retention, so it can exceed the results returned by List Workflow Runs."
+            "description": "Settled runs — completed, failed, or cancelled — counted as each one finishes; a paused run is counted once it settles. The counter is never reduced when a run ages out of log retention, so it can exceed the results returned by List workflow runs."
           },
           "lastRunAt": {
             "anyOf": [
@@ -7843,7 +9074,7 @@
               "deferred": [],
               "inputValidationErrors": [],
               "mintedBlockIds": {
-                "triage": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77"
+                "agent-1": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77"
               },
               "lint": {
                 "sources": [],
@@ -7854,7 +9085,7 @@
                 "invalidConnectionTargets": [],
                 "fieldIssues": [
                   {
-                    "blockId": "agent-1",
+                    "blockId": "a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77",
                     "blockName": "Triage",
                     "blockType": "agent",
                     "missingRequiredFields": ["systemPrompt"],
@@ -8586,7 +9817,7 @@
             "type": "integer",
             "minimum": 0,
             "maximum": 9007199254740991,
-            "description": "Variables the workflow now holds."
+            "description": "Number of variables after the batch."
           },
           "changed": {
             "type": "boolean",
@@ -8889,7 +10120,7 @@
         "required": ["name", "type"],
         "additionalProperties": false,
         "title": "Workflow input field",
-        "description": "A deployed API trigger input exposed by a workflow."
+        "description": "An input field from an input-definition trigger in the saved draft."
       },
       "WorkflowDetail": {
         "type": "object",
@@ -8951,7 +10182,7 @@
             "type": "integer",
             "minimum": 0,
             "maximum": 9007199254740991,
-            "description": "Settled runs — completed, failed, or cancelled — counted as each one finishes; a paused run is counted once it settles. The counter is never reduced when a run ages out of log retention, so it can exceed the results returned by List Workflow Runs."
+            "description": "Settled runs — completed, failed, or cancelled — counted as each one finishes; a paused run is counted once it settles. The counter is never reduced when a run ages out of log retention, so it can exceed the results returned by List workflow runs."
           },
           "lastRunAt": {
             "anyOf": [
@@ -8990,7 +10221,7 @@
             "items": {
               "$ref": "#/components/schemas/WorkflowInputField"
             },
-            "description": "Input fields exposed by the workflow API trigger."
+            "description": "Input fields from the saved draft's input-definition trigger; they may differ from the live deployment."
           }
         },
         "required": [
@@ -9011,7 +10242,7 @@
         ],
         "additionalProperties": false,
         "title": "Workflow detail",
-        "description": "Full workflow summary with variables and API-trigger input fields."
+        "description": "Workflow metadata, variables, and saved draft trigger input fields."
       },
       "WorkflowDetailResponse": {
         "type": "object",
@@ -9122,7 +10353,7 @@
           "archived": {
             "type": "boolean",
             "const": true,
-            "description": "Whether the workflow was archived. Restore Workflow recovers it and the schedules, webhooks, MCP tools, and chats archived with it."
+            "description": "Whether the workflow was archived. Restore workflow recovers it and the schedules, webhooks, MCP tools, and chats archived with it."
           }
         },
         "required": ["id", "deleted", "archived"],
@@ -9244,7 +10475,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -9934,7 +11165,7 @@
             "format": "date-time"
           },
           "state": {
-            "description": "Workflow graph saved with this deployment version. Sensitive values are redacted to null.",
+            "description": "Graph pinned by this version, with registered credential fields and opaque table/tool values cleared. Environment references and ordinary workflow variables remain included; inspect other configuration before sharing.",
             "$ref": "#/components/schemas/DeployedWorkflowState"
           }
         },
@@ -10773,7 +12004,7 @@
                 "type": "null"
               }
             ],
-            "description": "Advisory lint findings for the version this deploy publishes, checked as the deploying user. Findings never block a deploy. Null when the lint could not complete within its time budget; the deploy itself is unaffected."
+            "description": "Advisory lint for the admitted version, checked as the deploying member. Findings never block deployment. Null when lint exceeds its time budget or cannot complete; the deployment proceeds."
           }
         },
         "required": [
@@ -10787,7 +12018,7 @@
         ],
         "additionalProperties": false,
         "title": "Deploy result",
-        "description": "Deployment attempt accepted for asynchronous activation. `latestDeploymentAttempt` identifies the attempt. Poll Get Workflow Deployment for `isDeployed` and `deployedAt`, or List Workflow Versions for `isActive`."
+        "description": "Deployment accepted for asynchronous activation. Poll Get workflow deployment and match `latestDeploymentAttempt` to this attempt; an older version can remain live while it activates. List workflow versions reports `isActive`."
       },
       "DeployWorkflowResponse": {
         "type": "object",
@@ -11114,7 +12345,7 @@
           "state": {
             "type": "object",
             "additionalProperties": true,
-            "description": "Secret-sanitized workflow graph, edges, loops, parallels, metadata, and variables."
+            "description": "Saved graph, edges, containers, metadata, and variables. Registered credential fields are cleared; ordinary variables and unresolved environment references remain included."
           },
           "referenceManifest": {
             "description": "Versioned non-secret identifiers and registered source field occurrences for mapped import.",
@@ -11233,7 +12464,7 @@
         "required": ["version", "exportedAt", "workflow", "state"],
         "additionalProperties": false,
         "title": "Workflow export payload",
-        "description": "Portable, secret-sanitized workflow export. Workspace-scoped bindings must be selected again after import."
+        "description": "Portable saved draft with registered credential fields cleared. Workspace bindings are cleared by default and retained when `includeWorkspaceBindings=true`."
       },
       "ExportWorkflowResponse": {
         "type": "object",
@@ -11246,7 +12477,7 @@
         "required": ["data"],
         "additionalProperties": false,
         "title": "Export workflow response",
-        "description": "Portable, secret-sanitized workflow data.",
+        "description": "Portable workflow data with registered credential fields cleared.",
         "examples": [
           {
             "data": {
@@ -11342,7 +12573,7 @@
             "items": {
               "type": "string"
             },
-            "description": "One line per required workspace binding — a table, knowledge base, document, or other selector — that the payload carried empty, as `<block name>: <field> was stripped by export; set it before running`. Export clears those bindings unless `includeWorkspaceBindings=true` was sent, so a round-tripped workflow arrives unable to run until they are set again. Empty when nothing is missing."
+            "description": "Missing required workspace bindings, such as a table or knowledge base, reported as `<block name>: <field> was stripped by export; set it before running`. Set these fields before execution. Default exports clear workspace bindings; `includeWorkspaceBindings=true` retains non-secret bindings for same-workspace imports. Empty when no required binding is missing."
           },
           "operationId": {
             "type": "string",
@@ -11354,12 +12585,12 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
-            "description": "Stable client request ID for reconciliation and identical retries."
+            "description": "Client request ID used to commit this operation. Reuse identical mutation inputs with this ID after an uncertain response."
           },
           "kind": {
             "type": "string",
             "enum": ["workflow_import", "workspace_fork", "workspace_push", "workspace_pull"],
-            "description": "Resource or operation kind."
+            "description": "Type of committed workspace operation."
           },
           "applied": {
             "type": "boolean",
@@ -11375,7 +12606,7 @@
               "requires_configuration",
               "failed"
             ],
-            "description": "Current operation or deployment outcome."
+            "description": "Operation status; failed follow-up work does not undo the committed transaction."
           },
           "resourceIds": {
             "maxItems": 5000,
@@ -11467,16 +12698,16 @@
                   "type": "integer",
                   "minimum": 1,
                   "maximum": 9007199254740991,
-                  "description": "Reference format or deployment version number."
+                  "description": "Deployment version number for this admitted attempt."
                 },
                 "status": {
                   "type": "string",
                   "enum": ["preparing", "activating", "active", "failed", "superseded"],
-                  "description": "Current operation or deployment outcome."
+                  "description": "Status of this exact admitted deployment attempt."
                 },
                 "ready": {
                   "type": "boolean",
-                  "description": "Whether the operation passes its current apply or deployment readiness checks."
+                  "description": "Whether this exact deployment attempt is active and all required components are ready."
                 },
                 "pendingComponents": {
                   "maxItems": 32,
@@ -11533,7 +12764,7 @@
               "status": {
                 "type": "string",
                 "enum": ["pending", "completed", "failed"],
-                "description": "Current operation or deployment outcome."
+                "description": "Background resource-copy status."
               },
               "copied": {
                 "type": "integer",
@@ -11650,7 +12881,7 @@
             "maxLength": 2000
           },
           "mappings": {
-            "description": "Mappings keyed by resource type and source identifier.",
+            "description": "Mapping entries addressed by resource kind and source identifier.",
             "maxItems": 5000,
             "type": "array",
             "items": {
@@ -11792,7 +13023,7 @@
             }
           },
           "dependentValues": {
-            "description": "Destination-dependent choices keyed by source workflow, block, and field identities.",
+            "description": "Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated.",
             "maxItems": 2000,
             "type": "array",
             "items": {
@@ -11821,14 +13052,14 @@
             }
           },
           "requestId": {
-            "description": "Stable client request ID for reconciliation and identical retries.",
+            "description": "Stable client request ID for mapped import. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can create another workflow.",
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
             "pattern": "^[A-Za-z0-9._:-]+$"
           },
           "previewFingerprint": {
-            "description": "Fingerprint of the reviewed preview and its choices.",
+            "description": "Fingerprint returned by an import preview with the same choices. A changed plan returns 409; preview again. Do not invent this value.",
             "type": "string",
             "pattern": "^[a-f0-9]{64}$"
           }
@@ -11836,7 +13067,7 @@
         "required": ["workspaceId", "workflow"],
         "additionalProperties": false,
         "title": "Import workflow input",
-        "description": "Workflow document, destination, and optional reviewed mappings."
+        "description": "Workflow document, destination, and optional reviewed mappings. This example creates an empty draft."
       },
       "ChatDeploymentListItem": {
         "type": "object",
@@ -11965,7 +13196,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -12224,12 +13455,12 @@
             "maxLength": 64
           },
           "welcomeMessage": {
-            "description": "First message shown to a visitor.",
+            "description": "First message shown to a visitor. On replace, omission uses the platform default; an empty string keeps the existing message.",
             "type": "string",
             "maxLength": 2000
           },
           "imageUrl": {
-            "description": "Avatar image shown beside assistant messages.",
+            "description": "Avatar image shown beside assistant messages. On replace, omission or an empty string keeps the existing avatar.",
             "type": "string",
             "maxLength": 2048
           }
@@ -12284,7 +13515,7 @@
             "maxLength": 2000
           },
           "customizations": {
-            "description": "Presentation overrides. Omitted fields take platform defaults.",
+            "description": "Presentation overrides. Omitted `primaryColor` and `welcomeMessage` use platform defaults; an omitted or empty `imageUrl` keeps the existing avatar. An empty `welcomeMessage` keeps the existing message.",
             "$ref": "#/components/schemas/ChatDeploymentCustomizations"
           },
           "authType": {
@@ -12635,7 +13866,7 @@
                           "sourceRunId": {
                             "type": "string",
                             "minLength": 1,
-                            "description": "Run ID supplying upstream block results when starting from a selected block."
+                            "description": "Run in this workflow whose persisted execution state supplies upstream block results. Missing or expired state returns 404."
                           }
                         },
                         "required": ["type", "blockId", "sourceRunId"],
@@ -12656,7 +13887,7 @@
           },
           "async": {
             "default": false,
-            "description": "Queue the run and return a 202 receipt when true. Requires an OAuth access token or API key, cannot be combined with `stream`, and rejects all streaming and output-shaping options (`selectedOutputs`, `includeThinking`, `includeToolCalls`, `includeFileBase64`, `base64MaxBytes`).",
+            "description": "Queue the run and return a 202 receipt. Requires an API key or OAuth access token and a deployed run source. Cannot stream, select outputs, enable thinking/tool events, or include file-inlining options (`includeFileBase64` or `base64MaxBytes`).",
             "type": "boolean"
           },
           "executionTimeoutSeconds": {
@@ -12775,7 +14006,7 @@
               "failed",
               "cancelled"
             ],
-            "description": "Current or terminal run status. `redacting` is transient, reported while a finished run's output is being scrubbed. `paused` means the run is waiting to be resumed — either held at a human-in-the-loop pause point, or left paused by a resume attempt that did not complete. Only the single-run response distinguishes the two, through `paused.automaticResumeWaitingReason`."
+            "description": "Current or terminal run status. `redacting` is transient, reported while a finished run's output is being scrubbed. `paused` means the run is waiting at a human or time pause, or a resume attempt did not complete. The single-run response provides the pause kind, resume time, and any automatic-resume waiting reason."
           },
           "trigger": {
             "type": "string",
@@ -12826,7 +14057,7 @@
                 "type": "null"
               }
             ],
-            "description": "Credit cost, or null when unavailable."
+            "description": "Credits consumed, or null when unavailable or hidden by organization permission groups."
           }
         },
         "required": [
@@ -12862,7 +14093,7 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
@@ -12958,7 +14189,7 @@
               "cancelled",
               "queued"
             ],
-            "description": "Current or terminal run status. `redacting` is transient, reported while a finished run's output is being scrubbed. `paused` means the run is waiting to be resumed — either held at a human-in-the-loop pause point, or left paused by a resume attempt that did not complete. Only the single-run response distinguishes the two, through `paused.automaticResumeWaitingReason`."
+            "description": "Current or terminal run status. `redacting` is transient, reported while a finished run's output is being scrubbed. `paused` means the run is waiting at a human or time pause, or a resume attempt did not complete. The single-run response provides the pause kind, resume time, and any automatic-resume waiting reason."
           },
           "trigger": {
             "anyOf": [
@@ -13073,7 +14304,7 @@
                         "type": "null"
                       }
                     ],
-                    "description": "Why automatic resume is waiting, or null when it is not — on a paused run, null means it is waiting on human input. Recorded whenever a resume attempt fails and cleared once one succeeds. A non-retryable or exhausted failure is prefixed `Automatic resume requires manual intervention: `."
+                    "description": "Recorded automatic-resume failure, or null when no failure is recorded. Inspect `pauseKind` and `resumeAt` to distinguish a scheduled time pause from human input. Cleared after a successful resume. A non-retryable or exhausted failure starts with `Automatic resume requires manual intervention: `."
                   },
                   "pausePointCount": {
                     "type": "number",
@@ -13119,7 +14350,7 @@
                 "type": "null"
               }
             ],
-            "description": "Credit cost, or null when unavailable."
+            "description": "Credits consumed, or null when unavailable or hidden by organization permission groups."
           },
           "error": {
             "anyOf": [
@@ -13141,7 +14372,7 @@
                 "type": "null"
               }
             ],
-            "description": "Final workflow output when requested, otherwise null."
+            "description": "Final output when `includeOutput=true`, or null when not requested or hidden by organization permission groups."
           },
           "blockOutputs": {
             "anyOf": [
@@ -13158,7 +14389,7 @@
                 "type": "null"
               }
             ],
-            "description": "Outputs of the blocks named by `selectedOutputs`, or null when none were requested. Gated by `selectedOutputs` alone — `includeOutput` governs `output` only."
+            "description": "Selected block outputs, or null when none were requested or execution data is hidden by organization permission groups. `selectedOutputs` controls these independently of `includeOutput`."
           },
           "files": {
             "anyOf": [
@@ -13172,7 +14403,7 @@
                 "type": "null"
               }
             ],
-            "description": "Files this run produced, or null when `includeOutput` is false. Matches the nullability of `output`."
+            "description": "Run-produced files when `includeOutput=true`, or null when not requested or execution data is hidden by organization permission groups."
           }
         },
         "required": [
@@ -13488,7 +14719,7 @@
                 "type": "null"
               }
             ],
-            "description": "Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change."
+            "description": "Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits."
           }
         },
         "required": ["data", "nextCursor"],
@@ -13680,7 +14911,7 @@
           "previewFingerprint": {
             "type": "string",
             "pattern": "^[a-f0-9]{64}$",
-            "description": "Fingerprint of the reviewed preview and its choices."
+            "description": "Fingerprint to submit when applying this preview with the same choices. Preview again after changing a choice."
           },
           "sourceWorkspaceId": {
             "type": "string",
@@ -13730,8 +14961,8 @@
           "draftOnly"
         ],
         "additionalProperties": false,
-        "title": "WorkspaceForkPreview",
-        "description": "The WorkspaceForkPreview result."
+        "title": "Workspace fork preview",
+        "description": "Read-only fork plan and fingerprint."
       },
       "PreviewWorkspaceForkResponse": {
         "type": "object",
@@ -13743,8 +14974,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "PreviewWorkspaceFork response",
-        "description": "The response for this operation."
+        "title": "Preview workspace fork response",
+        "description": "Deployed source workflows, selected-copy count, and a preview fingerprint."
       },
       "PreviewWorkspaceForkBody": {
         "type": "object",
@@ -13827,8 +15058,8 @@
           }
         },
         "additionalProperties": false,
-        "title": "PreviewWorkspaceFork body",
-        "description": "The body for this operation."
+        "title": "Preview workspace fork request",
+        "description": "Optional child name and explicitly selected resource copies."
       },
       "WorkspaceOperationReport": {
         "type": "object",
@@ -13843,7 +15074,7 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
-            "description": "Stable client request ID for reconciliation and identical retries."
+            "description": "Client request ID used to commit this operation. Reuse identical mutation inputs with this ID after an uncertain response."
           },
           "workspaceId": {
             "type": "string",
@@ -13854,7 +15085,7 @@
           "kind": {
             "type": "string",
             "enum": ["workflow_import", "workspace_fork", "workspace_push", "workspace_pull"],
-            "description": "Resource or operation kind."
+            "description": "Type of committed workspace operation."
           },
           "applied": {
             "type": "boolean",
@@ -13870,7 +15101,7 @@
               "requires_configuration",
               "failed"
             ],
-            "description": "Current operation or deployment outcome."
+            "description": "Operation status; failed follow-up work does not undo the committed transaction."
           },
           "resourceIds": {
             "maxItems": 5000,
@@ -13962,16 +15193,16 @@
                   "type": "integer",
                   "minimum": 1,
                   "maximum": 9007199254740991,
-                  "description": "Reference format or deployment version number."
+                  "description": "Deployment version number for this admitted attempt."
                 },
                 "status": {
                   "type": "string",
                   "enum": ["preparing", "activating", "active", "failed", "superseded"],
-                  "description": "Current operation or deployment outcome."
+                  "description": "Status of this exact admitted deployment attempt."
                 },
                 "ready": {
                   "type": "boolean",
-                  "description": "Whether the operation passes its current apply or deployment readiness checks."
+                  "description": "Whether this exact deployment attempt is active and all required components are ready."
                 },
                 "pendingComponents": {
                   "maxItems": 32,
@@ -14028,7 +15259,7 @@
               "status": {
                 "type": "string",
                 "enum": ["pending", "completed", "failed"],
-                "description": "Current operation or deployment outcome."
+                "description": "Background resource-copy status."
               },
               "copied": {
                 "type": "integer",
@@ -14058,8 +15289,8 @@
           "issues"
         ],
         "additionalProperties": false,
-        "title": "WorkspaceOperationReport",
-        "description": "The WorkspaceOperationReport result."
+        "title": "Workspace operation receipt",
+        "description": "Committed operation receipt, resource copies, and exact deployment readiness."
       },
       "ForkWorkspaceResponse": {
         "type": "object",
@@ -14071,8 +15302,22 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "ForkWorkspace response",
-        "description": "The response for this operation."
+        "title": "Fork workspace response",
+        "description": "Committed fork receipt and resource-copy progress.",
+        "examples": [
+          {
+            "data": {
+              "operationId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
+              "requestId": "fork-support-2026-10-13",
+              "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+              "kind": "workspace_fork",
+              "applied": true,
+              "status": "processing",
+              "resourceIds": ["destination_workflow_id"],
+              "issues": []
+            }
+          }
+        ]
       },
       "ForkWorkspaceBody": {
         "type": "object",
@@ -14157,18 +15402,25 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
-            "description": "Stable client request ID for reconciliation and identical retries."
+            "description": "Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation."
           },
           "previewFingerprint": {
             "type": "string",
             "pattern": "^[a-f0-9]{64}$",
-            "description": "Fingerprint of the reviewed preview and its choices."
+            "description": "Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value."
           }
         },
         "required": ["requestId", "previewFingerprint"],
         "additionalProperties": false,
-        "title": "ForkWorkspace body",
-        "description": "The body for this operation."
+        "title": "Fork workspace request",
+        "description": "Child name and copy choices, with the actual preview fingerprint and a stable request ID.",
+        "examples": [
+          {
+            "name": "Support sandbox",
+            "requestId": "fork-support-2026-10-13",
+            "previewFingerprint": "c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a"
+          }
+        ]
       },
       "WorkspaceSyncPreview": {
         "type": "object",
@@ -14176,7 +15428,7 @@
           "previewFingerprint": {
             "type": "string",
             "pattern": "^[a-f0-9]{64}$",
-            "description": "Fingerprint of the reviewed preview and its choices."
+            "description": "Fingerprint to submit when applying this preview with the same choices. Preview again after changing a choice."
           },
           "sourceWorkspaceId": {
             "type": "string",
@@ -14192,7 +15444,7 @@
           },
           "ready": {
             "type": "boolean",
-            "description": "Whether the operation passes its current apply or deployment readiness checks."
+            "description": "Whether required bindings, configuration, and sync blockers are resolved. This does not mean the target is already deployed."
           },
           "workflows": {
             "maxItems": 2000,
@@ -14589,8 +15841,8 @@
           "triggerUrlChanges"
         ],
         "additionalProperties": false,
-        "title": "WorkspaceSyncPreview",
-        "description": "The WorkspaceSyncPreview result."
+        "title": "Workspace sync preview",
+        "description": "Read-only sync actions, bindings, configuration, and trigger-path choices."
       },
       "PreviewWorkspacePushResponse": {
         "type": "object",
@@ -14602,8 +15854,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "PreviewWorkspacePush response",
-        "description": "The response for this operation."
+        "title": "Preview workspace push response",
+        "description": "Current-to-other workflow actions, required choices, and preview fingerprint."
       },
       "PreviewWorkspacePushBody": {
         "type": "object",
@@ -14615,7 +15867,7 @@
             "description": "Workspace on the other side of the direct fork edge."
           },
           "mappings": {
-            "description": "Mappings keyed by resource type and source identifier.",
+            "description": "Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync.",
             "maxItems": 5000,
             "type": "array",
             "items": {
@@ -14664,7 +15916,7 @@
             }
           },
           "dependentValues": {
-            "description": "Destination-dependent choices keyed by source workflow, block, and field identities.",
+            "description": "Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them.",
             "maxItems": 2000,
             "type": "array",
             "items": {
@@ -14833,8 +16085,8 @@
         },
         "required": ["otherWorkspaceId"],
         "additionalProperties": false,
-        "title": "PreviewWorkspacePush body",
-        "description": "The body for this operation."
+        "title": "Preview workspace push request",
+        "description": "Other workspace and proposed source-to-target sync choices."
       },
       "PushWorkspaceResponse": {
         "type": "object",
@@ -14846,8 +16098,22 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "PushWorkspace response",
-        "description": "The response for this operation."
+        "title": "Push workspace response",
+        "description": "Committed push receipt with copy and deployment readiness.",
+        "examples": [
+          {
+            "data": {
+              "operationId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
+              "requestId": "push-support-2026-10-13",
+              "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+              "kind": "workspace_push",
+              "applied": true,
+              "status": "processing",
+              "resourceIds": ["destination_workflow_id"],
+              "issues": []
+            }
+          }
+        ]
       },
       "PushWorkspaceBody": {
         "type": "object",
@@ -14859,7 +16125,7 @@
             "description": "Workspace on the other side of the direct fork edge."
           },
           "mappings": {
-            "description": "Mappings keyed by resource type and source identifier.",
+            "description": "Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync.",
             "maxItems": 5000,
             "type": "array",
             "items": {
@@ -14908,7 +16174,7 @@
             }
           },
           "dependentValues": {
-            "description": "Destination-dependent choices keyed by source workflow, block, and field identities.",
+            "description": "Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them.",
             "maxItems": 2000,
             "type": "array",
             "items": {
@@ -15078,23 +16344,31 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
-            "description": "Stable client request ID for reconciliation and identical retries."
+            "description": "Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation."
           },
           "previewFingerprint": {
             "type": "string",
             "pattern": "^[a-f0-9]{64}$",
-            "description": "Fingerprint of the reviewed preview and its choices."
+            "description": "Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value."
           },
           "confirm": {
             "type": "boolean",
             "const": true,
-            "description": "Explicit acknowledgement that sync replaces target workflows."
+            "description": "Confirm replacement of mapped target drafts and archival of mapped targets whose sources were deleted or archived."
           }
         },
         "required": ["otherWorkspaceId", "requestId", "previewFingerprint", "confirm"],
         "additionalProperties": false,
-        "title": "PushWorkspace body",
-        "description": "The body for this operation."
+        "title": "Push workspace request",
+        "description": "Confirmed current-to-other choices, actual preview fingerprint, and stable request ID.",
+        "examples": [
+          {
+            "otherWorkspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+            "requestId": "push-support-2026-10-13",
+            "previewFingerprint": "c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a",
+            "confirm": true
+          }
+        ]
       },
       "PreviewWorkspacePullResponse": {
         "type": "object",
@@ -15106,8 +16380,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "PreviewWorkspacePull response",
-        "description": "The response for this operation."
+        "title": "Preview workspace pull response",
+        "description": "Other-to-current workflow actions, required choices, and preview fingerprint."
       },
       "PreviewWorkspacePullBody": {
         "type": "object",
@@ -15119,7 +16393,7 @@
             "description": "Workspace on the other side of the direct fork edge."
           },
           "mappings": {
-            "description": "Mappings keyed by resource type and source identifier.",
+            "description": "Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync.",
             "maxItems": 5000,
             "type": "array",
             "items": {
@@ -15168,7 +16442,7 @@
             }
           },
           "dependentValues": {
-            "description": "Destination-dependent choices keyed by source workflow, block, and field identities.",
+            "description": "Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them.",
             "maxItems": 2000,
             "type": "array",
             "items": {
@@ -15337,8 +16611,8 @@
         },
         "required": ["otherWorkspaceId"],
         "additionalProperties": false,
-        "title": "PreviewWorkspacePull body",
-        "description": "The body for this operation."
+        "title": "Preview workspace pull request",
+        "description": "Other workspace and proposed source-to-target sync choices."
       },
       "PullWorkspaceResponse": {
         "type": "object",
@@ -15350,8 +16624,22 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "PullWorkspace response",
-        "description": "The response for this operation."
+        "title": "Pull workspace response",
+        "description": "Committed pull receipt with copy and deployment readiness.",
+        "examples": [
+          {
+            "data": {
+              "operationId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
+              "requestId": "pull-support-2026-10-13",
+              "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+              "kind": "workspace_pull",
+              "applied": true,
+              "status": "processing",
+              "resourceIds": ["destination_workflow_id"],
+              "issues": []
+            }
+          }
+        ]
       },
       "PullWorkspaceBody": {
         "type": "object",
@@ -15363,7 +16651,7 @@
             "description": "Workspace on the other side of the direct fork edge."
           },
           "mappings": {
-            "description": "Mappings keyed by resource type and source identifier.",
+            "description": "Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync.",
             "maxItems": 5000,
             "type": "array",
             "items": {
@@ -15412,7 +16700,7 @@
             }
           },
           "dependentValues": {
-            "description": "Destination-dependent choices keyed by source workflow, block, and field identities.",
+            "description": "Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them.",
             "maxItems": 2000,
             "type": "array",
             "items": {
@@ -15582,23 +16870,31 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128,
-            "description": "Stable client request ID for reconciliation and identical retries."
+            "description": "Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation."
           },
           "previewFingerprint": {
             "type": "string",
             "pattern": "^[a-f0-9]{64}$",
-            "description": "Fingerprint of the reviewed preview and its choices."
+            "description": "Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value."
           },
           "confirm": {
             "type": "boolean",
             "const": true,
-            "description": "Explicit acknowledgement that sync replaces target workflows."
+            "description": "Confirm replacement of mapped target drafts and archival of mapped targets whose sources were deleted or archived."
           }
         },
         "required": ["otherWorkspaceId", "requestId", "previewFingerprint", "confirm"],
         "additionalProperties": false,
-        "title": "PullWorkspace body",
-        "description": "The body for this operation."
+        "title": "Pull workspace request",
+        "description": "Confirmed other-to-current choices, actual preview fingerprint, and stable request ID.",
+        "examples": [
+          {
+            "otherWorkspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
+            "requestId": "pull-support-2026-10-13",
+            "previewFingerprint": "c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a",
+            "confirm": true
+          }
+        ]
       },
       "GetWorkspaceForkAvailabilityResult": {
         "type": "object",
@@ -15610,8 +16906,8 @@
         },
         "required": ["available"],
         "additionalProperties": false,
-        "title": "GetWorkspaceForkAvailabilityResult",
-        "description": "The GetWorkspaceForkAvailabilityResult result."
+        "title": "Get workspace fork availability result",
+        "description": "Fork feature availability for this workspace."
       },
       "GetWorkspaceForkAvailabilityResponse": {
         "type": "object",
@@ -15623,8 +16919,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "GetWorkspaceForkAvailability response",
-        "description": "The response for this operation."
+        "title": "Get workspace fork availability response",
+        "description": "Whether forking is enabled for this deployment and workspace plan."
       },
       "GetWorkspaceForkLineageResult": {
         "type": "object",
@@ -15699,8 +16995,8 @@
         },
         "required": ["current", "parent"],
         "additionalProperties": false,
-        "title": "GetWorkspaceForkLineageResult",
-        "description": "The GetWorkspaceForkLineageResult result."
+        "title": "Get workspace fork lineage result",
+        "description": "Current workspace and its active parent."
       },
       "GetWorkspaceForkLineageResponse": {
         "type": "object",
@@ -15712,8 +17008,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "GetWorkspaceForkLineage response",
-        "description": "The response for this operation."
+        "title": "Get workspace fork lineage response",
+        "description": "Current workspace and its active direct parent, when present."
       },
       "ListWorkspaceForkChildrenResult": {
         "type": "object",
@@ -15749,8 +17045,8 @@
         },
         "required": ["id", "name", "organizationId", "createdAt"],
         "additionalProperties": false,
-        "title": "ListWorkspaceForkChildrenResult",
-        "description": "The ListWorkspaceForkChildrenResult result."
+        "title": "List workspace fork children result",
+        "description": "An active direct child workspace."
       },
       "ListWorkspaceForkChildrenResponse": {
         "type": "object",
@@ -15771,13 +17067,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "ListWorkspaceForkChildren response",
-        "description": "The response for this operation."
+        "title": "List workspace fork children response",
+        "description": "A page of active direct child workspaces."
       },
       "ListWorkspaceForkResourcesResult": {
         "type": "object",
@@ -15817,8 +17113,8 @@
         },
         "required": ["id", "label"],
         "additionalProperties": false,
-        "title": "ListWorkspaceForkResourcesResult",
-        "description": "The ListWorkspaceForkResourcesResult result."
+        "title": "List workspace fork resources result",
+        "description": "A copyable resource candidate."
       },
       "ListWorkspaceForkResourcesResponse": {
         "type": "object",
@@ -15839,13 +17135,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "ListWorkspaceForkResources response",
-        "description": "The response for this operation."
+        "title": "List workspace fork resources response",
+        "description": "A page of copyable resource candidates."
       },
       "GetWorkspaceForkMappingsResult": {
         "type": "object",
@@ -15895,8 +17191,8 @@
         },
         "required": ["resourceType", "sourceId", "targetId", "id"],
         "additionalProperties": false,
-        "title": "GetWorkspaceForkMappingsResult",
-        "description": "The GetWorkspaceForkMappingsResult result."
+        "title": "Get workspace fork mappings result",
+        "description": "A saved directional mapping entry."
       },
       "GetWorkspaceForkMappingsResponse": {
         "type": "object",
@@ -15917,13 +17213,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "GetWorkspaceForkMappings response",
-        "description": "The response for this operation."
+        "title": "Get workspace fork mappings response",
+        "description": "A page of persisted source-to-target mapping entries."
       },
       "UpdateWorkspaceForkMappingsResult": {
         "type": "object",
@@ -15937,8 +17233,8 @@
         },
         "required": ["updated"],
         "additionalProperties": false,
-        "title": "UpdateWorkspaceForkMappingsResult",
-        "description": "The UpdateWorkspaceForkMappingsResult result."
+        "title": "Update workspace fork mappings result",
+        "description": "Count of changed mapping records."
       },
       "UpdateWorkspaceForkMappingsResponse": {
         "type": "object",
@@ -15950,8 +17246,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "UpdateWorkspaceForkMappings response",
-        "description": "The response for this operation."
+        "title": "Update workspace fork mappings response",
+        "description": "Number of mapping records changed."
       },
       "UpdateWorkspaceForkMappingsBody": {
         "type": "object",
@@ -16014,13 +17310,13 @@
               "required": ["resourceType", "sourceId", "targetId"],
               "additionalProperties": false
             },
-            "description": "Mappings keyed by resource type and source identifier."
+            "description": "Mapping entries addressed by resource type and `sourceId`. `targetId: null` clears a mapping."
           }
         },
         "required": ["otherWorkspaceId", "direction", "mappings"],
         "additionalProperties": false,
-        "title": "UpdateWorkspaceForkMappings body",
-        "description": "The body for this operation."
+        "title": "Update workspace fork mappings request",
+        "description": "Other workspace, direction, and mapping entries to update."
       },
       "RollbackWorkspaceForkResult": {
         "type": "object",
@@ -16061,8 +17357,8 @@
         },
         "required": ["restored", "archived", "unarchived", "skipped", "pendingActivations"],
         "additionalProperties": false,
-        "title": "RollbackWorkspaceForkResult",
-        "description": "The RollbackWorkspaceForkResult result."
+        "title": "Rollback workspace fork result",
+        "description": "Workflow restoration and pending-activation counts."
       },
       "RollbackWorkspaceForkResponse": {
         "type": "object",
@@ -16074,8 +17370,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "RollbackWorkspaceFork response",
-        "description": "The response for this operation."
+        "title": "Rollback workspace fork response",
+        "description": "Restored, archived, skipped, and still-activating workflow counts."
       },
       "RollbackWorkspaceForkBody": {
         "type": "object",
@@ -16089,8 +17385,8 @@
         },
         "required": ["otherWorkspaceId"],
         "additionalProperties": false,
-        "title": "RollbackWorkspaceFork body",
-        "description": "The body for this operation."
+        "title": "Rollback workspace fork request",
+        "description": "Other workspace whose latest inbound sync should be undone."
       },
       "UnlinkWorkspaceForkResult": {
         "type": "object",
@@ -16102,8 +17398,8 @@
         },
         "required": ["unlinked"],
         "additionalProperties": false,
-        "title": "UnlinkWorkspaceForkResult",
-        "description": "The UnlinkWorkspaceForkResult result."
+        "title": "Unlink workspace fork result",
+        "description": "Fork-edge removal acknowledgment."
       },
       "UnlinkWorkspaceForkResponse": {
         "type": "object",
@@ -16115,8 +17411,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "UnlinkWorkspaceFork response",
-        "description": "The response for this operation."
+        "title": "Unlink workspace fork response",
+        "description": "Confirmation that the relationship was removed."
       },
       "UnlinkWorkspaceForkBody": {
         "type": "object",
@@ -16130,8 +17426,8 @@
         },
         "required": ["otherWorkspaceId"],
         "additionalProperties": false,
-        "title": "UnlinkWorkspaceFork body",
-        "description": "The body for this operation."
+        "title": "Unlink workspace fork request",
+        "description": "Other workspace on the direct fork edge to remove."
       },
       "UpdateWorkspaceForkExclusionsResult": {
         "type": "object",
@@ -16145,8 +17441,8 @@
         },
         "required": ["updated"],
         "additionalProperties": false,
-        "title": "UpdateWorkspaceForkExclusionsResult",
-        "description": "The UpdateWorkspaceForkExclusionsResult result."
+        "title": "Update workspace fork exclusions result",
+        "description": "Count of changed workflow exclusion flags."
       },
       "UpdateWorkspaceForkExclusionsResponse": {
         "type": "object",
@@ -16158,8 +17454,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "UpdateWorkspaceForkExclusions response",
-        "description": "The response for this operation."
+        "title": "Update workspace fork exclusions response",
+        "description": "Number of workflow exclusion flags changed."
       },
       "UpdateWorkspaceForkExclusionsBody": {
         "type": "object",
@@ -16181,8 +17477,8 @@
         },
         "required": ["workflowIds", "forkSyncExcluded"],
         "additionalProperties": false,
-        "title": "UpdateWorkspaceForkExclusions body",
-        "description": "The body for this operation."
+        "title": "Update workspace fork exclusions request",
+        "description": "Workflow IDs and whether to exclude them from sync."
       },
       "PreviewWorkflowImportResult": {
         "type": "object",
@@ -16191,11 +17487,11 @@
             "type": "string",
             "minLength": 64,
             "maxLength": 64,
-            "description": "Fingerprint of the reviewed preview and its choices."
+            "description": "Fingerprint to send when applying this import with the same choices. Preview again after changing any choice."
           },
           "ready": {
             "type": "boolean",
-            "description": "Whether the operation passes its current apply or deployment readiness checks."
+            "description": "Whether every required destination binding and configuration field is resolved for import."
           },
           "bindings": {
             "maxItems": 10000,
@@ -16586,8 +17882,8 @@
           "discovery"
         ],
         "additionalProperties": false,
-        "title": "PreviewWorkflowImportResult",
-        "description": "The PreviewWorkflowImportResult result."
+        "title": "Workflow import preview",
+        "description": "Import readiness, unresolved bindings, and destination discovery instructions."
       },
       "PreviewWorkflowImportResponse": {
         "type": "object",
@@ -16599,8 +17895,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "PreviewWorkflowImport response",
-        "description": "The response for this operation."
+        "title": "Preview workflow import response",
+        "description": "Import readiness, unresolved bindings, and destination discovery instructions."
       },
       "ImportWorkflowRequest": {
         "type": "object",
@@ -16642,7 +17938,7 @@
             "maxLength": 2000
           },
           "mappings": {
-            "description": "Mappings keyed by resource type and source identifier.",
+            "description": "Mapping entries addressed by resource kind and source identifier.",
             "maxItems": 5000,
             "type": "array",
             "items": {
@@ -16784,7 +18080,7 @@
             }
           },
           "dependentValues": {
-            "description": "Destination-dependent choices keyed by source workflow, block, and field identities.",
+            "description": "Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated.",
             "maxItems": 2000,
             "type": "array",
             "items": {
@@ -16874,7 +18170,7 @@
             "items": {
               "$ref": "#/components/schemas/SelectorOption"
             },
-            "description": "Requested options or operation result."
+            "description": "Authorized provider options in this page."
           },
           "nextCursor": {
             "anyOf": [
@@ -16890,13 +18186,13 @@
           },
           "truncated": {
             "type": "boolean",
-            "description": "Whether the provider returned only a bounded subset of its options."
+            "description": "Whether provider limits left the result incomplete. A null `nextCursor` with `truncated: true` does not establish that all options were searched."
           }
         },
         "required": ["data", "nextCursor", "truncated"],
         "additionalProperties": false,
-        "title": "ListSelector response",
-        "description": "The response for this operation."
+        "title": "List selector response",
+        "description": "A page of authorized options, continuation cursor, and truncation status."
       },
       "ListSelectorBody": {
         "type": "object",
@@ -17021,7 +18317,7 @@
               "providers.ollamaEmbeddingModels",
               "providers.openrouterEmbeddingModels"
             ],
-            "description": "Registered selector key for discovering this field’s destination options."
+            "description": "Registered selector key from an import or sync preview, such as `gmail.labels`."
           },
           "context": {
             "default": {},
@@ -17044,14 +18340,14 @@
             "maxLength": 1024
           },
           "cursor": {
-            "description": "Opaque continuation cursor returned by the preceding page.",
+            "description": "Cursor returned by the preceding page. Keep `workspaceId`, `selectorKey`, `context`, and `search` unchanged; only `limit` may change. Restart without a cursor after a changed-page 409.",
             "type": "string",
             "minLength": 1,
             "maxLength": 32768
           },
           "limit": {
             "default": 50,
-            "description": "Maximum number of items to return on one page.",
+            "description": "Maximum options per page, from 1 to 100. Defaults to 50.",
             "type": "integer",
             "minimum": 1,
             "maximum": 100
@@ -17059,8 +18355,8 @@
         },
         "required": ["workspaceId", "selectorKey"],
         "additionalProperties": false,
-        "title": "ListSelector body",
-        "description": "The body for this operation."
+        "title": "List selector request",
+        "description": "Workspace, registered selector key, context, and optional search/cursor."
       },
       "GetSelectorResponse": {
         "type": "object",
@@ -17079,8 +18375,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "GetSelector response",
-        "description": "The response for this operation."
+        "title": "Get selector response",
+        "description": "The authorized option, or data:null when absent from complete results."
       },
       "GetSelectorBody": {
         "type": "object",
@@ -17205,7 +18501,7 @@
               "providers.ollamaEmbeddingModels",
               "providers.openrouterEmbeddingModels"
             ],
-            "description": "Registered selector key for discovering this field’s destination options."
+            "description": "Registered selector key from an import or sync preview, such as `gmail.labels`."
           },
           "context": {
             "default": {},
@@ -17225,13 +18521,13 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 16384,
-            "description": "Resource identifier."
+            "description": "Provider option ID to resolve with the same selector and declared context."
           }
         },
         "required": ["workspaceId", "selectorKey", "id"],
         "additionalProperties": false,
-        "title": "GetSelector body",
-        "description": "The body for this operation."
+        "title": "Get selector request",
+        "description": "Workspace, registered selector key, context, and provider option ID."
       },
       "GetWorkspaceOperationResponse": {
         "type": "object",
@@ -17243,8 +18539,8 @@
         },
         "required": ["data"],
         "additionalProperties": false,
-        "title": "GetWorkspaceOperation response",
-        "description": "The response for this operation."
+        "title": "Get workspace operation response",
+        "description": "Refreshed commit, copy progress, and exact deployment readiness."
       },
       "ListWorkspaceOperationsResponse": {
         "type": "object",
@@ -17265,13 +18561,13 @@
                 "type": "null"
               }
             ],
-            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself."
+            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
           }
         },
         "required": ["data", "nextCursor"],
         "additionalProperties": false,
-        "title": "ListWorkspaceOperations response",
-        "description": "The response for this operation."
+        "title": "List workspace operations response",
+        "description": "A page of stored operation receipts."
       }
     }
   },
diff --git a/apps/docs/public/static/api-deployment/api-info.png b/apps/docs/public/static/api-deployment/api-info.png
deleted file mode 100644
index 9a88b089aee..00000000000
Binary files a/apps/docs/public/static/api-deployment/api-info.png and /dev/null differ
diff --git a/apps/docs/public/static/api-deployment/api-select-outputs.png b/apps/docs/public/static/api-deployment/api-select-outputs.png
deleted file mode 100644
index 24267bcd8f1..00000000000
Binary files a/apps/docs/public/static/api-deployment/api-select-outputs.png and /dev/null differ
diff --git a/apps/docs/public/static/api-deployment/api-tab.png b/apps/docs/public/static/api-deployment/api-tab.png
deleted file mode 100644
index bf6f3bb2316..00000000000
Binary files a/apps/docs/public/static/api-deployment/api-tab.png and /dev/null differ
diff --git a/apps/docs/public/static/api-deployment/api-versions-menu.png b/apps/docs/public/static/api-deployment/api-versions-menu.png
deleted file mode 100644
index ff148326326..00000000000
Binary files a/apps/docs/public/static/api-deployment/api-versions-menu.png and /dev/null differ
diff --git a/apps/docs/public/static/api-deployment/api-versions.png b/apps/docs/public/static/api-deployment/api-versions.png
deleted file mode 100644
index 595091daf37..00000000000
Binary files a/apps/docs/public/static/api-deployment/api-versions.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/credential-loop.png b/apps/docs/public/static/blocks/credential-loop.png
deleted file mode 100644
index 1da2f8f5088..00000000000
Binary files a/apps/docs/public/static/blocks/credential-loop.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/guardrails-2.png b/apps/docs/public/static/blocks/guardrails-2.png
deleted file mode 100644
index 7e42592c4ee..00000000000
Binary files a/apps/docs/public/static/blocks/guardrails-2.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/hitl-2.png b/apps/docs/public/static/blocks/hitl-2.png
deleted file mode 100644
index 2aca11e6d30..00000000000
Binary files a/apps/docs/public/static/blocks/hitl-2.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/loop-1.png b/apps/docs/public/static/blocks/loop-1.png
deleted file mode 100644
index 9da828ff7f1..00000000000
Binary files a/apps/docs/public/static/blocks/loop-1.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/loop-2.png b/apps/docs/public/static/blocks/loop-2.png
deleted file mode 100644
index de0f4f06a24..00000000000
Binary files a/apps/docs/public/static/blocks/loop-2.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/loop-3.png b/apps/docs/public/static/blocks/loop-3.png
deleted file mode 100644
index 104fc269edd..00000000000
Binary files a/apps/docs/public/static/blocks/loop-3.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/loop-4.png b/apps/docs/public/static/blocks/loop-4.png
deleted file mode 100644
index dccd6c76dae..00000000000
Binary files a/apps/docs/public/static/blocks/loop-4.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/mcp-add-modal.png b/apps/docs/public/static/blocks/mcp-add-modal.png
deleted file mode 100644
index f80bc53f9bf..00000000000
Binary files a/apps/docs/public/static/blocks/mcp-add-modal.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/mcp-agent-dropdown.png b/apps/docs/public/static/blocks/mcp-agent-dropdown.png
deleted file mode 100644
index 06c78b1fa24..00000000000
Binary files a/apps/docs/public/static/blocks/mcp-agent-dropdown.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/mcp-agent-tools.png b/apps/docs/public/static/blocks/mcp-agent-tools.png
deleted file mode 100644
index 31242e894ce..00000000000
Binary files a/apps/docs/public/static/blocks/mcp-agent-tools.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/mcp-client-config.png b/apps/docs/public/static/blocks/mcp-client-config.png
deleted file mode 100644
index 40887f50051..00000000000
Binary files a/apps/docs/public/static/blocks/mcp-client-config.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/mcp-deploy-modal.png b/apps/docs/public/static/blocks/mcp-deploy-modal.png
deleted file mode 100644
index efb51451ace..00000000000
Binary files a/apps/docs/public/static/blocks/mcp-deploy-modal.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/mcp-server-add-modal.png b/apps/docs/public/static/blocks/mcp-server-add-modal.png
deleted file mode 100644
index 55b59a227f7..00000000000
Binary files a/apps/docs/public/static/blocks/mcp-server-add-modal.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/mcp-server-details.png b/apps/docs/public/static/blocks/mcp-server-details.png
deleted file mode 100644
index b454438d897..00000000000
Binary files a/apps/docs/public/static/blocks/mcp-server-details.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/mcp-servers-settings.png b/apps/docs/public/static/blocks/mcp-servers-settings.png
deleted file mode 100644
index b75ad706447..00000000000
Binary files a/apps/docs/public/static/blocks/mcp-servers-settings.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/mcp-settings.png b/apps/docs/public/static/blocks/mcp-settings.png
deleted file mode 100644
index a3b2bc06d02..00000000000
Binary files a/apps/docs/public/static/blocks/mcp-settings.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/mcp-tool-block.png b/apps/docs/public/static/blocks/mcp-tool-block.png
deleted file mode 100644
index ead01d5912e..00000000000
Binary files a/apps/docs/public/static/blocks/mcp-tool-block.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/parallel-1.png b/apps/docs/public/static/blocks/parallel-1.png
deleted file mode 100644
index 31b388fda61..00000000000
Binary files a/apps/docs/public/static/blocks/parallel-1.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/parallel-2.png b/apps/docs/public/static/blocks/parallel-2.png
deleted file mode 100644
index 8a2cdde9eb4..00000000000
Binary files a/apps/docs/public/static/blocks/parallel-2.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/schedule-3.png b/apps/docs/public/static/blocks/schedule-3.png
deleted file mode 100644
index aafe28fac5f..00000000000
Binary files a/apps/docs/public/static/blocks/schedule-3.png and /dev/null differ
diff --git a/apps/docs/public/static/blocks/workflow-2.png b/apps/docs/public/static/blocks/workflow-2.png
deleted file mode 100644
index 5fa5062b420..00000000000
Binary files a/apps/docs/public/static/blocks/workflow-2.png and /dev/null differ
diff --git a/apps/docs/public/static/chat/chat-deploy-config.png b/apps/docs/public/static/chat/chat-deploy-config.png
deleted file mode 100644
index 98b19a1d576..00000000000
Binary files a/apps/docs/public/static/chat/chat-deploy-config.png and /dev/null differ
diff --git a/apps/docs/public/static/chat/chat-deploy-output.png b/apps/docs/public/static/chat/chat-deploy-output.png
deleted file mode 100644
index 31d59fe8f01..00000000000
Binary files a/apps/docs/public/static/chat/chat-deploy-output.png and /dev/null differ
diff --git a/apps/docs/public/static/chat/chat-live.png b/apps/docs/public/static/chat/chat-live.png
deleted file mode 100644
index 2d33ecef4e1..00000000000
Binary files a/apps/docs/public/static/chat/chat-live.png and /dev/null differ
diff --git a/apps/docs/public/static/connectors/connectors-excluded.png b/apps/docs/public/static/connectors/connectors-excluded.png
deleted file mode 100644
index 51605d86f1b..00000000000
Binary files a/apps/docs/public/static/connectors/connectors-excluded.png and /dev/null differ
diff --git a/apps/docs/public/static/connectors/connectors-list.png b/apps/docs/public/static/connectors/connectors-list.png
deleted file mode 100644
index 638a0c70a9d..00000000000
Binary files a/apps/docs/public/static/connectors/connectors-list.png and /dev/null differ
diff --git a/apps/docs/public/static/connectors/connectors-sources.png b/apps/docs/public/static/connectors/connectors-sources.png
deleted file mode 100644
index 3aa4181a846..00000000000
Binary files a/apps/docs/public/static/connectors/connectors-sources.png and /dev/null differ
diff --git a/apps/docs/public/static/connectors/connectors-sync-history.png b/apps/docs/public/static/connectors/connectors-sync-history.png
deleted file mode 100644
index 2daa122ea4c..00000000000
Binary files a/apps/docs/public/static/connectors/connectors-sync-history.png and /dev/null differ
diff --git a/apps/docs/public/static/credentials/secret-dropdown.png b/apps/docs/public/static/credentials/secret-dropdown.png
deleted file mode 100644
index 0f37155beb6..00000000000
Binary files a/apps/docs/public/static/credentials/secret-dropdown.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/access-control-blocks.png b/apps/docs/public/static/enterprise/access-control-blocks.png
deleted file mode 100644
index 709be54f7ef..00000000000
Binary files a/apps/docs/public/static/enterprise/access-control-blocks.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/access-control-groups.png b/apps/docs/public/static/enterprise/access-control-groups.png
deleted file mode 100644
index 7e1a264b422..00000000000
Binary files a/apps/docs/public/static/enterprise/access-control-groups.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/access-control-model-providers.png b/apps/docs/public/static/enterprise/access-control-model-providers.png
deleted file mode 100644
index 57797021716..00000000000
Binary files a/apps/docs/public/static/enterprise/access-control-model-providers.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/access-control-platform.png b/apps/docs/public/static/enterprise/access-control-platform.png
deleted file mode 100644
index 2eb5cf5304f..00000000000
Binary files a/apps/docs/public/static/enterprise/access-control-platform.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/audit-logs.png b/apps/docs/public/static/enterprise/audit-logs.png
deleted file mode 100644
index 5838898f6f9..00000000000
Binary files a/apps/docs/public/static/enterprise/audit-logs.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/custom-blocks-canvas.png b/apps/docs/public/static/enterprise/custom-blocks-canvas.png
deleted file mode 100644
index e952b15bb1b..00000000000
Binary files a/apps/docs/public/static/enterprise/custom-blocks-canvas.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/custom-blocks-form.png b/apps/docs/public/static/enterprise/custom-blocks-form.png
deleted file mode 100644
index ed68e0e9ce5..00000000000
Binary files a/apps/docs/public/static/enterprise/custom-blocks-form.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/custom-blocks-list.png b/apps/docs/public/static/enterprise/custom-blocks-list.png
deleted file mode 100644
index 18671499275..00000000000
Binary files a/apps/docs/public/static/enterprise/custom-blocks-list.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/data-drains-list.png b/apps/docs/public/static/enterprise/data-drains-list.png
deleted file mode 100644
index b18af7cade5..00000000000
Binary files a/apps/docs/public/static/enterprise/data-drains-list.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/data-drains-new.png b/apps/docs/public/static/enterprise/data-drains-new.png
deleted file mode 100644
index 4d85d0fc682..00000000000
Binary files a/apps/docs/public/static/enterprise/data-drains-new.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/data-retention.png b/apps/docs/public/static/enterprise/data-retention.png
deleted file mode 100644
index 92e3a510b44..00000000000
Binary files a/apps/docs/public/static/enterprise/data-retention.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/forks-activity.png b/apps/docs/public/static/enterprise/forks-activity.png
deleted file mode 100644
index dd9398b34a2..00000000000
Binary files a/apps/docs/public/static/enterprise/forks-activity.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/forks-copy-resources.png b/apps/docs/public/static/enterprise/forks-copy-resources.png
deleted file mode 100644
index 616b8204a1f..00000000000
Binary files a/apps/docs/public/static/enterprise/forks-copy-resources.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/forks-create-modal.png b/apps/docs/public/static/enterprise/forks-create-modal.png
deleted file mode 100644
index ff20e2c78e7..00000000000
Binary files a/apps/docs/public/static/enterprise/forks-create-modal.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/forks-list.png b/apps/docs/public/static/enterprise/forks-list.png
deleted file mode 100644
index 5d31ccef839..00000000000
Binary files a/apps/docs/public/static/enterprise/forks-list.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/forks-sync-confirm.png b/apps/docs/public/static/enterprise/forks-sync-confirm.png
deleted file mode 100644
index 74d5ea07dd2..00000000000
Binary files a/apps/docs/public/static/enterprise/forks-sync-confirm.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/forks-sync-overview.png b/apps/docs/public/static/enterprise/forks-sync-overview.png
deleted file mode 100644
index 3ae743c1571..00000000000
Binary files a/apps/docs/public/static/enterprise/forks-sync-overview.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/scim-provisioning.png b/apps/docs/public/static/enterprise/scim-provisioning.png
deleted file mode 100644
index 57e8a4d23b1..00000000000
Binary files a/apps/docs/public/static/enterprise/scim-provisioning.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/sso-form.png b/apps/docs/public/static/enterprise/sso-form.png
deleted file mode 100644
index 162d93d2ccc..00000000000
Binary files a/apps/docs/public/static/enterprise/sso-form.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/usage-tracking-workspace-detail.png b/apps/docs/public/static/enterprise/usage-tracking-workspace-detail.png
deleted file mode 100644
index 70003a33efb..00000000000
Binary files a/apps/docs/public/static/enterprise/usage-tracking-workspace-detail.png and /dev/null differ
diff --git a/apps/docs/public/static/enterprise/whitelabeling.png b/apps/docs/public/static/enterprise/whitelabeling.png
deleted file mode 100644
index f643dd2f989..00000000000
Binary files a/apps/docs/public/static/enterprise/whitelabeling.png and /dev/null differ
diff --git a/apps/docs/public/static/getting-started/started-1.png b/apps/docs/public/static/getting-started/started-1.png
deleted file mode 100644
index bdf273863e8..00000000000
Binary files a/apps/docs/public/static/getting-started/started-1.png and /dev/null differ
diff --git a/apps/docs/public/static/introduction.png b/apps/docs/public/static/introduction.png
deleted file mode 100644
index 8465abf568b..00000000000
Binary files a/apps/docs/public/static/introduction.png and /dev/null differ
diff --git a/apps/docs/public/static/logs/console.png b/apps/docs/public/static/logs/console.png
deleted file mode 100644
index bea125e5724..00000000000
Binary files a/apps/docs/public/static/logs/console.png and /dev/null differ
diff --git a/apps/docs/public/static/logs/logs-cost.png b/apps/docs/public/static/logs/logs-cost.png
deleted file mode 100644
index a6111156fe2..00000000000
Binary files a/apps/docs/public/static/logs/logs-cost.png and /dev/null differ
diff --git a/apps/docs/public/static/logs/logs-frozen-canvas.png b/apps/docs/public/static/logs/logs-frozen-canvas.png
deleted file mode 100644
index 03c03076e79..00000000000
Binary files a/apps/docs/public/static/logs/logs-frozen-canvas.png and /dev/null differ
diff --git a/apps/docs/public/static/logs/logs-sidebar.png b/apps/docs/public/static/logs/logs-sidebar.png
deleted file mode 100644
index 0f98a5d4069..00000000000
Binary files a/apps/docs/public/static/logs/logs-sidebar.png and /dev/null differ
diff --git a/apps/docs/public/static/logs/run-inspector.png b/apps/docs/public/static/logs/run-inspector.png
deleted file mode 100644
index b243bafee2c..00000000000
Binary files a/apps/docs/public/static/logs/run-inspector.png and /dev/null differ
diff --git a/apps/docs/public/static/logs/workspace-logs.png b/apps/docs/public/static/logs/workspace-logs.png
deleted file mode 100644
index 25c96cae066..00000000000
Binary files a/apps/docs/public/static/logs/workspace-logs.png and /dev/null differ
diff --git a/apps/docs/public/static/mothership/chart-example.png b/apps/docs/public/static/mothership/chart-example.png
deleted file mode 100644
index aa7c006d58f..00000000000
Binary files a/apps/docs/public/static/mothership/chart-example.png and /dev/null differ
diff --git a/apps/docs/public/static/mothership/image-example.png b/apps/docs/public/static/mothership/image-example.png
deleted file mode 100644
index 839e8dc9e5e..00000000000
Binary files a/apps/docs/public/static/mothership/image-example.png and /dev/null differ
diff --git a/apps/docs/public/static/mothership/pptx-example.png b/apps/docs/public/static/mothership/pptx-example.png
deleted file mode 100644
index b09528155b3..00000000000
Binary files a/apps/docs/public/static/mothership/pptx-example.png and /dev/null differ
diff --git a/apps/docs/public/static/mothership/table-example.png b/apps/docs/public/static/mothership/table-example.png
deleted file mode 100644
index 2a12834b441..00000000000
Binary files a/apps/docs/public/static/mothership/table-example.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/add-env-variable.png b/apps/docs/public/static/quick-reference/add-env-variable.png
deleted file mode 100644
index 0b84197cfa8..00000000000
Binary files a/apps/docs/public/static/quick-reference/add-env-variable.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/clear-chat.png b/apps/docs/public/static/quick-reference/clear-chat.png
deleted file mode 100644
index 2e2e2dd0804..00000000000
Binary files a/apps/docs/public/static/quick-reference/clear-chat.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/clear-terminal.png b/apps/docs/public/static/quick-reference/clear-terminal.png
deleted file mode 100644
index 62a533aa938..00000000000
Binary files a/apps/docs/public/static/quick-reference/clear-terminal.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/copy-api.png b/apps/docs/public/static/quick-reference/copy-api.png
deleted file mode 100644
index ad044671250..00000000000
Binary files a/apps/docs/public/static/quick-reference/copy-api.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/copy-log.png b/apps/docs/public/static/quick-reference/copy-log.png
deleted file mode 100644
index 71a2ac0f0e9..00000000000
Binary files a/apps/docs/public/static/quick-reference/copy-log.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/create-workflow.png b/apps/docs/public/static/quick-reference/create-workflow.png
deleted file mode 100644
index 958e5b54ba7..00000000000
Binary files a/apps/docs/public/static/quick-reference/create-workflow.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/delete-block.png b/apps/docs/public/static/quick-reference/delete-block.png
deleted file mode 100644
index 3b0d74ee63f..00000000000
Binary files a/apps/docs/public/static/quick-reference/delete-block.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/deploy.png b/apps/docs/public/static/quick-reference/deploy.png
deleted file mode 100644
index caede0c00b3..00000000000
Binary files a/apps/docs/public/static/quick-reference/deploy.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/disable-block.png b/apps/docs/public/static/quick-reference/disable-block.png
deleted file mode 100644
index 87e8d8b6c8f..00000000000
Binary files a/apps/docs/public/static/quick-reference/disable-block.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/env-variable-reference.png b/apps/docs/public/static/quick-reference/env-variable-reference.png
deleted file mode 100644
index 837844de1e6..00000000000
Binary files a/apps/docs/public/static/quick-reference/env-variable-reference.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/filter-block.png b/apps/docs/public/static/quick-reference/filter-block.png
deleted file mode 100644
index 9dd8195bce1..00000000000
Binary files a/apps/docs/public/static/quick-reference/filter-block.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/folder-context-menu.png b/apps/docs/public/static/quick-reference/folder-context-menu.png
deleted file mode 100644
index 61be5fe2adf..00000000000
Binary files a/apps/docs/public/static/quick-reference/folder-context-menu.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/import-workflow.png b/apps/docs/public/static/quick-reference/import-workflow.png
deleted file mode 100644
index cca2c95d789..00000000000
Binary files a/apps/docs/public/static/quick-reference/import-workflow.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/lock-block.png b/apps/docs/public/static/quick-reference/lock-block.png
deleted file mode 100644
index 82ea992a4d9..00000000000
Binary files a/apps/docs/public/static/quick-reference/lock-block.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/output-select.png b/apps/docs/public/static/quick-reference/output-select.png
deleted file mode 100644
index 919e3731afc..00000000000
Binary files a/apps/docs/public/static/quick-reference/output-select.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/promote-deployment.png b/apps/docs/public/static/quick-reference/promote-deployment.png
deleted file mode 100644
index b2205d084c6..00000000000
Binary files a/apps/docs/public/static/quick-reference/promote-deployment.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/run-from-block.png b/apps/docs/public/static/quick-reference/run-from-block.png
deleted file mode 100644
index 95bc745372c..00000000000
Binary files a/apps/docs/public/static/quick-reference/run-from-block.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/run-until-block.png b/apps/docs/public/static/quick-reference/run-until-block.png
deleted file mode 100644
index 81e8a47fa15..00000000000
Binary files a/apps/docs/public/static/quick-reference/run-until-block.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/run-workflow.png b/apps/docs/public/static/quick-reference/run-workflow.png
deleted file mode 100644
index cb62983b3ce..00000000000
Binary files a/apps/docs/public/static/quick-reference/run-workflow.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/search-everything.png b/apps/docs/public/static/quick-reference/search-everything.png
deleted file mode 100644
index cb83b9cc117..00000000000
Binary files a/apps/docs/public/static/quick-reference/search-everything.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/stop-workflow.png b/apps/docs/public/static/quick-reference/stop-workflow.png
deleted file mode 100644
index af09e6f997b..00000000000
Binary files a/apps/docs/public/static/quick-reference/stop-workflow.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/terminal-search.png b/apps/docs/public/static/quick-reference/terminal-search.png
deleted file mode 100644
index de7187563cb..00000000000
Binary files a/apps/docs/public/static/quick-reference/terminal-search.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/terminal.png b/apps/docs/public/static/quick-reference/terminal.png
deleted file mode 100644
index bea125e5724..00000000000
Binary files a/apps/docs/public/static/quick-reference/terminal.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/test-chat.png b/apps/docs/public/static/quick-reference/test-chat.png
deleted file mode 100644
index 46c28011a9e..00000000000
Binary files a/apps/docs/public/static/quick-reference/test-chat.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/toggle-manual-mode.png b/apps/docs/public/static/quick-reference/toggle-manual-mode.png
deleted file mode 100644
index 25bfaca6679..00000000000
Binary files a/apps/docs/public/static/quick-reference/toggle-manual-mode.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/update-deployment.png b/apps/docs/public/static/quick-reference/update-deployment.png
deleted file mode 100644
index 0b91c44a645..00000000000
Binary files a/apps/docs/public/static/quick-reference/update-deployment.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/variable-reference.png b/apps/docs/public/static/quick-reference/variable-reference.png
deleted file mode 100644
index 820018e49e4..00000000000
Binary files a/apps/docs/public/static/quick-reference/variable-reference.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/variables.png b/apps/docs/public/static/quick-reference/variables.png
deleted file mode 100644
index 2280366da61..00000000000
Binary files a/apps/docs/public/static/quick-reference/variables.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/view-deployment.png b/apps/docs/public/static/quick-reference/view-deployment.png
deleted file mode 100644
index 25633787b26..00000000000
Binary files a/apps/docs/public/static/quick-reference/view-deployment.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/workflow-context-menu.png b/apps/docs/public/static/quick-reference/workflow-context-menu.png
deleted file mode 100644
index 87893226dda..00000000000
Binary files a/apps/docs/public/static/quick-reference/workflow-context-menu.png and /dev/null differ
diff --git a/apps/docs/public/static/quick-reference/workspace-context-menu.png b/apps/docs/public/static/quick-reference/workspace-context-menu.png
deleted file mode 100644
index 853f532e614..00000000000
Binary files a/apps/docs/public/static/quick-reference/workspace-context-menu.png and /dev/null differ
diff --git a/apps/docs/public/static/search/github-app-email-permission.jpg b/apps/docs/public/static/search/github-app-email-permission.jpg
deleted file mode 100644
index a7086ca4739..00000000000
Binary files a/apps/docs/public/static/search/github-app-email-permission.jpg and /dev/null differ
diff --git a/apps/docs/public/static/search/github-app-repository-permissions.jpg b/apps/docs/public/static/search/github-app-repository-permissions.jpg
deleted file mode 100644
index 0e95461689e..00000000000
Binary files a/apps/docs/public/static/search/github-app-repository-permissions.jpg and /dev/null differ
diff --git a/apps/docs/public/static/secrets/secret-details.png b/apps/docs/public/static/secrets/secret-details.png
deleted file mode 100644
index a71ba5d15df..00000000000
Binary files a/apps/docs/public/static/secrets/secret-details.png and /dev/null differ
diff --git a/apps/docs/public/static/start.png b/apps/docs/public/static/start.png
deleted file mode 100644
index 5b43e721567..00000000000
Binary files a/apps/docs/public/static/start.png and /dev/null differ
diff --git a/apps/docs/public/static/tables/workflow-columns/cell-menu.png b/apps/docs/public/static/tables/workflow-columns/cell-menu.png
deleted file mode 100644
index 780d84cc0e4..00000000000
Binary files a/apps/docs/public/static/tables/workflow-columns/cell-menu.png and /dev/null differ
diff --git a/apps/docs/public/static/tables/workflow-columns/column-mapping.png b/apps/docs/public/static/tables/workflow-columns/column-mapping.png
deleted file mode 100644
index 93871f78ab6..00000000000
Binary files a/apps/docs/public/static/tables/workflow-columns/column-mapping.png and /dev/null differ
diff --git a/apps/docs/public/static/tables/workflow-columns/configure-workflow.png b/apps/docs/public/static/tables/workflow-columns/configure-workflow.png
deleted file mode 100644
index c5862fa5881..00000000000
Binary files a/apps/docs/public/static/tables/workflow-columns/configure-workflow.png and /dev/null differ
diff --git a/apps/docs/public/static/tables/workflow-columns/new-column-menu.png b/apps/docs/public/static/tables/workflow-columns/new-column-menu.png
deleted file mode 100644
index 74df46419ae..00000000000
Binary files a/apps/docs/public/static/tables/workflow-columns/new-column-menu.png and /dev/null differ
diff --git a/apps/docs/public/static/tables/workflow-columns/row-trace.png b/apps/docs/public/static/tables/workflow-columns/row-trace.png
deleted file mode 100644
index f44ce82622e..00000000000
Binary files a/apps/docs/public/static/tables/workflow-columns/row-trace.png and /dev/null differ
diff --git a/apps/docs/public/static/tables/workflow-columns/table-groups.png b/apps/docs/public/static/tables/workflow-columns/table-groups.png
deleted file mode 100644
index 6ac00a0e72d..00000000000
Binary files a/apps/docs/public/static/tables/workflow-columns/table-groups.png and /dev/null differ
diff --git a/apps/docs/public/static/tags/tags-create.png b/apps/docs/public/static/tags/tags-create.png
deleted file mode 100644
index 8504eee9e26..00000000000
Binary files a/apps/docs/public/static/tags/tags-create.png and /dev/null differ
diff --git a/apps/docs/public/static/tags/tags-document-list.png b/apps/docs/public/static/tags/tags-document-list.png
deleted file mode 100644
index 11f5281263a..00000000000
Binary files a/apps/docs/public/static/tags/tags-document-list.png and /dev/null differ
diff --git a/apps/docs/public/static/tags/tags-knowledge-block.png b/apps/docs/public/static/tags/tags-knowledge-block.png
deleted file mode 100644
index b5ed5bef238..00000000000
Binary files a/apps/docs/public/static/tags/tags-knowledge-block.png and /dev/null differ
diff --git a/apps/sim/app/o/[organizationId]/settings/components/integrations/search-source-setup.test.tsx b/apps/sim/app/o/[organizationId]/settings/components/integrations/search-source-setup.test.tsx
index dcd81173c9c..251045dc38d 100644
--- a/apps/sim/app/o/[organizationId]/settings/components/integrations/search-source-setup.test.tsx
+++ b/apps/sim/app/o/[organizationId]/settings/components/integrations/search-source-setup.test.tsx
@@ -280,7 +280,7 @@ async function openSyncFrequency() {
 }
 
 function menuItem(label: string): HTMLElement {
-  const match = Array.from(document.querySelectorAll<HTMLElement>('[role="menuitem"]')).find(
+  const match = Array.from(document.querySelectorAll<HTMLElement>('[role="menuitemradio"]')).find(
     (node) => node.textContent?.trim() === label
   )
   expect(match, `Menu item ${label}`).toBeDefined()
diff --git a/apps/sim/app/o/[organizationId]/settings/components/search-mcp-connection.test.tsx b/apps/sim/app/o/[organizationId]/settings/components/search-mcp-connection.test.tsx
index 517b93ac1de..0a0a7237fc4 100644
--- a/apps/sim/app/o/[organizationId]/settings/components/search-mcp-connection.test.tsx
+++ b/apps/sim/app/o/[organizationId]/settings/components/search-mcp-connection.test.tsx
@@ -37,7 +37,7 @@ describe('Search MCP client connection', () => {
     await act(async () => {
       trigger.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
     })
-    const item = Array.from(document.querySelectorAll<HTMLElement>('[role="menuitem"]')).find(
+    const item = Array.from(document.querySelectorAll<HTMLElement>('[role="menuitemradio"]')).find(
       (element) => element.textContent?.trim() === label
     )
     expect(item, `Expected the ${label} client`).toBeDefined()
diff --git a/apps/sim/components/settings/unsaved-changes-regression.test.tsx b/apps/sim/components/settings/unsaved-changes-regression.test.tsx
index 1bcc7bb29ac..072f3d6c759 100644
--- a/apps/sim/components/settings/unsaved-changes-regression.test.tsx
+++ b/apps/sim/components/settings/unsaved-changes-regression.test.tsx
@@ -786,7 +786,7 @@ function select(label: string, optionText: string) {
   const trigger = container.querySelector<HTMLButtonElement>(`button[aria-label="${label}"]`)
   if (!trigger) throw new Error(`Missing select ${label}`)
   act(() => trigger.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true })))
-  const option = [...document.querySelectorAll<HTMLElement>('[role="menuitem"]')].find(
+  const option = [...document.querySelectorAll<HTMLElement>('[role="menuitemradio"]')].find(
     (node) => node.textContent?.trim() === optionText
   )
   if (!option) throw new Error(`Missing option ${optionText}`)
diff --git a/apps/sim/ee/credential-groups/components/organization-workspace-grant-modal.test.tsx b/apps/sim/ee/credential-groups/components/organization-workspace-grant-modal.test.tsx
index d944ba82b74..d4fdb37de07 100644
--- a/apps/sim/ee/credential-groups/components/organization-workspace-grant-modal.test.tsx
+++ b/apps/sim/ee/credential-groups/components/organization-workspace-grant-modal.test.tsx
@@ -83,7 +83,7 @@ describe('workspace integration grant editor', () => {
     await act(async () =>
       trigger.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true, button: 0 }))
     )
-    const option = [...document.querySelectorAll<HTMLElement>('[role="menuitem"]')].find(
+    const option = [...document.querySelectorAll<HTMLElement>('[role="menuitemradio"]')].find(
       (element) => element.textContent === 'Finance'
     )
     expect(option).toBeDefined()
diff --git a/apps/sim/lib/api/contracts/v2/audit-logs.ts b/apps/sim/lib/api/contracts/v2/audit-logs.ts
index b2b41ff5477..de5ded5af94 100644
--- a/apps/sim/lib/api/contracts/v2/audit-logs.ts
+++ b/apps/sim/lib/api/contracts/v2/audit-logs.ts
@@ -102,8 +102,16 @@ export const v2ListAuditLogsQuerySchema = v1ListAuditLogsQuerySchema
      * instead of a driver-level 500. `GET /logs` and `GET /workflows/{workflowId}/runs`
      * already share it, and an audit trail is read alongside them.
      */
-    startDate: v2RunWindowBoundSchema('startDate').optional(),
-    endDate: v2RunWindowBoundSchema('endDate').optional(),
+    startDate: v2RunWindowBoundSchema('startDate')
+      .optional()
+      .describe(
+        'Include audit entries created at or after this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected.'
+      ),
+    endDate: v2RunWindowBoundSchema('endDate')
+      .optional()
+      .describe(
+        'Include audit entries created at or before this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected.'
+      ),
     /**
      * Declared with the shared boolean flag rather than reused from the v1
      * shape: v1 spells it as a `'true'`/`'false'` string enum, and every other
diff --git a/apps/sim/lib/api/contracts/v2/billing.ts b/apps/sim/lib/api/contracts/v2/billing.ts
index 6cdca3c89c3..d95924c4cdf 100644
--- a/apps/sim/lib/api/contracts/v2/billing.ts
+++ b/apps/sim/lib/api/contracts/v2/billing.ts
@@ -42,7 +42,7 @@ export const v2BillingStatusQuerySchema = z
     workspaceId: workspaceIdSchema
       .optional()
       .describe(
-        'Workspace whose payer should be resolved. A workspace API key is pinned to its own workspace: any other id answers `404 Workspace not found`, which is also what an id that does not exist answers.'
+        'Workspace whose payer to report. A workspace API key is bound to its own workspace; a different or unknown ID returns `404 Workspace not found`. Omit for account billing when using a personal API key or OAuth token.'
       ),
   })
   .strict()
@@ -85,7 +85,7 @@ export const v2BillingStatusDataSchema = z
           .meta({ format: 'date-time' }),
       })
       .describe(
-        'Current billing period. Only a Stripe subscription defines a real period; without one — notably on the free plan — this is the open interval 1970-01-01 to 9999-12-31 and must not be read as a monthly window.'
+        'Current subscription billing period. Without a Stripe subscription, including on Free, the bounds are 1970-01-01 to 9999-12-31; they do not represent a monthly window.'
       ),
     plan: z.string().describe('Current billing plan.'),
     status: z
@@ -96,7 +96,7 @@ export const v2BillingStatusDataSchema = z
         used: z
           .number()
           .describe(
-            'Credits consumed so far. The counter is reset by Stripe invoice webhooks, so on a paid plan it covers the current billing period; on the free plan nothing resets it and the value is lifetime consumption.'
+            'Credits consumed during the current billing period on a paid plan, or over the account’s lifetime on Free.'
           ),
         limit: z
           .number()
@@ -107,7 +107,7 @@ export const v2BillingStatusDataSchema = z
       })
       .nullable()
       .describe(
-        "The payer's credit usage and allowance — periodic on a paid plan, lifetime on the free plan, where the counter never resets. Null when the caller cannot manage that payer's billing. Always null for a workspace API key."
+        'The payer’s credit usage and allowance: per billing period on paid plans, lifetime on Free. Null when the caller cannot manage the payer’s billing, including every workspace API key.'
       ),
     storage: z
       .object({
@@ -154,10 +154,10 @@ export const v2GetBillingStatusContract = defineRouteContract({
  * question about a value the caller was just told is not acceptable.
  */
 const billingWindowStartSchema = v2RunWindowBoundSchema('startDate').describe(
-  'Only include usage events recorded at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. Requires `period=custom`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.'
+  'Include events at or after this UTC ISO 8601 timestamp, for example `2026-08-06T00:00:00Z`. Required with `period=custom`. Date-only values, UTC offsets instead of `Z`, and year `0000` are rejected.'
 )
 const billingWindowEndSchema = v2RunWindowBoundSchema('endDate').describe(
-  'Only include usage events recorded at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. Requires `period=custom`, and defaults to now when omitted. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.'
+  'Include events at or before this UTC ISO 8601 timestamp, for example `2026-08-06T00:00:00Z`. Allowed only with `period=custom`; omission defaults to now. Date-only values, UTC offsets instead of `Z`, and year `0000` are rejected.'
 )
 
 export const v2BillingLogsQuerySchema = z
@@ -256,7 +256,9 @@ export const v2BillingLogEntrySchema = z
       .string()
       .describe('ISO 8601 timestamp when the usage event was recorded.')
       .meta({ format: 'date-time' }),
-    source: usageLogSourceSchema.describe('Product surface that consumed the credits.'),
+    source: usageLogSourceSchema.describe(
+      'Product surface that consumed credits. The legacy `mothership_block` value identifies the Agent block; `sim-chat` identifies Sim Chat.'
+    ),
     workspaceId: z
       .string()
       .nullable()
diff --git a/apps/sim/lib/api/contracts/v2/catalog.ts b/apps/sim/lib/api/contracts/v2/catalog.ts
index f84ccda8c38..dd905cd2008 100644
--- a/apps/sim/lib/api/contracts/v2/catalog.ts
+++ b/apps/sim/lib/api/contracts/v2/catalog.ts
@@ -318,7 +318,9 @@ const v2ToolParamSchema = z
     visibility: z
       .string()
       .optional()
-      .describe('Who may supply the value: `user-or-llm`, `user-only`, `llm-only`, or `hidden`.'),
+      .describe(
+        'Source of the value in a workflow or Agent block: `user-or-llm`, `user-only`, `llm-only`, or `hidden`. A direct Run tool caller may supply non-hidden parameters; Sim supplies hidden ones.'
+      ),
     description: z.string().optional().describe('What the parameter means.'),
     default: z.unknown().optional().describe('Value used when the parameter is omitted.'),
     // untyped-response: tool param JSON Schema is provider-defined and arbitrarily nested
@@ -392,7 +394,7 @@ export type V2ToolOutput = z.output<typeof v2ToolOutputSchema>
 const v2HostedApiKeySchema = z
   .enum(['always', 'conditional', 'none'])
   .describe(
-    'Whether Sim supplies the API key on THIS deployment: `always`, `conditional` (only for some parameter combinations), or `none` (bring your own). Self-hosted deployments supply no hosted keys, so every tool reports `none` there regardless of what it declares.'
+    'API-key hosting on this deployment: `always`, `conditional` for some parameter combinations, or `none` when Sim does not supply a key. Supply your own key only if the tool requires one. Self-hosted deployments report `none` for every tool.'
   )
 
 const v2ToolOAuthSchema = z.object({
@@ -450,12 +452,12 @@ export const v2ExecuteToolBodySchema = z
       )
       .default({})
       .describe(
-        'Tool arguments keyed by published parameter IDs. For `user-only` parameters, a whole-value `{{VAR_NAME}}` reference resolves a workspace environment variable. Other values pass through unchanged.'
+        'Arguments keyed by published parameter IDs. Hidden and undeclared fields are rejected. Send connected credentials as top-level `credentialId`, not `input.credential`, `input.credentialId`, or `input.oauthCredential`. Whole-value `{{VAR_NAME}}` references resolve environment variables only for `user-only` parameters; other values pass through unchanged.'
       ),
     credentialId: catalogIdSchema
       .optional()
       .describe(
-        'Credential to authenticate with. Required when the tool declares an OAuth requirement; the workspace credentials list names the candidates.'
+        'Connected credential to authenticate with. Required for tools declaring required OAuth or a required credential-selector parameter. Use List credentials to find candidates; do not send credential aliases inside `input`.'
       ),
     timeoutSeconds: z
       .number()
@@ -466,7 +468,9 @@ export const v2ExecuteToolBodySchema = z
         `timeoutSeconds cannot exceed ${V2_TOOL_EXECUTION_MAX_TIMEOUT_SECONDS}`
       )
       .optional()
-      .describe('How long to wait for the tool before abandoning the call.'),
+      .describe(
+        'Maximum wait time in seconds; defaults to 120 and cannot exceed 300. Timeout does not guarantee that a third-party side effect was cancelled.'
+      ),
   })
   .strict()
 export type V2ExecuteToolBody = z.input<typeof v2ExecuteToolBodySchema>
@@ -521,7 +525,9 @@ const v2OperationInputSchema = z
     visibility: z
       .string()
       .optional()
-      .describe('Who may supply the value: `user-or-llm`, `user-only`, `llm-only`, or `hidden`.'),
+      .describe(
+        'Source of the value in a workflow or Agent block: `user-or-llm`, `user-only`, `llm-only`, or `hidden`. A direct Run tool caller may supply non-hidden parameters; Sim supplies hidden ones.'
+      ),
     description: z.string().optional().describe('What the value means.'),
     default: z.unknown().optional().describe('Value used when this input is omitted.'),
     // untyped-response: tool param JSON Schema is provider-defined and arbitrarily nested
@@ -853,20 +859,23 @@ export type V2ListToolsQuery = z.output<typeof v2ListToolsQuerySchema>
 
 export const v2GetBlockParamsSchema = z.object({
   blockId: catalogIdSchema.describe(
-    'Block type identifier. An unversioned base type resolves to the newest version, and the response echoes the resolved id.'
+    'Block type identifier. An unversioned base type resolves to the newest visible version. The response echoes the resolved ID.'
   ),
 })
 export type V2GetBlockParams = z.output<typeof v2GetBlockParamsSchema>
 
 export const v2GetToolParamsSchema = z.object({
   toolId: catalogIdSchema.describe(
-    'Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id.'
+    'Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID.'
   ),
 })
 export type V2GetToolParams = z.output<typeof v2GetToolParamsSchema>
 
 export const v2ListConnectorTypesQuerySchema = catalogWorkspaceQuerySchema
   .extend({
+    workspaceId: catalogWorkspaceQuerySchema.shape.workspaceId.describe(
+      'Workspace used to authorize Knowledge Base access to the deployment’s connector-type registry. Workspace integration allowlists and revealed preview blocks do not filter this catalog.'
+    ),
     search: v2SearchSchema.describe('Case-insensitive substring match against the connector name.'),
     detail: v2ConnectorTypeDetailSchema
       .optional()
diff --git a/apps/sim/lib/api/contracts/v2/chat-deployments.ts b/apps/sim/lib/api/contracts/v2/chat-deployments.ts
index 77420d073fb..b5631257316 100644
--- a/apps/sim/lib/api/contracts/v2/chat-deployments.ts
+++ b/apps/sim/lib/api/contracts/v2/chat-deployments.ts
@@ -72,12 +72,16 @@ export const v2ChatDeploymentCustomizationsSchema = z
       .string()
       .max(2000, 'customizations.welcomeMessage must be at most 2000 characters')
       .optional()
-      .describe('First message shown to a visitor.'),
+      .describe(
+        'First message shown to a visitor. On replace, omission uses the platform default; an empty string keeps the existing message.'
+      ),
     imageUrl: z
       .string()
       .max(2048, 'customizations.imageUrl must be at most 2048 characters')
       .optional()
-      .describe('Avatar image shown beside assistant messages.'),
+      .describe(
+        'Avatar image shown beside assistant messages. On replace, omission or an empty string keeps the existing avatar.'
+      ),
   })
   .strict()
   .meta({
@@ -333,7 +337,9 @@ export const v2ReplaceChatDeploymentBodySchema = z
       .describe('Description shown to visitors. Omitted clears it.'),
     customizations: v2ChatDeploymentCustomizationsSchema
       .optional()
-      .describe('Presentation overrides. Omitted fields take platform defaults.'),
+      .describe(
+        'Presentation overrides. Omitted `primaryColor` and `welcomeMessage` use platform defaults; an omitted or empty `imageUrl` keeps the existing avatar. An empty `welcomeMessage` keeps the existing message.'
+      ),
     authType: chatAuthTypeSchema
       .optional()
       .describe('How visitors are gated. `public` leaves the chat open to anyone holding the URL.')
diff --git a/apps/sim/lib/api/contracts/v2/credentials.ts b/apps/sim/lib/api/contracts/v2/credentials.ts
index 7940eed4c4a..e0be8228301 100644
--- a/apps/sim/lib/api/contracts/v2/credentials.ts
+++ b/apps/sim/lib/api/contracts/v2/credentials.ts
@@ -168,7 +168,7 @@ export const v2CredentialProviderSchema = z
   ])
   .meta({
     id: 'V2CredentialProvider',
-    title: 'Credential Provider',
+    title: 'Credential provider',
     description: 'An OAuth or service-account connection method available to a workspace.',
   })
 export type V2CredentialProvider = z.output<typeof v2CredentialProviderSchema>
@@ -377,7 +377,7 @@ export const v2CredentialConnectionAuthorizationSchema = z
   })
   .meta({
     id: 'V2CredentialConnectionAuthorization',
-    title: 'Credential Connection Authorization',
+    title: 'Credential connection authorization',
     description: 'A short-lived browser entrypoint for an OAuth connection flow.',
   })
 export type V2CredentialConnectionAuthorization = z.output<
diff --git a/apps/sim/lib/api/contracts/v2/file-versions.ts b/apps/sim/lib/api/contracts/v2/file-versions.ts
index 153dc6d0a85..8bd6515d313 100644
--- a/apps/sim/lib/api/contracts/v2/file-versions.ts
+++ b/apps/sim/lib/api/contracts/v2/file-versions.ts
@@ -137,7 +137,7 @@ export const v2RevertFileVersionBodySchema = z
       .min(1)
       .optional()
       .describe(
-        'Revert only while the file still holds the content this revision names, as returned by Get File Metadata or an earlier write; otherwise the request fails with `409`. Unlike a version number, it also catches edits that folded into the current version.'
+        'Revert only while the file still holds the content this revision names, as returned by Get file metadata or an earlier write; otherwise the request fails with `409`. Unlike a version number, it also catches edits that folded into the current version.'
       ),
   })
   .strict()
@@ -217,7 +217,11 @@ export const v2DeleteFileVersionResultSchema = z
   .object({
     fileId: z.string().describe('File whose version was deleted.'),
     version: versionNumberSchema.describe('Version number that was deleted.'),
-    deleted: z.literal(true).describe('Always true: the version and its stored content are gone.'),
+    deleted: z
+      .literal(true)
+      .describe(
+        'True when the version was removed from history. Stored-content deletion may finish through a background retry.'
+      ),
   })
   .strict()
   .meta({
diff --git a/apps/sim/lib/api/contracts/v2/files.ts b/apps/sim/lib/api/contracts/v2/files.ts
index 9e8a8003ca5..f62f33c840d 100644
--- a/apps/sim/lib/api/contracts/v2/files.ts
+++ b/apps/sim/lib/api/contracts/v2/files.ts
@@ -67,12 +67,6 @@ import { FILE_SEARCH_MODES } from '@/lib/workspace-files/search/pattern'
  * multipart part state; completion atomically registers the workspace file.
  */
 
-/** A workspace file as exposed by the v2 surface. */
-/**
- * Makes a content write conditional on the file still holding the content the caller read, named
- * by the `revision` Get File Metadata returns. A version number cannot express this: collaborative
- * and workflow writes fold into the current version rather than adding one.
- */
 /** The token naming the content a write produced, for the caller's next conditional write. */
 export const writtenFileRevisionSchema = z
   .string()
@@ -81,12 +75,17 @@ export const writtenFileRevisionSchema = z
     'Opaque token for the content this write produced. Send it back as `expectedRevision` on the next write. Absent for a file with no recorded content version.'
   )
 
+/**
+ * Makes a content write conditional on the file still holding the content the caller read, named
+ * by the `revision` Get file metadata returns. A version number cannot express this: collaborative
+ * and workflow writes fold into the current version rather than adding one.
+ */
 const expectedFileRevisionSchema = z
   .string()
   .min(1)
   .optional()
   .describe(
-    'Revision from Get File Metadata or an earlier write; the request is refused with `409` when the content moved on.'
+    'Revision from Get file metadata or an earlier write; the request is refused with `409` when the content moved on.'
   )
 
 export const v2FileSchema = z
@@ -186,7 +185,7 @@ export const v2FileMetadataSchema = v2FileSchema
         "Opaque token for the file's current content. Send it back as `expectedRevision` so a write or revert is refused when the content moved on. Absent for a file with no recorded content version."
       ),
     currentVersion: versionNumberSchema.describe(
-      'Version number of the current content. List File Versions returns the history; pass this as `expectedCurrentVersion` to revert only if nothing changed since.'
+      'Current version number. List file versions returns the history. Pass this as `expectedCurrentVersion` to require that version to remain current; use `expectedRevision` to detect edits folded into the same version.'
     ),
   })
   .meta({
@@ -324,7 +323,7 @@ export const v2CreateFileBodySchema = z
       .max(70_000_000, 'content is too large')
       .default('')
       .describe(
-        'Initial file content. Omit or send an empty string for a zero-byte file. The 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`. Use an upload session for anything larger.'
+        'Initial file content. Omit or send an empty string for a zero-byte file. The complete JSON request is capped at 10 MiB, including UTF-8 encoding, escaping, base64, and the envelope. The separate decoded-file limit is 50 MiB. Use an upload session for larger payloads.'
       ),
     encoding: z
       .enum(['utf-8', 'base64'])
@@ -727,7 +726,7 @@ export const v2UpdateFileContentBodySchema = z
       .string()
       .max(70_000_000, 'content is too large')
       .describe(
-        'Complete replacement content for the file. The 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`.'
+        'Complete replacement content for the file. The complete JSON request is capped at 10 MiB, including UTF-8 encoding, escaping, base64, and the envelope. The separate decoded-file limit is 50 MiB. Small patches can edit a larger stored text file without sending its full content.'
       ),
     encoding: z
       .enum(['utf-8', 'base64'])
diff --git a/apps/sim/lib/api/contracts/v2/knowledge-chunks.ts b/apps/sim/lib/api/contracts/v2/knowledge-chunks.ts
index e9602911bff..6e7b676bfc1 100644
--- a/apps/sim/lib/api/contracts/v2/knowledge-chunks.ts
+++ b/apps/sim/lib/api/contracts/v2/knowledge-chunks.ts
@@ -146,12 +146,14 @@ const v2KnowledgeChunkContentSchema = z
     MAX_V2_KNOWLEDGE_CHUNK_CONTENT_LENGTH,
     `content cannot exceed ${MAX_V2_KNOWLEDGE_CHUNK_CONTENT_LENGTH} characters`
   )
-  .describe('Text to embed. It is embedded on write, so the chunk is searchable immediately.')
+  .describe(
+    'Text embedded before the response. Search includes it when the chunk and document are enabled and the document has completed processing.'
+  )
 
 /**
  * A created chunk is appended: its `chunkIndex` is assigned server-side as one
  * past the document's current maximum, and it inherits the document's tag
- * values. The document must have finished processing.
+ * values. Search includes it after the document has finished processing.
  */
 export const v2CreateKnowledgeChunkBodySchema = z
   .object({
diff --git a/apps/sim/lib/api/contracts/v2/knowledge.ts b/apps/sim/lib/api/contracts/v2/knowledge.ts
index f23869161d3..185ec13cb60 100644
--- a/apps/sim/lib/api/contracts/v2/knowledge.ts
+++ b/apps/sim/lib/api/contracts/v2/knowledge.ts
@@ -97,7 +97,7 @@ const v2KnowledgeChunkingConfigSchema = knowledgeBaseDataSchema.shape.chunkingCo
       .describe('Minimum chunk size in characters.')
       .meta({ examples: [100] }),
     overlap: knowledgeBaseDataSchema.shape.chunkingConfig.shape.overlap
-      .describe('Number of overlapping characters between adjacent chunks.')
+      .describe('Requested overlap in tokens between adjacent chunks.')
       .meta({ examples: [200] }),
     strategy: knowledgeBaseDataSchema.shape.chunkingConfig.shape.strategy.describe(
       'Chunking strategy applied during document processing.'
@@ -174,7 +174,7 @@ export const v2KnowledgeBaseSchema = knowledgeBaseDataSchema
     deletedAt: v2TimestampSchema
       .nullable()
       .describe(
-        'ISO 8601 archive timestamp, or null while active. Use List Knowledge Bases with `scope=archived` to find archived knowledge bases.'
+        'ISO 8601 archive timestamp, or null while active. Use List knowledge bases with `scope=archived` to find archived knowledge bases.'
       )
       .meta({ format: 'date-time', examples: ['2026-01-16T09:00:00Z'] }),
   })
@@ -282,7 +282,7 @@ export const v2KnowledgeDocumentTagsSchema = z
       .describe('Tag value; dates are ISO 8601 strings and an unset tag is null.')
   )
   .describe(
-    'Document tag values keyed by display name. Writes use slots such as `tag1`; use List Tags to map names to slots.'
+    'Document tag values keyed by display name. Writes use slots such as `tag1`; use List tags to map names to slots.'
   )
   .meta({ examples: [{ category: 'billing', priority: 2 }] })
 
@@ -440,16 +440,10 @@ export const v2KnowledgeSearchDataSchema = z
       .nonnegative()
       .describe('Number of results returned.')
       .meta({ examples: [4] }),
-    /**
-     * Required, not optional. Reranking degrades to vector ordering on a provider
-     * failure or an unconfigured credential, and that fallback was previously
-     * indistinguishable from a reranker that ran — same 200, same order, no
-     * `rerankerScore` on any result. A field a caller has to remember to look for
-     * would reproduce the same gap for anyone who does not.
-     */
+    /** Required so callers can distinguish a successful rerank from fallback retrieval ordering after provider or credential failures. */
     rerankerStatus: rerankerStatusSchema
       .describe(
-        'What the reranker did on this search. `applied` means it ordered the results, which carry `rerankerScore`. `unavailable` means it was attempted but could not complete, so results are in vector order with no `rerankerScore` — the search still succeeded, and is worth retrying. `skipped` means there was nothing to rank. `not_requested` means `rerankerEnabled` was absent or false.'
+        'Reranking outcome. `applied` means results carry `rerankerScore` and follow that score. `unavailable` means reranking could not produce a usable order; the search succeeded in retrieval order without `rerankerScore`. Retry if reranking is needed. `skipped` means there was nothing to rank. `not_requested` means `rerankerEnabled` was absent or false.'
       )
       .meta({ examples: ['applied'] }),
   })
@@ -564,7 +558,7 @@ export const v2UploadKnowledgeDocumentFormSchema = z
     file: z
       .file()
       .max(MAX_KNOWLEDGE_DOCUMENT_FILE_SIZE)
-      .describe('Document file to upload; the maximum size is 100 MB.'),
+      .describe('Document file to upload; the maximum size is 100 MiB.'),
   })
   .catchall(z.unknown().describe('Additional multipart form fields are ignored.'))
 export type V2UploadKnowledgeDocumentForm = z.input<typeof v2UploadKnowledgeDocumentFormSchema>
@@ -642,7 +636,7 @@ export const v2ListKnowledgeBasesQuerySchema = z
     scope: v2KnowledgeBaseScopeSchema
       .default('active')
       .describe(
-        'Lifecycle scope: active or archived knowledge bases. Use Restore Knowledge Base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.'
+        'Lifecycle scope: active or archived knowledge bases. Use Restore knowledge base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.'
       ),
     folderPath: v2FolderPathInputSchema
       .optional()
@@ -668,7 +662,7 @@ const v2KnowledgeChunkingConfigInputSchema = withChunkingConfigRules(
         .meta({ examples: [100] }),
       overlap: chunkingConfigFieldsSchema.shape.overlap
         .default(DEFAULT_CHUNKING_CONFIG.overlap)
-        .describe('Number of overlapping characters between adjacent chunks.')
+        .describe('Requested overlap in tokens between adjacent chunks.')
         .meta({ examples: [200] }),
       strategy: chunkingConfigFieldsSchema.shape.strategy.describe(
         'Chunking strategy applied during document processing. `regex` additionally requires `strategyOptions.pattern`.'
@@ -954,7 +948,9 @@ export const v2KnowledgeSearchBodySchema = z
       'Workspace that owns the knowledge bases.'
     ),
     knowledgeBaseIds: v1KnowledgeSearchBodySchema.shape.knowledgeBaseIds
-      .describe('One knowledge base identifier or an array of up to 20 identifiers.')
+      .describe(
+        'One knowledge base ID or an array of up to 20 IDs. Query searches require the same embedding model and dimensions across all selected bases; search incompatible bases separately. Tag-only searches do not require this.'
+      )
       .meta({ examples: [['7c9e6679-7425-40de-944b-e07fc1f90ae7']] }),
     query: z
       .string()
@@ -986,13 +982,13 @@ export const v2KnowledgeSearchBodySchema = z
         `Up to ${MAX_V2_KNOWLEDGE_DOCUMENT_TAG_FILTERS} filters combined with AND; repeating a tag narrows results. To express OR, run separate searches. Every tag must exist with the same slot and field type in each selected knowledge base or the request is rejected. List valid names with the knowledge-base tag-list operation.`
       ),
     searchMode: v1KnowledgeSearchBodySchema.shape.searchMode.describe(
-      'Retrieval strategy: vector is semantic-only, while hybrid also runs full-text search.'
+      'Retrieval strategy: `vector` uses semantic search; `hybrid` also runs full-text search. Omit to use the workspace policy.'
     ),
     rerankerEnabled: z
       .boolean()
       .optional()
       .describe(
-        'Re-order retrieved chunks with a reranking model before truncating to `topK`. Ignored for a tag-only search, and billed as an additional search unit. Reranking is best-effort — a provider failure falls back to vector ordering, so check `rerankerStatus` on the response.'
+        'Reorder retrieved chunks with a reranking model before truncating to `topK`. Ignored for tag-only searches. A completed reranking call adds a search unit. If reranking is unavailable, results keep their retrieval order; check `rerankerStatus`.'
       ),
     /**
      * Defaulted, matching the internal search contract this one otherwise
@@ -1225,7 +1221,7 @@ export const v2GetKnowledgeDocumentContract = defineRouteContract({
  */
 export const v2KnowledgeTagSchema = z
   .object({
-    id: z.string().describe('Tag definition ID used by Update Tag and Delete Tag.'),
+    id: z.string().describe('Tag definition ID used by Update tag and Delete tag.'),
     displayName: z
       .string()
       .describe('Display name used by tag filters and by tag values on document reads.')
@@ -1233,7 +1229,7 @@ export const v2KnowledgeTagSchema = z
     tagSlot: z
       .string()
       .describe(
-        'Storage slot the tag occupies. Document writes set tag values by slot (`tag1`..`tag7`).'
+        'Slot used by document updates: `tag1`–`tag7`, `number1`–`number5`, `date1`–`date2`, or `boolean1`–`boolean3`. Upload creation accepts text slots; use Update document for other types.'
       )
       .meta({ examples: ['tag1'] }),
     fieldType: z
@@ -2005,7 +2001,7 @@ export const v2AddWorkspaceFilesToKnowledgeBaseBodySchema = z
         `fileReferences cannot contain more than ${MAX_V2_BULK_KNOWLEDGE_DOCUMENTS} files`
       )
       .describe(
-        'Workspace file identifiers or storage keys to index. Duplicates resolving to the same file are indexed once.'
+        'Workspace file IDs or paths to index. Prefer IDs or canonical `files/<folder>/<name>` paths. Duplicates resolving to the same file are indexed once.'
       ),
   })
   .strict()
diff --git a/apps/sim/lib/api/contracts/v2/logs-stats.ts b/apps/sim/lib/api/contracts/v2/logs-stats.ts
index aa613db5ad0..87adf00110a 100644
--- a/apps/sim/lib/api/contracts/v2/logs-stats.ts
+++ b/apps/sim/lib/api/contracts/v2/logs-stats.ts
@@ -56,7 +56,7 @@ const v2IncludeEmptySegmentsSchema = z
   .describe(
     'Whether buckets with no runs are included in every series. Off by default, so each series carries only the buckets that hold at least one run; set it to publish exactly `segmentCount` buckets per series, empty ones included. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.'
   )
-  .meta({ enum: [...V2_TRUE_VALUES, ...V2_FALSE_VALUES] })
+  .meta({ enum: [...V2_TRUE_VALUES, ...V2_FALSE_VALUES], default: 'false' })
 
 const v2LogSegmentSchema = z
   .object({
diff --git a/apps/sim/lib/api/contracts/v2/mcp-servers.ts b/apps/sim/lib/api/contracts/v2/mcp-servers.ts
index d711e4ee851..2d92aabc3e8 100644
--- a/apps/sim/lib/api/contracts/v2/mcp-servers.ts
+++ b/apps/sim/lib/api/contracts/v2/mcp-servers.ts
@@ -116,17 +116,11 @@ export const v2McpServerSchema = z
     enabled: mcpServerSchema.shape.enabled.describe(
       'Whether the server tools are available to workflows.'
     ),
-    /**
-     * These three are written only by a real discovery. Registration's one
-     * outbound touch is the auth-type probe, which classifies the endpoint and
-     * never records a connection, so registration leaves all three at their
-     * defaults rather than asserting a connection nothing has verified.
-     */
     connectionStatus: mcpServerSchema.shape.connectionStatus.describe(
-      'Result of the most recent connection attempt. Registration and re-registration establish no connection — the auth-type probe they may send does not count as one — so a server begins, and returns to, `disconnected` until a tool discovery runs.'
+      'Result of the most recent tool connection attempt. New registrations start `disconnected`; re-registration resets this state only when connection inputs change. Authentication probes do not establish a tool connection. Tool discovery updates this state.'
     ),
     lastError: mcpServerSchema.shape.lastError.describe(
-      'Message from the most recent failed connection, or null when absent. A re-registration clears it, since the configuration it described no longer applies.'
+      'Message from the most recent failed tool connection, or null when absent. Successful discovery or re-registration with changed connection inputs clears it.'
     ),
     toolCount: mcpServerSchema.shape.toolCount.describe(
       'Number of tools discovered on the server.'
@@ -135,7 +129,7 @@ export const v2McpServerSchema = z
       'ISO 8601 timestamp of the most recent tool-list refresh.'
     ),
     lastConnected: mcpServerSchema.shape.lastConnected.describe(
-      'ISO 8601 timestamp of the most recent successful connection. Absent until the server completes one; registering a server does not set it.'
+      'ISO 8601 timestamp of the most recent successful tool connection. Absent until one succeeds, or after re-registration changes connection inputs.'
     ),
     createdAt: mcpServerSchema.shape.createdAt.describe(
       'ISO 8601 timestamp when the server was registered.'
@@ -230,7 +224,7 @@ export const v2CreateMcpServerBodySchema = z
     authType: mcpAuthTypeSchema
       .optional()
       .describe(
-        'Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server does not advertise OAuth. A server publishing RFC 9728 metadata is therefore stored as `oauth`, and headers configured afterwards will not authenticate — send this field explicitly to pin the method.'
+        'Authentication method. On creation, omission without `headers` probes once: an OAuth challenge selects `oauth`, an unauthenticated success selects `none`, and other outcomes fall back to `headers`. An OAuth client ID selects `oauth` when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method.'
       ),
     /** Write-only. Reads expose `hasHeaders` and `headerNames` instead. */
     headers: v2McpServerHeadersSchema
diff --git a/apps/sim/lib/api/contracts/v2/meta.ts b/apps/sim/lib/api/contracts/v2/meta.ts
index d896e4cff50..1d8c83df377 100644
--- a/apps/sim/lib/api/contracts/v2/meta.ts
+++ b/apps/sim/lib/api/contracts/v2/meta.ts
@@ -6,7 +6,7 @@ import { v2DataResponse, v2TimestampSchema } from '@/lib/api/contracts/v2/shared
 export const v2ApiKeyTypeSchema = z
   .enum(['personal', 'workspace', 'oauth_access_token'])
   .describe(
-    'Whether the calling credential is a personal API key carrying the full authority of its owner across their workspaces, a key scoped to one workspace, or an OAuth access token acting for its user within the scopes it was granted.'
+    'Calling credential kind: a personal API key acting for its owner, a key bound to one workspace, or an OAuth access token acting for its user within granted scopes. Resource permissions and credential policies still apply.'
   )
 export type V2ApiKeyType = z.output<typeof v2ApiKeyTypeSchema>
 
@@ -25,7 +25,7 @@ export const v2MetaSchema = z
   })
   .meta({
     id: 'V2Meta',
-    title: 'API capabilities',
+    title: 'API status',
     description: 'API availability and lifecycle facts about the calling credential.',
   })
 export type V2Meta = z.output<typeof v2MetaSchema>
diff --git a/apps/sim/lib/api/contracts/v2/openapi/README.md b/apps/sim/lib/api/contracts/v2/openapi/README.md
index c450535b2b0..586269c6d1c 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/README.md
+++ b/apps/sim/lib/api/contracts/v2/openapi/README.md
@@ -6,7 +6,7 @@ Write enough context to choose and use an operation correctly. Concision means r
 
 | Location | Content |
 | --- | --- |
-| Operation `summary` | A short action and resource name, using the existing title-case convention: `Create Workflow`, `Replace File Content`. |
+| Operation `summary` | A short action and resource name in sentence case: `Create workflow`, `Replace file content`. Preserve product names and acronyms such as API, MCP, OAuth, and SSO. |
 | Operation `description` | The result, relevant scope, and important behavior: side effects, partial success, asynchronous completion, destructive changes, retry safety, or a distinction from a related operation. |
 | Parameter or schema description | The field's meaning, units, omission/null behavior, dependencies, and interpretation. Let the schema declare types, required fields, enums, and bounds; explain them in prose only when needed for correct use. |
 | Response description | What the result represents, including partial, truncated, pending, or redacted results. |
@@ -26,7 +26,7 @@ Write enough context to choose and use an operation correctly. Concision means r
 - Describe user-visible outcomes instead of storage formats, locking, redaction internals, or deployment architecture. For an open-ended status, say to handle unknown values; the caller does not need to know how statuses are stored. Keep implementation details only when they change correct usage.
 - Avoid generic filter inventories and repeated schema details. Preserve exceptions such as bounded pages, null cursors with truncated results, and counts read independently of result pages.
 
-For example, an upsert description should say: “Insert a row or replace the row matching a selected unique column. On replacement, omitted columns are cleared; send the complete row. Use Update Row for a partial patch.”
+For example, an upsert description should say: “Insert a row or replace the row matching a selected unique column. On replacement, omitted columns are cleared; send the complete row. Use Update row for a partial patch.”
 
 ## Sources and verification
 
diff --git a/apps/sim/lib/api/contracts/v2/openapi/access-requests.ts b/apps/sim/lib/api/contracts/v2/openapi/access-requests.ts
index f7efbe4ffd9..f084914e8b3 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/access-requests.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/access-requests.ts
@@ -43,12 +43,12 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.discover,
       operationId: 'discoverWorkspaceAccessRequests',
-      summary: 'Discover Workspace Access Requests',
+      summary: 'Discover workspace access requests',
       description: `Discover the acting user’s access to features, integrations, models, tools, authentication methods, and member credit limits. Returns an empty list while requests are disabled. Requires access to the workspace; external collaborators use their workspace grant. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Discover Workspace Access Requests result.',
+        description: 'A page of access targets and the acting user’s current access state.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -56,20 +56,20 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2DiscoverWorkspaceAccessRequestsContract.params,
         'DiscoverWorkspaceAccessRequestsParams',
-        'Discover Workspace Access Requests parameters',
-        'Scope and request identifiers.'
+        'Discover workspace access requests parameters',
+        'Workspace identifier.'
       ),
       query: documentedSchema(
         v2DiscoverWorkspaceAccessRequestsContract.query,
         'DiscoverWorkspaceAccessRequestsQuery',
-        'Discover Workspace Access Requests query',
+        'Discover workspace access requests query',
         'Query parameters for this operation.'
       ),
       response: documentedSchema(
         v2DiscoverWorkspaceAccessRequestsContract.response.schema,
         'DiscoverWorkspaceAccessRequestsResponse',
-        'Discover Workspace Access Requests response',
-        'Discover Workspace Access Requests result.',
+        'Discover workspace access requests response',
+        'A page of access targets and the acting user’s current access state.',
         [
           {
             data: [
@@ -92,12 +92,12 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.listMine,
       operationId: 'listMyWorkspaceAccessRequests',
-      summary: 'List My Workspace Access Requests',
+      summary: 'List my workspace access requests',
       description: `List only the acting user’s requests in this workspace, including resolved history and organization-wide member credit-limit requests. History remains available while requests are disabled. Requires access to the workspace; external collaborators use their workspace grant. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'List My Workspace Access Requests result.',
+        description: 'A page of the acting user’s workspace and member-credit requests.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -105,20 +105,20 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2ListMyWorkspaceAccessRequestsContract.params,
         'ListMyWorkspaceAccessRequestsParams',
-        'List My Workspace Access Requests parameters',
-        'Scope and request identifiers.'
+        'List my workspace access requests parameters',
+        'Workspace identifier.'
       ),
       query: documentedSchema(
         v2ListMyWorkspaceAccessRequestsContract.query,
         'ListMyWorkspaceAccessRequestsQuery',
-        'List My Workspace Access Requests query',
+        'List my workspace access requests query',
         'Query parameters for this operation.'
       ),
       response: documentedSchema(
         v2ListMyWorkspaceAccessRequestsContract.response.schema,
         'ListMyWorkspaceAccessRequestsResponse',
-        'List My Workspace Access Requests response',
-        'List My Workspace Access Requests result.',
+        'List my workspace access requests response',
+        'A page of the acting user’s workspace and member-credit requests.',
         [{ data: [requestExample], nextCursor: null }]
       ),
     }
@@ -128,12 +128,13 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.create,
       operationId: 'createWorkspaceAccessRequest',
-      summary: 'Create Workspace Access Request',
-      description: `Request access for the acting user using a target from discovery. Returns an existing matching pending request when applicable; the result may be closed if access is already available. Permission approvals change the governing group for all affected members. Requires access to the workspace; external collaborators use their workspace grant. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create workspace access request',
+      description: `Request access using a target from Discover workspace access requests. Requires access to an organization-owned workspace with requests enabled; external collaborators use their workspace grant. Each requester can have 100 pending requests and submit 100 in 24 hours within the organization. Matching pending requests are reused; an existing request may be closed if access is already available. Permission approvals change the governing group for all affected members. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Create Workspace Access Request result.',
+        description:
+          'The new request, matching pending request, or existing request closed because access became available.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -141,27 +142,27 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2CreateWorkspaceAccessRequestContract.params,
         'CreateWorkspaceAccessRequestParams',
-        'Create Workspace Access Request parameters',
-        'Scope and request identifiers.'
+        'Create workspace access request parameters',
+        'Workspace identifier.'
       ),
       query: documentedSchema(
         v2CreateWorkspaceAccessRequestContract.query,
         'CreateWorkspaceAccessRequestQuery',
-        'Create Workspace Access Request query',
-        'Query parameters for this operation.'
+        'Create workspace access request query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2CreateWorkspaceAccessRequestContract.body,
         'CreateWorkspaceAccessRequestBody',
-        'Create Workspace Access Request body',
-        'Inputs for this operation.',
+        'Create workspace access request body',
+        'A discovered access target and an optional reason for the request.',
         [{ target: requestExample.target, reason: 'Maintain team data' }]
       ),
       response: documentedSchema(
         v2CreateWorkspaceAccessRequestContract.response.schema,
         'CreateWorkspaceAccessRequestResponse',
-        'Create Workspace Access Request response',
-        'Create Workspace Access Request result.',
+        'Create workspace access request response',
+        'The new request, matching pending request, or existing request closed because access became available.',
         [{ data: requestExample }]
       ),
     }
@@ -171,12 +172,12 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.cancel,
       operationId: 'cancelWorkspaceAccessRequest',
-      summary: 'Cancel Workspace Access Request',
+      summary: 'Cancel workspace access request',
       description: `Cancel the acting user’s pending request in this scope, including an organization-wide member credit-limit request. Already resolved requests are returned unchanged. Cancellation remains available while requests are disabled. Requires access to the workspace; external collaborators use their workspace grant. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Cancel Workspace Access Request result.',
+        description: 'The cancelled request, or the unchanged request if already resolved.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -184,20 +185,20 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2CancelWorkspaceAccessRequestContract.params,
         'CancelWorkspaceAccessRequestParams',
-        'Cancel Workspace Access Request parameters',
+        'Cancel workspace access request parameters',
         'Scope and request identifiers.'
       ),
       query: documentedSchema(
         v2CancelWorkspaceAccessRequestContract.query,
         'CancelWorkspaceAccessRequestQuery',
-        'Cancel Workspace Access Request query',
-        'Query parameters for this operation.'
+        'Cancel workspace access request query',
+        'No query parameters.'
       ),
       response: documentedSchema(
         v2CancelWorkspaceAccessRequestContract.response.schema,
         'CancelWorkspaceAccessRequestResponse',
-        'Cancel Workspace Access Request response',
-        'Cancel Workspace Access Request result.',
+        'Cancel workspace access request response',
+        'The cancelled request, or the unchanged request if already resolved.',
         [
           {
             data: { ...requestExample, status: 'cancelled', decidedAt: '2026-06-01T10:00:00.000Z' },
@@ -211,12 +212,12 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.discover,
       operationId: 'discoverOrganizationAccessRequests',
-      summary: 'Discover Organization Access Requests',
+      summary: 'Discover organization access requests',
       description: `Discover the acting user’s access to features, integrations, models, tools, authentication methods, and member credit limits. Returns an empty list while requests are disabled. Requires organization membership. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Discover Organization Access Requests result.',
+        description: 'A page of access targets and the acting user’s current access state.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -224,20 +225,20 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2DiscoverOrganizationAccessRequestsContract.params,
         'DiscoverOrganizationAccessRequestsParams',
-        'Discover Organization Access Requests parameters',
-        'Scope and request identifiers.'
+        'Discover organization access requests parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2DiscoverOrganizationAccessRequestsContract.query,
         'DiscoverOrganizationAccessRequestsQuery',
-        'Discover Organization Access Requests query',
+        'Discover organization access requests query',
         'Query parameters for this operation.'
       ),
       response: documentedSchema(
         v2DiscoverOrganizationAccessRequestsContract.response.schema,
         'DiscoverOrganizationAccessRequestsResponse',
-        'Discover Organization Access Requests response',
-        'Discover Organization Access Requests result.',
+        'Discover organization access requests response',
+        'A page of access targets and the acting user’s current access state.',
         [
           {
             data: [
@@ -260,12 +261,12 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.listMine,
       operationId: 'listMyOrganizationAccessRequests',
-      summary: 'List My Organization Access Requests',
-      description: `List the acting user’s organization-level requests and member credit-limit requests, including resolved history. For workspace-scoped requests, use List My Workspace Access Requests. History remains available while requests are disabled. Requires organization membership. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List my organization access requests',
+      description: `List the acting user’s organization-level requests and member credit-limit requests, including resolved history. For workspace-scoped requests, use List my workspace access requests. History remains available while requests are disabled. Requires organization membership. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'List My Organization Access Requests result.',
+        description: 'A page of the acting user’s organization and member-credit requests.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -273,20 +274,20 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2ListMyOrganizationAccessRequestsContract.params,
         'ListMyOrganizationAccessRequestsParams',
-        'List My Organization Access Requests parameters',
-        'Scope and request identifiers.'
+        'List my organization access requests parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2ListMyOrganizationAccessRequestsContract.query,
         'ListMyOrganizationAccessRequestsQuery',
-        'List My Organization Access Requests query',
+        'List my organization access requests query',
         'Query parameters for this operation.'
       ),
       response: documentedSchema(
         v2ListMyOrganizationAccessRequestsContract.response.schema,
         'ListMyOrganizationAccessRequestsResponse',
-        'List My Organization Access Requests response',
-        'List My Organization Access Requests result.',
+        'List my organization access requests response',
+        'A page of the acting user’s organization and member-credit requests.',
         [{ data: [{ ...requestExample, workspaceId: null }], nextCursor: null }]
       ),
     }
@@ -296,12 +297,13 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.create,
       operationId: 'createOrganizationAccessRequest',
-      summary: 'Create Organization Access Request',
-      description: `Request access for the acting user using a target from discovery. Returns an existing matching pending request when applicable; the result may be closed if access is already available. Permission approvals change the governing group for all affected members. Requires organization membership. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create organization access request',
+      description: `Request access using a target from Discover organization access requests. Requires organization membership and requests enabled. Each requester can have 100 pending requests and submit 100 in 24 hours within the organization. Matching pending requests are reused; an existing request may be closed if access is already available. Permission approvals change the governing group for all affected members. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Create Organization Access Request result.',
+        description:
+          'The new request, matching pending request, or existing request closed because access became available.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -309,27 +311,27 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2CreateOrganizationAccessRequestContract.params,
         'CreateOrganizationAccessRequestParams',
-        'Create Organization Access Request parameters',
-        'Scope and request identifiers.'
+        'Create organization access request parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2CreateOrganizationAccessRequestContract.query,
         'CreateOrganizationAccessRequestQuery',
-        'Create Organization Access Request query',
-        'Query parameters for this operation.'
+        'Create organization access request query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2CreateOrganizationAccessRequestContract.body,
         'CreateOrganizationAccessRequestBody',
-        'Create Organization Access Request body',
-        'Inputs for this operation.',
+        'Create organization access request body',
+        'A discovered access target and an optional reason for the request.',
         [{ target: requestExample.target, reason: 'Maintain team data' }]
       ),
       response: documentedSchema(
         v2CreateOrganizationAccessRequestContract.response.schema,
         'CreateOrganizationAccessRequestResponse',
-        'Create Organization Access Request response',
-        'Create Organization Access Request result.',
+        'Create organization access request response',
+        'The new request, matching pending request, or existing request closed because access became available.',
         [{ data: { ...requestExample, workspaceId: null } }]
       ),
     }
@@ -339,12 +341,12 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.cancel,
       operationId: 'cancelOrganizationAccessRequest',
-      summary: 'Cancel Organization Access Request',
+      summary: 'Cancel organization access request',
       description: `Cancel the acting user’s pending request in this scope, including an organization-wide member credit-limit request. Already resolved requests are returned unchanged. Cancellation remains available while requests are disabled. Requires organization membership. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Cancel Organization Access Request result.',
+        description: 'The cancelled request, or the unchanged request if already resolved.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -352,20 +354,20 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2CancelOrganizationAccessRequestContract.params,
         'CancelOrganizationAccessRequestParams',
-        'Cancel Organization Access Request parameters',
+        'Cancel organization access request parameters',
         'Scope and request identifiers.'
       ),
       query: documentedSchema(
         v2CancelOrganizationAccessRequestContract.query,
         'CancelOrganizationAccessRequestQuery',
-        'Cancel Organization Access Request query',
-        'Query parameters for this operation.'
+        'Cancel organization access request query',
+        'No query parameters.'
       ),
       response: documentedSchema(
         v2CancelOrganizationAccessRequestContract.response.schema,
         'CancelOrganizationAccessRequestResponse',
-        'Cancel Organization Access Request response',
-        'Cancel Organization Access Request result.',
+        'Cancel organization access request response',
+        'The cancelled request, or the unchanged request if already resolved.',
         [
           {
             data: {
@@ -384,12 +386,12 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.listOrganization,
       operationId: 'listOrganizationAccessRequests',
-      summary: 'List Organization Access Requests',
-      description: `List requests across the organization for administrator review. Includes requests from organization members and external workspace collaborators; history remains available while requests are disabled. Requires organization administrator access. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List organization access requests',
+      description: `List requests across the organization for administrator review. Includes requests from organization members and external workspace collaborators; history remains available while requests are disabled. Requires organization Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'List Organization Access Requests result.',
+        description: 'A page of requests across the organization for Admin review.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -397,20 +399,20 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2ListOrganizationAccessRequestsContract.params,
         'ListOrganizationAccessRequestsParams',
-        'List Organization Access Requests parameters',
-        'Scope and request identifiers.'
+        'List organization access requests parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2ListOrganizationAccessRequestsContract.query,
         'ListOrganizationAccessRequestsQuery',
-        'List Organization Access Requests query',
+        'List organization access requests query',
         'Query parameters for this operation.'
       ),
       response: documentedSchema(
         v2ListOrganizationAccessRequestsContract.response.schema,
         'ListOrganizationAccessRequestsResponse',
-        'List Organization Access Requests response',
-        'List Organization Access Requests result.',
+        'List organization access requests response',
+        'A page of requests across the organization for Admin review.',
         [{ data: [requestExample], nextCursor: null }]
       ),
     }
@@ -420,12 +422,12 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.preview,
       operationId: 'previewOrganizationAccessRequest',
-      summary: 'Preview Organization Access Request',
-      description: `Preview the current permission changes, affected group and audience, or member credit cap. Review canApply, changes, impact, and fingerprint before resolving. Permission changes affect the entire governing group, not only the requester. Requires organization administrator access. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Preview organization access request',
+      description: `Preview the current permission changes, affected group and audience, or member credit cap. Review \`canApply\`, \`changes\`, \`impact\`, and \`fingerprint\` before resolving. Permission changes affect the entire governing group, not only the requester. Requires organization Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Preview Organization Access Request result.',
+        description: 'The proposed group or credit-cap change, affected audience, and fingerprint.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -433,20 +435,20 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2PreviewOrganizationAccessRequestContract.params,
         'PreviewOrganizationAccessRequestParams',
-        'Preview Organization Access Request parameters',
+        'Preview organization access request parameters',
         'Scope and request identifiers.'
       ),
       query: documentedSchema(
         v2PreviewOrganizationAccessRequestContract.query,
         'PreviewOrganizationAccessRequestQuery',
-        'Preview Organization Access Request query',
-        'Query parameters for this operation.'
+        'Preview organization access request query',
+        'No query parameters.'
       ),
       response: documentedSchema(
         v2PreviewOrganizationAccessRequestContract.response.schema,
         'PreviewOrganizationAccessRequestResponse',
-        'Preview Organization Access Request response',
-        'Preview Organization Access Request result.',
+        'Preview organization access request response',
+        'The proposed group or credit-cap change, affected audience, and fingerprint.',
         [
           {
             data: {
@@ -478,12 +480,12 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.resolve,
       operationId: 'resolveOrganizationAccessRequest',
-      summary: 'Resolve Organization Access Request',
-      description: `Apply a reviewed request or decline it with a reason. Applying requires the preview fingerprint; changed policy or membership returns a conflict. Credit requests also require a higher newLimitCredits. Already resolved requests are returned unchanged. Requires organization administrator access. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Resolve organization access request',
+      description: `Apply a reviewed request or decline it with a reason. Applying requires the preview fingerprint; changed policy or membership returns a conflict. Credit requests also require a higher \`newLimitCredits\`. Already resolved requests are returned unchanged. Requires organization Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Resolve Organization Access Request result.',
+        description: 'The applied or declined request, or its unchanged resolved state.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -491,27 +493,27 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2ResolveOrganizationAccessRequestContract.params,
         'ResolveOrganizationAccessRequestParams',
-        'Resolve Organization Access Request parameters',
+        'Resolve organization access request parameters',
         'Scope and request identifiers.'
       ),
       query: documentedSchema(
         v2ResolveOrganizationAccessRequestContract.query,
         'ResolveOrganizationAccessRequestQuery',
-        'Resolve Organization Access Request query',
-        'Query parameters for this operation.'
+        'Resolve organization access request query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2ResolveOrganizationAccessRequestContract.body,
         'ResolveOrganizationAccessRequestBody',
-        'Resolve Organization Access Request body',
-        'Inputs for this operation.',
+        'Resolve organization access request body',
+        'Apply the reviewed fingerprint, with a higher credit cap when applicable, or decline with a reason.',
         [{ action: 'apply', expectedFingerprint: 'current-preview-fingerprint' }]
       ),
       response: documentedSchema(
         v2ResolveOrganizationAccessRequestContract.response.schema,
         'ResolveOrganizationAccessRequestResponse',
-        'Resolve Organization Access Request response',
-        'Resolve Organization Access Request result.',
+        'Resolve organization access request response',
+        'The applied or declined request, or its unchanged resolved state.',
         [
           {
             data: { ...requestExample, status: 'fulfilled', decidedAt: '2026-06-01T10:00:00.000Z' },
@@ -525,12 +527,12 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.getSettings,
       operationId: 'getOrganizationAccessRequestSettings',
-      summary: 'Get Organization Access Request Settings',
-      description: `Get whether the organization allows new access requests and approvals. This preference does not enable features unavailable in the deployment or subscription. Requires organization administrator access. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get organization access request settings',
+      description: `Get whether the organization allows new access requests and approvals. This preference does not enable features unavailable in the deployment or subscription. Requires organization Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Get Organization Access Request Settings result.',
+        description: 'Whether new requests and approvals are allowed.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -538,20 +540,20 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2GetOrganizationAccessRequestSettingsContract.params,
         'GetOrganizationAccessRequestSettingsParams',
-        'Get Organization Access Request Settings parameters',
-        'Scope and request identifiers.'
+        'Get organization access request settings parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2GetOrganizationAccessRequestSettingsContract.query,
         'GetOrganizationAccessRequestSettingsQuery',
-        'Get Organization Access Request Settings query',
-        'Query parameters for this operation.'
+        'Get organization access request settings query',
+        'No query parameters.'
       ),
       response: documentedSchema(
         v2GetOrganizationAccessRequestSettingsContract.response.schema,
         'GetOrganizationAccessRequestSettingsResponse',
-        'Get Organization Access Request Settings response',
-        'Get Organization Access Request Settings result.',
+        'Get organization access request settings response',
+        'Whether new requests and approvals are allowed.',
         [{ data: { allowRequests: true } }]
       ),
     }
@@ -561,12 +563,12 @@ export const accessRequestOpenApiRoutes = [
     {
       applicationOperation: accessRequestOperations.updateSettings,
       operationId: 'updateOrganizationAccessRequestSettings',
-      summary: 'Update Organization Access Request Settings',
-      description: `Allow or pause new access requests and approvals. Pausing preserves history, cancellation, and decline, and does not revoke previously granted access. Requires organization administrator access. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update organization access request settings',
+      description: `Allow or pause new access requests and approvals. Pausing preserves history, cancellation, and decline, and does not revoke previously granted access. Requires organization Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Access Requests'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Update Organization Access Request Settings result.',
+        description: 'The saved setting for new requests and approvals.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -574,27 +576,27 @@ export const accessRequestOpenApiRoutes = [
       params: documentedSchema(
         v2UpdateOrganizationAccessRequestSettingsContract.params,
         'UpdateOrganizationAccessRequestSettingsParams',
-        'Update Organization Access Request Settings parameters',
-        'Scope and request identifiers.'
+        'Update organization access request settings parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2UpdateOrganizationAccessRequestSettingsContract.query,
         'UpdateOrganizationAccessRequestSettingsQuery',
-        'Update Organization Access Request Settings query',
-        'Query parameters for this operation.'
+        'Update organization access request settings query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2UpdateOrganizationAccessRequestSettingsContract.body,
         'UpdateOrganizationAccessRequestSettingsBody',
-        'Update Organization Access Request Settings body',
-        'Inputs for this operation.',
+        'Update organization access request settings body',
+        'Whether new requests and approvals are allowed.',
         [{ allowRequests: false }]
       ),
       response: documentedSchema(
         v2UpdateOrganizationAccessRequestSettingsContract.response.schema,
         'UpdateOrganizationAccessRequestSettingsResponse',
-        'Update Organization Access Request Settings response',
-        'Update Organization Access Request Settings result.',
+        'Update organization access request settings response',
+        'The saved setting for new requests and approvals.',
         [{ data: { allowRequests: false } }]
       ),
     }
diff --git a/apps/sim/lib/api/contracts/v2/openapi/billing.ts b/apps/sim/lib/api/contracts/v2/openapi/billing.ts
index 0a1e1e1b4e4..b0bc54c6900 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/billing.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/billing.ts
@@ -81,9 +81,9 @@ const routes = [
     billingOperation({
       applicationOperation: billingOperations.readStatus,
       operationId: 'getBillingStatus',
-      summary: 'Get Billing Status',
+      summary: 'Get billing status',
       description:
-        "Get the current plan, billing standing, credit allowance, and storage quota. Pooled `credits` and `storage` are visible only to callers who can manage the payer's billing; workspace API keys receive null for both. Use List Billing Logs for credit history.",
+        "Get the current plan, billing standing, credit allowance, and storage quota. Pooled `credits` and `storage` are visible only to callers who can manage the payer's billing; workspace API keys receive null for both. Use List billing logs for credit history.",
       errors: RESOURCE_ERRORS,
       success: { description: 'The current billing and storage status.' },
     }),
@@ -108,7 +108,7 @@ const routes = [
     billingOperation({
       applicationOperation: billingOperations.listLogs,
       operationId: 'listBillingLogs',
-      summary: 'List Billing Logs',
+      summary: 'List billing logs',
       description:
         'List credit usage with source filtering and cursor pagination. The default `period` is `30d`; pagination covers only the selected time window. An inverted custom window returns `400`.',
       errors: RESOURCE_ERRORS,
@@ -135,7 +135,7 @@ const routes = [
 export const billingOpenApiDocument = defineOpenApiDocument({
   output: 'apps/docs/openapi-v2-billing.json',
   info: {
-    title: 'Sim API v2 — Billing',
+    title: 'Sim API v2 — billing',
     description:
       'Version 2 of the Sim REST API for billing standing, credit allowance, storage quota, and cursor-paginated usage history.',
     version: '2.0.0',
diff --git a/apps/sim/lib/api/contracts/v2/openapi/credential-members.ts b/apps/sim/lib/api/contracts/v2/openapi/credential-members.ts
index 16d3cb12ea6..5dc18686a19 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/credential-members.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/credential-members.ts
@@ -17,17 +17,20 @@ export const credentialMemberOpenApiRoutes = [
     {
       applicationOperation: credentialOperations.listMembers,
       operationId: 'listCredentialMembers',
-      summary: 'List Credential Members',
-      description: `List explicit credential grants, including revoked grants, and inherited workspace administrator access. Requires workspace read access and the integrations.manage capability. Personal API keys and OAuth tokens can access OAuth or service-account credentials; sessions can also access workspace environment credentials. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List credential members',
+      description: `List explicit credential grants, including revoked grants, and inherited workspace Admin access. Personal API keys and OAuth access tokens can list grants for OAuth or service-account credentials. Requires workspace read access and the \`integrations.manage\` capability. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Credentials'],
       errors: RESOURCE_ERRORS,
-      success: { description: 'List Credential Members result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'A page of explicit and inherited credential grants.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2ListCredentialMembersContract.params,
         'ListCredentialMembersParams',
-        'List Credential Members parameters',
+        'List credential members parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
@@ -39,8 +42,8 @@ export const credentialMemberOpenApiRoutes = [
       response: documentedSchema(
         v2ListCredentialMembersContract.response.schema,
         'ListCredentialMembersResponse',
-        'List Credential Members response',
-        'List Credential Members result.'
+        'List credential members response',
+        'A page of explicit and inherited credential grants.'
       ),
     }
   ),
@@ -49,17 +52,20 @@ export const credentialMemberOpenApiRoutes = [
     {
       applicationOperation: credentialOperations.upsertMember,
       operationId: 'upsertCredentialMember',
-      summary: 'Upsert Credential Member',
-      description: `Grant or change an existing workspace member’s credential role. Requires credential administrator access and the integrations.manage capability. Revoked grants become active again; inherited administrators cannot be demoted. A new grant returns 201; an existing grant returns 200. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Upsert credential member',
+      description: `Grant or change a current workspace member’s credential role. Requires credential Admin access and the \`integrations.manage\` capability. Revoked grants become active again; inherited workspace Admins cannot be demoted. A new grant returns \`201\`; an existing grant returns \`200\`. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Credentials'],
       errors: RESOURCE_ERRORS,
-      success: { description: 'Upsert Credential Member result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The saved credential role and whether a grant was created.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2UpsertCredentialMemberContract.params,
         'UpsertCredentialMemberParams',
-        'Upsert Credential Member parameters',
+        'Upsert credential member parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
@@ -71,14 +77,14 @@ export const credentialMemberOpenApiRoutes = [
       body: documentedSchema(
         v2UpsertCredentialMemberContract.body,
         'UpsertCredentialMemberBody',
-        'Upsert Credential Member body',
-        'Configuration accepted by Upsert Credential Member.'
+        'Upsert credential member body',
+        'The current workspace member and credential role to grant.'
       ),
       response: documentedSchema(
         v2UpsertCredentialMemberContract.response.schema,
         'UpsertCredentialMemberResponse',
-        'Upsert Credential Member response',
-        'Upsert Credential Member result.'
+        'Upsert credential member response',
+        'The saved credential role and whether a grant was created.'
       ),
     }
   ),
@@ -87,17 +93,20 @@ export const credentialMemberOpenApiRoutes = [
     {
       applicationOperation: credentialOperations.removeMember,
       operationId: 'removeCredentialMember',
-      summary: 'Remove Credential Member',
-      description: `Revoke an active explicit credential grant. Requires credential administrator access and the integrations.manage capability. Inherited workspace administrators cannot be removed; an absent or already-revoked grant returns 404. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Remove credential member',
+      description: `Revoke an active explicit credential grant. Requires credential Admin access and the \`integrations.manage\` capability. Inherited workspace Admins cannot be removed; an absent or already-revoked grant returns \`404\`. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Credentials'],
       errors: RESOURCE_ERRORS,
-      success: { description: 'Remove Credential Member result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'Acknowledgement that the explicit credential grant was revoked.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2RemoveCredentialMemberContract.params,
         'RemoveCredentialMemberParams',
-        'Remove Credential Member parameters',
+        'Remove credential member parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
@@ -109,8 +118,8 @@ export const credentialMemberOpenApiRoutes = [
       response: documentedSchema(
         v2RemoveCredentialMemberContract.response.schema,
         'RemoveCredentialMemberResponse',
-        'Remove Credential Member response',
-        'Remove Credential Member result.'
+        'Remove credential member response',
+        'Acknowledgement that the explicit credential grant was revoked.'
       ),
     }
   ),
diff --git a/apps/sim/lib/api/contracts/v2/openapi/files-audit.ts b/apps/sim/lib/api/contracts/v2/openapi/files-audit.ts
index d0b268056d6..fe19ef283db 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/files-audit.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/files-audit.ts
@@ -159,7 +159,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.list,
       operationId: 'listFiles',
-      summary: 'List Files',
+      summary: 'List files',
       description: `List active workspace files with folder filtering, search, sorting, and cursor pagination. Use \`scope=archived\` to find files available for restoration. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'A page of workspace files.' },
@@ -185,7 +185,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.create,
       operationId: 'createFile',
-      summary: 'Create File',
+      summary: 'Create file',
       description:
         'Create a workspace file from inline UTF-8 or base64 content. Use an upload session for streamed or larger files.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
@@ -220,7 +220,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.uploadCreate,
       operationId: 'createFileUpload',
-      summary: 'Create File Upload',
+      summary: 'Create file upload',
       description:
         'Create a resumable upload session and receive either a signed PUT URL or multipart instructions.',
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
@@ -255,7 +255,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.uploadRead,
       operationId: 'getFileUpload',
-      summary: 'Get File Upload',
+      summary: 'Get file upload',
       description:
         "Get an upload session's state to determine whether an interrupted transfer can resume. Requires the signed upload token and current workspace access.",
       errors: RESOURCE_ERRORS,
@@ -293,7 +293,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.uploadCancel,
       operationId: 'abortFileUpload',
-      summary: 'Abort File Upload',
+      summary: 'Abort file upload',
       description:
         'Abort an incomplete upload session and discard its uploaded data. Completed uploads cannot be aborted.',
       errors: RESOURCE_CONFLICT_ERRORS,
@@ -331,7 +331,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.uploadParts,
       operationId: 'createFileUploadPartUrls',
-      summary: 'Create File Upload Part URLs',
+      summary: 'Create file upload part URLs',
       description: 'Create signed URLs for a bounded set of multipart upload part numbers.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'Signed URLs for the requested upload parts.' },
@@ -375,7 +375,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.uploadComplete,
       operationId: 'completeFileUpload',
-      summary: 'Complete File Upload',
+      summary: 'Complete file upload',
       description:
         'Finalize an upload and register its workspace file. Repeating a completed upload returns the existing file.',
       errors: RESOURCE_CONFLICT_ERRORS,
@@ -413,9 +413,9 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.readContent,
       operationId: 'readFileText',
-      summary: 'Read File Text',
+      summary: 'Read file text',
       description:
-        'Extract text without changing the file. Accepts its ID or canonical path (`files/<folder>/<name>` or `uploads/<name>` for an unlisted chat upload); the response echoes the read path. Use Unzip File to unpack archives or Download File for original bytes. Unsupported types return `400`, compiling documents return `409`, and oversized files return `413`. `degraded: true` indicates incomplete or synthesized text, such as the legacy `.pptx` fallback; `truncated: true` indicates a parser limit.',
+        'Extract text without changing the file. Accepts its ID or canonical path (`files/<folder>/<name>` or `uploads/<name>` for an unlisted chat upload); the response echoes the read path. Use Unzip file to unpack archives or Download file for original bytes. Unsupported types return `400`, compiling documents return `409`, and oversized files return `413`. `degraded: true` indicates incomplete or synthesized text, such as the legacy `.pptx` fallback; `truncated: true` indicates a parser limit.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The extracted text and its extraction-quality flags.' },
     }),
@@ -445,7 +445,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.listVersions,
       operationId: 'listFileVersions',
-      summary: 'List File Versions',
+      summary: 'List file versions',
       description:
         'List the versions of a file, newest first by default. Each write that changes the bytes records one; identical rewrites do not. Collaborative edits, and repeated workflow writes by one author, fold into a version under ten minutes old and written in the last five. Renames and moves are not versions. Retention removes older versions by age and plan but keeps the newest ten, so numbers can have gaps.',
       errors: RESOURCE_ERRORS,
@@ -478,7 +478,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.readVersion,
       operationId: 'getFileVersion',
-      summary: 'Get File Version',
+      summary: 'Get file version',
       description:
         'Get one version of a file. A version removed by retention, or one that never existed, returns `404`.',
       errors: RESOURCE_ERRORS,
@@ -511,9 +511,9 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.deleteVersion,
       operationId: 'deleteFileVersion',
-      summary: 'Delete File Version',
+      summary: 'Delete file version',
       description:
-        'Permanently delete one earlier version and its stored content, for example to purge a leaked value from history before retention removes it. The current version returns `409`; revert to another version first. A version that does not exist returns `404`.',
+        'Permanently remove an earlier version from history and schedule deletion of its stored content. Storage cleanup may retry in the background. The current version returns `409`; revert to another version first. A version that does not exist returns `404`.',
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'Deletion confirmation.' },
     }),
@@ -544,9 +544,9 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.readVersionContent,
       operationId: 'readFileVersionText',
-      summary: 'Read File Version Text',
+      summary: 'Read file version text',
       description:
-        'Extract the text of one version, exactly as Read File Text extracts the current content. Unsupported types return `400`, compiling documents return `409`, and oversized versions return `413`.',
+        'Extract the text of one version, exactly as Read file text extracts the current content. Unsupported types return `400`, compiling documents return `409`, and oversized versions return `413`.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: {
         description: 'The extracted text of the version and its extraction-quality flags.',
@@ -578,8 +578,8 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.downloadVersion,
       operationId: 'downloadFileVersion',
-      summary: 'Download File Version',
-      description: `Download the bytes of one version, served exactly as Download File serves the current bytes. Generated documents use compiled artifacts, returning \`409\` while compiling and \`413\` above the rendered-size ceiling. Downloading records an audit event. ${HEAD_MIRRORS_GET} ${HEAD_OMITS_PAYLOAD_HEADERS}`,
+      summary: 'Download file version',
+      description: `Download the bytes of one version, served exactly as Download file serves the current bytes. Generated documents use compiled artifacts, returning \`409\` while compiling and \`413\` above the rendered-size ceiling. Downloading records an audit event. ${HEAD_MIRRORS_GET} ${HEAD_OMITS_PAYLOAD_HEADERS}`,
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: {
         description: 'The version bytes.',
@@ -607,9 +607,9 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.revertVersion,
       operationId: 'revertFileVersion',
-      summary: 'Revert File Version',
+      summary: 'Revert file version',
       description:
-        'Make the content of a version current again by writing it as a new `revert` version, so the revert can itself be reverted. Open editors receive the change. Reverting to the current version writes nothing and returns `reverted: false`. A concurrent write, or an `expectedCurrentVersion` that is no longer current, returns `409`; a version above 100 MB returns `413`.',
+        'Make the content of a version current again by writing it as a new `revert` version, so the revert can itself be reverted. Open editors receive the change. Reverting to the current version writes nothing and returns `reverted: false`. A concurrent write, or an `expectedCurrentVersion` that is no longer current, returns `409`; a version above 100 MiB returns `413`.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The file and its current version after the revert.' },
     }),
@@ -656,7 +656,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.download,
       operationId: 'bulkDownloadFiles',
-      summary: 'Bulk Download Files',
+      summary: 'Bulk download files',
       description: `Stream selected files and recursive folder contents as a ZIP archive. Each selection parameter and the resolved set allow ${MAX_ZIP_DOWNLOAD_FILES} entries; unmatched paths or excess entries return \`400\`. Total bytes are bounded. Downloads record an audit event. ${HEAD_MIRRORS_GET} ${HEAD_OMITS_PAYLOAD_HEADERS}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
@@ -679,9 +679,9 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.extractArchive,
       operationId: 'unzipFile',
-      summary: 'Unzip File',
+      summary: 'Unzip file',
       description:
-        'Extract a ZIP archive into a new sibling folder and return counts and the destination path. Use List Files to inspect its contents. Large archives can take minutes; concurrent extraction of the same archive returns `409`. Size or processing-time limits return `413`.',
+        'Extract a ZIP archive into a new sibling folder and return counts and the destination path. Use List files to inspect its contents. Large archives can take minutes; concurrent extraction of the same archive returns `409`. Size or processing-time limits return `413`.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'Counts and destination folder for the unpacked archive.' },
     }),
@@ -712,7 +712,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.download,
       operationId: 'downloadFile',
-      summary: 'Download File',
+      summary: 'Download file',
       description: `Download current file bytes. Generated documents use compiled artifacts, returning \`409\` while compiling and \`413\` above the rendered-size ceiling. Downloading records an audit event. ${HEAD_MIRRORS_GET} ${HEAD_OMITS_PAYLOAD_HEADERS}`,
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: {
@@ -741,9 +741,9 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.delete,
       operationId: 'deleteFile',
-      summary: 'Delete File',
+      summary: 'Delete file',
       description:
-        'Archive a workspace file, retaining its stored bytes and removing API read access. List Files with `scope=archived` finds it; Restore File recovers it. Archiving an already archived file returns `404`.',
+        'Archive a workspace file, retaining its stored bytes and removing API read access. List files with `scope=archived` finds it; Restore file recovers it. Archiving an already archived file returns `404`.',
       errors: RESOURCE_ERRORS,
       success: { description: 'Deletion confirmation.' },
     }),
@@ -773,7 +773,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.rename,
       operationId: 'renameFile',
-      summary: 'Rename File',
+      summary: 'Rename file',
       description: 'Rename a workspace file without changing its containing folder.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The renamed file.' },
@@ -812,7 +812,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.restore,
       operationId: 'restoreFile',
-      summary: 'Restore File',
+      summary: 'Restore file',
       description:
         'Restore a soft-deleted file to its original folder, or the workspace root if that folder was archived. Name collisions add a `_restored` suffix; read `folderPath` and `name` from the response. Already-active files return unchanged, making retries safe. An archived workspace returns `400`; an unresolved name collision returns `409`.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
@@ -837,7 +837,7 @@ const declaredRoutes = [
         v2RestoreFileContract.response.schema,
         'V2RestoreFileResponse',
         'Restore file response',
-        'The restored workspace file, at the root and under its post-restore name.',
+        'The restored file, with its resulting folderPath and name.',
         [{ data: { ...FILE_EXAMPLE, name: 'data_restored.csv', folderPath: '/' } }]
       ),
     }
@@ -847,9 +847,9 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.readMetadata,
       operationId: 'getFile',
-      summary: 'Get File Metadata',
+      summary: 'Get file metadata',
       description:
-        'Get file metadata, its public-share configuration, and the version number of its current content. The `share` field is null when the file has never been shared. `currentVersion` identifies the content in List File Versions and is the precondition Revert File Version accepts.',
+        'Get file metadata, its public-share configuration, and the version number of its current content. The `share` field is null when the file has never been shared. `currentVersion` identifies the content in List file versions and is the precondition Revert file version accepts.',
       errors: RESOURCE_ERRORS,
       success: { description: 'File metadata and public-share state.' },
     }),
@@ -898,7 +898,7 @@ const declaredRoutes = [
     auditOperation({
       applicationOperation: auditLogOperations.list,
       operationId: 'listAuditLogs',
-      summary: 'List Audit Logs',
+      summary: 'List audit logs',
       description: `List an organization audit trail with filters and opaque cursor pagination. Requires an Enterprise subscription and organization admin or owner access. ${WORKSPACE_API_KEY_DENIED}`,
       errors: WORKSPACE_ERRORS,
       success: { description: 'A page of audit-log entries.' },
@@ -924,7 +924,7 @@ const declaredRoutes = [
     auditOperation({
       applicationOperation: auditLogOperations.readDetail,
       operationId: 'getAuditLog',
-      summary: 'Get Audit Log',
+      summary: 'Get audit log',
       description: `Get one organization audit-log entry. Requires an Enterprise subscription and organization admin or owner access. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The requested audit-log entry.' },
@@ -956,7 +956,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.move,
       operationId: 'moveFileItems',
-      summary: 'Move Files',
+      summary: 'Move files',
       description: 'Move up to 1,000 files to a folder path or the workspace root.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'Count of moved files.' },
@@ -990,7 +990,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.readShare,
       operationId: 'getFileShare',
-      summary: 'Get File Share',
+      summary: 'Get file share',
       description:
         "Get a file's public-share configuration. An unshared file returns `data: null`; a disabled share returns its configuration with `isActive: false`.",
       errors: RESOURCE_ERRORS,
@@ -1023,7 +1023,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.updateShare,
       operationId: 'upsertFileShare',
-      summary: 'Enable or Disable File Share',
+      summary: 'Enable or disable file share',
       description: `Create or update a file's public share. \`isActive\` is required; other fields describe their behavior when access modes change. Enabling a protected mode on a previously unshared file requires its credential in the same request. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The updated file share.' },
@@ -1067,9 +1067,9 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.updateContent,
       operationId: 'editFileContent',
-      summary: 'Edit File Content',
+      summary: 'Edit file content',
       description:
-        'Edit part of a UTF-8 file; use Replace File Content to replace it entirely. Search-and-replace requires one exact match unless `replaceAll` is true. Anchored modes match trimmed complete lines; their input descriptions specify boundary handling. Non-UTF-8 files return `400`. Concurrent writes return `409`; re-read before retrying.',
+        'Edit part of a UTF-8 file; use Replace file content to replace it entirely. Search-and-replace requires one exact match unless `replaceAll` is true. Anchored modes match trimmed complete lines; their input descriptions specify boundary handling. Non-UTF-8 files return `400`. Concurrent writes return `409`; re-read before retrying.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge', 'Locked'],
       success: { description: 'The edited file and its new line count.' },
     }),
@@ -1119,7 +1119,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.searchContent,
       operationId: 'searchFileContent',
-      summary: 'Search File Content',
+      summary: 'Search file content',
       description:
         'Search indexed text in active workspace files and return matching lines with file IDs and line numbers. `folderPaths` limits both results and reported coverage. Missing matches are inconclusive if `complete` is false or `indexStatus.skippedFiles` or `indexStatus.partialFiles` is nonzero. `truncated` means additional matches exist beyond `maxResults`.',
       errors: [...WORKSPACE_ERRORS, 'NotFound', 'Locked'],
@@ -1168,7 +1168,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.updateContent,
       operationId: 'updateFileContent',
-      summary: 'Replace File Content',
+      summary: 'Replace file content',
       description:
         'Replace the complete contents of an existing file from UTF-8 or base64 input. A stale `expectedRevision`, or a write that raced this one, returns `409`; re-read before retrying.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
@@ -1215,9 +1215,9 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.delete,
       operationId: 'bulkDeleteFiles',
-      summary: 'Delete Files',
+      summary: 'Delete files',
       description:
-        'Archive up to 1,000 workspace files while retaining their stored bytes. Use Restore File to recover each file.',
+        'Archive up to 1,000 workspace files while retaining their stored bytes. Use Restore file to recover each file.',
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'Count of deleted files.' },
     }),
@@ -1249,8 +1249,8 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.listFolders,
       operationId: 'listFilesFolders',
-      summary: 'List Folders',
-      description: `List workspace file folders with parent-path filtering and sorting. Use \`scope=archived\` to find paths accepted by Restore Folder. ${FULL_SET_LIST}`,
+      summary: 'List folders',
+      description: `List workspace file folders with parent-path filtering and sorting. Use \`scope=archived\` to find paths accepted by Restore folder. ${FULL_SET_LIST}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'Workspace file folders.' },
     }),
@@ -1274,9 +1274,9 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.restoreFolder,
       operationId: 'restoreFilesFolder',
-      summary: 'Restore Folder',
+      summary: 'Restore folder',
       description:
-        'Restore a folder and the files and subfolders archived with it. Use the path from List Folders with `scope=archived`. A path that is not archived returns `404`.',
+        'Restore a folder and the files and subfolders archived with it. Use the path from List folders with `scope=archived`. A path that is not archived returns `404`.',
       errors: [...RESOURCE_CONFLICT_ERRORS],
       success: { description: 'The restored folder and what it brought back.' },
     }),
@@ -1301,7 +1301,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.createFolder,
       operationId: 'createFilesFolder',
-      summary: 'Create Folder',
+      summary: 'Create folder',
       description: 'Create a folder at the supplied workspace path.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The created folder.' },
@@ -1333,7 +1333,7 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.updateFolder,
       operationId: 'relocateFilesFolder',
-      summary: 'Rename or Move Folder',
+      summary: 'Rename or move folder',
       description: 'Rename or move a folder and atomically update all descendant paths.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The relocated folder.' },
@@ -1366,9 +1366,9 @@ const declaredRoutes = [
     filesOperation({
       applicationOperation: fileOperations.deleteFolder,
       operationId: 'deleteFilesFolder',
-      summary: 'Delete Folder',
+      summary: 'Delete folder',
       description:
-        'Archive an empty folder, or set `recursive=true` to archive its files and subfolders. Use Restore Folder to recover the archived contents.',
+        'Archive an empty folder, or set `recursive=true` to archive its files and subfolders. Use Restore folder to recover the archived contents.',
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'Folder deletion confirmation and deleted item counts.' },
     }),
diff --git a/apps/sim/lib/api/contracts/v2/openapi/knowledge-chunks.ts b/apps/sim/lib/api/contracts/v2/openapi/knowledge-chunks.ts
index 989aa2cfd74..dddcb216b31 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/knowledge-chunks.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/knowledge-chunks.ts
@@ -39,8 +39,8 @@ export const knowledgeChunkOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.listChunks,
       operationId: 'listKnowledgeChunks',
-      summary: 'List Chunks',
-      description: `List document chunks with content search, enabled filtering, sorting, and cursor pagination. Tags use slots; use List Tags to resolve display names. ${DOCUMENT_NOT_READY} ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List chunks',
+      description: `List document chunks with content search, enabled filtering, sorting, and cursor pagination. Tags use slots; use List tags to resolve display names. ${DOCUMENT_NOT_READY} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'A page of document chunks.' },
     }),
@@ -70,8 +70,8 @@ export const knowledgeChunkOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.createChunk,
       operationId: 'createKnowledgeChunk',
-      summary: 'Create Chunk',
-      description: `Append a chunk, embedding it before the response so it is immediately searchable. It inherits the document's tags and next \`chunkIndex\`. ${CONNECTOR_MANAGED} ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create chunk',
+      description: `Append a chunk and embed it before returning. It inherits the document's tags and next \`chunkIndex\`. Search includes it when the chunk and document are enabled and the document has completed processing. ${CONNECTOR_MANAGED} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The created chunk.' },
     }),
@@ -108,7 +108,7 @@ export const knowledgeChunkOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.bulkChunks,
       operationId: 'bulkUpdateKnowledgeChunks',
-      summary: 'Bulk Update Chunks',
+      summary: 'Bulk update chunks',
       description: `Enable, disable, or delete multiple chunks in one best-effort request. Unknown chunk IDs appear in \`errors\` without failing the request; \`processed\` counts matched chunks, not changes. ${CONNECTOR_MANAGED} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'Outcome of the bulk chunk operation.' },
@@ -147,7 +147,7 @@ export const knowledgeChunkOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.readChunk,
       operationId: 'getKnowledgeChunk',
-      summary: 'Get Chunk',
+      summary: 'Get chunk',
       description: `Get one chunk of a document, including the exact text that was embedded. ${DOCUMENT_NOT_READY} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The requested chunk.' },
@@ -178,7 +178,7 @@ export const knowledgeChunkOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.updateChunk,
       operationId: 'updateKnowledgeChunk',
-      summary: 'Update Chunk',
+      summary: 'Update chunk',
       description: `Correct chunk text or disable it from search. Changing \`content\` re-embeds immediately and recalculates document token and character counts; disabling retains the index. ${CONNECTOR_MANAGED} ${DOCUMENT_NOT_READY} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The updated chunk.' },
@@ -211,7 +211,7 @@ export const knowledgeChunkOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.deleteChunk,
       operationId: 'deleteKnowledgeChunk',
-      summary: 'Delete Chunk',
+      summary: 'Delete chunk',
       description: `Permanently remove one chunk and subtract it from document counts. Remaining \`chunkIndex\` values stay stable and may become non-contiguous. ${CONNECTOR_MANAGED} ${DOCUMENT_NOT_READY} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'Chunk deletion acknowledgement.' },
diff --git a/apps/sim/lib/api/contracts/v2/openapi/knowledge-tags.ts b/apps/sim/lib/api/contracts/v2/openapi/knowledge-tags.ts
index b356ca63709..35fc2a6c616 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/knowledge-tags.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/knowledge-tags.ts
@@ -36,8 +36,8 @@ export const knowledgeTagOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.createTag,
       operationId: 'createKnowledgeTag',
-      summary: 'Create Tag',
-      description: `Create a tag definition. Write document values by \`tagSlot\` and filter by \`displayName\`. Omitting \`tagSlot\` selects a free slot; exhaustion returns \`400\`. An occupied slot or duplicate name returns \`409\`. Use Bulk Save Tag Definitions for multiple definitions. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create tag',
+      description: `Create a tag definition. Write document values by \`tagSlot\` and filter by \`displayName\`. Omitting \`tagSlot\` selects a free slot; exhaustion returns \`400\`. An occupied slot or duplicate name returns \`409\`. Use Bulk save tag definitions for multiple definitions. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The created tag definition.' },
     }),
@@ -69,7 +69,7 @@ export const knowledgeTagOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.updateTag,
       operationId: 'updateKnowledgeTag',
-      summary: 'Update Tag',
+      summary: 'Update tag',
       description: `Rename a tag or change its slot-compatible \`fieldType\`. Renaming changes read and filter names without moving the slot or its values. Slots are fixed for a tag's lifetime; an incompatible type returns \`400\` and requires creating a new tag. A duplicate display name returns \`409\`. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The updated tag definition.' },
@@ -102,7 +102,7 @@ export const knowledgeTagOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.deleteTag,
       operationId: 'deleteKnowledgeTag',
-      summary: 'Delete Tag',
+      summary: 'Delete tag',
       description: `Permanently delete a tag definition and its values from every document and chunk in the knowledge base. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'Tag deletion acknowledgement.' },
@@ -133,8 +133,8 @@ export const knowledgeTagOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.readNextTagSlot,
       operationId: 'getNextKnowledgeTagSlot',
-      summary: 'Get Next Tag Slot',
-      description: `Get the next available slot and remaining capacity for a field type. This does not reserve a slot. Create Tag selects a free slot when \`tagSlot\` is omitted. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get next tag slot',
+      description: `Get the next available slot and remaining capacity for a field type. This does not reserve a slot. Create tag selects a free slot when \`tagSlot\` is omitted. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'Slot availability for the requested field type.' },
     }),
@@ -164,7 +164,7 @@ export const knowledgeTagOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.readTagUsage,
       operationId: 'listKnowledgeTagUsage',
-      summary: 'List Tag Usage',
+      summary: 'List tag usage',
       description: `Count the documents and chunks with a value for each defined tag. ${FULL_SET_LIST} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'Usage counts for every defined tag.' },
@@ -195,8 +195,8 @@ export const knowledgeTagOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.saveDocumentTagDefinitions,
       operationId: 'bulkSaveKnowledgeTagDefinitions',
-      summary: 'Bulk Save Tag Definitions',
-      description: `Create or update tag definitions, preserving unspecified slots. Updates require \`originalDisplayName\`; other entries create tags. Slot and name conflicts appear in per-definition \`errors\` with HTTP \`200\`, leaving conflicting values unchanged. Use Update Document to set tag values. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Bulk save tag definitions',
+      description: `Create or update tag definitions, preserving unspecified slots. Updates require \`originalDisplayName\`; other entries create tags. Slot and name conflicts appear in per-definition \`errors\` with HTTP \`200\`, leaving conflicting values unchanged. Use Update document to set tag values. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'Definitions created and updated by the save.' },
     }),
@@ -233,8 +233,8 @@ export const knowledgeTagOpenApiRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.deleteDocumentTagDefinitions,
       operationId: 'deleteKnowledgeTagDefinitions',
-      summary: 'Delete Tag Definitions',
-      description: `Delete unused tag definitions by default. With \`unused=false\`, permanently delete all definitions and their values from documents and chunks. Use Delete Tag to remove one definition. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Delete tag definitions',
+      description: `Delete unused tag definitions by default. With \`unused=false\`, permanently delete all definitions and their values from documents and chunks. Use Delete tag to remove one definition. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'Number of tag definitions removed.' },
     }),
diff --git a/apps/sim/lib/api/contracts/v2/openapi/knowledge.ts b/apps/sim/lib/api/contracts/v2/openapi/knowledge.ts
index 5bf3b052979..25ceaba8ac4 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/knowledge.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/knowledge.ts
@@ -119,7 +119,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.list,
       operationId: 'listKnowledgeBases',
-      summary: 'List Knowledge Bases',
+      summary: 'List knowledge bases',
       description: `List active knowledge bases in a workspace with folder filtering, search, sorting, and cursor pagination. Use \`scope=archived\` to find knowledge bases available for restoration. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'A page of knowledge bases.' },
@@ -144,7 +144,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.create,
       operationId: 'createKnowledgeBase',
-      summary: 'Create Knowledge Base',
+      summary: 'Create knowledge base',
       description: `Create a knowledge base in a workspace with optional folder placement and chunking configuration. An unknown \`folderPath\` returns \`404\`. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The created knowledge base.' },
@@ -177,7 +177,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.read,
       operationId: 'getKnowledgeBase',
-      summary: 'Get Knowledge Base',
+      summary: 'Get knowledge base',
       description: `Get a knowledge base's metadata and document counts. Inaccessible knowledge bases return \`404\`. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The requested knowledge base.' },
@@ -208,7 +208,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.export,
       operationId: 'exportKnowledgeBase',
-      summary: 'Export Knowledge Base',
+      summary: 'Export knowledge base',
       description: `Stream a knowledge base as a bundle archive: its configuration, tag definitions, each workspace-visible document's file and chunk text, and optionally chunk vectors. Access-control lists, connector links, and credentials never leave. More than ${MAX_KNOWLEDGE_BUNDLE_DOCUMENTS} documents returns \`413\`. Exports record an audit event. ${HEAD_MIRRORS_GET} ${HEAD_OMITS_PAYLOAD_HEADERS}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: {
@@ -237,7 +237,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.update,
       operationId: 'updateKnowledgeBase',
-      summary: 'Update Knowledge Base',
+      summary: 'Update knowledge base',
       description: `Update a knowledge base's name, description, chunking configuration, or folder placement. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The updated knowledge base.' },
@@ -270,9 +270,9 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.delete,
       operationId: 'deleteKnowledgeBase',
-      summary: 'Delete Knowledge Base',
+      summary: 'Delete knowledge base',
       description:
-        'Archive a knowledge base, its documents, and its connectors, pausing synchronization. Use List Knowledge Bases with `scope=archived` to find it and Restore Knowledge Base to recover it.',
+        'Archive a knowledge base, its documents, and its connectors, pausing synchronization. Use List knowledge bases with `scope=archived` to find it and Restore knowledge base to recover it.',
       errors: RESOURCE_ERRORS,
       success: { description: 'Knowledge base deletion acknowledgement.' },
     }),
@@ -302,7 +302,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.listConnectors,
       operationId: 'listKnowledgeConnectors',
-      summary: 'List Knowledge Connectors',
+      summary: 'List knowledge connectors',
       description: `List external sources connected to a knowledge base with cursor pagination. Stored API keys are never returned. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'A page of knowledge connectors.' },
@@ -334,7 +334,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.createConnector,
       operationId: 'createKnowledgeConnector',
-      summary: 'Create Knowledge Connector',
+      summary: 'Create knowledge connector',
       description: `Validate and connect an external source, then queue its initial synchronization. The \`apiKey\` field is never returned. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
@@ -378,7 +378,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.readConnector,
       operationId: 'getKnowledgeConnector',
-      summary: 'Get Knowledge Connector',
+      summary: 'Get knowledge connector',
       description: `Get one connector and its ten most recent synchronization attempts. Stored API keys are never returned. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: {
@@ -412,7 +412,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.updateConnector,
       operationId: 'updateKnowledgeConnector',
-      summary: 'Update Knowledge Connector',
+      summary: 'Update knowledge connector',
       description: `Update connector source configuration, schedule, or active state. Replacing source configuration on a runnable connector queues an immediate synchronization; paused connectors retain the change without synchronizing until resumed. Source configuration cannot be replaced while synchronization is already in progress. Authentication material cannot be changed through this operation. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The updated connector.' },
@@ -434,10 +434,18 @@ const declaredRoutes = [
       ),
       response: documentedSchema(
         v2UpdateKnowledgeConnectorContract.response.schema,
-        'V2KnowledgeConnectorResponse',
-        'Knowledge connector response',
+        'UpdateKnowledgeConnectorResponse',
+        'Update knowledge connector response',
         'A single connector without secret material.',
-        [{ data: KNOWLEDGE_CONNECTOR_EXAMPLE }]
+        [
+          {
+            data: {
+              ...KNOWLEDGE_CONNECTOR_EXAMPLE,
+              status: 'paused',
+              updatedAt: '2026-06-20T14:03:00.000Z',
+            },
+          },
+        ]
       ),
     }
   ),
@@ -446,7 +454,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.deleteConnector,
       operationId: 'deleteKnowledgeConnector',
-      summary: 'Delete Knowledge Connector',
+      summary: 'Delete knowledge connector',
       description: `Delete a connector and optionally its synchronized documents. Documents are retained by default. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: {
@@ -489,7 +497,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.syncConnector,
       operationId: 'syncKnowledgeConnector',
-      summary: 'Sync Knowledge Connector',
+      summary: 'Sync knowledge connector',
       description: `Queue a connector synchronization. Rehydration forces existing documents to be fetched and indexed again. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'Synchronization was queued.' },
@@ -523,7 +531,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.listConnectorDocuments,
       operationId: 'listKnowledgeConnectorDocuments',
-      summary: 'List Knowledge Connector Documents',
+      summary: 'List knowledge connector documents',
       description: `List documents produced by one connector with opaque cursor pagination. Excluded documents are omitted unless explicitly requested. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'A page of connector documents.' },
@@ -555,7 +563,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.updateConnectorDocuments,
       operationId: 'updateKnowledgeConnectorDocuments',
-      summary: 'Update Knowledge Connector Documents',
+      summary: 'Update knowledge connector documents',
       description: `Exclude connector documents from knowledge search or restore previously excluded documents. Only documents produced by the selected connector can change. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: {
@@ -605,7 +613,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.search,
       operationId: 'searchKnowledge',
-      summary: 'Search Knowledge',
+      summary: 'Search knowledge',
       description:
         'Search one or more knowledge bases with semantic vector retrieval, optional hybrid full-text retrieval, and structured tag filters. Every result names the `knowledgeBaseId` it came from. A request body over 2 MiB is a `413`. Reranking returns `409` when the stored results cannot pass secret-provenance enforcement.',
       errors: [
@@ -648,7 +656,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.listTags,
       operationId: 'listKnowledgeTags',
-      summary: 'List Tags',
+      summary: 'List tags',
       description: `List the knowledge base's tag definitions with display names, write slots, and field types. Filters and document reads use display names; document writes use slots. ${FULL_SET_LIST}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The knowledge base tag vocabulary.' },
@@ -679,9 +687,9 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.listDocuments,
       operationId: 'listKnowledgeDocuments',
-      summary: 'List Documents',
+      summary: 'List documents',
       description:
-        'List documents with filename search, state and tag filters, sorting, and cursor pagination. Tag values use display names; use List Tags to resolve the slots required for writes.',
+        'List documents with filename search, state and tag filters, sorting, and cursor pagination. Tag values use display names; use List tags to resolve the slots required for writes.',
       errors: RESOURCE_ERRORS,
       success: { description: 'A page of knowledge documents.' },
     }),
@@ -711,8 +719,8 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.bulkDocuments,
       operationId: 'bulkUpdateKnowledgeDocuments',
-      summary: 'Bulk Enable or Disable Documents',
-      description: `Enable or disable selected documents, or use \`selectAll\` for the entire knowledge base. Use Delete Document to remove documents individually. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Bulk enable or disable documents',
+      description: `Enable or disable selected documents, or use \`selectAll\` for the entire knowledge base. Use Delete document to remove documents individually. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: {
         description: 'The number and identifiers of the documents that changed.',
@@ -752,7 +760,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.uploadDocument,
       operationId: 'uploadKnowledgeDocument',
-      summary: 'Upload Document',
+      summary: 'Upload document',
       description:
         'Upload one document as multipart form data. Processing continues asynchronously after the document is accepted.',
       errors: [
@@ -799,7 +807,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.uploadCreate,
       operationId: 'createKnowledgeDocumentUpload',
-      summary: 'Create Document Upload',
+      summary: 'Create document upload',
       description:
         'Create a resumable upload session and receive direct PUT or multipart transfer instructions.',
       errors: [
@@ -848,7 +856,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.uploadCancel,
       operationId: 'abortKnowledgeDocumentUpload',
-      summary: 'Abort Document Upload',
+      summary: 'Abort document upload',
       description:
         'Abort an incomplete upload session and discard its uploaded data. Completed uploads cannot be aborted.',
       errors: RESOURCE_CONFLICT_ERRORS,
@@ -886,7 +894,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.uploadParts,
       operationId: 'createKnowledgeDocumentUploadPartUrls',
-      summary: 'Create Document Upload Part URLs',
+      summary: 'Create document upload part URLs',
       description: 'Create short-lived signed PUT URLs for up to 100 multipart part numbers.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'Signed URLs for the requested upload parts.' },
@@ -930,7 +938,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.uploadComplete,
       operationId: 'completeKnowledgeDocumentUpload',
-      summary: 'Complete Document Upload',
+      summary: 'Complete document upload',
       description:
         'Verify a direct upload or assemble multipart parts, create the knowledge document, and queue asynchronous processing.',
       errors: [...WORKSPACE_ERRORS, 'NotFound', 'Conflict'],
@@ -968,7 +976,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.readDocument,
       operationId: 'getKnowledgeDocument',
-      summary: 'Get Document',
+      summary: 'Get document',
       description: 'Get document metadata, processing status, and source connector details.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The requested knowledge document.' },
@@ -999,8 +1007,8 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.updateDocument,
       operationId: 'updateKnowledgeDocument',
-      summary: 'Update Document',
-      description: `Rename a document, change search availability, update tag slots, or requeue processing. Omitted fields remain unchanged; indexing state is read-only. Use List Tags to resolve names to slots and Get Document for source connector details, which this response omits. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update document',
+      description: `Rename a document, change search availability, update tag slots, or requeue processing. Omitted fields remain unchanged; indexing state is read-only. Use List tags to resolve names to slots and Get document for source connector details, which this response omits. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: {
         description: 'The updated document, or the requeue acknowledgement.',
@@ -1034,7 +1042,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.deleteDocument,
       operationId: 'deleteKnowledgeDocument',
-      summary: 'Delete Document',
+      summary: 'Delete document',
       description:
         'Remove a document from listings and search. Uploaded documents and their chunks are deleted. Connector documents are excluded while retaining their stored data; later synchronization does not re-add them.',
       errors: RESOURCE_ERRORS,
@@ -1066,7 +1074,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.listFolders,
       operationId: 'listKnowledgeFolders',
-      summary: 'List Folders',
+      summary: 'List folders',
       description: `List folders in the knowledge-base folder tree with filtering and sorting. ${FULL_SET_LIST} ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'A page of knowledge-base folders.' },
@@ -1091,7 +1099,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.createFolder,
       operationId: 'createKnowledgeFolder',
-      summary: 'Create Folder',
+      summary: 'Create folder',
       description: `Create a folder in the knowledge-base folder tree. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The created knowledge-base folder.' },
@@ -1118,7 +1126,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.relocateFolder,
       operationId: 'relocateKnowledgeFolder',
-      summary: 'Rename or Move Folder',
+      summary: 'Rename or move folder',
       description: `Rename or move a folder and atomically rewrite descendant paths. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The relocated knowledge-base folder.' },
@@ -1151,9 +1159,9 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.deleteFolder,
       operationId: 'deleteKnowledgeFolder',
-      summary: 'Delete Folder',
+      summary: 'Delete folder',
       description:
-        'Archive an empty folder, or set `recursive=true` to archive its subfolders and knowledge bases. Use Restore Knowledge Base to recover knowledge bases.',
+        'Archive an empty folder, or set `recursive=true` to archive its subfolders and knowledge bases. Use Restore knowledge base to recover knowledge bases.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: {
         description: 'Folder deletion acknowledgement and deleted item counts.',
@@ -1179,7 +1187,7 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.restore,
       operationId: 'restoreKnowledgeBase',
-      summary: 'Restore Knowledge Base',
+      summary: 'Restore knowledge base',
       description: `Restore a knowledge base and the documents and connectors archived with it. Active knowledge bases return unchanged without a new audit event. An archived workspace returns \`409\`; an archived containing folder moves the restored knowledge base to the workspace root. ${FOLDER_TREE_TOO_LARGE}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The restored knowledge base.' },
@@ -1212,8 +1220,8 @@ const declaredRoutes = [
     knowledgeOperation({
       applicationOperation: knowledgeOperations.addWorkspaceFiles,
       operationId: 'addWorkspaceFilesToKnowledgeBase',
-      summary: 'Index Workspace Files',
-      description: `Queue stored workspace files for indexing without re-uploading bytes. Unreadable, unsupported, or over-100 MB files appear in \`failed\`; valid files are queued. Partial success returns \`200\`. Use Get Document to poll processing after receiving document IDs. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Index workspace files',
+      description: `Queue stored workspace files for indexing without re-uploading bytes. Unreadable, unsupported, or over-100 MiB files appear in \`failed\`; valid files are queued. Partial success returns \`200\`. Use Get document to poll processing after receiving document IDs. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'UsageLimitExceeded'],
       success: {
         description: 'Files queued for indexing, with any that could not be.',
@@ -1278,7 +1286,7 @@ export const knowledgeOpenApiDocument = defineOpenApiDocument({
   headers: { ...V2_BINARY_DOWNLOAD_HEADERS, ...V2_COMMON_HEADERS },
   errorSchema: V2_ERROR_SCHEMA,
   errorResponses: withErrorExamples({
-    Conflict: { message: 'Upload has already been completed' },
+    Conflict: { message: 'The request conflicts with current knowledge resource state' },
   }),
   routes,
 })
diff --git a/apps/sim/lib/api/contracts/v2/openapi/logs.ts b/apps/sim/lib/api/contracts/v2/openapi/logs.ts
index a6d1f78ee16..eff693b0ad0 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/logs.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/logs.ts
@@ -37,7 +37,7 @@ const LOG_LIST_EXAMPLE = {
       startedAt: '2026-01-15T10:30:00.000Z',
       endedAt: '2026-01-15T10:30:01.250Z',
       totalDurationMs: 1250,
-      cost: { total: 0.0032 },
+      cost: { total: 0.0072 },
       hasHandledErrors: false,
       files: [
         {
@@ -64,7 +64,7 @@ const LOG_DETAIL_EXAMPLE = {
     startedAt: '2026-01-15T10:30:00.000Z',
     endedAt: '2026-01-15T10:30:01.250Z',
     totalDurationMs: 1250,
-    files: null,
+    files: LOG_LIST_EXAMPLE.data[0].files,
     /**
      * Deliberately a different address from `workflow.ownerEmail` below. This is
      * an `api` run, so it executed as the workspace billing account while the
@@ -87,9 +87,9 @@ const LOG_DETAIL_EXAMPLE = {
     traceSpans: [],
     finalOutput: { result: 'Hello, world!' },
     cost: {
-      total: 0.0032,
+      total: 0.0072,
       items: [
-        { category: 'fixed', description: 'Base execution charge', cost: 0.001 },
+        { category: 'fixed', description: 'Base execution charge', cost: 0.005 },
         {
           category: 'model',
           description: 'gpt-5',
@@ -165,7 +165,7 @@ const declaredRoutes = [
     logsOperation({
       applicationOperation: logOperations.list,
       operationId: 'listLogs',
-      summary: 'List Logs',
+      summary: 'List logs',
       description: `List logs with filters, selectable detail, sorting, and cursor pagination. \`includeJobRuns=true\` includes chat and Sim-agent jobs only with \`sortBy=startedAt\`, because other orderings are unsupported. \`files\` contains only run-produced files; use the files API for input attachments. ${RUN_RETENTION} ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'A page of execution logs matching the filters.' },
@@ -191,7 +191,7 @@ const declaredRoutes = [
     logsOperation({
       applicationOperation: logOperations.readDetail,
       operationId: 'getLog',
-      summary: 'Get Log',
+      summary: 'Get log',
       description: `Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty \`traceSpans\` array does not prove none were recorded. ${RUN_RETENTION} ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The requested diagnostic log representation.' },
@@ -218,7 +218,7 @@ const declaredRoutes = [
     logsOperation({
       applicationOperation: logOperations.readStats,
       operationId: 'getLogStats',
-      summary: 'Get Log Statistics',
+      summary: 'Get log statistics',
       description: `Get bucketed run counts, success rate, errors, and mean latency for the workspace and individual workflows. Query fields describe window selection and bucketing. Folder filters cover subtrees. ${RUN_RETENTION} ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'Bucketed execution statistics for the workspace.' },
diff --git a/apps/sim/lib/api/contracts/v2/openapi/organization-usage.ts b/apps/sim/lib/api/contracts/v2/openapi/organization-usage.ts
index 32bbd70a923..660dc0f50e1 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/organization-usage.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/organization-usage.ts
@@ -21,12 +21,12 @@ export const organizationUsageOpenApiRoutes = [
     {
       applicationOperation: memberUsageLimitOperations.read,
       operationId: 'getOrganizationMemberUsageLimit',
-      summary: 'Get Organization Member Credit Limit',
-      description: `Read a person’s credit cap and credits consumed in the organization billing period. Hosted only. The userId identifies an organization member or external collaborator with workspace access in this organization; it is not a membership record ID. Null means no per-person cap, while organization limits still apply. Requires organization administrator access. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get organization member credit limit',
+      description: `Read a person’s credit cap and credits consumed in the organization billing period. Hosted deployments only. The \`userId\` identifies an organization member or external collaborator with workspace access in this organization; it is not a membership record ID. Null means no per-person cap, while organization limits still apply. Requires organization Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_ERRORS,
       success: {
-        description: 'Get Organization Member Credit Limit result.',
+        description: 'The person’s current credit cap and billing-period consumption.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -34,20 +34,20 @@ export const organizationUsageOpenApiRoutes = [
       params: documentedSchema(
         v2GetOrganizationMemberUsageLimitContract.params,
         'GetOrganizationMemberUsageLimitParams',
-        'Get Organization Member Credit Limit parameters',
-        'Organization and target user identifiers, where applicable.'
+        'Get organization member credit limit parameters',
+        'Organization and target user IDs.'
       ),
       query: documentedSchema(
         v2GetOrganizationMemberUsageLimitContract.query,
         'GetOrganizationMemberUsageLimitQuery',
-        'Get Organization Member Credit Limit query',
-        'Reporting window, filtering, and pagination controls, where applicable.'
+        'Get organization member credit limit query',
+        'No query parameters.'
       ),
       response: documentedSchema(
         v2GetOrganizationMemberUsageLimitContract.response.schema,
         'GetOrganizationMemberUsageLimitResponse',
-        'Get Organization Member Credit Limit response',
-        'Get Organization Member Credit Limit result.',
+        'Get organization member credit limit response',
+        'The person’s current credit cap and billing-period consumption.',
         [{ data: { creditsUsed: 200, creditLimit: 10000, billingInterval: 'month' } }]
       ),
     }
@@ -57,12 +57,12 @@ export const organizationUsageOpenApiRoutes = [
     {
       applicationOperation: memberUsageLimitOperations.update,
       operationId: 'updateOrganizationMemberUsageLimit',
-      summary: 'Update Organization Member Credit Limit',
-      description: `Set or clear a person’s credit cap. Hosted only. The userId must identify an organization member or external collaborator with workspace access in this organization. The cap is a nonnegative whole number of credits, not dollars: 0 prevents further credit-consuming usage; null removes the per-person cap. Organization limits continue to apply. Retrying the same value is safe. Requires organization administrator access. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update organization member credit limit',
+      description: `Set or clear a person’s credit cap. Hosted deployments only. The \`userId\` must identify an organization member or external collaborator with workspace access in this organization. The cap is a nonnegative whole number of credits, not dollars: \`0\` prevents further credit-consuming usage; \`null\` removes the per-person cap. Organization limits continue to apply. Retrying the same value is safe. Requires organization Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_ERRORS,
       success: {
-        description: 'Update Organization Member Credit Limit result.',
+        description: 'The saved credit cap, or null when the cap was cleared.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -70,27 +70,27 @@ export const organizationUsageOpenApiRoutes = [
       params: documentedSchema(
         v2UpdateOrganizationMemberUsageLimitContract.params,
         'UpdateOrganizationMemberUsageLimitParams',
-        'Update Organization Member Credit Limit parameters',
-        'Organization and target user identifiers, where applicable.'
+        'Update organization member credit limit parameters',
+        'Organization and target user IDs.'
       ),
       query: documentedSchema(
         v2UpdateOrganizationMemberUsageLimitContract.query,
         'UpdateOrganizationMemberUsageLimitQuery',
-        'Update Organization Member Credit Limit query',
-        'Reporting window, filtering, and pagination controls, where applicable.'
+        'Update organization member credit limit query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2UpdateOrganizationMemberUsageLimitContract.body,
         'UpdateOrganizationMemberUsageLimitBody',
-        'Update Organization Member Credit Limit body',
+        'Update organization member credit limit body',
         'Credit cap in whole credits; null clears the cap.',
         [{ creditLimit: 10000 }, { creditLimit: null }]
       ),
       response: documentedSchema(
         v2UpdateOrganizationMemberUsageLimitContract.response.schema,
         'UpdateOrganizationMemberUsageLimitResponse',
-        'Update Organization Member Credit Limit response',
-        'Update Organization Member Credit Limit result.',
+        'Update organization member credit limit response',
+        'The saved credit cap, or null when the cap was cleared.',
         [{ data: { creditLimit: 10000 } }]
       ),
     }
@@ -100,12 +100,12 @@ export const organizationUsageOpenApiRoutes = [
     {
       applicationOperation: organizationUsageOperations.readSummary,
       operationId: 'getOrganizationUsageSummary',
-      summary: 'Get Organization Usage Summary',
-      description: `Read pooled credits, a usage series, and an exact previous-period comparison when available. Requires organization administrator access and Usage Monitoring (Enterprise on hosted; enabled on self-hosted). Defaults to 30 days. Custom dates include both dates in the selected timezone and cannot exceed 92 days. Billing windows exceeding 366 days are rejected. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get organization usage summary',
+      description: `Read pooled credits, a usage series, and an exact previous-period comparison when available. Requires organization Admin access and Usage Monitoring: Enterprise when billing is enabled, or deployment enablement when billing is disabled. Defaults to 30 days. Custom dates include both dates in the selected timezone and cannot exceed 92 days. Billing windows exceeding 366 days are rejected. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_ERRORS,
       success: {
-        description: 'Get Organization Usage Summary result.',
+        description: 'Reporting bounds, pooled credits, and chronological usage buckets.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -113,20 +113,20 @@ export const organizationUsageOpenApiRoutes = [
       params: documentedSchema(
         v2GetOrganizationUsageSummaryContract.params,
         'GetOrganizationUsageSummaryParams',
-        'Get Organization Usage Summary parameters',
-        'Organization and target user identifiers, where applicable.'
+        'Get organization usage summary parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2GetOrganizationUsageSummaryContract.query,
         'GetOrganizationUsageSummaryQuery',
-        'Get Organization Usage Summary query',
-        'Reporting window, filtering, and pagination controls, where applicable.'
+        'Get organization usage summary query',
+        'Reporting window and optional workspace filter.'
       ),
       response: documentedSchema(
         v2GetOrganizationUsageSummaryContract.response.schema,
         'GetOrganizationUsageSummaryResponse',
-        'Get Organization Usage Summary response',
-        'Get Organization Usage Summary result.',
+        'Get organization usage summary response',
+        'Reporting bounds, pooled credits, and chronological usage buckets.',
         [
           {
             data: {
@@ -150,12 +150,12 @@ export const organizationUsageOpenApiRoutes = [
     {
       applicationOperation: organizationUsageOperations.readBreakdown,
       operationId: 'getOrganizationUsageBreakdown',
-      summary: 'Get Organization Usage Breakdown',
-      description: `Read ranked organization usage by member, workspace, workflow, model, BYOK provider, or source. Requires organization administrator access and Usage Monitoring. Omitted usage is summarized in other. BYOK ranks tokens; other dimensions rank cost. More than 10,000 underlying groups returns 413; narrow the window or workspace. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get organization usage breakdown',
+      description: `Read ranked usage by member, workspace, workflow, model, BYOK provider, or source. Requires organization Admin access and Usage Monitoring. \`other\` summarizes groups omitted by the limit. BYOK ranks tokens; other dimensions rank cost. More than 10,000 underlying groups returns \`413\`; narrow the window or workspace. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: {
-        description: 'Get Organization Usage Breakdown result.',
+        description: 'Ranked usage groups and the combined remainder.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -163,20 +163,20 @@ export const organizationUsageOpenApiRoutes = [
       params: documentedSchema(
         v2GetOrganizationUsageBreakdownContract.params,
         'GetOrganizationUsageBreakdownParams',
-        'Get Organization Usage Breakdown parameters',
-        'Organization and target user identifiers, where applicable.'
+        'Get organization usage breakdown parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2GetOrganizationUsageBreakdownContract.query,
         'GetOrganizationUsageBreakdownQuery',
-        'Get Organization Usage Breakdown query',
-        'Reporting window, filtering, and pagination controls, where applicable.'
+        'Get organization usage breakdown query',
+        'Reporting window, optional workspace filter, grouping dimension, and result limit.'
       ),
       response: documentedSchema(
         v2GetOrganizationUsageBreakdownContract.response.schema,
         'GetOrganizationUsageBreakdownResponse',
-        'Get Organization Usage Breakdown response',
-        'Get Organization Usage Breakdown result.',
+        'Get organization usage breakdown response',
+        'Ranked usage groups and the combined remainder.',
         [
           {
             data: {
@@ -197,12 +197,12 @@ export const organizationUsageOpenApiRoutes = [
     {
       applicationOperation: organizationUsageOperations.listEvents,
       operationId: 'listOrganizationUsageEvents',
-      summary: 'List Organization Usage Events',
-      description: `Page through usage events, including zero-cost reporting. Requires organization administrator access and Usage Monitoring. Defaults to 30 days. Cursors retain the initial reporting window; keep filters and sort unchanged while paging. The sim-chat source covers both chat surfaces. Per-event rounding can produce credits=0 with hasCost=true. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List organization usage events',
+      description: `List usage events, including zero-cost activity. Requires organization Admin access and Usage Monitoring. Defaults to 30 days. Cursors retain the initial reporting window; keep filters and sort unchanged while paging. \`sim-chat\` covers both chat surfaces. Per-event rounding can yield \`credits: 0\` with \`hasCost: true\`. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_ERRORS,
       success: {
-        description: 'List Organization Usage Events result.',
+        description: 'A page of usage events, including zero-cost activity.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -210,20 +210,20 @@ export const organizationUsageOpenApiRoutes = [
       params: documentedSchema(
         v2ListOrganizationUsageEventsContract.params,
         'ListOrganizationUsageEventsParams',
-        'List Organization Usage Events parameters',
-        'Organization and target user identifiers, where applicable.'
+        'List organization usage events parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2ListOrganizationUsageEventsContract.query,
         'ListOrganizationUsageEventsQuery',
-        'List Organization Usage Events query',
-        'Reporting window, filtering, and pagination controls, where applicable.'
+        'List organization usage events query',
+        'Reporting window, source filter, sorting, and pagination.'
       ),
       response: documentedSchema(
         v2ListOrganizationUsageEventsContract.response.schema,
         'ListOrganizationUsageEventsResponse',
-        'List Organization Usage Events response',
-        'List Organization Usage Events result.',
+        'List organization usage events response',
+        'A page of usage events, including zero-cost activity.',
         [
           {
             data: [
diff --git a/apps/sim/lib/api/contracts/v2/openapi/organizations.ts b/apps/sim/lib/api/contracts/v2/openapi/organizations.ts
index 4c34e9a5896..2be982da7cd 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/organizations.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/organizations.ts
@@ -31,24 +31,27 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: organizationOperations.list,
       operationId: 'listOrganizations',
-      summary: 'List Organizations',
+      summary: 'List organizations',
       description: `List organizations the acting user belongs to. Organizations that disallow the calling credential are omitted. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_ERRORS,
-      success: { description: 'List Organizations result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'A page of organizations and the acting user’s role in each.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       query: documentedSchema(
         v2ListOrganizationsContract.query,
         'ListOrganizationsQuery',
-        'List Organizations query',
+        'List organizations query',
         'Filtering and pagination controls.'
       ),
       response: documentedSchema(
         v2ListOrganizationsContract.response.schema,
         'ListOrganizationsResponse',
-        'List Organizations response',
-        'List Organizations result.',
+        'List organizations response',
+        'A page of organizations and the acting user’s role in each.',
         [
           {
             data: [
@@ -72,25 +75,28 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: organizationOperations.read,
       operationId: 'getOrganization',
-      summary: 'Get Organization',
+      summary: 'Get organization',
       description: `Get organization metadata and the acting user’s organization role. Requires organization membership. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_ERRORS,
-      success: { description: 'Get Organization result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'Organization metadata and the acting user’s role.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2GetOrganizationContract.params,
         'GetOrganizationParams',
-        'Get Organization parameters',
-        'Organization and resource identifiers.'
+        'Get organization parameters',
+        'Organization identifier.'
       ),
       query: v2GetOrganizationContract.query,
       response: documentedSchema(
         v2GetOrganizationContract.response.schema,
         'GetOrganizationResponse',
-        'Get Organization response',
-        'Get Organization result.',
+        'Get organization response',
+        'Organization metadata and the acting user’s role.',
         [
           {
             data: {
@@ -111,30 +117,33 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: organizationOperations.listWorkspaces,
       operationId: 'listOrganizationWorkspaces',
-      summary: 'List Organization Workspaces',
-      description: `List active workspaces owned by the organization. Requires organization administrator access; does not require Access Control. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List organization workspaces',
+      description: `List active workspaces owned by the organization. Requires organization Admin access; does not require Access Control. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_ERRORS,
-      success: { description: 'List Organization Workspaces result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'A page of active workspaces owned by the organization.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2ListOrganizationWorkspacesContract.params,
         'ListOrganizationWorkspacesParams',
-        'List Organization Workspaces parameters',
-        'Organization and resource identifiers.'
+        'List organization workspaces parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2ListOrganizationWorkspacesContract.query,
         'ListOrganizationWorkspacesQuery',
-        'List Organization Workspaces query',
+        'List organization workspaces query',
         'Filtering and pagination controls.'
       ),
       response: documentedSchema(
         v2ListOrganizationWorkspacesContract.response.schema,
         'ListOrganizationWorkspacesResponse',
-        'List Organization Workspaces response',
-        'List Organization Workspaces result.',
+        'List organization workspaces response',
+        'A page of active workspaces owned by the organization.',
         [{ data: [{ id: 'workspace-123', name: 'Engineering' }], nextCursor: null }]
       ),
     }
@@ -144,30 +153,33 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: organizationOperations.listMembers,
       operationId: 'listOrganizationMembers',
-      summary: 'List Organization Members',
+      summary: 'List organization members',
       description: `List organization members by name or email. Ordinary members must have access to the member directory; organization administrators retain access. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_ERRORS,
-      success: { description: 'List Organization Members result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'A page of organization members and their organization roles.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2ListOrganizationMembersContract.params,
         'ListOrganizationMembersParams',
-        'List Organization Members parameters',
-        'Organization and resource identifiers.'
+        'List organization members parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2ListOrganizationMembersContract.query,
         'ListOrganizationMembersQuery',
-        'List Organization Members query',
+        'List organization members query',
         'Filtering and pagination controls.'
       ),
       response: documentedSchema(
         v2ListOrganizationMembersContract.response.schema,
         'ListOrganizationMembersResponse',
-        'List Organization Members response',
-        'List Organization Members result.',
+        'List organization members response',
+        'A page of organization members and their organization roles.',
         [
           {
             data: [
@@ -190,32 +202,35 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: organizationOperations.updateMember,
       operationId: 'updateOrganizationMember',
-      summary: 'Update Organization Member',
-      description: `Change a member’s organization role. Requires organization administrator access. The owner’s role and memberships managed by an identity provider cannot be changed here. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update organization member',
+      description: `Change a member’s organization role. Requires organization Admin access. The owner’s role and memberships managed by an identity provider cannot be changed here. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Update Organization Member result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The member with the updated organization role.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2UpdateOrganizationMemberContract.params,
         'UpdateOrganizationMemberParams',
-        'Update Organization Member parameters',
+        'Update organization member parameters',
         'Organization and resource identifiers.'
       ),
       query: v2UpdateOrganizationMemberContract.query,
       body: documentedSchema(
         v2UpdateOrganizationMemberContract.body,
         'UpdateOrganizationMemberBody',
-        'Update Organization Member body',
-        'Update Organization Member input.',
+        'Update organization member body',
+        'The new organization role for this member.',
         [{ role: 'admin' }]
       ),
       response: documentedSchema(
         v2UpdateOrganizationMemberContract.response.schema,
         'UpdateOrganizationMemberResponse',
-        'Update Organization Member response',
-        'Update Organization Member result.',
+        'Update organization member response',
+        'The member with the updated organization role.',
         [
           {
             data: {
@@ -235,25 +250,28 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: organizationOperations.removeMember,
       operationId: 'removeOrganizationMember',
-      summary: 'Remove Organization Member',
+      summary: 'Remove organization member',
       description: `Remove a member and revoke their access to organization workspaces. Administrators may remove members; members may remove themselves. The organization owner cannot be removed. Owned organization resources are reassigned and the departing member’s sessions end. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Remove Organization Member result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'Acknowledgement that organization access was removed.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2RemoveOrganizationMemberContract.params,
         'RemoveOrganizationMemberParams',
-        'Remove Organization Member parameters',
+        'Remove organization member parameters',
         'Organization and resource identifiers.'
       ),
       query: v2RemoveOrganizationMemberContract.query,
       response: documentedSchema(
         v2RemoveOrganizationMemberContract.response.schema,
         'RemoveOrganizationMemberResponse',
-        'Remove Organization Member response',
-        'Remove Organization Member result.',
+        'Remove organization member response',
+        'Acknowledgement that organization access was removed.',
         [{ data: { userId: 'user-123', deleted: true } }]
       ),
     }
@@ -263,12 +281,12 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: organizationOperations.listInvitations,
       operationId: 'listOrganizationInvitations',
-      summary: 'List Organization Invitations',
-      description: `List invitations owned by the organization, including invitations with workspace grants. Requires organization administrator access. Expired invitations are reported without modifying them. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List organization invitations',
+      description: `List invitations owned by the organization, including invitations with workspace grants. Requires organization Admin access. Expired invitations are reported without modifying them. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_ERRORS,
       success: {
-        description: 'List Organization Invitations result.',
+        description: 'A page of invitations, including their current status.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -276,20 +294,20 @@ export const organizationOpenApiRoutes = [
       params: documentedSchema(
         v2ListOrganizationInvitationsContract.params,
         'ListOrganizationInvitationsParams',
-        'List Organization Invitations parameters',
-        'Organization and resource identifiers.'
+        'List organization invitations parameters',
+        'Organization identifier.'
       ),
       query: documentedSchema(
         v2ListOrganizationInvitationsContract.query,
         'ListOrganizationInvitationsQuery',
-        'List Organization Invitations query',
+        'List organization invitations query',
         'Filtering and pagination controls.'
       ),
       response: documentedSchema(
         v2ListOrganizationInvitationsContract.response.schema,
         'ListOrganizationInvitationsResponse',
-        'List Organization Invitations response',
-        'List Organization Invitations result.',
+        'List organization invitations response',
+        'A page of invitations, including their current status.',
         [
           {
             data: [
@@ -316,12 +334,12 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: organizationOperations.createInvitation,
       operationId: 'createOrganizationInvitation',
-      summary: 'Create Organization Invitation',
-      description: `Email an invitation to join the organization as a member or administrator. Requires organization administrator access, invitations enabled, and an available seat on an eligible plan. This grants no workspace-specific permissions. An unexpired pending invitation for the email conflicts; use Resend Organization Invitation to send it again. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create organization invitation',
+      description: `Email an invitation to join the organization as a member or Admin. Requires organization Admin access and invitations enabled; an eligible plan and available seat are required when billing is enabled. It grants no workspace-specific permissions. Existing organization membership or an unexpired pending invitation for the email returns \`409\`. Use Resend organization invitation to send a pending invitation again. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Create Organization Invitation result.',
+        description: 'The pending organization invitation.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -329,22 +347,22 @@ export const organizationOpenApiRoutes = [
       params: documentedSchema(
         v2CreateOrganizationInvitationContract.params,
         'CreateOrganizationInvitationParams',
-        'Create Organization Invitation parameters',
-        'Organization and resource identifiers.'
+        'Create organization invitation parameters',
+        'Organization identifier.'
       ),
       query: v2CreateOrganizationInvitationContract.query,
       body: documentedSchema(
         v2CreateOrganizationInvitationContract.body,
         'CreateOrganizationInvitationBody',
-        'Create Organization Invitation body',
-        'Create Organization Invitation input.',
+        'Create organization invitation body',
+        'Invitee email and organization role to offer.',
         [{ email: 'member@example.com', role: 'member' }]
       ),
       response: documentedSchema(
         v2CreateOrganizationInvitationContract.response.schema,
         'CreateOrganizationInvitationResponse',
-        'Create Organization Invitation response',
-        'Create Organization Invitation result.',
+        'Create organization invitation response',
+        'The pending organization invitation.',
         [
           {
             data: {
@@ -368,25 +386,28 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: organizationOperations.readInvitation,
       operationId: 'getOrganizationInvitation',
-      summary: 'Get Organization Invitation',
-      description: `Get an invitation owned by the organization. Requires organization administrator access. Use List Organization Invitation Workspaces to inspect its workspace grants. The response excludes the acceptance token. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get organization invitation',
+      description: `Get an invitation owned by the organization. Requires organization Admin access. Use List organization invitation workspaces to inspect its workspace grants. The response excludes the acceptance token. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_ERRORS,
-      success: { description: 'Get Organization Invitation result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'Invitation metadata without its acceptance token.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2GetOrganizationInvitationContract.params,
         'GetOrganizationInvitationParams',
-        'Get Organization Invitation parameters',
+        'Get organization invitation parameters',
         'Organization and resource identifiers.'
       ),
       query: v2GetOrganizationInvitationContract.query,
       response: documentedSchema(
         v2GetOrganizationInvitationContract.response.schema,
         'GetOrganizationInvitationResponse',
-        'Get Organization Invitation response',
-        'Get Organization Invitation result.',
+        'Get organization invitation response',
+        'Invitation metadata without its acceptance token.',
         [
           {
             data: {
@@ -410,8 +431,8 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: organizationOperations.listInvitationWorkspaces,
       operationId: 'listOrganizationInvitationWorkspaces',
-      summary: 'List Organization Invitation Workspaces',
-      description: `List workspace grants attached to an invitation of any status. Includes archived workspaces still owned by the organization; workspaces moved to another organization are omitted. Requires organization administrator access. These grants describe the invitation, not the invitee's current access. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List organization invitation workspaces',
+      description: `List workspace grants attached to an invitation of any status. Includes archived workspaces still owned by the organization; workspaces moved to another organization are omitted. Requires organization Admin access. These grants describe the invitation, not the invitee's current access. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_ERRORS,
       success: {
@@ -423,19 +444,19 @@ export const organizationOpenApiRoutes = [
       params: documentedSchema(
         v2ListOrganizationInvitationWorkspacesContract.params,
         'ListOrganizationInvitationWorkspacesParams',
-        'List Organization Invitation Workspaces parameters',
+        'List organization invitation workspaces parameters',
         'Organization and invitation identifiers.'
       ),
       query: documentedSchema(
         v2ListOrganizationInvitationWorkspacesContract.query,
         'ListOrganizationInvitationWorkspacesQuery',
-        'List Organization Invitation Workspaces query',
+        'List organization invitation workspaces query',
         'Filtering, sorting, and pagination controls.'
       ),
       response: documentedSchema(
         v2ListOrganizationInvitationWorkspacesContract.response.schema,
         'ListOrganizationInvitationWorkspacesResponse',
-        'List Organization Invitation Workspaces response',
+        'List organization invitation workspaces response',
         'Workspace grants retained on an invitation.',
         [
           {
@@ -453,12 +474,12 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: invitationOperations.resend,
       operationId: 'resendOrganizationInvitation',
-      summary: 'Resend Organization Invitation',
-      description: `Email an unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization administrator access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Resend organization invitation',
+      description: `Email an unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization Admin access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Resend Organization Invitation result.',
+        description: 'The pending invitation with its renewed expiry.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -466,22 +487,22 @@ export const organizationOpenApiRoutes = [
       params: documentedSchema(
         v2ResendOrganizationInvitationContract.params,
         'ResendOrganizationInvitationParams',
-        'Resend Organization Invitation parameters',
+        'Resend organization invitation parameters',
         'Organization and resource identifiers.'
       ),
       query: v2ResendOrganizationInvitationContract.query,
       body: documentedSchema(
         v2ResendOrganizationInvitationContract.body,
         'ResendOrganizationInvitationBody',
-        'Resend Organization Invitation body',
-        'Resend Organization Invitation input.',
+        'Resend organization invitation body',
+        'An empty JSON object; the pending invitation supplies the recipient and role.',
         [{}]
       ),
       response: documentedSchema(
         v2ResendOrganizationInvitationContract.response.schema,
         'ResendOrganizationInvitationResponse',
-        'Resend Organization Invitation response',
-        'Resend Organization Invitation result.',
+        'Resend organization invitation response',
+        'The pending invitation with its renewed expiry.',
         [
           {
             data: {
@@ -505,12 +526,12 @@ export const organizationOpenApiRoutes = [
     {
       applicationOperation: invitationOperations.revoke,
       operationId: 'revokeOrganizationInvitation',
-      summary: 'Revoke Organization Invitation',
-      description: `Cancel an unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization administrator access. This does not remove a person who already accepted; use Remove Organization Member for that. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Revoke organization invitation',
+      description: `Cancel an unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization Admin access. This does not remove a person who already accepted; use Remove organization member for that. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Revoke Organization Invitation result.',
+        description: 'Acknowledgement that the pending invitation was cancelled.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -518,15 +539,15 @@ export const organizationOpenApiRoutes = [
       params: documentedSchema(
         v2RevokeOrganizationInvitationContract.params,
         'RevokeOrganizationInvitationParams',
-        'Revoke Organization Invitation parameters',
+        'Revoke organization invitation parameters',
         'Organization and resource identifiers.'
       ),
       query: v2RevokeOrganizationInvitationContract.query,
       response: documentedSchema(
         v2RevokeOrganizationInvitationContract.response.schema,
         'RevokeOrganizationInvitationResponse',
-        'Revoke Organization Invitation response',
-        'Revoke Organization Invitation result.',
+        'Revoke organization invitation response',
+        'Acknowledgement that the pending invitation was cancelled.',
         [{ data: { id: 'invitation-123', status: 'cancelled' } }]
       ),
     }
diff --git a/apps/sim/lib/api/contracts/v2/openapi/permission-groups.ts b/apps/sim/lib/api/contracts/v2/openapi/permission-groups.ts
index 170e3728704..0d0d184e6e5 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/permission-groups.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/permission-groups.ts
@@ -42,7 +42,7 @@ const MEMBER = {
   userEmail: 'member@example.com',
   userImage: null,
 }
-const AUTHORITY = `Requires organization admin or owner access and active Access Control. ${WORKSPACE_API_KEY_DENIED}`
+const AUTHORITY = `Requires organization Admin or owner access and active Access Control. ${WORKSPACE_API_KEY_DENIED}`
 
 export const permissionGroupOpenApiRoutes = [
   defineOpenApiRoute(
@@ -50,11 +50,14 @@ export const permissionGroupOpenApiRoutes = [
     {
       applicationOperation: permissionGroupOperations.list,
       operationId: 'listPermissionGroups',
-      summary: 'List Permission Groups',
+      summary: 'List permission groups',
       description: `List permission groups in an organization with cursor pagination. ${AUTHORITY}`,
       tags: ['Permission Groups'],
       errors: RESOURCE_ERRORS,
-      success: { description: 'List Permission Groups result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'A page of permission groups with resolved settings.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
@@ -72,8 +75,8 @@ export const permissionGroupOpenApiRoutes = [
       response: documentedSchema(
         v2ListPermissionGroupsContract.response.schema,
         'ListPermissionGroupsResponse',
-        'List Permission Groups response',
-        'List Permission Groups result.',
+        'List permission groups response',
+        'A page of permission groups with resolved settings.',
         [{ data: [GROUP], nextCursor: null }]
       ),
     }
@@ -83,11 +86,14 @@ export const permissionGroupOpenApiRoutes = [
     {
       applicationOperation: permissionGroupOperations.create,
       operationId: 'createPermissionGroup',
-      summary: 'Create Permission Group',
+      summary: 'Create permission group',
       description: `Create a permission group. A non-default group requires workspaces and initially governs everyone in them. Creating a default group demotes the previous default to an inactive group until it is assigned workspaces. Overlapping all-member scopes conflict. ${AUTHORITY}`,
       tags: ['Permission Groups'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Create Permission Group result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The created group, its resolved settings, and workspace scope.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
@@ -100,15 +106,15 @@ export const permissionGroupOpenApiRoutes = [
       body: documentedSchema(
         v2CreatePermissionGroupContract.body,
         'CreatePermissionGroupRequest',
-        'Create Permission Group request',
-        'Create Permission Group inputs.',
+        'Create permission group request',
+        'Group name, initial restrictions, and default or workspace-specific scope.',
         [{ name: 'Restricted', workspaceIds: ['workspace-123'] }]
       ),
       response: documentedSchema(
         v2CreatePermissionGroupContract.response.schema,
         'CreatePermissionGroupResponse',
-        'Create Permission Group response',
-        'Create Permission Group result.',
+        'Create permission group response',
+        'The created group, its resolved settings, and workspace scope.',
         [{ data: GROUP }]
       ),
     }
@@ -118,11 +124,14 @@ export const permissionGroupOpenApiRoutes = [
     {
       applicationOperation: permissionGroupOperations.read,
       operationId: 'getPermissionGroup',
-      summary: 'Get Permission Group',
+      summary: 'Get permission group',
       description: `Get a permission group and its resolved settings. ${AUTHORITY}`,
       tags: ['Permission Groups'],
       errors: RESOURCE_ERRORS,
-      success: { description: 'Get Permission Group result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The group, its resolved settings, and workspace scope.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
@@ -135,8 +144,8 @@ export const permissionGroupOpenApiRoutes = [
       response: documentedSchema(
         v2GetPermissionGroupContract.response.schema,
         'GetPermissionGroupResponse',
-        'Get Permission Group response',
-        'Get Permission Group result.',
+        'Get permission group response',
+        'The group, its resolved settings, and workspace scope.',
         [{ data: GROUP }]
       ),
     }
@@ -146,11 +155,14 @@ export const permissionGroupOpenApiRoutes = [
     {
       applicationOperation: permissionGroupOperations.update,
       operationId: 'updatePermissionGroup',
-      summary: 'Update Permission Group',
+      summary: 'Update permission group',
       description: `Update a permission group. Omitted fields remain unchanged; config keys are patched and supplied arrays replace their lists. Promoting a group to default demotes the previous default; demoting without workspaceIds leaves it inactive. Overlapping member or all-member scopes conflict. ${AUTHORITY}`,
       tags: ['Permission Groups'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Update Permission Group result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The updated group with resolved settings and workspace scope.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
@@ -163,15 +175,15 @@ export const permissionGroupOpenApiRoutes = [
       body: documentedSchema(
         v2UpdatePermissionGroupContract.body,
         'UpdatePermissionGroupRequest',
-        'Update Permission Group request',
-        'Update Permission Group inputs.',
+        'Update permission group request',
+        'Group fields and restriction keys to change; supplied lists replace their contents.',
         [{ description: 'Restricted workspace access' }]
       ),
       response: documentedSchema(
         v2UpdatePermissionGroupContract.response.schema,
         'UpdatePermissionGroupResponse',
-        'Update Permission Group response',
-        'Update Permission Group result.',
+        'Update permission group response',
+        'The updated group with resolved settings and workspace scope.',
         [{ data: GROUP }]
       ),
     }
@@ -181,11 +193,14 @@ export const permissionGroupOpenApiRoutes = [
     {
       applicationOperation: permissionGroupOperations.delete,
       operationId: 'deletePermissionGroup',
-      summary: 'Delete Permission Group',
+      summary: 'Delete permission group',
       description: `Permanently delete a permission group and its membership assignments. Members then inherit any other applicable restrictions. ${AUTHORITY}`,
       tags: ['Permission Groups'],
       errors: RESOURCE_ERRORS,
-      success: { description: 'Delete Permission Group result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'Acknowledgement that the group and its assignments were deleted.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
@@ -198,8 +213,8 @@ export const permissionGroupOpenApiRoutes = [
       response: documentedSchema(
         v2DeletePermissionGroupContract.response.schema,
         'DeletePermissionGroupResponse',
-        'Delete Permission Group response',
-        'Delete Permission Group result.',
+        'Delete permission group response',
+        'Acknowledgement that the group and its assignments were deleted.',
         [{ data: { id: 'group-123', deleted: true } }]
       ),
     }
@@ -209,12 +224,12 @@ export const permissionGroupOpenApiRoutes = [
     {
       applicationOperation: permissionGroupOperations.listMembers,
       operationId: 'listPermissionGroupMembers',
-      summary: 'List Permission Group Members',
+      summary: 'List permission group members',
       description: `List explicit membership assignments in a permission group with cursor pagination. An empty inherit group applies to everyone in its workspaces. ${AUTHORITY}`,
       tags: ['Permission Groups'],
       errors: RESOURCE_ERRORS,
       success: {
-        description: 'List Permission Group Members result.',
+        description: 'A page of explicit group membership assignments.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -234,8 +249,8 @@ export const permissionGroupOpenApiRoutes = [
       response: documentedSchema(
         v2ListPermissionGroupMembersContract.response.schema,
         'ListPermissionGroupMembersResponse',
-        'List Permission Group Members response',
-        'List Permission Group Members result.',
+        'List permission group members response',
+        'A page of explicit group membership assignments.',
         [{ data: [MEMBER], nextCursor: null }]
       ),
     }
@@ -245,11 +260,14 @@ export const permissionGroupOpenApiRoutes = [
     {
       applicationOperation: permissionGroupOperations.addMember,
       operationId: 'addPermissionGroupMember',
-      summary: 'Add Permission Group Member',
+      summary: 'Add permission group member',
       description: `Assign an organization member to a permission group. An existing assignment or membership in another group targeting the same workspace returns a conflict. ${AUTHORITY}`,
       tags: ['Permission Groups'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Add Permission Group Member result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The new explicit membership assignment.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
@@ -262,15 +280,15 @@ export const permissionGroupOpenApiRoutes = [
       body: documentedSchema(
         v2AddPermissionGroupMemberContract.body,
         'AddPermissionGroupMemberRequest',
-        'Add Permission Group Member request',
-        'Add Permission Group Member inputs.',
+        'Add permission group member request',
+        'The organization member to assign to this group.',
         [{ userId: 'user-123' }]
       ),
       response: documentedSchema(
         v2AddPermissionGroupMemberContract.response.schema,
         'AddPermissionGroupMemberResponse',
-        'Add Permission Group Member response',
-        'Add Permission Group Member result.',
+        'Add permission group member response',
+        'The new explicit membership assignment.',
         [
           {
             data: {
@@ -291,12 +309,12 @@ export const permissionGroupOpenApiRoutes = [
     {
       applicationOperation: permissionGroupOperations.removeMember,
       operationId: 'removePermissionGroupMember',
-      summary: 'Remove Permission Group Member',
+      summary: 'Remove permission group member',
       description: `Remove a member by user identifier. Removing the last member from an inherit group makes it govern everyone in its workspaces; a conflicting all-member group prevents the removal. ${AUTHORITY}`,
       tags: ['Permission Groups'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
-        description: 'Remove Permission Group Member result.',
+        description: 'Acknowledgement that the explicit assignment was removed.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -311,8 +329,8 @@ export const permissionGroupOpenApiRoutes = [
       response: documentedSchema(
         v2RemovePermissionGroupMemberContract.response.schema,
         'RemovePermissionGroupMemberResponse',
-        'Remove Permission Group Member response',
-        'Remove Permission Group Member result.',
+        'Remove permission group member response',
+        'Acknowledgement that the explicit assignment was removed.',
         [{ data: { userId: 'user-123', deleted: true } }]
       ),
     }
@@ -322,12 +340,12 @@ export const permissionGroupOpenApiRoutes = [
     {
       applicationOperation: permissionGroupOperations.bulkAddMembers,
       operationId: 'bulkAddPermissionGroupMembers',
-      summary: 'Bulk Add Permission Group Members',
+      summary: 'Bulk add permission group members',
       description: `Assign up to 1000 selected organization members, or the entire organization roster, atomically. Existing assignments are skipped and users outside the organization are ignored. Any overlapping membership conflict rejects the entire batch. ${AUTHORITY}`,
       tags: ['Permission Groups'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: {
-        description: 'Bulk Add Permission Group Members result.',
+        description: 'Counts of added members and existing assignments skipped.',
         headers: RATE_LIMIT_HEADERS,
       },
     },
@@ -342,15 +360,15 @@ export const permissionGroupOpenApiRoutes = [
       body: documentedSchema(
         v2BulkAddPermissionGroupMembersContract.body,
         'BulkAddPermissionGroupMembersRequest',
-        'Bulk Add Permission Group Members request',
-        'Bulk Add Permission Group Members inputs.',
+        'Bulk add permission group members request',
+        'Selected organization members or the entire current organization roster.',
         [{ userIds: ['user-123'] }]
       ),
       response: documentedSchema(
         v2BulkAddPermissionGroupMembersContract.response.schema,
         'BulkAddPermissionGroupMembersResponse',
-        'Bulk Add Permission Group Members response',
-        'Bulk Add Permission Group Members result.',
+        'Bulk add permission group members response',
+        'Counts of added members and existing assignments skipped.',
         [{ data: { added: 1, skipped: 0 } }]
       ),
     }
diff --git a/apps/sim/lib/api/contracts/v2/openapi/resources.ts b/apps/sim/lib/api/contracts/v2/openapi/resources.ts
index 8d1c1beea67..b8416de9b3a 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/resources.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/resources.ts
@@ -182,42 +182,146 @@ const BLOCK_DETAIL_EXAMPLE = {
 const CONNECTOR_TYPE_SUMMARY_EXAMPLE = {
   connectorType: 'google_drive',
   name: 'Google Drive',
-  description: 'Sync documents from a Google Drive folder.',
+  description: 'Sync documents from Google Drive',
   auth: { mode: 'oauth' },
 } as const
 
 const CONNECTOR_TYPE_EXAMPLE = {
   connectorType: 'google_drive',
   name: 'Google Drive',
-  description: 'Sync documents from a Google Drive folder.',
+  description: 'Sync documents from Google Drive',
   version: '1.0.0',
   auth: {
     mode: 'oauth',
     provider: 'google-drive',
-    requiredScopes: ['https://www.googleapis.com/auth/drive.readonly'],
+    requiredScopes: ['https://www.googleapis.com/auth/drive'],
   },
   configFields: [
+    {
+      id: 'adminEmail',
+      title: 'Crawl as',
+      type: 'short-input',
+      placeholder: 'admin@yourcompany.com',
+      required: false,
+      description:
+        'The Google Workspace user this service account acts as when fetching content for connected members.',
+    },
+    {
+      id: 'userEmails',
+      title: 'Users',
+      type: 'short-input',
+      placeholder: 'All active Google Workspace users',
+      required: false,
+      description:
+        'Optional primary email addresses, separated by commas (up to 100). Leave blank to index all active users across this Google Workspace customer.',
+      multi: true,
+    },
+    {
+      id: 'openSharing',
+      title: 'Openly shared files',
+      type: 'dropdown',
+      placeholder: 'Keep out of search',
+      required: false,
+      description:
+        'Files shared beyond named people and groups. Kept out of search by default, because a domain-wide or public share is more often an accident than an intention. Never applies to link-only shares, which stay unsearchable.',
+      options: [
+        {
+          label: 'Keep out of search',
+          id: 'none',
+        },
+        {
+          label: 'Anyone in the domain can find',
+          id: 'domain',
+        },
+        {
+          label: 'Anyone can find',
+          id: 'anyone',
+        },
+      ],
+    },
     {
       id: 'folderSelector',
-      title: 'Folder',
+      title: 'Folders',
       type: 'selector',
-      selectorKey: 'google-drive-folder',
+      placeholder: 'Select one or more folders (optional)',
+      required: false,
+      description: 'Includes files in each selected folder and its accessible subfolders.',
+      selectorKey: 'google.drive',
       mimeType: 'application/vnd.google-apps.folder',
       mode: 'basic',
       canonicalParamId: 'folderId',
-      required: true,
+      multi: true,
     },
     {
-      id: 'manualFolderId',
-      title: 'Folder ID',
+      id: 'folderId',
+      title: 'Folder IDs',
       type: 'short-input',
-      placeholder: 'Enter the folder ID',
+      placeholder: 'e.g. 1aBcDeFg…, 2cDeFgHi… (comma-separated for multiple)',
+      required: false,
+      description: 'Includes files in each selected folder and its accessible subfolders.',
       mode: 'advanced',
       canonicalParamId: 'folderId',
+      multi: true,
+    },
+    {
+      id: 'fileType',
+      title: 'File Type',
+      type: 'dropdown',
+      required: false,
+      options: [
+        {
+          label: 'All supported files',
+          id: 'all',
+        },
+        {
+          label: 'Google Docs only',
+          id: 'documents',
+        },
+        {
+          label: 'Google Sheets only',
+          id: 'spreadsheets',
+        },
+        {
+          label: 'Google Slides only',
+          id: 'presentations',
+        },
+        {
+          label: 'Plain text files only',
+          id: 'text',
+        },
+      ],
+    },
+    {
+      id: 'maxFiles',
+      title: 'Max Files',
+      type: 'short-input',
+      placeholder: 'e.g. 500 (default: unlimited)',
+      required: false,
+    },
+  ],
+  supportsIncrementalSync: false,
+  tagDefinitions: [
+    {
+      id: 'owners',
+      displayName: 'Owner',
+      fieldType: 'text',
+    },
+    {
+      id: 'fileType',
+      displayName: 'File Type',
+      fieldType: 'text',
+    },
+    {
+      id: 'lastModified',
+      displayName: 'Last Modified',
+      fieldType: 'date',
+    },
+    {
+      id: 'starred',
+      displayName: 'Starred',
+      fieldType: 'boolean',
     },
   ],
-  supportsIncrementalSync: true,
-  tagDefinitions: [{ id: 'owner', displayName: 'Owner', fieldType: 'text' }],
 } as const
 
 /**
@@ -565,11 +669,11 @@ const declaredRoutes = [
     resourceOperation('Workspaces', {
       applicationOperation: workspaceOperations.listPublic,
       operationId: 'listWorkspaces',
-      summary: 'List Workspaces',
+      summary: 'List workspaces',
       description:
-        'List active workspaces available to the calling credential with opaque cursor pagination. A personal API key or OAuth token sees accessible workspaces that permit user-held API credentials; a workspace API key sees only its bound workspace.',
+        'List active workspaces available to the calling credential. Personal API keys and OAuth tokens see accessible workspaces that permit user-held API credentials; a workspace API key sees only its bound workspace. Results use cursor pagination.',
       errors: RESOURCE_ERRORS,
-      success: { description: 'Public metadata for workspaces available to the credential.' },
+      success: { description: 'Metadata for workspaces available to the credential.' },
     }),
     {
       query: documentedSchema(
@@ -582,7 +686,7 @@ const declaredRoutes = [
         v2ListWorkspacesContract.response.schema,
         'ListWorkspacesResponse',
         'List workspaces response',
-        'Public metadata for workspaces available to the credential.',
+        'Metadata for workspaces available to the credential.',
         [{ data: [WORKSPACE_EXAMPLE], nextCursor: null }]
       ),
     }
@@ -592,10 +696,11 @@ const declaredRoutes = [
     resourceOperation('Workspaces', {
       applicationOperation: workspaceOperations.readPublicDetail,
       operationId: 'getWorkspace',
-      summary: 'Get Workspace',
-      description: 'Get metadata for an accessible workspace.',
+      summary: 'Get workspace',
+      description:
+        'Get metadata for a workspace the calling credential can access. Requires workspace read access.',
       errors: RESOURCE_ERRORS,
-      success: { description: 'Public workspace metadata.' },
+      success: { description: 'Workspace metadata.' },
     }),
     {
       query: v2GetWorkspaceContract.query,
@@ -609,7 +714,7 @@ const declaredRoutes = [
         v2GetWorkspaceContract.response.schema,
         'GetWorkspaceResponse',
         'Get workspace response',
-        'Public metadata for one workspace.',
+        'Metadata for one workspace.',
         [{ data: WORKSPACE_EXAMPLE }]
       ),
     }
@@ -619,9 +724,9 @@ const declaredRoutes = [
     resourceOperation('Workspaces', {
       applicationOperation: workspaceOperations.listPublicMembers,
       operationId: 'listWorkspaceMembers',
-      summary: 'List Workspace Members',
+      summary: 'List workspace members',
       description:
-        'List workspace members by email, including explicit grants and inherited organization admin access. Each member includes a stable user ID for member administration.',
+        'List effective workspace members, ordered by email, including explicit grants and inherited organization Admin access. Use each member’s `userId` for member administration. Requires workspace read access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'An email-ordered page of effective workspace members.' },
     }),
@@ -652,9 +757,9 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.list,
       operationId: 'listMcpServers',
-      summary: 'List MCP Servers',
+      summary: 'List MCP servers',
       description:
-        'List MCP servers registered in a workspace, excluding request-header values and OAuth secrets. Connection metadata remains at registration defaults until List MCP Server Tools performs discovery.',
+        'List external MCP servers registered in the workspace. Request-header values and OAuth secrets are omitted. Connection metadata remains at registration defaults until List MCP server tools performs discovery. Requires workspace read access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'MCP servers registered in the workspace.' },
     }),
@@ -679,9 +784,9 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.create,
       operationId: 'createMcpServer',
-      summary: 'Create MCP Server',
+      summary: 'Create MCP server',
       description:
-        'Register an external MCP server without connecting to it. A duplicate URL returns `409`; use Update MCP Server to change the existing registration. The server remains disconnected until List MCP Server Tools succeeds.',
+        'Register an external MCP server without establishing a tool connection; registration may probe its authentication method. A duplicate URL returns `409`; use Update MCP server to change the registration. It stays disconnected until List MCP server tools succeeds. Requires workspace write access.',
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The MCP server was registered.' },
     }),
@@ -716,9 +821,9 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.read,
       operationId: 'getMcpServer',
-      summary: 'Get MCP Server',
+      summary: 'Get MCP server',
       description:
-        'Get one MCP server by identifier. Request-header values and OAuth client secrets are never returned.',
+        'Get a registered external MCP server. Request-header values and OAuth client secrets are omitted. Requires workspace read access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The MCP server.' },
     }),
@@ -749,9 +854,9 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.update,
       operationId: 'updateMcpServer',
-      summary: 'Update MCP Server',
+      summary: 'Update MCP server',
       description:
-        "Update an MCP server's supplied fields. Omitted fields remain unchanged unless the field specifies otherwise. Authentication changes revoke the stored OAuth grant and reset connection metadata. Use List MCP Server Tools to reconnect.",
+        'Update an external MCP server. Omitted fields remain unchanged unless a field specifies otherwise. Authentication changes revoke its stored OAuth grant and reset connection metadata; use List MCP server tools to reconnect. The endpoint URL is immutable. Requires workspace write access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The updated MCP server.' },
     }),
@@ -784,9 +889,9 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.delete,
       operationId: 'deleteMcpServer',
-      summary: 'Delete MCP Server',
+      summary: 'Delete MCP server',
       description:
-        "Remove an MCP server and revoke its OAuth tokens. Workflows retain blocks that referenced the server's tools, but those tools can no longer be called.",
+        'Remove an external MCP server and revoke its OAuth tokens. Workflow blocks retain references to its tools, but those tools can no longer be called. Requires workspace write access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The MCP server was deleted.' },
     }),
@@ -817,10 +922,13 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.discoverTools,
       operationId: 'listMcpServerTools',
-      summary: 'List MCP Server Tools',
-      description: `Discover up to 1,000 tools within 5 MB, connect to the server, and update connection metadata. Results are unpaginated. Invalid OAuth returns \`409\` with \`MCP_SERVER_REAUTHORIZATION_REQUIRED\`; reauthorize through the browser. Unavailable servers return \`503\`. ${HEAD_MIRRORS_GET} ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List MCP server tools',
+      description: `Discover tools on an enabled external MCP server and update connection metadata. Discovery is bounded by 1,000 tools, 5 MiB, 50 upstream pages, and 60 seconds; limits or later-page failures can return an unmarked partial inventory. Results are unpaginated and may be cached; \`refresh=true\` requests fresh discovery. Invalid OAuth returns \`409\` with \`MCP_SERVER_REAUTHORIZATION_REQUIRED\`; reauthorize in the browser. Disabled servers and servers requiring a managed Credential Group connection return \`409\`; unavailable servers return \`503\`. Requires workspace read access. ${HEAD_MIRRORS_GET} ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Tools exposed by the MCP server.' },
+      success: {
+        description:
+          'Tools discovered so far. Limits or later-page failures can leave the inventory incomplete; the response has no truncation indicator or pagination.',
+      },
     }),
     {
       params: documentedSchema(
@@ -839,7 +947,7 @@ const declaredRoutes = [
         v2ListMcpServerToolsContract.response.schema,
         'ListMcpServerToolsResponse',
         'List MCP server tools response',
-        'Tools exposed by the MCP server.',
+        'Tools discovered so far. Limits or later-page failures can leave the inventory incomplete; the response has no truncation indicator or pagination.',
         [{ data: [MCP_TOOL_EXAMPLE], nextCursor: null }]
       ),
     }
@@ -849,9 +957,9 @@ const declaredRoutes = [
     resourceOperation('Skills', {
       applicationOperation: skillOperations.list,
       operationId: 'listSkills',
-      summary: 'List Skills',
+      summary: 'List skills',
       description:
-        'List workspace and built-in skills with cursor pagination. Built-in skills are read-only. The list omits skill bodies; use Get Skill to read content.',
+        'List workspace and built-in skills with cursor pagination. Built-in skills are read-only. Skill bodies are omitted; use Get skill to read content. Requires workspace read access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'Skills available in the workspace.' },
     }),
@@ -876,8 +984,8 @@ const declaredRoutes = [
     resourceOperation('Skills', {
       applicationOperation: skillOperations.create,
       operationId: 'createSkill',
-      summary: 'Create Skill',
-      description: `Create one skill in a workspace. Its kebab-case name must be unique and cannot be reserved by a built-in skill. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create skill',
+      description: `Create a workspace skill with a unique kebab-case name that is not reserved by a built-in skill. Requires workspace write access. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The skill was created.' },
     }),
@@ -911,9 +1019,9 @@ const declaredRoutes = [
     resourceOperation('Skills', {
       applicationOperation: skillOperations.read,
       operationId: 'getSkill',
-      summary: 'Get Skill',
+      summary: 'Get skill',
       description:
-        'Get one workspace or built-in skill, including its full content. Built-in skills are marked read-only.',
+        'Get a workspace or built-in skill, including its full instructions. Built-in skills are read-only. Requires workspace read access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The skill.' },
     }),
@@ -944,8 +1052,8 @@ const declaredRoutes = [
     resourceOperation('Skills', {
       applicationOperation: skillOperations.update,
       operationId: 'updateSkill',
-      summary: 'Update Skill',
-      description: `Update a workspace skill. Omitted fields remain unchanged. Built-in skills are read-only. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update skill',
+      description: `Update a workspace skill. Omitted fields remain unchanged. Requires skill editor or workspace Admin access; workspace write access alone does not grant editor access. Built-in skills cannot be changed. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The updated skill.' },
     }),
@@ -978,8 +1086,8 @@ const declaredRoutes = [
     resourceOperation('Skills', {
       applicationOperation: skillOperations.delete,
       operationId: 'deleteSkill',
-      summary: 'Delete Skill',
-      description: `Delete a workspace skill. Built-in skills are read-only and cannot be deleted. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Delete skill',
+      description: `Delete a workspace skill. Requires skill editor or workspace Admin access. Built-in skills cannot be deleted. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The skill was deleted.' },
     }),
@@ -1010,8 +1118,9 @@ const declaredRoutes = [
     resourceOperation('Skills', {
       applicationOperation: skillOperations.listEditors,
       operationId: 'listSkillEditors',
-      summary: 'List Skill Editors',
-      description: 'List skill editors and workspace administrators with cursor pagination.',
+      summary: 'List skill editors',
+      description:
+        'List explicit skill editors and workspace Admins with cursor pagination. Built-in skills return an empty list. Requires workspace read access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'Users who can edit the skill.' },
     }),
@@ -1032,7 +1141,7 @@ const declaredRoutes = [
         v2ListSkillEditorsContract.response.schema,
         'ListSkillEditorsResponse',
         'List skill editors response',
-        'Public identity fields for users who can edit the skill.',
+        'Identity fields for users who can edit the skill.',
         [{ data: [SKILL_EDITOR_EXAMPLE], nextCursor: null }]
       ),
     }
@@ -1042,8 +1151,8 @@ const declaredRoutes = [
     resourceOperation('Skills', {
       applicationOperation: skillOperations.grantEditor,
       operationId: 'grantSkillEditor',
-      summary: 'Grant Skill Editor',
-      description: `Grant skill editor access to a workspace member by email. Requires an existing editor or workspace admin; admins already have access and cannot receive explicit grants. Existing grants return \`200\`; new grants return \`201\`. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Grant skill editor',
+      description: `Grant skill editor access to a current workspace member by email. Requires an existing skill editor or workspace Admin. Workspace Admins already have derived access and cannot receive explicit grants. Existing grants return \`200\`; new grants return \`201\`. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: {
         byStatus: {
@@ -1071,7 +1180,7 @@ const declaredRoutes = [
         v2GrantSkillEditorContract.response.schema,
         'GrantSkillEditorResponse',
         'Grant skill editor response',
-        'Public identity fields for the editor.',
+        'Identity fields for the editor.',
         [{ data: SKILL_EDITOR_EXAMPLE }]
       ),
     }
@@ -1081,8 +1190,8 @@ const declaredRoutes = [
     resourceOperation('Skills', {
       applicationOperation: skillOperations.revokeEditor,
       operationId: 'revokeSkillEditor',
-      summary: 'Revoke Skill Editor',
-      description: `Revoke an explicit editor grant by email. The caller must already be a skill editor or workspace administrator. Workspace administrators have derived access that cannot be revoked. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Revoke skill editor',
+      description: `Revoke an explicit skill editor grant by email. Requires an existing skill editor or workspace Admin. Workspace Admins have derived access that cannot be revoked. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The explicit editor grant was revoked.' },
     }),
@@ -1113,8 +1222,9 @@ const declaredRoutes = [
     resourceOperation('Custom Tools', {
       applicationOperation: customToolOperations.list,
       operationId: 'listCustomTools',
-      summary: 'List Custom Tools',
-      description: 'List code-backed custom tools in a workspace with cursor pagination.',
+      summary: 'List custom tools',
+      description:
+        'List code-backed custom tools in the workspace with cursor pagination. Each entry includes its declaration and implementation. Requires workspace read access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'Custom tools defined in the workspace.' },
     }),
@@ -1139,9 +1249,9 @@ const declaredRoutes = [
     resourceOperation('Custom Tools', {
       applicationOperation: customToolOperations.create,
       operationId: 'createCustomTool',
-      summary: 'Create Custom Tool',
+      summary: 'Create custom tool',
       description:
-        'Create a code-backed custom tool in a workspace. Its title must be unique because tools resolve by title at call time.',
+        'Create a code-backed custom tool. Its title must be unique within the workspace because tools resolve by title at call time. Requires workspace write access.',
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The custom tool was created.' },
     }),
@@ -1175,8 +1285,9 @@ const declaredRoutes = [
     resourceOperation('Custom Tools', {
       applicationOperation: customToolOperations.read,
       operationId: 'getCustomTool',
-      summary: 'Get Custom Tool',
-      description: 'Get one custom tool by identifier, scoped to its workspace.',
+      summary: 'Get custom tool',
+      description:
+        'Get a custom tool’s declaration and code by identifier, scoped to its workspace. Requires workspace read access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The custom tool.' },
     }),
@@ -1207,9 +1318,9 @@ const declaredRoutes = [
     resourceOperation('Custom Tools', {
       applicationOperation: customToolOperations.update,
       operationId: 'updateCustomTool',
-      summary: 'Update Custom Tool',
+      summary: 'Update custom tool',
       description:
-        'Update a custom tool. Omitted fields remain unchanged; titles must remain unique within the workspace.',
+        'Update a custom tool. Omitted fields remain unchanged; supplied schemas and code replace the stored versions. Titles must remain unique within the workspace. Requires workspace write access.',
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The updated custom tool.' },
     }),
@@ -1242,9 +1353,9 @@ const declaredRoutes = [
     resourceOperation('Custom Tools', {
       applicationOperation: customToolOperations.delete,
       operationId: 'deleteCustomTool',
-      summary: 'Delete Custom Tool',
+      summary: 'Delete custom tool',
       description:
-        'Delete a custom tool. Agent blocks retain their configuration but can no longer call the deleted tool.',
+        'Delete a custom tool. Agent blocks retain their configuration but can no longer call the deleted tool. Requires workspace write access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The custom tool was deleted.' },
     }),
@@ -1275,9 +1386,9 @@ const declaredRoutes = [
     resourceOperation('Sandboxes', {
       applicationOperation: sandboxOperations.list,
       operationId: 'listSandboxes',
-      summary: 'List Sandboxes',
+      summary: 'List sandboxes',
       description:
-        'List reusable dependency environments for Function blocks, including language packages, managed CLIs, and system packages. Sandboxes remain visible after a plan downgrade.',
+        'List reusable dependency environments for Function blocks, including language packages, managed CLIs, and system packages. Requires workspace read access. Existing sandboxes remain visible after a plan downgrade.',
       errors: RESOURCE_ERRORS,
       success: { description: 'Sandboxes defined in the workspace.' },
     }),
@@ -1302,8 +1413,8 @@ const declaredRoutes = [
     resourceOperation('Sandboxes', {
       applicationOperation: sandboxOperations.create,
       operationId: 'createSandbox',
-      summary: 'Create Sandbox',
-      description: `Create a uniquely named dependency environment. If a build is needed, track readiness with \`buildStatus\`; null means no build is required. Invalid dependencies return \`400\` with field details. Requires workspace admin access on Max or Enterprise. Creates and updates share a rate limit; respect \`Retry-After\`. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create sandbox',
+      description: `Create a uniquely named dependency environment. Requires workspace Admin access and a configured remote Function runtime. With billing enabled, Max or Enterprise is required unless deployment entitlement overrides it; billing-disabled deployments require sandbox entitlement. Poll Get sandbox for \`buildStatus\`; \`null\` means no image build is needed. Invalid dependencies return \`400\` with field details. Creates and updates share a rate limit; respect \`Retry-After\`. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
         description:
@@ -1341,9 +1452,9 @@ const declaredRoutes = [
     resourceOperation('Sandboxes', {
       applicationOperation: sandboxOperations.read,
       operationId: 'getSandbox',
-      summary: 'Get Sandbox',
+      summary: 'Get sandbox',
       description:
-        'Get one sandbox by identifier, scoped to its workspace, including its current build state and any build failure.',
+        'Get a sandbox’s dependency configuration, current build state, and any build failure. Requires workspace read access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The sandbox.' },
     }),
@@ -1374,8 +1485,8 @@ const declaredRoutes = [
     resourceOperation('Sandboxes', {
       applicationOperation: sandboxOperations.update,
       operationId: 'updateSandbox',
-      summary: 'Update Sandbox',
-      description: `Update a sandbox, preserving omitted fields and replacing supplied lists. Dependency changes may start a build; resending a failed specification retries its build. \`buildStatus: null\` means no build is required. Requires workspace admin access on Max or Enterprise. Creates and updates share a rate limit; respect \`Retry-After\`. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update sandbox',
+      description: `Update a sandbox; omitted fields stay unchanged and supplied lists replace their contents. Dependency changes may start a build; resending a failed specification retries it. \`buildStatus: null\` means no image build is needed. Requires workspace Admin access and a configured remote Function runtime. With billing enabled, Max or Enterprise is required unless deployment entitlement overrides it; billing-disabled deployments require sandbox entitlement. Creates and updates share a rate limit; respect \`Retry-After\`. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The updated sandbox.' },
     }),
@@ -1417,8 +1528,8 @@ const declaredRoutes = [
     resourceOperation('Sandboxes', {
       applicationOperation: sandboxOperations.delete,
       operationId: 'deleteSandbox',
-      summary: 'Delete Sandbox',
-      description: `Delete a sandbox. Function blocks using it fail until reconfigured. Requires workspace admin access on Max or Enterprise. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Delete sandbox',
+      description: `Delete a sandbox. Function blocks using it fail until reconfigured. Requires workspace Admin access and sandbox entitlement: with billing enabled, Max or Enterprise is required unless deployment entitlement overrides it; billing-disabled deployments require sandbox entitlement. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The sandbox was deleted.' },
     }),
@@ -1449,9 +1560,9 @@ const declaredRoutes = [
     resourceOperation('Credentials', {
       applicationOperation: credentialOperations.listConnections,
       operationId: 'listCredentials',
-      summary: 'List Credentials',
+      summary: 'List credentials',
       description:
-        'List OAuth and service-account connections visible to the caller. Secret material is never returned.',
+        'List OAuth and service-account connections visible to the caller. Requires workspace read access. Stored tokens, keys, and service-account payloads are omitted.',
       errors: RESOURCE_ERRORS,
       success: { description: 'Credentials visible to the caller.' },
     }),
@@ -1476,7 +1587,7 @@ const declaredRoutes = [
     resourceOperation('Credentials', {
       applicationOperation: credentialOperations.listProviders,
       operationId: 'listCredentialProviders',
-      summary: 'List Credential Providers',
+      summary: 'List credential providers',
       description: `List OAuth and service-account connection methods and their availability. OAuth options provide provider IDs for browser connections; service-account methods declare required fields and write-only secrets. Supports provider-name search. ${FULL_SET_LIST}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'Credential provider catalog with caller-specific availability.' },
@@ -1507,8 +1618,8 @@ const declaredRoutes = [
     resourceOperation('Credentials', {
       applicationOperation: credentialOperations.createServiceAccount,
       operationId: 'createServiceAccountCredential',
-      summary: 'Create Service-Account Credential',
-      description: `Verify and store a service-account credential using the fields from List Credential Providers, encoded as a JSON object string in \`credentials\`. Secrets are never returned. A matching source returns the existing credential with \`200\`; creation returns \`201\`. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create service-account credential',
+      description: `Verify and store a service-account credential. Use the fields from List credential providers, encoded as a JSON object string in \`credentials\`. Requires workspace write access. A matching source returns the existing credential with \`200\`; creation returns \`201\`. Stored secrets are omitted from the response. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
         byStatus: {
@@ -1549,8 +1660,8 @@ const declaredRoutes = [
     resourceOperation('Credentials', {
       applicationOperation: credentialOperations.createConnection,
       operationId: 'createCredentialConnection',
-      summary: 'Create Credential Connection',
-      description: `Create a short-lived browser URL for connecting an OAuth provider or reconnecting an existing OAuth credential. Open the URL, sign in as the authenticated user, complete provider authorization, then refresh the credentials list. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create credential connection',
+      description: `Create a short-lived browser URL to connect an OAuth provider or reconnect a credential. Requires workspace write access; reconnecting also requires credential Admin access. Open the URL, sign in as the acting user, complete provider authorization, then refresh List credentials. QuickBooks requires caller-managed \`oauthClientConfig\` for either flow. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'A short-lived browser authorization URL.' },
     }),
@@ -1560,7 +1671,22 @@ const declaredRoutes = [
         v2CreateCredentialConnectionContract.body,
         'CreateCredentialConnectionBody',
         'Create credential connection body',
-        'For a new connection, provide providerId and displayName. For a reconnect, provide only credentialId; the existing display name is preserved.'
+        'Provide workspaceId for every flow. For a new connection, send providerId and displayName; for a reconnect, send credentialId and retain the existing name. QuickBooks also requires oauthClientConfig for either flow; omit it for other providers.',
+        [
+          { workspaceId: WORKSPACE_ID, providerId: 'slack', displayName: 'Support Slack' },
+          { workspaceId: WORKSPACE_ID, credentialId: CREDENTIAL_EXAMPLE.id },
+          {
+            workspaceId: WORKSPACE_ID,
+            providerId: 'quickbooks',
+            displayName: 'Accounting',
+            oauthClientConfig: {
+              clientId: 'YOUR_INTUIT_CLIENT_ID',
+              clientSecret: 'YOUR_INTUIT_CLIENT_SECRET',
+              environment: 'sandbox',
+              webhookVerifierToken: 'YOUR_WEBHOOK_VERIFIER_TOKEN',
+            },
+          },
+        ]
       ),
       response: documentedSchema(
         v2CreateCredentialConnectionContract.response.schema,
@@ -1576,8 +1702,8 @@ const declaredRoutes = [
     resourceOperation('Credentials', {
       applicationOperation: credentialOperations.delete,
       operationId: 'deleteCredential',
-      summary: 'Disconnect Credential',
-      description: `Disconnect an OAuth or service-account credential and clear its stored workflow, deployment, paused-run, knowledge-connector, and webhook references. Credential admin access is required. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Disconnect credential',
+      description: `Disconnect an OAuth or service-account credential and clear its stored workflow, deployment, paused-run, knowledge-connector, and webhook references. Requires credential Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The credential was disconnected.' },
     }),
@@ -1608,8 +1734,8 @@ const declaredRoutes = [
     resourceOperation('Secrets', {
       applicationOperation: secretOperations.list,
       operationId: 'listSecrets',
-      summary: 'List Secrets',
-      description: `List workspace and caller-owned personal secrets with cursor pagination. Only workspace secrets marked \`unredacted\` include values; all other entries contain metadata only. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List secrets',
+      description: `List workspace secrets visible to the caller and caller-owned personal secrets. Only workspace secrets marked \`unredacted\` can include values; every other entry contains metadata only. Requires workspace read access. Personal secrets belong to the caller across workspaces. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'Secret metadata visible to the caller.' },
     }),
@@ -1634,8 +1760,8 @@ const declaredRoutes = [
     resourceOperation('Secrets', {
       applicationOperation: secretOperations.set,
       operationId: 'setSecret',
-      summary: 'Set Secret',
-      description: `Create or replace a workspace or personal secret without returning its value. For existing workspace secrets, omit \`value\` to update metadata only; this returns \`404\` if absent. Personal secrets always require \`value\`. List Secrets can reveal workspace values marked \`unredacted\`. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Set secret',
+      description: `Create or replace a workspace or caller-owned personal secret. New workspace secrets require workspace write access; existing ones require workspace Admin or secret Admin access. Omit \`value\` to update an existing workspace secret’s metadata; a missing secret returns \`404\`. Personal secrets always require \`value\`. This operation returns metadata only; List secrets can reveal permitted workspace values marked \`unredacted\`. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: {
         byStatus: {
@@ -1687,8 +1813,8 @@ const declaredRoutes = [
     resourceOperation('Secrets', {
       applicationOperation: secretOperations.delete,
       operationId: 'deleteSecret',
-      summary: 'Delete Secret',
-      description: `Delete a workspace or caller-owned personal secret without reading or returning its stored value. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Delete secret',
+      description: `Delete a workspace or caller-owned personal secret without returning its value. Workspace secrets require workspace Admin or secret Admin access. Deleting a personal secret removes it for the caller across all workspaces. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The secret was deleted.' },
     }),
@@ -1727,9 +1853,9 @@ const declaredRoutes = [
     resourceOperation('Meta', {
       applicationOperation: v2MetaOperations.read,
       operationId: 'getApiMeta',
-      summary: 'Get API Capabilities',
+      summary: 'Get API status',
       description:
-        'Get whether v2 is available, what kind of API credential is calling, and when it expires. Requires a valid API key or OAuth access token.',
+        'Get the calling credential’s type and expiry. Requires a valid API key or OAuth access token. `v2Enabled` is true whenever this endpoint is served; the response does not enumerate resource permissions.',
       errors: META_ERRORS,
       success: { description: 'Availability and lifecycle facts about the calling credential.' },
     }),
@@ -1738,7 +1864,7 @@ const declaredRoutes = [
       response: documentedSchema(
         v2GetMetaContract.response.schema,
         'GetApiMetaResponse',
-        'API capabilities response',
+        'API status response',
         'API availability, credential type, and expiry for the caller.',
         [{ data: { v2Enabled: true, keyType: 'personal', expiresAt: null } }]
       ),
@@ -1749,10 +1875,10 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.listWorkflowDeployments,
       operationId: 'listWorkflowMcpServers',
-      summary: 'List Workflow MCP Servers',
-      description: `List MCP servers that expose deployed workflows to external clients. Use List MCP Servers for external servers Sim calls. Tool names share a 2,000-name page limit; inspect \`toolNamesTruncated\` and use List Workflow MCP Tools for a server's inventory. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List workflow MCP servers',
+      description: `List MCP servers that expose deployed workflows to external clients. Use List MCP servers for external servers Sim calls. Requires workspace read access. Tool names share a 2,000-name page limit; when \`toolNamesTruncated\` is true, \`toolCount\` and \`toolNames\` may be incomplete. Use List workflow MCP tools for a server’s bounded inventory. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
-      success: { description: 'A page of published MCP servers.' },
+      success: { description: 'A page of workflow MCP servers.' },
     }),
     {
       query: v2ListWorkflowMcpServersContract.query,
@@ -1760,7 +1886,7 @@ const declaredRoutes = [
         v2ListWorkflowMcpServersContract.response.schema,
         'ListWorkflowMcpServersResponse',
         'List workflow MCP servers response',
-        'A cursor-paginated page of published MCP servers.',
+        'A page of workflow MCP servers with bounded tool-name inventories.',
         [{ data: [WORKFLOW_MCP_SERVER_LIST_EXAMPLE], nextCursor: null, toolNamesTruncated: false }]
       ),
     }
@@ -1770,10 +1896,10 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.createWorkflowDeploymentServer,
       operationId: 'createWorkflowMcpServer',
-      summary: 'Create Workflow MCP Server',
-      description: `Create an MCP server that exposes deployed workflows as tools. Every supplied workflow must already be deployed. With \`isPublic: true\`, anyone with the server URL can execute its workflows without a Sim API key. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create workflow MCP server',
+      description: `Create an MCP server exposing deployed workflows as tools. Every supplied workflow must already be deployed. With \`isPublic: true\`, anyone holding the server URL can execute its workflows without a Sim API key. Requires workspace Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'The published MCP server.' },
+      success: { description: 'The workflow MCP server.' },
     }),
     {
       query: v2CreateWorkflowMcpServerContract.query,
@@ -1782,7 +1908,7 @@ const declaredRoutes = [
         v2CreateWorkflowMcpServerContract.response.schema,
         'CreateWorkflowMcpServerResponse',
         'Create workflow MCP server response',
-        'The published MCP server.',
+        'The workflow MCP server.',
         [{ data: WORKFLOW_MCP_SERVER_EXAMPLE }]
       ),
     }
@@ -1792,8 +1918,8 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.readWorkflowDeploymentServer,
       operationId: 'getWorkflowMcpServer',
-      summary: 'Get Workflow MCP Server',
-      description: `Get a published workflow MCP server's metadata and client endpoint. Use List Workflow MCP Tools for its tool inventory. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get workflow MCP server',
+      description: `Get a workflow MCP server’s metadata and client endpoint. Use List workflow MCP tools for its inventory. Requires workspace read access. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The MCP server.' },
     }),
@@ -1804,7 +1930,7 @@ const declaredRoutes = [
         v2GetWorkflowMcpServerContract.response.schema,
         'GetWorkflowMcpServerResponse',
         'Get workflow MCP server response',
-        'A single published MCP server.',
+        'One workflow MCP server and its client endpoint.',
         [{ data: WORKFLOW_MCP_SERVER_EXAMPLE }]
       ),
     }
@@ -1814,11 +1940,13 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.listWorkflowDeploymentTools,
       operationId: 'listWorkflowMcpTools',
-      summary: 'List Workflow MCP Tools',
-      description: `List published tools ordered by name, including the \`workflowId\` used to delete each registration. Undeploying a workflow makes its registrations \`inactive\`; redeploying reactivates them. Results are capped at 2,000 tools: \`nextCursor\` is always null, and \`truncated\` marks an incomplete inventory that cannot be paginated. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List workflow MCP tools',
+      description: `List tool registrations ordered by name, including the \`workflowId\` used to remove each registration. Undeploying a workflow makes its registrations \`inactive\`; redeploying reactivates them. Results are capped at 2,000 tools: \`nextCursor\` is always null, and \`truncated\` marks an incomplete inventory that cannot be paginated. Requires workspace read access. ${WORKSPACE_API_KEY_DENIED}`,
 
       errors: RESOURCE_ERRORS,
-      success: { description: 'The tools this server publishes.' },
+      success: {
+        description: 'Tool registrations on this server, including inactive registrations.',
+      },
     }),
     {
       query: v2ListWorkflowMcpToolsContract.query,
@@ -1827,7 +1955,7 @@ const declaredRoutes = [
         v2ListWorkflowMcpToolsContract.response.schema,
         'ListWorkflowMcpToolsResponse',
         'List workflow MCP tools response',
-        'The tools a published MCP server exposes.',
+        'A bounded inventory of tool registrations on the workflow MCP server.',
         [
           {
             data: [omitUpdated(WORKFLOW_MCP_TOOL_EXAMPLE)],
@@ -1843,8 +1971,8 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.updateWorkflowDeploymentServer,
       operationId: 'updateWorkflowMcpServer',
-      summary: 'Update Workflow MCP Server',
-      description: `Update a workflow MCP server's name, description, or public access. Omitted fields remain unchanged; \`description: null\` clears the description. Publish or unpublish tools separately. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update workflow MCP server',
+      description: `Update a workflow MCP server’s name, description, or public access. Omitted fields stay unchanged; \`description: null\` clears the description. With \`isPublic: true\`, anyone holding its URL can execute its tools without a Sim API key. Deploy or undeploy tools separately. Requires workspace Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The updated MCP server.' },
     }),
@@ -1866,10 +1994,10 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.deleteWorkflowDeploymentServer,
       operationId: 'deleteWorkflowMcpServer',
-      summary: 'Delete Workflow MCP Server',
-      description: `Delete a workflow MCP server and stop serving its tools. The underlying workflows remain deployed and executable through the workflow API. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Delete workflow MCP server',
+      description: `Delete a workflow MCP server and stop serving its tools. Its workflows remain deployed and executable through the workflow API. Requires workspace Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'The MCP server was unpublished.' },
+      success: { description: 'The workflow MCP server was deleted.' },
     }),
     {
       query: v2DeleteWorkflowMcpServerContract.query,
@@ -1878,7 +2006,7 @@ const declaredRoutes = [
         v2DeleteWorkflowMcpServerContract.response.schema,
         'DeleteWorkflowMcpServerResponse',
         'Delete workflow MCP server response',
-        'Acknowledgement that the MCP server was unpublished.',
+        'Acknowledgement that the workflow MCP server was deleted.',
         [{ data: { id: WORKFLOW_MCP_SERVER_EXAMPLE.id, deleted: true } }]
       ),
     }
@@ -1888,10 +2016,10 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.deployWorkflowTool,
       operationId: 'deployWorkflowMcpTool',
-      summary: 'Publish Workflow As MCP Tool',
-      description: `Publish a deployed workflow as an MCP tool using its deployed input schema. Each server has at most one tool per workflow; repeating the call replaces that tool and returns \`200\` with \`updated: true\`. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Deploy workflow as MCP tool',
+      description: `Deploy a workflow as an MCP tool using its deployed input schema. The workflow must already be deployed. Each server has at most one tool per workflow; repeating the call replaces the tool and returns \`200\` with \`updated: true\`. Requires workspace Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'The published tool.' },
+      success: { description: 'The deployed MCP tool registration.' },
     }),
     {
       query: v2DeployWorkflowMcpToolContract.query,
@@ -1900,8 +2028,8 @@ const declaredRoutes = [
       response: documentedSchema(
         v2DeployWorkflowMcpToolContract.response.schema,
         'DeployWorkflowMcpToolResponse',
-        'Publish workflow as MCP tool response',
-        'The published tool.',
+        'Deploy workflow as MCP tool response',
+        'The deployed MCP tool registration.',
         [{ data: WORKFLOW_MCP_TOOL_EXAMPLE }]
       ),
     }
@@ -1911,8 +2039,8 @@ const declaredRoutes = [
     resourceOperation('MCP Servers', {
       applicationOperation: mcpServerOperations.undeployWorkflowTool,
       operationId: 'undeployWorkflowMcpTool',
-      summary: 'Unpublish Workflow MCP Tool',
-      description: `Unpublish an MCP tool by its workflow ID. The workflow's API deployment remains active. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Undeploy workflow MCP tool',
+      description: `Remove an MCP tool registration by its workflow ID. The workflow’s API deployment remains active. Requires workspace Admin access. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The tool was removed.' },
     }),
@@ -1922,7 +2050,7 @@ const declaredRoutes = [
       response: documentedSchema(
         v2UndeployWorkflowMcpToolContract.response.schema,
         'UndeployWorkflowMcpToolResponse',
-        'Unpublish workflow MCP tool response',
+        'Undeploy workflow MCP tool response',
         'Acknowledgement that the tool was removed.',
         [
           {
@@ -1942,8 +2070,8 @@ const declaredRoutes = [
     resourceOperation('Credentials', {
       applicationOperation: credentialOperations.update,
       operationId: 'updateCredential',
-      summary: 'Update Credential',
-      description: `Rename a service-account credential or rotate its secret fields, preserving omitted values and the credential ID. Requires credential admin access. Provider rejection preserves the old secret and returns \`400\` with \`providerErrorCode\`; outages return \`503\`. Fields for a different credential type return \`400\`. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update credential',
+      description: `Rename an OAuth or service-account credential, change its description, or rotate a service-account secret. Omitted metadata remains unchanged. Rotation requires the provider’s required secret fields to be resubmitted; it replaces the verified secret while retaining the credential ID. Requires credential Admin access. Provider rejection keeps the old secret and returns \`400\` with \`providerErrorCode\`; outages return \`503\`. Secret fields sent for an OAuth credential return \`400\`. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The updated credential without secret material.' },
     }),
@@ -1964,8 +2092,15 @@ const declaredRoutes = [
         v2UpdateCredentialContract.body,
         'UpdateCredentialRequest',
         'Update credential request',
-        'Replacement display metadata and the write-only fields declared by provider discovery.',
-        [{ clientSecret: 'YOUR_ROTATED_CLIENT_SECRET' }]
+        'Metadata fields to change, or the complete required fields for a service-account secret rotation. Use List credential providers for the selected provider’s fields.',
+        [
+          { displayName: 'Billing automation' },
+          {
+            clientId: 'YOUR_CLIENT_ID',
+            clientSecret: 'YOUR_ROTATED_CLIENT_SECRET',
+            orgId: 'YOUR_ACCOUNT_ID',
+          },
+        ]
       ),
       response: documentedSchema(
         v2UpdateCredentialContract.response.schema,
@@ -1981,9 +2116,9 @@ const declaredRoutes = [
     resourceOperation('Catalog', {
       applicationOperation: catalogOperations.listBlocks,
       operationId: 'listBlocks',
-      summary: 'List Blocks',
+      summary: 'List blocks',
       description:
-        'List built-in and workspace-deployed blocks visible to the caller. Integration allowlists and preview visibility restrict results. Use `capability=trigger` for workflow starters and Get Block or Get Tool to resolve operation and tool IDs.',
+        'List built-in and workspace-deployed blocks visible to the caller. Integration allowlists and preview visibility restrict results. Use `capability=trigger` for workflow starters and Get block or Get tool to resolve operation and tool IDs.',
       errors: RESOURCE_ERRORS,
       success: { description: 'A page of blocks available in the workspace.' },
     }),
@@ -2008,7 +2143,7 @@ const declaredRoutes = [
     resourceOperation('Catalog', {
       applicationOperation: catalogOperations.readBlock,
       operationId: 'getBlock',
-      summary: 'Get Block',
+      summary: 'Get block',
       description:
         "Get a block's fields, conditions, operations, tool schemas, and triggers. Unversioned types resolve to the newest visible version; the returned `id` identifies that version. Hidden or missing blocks return `404`.",
       errors: RESOURCE_ERRORS,
@@ -2041,9 +2176,9 @@ const declaredRoutes = [
     resourceOperation('Catalog', {
       applicationOperation: catalogOperations.listTools,
       operationId: 'listTools',
-      summary: 'List Tools',
+      summary: 'List tools',
       description:
-        "List built-in tools exposed by blocks visible to the caller. Use List MCP Server Tools for an external server's tools and List Custom Tools for workspace code-backed tools.",
+        "List built-in tools exposed by blocks visible to the caller. Use List MCP server tools for an external server's tools and List custom tools for workspace code-backed tools.",
       errors: RESOURCE_ERRORS,
       success: { description: 'A page of built-in tools available in the workspace.' },
     }),
@@ -2068,9 +2203,9 @@ const declaredRoutes = [
     resourceOperation('Catalog', {
       applicationOperation: catalogOperations.readTool,
       operationId: 'getTool',
-      summary: 'Get Tool',
+      summary: 'Get tool',
       description:
-        "Get a built-in tool's parameters and outputs. Registered IDs resolve exactly; other names resolve to the newest family version. The returned `id` identifies the resolved tool. Hidden or missing tools return `404`.",
+        'Get a built-in tool’s parameters and outputs. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The returned `id` identifies that tool. Hidden or missing tools return `404`. Requires workspace read access.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The tool.' },
     }),
@@ -2101,8 +2236,8 @@ const declaredRoutes = [
     resourceOperation('Catalog', {
       applicationOperation: toolExecutionOperations.execute,
       operationId: 'executeTool',
-      summary: 'Run Tool',
-      description: `Run a built-in tool using published parameter IDs. Sim resolves \`credentialId\`, hosted keys, and whole-value \`{{VAR_NAME}}\` references for \`user-only\` parameters; other values pass through verbatim. Third-party refusal returns \`200\` with \`status: "failed"\`; the error envelope covers API failures. Hidden or missing tools return \`404\`; disallowed integrations return \`403\` with \`error.details.code: INTEGRATION_NOT_ALLOWED\`. Hosted-key use is billed to the workspace; a call that would use a hosted key from a workspace over its usage or billing limits returns \`402\`. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Run tool',
+      description: `Run a built-in tool using published parameter IDs. Requires workspace read access. Sim resolves \`credentialId\`, hosted keys, and whole-value \`{{VAR_NAME}}\` references in \`user-only\` parameters; other values pass through unchanged. Send connected credentials as top-level \`credentialId\`, not inside \`input\`. Third-party refusal returns \`200\` with \`status: "failed"\`; API failures use the error envelope. Hidden or missing tools return \`404\`; disallowed integrations return \`403\` with \`error.details.code: INTEGRATION_NOT_ALLOWED\`. Hosted-key usage is billed to the workspace. A call that would use a hosted key returns \`402\` when the workspace exceeds usage or billing limits. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'UsageLimitExceeded'],
       success: { description: 'The outcome of the tool call.' },
     }),
@@ -2118,7 +2253,7 @@ const declaredRoutes = [
         v2ExecuteToolContract.body,
         'ExecuteToolRequest',
         'Run tool request',
-        'Workspace, arguments, and the credential to authenticate with.',
+        'Workspace, accepted tool arguments, and optional connected credential. Hidden fields and credential aliases inside input are rejected.',
         [
           {
             workspaceId: WORKSPACE_ID,
@@ -2141,8 +2276,9 @@ const declaredRoutes = [
     resourceOperation('Catalog', {
       applicationOperation: catalogOperations.listConnectorTypes,
       operationId: 'listConnectorTypes',
-      summary: 'List Connector Types',
-      description: `List knowledge-base connector types with opaque cursors, defaulting to 25 summaries per page: identifier, name, description, and auth mode. \`detail=full\` adds accepted source configuration fields. Fields with \`multi: true\` accept \`string[]\` instead of \`string\`. A \`canonicalParamId\` pairs a picker with manual entry for the same configuration key: send exactly one value, keyed by \`canonicalParamId\` rather than the field’s \`id\`.`,
+      summary: 'List connector types',
+      description:
+        'List connector types from the deployment’s knowledge-base connector registry. Requires workspace read access and Knowledge Base access; workspace integration allowlists and revealed preview blocks do not filter this catalog. Results default to 25 summaries per page. `detail=full` adds configuration fields. Fields with `multi: true` accept `string[]`. For picker/manual-entry pairs, send one value under `canonicalParamId`, not the field’s `id`.',
       errors: RESOURCE_ERRORS,
       success: { description: 'One page of the connector-type catalog.' },
     }),
@@ -2180,7 +2316,7 @@ const routes = declaredRoutes.map(withRequestBodyErrors)
 export const resourcesOpenApiDocument = defineOpenApiDocument({
   output: 'apps/docs/openapi-v2-resources.json',
   info: {
-    title: 'Sim API v2 — Resources',
+    title: 'Sim API v2 — resources',
     description:
       'Version 2 of the Sim REST API for workspace metadata, members, MCP servers, skills, custom tools, sandboxes, credentials, write-only secrets, organization permission groups, and the block, tool, and connector-type catalogs.',
     version: '2.0.0',
@@ -2211,7 +2347,7 @@ export const resourcesOpenApiDocument = defineOpenApiDocument({
     },
     {
       name: 'Meta',
-      description: 'Discover what the calling API credential can reach.',
+      description: 'Read API availability and the calling credential’s type and expiry.',
     },
     {
       name: 'Workspaces',
@@ -2241,11 +2377,12 @@ export const resourcesOpenApiDocument = defineOpenApiDocument({
     },
     {
       name: 'Secrets',
-      description: 'Set and manage write-only workspace and personal secret values.',
+      description:
+        'Manage workspace and personal secrets; writes return metadata, and visible workspace values may appear in lists.',
     },
     {
       name: 'Catalog',
-      description: 'Discover the blocks, tools, and connector types this workspace can build with.',
+      description: 'Inspect workflow blocks, built-in tools, and knowledge-base connector types.',
     },
   ],
   security: V2_AUTH_SECURITY,
diff --git a/apps/sim/lib/api/contracts/v2/openapi/shared.ts b/apps/sim/lib/api/contracts/v2/openapi/shared.ts
index ec711673713..e2b80cd5536 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/shared.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/shared.ts
@@ -10,9 +10,8 @@ import type {
 
 interface ErrorResponseOptions {
   /**
-   * The `message` a caller actually receives for this status. Every one below is a literal
-   * the runtime emits — the generic path for that status, not a domain's phrasing of it —
-   * so the reference can be read as the response rather than as an illustration.
+   * Representative response message. Fixed surface errors use their runtime
+   * literal; domain errors use an illustrative message because wording varies.
    */
   message: string
   /** `error.details`, for the statuses that populate it. Omitted where none is sent. */
@@ -124,12 +123,7 @@ export const ERROR_RESPONSES = {
     message: 'Not found',
   }),
   Conflict: errorResponse(409, 'The request conflicts with current resource state.', {
-    /**
-     * The workflows phrasing, which is the default because that document does not override
-     * it. Nothing in the response layer supplies a 409 message, so every other document
-     * carrying this status names its own through {@link withErrorExamples}.
-     */
-    message: 'Webhook path already in use',
+    message: 'The request conflicts with current resource state',
   }),
   RunIdConflict: errorResponse(
     409,
@@ -203,7 +197,7 @@ export const ERROR_RESPONSES = {
   }),
   ServiceUnavailable: errorResponse(
     503,
-    'A required service is temporarily unavailable. `Retry-After` carries the seconds to wait; treat it as a floor and add jitter. The header is omitted when `error.details.code` is `ASYNC_ENQUEUE_AMBIGUOUS`, because the run may already have started — reconcile against the returned run id instead of retrying.',
+    'A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.',
     { message: 'Service temporarily unavailable', headers: ['Retry-After'] }
   ),
 } as const satisfies Readonly<Record<string, OpenApiErrorResponse>>
@@ -357,7 +351,7 @@ export const FOLDER_TREE_TOO_LARGE = 'Workspace folder trees exceeding 10,000 fo
  * promise. The authoritative membership is pinned in
  * `contracts/v2/list-pagination.test.ts` as `FULL_SET_LISTS`.
  */
-export const FULL_SET_LIST = 'Returns the complete set in one page; `nextCursor` is always null.'
+export const FULL_SET_LIST = 'Returns one page; `nextCursor` is always null.'
 
 /**
  * Appended to a `GET` whose route declares `headSafe: false` because the read
@@ -378,7 +372,7 @@ export const HEAD_MIRRORS_GET =
  * `headSafe: false` exists to skip.
  */
 export const HEAD_OMITS_PAYLOAD_HEADERS =
-  '`HEAD` omits `Content-Length`; use file metadata to size downloads.'
+  '`HEAD` omits `Content-Length` and cannot determine the download size.'
 
 /**
  * Appended to an operation whose semantic operation sets `workspaceApiKey: 'deny'`.
@@ -405,26 +399,13 @@ export const WORKSPACE_API_KEY_DENIED_AS_NOT_FOUND =
   'A workspace API key is rejected as `404` rather than `403`, because unauthorized resources are concealed; use a personal API key or an appropriately scoped OAuth token.'
 
 /**
- * Appended to the two reads over `workflow_execution_logs`, which is the only
- * store of a run and is hard-deleted — rows and execution files both — by the
- * `cleanup-logs` background task once a run passes the payer's window.
- *
- * The window itself is `CLEANUP_CONFIG['cleanup-logs'].defaults` in
- * `lib/billing/cleanup-dispatcher.ts`: 30 days on the free plan, and `null`
- * — meaning the plan is skipped entirely and nothing is deleted — on Pro and
- * Team. Enterprise resolves per organization through
- * `resolveEffectiveRetentionHours`, with a per-workspace override, and is
- * likewise unbounded until someone configures it. Self-hosted classifies every
- * workspace as enterprise and dispatches nothing unless data retention is
- * enabled.
- *
- * Stated because deletion is otherwise invisible: an aged-out run is not a
- * tombstone or a 404, it is simply absent. The matching `runCount` caveat lives
- * on that field rather than here. Kept as one constant so the two sibling reads
- * cannot drift into two paraphrases of one window.
+ * Shared by run-list reads. `cleanup-logs` deletes both log rows and execution files, so expired
+ * runs disappear from lists rather than leave tombstones. Plan windows come from
+ * `CLEANUP_CONFIG['cleanup-logs'].defaults` in `lib/billing/cleanup-dispatcher.ts`; organization and
+ * workspace policies resolve through `resolveEffectiveRetentionHours`.
  */
 export const RUN_RETENTION =
-  'Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides.'
+  'Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup.'
 
 /**
  * Response headers a binary download declares on top of the common set. Shared
diff --git a/apps/sim/lib/api/contracts/v2/openapi/sso.ts b/apps/sim/lib/api/contracts/v2/openapi/sso.ts
index f66f4039468..271335d9c58 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/sso.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/sso.ts
@@ -26,30 +26,33 @@ export const ssoOpenApiRoutes = [
     {
       applicationOperation: ssoProviderOperations.list,
       operationId: 'listSsoProviders',
-      summary: 'List SSO Providers',
-      description: `List identity providers owned by the organization. Requires organization administrator access. OIDC client secrets are redacted and SAML private keys are omitted. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List SSO providers',
+      description: `List identity providers owned by the organization. Requires organization Admin access. OIDC client secrets are redacted and SAML private keys are omitted. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'List SSO Providers result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'A page of identity providers with redacted configuration.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2ListSsoProvidersContract.params,
         'ListSsoProvidersParams',
-        'List SSO Providers parameters',
+        'List SSO providers parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
         v2ListSsoProvidersContract.query,
         'ListSsoProvidersQuery',
         'Query parameters',
-        'Filters and pagination controls.'
+        'Sorting and pagination controls.'
       ),
       response: documentedSchema(
         v2ListSsoProvidersContract.response.schema,
         'ListSsoProvidersResponse',
-        'List SSO Providers response',
-        'List SSO Providers result.'
+        'List SSO providers response',
+        'A page of identity providers with redacted configuration.'
       ),
     }
   ),
@@ -58,30 +61,33 @@ export const ssoOpenApiRoutes = [
     {
       applicationOperation: ssoProviderOperations.list,
       operationId: 'getSsoProvider',
-      summary: 'Get SSO Provider',
-      description: `Get an identity provider owned by the organization. Requires organization administrator access. OIDC client secrets are redacted and SAML private keys are omitted. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get SSO provider',
+      description: `Get an identity provider owned by the organization. Requires organization Admin access. OIDC client secrets are redacted and SAML private keys are omitted. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Get SSO Provider result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The identity provider with redacted configuration.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2GetSsoProviderContract.params,
         'GetSsoProviderParams',
-        'Get SSO Provider parameters',
+        'Get SSO provider parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
         v2GetSsoProviderContract.query,
         'GetSsoProviderQuery',
         'Query parameters',
-        'Filters and pagination controls.'
+        'No query parameters.'
       ),
       response: documentedSchema(
         v2GetSsoProviderContract.response.schema,
         'GetSsoProviderResponse',
-        'Get SSO Provider response',
-        'Get SSO Provider result.'
+        'Get SSO provider response',
+        'The identity provider with redacted configuration.'
       ),
     }
   ),
@@ -90,36 +96,39 @@ export const ssoOpenApiRoutes = [
     {
       applicationOperation: ssoProviderOperations.save,
       operationId: 'saveSsoProvider',
-      summary: 'Save SSO Provider',
-      description: `Create or update an organization identity provider’s configuration on a verified domain. Requires organization administrator access and SSO entitlement. Existing providers return 200; creation returns 201. Omission behavior is field-specific; OIDC’s redacted secret marker preserves the saved secret. Identity changes with linked accounts conflict. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Save SSO provider',
+      description: `Create or update an organization identity provider’s configuration on a verified domain. Requires organization Admin access and SSO entitlement. Existing providers return 200; creation returns 201. Omission behavior is field-specific; OIDC’s redacted secret marker preserves the saved secret. Identity changes with linked accounts conflict. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Save SSO Provider result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The saved provider ID, protocol, and whether it was created.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2SaveSsoProviderContract.params,
         'SaveSsoProviderParams',
-        'Save SSO Provider parameters',
+        'Save SSO provider parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
         v2SaveSsoProviderContract.query,
         'SaveSsoProviderQuery',
         'Query parameters',
-        'Filters and pagination controls.'
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2SaveSsoProviderContract.body,
         'SaveSsoProviderBody',
-        'Save SSO Provider body',
-        'Configuration accepted by Save SSO Provider.'
+        'Save SSO provider body',
+        'Provider protocol, verified domain, and identity-provider configuration. Omission behavior is field-specific.'
       ),
       response: documentedSchema(
         v2SaveSsoProviderContract.response.schema,
         'SaveSsoProviderResponse',
-        'Save SSO Provider response',
-        'Save SSO Provider result.'
+        'Save SSO provider response',
+        'The saved provider ID, protocol, and whether it was created.'
       ),
     }
   ),
@@ -128,30 +137,33 @@ export const ssoOpenApiRoutes = [
     {
       applicationOperation: ssoProviderOperations.delete,
       operationId: 'deleteSsoProvider',
-      summary: 'Delete SSO Provider',
-      description: `Remove an identity provider and clear its primary selection. Requires organization administrator access. Existing accounts, memberships, and sessions remain; sign-in falls back to another verified provider on the domain. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Delete SSO provider',
+      description: `Remove an identity provider and clear its primary selection. Requires organization Admin access. Existing accounts, memberships, and sessions remain. Domain sign-in falls back to another verified provider if one remains; use Get SSO policy to inspect whether SSO is still enforced. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Delete SSO Provider result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'Acknowledgement that the identity provider was removed.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2DeleteSsoProviderContract.params,
         'DeleteSsoProviderParams',
-        'Delete SSO Provider parameters',
+        'Delete SSO provider parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
         v2DeleteSsoProviderContract.query,
         'DeleteSsoProviderQuery',
         'Query parameters',
-        'Filters and pagination controls.'
+        'No query parameters.'
       ),
       response: documentedSchema(
         v2DeleteSsoProviderContract.response.schema,
         'DeleteSsoProviderResponse',
-        'Delete SSO Provider response',
-        'Delete SSO Provider result.'
+        'Delete SSO provider response',
+        'Acknowledgement that the identity provider was removed.'
       ),
     }
   ),
@@ -160,36 +172,39 @@ export const ssoOpenApiRoutes = [
     {
       applicationOperation: ssoSettingsOperations.setPrimary,
       operationId: 'setPrimarySsoProvider',
-      summary: 'Set Primary SSO Provider',
-      description: `Make a verified organization provider handle sign-in for its domain. Requires organization administrator access. Other providers remain available for testing and later switching. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Set primary SSO provider',
+      description: `Make a verified organization provider handle sign-in for its domain. Requires organization Admin access. Other providers remain available for testing and later switching. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Set Primary SSO Provider result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The provider selected for its verified domain.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2SetPrimarySsoProviderContract.params,
         'SetPrimarySsoProviderParams',
-        'Set Primary SSO Provider parameters',
+        'Set primary SSO provider parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
         v2SetPrimarySsoProviderContract.query,
         'SetPrimarySsoProviderQuery',
         'Query parameters',
-        'Filters and pagination controls.'
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2SetPrimarySsoProviderContract.body,
         'SetPrimarySsoProviderBody',
-        'Set Primary SSO Provider body',
-        'Configuration accepted by Set Primary SSO Provider.'
+        'Set primary SSO provider body',
+        'An empty JSON object; the path identifies the provider to make primary.'
       ),
       response: documentedSchema(
         v2SetPrimarySsoProviderContract.response.schema,
         'SetPrimarySsoProviderResponse',
-        'Set Primary SSO Provider response',
-        'Set Primary SSO Provider result.'
+        'Set primary SSO provider response',
+        'The provider selected for its verified domain.'
       ),
     }
   ),
@@ -198,30 +213,33 @@ export const ssoOpenApiRoutes = [
     {
       applicationOperation: ssoSettingsOperations.readRequirement,
       operationId: 'getSsoPolicy',
-      summary: 'Get SSO Policy',
+      summary: 'Get SSO policy',
       description: `Get the stored organization SSO requirement and whether it is currently enforced. Requires organization membership. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Get SSO Policy result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The stored SSO requirement and its effective enforcement state.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2GetSsoPolicyContract.params,
         'GetSsoPolicyParams',
-        'Get SSO Policy parameters',
+        'Get SSO policy parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
         v2GetSsoPolicyContract.query,
         'GetSsoPolicyQuery',
         'Query parameters',
-        'Filters and pagination controls.'
+        'No query parameters.'
       ),
       response: documentedSchema(
         v2GetSsoPolicyContract.response.schema,
         'GetSsoPolicyResponse',
-        'Get SSO Policy response',
-        'Get SSO Policy result.'
+        'Get SSO policy response',
+        'The stored SSO requirement and its effective enforcement state.'
       ),
     }
   ),
@@ -230,36 +248,39 @@ export const ssoOpenApiRoutes = [
     {
       applicationOperation: ssoSettingsOperations.setRequirement,
       operationId: 'updateSsoPolicy',
-      summary: 'Update SSO Policy',
-      description: `Require or stop requiring SSO on future sign-ins. Requires organization administrator access. Enabling requires SSO entitlement and a verified provider; disabling remains available after entitlement is lost. Existing sessions remain active. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update SSO policy',
+      description: `Require or stop requiring SSO on future sign-ins. Requires organization Admin access. Enabling requires SSO entitlement and a verified provider; disabling remains available after entitlement is lost. Existing sessions remain active. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Update SSO Policy result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The saved SSO requirement and its effective enforcement state.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2UpdateSsoPolicyContract.params,
         'UpdateSsoPolicyParams',
-        'Update SSO Policy parameters',
+        'Update SSO policy parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
         v2UpdateSsoPolicyContract.query,
         'UpdateSsoPolicyQuery',
         'Query parameters',
-        'Filters and pagination controls.'
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2UpdateSsoPolicyContract.body,
         'UpdateSsoPolicyBody',
-        'Update SSO Policy body',
-        'Configuration accepted by Update SSO Policy.'
+        'Update SSO policy body',
+        'Whether future sign-ins must use SSO.'
       ),
       response: documentedSchema(
         v2UpdateSsoPolicyContract.response.schema,
         'UpdateSsoPolicyResponse',
-        'Update SSO Policy response',
-        'Update SSO Policy result.'
+        'Update SSO policy response',
+        'The saved SSO requirement and its effective enforcement state.'
       ),
     }
   ),
@@ -268,30 +289,33 @@ export const ssoOpenApiRoutes = [
     {
       applicationOperation: organizationSecurityOperations.listDomains,
       operationId: 'listOrganizationDomains',
-      summary: 'List Organization Domains',
+      summary: 'List organization domains',
       description: `List the organization’s domain claims with cursor pagination. Requires organization membership. Pending DNS challenge values are returned only to administrators using their own credentials. Organizations without Enterprise domain entitlement return an empty list. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'List Organization Domains result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'A page of domain claims; pending challenges are limited to Admins.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2ListOrganizationDomainsContract.params,
         'ListOrganizationDomainsParams',
-        'List Organization Domains parameters',
+        'List organization domains parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
         v2ListOrganizationDomainsContract.query,
         'ListOrganizationDomainsQuery',
         'Query parameters',
-        'Filters and pagination controls.'
+        'Sorting and pagination controls.'
       ),
       response: documentedSchema(
         v2ListOrganizationDomainsContract.response.schema,
         'ListOrganizationDomainsResponse',
-        'List Organization Domains response',
-        'List Organization Domains result.'
+        'List organization domains response',
+        'A page of domain claims; pending challenges are limited to Admins.'
       ),
     }
   ),
@@ -300,36 +324,39 @@ export const ssoOpenApiRoutes = [
     {
       applicationOperation: organizationSecurityOperations.addDomain,
       operationId: 'addOrganizationDomain',
-      summary: 'Add Organization Domain',
-      description: `Claim a domain and receive its DNS TXT challenge. Requires organization administrator access and Enterprise domain entitlement. An existing claim returns 200; a new claim returns 201. A domain verified by another organization conflicts. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Add organization domain',
+      description: `Claim a domain and receive its DNS TXT challenge. Requires organization Admin access and, when billing is enabled, Enterprise domain entitlement. An organization can claim at most 25 domains. Existing claims return \`200\`; new claims return \`201\`. A domain verified by another organization returns \`409\`. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Add Organization Domain result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The domain claim and its pending DNS challenge, when applicable.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2AddOrganizationDomainContract.params,
         'AddOrganizationDomainParams',
-        'Add Organization Domain parameters',
+        'Add organization domain parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
         v2AddOrganizationDomainContract.query,
         'AddOrganizationDomainQuery',
         'Query parameters',
-        'Filters and pagination controls.'
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2AddOrganizationDomainContract.body,
         'AddOrganizationDomainBody',
-        'Add Organization Domain body',
-        'Configuration accepted by Add Organization Domain.'
+        'Add organization domain body',
+        'The domain to claim and verify.'
       ),
       response: documentedSchema(
         v2AddOrganizationDomainContract.response.schema,
         'AddOrganizationDomainResponse',
-        'Add Organization Domain response',
-        'Add Organization Domain result.'
+        'Add organization domain response',
+        'The domain claim and its pending DNS challenge, when applicable.'
       ),
     }
   ),
@@ -338,36 +365,39 @@ export const ssoOpenApiRoutes = [
     {
       applicationOperation: organizationSecurityOperations.verifyDomain,
       operationId: 'verifyOrganizationDomain',
-      summary: 'Verify Organization Domain',
-      description: `Verify domain ownership through the published DNS TXT challenge and grant domain trust to matching organization providers. Requires organization administrator access and Enterprise domain entitlement. An already-verified domain is returned unchanged. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Verify organization domain',
+      description: `Verify domain ownership through its DNS TXT challenge and grant domain trust to matching organization providers. Requires organization Admin access and, when billing is enabled, Enterprise domain entitlement. Billing-disabled self-hosted deployments may configure operator verification. An already-verified domain is returned unchanged. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Verify Organization Domain result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'The domain claim after ownership verification.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2VerifyOrganizationDomainContract.params,
         'VerifyOrganizationDomainParams',
-        'Verify Organization Domain parameters',
+        'Verify organization domain parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
         v2VerifyOrganizationDomainContract.query,
         'VerifyOrganizationDomainQuery',
         'Query parameters',
-        'Filters and pagination controls.'
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2VerifyOrganizationDomainContract.body,
         'VerifyOrganizationDomainBody',
-        'Verify Organization Domain body',
-        'Configuration accepted by Verify Organization Domain.'
+        'Verify organization domain body',
+        'An empty JSON object; verification uses the claim’s current DNS challenge.'
       ),
       response: documentedSchema(
         v2VerifyOrganizationDomainContract.response.schema,
         'VerifyOrganizationDomainResponse',
-        'Verify Organization Domain response',
-        'Verify Organization Domain result.'
+        'Verify organization domain response',
+        'The domain claim after ownership verification.'
       ),
     }
   ),
@@ -376,30 +406,33 @@ export const ssoOpenApiRoutes = [
     {
       applicationOperation: organizationSecurityOperations.removeDomain,
       operationId: 'removeOrganizationDomain',
-      summary: 'Remove Organization Domain',
-      description: `Remove a domain claim and revoke verified sign-in authority from matching organization providers. Requires organization administrator access and Enterprise domain entitlement. Existing accounts and memberships remain. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Remove organization domain',
+      description: `Remove a domain claim and revoke verified sign-in authority from matching organization providers. Requires organization Admin access and, when billing is enabled, Enterprise domain entitlement. Existing accounts and memberships remain. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Organizations'],
       errors: RESOURCE_CONFLICT_ERRORS,
-      success: { description: 'Remove Organization Domain result.', headers: RATE_LIMIT_HEADERS },
+      success: {
+        description: 'Acknowledgement that the domain claim was removed.',
+        headers: RATE_LIMIT_HEADERS,
+      },
     },
     {
       params: documentedSchema(
         v2RemoveOrganizationDomainContract.params,
         'RemoveOrganizationDomainParams',
-        'Remove Organization Domain parameters',
+        'Remove organization domain parameters',
         'Resource identifiers.'
       ),
       query: documentedSchema(
         v2RemoveOrganizationDomainContract.query,
         'RemoveOrganizationDomainQuery',
         'Query parameters',
-        'Filters and pagination controls.'
+        'No query parameters.'
       ),
       response: documentedSchema(
         v2RemoveOrganizationDomainContract.response.schema,
         'RemoveOrganizationDomainResponse',
-        'Remove Organization Domain response',
-        'Remove Organization Domain result.'
+        'Remove organization domain response',
+        'Acknowledgement that the domain claim was removed.'
       ),
     }
   ),
diff --git a/apps/sim/lib/api/contracts/v2/openapi/tables.ts b/apps/sim/lib/api/contracts/v2/openapi/tables.ts
index d162f682bf3..842e126b3f7 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/tables.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/tables.ts
@@ -106,11 +106,8 @@ const TABLE_MUTATION_ERRORS = [
 ] as const satisfies readonly ErrorResponseId[]
 
 /**
- * The two table query reads declare their own `maxBodyBytes` — 1 MiB, far below
- * the 50 MB default every JSON body is held to — so their `413` is a routine
- * answer to an oversized predicate rather than an abuse ceiling, and it is named
- * here and in their descriptions. Every other table read carries its input in
- * the query string and has no body ceiling to exceed.
+ * Table query reads reject JSON predicates over 1 MiB and document that 413.
+ * Other table reads use query parameters and cannot exceed a JSON body cap.
  */
 const TABLE_QUERY_ERRORS = [
   ...RESOURCE_ERRORS,
@@ -139,7 +136,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.list,
       operationId: 'listTables',
-      summary: 'List Tables',
+      summary: 'List tables',
       description: `List active tables with folder filtering, search, sorting, and cursor pagination. Use \`scope=archived\` to find tables available for restoration. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...WORKSPACE_ERRORS, 'NotFound', 'PayloadTooLarge'],
       success: { description: 'A page of tables in the workspace.' },
@@ -164,7 +161,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.create,
       operationId: 'createTable',
-      summary: 'Create Table',
+      summary: 'Create table',
       description: 'Create a table with a typed column schema and optional folder placement.',
       errors: [...WORKSPACE_ERRORS, 'NotFound', 'Conflict', 'PayloadTooLarge'],
       success: { description: 'The created table.' },
@@ -203,7 +200,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.read,
       operationId: 'getTable',
-      summary: 'Get Table',
+      summary: 'Get table',
       description: `Get a table with its metadata, column schema, locks, and current job. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The requested table.' },
@@ -234,9 +231,9 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.delete,
       operationId: 'deleteTable',
-      summary: 'Delete Table',
+      summary: 'Delete table',
       description:
-        'Archive a table while retaining its rows. Use List Tables with `scope=archived` to find it and Restore Table to recover it.',
+        'Archive a table while retaining its rows. Use List tables with `scope=archived` to find it and Restore table to recover it.',
       errors: TABLE_MUTATION_ERRORS,
       success: { description: 'Table deletion acknowledgement.' },
     }),
@@ -266,7 +263,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.update,
       operationId: 'updateTable',
-      summary: 'Update Table',
+      summary: 'Update table',
       description: `Rename a table, edit its description, or move it to a folder. Fields are saved independently: a failed request may leave partial changes. \`error.details.applied\` lists saved fields; retry only the remaining fields. If absent, nothing changed. Lock flags are read-only. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The updated table.' },
@@ -299,7 +296,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.addColumn,
       operationId: 'addTableColumn',
-      summary: 'Add Column',
+      summary: 'Add column',
       description: 'Add a typed column and return the complete resulting table schema.',
       errors: TABLE_MUTATION_ERRORS,
       success: { description: 'The updated table columns.' },
@@ -332,7 +329,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.updateColumn,
       operationId: 'updateTableColumn',
-      summary: 'Update Column',
+      summary: 'Update column',
       description:
         'Update a column by name and return the complete schema. Renames update rows, views, and workflow-group references keyed by column ID. Workflow Table blocks keep their authored `filter`, `order`, and `data` JSON unchanged. Bound blocks still referencing the old name appear in `unmigrated`; edit them with Apply Workflow Operations to prevent failures on their next run.',
       errors: TABLE_MUTATION_ERRORS,
@@ -393,7 +390,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.deleteColumn,
       operationId: 'deleteTableColumn',
-      summary: 'Delete Column',
+      summary: 'Delete column',
       description: 'Delete a column by name while preserving at least one table column.',
       errors: TABLE_MUTATION_ERRORS,
       success: { description: 'The surviving table columns.' },
@@ -426,10 +423,10 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.listRows,
       operationId: 'listTableRows',
-      summary: 'List Rows',
+      summary: 'List rows',
       description:
-        'List rows in default order with cursor pagination. Pages default to a 5 MB limit and may contain fewer rows than requested; continue until `nextCursor` is null. Use Query Rows for filtering and sorting. `includeRunState=true` adds per-group run outcomes and reduces the row limit.',
-      errors: RESOURCE_ERRORS,
+        'List rows in default order with cursor pagination. Pages default to a 5 MiB limit and may contain fewer rows than requested; continue until `nextCursor` is null. Use Query rows for filtering and sorting. `includeRunState=true` adds per-group run outcomes and reduces the row limit.',
+      errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'A page of table rows.' },
     }),
     {
@@ -458,7 +455,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.createRows,
       operationId: 'createTableRows',
-      summary: 'Create Rows',
+      summary: 'Create rows',
       description:
         'Insert one row with a data object or insert a bounded batch with a rows array. Cell keys are column names.',
       errors: TABLE_MUTATION_ERRORS,
@@ -492,7 +489,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.updateRows,
       operationId: 'updateTableRows',
-      summary: 'Update Rows by Filter',
+      summary: 'Update rows by filter',
       description: 'Apply the same partial data patch to every row matching a non-empty predicate.',
       errors: TABLE_MUTATION_ERRORS,
       success: { description: 'The bulk update result.' },
@@ -531,7 +528,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.deleteRows,
       operationId: 'deleteTableRows',
-      summary: 'Delete Rows',
+      summary: 'Delete rows',
       description:
         'Delete rows by a non-empty predicate or an explicit bounded list of row identifiers.',
       errors: TABLE_MUTATION_ERRORS,
@@ -565,10 +562,10 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.readRow,
       operationId: 'getTableRow',
-      summary: 'Get Row',
+      summary: 'Get row',
       description:
         "Get one row by identifier. Set `includeRunState=true` to attach the row's per-workflow-group run outcomes.",
-      errors: RESOURCE_ERRORS,
+      errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The requested table row.' },
     }),
     {
@@ -597,7 +594,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.updateRow,
       operationId: 'updateTableRow',
-      summary: 'Update Row',
+      summary: 'Update row',
       description: 'Merge a partial data patch into one row by identifier.',
       errors: TABLE_MUTATION_ERRORS,
       success: { description: 'The updated table row.' },
@@ -630,7 +627,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.deleteRow,
       operationId: 'deleteTableRow',
-      summary: 'Delete Row',
+      summary: 'Delete row',
       description: 'Delete one row by identifier.',
       errors: TABLE_MUTATION_ERRORS,
       success: { description: 'The row deletion result.' },
@@ -661,9 +658,9 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.upsertRow,
       operationId: 'upsertTableRow',
-      summary: 'Upsert Row',
+      summary: 'Upsert row',
       description:
-        'Insert a row or replace the row matching a selected unique column. On replacement, omitted columns are cleared; send the complete row. Use Update Row for a partial patch.',
+        'Insert a row or replace the row matching a selected unique column. On replacement, omitted columns are cleared; send the complete row. Use Update row for a partial patch.',
       errors: TABLE_MUTATION_ERRORS,
       success: { description: 'The upserted row and operation performed.' },
     }),
@@ -701,9 +698,9 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.queryRows,
       operationId: 'queryTableRows',
-      summary: 'Query Rows',
+      summary: 'Query rows',
       description:
-        'Query rows with typed predicates, sorting, and cursor pagination. Omit the predicate to match all rows. Pages default to a 5 MB limit; continue until `nextCursor` is null. Oversized predicates return `413`. `includeRunState` adds per-group outcomes and reduces the row limit. Counts are read separately and can differ from paged results if rows change.',
+        'Query rows with typed predicates, sorting, and cursor pagination. Omit the predicate to match all rows. Pages default to a 5 MiB limit; continue until `nextCursor` is null. Oversized predicates return `413`. `includeRunState` adds per-group outcomes and reduces the row limit. Counts are read separately and can differ from paged results if rows change.',
       errors: TABLE_QUERY_ERRORS,
       success: { description: 'A page of matching table rows.' },
     }),
@@ -755,7 +752,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.queryRows,
       operationId: 'countTableRows',
-      summary: 'Count Rows',
+      summary: 'Count rows',
       description:
         'Count rows matching a typed predicate, or omit the predicate to count all rows. The count is read separately from row pages and can change between requests. Oversized predicates return `413`.',
       errors: TABLE_QUERY_ERRORS,
@@ -794,7 +791,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.listViews,
       operationId: 'listTableViews',
-      summary: 'List Views',
+      summary: 'List views',
       description: `List saved table views, omitting references to removed columns. ${FULL_SET_LIST}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The saved table views.' },
@@ -825,7 +822,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.createView,
       operationId: 'createTableView',
-      summary: 'Create View',
+      summary: 'Create view',
       description: 'Save a filter, sort, and column layout as a named presentation of a table.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The created table view.' },
@@ -867,7 +864,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.readView,
       operationId: 'getTableView',
-      summary: 'Get View',
+      summary: 'Get view',
       description: 'Get one saved table view by identifier.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The requested table view.' },
@@ -899,7 +896,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.updateView,
       operationId: 'updateTableView',
-      summary: 'Update View',
+      summary: 'Update view',
       description:
         'Rename a view, replace or shallow-merge its configuration, or promote it to the table default.',
       errors: RESOURCE_ERRORS,
@@ -933,7 +930,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.deleteView,
       operationId: 'deleteTableView',
-      summary: 'Delete View',
+      summary: 'Delete view',
       description: 'Delete a saved presentation without changing any table rows.',
       errors: RESOURCE_ERRORS,
       success: { description: 'Table view deletion acknowledgement.' },
@@ -964,7 +961,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.listGroups,
       operationId: 'listTableWorkflowGroups',
-      summary: 'List Workflow Groups',
+      summary: 'List workflow groups',
       description: `List the workflow and enrichment groups that can be dispatched for a table. ${FULL_SET_LIST}`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The table workflow groups.' },
@@ -995,7 +992,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.createGroup,
       operationId: 'addTableWorkflowGroup',
-      summary: 'Add Workflow Group',
+      summary: 'Add workflow group',
       description:
         'Bind a workflow or enrichment to the table and create the columns populated by its outputs. An output whose column the table already has attaches that column to the group instead of creating it, so `outputColumns` may be omitted when every output lands in an existing column.',
       errors: TABLE_MUTATION_ERRORS,
@@ -1039,7 +1036,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.updateGroup,
       operationId: 'updateTableWorkflowGroup',
-      summary: 'Update Workflow Group',
+      summary: 'Update workflow group',
       description:
         'Restructure a workflow group, its producer, outputs, or execution behavior. Repointing the group at a different workflow concurrently invalidates the resolved output types and returns `409` — retry the update.',
       errors: RESOURCE_MUTATION_ERRORS,
@@ -1073,7 +1070,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.deleteGroup,
       operationId: 'deleteTableWorkflowGroup',
-      summary: 'Delete Workflow Group',
+      summary: 'Delete workflow group',
       description: 'Delete a workflow group and every table column populated by that group.',
       errors: TABLE_MUTATION_ERRORS,
       success: { description: 'Workflow-group deletion acknowledgement and surviving columns.' },
@@ -1106,9 +1103,9 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.startRun,
       operationId: 'createTableDispatch',
-      summary: 'Create Run Dispatch',
+      summary: 'Create run dispatch',
       description:
-        'Start workflow or enrichment groups across all rows or selected rows. Poll Get Run Dispatch until `complete` or `canceled`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`. Use Cancel Run Dispatch to stop further scheduling.',
+        'Start workflow or enrichment groups across all rows or selected rows. Poll Get run dispatch until `complete` or `canceled`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`. Use Cancel run dispatch to stop further scheduling.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The accepted run dispatch.' },
     }),
@@ -1140,9 +1137,9 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.startRun,
       operationId: 'runRowEnrichment',
-      summary: 'Run Enrichment For One Row',
+      summary: 'Run enrichment for one row',
       description:
-        'Start one workflow or enrichment group for a table row. Poll Get Run Dispatch using the returned `dispatchId`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`.',
+        'Start one workflow or enrichment group for a table row. Poll Get run dispatch using the returned `dispatchId`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The accepted row enrichment dispatch.' },
     }),
@@ -1174,8 +1171,8 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.searchRows,
       operationId: 'searchTableRows',
-      summary: 'Search Rows',
-      description: `Search cell text for a case-insensitive substring within an optional filtered and sorted view. Returns cell coordinates, not row data; \`ordinal\` matches the view used by Query Rows. Results are unpaginated and capped at ${TABLE_LIMITS.MAX_FIND_MATCHES}. If \`truncated\` is true, narrow the search or predicate.`,
+      summary: 'Search rows',
+      description: `Search cell text for a case-insensitive substring within an optional filtered and sorted view. Returns cell coordinates, not row data; \`ordinal\` matches the view used by Query rows. Results are unpaginated and capped at ${TABLE_LIMITS.MAX_FIND_MATCHES}. If \`truncated\` is true, narrow the search or predicate.`,
       errors: RESOURCE_ERRORS,
       success: { description: 'The matching table cells.' },
     }),
@@ -1213,7 +1210,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.createImport,
       operationId: 'createTableImport',
-      summary: 'Create Table Import',
+      summary: 'Create table import',
       description:
         'Create a CSV import. Upload sources receive signed transfer instructions; workspace-file sources start processing directly.',
       errors: [...WORKSPACE_ERRORS, 'NotFound', 'Conflict', 'Locked', 'PayloadTooLarge'],
@@ -1248,7 +1245,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.readImport,
       operationId: 'getTableImport',
-      summary: 'Get Table Import',
+      summary: 'Get table import',
       description:
         "Get an import's progress and status. During `uploading`, the signed upload token is required; omitting it returns `404`.",
       errors: RESOURCE_ERRORS,
@@ -1287,7 +1284,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.cancelImport,
       operationId: 'cancelTableImport',
-      summary: 'Cancel Table Import',
+      summary: 'Cancel table import',
       description:
         'Cancel an upload or processing import. Committed row batches remain. Non-cancelable states, including `expired`, return `409`; unknown or purged imports return `404`.',
       errors: RESOURCE_CONFLICT_ERRORS,
@@ -1325,7 +1322,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.createImportParts,
       operationId: 'createTableImportPartUrls',
-      summary: 'Create Table Import Part URLs',
+      summary: 'Create table import part URLs',
       description:
         'Create signed URLs for multipart upload parts. Requires the `uploading` state; other states return `409`. Unknown or purged imports return `404`.',
       errors: RESOURCE_CONFLICT_ERRORS,
@@ -1370,7 +1367,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.completeImport,
       operationId: 'completeTableImportUpload',
-      summary: 'Complete Table Import Upload',
+      summary: 'Complete table import upload',
       description:
         'Verify or assemble uploaded CSV bytes and start processing under the same import ID. Requires an import awaiting upload completion; other states return `409`. Unknown or purged imports return `404`.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'Locked'],
@@ -1408,7 +1405,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.createExport,
       operationId: 'createTableExport',
-      summary: 'Create Table Export',
+      summary: 'Create table export',
       description:
         'Create a CSV or JSON export. Exports of small tables finish during the request; larger exports run asynchronously.',
       errors: RESOURCE_CONFLICT_ERRORS,
@@ -1442,7 +1439,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.readExport,
       operationId: 'getTableExport',
-      summary: 'Get Table Export',
+      summary: 'Get table export',
       description: "Get a table export's progress and status.",
       errors: RESOURCE_ERRORS,
       success: { description: 'The requested table export.' },
@@ -1474,7 +1471,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.cancelExport,
       operationId: 'cancelTableExport',
-      summary: 'Cancel Table Export',
+      summary: 'Cancel table export',
       description: 'Cancel an export that is still in progress.',
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The canceled table export.' },
@@ -1505,7 +1502,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.downloadExport,
       operationId: 'downloadTableExport',
-      summary: 'Download Table Export',
+      summary: 'Download table export',
       description:
         'Get a short-lived signed download URL for a completed export. Other states return `409`; an unavailable export file returns `404`.',
       errors: RESOURCE_CONFLICT_ERRORS,
@@ -1537,7 +1534,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.cancelRuns,
       operationId: 'cancelTableRuns',
-      summary: 'Cancel Column Runs',
+      summary: 'Cancel column runs',
       description:
         'Stop in-flight and pending workflow or enrichment cell runs across the table or one selected row.',
       errors: RESOURCE_ERRORS,
@@ -1555,7 +1552,7 @@ const declaredRoutes = [
         v2CancelTableRunsContract.body,
         'CancelTableRunsRequest',
         'Cancel table runs request',
-        'Workspace scope, cancellation scope, and optional predicate or producer groups.',
+        'Workspace scope, row or all-table cancellation, and optional row predicate or exclusions.',
         [{ workspaceId: WORKSPACE_ID, scope: 'row', rowId: ROW_ID }]
       ),
       response: documentedSchema(
@@ -1571,7 +1568,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.listFolders,
       operationId: 'listTablesFolders',
-      summary: 'List Folders',
+      summary: 'List folders',
       description: `List table folders, optionally limiting results to direct children of a parent path. ${FULL_SET_LIST}`,
       errors: [...WORKSPACE_ERRORS, 'NotFound', 'PayloadTooLarge'],
       success: { description: 'The table folders.' },
@@ -1596,7 +1593,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.createFolder,
       operationId: 'createTablesFolder',
-      summary: 'Create Folder',
+      summary: 'Create folder',
       description: 'Create one table-folder leaf whose parent path already exists.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The created table folder.' },
@@ -1623,7 +1620,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.updateFolder,
       operationId: 'relocateTablesFolder',
-      summary: 'Rename or Move Folder',
+      summary: 'Rename or move folder',
       description: 'Rename or move a table folder and update all descendant paths.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The relocated table folder.' },
@@ -1656,9 +1653,9 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.deleteFolder,
       operationId: 'deleteTablesFolder',
-      summary: 'Delete Folder',
+      summary: 'Delete folder',
       description:
-        'Archive an empty folder, or set `recursive=true` to archive its tables and subfolders. Use Restore Folder to recover the archived contents.',
+        'Archive an empty folder, or set `recursive=true` to archive its tables and subfolders. Use Restore folder to recover the archived contents.',
       errors: [...RESOURCE_MUTATION_ERRORS, 'PayloadTooLarge'],
       success: { description: 'Table-folder deletion acknowledgement.' },
     }),
@@ -1682,9 +1679,9 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.restoreFolder,
       operationId: 'restoreTablesFolder',
-      summary: 'Restore Folder',
+      summary: 'Restore folder',
       description:
-        'Restore an archived table folder, its descendants, and tables using its former path. An archived parent moves it to the root; name conflicts may change the returned `path`. Non-archived paths return `404`. Save the path from Delete Folder, because List Folders does not include archived table folders.',
+        'Restore an archived table folder, its descendants, and tables using its former path. An archived parent moves it to the root; name conflicts may change the returned `path`. Non-archived paths return `404`. Save the path from Delete folder, because List folders does not include archived table folders.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The restored table folder and what it brought back.' },
     }),
@@ -1710,9 +1707,9 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.restore,
       operationId: 'restoreTable',
-      summary: 'Restore Table',
+      summary: 'Restore table',
       description:
-        'Restore a table and its archived rows, views, and workflow groups. Active tables return unchanged without a new audit event. Name conflicts may change the returned `name`. Find archived tables with List Tables and `scope=archived`.',
+        'Restore a table and its archived rows, views, and workflow groups. Active tables return unchanged without a new audit event. Name conflicts may change the returned `name`. Find archived tables with List tables and `scope=archived`.',
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The restored table.' },
     }),
@@ -1744,9 +1741,9 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.updateRows,
       operationId: 'bulkUpdateTableRows',
-      summary: 'Bulk Update Rows',
+      summary: 'Bulk update rows',
       description:
-        'Apply separate partial patches to up to 1,000 rows, preserving omitted columns. A row outside the table rejects the entire request with `400` and lists missing IDs. Use Update Rows by Filter to apply one patch to every matching row.',
+        'Apply separate partial patches to up to 1,000 rows, preserving omitted columns. A row outside the table rejects the entire request with `400` and lists missing IDs. Use Update rows by filter to apply one patch to every matching row.',
       errors: [...TABLE_MUTATION_ERRORS, 'PayloadTooLarge'],
       success: { description: 'The bulk update result.' },
     }),
@@ -1786,10 +1783,10 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.readRow,
       operationId: 'getRowEnrichment',
-      summary: 'Get Row Group Run',
+      summary: 'Get row group run',
       description:
-        'Read a workflow or enrichment group’s outcome for one row: `runState` (as exposed by `includeRunState`), output cells keyed by column name, and enrichment providers in cascade order with status, hosted-key cost, duration, and the matching provider. Existing rows always answer: `runState: null` means never run; `cascade: null` means no breakdown recorded. Missing tables, rows, or groups return `404`.',
-      errors: RESOURCE_ERRORS,
+        'Read one row’s workflow or enrichment-group outcome: run state, output cells keyed by column name, and providers in cascade order with status, hosted-key cost, duration, and the matching provider. `runState: null` means never run; `cascade: null` means no breakdown was recorded. Missing tables, rows, or groups return `404`. Run state above 2 MiB returns `413`.',
+      errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: {
         description: 'The run state, output cells, and provider cascade for the group on the row.',
       },
@@ -1820,7 +1817,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.readRun,
       operationId: 'getTableDispatch',
-      summary: 'Get Run Dispatch',
+      summary: 'Get run dispatch',
       description:
         "Get a dispatch's current state. Poll until `complete` or `canceled`; use row reads with `includeRunState` for per-cell outcomes.",
       errors: RESOURCE_ERRORS,
@@ -1852,9 +1849,9 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.cancelRuns,
       operationId: 'cancelTableDispatch',
-      summary: 'Cancel Run Dispatch',
+      summary: 'Cancel run dispatch',
       description:
-        'Stop a dispatch from scheduling more cells. Already queued or running cells continue; use Cancel Column Runs to stop them. Completed or canceled dispatches return unchanged.',
+        'Stop a dispatch from scheduling more cells. Already queued or running cells continue; use Cancel column runs to stop them. Completed or canceled dispatches return unchanged.',
       errors: RESOURCE_ERRORS,
       success: { description: 'The dispatch in its post-cancellation state.' },
     }),
@@ -1884,7 +1881,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.readRun,
       operationId: 'listTableDispatches',
-      summary: 'List Run Dispatches',
+      summary: 'List run dispatches',
       description:
         'List the run dispatches on one table, most recent first — settled dispatches (`complete`, `canceled`) alongside the ones still in flight, so a run that finished between two polls is still visible next to the `dispatchId` its create returned. Capped at the 100 most recent, so this list is unpaginated and `nextCursor` is always null.',
       errors: RESOURCE_ERRORS,
@@ -1916,7 +1913,7 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.bulkMove,
       operationId: 'moveTables',
-      summary: 'Move Tables and Folders',
+      summary: 'Move tables and folders',
       description:
         'Move up to 100 tables and folders to one destination. Items succeed or fail independently: covered tables are `skipped`, missing items are `notFound`, and lock or cycle failures include reasons in `failed`. An invalid destination rejects the request before any move.',
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
@@ -1951,9 +1948,9 @@ const declaredRoutes = [
     tableOperation({
       applicationOperation: tableOperations.bulkDelete,
       operationId: 'bulkDeleteTables',
-      summary: 'Bulk Delete Tables and Folders',
+      summary: 'Bulk delete tables and folders',
       description:
-        'Archive up to 100 selected tables and folders, including folder contents. Items succeed or fail independently, with `skipped`, `notFound`, and `failed` outcomes. `deletedItems` includes all descendants. Use Restore Table or Restore Folder to recover archived items.',
+        'Archive up to 100 selected tables and folders, including folder contents. Items succeed or fail independently, with `skipped`, `notFound`, and `failed` outcomes. `deletedItems` includes all descendants. Use Restore table or Restore folder to recover archived items.',
       errors: [...RESOURCE_ERRORS, 'Locked', 'PayloadTooLarge'],
       success: { description: 'Per-item outcome of the bulk delete.' },
     }),
@@ -2020,10 +2017,10 @@ export const tablesOpenApiDocument = defineOpenApiDocument({
   headers: V2_COMMON_HEADERS,
   errorSchema: V2_ERROR_SCHEMA,
   errorResponses: withErrorExamples({
-    Conflict: { message: 'A table named "Orders" already exists in this workspace' },
+    Conflict: { message: 'The request conflicts with current table state' },
     Locked: {
-      message: 'This table is insert-locked: new rows cannot be added.',
-      /** Names which of the four locks refused the write, so a caller can say which. */
+      message: 'A table lock prevents this operation.',
+      /** Example lock kind; the response identifies the lock that refused the operation. */
       details: { lock: 'insert' },
     },
   }),
diff --git a/apps/sim/lib/api/contracts/v2/openapi/workflows.ts b/apps/sim/lib/api/contracts/v2/openapi/workflows.ts
index 805c2530cfd..bf5d9851c88 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/workflows.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/workflows.ts
@@ -12,7 +12,6 @@ import {
   FOLDER_TREE_TOO_LARGE,
   FULL_SET_LIST,
   HEAD_MIRRORS_GET,
-  HEAD_OMITS_PAYLOAD_HEADERS,
   RATE_LIMIT_HEADERS,
   RESOURCE_CONFLICT_ERRORS,
   RESOURCE_ERRORS,
@@ -250,8 +249,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.list,
       operationId: 'listWorkflows',
-      summary: 'List Workflows',
-      description: `List active workflows in a workspace. Use \`scope=archived\` to find workflows available for restoration. Supports folder and deployment filters, search, sorting, and cursor pagination. ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'List workflows',
+      description: `List active workflows in a workspace with workspace read access. Use \`scope=archived\` to find workflows available for restoration. Filter by folder, deployment, or name; sort and page with the returned cursor. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...WORKSPACE_ERRORS, 'NotFound', 'PayloadTooLarge'],
       success: jsonSuccess('A page of workflows.'),
     }),
@@ -271,8 +270,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.create,
       operationId: 'createWorkflowV2',
-      summary: 'Create Workflow',
-      description: `Create a workflow at the workspace root or in a workflow folder. The response includes seeded blocks and their IDs for attaching edges. ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'Create workflow',
+      description: `Create an undeployed workflow at the workspace root or in a workflow folder. Requires workspace write access. The response includes the seeded start block and its ID for connecting other blocks. A name already used in the destination folder returns \`409\`. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...WORKSPACE_ERRORS, 'NotFound', 'Conflict', 'Locked', 'PayloadTooLarge'],
       success: jsonSuccess('The created workflow.'),
     }),
@@ -304,9 +303,9 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.read,
       operationId: 'getWorkflowState',
-      summary: 'Get Workflow State',
+      summary: 'Get workflow state',
       description:
-        'Get the editable draft graph, including blocks, edges, loop and parallel containers, and variables. Use this state with Replace Workflow State to preserve workspace bindings; Export Workflow removes those bindings for portability. This read records no audit event, and `HEAD` mirrors `GET`.',
+        'Read the saved editable draft, including blocks, edges, loop and parallel containers, and variables. Requires workspace read access. Configured values are included; use this state with Replace workflow state for same-workspace editing, or Export workflow for portable data with registered credential fields cleared. This read records no audit event; `HEAD` mirrors `GET`.',
       /**
        * No `413`: unlike the workflow reads beside it this one resolves no
        * folder path, so it never materializes the workspace's folder tree, and
@@ -333,8 +332,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.replaceState,
       operationId: 'replaceWorkflowState',
-      summary: 'Replace Workflow State',
-      description: `Atomically replace the draft graph; row-locked concurrent writes are last-write-wins. Block, edge, or subflow IDs owned by another workflow return \`409\`. Deployments remain immutable snapshots; schedules and webhook registrations are unchanged. Deploy to publish edits. Lint is advisory. Use \`dryRun=true\` to validate without writing. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Replace workflow state',
+      description: `Replace the draft graph in one write. Requires workspace write access. Concurrent row-locked writes are last-write-wins; IDs owned by another workflow return \`409\`. Deployments, schedules, and webhook registrations are unchanged. Deploy to serve the edits.\n\nLint is advisory. Use \`dryRun=true\` to validate without saving, auditing, or notifying collaborators. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_MUTATION_ERRORS,
       success: jsonSuccess('The draft graph was replaced.'),
     }),
@@ -371,8 +370,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.applyOperations,
       operationId: 'applyWorkflowOperations',
-      summary: 'Apply Workflow Operations',
-      description: `Edit the draft graph and block enablement in one write. Inspect \`skipped\` for failures; do not retry \`deferred\` edges. With \`atomic=true\`, skipped operations or dropped inputs return \`409\` (\`OPERATIONS_NOT_APPLIED\`) without saving. \`mintedBlockIds\` maps labels to generated IDs. Lint is advisory; \`dryRun=true\` validates without saving, auditing, or notifying. The live deployment is unchanged. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Apply workflow operations',
+      description: `Apply draft edits and block enablement changes in one write. Requires workspace write access. The live deployment is unchanged; lint is advisory.\n\nInspect \`skipped\` and \`inputValidationErrors\` for edits that did not apply. Deferred edges apply when their targets exist; do not resubmit them. With \`atomic=true\`, declined operations or dropped inputs return \`409\` (\`OPERATIONS_NOT_APPLIED\`) without saving. Use returned \`mintedBlockIds\` in later requests. \`dryRun=true\` evaluates without saving, auditing, or notifying. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_MUTATION_ERRORS,
       success: jsonSuccess('The batch was applied.'),
     }),
@@ -398,7 +397,7 @@ const declaredRoutes = [
               skipped: [],
               deferred: [],
               inputValidationErrors: [],
-              mintedBlockIds: { triage: 'a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77' },
+              mintedBlockIds: { 'agent-1': 'a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77' },
               lint: {
                 sources: [],
                 sinks: [],
@@ -408,7 +407,7 @@ const declaredRoutes = [
                 invalidConnectionTargets: [],
                 fieldIssues: [
                   {
-                    blockId: 'agent-1',
+                    blockId: 'a3f1c0b2-7a44-4c1d-9d3a-2b8e5f0a1c77',
                     blockName: 'Triage',
                     blockType: 'agent',
                     missingRequiredFields: ['systemPrompt'],
@@ -433,9 +432,9 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.applyVariableOperations,
       operationId: 'applyWorkflowVariables',
-      summary: 'Update Workflow Variables',
+      summary: 'Update workflow variables',
       description:
-        'Add, edit, or delete variables by name, applying operations in order. Values are coerced to their declared type when possible; otherwise they are stored as supplied. A batch with no changes returns `200` with `changed: false`. Read current variables with Get Workflow.',
+        'Add, edit, or delete variables by name with workspace write access. Operations run in order. Values are coerced to their declared type when possible and otherwise stored as supplied. A no-op batch returns `changed: false`; read current values with Get workflow.',
       errors: RESOURCE_MUTATION_ERRORS,
       success: jsonSuccess('The variable set after the batch.'),
     }),
@@ -457,8 +456,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.duplicate,
       operationId: 'duplicateWorkflow',
-      summary: 'Duplicate Workflow',
-      description: `Copy a workflow's graph and variables into the same workspace. Omit \`name\` to reuse the source name; name collisions in the destination folder are resolved automatically. ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'Duplicate workflow',
+      description: `Create an undeployed copy of a workflow's graph and variables in the same workspace. Requires workspace write access. The destination folder and name default to the source; name collisions in the destination are resolved automatically. ${FOLDER_TREE_TOO_LARGE}`,
       errors: RESOURCE_MUTATION_ERRORS,
       success: jsonSuccess('The created copy.'),
     }),
@@ -491,8 +490,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.restore,
       operationId: 'restoreWorkflow',
-      summary: 'Restore Workflow',
-      description: `Restore an archived workflow and the schedules, webhooks, MCP tools, and chats archived with it. An active workflow returns \`409\`. If its folder is archived, the workflow returns to the workspace root. ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'Restore workflow',
+      description: `Restore an archived workflow and its archived schedules, webhooks, MCP tools, and hosted chat. Requires workspace write access. An active workflow returns \`409\`. If its folder is archived, the workflow returns to the workspace root. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_MUTATION_ERRORS, 'PayloadTooLarge'],
       success: jsonSuccess('The restored workflow.'),
     }),
@@ -513,8 +512,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.moveBulk,
       operationId: 'moveWorkflows',
-      summary: 'Move Workflows',
-      description: `Move up to 100 workflows into one folder. Moves succeed or fail independently; missing, archived, or locked workflows appear in \`failed\`. Duplicate IDs are ignored. ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'Move workflows',
+      description: `Move up to 100 workflows to one folder with workspace write access. Each move succeeds or fails independently; missing, archived, or locked workflows appear in \`failed\`. Duplicate IDs are ignored. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...WORKSPACE_ERRORS, 'NotFound'],
       success: jsonSuccess('Which workflows moved and which did not.'),
     }),
@@ -535,8 +534,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.read,
       operationId: 'getWorkflow',
-      summary: 'Get Workflow',
-      description: `Get a workflow with its variables and deployed API-trigger inputs. ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'Get workflow',
+      description: `Get workflow metadata, variables, and trigger input fields from the saved draft. Requires workspace read access. Input fields may differ from the live deployment. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: jsonSuccess('The requested workflow.'),
     }),
@@ -557,8 +556,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.update,
       operationId: 'updateWorkflowV2',
-      summary: 'Update Workflow',
-      description: `Update a workflow's name, description, or folder path. ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'Update workflow',
+      description: `Update a workflow's name, description, or folder path with workspace write access. Omitted fields remain unchanged; \`description: null\` clears the description. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_MUTATION_ERRORS, 'PayloadTooLarge'],
       success: jsonSuccess('The updated workflow.'),
     }),
@@ -580,9 +579,9 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.delete,
       operationId: 'deleteWorkflowV2',
-      summary: 'Delete Workflow',
+      summary: 'Delete workflow',
       description:
-        'Archive a workflow and stop its schedules, webhooks, MCP tools, and chats. Use List Workflows with `scope=archived` to find it and Restore Workflow to recover it and its archived resources. Both `deleted` and `archived` acknowledge archival.',
+        'Archive a workflow and stop its schedules, webhooks, MCP tools, and hosted chat. Requires workspace write access. Find it with List workflows (`scope=archived`) and recover it with Restore workflow. Both `deleted` and `archived` acknowledge archival.',
       errors: [...RESOURCE_ERRORS, 'Locked'],
       success: jsonSuccess('The workflow was archived.'),
     }),
@@ -603,8 +602,9 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.listVersions,
       operationId: 'listWorkflowVersionsV2',
-      summary: 'List Workflow Versions',
-      description: 'List immutable deployment versions of a workflow, newest first.',
+      summary: 'List workflow versions',
+      description:
+        'List saved deployment versions, newest first, with workspace read access. Each version pins an immutable graph; its name and release note can be updated.',
       errors: RESOURCE_ERRORS,
       success: jsonSuccess('A page of deployment versions.'),
     }),
@@ -625,9 +625,9 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.compareVersions,
       operationId: 'compareWorkflowVersionsV2',
-      summary: 'Compare Workflow Versions',
+      summary: 'Compare workflow versions',
       description:
-        'Compare two deployment versions of the same workflow. Reports semantic changes, excluding canvas layout; credential-bearing values are withheld while their changes remain visible. Connections include stable block and port identifiers. The combined snapshots and the comparison result must each fit within 16 MiB.',
+        'Compare two deployment versions of the same workflow with workspace read access. The comparison excludes layout changes and withholds credential-bearing values while reporting their changes. Connections include stable block and port IDs. The combined snapshots and the comparison result must each fit within 16 MiB.',
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: jsonSuccess('Changes from the base deployment to the target deployment.'),
     }),
@@ -674,8 +674,9 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.readVersion,
       operationId: 'getWorkflowVersionV2',
-      summary: 'Get Workflow Version',
-      description: 'Get an immutable deployment version and its pinned workflow graph snapshot.',
+      summary: 'Get workflow version',
+      description:
+        'Get a deployment version and its pinned graph with workspace read access. Registered credential fields and opaque table/tool values are cleared. Environment references and ordinary workflow variables remain included; review other configuration before sharing.',
       errors: RESOURCE_ERRORS,
       success: jsonSuccess('The requested deployment version.'),
     }),
@@ -708,9 +709,9 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.updateVersion,
       operationId: 'updateWorkflowVersionV2',
-      summary: 'Update Workflow Version',
+      summary: 'Update workflow version',
       description:
-        "Update a deployment version's name or release note. Omitted fields remain unchanged; `description: null` clears the note. The graph and live version remain unchanged. Use Activate Workflow Version to make this version live.",
+        "Update a deployment version's name or release note with workspace write access. Omitted fields remain unchanged; `description: null` clears the note. The graph and live version are unchanged. Use Activate workflow version to serve it.",
       errors: RESOURCE_ERRORS,
       success: jsonSuccess('The updated version metadata.'),
     }),
@@ -740,8 +741,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.activateVersion,
       operationId: 'activateWorkflowVersion',
-      summary: 'Activate Workflow Version',
-      description: `Asynchronously activate a specific deployment version, including when the workflow is not currently deployed. The draft remains unchanged. Read Get Workflow Deployment for \`isDeployed\` and \`latestDeploymentAttempt\`. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Activate workflow version',
+      description: `Activate a specific deployment version asynchronously. Requires workspace Admin access and works when the workflow is undeployed. The draft is unchanged. Poll Get workflow deployment for the accepted \`latestDeploymentAttempt\`; \`isDeployed\` alone can describe an older live version. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'Conflict', 'PayloadTooLarge', 'Locked'],
       success: jsonSuccess('The accepted activation attempt.'),
     }),
@@ -786,8 +787,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.revertVersion,
       operationId: 'revertWorkflowVersion',
-      summary: 'Revert Workflow To Version',
-      description: `Replace the editable draft with a deployment version, discarding current draft edits. Use \`active\` for the live version. The live deployment remains unchanged; Activate Workflow Version or Rollback Workflow changes it. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Revert workflow to version',
+      description: `Overwrite the editable draft with a deployment version, discarding current draft edits. Requires workspace Admin access. Use \`active\` for the live version. The live deployment is unchanged; use Activate workflow version or Rollback workflow to change it. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'Conflict', 'PayloadTooLarge', 'Locked'],
       success: jsonSuccess('The draft after it was overwritten.'),
     }),
@@ -809,8 +810,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.read,
       operationId: 'getWorkflowDeployment',
-      summary: 'Get Workflow Deployment',
-      description: `Read live status, deployment time, latest attempt readiness and failure, draft divergence (\`needsRedeployment\`), anonymous execution access (\`isPublicApi\`), and registered webhook URLs. This read exposes public API access and webhook URLs; see their field descriptions for security and delivery details.\n\n${WORKFLOW_DEPLOYMENT_VS_CHAT}`,
+      summary: 'Get workflow deployment',
+      description: `Read live deployment status, the latest attempt's readiness or failure, and draft divergence (\`needsRedeployment\`). Requires workspace read access. \`isPublicApi\` reports anonymous billed execution; \`webhooks\` lists registered delivery URLs.\n\n${WORKFLOW_DEPLOYMENT_VS_CHAT}`,
       errors: RESOURCE_ERRORS,
       success: jsonSuccess('The current deployment state.'),
     }),
@@ -866,8 +867,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.updatePublicApi,
       operationId: 'updateWorkflowPublicApi',
-      summary: 'Update Workflow Public API Access',
-      description: `Enable or disable unauthenticated execution of the deployed workflow. Enabling allows anyone with the execution URL to consume billed usage. Organization sharing restrictions return \`403\` with \`PUBLIC_SHARING_NOT_ALLOWED\`. Hosted chat is managed separately. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update workflow public API access',
+      description: `Enable or disable unauthenticated execution of the deployed workflow. Requires workspace Admin access. Enabling lets anyone with the execution URL consume billed usage. Organization sharing restrictions return \`403\` with \`PUBLIC_SHARING_NOT_ALLOWED\`. Hosted chat is managed separately. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge', 'Locked'],
       success: jsonSuccess('The updated public API setting.'),
     }),
@@ -889,8 +890,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.deploy,
       operationId: 'deployWorkflow',
-      summary: 'Deploy Workflow',
-      description: `Create and asynchronously activate a deployment version. Every call creates a new version; retrying after a timeout can create a duplicate. Read Get Workflow Deployment to check activation. \`lint\` reports advisory findings for the published version; they never block the deploy. A conflicting webhook path returns \`409\`. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Deploy workflow',
+      description: `Create a deployment version and activate it asynchronously. Requires workspace Admin access. Each accepted deploy creates a new version; retrying after a timeout can create a duplicate. Poll Get workflow deployment for the accepted \`latestDeploymentAttempt\` before treating the version as live.\n\n\`lint\` reports advisory findings for this version and never blocks deployment. A conflicting webhook path returns \`409\`. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'Conflict', 'PayloadTooLarge', 'Locked'],
       success: jsonSuccess('The accepted deployment attempt.'),
     }),
@@ -936,8 +937,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.undeploy,
       operationId: 'undeployWorkflow',
-      summary: 'Undeploy Workflow',
-      description: `Deactivate the currently serving workflow version. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Undeploy workflow',
+      description: `Deactivate the live workflow version and stop its scheduled and webhook triggers. Requires workspace Admin access and a deployed workflow. Deployed MCP tools become inactive; \`archivedMcpTools\` identifies them. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'Locked'],
       success: jsonSuccess('The workflow was undeployed.'),
     }),
@@ -970,8 +971,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.activateVersion,
       operationId: 'rollbackWorkflow',
-      summary: 'Rollback Workflow',
-      description: `Asynchronously activate a previous deployment version, defaulting to the preceding active version. Requires a deployed workflow and leaves the draft unchanged. Use Activate Workflow Version to select a version when the workflow is undeployed. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Rollback workflow',
+      description: `Activate a previous deployment version asynchronously, defaulting to the preceding active version. Requires workspace Admin access and a deployed workflow. The draft is unchanged. Poll the accepted \`latestDeploymentAttempt\`. To select a version while undeployed, use Activate workflow version. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'Conflict', 'PayloadTooLarge', 'Locked'],
       success: jsonSuccess('The accepted rollback attempt.'),
     }),
@@ -1016,8 +1017,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.export,
       operationId: 'exportWorkflow',
-      summary: 'Export Workflow',
-      description: `Export a portable, secret-sanitized workflow. Use includeReferences=true for non-secret source identities and field occurrences used by mapped imports. Use includeWorkspaceBindings=true to retain non-secret workspace bindings for a same-workspace round trip; default exports clear those bindings. Credentials and secrets are cleared either way. Exporting records an audit event. ${HEAD_MIRRORS_GET} ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'Export workflow',
+      description: `Export the saved draft as portable workflow data with workspace read access. Registered credential fields and opaque table/tool values are cleared; environment references and ordinary workflow variables remain included. Review other configuration before sharing.\n\nDefault exports clear workspace bindings. Use \`includeWorkspaceBindings=true\` to retain non-secret bindings for a same-workspace import, or \`includeReferences=true\` for source identities and field occurrences used by mapped imports. Exporting records an audit event. ${HEAD_MIRRORS_GET} ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_ERRORS, 'PayloadTooLarge'],
       success: jsonSuccess('The workflow export payload.'),
     }),
@@ -1028,7 +1029,7 @@ const declaredRoutes = [
         v2ExportWorkflowContract.response.schema,
         'ExportWorkflowResponse',
         'Export workflow response',
-        'Portable, secret-sanitized workflow data.',
+        'Portable workflow data with registered credential fields cleared.',
         [
           {
             data: {
@@ -1053,8 +1054,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.import,
       operationId: 'importWorkflow',
-      summary: 'Import Workflow',
-      description: `Create an undeployed workflow from a portable export object, bare state, or JSON string. Mapping options require a preview fingerprint and stable request ID; unresolved required configuration creates nothing. Mapped imports return source-to-imported block IDs and an operation receipt. ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'Import workflow',
+      description: `Create an undeployed workflow from a portable export object, bare draft state, or JSON string. Requires workspace write access. The empty-state example creates a draft that needs runnable blocks before execution.\n\nMapped imports require a preview with the same choices, its \`previewFingerprint\`, and a stable \`requestId\`. Unresolved required configuration creates nothing. Identical retries return the committed result; reusing the ID with changed inputs returns \`409\`. The result includes regenerated graph IDs and an operation receipt. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_MUTATION_ERRORS, 'PayloadTooLarge'],
       success: jsonSuccess('The imported workflow.'),
     }),
@@ -1064,7 +1065,8 @@ const declaredRoutes = [
         v2ImportWorkflowContract.body,
         'ImportWorkflowBody',
         'Import workflow input',
-        'Workflow document, destination, and optional reviewed mappings.'
+        'Workflow document, destination, and optional reviewed mappings. This example creates an empty draft.',
+        [{ workspaceId: WORKSPACE_ID, name: 'Support draft', workflow: { blocks: {}, edges: [] } }]
       ),
       response: documentedSchema(
         v2ImportWorkflowContract.response.schema,
@@ -1099,9 +1101,9 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: chatDeploymentOperations.list,
       operationId: 'listChatDeployments',
-      summary: 'List Chat Deployments',
+      summary: 'List chat deployments',
       description:
-        "List hosted chats and their public URLs with cursor pagination. Filter by `workflowId` for one workflow's chat. The list requires workspace read access; Get Workflow Chat Deployment requires admin access and includes visitor access settings and customizations. Passwords are never returned.",
+        "List hosted chats and their URLs with workspace read access and cursor pagination. Filter by `workflowId` for one workflow's chat. The admin-only detail read also includes visitor access settings and customizations. Passwords are never returned; organization permission groups can restrict chat deployment access.",
       errors: RESOURCE_ERRORS,
       success: jsonSuccess('A page of chat deployments.'),
     }),
@@ -1121,8 +1123,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: chatDeploymentOperations.read,
       operationId: 'getWorkflowChatDeployment',
-      summary: 'Get Workflow Chat Deployment',
-      description: `Get a workflow's hosted chat and visitor access settings. Requires workspace admin access; a missing chat returns \`404\`. Passwords are never returned; \`hasPassword\` indicates whether one is set. Hosted chat and workflow API deployment are managed separately. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get workflow chat deployment',
+      description: `Get a workflow's hosted chat and visitor access settings with workspace Admin access. A missing chat returns \`404\`. Passwords are never returned; \`hasPassword\` reports whether one is set. Hosted chat and workflow API deployment are managed separately. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: jsonSuccess("The workflow's chat deployment."),
     }),
@@ -1143,10 +1145,10 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: chatDeploymentOperations.replace,
       operationId: 'replaceWorkflowChatDeployment',
-      summary: 'Create or Replace Workflow Chat Deployment',
-      description: `Create or replace a workflow's hosted chat and deploy its draft. Omitted fields reset to defaults except per-field customizations. Password authentication requires \`password\`; email or SSO requires non-empty \`allowedEmails\`. Public authentication allows anyone with the chat URL to use it. A duplicate identifier or pending deployment returns \`409\`. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create or replace workflow chat deployment',
+      description: `Create or replace a workflow's hosted chat and deploy its saved draft. Requires workspace Admin access. Omitted fields use defaults; customization exceptions are described on their fields.\n\nPassword authentication requires \`password\`; email or SSO requires non-empty \`allowedEmails\`. Public authentication lets anyone with the chat URL run it. A duplicate identifier or pending deployment returns \`409\`. ${WORKSPACE_API_KEY_DENIED}`,
       errors: [...RESOURCE_ERRORS, 'Conflict', 'PayloadTooLarge', 'Locked'],
-      success: jsonSuccess('The published chat deployment.'),
+      success: jsonSuccess('The saved chat deployment.'),
     }),
     {
       query: v2ReplaceWorkflowChatDeploymentContract.query,
@@ -1166,8 +1168,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: chatDeploymentOperations.delete,
       operationId: 'deleteWorkflowChatDeployment',
-      summary: 'Delete Workflow Chat Deployment',
-      description: `Remove a workflow's hosted chat and release its URL identifier. The workflow API deployment remains active; use Undeploy Workflow to stop it. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Delete workflow chat deployment',
+      description: `Remove the hosted chat and release its URL identifier with workspace Admin access. The workflow API deployment remains active; use Undeploy workflow to stop it. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: jsonSuccess('The chat deployment was removed.'),
     }),
@@ -1188,8 +1190,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.execute,
       operationId: 'executeWorkflowV2',
-      summary: 'Execute Workflow',
-      description: `Execute a deployment or use \`run.source: "manual"\` for the draft. Manual runs require personal or OAuth write access and reject async. Public deployments allow anonymous sync or streaming. Request \`application/x-ndjson\` for heartbeats and the final result. Timeouts return \`200\` with failed status and \`TIMEOUT\`. Supply \`X-Run-Id\` to prevent duplicate execution; reuse returns \`409\`, never a replay. ${EXECUTE_OPTION_CONSTRAINTS}`,
+      summary: 'Execute workflow',
+      description: `Run the active deployment, or set \`run.source: "manual"\` to run the saved draft. Deployed execution requires workspace read access and OAuth \`api:write\` scope or an API key; public deployments also allow anonymous synchronous or streamed runs. Manual runs require personal-key or OAuth write access and cannot be async.\n\nUse \`async: true\` for a queue receipt, or \`stream: true\` for SSE. For a synchronous run with both flags false, send \`Accept: application/x-ndjson\` for heartbeat frames and a final frame containing \`data\`. Timeouts return \`200\` with \`status: "failed"\` and \`error.code: "TIMEOUT"\`; inspect run status. See [Streaming](/workflows/deployment/api#streaming) for event formats. ${EXECUTE_OPTION_CONSTRAINTS}\n\nSupply \`X-Run-Id\` to prevent duplicate execution. Reuse returns \`409\`, without replaying results. A \`503\` with \`error.details.code: "ASYNC_ENQUEUE_AMBIGUOUS"\` omits \`Retry-After\` because the run may already have started. Reconcile using the returned run ID; do not start another run with a new or omitted ID.`,
       errors: [
         'BadRequest',
         'Unauthorized',
@@ -1233,8 +1235,8 @@ const declaredRoutes = [
     workflowRunOperation({
       applicationOperation: workflowOperations.listRuns,
       operationId: 'listWorkflowRunsV2',
-      summary: 'List Workflow Runs',
-      description: `List recorded runs of a workflow with filtering and opaque cursor pagination. ${RUN_RETENTION}`,
+      summary: 'List workflow runs',
+      description: `List recorded workflow runs with workspace read access, filters, and cursor pagination. Cost can be hidden by organization permission groups. ${RUN_RETENTION}`,
       errors: RESOURCE_ERRORS,
       success: jsonSuccess('A page of workflow runs.'),
     }),
@@ -1271,8 +1273,8 @@ const declaredRoutes = [
     workflowRunOperation({
       applicationOperation: workflowOperations.readRun,
       operationId: 'getWorkflowRunV2',
-      summary: 'Get Workflow Run',
-      description: `Get current run state with optional final and block outputs. With \`includeOutput\`, \`files\` includes download paths; \`includeFileBase64\` inlines file bytes and returns \`413\` with the download path when one file or the total exceeds 16 MiB. ${HEAD_MIRRORS_GET}`,
+      summary: 'Get workflow run',
+      description: `Read current run state with workspace read access. Request final output and files with \`includeOutput\`, or block outputs with \`selectedOutputs\`. Organization permission groups can hide output, files, or cost.\n\n\`includeFileBase64\` inlines file bytes. A file or the total above 16 MiB returns \`413\` naming a download path; download large files individually. ${HEAD_MIRRORS_GET}`,
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
       success: jsonSuccess('The workflow run status.'),
     }),
@@ -1320,8 +1322,8 @@ const declaredRoutes = [
     workflowRunOperation({
       applicationOperation: workflowOperations.downloadRunFile,
       operationId: 'downloadWorkflowRunFileV2',
-      summary: 'Download Workflow Run File',
-      description: `Download one run-produced file by ID. Downloads record an audit event. ${RUN_RETENTION} ${HEAD_MIRRORS_GET} ${HEAD_OMITS_PAYLOAD_HEADERS}`,
+      summary: 'Download workflow run file',
+      description: `Download one run-produced file by its reported ID with workspace read access. Downloads record an audit event. ${RUN_RETENTION} ${HEAD_MIRRORS_GET} \`HEAD\` does not provide byte length; use the file's size in Get workflow run when available.`,
       errors: [...RESOURCE_CONFLICT_ERRORS],
       success: {
         description: 'The run file bytes.',
@@ -1339,9 +1341,9 @@ const declaredRoutes = [
     workflowRunOperation({
       applicationOperation: workflowOperations.resumeRun,
       operationId: 'resumeWorkflowRunV2',
-      summary: 'Resume Workflow Run',
+      summary: 'Resume workflow run',
       description:
-        'Resume one human-in-the-loop pause. The resumed attempt receives a new run ID and returns either a synchronous result or a queue receipt.',
+        'Resume one human-in-the-loop pause with workspace write access. The resumed attempt receives a new run ID and returns a synchronous result or queue receipt. A run that originally streamed resumes asynchronously through v2; this endpoint returns no SSE stream.',
       errors: [...RESOURCE_ERRORS, 'UsageLimitExceeded', 'Conflict', 'PayloadTooLarge'],
       success: {
         byStatus: {
@@ -1369,9 +1371,9 @@ const declaredRoutes = [
     workflowRunOperation({
       applicationOperation: workflowOperations.cancelRun,
       operationId: 'cancelRunV2',
-      summary: 'Cancel Workflow Run',
+      summary: 'Cancel workflow run',
       description:
-        'Request cancellation of a running, queued, or paused workflow run. Cancelling a run already in a terminal state is a `200` no-op answered with `success: false` and an `already_*` reason. A run produced by a table workflow group is a `409` when its cell can no longer accept the cancellation.',
+        'Request cancellation of a running, queued, or paused workflow run with workspace write access. Cancellation is best effort; inspect the outcome flags and `reason`. A terminal run returns `200` with `success: false` and an `already_*` reason. A table workflow-group run returns `409` when its cell can no longer accept cancellation.',
       errors: RESOURCE_CONFLICT_ERRORS,
       success: jsonSuccess('The cancellation outcome.'),
     }),
@@ -1404,8 +1406,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.listFolders,
       operationId: 'listWorkflowsFolders',
-      summary: 'List Workflow Folders',
-      description: `List workflow folders in a workspace. ${FULL_SET_LIST} ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'List workflow folders',
+      description: `List workflow folders with workspace read access, optional parent/name filters, and sorting. ${FULL_SET_LIST} ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...WORKSPACE_ERRORS, 'NotFound', 'PayloadTooLarge'],
       success: jsonSuccess('A list of workflow folders.'),
     }),
@@ -1430,8 +1432,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.createFolder,
       operationId: 'createWorkflowsFolder',
-      summary: 'Create Workflow Folder',
-      description: `Create a workflow folder in a workspace. ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'Create workflow folder',
+      description: `Create a workflow folder at a non-root path with workspace write access. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_MUTATION_ERRORS, 'PayloadTooLarge'],
       success: jsonSuccess('The created workflow folder.'),
     }),
@@ -1458,8 +1460,8 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.relocateFolder,
       operationId: 'relocateWorkflowsFolder',
-      summary: 'Rename or Move Workflow Folder',
-      description: `Rename or move a workflow folder and update all descendant paths. ${FOLDER_TREE_TOO_LARGE}`,
+      summary: 'Rename or move workflow folder',
+      description: `Rename or move a workflow folder and update descendant paths with workspace write access. An existing destination receives the folder as a child; otherwise the destination is its new full path. ${FOLDER_TREE_TOO_LARGE}`,
       errors: [...RESOURCE_MUTATION_ERRORS, 'PayloadTooLarge'],
       success: jsonSuccess('The relocated workflow folder.'),
     }),
@@ -1492,9 +1494,9 @@ const declaredRoutes = [
     workflowOperation({
       applicationOperation: workflowOperations.deleteFolder,
       operationId: 'deleteWorkflowsFolder',
-      summary: 'Delete Workflow Folder',
+      summary: 'Delete workflow folder',
       description:
-        'Archive an empty workflow folder, or set `recursive=true` to archive its subfolders and workflows. Use Restore Workflow to recover workflows.',
+        "Archive an empty workflow folder with workspace write access. `recursive=true` also archives its subfolders and workflows, stopping the archived workflows' triggers and hosted surfaces. Use Restore workflow to recover workflows.",
       errors: [...RESOURCE_MUTATION_ERRORS, 'PayloadTooLarge'],
       success: jsonSuccess('The workflow folder was deleted.'),
     }),
diff --git a/apps/sim/lib/api/contracts/v2/openapi/workspace-invitations.ts b/apps/sim/lib/api/contracts/v2/openapi/workspace-invitations.ts
index 1b7abdaa7df..a9f0f2e4a5c 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/workspace-invitations.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/workspace-invitations.ts
@@ -14,8 +14,8 @@ export const workspaceInvitationOpenApiRoutes = [
     {
       applicationOperation: workspaceInvitationOperations.sendBatch,
       operationId: 'createWorkspaceInvitations',
-      summary: 'Create Workspace Invitations',
-      description: `Invite people to a workspace or grant access immediately to existing organization members. Requires workspace administrator access and current invitation eligibility; organization administrator invitations also require organization administrator access. Recipients are processed independently: inspect failed even after HTTP 200, and inspect invitation status before retrying a delivery failure. Existing access is preserved. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Create workspace invitations',
+      description: `Invite people to a workspace or grant access immediately to existing organization members. Requires workspace Admin access and current invitation eligibility; invitations offering organization Admin membership also require organization Admin access. Recipients are processed independently: inspect \`failed\` even after HTTP \`200\`, and inspect invitation status before retrying a delivery failure. Existing access is preserved. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspaces'],
       errors: RESOURCE_CONFLICT_ERRORS,
       success: {
@@ -27,21 +27,21 @@ export const workspaceInvitationOpenApiRoutes = [
       params: documentedSchema(
         v2CreateWorkspaceInvitationsContract.params,
         'CreateWorkspaceInvitationsParams',
-        'Create Workspace Invitations parameters',
+        'Create workspace invitations parameters',
         'Target workspace.'
       ),
       query: v2CreateWorkspaceInvitationsContract.query,
       body: documentedSchema(
         v2CreateWorkspaceInvitationsContract.body,
         'CreateWorkspaceInvitationsBody',
-        'Create Workspace Invitations body',
+        'Create workspace invitations body',
         'Recipients and the access to grant.',
         [{ emails: ['member@example.com'], permission: 'write', membership: 'member' }]
       ),
       response: documentedSchema(
         v2CreateWorkspaceInvitationsContract.response.schema,
         'CreateWorkspaceInvitationsResponse',
-        'Create Workspace Invitations response',
+        'Create workspace invitations response',
         'Successful recipients remain committed when later recipients fail.',
         [
           {
diff --git a/apps/sim/lib/api/contracts/v2/openapi/workspace-permissions.ts b/apps/sim/lib/api/contracts/v2/openapi/workspace-permissions.ts
index 404b2892aed..0e75f341042 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/workspace-permissions.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/workspace-permissions.ts
@@ -14,7 +14,7 @@ export const workspacePermissionOpenApiRoutes = [
     {
       applicationOperation: permissionGroupWorkspaceOperations.readUserConfig,
       operationId: 'getWorkspacePermissionConfig',
-      summary: 'Get Workspace Permission Config',
+      summary: 'Get workspace permission config',
       description: `Get the acting user's governing permission group and configuration for a workspace they can access. This describes permission-group restrictions, not the user's workspace role. Group and config are null when no group governs the caller; entitled indicates whether organization permission governance is active. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspaces'],
       errors: RESOURCE_ERRORS,
@@ -27,14 +27,14 @@ export const workspacePermissionOpenApiRoutes = [
       params: documentedSchema(
         v2GetWorkspacePermissionConfigContract.params,
         'GetWorkspacePermissionConfigParams',
-        'Get Workspace Permission Config parameters',
+        'Get workspace permission config parameters',
         'Target workspace.'
       ),
       query: v2GetWorkspacePermissionConfigContract.query,
       response: documentedSchema(
         v2GetWorkspacePermissionConfigContract.response.schema,
         'GetWorkspacePermissionConfigResponse',
-        'Get Workspace Permission Config response',
+        'Get workspace permission config response',
         'Configuration for the acting caller only.',
         [
           {
diff --git a/apps/sim/lib/api/contracts/v2/openapi/workspace-sync.ts b/apps/sim/lib/api/contracts/v2/openapi/workspace-sync.ts
index 239869709ce..8e622737eba 100644
--- a/apps/sim/lib/api/contracts/v2/openapi/workspace-sync.ts
+++ b/apps/sim/lib/api/contracts/v2/openapi/workspace-sync.ts
@@ -32,42 +32,50 @@ import { workflowOperations } from '@/lib/workflows/application/operations'
 import { workspaceOperations } from '@/lib/workspaces/operations/operations'
 import { forkOperations } from '@/ee/workspace-forking/application/operations'
 
+const FORKING_REQUIREMENT =
+  'Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`.'
+
+const PREVIEW_FINGERPRINT_EXAMPLE =
+  'c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a'
+
 export const workspaceSyncOpenApiRoutes = [
   defineOpenApiRoute(
     v2PreviewWorkspaceForkContract,
     {
       applicationOperation: forkOperations.preview,
       operationId: 'previewWorkspaceFork',
-      summary: 'Preview Workspace Fork',
-      description: `Preview the deployed workflows and explicitly selected resources that a new workspace fork would copy. The result is read-only and supplies the fingerprint required by Fork Workspace. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Preview workspace fork',
+      description: `Preview deployed workflows and explicitly selected resources for a new child workspace. Requires source workspace Admin access and permission to create a workspace in its organization. The read-only result supplies the fingerprint for Fork workspace with the same choices. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: {
+        description: 'Deployed source workflows, selected-copy count, and a preview fingerprint.',
+      },
     },
     {
       params: documentedSchema(
         v2PreviewWorkspaceForkContract.params,
         'PreviewWorkspaceForkParams',
-        'PreviewWorkspaceFork params',
-        'The params for this operation.'
+        'Preview workspace fork path parameters',
+        'Source workspace'
       ),
       query: documentedSchema(
         v2PreviewWorkspaceForkContract.query,
         'PreviewWorkspaceForkQuery',
-        'PreviewWorkspaceFork query',
-        'The query for this operation.'
+        'Preview workspace fork query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2PreviewWorkspaceForkContract.body,
         'PreviewWorkspaceForkBody',
-        'PreviewWorkspaceFork body',
-        'The body for this operation.'
+        'Preview workspace fork request',
+        'Optional child name and explicitly selected resource copies.'
       ),
       response: documentedSchema(
         v2PreviewWorkspaceForkContract.response.schema,
         'PreviewWorkspaceForkResponse',
-        'PreviewWorkspaceFork response',
-        'The response for this operation.'
+        'Preview workspace fork response',
+        'Deployed source workflows, selected-copy count, and a preview fingerprint.'
       ),
     }
   ),
@@ -76,36 +84,57 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.create,
       operationId: 'forkWorkspace',
-      summary: 'Fork Workspace',
-      description: `Create a child workspace with undeployed workflow drafts. Requires the reviewed preview fingerprint and a stable request ID. Identical retries return the same operation; reuse with different inputs returns 409. Poll Get Workspace Operation until selected resource copies complete. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Fork workspace',
+      description: `Create a child workspace with undeployed drafts of the source's deployed workflows. Requires source workspace Admin access and permission to create a workspace in its organization. ${FORKING_REQUIREMENT}\n\nFirst preview the same name and copy choices, then send the returned fingerprint and a stable request ID. The example fingerprint is illustrative. Identical retries return the same committed operation; changed inputs with that ID return \`409\`. Poll Get workspace operation until selected resource copies finish. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: { description: 'Committed fork receipt and resource-copy progress.' },
     },
     {
       params: documentedSchema(
         v2ForkWorkspaceContract.params,
         'ForkWorkspaceParams',
-        'ForkWorkspace params',
-        'The params for this operation.'
+        'Fork workspace path parameters',
+        'Source workspace'
       ),
       query: documentedSchema(
         v2ForkWorkspaceContract.query,
         'ForkWorkspaceQuery',
-        'ForkWorkspace query',
-        'The query for this operation.'
+        'Fork workspace query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2ForkWorkspaceContract.body,
         'ForkWorkspaceBody',
-        'ForkWorkspace body',
-        'The body for this operation.'
+        'Fork workspace request',
+        'Child name and copy choices, with the actual preview fingerprint and a stable request ID.',
+        [
+          {
+            name: 'Support sandbox',
+            requestId: 'fork-support-2026-10-13',
+            previewFingerprint: PREVIEW_FINGERPRINT_EXAMPLE,
+          },
+        ]
       ),
       response: documentedSchema(
         v2ForkWorkspaceContract.response.schema,
         'ForkWorkspaceResponse',
-        'ForkWorkspace response',
-        'The response for this operation.'
+        'Fork workspace response',
+        'Committed fork receipt and resource-copy progress.',
+        [
+          {
+            data: {
+              operationId: 'e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13',
+              requestId: 'fork-support-2026-10-13',
+              workspaceId: '9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94',
+              kind: 'workspace_fork',
+              applied: true,
+              status: 'processing',
+              resourceIds: ['destination_workflow_id'],
+              issues: [],
+            },
+          },
+        ]
       ),
     }
   ),
@@ -114,36 +143,39 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.syncPreview,
       operationId: 'previewWorkspacePush',
-      summary: 'Preview Workspace Push',
-      description: `Preview deployed source workflows replacing mapped targets along a direct fork edge. Push sends the current workspace to the other; pull brings the other into the current workspace. Proposed mappings are not saved. Dependent choices use source workflow, block, and field identities. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Preview workspace push',
+      description: `Preview changes from this workspace into the other workspace along a direct fork edge. Requires Admin access to both workspaces. The plan lists workflows to create, replace, or archive; replacements overwrite target drafts with the source deployment. Proposed mappings are not saved. Dependent choices use source workflow, block, and field IDs. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: {
+        description:
+          'Current-to-other workflow actions, required choices, and preview fingerprint.',
+      },
     },
     {
       params: documentedSchema(
         v2PreviewWorkspacePushContract.params,
         'PreviewWorkspacePushParams',
-        'PreviewWorkspacePush params',
-        'The params for this operation.'
+        'Preview workspace push path parameters',
+        'Acting source workspace'
       ),
       query: documentedSchema(
         v2PreviewWorkspacePushContract.query,
         'PreviewWorkspacePushQuery',
-        'PreviewWorkspacePush query',
-        'The query for this operation.'
+        'Preview workspace push query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2PreviewWorkspacePushContract.body,
         'PreviewWorkspacePushBody',
-        'PreviewWorkspacePush body',
-        'The body for this operation.'
+        'Preview workspace push request',
+        'Other workspace and proposed source-to-target sync choices.'
       ),
       response: documentedSchema(
         v2PreviewWorkspacePushContract.response.schema,
         'PreviewWorkspacePushResponse',
-        'PreviewWorkspacePush response',
-        'The response for this operation.'
+        'Preview workspace push response',
+        'Current-to-other workflow actions, required choices, and preview fingerprint.'
       ),
     }
   ),
@@ -152,36 +184,58 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.sync,
       operationId: 'pushWorkspace',
-      summary: 'Push Workspace',
-      description: `Apply a reviewed push or pull with inline mappings in one transaction. Requires confirmation, the preview fingerprint, and a stable request ID. Unresolved or changed plans return 409 without applying. The receipt distinguishes committed changes from copy and deployment readiness; poll Get Workspace Operation before treating the target as ready. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Push workspace',
+      description: `Apply a reviewed sync from this workspace into the other workspace along a direct fork edge. Requires Admin access to both workspaces. Creates unmatched deployed workflows, overwrites mapped target drafts, and archives mapped targets whose sources were deleted or archived. Undeployed sources alone do not archive targets. ${FORKING_REQUIREMENT}\n\nSend \`confirm: true\`, the fingerprint from a preview with identical choices, and a stable request ID. The example hash is illustrative. Changed or unresolved plans return \`409\` without applying. Identical retries return the committed operation; changed inputs with that ID return \`409\`. Copies and deployment activation can finish after the transaction commits. Poll Get workspace operation before treating the target as ready. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: { description: 'Committed push receipt with copy and deployment readiness.' },
     },
     {
       params: documentedSchema(
         v2PushWorkspaceContract.params,
         'PushWorkspaceParams',
-        'PushWorkspace params',
-        'The params for this operation.'
+        'Push workspace path parameters',
+        'Acting source workspace'
       ),
       query: documentedSchema(
         v2PushWorkspaceContract.query,
         'PushWorkspaceQuery',
-        'PushWorkspace query',
-        'The query for this operation.'
+        'Push workspace query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2PushWorkspaceContract.body,
         'PushWorkspaceBody',
-        'PushWorkspace body',
-        'The body for this operation.'
+        'Push workspace request',
+        'Confirmed current-to-other choices, actual preview fingerprint, and stable request ID.',
+        [
+          {
+            otherWorkspaceId: '9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94',
+            requestId: 'push-support-2026-10-13',
+            previewFingerprint: PREVIEW_FINGERPRINT_EXAMPLE,
+            confirm: true,
+          },
+        ]
       ),
       response: documentedSchema(
         v2PushWorkspaceContract.response.schema,
         'PushWorkspaceResponse',
-        'PushWorkspace response',
-        'The response for this operation.'
+        'Push workspace response',
+        'Committed push receipt with copy and deployment readiness.',
+        [
+          {
+            data: {
+              operationId: 'e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13',
+              requestId: 'push-support-2026-10-13',
+              workspaceId: '9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94',
+              kind: 'workspace_push',
+              applied: true,
+              status: 'processing',
+              resourceIds: ['destination_workflow_id'],
+              issues: [],
+            },
+          },
+        ]
       ),
     }
   ),
@@ -190,36 +244,39 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.syncPreview,
       operationId: 'previewWorkspacePull',
-      summary: 'Preview Workspace Pull',
-      description: `Preview deployed source workflows replacing mapped targets along a direct fork edge. Push sends the current workspace to the other; pull brings the other into the current workspace. Proposed mappings are not saved. Dependent choices use source workflow, block, and field identities. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Preview workspace pull',
+      description: `Preview changes from the other workspace into this workspace along a direct fork edge. Requires Admin access to both workspaces. The plan lists workflows to create, replace, or archive; replacements overwrite target drafts with the source deployment. Proposed mappings are not saved. Dependent choices use source workflow, block, and field IDs. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: {
+        description:
+          'Other-to-current workflow actions, required choices, and preview fingerprint.',
+      },
     },
     {
       params: documentedSchema(
         v2PreviewWorkspacePullContract.params,
         'PreviewWorkspacePullParams',
-        'PreviewWorkspacePull params',
-        'The params for this operation.'
+        'Preview workspace pull path parameters',
+        'Acting target workspace'
       ),
       query: documentedSchema(
         v2PreviewWorkspacePullContract.query,
         'PreviewWorkspacePullQuery',
-        'PreviewWorkspacePull query',
-        'The query for this operation.'
+        'Preview workspace pull query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2PreviewWorkspacePullContract.body,
         'PreviewWorkspacePullBody',
-        'PreviewWorkspacePull body',
-        'The body for this operation.'
+        'Preview workspace pull request',
+        'Other workspace and proposed source-to-target sync choices.'
       ),
       response: documentedSchema(
         v2PreviewWorkspacePullContract.response.schema,
         'PreviewWorkspacePullResponse',
-        'PreviewWorkspacePull response',
-        'The response for this operation.'
+        'Preview workspace pull response',
+        'Other-to-current workflow actions, required choices, and preview fingerprint.'
       ),
     }
   ),
@@ -228,36 +285,58 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.sync,
       operationId: 'pullWorkspace',
-      summary: 'Pull Workspace',
-      description: `Apply a reviewed push or pull with inline mappings in one transaction. Requires confirmation, the preview fingerprint, and a stable request ID. Unresolved or changed plans return 409 without applying. The receipt distinguishes committed changes from copy and deployment readiness; poll Get Workspace Operation before treating the target as ready. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Pull workspace',
+      description: `Apply a reviewed sync from the other workspace into this workspace along a direct fork edge. Requires Admin access to both workspaces. Creates unmatched deployed workflows, overwrites mapped target drafts, and archives mapped targets whose sources were deleted or archived. Undeployed sources alone do not archive targets. ${FORKING_REQUIREMENT}\n\nSend \`confirm: true\`, the fingerprint from a preview with identical choices, and a stable request ID. The example hash is illustrative. Changed or unresolved plans return \`409\` without applying. Identical retries return the committed operation; changed inputs with that ID return \`409\`. Copies and deployment activation can finish after the transaction commits. Poll Get workspace operation before treating the target as ready. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: { description: 'Committed pull receipt with copy and deployment readiness.' },
     },
     {
       params: documentedSchema(
         v2PullWorkspaceContract.params,
         'PullWorkspaceParams',
-        'PullWorkspace params',
-        'The params for this operation.'
+        'Pull workspace path parameters',
+        'Acting target workspace'
       ),
       query: documentedSchema(
         v2PullWorkspaceContract.query,
         'PullWorkspaceQuery',
-        'PullWorkspace query',
-        'The query for this operation.'
+        'Pull workspace query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2PullWorkspaceContract.body,
         'PullWorkspaceBody',
-        'PullWorkspace body',
-        'The body for this operation.'
+        'Pull workspace request',
+        'Confirmed other-to-current choices, actual preview fingerprint, and stable request ID.',
+        [
+          {
+            otherWorkspaceId: '9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94',
+            requestId: 'pull-support-2026-10-13',
+            previewFingerprint: PREVIEW_FINGERPRINT_EXAMPLE,
+            confirm: true,
+          },
+        ]
       ),
       response: documentedSchema(
         v2PullWorkspaceContract.response.schema,
         'PullWorkspaceResponse',
-        'PullWorkspace response',
-        'The response for this operation.'
+        'Pull workspace response',
+        'Committed pull receipt with copy and deployment readiness.',
+        [
+          {
+            data: {
+              operationId: 'e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13',
+              requestId: 'pull-support-2026-10-13',
+              workspaceId: '9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94',
+              kind: 'workspace_pull',
+              applied: true,
+              status: 'processing',
+              resourceIds: ['destination_workflow_id'],
+              issues: [],
+            },
+          },
+        ]
       ),
     }
   ),
@@ -266,30 +345,32 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.discover,
       operationId: 'getWorkspaceForkAvailability',
-      summary: 'Get Workspace Fork Availability',
-      description: `Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get workspace fork availability',
+      description: `Check whether workspace forking is enabled for this deployment and workspace plan. Requires workspace Admin access. Returns \`available: false\` when the feature gate is unmet. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: {
+        description: 'Whether forking is enabled for this deployment and workspace plan.',
+      },
     },
     {
       params: documentedSchema(
         v2GetWorkspaceForkAvailabilityContract.params,
         'GetWorkspaceForkAvailabilityParams',
-        'GetWorkspaceForkAvailability params',
-        'The params for this operation.'
+        'Get workspace fork availability path parameters',
+        'Workspace to check'
       ),
       query: documentedSchema(
         v2GetWorkspaceForkAvailabilityContract.query,
         'GetWorkspaceForkAvailabilityQuery',
-        'GetWorkspaceForkAvailability query',
-        'The query for this operation.'
+        'Get workspace fork availability query',
+        'No query parameters.'
       ),
       response: documentedSchema(
         v2GetWorkspaceForkAvailabilityContract.response.schema,
         'GetWorkspaceForkAvailabilityResponse',
-        'GetWorkspaceForkAvailability response',
-        'The response for this operation.'
+        'Get workspace fork availability response',
+        'Whether forking is enabled for this deployment and workspace plan.'
       ),
     }
   ),
@@ -298,30 +379,30 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.discover,
       operationId: 'getWorkspaceForkLineage',
-      summary: 'Get Workspace Fork Lineage',
-      description: `Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get workspace fork lineage',
+      description: `Read this workspace and its direct parent, or \`parent: null\` when it has no active parent. Requires workspace Admin access. The relationship does not grant access to the parent. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: { description: 'Current workspace and its active direct parent, when present.' },
     },
     {
       params: documentedSchema(
         v2GetWorkspaceForkLineageContract.params,
         'GetWorkspaceForkLineageParams',
-        'GetWorkspaceForkLineage params',
-        'The params for this operation.'
+        'Get workspace fork lineage path parameters',
+        'Workspace to inspect'
       ),
       query: documentedSchema(
         v2GetWorkspaceForkLineageContract.query,
         'GetWorkspaceForkLineageQuery',
-        'GetWorkspaceForkLineage query',
-        'The query for this operation.'
+        'Get workspace fork lineage query',
+        'No query parameters.'
       ),
       response: documentedSchema(
         v2GetWorkspaceForkLineageContract.response.schema,
         'GetWorkspaceForkLineageResponse',
-        'GetWorkspaceForkLineage response',
-        'The response for this operation.'
+        'Get workspace fork lineage response',
+        'Current workspace and its active direct parent, when present.'
       ),
     }
   ),
@@ -330,30 +411,30 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.discover,
       operationId: 'listWorkspaceForkChildren',
-      summary: 'List Workspace Fork Children',
-      description: `Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List workspace fork children',
+      description: `List this workspace's active direct children, newest first, with cursor pagination. Requires workspace Admin access. A fork relationship does not grant access to a child workspace. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: { description: 'A page of active direct child workspaces.' },
     },
     {
       params: documentedSchema(
         v2ListWorkspaceForkChildrenContract.params,
         'ListWorkspaceForkChildrenParams',
-        'ListWorkspaceForkChildren params',
-        'The params for this operation.'
+        'List workspace fork children path parameters',
+        'Parent workspace'
       ),
       query: documentedSchema(
         v2ListWorkspaceForkChildrenContract.query,
         'ListWorkspaceForkChildrenQuery',
-        'ListWorkspaceForkChildren query',
-        'The query for this operation.'
+        'List workspace fork children query',
+        'Pagination for active direct children, newest first.'
       ),
       response: documentedSchema(
         v2ListWorkspaceForkChildrenContract.response.schema,
         'ListWorkspaceForkChildrenResponse',
-        'ListWorkspaceForkChildren response',
-        'The response for this operation.'
+        'List workspace fork children response',
+        'A page of active direct child workspaces.'
       ),
     }
   ),
@@ -362,30 +443,30 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.discover,
       operationId: 'listWorkspaceForkResources',
-      summary: 'List Workspace Fork Resources',
-      description: `Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List workspace fork resources',
+      description: `List copyable resources of one kind in this workspace with cursor pagination. Requires workspace Admin access. Fork creation uses file IDs; sync copy choices use file storage keys from source references or file resource reads. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: { description: 'A page of copyable resource candidates.' },
     },
     {
       params: documentedSchema(
         v2ListWorkspaceForkResourcesContract.params,
         'ListWorkspaceForkResourcesParams',
-        'ListWorkspaceForkResources params',
-        'The params for this operation.'
+        'List workspace fork resources path parameters',
+        'Source workspace'
       ),
       query: documentedSchema(
         v2ListWorkspaceForkResourcesContract.query,
         'ListWorkspaceForkResourcesQuery',
-        'ListWorkspaceForkResources query',
-        'The query for this operation.'
+        'List workspace fork resources query',
+        'Resource kind and cursor pagination.'
       ),
       response: documentedSchema(
         v2ListWorkspaceForkResourcesContract.response.schema,
         'ListWorkspaceForkResourcesResponse',
-        'ListWorkspaceForkResources response',
-        'The response for this operation.'
+        'List workspace fork resources response',
+        'A page of copyable resource candidates.'
       ),
     }
   ),
@@ -394,30 +475,30 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.mappingsRead,
       operationId: 'getWorkspaceForkMappings',
-      summary: 'Get Workspace Fork Mappings',
-      description: `Read persisted mappings in the requested source-to-target direction. Candidate discovery uses the destination resource and selector listing operations. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get workspace fork mappings',
+      description: `Read persisted resource mappings in the requested source-to-target direction along a direct fork edge. Requires Admin access to both workspaces. Discover candidates with destination resource reads and selector operations. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: { description: 'A page of persisted source-to-target mapping entries.' },
     },
     {
       params: documentedSchema(
         v2GetWorkspaceForkMappingsContract.params,
         'GetWorkspaceForkMappingsParams',
-        'GetWorkspaceForkMappings params',
-        'The params for this operation.'
+        'Get workspace fork mappings path parameters',
+        'Acting workspace'
       ),
       query: documentedSchema(
         v2GetWorkspaceForkMappingsContract.query,
         'GetWorkspaceForkMappingsQuery',
-        'GetWorkspaceForkMappings query',
-        'The query for this operation.'
+        'Get workspace fork mappings query',
+        'Other workspace, direction, and mapping pagination.'
       ),
       response: documentedSchema(
         v2GetWorkspaceForkMappingsContract.response.schema,
         'GetWorkspaceForkMappingsResponse',
-        'GetWorkspaceForkMappings response',
-        'The response for this operation.'
+        'Get workspace fork mappings response',
+        'A page of persisted source-to-target mapping entries.'
       ),
     }
   ),
@@ -426,36 +507,36 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.mappingsUpdate,
       operationId: 'updateWorkspaceForkMappings',
-      summary: 'Update Workspace Fork Mappings',
-      description: `Update edge mappings after validating destination resource membership and credential provider compatibility. Push addresses current-to-other mappings; pull addresses other-to-current mappings. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update workspace fork mappings',
+      description: `Update mappings along a direct fork edge with Admin access to both workspaces. Destination resource membership and credential provider compatibility are validated. Push maps current-to-other; pull maps other-to-current. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: { description: 'Number of mapping records changed.' },
     },
     {
       params: documentedSchema(
         v2UpdateWorkspaceForkMappingsContract.params,
         'UpdateWorkspaceForkMappingsParams',
-        'UpdateWorkspaceForkMappings params',
-        'The params for this operation.'
+        'Update workspace fork mappings path parameters',
+        'Acting workspace'
       ),
       query: documentedSchema(
         v2UpdateWorkspaceForkMappingsContract.query,
         'UpdateWorkspaceForkMappingsQuery',
-        'UpdateWorkspaceForkMappings query',
-        'The query for this operation.'
+        'Update workspace fork mappings query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2UpdateWorkspaceForkMappingsContract.body,
         'UpdateWorkspaceForkMappingsBody',
-        'UpdateWorkspaceForkMappings body',
-        'The body for this operation.'
+        'Update workspace fork mappings request',
+        'Other workspace, direction, and mapping entries to update.'
       ),
       response: documentedSchema(
         v2UpdateWorkspaceForkMappingsContract.response.schema,
         'UpdateWorkspaceForkMappingsResponse',
-        'UpdateWorkspaceForkMappings response',
-        'The response for this operation.'
+        'Update workspace fork mappings response',
+        'Number of mapping records changed.'
       ),
     }
   ),
@@ -464,36 +545,38 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.rollback,
       operationId: 'rollbackWorkspaceFork',
-      summary: 'Rollback Workspace Fork',
-      description: `Restore the latest sync into this workspace using its prior deployed versions. Requires target admin. It does not restore arbitrary drafts or remove every copied resource. Pending activations are reported. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Rollback workspace fork',
+      description: `Restore the latest sync into this workspace from the named other workspace using prior deployed versions. Requires target workspace Admin access. A newer sync from another fork edge returns \`409\`. Arbitrary draft edits and copied resources are not restored or removed. Inspect \`pendingActivations\`; retry rollback if activation remains unfinished. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: {
+        description: 'Restored, archived, skipped, and still-activating workflow counts.',
+      },
     },
     {
       params: documentedSchema(
         v2RollbackWorkspaceForkContract.params,
         'RollbackWorkspaceForkParams',
-        'RollbackWorkspaceFork params',
-        'The params for this operation.'
+        'Rollback workspace fork path parameters',
+        'Workspace receiving the rollback'
       ),
       query: documentedSchema(
         v2RollbackWorkspaceForkContract.query,
         'RollbackWorkspaceForkQuery',
-        'RollbackWorkspaceFork query',
-        'The query for this operation.'
+        'Rollback workspace fork query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2RollbackWorkspaceForkContract.body,
         'RollbackWorkspaceForkBody',
-        'RollbackWorkspaceFork body',
-        'The body for this operation.'
+        'Rollback workspace fork request',
+        'Other workspace whose latest inbound sync should be undone.'
       ),
       response: documentedSchema(
         v2RollbackWorkspaceForkContract.response.schema,
         'RollbackWorkspaceForkResponse',
-        'RollbackWorkspaceFork response',
-        'The response for this operation.'
+        'Rollback workspace fork response',
+        'Restored, archived, skipped, and still-activating workflow counts.'
       ),
     }
   ),
@@ -502,36 +585,36 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.unlink,
       operationId: 'unlinkWorkspaceFork',
-      summary: 'Unlink Workspace Fork',
-      description: `Remove the direct fork relationship and its mappings. Requires admin on the acting workspace. Existing workflow and resource content remains available. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Unlink workspace fork',
+      description: `Remove the direct fork relationship and its mappings with Admin access to the acting workspace. Existing workflows and resources remain available. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: { description: 'Confirmation that the relationship was removed.' },
     },
     {
       params: documentedSchema(
         v2UnlinkWorkspaceForkContract.params,
         'UnlinkWorkspaceForkParams',
-        'UnlinkWorkspaceFork params',
-        'The params for this operation.'
+        'Unlink workspace fork path parameters',
+        'Workspace severing the relationship'
       ),
       query: documentedSchema(
         v2UnlinkWorkspaceForkContract.query,
         'UnlinkWorkspaceForkQuery',
-        'UnlinkWorkspaceFork query',
-        'The query for this operation.'
+        'Unlink workspace fork query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2UnlinkWorkspaceForkContract.body,
         'UnlinkWorkspaceForkBody',
-        'UnlinkWorkspaceFork body',
-        'The body for this operation.'
+        'Unlink workspace fork request',
+        'Other workspace on the direct fork edge to remove.'
       ),
       response: documentedSchema(
         v2UnlinkWorkspaceForkContract.response.schema,
         'UnlinkWorkspaceForkResponse',
-        'UnlinkWorkspaceFork response',
-        'The response for this operation.'
+        'Unlink workspace fork response',
+        'Confirmation that the relationship was removed.'
       ),
     }
   ),
@@ -540,36 +623,36 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: forkOperations.exclusions,
       operationId: 'updateWorkspaceForkExclusions',
-      summary: 'Update Workspace Fork Exclusions',
-      description: `Include or exclude selected workflows from fork sync. Excluded workflows are skipped as sources and targets. Missing, archived, and unchanged workflow IDs are skipped. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Update workspace fork exclusions',
+      description: `Include or exclude selected workflows from fork sync with workspace Admin access. Excluded workflows are skipped as sources and targets. Missing, archived, and unchanged workflow IDs are skipped. ${FORKING_REQUIREMENT} ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The workspace operation result.' },
+      success: { description: 'Number of workflow exclusion flags changed.' },
     },
     {
       params: documentedSchema(
         v2UpdateWorkspaceForkExclusionsContract.params,
         'UpdateWorkspaceForkExclusionsParams',
-        'UpdateWorkspaceForkExclusions params',
-        'The params for this operation.'
+        'Update workspace fork exclusions path parameters',
+        'Workspace holding the workflows'
       ),
       query: documentedSchema(
         v2UpdateWorkspaceForkExclusionsContract.query,
         'UpdateWorkspaceForkExclusionsQuery',
-        'UpdateWorkspaceForkExclusions query',
-        'The query for this operation.'
+        'Update workspace fork exclusions query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2UpdateWorkspaceForkExclusionsContract.body,
         'UpdateWorkspaceForkExclusionsBody',
-        'UpdateWorkspaceForkExclusions body',
-        'The body for this operation.'
+        'Update workspace fork exclusions request',
+        'Workflow IDs and whether to exclude them from sync.'
       ),
       response: documentedSchema(
         v2UpdateWorkspaceForkExclusionsContract.response.schema,
         'UpdateWorkspaceForkExclusionsResponse',
-        'UpdateWorkspaceForkExclusions response',
-        'The response for this operation.'
+        'Update workspace fork exclusions response',
+        'Number of workflow exclusion flags changed.'
       ),
     }
   ),
@@ -578,25 +661,29 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: workflowOperations.importPreview,
       operationId: 'previewWorkflowImport',
-      summary: 'Preview Workflow Import',
-      description: `Validate destination mappings and dependent choices without creating a workflow. Returns unresolved fields, discovery instructions, and a fingerprint required by mapped import. No source workspace is queried from imported provenance.`,
+      summary: 'Preview workflow import',
+      description:
+        'Validate destination mappings and configuration with workspace write access, without creating a workflow. The result reports readiness, unresolved fields, discovery instructions, and a fingerprint for mapped import with the same choices. Imported provenance never authorizes or queries a source workspace.',
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The operation result.' },
+      success: {
+        description:
+          'Import readiness, unresolved bindings, and destination discovery instructions.',
+      },
     },
     {
       query: documentedSchema(
         v2PreviewWorkflowImportContract.query,
         'PreviewWorkflowImportQuery',
-        'PreviewWorkflowImport query',
-        'The query for this operation.'
+        'Preview workflow import query',
+        'No query parameters.'
       ),
       body: v2PreviewWorkflowImportContract.body,
       response: documentedSchema(
         v2PreviewWorkflowImportContract.response.schema,
         'PreviewWorkflowImportResponse',
-        'PreviewWorkflowImport response',
-        'The response for this operation.'
+        'Preview workflow import response',
+        'Import readiness, unresolved bindings, and destination discovery instructions.'
       ),
     }
   ),
@@ -605,30 +692,32 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: selectorOperations.execute,
       operationId: 'listSelector',
-      summary: 'List Selector Options',
-      description: `List workspace-scoped configuration choices using the selector key and dependencies from an import or sync preview. Missing OAuth connections require human authorization before provider choices can be discovered. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'List selector options',
+      description: `List authorized workspace configuration choices using the selector key and context from an import or sync preview. Requires workspace read access. Missing OAuth connections require human authorization. Keep workspace, selector, context, and search unchanged while paging; a changed provider page returns \`409\` and requires restarting without a cursor. Provider pages above 8 MiB return \`413\`; narrow the search. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The operation result.' },
+      success: {
+        description: 'A page of authorized options, continuation cursor, and truncation status.',
+      },
     },
     {
       query: documentedSchema(
         v2ListSelectorContract.query,
         'ListSelectorQuery',
-        'ListSelector query',
-        'The query for this operation.'
+        'List selector query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2ListSelectorContract.body,
         'ListSelectorBody',
-        'ListSelector body',
-        'The body for this operation.'
+        'List selector request',
+        'Workspace, registered selector key, context, and optional search/cursor.'
       ),
       response: documentedSchema(
         v2ListSelectorContract.response.schema,
         'ListSelectorResponse',
-        'ListSelector response',
-        'The response for this operation.'
+        'List selector response',
+        'A page of authorized options, continuation cursor, and truncation status.'
       ),
     }
   ),
@@ -637,30 +726,32 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: selectorOperations.execute,
       operationId: 'getSelector',
-      summary: 'Get Selector Option',
-      description: `Resolve a workspace configuration option by its provider identifier and declared dependencies. ${WORKSPACE_API_KEY_DENIED}`,
+      summary: 'Get selector option',
+      description: `Get an authorized configuration choice by provider ID and declared context with workspace read access. Returns \`data: null\` when the option is absent from complete results. Truncated results or pagination limits that prevent verification return \`413\`; a list-only lookup checks at most 100 pages or 10,000 options. ${WORKSPACE_API_KEY_DENIED}`,
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The operation result.' },
+      success: {
+        description: 'The authorized option, or data:null when absent from complete results.',
+      },
     },
     {
       query: documentedSchema(
         v2GetSelectorContract.query,
         'GetSelectorQuery',
-        'GetSelector query',
-        'The query for this operation.'
+        'Get selector query',
+        'No query parameters.'
       ),
       body: documentedSchema(
         v2GetSelectorContract.body,
         'GetSelectorBody',
-        'GetSelector body',
-        'The body for this operation.'
+        'Get selector request',
+        'Workspace, registered selector key, context, and provider option ID.'
       ),
       response: documentedSchema(
         v2GetSelectorContract.response.schema,
         'GetSelectorResponse',
-        'GetSelector response',
-        'The response for this operation.'
+        'Get selector response',
+        'The authorized option, or data:null when absent from complete results.'
       ),
     }
   ),
@@ -669,30 +760,31 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: workspaceOperations.read,
       operationId: 'getWorkspaceOperation',
-      summary: 'Get Workspace Operation',
-      description: `Read a committed operation, copy progress, exact deployment readiness, and structured issues. A failed follow-up does not mean the business transaction was rolled back.`,
+      summary: 'Get workspace operation',
+      description:
+        'Read a committed operation and refresh its copy progress, exact admitted deployment readiness, and structured issues with workspace read access. `applied: true` means the transaction committed even if follow-up work failed. This read does not require the fork-specific Admin role or feature gate.',
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The operation result.' },
+      success: { description: 'Refreshed commit, copy progress, and exact deployment readiness.' },
     },
     {
       query: documentedSchema(
         v2GetWorkspaceOperationContract.query,
         'GetWorkspaceOperationQuery',
-        'GetWorkspaceOperation query',
-        'The query for this operation.'
+        'Get workspace operation query',
+        'No query parameters.'
       ),
       params: documentedSchema(
         v2GetWorkspaceOperationContract.params,
         'GetWorkspaceOperationParams',
-        'GetWorkspaceOperation params',
-        'The params for this operation.'
+        'Get workspace operation path parameters',
+        'Workspace and committed operation ID'
       ),
       response: documentedSchema(
         v2GetWorkspaceOperationContract.response.schema,
         'GetWorkspaceOperationResponse',
-        'GetWorkspaceOperation response',
-        'The response for this operation.'
+        'Get workspace operation response',
+        'Refreshed commit, copy progress, and exact deployment readiness.'
       ),
     }
   ),
@@ -701,30 +793,31 @@ export const workspaceSyncOpenApiRoutes = [
     {
       applicationOperation: workspaceOperations.read,
       operationId: 'listWorkspaceOperations',
-      summary: 'List Workspace Operations',
-      description: `Page committed operations newest first. Filter by the original request ID to reconcile an uncertain mutation response.`,
+      summary: 'List workspace operations',
+      description:
+        'List stored operation receipts newest first with workspace read access. Filter by the original `requestId` to reconcile an uncertain mutation response. Read an individual operation to refresh its copy and deployment readiness. This list does not require the fork-specific Admin role or feature gate.',
       tags: ['Workspace Sync'],
       errors: [...RESOURCE_CONFLICT_ERRORS, 'PayloadTooLarge'],
-      success: { description: 'The operation result.' },
+      success: { description: 'A page of stored operation receipts.' },
     },
     {
       query: documentedSchema(
         v2ListWorkspaceOperationsContract.query,
         'ListWorkspaceOperationsQuery',
-        'ListWorkspaceOperations query',
-        'The query for this operation.'
+        'List workspace operations query',
+        'Request ID filter and newest-first cursor pagination.'
       ),
       params: documentedSchema(
         v2ListWorkspaceOperationsContract.params,
         'ListWorkspaceOperationsParams',
-        'ListWorkspaceOperations params',
-        'The params for this operation.'
+        'List workspace operations path parameters',
+        'Workspace whose receipts to list'
       ),
       response: documentedSchema(
         v2ListWorkspaceOperationsContract.response.schema,
         'ListWorkspaceOperationsResponse',
-        'ListWorkspaceOperations response',
-        'The response for this operation.'
+        'List workspace operations response',
+        'A page of stored operation receipts.'
       ),
     }
   ),
diff --git a/apps/sim/lib/api/contracts/v2/permission-groups.ts b/apps/sim/lib/api/contracts/v2/permission-groups.ts
index fa378390402..eaaf6314694 100644
--- a/apps/sim/lib/api/contracts/v2/permission-groups.ts
+++ b/apps/sim/lib/api/contracts/v2/permission-groups.ts
@@ -48,12 +48,12 @@ export const v2PermissionGroupSchema = z
     isDefault: z
       .boolean()
       .describe(
-        'Whether this is the organization default, which applies to everyone across all its workspaces regardless of member assignments.'
+        'Whether this is the organization fallback group. It governs a human caller with no applicable workspace-specific group; its own membership assignments do not limit its audience. Organization-level actions use the default group.'
       ),
     membershipMode: z
       .string()
       .describe(
-        'An empty inherit group governs everyone in its workspaces; an empty explicit group governs nobody.'
+        'When no explicit assignments exist, an `inherit` group governs every member in its targeted workspaces. An empty `explicit` group, including a SCIM-managed group, governs nobody.'
       ),
     workspaceIds: z
       .array(z.string())
@@ -65,7 +65,8 @@ export const v2PermissionGroupSchema = z
   .meta({
     id: 'V2PermissionGroup',
     title: 'Permission group',
-    description: 'An organization permission group and its resolved settings.',
+    description:
+      'An organization permission group and its resolved settings for human callers. Workspace API keys use their workspace role and operation policy without a user permission group.',
   })
 export type V2PermissionGroup = z.output<typeof v2PermissionGroupSchema>
 
diff --git a/apps/sim/lib/api/contracts/v2/secrets.ts b/apps/sim/lib/api/contracts/v2/secrets.ts
index bc25ae81d82..6f80d164e15 100644
--- a/apps/sim/lib/api/contracts/v2/secrets.ts
+++ b/apps/sim/lib/api/contracts/v2/secrets.ts
@@ -51,7 +51,7 @@ export const v2SecretSchema = z
   .meta({
     id: 'V2Secret',
     title: 'Secret metadata',
-    description: 'Public secret metadata without the stored secret value.',
+    description: 'Secret metadata without the stored value.',
   })
 export type V2Secret = z.output<typeof v2SecretSchema>
 
@@ -133,7 +133,7 @@ export const v2SetSecretBodySchema = z
       .max(65_536, 'value is too long')
       .optional()
       .describe(
-        'Write-only secret value. It is never returned. Omit it on a workspace secret to change description or unredacted alone, leaving the stored value untouched; the secret must already exist. Always required for a personal secret, which carries no other writable field.'
+        'Secret value, omitted from the Set secret response. For an existing workspace secret, omit it to change only `description` or `unredacted`. Personal secrets always require a value and accept no writable metadata.'
       )
       .meta({ writeOnly: true }),
     description: z
diff --git a/apps/sim/lib/api/contracts/v2/selectors.ts b/apps/sim/lib/api/contracts/v2/selectors.ts
index 250af323a67..4308baa71e0 100644
--- a/apps/sim/lib/api/contracts/v2/selectors.ts
+++ b/apps/sim/lib/api/contracts/v2/selectors.ts
@@ -26,8 +26,7 @@ export const v2SelectorInputSchema = z
     workspaceId: workspaceIdSchema.describe('Explicit current workspace scope.'),
     selectorKey: z
       .enum(workspaceSelectorKeys as [ServerSelectorKey, ...ServerSelectorKey[]])
-      .describe('Selector key returned by an import or sync preview, for example gmail.labels.')
-      .describe('Registered selector key for discovering this field’s destination options.'),
+      .describe('Registered selector key from an import or sync preview, such as `gmail.labels`.'),
     context: selectorContextSchema
       .default({})
       .describe(
@@ -44,14 +43,16 @@ export const v2ListSelectorBodySchema = v2SelectorInputSchema
       .min(1)
       .max(32 * 1024)
       .optional()
-      .describe('Opaque continuation cursor returned by the preceding page.'),
+      .describe(
+        'Cursor returned by the preceding page. Keep `workspaceId`, `selectorKey`, `context`, and `search` unchanged; only `limit` may change. Restart without a cursor after a changed-page 409.'
+      ),
     limit: z
       .number()
       .int()
       .min(1)
       .max(100)
       .default(50)
-      .describe('Maximum number of items to return on one page.'),
+      .describe('Maximum options per page, from 1 to 100. Defaults to 50.'),
   })
   .strict()
 export const v2GetSelectorBodySchema = v2SelectorInputSchema
@@ -60,8 +61,7 @@ export const v2GetSelectorBodySchema = v2SelectorInputSchema
       .string()
       .min(1)
       .max(16 * 1024)
-      .describe('Provider resource identifier to resolve.')
-      .describe('Resource identifier.'),
+      .describe('Provider option ID to resolve with the same selector and declared context.'),
   })
   .strict()
 
@@ -76,7 +76,7 @@ export const v2ListSelectorContract = defineRouteContract({
       data: z
         .array(selectorOptionSchema)
         .max(100)
-        .describe('Requested options or operation result.'),
+        .describe('Authorized provider options in this page.'),
       nextCursor: z
         .string()
         .max(32 * 1024)
@@ -86,7 +86,9 @@ export const v2ListSelectorContract = defineRouteContract({
         ),
       truncated: z
         .boolean()
-        .describe('Whether the provider returned only a bounded subset of its options.'),
+        .describe(
+          'Whether provider limits left the result incomplete. A null `nextCursor` with `truncated: true` does not establish that all options were searched.'
+        ),
     }),
   },
 })
diff --git a/apps/sim/lib/api/contracts/v2/shared.ts b/apps/sim/lib/api/contracts/v2/shared.ts
index 9a62cd3d5de..d73c885d5fd 100644
--- a/apps/sim/lib/api/contracts/v2/shared.ts
+++ b/apps/sim/lib/api/contracts/v2/shared.ts
@@ -253,8 +253,8 @@ export const v2CursorListResponse = <T extends z.ZodType>(
       .nullable()
       .describe(
         options.paged === false
-          ? 'Always `null` — this list has no `cursor` or `limit` param and returns its whole bounded set in one page. Present so the list can gain pages later without a shape change.'
-          : 'Opaque cursor for the next page. Send it back as `cursor`; `null` means there is nothing further to fetch. Never construct one yourself.'
+          ? 'Always `null`. This list has no `cursor` or `limit` parameters; see the operation for inventory limits.'
+          : 'Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself.'
       ),
   })
 
@@ -455,15 +455,11 @@ export const V2_SEARCH_MAX_LENGTH = 200
 /**
  * Added to `sortBy` wherever a text name column is sortable.
  *
- * Name ordering is `ORDER BY` on the stored text with no `COLLATE` and no
- * `lower()`, so it is whatever the server database's collation does — under a
- * `C`-collated deployment that is byte order, which puts every capitalized name
- * ahead of every lowercase one. Nothing in the API pins the collation, so the
- * spec must not promise one; what it can promise is that Sim does not case-fold,
- * which is the part a caller gets wrong.
+ * Lists use different database and in-memory comparators, so the shared
+ * description does not promise one collation or case-folding rule.
  */
 export function nameSortCollation(field = 'name') {
-  return `Sorting by \`${field}\` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.`
+  return `Do not rely on case-insensitive ordering when sorting by \`${field}\`.`
 }
 
 export const v2SearchSchema = z
@@ -661,7 +657,7 @@ export const v2DeleteFolderQuerySchema = z
       .stringbool({ case: 'sensitive' })
       .prefault('false')
       .describe(
-        "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected."
+        "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted."
       )
       .meta({ enum: [...V2_TRUE_VALUES, ...V2_FALSE_VALUES] }),
   })
diff --git a/apps/sim/lib/api/contracts/v2/tables.ts b/apps/sim/lib/api/contracts/v2/tables.ts
index 04f6e81c480..cba5d2b0f40 100644
--- a/apps/sim/lib/api/contracts/v2/tables.ts
+++ b/apps/sim/lib/api/contracts/v2/tables.ts
@@ -902,7 +902,7 @@ export const v2TableRowsQuerySchema = tableRowsQueryBaseSchema
       .optional()
       .default(false)
       .describe(
-        `Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its \`blockErrors\` are unbounded, so a full page carries it only when asked. Caps \`limit\` at ${V2_MAX_RUN_STATE_ROW_LIMIT}.`
+        `Include per-workflow-group run outcomes on every row. Off by default. Caps \`limit\` at ${V2_MAX_RUN_STATE_ROW_LIMIT}. Run state above 2 MiB returns \`413\`; request fewer rows or omit run state.`
       ),
   })
   .strict()
@@ -964,7 +964,9 @@ export const v2QueryRowsBodySchema = z
         `Limit cannot exceed ${V2_MAX_ROW_LIMIT}; use limit=0 for a full result or create an export resource for large datasets`
       )
       .optional()
-      .describe('Maximum rows to return; zero requests an unbounded result.'),
+      .describe(
+        'Maximum rows per page. `0` requests all matches, subject to a 5 MiB row-data ceiling; larger results return `400` with `TABLE_QUERY_RESULT_TOO_LARGE`. Use paged queries or an export for larger results.'
+      ),
     cursor: z
       .string()
       .min(1, 'cursor must be a non-empty token')
@@ -975,7 +977,7 @@ export const v2QueryRowsBodySchema = z
       .optional()
       .default(false)
       .describe(
-        `Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its \`blockErrors\` are unbounded, so a full page carries it only when asked. Incompatible with \`limit: 0\`, and caps \`limit\` at ${V2_MAX_RUN_STATE_ROW_LIMIT}.`
+        `Include per-workflow-group run outcomes on every row. Off by default. Incompatible with \`limit: 0\`; caps \`limit\` at ${V2_MAX_RUN_STATE_ROW_LIMIT}. Run state above 2 MiB returns \`413\`; request fewer rows or omit run state.`
       ),
   })
   .strict()
@@ -1244,7 +1246,9 @@ export const v2GetTableRowQuerySchema = v2TableWorkspaceQuerySchema
     includeRunState: booleanQueryFlagSchema
       .optional()
       .default(false)
-      .describe('Include per-workflow-group run state on the returned row. Off by default.'),
+      .describe(
+        'Include per-workflow-group run outcomes on the row. Off by default. Run state above 2 MiB returns `413`; omit this option to read the row without run state.'
+      ),
   })
   .strict()
 export type V2GetTableRowQuery = z.output<typeof v2GetTableRowQuerySchema>
diff --git a/apps/sim/lib/api/contracts/v2/workflow-mcp-servers.ts b/apps/sim/lib/api/contracts/v2/workflow-mcp-servers.ts
index 8266459ac74..9c728e587ba 100644
--- a/apps/sim/lib/api/contracts/v2/workflow-mcp-servers.ts
+++ b/apps/sim/lib/api/contracts/v2/workflow-mcp-servers.ts
@@ -55,7 +55,7 @@ export type V2WorkflowMcpServerParams = z.output<typeof v2WorkflowMcpServerParam
 
 export const v2WorkflowMcpToolParamsSchema = v2WorkflowMcpServerParamsSchema
   .extend({
-    workflowId: workflowIdSchema.describe('Workflow published as a tool on this server.'),
+    workflowId: workflowIdSchema.describe('Workflow registered as an MCP tool on this server.'),
   })
   .meta({
     id: 'WorkflowMcpToolParams',
@@ -73,7 +73,7 @@ export const v2WorkflowMcpServerSchema = z
     isPublic: z.boolean().describe('Whether the server answers MCP clients without a Sim API key.'),
     mcpServerUrl: z
       .string()
-      .describe('Endpoint an MCP client connects to. Published here so callers never build it.')
+      .describe('MCP client endpoint. Use this returned URL instead of constructing one.')
       .meta({ examples: ['https://www.sim.ai/api/mcp/serve/wfmcp_01J8ZK3QW4M6X2R9T7B5C0V2'] }),
     createdAt: z
       .string()
@@ -87,7 +87,7 @@ export const v2WorkflowMcpServerSchema = z
   .meta({
     id: 'WorkflowMcpServer',
     title: 'Workflow MCP server',
-    description: 'A workspace-published MCP server exposing deployed workflows as tools.',
+    description: 'A workflow MCP server exposing deployed workflows as tools.',
   })
 export type V2WorkflowMcpServer = z.output<typeof v2WorkflowMcpServerSchema>
 
@@ -99,15 +99,23 @@ export type V2WorkflowMcpServer = z.output<typeof v2WorkflowMcpServerSchema>
  */
 export const v2WorkflowMcpServerListItemSchema = v2WorkflowMcpServerSchema
   .extend({
-    toolCount: z.number().int().nonnegative().describe('Number of workflows published as tools.'),
+    toolCount: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe(
+        'Number of returned tool names for this server. It may undercount registrations when the page’s `toolNamesTruncated` flag is true.'
+      ),
     toolNames: z
       .array(z.string())
-      .describe('Tool names this server publishes, alphabetically ordered.'),
+      .describe(
+        'Returned registered tool names, ordered alphabetically. The list may be incomplete when toolNamesTruncated is true.'
+      ),
   })
   .meta({
     id: 'WorkflowMcpServerListItem',
     title: 'Workflow MCP server list item',
-    description: 'A published MCP server together with the tool names it exposes.',
+    description: 'A workflow MCP server and its bounded tool-name inventory.',
   })
 export type V2WorkflowMcpServerListItem = z.output<typeof v2WorkflowMcpServerListItemSchema>
 
@@ -116,7 +124,7 @@ export type V2WorkflowMcpServerSortBy = (typeof v2WorkflowMcpServerSortFields)[n
 
 export const v2ListWorkflowMcpServersQuerySchema = z
   .object({
-    workspaceId: workspaceIdSchema.describe('Workspace whose published MCP servers to list.'),
+    workspaceId: workspaceIdSchema.describe('Workspace whose workflow MCP servers to list.'),
     ...v2SortFields(v2WorkflowMcpServerSortFields, { sortBy: 'createdAt', sortOrder: 'desc' }),
     ...v2PaginationFields({ description: 'Maximum workflow-MCP servers to return per page.' }),
   })
@@ -124,13 +132,15 @@ export const v2ListWorkflowMcpServersQuerySchema = z
   .meta({
     id: 'ListWorkflowMcpServersQuery',
     title: 'List workflow MCP servers query',
-    description: 'Workspace scope, ordering, and pagination for published MCP servers.',
+    description: 'Workspace scope, ordering, and pagination for workflow MCP servers.',
   })
 export type V2ListWorkflowMcpServersQuery = z.output<typeof v2ListWorkflowMcpServersQuerySchema>
 
 export const v2CreateWorkflowMcpServerBodySchema = z
   .object({
-    workspaceId: workspaceIdSchema.describe('Workspace in which to publish the server.'),
+    workspaceId: workspaceIdSchema.describe(
+      'Workspace in which to create the workflow MCP server.'
+    ),
     name: z
       .string({ error: 'name is required' })
       .trim()
@@ -153,7 +163,7 @@ export const v2CreateWorkflowMcpServerBodySchema = z
       .boolean()
       .optional()
       .describe(
-        'Whether the server answers MCP clients without a Sim API key. Defaults to false — a public server executes the workflows it publishes for anyone holding its URL.'
+        'Whether the server accepts MCP clients without a Sim API key. Defaults to false; a public server lets anyone holding its URL execute the workflows it exposes.'
       )
       .meta({ default: false }),
     workflowIds: z
@@ -163,13 +173,13 @@ export const v2CreateWorkflowMcpServerBodySchema = z
         `workflowIds must contain at most ${V2_WORKFLOW_MCP_PARAMETER_DESCRIPTIONS_MAX} entries`
       )
       .optional()
-      .describe('Deployed workflows to publish as tools on the new server.'),
+      .describe('Deployed workflows to expose as MCP tools on the new server.'),
   })
   .strict()
   .meta({
     id: 'CreateWorkflowMcpServerRequest',
     title: 'Create workflow MCP server request',
-    description: 'A new workspace-published MCP server and the workflows it exposes.',
+    description: 'A new workflow MCP server and deployed workflows to expose as tools.',
     examples: [
       {
         workspaceId: '9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94',
@@ -216,27 +226,28 @@ export const v2UpdateWorkflowMcpServerBodySchema = z
   .meta({
     id: 'UpdateWorkflowMcpServerRequest',
     title: 'Update workflow MCP server request',
-    description: 'Merge-patch body for a published MCP server.',
+    description:
+      'Server fields to change. Omitted fields remain unchanged; `description: null` clears the description.',
     examples: [{ isPublic: true }],
   })
 export type V2UpdateWorkflowMcpServerBody = z.input<typeof v2UpdateWorkflowMcpServerBodySchema>
 
 export const v2DeleteWorkflowMcpServerDataSchema = z
   .object({
-    id: z.string().describe('Identifier of the unpublished server.'),
-    deleted: z.literal(true).describe('Whether the server was unpublished.'),
+    id: z.string().describe('Identifier of the deleted workflow MCP server.'),
+    deleted: z.literal(true).describe('Whether the workflow MCP server was deleted.'),
   })
   .meta({
     id: 'DeleteWorkflowMcpServerResult',
     title: 'Delete workflow MCP server result',
-    description: 'Unpublish acknowledgement.',
+    description: 'Workflow MCP server deletion acknowledgement.',
   })
 export type V2DeleteWorkflowMcpServerData = z.output<typeof v2DeleteWorkflowMcpServerDataSchema>
 
 export const v2WorkflowMcpToolSchema = z
   .object({
     id: z.string().describe('Unique tool identifier.'),
-    serverId: z.string().describe('Server that publishes this tool.'),
+    serverId: z.string().describe('Server exposing this MCP tool.'),
     workflowId: z.string().describe('Workflow this tool executes.'),
     toolName: z
       .string()
@@ -249,7 +260,7 @@ export const v2WorkflowMcpToolSchema = z
     updated: z
       .boolean()
       .describe(
-        'False when the workflow was newly published on this server, true when an existing tool was replaced. Publishing is idempotent per workflow, so a repeat call answers 200 with true rather than conflicting.'
+        'False for a new registration, true when an existing registration for this workflow was replaced. Repeating the operation returns 200 with true instead of a duplicate conflict.'
       ),
     createdAt: z
       .string()
@@ -263,14 +274,14 @@ export const v2WorkflowMcpToolSchema = z
   .meta({
     id: 'WorkflowMcpTool',
     title: 'Workflow MCP tool',
-    description: 'A deployed workflow published as a tool on a workflow-MCP server.',
+    description: 'A deployed workflow exposed as a tool on a workflow MCP server.',
   })
 export type V2WorkflowMcpTool = z.output<typeof v2WorkflowMcpToolSchema>
 
 export const v2DeployWorkflowMcpToolBodySchema = z
   .object({
     workflowId: workflowIdSchema.describe(
-      'Deployed workflow to publish. The workflow must already be deployed.'
+      'Workflow to expose as an MCP tool. It must already be deployed.'
     ),
     toolName: z
       .string()
@@ -326,8 +337,8 @@ export const v2DeployWorkflowMcpToolBodySchema = z
   .strict()
   .meta({
     id: 'DeployWorkflowMcpToolRequest',
-    title: 'Publish workflow as MCP tool request',
-    description: 'The workflow to publish and the tool metadata MCP clients see.',
+    title: 'Deploy workflow as MCP tool request',
+    description: 'The deployed workflow and tool metadata presented to MCP clients.',
     examples: [{ workflowId: '3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36', toolName: 'triage_ticket' }],
   })
 export type V2DeployWorkflowMcpToolBody = z.input<typeof v2DeployWorkflowMcpToolBodySchema>
@@ -336,12 +347,12 @@ export const v2UndeployWorkflowMcpToolDataSchema = z
   .object({
     id: z.string().describe('Identifier of the removed tool.'),
     serverId: z.string().describe('Server the tool was removed from.'),
-    workflowId: z.string().describe('Workflow that is no longer published.'),
+    workflowId: z.string().describe('Workflow whose MCP tool registration was removed.'),
     deleted: z.literal(true).describe('Whether the tool was removed.'),
   })
   .meta({
     id: 'UndeployWorkflowMcpToolResult',
-    title: 'Unpublish workflow MCP tool result',
+    title: 'Undeploy workflow MCP tool result',
     description: 'Tool removal acknowledgement.',
   })
 export type V2UndeployWorkflowMcpToolData = z.output<typeof v2UndeployWorkflowMcpToolDataSchema>
@@ -356,7 +367,7 @@ export const v2ListWorkflowMcpServersContract = defineRouteContract({
       toolNamesTruncated: z
         .boolean()
         .describe(
-          'Whether the page-wide tool-name limit left some inventories incomplete. Use List Workflow MCP Tools for one server and check its `truncated` flag before treating the inventory as complete. `nextCursor` paginates servers, not tool names.'
+          'Whether the page-wide tool-name limit left some inventories incomplete. Use List workflow MCP tools for one server and check its `truncated` flag before treating the inventory as complete. `nextCursor` paginates servers, not tool names.'
         ),
     }),
   },
@@ -383,7 +394,7 @@ export const v2CreateWorkflowMcpServerContract = defineRouteContract({
 export const v2WorkflowMcpToolStatusSchema = z
   .enum(['active', 'inactive'])
   .describe(
-    'Whether MCP clients can call the tool. `inactive` is a registration that undeploying its workflow archived: it is not callable and its name stays reserved on the server, and the next deploy of the workflow makes it `active` again. Unpublishing an inactive tool removes it for good.'
+    'Whether MCP clients can call the tool. Undeploying its workflow archives the registration as `inactive`; it cannot be called and its name stays reserved. Redeploying the workflow makes it `active` again. Undeploying an inactive MCP tool permanently removes its registration.'
   )
 export type V2WorkflowMcpToolStatus = z.output<typeof v2WorkflowMcpToolStatusSchema>
 
@@ -405,7 +416,7 @@ export const v2WorkflowMcpToolListItemSchema = v2WorkflowMcpToolSchema
     id: 'WorkflowMcpToolListItem',
     title: 'Workflow MCP tool list item',
     description:
-      'A tool a server publishes, as returned by a read. Archived registrations are included with `status: "inactive"`.',
+      'A tool registration on a workflow MCP server. Archived registrations are included with `status: "inactive"`.',
   })
 
 export type V2WorkflowMcpToolListItem = z.output<typeof v2WorkflowMcpToolListItemSchema>
@@ -432,7 +443,7 @@ export const v2ListWorkflowMcpToolsContract = defineRouteContract({
       truncated: z
         .boolean()
         .describe(
-          'Whether the tool limit left this inventory incomplete. The list is unpaginated and `nextCursor` remains null even when truncated. Do not treat a truncated inventory as the complete set of published tools.'
+          'Whether the tool limit left this inventory incomplete. The list is unpaginated and nextCursor remains null even when truncated; an incomplete inventory does not represent every registration.'
         ),
     }),
   },
diff --git a/apps/sim/lib/api/contracts/v2/workflows.ts b/apps/sim/lib/api/contracts/v2/workflows.ts
index bfa0c0f408b..f3ad518de4d 100644
--- a/apps/sim/lib/api/contracts/v2/workflows.ts
+++ b/apps/sim/lib/api/contracts/v2/workflows.ts
@@ -85,7 +85,7 @@ export const v2WorkflowRunIdSchema = runIdSchema
  * a claimed ID reusable. Reusing a claimed ID returns a conflict, never a replay.
  */
 const X_RUN_ID_DESCRIPTION =
-  'Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get Workflow Run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.'
+  'Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get workflow run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.'
 
 const X_SIM_VIA_DESCRIPTION =
   'Comma-separated workflow identifiers naming the workflow-to-workflow call chain that led to this request. Each hop appends its own workflow id, and Sim sets it automatically; supply it yourself only when relaying an existing chain. A chain at the maximum depth is rejected with `409` and `error.details.code: "CALL_CHAIN_DEPTH_EXCEEDED"`.'
@@ -224,7 +224,7 @@ export const v2WorkflowListItemSchema = z
       .int()
       .nonnegative()
       .describe(
-        'Settled runs — completed, failed, or cancelled — counted as each one finishes; a paused run is counted once it settles. The counter is never reduced when a run ages out of log retention, so it can exceed the results returned by List Workflow Runs.'
+        'Settled runs — completed, failed, or cancelled — counted as each one finishes; a paused run is counted once it settles. The counter is never reduced when a run ages out of log retention, so it can exceed the results returned by List workflow runs.'
       ),
     lastRunAt: z
       .string()
@@ -260,7 +260,7 @@ const v2WorkflowInputFieldSchema = z
   .meta({
     id: 'WorkflowInputField',
     title: 'Workflow input field',
-    description: 'A deployed API trigger input exposed by a workflow.',
+    description: 'An input field from an input-definition trigger in the saved draft.',
   })
 
 export const v2WorkflowDetailSchema = v2WorkflowListItemSchema
@@ -277,12 +277,14 @@ export const v2WorkflowDetailSchema = v2WorkflowListItemSchema
       .describe('Workflow-scoped variables keyed by variable identifier.'),
     inputs: z
       .array(v2WorkflowInputFieldSchema)
-      .describe('Input fields exposed by the workflow API trigger.'),
+      .describe(
+        "Input fields from the saved draft's input-definition trigger; they may differ from the live deployment."
+      ),
   })
   .meta({
     id: 'WorkflowDetail',
     title: 'Workflow detail',
-    description: 'Full workflow summary with variables and API-trigger input fields.',
+    description: 'Workflow metadata, variables, and saved draft trigger input fields.',
   })
 
 export type V2WorkflowDetail = z.output<typeof v2WorkflowDetailSchema>
@@ -557,14 +559,14 @@ export const v2DeployWorkflowDataSchema = v2DeploymentStateSchema
     lint: v2WorkflowLintSchema
       .nullable()
       .describe(
-        'Advisory lint findings for the version this deploy publishes, checked as the deploying user. Findings never block a deploy. Null when the lint could not complete within its time budget; the deploy itself is unaffected.'
+        'Advisory lint for the admitted version, checked as the deploying member. Findings never block deployment. Null when lint exceeds its time budget or cannot complete; the deployment proceeds.'
       ),
   })
   .meta({
     id: 'DeployResult',
     title: 'Deploy result',
     description:
-      'Deployment attempt accepted for asynchronous activation. `latestDeploymentAttempt` identifies the attempt. Poll Get Workflow Deployment for `isDeployed` and `deployedAt`, or List Workflow Versions for `isActive`.',
+      'Deployment accepted for asynchronous activation. Poll Get workflow deployment and match `latestDeploymentAttempt` to this attempt; an older version can remain live while it activates. List workflow versions reports `isActive`.',
   })
 export type V2DeployWorkflowData = z.output<typeof v2DeployWorkflowDataSchema>
 
@@ -740,7 +742,7 @@ export const v2DeleteWorkflowDataSchema = z
     archived: z
       .literal(true)
       .describe(
-        'Whether the workflow was archived. Restore Workflow recovers it and the schedules, webhooks, MCP tools, and chats archived with it.'
+        'Whether the workflow was archived. Restore workflow recovers it and the schedules, webhooks, MCP tools, and chats archived with it.'
       ),
   })
   .meta({
@@ -966,7 +968,7 @@ export const v2WorkflowVersionDetailSchema = z
       .describe('ISO 8601 timestamp when this version was created.')
       .meta({ format: 'date-time' }),
     state: deployedWorkflowStateSchema.describe(
-      'Workflow graph saved with this deployment version. Sensitive values are redacted to null.'
+      'Graph pinned by this version, with registered credential fields and opaque table/tool values cleared. Environment references and ordinary workflow variables remain included; inspect other configuration before sharing.'
     ),
   })
   .meta({
@@ -1404,7 +1406,7 @@ export const v2WorkflowRunSelectionSchema = z.discriminatedUnion('source', [
                 .string()
                 .min(1, 'run.entry.sourceRunId cannot be empty')
                 .describe(
-                  'Run ID supplying upstream block results when starting from a selected block.'
+                  'Run in this workflow whose persisted execution state supplies upstream block results. Missing or expired state returns 404.'
                 ),
             })
             .strict(),
@@ -1452,7 +1454,7 @@ export const v2ExecuteWorkflowBodySchema = z
       .optional()
       .default(false)
       .describe(
-        'Queue the run and return a 202 receipt when true. Requires an OAuth access token or API key, cannot be combined with `stream`, and rejects all streaming and output-shaping options (`selectedOutputs`, `includeThinking`, `includeToolCalls`, `includeFileBase64`, `base64MaxBytes`).'
+        'Queue the run and return a 202 receipt. Requires an API key or OAuth access token and a deployed run source. Cannot stream, select outputs, enable thinking/tool events, or include file-inlining options (`includeFileBase64` or `base64MaxBytes`).'
       ),
     /**
      * An upper bound on the request, not the effective timeout: the server
@@ -1695,7 +1697,7 @@ export const v2ResumeWorkflowContract = defineRouteContract({
 })
 
 const RUN_STATUS_DESCRIPTION =
-  "Current or terminal run status. `redacting` is transient, reported while a finished run's output is being scrubbed. `paused` means the run is waiting to be resumed — either held at a human-in-the-loop pause point, or left paused by a resume attempt that did not complete. Only the single-run response distinguishes the two, through `paused.automaticResumeWaitingReason`."
+  "Current or terminal run status. `redacting` is transient, reported while a finished run's output is being scrubbed. `paused` means the run is waiting at a human or time pause, or a resume attempt did not complete. The single-run response provides the pause kind, resume time, and any automatic-resume waiting reason."
 
 /**
  * The list projection passes `workflow_execution_logs.status` through except where it
@@ -1798,7 +1800,9 @@ export const v2WorkflowRunListItemSchema = z
     cost: z
       .object({ total: z.number().describe('Total credits consumed by the run.') })
       .nullable()
-      .describe('Credit cost, or null when unavailable.'),
+      .describe(
+        'Credits consumed, or null when unavailable or hidden by organization permission groups.'
+      ),
   })
   .meta({
     id: 'WorkflowRunListItem',
@@ -1903,7 +1907,9 @@ export const v2WorkflowRunStatusSchema = z
     cost: z
       .object({ total: z.number().describe('Total credits consumed by the run.') })
       .nullable()
-      .describe('Credit cost, or null when unavailable.'),
+      .describe(
+        'Credits consumed, or null when unavailable or hidden by organization permission groups.'
+      ),
     error: v2ExecutionErrorSchema
       .nullable()
       .describe(
@@ -1914,18 +1920,20 @@ export const v2WorkflowRunStatusSchema = z
       .unknown()
       .describe('Final workflow output value.')
       .nullable()
-      .describe('Final workflow output when requested, otherwise null.'),
+      .describe(
+        'Final output when `includeOutput=true`, or null when not requested or hidden by organization permission groups.'
+      ),
     blockOutputs: z
       .record(z.string(), z.unknown().describe('Output value produced by one workflow block.'))
       .nullable()
       .describe(
-        'Outputs of the blocks named by `selectedOutputs`, or null when none were requested. Gated by `selectedOutputs` alone — `includeOutput` governs `output` only.'
+        'Selected block outputs, or null when none were requested or execution data is hidden by organization permission groups. `selectedOutputs` controls these independently of `includeOutput`.'
       ),
     files: z
       .array(v2RunFileSchema)
       .nullable()
       .describe(
-        'Files this run produced, or null when `includeOutput` is false. Matches the nullability of `output`.'
+        'Run-produced files when `includeOutput=true`, or null when not requested or execution data is hidden by organization permission groups.'
       ),
   })
   .meta({
@@ -2138,14 +2146,14 @@ export const v2WorkflowExportPayloadSchema = v1WorkflowExportPayloadSchema
       required: undefined,
       additionalProperties: true,
       description:
-        'Secret-sanitized workflow graph, edges, loops, parallels, metadata, and variables.',
+        'Saved graph, edges, containers, metadata, and variables. Registered credential fields are cleared; ordinary variables and unresolved environment references remain included.',
     }),
   })
   .meta({
     id: 'WorkflowExportPayload',
     title: 'Workflow export payload',
     description:
-      'Portable, secret-sanitized workflow export. Workspace-scoped bindings must be selected again after import.',
+      'Portable saved draft with registered credential fields cleared. Workspace bindings are cleared by default and retained when `includeWorkspaceBindings=true`.',
   })
 
 export const v2ImportWorkflowBaseBodySchema = v1ImportWorkflowBodySchema
@@ -2215,7 +2223,7 @@ export const v2ImportWorkflowBaseBodySchema = v1ImportWorkflowBodySchema
       )
       .max(5000)
       .optional()
-      .describe('Mappings keyed by resource type and source identifier.'),
+      .describe('Mapping entries addressed by resource kind and source identifier.'),
     bindings: z
       .array(
         referenceOccurrenceSchema
@@ -2261,7 +2269,7 @@ export const v2ImportWorkflowBaseBodySchema = v1ImportWorkflowBodySchema
       .max(2000)
       .optional()
       .describe(
-        'Destination-dependent choices keyed by source workflow, block, and field identities.'
+        'Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated.'
       ),
   })
   .strict()
@@ -2287,15 +2295,15 @@ export const v2ImportWorkflowBodySchema = v2ImportWorkflowBaseBodySchema
       .regex(/^[A-Za-z0-9._:-]+$/)
       .optional()
       .describe(
-        'Stable client-generated retry ID. Reuse it after uncertain completion; never submit a fresh ID to retry.'
-      )
-      .describe('Stable client request ID for reconciliation and identical retries.'),
+        'Stable client request ID for mapped import. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can create another workflow.'
+      ),
     previewFingerprint: z
       .string()
       .regex(/^[a-f0-9]{64}$/)
       .optional()
-      .describe('Fingerprint returned by the last import preview.')
-      .describe('Fingerprint of the reviewed preview and its choices.'),
+      .describe(
+        'Fingerprint returned by an import preview with the same choices. A changed plan returns 409; preview again. Do not invent this value.'
+      ),
   })
   .strict()
   .superRefine((body, ctx) => {
@@ -2390,11 +2398,13 @@ export const v2PreviewWorkflowImportContract = defineRouteContract({
           previewFingerprint: z
             .string()
             .length(64)
-            .describe('Fingerprint of the reviewed preview and its choices.'),
+            .describe(
+              'Fingerprint to send when applying this import with the same choices. Preview again after changing any choice.'
+            ),
           ready: z
             .boolean()
             .describe(
-              'Whether the operation passes its current apply or deployment readiness checks.'
+              'Whether every required destination binding and configuration field is resolved for import.'
             ),
           bindings: z
             .array(v2ImportBindingResolutionSchema)
@@ -2434,8 +2444,9 @@ export const v2PreviewWorkflowImportContract = defineRouteContract({
         })
         .meta({
           id: 'PreviewWorkflowImportResult',
-          title: 'PreviewWorkflowImportResult',
-          description: 'The PreviewWorkflowImportResult result.',
+          title: 'Workflow import preview',
+          description:
+            'Import readiness, unresolved bindings, and destination discovery instructions.',
         })
     ),
   },
@@ -2495,7 +2506,7 @@ export const v2ImportWorkflowDataSchema = z
     warnings: z
       .array(z.string())
       .describe(
-        'One line per required workspace binding — a table, knowledge base, document, or other selector — that the payload carried empty, as `<block name>: <field> was stripped by export; set it before running`. Export clears those bindings unless `includeWorkspaceBindings=true` was sent, so a round-tripped workflow arrives unable to run until they are set again. Empty when nothing is missing.'
+        'Missing required workspace bindings, such as a table or knowledge base, reported as `<block name>: <field> was stripped by export; set it before running`. Set these fields before execution. Default exports clear workspace bindings; `includeWorkspaceBindings=true` retains non-secret bindings for same-workspace imports. Empty when no required binding is missing.'
       ),
   })
   .extend(v2OperationReportSchema.omit({ workspaceId: true }).partial().shape)
@@ -2515,7 +2526,7 @@ export const v2ExportWorkflowQuerySchema = z
       ),
     includeWorkspaceBindings: booleanQueryFlagSchema
       .describe(
-        'Whether to keep workspace-scoped bindings — table, knowledge base, document, folder, channel, and other resource selectors — in the exported state. Defaults to false, the sharing-safe export in which those ids are cleared because they resolve nowhere else. Send true for a same-workspace round trip so the re-imported workflow can run without re-selecting them. Credentials, passwords, and table sub-block values are cleared either way.'
+        'Keep non-secret table, knowledge base, document, folder, channel, and other workspace bindings for a same-workspace import. Defaults to false, which clears these IDs. Registered credential fields and opaque table/tool values are cleared either way; environment references and ordinary workflow variables remain included.'
       )
       .optional()
       .default(false),
@@ -3686,7 +3697,7 @@ export type V2ApplyWorkflowVariablesBody = z.input<typeof v2ApplyWorkflowVariabl
 export const v2ApplyWorkflowVariablesDataSchema = z
   .object({
     id: z.string().describe('Identifier of the workflow whose variables were updated.'),
-    variableCount: z.number().int().nonnegative().describe('Variables the workflow now holds.'),
+    variableCount: z.number().int().nonnegative().describe('Number of variables after the batch.'),
     changed: z
       .boolean()
       .describe('Whether anything actually changed. A no-op batch answers `200` with `false`.'),
diff --git a/apps/sim/lib/api/contracts/v2/workspace-fork.ts b/apps/sim/lib/api/contracts/v2/workspace-fork.ts
index 6d02f4bf1be..2d4eb83a7f4 100644
--- a/apps/sim/lib/api/contracts/v2/workspace-fork.ts
+++ b/apps/sim/lib/api/contracts/v2/workspace-fork.ts
@@ -24,13 +24,13 @@ export const v2ForkRequestIdSchema = z
   .min(1)
   .max(128)
   .describe(
-    'Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409.'
+    'Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation.'
   )
 export const v2ForkFingerprintSchema = z
   .string()
   .regex(/^[a-f0-9]{64}$/)
   .describe(
-    'Fingerprint from a preview with the same choices. A changed plan returns 409; request a new preview.'
+    'Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value.'
   )
 export const v2ForkMappingSchema = z
   .object({
@@ -165,12 +165,8 @@ export const v2ForkPreviewBodySchema = z
   .strict()
 export const v2ForkApplyBodySchema = v2ForkPreviewBodySchema
   .extend({
-    requestId: v2ForkRequestIdSchema.describe(
-      'Stable client request ID for reconciliation and identical retries.'
-    ),
-    previewFingerprint: v2ForkFingerprintSchema.describe(
-      'Fingerprint of the reviewed preview and its choices.'
-    ),
+    requestId: v2ForkRequestIdSchema,
+    previewFingerprint: v2ForkFingerprintSchema,
   })
   .strict()
 export const v2SyncPreviewBodySchema = z
@@ -182,15 +178,15 @@ export const v2SyncPreviewBodySchema = z
       .array(v2ForkMappingSchema)
       .max(5000)
       .optional()
-      .describe('Proposed mappings; preview does not save them. Apply commits them with the sync.')
-      .describe('Mappings keyed by resource type and source identifier.'),
+      .describe(
+        'Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync.'
+      ),
     dependentValues: z
       .array(v2ForkDependentValueSchema)
       .max(2000)
       .optional()
-      .describe('Destination choices addressed by source workflow, block, and field identities.')
       .describe(
-        'Destination-dependent choices keyed by source workflow, block, and field identities.'
+        'Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them.'
       ),
     copyResources: v2SyncCopySelectionSchema
       .optional()
@@ -224,24 +220,19 @@ export const v2SyncPreviewBodySchema = z
   .strict()
 export const v2SyncApplyBodySchema = v2SyncPreviewBodySchema
   .extend({
-    requestId: v2ForkRequestIdSchema.describe(
-      'Stable client request ID for reconciliation and identical retries.'
-    ),
-    previewFingerprint: v2ForkFingerprintSchema.describe(
-      'Fingerprint of the reviewed preview and its choices.'
-    ),
+    requestId: v2ForkRequestIdSchema,
+    previewFingerprint: v2ForkFingerprintSchema,
     confirm: z
       .literal(true)
       .describe(
-        'Acknowledge replacement of target workflows and archival of mapped targets whose sources were deleted.'
-      )
-      .describe('Explicit acknowledgement that sync replaces target workflows.'),
+        'Confirm replacement of mapped target drafts and archival of mapped targets whose sources were deleted or archived.'
+      ),
   })
   .strict()
 export const v2ForkPreviewDataSchema = z
   .object({
     previewFingerprint: v2ForkFingerprintSchema.describe(
-      'Fingerprint of the reviewed preview and its choices.'
+      'Fingerprint to submit when applying this preview with the same choices. Preview again after changing a choice.'
     ),
     sourceWorkspaceId: workspaceIdSchema.describe(
       'Canonical workspace the workflows and resources are copied from.'
@@ -266,8 +257,8 @@ export const v2ForkPreviewDataSchema = z
   })
   .meta({
     id: 'WorkspaceForkPreview',
-    title: 'WorkspaceForkPreview',
-    description: 'The WorkspaceForkPreview result.',
+    title: 'Workspace fork preview',
+    description: 'Read-only fork plan and fingerprint.',
   })
 export const v2SyncConfigurationSchema = z.object({
   sourceWorkflowId: workflowIdSchema.describe('Workflow identifier in the source workspace.'),
@@ -313,7 +304,7 @@ export const v2SyncConfigurationSchema = z.object({
 export const v2SyncPreviewDataSchema = z
   .object({
     previewFingerprint: v2ForkFingerprintSchema.describe(
-      'Fingerprint of the reviewed preview and its choices.'
+      'Fingerprint to submit when applying this preview with the same choices. Preview again after changing a choice.'
     ),
     sourceWorkspaceId: workspaceIdSchema.describe(
       'Canonical workspace the workflows and resources are copied from.'
@@ -321,7 +312,9 @@ export const v2SyncPreviewDataSchema = z
     targetWorkspaceId: workspaceIdSchema.describe('Canonical workspace receiving the changes.'),
     ready: z
       .boolean()
-      .describe('Whether the operation passes its current apply or deployment readiness checks.'),
+      .describe(
+        'Whether required bindings, configuration, and sync blockers are resolved. This does not mean the target is already deployed.'
+      ),
     workflows: z
       .array(
         z.object({
@@ -402,8 +395,8 @@ export const v2SyncPreviewDataSchema = z
   })
   .meta({
     id: 'WorkspaceSyncPreview',
-    title: 'WorkspaceSyncPreview',
-    description: 'The WorkspaceSyncPreview result.',
+    title: 'Workspace sync preview',
+    description: 'Read-only sync actions, bindings, configuration, and trigger-path choices.',
   })
 export const v2ForkOtherBodySchema = z
   .object({
@@ -440,7 +433,9 @@ export const v2ForkMappingUpdateBodySchema = z
     mappings: z
       .array(v2ForkMappingSchema)
       .max(5000)
-      .describe('Mappings keyed by resource type and source identifier.'),
+      .describe(
+        'Mapping entries addressed by resource type and `sourceId`. `targetId: null` clears a mapping.'
+      ),
   })
   .strict()
 export const v2ForkChildrenQuerySchema = z
@@ -466,7 +461,7 @@ export const v2ForkResourcesQuerySchema = z
         'mcpServers',
         'workflowMcpServers',
       ])
-      .describe('Resource or operation kind.'),
+      .describe('Kind of source resource to list for copy selection.'),
     sortBy: z.enum(['id']).default('id').describe('Supported stable sort key for this collection.'),
     sortOrder: z.enum(['asc']).default('asc').describe('Sort direction.'),
   })
@@ -562,8 +557,8 @@ export const v2GetWorkspaceForkAvailabilityContract = defineRouteContract({
         })
         .meta({
           id: 'GetWorkspaceForkAvailabilityResult',
-          title: 'GetWorkspaceForkAvailabilityResult',
-          description: 'The GetWorkspaceForkAvailabilityResult result.',
+          title: 'Get workspace fork availability result',
+          description: 'Fork feature availability for this workspace.',
         })
     ),
   },
@@ -586,8 +581,8 @@ export const v2GetWorkspaceForkLineageContract = defineRouteContract({
         })
         .meta({
           id: 'GetWorkspaceForkLineageResult',
-          title: 'GetWorkspaceForkLineageResult',
-          description: 'The GetWorkspaceForkLineageResult result.',
+          title: 'Get workspace fork lineage result',
+          description: 'Current workspace and its active parent.',
         })
     ),
   },
@@ -605,8 +600,8 @@ export const v2ListWorkspaceForkChildrenContract = defineRouteContract({
         .extend({ createdAt: z.iso.datetime().describe('ISO 8601 creation timestamp.') })
         .meta({
           id: 'ListWorkspaceForkChildrenResult',
-          title: 'ListWorkspaceForkChildrenResult',
-          description: 'The ListWorkspaceForkChildrenResult result.',
+          title: 'List workspace fork children result',
+          description: 'An active direct child workspace.',
         })
     ),
   },
@@ -637,8 +632,8 @@ export const v2ListWorkspaceForkResourcesContract = defineRouteContract({
         })
         .meta({
           id: 'ListWorkspaceForkResourcesResult',
-          title: 'ListWorkspaceForkResourcesResult',
-          description: 'The ListWorkspaceForkResourcesResult result.',
+          title: 'List workspace fork resources result',
+          description: 'A copyable resource candidate.',
         })
     ),
   },
@@ -656,8 +651,8 @@ export const v2GetWorkspaceForkMappingsContract = defineRouteContract({
         .extend({ id: z.string().max(256).describe('Resource identifier.') })
         .meta({
           id: 'GetWorkspaceForkMappingsResult',
-          title: 'GetWorkspaceForkMappingsResult',
-          description: 'The GetWorkspaceForkMappingsResult result.',
+          title: 'Get workspace fork mappings result',
+          description: 'A saved directional mapping entry.',
         })
     ),
   },
@@ -674,8 +669,8 @@ export const v2UpdateWorkspaceForkMappingsContract = defineRouteContract({
     schema: v2DataResponse(
       z.object({ updated: z.number().int().min(0).describe('Number of records changed.') }).meta({
         id: 'UpdateWorkspaceForkMappingsResult',
-        title: 'UpdateWorkspaceForkMappingsResult',
-        description: 'The UpdateWorkspaceForkMappingsResult result.',
+        title: 'Update workspace fork mappings result',
+        description: 'Count of changed mapping records.',
       })
     ),
   },
@@ -719,8 +714,8 @@ export const v2RollbackWorkspaceForkContract = defineRouteContract({
         })
         .meta({
           id: 'RollbackWorkspaceForkResult',
-          title: 'RollbackWorkspaceForkResult',
-          description: 'The RollbackWorkspaceForkResult result.',
+          title: 'Rollback workspace fork result',
+          description: 'Workflow restoration and pending-activation counts.',
         })
     ),
   },
@@ -737,8 +732,8 @@ export const v2UnlinkWorkspaceForkContract = defineRouteContract({
     schema: v2DataResponse(
       z.object({ unlinked: z.boolean().describe('Whether the fork edge was removed.') }).meta({
         id: 'UnlinkWorkspaceForkResult',
-        title: 'UnlinkWorkspaceForkResult',
-        description: 'The UnlinkWorkspaceForkResult result.',
+        title: 'Unlink workspace fork result',
+        description: 'Fork-edge removal acknowledgment.',
       })
     ),
   },
@@ -755,8 +750,8 @@ export const v2UpdateWorkspaceForkExclusionsContract = defineRouteContract({
     schema: v2DataResponse(
       z.object({ updated: z.number().int().min(0).describe('Number of records changed.') }).meta({
         id: 'UpdateWorkspaceForkExclusionsResult',
-        title: 'UpdateWorkspaceForkExclusionsResult',
-        description: 'The UpdateWorkspaceForkExclusionsResult result.',
+        title: 'Update workspace fork exclusions result',
+        description: 'Count of changed workflow exclusion flags.',
       })
     ),
   },
diff --git a/apps/sim/lib/api/contracts/v2/workspace-operations.ts b/apps/sim/lib/api/contracts/v2/workspace-operations.ts
index 3753f18271e..3142ffdf153 100644
--- a/apps/sim/lib/api/contracts/v2/workspace-operations.ts
+++ b/apps/sim/lib/api/contracts/v2/workspace-operations.ts
@@ -38,11 +38,13 @@ export const v2OperationReportSchema = z
       .string()
       .min(1)
       .max(128)
-      .describe('Stable client request ID for reconciliation and identical retries.'),
+      .describe(
+        'Client request ID used to commit this operation. Reuse identical mutation inputs with this ID after an uncertain response.'
+      ),
     workspaceId: workspaceIdSchema.describe('Explicit current workspace scope.'),
     kind: z
       .enum(['workflow_import', 'workspace_fork', 'workspace_push', 'workspace_pull'])
-      .describe('Resource or operation kind.'),
+      .describe('Type of committed workspace operation.'),
     applied: z
       .literal(true)
       .describe('The business transaction committed, including when follow-up work fails.'),
@@ -54,7 +56,7 @@ export const v2OperationReportSchema = z
         'requires_configuration',
         'failed',
       ])
-      .describe('Current operation or deployment outcome.'),
+      .describe('Operation status; failed follow-up work does not undo the committed transaction.'),
     resourceIds: z
       .array(z.string().min(1).max(256))
       .max(5000)
@@ -87,14 +89,14 @@ export const v2OperationReportSchema = z
             .number()
             .int()
             .min(1)
-            .describe('Reference format or deployment version number.'),
+            .describe('Deployment version number for this admitted attempt.'),
           status: z
             .enum(['preparing', 'activating', 'active', 'failed', 'superseded'])
-            .describe('Current operation or deployment outcome.'),
+            .describe('Status of this exact admitted deployment attempt.'),
           ready: z
             .boolean()
             .describe(
-              'Whether the operation passes its current apply or deployment readiness checks.'
+              'Whether this exact deployment attempt is active and all required components are ready.'
             ),
           pendingComponents: z
             .array(z.string().max(128))
@@ -119,7 +121,7 @@ export const v2OperationReportSchema = z
       .object({
         status: z
           .enum(['pending', 'completed', 'failed'])
-          .describe('Current operation or deployment outcome.'),
+          .describe('Background resource-copy status.'),
         copied: z.number().int().min(0).describe('Number of resources copied successfully.'),
         failed: z.number().int().min(0).describe('Number of resources that failed to copy.'),
       })
@@ -128,8 +130,8 @@ export const v2OperationReportSchema = z
   })
   .meta({
     id: 'WorkspaceOperationReport',
-    title: 'WorkspaceOperationReport',
-    description: 'The WorkspaceOperationReport result.',
+    title: 'Workspace operation receipt',
+    description: 'Committed operation receipt, resource copies, and exact deployment readiness.',
   })
 export const v2WorkspaceOperationParamsSchema = z
   .object({
@@ -149,8 +151,9 @@ export const v2ListWorkspaceOperationsQuerySchema = z
       .min(1)
       .max(128)
       .optional()
-      .describe('Find an uncertain mutation by its original request ID.')
-      .describe('Stable client request ID for reconciliation and identical retries.'),
+      .describe(
+        'Find an uncertain mutation by the original client request ID; keep the same filter while paging.'
+      ),
   })
   .strict()
 export const v2GetWorkspaceOperationContract = defineRouteContract({
diff --git a/apps/sim/lib/api/contracts/workflows.ts b/apps/sim/lib/api/contracts/workflows.ts
index 95c7445fff7..26a56fb29bd 100644
--- a/apps/sim/lib/api/contracts/workflows.ts
+++ b/apps/sim/lib/api/contracts/workflows.ts
@@ -619,7 +619,7 @@ export const workflowExecutionPausedDetailSchema = z.object({
     .string()
     .nullable()
     .describe(
-      'Why automatic resume is waiting, or null when it is not — on a paused run, null means it is waiting on human input. Recorded whenever a resume attempt fails and cleared once one succeeds. A non-retryable or exhausted failure is prefixed `Automatic resume requires manual intervention: `.'
+      'Recorded automatic-resume failure, or null when no failure is recorded. Inspect `pauseKind` and `resumeAt` to distinguish a scheduled time pause from human input. Cleared after a successful resume. A non-retryable or exhausted failure starts with `Automatic resume requires manual intervention: `.'
     ),
   pausedExecutionId: z.string().describe('Persistent paused-execution record identifier.'),
   pausePointCount: z.number().describe('Number of pause points tracked for the execution.'),
diff --git a/apps/sim/lib/api/mcp/generated/v2-operations.ts b/apps/sim/lib/api/mcp/generated/v2-operations.ts
index e8655454a6d..a585e7f3629 100644
--- a/apps/sim/lib/api/mcp/generated/v2-operations.ts
+++ b/apps/sim/lib/api/mcp/generated/v2-operations.ts
@@ -356,7 +356,7 @@ import type { V2McpOperation } from '@/lib/api/mcp/types'
 export const V2_MCP_OPERATIONS = {
   abortFileUpload: {
     contract: v2AbortFileUploadContract,
-    summary: 'Abort File Upload',
+    summary: 'Abort file upload',
     description:
       'Abort an incomplete upload session and discard its uploaded data. Completed uploads cannot be aborted.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -364,7 +364,7 @@ export const V2_MCP_OPERATIONS = {
   },
   abortKnowledgeDocumentUpload: {
     contract: v2AbortKnowledgeDocumentUploadContract,
-    summary: 'Abort Document Upload',
+    summary: 'Abort document upload',
     description:
       'Abort an incomplete upload session and discard its uploaded data. Completed uploads cannot be aborted.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -374,9 +374,9 @@ export const V2_MCP_OPERATIONS = {
   },
   activateWorkflowVersion: {
     contract: v2ActivateWorkflowVersionContract,
-    summary: 'Activate Workflow Version',
+    summary: 'Activate workflow version',
     description:
-      'Asynchronously activate a specific deployment version, including when the workflow is not currently deployed. The draft remains unchanged. Read Get Workflow Deployment for `isDeployed` and `latestDeploymentAttempt`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Activate a specific deployment version asynchronously. Requires workspace Admin access and works when the workflow is undeployed. The draft is unchanged. Poll Get workflow deployment for the accepted `latestDeploymentAttempt`; `isDeployed` alone can describe an older live version. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/versions/[version]/activate/route').then(
@@ -385,9 +385,9 @@ export const V2_MCP_OPERATIONS = {
   },
   addOrganizationDomain: {
     contract: v2AddOrganizationDomainContract,
-    summary: 'Add Organization Domain',
+    summary: 'Add organization domain',
     description:
-      'Claim a domain and receive its DNS TXT challenge. Requires organization administrator access and Enterprise domain entitlement. An existing claim returns 200; a new claim returns 201. A domain verified by another organization conflicts. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Claim a domain and receive its DNS TXT challenge. Requires organization Admin access and, when billing is enabled, Enterprise domain entitlement. An organization can claim at most 25 domains. Existing claims return `200`; new claims return `201`. A domain verified by another organization returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/domains/route').then(
@@ -396,9 +396,9 @@ export const V2_MCP_OPERATIONS = {
   },
   addPermissionGroupMember: {
     contract: v2AddPermissionGroupMemberContract,
-    summary: 'Add Permission Group Member',
+    summary: 'Add permission group member',
     description:
-      'Assign an organization member to a permission group. An existing assignment or membership in another group targeting the same workspace returns a conflict. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Assign an organization member to a permission group. An existing assignment or membership in another group targeting the same workspace returns a conflict. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import(
@@ -407,7 +407,7 @@ export const V2_MCP_OPERATIONS = {
   },
   addTableColumn: {
     contract: v2AddTableColumnContract,
-    summary: 'Add Column',
+    summary: 'Add column',
     description:
       'Add a typed column and return the complete resulting table schema.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -415,16 +415,16 @@ export const V2_MCP_OPERATIONS = {
   },
   addWorkflowGroup: {
     contract: v2AddWorkflowGroupContract,
-    summary: 'Add Workflow Group',
+    summary: 'Add workflow group',
     description:
       'Bind a workflow or enrichment to the table and create the columns populated by its outputs. An output whose column the table already has attaches that column to the group instead of creating it, so `outputColumns` may be omitted when every output lands in an existing column.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/groups/route').then((route) => route.POST),
   },
   addWorkspaceFilesToKnowledgeBase: {
     contract: v2AddWorkspaceFilesToKnowledgeBaseContract,
-    summary: 'Index Workspace Files',
+    summary: 'Index workspace files',
     description:
-      'Queue stored workspace files for indexing without re-uploading bytes. Unreadable, unsupported, or over-100 MB files appear in `failed`; valid files are queued. Partial success returns `200`. Use Get Document to poll processing after receiving document IDs. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Queue stored workspace files for indexing without re-uploading bytes. Unreadable, unsupported, or over-100 MiB files appear in `failed`; valid files are queued. Partial success returns `200`. Use Get document to poll processing after receiving document IDs. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/documents/from-workspace-files/route').then(
@@ -433,26 +433,26 @@ export const V2_MCP_OPERATIONS = {
   },
   applyWorkflowOperations: {
     contract: v2ApplyWorkflowOperationsContract,
-    summary: 'Apply Workflow Operations',
+    summary: 'Apply workflow operations',
     description:
-      'Edit the draft graph and block enablement in one write. Inspect `skipped` for failures; do not retry `deferred` edges. With `atomic=true`, skipped operations or dropped inputs return `409` (`OPERATIONS_NOT_APPLIED`) without saving. `mintedBlockIds` maps labels to generated IDs. Lint is advisory; `dryRun=true` validates without saving, auditing, or notifying. The live deployment is unchanged. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Apply draft edits and block enablement changes in one write. Requires workspace write access. The live deployment is unchanged; lint is advisory.\n\nInspect `skipped` and `inputValidationErrors` for edits that did not apply. Deferred edges apply when their targets exist; do not resubmit them. With `atomic=true`, declined operations or dropped inputs return `409` (`OPERATIONS_NOT_APPLIED`) without saving. Use returned `mintedBlockIds` in later requests. `dryRun=true` evaluates without saving, auditing, or notifying. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/operations/route').then((route) => route.POST),
   },
   applyWorkflowVariables: {
     contract: v2ApplyWorkflowVariablesContract,
-    summary: 'Update Workflow Variables',
+    summary: 'Update workflow variables',
     description:
-      'Add, edit, or delete variables by name, applying operations in order. Values are coerced to their declared type when possible; otherwise they are stored as supplied. A batch with no changes returns `200` with `changed: false`. Read current variables with Get Workflow.\n\nOAuth scope: `api:write`.',
+      'Add, edit, or delete variables by name with workspace write access. Operations run in order. Values are coerced to their declared type when possible and otherwise stored as supplied. A no-op batch returns `changed: false`; read current values with Get workflow.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/variables/route').then((route) => route.PATCH),
   },
   bulkAddPermissionGroupMembers: {
     contract: v2BulkAddPermissionGroupMembersContract,
-    summary: 'Bulk Add Permission Group Members',
+    summary: 'Bulk add permission group members',
     description:
-      'Assign up to 1000 selected organization members, or the entire organization roster, atomically. Existing assignments are skipped and users outside the organization are ignored. Any overlapping membership conflict rejects the entire batch. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Assign up to 1000 selected organization members, or the entire organization roster, atomically. Existing assignments are skipped and users outside the organization are ignored. Any overlapping membership conflict rejects the entire batch. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import(
@@ -461,30 +461,30 @@ export const V2_MCP_OPERATIONS = {
   },
   bulkDeleteFiles: {
     contract: v2BulkDeleteFilesContract,
-    summary: 'Delete Files',
+    summary: 'Delete files',
     description:
-      'Archive up to 1,000 workspace files while retaining their stored bytes. Use Restore File to recover each file.\n\nOAuth scope: `api:write`.',
+      'Archive up to 1,000 workspace files while retaining their stored bytes. Use Restore file to recover each file.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/bulk-delete/route').then((route) => route.POST),
   },
   bulkDeleteTables: {
     contract: v2BulkDeleteTablesContract,
-    summary: 'Bulk Delete Tables and Folders',
+    summary: 'Bulk delete tables and folders',
     description:
-      'Archive up to 100 selected tables and folders, including folder contents. Items succeed or fail independently, with `skipped`, `notFound`, and `failed` outcomes. `deletedItems` includes all descendants. Use Restore Table or Restore Folder to recover archived items.\n\nOAuth scope: `api:write`.',
+      'Archive up to 100 selected tables and folders, including folder contents. Items succeed or fail independently, with `skipped`, `notFound`, and `failed` outcomes. `deletedItems` includes all descendants. Use Restore table or Restore folder to recover archived items.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/bulk-delete/route').then((route) => route.POST),
   },
   bulkSaveKnowledgeTagDefinitions: {
     contract: v2BulkSaveKnowledgeTagDefinitionsContract,
-    summary: 'Bulk Save Tag Definitions',
+    summary: 'Bulk save tag definitions',
     description:
-      'Create or update tag definitions, preserving unspecified slots. Updates require `originalDisplayName`; other entries create tags. Slot and name conflicts appear in per-definition `errors` with HTTP `200`, leaving conflicting values unchanged. Use Update Document to set tag values. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Create or update tag definitions, preserving unspecified slots. Updates require `originalDisplayName`; other entries create tags. Slot and name conflicts appear in per-definition `errors` with HTTP `200`, leaving conflicting values unchanged. Use Update document to set tag values. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/tags/route').then((route) => route.PUT),
   },
   bulkUpdateKnowledgeChunks: {
     contract: v2BulkUpdateKnowledgeChunksContract,
-    summary: 'Bulk Update Chunks',
+    summary: 'Bulk update chunks',
     description:
       'Enable, disable, or delete multiple chunks in one best-effort request. Unknown chunk IDs appear in `errors` without failing the request; `processed` counts matched chunks, not changes. Connector-synced chunks are read-only and return `403` with `error.details.code: "CONNECTOR_MANAGED_RESOURCE_READ_ONLY"`; change the source and re-sync, or exclude the document. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -495,9 +495,9 @@ export const V2_MCP_OPERATIONS = {
   },
   bulkUpdateKnowledgeDocuments: {
     contract: v2BulkUpdateKnowledgeDocumentsContract,
-    summary: 'Bulk Enable or Disable Documents',
+    summary: 'Bulk enable or disable documents',
     description:
-      'Enable or disable selected documents, or use `selectAll` for the entire knowledge base. Use Delete Document to remove documents individually. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Enable or disable selected documents, or use `selectAll` for the entire knowledge base. Use Delete document to remove documents individually. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/documents/route').then(
@@ -506,15 +506,15 @@ export const V2_MCP_OPERATIONS = {
   },
   bulkUpdateTableRows: {
     contract: v2BulkUpdateTableRowsContract,
-    summary: 'Bulk Update Rows',
+    summary: 'Bulk update rows',
     description:
-      'Apply separate partial patches to up to 1,000 rows, preserving omitted columns. A row outside the table rejects the entire request with `400` and lists missing IDs. Use Update Rows by Filter to apply one patch to every matching row.\n\nOAuth scope: `api:write`.',
+      'Apply separate partial patches to up to 1,000 rows, preserving omitted columns. A row outside the table rejects the entire request with `400` and lists missing IDs. Use Update rows by filter to apply one patch to every matching row.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/rows/bulk-update/route').then((route) => route.POST),
   },
   cancelOrganizationAccessRequest: {
     contract: v2CancelOrganizationAccessRequestContract,
-    summary: 'Cancel Organization Access Request',
+    summary: 'Cancel organization access request',
     description:
       'Cancel the acting user’s pending request in this scope, including an organization-wide member credit-limit request. Already resolved requests are returned unchanged. Cancellation remains available while requests are disabled. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -525,9 +525,9 @@ export const V2_MCP_OPERATIONS = {
   },
   cancelTableDispatch: {
     contract: v2CancelTableDispatchContract,
-    summary: 'Cancel Run Dispatch',
+    summary: 'Cancel run dispatch',
     description:
-      'Stop a dispatch from scheduling more cells. Already queued or running cells continue; use Cancel Column Runs to stop them. Completed or canceled dispatches return unchanged.\n\nOAuth scope: `api:write`.',
+      'Stop a dispatch from scheduling more cells. Already queued or running cells continue; use Cancel column runs to stop them. Completed or canceled dispatches return unchanged.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/dispatches/[dispatchId]/route').then(
         (route) => route.DELETE
@@ -535,7 +535,7 @@ export const V2_MCP_OPERATIONS = {
   },
   cancelTableExport: {
     contract: v2CancelTableExportContract,
-    summary: 'Cancel Table Export',
+    summary: 'Cancel table export',
     description: 'Cancel an export that is still in progress.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/exports/[exportId]/route').then(
@@ -544,7 +544,7 @@ export const V2_MCP_OPERATIONS = {
   },
   cancelTableImport: {
     contract: v2CancelTableImportContract,
-    summary: 'Cancel Table Import',
+    summary: 'Cancel table import',
     description:
       'Cancel an upload or processing import. Committed row batches remain. Non-cancelable states, including `expired`, return `409`; unknown or purged imports return `404`.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -552,7 +552,7 @@ export const V2_MCP_OPERATIONS = {
   },
   cancelTableRuns: {
     contract: v2CancelTableRunsContract,
-    summary: 'Cancel Column Runs',
+    summary: 'Cancel column runs',
     description:
       'Stop in-flight and pending workflow or enrichment cell runs across the table or one selected row.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -560,9 +560,9 @@ export const V2_MCP_OPERATIONS = {
   },
   cancelWorkflowRun: {
     contract: v2CancelWorkflowRunContract,
-    summary: 'Cancel Workflow Run',
+    summary: 'Cancel workflow run',
     description:
-      'Request cancellation of a running, queued, or paused workflow run. Cancelling a run already in a terminal state is a `200` no-op answered with `success: false` and an `already_*` reason. A run produced by a table workflow group is a `409` when its cell can no longer accept the cancellation.\n\nOAuth scope: `api:write`.',
+      'Request cancellation of a running, queued, or paused workflow run with workspace write access. Cancellation is best effort; inspect the outcome flags and `reason`. A terminal run returns `200` with `success: false` and an `already_*` reason. A table workflow-group run returns `409` when its cell can no longer accept cancellation.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/runs/[runId]/cancel/route').then(
         (route) => route.POST
@@ -570,7 +570,7 @@ export const V2_MCP_OPERATIONS = {
   },
   cancelWorkspaceAccessRequest: {
     contract: v2CancelWorkspaceAccessRequestContract,
-    summary: 'Cancel Workspace Access Request',
+    summary: 'Cancel workspace access request',
     description:
       'Cancel the acting user’s pending request in this scope, including an organization-wide member credit-limit request. Already resolved requests are returned unchanged. Cancellation remains available while requests are disabled. Requires access to the workspace; external collaborators use their workspace grant. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -585,9 +585,9 @@ export const V2_MCP_OPERATIONS = {
   },
   compareWorkflowVersions: {
     contract: v2CompareWorkflowVersionsContract,
-    summary: 'Compare Workflow Versions',
+    summary: 'Compare workflow versions',
     description:
-      'Compare two deployment versions of the same workflow. Reports semantic changes, excluding canvas layout; credential-bearing values are withheld while their changes remain visible. Connections include stable block and port identifiers. The combined snapshots and the comparison result must each fit within 16 MiB.\n\nOAuth scope: `api:read`.',
+      'Compare two deployment versions of the same workflow with workspace read access. The comparison excludes layout changes and withholds credential-bearing values while reporting their changes. Connections include stable block and port IDs. The combined snapshots and the comparison result must each fit within 16 MiB.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/versions/compare/route').then(
         (route) => route.GET
@@ -595,7 +595,7 @@ export const V2_MCP_OPERATIONS = {
   },
   completeFileUpload: {
     contract: v2CompleteFileUploadContract,
-    summary: 'Complete File Upload',
+    summary: 'Complete file upload',
     description:
       'Finalize an upload and register its workspace file. Repeating a completed upload returns the existing file.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -603,7 +603,7 @@ export const V2_MCP_OPERATIONS = {
   },
   completeKnowledgeDocumentUpload: {
     contract: v2CompleteKnowledgeDocumentUploadContract,
-    summary: 'Complete Document Upload',
+    summary: 'Complete document upload',
     description:
       'Verify a direct upload or assemble multipart parts, create the knowledge document, and queue asynchronous processing.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -613,7 +613,7 @@ export const V2_MCP_OPERATIONS = {
   },
   completeTableImport: {
     contract: v2CompleteTableImportContract,
-    summary: 'Complete Table Import Upload',
+    summary: 'Complete table import upload',
     description:
       'Verify or assemble uploaded CSV bytes and start processing under the same import ID. Requires an import awaiting upload completion; other states return `409`. Unknown or purged imports return `404`.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -621,42 +621,42 @@ export const V2_MCP_OPERATIONS = {
   },
   createCredentialConnection: {
     contract: v2CreateCredentialConnectionContract,
-    summary: 'Create Credential Connection',
+    summary: 'Create credential connection',
     description:
-      'Create a short-lived browser URL for connecting an OAuth provider or reconnecting an existing OAuth credential. Open the URL, sign in as the authenticated user, complete provider authorization, then refresh the credentials list. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Create a short-lived browser URL to connect an OAuth provider or reconnect a credential. Requires workspace write access; reconnecting also requires credential Admin access. Open the URL, sign in as the acting user, complete provider authorization, then refresh List credentials. QuickBooks requires caller-managed `oauthClientConfig` for either flow. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/credentials/connections/route').then((route) => route.POST),
   },
   createCustomTool: {
     contract: v2CreateCustomToolContract,
-    summary: 'Create Custom Tool',
+    summary: 'Create custom tool',
     description:
-      'Create a code-backed custom tool in a workspace. Its title must be unique because tools resolve by title at call time.\n\nOAuth scope: `api:write`.',
+      'Create a code-backed custom tool. Its title must be unique within the workspace because tools resolve by title at call time. Requires workspace write access.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/custom-tools/route').then((route) => route.POST),
   },
   createFile: {
     contract: v2CreateFileContract,
-    summary: 'Create File',
+    summary: 'Create file',
     description:
       'Create a workspace file from inline UTF-8 or base64 content. Use an upload session for streamed or larger files.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/route').then((route) => route.POST),
   },
   createFileFolder: {
     contract: v2CreateFileFolderContract,
-    summary: 'Create Folder',
+    summary: 'Create folder',
     description: 'Create a folder at the supplied workspace path.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/folders/route').then((route) => route.POST),
   },
   createFileUpload: {
     contract: v2CreateFileUploadContract,
-    summary: 'Create File Upload',
+    summary: 'Create file upload',
     description:
       'Create a resumable upload session and receive either a signed PUT URL or multipart instructions.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/uploads/route').then((route) => route.POST),
   },
   createFileUploadPartUrls: {
     contract: v2CreateFileUploadPartUrlsContract,
-    summary: 'Create File Upload Part URLs',
+    summary: 'Create file upload part URLs',
     description:
       'Create signed URLs for a bounded set of multipart upload part numbers.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -664,16 +664,16 @@ export const V2_MCP_OPERATIONS = {
   },
   createKnowledgeBase: {
     contract: v2CreateKnowledgeBaseContract,
-    summary: 'Create Knowledge Base',
+    summary: 'Create knowledge base',
     description:
       'Create a knowledge base in a workspace with optional folder placement and chunking configuration. An unknown `folderPath` returns `404`. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/knowledge/route').then((route) => route.POST),
   },
   createKnowledgeChunk: {
     contract: v2CreateKnowledgeChunkContract,
-    summary: 'Create Chunk',
+    summary: 'Create chunk',
     description:
-      'Append a chunk, embedding it before the response so it is immediately searchable. It inherits the document\'s tags and next `chunkIndex`. Connector-synced chunks are read-only and return `403` with `error.details.code: "CONNECTOR_MANAGED_RESOURCE_READ_ONLY"`; change the source and re-sync, or exclude the document. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Append a chunk and embed it before returning. It inherits the document\'s tags and next `chunkIndex`. Search includes it when the chunk and document are enabled and the document has completed processing. Connector-synced chunks are read-only and return `403` with `error.details.code: "CONNECTOR_MANAGED_RESOURCE_READ_ONLY"`; change the source and re-sync, or exclude the document. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/documents/[documentId]/chunks/route').then(
@@ -682,7 +682,7 @@ export const V2_MCP_OPERATIONS = {
   },
   createKnowledgeConnector: {
     contract: v2CreateKnowledgeConnectorContract,
-    summary: 'Create Knowledge Connector',
+    summary: 'Create knowledge connector',
     description:
       'Validate and connect an external source, then queue its initial synchronization. The `apiKey` field is never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -693,7 +693,7 @@ export const V2_MCP_OPERATIONS = {
   },
   createKnowledgeDocumentUpload: {
     contract: v2CreateKnowledgeDocumentUploadContract,
-    summary: 'Create Document Upload',
+    summary: 'Create document upload',
     description:
       'Create a resumable upload session and receive direct PUT or multipart transfer instructions.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -703,7 +703,7 @@ export const V2_MCP_OPERATIONS = {
   },
   createKnowledgeDocumentUploadPartUrls: {
     contract: v2CreateKnowledgeDocumentUploadPartUrlsContract,
-    summary: 'Create Document Upload Part URLs',
+    summary: 'Create document upload part URLs',
     description:
       'Create short-lived signed PUT URLs for up to 100 multipart part numbers.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -713,32 +713,32 @@ export const V2_MCP_OPERATIONS = {
   },
   createKnowledgeFolder: {
     contract: v2CreateKnowledgeFolderContract,
-    summary: 'Create Folder',
+    summary: 'Create folder',
     description:
       'Create a folder in the knowledge-base folder tree. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/knowledge/folders/route').then((route) => route.POST),
   },
   createKnowledgeTag: {
     contract: v2CreateKnowledgeTagContract,
-    summary: 'Create Tag',
+    summary: 'Create tag',
     description:
-      'Create a tag definition. Write document values by `tagSlot` and filter by `displayName`. Omitting `tagSlot` selects a free slot; exhaustion returns `400`. An occupied slot or duplicate name returns `409`. Use Bulk Save Tag Definitions for multiple definitions. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Create a tag definition. Write document values by `tagSlot` and filter by `displayName`. Omitting `tagSlot` selects a free slot; exhaustion returns `400`. An occupied slot or duplicate name returns `409`. Use Bulk save tag definitions for multiple definitions. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/tags/route').then((route) => route.POST),
   },
   createMcpServer: {
     contract: v2CreateMcpServerContract,
-    summary: 'Create MCP Server',
+    summary: 'Create MCP server',
     description:
-      'Register an external MCP server without connecting to it. A duplicate URL returns `409`; use Update MCP Server to change the existing registration. The server remains disconnected until List MCP Server Tools succeeds.\n\nOAuth scope: `api:write`.',
+      'Register an external MCP server without establishing a tool connection; registration may probe its authentication method. A duplicate URL returns `409`; use Update MCP server to change the registration. It stays disconnected until List MCP server tools succeeds. Requires workspace write access.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/mcp-servers/route').then((route) => route.POST),
   },
   createOrganizationAccessRequest: {
     contract: v2CreateOrganizationAccessRequestContract,
-    summary: 'Create Organization Access Request',
+    summary: 'Create organization access request',
     description:
-      'Request access for the acting user using a target from discovery. Returns an existing matching pending request when applicable; the result may be closed if access is already available. Permission approvals change the governing group for all affected members. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Request access using a target from Discover organization access requests. Requires organization membership and requests enabled. Each requester can have 100 pending requests and submit 100 in 24 hours within the organization. Matching pending requests are reused; an existing request may be closed if access is already available. Permission approvals change the governing group for all affected members. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/access-requests/route').then(
@@ -747,9 +747,9 @@ export const V2_MCP_OPERATIONS = {
   },
   createOrganizationInvitation: {
     contract: v2CreateOrganizationInvitationContract,
-    summary: 'Create Organization Invitation',
+    summary: 'Create organization invitation',
     description:
-      'Email an invitation to join the organization as a member or administrator. Requires organization administrator access, invitations enabled, and an available seat on an eligible plan. This grants no workspace-specific permissions. An unexpired pending invitation for the email conflicts; use Resend Organization Invitation to send it again. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Email an invitation to join the organization as a member or Admin. Requires organization Admin access and invitations enabled; an eligible plan and available seat are required when billing is enabled. It grants no workspace-specific permissions. Existing organization membership or an unexpired pending invitation for the email returns `409`. Use Resend organization invitation to send a pending invitation again. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/invitations/route').then(
@@ -758,9 +758,9 @@ export const V2_MCP_OPERATIONS = {
   },
   createPermissionGroup: {
     contract: v2CreatePermissionGroupContract,
-    summary: 'Create Permission Group',
+    summary: 'Create permission group',
     description:
-      'Create a permission group. A non-default group requires workspaces and initially governs everyone in them. Creating a default group demotes the previous default to an inactive group until it is assigned workspaces. Overlapping all-member scopes conflict. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Create a permission group. A non-default group requires workspaces and initially governs everyone in them. Creating a default group demotes the previous default to an inactive group until it is assigned workspaces. Overlapping all-member scopes conflict. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/permission-groups/route').then(
@@ -769,46 +769,46 @@ export const V2_MCP_OPERATIONS = {
   },
   createSandbox: {
     contract: v2CreateSandboxContract,
-    summary: 'Create Sandbox',
+    summary: 'Create sandbox',
     description:
-      'Create a uniquely named dependency environment. If a build is needed, track readiness with `buildStatus`; null means no build is required. Invalid dependencies return `400` with field details. Requires workspace admin access on Max or Enterprise. Creates and updates share a rate limit; respect `Retry-After`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Create a uniquely named dependency environment. Requires workspace Admin access and a configured remote Function runtime. With billing enabled, Max or Enterprise is required unless deployment entitlement overrides it; billing-disabled deployments require sandbox entitlement. Poll Get sandbox for `buildStatus`; `null` means no image build is needed. Invalid dependencies return `400` with field details. Creates and updates share a rate limit; respect `Retry-After`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/sandboxes/route').then((route) => route.POST),
   },
   createServiceAccountCredential: {
     contract: v2CreateServiceAccountCredentialContract,
-    summary: 'Create Service-Account Credential',
+    summary: 'Create service-account credential',
     description:
-      'Verify and store a service-account credential using the fields from List Credential Providers, encoded as a JSON object string in `credentials`. Secrets are never returned. A matching source returns the existing credential with `200`; creation returns `201`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Verify and store a service-account credential. Use the fields from List credential providers, encoded as a JSON object string in `credentials`. Requires workspace write access. A matching source returns the existing credential with `200`; creation returns `201`. Stored secrets are omitted from the response. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/credentials/route').then((route) => route.POST),
   },
   createSkill: {
     contract: v2CreateSkillContract,
-    summary: 'Create Skill',
+    summary: 'Create skill',
     description:
-      'Create one skill in a workspace. Its kebab-case name must be unique and cannot be reserved by a built-in skill. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Create a workspace skill with a unique kebab-case name that is not reserved by a built-in skill. Requires workspace write access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/skills/route').then((route) => route.POST),
   },
   createTable: {
     contract: v2CreateTableContract,
-    summary: 'Create Table',
+    summary: 'Create table',
     description:
       'Create a table with a typed column schema and optional folder placement.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/route').then((route) => route.POST),
   },
   createTableDispatch: {
     contract: v2CreateTableDispatchContract,
-    summary: 'Create Run Dispatch',
+    summary: 'Create run dispatch',
     description:
-      'Start workflow or enrichment groups across all rows or selected rows. Poll Get Run Dispatch until `complete` or `canceled`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`. Use Cancel Run Dispatch to stop further scheduling.\n\nOAuth scope: `api:write`.',
+      'Start workflow or enrichment groups across all rows or selected rows. Poll Get run dispatch until `complete` or `canceled`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`. Use Cancel run dispatch to stop further scheduling.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/dispatches/route').then((route) => route.POST),
   },
   createTableExport: {
     contract: v2CreateTableExportContract,
-    summary: 'Create Table Export',
+    summary: 'Create table export',
     description:
       'Create a CSV or JSON export. Exports of small tables finish during the request; larger exports run asynchronously.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -816,21 +816,21 @@ export const V2_MCP_OPERATIONS = {
   },
   createTableFolder: {
     contract: v2CreateTableFolderContract,
-    summary: 'Create Folder',
+    summary: 'Create folder',
     description:
       'Create one table-folder leaf whose parent path already exists.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/folders/route').then((route) => route.POST),
   },
   createTableImport: {
     contract: v2CreateTableImportContract,
-    summary: 'Create Table Import',
+    summary: 'Create table import',
     description:
       'Create a CSV import. Upload sources receive signed transfer instructions; workspace-file sources start processing directly.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/imports/route').then((route) => route.POST),
   },
   createTableImportPartUrls: {
     contract: v2CreateTableImportPartUrlsContract,
-    summary: 'Create Table Import Part URLs',
+    summary: 'Create table import part URLs',
     description:
       'Create signed URLs for multipart upload parts. Requires the `uploading` state; other states return `409`. Unknown or purged imports return `404`.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -838,45 +838,45 @@ export const V2_MCP_OPERATIONS = {
   },
   createTableRows: {
     contract: v2CreateTableRowsContract,
-    summary: 'Create Rows',
+    summary: 'Create rows',
     description:
       'Insert one row with a data object or insert a bounded batch with a rows array. Cell keys are column names.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/rows/route').then((route) => route.POST),
   },
   createTableView: {
     contract: v2CreateTableViewContract,
-    summary: 'Create View',
+    summary: 'Create view',
     description:
       'Save a filter, sort, and column layout as a named presentation of a table.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/views/route').then((route) => route.POST),
   },
   createWorkflow: {
     contract: v2CreateWorkflowContract,
-    summary: 'Create Workflow',
+    summary: 'Create workflow',
     description:
-      'Create a workflow at the workspace root or in a workflow folder. The response includes seeded blocks and their IDs for attaching edges. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
+      'Create an undeployed workflow at the workspace root or in a workflow folder. Requires workspace write access. The response includes the seeded start block and its ID for connecting other blocks. A name already used in the destination folder returns `409`. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/workflows/route').then((route) => route.POST),
   },
   createWorkflowFolder: {
     contract: v2CreateWorkflowFolderContract,
-    summary: 'Create Workflow Folder',
+    summary: 'Create workflow folder',
     description:
-      'Create a workflow folder in a workspace. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
+      'Create a workflow folder at a non-root path with workspace write access. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/workflows/folders/route').then((route) => route.POST),
   },
   createWorkflowMcpServer: {
     contract: v2CreateWorkflowMcpServerContract,
-    summary: 'Create Workflow MCP Server',
+    summary: 'Create workflow MCP server',
     description:
-      'Create an MCP server that exposes deployed workflows as tools. Every supplied workflow must already be deployed. With `isPublic: true`, anyone with the server URL can execute its workflows without a Sim API key. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Create an MCP server exposing deployed workflows as tools. Every supplied workflow must already be deployed. With `isPublic: true`, anyone holding the server URL can execute its workflows without a Sim API key. Requires workspace Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/workflow-mcp-servers/route').then((route) => route.POST),
   },
   createWorkspaceAccessRequest: {
     contract: v2CreateWorkspaceAccessRequestContract,
-    summary: 'Create Workspace Access Request',
+    summary: 'Create workspace access request',
     description:
-      'Request access for the acting user using a target from discovery. Returns an existing matching pending request when applicable; the result may be closed if access is already available. Permission approvals change the governing group for all affected members. Requires access to the workspace; external collaborators use their workspace grant. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Request access using a target from Discover workspace access requests. Requires access to an organization-owned workspace with requests enabled; external collaborators use their workspace grant. Each requester can have 100 pending requests and submit 100 in 24 hours within the organization. Matching pending requests are reused; an existing request may be closed if access is already available. Permission approvals change the governing group for all affected members. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/access-requests/route').then(
@@ -885,63 +885,63 @@ export const V2_MCP_OPERATIONS = {
   },
   createWorkspaceInvitations: {
     contract: v2CreateWorkspaceInvitationsContract,
-    summary: 'Create Workspace Invitations',
+    summary: 'Create workspace invitations',
     description:
-      'Invite people to a workspace or grant access immediately to existing organization members. Requires workspace administrator access and current invitation eligibility; organization administrator invitations also require organization administrator access. Recipients are processed independently: inspect failed even after HTTP 200, and inspect invitation status before retrying a delivery failure. Existing access is preserved. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Invite people to a workspace or grant access immediately to existing organization members. Requires workspace Admin access and current invitation eligibility; invitations offering organization Admin membership also require organization Admin access. Recipients are processed independently: inspect `failed` even after HTTP `200`, and inspect invitation status before retrying a delivery failure. Existing access is preserved. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/invitations/route').then((route) => route.POST),
   },
   deleteCredential: {
     contract: v2DeleteCredentialContract,
-    summary: 'Disconnect Credential',
+    summary: 'Disconnect credential',
     description:
-      'Disconnect an OAuth or service-account credential and clear its stored workflow, deployment, paused-run, knowledge-connector, and webhook references. Credential admin access is required. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Disconnect an OAuth or service-account credential and clear its stored workflow, deployment, paused-run, knowledge-connector, and webhook references. Requires credential Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/credentials/[credentialId]/route').then((route) => route.DELETE),
   },
   deleteCustomTool: {
     contract: v2DeleteCustomToolContract,
-    summary: 'Delete Custom Tool',
+    summary: 'Delete custom tool',
     description:
-      'Delete a custom tool. Agent blocks retain their configuration but can no longer call the deleted tool.\n\nOAuth scope: `api:write`.',
+      'Delete a custom tool. Agent blocks retain their configuration but can no longer call the deleted tool. Requires workspace write access.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/custom-tools/[customToolId]/route').then((route) => route.DELETE),
   },
   deleteFile: {
     contract: v2DeleteFileContract,
-    summary: 'Delete File',
+    summary: 'Delete file',
     description:
-      'Archive a workspace file, retaining its stored bytes and removing API read access. List Files with `scope=archived` finds it; Restore File recovers it. Archiving an already archived file returns `404`.\n\nOAuth scope: `api:write`.',
+      'Archive a workspace file, retaining its stored bytes and removing API read access. List files with `scope=archived` finds it; Restore file recovers it. Archiving an already archived file returns `404`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/[fileId]/route').then((route) => route.DELETE),
   },
   deleteFileFolder: {
     contract: v2DeleteFileFolderContract,
-    summary: 'Delete Folder',
+    summary: 'Delete folder',
     description:
-      'Archive an empty folder, or set `recursive=true` to archive its files and subfolders. Use Restore Folder to recover the archived contents.\n\nOAuth scope: `api:write`.',
+      'Archive an empty folder, or set `recursive=true` to archive its files and subfolders. Use Restore folder to recover the archived contents.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/folders/route').then((route) => route.DELETE),
   },
   deleteFileVersion: {
     contract: v2DeleteFileVersionContract,
-    summary: 'Delete File Version',
+    summary: 'Delete file version',
     description:
-      'Permanently delete one earlier version and its stored content, for example to purge a leaked value from history before retention removes it. The current version returns `409`; revert to another version first. A version that does not exist returns `404`.\n\nOAuth scope: `api:write`.',
+      'Permanently remove an earlier version from history and schedule deletion of its stored content. Storage cleanup may retry in the background. The current version returns `409`; revert to another version first. A version that does not exist returns `404`.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/files/[fileId]/versions/[version]/route').then((route) => route.DELETE),
   },
   deleteKnowledgeBase: {
     contract: v2DeleteKnowledgeBaseContract,
-    summary: 'Delete Knowledge Base',
+    summary: 'Delete knowledge base',
     description:
-      'Archive a knowledge base, its documents, and its connectors, pausing synchronization. Use List Knowledge Bases with `scope=archived` to find it and Restore Knowledge Base to recover it.\n\nOAuth scope: `api:write`.',
+      'Archive a knowledge base, its documents, and its connectors, pausing synchronization. Use List knowledge bases with `scope=archived` to find it and Restore knowledge base to recover it.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/route').then((route) => route.DELETE),
   },
   deleteKnowledgeChunk: {
     contract: v2DeleteKnowledgeChunkContract,
-    summary: 'Delete Chunk',
+    summary: 'Delete chunk',
     description:
       'Permanently remove one chunk and subtract it from document counts. Remaining `chunkIndex` values stay stable and may become non-contiguous. Connector-synced chunks are read-only and return `403` with `error.details.code: "CONNECTOR_MANAGED_RESOURCE_READ_ONLY"`; change the source and re-sync, or exclude the document. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -952,7 +952,7 @@ export const V2_MCP_OPERATIONS = {
   },
   deleteKnowledgeConnector: {
     contract: v2DeleteKnowledgeConnectorContract,
-    summary: 'Delete Knowledge Connector',
+    summary: 'Delete knowledge connector',
     description:
       'Delete a connector and optionally its synchronized documents. Documents are retained by default. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -963,7 +963,7 @@ export const V2_MCP_OPERATIONS = {
   },
   deleteKnowledgeDocument: {
     contract: v2DeleteKnowledgeDocumentContract,
-    summary: 'Delete Document',
+    summary: 'Delete document',
     description:
       'Remove a document from listings and search. Uploaded documents and their chunks are deleted. Connector documents are excluded while retaining their stored data; later synchronization does not re-add them.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -973,14 +973,14 @@ export const V2_MCP_OPERATIONS = {
   },
   deleteKnowledgeFolder: {
     contract: v2DeleteKnowledgeFolderContract,
-    summary: 'Delete Folder',
+    summary: 'Delete folder',
     description:
-      'Archive an empty folder, or set `recursive=true` to archive its subfolders and knowledge bases. Use Restore Knowledge Base to recover knowledge bases.\n\nOAuth scope: `api:write`.',
+      'Archive an empty folder, or set `recursive=true` to archive its subfolders and knowledge bases. Use Restore knowledge base to recover knowledge bases.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/knowledge/folders/route').then((route) => route.DELETE),
   },
   deleteKnowledgeTag: {
     contract: v2DeleteKnowledgeTagContract,
-    summary: 'Delete Tag',
+    summary: 'Delete tag',
     description:
       'Permanently delete a tag definition and its values from every document and chunk in the knowledge base. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -991,26 +991,26 @@ export const V2_MCP_OPERATIONS = {
   },
   deleteKnowledgeTagDefinitions: {
     contract: v2DeleteKnowledgeTagDefinitionsContract,
-    summary: 'Delete Tag Definitions',
+    summary: 'Delete tag definitions',
     description:
-      'Delete unused tag definitions by default. With `unused=false`, permanently delete all definitions and their values from documents and chunks. Use Delete Tag to remove one definition. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Delete unused tag definitions by default. With `unused=false`, permanently delete all definitions and their values from documents and chunks. Use Delete tag to remove one definition. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/tags/route').then((route) => route.DELETE),
   },
   deleteMcpServer: {
     contract: v2DeleteMcpServerContract,
-    summary: 'Delete MCP Server',
+    summary: 'Delete MCP server',
     description:
-      "Remove an MCP server and revoke its OAuth tokens. Workflows retain blocks that referenced the server's tools, but those tools can no longer be called.\n\nOAuth scope: `api:write`.",
+      'Remove an external MCP server and revoke its OAuth tokens. Workflow blocks retain references to its tools, but those tools can no longer be called. Requires workspace write access.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/mcp-servers/[mcpServerId]/route').then((route) => route.DELETE),
   },
   deletePermissionGroup: {
     contract: v2DeletePermissionGroupContract,
-    summary: 'Delete Permission Group',
+    summary: 'Delete permission group',
     description:
-      'Permanently delete a permission group and its membership assignments. Members then inherit any other applicable restrictions. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Permanently delete a permission group and its membership assignments. Members then inherit any other applicable restrictions. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/permission-groups/[groupId]/route').then(
@@ -1019,33 +1019,33 @@ export const V2_MCP_OPERATIONS = {
   },
   deleteSandbox: {
     contract: v2DeleteSandboxContract,
-    summary: 'Delete Sandbox',
+    summary: 'Delete sandbox',
     description:
-      'Delete a sandbox. Function blocks using it fail until reconfigured. Requires workspace admin access on Max or Enterprise. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Delete a sandbox. Function blocks using it fail until reconfigured. Requires workspace Admin access and sandbox entitlement: with billing enabled, Max or Enterprise is required unless deployment entitlement overrides it; billing-disabled deployments require sandbox entitlement. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/sandboxes/[sandboxId]/route').then((route) => route.DELETE),
   },
   deleteSecret: {
     contract: v2DeleteSecretContract,
-    summary: 'Delete Secret',
+    summary: 'Delete secret',
     description:
-      'Delete a workspace or caller-owned personal secret without reading or returning its stored value. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Delete a workspace or caller-owned personal secret without returning its value. Workspace secrets require workspace Admin or secret Admin access. Deleting a personal secret removes it for the caller across all workspaces. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/secrets/[name]/route').then((route) => route.DELETE),
   },
   deleteSkill: {
     contract: v2DeleteSkillContract,
-    summary: 'Delete Skill',
+    summary: 'Delete skill',
     description:
-      'Delete a workspace skill. Built-in skills are read-only and cannot be deleted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Delete a workspace skill. Requires skill editor or workspace Admin access. Built-in skills cannot be deleted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/skills/[skillId]/route').then((route) => route.DELETE),
   },
   deleteSsoProvider: {
     contract: v2DeleteSsoProviderContract,
-    summary: 'Delete SSO Provider',
+    summary: 'Delete SSO provider',
     description:
-      'Remove an identity provider and clear its primary selection. Requires organization administrator access. Existing accounts, memberships, and sessions remain; sign-in falls back to another verified provider on the domain. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Remove an identity provider and clear its primary selection. Requires organization Admin access. Existing accounts, memberships, and sessions remain. Domain sign-in falls back to another verified provider if one remains; use Get SSO policy to inspect whether SSO is still enforced. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/sso/providers/[providerId]/route').then(
@@ -1054,14 +1054,14 @@ export const V2_MCP_OPERATIONS = {
   },
   deleteTable: {
     contract: v2DeleteTableContract,
-    summary: 'Delete Table',
+    summary: 'Delete table',
     description:
-      'Archive a table while retaining its rows. Use List Tables with `scope=archived` to find it and Restore Table to recover it.\n\nOAuth scope: `api:write`.',
+      'Archive a table while retaining its rows. Use List tables with `scope=archived` to find it and Restore table to recover it.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/route').then((route) => route.DELETE),
   },
   deleteTableColumn: {
     contract: v2DeleteTableColumnContract,
-    summary: 'Delete Column',
+    summary: 'Delete column',
     description:
       'Delete a column by name while preserving at least one table column.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -1069,28 +1069,28 @@ export const V2_MCP_OPERATIONS = {
   },
   deleteTableFolder: {
     contract: v2DeleteTableFolderContract,
-    summary: 'Delete Folder',
+    summary: 'Delete folder',
     description:
-      'Archive an empty folder, or set `recursive=true` to archive its tables and subfolders. Use Restore Folder to recover the archived contents.\n\nOAuth scope: `api:write`.',
+      'Archive an empty folder, or set `recursive=true` to archive its tables and subfolders. Use Restore folder to recover the archived contents.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/folders/route').then((route) => route.DELETE),
   },
   deleteTableRow: {
     contract: v2DeleteTableRowContract,
-    summary: 'Delete Row',
+    summary: 'Delete row',
     description: 'Delete one row by identifier.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/rows/[rowId]/route').then((route) => route.DELETE),
   },
   deleteTableRows: {
     contract: v2DeleteTableRowsContract,
-    summary: 'Delete Rows',
+    summary: 'Delete rows',
     description:
       'Delete rows by a non-empty predicate or an explicit bounded list of row identifiers.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/rows/route').then((route) => route.DELETE),
   },
   deleteTableView: {
     contract: v2DeleteTableViewContract,
-    summary: 'Delete View',
+    summary: 'Delete view',
     description:
       'Delete a saved presentation without changing any table rows.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -1098,17 +1098,17 @@ export const V2_MCP_OPERATIONS = {
   },
   deleteWorkflow: {
     contract: v2DeleteWorkflowContract,
-    summary: 'Delete Workflow',
+    summary: 'Delete workflow',
     description:
-      'Archive a workflow and stop its schedules, webhooks, MCP tools, and chats. Use List Workflows with `scope=archived` to find it and Restore Workflow to recover it and its archived resources. Both `deleted` and `archived` acknowledge archival.\n\nOAuth scope: `api:write`.',
+      'Archive a workflow and stop its schedules, webhooks, MCP tools, and hosted chat. Requires workspace write access. Find it with List workflows (`scope=archived`) and recover it with Restore workflow. Both `deleted` and `archived` acknowledge archival.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/route').then((route) => route.DELETE),
   },
   deleteWorkflowChatDeployment: {
     contract: v2DeleteWorkflowChatDeploymentContract,
-    summary: 'Delete Workflow Chat Deployment',
+    summary: 'Delete workflow chat deployment',
     description:
-      "Remove a workflow's hosted chat and release its URL identifier. The workflow API deployment remains active; use Undeploy Workflow to stop it. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+      'Remove the hosted chat and release its URL identifier with workspace Admin access. The workflow API deployment remains active; use Undeploy workflow to stop it. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/deployments/chat/route').then(
@@ -1117,14 +1117,14 @@ export const V2_MCP_OPERATIONS = {
   },
   deleteWorkflowFolder: {
     contract: v2DeleteWorkflowFolderContract,
-    summary: 'Delete Workflow Folder',
+    summary: 'Delete workflow folder',
     description:
-      'Archive an empty workflow folder, or set `recursive=true` to archive its subfolders and workflows. Use Restore Workflow to recover workflows.\n\nOAuth scope: `api:write`.',
+      "Archive an empty workflow folder with workspace write access. `recursive=true` also archives its subfolders and workflows, stopping the archived workflows' triggers and hosted surfaces. Use Restore workflow to recover workflows.\n\nOAuth scope: `api:write`.",
     handler: () => import('@/app/api/v2/workflows/folders/route').then((route) => route.DELETE),
   },
   deleteWorkflowGroup: {
     contract: v2DeleteWorkflowGroupContract,
-    summary: 'Delete Workflow Group',
+    summary: 'Delete workflow group',
     description:
       'Delete a workflow group and every table column populated by that group.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -1132,27 +1132,27 @@ export const V2_MCP_OPERATIONS = {
   },
   deleteWorkflowMcpServer: {
     contract: v2DeleteWorkflowMcpServerContract,
-    summary: 'Delete Workflow MCP Server',
+    summary: 'Delete workflow MCP server',
     description:
-      'Delete a workflow MCP server and stop serving its tools. The underlying workflows remain deployed and executable through the workflow API. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Delete a workflow MCP server and stop serving its tools. Its workflows remain deployed and executable through the workflow API. Requires workspace Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflow-mcp-servers/[serverId]/route').then((route) => route.DELETE),
   },
   deployWorkflow: {
     contract: v2DeployWorkflowContract,
-    summary: 'Deploy Workflow',
+    summary: 'Deploy workflow',
     description:
-      'Create and asynchronously activate a deployment version. Every call creates a new version; retrying after a timeout can create a duplicate. Read Get Workflow Deployment to check activation. `lint` reports advisory findings for the published version; they never block the deploy. A conflicting webhook path returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Create a deployment version and activate it asynchronously. Requires workspace Admin access. Each accepted deploy creates a new version; retrying after a timeout can create a duplicate. Poll Get workflow deployment for the accepted `latestDeploymentAttempt` before treating the version as live.\n\n`lint` reports advisory findings for this version and never blocks deployment. A conflicting webhook path returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/deploy/route').then((route) => route.POST),
   },
   deployWorkflowMcpTool: {
     contract: v2DeployWorkflowMcpToolContract,
-    summary: 'Publish Workflow As MCP Tool',
+    summary: 'Deploy workflow as MCP tool',
     description:
-      'Publish a deployed workflow as an MCP tool using its deployed input schema. Each server has at most one tool per workflow; repeating the call replaces that tool and returns `200` with `updated: true`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Deploy a workflow as an MCP tool using its deployed input schema. The workflow must already be deployed. Each server has at most one tool per workflow; repeating the call replaces the tool and returns `200` with `updated: true`. Requires workspace Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflow-mcp-servers/[serverId]/tools/route').then(
@@ -1161,7 +1161,7 @@ export const V2_MCP_OPERATIONS = {
   },
   discoverOrganizationAccessRequests: {
     contract: v2DiscoverOrganizationAccessRequestsContract,
-    summary: 'Discover Organization Access Requests',
+    summary: 'Discover organization access requests',
     description:
       'Discover the acting user’s access to features, integrations, models, tools, authentication methods, and member credit limits. Returns an empty list while requests are disabled. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1172,7 +1172,7 @@ export const V2_MCP_OPERATIONS = {
   },
   discoverWorkspaceAccessRequests: {
     contract: v2DiscoverWorkspaceAccessRequestsContract,
-    summary: 'Discover Workspace Access Requests',
+    summary: 'Discover workspace access requests',
     description:
       'Discover the acting user’s access to features, integrations, models, tools, authentication methods, and member credit limits. Returns an empty list while requests are disabled. Requires access to the workspace; external collaborators use their workspace grant. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1183,55 +1183,55 @@ export const V2_MCP_OPERATIONS = {
   },
   duplicateWorkflow: {
     contract: v2DuplicateWorkflowContract,
-    summary: 'Duplicate Workflow',
+    summary: 'Duplicate workflow',
     description:
-      "Copy a workflow's graph and variables into the same workspace. Omit `name` to reuse the source name; name collisions in the destination folder are resolved automatically. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+      "Create an undeployed copy of a workflow's graph and variables in the same workspace. Requires workspace write access. The destination folder and name default to the source; name collisions in the destination are resolved automatically. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/duplicate/route').then((route) => route.POST),
   },
   editFileContent: {
     contract: v2EditFileContentContract,
-    summary: 'Edit File Content',
+    summary: 'Edit file content',
     description:
-      'Edit part of a UTF-8 file; use Replace File Content to replace it entirely. Search-and-replace requires one exact match unless `replaceAll` is true. Anchored modes match trimmed complete lines; their input descriptions specify boundary handling. Non-UTF-8 files return `400`. Concurrent writes return `409`; re-read before retrying.\n\nOAuth scope: `api:write`.',
+      'Edit part of a UTF-8 file; use Replace file content to replace it entirely. Search-and-replace requires one exact match unless `replaceAll` is true. Anchored modes match trimmed complete lines; their input descriptions specify boundary handling. Non-UTF-8 files return `400`. Concurrent writes return `409`; re-read before retrying.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/[fileId]/content/route').then((route) => route.PATCH),
   },
   executeTool: {
     contract: v2ExecuteToolContract,
-    summary: 'Run Tool',
+    summary: 'Run tool',
     description:
-      'Run a built-in tool using published parameter IDs. Sim resolves `credentialId`, hosted keys, and whole-value `{{VAR_NAME}}` references for `user-only` parameters; other values pass through verbatim. Third-party refusal returns `200` with `status: "failed"`; the error envelope covers API failures. Hidden or missing tools return `404`; disallowed integrations return `403` with `error.details.code: INTEGRATION_NOT_ALLOWED`. Hosted-key use is billed to the workspace; a call that would use a hosted key from a workspace over its usage or billing limits returns `402`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Run a built-in tool using published parameter IDs. Requires workspace read access. Sim resolves `credentialId`, hosted keys, and whole-value `{{VAR_NAME}}` references in `user-only` parameters; other values pass through unchanged. Send connected credentials as top-level `credentialId`, not inside `input`. Third-party refusal returns `200` with `status: "failed"`; API failures use the error envelope. Hidden or missing tools return `404`; disallowed integrations return `403` with `error.details.code: INTEGRATION_NOT_ALLOWED`. Hosted-key usage is billed to the workspace. A call that would use a hosted key returns `402` when the workspace exceeds usage or billing limits. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/tools/[toolId]/execute/route').then((route) => route.POST),
   },
   executeWorkflow: {
     contract: v2ExecuteWorkflowContract,
-    summary: 'Execute Workflow',
+    summary: 'Execute workflow',
     description:
-      'Execute a deployment or use `run.source: "manual"` for the draft. Manual runs require personal or OAuth write access and reject async. Public deployments allow anonymous sync or streaming. Request `application/x-ndjson` for heartbeats and the final result. Timeouts return `200` with failed status and `TIMEOUT`. Supply `X-Run-Id` to prevent duplicate execution; reuse returns `409`, never a replay. Input descriptions specify compatible modes; invalid combinations return `400`.\n\nOAuth scope: `api:write`.',
+      'Run the active deployment, or set `run.source: "manual"` to run the saved draft. Deployed execution requires workspace read access and OAuth `api:write` scope or an API key; public deployments also allow anonymous synchronous or streamed runs. Manual runs require personal-key or OAuth write access and cannot be async.\n\nUse `async: true` for a queue receipt, or `stream: true` for SSE. For a synchronous run with both flags false, send `Accept: application/x-ndjson` for heartbeat frames and a final frame containing `data`. Timeouts return `200` with `status: "failed"` and `error.code: "TIMEOUT"`; inspect run status. See [Streaming](/workflows/deployment/api#streaming) for event formats. Input descriptions specify compatible modes; invalid combinations return `400`.\n\nSupply `X-Run-Id` to prevent duplicate execution. Reuse returns `409`, without replaying results. A `503` with `error.details.code: "ASYNC_ENQUEUE_AMBIGUOUS"` omits `Retry-After` because the run may already have started. Reconcile using the returned run ID; do not start another run with a new or omitted ID.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/execute/route').then((route) => route.POST),
   },
   exportWorkflow: {
     contract: v2ExportWorkflowContract,
-    summary: 'Export Workflow',
+    summary: 'Export workflow',
     description:
-      'Export a portable, secret-sanitized workflow. Use includeReferences=true for non-secret source identities and field occurrences used by mapped imports. Use includeWorkspaceBindings=true to retain non-secret workspace bindings for a same-workspace round trip; default exports clear those bindings. Credentials and secrets are cleared either way. Exporting records an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
+      'Export the saved draft as portable workflow data with workspace read access. Registered credential fields and opaque table/tool values are cleared; environment references and ordinary workflow variables remain included. Review other configuration before sharing.\n\nDefault exports clear workspace bindings. Use `includeWorkspaceBindings=true` to retain non-secret bindings for a same-workspace import, or `includeReferences=true` for source identities and field occurrences used by mapped imports. Exporting records an audit event. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/export/route').then((route) => route.GET),
   },
   forkWorkspace: {
     contract: v2ForkWorkspaceContract,
-    summary: 'Fork Workspace',
+    summary: 'Fork workspace',
     description:
-      'Create a child workspace with undeployed workflow drafts. Requires the reviewed preview fingerprint and a stable request ID. Identical retries return the same operation; reuse with different inputs returns 409. Poll Get Workspace Operation until selected resource copies complete. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      "Create a child workspace with undeployed drafts of the source's deployed workflows. Requires source workspace Admin access and permission to create a workspace in its organization. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`.\n\nFirst preview the same name and copy choices, then send the returned fingerprint and a stable request ID. The example fingerprint is illustrative. Identical retries return the same committed operation; changed inputs with that ID return `409`. Poll Get workspace operation until selected resource copies finish. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/route').then((route) => route.POST),
   },
   getAuditLog: {
     contract: v2GetAuditLogContract,
-    summary: 'Get Audit Log',
+    summary: 'Get audit log',
     description:
       'Get one organization audit-log entry. Requires an Enterprise subscription and organization admin or owner access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1239,50 +1239,50 @@ export const V2_MCP_OPERATIONS = {
   },
   getBillingStatus: {
     contract: v2GetBillingStatusContract,
-    summary: 'Get Billing Status',
+    summary: 'Get billing status',
     description:
-      "Get the current plan, billing standing, credit allowance, and storage quota. Pooled `credits` and `storage` are visible only to callers who can manage the payer's billing; workspace API keys receive null for both. Use List Billing Logs for credit history.\n\nOAuth scope: `api:read`.",
+      "Get the current plan, billing standing, credit allowance, and storage quota. Pooled `credits` and `storage` are visible only to callers who can manage the payer's billing; workspace API keys receive null for both. Use List billing logs for credit history.\n\nOAuth scope: `api:read`.",
     handler: () => import('@/app/api/v2/billing/status/route').then((route) => route.GET),
   },
   getBlock: {
     contract: v2GetBlockContract,
-    summary: 'Get Block',
+    summary: 'Get block',
     description:
       "Get a block's fields, conditions, operations, tool schemas, and triggers. Unversioned types resolve to the newest visible version; the returned `id` identifies that version. Hidden or missing blocks return `404`.\n\nOAuth scope: `api:read`.",
     handler: () => import('@/app/api/v2/blocks/[blockId]/route').then((route) => route.GET),
   },
   getCustomTool: {
     contract: v2GetCustomToolContract,
-    summary: 'Get Custom Tool',
+    summary: 'Get custom tool',
     description:
-      'Get one custom tool by identifier, scoped to its workspace.\n\nOAuth scope: `api:read`.',
+      'Get a custom tool’s declaration and code by identifier, scoped to its workspace. Requires workspace read access.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/custom-tools/[customToolId]/route').then((route) => route.GET),
   },
   getFile: {
     contract: v2GetFileContract,
-    summary: 'Get File Metadata',
+    summary: 'Get file metadata',
     description:
-      'Get file metadata, its public-share configuration, and the version number of its current content. The `share` field is null when the file has never been shared. `currentVersion` identifies the content in List File Versions and is the precondition Revert File Version accepts.\n\nOAuth scope: `api:read`.',
+      'Get file metadata, its public-share configuration, and the version number of its current content. The `share` field is null when the file has never been shared. `currentVersion` identifies the content in List file versions and is the precondition Revert file version accepts.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/files/[fileId]/metadata/route').then((route) => route.GET),
   },
   getFileShare: {
     contract: v2GetFileShareContract,
-    summary: 'Get File Share',
+    summary: 'Get file share',
     description:
       "Get a file's public-share configuration. An unshared file returns `data: null`; a disabled share returns its configuration with `isActive: false`.\n\nOAuth scope: `api:read`.",
     handler: () => import('@/app/api/v2/files/[fileId]/share/route').then((route) => route.GET),
   },
   getFileUpload: {
     contract: v2GetFileUploadContract,
-    summary: 'Get File Upload',
+    summary: 'Get file upload',
     description:
       "Get an upload session's state to determine whether an interrupted transfer can resume. Requires the signed upload token and current workspace access.\n\nOAuth scope: `api:read`.",
     handler: () => import('@/app/api/v2/files/uploads/[uploadId]/route').then((route) => route.GET),
   },
   getFileVersion: {
     contract: v2GetFileVersionContract,
-    summary: 'Get File Version',
+    summary: 'Get file version',
     description:
       'Get one version of a file. A version removed by retention, or one that never existed, returns `404`.\n\nOAuth scope: `api:read`.',
     handler: () =>
@@ -1290,7 +1290,7 @@ export const V2_MCP_OPERATIONS = {
   },
   getKnowledgeBase: {
     contract: v2GetKnowledgeBaseContract,
-    summary: 'Get Knowledge Base',
+    summary: 'Get knowledge base',
     description:
       "Get a knowledge base's metadata and document counts. Inaccessible knowledge bases return `404`. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
     handler: () =>
@@ -1298,7 +1298,7 @@ export const V2_MCP_OPERATIONS = {
   },
   getKnowledgeChunk: {
     contract: v2GetKnowledgeChunkContract,
-    summary: 'Get Chunk',
+    summary: 'Get chunk',
     description:
       'Get one chunk of a document, including the exact text that was embedded. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1309,7 +1309,7 @@ export const V2_MCP_OPERATIONS = {
   },
   getKnowledgeConnector: {
     contract: v2GetKnowledgeConnectorContract,
-    summary: 'Get Knowledge Connector',
+    summary: 'Get knowledge connector',
     description:
       'Get one connector and its ten most recent synchronization attempts. Stored API keys are never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1320,7 +1320,7 @@ export const V2_MCP_OPERATIONS = {
   },
   getKnowledgeDocument: {
     contract: v2GetKnowledgeDocumentContract,
-    summary: 'Get Document',
+    summary: 'Get document',
     description:
       'Get document metadata, processing status, and source connector details.\n\nOAuth scope: `api:read`.',
     handler: () =>
@@ -1330,38 +1330,38 @@ export const V2_MCP_OPERATIONS = {
   },
   getLog: {
     contract: v2GetLogContract,
-    summary: 'Get Log',
+    summary: 'Get log',
     description:
-      "Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty `traceSpans` array does not prove none were recorded. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
+      "Get a run's workflow graph, trace spans, final output, and cost. Trace spans expire separately, so an empty `traceSpans` array does not prove none were recorded. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.",
     handler: () => import('@/app/api/v2/logs/[runId]/route').then((route) => route.GET),
   },
   getLogStats: {
     contract: v2GetLogStatsContract,
-    summary: 'Get Log Statistics',
+    summary: 'Get log statistics',
     description:
-      'Get bucketed run counts, success rate, errors, and mean latency for the workspace and individual workflows. Query fields describe window selection and bucketing. Folder filters cover subtrees. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
+      'Get bucketed run counts, success rate, errors, and mean latency for the workspace and individual workflows. Query fields describe window selection and bucketing. Folder filters cover subtrees. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/logs/stats/route').then((route) => route.GET),
   },
   getMcpServer: {
     contract: v2GetMcpServerContract,
-    summary: 'Get MCP Server',
+    summary: 'Get MCP server',
     description:
-      'Get one MCP server by identifier. Request-header values and OAuth client secrets are never returned.\n\nOAuth scope: `api:read`.',
+      'Get a registered external MCP server. Request-header values and OAuth client secrets are omitted. Requires workspace read access.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/mcp-servers/[mcpServerId]/route').then((route) => route.GET),
   },
   getMeta: {
     contract: v2GetMetaContract,
-    summary: 'Get API Capabilities',
+    summary: 'Get API status',
     description:
-      'Get whether v2 is available, what kind of API credential is calling, and when it expires. Requires a valid API key or OAuth access token.\n\nOAuth scope: `api:read`.',
+      'Get the calling credential’s type and expiry. Requires a valid API key or OAuth access token. `v2Enabled` is true whenever this endpoint is served; the response does not enumerate resource permissions.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/meta/route').then((route) => route.GET),
   },
   getNextKnowledgeTagSlot: {
     contract: v2GetNextKnowledgeTagSlotContract,
-    summary: 'Get Next Tag Slot',
+    summary: 'Get next tag slot',
     description:
-      'Get the next available slot and remaining capacity for a field type. This does not reserve a slot. Create Tag selects a free slot when `tagSlot` is omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Get the next available slot and remaining capacity for a field type. This does not reserve a slot. Create tag selects a free slot when `tagSlot` is omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/tags/next-slot/route').then(
@@ -1370,7 +1370,7 @@ export const V2_MCP_OPERATIONS = {
   },
   getOrganization: {
     contract: v2GetOrganizationContract,
-    summary: 'Get Organization',
+    summary: 'Get organization',
     description:
       'Get organization metadata and the acting user’s organization role. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1379,9 +1379,9 @@ export const V2_MCP_OPERATIONS = {
   },
   getOrganizationAccessRequestSettings: {
     contract: v2GetOrganizationAccessRequestSettingsContract,
-    summary: 'Get Organization Access Request Settings',
+    summary: 'Get organization access request settings',
     description:
-      'Get whether the organization allows new access requests and approvals. This preference does not enable features unavailable in the deployment or subscription. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Get whether the organization allows new access requests and approvals. This preference does not enable features unavailable in the deployment or subscription. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/access-requests/settings/route').then(
@@ -1390,9 +1390,9 @@ export const V2_MCP_OPERATIONS = {
   },
   getOrganizationInvitation: {
     contract: v2GetOrganizationInvitationContract,
-    summary: 'Get Organization Invitation',
+    summary: 'Get organization invitation',
     description:
-      'Get an invitation owned by the organization. Requires organization administrator access. Use List Organization Invitation Workspaces to inspect its workspace grants. The response excludes the acceptance token. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Get an invitation owned by the organization. Requires organization Admin access. Use List organization invitation workspaces to inspect its workspace grants. The response excludes the acceptance token. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/invitations/[invitationId]/route').then(
@@ -1401,9 +1401,9 @@ export const V2_MCP_OPERATIONS = {
   },
   getOrganizationMemberUsageLimit: {
     contract: v2GetOrganizationMemberUsageLimitContract,
-    summary: 'Get Organization Member Credit Limit',
+    summary: 'Get organization member credit limit',
     description:
-      'Read a person’s credit cap and credits consumed in the organization billing period. Hosted only. The userId identifies an organization member or external collaborator with workspace access in this organization; it is not a membership record ID. Null means no per-person cap, while organization limits still apply. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Read a person’s credit cap and credits consumed in the organization billing period. Hosted deployments only. The `userId` identifies an organization member or external collaborator with workspace access in this organization; it is not a membership record ID. Null means no per-person cap, while organization limits still apply. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/members/[userId]/usage-limit/route').then(
@@ -1412,9 +1412,9 @@ export const V2_MCP_OPERATIONS = {
   },
   getOrganizationUsageBreakdown: {
     contract: v2GetOrganizationUsageBreakdownContract,
-    summary: 'Get Organization Usage Breakdown',
+    summary: 'Get organization usage breakdown',
     description:
-      'Read ranked organization usage by member, workspace, workflow, model, BYOK provider, or source. Requires organization administrator access and Usage Monitoring. Omitted usage is summarized in other. BYOK ranks tokens; other dimensions rank cost. More than 10,000 underlying groups returns 413; narrow the window or workspace. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Read ranked usage by member, workspace, workflow, model, BYOK provider, or source. Requires organization Admin access and Usage Monitoring. `other` summarizes groups omitted by the limit. BYOK ranks tokens; other dimensions rank cost. More than 10,000 underlying groups returns `413`; narrow the window or workspace. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/usage/breakdown/route').then(
@@ -1423,9 +1423,9 @@ export const V2_MCP_OPERATIONS = {
   },
   getOrganizationUsageSummary: {
     contract: v2GetOrganizationUsageSummaryContract,
-    summary: 'Get Organization Usage Summary',
+    summary: 'Get organization usage summary',
     description:
-      'Read pooled credits, a usage series, and an exact previous-period comparison when available. Requires organization administrator access and Usage Monitoring (Enterprise on hosted; enabled on self-hosted). Defaults to 30 days. Custom dates include both dates in the selected timezone and cannot exceed 92 days. Billing windows exceeding 366 days are rejected. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Read pooled credits, a usage series, and an exact previous-period comparison when available. Requires organization Admin access and Usage Monitoring: Enterprise when billing is enabled, or deployment enablement when billing is disabled. Defaults to 30 days. Custom dates include both dates in the selected timezone and cannot exceed 92 days. Billing windows exceeding 366 days are rejected. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/usage/summary/route').then(
@@ -1434,9 +1434,9 @@ export const V2_MCP_OPERATIONS = {
   },
   getPermissionGroup: {
     contract: v2GetPermissionGroupContract,
-    summary: 'Get Permission Group',
+    summary: 'Get permission group',
     description:
-      'Get a permission group and its resolved settings. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Get a permission group and its resolved settings. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/permission-groups/[groupId]/route').then(
@@ -1445,9 +1445,9 @@ export const V2_MCP_OPERATIONS = {
   },
   getRowEnrichment: {
     contract: v2GetRowEnrichmentContract,
-    summary: 'Get Row Group Run',
+    summary: 'Get row group run',
     description:
-      'Read a workflow or enrichment group’s outcome for one row: `runState` (as exposed by `includeRunState`), output cells keyed by column name, and enrichment providers in cascade order with status, hosted-key cost, duration, and the matching provider. Existing rows always answer: `runState: null` means never run; `cascade: null` means no breakdown recorded. Missing tables, rows, or groups return `404`.\n\nOAuth scope: `api:read`.',
+      'Read one row’s workflow or enrichment-group outcome: run state, output cells keyed by column name, and providers in cascade order with status, hosted-key cost, duration, and the matching provider. `runState: null` means never run; `cascade: null` means no breakdown was recorded. Missing tables, rows, or groups return `404`. Run state above 2 MiB returns `413`.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/rows/[rowId]/enrichment/[groupId]/route').then(
         (route) => route.GET
@@ -1455,29 +1455,29 @@ export const V2_MCP_OPERATIONS = {
   },
   getSandbox: {
     contract: v2GetSandboxContract,
-    summary: 'Get Sandbox',
+    summary: 'Get sandbox',
     description:
-      'Get one sandbox by identifier, scoped to its workspace, including its current build state and any build failure.\n\nOAuth scope: `api:read`.',
+      'Get a sandbox’s dependency configuration, current build state, and any build failure. Requires workspace read access.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/sandboxes/[sandboxId]/route').then((route) => route.GET),
   },
   getSelector: {
     contract: v2GetSelectorContract,
-    summary: 'Get Selector Option',
+    summary: 'Get selector option',
     description:
-      'Resolve a workspace configuration option by its provider identifier and declared dependencies. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Get an authorized configuration choice by provider ID and declared context with workspace read access. Returns `data: null` when the option is absent from complete results. Truncated results or pagination limits that prevent verification return `413`; a list-only lookup checks at most 100 pages or 10,000 options. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/selectors/get/route').then((route) => route.POST),
   },
   getSkill: {
     contract: v2GetSkillContract,
-    summary: 'Get Skill',
+    summary: 'Get skill',
     description:
-      'Get one workspace or built-in skill, including its full content. Built-in skills are marked read-only.\n\nOAuth scope: `api:read`.',
+      'Get a workspace or built-in skill, including its full instructions. Built-in skills are read-only. Requires workspace read access.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/skills/[skillId]/route').then((route) => route.GET),
   },
   getSsoPolicy: {
     contract: v2GetSsoPolicyContract,
-    summary: 'Get SSO Policy',
+    summary: 'Get SSO policy',
     description:
       'Get the stored organization SSO requirement and whether it is currently enforced. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1488,9 +1488,9 @@ export const V2_MCP_OPERATIONS = {
   },
   getSsoProvider: {
     contract: v2GetSsoProviderContract,
-    summary: 'Get SSO Provider',
+    summary: 'Get SSO provider',
     description:
-      'Get an identity provider owned by the organization. Requires organization administrator access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Get an identity provider owned by the organization. Requires organization Admin access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/sso/providers/[providerId]/route').then(
@@ -1499,14 +1499,14 @@ export const V2_MCP_OPERATIONS = {
   },
   getTable: {
     contract: v2GetTableContract,
-    summary: 'Get Table',
+    summary: 'Get table',
     description:
       'Get a table with its metadata, column schema, locks, and current job. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/route').then((route) => route.GET),
   },
   getTableDispatch: {
     contract: v2GetTableDispatchContract,
-    summary: 'Get Run Dispatch',
+    summary: 'Get run dispatch',
     description:
       "Get a dispatch's current state. Poll until `complete` or `canceled`; use row reads with `includeRunState` for per-cell outcomes.\n\nOAuth scope: `api:read`.",
     handler: () =>
@@ -1516,14 +1516,14 @@ export const V2_MCP_OPERATIONS = {
   },
   getTableExport: {
     contract: v2GetTableExportContract,
-    summary: 'Get Table Export',
+    summary: 'Get table export',
     description: "Get a table export's progress and status.\n\nOAuth scope: `api:read`.",
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/exports/[exportId]/route').then((route) => route.GET),
   },
   getTableImport: {
     contract: v2GetTableImportContract,
-    summary: 'Get Table Import',
+    summary: 'Get table import',
     description:
       "Get an import's progress and status. During `uploading`, the signed upload token is required; omitting it returns `404`.\n\nOAuth scope: `api:read`.",
     handler: () =>
@@ -1531,7 +1531,7 @@ export const V2_MCP_OPERATIONS = {
   },
   getTableRow: {
     contract: v2GetTableRowContract,
-    summary: 'Get Row',
+    summary: 'Get row',
     description:
       "Get one row by identifier. Set `includeRunState=true` to attach the row's per-workflow-group run outcomes.\n\nOAuth scope: `api:read`.",
     handler: () =>
@@ -1539,30 +1539,30 @@ export const V2_MCP_OPERATIONS = {
   },
   getTableView: {
     contract: v2GetTableViewContract,
-    summary: 'Get View',
+    summary: 'Get view',
     description: 'Get one saved table view by identifier.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/views/[viewId]/route').then((route) => route.GET),
   },
   getTool: {
     contract: v2GetToolContract,
-    summary: 'Get Tool',
+    summary: 'Get tool',
     description:
-      "Get a built-in tool's parameters and outputs. Registered IDs resolve exactly; other names resolve to the newest family version. The returned `id` identifies the resolved tool. Hidden or missing tools return `404`.\n\nOAuth scope: `api:read`.",
+      'Get a built-in tool’s parameters and outputs. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The returned `id` identifies that tool. Hidden or missing tools return `404`. Requires workspace read access.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/tools/[toolId]/route').then((route) => route.GET),
   },
   getWorkflow: {
     contract: v2GetWorkflowContract,
-    summary: 'Get Workflow',
+    summary: 'Get workflow',
     description:
-      'Get a workflow with its variables and deployed API-trigger inputs. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
+      'Get workflow metadata, variables, and trigger input fields from the saved draft. Requires workspace read access. Input fields may differ from the live deployment. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/workflows/[workflowId]/route').then((route) => route.GET),
   },
   getWorkflowChatDeployment: {
     contract: v2GetWorkflowChatDeploymentContract,
-    summary: 'Get Workflow Chat Deployment',
+    summary: 'Get workflow chat deployment',
     description:
-      "Get a workflow's hosted chat and visitor access settings. Requires workspace admin access; a missing chat returns `404`. Passwords are never returned; `hasPassword` indicates whether one is set. Hosted chat and workflow API deployment are managed separately. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+      "Get a workflow's hosted chat and visitor access settings with workspace Admin access. A missing chat returns `404`. Passwords are never returned; `hasPassword` reports whether one is set. Hosted chat and workflow API deployment are managed separately. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/deployments/chat/route').then(
@@ -1571,42 +1571,42 @@ export const V2_MCP_OPERATIONS = {
   },
   getWorkflowDeployment: {
     contract: v2GetWorkflowDeploymentContract,
-    summary: 'Get Workflow Deployment',
+    summary: 'Get workflow deployment',
     description:
-      'Read live status, deployment time, latest attempt readiness and failure, draft divergence (`needsRedeployment`), anonymous execution access (`isPublicApi`), and registered webhook URLs. This read exposes public API access and webhook URLs; see their field descriptions for security and delivery details.\n\n`/workflows/{workflowId}/deployment` controls overall API executability; `/deployments/chat` controls only the hosted-chat surface. A workflow can remain deployed without a chat.\n\nOAuth scope: `api:read`.',
+      "Read live deployment status, the latest attempt's readiness or failure, and draft divergence (`needsRedeployment`). Requires workspace read access. `isPublicApi` reports anonymous billed execution; `webhooks` lists registered delivery URLs.\n\n`/workflows/{workflowId}/deployment` controls overall API executability; `/deployments/chat` controls only the hosted-chat surface. A workflow can remain deployed without a chat.\n\nOAuth scope: `api:read`.",
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/deployment/route').then((route) => route.GET),
   },
   getWorkflowMcpServer: {
     contract: v2GetWorkflowMcpServerContract,
-    summary: 'Get Workflow MCP Server',
+    summary: 'Get workflow MCP server',
     description:
-      "Get a published workflow MCP server's metadata and client endpoint. Use List Workflow MCP Tools for its tool inventory. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+      'Get a workflow MCP server’s metadata and client endpoint. Use List workflow MCP tools for its inventory. Requires workspace read access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflow-mcp-servers/[serverId]/route').then((route) => route.GET),
   },
   getWorkflowRun: {
     contract: v2GetWorkflowRunContract,
-    summary: 'Get Workflow Run',
+    summary: 'Get workflow run',
     description:
-      'Get current run state with optional final and block outputs. With `includeOutput`, `files` includes download paths; `includeFileBase64` inlines file bytes and returns `413` with the download path when one file or the total exceeds 16 MiB. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success.\n\nOAuth scope: `api:read`.',
+      'Read current run state with workspace read access. Request final output and files with `includeOutput`, or block outputs with `selectedOutputs`. Organization permission groups can hide output, files, or cost.\n\n`includeFileBase64` inlines file bytes. A file or the total above 16 MiB returns `413` naming a download path; download large files individually. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/runs/[runId]/route').then((route) => route.GET),
   },
   getWorkflowState: {
     contract: v2GetWorkflowStateContract,
-    summary: 'Get Workflow State',
+    summary: 'Get workflow state',
     description:
-      'Get the editable draft graph, including blocks, edges, loop and parallel containers, and variables. Use this state with Replace Workflow State to preserve workspace bindings; Export Workflow removes those bindings for portability. This read records no audit event, and `HEAD` mirrors `GET`.\n\nOAuth scope: `api:read`.',
+      'Read the saved editable draft, including blocks, edges, loop and parallel containers, and variables. Requires workspace read access. Configured values are included; use this state with Replace workflow state for same-workspace editing, or Export workflow for portable data with registered credential fields cleared. This read records no audit event; `HEAD` mirrors `GET`.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/state/route').then((route) => route.GET),
   },
   getWorkflowVersion: {
     contract: v2GetWorkflowVersionContract,
-    summary: 'Get Workflow Version',
+    summary: 'Get workflow version',
     description:
-      'Get an immutable deployment version and its pinned workflow graph snapshot.\n\nOAuth scope: `api:read`.',
+      'Get a deployment version and its pinned graph with workspace read access. Registered credential fields and opaque table/tool values are cleared. Environment references and ordinary workflow variables remain included; review other configuration before sharing.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/versions/[version]/route').then(
         (route) => route.GET
@@ -1614,15 +1614,16 @@ export const V2_MCP_OPERATIONS = {
   },
   getWorkspace: {
     contract: v2GetWorkspaceContract,
-    summary: 'Get Workspace',
-    description: 'Get metadata for an accessible workspace.\n\nOAuth scope: `api:read`.',
+    summary: 'Get workspace',
+    description:
+      'Get metadata for a workspace the calling credential can access. Requires workspace read access.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/workspaces/[workspaceId]/route').then((route) => route.GET),
   },
   getWorkspaceForkAvailability: {
     contract: v2GetWorkspaceForkAvailabilityContract,
-    summary: 'Get Workspace Fork Availability',
+    summary: 'Get workspace fork availability',
     description:
-      'Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Check whether workspace forking is enabled for this deployment and workspace plan. Requires workspace Admin access. Returns `available: false` when the feature gate is unmet. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/availability/route').then(
@@ -1631,18 +1632,18 @@ export const V2_MCP_OPERATIONS = {
   },
   getWorkspaceForkLineage: {
     contract: v2GetWorkspaceForkLineageContract,
-    summary: 'Get Workspace Fork Lineage',
+    summary: 'Get workspace fork lineage',
     description:
-      'Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Read this workspace and its direct parent, or `parent: null` when it has no active parent. Requires workspace Admin access. The relationship does not grant access to the parent. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/lineage/route').then((route) => route.GET),
   },
   getWorkspaceForkMappings: {
     contract: v2GetWorkspaceForkMappingsContract,
-    summary: 'Get Workspace Fork Mappings',
+    summary: 'Get workspace fork mappings',
     description:
-      'Read persisted mappings in the requested source-to-target direction. Candidate discovery uses the destination resource and selector listing operations. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Read persisted resource mappings in the requested source-to-target direction along a direct fork edge. Requires Admin access to both workspaces. Discover candidates with destination resource reads and selector operations. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/mappings/route').then(
@@ -1651,9 +1652,9 @@ export const V2_MCP_OPERATIONS = {
   },
   getWorkspaceOperation: {
     contract: v2GetWorkspaceOperationContract,
-    summary: 'Get Workspace Operation',
+    summary: 'Get workspace operation',
     description:
-      'Read a committed operation, copy progress, exact deployment readiness, and structured issues. A failed follow-up does not mean the business transaction was rolled back.\n\nOAuth scope: `api:read`.',
+      'Read a committed operation and refresh its copy progress, exact admitted deployment readiness, and structured issues with workspace read access. `applied: true` means the transaction committed even if follow-up work failed. This read does not require the fork-specific Admin role or feature gate.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/operations/[operationId]/route').then(
         (route) => route.GET
@@ -1661,7 +1662,7 @@ export const V2_MCP_OPERATIONS = {
   },
   getWorkspacePermissionConfig: {
     contract: v2GetWorkspacePermissionConfigContract,
-    summary: 'Get Workspace Permission Config',
+    summary: 'Get workspace permission config',
     description:
       "Get the acting user's governing permission group and configuration for a workspace they can access. This describes permission-group restrictions, not the user's workspace role. Group and config are null when no group governs the caller; entitled indicates whether organization permission governance is active. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
     workspaceKeyUnsupported: true,
@@ -1672,23 +1673,23 @@ export const V2_MCP_OPERATIONS = {
   },
   grantSkillEditor: {
     contract: v2GrantSkillEditorContract,
-    summary: 'Grant Skill Editor',
+    summary: 'Grant skill editor',
     description:
-      'Grant skill editor access to a workspace member by email. Requires an existing editor or workspace admin; admins already have access and cannot receive explicit grants. Existing grants return `200`; new grants return `201`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Grant skill editor access to a current workspace member by email. Requires an existing skill editor or workspace Admin. Workspace Admins already have derived access and cannot receive explicit grants. Existing grants return `200`; new grants return `201`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/skills/[skillId]/editors/route').then((route) => route.POST),
   },
   importWorkflow: {
     contract: v2ImportWorkflowContract,
-    summary: 'Import Workflow',
+    summary: 'Import workflow',
     description:
-      'Create an undeployed workflow from a portable export object, bare state, or JSON string. Mapping options require a preview fingerprint and stable request ID; unresolved required configuration creates nothing. Mapped imports return source-to-imported block IDs and an operation receipt. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
+      'Create an undeployed workflow from a portable export object, bare draft state, or JSON string. Requires workspace write access. The empty-state example creates a draft that needs runnable blocks before execution.\n\nMapped imports require a preview with the same choices, its `previewFingerprint`, and a stable `requestId`. Unresolved required configuration creates nothing. Identical retries return the committed result; reusing the ID with changed inputs returns `409`. The result includes regenerated graph IDs and an operation receipt. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/workflows/import/route').then((route) => route.POST),
   },
   listAuditLogs: {
     contract: v2ListAuditLogsContract,
-    summary: 'List Audit Logs',
+    summary: 'List audit logs',
     description:
       'List an organization audit trail with filters and opaque cursor pagination. Requires an Enterprise subscription and organization admin or owner access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1696,95 +1697,95 @@ export const V2_MCP_OPERATIONS = {
   },
   listBillingLogs: {
     contract: v2ListBillingLogsContract,
-    summary: 'List Billing Logs',
+    summary: 'List billing logs',
     description:
       'List credit usage with source filtering and cursor pagination. The default `period` is `30d`; pagination covers only the selected time window. An inverted custom window returns `400`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/billing/logs/route').then((route) => route.GET),
   },
   listBlocks: {
     contract: v2ListBlocksContract,
-    summary: 'List Blocks',
+    summary: 'List blocks',
     description:
-      'List built-in and workspace-deployed blocks visible to the caller. Integration allowlists and preview visibility restrict results. Use `capability=trigger` for workflow starters and Get Block or Get Tool to resolve operation and tool IDs.\n\nOAuth scope: `api:read`.',
+      'List built-in and workspace-deployed blocks visible to the caller. Integration allowlists and preview visibility restrict results. Use `capability=trigger` for workflow starters and Get block or Get tool to resolve operation and tool IDs.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/blocks/route').then((route) => route.GET),
   },
   listChatDeployments: {
     contract: v2ListChatDeploymentsContract,
-    summary: 'List Chat Deployments',
+    summary: 'List chat deployments',
     description:
-      "List hosted chats and their public URLs with cursor pagination. Filter by `workflowId` for one workflow's chat. The list requires workspace read access; Get Workflow Chat Deployment requires admin access and includes visitor access settings and customizations. Passwords are never returned.\n\nOAuth scope: `api:read`.",
+      "List hosted chats and their URLs with workspace read access and cursor pagination. Filter by `workflowId` for one workflow's chat. The admin-only detail read also includes visitor access settings and customizations. Passwords are never returned; organization permission groups can restrict chat deployment access.\n\nOAuth scope: `api:read`.",
     handler: () => import('@/app/api/v2/chat-deployments/route').then((route) => route.GET),
   },
   listConnectorTypes: {
     contract: v2ListConnectorTypesContract,
-    summary: 'List Connector Types',
+    summary: 'List connector types',
     description:
-      'List knowledge-base connector types with opaque cursors, defaulting to 25 summaries per page: identifier, name, description, and auth mode. `detail=full` adds accepted source configuration fields. Fields with `multi: true` accept `string[]` instead of `string`. A `canonicalParamId` pairs a picker with manual entry for the same configuration key: send exactly one value, keyed by `canonicalParamId` rather than the field’s `id`.\n\nOAuth scope: `api:read`.',
+      'List connector types from the deployment’s knowledge-base connector registry. Requires workspace read access and Knowledge Base access; workspace integration allowlists and revealed preview blocks do not filter this catalog. Results default to 25 summaries per page. `detail=full` adds configuration fields. Fields with `multi: true` accept `string[]`. For picker/manual-entry pairs, send one value under `canonicalParamId`, not the field’s `id`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/connector-types/route').then((route) => route.GET),
   },
   listCredentialMembers: {
     contract: v2ListCredentialMembersContract,
-    summary: 'List Credential Members',
+    summary: 'List credential members',
     description:
-      'List explicit credential grants, including revoked grants, and inherited workspace administrator access. Requires workspace read access and the integrations.manage capability. Personal API keys and OAuth tokens can access OAuth or service-account credentials; sessions can also access workspace environment credentials. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List explicit credential grants, including revoked grants, and inherited workspace Admin access. Personal API keys and OAuth access tokens can list grants for OAuth or service-account credentials. Requires workspace read access and the `integrations.manage` capability. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/credentials/[credentialId]/members/route').then((route) => route.GET),
   },
   listCredentialProviders: {
     contract: v2ListCredentialProvidersContract,
-    summary: 'List Credential Providers',
+    summary: 'List credential providers',
     description:
-      'List OAuth and service-account connection methods and their availability. OAuth options provide provider IDs for browser connections; service-account methods declare required fields and write-only secrets. Supports provider-name search. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.',
+      'List OAuth and service-account connection methods and their availability. OAuth options provide provider IDs for browser connections; service-account methods declare required fields and write-only secrets. Supports provider-name search. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/credentials/providers/route').then((route) => route.GET),
   },
   listCredentials: {
     contract: v2ListCredentialsContract,
-    summary: 'List Credentials',
+    summary: 'List credentials',
     description:
-      'List OAuth and service-account connections visible to the caller. Secret material is never returned.\n\nOAuth scope: `api:read`.',
+      'List OAuth and service-account connections visible to the caller. Requires workspace read access. Stored tokens, keys, and service-account payloads are omitted.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/credentials/route').then((route) => route.GET),
   },
   listCustomTools: {
     contract: v2ListCustomToolsContract,
-    summary: 'List Custom Tools',
+    summary: 'List custom tools',
     description:
-      'List code-backed custom tools in a workspace with cursor pagination.\n\nOAuth scope: `api:read`.',
+      'List code-backed custom tools in the workspace with cursor pagination. Each entry includes its declaration and implementation. Requires workspace read access.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/custom-tools/route').then((route) => route.GET),
   },
   listFileFolders: {
     contract: v2ListFileFoldersContract,
-    summary: 'List Folders',
+    summary: 'List folders',
     description:
-      'List workspace file folders with parent-path filtering and sorting. Use `scope=archived` to find paths accepted by Restore Folder. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.',
+      'List workspace file folders with parent-path filtering and sorting. Use `scope=archived` to find paths accepted by Restore folder. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/files/folders/route').then((route) => route.GET),
   },
   listFiles: {
     contract: v2ListFilesContract,
-    summary: 'List Files',
+    summary: 'List files',
     description:
       'List active workspace files with folder filtering, search, sorting, and cursor pagination. Use `scope=archived` to find files available for restoration. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/files/route').then((route) => route.GET),
   },
   listFileVersions: {
     contract: v2ListFileVersionsContract,
-    summary: 'List File Versions',
+    summary: 'List file versions',
     description:
       'List the versions of a file, newest first by default. Each write that changes the bytes records one; identical rewrites do not. Collaborative edits, and repeated workflow writes by one author, fold into a version under ten minutes old and written in the last five. Renames and moves are not versions. Retention removes older versions by age and plan but keeps the newest ten, so numbers can have gaps.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/files/[fileId]/versions/route').then((route) => route.GET),
   },
   listKnowledgeBases: {
     contract: v2ListKnowledgeBasesContract,
-    summary: 'List Knowledge Bases',
+    summary: 'List knowledge bases',
     description:
       'List active knowledge bases in a workspace with folder filtering, search, sorting, and cursor pagination. Use `scope=archived` to find knowledge bases available for restoration. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/knowledge/route').then((route) => route.GET),
   },
   listKnowledgeChunks: {
     contract: v2ListKnowledgeChunksContract,
-    summary: 'List Chunks',
+    summary: 'List chunks',
     description:
-      'List document chunks with content search, enabled filtering, sorting, and cursor pagination. Tags use slots; use List Tags to resolve display names. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List document chunks with content search, enabled filtering, sorting, and cursor pagination. Tags use slots; use List tags to resolve display names. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/documents/[documentId]/chunks/route').then(
@@ -1793,7 +1794,7 @@ export const V2_MCP_OPERATIONS = {
   },
   listKnowledgeConnectorDocuments: {
     contract: v2ListKnowledgeConnectorDocumentsContract,
-    summary: 'List Knowledge Connector Documents',
+    summary: 'List knowledge connector documents',
     description:
       'List documents produced by one connector with opaque cursor pagination. Excluded documents are omitted unless explicitly requested. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1804,7 +1805,7 @@ export const V2_MCP_OPERATIONS = {
   },
   listKnowledgeConnectors: {
     contract: v2ListKnowledgeConnectorsContract,
-    summary: 'List Knowledge Connectors',
+    summary: 'List knowledge connectors',
     description:
       'List external sources connected to a knowledge base with cursor pagination. Stored API keys are never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1815,32 +1816,32 @@ export const V2_MCP_OPERATIONS = {
   },
   listKnowledgeDocuments: {
     contract: v2ListKnowledgeDocumentsContract,
-    summary: 'List Documents',
+    summary: 'List documents',
     description:
-      'List documents with filename search, state and tag filters, sorting, and cursor pagination. Tag values use display names; use List Tags to resolve the slots required for writes.\n\nOAuth scope: `api:read`.',
+      'List documents with filename search, state and tag filters, sorting, and cursor pagination. Tag values use display names; use List tags to resolve the slots required for writes.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/documents/route').then((route) => route.GET),
   },
   listKnowledgeFolders: {
     contract: v2ListKnowledgeFoldersContract,
-    summary: 'List Folders',
+    summary: 'List folders',
     description:
-      'List folders in the knowledge-base folder tree with filtering and sorting. Returns the complete set in one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
+      'List folders in the knowledge-base folder tree with filtering and sorting. Returns one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/knowledge/folders/route').then((route) => route.GET),
   },
   listKnowledgeTags: {
     contract: v2ListKnowledgeTagsContract,
-    summary: 'List Tags',
+    summary: 'List tags',
     description:
-      "List the knowledge base's tag definitions with display names, write slots, and field types. Filters and document reads use display names; document writes use slots. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
+      "List the knowledge base's tag definitions with display names, write slots, and field types. Filters and document reads use display names; document writes use slots. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.",
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/tags/route').then((route) => route.GET),
   },
   listKnowledgeTagUsage: {
     contract: v2ListKnowledgeTagUsageContract,
-    summary: 'List Tag Usage',
+    summary: 'List tag usage',
     description:
-      'Count the documents and chunks with a value for each defined tag. Returns the complete set in one page; `nextCursor` is always null. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Count the documents and chunks with a value for each defined tag. Returns one page; `nextCursor` is always null. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/tags/usage/route').then(
@@ -1849,32 +1850,32 @@ export const V2_MCP_OPERATIONS = {
   },
   listLogs: {
     contract: v2ListLogsContract,
-    summary: 'List Logs',
+    summary: 'List logs',
     description:
-      'List logs with filters, selectable detail, sorting, and cursor pagination. `includeJobRuns=true` includes chat and Sim-agent jobs only with `sortBy=startedAt`, because other orderings are unsupported. `files` contains only run-produced files; use the files API for input attachments. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
+      'List logs with filters, selectable detail, sorting, and cursor pagination. `includeJobRuns=true` includes chat and Sim-agent jobs only with `sortBy=startedAt`, because other orderings are unsupported. `files` contains only run-produced files; use the files API for input attachments. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/logs/route').then((route) => route.GET),
   },
   listMcpServers: {
     contract: v2ListMcpServersContract,
-    summary: 'List MCP Servers',
+    summary: 'List MCP servers',
     description:
-      'List MCP servers registered in a workspace, excluding request-header values and OAuth secrets. Connection metadata remains at registration defaults until List MCP Server Tools performs discovery.\n\nOAuth scope: `api:read`.',
+      'List external MCP servers registered in the workspace. Request-header values and OAuth secrets are omitted. Connection metadata remains at registration defaults until List MCP server tools performs discovery. Requires workspace read access.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/mcp-servers/route').then((route) => route.GET),
   },
   listMcpServerTools: {
     contract: v2ListMcpServerToolsContract,
-    summary: 'List MCP Server Tools',
+    summary: 'List MCP server tools',
     description:
-      'Discover up to 1,000 tools within 5 MB, connect to the server, and update connection metadata. Results are unpaginated. Invalid OAuth returns `409` with `MCP_SERVER_REAUTHORIZATION_REQUIRED`; reauthorize through the browser. Unavailable servers return `503`. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Discover tools on an enabled external MCP server and update connection metadata. Discovery is bounded by 1,000 tools, 5 MiB, 50 upstream pages, and 60 seconds; limits or later-page failures can return an unmarked partial inventory. Results are unpaginated and may be cached; `refresh=true` requests fresh discovery. Invalid OAuth returns `409` with `MCP_SERVER_REAUTHORIZATION_REQUIRED`; reauthorize in the browser. Disabled servers and servers requiring a managed Credential Group connection return `409`; unavailable servers return `503`. Requires workspace read access. `HEAD` checks access with the same authorization as `GET` but skips side effects, returning an empty `200` without payload headers on success. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/mcp-servers/[mcpServerId]/tools/route').then((route) => route.GET),
   },
   listMyOrganizationAccessRequests: {
     contract: v2ListMyOrganizationAccessRequestsContract,
-    summary: 'List My Organization Access Requests',
+    summary: 'List my organization access requests',
     description:
-      'List the acting user’s organization-level requests and member credit-limit requests, including resolved history. For workspace-scoped requests, use List My Workspace Access Requests. History remains available while requests are disabled. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List the acting user’s organization-level requests and member credit-limit requests, including resolved history. For workspace-scoped requests, use List my workspace access requests. History remains available while requests are disabled. Requires organization membership. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/access-requests/mine/route').then(
@@ -1883,7 +1884,7 @@ export const V2_MCP_OPERATIONS = {
   },
   listMyWorkspaceAccessRequests: {
     contract: v2ListMyWorkspaceAccessRequestsContract,
-    summary: 'List My Workspace Access Requests',
+    summary: 'List my workspace access requests',
     description:
       'List only the acting user’s requests in this workspace, including resolved history and organization-wide member credit-limit requests. History remains available while requests are disabled. Requires access to the workspace; external collaborators use their workspace grant. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1894,9 +1895,9 @@ export const V2_MCP_OPERATIONS = {
   },
   listOrganizationAccessRequests: {
     contract: v2ListOrganizationAccessRequestsContract,
-    summary: 'List Organization Access Requests',
+    summary: 'List organization access requests',
     description:
-      'List requests across the organization for administrator review. Includes requests from organization members and external workspace collaborators; history remains available while requests are disabled. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List requests across the organization for administrator review. Includes requests from organization members and external workspace collaborators; history remains available while requests are disabled. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/access-requests/route').then(
@@ -1905,7 +1906,7 @@ export const V2_MCP_OPERATIONS = {
   },
   listOrganizationDomains: {
     contract: v2ListOrganizationDomainsContract,
-    summary: 'List Organization Domains',
+    summary: 'List organization domains',
     description:
       'List the organization’s domain claims with cursor pagination. Requires organization membership. Pending DNS challenge values are returned only to administrators using their own credentials. Organizations without Enterprise domain entitlement return an empty list. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1916,9 +1917,9 @@ export const V2_MCP_OPERATIONS = {
   },
   listOrganizationInvitations: {
     contract: v2ListOrganizationInvitationsContract,
-    summary: 'List Organization Invitations',
+    summary: 'List organization invitations',
     description:
-      'List invitations owned by the organization, including invitations with workspace grants. Requires organization administrator access. Expired invitations are reported without modifying them. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List invitations owned by the organization, including invitations with workspace grants. Requires organization Admin access. Expired invitations are reported without modifying them. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/invitations/route').then(
@@ -1927,9 +1928,9 @@ export const V2_MCP_OPERATIONS = {
   },
   listOrganizationInvitationWorkspaces: {
     contract: v2ListOrganizationInvitationWorkspacesContract,
-    summary: 'List Organization Invitation Workspaces',
+    summary: 'List organization invitation workspaces',
     description:
-      "List workspace grants attached to an invitation of any status. Includes archived workspaces still owned by the organization; workspaces moved to another organization are omitted. Requires organization administrator access. These grants describe the invitation, not the invitee's current access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+      "List workspace grants attached to an invitation of any status. Includes archived workspaces still owned by the organization; workspaces moved to another organization are omitted. Requires organization Admin access. These grants describe the invitation, not the invitee's current access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
     workspaceKeyUnsupported: true,
     handler: () =>
       import(
@@ -1938,7 +1939,7 @@ export const V2_MCP_OPERATIONS = {
   },
   listOrganizationMembers: {
     contract: v2ListOrganizationMembersContract,
-    summary: 'List Organization Members',
+    summary: 'List organization members',
     description:
       'List organization members by name or email. Ordinary members must have access to the member directory; organization administrators retain access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1949,7 +1950,7 @@ export const V2_MCP_OPERATIONS = {
   },
   listOrganizations: {
     contract: v2ListOrganizationsContract,
-    summary: 'List Organizations',
+    summary: 'List organizations',
     description:
       'List organizations the acting user belongs to. Organizations that disallow the calling credential are omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
@@ -1957,9 +1958,9 @@ export const V2_MCP_OPERATIONS = {
   },
   listOrganizationUsageEvents: {
     contract: v2ListOrganizationUsageEventsContract,
-    summary: 'List Organization Usage Events',
+    summary: 'List organization usage events',
     description:
-      'Page through usage events, including zero-cost reporting. Requires organization administrator access and Usage Monitoring. Defaults to 30 days. Cursors retain the initial reporting window; keep filters and sort unchanged while paging. The sim-chat source covers both chat surfaces. Per-event rounding can produce credits=0 with hasCost=true. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List usage events, including zero-cost activity. Requires organization Admin access and Usage Monitoring. Defaults to 30 days. Cursors retain the initial reporting window; keep filters and sort unchanged while paging. `sim-chat` covers both chat surfaces. Per-event rounding can yield `credits: 0` with `hasCost: true`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/usage/events/route').then(
@@ -1968,9 +1969,9 @@ export const V2_MCP_OPERATIONS = {
   },
   listOrganizationWorkspaces: {
     contract: v2ListOrganizationWorkspacesContract,
-    summary: 'List Organization Workspaces',
+    summary: 'List organization workspaces',
     description:
-      'List active workspaces owned by the organization. Requires organization administrator access; does not require Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List active workspaces owned by the organization. Requires organization Admin access; does not require Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/workspaces/route').then(
@@ -1979,9 +1980,9 @@ export const V2_MCP_OPERATIONS = {
   },
   listPermissionGroupMembers: {
     contract: v2ListPermissionGroupMembersContract,
-    summary: 'List Permission Group Members',
+    summary: 'List permission group members',
     description:
-      'List explicit membership assignments in a permission group with cursor pagination. An empty inherit group applies to everyone in its workspaces. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List explicit membership assignments in a permission group with cursor pagination. An empty inherit group applies to everyone in its workspaces. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import(
@@ -1990,9 +1991,9 @@ export const V2_MCP_OPERATIONS = {
   },
   listPermissionGroups: {
     contract: v2ListPermissionGroupsContract,
-    summary: 'List Permission Groups',
+    summary: 'List permission groups',
     description:
-      'List permission groups in an organization with cursor pagination. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List permission groups in an organization with cursor pagination. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/permission-groups/route').then(
@@ -2001,46 +2002,46 @@ export const V2_MCP_OPERATIONS = {
   },
   listSandboxes: {
     contract: v2ListSandboxesContract,
-    summary: 'List Sandboxes',
+    summary: 'List sandboxes',
     description:
-      'List reusable dependency environments for Function blocks, including language packages, managed CLIs, and system packages. Sandboxes remain visible after a plan downgrade.\n\nOAuth scope: `api:read`.',
+      'List reusable dependency environments for Function blocks, including language packages, managed CLIs, and system packages. Requires workspace read access. Existing sandboxes remain visible after a plan downgrade.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/sandboxes/route').then((route) => route.GET),
   },
   listSecrets: {
     contract: v2ListSecretsContract,
-    summary: 'List Secrets',
+    summary: 'List secrets',
     description:
-      'List workspace and caller-owned personal secrets with cursor pagination. Only workspace secrets marked `unredacted` include values; all other entries contain metadata only. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List workspace secrets visible to the caller and caller-owned personal secrets. Only workspace secrets marked `unredacted` can include values; every other entry contains metadata only. Requires workspace read access. Personal secrets belong to the caller across workspaces. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/secrets/route').then((route) => route.GET),
   },
   listSelector: {
     contract: v2ListSelectorContract,
-    summary: 'List Selector Options',
+    summary: 'List selector options',
     description:
-      'List workspace-scoped configuration choices using the selector key and dependencies from an import or sync preview. Missing OAuth connections require human authorization before provider choices can be discovered. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List authorized workspace configuration choices using the selector key and context from an import or sync preview. Requires workspace read access. Missing OAuth connections require human authorization. Keep workspace, selector, context, and search unchanged while paging; a changed provider page returns `409` and requires restarting without a cursor. Provider pages above 8 MiB return `413`; narrow the search. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/selectors/list/route').then((route) => route.POST),
   },
   listSkillEditors: {
     contract: v2ListSkillEditorsContract,
-    summary: 'List Skill Editors',
+    summary: 'List skill editors',
     description:
-      'List skill editors and workspace administrators with cursor pagination.\n\nOAuth scope: `api:read`.',
+      'List explicit skill editors and workspace Admins with cursor pagination. Built-in skills return an empty list. Requires workspace read access.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/skills/[skillId]/editors/route').then((route) => route.GET),
   },
   listSkills: {
     contract: v2ListSkillsContract,
-    summary: 'List Skills',
+    summary: 'List skills',
     description:
-      'List workspace and built-in skills with cursor pagination. Built-in skills are read-only. The list omits skill bodies; use Get Skill to read content.\n\nOAuth scope: `api:read`.',
+      'List workspace and built-in skills with cursor pagination. Built-in skills are read-only. Skill bodies are omitted; use Get skill to read content. Requires workspace read access.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/skills/route').then((route) => route.GET),
   },
   listSsoProviders: {
     contract: v2ListSsoProvidersContract,
-    summary: 'List SSO Providers',
+    summary: 'List SSO providers',
     description:
-      'List identity providers owned by the organization. Requires organization administrator access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List identity providers owned by the organization. Requires organization Admin access. OIDC client secrets are redacted and SAML private keys are omitted. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/sso/providers/route').then(
@@ -2049,7 +2050,7 @@ export const V2_MCP_OPERATIONS = {
   },
   listTableDispatches: {
     contract: v2ListTableDispatchesContract,
-    summary: 'List Run Dispatches',
+    summary: 'List run dispatches',
     description:
       'List the run dispatches on one table, most recent first — settled dispatches (`complete`, `canceled`) alongside the ones still in flight, so a run that finished between two polls is still visible next to the `dispatchId` its create returned. Capped at the 100 most recent, so this list is unpaginated and `nextCursor` is always null.\n\nOAuth scope: `api:read`.',
     handler: () =>
@@ -2057,98 +2058,98 @@ export const V2_MCP_OPERATIONS = {
   },
   listTableFolders: {
     contract: v2ListTableFoldersContract,
-    summary: 'List Folders',
+    summary: 'List folders',
     description:
-      'List table folders, optionally limiting results to direct children of a parent path. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.',
+      'List table folders, optionally limiting results to direct children of a parent path. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/tables/folders/route').then((route) => route.GET),
   },
   listTableRows: {
     contract: v2ListTableRowsContract,
-    summary: 'List Rows',
+    summary: 'List rows',
     description:
-      'List rows in default order with cursor pagination. Pages default to a 5 MB limit and may contain fewer rows than requested; continue until `nextCursor` is null. Use Query Rows for filtering and sorting. `includeRunState=true` adds per-group run outcomes and reduces the row limit.\n\nOAuth scope: `api:read`.',
+      'List rows in default order with cursor pagination. Pages default to a 5 MiB limit and may contain fewer rows than requested; continue until `nextCursor` is null. Use Query rows for filtering and sorting. `includeRunState=true` adds per-group run outcomes and reduces the row limit.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/rows/route').then((route) => route.GET),
   },
   listTables: {
     contract: v2ListTablesContract,
-    summary: 'List Tables',
+    summary: 'List tables',
     description:
       'List active tables with folder filtering, search, sorting, and cursor pagination. Use `scope=archived` to find tables available for restoration. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/tables/route').then((route) => route.GET),
   },
   listTableViews: {
     contract: v2ListTableViewsContract,
-    summary: 'List Views',
+    summary: 'List views',
     description:
-      'List saved table views, omitting references to removed columns. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.',
+      'List saved table views, omitting references to removed columns. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/views/route').then((route) => route.GET),
   },
   listTools: {
     contract: v2ListToolsContract,
-    summary: 'List Tools',
+    summary: 'List tools',
     description:
-      "List built-in tools exposed by blocks visible to the caller. Use List MCP Server Tools for an external server's tools and List Custom Tools for workspace code-backed tools.\n\nOAuth scope: `api:read`.",
+      "List built-in tools exposed by blocks visible to the caller. Use List MCP server tools for an external server's tools and List custom tools for workspace code-backed tools.\n\nOAuth scope: `api:read`.",
     handler: () => import('@/app/api/v2/tools/route').then((route) => route.GET),
   },
   listWorkflowFolders: {
     contract: v2ListWorkflowFoldersContract,
-    summary: 'List Workflow Folders',
+    summary: 'List workflow folders',
     description:
-      'List workflow folders in a workspace. Returns the complete set in one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
+      'List workflow folders with workspace read access, optional parent/name filters, and sorting. Returns one page; `nextCursor` is always null. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/workflows/folders/route').then((route) => route.GET),
   },
   listWorkflowGroups: {
     contract: v2ListWorkflowGroupsContract,
-    summary: 'List Workflow Groups',
+    summary: 'List workflow groups',
     description:
-      'List the workflow and enrichment groups that can be dispatched for a table. Returns the complete set in one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.',
+      'List the workflow and enrichment groups that can be dispatched for a table. Returns one page; `nextCursor` is always null.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/groups/route').then((route) => route.GET),
   },
   listWorkflowMcpServers: {
     contract: v2ListWorkflowMcpServersContract,
-    summary: 'List Workflow MCP Servers',
+    summary: 'List workflow MCP servers',
     description:
-      "List MCP servers that expose deployed workflows to external clients. Use List MCP Servers for external servers Sim calls. Tool names share a 2,000-name page limit; inspect `toolNamesTruncated` and use List Workflow MCP Tools for a server's inventory. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
+      'List MCP servers that expose deployed workflows to external clients. Use List MCP servers for external servers Sim calls. Requires workspace read access. Tool names share a 2,000-name page limit; when `toolNamesTruncated` is true, `toolCount` and `toolNames` may be incomplete. Use List workflow MCP tools for a server’s bounded inventory. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/workflow-mcp-servers/route').then((route) => route.GET),
   },
   listWorkflowMcpTools: {
     contract: v2ListWorkflowMcpToolsContract,
-    summary: 'List Workflow MCP Tools',
+    summary: 'List workflow MCP tools',
     description:
-      'List published tools ordered by name, including the `workflowId` used to delete each registration. Undeploying a workflow makes its registrations `inactive`; redeploying reactivates them. Results are capped at 2,000 tools: `nextCursor` is always null, and `truncated` marks an incomplete inventory that cannot be paginated. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List tool registrations ordered by name, including the `workflowId` used to remove each registration. Undeploying a workflow makes its registrations `inactive`; redeploying reactivates them. Results are capped at 2,000 tools: `nextCursor` is always null, and `truncated` marks an incomplete inventory that cannot be paginated. Requires workspace read access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflow-mcp-servers/[serverId]/tools/route').then((route) => route.GET),
   },
   listWorkflowRuns: {
     contract: v2ListWorkflowRunsContract,
-    summary: 'List Workflow Runs',
+    summary: 'List workflow runs',
     description:
-      'List recorded runs of a workflow with filtering and opaque cursor pagination. Expired runs are permanently deleted. Retention is 30 days from run start on Free, unlimited on Pro and Team, and configured per organization on Enterprise with workspace overrides.\n\nOAuth scope: `api:read`.',
+      'List recorded workflow runs with workspace read access, filters, and cursor pagination. Cost can be hidden by organization permission groups. Expired runs are permanently deleted by retention cleanup. Sim Cloud Free defaults to 30 days from run start; paid plans and billing-disabled deployments have no default expiry. Organization policies and workspace overrides can set an effective window. Billing-disabled cleanup requires enabled data retention. Runs referenced by active pauses are protected from cleanup.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/runs/route').then((route) => route.GET),
   },
   listWorkflows: {
     contract: v2ListWorkflowsContract,
-    summary: 'List Workflows',
+    summary: 'List workflows',
     description:
-      'List active workflows in a workspace. Use `scope=archived` to find workflows available for restoration. Supports folder and deployment filters, search, sorting, and cursor pagination. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
+      'List active workflows in a workspace with workspace read access. Use `scope=archived` to find workflows available for restoration. Filter by folder, deployment, or name; sort and page with the returned cursor. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/workflows/route').then((route) => route.GET),
   },
   listWorkflowVersions: {
     contract: v2ListWorkflowVersionsContract,
-    summary: 'List Workflow Versions',
+    summary: 'List workflow versions',
     description:
-      'List immutable deployment versions of a workflow, newest first.\n\nOAuth scope: `api:read`.',
+      'List saved deployment versions, newest first, with workspace read access. Each version pins an immutable graph; its name and release note can be updated.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/versions/route').then((route) => route.GET),
   },
   listWorkspaceForkChildren: {
     contract: v2ListWorkspaceForkChildrenContract,
-    summary: 'List Workspace Fork Children',
+    summary: 'List workspace fork children',
     description:
-      'Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      "List this workspace's active direct children, newest first, with cursor pagination. Requires workspace Admin access. A fork relationship does not grant access to a child workspace. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.",
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/children/route').then(
@@ -2157,9 +2158,9 @@ export const V2_MCP_OPERATIONS = {
   },
   listWorkspaceForkResources: {
     contract: v2ListWorkspaceForkResourcesContract,
-    summary: 'List Workspace Fork Resources',
+    summary: 'List workspace fork resources',
     description:
-      'Inspect workspace fork information and copyable resources. Lineage does not grant access to the other workspace; fork creation requires source admin and sync requires admin on both sides. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'List copyable resources of one kind in this workspace with cursor pagination. Requires workspace Admin access. Fork creation uses file IDs; sync copy choices use file storage keys from source references or file resource reads. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/resources/route').then(
@@ -2168,53 +2169,53 @@ export const V2_MCP_OPERATIONS = {
   },
   listWorkspaceMembers: {
     contract: v2ListWorkspaceMembersContract,
-    summary: 'List Workspace Members',
+    summary: 'List workspace members',
     description:
-      'List workspace members by email, including explicit grants and inherited organization admin access. Each member includes a stable user ID for member administration.\n\nOAuth scope: `api:read`.',
+      'List effective workspace members, ordered by email, including explicit grants and inherited organization Admin access. Use each member’s `userId` for member administration. Requires workspace read access.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/members/route').then((route) => route.GET),
   },
   listWorkspaceOperations: {
     contract: v2ListWorkspaceOperationsContract,
-    summary: 'List Workspace Operations',
+    summary: 'List workspace operations',
     description:
-      'Page committed operations newest first. Filter by the original request ID to reconcile an uncertain mutation response.\n\nOAuth scope: `api:read`.',
+      'List stored operation receipts newest first with workspace read access. Filter by the original `requestId` to reconcile an uncertain mutation response. Read an individual operation to refresh its copy and deployment readiness. This list does not require the fork-specific Admin role or feature gate.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/operations/route').then((route) => route.GET),
   },
   listWorkspaces: {
     contract: v2ListWorkspacesContract,
-    summary: 'List Workspaces',
+    summary: 'List workspaces',
     description:
-      'List active workspaces available to the calling credential with opaque cursor pagination. A personal API key or OAuth token sees accessible workspaces that permit user-held API credentials; a workspace API key sees only its bound workspace.\n\nOAuth scope: `api:read`.',
+      'List active workspaces available to the calling credential. Personal API keys and OAuth tokens see accessible workspaces that permit user-held API credentials; a workspace API key sees only its bound workspace. Results use cursor pagination.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/workspaces/route').then((route) => route.GET),
   },
   moveFileItems: {
     contract: v2MoveFileItemsContract,
-    summary: 'Move Files',
+    summary: 'Move files',
     description:
       'Move up to 1,000 files to a folder path or the workspace root.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/move/route').then((route) => route.POST),
   },
   moveTables: {
     contract: v2MoveTablesContract,
-    summary: 'Move Tables and Folders',
+    summary: 'Move tables and folders',
     description:
       'Move up to 100 tables and folders to one destination. Items succeed or fail independently: covered tables are `skipped`, missing items are `notFound`, and lock or cycle failures include reasons in `failed`. An invalid destination rejects the request before any move.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/move/route').then((route) => route.POST),
   },
   moveWorkflows: {
     contract: v2MoveWorkflowsContract,
-    summary: 'Move Workflows',
+    summary: 'Move workflows',
     description:
-      'Move up to 100 workflows into one folder. Moves succeed or fail independently; missing, archived, or locked workflows appear in `failed`. Duplicate IDs are ignored. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
+      'Move up to 100 workflows to one folder with workspace write access. Each move succeeds or fails independently; missing, archived, or locked workflows appear in `failed`. Duplicate IDs are ignored. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/workflows/move/route').then((route) => route.POST),
   },
   previewOrganizationAccessRequest: {
     contract: v2PreviewOrganizationAccessRequestContract,
-    summary: 'Preview Organization Access Request',
+    summary: 'Preview organization access request',
     description:
-      'Preview the current permission changes, affected group and audience, or member credit cap. Review canApply, changes, impact, and fingerprint before resolving. Permission changes affect the entire governing group, not only the requester. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
+      'Preview the current permission changes, affected group and audience, or member credit cap. Review `canApply`, `changes`, `impact`, and `fingerprint` before resolving. Permission changes affect the entire governing group, not only the requester. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:read`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import(
@@ -2223,17 +2224,17 @@ export const V2_MCP_OPERATIONS = {
   },
   previewWorkflowImport: {
     contract: v2PreviewWorkflowImportContract,
-    summary: 'Preview Workflow Import',
+    summary: 'Preview workflow import',
     description:
-      'Validate destination mappings and dependent choices without creating a workflow. Returns unresolved fields, discovery instructions, and a fingerprint required by mapped import. No source workspace is queried from imported provenance.\n\nOAuth scope: `api:write`.',
+      'Validate destination mappings and configuration with workspace write access, without creating a workflow. The result reports readiness, unresolved fields, discovery instructions, and a fingerprint for mapped import with the same choices. Imported provenance never authorizes or queries a source workspace.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/workflows/import/preview/route').then((route) => route.POST),
   },
   previewWorkspaceFork: {
     contract: v2PreviewWorkspaceForkContract,
-    summary: 'Preview Workspace Fork',
+    summary: 'Preview workspace fork',
     description:
-      'Preview the deployed workflows and explicitly selected resources that a new workspace fork would copy. The result is read-only and supplies the fingerprint required by Fork Workspace. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Preview deployed workflows and explicitly selected resources for a new child workspace. Requires source workspace Admin access and permission to create a workspace in its organization. The read-only result supplies the fingerprint for Fork workspace with the same choices. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/preview/route').then(
@@ -2242,9 +2243,9 @@ export const V2_MCP_OPERATIONS = {
   },
   previewWorkspacePull: {
     contract: v2PreviewWorkspacePullContract,
-    summary: 'Preview Workspace Pull',
+    summary: 'Preview workspace pull',
     description:
-      'Preview deployed source workflows replacing mapped targets along a direct fork edge. Push sends the current workspace to the other; pull brings the other into the current workspace. Proposed mappings are not saved. Dependent choices use source workflow, block, and field identities. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Preview changes from the other workspace into this workspace along a direct fork edge. Requires Admin access to both workspaces. The plan lists workflows to create, replace, or archive; replacements overwrite target drafts with the source deployment. Proposed mappings are not saved. Dependent choices use source workflow, block, and field IDs. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/pull/preview/route').then(
@@ -2253,9 +2254,9 @@ export const V2_MCP_OPERATIONS = {
   },
   previewWorkspacePush: {
     contract: v2PreviewWorkspacePushContract,
-    summary: 'Preview Workspace Push',
+    summary: 'Preview workspace push',
     description:
-      'Preview deployed source workflows replacing mapped targets along a direct fork edge. Push sends the current workspace to the other; pull brings the other into the current workspace. Proposed mappings are not saved. Dependent choices use source workflow, block, and field identities. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Preview changes from this workspace into the other workspace along a direct fork edge. Requires Admin access to both workspaces. The plan lists workflows to create, replace, or archive; replacements overwrite target drafts with the source deployment. Proposed mappings are not saved. Dependent choices use source workflow, block, and field IDs. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/push/preview/route').then(
@@ -2264,32 +2265,32 @@ export const V2_MCP_OPERATIONS = {
   },
   pullWorkspace: {
     contract: v2PullWorkspaceContract,
-    summary: 'Pull Workspace',
+    summary: 'Pull workspace',
     description:
-      'Apply a reviewed push or pull with inline mappings in one transaction. Requires confirmation, the preview fingerprint, and a stable request ID. Unresolved or changed plans return 409 without applying. The receipt distinguishes committed changes from copy and deployment readiness; poll Get Workspace Operation before treating the target as ready. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Apply a reviewed sync from the other workspace into this workspace along a direct fork edge. Requires Admin access to both workspaces. Creates unmatched deployed workflows, overwrites mapped target drafts, and archives mapped targets whose sources were deleted or archived. Undeployed sources alone do not archive targets. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`.\n\nSend `confirm: true`, the fingerprint from a preview with identical choices, and a stable request ID. The example hash is illustrative. Changed or unresolved plans return `409` without applying. Identical retries return the committed operation; changed inputs with that ID return `409`. Copies and deployment activation can finish after the transaction commits. Poll Get workspace operation before treating the target as ready. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/pull/route').then((route) => route.POST),
   },
   pushWorkspace: {
     contract: v2PushWorkspaceContract,
-    summary: 'Push Workspace',
+    summary: 'Push workspace',
     description:
-      'Apply a reviewed push or pull with inline mappings in one transaction. Requires confirmation, the preview fingerprint, and a stable request ID. Unresolved or changed plans return 409 without applying. The receipt distinguishes committed changes from copy and deployment readiness; poll Get Workspace Operation before treating the target as ready. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Apply a reviewed sync from this workspace into the other workspace along a direct fork edge. Requires Admin access to both workspaces. Creates unmatched deployed workflows, overwrites mapped target drafts, and archives mapped targets whose sources were deleted or archived. Undeployed sources alone do not archive targets. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`.\n\nSend `confirm: true`, the fingerprint from a preview with identical choices, and a stable request ID. The example hash is illustrative. Changed or unresolved plans return `409` without applying. Identical retries return the committed operation; changed inputs with that ID return `409`. Copies and deployment activation can finish after the transaction commits. Poll Get workspace operation before treating the target as ready. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/push/route').then((route) => route.POST),
   },
   queryRows: {
     contract: v2QueryRowsContract,
-    summary: 'Query Rows',
+    summary: 'Query rows',
     description:
-      'Query rows with typed predicates, sorting, and cursor pagination. Omit the predicate to match all rows. Pages default to a 5 MB limit; continue until `nextCursor` is null. Oversized predicates return `413`. `includeRunState` adds per-group outcomes and reduces the row limit. Counts are read separately and can differ from paged results if rows change.\n\nOAuth scope: `api:read`.',
+      'Query rows with typed predicates, sorting, and cursor pagination. Omit the predicate to match all rows. Pages default to a 5 MiB limit; continue until `nextCursor` is null. Oversized predicates return `413`. `includeRunState` adds per-group outcomes and reduces the row limit. Counts are read separately and can differ from paged results if rows change.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/query/route').then((route) => route.POST),
   },
   queryRowsCount: {
     contract: v2QueryRowsCountContract,
-    summary: 'Count Rows',
+    summary: 'Count rows',
     description:
       'Count rows matching a typed predicate, or omit the predicate to count all rows. The count is read separately from row pages and can change between requests. Oversized predicates return `413`.\n\nOAuth scope: `api:read`.',
     handler: () =>
@@ -2297,16 +2298,16 @@ export const V2_MCP_OPERATIONS = {
   },
   readFileText: {
     contract: v2ReadFileTextContract,
-    summary: 'Read File Text',
+    summary: 'Read file text',
     description:
-      'Extract text without changing the file. Accepts its ID or canonical path (`files/<folder>/<name>` or `uploads/<name>` for an unlisted chat upload); the response echoes the read path. Use Unzip File to unpack archives or Download File for original bytes. Unsupported types return `400`, compiling documents return `409`, and oversized files return `413`. `degraded: true` indicates incomplete or synthesized text, such as the legacy `.pptx` fallback; `truncated: true` indicates a parser limit.\n\nOAuth scope: `api:read`.',
+      'Extract text without changing the file. Accepts its ID or canonical path (`files/<folder>/<name>` or `uploads/<name>` for an unlisted chat upload); the response echoes the read path. Use Unzip file to unpack archives or Download file for original bytes. Unsupported types return `400`, compiling documents return `409`, and oversized files return `413`. `degraded: true` indicates incomplete or synthesized text, such as the legacy `.pptx` fallback; `truncated: true` indicates a parser limit.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/files/[fileId]/text/route').then((route) => route.GET),
   },
   readFileVersionText: {
     contract: v2ReadFileVersionTextContract,
-    summary: 'Read File Version Text',
+    summary: 'Read file version text',
     description:
-      'Extract the text of one version, exactly as Read File Text extracts the current content. Unsupported types return `400`, compiling documents return `409`, and oversized versions return `413`.\n\nOAuth scope: `api:read`.',
+      'Extract the text of one version, exactly as Read file text extracts the current content. Unsupported types return `400`, compiling documents return `409`, and oversized versions return `413`.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/files/[fileId]/versions/[version]/text/route').then(
         (route) => route.GET
@@ -2314,37 +2315,37 @@ export const V2_MCP_OPERATIONS = {
   },
   relocateFileFolder: {
     contract: v2RelocateFileFolderContract,
-    summary: 'Rename or Move Folder',
+    summary: 'Rename or move folder',
     description:
       'Rename or move a folder and atomically update all descendant paths.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/folders/route').then((route) => route.PATCH),
   },
   relocateKnowledgeFolder: {
     contract: v2RelocateKnowledgeFolderContract,
-    summary: 'Rename or Move Folder',
+    summary: 'Rename or move folder',
     description:
       'Rename or move a folder and atomically rewrite descendant paths. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/knowledge/folders/route').then((route) => route.PATCH),
   },
   relocateTableFolder: {
     contract: v2RelocateTableFolderContract,
-    summary: 'Rename or Move Folder',
+    summary: 'Rename or move folder',
     description:
       'Rename or move a table folder and update all descendant paths.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/folders/route').then((route) => route.PATCH),
   },
   relocateWorkflowFolder: {
     contract: v2RelocateWorkflowFolderContract,
-    summary: 'Rename or Move Workflow Folder',
+    summary: 'Rename or move workflow folder',
     description:
-      'Rename or move a workflow folder and update all descendant paths. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
+      'Rename or move a workflow folder and update descendant paths with workspace write access. An existing destination receives the folder as a child; otherwise the destination is its new full path. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/workflows/folders/route').then((route) => route.PATCH),
   },
   removeCredentialMember: {
     contract: v2RemoveCredentialMemberContract,
-    summary: 'Remove Credential Member',
+    summary: 'Remove credential member',
     description:
-      'Revoke an active explicit credential grant. Requires credential administrator access and the integrations.manage capability. Inherited workspace administrators cannot be removed; an absent or already-revoked grant returns 404. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Revoke an active explicit credential grant. Requires credential Admin access and the `integrations.manage` capability. Inherited workspace Admins cannot be removed; an absent or already-revoked grant returns `404`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/credentials/[credentialId]/members/[userId]/route').then(
@@ -2353,9 +2354,9 @@ export const V2_MCP_OPERATIONS = {
   },
   removeOrganizationDomain: {
     contract: v2RemoveOrganizationDomainContract,
-    summary: 'Remove Organization Domain',
+    summary: 'Remove organization domain',
     description:
-      'Remove a domain claim and revoke verified sign-in authority from matching organization providers. Requires organization administrator access and Enterprise domain entitlement. Existing accounts and memberships remain. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Remove a domain claim and revoke verified sign-in authority from matching organization providers. Requires organization Admin access and, when billing is enabled, Enterprise domain entitlement. Existing accounts and memberships remain. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/domains/[domainId]/route').then(
@@ -2364,7 +2365,7 @@ export const V2_MCP_OPERATIONS = {
   },
   removeOrganizationMember: {
     contract: v2RemoveOrganizationMemberContract,
-    summary: 'Remove Organization Member',
+    summary: 'Remove organization member',
     description:
       'Remove a member and revoke their access to organization workspaces. Administrators may remove members; members may remove themselves. The organization owner cannot be removed. Owned organization resources are reassigned and the departing member’s sessions end. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -2375,9 +2376,9 @@ export const V2_MCP_OPERATIONS = {
   },
   removePermissionGroupMember: {
     contract: v2RemovePermissionGroupMemberContract,
-    summary: 'Remove Permission Group Member',
+    summary: 'Remove permission group member',
     description:
-      'Remove a member by user identifier. Removing the last member from an inherit group makes it govern everyone in its workspaces; a conflicting all-member group prevents the removal. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Remove a member by user identifier. Removing the last member from an inherit group makes it govern everyone in its workspaces; a conflicting all-member group prevents the removal. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import(
@@ -2386,16 +2387,16 @@ export const V2_MCP_OPERATIONS = {
   },
   renameFile: {
     contract: v2RenameFileContract,
-    summary: 'Rename File',
+    summary: 'Rename file',
     description:
       'Rename a workspace file without changing its containing folder.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/[fileId]/route').then((route) => route.PATCH),
   },
   replaceWorkflowChatDeployment: {
     contract: v2ReplaceWorkflowChatDeploymentContract,
-    summary: 'Create or Replace Workflow Chat Deployment',
+    summary: 'Create or replace workflow chat deployment',
     description:
-      "Create or replace a workflow's hosted chat and deploy its draft. Omitted fields reset to defaults except per-field customizations. Password authentication requires `password`; email or SSO requires non-empty `allowedEmails`. Public authentication allows anyone with the chat URL to use it. A duplicate identifier or pending deployment returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+      "Create or replace a workflow's hosted chat and deploy its saved draft. Requires workspace Admin access. Omitted fields use defaults; customization exceptions are described on their fields.\n\nPassword authentication requires `password`; email or SSO requires non-empty `allowedEmails`. Public authentication lets anyone with the chat URL run it. A duplicate identifier or pending deployment returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/deployments/chat/route').then(
@@ -2404,18 +2405,18 @@ export const V2_MCP_OPERATIONS = {
   },
   replaceWorkflowState: {
     contract: v2ReplaceWorkflowStateContract,
-    summary: 'Replace Workflow State',
+    summary: 'Replace workflow state',
     description:
-      'Atomically replace the draft graph; row-locked concurrent writes are last-write-wins. Block, edge, or subflow IDs owned by another workflow return `409`. Deployments remain immutable snapshots; schedules and webhook registrations are unchanged. Deploy to publish edits. Lint is advisory. Use `dryRun=true` to validate without writing. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Replace the draft graph in one write. Requires workspace write access. Concurrent row-locked writes are last-write-wins; IDs owned by another workflow return `409`. Deployments, schedules, and webhook registrations are unchanged. Deploy to serve the edits.\n\nLint is advisory. Use `dryRun=true` to validate without saving, auditing, or notifying collaborators. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/state/route').then((route) => route.PUT),
   },
   resendOrganizationInvitation: {
     contract: v2ResendOrganizationInvitationContract,
-    summary: 'Resend Organization Invitation',
+    summary: 'Resend organization invitation',
     description:
-      'Email an unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization administrator access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Email an unexpired pending invitation again, renew its expiry, and replace its previous acceptance link. Requires organization Admin access and current invitation eligibility. Retrying sends another email; inspect the invitation after a delivery failure before retrying. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import(
@@ -2424,9 +2425,9 @@ export const V2_MCP_OPERATIONS = {
   },
   resolveOrganizationAccessRequest: {
     contract: v2ResolveOrganizationAccessRequestContract,
-    summary: 'Resolve Organization Access Request',
+    summary: 'Resolve organization access request',
     description:
-      'Apply a reviewed request or decline it with a reason. Applying requires the preview fingerprint; changed policy or membership returns a conflict. Credit requests also require a higher newLimitCredits. Already resolved requests are returned unchanged. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Apply a reviewed request or decline it with a reason. Applying requires the preview fingerprint; changed policy or membership returns a conflict. Credit requests also require a higher `newLimitCredits`. Already resolved requests are returned unchanged. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import(
@@ -2435,21 +2436,21 @@ export const V2_MCP_OPERATIONS = {
   },
   restoreFile: {
     contract: v2RestoreFileContract,
-    summary: 'Restore File',
+    summary: 'Restore file',
     description:
       'Restore a soft-deleted file to its original folder, or the workspace root if that folder was archived. Name collisions add a `_restored` suffix; read `folderPath` and `name` from the response. Already-active files return unchanged, making retries safe. An archived workspace returns `400`; an unresolved name collision returns `409`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/[fileId]/restore/route').then((route) => route.POST),
   },
   restoreFileFolder: {
     contract: v2RestoreFileFolderContract,
-    summary: 'Restore Folder',
+    summary: 'Restore folder',
     description:
-      'Restore a folder and the files and subfolders archived with it. Use the path from List Folders with `scope=archived`. A path that is not archived returns `404`.\n\nOAuth scope: `api:write`.',
+      'Restore a folder and the files and subfolders archived with it. Use the path from List folders with `scope=archived`. A path that is not archived returns `404`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/folders/restore/route').then((route) => route.POST),
   },
   restoreKnowledgeBase: {
     contract: v2RestoreKnowledgeBaseContract,
-    summary: 'Restore Knowledge Base',
+    summary: 'Restore knowledge base',
     description:
       'Restore a knowledge base and the documents and connectors archived with it. Active knowledge bases return unchanged without a new audit event. An archived workspace returns `409`; an archived containing folder moves the restored knowledge base to the workspace root. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -2457,32 +2458,32 @@ export const V2_MCP_OPERATIONS = {
   },
   restoreTable: {
     contract: v2RestoreTableContract,
-    summary: 'Restore Table',
+    summary: 'Restore table',
     description:
-      'Restore a table and its archived rows, views, and workflow groups. Active tables return unchanged without a new audit event. Name conflicts may change the returned `name`. Find archived tables with List Tables and `scope=archived`.\n\nOAuth scope: `api:write`.',
+      'Restore a table and its archived rows, views, and workflow groups. Active tables return unchanged without a new audit event. Name conflicts may change the returned `name`. Find archived tables with List tables and `scope=archived`.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/restore/route').then((route) => route.POST),
   },
   restoreTableFolder: {
     contract: v2RestoreTableFolderContract,
-    summary: 'Restore Folder',
+    summary: 'Restore folder',
     description:
-      'Restore an archived table folder, its descendants, and tables using its former path. An archived parent moves it to the root; name conflicts may change the returned `path`. Non-archived paths return `404`. Save the path from Delete Folder, because List Folders does not include archived table folders.\n\nOAuth scope: `api:write`.',
+      'Restore an archived table folder, its descendants, and tables using its former path. An archived parent moves it to the root; name conflicts may change the returned `path`. Non-archived paths return `404`. Save the path from Delete folder, because List folders does not include archived table folders.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/folders/restore/route').then((route) => route.POST),
   },
   restoreWorkflow: {
     contract: v2RestoreWorkflowContract,
-    summary: 'Restore Workflow',
+    summary: 'Restore workflow',
     description:
-      'Restore an archived workflow and the schedules, webhooks, MCP tools, and chats archived with it. An active workflow returns `409`. If its folder is archived, the workflow returns to the workspace root. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
+      'Restore an archived workflow and its archived schedules, webhooks, MCP tools, and hosted chat. Requires workspace write access. An active workflow returns `409`. If its folder is archived, the workflow returns to the workspace root. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/restore/route').then((route) => route.POST),
   },
   resumeWorkflow: {
     contract: v2ResumeWorkflowContract,
-    summary: 'Resume Workflow Run',
+    summary: 'Resume workflow run',
     description:
-      'Resume one human-in-the-loop pause. The resumed attempt receives a new run ID and returns either a synchronous result or a queue receipt.\n\nOAuth scope: `api:write`.',
+      'Resume one human-in-the-loop pause with workspace write access. The resumed attempt receives a new run ID and returns a synchronous result or queue receipt. A run that originally streamed resumes asynchronously through v2; this endpoint returns no SSE stream.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/runs/[runId]/resume/route').then(
         (route) => route.POST
@@ -2490,9 +2491,9 @@ export const V2_MCP_OPERATIONS = {
   },
   revertFileVersion: {
     contract: v2RevertFileVersionContract,
-    summary: 'Revert File Version',
+    summary: 'Revert file version',
     description:
-      'Make the content of a version current again by writing it as a new `revert` version, so the revert can itself be reverted. Open editors receive the change. Reverting to the current version writes nothing and returns `reverted: false`. A concurrent write, or an `expectedCurrentVersion` that is no longer current, returns `409`; a version above 100 MB returns `413`.\n\nOAuth scope: `api:write`.',
+      'Make the content of a version current again by writing it as a new `revert` version, so the revert can itself be reverted. Open editors receive the change. Reverting to the current version writes nothing and returns `reverted: false`. A concurrent write, or an `expectedCurrentVersion` that is no longer current, returns `409`; a version above 100 MiB returns `413`.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/files/[fileId]/versions/[version]/revert/route').then(
         (route) => route.POST
@@ -2500,9 +2501,9 @@ export const V2_MCP_OPERATIONS = {
   },
   revertWorkflowVersion: {
     contract: v2RevertWorkflowVersionContract,
-    summary: 'Revert Workflow To Version',
+    summary: 'Revert workflow to version',
     description:
-      'Replace the editable draft with a deployment version, discarding current draft edits. Use `active` for the live version. The live deployment remains unchanged; Activate Workflow Version or Rollback Workflow changes it. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Overwrite the editable draft with a deployment version, discarding current draft edits. Requires workspace Admin access. Use `active` for the live version. The live deployment is unchanged; use Activate workflow version or Rollback workflow to change it. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/versions/[version]/revert/route').then(
@@ -2511,9 +2512,9 @@ export const V2_MCP_OPERATIONS = {
   },
   revokeOrganizationInvitation: {
     contract: v2RevokeOrganizationInvitationContract,
-    summary: 'Revoke Organization Invitation',
+    summary: 'Revoke organization invitation',
     description:
-      'Cancel an unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization administrator access. This does not remove a person who already accepted; use Remove Organization Member for that. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Cancel an unexpired pending invitation and all its workspace grants so it can no longer be accepted. Requires organization Admin access. This does not remove a person who already accepted; use Remove organization member for that. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/invitations/[invitationId]/route').then(
@@ -2522,27 +2523,27 @@ export const V2_MCP_OPERATIONS = {
   },
   revokeSkillEditor: {
     contract: v2RevokeSkillEditorContract,
-    summary: 'Revoke Skill Editor',
+    summary: 'Revoke skill editor',
     description:
-      'Revoke an explicit editor grant by email. The caller must already be a skill editor or workspace administrator. Workspace administrators have derived access that cannot be revoked. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Revoke an explicit skill editor grant by email. Requires an existing skill editor or workspace Admin. Workspace Admins have derived access that cannot be revoked. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/skills/[skillId]/editors/route').then((route) => route.DELETE),
   },
   rollbackWorkflow: {
     contract: v2RollbackWorkflowContract,
-    summary: 'Rollback Workflow',
+    summary: 'Rollback workflow',
     description:
-      'Asynchronously activate a previous deployment version, defaulting to the preceding active version. Requires a deployed workflow and leaves the draft unchanged. Use Activate Workflow Version to select a version when the workflow is undeployed. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Activate a previous deployment version asynchronously, defaulting to the preceding active version. Requires workspace Admin access and a deployed workflow. The draft is unchanged. Poll the accepted `latestDeploymentAttempt`. To select a version while undeployed, use Activate workflow version. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/rollback/route').then((route) => route.POST),
   },
   rollbackWorkspaceFork: {
     contract: v2RollbackWorkspaceForkContract,
-    summary: 'Rollback Workspace Fork',
+    summary: 'Rollback workspace fork',
     description:
-      'Restore the latest sync into this workspace using its prior deployed versions. Requires target admin. It does not restore arbitrary drafts or remove every copied resource. Pending activations are reported. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Restore the latest sync into this workspace from the named other workspace using prior deployed versions. Requires target workspace Admin access. A newer sync from another fork edge returns `409`. Arbitrary draft edits and copied resources are not restored or removed. Inspect `pendingActivations`; retry rollback if activation remains unfinished. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/rollback/route').then(
@@ -2551,9 +2552,9 @@ export const V2_MCP_OPERATIONS = {
   },
   runRowEnrichment: {
     contract: v2RunRowEnrichmentContract,
-    summary: 'Run Enrichment For One Row',
+    summary: 'Run enrichment for one row',
     description:
-      'Start one workflow or enrichment group for a table row. Poll Get Run Dispatch using the returned `dispatchId`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`.\n\nOAuth scope: `api:write`.',
+      'Start one workflow or enrichment group for a table row. Poll Get run dispatch using the returned `dispatchId`. A null `dispatchId` means no dispatch is available to poll; check row outcomes with `includeRunState`.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/rows/[rowId]/enrichment/[groupId]/route').then(
         (route) => route.POST
@@ -2561,9 +2562,9 @@ export const V2_MCP_OPERATIONS = {
   },
   saveSsoProvider: {
     contract: v2SaveSsoProviderContract,
-    summary: 'Save SSO Provider',
+    summary: 'Save SSO provider',
     description:
-      'Create or update an organization identity provider’s configuration on a verified domain. Requires organization administrator access and SSO entitlement. Existing providers return 200; creation returns 201. Omission behavior is field-specific; OIDC’s redacted secret marker preserves the saved secret. Identity changes with linked accounts conflict. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Create or update an organization identity provider’s configuration on a verified domain. Requires organization Admin access and SSO entitlement. Existing providers return 200; creation returns 201. Omission behavior is field-specific; OIDC’s redacted secret marker preserves the saved secret. Identity changes with linked accounts conflict. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/sso/providers/route').then(
@@ -2572,31 +2573,31 @@ export const V2_MCP_OPERATIONS = {
   },
   searchFileContent: {
     contract: v2SearchFileContentContract,
-    summary: 'Search File Content',
+    summary: 'Search file content',
     description:
       'Search indexed text in active workspace files and return matching lines with file IDs and line numbers. `folderPaths` limits both results and reported coverage. Missing matches are inconclusive if `complete` is false or `indexStatus.skippedFiles` or `indexStatus.partialFiles` is nonzero. `truncated` means additional matches exist beyond `maxResults`.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/files/search/route').then((route) => route.GET),
   },
   searchKnowledge: {
     contract: v2SearchKnowledgeContract,
-    summary: 'Search Knowledge',
+    summary: 'Search knowledge',
     description:
       'Search one or more knowledge bases with semantic vector retrieval, optional hybrid full-text retrieval, and structured tag filters. Every result names the `knowledgeBaseId` it came from. A request body over 2 MiB is a `413`. Reranking returns `409` when the stored results cannot pass secret-provenance enforcement.\n\nOAuth scope: `api:read`.',
     handler: () => import('@/app/api/v2/knowledge/search/route').then((route) => route.POST),
   },
   searchTableRows: {
     contract: v2SearchTableRowsContract,
-    summary: 'Search Rows',
+    summary: 'Search rows',
     description:
-      'Search cell text for a case-insensitive substring within an optional filtered and sorted view. Returns cell coordinates, not row data; `ordinal` matches the view used by Query Rows. Results are unpaginated and capped at 1000. If `truncated` is true, narrow the search or predicate.\n\nOAuth scope: `api:read`.',
+      'Search cell text for a case-insensitive substring within an optional filtered and sorted view. Returns cell coordinates, not row data; `ordinal` matches the view used by Query rows. Results are unpaginated and capped at 1000. If `truncated` is true, narrow the search or predicate.\n\nOAuth scope: `api:read`.',
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/rows/search/route').then((route) => route.POST),
   },
   setPrimarySsoProvider: {
     contract: v2SetPrimarySsoProviderContract,
-    summary: 'Set Primary SSO Provider',
+    summary: 'Set primary SSO provider',
     description:
-      'Make a verified organization provider handle sign-in for its domain. Requires organization administrator access. Other providers remain available for testing and later switching. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Make a verified organization provider handle sign-in for its domain. Requires organization Admin access. Other providers remain available for testing and later switching. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import(
@@ -2605,15 +2606,15 @@ export const V2_MCP_OPERATIONS = {
   },
   setSecret: {
     contract: v2SetSecretContract,
-    summary: 'Set Secret',
+    summary: 'Set secret',
     description:
-      'Create or replace a workspace or personal secret without returning its value. For existing workspace secrets, omit `value` to update metadata only; this returns `404` if absent. Personal secrets always require `value`. List Secrets can reveal workspace values marked `unredacted`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Create or replace a workspace or caller-owned personal secret. New workspace secrets require workspace write access; existing ones require workspace Admin or secret Admin access. Omit `value` to update an existing workspace secret’s metadata; a missing secret returns `404`. Personal secrets always require `value`. This operation returns metadata only; List secrets can reveal permitted workspace values marked `unredacted`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/secrets/[name]/route').then((route) => route.PUT),
   },
   syncKnowledgeConnector: {
     contract: v2SyncKnowledgeConnectorContract,
-    summary: 'Sync Knowledge Connector',
+    summary: 'Sync knowledge connector',
     description:
       'Queue a connector synchronization. Rehydration forces existing documents to be fetched and indexed again. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -2624,7 +2625,7 @@ export const V2_MCP_OPERATIONS = {
   },
   tableExportDownload: {
     contract: v2TableExportDownloadContract,
-    summary: 'Download Table Export',
+    summary: 'Download table export',
     description:
       'Get a short-lived signed download URL for a completed export. Other states return `409`; an unavailable export file returns `404`.\n\nOAuth scope: `api:read`.',
     handler: () =>
@@ -2634,18 +2635,18 @@ export const V2_MCP_OPERATIONS = {
   },
   undeployWorkflow: {
     contract: v2UndeployWorkflowContract,
-    summary: 'Undeploy Workflow',
+    summary: 'Undeploy workflow',
     description:
-      'Deactivate the currently serving workflow version. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Deactivate the live workflow version and stop its scheduled and webhook triggers. Requires workspace Admin access and a deployed workflow. Deployed MCP tools become inactive; `archivedMcpTools` identifies them. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/deploy/route').then((route) => route.DELETE),
   },
   undeployWorkflowMcpTool: {
     contract: v2UndeployWorkflowMcpToolContract,
-    summary: 'Unpublish Workflow MCP Tool',
+    summary: 'Undeploy workflow MCP tool',
     description:
-      "Unpublish an MCP tool by its workflow ID. The workflow's API deployment remains active. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+      'Remove an MCP tool registration by its workflow ID. The workflow’s API deployment remains active. Requires workspace Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflow-mcp-servers/[serverId]/tools/[workflowId]/route').then(
@@ -2654,47 +2655,47 @@ export const V2_MCP_OPERATIONS = {
   },
   unlinkWorkspaceFork: {
     contract: v2UnlinkWorkspaceForkContract,
-    summary: 'Unlink Workspace Fork',
+    summary: 'Unlink workspace fork',
     description:
-      'Remove the direct fork relationship and its mappings. Requires admin on the acting workspace. Existing workflow and resource content remains available. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Remove the direct fork relationship and its mappings with Admin access to the acting workspace. Existing workflows and resources remain available. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/unlink/route').then((route) => route.POST),
   },
   unzipFile: {
     contract: v2UnzipFileContract,
-    summary: 'Unzip File',
+    summary: 'Unzip file',
     description:
-      'Extract a ZIP archive into a new sibling folder and return counts and the destination path. Use List Files to inspect its contents. Large archives can take minutes; concurrent extraction of the same archive returns `409`. Size or processing-time limits return `413`.\n\nOAuth scope: `api:write`.',
+      'Extract a ZIP archive into a new sibling folder and return counts and the destination path. Use List files to inspect its contents. Large archives can take minutes; concurrent extraction of the same archive returns `409`. Size or processing-time limits return `413`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/[fileId]/unzip/route').then((route) => route.POST),
   },
   updateCredential: {
     contract: v2UpdateCredentialContract,
-    summary: 'Update Credential',
+    summary: 'Update credential',
     description:
-      'Rename a service-account credential or rotate its secret fields, preserving omitted values and the credential ID. Requires credential admin access. Provider rejection preserves the old secret and returns `400` with `providerErrorCode`; outages return `503`. Fields for a different credential type return `400`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Rename an OAuth or service-account credential, change its description, or rotate a service-account secret. Omitted metadata remains unchanged. Rotation requires the provider’s required secret fields to be resubmitted; it replaces the verified secret while retaining the credential ID. Requires credential Admin access. Provider rejection keeps the old secret and returns `400` with `providerErrorCode`; outages return `503`. Secret fields sent for an OAuth credential return `400`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/credentials/[credentialId]/route').then((route) => route.PATCH),
   },
   updateCustomTool: {
     contract: v2UpdateCustomToolContract,
-    summary: 'Update Custom Tool',
+    summary: 'Update custom tool',
     description:
-      'Update a custom tool. Omitted fields remain unchanged; titles must remain unique within the workspace.\n\nOAuth scope: `api:write`.',
+      'Update a custom tool. Omitted fields remain unchanged; supplied schemas and code replace the stored versions. Titles must remain unique within the workspace. Requires workspace write access.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/custom-tools/[customToolId]/route').then((route) => route.PATCH),
   },
   updateFileContent: {
     contract: v2UpdateFileContentContract,
-    summary: 'Replace File Content',
+    summary: 'Replace file content',
     description:
       'Replace the complete contents of an existing file from UTF-8 or base64 input. A stale `expectedRevision`, or a write that raced this one, returns `409`; re-read before retrying.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/files/[fileId]/content/route').then((route) => route.PUT),
   },
   updateKnowledgeBase: {
     contract: v2UpdateKnowledgeBaseContract,
-    summary: 'Update Knowledge Base',
+    summary: 'Update knowledge base',
     description:
       "Update a knowledge base's name, description, chunking configuration, or folder placement. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
     handler: () =>
@@ -2702,7 +2703,7 @@ export const V2_MCP_OPERATIONS = {
   },
   updateKnowledgeChunk: {
     contract: v2UpdateKnowledgeChunkContract,
-    summary: 'Update Chunk',
+    summary: 'Update chunk',
     description:
       'Correct chunk text or disable it from search. Changing `content` re-embeds immediately and recalculates document token and character counts; disabling retains the index. Connector-synced chunks are read-only and return `403` with `error.details.code: "CONNECTOR_MANAGED_RESOURCE_READ_ONLY"`; change the source and re-sync, or exclude the document. Documents that have not finished processing return `409` with their current status. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -2713,7 +2714,7 @@ export const V2_MCP_OPERATIONS = {
   },
   updateKnowledgeConnector: {
     contract: v2UpdateKnowledgeConnectorContract,
-    summary: 'Update Knowledge Connector',
+    summary: 'Update knowledge connector',
     description:
       'Update connector source configuration, schedule, or active state. Replacing source configuration on a runnable connector queues an immediate synchronization; paused connectors retain the change without synchronizing until resumed. Source configuration cannot be replaced while synchronization is already in progress. Authentication material cannot be changed through this operation. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -2724,7 +2725,7 @@ export const V2_MCP_OPERATIONS = {
   },
   updateKnowledgeConnectorDocuments: {
     contract: v2UpdateKnowledgeConnectorDocumentsContract,
-    summary: 'Update Knowledge Connector Documents',
+    summary: 'Update knowledge connector documents',
     description:
       'Exclude connector documents from knowledge search or restore previously excluded documents. Only documents produced by the selected connector can change. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
@@ -2735,9 +2736,9 @@ export const V2_MCP_OPERATIONS = {
   },
   updateKnowledgeDocument: {
     contract: v2UpdateKnowledgeDocumentContract,
-    summary: 'Update Document',
+    summary: 'Update document',
     description:
-      'Rename a document, change search availability, update tag slots, or requeue processing. Omitted fields remain unchanged; indexing state is read-only. Use List Tags to resolve names to slots and Get Document for source connector details, which this response omits. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Rename a document, change search availability, update tag slots, or requeue processing. Omitted fields remain unchanged; indexing state is read-only. Use List tags to resolve names to slots and Get document for source connector details, which this response omits. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/knowledge/[knowledgeBaseId]/documents/[documentId]/route').then(
@@ -2746,7 +2747,7 @@ export const V2_MCP_OPERATIONS = {
   },
   updateKnowledgeTag: {
     contract: v2UpdateKnowledgeTagContract,
-    summary: 'Update Tag',
+    summary: 'Update tag',
     description:
       "Rename a tag or change its slot-compatible `fieldType`. Renaming changes read and filter names without moving the slot or its values. Slots are fixed for a tag's lifetime; an incompatible type returns `400` and requires creating a new tag. A duplicate display name returns `409`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
     workspaceKeyUnsupported: true,
@@ -2757,17 +2758,17 @@ export const V2_MCP_OPERATIONS = {
   },
   updateMcpServer: {
     contract: v2UpdateMcpServerContract,
-    summary: 'Update MCP Server',
+    summary: 'Update MCP server',
     description:
-      "Update an MCP server's supplied fields. Omitted fields remain unchanged unless the field specifies otherwise. Authentication changes revoke the stored OAuth grant and reset connection metadata. Use List MCP Server Tools to reconnect.\n\nOAuth scope: `api:write`.",
+      'Update an external MCP server. Omitted fields remain unchanged unless a field specifies otherwise. Authentication changes revoke its stored OAuth grant and reset connection metadata; use List MCP server tools to reconnect. The endpoint URL is immutable. Requires workspace write access.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/mcp-servers/[mcpServerId]/route').then((route) => route.PATCH),
   },
   updateOrganizationAccessRequestSettings: {
     contract: v2UpdateOrganizationAccessRequestSettingsContract,
-    summary: 'Update Organization Access Request Settings',
+    summary: 'Update organization access request settings',
     description:
-      'Allow or pause new access requests and approvals. Pausing preserves history, cancellation, and decline, and does not revoke previously granted access. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Allow or pause new access requests and approvals. Pausing preserves history, cancellation, and decline, and does not revoke previously granted access. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/access-requests/settings/route').then(
@@ -2776,9 +2777,9 @@ export const V2_MCP_OPERATIONS = {
   },
   updateOrganizationMember: {
     contract: v2UpdateOrganizationMemberContract,
-    summary: 'Update Organization Member',
+    summary: 'Update organization member',
     description:
-      'Change a member’s organization role. Requires organization administrator access. The owner’s role and memberships managed by an identity provider cannot be changed here. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Change a member’s organization role. Requires organization Admin access. The owner’s role and memberships managed by an identity provider cannot be changed here. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/members/[userId]/route').then(
@@ -2787,9 +2788,9 @@ export const V2_MCP_OPERATIONS = {
   },
   updateOrganizationMemberUsageLimit: {
     contract: v2UpdateOrganizationMemberUsageLimitContract,
-    summary: 'Update Organization Member Credit Limit',
+    summary: 'Update organization member credit limit',
     description:
-      'Set or clear a person’s credit cap. Hosted only. The userId must identify an organization member or external collaborator with workspace access in this organization. The cap is a nonnegative whole number of credits, not dollars: 0 prevents further credit-consuming usage; null removes the per-person cap. Organization limits continue to apply. Retrying the same value is safe. Requires organization administrator access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Set or clear a person’s credit cap. Hosted deployments only. The `userId` must identify an organization member or external collaborator with workspace access in this organization. The cap is a nonnegative whole number of credits, not dollars: `0` prevents further credit-consuming usage; `null` removes the per-person cap. Organization limits continue to apply. Retrying the same value is safe. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/members/[userId]/usage-limit/route').then(
@@ -2798,9 +2799,9 @@ export const V2_MCP_OPERATIONS = {
   },
   updatePermissionGroup: {
     contract: v2UpdatePermissionGroupContract,
-    summary: 'Update Permission Group',
+    summary: 'Update permission group',
     description:
-      'Update a permission group. Omitted fields remain unchanged; config keys are patched and supplied arrays replace their lists. Promoting a group to default demotes the previous default; demoting without workspaceIds leaves it inactive. Overlapping member or all-member scopes conflict. Requires organization admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Update a permission group. Omitted fields remain unchanged; config keys are patched and supplied arrays replace their lists. Promoting a group to default demotes the previous default; demoting without workspaceIds leaves it inactive. Overlapping member or all-member scopes conflict. Requires organization Admin or owner access and active Access Control. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/permission-groups/[groupId]/route').then(
@@ -2809,32 +2810,32 @@ export const V2_MCP_OPERATIONS = {
   },
   updateRowsByFilter: {
     contract: v2UpdateRowsByFilterContract,
-    summary: 'Update Rows by Filter',
+    summary: 'Update rows by filter',
     description:
       'Apply the same partial data patch to every row matching a non-empty predicate.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/rows/route').then((route) => route.PATCH),
   },
   updateSandbox: {
     contract: v2UpdateSandboxContract,
-    summary: 'Update Sandbox',
+    summary: 'Update sandbox',
     description:
-      'Update a sandbox, preserving omitted fields and replacing supplied lists. Dependency changes may start a build; resending a failed specification retries its build. `buildStatus: null` means no build is required. Requires workspace admin access on Max or Enterprise. Creates and updates share a rate limit; respect `Retry-After`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Update a sandbox; omitted fields stay unchanged and supplied lists replace their contents. Dependency changes may start a build; resending a failed specification retries it. `buildStatus: null` means no image build is needed. Requires workspace Admin access and a configured remote Function runtime. With billing enabled, Max or Enterprise is required unless deployment entitlement overrides it; billing-disabled deployments require sandbox entitlement. Creates and updates share a rate limit; respect `Retry-After`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/sandboxes/[sandboxId]/route').then((route) => route.PATCH),
   },
   updateSkill: {
     contract: v2UpdateSkillContract,
-    summary: 'Update Skill',
+    summary: 'Update skill',
     description:
-      'Update a workspace skill. Omitted fields remain unchanged. Built-in skills are read-only. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Update a workspace skill. Omitted fields remain unchanged. Requires skill editor or workspace Admin access; workspace write access alone does not grant editor access. Built-in skills cannot be changed. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () => import('@/app/api/v2/skills/[skillId]/route').then((route) => route.PATCH),
   },
   updateSsoPolicy: {
     contract: v2UpdateSsoPolicyContract,
-    summary: 'Update SSO Policy',
+    summary: 'Update SSO policy',
     description:
-      'Require or stop requiring SSO on future sign-ins. Requires organization administrator access. Enabling requires SSO entitlement and a verified provider; disabling remains available after entitlement is lost. Existing sessions remain active. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Require or stop requiring SSO on future sign-ins. Requires organization Admin access. Enabling requires SSO entitlement and a verified provider; disabling remains available after entitlement is lost. Existing sessions remain active. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/sso/policy/route').then(
@@ -2843,14 +2844,14 @@ export const V2_MCP_OPERATIONS = {
   },
   updateTable: {
     contract: v2UpdateTableContract,
-    summary: 'Update Table',
+    summary: 'Update table',
     description:
       'Rename a table, edit its description, or move it to a folder. Fields are saved independently: a failed request may leave partial changes. `error.details.applied` lists saved fields; retry only the remaining fields. If absent, nothing changed. Lock flags are read-only. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.',
     handler: () => import('@/app/api/v2/tables/[tableId]/route').then((route) => route.PATCH),
   },
   updateTableColumn: {
     contract: v2UpdateTableColumnContract,
-    summary: 'Update Column',
+    summary: 'Update column',
     description:
       'Update a column by name and return the complete schema. Renames update rows, views, and workflow-group references keyed by column ID. Workflow Table blocks keep their authored `filter`, `order`, and `data` JSON unchanged. Bound blocks still referencing the old name appear in `unmigrated`; edit them with Apply Workflow Operations to prevent failures on their next run.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -2858,7 +2859,7 @@ export const V2_MCP_OPERATIONS = {
   },
   updateTableRow: {
     contract: v2UpdateTableRowContract,
-    summary: 'Update Row',
+    summary: 'Update row',
     description:
       'Merge a partial data patch into one row by identifier.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -2866,7 +2867,7 @@ export const V2_MCP_OPERATIONS = {
   },
   updateTableView: {
     contract: v2UpdateTableViewContract,
-    summary: 'Update View',
+    summary: 'Update view',
     description:
       'Rename a view, replace or shallow-merge its configuration, or promote it to the table default.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -2874,14 +2875,14 @@ export const V2_MCP_OPERATIONS = {
   },
   updateWorkflow: {
     contract: v2UpdateWorkflowContract,
-    summary: 'Update Workflow',
+    summary: 'Update workflow',
     description:
-      "Update a workflow's name, description, or folder path. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
+      "Update a workflow's name, description, or folder path with workspace write access. Omitted fields remain unchanged; `description: null` clears the description. Workspace folder trees exceeding 10,000 folders return `413`.\n\nOAuth scope: `api:write`.",
     handler: () => import('@/app/api/v2/workflows/[workflowId]/route').then((route) => route.PATCH),
   },
   updateWorkflowGroup: {
     contract: v2UpdateWorkflowGroupContract,
-    summary: 'Update Workflow Group',
+    summary: 'Update workflow group',
     description:
       'Restructure a workflow group, its producer, outputs, or execution behavior. Repointing the group at a different workflow concurrently invalidates the resolved output types and returns `409` — retry the update.\n\nOAuth scope: `api:write`.',
     handler: () =>
@@ -2889,27 +2890,27 @@ export const V2_MCP_OPERATIONS = {
   },
   updateWorkflowMcpServer: {
     contract: v2UpdateWorkflowMcpServerContract,
-    summary: 'Update Workflow MCP Server',
+    summary: 'Update workflow MCP server',
     description:
-      "Update a workflow MCP server's name, description, or public access. Omitted fields remain unchanged; `description: null` clears the description. Publish or unpublish tools separately. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+      'Update a workflow MCP server’s name, description, or public access. Omitted fields stay unchanged; `description: null` clears the description. With `isPublic: true`, anyone holding its URL can execute its tools without a Sim API key. Deploy or undeploy tools separately. Requires workspace Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflow-mcp-servers/[serverId]/route').then((route) => route.PATCH),
   },
   updateWorkflowPublicApi: {
     contract: v2UpdateWorkflowPublicApiContract,
-    summary: 'Update Workflow Public API Access',
+    summary: 'Update workflow public API access',
     description:
-      'Enable or disable unauthenticated execution of the deployed workflow. Enabling allows anyone with the execution URL to consume billed usage. Organization sharing restrictions return `403` with `PUBLIC_SHARING_NOT_ALLOWED`. Hosted chat is managed separately. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Enable or disable unauthenticated execution of the deployed workflow. Requires workspace Admin access. Enabling lets anyone with the execution URL consume billed usage. Organization sharing restrictions return `403` with `PUBLIC_SHARING_NOT_ALLOWED`. Hosted chat is managed separately. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/deployment/route').then((route) => route.PATCH),
   },
   updateWorkflowVersion: {
     contract: v2UpdateWorkflowVersionContract,
-    summary: 'Update Workflow Version',
+    summary: 'Update workflow version',
     description:
-      "Update a deployment version's name or release note. Omitted fields remain unchanged; `description: null` clears the note. The graph and live version remain unchanged. Use Activate Workflow Version to make this version live.\n\nOAuth scope: `api:write`.",
+      "Update a deployment version's name or release note with workspace write access. Omitted fields remain unchanged; `description: null` clears the note. The graph and live version are unchanged. Use Activate workflow version to serve it.\n\nOAuth scope: `api:write`.",
     handler: () =>
       import('@/app/api/v2/workflows/[workflowId]/versions/[version]/route').then(
         (route) => route.PATCH
@@ -2917,9 +2918,9 @@ export const V2_MCP_OPERATIONS = {
   },
   updateWorkspaceForkExclusions: {
     contract: v2UpdateWorkspaceForkExclusionsContract,
-    summary: 'Update Workspace Fork Exclusions',
+    summary: 'Update workspace fork exclusions',
     description:
-      'Include or exclude selected workflows from fork sync. Excluded workflows are skipped as sources and targets. Missing, archived, and unchanged workflow IDs are skipped. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Include or exclude selected workflows from fork sync with workspace Admin access. Excluded workflows are skipped as sources and targets. Missing, archived, and unchanged workflow IDs are skipped. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/exclusions/route').then(
@@ -2928,9 +2929,9 @@ export const V2_MCP_OPERATIONS = {
   },
   updateWorkspaceForkMappings: {
     contract: v2UpdateWorkspaceForkMappingsContract,
-    summary: 'Update Workspace Fork Mappings',
+    summary: 'Update workspace fork mappings',
     description:
-      'Update edge mappings after validating destination resource membership and credential provider compatibility. Push addresses current-to-other mappings; pull addresses other-to-current mappings. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Update mappings along a direct fork edge with Admin access to both workspaces. Destination resource membership and credential provider compatibility are validated. Push maps current-to-other; pull maps other-to-current. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/fork/mappings/route').then(
@@ -2939,16 +2940,16 @@ export const V2_MCP_OPERATIONS = {
   },
   upsertCredentialMember: {
     contract: v2UpsertCredentialMemberContract,
-    summary: 'Upsert Credential Member',
+    summary: 'Upsert credential member',
     description:
-      'Grant or change an existing workspace member’s credential role. Requires credential administrator access and the integrations.manage capability. Revoked grants become active again; inherited administrators cannot be demoted. A new grant returns 201; an existing grant returns 200. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Grant or change a current workspace member’s credential role. Requires credential Admin access and the `integrations.manage` capability. Revoked grants become active again; inherited workspace Admins cannot be demoted. A new grant returns `201`; an existing grant returns `200`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/credentials/[credentialId]/members/route').then((route) => route.POST),
   },
   upsertFileShare: {
     contract: v2UpsertFileShareContract,
-    summary: 'Enable or Disable File Share',
+    summary: 'Enable or disable file share',
     description:
       "Create or update a file's public share. `isActive` is required; other fields describe their behavior when access modes change. Enabling a protected mode on a previously unshared file requires its credential in the same request. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
     workspaceKeyUnsupported: true,
@@ -2956,17 +2957,17 @@ export const V2_MCP_OPERATIONS = {
   },
   upsertTableRow: {
     contract: v2UpsertTableRowContract,
-    summary: 'Upsert Row',
+    summary: 'Upsert row',
     description:
-      'Insert a row or replace the row matching a selected unique column. On replacement, omitted columns are cleared; send the complete row. Use Update Row for a partial patch.\n\nOAuth scope: `api:write`.',
+      'Insert a row or replace the row matching a selected unique column. On replacement, omitted columns are cleared; send the complete row. Use Update row for a partial patch.\n\nOAuth scope: `api:write`.',
     handler: () =>
       import('@/app/api/v2/tables/[tableId]/rows/upsert/route').then((route) => route.POST),
   },
   verifyOrganizationDomain: {
     contract: v2VerifyOrganizationDomainContract,
-    summary: 'Verify Organization Domain',
+    summary: 'Verify organization domain',
     description:
-      'Verify domain ownership through the published DNS TXT challenge and grant domain trust to matching organization providers. Requires organization administrator access and Enterprise domain entitlement. An already-verified domain is returned unchanged. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Verify domain ownership through its DNS TXT challenge and grant domain trust to matching organization providers. Requires organization Admin access and, when billing is enabled, Enterprise domain entitlement. Billing-disabled self-hosted deployments may configure operator verification. An already-verified domain is returned unchanged. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/organizations/[organizationId]/domains/[domainId]/verify/route').then(
diff --git a/apps/sim/lib/permission-groups/fields.ts b/apps/sim/lib/permission-groups/fields.ts
index 47e21c1d8c0..ee5d18c724e 100644
--- a/apps/sim/lib/permission-groups/fields.ts
+++ b/apps/sim/lib/permission-groups/fields.ts
@@ -379,7 +379,7 @@ export const PERMISSION_GROUP_FIELDS = {
     id: 'hide-deploy-chatbot',
     label: 'Chat Deployment',
     category: 'Deployment',
-    hint: 'Prevent publishing a workflow as a chat.',
+    hint: 'Prevent deploying a workflow as a chat.',
   }),
   allowedChatDeployAuthTypes: allowlist(shareAuthType, 'capability', {
     limited:
diff --git a/apps/sim/scripts/test-mobile-e2e.ts b/apps/sim/scripts/test-mobile-e2e.ts
index e98317b3a34..0ebc467311b 100644
--- a/apps/sim/scripts/test-mobile-e2e.ts
+++ b/apps/sim/scripts/test-mobile-e2e.ts
@@ -1111,7 +1111,7 @@ async function exerciseViewport(
         await expectContained(page, navigation)
         await navigation.getByRole('button', { name: 'General', exact: true }).tap()
         await expectContained(page, page.getByRole('menu'))
-        await page.getByRole('menuitem', { name: 'General', exact: true }).tap()
+        await page.getByRole('menuitemradio', { name: 'General', exact: true }).tap()
         await expect(page.getByRole('menu')).toHaveCount(0)
         await expect(page).toHaveURL(/\/selfhost\/settings\/general/)
         await expect(navigation).toBeVisible()
diff --git a/packages/emcn/src/components/chip-select/chip-select.tsx b/packages/emcn/src/components/chip-select/chip-select.tsx
index 5e5f1a69327..4ff3a6e5a4e 100644
--- a/packages/emcn/src/components/chip-select/chip-select.tsx
+++ b/packages/emcn/src/components/chip-select/chip-select.tsx
@@ -241,6 +241,8 @@ export function ChipSelect({
     return (
       <DropdownMenuItem
         key={opt.value}
+        role='menuitemradio'
+        aria-checked={value === opt.value}
         disabled={opt.disabled}
         onSelect={() => onChange?.(opt.value)}
       >
diff --git a/packages/sim-cli/src/commands/protocol/chat.ts b/packages/sim-cli/src/commands/protocol/chat.ts
index c896519ab28..350996d825d 100644
--- a/packages/sim-cli/src/commands/protocol/chat.ts
+++ b/packages/sim-cli/src/commands/protocol/chat.ts
@@ -114,7 +114,7 @@ document, conversation ID included.
 
 Examples:
   $ sim chat "What workflows do I have?"
-  $ sim chat -c 3f2a… "Which of those run on a schedule?"
+  $ sim chat -c "$CONVERSATION_ID" "Which of those run on a schedule?"
   $ sim --output json chat "Summarize yesterday's failed runs" | jq -r '.content'
 `
     )
diff --git a/packages/sim-cli/src/commands/protocol/tables-import.ts b/packages/sim-cli/src/commands/protocol/tables-import.ts
index 4c5a5a9dd6c..5777644c607 100644
--- a/packages/sim-cli/src/commands/protocol/tables-import.ts
+++ b/packages/sim-cli/src/commands/protocol/tables-import.ts
@@ -151,12 +151,15 @@ export function attachTableImport(tables: Command): void {
     'getTableImport',
   ])
   importCommand
-    .argument('[path]', 'Local CSV file to import; omit when using --file-id')
+    .argument(
+      '[path]',
+      'Local CSV file to import; choose exactly one source: this path or --file-id'
+    )
     .allowExcessArguments(false)
     .description('Import a CSV, into a new table by default')
     .option(
       '--name <name>',
-      'Identifier for the new table: letters, numbers, and underscores; defaults to the sanitized file name'
+      'Name for a new table: letters, numbers, and underscores. A local CSV defaults to its sanitized filename; required with --file-id unless --table-id names an existing table'
     )
     .option('--table-id <id>', 'Import into this existing table instead of creating one')
     .addOption(
diff --git a/packages/sim-cli/src/commands/protocol/workflow-run-wait.ts b/packages/sim-cli/src/commands/protocol/workflow-run-wait.ts
index f4282227d29..f238cb3b947 100644
--- a/packages/sim-cli/src/commands/protocol/workflow-run-wait.ts
+++ b/packages/sim-cli/src/commands/protocol/workflow-run-wait.ts
@@ -215,7 +215,7 @@ export function attachWorkflowRunWait(runs: Command): void {
   wait
     .argument('<runId>', V2_OPERATIONS.getWorkflowRun.pathParamDocs?.runId)
     .allowExcessArguments(false)
-    .description('Wait for a run to reach a terminal state, then show it')
+    .description('Wait until a run finishes or needs input')
     .addOption(
       new Option('--workflow <workflowId>', 'Workflow ID (required)').makeOptionMandatory()
     )
@@ -225,6 +225,10 @@ export function attachWorkflowRunWait(runs: Command): void {
         `Give up after this many seconds, or 0 to wait indefinitely (default: ${DEFAULT_WAIT_TIMEOUT_SECONDS}). Bounds the whole wait; SIM_TIMEOUT_SECONDS bounds one request`
       )
     )
+    .addHelpText(
+      'after',
+      'Exit codes: 0 completed, 1 failed, 2 cancelled, 3 needs input, 4 timed out. Time-based pauses continue waiting; a human pause or an unspecified pause kind ends the wait with code 3. Use `sim workflows runs resume` with the pause context to continue.'
+    )
     .action(async (runId: string, options: { workflow: string; waitTimeout?: string }) => {
       const timeoutSeconds =
         options.waitTimeout === undefined
diff --git a/packages/sim-cli/src/commands/protocol/workspace-operation-wait.ts b/packages/sim-cli/src/commands/protocol/workspace-operation-wait.ts
index 0ccb22f5309..80127b89403 100644
--- a/packages/sim-cli/src/commands/protocol/workspace-operation-wait.ts
+++ b/packages/sim-cli/src/commands/protocol/workspace-operation-wait.ts
@@ -165,10 +165,12 @@ export function attachWorkspaceOperationWait(operations: Command): void {
   wait
     .argument('<operationId>', 'Operation ID returned by import, fork, push, or pull')
     .allowExcessArguments(false)
-    .description(
-      'Wait for copy and deployment readiness; exit 3 for configuration, 1 for failure, or 4 for timeout'
-    )
+    .description('Wait for workspace copy and deployment readiness')
     .option('--wait-timeout <seconds>', 'Maximum total wait (default 3600; 0 waits indefinitely)')
+    .addHelpText(
+      'after',
+      'Exit codes: 0 completed (including completion with warnings), 1 follow-up work failed, 3 destination configuration is required, 4 timed out. The mutation may already be committed; reconcile using the same operation or request ID rather than repeating it with a new ID.'
+    )
     .action(async (operationId: string, options: { waitTimeout?: string }) => {
       const timeout = workspaceWaitTimeout(options.waitTimeout)
       const { client, profile } = connectWait()
diff --git a/packages/sim-cli/src/commands/search.ts b/packages/sim-cli/src/commands/search.ts
index ff96f43d52f..ab3d38e30f8 100644
--- a/packages/sim-cli/src/commands/search.ts
+++ b/packages/sim-cli/src/commands/search.ts
@@ -127,7 +127,7 @@ export function searchCommands(program: Command, query: string, exclude: Command
 
 export function searchCommand(): Command {
   return new Command('search')
-    .description('Find the command for a task, described in plain words')
+    .description('Find commands for a task')
     .argument('<query...>', 'What you want to do, e.g. "cancel a workflow run"')
     .addHelpText(
       'after',
diff --git a/packages/sim-cli/src/commands/secrets.ts b/packages/sim-cli/src/commands/secrets.ts
index a4dddf561b8..f68cd6a86b6 100644
--- a/packages/sim-cli/src/commands/secrets.ts
+++ b/packages/sim-cli/src/commands/secrets.ts
@@ -187,6 +187,10 @@ export function attachSecretCommands(program: Command): void {
       `${V2_OPERATIONS.setSecret.body.unredacted.describe} Pass --no-unredacted to restore redaction`
     )
     .option('--no-unredacted', 'Send --unredacted as false')
+    .addHelpText(
+      'after',
+      'Omit --value to enter it privately in a terminal. For an existing workspace secret, passing only --description or a redaction flag keeps the stored value and does not prompt. Personal secrets always require a value; they accept no writable metadata. In scripts, pass --value @path or --value @-.'
+    )
     .on('option:unredacted', () => redactionSpellings.add('--unredacted'))
     .on('option:no-unredacted', () => redactionSpellings.add('--no-unredacted'))
     .action((name: string, options: SetSecretOptions) =>
diff --git a/packages/sim-cli/src/commands/telemetry.ts b/packages/sim-cli/src/commands/telemetry.ts
index 9bb8368c0a5..f30b31418e3 100644
--- a/packages/sim-cli/src/commands/telemetry.ts
+++ b/packages/sim-cli/src/commands/telemetry.ts
@@ -48,7 +48,11 @@ export function telemetryCommand(): Command {
 
   telemetry
     .command('status')
-    .description('Show whether usage reporting is on, and why not if it is off')
+    .description('Show usage-reporting status')
+    .addHelpText(
+      'after',
+      'Telemetry commands always print text. DO_NOT_TRACK and SIM_TELEMETRY_DISABLED override the saved preference; a build without a reporting destination remains off. See the usage-data guide for the data collected.'
+    )
     .action(() => {
       console.log(describe(currentStatus()))
       console.log(`Learn more: ${USAGE_DATA_DOCS_URL}`)
@@ -56,7 +60,7 @@ export function telemetryCommand(): Command {
 
   telemetry
     .command('enable')
-    .description('Turn usage reporting on for this machine')
+    .description('Enable the usage-reporting preference for this machine')
     .action(() => setEnabled(true))
 
   telemetry
diff --git a/packages/sim-cli/src/contract/commands.ts b/packages/sim-cli/src/contract/commands.ts
index 891a106eee4..c55bbbd0658 100644
--- a/packages/sim-cli/src/contract/commands.ts
+++ b/packages/sim-cli/src/contract/commands.ts
@@ -69,7 +69,7 @@ const FOLDER_PATH_FLAG = {
 } as const
 const FOLDER_DELETE_FLAGS = {
   path: FOLDER_PATH_INPUT,
-  recursive: { boolean: true, describe: 'Delete the folder and its descendants' },
+  recursive: { boolean: true, describe: 'Archive the folder and its descendants' },
 } as const
 const KNOWLEDGE_BASE_PATH_ARGUMENT = { knowledgeBaseId: 'knowledgeBaseId' } as const
 /**
@@ -153,7 +153,7 @@ export const CLI_CONTRACT: CliContract = {
     // fields otherwise render as an unexplained em-dash for exactly the key
     // most people run the CLI with.
     describe:
-      'Show billing status, credits spent this period, and storage used (credits and storage require an OAuth login or personal API key)',
+      'Show billing status, credits spent, and storage used (credits and storage require an OAuth login or personal API key)',
     fields: [
       { header: 'plan' },
       { header: 'status' },
@@ -180,7 +180,9 @@ export const CLI_CONTRACT: CliContract = {
     describe:
       "List credit usage events (an OAuth login or personal API key reports only your events; a workspace API key reports every member's in aggregate, unattributed)",
     flags: {
-      source: { describe: 'Filter by usage source; sim-chat combines Copilot and workspace chat' },
+      source: {
+        describe: 'Filter by usage source; sim-chat combines Sim agent and workspace Chat usage',
+      },
       period: { describe: 'Billing period' },
       startDate: { describe: 'Custom period start (ISO 8601)' },
       endDate: { describe: 'Custom period end (ISO 8601)' },
@@ -470,7 +472,7 @@ export const CLI_CONTRACT: CliContract = {
    */
   getMeta: {
     command: 'meta status',
-    describe: 'Show what this API supports and which limits apply',
+    describe: 'Show API availability and the calling credential’s type and expiry',
   },
   getWorkflowChatDeployment: {
     command: 'workflows chat status',
@@ -569,7 +571,8 @@ export const CLI_CONTRACT: CliContract = {
     },
   },
   applyWorkflowVariables: {
-    confirm: 'This replaces the workflow’s variables and cannot be undone.',
+    confirm:
+      'This applies the listed variable changes; variables omitted from the operations remain unchanged.',
     flags: {
       operations: { json: true, describe: WORKFLOW_VARIABLE_OPERATIONS_HELP },
     },
@@ -640,7 +643,8 @@ export const CLI_CONTRACT: CliContract = {
     // collision rename as `files batch-delete` above and takes the same word.
     command: 'tables batch-delete',
     flags: { folderPaths: FOLDER_PATHS_FLAG },
-    confirm: 'This deletes every listed table and all of their rows.',
+    confirm:
+      'This archives the selected tables and folders, including their rows. Restore eligible tables with `tables restore`.',
   },
   searchFileContent: {
     flags: {
@@ -686,7 +690,7 @@ export const CLI_CONTRACT: CliContract = {
   },
 
   upsertTableRow: {
-    describe: 'Insert a row, or update the one that conflicts on a unique column',
+    describe: 'Insert a row, or replace the one matching a unique column',
     flags: {
       data: { json: true },
       conflictTarget: { name: 'on', describe: 'Unique column to resolve the conflict against' },
@@ -697,6 +701,10 @@ export const CLI_CONTRACT: CliContract = {
     command: 'tables rows query',
     describe: 'Query rows with a filter and sort',
     flags: {
+      includeRunState: {
+        describe:
+          'Include per-workflow-group run outcomes on every row. Off by default. Each request above 2 MiB of run state returns 413; request fewer rows or omit run state. CLI --limit 0 still fetches bounded pages.',
+      },
       predicate: { name: 'filter', json: true, describe: TABLE_READ_FILTER_HELP },
       sort: { json: true, describe: TABLE_SORT_HELP },
     },
@@ -737,7 +745,15 @@ export const CLI_CONTRACT: CliContract = {
       folderPath: FOLDER_PATH_FLAG,
     },
   },
-  createFile: { flags: { folderPath: FOLDER_PATH_FLAG } },
+  createFile: {
+    flags: {
+      folderPath: FOLDER_PATH_FLAG,
+      content: {
+        describe:
+          'Initial file content. Omit or send an empty string for a zero-byte file. The complete JSON request is capped at 10 MiB, including encoding and the envelope; the separate decoded-file limit is 50 MiB. For larger payloads, use `sim files upload <path>`',
+      },
+    },
+  },
   createKnowledgeBase: { flags: { folderPath: FOLDER_PATH_FLAG } },
   updateKnowledgeBase: {
     variants: [moveResource('knowledge mv', 'knowledge base')],
@@ -944,7 +960,7 @@ export const CLI_CONTRACT: CliContract = {
       fileReferences: {
         name: 'file',
         list: true,
-        describe: 'Workspace file ID or key (repeatable)',
+        describe: 'Workspace file ID or canonical files/<folder>/<name> path (repeatable)',
       },
     },
   },
@@ -1392,7 +1408,7 @@ export const CLI_CONTRACT: CliContract = {
       organizationId: {
         name: 'organization',
         describe:
-          'Organization ID; defaults to your only organization, and is required when your account belongs to more than one (OAuth login or personal API key required)',
+          'Organization whose audit trail to read; defaults to the caller’s organization. A caller that belongs to no organization, or names one it does not belong to, is refused with 403',
       },
     },
     columns: [
@@ -1411,7 +1427,7 @@ export const CLI_CONTRACT: CliContract = {
       organizationId: {
         name: 'organization',
         describe:
-          'Organization ID; defaults to your only organization, and is required when your account belongs to more than one (OAuth login or personal API key required)',
+          'Organization whose audit trail to read; defaults to the caller’s organization. A caller that belongs to no organization, or names one it does not belong to, is refused with 403',
       },
     },
   },
@@ -1426,7 +1442,7 @@ export const CLI_CONTRACT: CliContract = {
     flags: {
       fileIds: { list: true },
     },
-    confirm: 'This deletes every listed file.',
+    confirm: 'This archives the listed files; restore them with `files restore`.',
   },
   getFile: {
     command: 'files describe',
@@ -1532,7 +1548,8 @@ export const CLI_CONTRACT: CliContract = {
   deleteFileVersion: {
     command: 'files versions delete',
     describe: 'Permanently delete a previous version of a file',
-    confirm: 'This permanently deletes the version and its stored content.',
+    confirm:
+      'This permanently removes the version from history and schedules deletion of its stored content; storage cleanup may retry in the background.',
   },
   // Left to derive, the folder restore lands under `files restore` and turns
   // that leaf back into a group holding a lone `create` — the exact shape the
@@ -1575,9 +1592,9 @@ export const CLI_CONTRACT: CliContract = {
   },
   replaceWorkflowChatDeployment: {
     command: 'workflows chat publish',
-    describe: 'Publish or replace a workflow’s chat deployment',
+    describe: 'Deploy or replace a workflow chat',
     confirm:
-      'This replaces the chat deployment wholesale. Any field you omit returns to its default, including a stored password or allow-list.',
+      'This replaces visitor access settings for the chat deployment. Omitted authentication fields reset to defaults, including the password and allowed-email list; avatar and welcome-message behavior follows their option descriptions.',
   },
   deleteWorkflowChatDeployment: {
     command: 'workflows chat unpublish',
@@ -2018,7 +2035,7 @@ export const CLI_CONTRACT: CliContract = {
       // `workflow-run-follow.ts`, because an `--async` run rejects the field.
       includeFileBase64: {
         describe:
-          'Inline eligible output files as base64 content (default: true; Sim’s in-app agent gets file references only unless this flag is passed). Rejected when `async` is true.',
+          'Inline eligible output files as base64 content. Defaults to true for the installed CLI; Chat defaults to file references and admits requested bytes only for synchronous runs. Rejected when async is true.',
       },
       // Exposed under its domain name: every other flag in the CLI is one, and
       // `--x-run-id` would be the only place the raw HTTP header spelling
diff --git a/packages/sim-cli/src/generated/v2-api.ts b/packages/sim-cli/src/generated/v2-api.ts
index 6c049087164..303687312e4 100644
--- a/packages/sim-cli/src/generated/v2-api.ts
+++ b/packages/sim-cli/src/generated/v2-api.ts
@@ -14656,7 +14656,7 @@ export const V2_OPERATIONS = {
     pathParams: ['uploadId'] as const,
     pathParamDocs: { uploadId: 'Upload session identifier.' },
     responseMode: 'json',
-    summary: 'Abort File Upload',
+    summary: 'Abort file upload',
     query: {
       workspaceId: {
         kind: 'string',
@@ -14681,7 +14681,7 @@ export const V2_OPERATIONS = {
       uploadId: 'Upload session identifier returned when the upload was created.',
     },
     responseMode: 'json',
-    summary: 'Abort Document Upload',
+    summary: 'Abort document upload',
     query: {
       workspaceId: {
         kind: 'string',
@@ -14706,7 +14706,7 @@ export const V2_OPERATIONS = {
       version: 'Numeric deployment version.',
     },
     responseMode: 'json',
-    summary: 'Activate Workflow Version',
+    summary: 'Activate workflow version',
     workspaceKeyUnsupported: true,
   },
   addOrganizationDomain: {
@@ -14718,7 +14718,7 @@ export const V2_OPERATIONS = {
         'Organization whose single sign-on settings and verified domains are managed.',
     },
     responseMode: 'json',
-    summary: 'Add Organization Domain',
+    summary: 'Add organization domain',
     workspaceKeyUnsupported: true,
     body: {
       domain: {
@@ -14737,7 +14737,7 @@ export const V2_OPERATIONS = {
       groupId: 'Permission group identifier.',
     },
     responseMode: 'json',
-    summary: 'Add Permission Group Member',
+    summary: 'Add permission group member',
     workspaceKeyUnsupported: true,
     body: {
       userId: { kind: 'string', required: true, describe: 'Existing organization member to add.' },
@@ -14749,7 +14749,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Add Column',
+    summary: 'Add column',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
       column: { kind: 'object', required: true, describe: 'Column definition to add.' },
@@ -14761,7 +14761,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Add Workflow Group',
+    summary: 'Add workflow group',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       group: {
@@ -14788,7 +14788,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Index Workspace Files',
+    summary: 'Index workspace files',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -14800,7 +14800,7 @@ export const V2_OPERATIONS = {
         kind: 'array',
         required: true,
         describe:
-          'Workspace file identifiers or storage keys to index. Duplicates resolving to the same file are indexed once.',
+          'Workspace file IDs or paths to index. Prefer IDs or canonical `files/<folder>/<name>` paths. Duplicates resolving to the same file are indexed once.',
       },
     },
   },
@@ -14810,7 +14810,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Apply Workflow Operations',
+    summary: 'Apply workflow operations',
     workspaceKeyUnsupported: true,
     query: {
       dryRun: {
@@ -14847,7 +14847,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Update Workflow Variables',
+    summary: 'Update workflow variables',
     body: {
       operations: {
         kind: 'array',
@@ -14865,7 +14865,7 @@ export const V2_OPERATIONS = {
       groupId: 'Permission group identifier.',
     },
     responseMode: 'json',
-    summary: 'Bulk Add Permission Group Members',
+    summary: 'Bulk add permission group members',
     workspaceKeyUnsupported: true,
     body: {
       userIds: {
@@ -14885,7 +14885,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files/bulk-delete',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Delete Files',
+    summary: 'Delete files',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace containing the files.' },
       fileIds: { kind: 'array', required: true, describe: 'File identifiers to delete.' },
@@ -14896,7 +14896,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/tables/bulk-delete',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Bulk Delete Tables and Folders',
+    summary: 'Bulk delete tables and folders',
     body: {
       workspaceId: {
         kind: 'string',
@@ -14916,7 +14916,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files/bulk-download',
     pathParams: [] as const,
     responseMode: 'binary',
-    summary: 'Bulk Download Files',
+    summary: 'Bulk download files',
     query: {
       workspaceId: {
         kind: 'string',
@@ -14940,7 +14940,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Bulk Save Tag Definitions',
+    summary: 'Bulk save tag definitions',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -14964,7 +14964,7 @@ export const V2_OPERATIONS = {
       documentId: 'Unique knowledge document identifier.',
     },
     responseMode: 'json',
-    summary: 'Bulk Update Chunks',
+    summary: 'Bulk update chunks',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -14992,7 +14992,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Bulk Enable or Disable Documents',
+    summary: 'Bulk enable or disable documents',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -15025,7 +15025,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Bulk Update Rows',
+    summary: 'Bulk update rows',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
       updates: {
@@ -15044,7 +15044,7 @@ export const V2_OPERATIONS = {
       requestId: 'Access request identifier.',
     },
     responseMode: 'json',
-    summary: 'Cancel Organization Access Request',
+    summary: 'Cancel organization access request',
     workspaceKeyUnsupported: true,
   },
   cancelTableDispatch: {
@@ -15056,7 +15056,7 @@ export const V2_OPERATIONS = {
       dispatchId: 'Unique table run-dispatch identifier.',
     },
     responseMode: 'json',
-    summary: 'Cancel Run Dispatch',
+    summary: 'Cancel run dispatch',
     query: {
       workspaceId: {
         kind: 'string',
@@ -15074,7 +15074,7 @@ export const V2_OPERATIONS = {
       exportId: 'Unique table-export identifier.',
     },
     responseMode: 'json',
-    summary: 'Cancel Table Export',
+    summary: 'Cancel table export',
     query: {
       workspaceId: {
         kind: 'string',
@@ -15089,7 +15089,7 @@ export const V2_OPERATIONS = {
     pathParams: ['importId'] as const,
     pathParamDocs: { importId: 'Unique table-import identifier.' },
     responseMode: 'json',
-    summary: 'Cancel Table Import',
+    summary: 'Cancel table import',
     query: {
       workspaceId: {
         kind: 'string',
@@ -15110,7 +15110,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Cancel Column Runs',
+    summary: 'Cancel column runs',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       scope: {
@@ -15137,7 +15137,7 @@ export const V2_OPERATIONS = {
       runId: 'Unique workflow run identifier.',
     },
     responseMode: 'json',
-    summary: 'Cancel Workflow Run',
+    summary: 'Cancel workflow run',
   },
   cancelWorkspaceAccessRequest: {
     method: 'POST',
@@ -15148,7 +15148,7 @@ export const V2_OPERATIONS = {
       requestId: 'Access request identifier.',
     },
     responseMode: 'json',
-    summary: 'Cancel Workspace Access Request',
+    summary: 'Cancel workspace access request',
     workspaceKeyUnsupported: true,
   },
   chat: {
@@ -15180,7 +15180,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Compare Workflow Versions',
+    summary: 'Compare workflow versions',
     query: {
       base: { kind: 'integer', required: true, describe: 'Deployment version to compare from.' },
       target: {
@@ -15196,7 +15196,7 @@ export const V2_OPERATIONS = {
     pathParams: ['uploadId'] as const,
     pathParamDocs: { uploadId: 'Upload session identifier.' },
     responseMode: 'json',
-    summary: 'Complete File Upload',
+    summary: 'Complete file upload',
     query: {
       workspaceId: {
         kind: 'string',
@@ -15221,7 +15221,7 @@ export const V2_OPERATIONS = {
       uploadId: 'Upload session identifier returned when the upload was created.',
     },
     responseMode: 'json',
-    summary: 'Complete Document Upload',
+    summary: 'Complete document upload',
     query: {
       workspaceId: {
         kind: 'string',
@@ -15243,7 +15243,7 @@ export const V2_OPERATIONS = {
     pathParams: ['importId'] as const,
     pathParamDocs: { importId: 'Unique table-import identifier.' },
     responseMode: 'json',
-    summary: 'Complete Table Import Upload',
+    summary: 'Complete table import upload',
     query: {
       workspaceId: {
         kind: 'string',
@@ -15264,7 +15264,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/credentials/connections',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Credential Connection',
+    summary: 'Create credential connection',
     workspaceKeyUnsupported: true,
     opaqueBody: true,
   },
@@ -15273,7 +15273,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/custom-tools',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Custom Tool',
+    summary: 'Create custom tool',
     body: {
       workspaceId: {
         kind: 'string',
@@ -15302,7 +15302,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create File',
+    summary: 'Create file',
     body: {
       workspaceId: {
         kind: 'string',
@@ -15327,7 +15327,7 @@ export const V2_OPERATIONS = {
         kind: 'string',
         default: '',
         describe:
-          'Initial file content. Omit or send an empty string for a zero-byte file. The 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`. Use an upload session for anything larger.',
+          'Initial file content. Omit or send an empty string for a zero-byte file. The complete JSON request is capped at 10 MiB, including UTF-8 encoding, escaping, base64, and the envelope. The separate decoded-file limit is 50 MiB. Use an upload session for larger payloads.',
       },
       encoding: {
         kind: 'enum',
@@ -15342,7 +15342,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Folder',
+    summary: 'Create folder',
     body: {
       workspaceId: {
         kind: 'string',
@@ -15357,7 +15357,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files/uploads',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create File Upload',
+    summary: 'Create file upload',
     body: {
       workspaceId: {
         kind: 'string',
@@ -15379,7 +15379,7 @@ export const V2_OPERATIONS = {
     pathParams: ['uploadId'] as const,
     pathParamDocs: { uploadId: 'Upload session identifier.' },
     responseMode: 'json',
-    summary: 'Create File Upload Part URLs',
+    summary: 'Create file upload part URLs',
     query: {
       workspaceId: {
         kind: 'string',
@@ -15407,7 +15407,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/knowledge',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Knowledge Base',
+    summary: 'Create knowledge base',
     body: {
       workspaceId: {
         kind: 'string',
@@ -15435,7 +15435,7 @@ export const V2_OPERATIONS = {
       documentId: 'Unique knowledge document identifier.',
     },
     responseMode: 'json',
-    summary: 'Create Chunk',
+    summary: 'Create chunk',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -15446,7 +15446,8 @@ export const V2_OPERATIONS = {
       content: {
         kind: 'string',
         required: true,
-        describe: 'Text to embed. It is embedded on write, so the chunk is searchable immediately.',
+        describe:
+          'Text embedded before the response. Search includes it when the chunk and document are enabled and the document has completed processing.',
       },
       enabled: {
         kind: 'boolean',
@@ -15461,7 +15462,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Create Knowledge Connector',
+    summary: 'Create knowledge connector',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -15498,7 +15499,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Create Document Upload',
+    summary: 'Create document upload',
     body: {
       workspaceId: {
         kind: 'string',
@@ -15535,7 +15536,7 @@ export const V2_OPERATIONS = {
       uploadId: 'Upload session identifier returned when the upload was created.',
     },
     responseMode: 'json',
-    summary: 'Create Document Upload Part URLs',
+    summary: 'Create document upload part URLs',
     query: {
       workspaceId: {
         kind: 'string',
@@ -15563,7 +15564,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/knowledge/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Folder',
+    summary: 'Create folder',
     body: {
       workspaceId: {
         kind: 'string',
@@ -15579,7 +15580,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Create Tag',
+    summary: 'Create tag',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -15630,7 +15631,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/mcp-servers',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create MCP Server',
+    summary: 'Create MCP server',
     body: {
       workspaceId: {
         kind: 'string',
@@ -15655,7 +15656,7 @@ export const V2_OPERATIONS = {
         kind: 'enum',
         values: ['none', 'headers', 'oauth'] as const,
         describe:
-          'Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server does not advertise OAuth. A server publishing RFC 9728 metadata is therefore stored as `oauth`, and headers configured afterwards will not authenticate — send this field explicitly to pin the method.',
+          'Authentication method. On creation, omission without `headers` probes once: an OAuth challenge selects `oauth`, an unauthenticated success selects `none`, and other outcomes fall back to `headers`. An OAuth client ID selects `oauth` when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method.',
       },
       headers: {
         kind: 'object',
@@ -15695,7 +15696,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization that owns the access requests.' },
     responseMode: 'json',
-    summary: 'Create Organization Access Request',
+    summary: 'Create organization access request',
     workspaceKeyUnsupported: true,
     body: {
       target: {
@@ -15713,7 +15714,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization identifier.' },
     responseMode: 'json',
-    summary: 'Create Organization Invitation',
+    summary: 'Create organization invitation',
     workspaceKeyUnsupported: true,
     body: {
       email: { kind: 'string', required: true, describe: 'Email address of the person to invite.' },
@@ -15732,7 +15733,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization that owns the permission groups.' },
     responseMode: 'json',
-    summary: 'Create Permission Group',
+    summary: 'Create permission group',
     workspaceKeyUnsupported: true,
     body: {
       name: {
@@ -15762,7 +15763,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/sandboxes',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Sandbox',
+    summary: 'Create sandbox',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -15803,7 +15804,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/credentials',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Service-Account Credential',
+    summary: 'Create service-account credential',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -15844,7 +15845,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/skills',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Skill',
+    summary: 'Create skill',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -15875,7 +15876,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/tables',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Table',
+    summary: 'Create table',
     body: {
       name: { kind: 'string', required: true, describe: 'Table name.' },
       description: { kind: 'string', describe: 'Optional table description.' },
@@ -15890,7 +15891,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Create Run Dispatch',
+    summary: 'Create run dispatch',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       groupIds: {
@@ -15920,7 +15921,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Create Table Export',
+    summary: 'Create table export',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       format: {
@@ -15936,7 +15937,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/tables/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Folder',
+    summary: 'Create folder',
     body: {
       workspaceId: {
         kind: 'string',
@@ -15951,7 +15952,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/tables/imports',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Table Import',
+    summary: 'Create table import',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       source: { kind: 'unknown', required: true, describe: 'CSV source for the import.' },
@@ -15970,7 +15971,7 @@ export const V2_OPERATIONS = {
     pathParams: ['importId'] as const,
     pathParamDocs: { importId: 'Unique table-import identifier.' },
     responseMode: 'json',
-    summary: 'Create Table Import Part URLs',
+    summary: 'Create table import part URLs',
     query: {
       workspaceId: {
         kind: 'string',
@@ -15999,7 +16000,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Create Rows',
+    summary: 'Create rows',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
     },
@@ -16011,7 +16012,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Create View',
+    summary: 'Create view',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
       name: { kind: 'string', required: true, describe: 'Saved-view display name.' },
@@ -16027,7 +16028,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workflows',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Workflow',
+    summary: 'Create workflow',
     body: {
       workspaceId: {
         kind: 'string',
@@ -16048,7 +16049,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workflows/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Workflow Folder',
+    summary: 'Create workflow folder',
     body: {
       workspaceId: {
         kind: 'string',
@@ -16063,13 +16064,13 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workflow-mcp-servers',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Create Workflow MCP Server',
+    summary: 'Create workflow MCP server',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
         kind: 'string',
         required: true,
-        describe: 'Workspace in which to publish the server.',
+        describe: 'Workspace in which to create the workflow MCP server.',
       },
       name: {
         kind: 'string',
@@ -16081,11 +16082,11 @@ export const V2_OPERATIONS = {
         kind: 'boolean',
         default: false,
         describe:
-          'Whether the server answers MCP clients without a Sim API key. Defaults to false — a public server executes the workflows it publishes for anyone holding its URL.',
+          'Whether the server accepts MCP clients without a Sim API key. Defaults to false; a public server lets anyone holding its URL execute the workflows it exposes.',
       },
       workflowIds: {
         kind: 'array',
-        describe: 'Deployed workflows to publish as tools on the new server.',
+        describe: 'Deployed workflows to expose as MCP tools on the new server.',
       },
     },
   },
@@ -16095,7 +16096,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Workspace in which the acting user requests access.' },
     responseMode: 'json',
-    summary: 'Create Workspace Access Request',
+    summary: 'Create workspace access request',
     workspaceKeyUnsupported: true,
     body: {
       target: {
@@ -16113,7 +16114,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Unique workspace identifier.' },
     responseMode: 'json',
-    summary: 'Create Workspace Invitations',
+    summary: 'Create workspace invitations',
     workspaceKeyUnsupported: true,
     body: {
       emails: {
@@ -16143,7 +16144,7 @@ export const V2_OPERATIONS = {
     pathParams: ['credentialId'] as const,
     pathParamDocs: { credentialId: 'Credential to disconnect.' },
     responseMode: 'json',
-    summary: 'Disconnect Credential',
+    summary: 'Disconnect credential',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -16159,7 +16160,7 @@ export const V2_OPERATIONS = {
     pathParams: ['customToolId'] as const,
     pathParamDocs: { customToolId: 'Unique custom tool identifier.' },
     responseMode: 'json',
-    summary: 'Delete Custom Tool',
+    summary: 'Delete custom tool',
     query: {
       workspaceId: {
         kind: 'string',
@@ -16174,7 +16175,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId'] as const,
     pathParamDocs: { fileId: 'File identifier.' },
     responseMode: 'json',
-    summary: 'Delete File',
+    summary: 'Delete file',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
     },
@@ -16184,7 +16185,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Delete Folder',
+    summary: 'Delete folder',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace containing the folder.' },
       path: { kind: 'string', required: true, describe: 'Path of the folder to delete.' },
@@ -16206,7 +16207,7 @@ export const V2_OPERATIONS = {
         ] as const,
         default: 'false',
         describe:
-          "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+          "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
       },
     },
   },
@@ -16216,7 +16217,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId', 'version'] as const,
     pathParamDocs: { fileId: 'File identifier.', version: 'Version number.' },
     responseMode: 'json',
-    summary: 'Delete File Version',
+    summary: 'Delete file version',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
     },
@@ -16227,7 +16228,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Delete Knowledge Base',
+    summary: 'Delete knowledge base',
     query: {
       workspaceId: {
         kind: 'string',
@@ -16246,7 +16247,7 @@ export const V2_OPERATIONS = {
       chunkId: 'Unique chunk identifier.',
     },
     responseMode: 'json',
-    summary: 'Delete Chunk',
+    summary: 'Delete chunk',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -16265,7 +16266,7 @@ export const V2_OPERATIONS = {
       connectorId: 'Connector selected for the operation.',
     },
     responseMode: 'json',
-    summary: 'Delete Knowledge Connector',
+    summary: 'Delete knowledge connector',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -16288,7 +16289,7 @@ export const V2_OPERATIONS = {
       documentId: 'Unique knowledge document identifier.',
     },
     responseMode: 'json',
-    summary: 'Delete Document',
+    summary: 'Delete document',
     query: {
       workspaceId: {
         kind: 'string',
@@ -16302,7 +16303,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/knowledge/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Delete Folder',
+    summary: 'Delete folder',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace containing the folder.' },
       path: { kind: 'string', required: true, describe: 'Path of the folder to delete.' },
@@ -16324,7 +16325,7 @@ export const V2_OPERATIONS = {
         ] as const,
         default: 'false',
         describe:
-          "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+          "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
       },
     },
   },
@@ -16337,7 +16338,7 @@ export const V2_OPERATIONS = {
       tagId: 'Unique tag definition identifier.',
     },
     responseMode: 'json',
-    summary: 'Delete Tag',
+    summary: 'Delete tag',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -16353,7 +16354,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Delete Tag Definitions',
+    summary: 'Delete tag definitions',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -16374,7 +16375,7 @@ export const V2_OPERATIONS = {
     pathParams: ['mcpServerId'] as const,
     pathParamDocs: { mcpServerId: 'Unique MCP server identifier.' },
     responseMode: 'json',
-    summary: 'Delete MCP Server',
+    summary: 'Delete MCP server',
     query: {
       workspaceId: {
         kind: 'string',
@@ -16392,7 +16393,7 @@ export const V2_OPERATIONS = {
       groupId: 'Permission group identifier.',
     },
     responseMode: 'json',
-    summary: 'Delete Permission Group',
+    summary: 'Delete permission group',
     workspaceKeyUnsupported: true,
   },
   deleteSandbox: {
@@ -16401,7 +16402,7 @@ export const V2_OPERATIONS = {
     pathParams: ['sandboxId'] as const,
     pathParamDocs: { sandboxId: 'Unique sandbox identifier.' },
     responseMode: 'json',
-    summary: 'Delete Sandbox',
+    summary: 'Delete sandbox',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the sandbox.' },
@@ -16413,7 +16414,7 @@ export const V2_OPERATIONS = {
     pathParams: ['name'] as const,
     pathParamDocs: { name: 'Secret to delete.' },
     responseMode: 'json',
-    summary: 'Delete Secret',
+    summary: 'Delete secret',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -16440,7 +16441,7 @@ export const V2_OPERATIONS = {
         'Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.',
     },
     responseMode: 'json',
-    summary: 'Delete Skill',
+    summary: 'Delete skill',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the skill.' },
@@ -16456,7 +16457,7 @@ export const V2_OPERATIONS = {
       providerId: 'Identity provider identifier.',
     },
     responseMode: 'json',
-    summary: 'Delete SSO Provider',
+    summary: 'Delete SSO provider',
     workspaceKeyUnsupported: true,
   },
   deleteTable: {
@@ -16465,7 +16466,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Delete Table',
+    summary: 'Delete table',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
     },
@@ -16476,7 +16477,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Delete Column',
+    summary: 'Delete column',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       columnName: { kind: 'string', required: true, describe: 'Name of the column to delete.' },
@@ -16487,7 +16488,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/tables/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Delete Folder',
+    summary: 'Delete folder',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace containing the folder.' },
       path: { kind: 'string', required: true, describe: 'Path of the folder to delete.' },
@@ -16509,7 +16510,7 @@ export const V2_OPERATIONS = {
         ] as const,
         default: 'false',
         describe:
-          "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+          "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
       },
     },
   },
@@ -16519,7 +16520,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId', 'rowId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.', rowId: 'Unique table row identifier.' },
     responseMode: 'json',
-    summary: 'Delete Row',
+    summary: 'Delete row',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
     },
@@ -16530,7 +16531,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Delete Rows',
+    summary: 'Delete rows',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       filter: {
@@ -16548,7 +16549,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId', 'viewId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.', viewId: 'Unique saved-view identifier.' },
     responseMode: 'json',
-    summary: 'Delete View',
+    summary: 'Delete view',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
     },
@@ -16559,7 +16560,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Delete Workflow',
+    summary: 'Delete workflow',
   },
   deleteWorkflowChatDeployment: {
     method: 'DELETE',
@@ -16567,7 +16568,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Delete Workflow Chat Deployment',
+    summary: 'Delete workflow chat deployment',
     workspaceKeyUnsupported: true,
   },
   deleteWorkflowFolder: {
@@ -16575,7 +16576,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workflows/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Delete Workflow Folder',
+    summary: 'Delete workflow folder',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace containing the folder.' },
       path: { kind: 'string', required: true, describe: 'Path of the folder to delete.' },
@@ -16597,7 +16598,7 @@ export const V2_OPERATIONS = {
         ] as const,
         default: 'false',
         describe:
-          "Delete the folder's nested files and folders too. An empty folder deletes either way; a non-empty one needs this. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.",
+          "Delete the folder's contents and nested folders too. Required for a non-empty folder. Only the listed case-sensitive spellings are accepted.",
       },
     },
   },
@@ -16607,7 +16608,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Delete Workflow Group',
+    summary: 'Delete workflow group',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       groupId: { kind: 'string', required: true, describe: 'Workflow group to delete.' },
@@ -16619,7 +16620,7 @@ export const V2_OPERATIONS = {
     pathParams: ['serverId'] as const,
     pathParamDocs: { serverId: 'Unique workflow-MCP server identifier.' },
     responseMode: 'json',
-    summary: 'Delete Workflow MCP Server',
+    summary: 'Delete workflow MCP server',
     workspaceKeyUnsupported: true,
   },
   deployWorkflow: {
@@ -16628,7 +16629,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Deploy Workflow',
+    summary: 'Deploy workflow',
     workspaceKeyUnsupported: true,
     body: {
       name: { kind: 'string', describe: 'Optional label for the deployment version.' },
@@ -16644,13 +16645,13 @@ export const V2_OPERATIONS = {
     pathParams: ['serverId'] as const,
     pathParamDocs: { serverId: 'Unique workflow-MCP server identifier.' },
     responseMode: 'json',
-    summary: 'Publish Workflow As MCP Tool',
+    summary: 'Deploy workflow as MCP tool',
     workspaceKeyUnsupported: true,
     body: {
       workflowId: {
         kind: 'string',
         required: true,
-        describe: 'Deployed workflow to publish. The workflow must already be deployed.',
+        describe: 'Workflow to expose as an MCP tool. It must already be deployed.',
       },
       toolName: {
         kind: 'string',
@@ -16674,7 +16675,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization that owns the access requests.' },
     responseMode: 'json',
-    summary: 'Discover Organization Access Requests',
+    summary: 'Discover organization access requests',
     workspaceKeyUnsupported: true,
     query: {
       search: {
@@ -16733,7 +16734,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Workspace in which the acting user requests access.' },
     responseMode: 'json',
-    summary: 'Discover Workspace Access Requests',
+    summary: 'Discover workspace access requests',
     workspaceKeyUnsupported: true,
     query: {
       search: {
@@ -16792,7 +16793,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId'] as const,
     pathParamDocs: { fileId: 'File identifier.' },
     responseMode: 'binary',
-    summary: 'Download File',
+    summary: 'Download file',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
     },
@@ -16803,7 +16804,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId', 'version'] as const,
     pathParamDocs: { fileId: 'File identifier.', version: 'Version number.' },
     responseMode: 'binary',
-    summary: 'Download File Version',
+    summary: 'Download file version',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
     },
@@ -16818,7 +16819,7 @@ export const V2_OPERATIONS = {
       fileId: 'Identifier of a file the run produced, as reported by the run resource.',
     },
     responseMode: 'binary',
-    summary: 'Download Workflow Run File',
+    summary: 'Download workflow run file',
   },
   duplicateWorkflow: {
     method: 'POST',
@@ -16826,7 +16827,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Duplicate Workflow',
+    summary: 'Duplicate workflow',
     body: {
       name: {
         kind: 'string',
@@ -16844,7 +16845,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId'] as const,
     pathParamDocs: { fileId: 'File identifier.' },
     responseMode: 'json',
-    summary: 'Edit File Content',
+    summary: 'Edit file content',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
       edit: {
@@ -16856,7 +16857,7 @@ export const V2_OPERATIONS = {
       expectedRevision: {
         kind: 'string',
         describe:
-          'Revision from Get File Metadata or an earlier write; the request is refused with `409` when the content moved on.',
+          'Revision from Get file metadata or an earlier write; the request is refused with `409` when the content moved on.',
       },
     },
   },
@@ -16866,10 +16867,10 @@ export const V2_OPERATIONS = {
     pathParams: ['toolId'] as const,
     pathParamDocs: {
       toolId:
-        'Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id.',
+        'Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID.',
     },
     responseMode: 'json',
-    summary: 'Run Tool',
+    summary: 'Run tool',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -16882,16 +16883,17 @@ export const V2_OPERATIONS = {
         kind: 'object',
         default: {},
         describe:
-          'Tool arguments keyed by published parameter IDs. For `user-only` parameters, a whole-value `{{VAR_NAME}}` reference resolves a workspace environment variable. Other values pass through unchanged.',
+          'Arguments keyed by published parameter IDs. Hidden and undeclared fields are rejected. Send connected credentials as top-level `credentialId`, not `input.credential`, `input.credentialId`, or `input.oauthCredential`. Whole-value `{{VAR_NAME}}` references resolve environment variables only for `user-only` parameters; other values pass through unchanged.',
       },
       credentialId: {
         kind: 'string',
         describe:
-          'Credential to authenticate with. Required when the tool declares an OAuth requirement; the workspace credentials list names the candidates.',
+          'Connected credential to authenticate with. Required for tools declaring required OAuth or a required credential-selector parameter. Use List credentials to find candidates; do not send credential aliases inside `input`.',
       },
       timeoutSeconds: {
         kind: 'integer',
-        describe: 'How long to wait for the tool before abandoning the call.',
+        describe:
+          'Maximum wait time in seconds; defaults to 120 and cannot exceed 300. Timeout does not guarantee that a third-party side effect was cancelled.',
       },
     },
   },
@@ -16901,7 +16903,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Execute Workflow',
+    summary: 'Execute workflow',
     body: {
       input: {
         kind: 'object',
@@ -16916,7 +16918,7 @@ export const V2_OPERATIONS = {
         kind: 'boolean',
         default: false,
         describe:
-          'Queue the run and return a 202 receipt when true. Requires an OAuth access token or API key, cannot be combined with `stream`, and rejects all streaming and output-shaping options (`selectedOutputs`, `includeThinking`, `includeToolCalls`, `includeFileBase64`, `base64MaxBytes`).',
+          'Queue the run and return a 202 receipt. Requires an API key or OAuth access token and a deployed run source. Cannot stream, select outputs, enable thinking/tool events, or include file-inlining options (`includeFileBase64` or `base64MaxBytes`).',
       },
       executionTimeoutSeconds: {
         kind: 'integer',
@@ -16960,7 +16962,7 @@ export const V2_OPERATIONS = {
       'x-run-id': {
         kind: 'string',
         describe:
-          'Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get Workflow Run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.',
+          'Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns `409` with `RUN_ID_CONFLICT`, without replaying results. Check Get workflow run, but `404` can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.',
       },
       'x-sim-via': {
         kind: 'string',
@@ -16975,7 +16977,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'binary',
-    summary: 'Export Knowledge Base',
+    summary: 'Export knowledge base',
     query: {
       workspaceId: {
         kind: 'string',
@@ -16995,7 +16997,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Export Workflow',
+    summary: 'Export workflow',
     query: {
       includeReferences: {
         kind: 'boolean',
@@ -17005,7 +17007,7 @@ export const V2_OPERATIONS = {
       includeWorkspaceBindings: {
         kind: 'boolean',
         describe:
-          'Whether to keep workspace-scoped bindings — table, knowledge base, document, folder, channel, and other resource selectors — in the exported state. Defaults to false, the sharing-safe export in which those ids are cleared because they resolve nowhere else. Send true for a same-workspace round trip so the re-imported workflow can run without re-selecting them. Credentials, passwords, and table sub-block values are cleared either way.',
+          'Keep non-secret table, knowledge base, document, folder, channel, and other workspace bindings for a same-workspace import. Defaults to false, which clears these IDs. Registered credential fields and opaque table/tool values are cleared either way; environment references and ordinary workflow variables remain included.',
       },
     },
   },
@@ -17015,7 +17017,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Fork Workspace',
+    summary: 'Fork workspace',
     workspaceKeyUnsupported: true,
     body: {
       name: { kind: 'string', describe: 'Display name of the workflow or workspace.' },
@@ -17027,12 +17029,14 @@ export const V2_OPERATIONS = {
       requestId: {
         kind: 'string',
         required: true,
-        describe: 'Stable client request ID for reconciliation and identical retries.',
+        describe:
+          'Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation.',
       },
       previewFingerprint: {
         kind: 'string',
         required: true,
-        describe: 'Fingerprint of the reviewed preview and its choices.',
+        describe:
+          'Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value.',
       },
     },
   },
@@ -17042,7 +17046,7 @@ export const V2_OPERATIONS = {
     pathParams: ['auditLogId'] as const,
     pathParamDocs: { auditLogId: 'Audit-log entry identifier.' },
     responseMode: 'json',
-    summary: 'Get Audit Log',
+    summary: 'Get audit log',
     workspaceKeyUnsupported: true,
     query: {
       organizationId: {
@@ -17057,12 +17061,12 @@ export const V2_OPERATIONS = {
     path: '/api/v2/billing/status',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Get Billing Status',
+    summary: 'Get billing status',
     query: {
       workspaceId: {
         kind: 'string',
         describe:
-          'Workspace whose payer should be resolved. A workspace API key is pinned to its own workspace: any other id answers `404 Workspace not found`, which is also what an id that does not exist answers.',
+          'Workspace whose payer to report. A workspace API key is bound to its own workspace; a different or unknown ID returns `404 Workspace not found`. Omit for account billing when using a personal API key or OAuth token.',
       },
     },
   },
@@ -17072,10 +17076,10 @@ export const V2_OPERATIONS = {
     pathParams: ['blockId'] as const,
     pathParamDocs: {
       blockId:
-        'Block type identifier. An unversioned base type resolves to the newest version, and the response echoes the resolved id.',
+        'Block type identifier. An unversioned base type resolves to the newest visible version. The response echoes the resolved ID.',
     },
     responseMode: 'json',
-    summary: 'Get Block',
+    summary: 'Get block',
     query: {
       workspaceId: {
         kind: 'string',
@@ -17091,7 +17095,7 @@ export const V2_OPERATIONS = {
     pathParams: ['customToolId'] as const,
     pathParamDocs: { customToolId: 'Unique custom tool identifier.' },
     responseMode: 'json',
-    summary: 'Get Custom Tool',
+    summary: 'Get custom tool',
     query: {
       workspaceId: {
         kind: 'string',
@@ -17106,7 +17110,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId'] as const,
     pathParamDocs: { fileId: 'File identifier.' },
     responseMode: 'json',
-    summary: 'Get File Metadata',
+    summary: 'Get file metadata',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
       scope: {
@@ -17124,7 +17128,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId'] as const,
     pathParamDocs: { fileId: 'File identifier.' },
     responseMode: 'json',
-    summary: 'Get File Share',
+    summary: 'Get file share',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
     },
@@ -17135,7 +17139,7 @@ export const V2_OPERATIONS = {
     pathParams: ['uploadId'] as const,
     pathParamDocs: { uploadId: 'Upload session identifier.' },
     responseMode: 'json',
-    summary: 'Get File Upload',
+    summary: 'Get file upload',
     query: {
       workspaceId: {
         kind: 'string',
@@ -17157,7 +17161,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId', 'version'] as const,
     pathParamDocs: { fileId: 'File identifier.', version: 'Version number.' },
     responseMode: 'json',
-    summary: 'Get File Version',
+    summary: 'Get file version',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
     },
@@ -17168,7 +17172,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Get Knowledge Base',
+    summary: 'Get knowledge base',
     query: {
       workspaceId: {
         kind: 'string',
@@ -17187,7 +17191,7 @@ export const V2_OPERATIONS = {
       chunkId: 'Unique chunk identifier.',
     },
     responseMode: 'json',
-    summary: 'Get Chunk',
+    summary: 'Get chunk',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -17206,7 +17210,7 @@ export const V2_OPERATIONS = {
       connectorId: 'Connector selected for the operation.',
     },
     responseMode: 'json',
-    summary: 'Get Knowledge Connector',
+    summary: 'Get knowledge connector',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -17225,7 +17229,7 @@ export const V2_OPERATIONS = {
       documentId: 'Unique knowledge document identifier.',
     },
     responseMode: 'json',
-    summary: 'Get Document',
+    summary: 'Get document',
     query: {
       workspaceId: {
         kind: 'string',
@@ -17240,7 +17244,7 @@ export const V2_OPERATIONS = {
     pathParams: ['runId'] as const,
     pathParamDocs: { runId: 'Unique workflow run identifier.' },
     responseMode: 'json',
-    summary: 'Get Log',
+    summary: 'Get log',
     query: {
       includeWorkflowState: {
         kind: 'boolean',
@@ -17254,7 +17258,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/logs/stats',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Get Log Statistics',
+    summary: 'Get log statistics',
     query: {
       workspaceId: {
         kind: 'string',
@@ -17318,7 +17322,7 @@ export const V2_OPERATIONS = {
           'n',
           'disabled',
         ] as const,
-        default: false,
+        default: 'false',
         describe:
           'Whether buckets with no runs are included in every series. Off by default, so each series carries only the buckets that hold at least one run; set it to publish exactly `segmentCount` buckets per series, empty ones included. The listed spellings are the whole accepted vocabulary and are case-sensitive; any other value is rejected.',
       },
@@ -17330,7 +17334,7 @@ export const V2_OPERATIONS = {
     pathParams: ['mcpServerId'] as const,
     pathParamDocs: { mcpServerId: 'Unique MCP server identifier.' },
     responseMode: 'json',
-    summary: 'Get MCP Server',
+    summary: 'Get MCP server',
     query: {
       workspaceId: {
         kind: 'string',
@@ -17344,7 +17348,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/meta',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Get API Capabilities',
+    summary: 'Get API status',
   },
   getNextKnowledgeTagSlot: {
     method: 'GET',
@@ -17352,7 +17356,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Get Next Tag Slot',
+    summary: 'Get next tag slot',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -17375,7 +17379,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization identifier.' },
     responseMode: 'json',
-    summary: 'Get Organization',
+    summary: 'Get organization',
     workspaceKeyUnsupported: true,
   },
   getOrganizationAccessRequestSettings: {
@@ -17384,7 +17388,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization that owns the access requests.' },
     responseMode: 'json',
-    summary: 'Get Organization Access Request Settings',
+    summary: 'Get organization access request settings',
     workspaceKeyUnsupported: true,
   },
   getOrganizationInvitation: {
@@ -17396,7 +17400,7 @@ export const V2_OPERATIONS = {
       invitationId: 'Invitation identifier.',
     },
     responseMode: 'json',
-    summary: 'Get Organization Invitation',
+    summary: 'Get organization invitation',
     workspaceKeyUnsupported: true,
   },
   getOrganizationMemberUsageLimit: {
@@ -17409,7 +17413,7 @@ export const V2_OPERATIONS = {
         'User ID of an organization member or external collaborator with workspace access in this organization. Use List Organization Members or List Workspace Members to find it.',
     },
     responseMode: 'json',
-    summary: 'Get Organization Member Credit Limit',
+    summary: 'Get organization member credit limit',
     workspaceKeyUnsupported: true,
   },
   getOrganizationUsageBreakdown: {
@@ -17418,7 +17422,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization identifier.' },
     responseMode: 'json',
-    summary: 'Get Organization Usage Breakdown',
+    summary: 'Get organization usage breakdown',
     workspaceKeyUnsupported: true,
     query: {
       preset: {
@@ -17465,7 +17469,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization identifier.' },
     responseMode: 'json',
-    summary: 'Get Organization Usage Summary',
+    summary: 'Get organization usage summary',
     workspaceKeyUnsupported: true,
     query: {
       preset: {
@@ -17503,7 +17507,7 @@ export const V2_OPERATIONS = {
       groupId: 'Permission group identifier.',
     },
     responseMode: 'json',
-    summary: 'Get Permission Group',
+    summary: 'Get permission group',
     workspaceKeyUnsupported: true,
   },
   getRowEnrichment: {
@@ -17516,7 +17520,7 @@ export const V2_OPERATIONS = {
       groupId: 'Workflow or enrichment group to run.',
     },
     responseMode: 'json',
-    summary: 'Get Row Group Run',
+    summary: 'Get row group run',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
     },
@@ -17527,7 +17531,7 @@ export const V2_OPERATIONS = {
     pathParams: ['sandboxId'] as const,
     pathParamDocs: { sandboxId: 'Unique sandbox identifier.' },
     responseMode: 'json',
-    summary: 'Get Sandbox',
+    summary: 'Get sandbox',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the sandbox.' },
     },
@@ -17537,7 +17541,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/selectors/get',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Get Selector Option',
+    summary: 'Get selector option',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -17660,7 +17664,7 @@ export const V2_OPERATIONS = {
           'providers.ollamaEmbeddingModels',
           'providers.openrouterEmbeddingModels',
         ] as const,
-        describe: 'Registered selector key for discovering this field’s destination options.',
+        describe: 'Registered selector key from an import or sync preview, such as `gmail.labels`.',
       },
       context: {
         kind: 'object',
@@ -17668,7 +17672,11 @@ export const V2_OPERATIONS = {
         describe:
           'Only the dependencies declared by the selector, such as oauthCredential and channelId. Missing OAuth connections require human authorization.',
       },
-      id: { kind: 'string', required: true, describe: 'Resource identifier.' },
+      id: {
+        kind: 'string',
+        required: true,
+        describe: 'Provider option ID to resolve with the same selector and declared context.',
+      },
     },
   },
   getSkill: {
@@ -17680,7 +17688,7 @@ export const V2_OPERATIONS = {
         'Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.',
     },
     responseMode: 'json',
-    summary: 'Get Skill',
+    summary: 'Get skill',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the skill.' },
     },
@@ -17694,7 +17702,7 @@ export const V2_OPERATIONS = {
         'Organization whose single sign-on settings and verified domains are managed.',
     },
     responseMode: 'json',
-    summary: 'Get SSO Policy',
+    summary: 'Get SSO policy',
     workspaceKeyUnsupported: true,
   },
   getSsoProvider: {
@@ -17707,7 +17715,7 @@ export const V2_OPERATIONS = {
       providerId: 'Identity provider identifier.',
     },
     responseMode: 'json',
-    summary: 'Get SSO Provider',
+    summary: 'Get SSO provider',
     workspaceKeyUnsupported: true,
   },
   getTable: {
@@ -17716,7 +17724,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Get Table',
+    summary: 'Get table',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
     },
@@ -17730,7 +17738,7 @@ export const V2_OPERATIONS = {
       dispatchId: 'Unique table run-dispatch identifier.',
     },
     responseMode: 'json',
-    summary: 'Get Run Dispatch',
+    summary: 'Get run dispatch',
     query: {
       workspaceId: {
         kind: 'string',
@@ -17748,7 +17756,7 @@ export const V2_OPERATIONS = {
       exportId: 'Unique table-export identifier.',
     },
     responseMode: 'json',
-    summary: 'Get Table Export',
+    summary: 'Get table export',
     query: {
       workspaceId: {
         kind: 'string',
@@ -17763,7 +17771,7 @@ export const V2_OPERATIONS = {
     pathParams: ['importId'] as const,
     pathParamDocs: { importId: 'Unique table-import identifier.' },
     responseMode: 'json',
-    summary: 'Get Table Import',
+    summary: 'Get table import',
     query: {
       workspaceId: {
         kind: 'string',
@@ -17784,12 +17792,13 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId', 'rowId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.', rowId: 'Unique table row identifier.' },
     responseMode: 'json',
-    summary: 'Get Row',
+    summary: 'Get row',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
       includeRunState: {
         kind: 'boolean',
-        describe: 'Include per-workflow-group run state on the returned row. Off by default.',
+        describe:
+          'Include per-workflow-group run outcomes on the row. Off by default. Run state above 2 MiB returns `413`; omit this option to read the row without run state.',
       },
     },
   },
@@ -17799,7 +17808,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId', 'viewId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.', viewId: 'Unique saved-view identifier.' },
     responseMode: 'json',
-    summary: 'Get View',
+    summary: 'Get view',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
     },
@@ -17810,10 +17819,10 @@ export const V2_OPERATIONS = {
     pathParams: ['toolId'] as const,
     pathParamDocs: {
       toolId:
-        'Tool identifier. An unversioned name resolves to the newest version, and the response echoes the resolved id.',
+        'Tool identifier. An exact visible ID is retained; an unversioned name resolves to the newest visible family version. The response echoes the resolved ID.',
     },
     responseMode: 'json',
-    summary: 'Get Tool',
+    summary: 'Get tool',
     query: {
       workspaceId: {
         kind: 'string',
@@ -17829,7 +17838,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Get Workflow',
+    summary: 'Get workflow',
   },
   getWorkflowChatDeployment: {
     method: 'GET',
@@ -17837,7 +17846,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Get Workflow Chat Deployment',
+    summary: 'Get workflow chat deployment',
     workspaceKeyUnsupported: true,
   },
   getWorkflowDeployment: {
@@ -17846,7 +17855,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Get Workflow Deployment',
+    summary: 'Get workflow deployment',
   },
   getWorkflowMcpServer: {
     method: 'GET',
@@ -17854,7 +17863,7 @@ export const V2_OPERATIONS = {
     pathParams: ['serverId'] as const,
     pathParamDocs: { serverId: 'Unique workflow-MCP server identifier.' },
     responseMode: 'json',
-    summary: 'Get Workflow MCP Server',
+    summary: 'Get workflow MCP server',
     workspaceKeyUnsupported: true,
   },
   getWorkflowRun: {
@@ -17866,7 +17875,7 @@ export const V2_OPERATIONS = {
       runId: 'Unique workflow run identifier.',
     },
     responseMode: 'json',
-    summary: 'Get Workflow Run',
+    summary: 'Get workflow run',
     query: {
       includeOutput: {
         kind: 'boolean',
@@ -17895,7 +17904,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Get Workflow State',
+    summary: 'Get workflow state',
   },
   getWorkflowVersion: {
     method: 'GET',
@@ -17906,7 +17915,7 @@ export const V2_OPERATIONS = {
       version: 'Numeric deployment version.',
     },
     responseMode: 'json',
-    summary: 'Get Workflow Version',
+    summary: 'Get workflow version',
   },
   getWorkspace: {
     method: 'GET',
@@ -17914,7 +17923,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Workspace to retrieve.' },
     responseMode: 'json',
-    summary: 'Get Workspace',
+    summary: 'Get workspace',
   },
   getWorkspaceForkAvailability: {
     method: 'GET',
@@ -17922,7 +17931,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Get Workspace Fork Availability',
+    summary: 'Get workspace fork availability',
     workspaceKeyUnsupported: true,
   },
   getWorkspaceForkLineage: {
@@ -17931,7 +17940,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Get Workspace Fork Lineage',
+    summary: 'Get workspace fork lineage',
     workspaceKeyUnsupported: true,
   },
   getWorkspaceForkMappings: {
@@ -17940,7 +17949,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Get Workspace Fork Mappings',
+    summary: 'Get workspace fork mappings',
     workspaceKeyUnsupported: true,
     query: {
       otherWorkspaceId: {
@@ -17989,7 +17998,7 @@ export const V2_OPERATIONS = {
       operationId: 'Durable operation identifier to use for polling.',
     },
     responseMode: 'json',
-    summary: 'Get Workspace Operation',
+    summary: 'Get workspace operation',
   },
   getWorkspacePermissionConfig: {
     method: 'GET',
@@ -17997,7 +18006,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Unique workspace identifier.' },
     responseMode: 'json',
-    summary: 'Get Workspace Permission Config',
+    summary: 'Get workspace permission config',
     workspaceKeyUnsupported: true,
   },
   grantSkillEditor: {
@@ -18009,7 +18018,7 @@ export const V2_OPERATIONS = {
         'Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.',
     },
     responseMode: 'json',
-    summary: 'Grant Skill Editor',
+    summary: 'Grant skill editor',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the skill.' },
@@ -18025,7 +18034,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workflows/import',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Import Workflow',
+    summary: 'Import workflow',
     body: {
       workspaceId: {
         kind: 'string',
@@ -18046,7 +18055,7 @@ export const V2_OPERATIONS = {
       description: { kind: 'string', describe: 'Override for the imported workflow description.' },
       mappings: {
         kind: 'array',
-        describe: 'Mappings keyed by resource type and source identifier.',
+        describe: 'Mapping entries addressed by resource kind and source identifier.',
       },
       bindings: {
         kind: 'array',
@@ -18055,15 +18064,17 @@ export const V2_OPERATIONS = {
       dependentValues: {
         kind: 'array',
         describe:
-          'Destination-dependent choices keyed by source workflow, block, and field identities.',
+          'Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated.',
       },
       requestId: {
         kind: 'string',
-        describe: 'Stable client request ID for reconciliation and identical retries.',
+        describe:
+          'Stable client request ID for mapped import. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can create another workflow.',
       },
       previewFingerprint: {
         kind: 'string',
-        describe: 'Fingerprint of the reviewed preview and its choices.',
+        describe:
+          'Fingerprint returned by an import preview with the same choices. A changed plan returns 409; preview again. Do not invent this value.',
       },
     },
   },
@@ -18072,7 +18083,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/audit-logs',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Audit Logs',
+    summary: 'List audit logs',
     workspaceKeyUnsupported: true,
     query: {
       action: { kind: 'string', describe: 'Filter by exact action name.' },
@@ -18086,12 +18097,12 @@ export const V2_OPERATIONS = {
       startDate: {
         kind: 'string',
         describe:
-          'Only include runs started at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.',
+          'Include audit entries created at or after this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected.',
       },
       endDate: {
         kind: 'string',
         describe:
-          'Only include runs started at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.',
+          'Include audit entries created at or before this UTC ISO 8601 timestamp, such as `2026-08-06T00:00:00Z`. Dates without a time, timestamps with an offset instead of `Z`, and year `0000` are rejected.',
       },
       includeDeparted: {
         kind: 'boolean',
@@ -18121,7 +18132,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/billing/logs',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Billing Logs',
+    summary: 'List billing logs',
     query: {
       source: {
         kind: 'enum',
@@ -18154,12 +18165,12 @@ export const V2_OPERATIONS = {
       startDate: {
         kind: 'string',
         describe:
-          'Only include usage events recorded at or after this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. Requires `period=custom`. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.',
+          'Include events at or after this UTC ISO 8601 timestamp, for example `2026-08-06T00:00:00Z`. Required with `period=custom`. Date-only values, UTC offsets instead of `Z`, and year `0000` are rejected.',
       },
       endDate: {
         kind: 'string',
         describe:
-          'Only include usage events recorded at or before this UTC ISO 8601 timestamp, e.g. `2026-08-06T00:00:00Z`. Requires `period=custom`, and defaults to now when omitted. A date without a time, or a timestamp carrying a UTC offset instead of `Z`, is rejected, as is year `0000`, which names no storable instant.',
+          'Include events at or before this UTC ISO 8601 timestamp, for example `2026-08-06T00:00:00Z`. Allowed only with `period=custom`; omission defaults to now. Date-only values, UTC offsets instead of `Z`, and year `0000` are rejected.',
       },
       limit: {
         kind: 'integer',
@@ -18179,7 +18190,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/blocks',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Blocks',
+    summary: 'List blocks',
     query: {
       workspaceId: {
         kind: 'string',
@@ -18217,7 +18228,7 @@ export const V2_OPERATIONS = {
         values: ['id', 'name', 'category'] as const,
         default: 'id',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -18243,7 +18254,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/chat-deployments',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Chat Deployments',
+    summary: 'List chat deployments',
     query: {
       workspaceId: {
         kind: 'string',
@@ -18282,13 +18293,13 @@ export const V2_OPERATIONS = {
     path: '/api/v2/connector-types',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Connector Types',
+    summary: 'List connector types',
     query: {
       workspaceId: {
         kind: 'string',
         required: true,
         describe:
-          'Workspace whose integration allowlist, revealed preview blocks, and deployed custom blocks decide what this catalog contains.',
+          'Workspace used to authorize Knowledge Base access to the deployment’s connector-type registry. Workspace integration allowlists and revealed preview blocks do not filter this catalog.',
       },
       search: {
         kind: 'string',
@@ -18320,7 +18331,7 @@ export const V2_OPERATIONS = {
     pathParams: ['credentialId'] as const,
     pathParamDocs: { credentialId: 'Credential whose sharing grants are managed.' },
     responseMode: 'json',
-    summary: 'List Credential Members',
+    summary: 'List credential members',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -18344,7 +18355,7 @@ export const V2_OPERATIONS = {
         values: ['email', 'name'] as const,
         default: 'email',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -18359,7 +18370,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/credentials/providers',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Credential Providers',
+    summary: 'List credential providers',
     query: {
       workspaceId: {
         kind: 'string',
@@ -18378,7 +18389,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/credentials',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Credentials',
+    summary: 'List credentials',
     query: {
       workspaceId: {
         kind: 'string',
@@ -18428,7 +18439,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/custom-tools',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Custom Tools',
+    summary: 'List custom tools',
     query: {
       workspaceId: {
         kind: 'string',
@@ -18469,7 +18480,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Folders',
+    summary: 'List folders',
     query: {
       workspaceId: {
         kind: 'string',
@@ -18490,7 +18501,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'name',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -18534,7 +18545,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Files',
+    summary: 'List files',
     query: {
       workspaceId: {
         kind: 'string',
@@ -18581,7 +18592,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'size', 'uploadedAt', 'updatedAt'] as const,
         default: 'uploadedAt',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -18608,7 +18619,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId'] as const,
     pathParamDocs: { fileId: 'File identifier.' },
     responseMode: 'json',
-    summary: 'List File Versions',
+    summary: 'List file versions',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
       sortBy: {
@@ -18641,7 +18652,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/knowledge',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Knowledge Bases',
+    summary: 'List knowledge bases',
     query: {
       workspaceId: {
         kind: 'string',
@@ -18653,7 +18664,7 @@ export const V2_OPERATIONS = {
         values: ['active', 'archived'] as const,
         default: 'active',
         describe:
-          'Lifecycle scope: active or archived knowledge bases. Use Restore Knowledge Base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.',
+          'Lifecycle scope: active or archived knowledge bases. Use Restore knowledge base to recover archived entries. Folder paths resolve only active folders, so filtering by an archived folder returns no matches.',
       },
       folderPath: {
         kind: 'string',
@@ -18669,7 +18680,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'createdAt',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -18699,7 +18710,7 @@ export const V2_OPERATIONS = {
       documentId: 'Unique knowledge document identifier.',
     },
     responseMode: 'json',
-    summary: 'List Chunks',
+    summary: 'List chunks',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -18751,7 +18762,7 @@ export const V2_OPERATIONS = {
       connectorId: 'Connector selected for the operation.',
     },
     responseMode: 'json',
-    summary: 'List Knowledge Connector Documents',
+    summary: 'List knowledge connector documents',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -18782,7 +18793,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'List Knowledge Connectors',
+    summary: 'List knowledge connectors',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -18821,7 +18832,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'List Documents',
+    summary: 'List documents',
     query: {
       workspaceId: {
         kind: 'string',
@@ -18857,7 +18868,7 @@ export const V2_OPERATIONS = {
         ] as const,
         default: 'uploadedAt',
         describe:
-          'Field used to sort the result. Sorting by `filename` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `filename`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -18882,7 +18893,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/knowledge/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Folders',
+    summary: 'List folders',
     query: {
       workspaceId: {
         kind: 'string',
@@ -18903,7 +18914,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'name',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -18919,7 +18930,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'List Tags',
+    summary: 'List tags',
     query: {
       workspaceId: {
         kind: 'string',
@@ -18934,7 +18945,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'List Tag Usage',
+    summary: 'List tag usage',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -18949,7 +18960,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/logs',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Logs',
+    summary: 'List logs',
     query: {
       workspaceId: {
         kind: 'string',
@@ -19076,7 +19087,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/mcp-servers',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List MCP Servers',
+    summary: 'List MCP servers',
     query: {
       workspaceId: {
         kind: 'string',
@@ -19092,7 +19103,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'createdAt',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -19119,7 +19130,7 @@ export const V2_OPERATIONS = {
     pathParams: ['mcpServerId'] as const,
     pathParamDocs: { mcpServerId: 'Unique MCP server identifier.' },
     responseMode: 'json',
-    summary: 'List MCP Server Tools',
+    summary: 'List MCP server tools',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -19140,7 +19151,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization that owns the access requests.' },
     responseMode: 'json',
-    summary: 'List My Organization Access Requests',
+    summary: 'List my organization access requests',
     workspaceKeyUnsupported: true,
     query: {
       status: {
@@ -19179,7 +19190,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Workspace in which the acting user requests access.' },
     responseMode: 'json',
-    summary: 'List My Workspace Access Requests',
+    summary: 'List my workspace access requests',
     workspaceKeyUnsupported: true,
     query: {
       status: {
@@ -19218,7 +19229,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization that owns the access requests.' },
     responseMode: 'json',
-    summary: 'List Organization Access Requests',
+    summary: 'List organization access requests',
     workspaceKeyUnsupported: true,
     query: {
       status: {
@@ -19265,7 +19276,7 @@ export const V2_OPERATIONS = {
         'Organization whose single sign-on settings and verified domains are managed.',
     },
     responseMode: 'json',
-    summary: 'List Organization Domains',
+    summary: 'List organization domains',
     workspaceKeyUnsupported: true,
     query: {
       limit: {
@@ -19299,7 +19310,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization identifier.' },
     responseMode: 'json',
-    summary: 'List Organization Invitations',
+    summary: 'List organization invitations',
     workspaceKeyUnsupported: true,
     query: {
       search: {
@@ -19345,7 +19356,7 @@ export const V2_OPERATIONS = {
       invitationId: 'Invitation identifier.',
     },
     responseMode: 'json',
-    summary: 'List Organization Invitation Workspaces',
+    summary: 'List organization invitation workspaces',
     workspaceKeyUnsupported: true,
     query: {
       search: {
@@ -19357,7 +19368,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'id'] as const,
         default: 'name',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -19384,7 +19395,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization identifier.' },
     responseMode: 'json',
-    summary: 'List Organization Members',
+    summary: 'List organization members',
     workspaceKeyUnsupported: true,
     query: {
       search: {
@@ -19396,7 +19407,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'email', 'joinedAt'] as const,
         default: 'name',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -19422,7 +19433,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/organizations',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Organizations',
+    summary: 'List organizations',
     workspaceKeyUnsupported: true,
     query: {
       search: {
@@ -19434,7 +19445,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt'] as const,
         default: 'name',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -19461,7 +19472,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization identifier.' },
     responseMode: 'json',
-    summary: 'List Organization Usage Events',
+    summary: 'List organization usage events',
     workspaceKeyUnsupported: true,
     query: {
       preset: {
@@ -19531,7 +19542,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization identifier.' },
     responseMode: 'json',
-    summary: 'List Organization Workspaces',
+    summary: 'List organization workspaces',
     workspaceKeyUnsupported: true,
     query: {
       search: {
@@ -19543,7 +19554,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'id'] as const,
         default: 'name',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -19573,7 +19584,7 @@ export const V2_OPERATIONS = {
       groupId: 'Permission group identifier.',
     },
     responseMode: 'json',
-    summary: 'List Permission Group Members',
+    summary: 'List permission group members',
     workspaceKeyUnsupported: true,
     query: {
       sortBy: {
@@ -19607,7 +19618,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization that owns the permission groups.' },
     responseMode: 'json',
-    summary: 'List Permission Groups',
+    summary: 'List permission groups',
     workspaceKeyUnsupported: true,
     query: {
       search: {
@@ -19619,7 +19630,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'createdAt',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -19645,7 +19656,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/sandboxes',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Sandboxes',
+    summary: 'List sandboxes',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the sandbox.' },
       search: {
@@ -19657,7 +19668,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'name',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -19683,7 +19694,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/secrets',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Secrets',
+    summary: 'List secrets',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -19705,7 +19716,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'name',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -19731,7 +19742,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/selectors/list',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Selector Options',
+    summary: 'List selector options',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -19854,7 +19865,7 @@ export const V2_OPERATIONS = {
           'providers.ollamaEmbeddingModels',
           'providers.openrouterEmbeddingModels',
         ] as const,
-        describe: 'Registered selector key for discovering this field’s destination options.',
+        describe: 'Registered selector key from an import or sync preview, such as `gmail.labels`.',
       },
       context: {
         kind: 'object',
@@ -19865,12 +19876,13 @@ export const V2_OPERATIONS = {
       search: { kind: 'string', describe: 'Provider option search text.' },
       cursor: {
         kind: 'string',
-        describe: 'Opaque continuation cursor returned by the preceding page.',
+        describe:
+          'Cursor returned by the preceding page. Keep `workspaceId`, `selectorKey`, `context`, and `search` unchanged; only `limit` may change. Restart without a cursor after a changed-page 409.',
       },
       limit: {
         kind: 'integer',
         default: 50,
-        describe: 'Maximum number of items to return on one page.',
+        describe: 'Maximum options per page, from 1 to 100. Defaults to 50.',
       },
     },
   },
@@ -19883,7 +19895,7 @@ export const V2_OPERATIONS = {
         'Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.',
     },
     responseMode: 'json',
-    summary: 'List Skill Editors',
+    summary: 'List skill editors',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the skill.' },
       sortBy: {
@@ -19891,7 +19903,7 @@ export const V2_OPERATIONS = {
         values: ['email', 'name'] as const,
         default: 'email',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -19917,7 +19929,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/skills',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Skills',
+    summary: 'List skills',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the skill.' },
       search: {
@@ -19929,7 +19941,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'createdAt',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -19959,7 +19971,7 @@ export const V2_OPERATIONS = {
         'Organization whose single sign-on settings and verified domains are managed.',
     },
     responseMode: 'json',
-    summary: 'List SSO Providers',
+    summary: 'List SSO providers',
     workspaceKeyUnsupported: true,
     query: {
       limit: {
@@ -19993,7 +20005,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'List Run Dispatches',
+    summary: 'List run dispatches',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
     },
@@ -20003,7 +20015,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/tables/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Folders',
+    summary: 'List folders',
     query: {
       workspaceId: {
         kind: 'string',
@@ -20024,7 +20036,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'name',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -20040,7 +20052,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'List Rows',
+    summary: 'List rows',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
       limit: {
@@ -20057,7 +20069,7 @@ export const V2_OPERATIONS = {
       includeRunState: {
         kind: 'boolean',
         describe:
-          'Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it only when asked. Caps `limit` at 200.',
+          'Include per-workflow-group run outcomes on every row. Off by default. Caps `limit` at 200. Run state above 2 MiB returns `413`; request fewer rows or omit run state.',
       },
     },
   },
@@ -20066,7 +20078,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/tables',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Tables',
+    summary: 'List tables',
     query: {
       workspaceId: {
         kind: 'string',
@@ -20094,7 +20106,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'createdAt',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -20121,7 +20133,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'List Views',
+    summary: 'List views',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
     },
@@ -20131,7 +20143,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/tools',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Tools',
+    summary: 'List tools',
     query: {
       workspaceId: {
         kind: 'string',
@@ -20157,7 +20169,7 @@ export const V2_OPERATIONS = {
         values: ['id', 'name'] as const,
         default: 'id',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -20183,7 +20195,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workflows/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Workflow Folders',
+    summary: 'List workflow folders',
     query: {
       workspaceId: {
         kind: 'string',
@@ -20204,7 +20216,7 @@ export const V2_OPERATIONS = {
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'name',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -20220,7 +20232,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'List Workflow Groups',
+    summary: 'List workflow groups',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
     },
@@ -20230,20 +20242,20 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workflow-mcp-servers',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Workflow MCP Servers',
+    summary: 'List workflow MCP servers',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
         kind: 'string',
         required: true,
-        describe: 'Workspace whose published MCP servers to list.',
+        describe: 'Workspace whose workflow MCP servers to list.',
       },
       sortBy: {
         kind: 'enum',
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'createdAt',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -20270,7 +20282,7 @@ export const V2_OPERATIONS = {
     pathParams: ['serverId'] as const,
     pathParamDocs: { serverId: 'Unique workflow-MCP server identifier.' },
     responseMode: 'json',
-    summary: 'List Workflow MCP Tools',
+    summary: 'List workflow MCP tools',
     workspaceKeyUnsupported: true,
   },
   listWorkflowRuns: {
@@ -20279,7 +20291,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'List Workflow Runs',
+    summary: 'List workflow runs',
     query: {
       status: {
         kind: 'enum',
@@ -20322,7 +20334,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workflows',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Workflows',
+    summary: 'List workflows',
     query: {
       workspaceId: {
         kind: 'string',
@@ -20365,7 +20377,7 @@ export const V2_OPERATIONS = {
         values: ['position', 'name', 'createdAt', 'updatedAt', 'runCount'] as const,
         default: 'position',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -20381,7 +20393,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'List Workflow Versions',
+    summary: 'List workflow versions',
     query: {
       limit: {
         kind: 'integer',
@@ -20402,7 +20414,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'List Workspace Fork Children',
+    summary: 'List workspace fork children',
     workspaceKeyUnsupported: true,
     query: {
       limit: {
@@ -20436,7 +20448,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'List Workspace Fork Resources',
+    summary: 'List workspace fork resources',
     workspaceKeyUnsupported: true,
     query: {
       limit: {
@@ -20462,7 +20474,7 @@ export const V2_OPERATIONS = {
           'mcpServers',
           'workflowMcpServers',
         ] as const,
-        describe: 'Resource or operation kind.',
+        describe: 'Kind of source resource to list for copy selection.',
       },
       sortBy: {
         kind: 'enum',
@@ -20484,7 +20496,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Workspace to retrieve.' },
     responseMode: 'json',
-    summary: 'List Workspace Members',
+    summary: 'List workspace members',
     query: {
       limit: {
         kind: 'integer',
@@ -20505,7 +20517,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'List Workspace Operations',
+    summary: 'List workspace operations',
     query: {
       limit: {
         kind: 'integer',
@@ -20520,7 +20532,8 @@ export const V2_OPERATIONS = {
       },
       requestId: {
         kind: 'string',
-        describe: 'Stable client request ID for reconciliation and identical retries.',
+        describe:
+          'Find an uncertain mutation by the original client request ID; keep the same filter while paging.',
       },
     },
   },
@@ -20529,14 +20542,14 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workspaces',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'List Workspaces',
+    summary: 'List workspaces',
     query: {
       sortBy: {
         kind: 'enum',
         values: ['name', 'createdAt', 'updatedAt'] as const,
         default: 'createdAt',
         describe:
-          'Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order.',
+          'Field used to sort the result. Do not rely on case-insensitive ordering when sorting by `name`.',
       },
       sortOrder: {
         kind: 'enum',
@@ -20562,7 +20575,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files/move',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Move Files',
+    summary: 'Move files',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace containing the files.' },
       fileIds: { kind: 'array', required: true, describe: 'File identifiers to update.' },
@@ -20577,7 +20590,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/tables/move',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Move Tables and Folders',
+    summary: 'Move tables and folders',
     body: {
       workspaceId: {
         kind: 'string',
@@ -20597,7 +20610,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workflows/move',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Move Workflows',
+    summary: 'Move workflows',
     body: {
       workspaceId: {
         kind: 'string',
@@ -20625,7 +20638,7 @@ export const V2_OPERATIONS = {
       requestId: 'Access request identifier.',
     },
     responseMode: 'json',
-    summary: 'Preview Organization Access Request',
+    summary: 'Preview organization access request',
     workspaceKeyUnsupported: true,
   },
   previewWorkflowImport: {
@@ -20633,7 +20646,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workflows/import/preview',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Preview Workflow Import',
+    summary: 'Preview workflow import',
     body: {
       workspaceId: {
         kind: 'string',
@@ -20654,7 +20667,7 @@ export const V2_OPERATIONS = {
       description: { kind: 'string', describe: 'Override for the imported workflow description.' },
       mappings: {
         kind: 'array',
-        describe: 'Mappings keyed by resource type and source identifier.',
+        describe: 'Mapping entries addressed by resource kind and source identifier.',
       },
       bindings: {
         kind: 'array',
@@ -20663,7 +20676,7 @@ export const V2_OPERATIONS = {
       dependentValues: {
         kind: 'array',
         describe:
-          'Destination-dependent choices keyed by source workflow, block, and field identities.',
+          'Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated.',
       },
     },
   },
@@ -20673,7 +20686,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Preview Workspace Fork',
+    summary: 'Preview workspace fork',
     workspaceKeyUnsupported: true,
     body: {
       name: { kind: 'string', describe: 'Display name of the workflow or workspace.' },
@@ -20690,7 +20703,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Preview Workspace Pull',
+    summary: 'Preview workspace pull',
     workspaceKeyUnsupported: true,
     body: {
       otherWorkspaceId: {
@@ -20700,12 +20713,13 @@ export const V2_OPERATIONS = {
       },
       mappings: {
         kind: 'array',
-        describe: 'Mappings keyed by resource type and source identifier.',
+        describe:
+          'Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync.',
       },
       dependentValues: {
         kind: 'array',
         describe:
-          'Destination-dependent choices keyed by source workflow, block, and field identities.',
+          'Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them.',
       },
       copyResources: {
         kind: 'object',
@@ -20729,7 +20743,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Preview Workspace Push',
+    summary: 'Preview workspace push',
     workspaceKeyUnsupported: true,
     body: {
       otherWorkspaceId: {
@@ -20739,12 +20753,13 @@ export const V2_OPERATIONS = {
       },
       mappings: {
         kind: 'array',
-        describe: 'Mappings keyed by resource type and source identifier.',
+        describe:
+          'Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync.',
       },
       dependentValues: {
         kind: 'array',
         describe:
-          'Destination-dependent choices keyed by source workflow, block, and field identities.',
+          'Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them.',
       },
       copyResources: {
         kind: 'object',
@@ -20768,7 +20783,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Pull Workspace',
+    summary: 'Pull workspace',
     workspaceKeyUnsupported: true,
     body: {
       otherWorkspaceId: {
@@ -20778,12 +20793,13 @@ export const V2_OPERATIONS = {
       },
       mappings: {
         kind: 'array',
-        describe: 'Mappings keyed by resource type and source identifier.',
+        describe:
+          'Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync.',
       },
       dependentValues: {
         kind: 'array',
         describe:
-          'Destination-dependent choices keyed by source workflow, block, and field identities.',
+          'Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them.',
       },
       copyResources: {
         kind: 'object',
@@ -20802,17 +20818,20 @@ export const V2_OPERATIONS = {
       requestId: {
         kind: 'string',
         required: true,
-        describe: 'Stable client request ID for reconciliation and identical retries.',
+        describe:
+          'Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation.',
       },
       previewFingerprint: {
         kind: 'string',
         required: true,
-        describe: 'Fingerprint of the reviewed preview and its choices.',
+        describe:
+          'Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value.',
       },
       confirm: {
         kind: 'boolean',
         required: true,
-        describe: 'Explicit acknowledgement that sync replaces target workflows.',
+        describe:
+          'Confirm replacement of mapped target drafts and archival of mapped targets whose sources were deleted or archived.',
       },
     },
   },
@@ -20822,7 +20841,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Push Workspace',
+    summary: 'Push workspace',
     workspaceKeyUnsupported: true,
     body: {
       otherWorkspaceId: {
@@ -20832,12 +20851,13 @@ export const V2_OPERATIONS = {
       },
       mappings: {
         kind: 'array',
-        describe: 'Mappings keyed by resource type and source identifier.',
+        describe:
+          'Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync.',
       },
       dependentValues: {
         kind: 'array',
         describe:
-          'Destination-dependent choices keyed by source workflow, block, and field identities.',
+          'Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them.',
       },
       copyResources: {
         kind: 'object',
@@ -20856,17 +20876,20 @@ export const V2_OPERATIONS = {
       requestId: {
         kind: 'string',
         required: true,
-        describe: 'Stable client request ID for reconciliation and identical retries.',
+        describe:
+          'Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation.',
       },
       previewFingerprint: {
         kind: 'string',
         required: true,
-        describe: 'Fingerprint of the reviewed preview and its choices.',
+        describe:
+          'Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value.',
       },
       confirm: {
         kind: 'boolean',
         required: true,
-        describe: 'Explicit acknowledgement that sync replaces target workflows.',
+        describe:
+          'Confirm replacement of mapped target drafts and archival of mapped targets whose sources were deleted or archived.',
       },
     },
   },
@@ -20876,7 +20899,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Query Rows',
+    summary: 'Query rows',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       predicate: {
@@ -20887,14 +20910,15 @@ export const V2_OPERATIONS = {
       sort: { kind: 'array', describe: 'Ordered table-row sort specification.' },
       limit: {
         kind: 'integer',
-        describe: 'Maximum rows to return; zero requests an unbounded result.',
+        describe:
+          'Maximum rows per page. `0` requests all matches, subject to a 5 MiB row-data ceiling; larger results return `400` with `TABLE_QUERY_RESULT_TOO_LARGE`. Use paged queries or an export for larger results.',
       },
       cursor: { kind: 'string', describe: 'Opaque cursor returned by the previous query page.' },
       includeRunState: {
         kind: 'boolean',
         default: false,
         describe:
-          'Include per-workflow-group run state on every returned row. Off by default: run state is a separate sidecar read and its `blockErrors` are unbounded, so a full page carries it only when asked. Incompatible with `limit: 0`, and caps `limit` at 200.',
+          'Include per-workflow-group run outcomes on every row. Off by default. Incompatible with `limit: 0`; caps `limit` at 200. Run state above 2 MiB returns `413`; request fewer rows or omit run state.',
       },
     },
   },
@@ -20904,7 +20928,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Count Rows',
+    summary: 'Count rows',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       predicate: {
@@ -20923,7 +20947,7 @@ export const V2_OPERATIONS = {
         'File identifier, or the file’s VFS path: `files/<folder>/<name>`, or `uploads/<name>` for a Chat upload.',
     },
     responseMode: 'json',
-    summary: 'Read File Text',
+    summary: 'Read file text',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
       maxBytes: {
@@ -20948,7 +20972,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId', 'version'] as const,
     pathParamDocs: { fileId: 'File identifier.', version: 'Version number.' },
     responseMode: 'json',
-    summary: 'Read File Version Text',
+    summary: 'Read file version text',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
       maxBytes: {
@@ -20972,7 +20996,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Rename or Move Folder',
+    summary: 'Rename or move folder',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace containing the folder.' },
       path: { kind: 'string', required: true, describe: 'Current folder path.' },
@@ -20989,7 +21013,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/knowledge/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Rename or Move Folder',
+    summary: 'Rename or move folder',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace containing the folder.' },
       path: { kind: 'string', required: true, describe: 'Current folder path.' },
@@ -21006,7 +21030,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/tables/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Rename or Move Folder',
+    summary: 'Rename or move folder',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace containing the folder.' },
       path: { kind: 'string', required: true, describe: 'Current folder path.' },
@@ -21023,7 +21047,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/workflows/folders',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Rename or Move Workflow Folder',
+    summary: 'Rename or move workflow folder',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace containing the folder.' },
       path: { kind: 'string', required: true, describe: 'Current folder path.' },
@@ -21044,7 +21068,7 @@ export const V2_OPERATIONS = {
       userId: 'User whose explicit grant will be revoked.',
     },
     responseMode: 'json',
-    summary: 'Remove Credential Member',
+    summary: 'Remove credential member',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -21064,7 +21088,7 @@ export const V2_OPERATIONS = {
       domainId: 'Domain claim owned by this organization.',
     },
     responseMode: 'json',
-    summary: 'Remove Organization Domain',
+    summary: 'Remove organization domain',
     workspaceKeyUnsupported: true,
   },
   removeOrganizationMember: {
@@ -21076,7 +21100,7 @@ export const V2_OPERATIONS = {
       userId: 'User identifier of the organization member.',
     },
     responseMode: 'json',
-    summary: 'Remove Organization Member',
+    summary: 'Remove organization member',
     workspaceKeyUnsupported: true,
   },
   removePermissionGroupMember: {
@@ -21089,7 +21113,7 @@ export const V2_OPERATIONS = {
       userId: 'User identifier of the member to remove.',
     },
     responseMode: 'json',
-    summary: 'Remove Permission Group Member',
+    summary: 'Remove permission group member',
     workspaceKeyUnsupported: true,
   },
   renameFile: {
@@ -21098,7 +21122,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId'] as const,
     pathParamDocs: { fileId: 'File identifier.' },
     responseMode: 'json',
-    summary: 'Rename File',
+    summary: 'Rename file',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
       name: { kind: 'string', required: true, describe: 'New file name, including its extension.' },
@@ -21110,7 +21134,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Create or Replace Workflow Chat Deployment',
+    summary: 'Create or replace workflow chat deployment',
     workspaceKeyUnsupported: true,
     body: {
       identifier: {
@@ -21125,7 +21149,8 @@ export const V2_OPERATIONS = {
       },
       customizations: {
         kind: 'object',
-        describe: 'Presentation overrides. Omitted fields take platform defaults.',
+        describe:
+          'Presentation overrides. Omitted `primaryColor` and `welcomeMessage` use platform defaults; an omitted or empty `imageUrl` keeps the existing avatar. An empty `welcomeMessage` keeps the existing message.',
       },
       authType: {
         kind: 'enum',
@@ -21166,7 +21191,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Replace Workflow State',
+    summary: 'Replace workflow state',
     workspaceKeyUnsupported: true,
     query: {
       dryRun: {
@@ -21201,7 +21226,7 @@ export const V2_OPERATIONS = {
       invitationId: 'Invitation identifier.',
     },
     responseMode: 'json',
-    summary: 'Resend Organization Invitation',
+    summary: 'Resend organization invitation',
     workspaceKeyUnsupported: true,
   },
   resolveOrganizationAccessRequest: {
@@ -21213,7 +21238,7 @@ export const V2_OPERATIONS = {
       requestId: 'Access request identifier.',
     },
     responseMode: 'json',
-    summary: 'Resolve Organization Access Request',
+    summary: 'Resolve organization access request',
     workspaceKeyUnsupported: true,
     body: {
       action: {
@@ -21281,7 +21306,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId'] as const,
     pathParamDocs: { fileId: 'File identifier.' },
     responseMode: 'json',
-    summary: 'Restore File',
+    summary: 'Restore file',
     body: {
       workspaceId: {
         kind: 'string',
@@ -21295,7 +21320,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files/folders/restore',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Restore Folder',
+    summary: 'Restore folder',
     body: {
       workspaceId: {
         kind: 'string',
@@ -21316,7 +21341,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Restore Knowledge Base',
+    summary: 'Restore knowledge base',
     body: {
       workspaceId: {
         kind: 'string',
@@ -21331,7 +21356,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Restore Table',
+    summary: 'Restore table',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
     },
@@ -21341,7 +21366,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/tables/folders/restore',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Restore Folder',
+    summary: 'Restore folder',
     body: {
       workspaceId: {
         kind: 'string',
@@ -21361,7 +21386,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Restore Workflow',
+    summary: 'Restore workflow',
   },
   resumeWorkflow: {
     method: 'POST',
@@ -21372,7 +21397,7 @@ export const V2_OPERATIONS = {
       runId: 'Unique workflow run identifier.',
     },
     responseMode: 'json',
-    summary: 'Resume Workflow Run',
+    summary: 'Resume workflow run',
     body: {
       contextId: {
         kind: 'string',
@@ -21388,7 +21413,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId', 'version'] as const,
     pathParamDocs: { fileId: 'File identifier.', version: 'Version number.' },
     responseMode: 'json',
-    summary: 'Revert File Version',
+    summary: 'Revert file version',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
       expectedCurrentVersion: {
@@ -21399,7 +21424,7 @@ export const V2_OPERATIONS = {
       expectedRevision: {
         kind: 'string',
         describe:
-          'Revert only while the file still holds the content this revision names, as returned by Get File Metadata or an earlier write; otherwise the request fails with `409`. Unlike a version number, it also catches edits that folded into the current version.',
+          'Revert only while the file still holds the content this revision names, as returned by Get file metadata or an earlier write; otherwise the request fails with `409`. Unlike a version number, it also catches edits that folded into the current version.',
       },
     },
   },
@@ -21412,7 +21437,7 @@ export const V2_OPERATIONS = {
       version: 'Numeric deployment version, or `active` for the currently live version.',
     },
     responseMode: 'json',
-    summary: 'Revert Workflow To Version',
+    summary: 'Revert workflow to version',
     workspaceKeyUnsupported: true,
   },
   revokeOrganizationInvitation: {
@@ -21424,7 +21449,7 @@ export const V2_OPERATIONS = {
       invitationId: 'Invitation identifier.',
     },
     responseMode: 'json',
-    summary: 'Revoke Organization Invitation',
+    summary: 'Revoke organization invitation',
     workspaceKeyUnsupported: true,
   },
   revokeSkillEditor: {
@@ -21436,7 +21461,7 @@ export const V2_OPERATIONS = {
         'Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.',
     },
     responseMode: 'json',
-    summary: 'Revoke Skill Editor',
+    summary: 'Revoke skill editor',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the skill.' },
@@ -21453,7 +21478,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Rollback Workflow',
+    summary: 'Rollback workflow',
     workspaceKeyUnsupported: true,
     body: {
       version: {
@@ -21468,7 +21493,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Rollback Workspace Fork',
+    summary: 'Rollback workspace fork',
     workspaceKeyUnsupported: true,
     body: {
       otherWorkspaceId: {
@@ -21488,7 +21513,7 @@ export const V2_OPERATIONS = {
       groupId: 'Workflow or enrichment group to run.',
     },
     responseMode: 'json',
-    summary: 'Run Enrichment For One Row',
+    summary: 'Run enrichment for one row',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
     },
@@ -21502,7 +21527,7 @@ export const V2_OPERATIONS = {
         'Organization whose single sign-on settings and verified domains are managed.',
     },
     responseMode: 'json',
-    summary: 'Save SSO Provider',
+    summary: 'Save SSO provider',
     workspaceKeyUnsupported: true,
     body: {
       providerType: {
@@ -21777,7 +21802,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/files/search',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Search File Content',
+    summary: 'Search file content',
     query: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace to search.' },
       query: {
@@ -21823,7 +21848,7 @@ export const V2_OPERATIONS = {
     path: '/api/v2/knowledge/search',
     pathParams: [] as const,
     responseMode: 'json',
-    summary: 'Search Knowledge',
+    summary: 'Search knowledge',
     body: {
       workspaceId: {
         kind: 'string',
@@ -21833,7 +21858,8 @@ export const V2_OPERATIONS = {
       knowledgeBaseIds: {
         kind: 'unknown',
         required: true,
-        describe: 'One knowledge base identifier or an array of up to 20 identifiers.',
+        describe:
+          'One knowledge base ID or an array of up to 20 IDs. Query searches require the same embedding model and dimensions across all selected bases; search incompatible bases separately. Tag-only searches do not require this.',
       },
       query: {
         kind: 'string',
@@ -21854,12 +21880,12 @@ export const V2_OPERATIONS = {
       searchMode: {
         kind: 'enum',
         describe:
-          'Retrieval strategy: vector is semantic-only, while hybrid also runs full-text search.',
+          'Retrieval strategy: `vector` uses semantic search; `hybrid` also runs full-text search. Omit to use the workspace policy.',
       },
       rerankerEnabled: {
         kind: 'boolean',
         describe:
-          'Re-order retrieved chunks with a reranking model before truncating to `topK`. Ignored for a tag-only search, and billed as an additional search unit. Reranking is best-effort — a provider failure falls back to vector ordering, so check `rerankerStatus` on the response.',
+          'Reorder retrieved chunks with a reranking model before truncating to `topK`. Ignored for tag-only searches. A completed reranking call adds a search unit. If reranking is unavailable, results keep their retrieval order; check `rerankerStatus`.',
       },
       rerankerModel: {
         kind: 'enum',
@@ -21881,7 +21907,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Search Rows',
+    summary: 'Search rows',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       q: { kind: 'string', required: true, describe: 'Case-insensitive cell substring to find.' },
@@ -21903,7 +21929,7 @@ export const V2_OPERATIONS = {
       providerId: 'Identity provider identifier.',
     },
     responseMode: 'json',
-    summary: 'Set Primary SSO Provider',
+    summary: 'Set primary SSO provider',
     workspaceKeyUnsupported: true,
   },
   setSecret: {
@@ -21912,7 +21938,7 @@ export const V2_OPERATIONS = {
     pathParams: ['name'] as const,
     pathParamDocs: { name: 'Secret to create or replace.' },
     responseMode: 'json',
-    summary: 'Set Secret',
+    summary: 'Set secret',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -21931,7 +21957,7 @@ export const V2_OPERATIONS = {
       value: {
         kind: 'string',
         describe:
-          'Write-only secret value. It is never returned. Omit it on a workspace secret to change description or unredacted alone, leaving the stored value untouched; the secret must already exist. Always required for a personal secret, which carries no other writable field.',
+          'Secret value, omitted from the Set secret response. For an existing workspace secret, omit it to change only `description` or `unredacted`. Personal secrets always require a value and accept no writable metadata.',
       },
       description: {
         kind: 'string',
@@ -21954,7 +21980,7 @@ export const V2_OPERATIONS = {
       connectorId: 'Connector selected for the operation.',
     },
     responseMode: 'json',
-    summary: 'Sync Knowledge Connector',
+    summary: 'Sync knowledge connector',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -21978,7 +22004,7 @@ export const V2_OPERATIONS = {
       exportId: 'Unique table-export identifier.',
     },
     responseMode: 'json',
-    summary: 'Download Table Export',
+    summary: 'Download table export',
     query: {
       workspaceId: {
         kind: 'string',
@@ -21993,7 +22019,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Undeploy Workflow',
+    summary: 'Undeploy workflow',
     workspaceKeyUnsupported: true,
   },
   undeployWorkflowMcpTool: {
@@ -22002,10 +22028,10 @@ export const V2_OPERATIONS = {
     pathParams: ['serverId', 'workflowId'] as const,
     pathParamDocs: {
       serverId: 'Unique workflow-MCP server identifier.',
-      workflowId: 'Workflow published as a tool on this server.',
+      workflowId: 'Workflow registered as an MCP tool on this server.',
     },
     responseMode: 'json',
-    summary: 'Unpublish Workflow MCP Tool',
+    summary: 'Undeploy workflow MCP tool',
     workspaceKeyUnsupported: true,
   },
   unlinkWorkspaceFork: {
@@ -22014,7 +22040,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Unlink Workspace Fork',
+    summary: 'Unlink workspace fork',
     workspaceKeyUnsupported: true,
     body: {
       otherWorkspaceId: {
@@ -22030,7 +22056,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId'] as const,
     pathParamDocs: { fileId: 'File identifier.' },
     responseMode: 'json',
-    summary: 'Unzip File',
+    summary: 'Unzip file',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the archive.' },
     },
@@ -22041,7 +22067,7 @@ export const V2_OPERATIONS = {
     pathParams: ['credentialId'] as const,
     pathParamDocs: { credentialId: 'Credential to update.' },
     responseMode: 'json',
-    summary: 'Update Credential',
+    summary: 'Update credential',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -22096,7 +22122,7 @@ export const V2_OPERATIONS = {
     pathParams: ['customToolId'] as const,
     pathParamDocs: { customToolId: 'Unique custom tool identifier.' },
     responseMode: 'json',
-    summary: 'Update Custom Tool',
+    summary: 'Update custom tool',
     body: {
       workspaceId: {
         kind: 'string',
@@ -22114,14 +22140,14 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId'] as const,
     pathParamDocs: { fileId: 'File identifier.' },
     responseMode: 'json',
-    summary: 'Replace File Content',
+    summary: 'Replace file content',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
       content: {
         kind: 'string',
         required: true,
         describe:
-          'Complete replacement content for the file. The 70,000,000-character bound guards the JSON envelope; the decoded bytes must be at most 50 MiB, and a longer base64 payload is rejected with `413`.',
+          'Complete replacement content for the file. The complete JSON request is capped at 10 MiB, including UTF-8 encoding, escaping, base64, and the envelope. The separate decoded-file limit is 50 MiB. Small patches can edit a larger stored text file without sending its full content.',
       },
       encoding: {
         kind: 'enum',
@@ -22132,7 +22158,7 @@ export const V2_OPERATIONS = {
       expectedRevision: {
         kind: 'string',
         describe:
-          'Revision from Get File Metadata or an earlier write; the request is refused with `409` when the content moved on.',
+          'Revision from Get file metadata or an earlier write; the request is refused with `409` when the content moved on.',
       },
     },
   },
@@ -22142,7 +22168,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Update Knowledge Base',
+    summary: 'Update knowledge base',
     body: {
       workspaceId: {
         kind: 'string',
@@ -22165,7 +22191,7 @@ export const V2_OPERATIONS = {
       chunkId: 'Unique chunk identifier.',
     },
     responseMode: 'json',
-    summary: 'Update Chunk',
+    summary: 'Update chunk',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -22193,7 +22219,7 @@ export const V2_OPERATIONS = {
       connectorId: 'Connector selected for the operation.',
     },
     responseMode: 'json',
-    summary: 'Update Knowledge Connector',
+    summary: 'Update knowledge connector',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -22226,7 +22252,7 @@ export const V2_OPERATIONS = {
       connectorId: 'Connector selected for the operation.',
     },
     responseMode: 'json',
-    summary: 'Update Knowledge Connector Documents',
+    summary: 'Update knowledge connector documents',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -22256,7 +22282,7 @@ export const V2_OPERATIONS = {
       documentId: 'Unique knowledge document identifier.',
     },
     responseMode: 'json',
-    summary: 'Update Document',
+    summary: 'Update document',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -22302,7 +22328,7 @@ export const V2_OPERATIONS = {
       tagId: 'Unique tag definition identifier.',
     },
     responseMode: 'json',
-    summary: 'Update Tag',
+    summary: 'Update tag',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: {
@@ -22324,7 +22350,7 @@ export const V2_OPERATIONS = {
     pathParams: ['mcpServerId'] as const,
     pathParamDocs: { mcpServerId: 'Unique MCP server identifier.' },
     responseMode: 'json',
-    summary: 'Update MCP Server',
+    summary: 'Update MCP server',
     body: {
       workspaceId: {
         kind: 'string',
@@ -22348,7 +22374,7 @@ export const V2_OPERATIONS = {
         kind: 'enum',
         values: ['none', 'headers', 'oauth'] as const,
         describe:
-          'Authentication method. When omitted, and no `headers` are sent, registration probes the endpoint once to classify it, falling back to `headers` when the probe fails or the server does not advertise OAuth. A server publishing RFC 9728 metadata is therefore stored as `oauth`, and headers configured afterwards will not authenticate — send this field explicitly to pin the method.',
+          'Authentication method. On creation, omission without `headers` probes once: an OAuth challenge selects `oauth`, an unauthenticated success selects `none`, and other outcomes fall back to `headers`. An OAuth client ID selects `oauth` when the method is omitted. Set explicitly to use headers with a server advertising OAuth; adding headers later does not change the saved method.',
       },
       headers: {
         kind: 'object',
@@ -22388,7 +22414,7 @@ export const V2_OPERATIONS = {
     pathParams: ['organizationId'] as const,
     pathParamDocs: { organizationId: 'Organization that owns the access requests.' },
     responseMode: 'json',
-    summary: 'Update Organization Access Request Settings',
+    summary: 'Update organization access request settings',
     workspaceKeyUnsupported: true,
     body: {
       allowRequests: {
@@ -22408,7 +22434,7 @@ export const V2_OPERATIONS = {
       userId: 'User identifier of the organization member.',
     },
     responseMode: 'json',
-    summary: 'Update Organization Member',
+    summary: 'Update organization member',
     workspaceKeyUnsupported: true,
     body: {
       role: {
@@ -22429,7 +22455,7 @@ export const V2_OPERATIONS = {
         'User ID of an organization member or external collaborator with workspace access in this organization. Use List Organization Members or List Workspace Members to find it.',
     },
     responseMode: 'json',
-    summary: 'Update Organization Member Credit Limit',
+    summary: 'Update organization member credit limit',
     workspaceKeyUnsupported: true,
     body: {
       creditLimit: {
@@ -22450,7 +22476,7 @@ export const V2_OPERATIONS = {
       groupId: 'Permission group identifier.',
     },
     responseMode: 'json',
-    summary: 'Update Permission Group',
+    summary: 'Update permission group',
     workspaceKeyUnsupported: true,
     body: {
       name: { kind: 'string', describe: 'Group name, unique within the organization.' },
@@ -22482,7 +22508,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Update Rows by Filter',
+    summary: 'Update rows by filter',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       filter: {
@@ -22505,7 +22531,7 @@ export const V2_OPERATIONS = {
     pathParams: ['sandboxId'] as const,
     pathParamDocs: { sandboxId: 'Unique sandbox identifier.' },
     responseMode: 'json',
-    summary: 'Update Sandbox',
+    summary: 'Update sandbox',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the sandbox.' },
@@ -22542,7 +22568,7 @@ export const V2_OPERATIONS = {
         'Unique skill identifier. A built-in skill is `builtin-` followed by its name, for example `builtin-research`.',
     },
     responseMode: 'json',
-    summary: 'Update Skill',
+    summary: 'Update skill',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the skill.' },
@@ -22560,7 +22586,7 @@ export const V2_OPERATIONS = {
         'Organization whose single sign-on settings and verified domains are managed.',
     },
     responseMode: 'json',
-    summary: 'Update SSO Policy',
+    summary: 'Update SSO policy',
     workspaceKeyUnsupported: true,
     body: {
       requireSso: {
@@ -22576,7 +22602,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Update Table',
+    summary: 'Update table',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       name: { kind: 'string', describe: 'Replacement table name.' },
@@ -22597,7 +22623,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Update Column',
+    summary: 'Update column',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
       columnName: {
@@ -22614,7 +22640,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId', 'rowId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.', rowId: 'Unique table row identifier.' },
     responseMode: 'json',
-    summary: 'Update Row',
+    summary: 'Update row',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       data: {
@@ -22630,7 +22656,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId', 'viewId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.', viewId: 'Unique saved-view identifier.' },
     responseMode: 'json',
-    summary: 'Update View',
+    summary: 'Update view',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the table.' },
       name: { kind: 'string', describe: 'Replacement saved-view display name.' },
@@ -22651,7 +22677,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Update Workflow',
+    summary: 'Update workflow',
     body: {
       name: { kind: 'string', describe: 'Replacement workflow name.' },
       description: {
@@ -22670,7 +22696,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Update Workflow Group',
+    summary: 'Update workflow group',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       groupId: { kind: 'string', required: true, describe: 'Workflow group to update.' },
@@ -22701,7 +22727,7 @@ export const V2_OPERATIONS = {
     pathParams: ['serverId'] as const,
     pathParamDocs: { serverId: 'Unique workflow-MCP server identifier.' },
     responseMode: 'json',
-    summary: 'Update Workflow MCP Server',
+    summary: 'Update workflow MCP server',
     workspaceKeyUnsupported: true,
     body: {
       name: { kind: 'string', describe: 'Server display name, shown to connecting MCP clients.' },
@@ -22718,7 +22744,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workflowId'] as const,
     pathParamDocs: { workflowId: 'Unique workflow identifier.' },
     responseMode: 'json',
-    summary: 'Update Workflow Public API Access',
+    summary: 'Update workflow public API access',
     workspaceKeyUnsupported: true,
     body: {
       isPublicApi: {
@@ -22738,7 +22764,7 @@ export const V2_OPERATIONS = {
       version: 'Numeric deployment version.',
     },
     responseMode: 'json',
-    summary: 'Update Workflow Version',
+    summary: 'Update workflow version',
     body: {
       name: { kind: 'string', describe: 'New label for the deployment version.' },
       description: {
@@ -22753,7 +22779,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Update Workspace Fork Exclusions',
+    summary: 'Update workspace fork exclusions',
     workspaceKeyUnsupported: true,
     body: {
       workflowIds: {
@@ -22774,7 +22800,7 @@ export const V2_OPERATIONS = {
     pathParams: ['workspaceId'] as const,
     pathParamDocs: { workspaceId: 'Explicit current workspace scope.' },
     responseMode: 'json',
-    summary: 'Update Workspace Fork Mappings',
+    summary: 'Update workspace fork mappings',
     workspaceKeyUnsupported: true,
     body: {
       otherWorkspaceId: {
@@ -22792,7 +22818,8 @@ export const V2_OPERATIONS = {
       mappings: {
         kind: 'array',
         required: true,
-        describe: 'Mappings keyed by resource type and source identifier.',
+        describe:
+          'Mapping entries addressed by resource type and `sourceId`. `targetId: null` clears a mapping.',
       },
     },
   },
@@ -22802,7 +22829,7 @@ export const V2_OPERATIONS = {
     pathParams: ['knowledgeBaseId'] as const,
     pathParamDocs: { knowledgeBaseId: 'Unique knowledge base identifier.' },
     responseMode: 'json',
-    summary: 'Upload Document',
+    summary: 'Upload document',
     query: {
       workspaceId: {
         kind: 'string',
@@ -22817,7 +22844,7 @@ export const V2_OPERATIONS = {
     pathParams: ['credentialId'] as const,
     pathParamDocs: { credentialId: 'Credential whose sharing grants are managed.' },
     responseMode: 'json',
-    summary: 'Upsert Credential Member',
+    summary: 'Upsert credential member',
     workspaceKeyUnsupported: true,
     query: {
       workspaceId: {
@@ -22846,7 +22873,7 @@ export const V2_OPERATIONS = {
     pathParams: ['fileId'] as const,
     pathParamDocs: { fileId: 'File identifier.' },
     responseMode: 'json',
-    summary: 'Enable or Disable File Share',
+    summary: 'Enable or disable file share',
     workspaceKeyUnsupported: true,
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Workspace that owns the file.' },
@@ -22880,7 +22907,7 @@ export const V2_OPERATIONS = {
     pathParams: ['tableId'] as const,
     pathParamDocs: { tableId: 'Unique table identifier.' },
     responseMode: 'json',
-    summary: 'Upsert Row',
+    summary: 'Upsert row',
     body: {
       workspaceId: { kind: 'string', required: true, describe: 'Unique workspace identifier.' },
       data: {
@@ -22902,7 +22929,7 @@ export const V2_OPERATIONS = {
       domainId: 'Domain claim owned by this organization.',
     },
     responseMode: 'json',
-    summary: 'Verify Organization Domain',
+    summary: 'Verify organization domain',
     workspaceKeyUnsupported: true,
   },
 } as const
diff --git a/packages/sim-cli/src/runtime/options.ts b/packages/sim-cli/src/runtime/options.ts
index fa46d20bf55..fe6d5b7ba07 100644
--- a/packages/sim-cli/src/runtime/options.ts
+++ b/packages/sim-cli/src/runtime/options.ts
@@ -162,7 +162,7 @@ function addFieldOption(
     return
   }
 
-  const documented = `${describeField(flag, descriptor, name, field)}${
+  const fieldDescription = `${describeField(flag, descriptor, name, field)}${
     capsAFilter &&
     field === 'limit' &&
     (descriptor.kind === 'number' || descriptor.kind === 'integer')
@@ -170,6 +170,12 @@ function addFieldOption(
       : ''
   }`
 
+  const effectiveDefault = flag.requestDefault ?? descriptor.default
+  const documented =
+    effectiveDefault !== undefined && !/\bdefault(?:s|ing)?\b/i.test(fieldDescription)
+      ? `${fieldDescription}${/[.!?]$/.test(fieldDescription) ? '' : '.'} Defaults to ${JSON.stringify(effectiveDefault)}.`
+      : fieldDescription
+
   if (descriptor.kind === 'boolean' || flag.boolean) {
     const booleanDoc = withoutWireVocabulary(documented)
     if (descriptor.required) {
diff --git a/scripts/format-generated-source.ts b/scripts/format-generated-source.ts
index b0ff2f24da2..4dd093b1508 100644
--- a/scripts/format-generated-source.ts
+++ b/scripts/format-generated-source.ts
@@ -2,6 +2,8 @@ import { spawnSync } from 'node:child_process'
 import { extname, join } from 'node:path'
 import { localBin } from './local-bin'
 
+const MAX_FORMATTED_SOURCE_BYTES = 16 * 1024 * 1024
+
 export function formatGeneratedSource(source: string, stdinFilePath: string, cwd: string): string {
   // biome.json excludes the generated output dirs, and biome refuses to format a
   // stdin whose declared path is excluded — so declare a neutral path instead;
@@ -13,19 +15,28 @@ export function formatGeneratedSource(source: string, stdinFilePath: string, cwd
     'scripts',
     `.generated-format-buffer${extname(stdinFilePath) || '.ts'}`
   )
-  const result = spawnSync(localBin('biome'), ['format', '--stdin-file-path', neutralPath], {
-    cwd,
-    encoding: 'utf8',
-    input: source,
-  })
+  const result = spawnSync(
+    localBin('biome'),
+    ['format', '--stdin-file-path', neutralPath, `--files-max-size=${MAX_FORMATTED_SOURCE_BYTES}`],
+    {
+      cwd,
+      encoding: 'utf8',
+      input: source,
+      maxBuffer: MAX_FORMATTED_SOURCE_BYTES,
+    }
+  )
 
-  if (result.status !== 0) {
+  if (result.error || result.status !== 0) {
     throw new Error(
       `Failed to format generated source for ${neutralPath}:\n${
-        result.stderr || result.stdout || 'unknown error'
+        result.error?.message || result.stderr || result.stdout || 'unknown error'
       }`
     )
   }
 
+  if (source.trim() && !result.stdout.trim()) {
+    throw new Error(`Formatter returned empty output for ${neutralPath}:\n${result.stderr}`)
+  }
+
   return result.stdout
 }
diff --git a/scripts/generate-cli-docs.ts b/scripts/generate-cli-docs.ts
index aee73ae7ff3..627175aa1a9 100644
--- a/scripts/generate-cli-docs.ts
+++ b/scripts/generate-cli-docs.ts
@@ -16,12 +16,16 @@
  * keeps them honest.
  */
 
+import type { EventEmitter } from 'node:events'
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { compareStrings } from '@sim/utils/string'
 import type { Command } from 'commander'
+import { CLI_CONTRACT } from '../packages/sim-cli/src/contract/commands'
 import { V2_OPERATIONS } from '../packages/sim-cli/src/generated/v2-api'
 import { buildProgram } from '../packages/sim-cli/src/program'
+import { calledOperations, operationOf } from '../packages/sim-cli/src/runtime/called-operations'
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 export const OUTPUT_DIR = path.join(ROOT, 'apps/docs/content/docs/cli')
@@ -55,16 +59,478 @@ const OVERVIEW_PAGE = 'commands'
 /** Generated page carrying every command at once, for search and for agents. */
 const REFERENCE_PAGE = 'reference'
 
-/**
- * Sidebar titles for groups whose command name does not title-case cleanly.
- * Everything else gets its hyphens split and each word capitalized.
- */
-const GROUP_TITLES: Record<string, string> = {
-  'audit-logs': 'Audit Logs',
-  'custom-tools': 'Custom Tools',
-  'mcp-servers': 'MCP Servers',
-  'workflow-mcp-servers': 'Workflow MCP Servers',
-  cli: 'CLI',
+interface GroupDocumentation {
+  title?: string
+  description: string
+  notes?: readonly string[]
+  related?: readonly [string, string][]
+}
+
+const GROUP_DOCUMENTATION: Record<string, GroupDocumentation> = {
+  'audit-logs': {
+    description:
+      'Read organization audit actions and filter by actor, resource, workspace, or time.',
+    notes: [
+      'Requires an organization Admin or owner, an OAuth login or personal API key, and enabled enterprise audit access for the deployment.',
+    ],
+    related: [
+      ['Organization permissions', '/platform/permissions'],
+      ['Authentication', '/cli/authentication'],
+    ],
+  },
+  billing: {
+    description: 'Read billing status, credit usage, and storage usage.',
+    related: [
+      ['Costs', '/platform/costs'],
+      ['Authentication', '/cli/authentication'],
+    ],
+  },
+  blocks: {
+    description:
+      'Inspect workflow blocks, integration blocks, and triggers available to the workspace.',
+    notes: [
+      'The catalog reflects the workspace’s allowed integrations, revealed preview blocks, and deployed custom blocks.',
+    ],
+  },
+  'chat-deployments': {
+    description: 'List workflow chat deployments in the workspace.',
+    related: [['Deploy or update a workflow chat', '/cli/workflows#chat-deployments']],
+  },
+  cli: {
+    title: 'Command search',
+    description: 'Find a command by describing the task you want to perform.',
+  },
+  'connector-types': {
+    description:
+      'Discover knowledge connectors and their authentication and source-configuration schemas.',
+    notes: ['Use `--detail full` to inspect a connector’s configuration before creating it.'],
+    related: [['Create and sync knowledge connectors', '/cli/knowledge#connectors']],
+  },
+  credentials: {
+    description: 'Discover providers, connect accounts, and manage credential access.',
+    notes: [
+      'Run `sim --output json credentials providers list` to inspect the provider’s fields and authentication requirements before creating a service-account credential. OAuth connection commands return a link that a person must open to authorize the connection.',
+    ],
+    related: [['Credentials', '/platform/credentials']],
+  },
+  'custom-tools': {
+    description: 'Create and manage code-backed tools that agents can call.',
+    related: [['Custom tools', '/agents/custom-tools']],
+  },
+  files: {
+    description:
+      'Browse workspace files, read or write content, manage versions, and configure sharing.',
+    related: [
+      ['Files', '/files'],
+      ['Output formats', '/cli/output'],
+    ],
+  },
+  knowledge: {
+    description: 'Manage knowledge bases, indexed documents, search, tags, and connector syncs.',
+    related: [
+      ['Knowledge Base', '/knowledgebase'],
+      ['Tags and filters', '/knowledgebase/tags'],
+      ['Export and import', '/knowledgebase/export-import'],
+    ],
+  },
+  logs: {
+    description: 'Read run diagnostics, follow new runs, and summarize failures and latency.',
+    related: [
+      ['Logs and debugging', '/logs-debugging'],
+      ['Output formats', '/cli/output'],
+    ],
+  },
+  'mcp-servers': {
+    title: 'MCP servers',
+    description:
+      'Connect external Model Context Protocol (MCP) servers so workflows can use their tools.',
+    notes: [
+      'To serve Sim workflows to MCP clients instead, use [workflow MCP servers](/cli/workflow-mcp-servers).',
+    ],
+    related: [['MCP connections', '/agents/mcp']],
+  },
+  meta: {
+    title: 'API status',
+    description: 'Inspect API availability and the calling credential’s type and expiry.',
+    related: [['Authentication', '/cli/authentication']],
+  },
+  organizations: {
+    description: 'Manage organization membership, invitations, usage, access requests, and SSO.',
+    related: [
+      ['Organizations', '/platform/organization'],
+      ['Permissions', '/platform/permissions'],
+    ],
+  },
+  'permission-groups': {
+    description:
+      'Manage organization permission groups, their configuration, and member assignments.',
+    notes: [
+      'Use the linked API request schema for the supported `--config` keys. Supplied arrays replace their entire lists; omitted settings remain unchanged on update.',
+    ],
+    related: [['Permission groups', '/platform/permissions']],
+  },
+  profiles: {
+    description: 'List profiles and add a workspace profile that shares a stored login.',
+    notes: [
+      'Adding a profile reuses the active stored login and selects a default workspace. Supply `--workspace` when running without an interactive terminal.',
+    ],
+    related: [
+      ['Configuration', '/cli/configuration'],
+      ['Authentication', '/cli/authentication'],
+    ],
+  },
+  sandboxes: {
+    description: 'Manage reusable dependency sets for Function blocks.',
+    related: [['Function sandboxes', '/workflows/blocks/function#sandboxes']],
+  },
+  secrets: {
+    description: 'Set and manage workspace or personal secrets.',
+    notes: [
+      'Personal secrets belong to the caller across workspaces. Workspace secrets are shared resources. Listings include stored values only for workspace secrets marked visible (unredacted); all other entries contain metadata.',
+    ],
+    related: [['Credentials and secrets', '/platform/credentials']],
+  },
+  selectors: {
+    description:
+      'Discover destination options for registered fields, such as calendars, channels, and tables.',
+    notes: [
+      'A selector key identifies the field’s option source. Its context accepts only declared dependencies; missing OAuth access requires a person to authorize the connection.',
+    ],
+  },
+  skills: {
+    description: 'Create reusable agent instructions and manage their editors.',
+    related: [['Skills', '/agents/skills']],
+  },
+  tables: {
+    description: 'Manage tables, rows, schemas, views, enrichment runs, imports, and exports.',
+    related: [
+      ['Tables', '/tables'],
+      ['Workflow columns', '/tables/workflow-columns'],
+    ],
+  },
+  telemetry: {
+    description: 'Inspect and change this machine’s anonymous usage-reporting preference.',
+    related: [['Usage data', '/cli/usage-data']],
+  },
+  tools: {
+    description: 'Find built-in tools, inspect their parameters, and run them.',
+    notes: [
+      'Inspect a tool with `sim tools get <toolId>` before passing its parameters to `sim tools execute`.',
+    ],
+  },
+  'workflow-mcp-servers': {
+    title: 'Workflow MCP servers',
+    description: 'Serve deployed workflows as tools for Model Context Protocol (MCP) clients.',
+    notes: [
+      'These servers expose Sim workflows. To connect a server that provides external tools, use [MCP servers](/cli/mcp-servers).',
+    ],
+    related: [['MCP connections', '/agents/mcp']],
+  },
+  workflows: {
+    description: 'Build, deploy, run, and inspect workflows from the terminal.',
+    related: [
+      ['Workflow builder', '/workflows'],
+      ['Import and workspace sync', '/cli/workflow-sync'],
+      ['Scripting and exit codes', '/cli/scripting#exit-codes'],
+    ],
+  },
+  workspaces: {
+    description: 'Read workspace access and manage reviewed fork, push, and pull operations.',
+    related: [
+      ['Workspace sync', '/cli/workflow-sync'],
+      ['Workspaces', '/platform/workspaces'],
+    ],
+  },
+}
+
+interface CommandSection {
+  title: string
+  prefixes: readonly string[]
+}
+
+const GROUP_SECTIONS: Record<string, readonly CommandSection[]> = {
+  credentials: [
+    {
+      title: 'Provider discovery and connections',
+      prefixes: ['providers', 'list', 'create', 'connect', 'reconnect', 'update'],
+    },
+    { title: 'Credential members', prefixes: ['members'] },
+    { title: 'Disconnect credentials', prefixes: ['delete'] },
+  ],
+  files: [
+    { title: 'Browse and inspect', prefixes: ['ls', 'list', 'search', 'describe'] },
+    { title: 'Upload, create, and read', prefixes: ['upload', 'create', 'get', 'read'] },
+    { title: 'Edit and organize', prefixes: ['edit', 'set-content', 'rename', 'move', 'unzip'] },
+    { title: 'Sharing', prefixes: ['share'] },
+    {
+      title: 'Versions',
+      prefixes: [
+        'versions list',
+        'versions describe',
+        'versions read',
+        'versions download',
+        'versions revert',
+        'versions delete',
+      ],
+    },
+    { title: 'Archive and restore', prefixes: ['delete', 'batch-delete', 'restore'] },
+    { title: 'Folders', prefixes: ['folders', 'mkdir'] },
+  ],
+  knowledge: [
+    {
+      title: 'Knowledge bases',
+      prefixes: ['list', 'get', 'create', 'update', 'mv', 'delete', 'restore'],
+    },
+    { title: 'Search and export', prefixes: ['search', 'export'] },
+    { title: 'Documents', prefixes: ['documents', 'from-workspace-files'] },
+    { title: 'Chunks', prefixes: ['chunks'] },
+    { title: 'Tags', prefixes: ['tags'] },
+    {
+      title: 'Connectors',
+      prefixes: [
+        'connectors list',
+        'connectors get',
+        'connectors create',
+        'connectors update',
+        'connectors sync',
+        'connectors documents',
+        'connectors delete',
+      ],
+    },
+    { title: 'Folders', prefixes: ['ls', 'folders', 'mkdir'] },
+  ],
+  'mcp-servers': [
+    { title: 'Server connections', prefixes: ['list', 'get', 'create', 'update'] },
+    { title: 'Tool discovery', prefixes: ['tools'] },
+    { title: 'Remove servers', prefixes: ['delete'] },
+  ],
+  organizations: [
+    { title: 'Organizations and workspaces', prefixes: ['list', 'get', 'workspaces'] },
+    { title: 'Members and credit limits', prefixes: ['members'] },
+    { title: 'Invitations', prefixes: ['invitations'] },
+    { title: 'Usage', prefixes: ['usage summary', 'usage breakdown', 'usage events'] },
+    {
+      title: 'Access requests',
+      prefixes: [
+        'access-requests discover',
+        'access-requests create',
+        'access-requests mine',
+        'access-requests cancel',
+        'access-requests list',
+        'access-requests preview',
+        'access-requests resolve',
+        'access-requests settings',
+      ],
+    },
+    {
+      title: 'Verified domains',
+      prefixes: ['domains list', 'domains add', 'domains verify', 'domains remove'],
+    },
+    {
+      title: 'SSO providers and policy',
+      prefixes: [
+        'sso providers list',
+        'sso providers get',
+        'sso providers save',
+        'sso providers primary',
+        'sso providers delete',
+        'sso policy',
+      ],
+    },
+  ],
+  'permission-groups': [
+    { title: 'Group configuration', prefixes: ['list', 'get', 'create', 'update'] },
+    { title: 'Member assignments', prefixes: ['members'] },
+    { title: 'Delete groups', prefixes: ['delete'] },
+  ],
+  skills: [
+    { title: 'Skill instructions', prefixes: ['list', 'get', 'create', 'update'] },
+    { title: 'Editors', prefixes: ['editors'] },
+    { title: 'Delete skills', prefixes: ['delete'] },
+  ],
+  tables: [
+    {
+      title: 'Tables',
+      prefixes: [
+        'list',
+        'get',
+        'create',
+        'update',
+        'move',
+        'mv',
+        'delete',
+        'batch-delete',
+        'restore',
+      ],
+    },
+    { title: 'Rows and queries', prefixes: ['rows', 'upsert'] },
+    { title: 'Columns', prefixes: ['columns'] },
+    { title: 'Saved views', prefixes: ['views'] },
+    {
+      title: 'Producer groups and runs',
+      prefixes: ['groups', 'enrichment', 'dispatches', 'cancel-runs'],
+    },
+    { title: 'Imports', prefixes: ['import', 'imports'] },
+    {
+      title: 'Exports',
+      prefixes: ['exports create', 'exports get', 'exports download', 'exports cancel'],
+    },
+    { title: 'Folders', prefixes: ['ls', 'folders', 'mkdir'] },
+  ],
+  'workflow-mcp-servers': [
+    { title: 'Servers', prefixes: ['list', 'get', 'create', 'update'] },
+    { title: 'Workflow tools', prefixes: ['tools'] },
+    { title: 'Delete servers', prefixes: ['delete'] },
+  ],
+  workflows: [
+    {
+      title: 'Workflows',
+      prefixes: ['list', 'get', 'create', 'update', 'duplicate', 'move', 'mv', 'delete', 'restore'],
+    },
+    { title: 'Draft state and edits', prefixes: ['state', 'operations', 'variables'] },
+    {
+      title: 'Deployments and versions',
+      prefixes: ['deploy', 'deployment', 'versions', 'activate', 'revert', 'rollback', 'undeploy'],
+    },
+    {
+      title: 'Run and inspect',
+      prefixes: ['run', 'runs list', 'runs get', 'runs wait', 'runs resume', 'runs cancel'],
+    },
+    { title: 'Chat deployments', prefixes: ['chat status', 'chat publish', 'chat unpublish'] },
+    { title: 'Export and import', prefixes: ['export', 'import-preview', 'import'] },
+    { title: 'Folders', prefixes: ['ls', 'folders', 'mkdir'] },
+  ],
+  workspaces: [
+    {
+      title: 'Workspace access',
+      prefixes: ['list', 'get', 'members', 'invitations', 'permission-config'],
+    },
+    {
+      title: 'Access requests',
+      prefixes: [
+        'access-requests discover',
+        'access-requests create',
+        'access-requests mine',
+        'access-requests cancel',
+      ],
+    },
+    {
+      title: 'Forks and lineage',
+      prefixes: [
+        'fork-availability',
+        'fork-resources',
+        'fork-preview',
+        'fork',
+        'lineage',
+        'children',
+      ],
+    },
+    { title: 'Mappings', prefixes: ['mappings'] },
+    { title: 'Push and pull', prefixes: ['push-preview', 'push', 'pull-preview', 'pull'] },
+    { title: 'Operation status', prefixes: ['operations'] },
+    { title: 'Exclusions and recovery', prefixes: ['sync-exclusions', 'fork-rollback', 'unlink'] },
+  ],
+}
+
+const COMMAND_NOTES: Record<string, readonly string[]> = {
+  'tables import': [
+    'Choose exactly one source: a local CSV path or `--file-id`. For a new table imported with `--file-id`, supply `--name`. With `--table-id`, omit the new-table `--name` and `--folder` flags; `--mode`, `--mapping`, and `--create-columns` apply only to an existing table.',
+    '**Replace mode deletes all existing rows before loading the CSV and cannot be undone.** It requires `--yes`; cancellation leaves only the rows already imported.',
+    'The command watches the import by default. `--no-wait` returns a queued receipt. A completed import can still report `rowsRejected`, `cellsRejected`, and `rejectedSamples`; inspect them before accepting the result.',
+  ],
+  'workflows chat publish': [
+    'Omitting `--auth-type` selects public access: anyone holding the URL can chat. Supply the complete password or allow-list settings again when replacing a restricted deployment.',
+  ],
+  'workflows runs cancel': [
+    'Canceling a paused run prevents resuming that run. Starting a new run can repeat side effects already performed.',
+  ],
+  'workflows export': [
+    'The export clears credentials, passwords, and table sub-block values, but it is not a general secret scanner. Inspect literal variables and inline configuration before sharing the document.',
+  ],
+  'organizations sso providers save': [
+    'Choose `--provider-type oidc` or `saml`. OIDC requires `--client-id` and `--client-secret`; SAML requires `--entry-point` and `--cert`. Both require an organization-verified domain. The option descriptions state which omitted fields are preserved or cleared.',
+  ],
+}
+
+const LEGACY_COMMAND_ANCHORS: Record<string, string> = {
+  'workflow-mcp-servers tools create': 'publish-workflow-as-mcp-tool',
+  'workflow-mcp-servers tools delete': 'unpublish-workflow-mcp-tool',
+  'cli search': 'find-the-command-for-a-task-described-in-plain-words',
+  'telemetry status': 'show-whether-usage-reporting-is-on-and-why-not-if-it-is-off',
+  'telemetry enable': 'turn-usage-reporting-on-for-this-machine',
+  'workflows runs wait': 'wait-for-a-run-to-reach-a-terminal-state-then-show-it',
+  'workflows chat publish': 'publish-or-replace-a-workflows-chat-deployment',
+  'workspaces operations wait':
+    'wait-for-copy-and-deployment-readiness-exit-3-for-configuration-1-for-failure-or-4-for-timeout',
+}
+
+const VERB_ORDER = [
+  'list',
+  'ls',
+  'get',
+  'status',
+  'describe',
+  'query',
+  'count',
+  'search',
+  'stats',
+  'preview',
+  'discover',
+  'create',
+  'add',
+  'upload',
+  'save',
+  'set',
+  'upsert',
+  'update',
+  'edit',
+  'apply',
+  'update-each',
+  'batch-update',
+  'usage',
+  'next-slot',
+  'sync',
+  'primary',
+  'enrich',
+  'read',
+  'download',
+  'compare',
+  'revert',
+  'wait',
+  'resume',
+  'resend',
+  'cancel',
+  'delete',
+  'batch-delete',
+  'cleanup',
+  'remove',
+  'revoke',
+  'restore',
+] as const
+
+interface ApiReferenceOperation {
+  operationId?: string
+  tags?: string[]
+}
+
+function apiReferenceLinks(): Map<string, string> {
+  const links = new Map<string, string>()
+  for (const name of fs.readdirSync(path.join(ROOT, 'apps/docs'))) {
+    if (!/^openapi-v2-.*\.json$/.test(name)) continue
+    const document = JSON.parse(fs.readFileSync(path.join(ROOT, 'apps/docs', name), 'utf8')) as {
+      paths: Record<string, Record<string, ApiReferenceOperation>>
+    }
+    for (const [route, operations] of Object.entries(document.paths)) {
+      for (const [method, operation] of Object.entries(operations)) {
+        const tag = operation.tags?.[0]
+        if (!operation.operationId || !tag) continue
+        const url = `/api-reference/${tag.toLowerCase().replaceAll(' ', '-')}/${operation.operationId}`
+        links.set(operation.operationId, url)
+        links.set(`${method.toUpperCase()} ${route}`, url)
+      }
+    }
+  }
+  return links
 }
 
 interface DocumentedCommand {
@@ -74,12 +540,7 @@ interface DocumentedCommand {
 }
 
 function titleFor(name: string): string {
-  const override = GROUP_TITLES[name]
-  if (override) return override
-  return name
-    .split('-')
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(' ')
+  return GROUP_DOCUMENTATION[name]?.title ?? sentenceCase(name.replaceAll('-', ' '))
 }
 
 /**
@@ -123,37 +584,28 @@ function collectLeaves(command: Command, prefix: string[]): DocumentedCommand[]
  * the row filter help both contain one.
  */
 function code(value: string): string {
-  return `\`${escapeTablePipes(value)}\``
+  return value.includes('\\') ? literalCode(value) : `\`${value.replace(/\|/g, '\\|')}\``
 }
 
-/**
- * Escapes a value so a Markdown table row cannot be split by its content.
- *
- * A backslash has to be doubled before pipes are escaped, or an input already
- * ending in one turns `a\` + `|` into `a\\|`: the table parser reads `\\` as an
- * escaped backslash, leaving the pipe unescaped, and the cell splits early.
- *
- * The doubling is correct inside a code span too, even though code spans do not
- * process backslash escapes — the table layer consumes one level of escaping
- * before inline parsing runs, so `a\\\|` arrives at the code span as `a\|`.
- */
+/** A JSX string keeps code containing backslashes and pipes lossless through GFM tables. */
+function literalCode(value: string): string {
+  return `<code>{${JSON.stringify(value).replaceAll('|', '\\u007c')}}</code>`
+}
+
+/** Escapes backslashes and pipes in Markdown table prose. */
 function escapeTablePipes(value: string): string {
   return value.replace(/\\/g, '\\\\').replace(/\|/g, '\\|')
 }
 
-/**
- * Escapes prose — text NOT inside a code span — for a Markdown table cell.
- *
- * Here the entities are the right answer: MDX reads `{` as the start of a JS
- * expression and `<` as the start of a JSX tag, and both appear in help text
- * that embeds JSON examples.
- */
 function escapeCell(value: string): string {
-  return escapeTablePipes(escapeProse(value))
+  return mapCodeSpans(
+    value,
+    (text) => escapeTablePipes(escapeText(text)),
+    (span, content) => (content.includes('\\') ? literalCode(content) : span.replace(/\|/g, '\\|'))
+  )
 }
 
-/** Escapes MDX-significant characters in body prose. */
-function escapeProse(value: string): string {
+function escapeText(value: string): string {
   return value
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
@@ -161,6 +613,49 @@ function escapeProse(value: string): string {
     .replace(/\}/g, '&#125;')
 }
 
+/** Escapes MDX-significant prose while retaining inline-code contents. */
+function escapeProse(value: string): string {
+  return mapCodeSpans(value, escapeText, (span) => span)
+}
+
+function mapCodeSpans(
+  value: string,
+  prose: (text: string) => string,
+  inlineCode: (span: string, content: string) => string
+): string {
+  const delimiters = [...value.matchAll(/`+/g)]
+  let result = ''
+  let offset = 0
+  for (let index = 0; index < delimiters.length; index += 1) {
+    const opening = delimiters[index]
+    if (!opening) continue
+    let precedingBackslashes = 0
+    for (
+      let position = opening.index - 1;
+      position >= 0 && value[position] === '\\';
+      position -= 1
+    ) {
+      precedingBackslashes += 1
+    }
+    if (precedingBackslashes % 2 !== 0) continue
+    const closingIndex = delimiters.findIndex(
+      (delimiter, candidate) => candidate > index && delimiter[0].length === opening[0].length
+    )
+    const closing = delimiters[closingIndex]
+    if (!closing) continue
+    const end = closing.index + closing[0].length
+    result +=
+      prose(value.slice(offset, opening.index)) +
+      inlineCode(
+        value.slice(opening.index, end),
+        value.slice(opening.index + opening[0].length, closing.index)
+      )
+    offset = end
+    index = closingIndex
+  }
+  return result + prose(value.slice(offset))
+}
+
 function usageLine(entry: DocumentedCommand): string {
   const parts = ['sim', ...entry.path]
   for (const argument of entry.command.registeredArguments) {
@@ -227,8 +722,9 @@ export function describeOption(option: Command['options'][number]): string {
   if (option.argChoices && option.argChoices.length > 0) {
     parts.push(`Accepted values: ${option.argChoices.map(code).join(', ')}.`)
   }
-  if (option.defaultValue !== undefined) {
-    const fallback = formatDefault(option.defaultValue)
+  const defaultValue = option.defaultValue ?? option.defaultValueDescription
+  if (defaultValue !== undefined && !/\bdefault(?:s|ing)?\b/i.test(option.description)) {
+    const fallback = formatDefault(defaultValue)
     if (fallback) parts.push(`Defaults to ${code(fallback)}.`)
   }
   const description = parts.filter(Boolean).join(' ')
@@ -272,7 +768,7 @@ function renderOptions(entry: DocumentedCommand): string[] {
 
   const rows = options.map(
     (option) =>
-      `| ${code(option.flags)} | ${isRequiredOption(option) ? 'Yes' : 'No'} | ${describeOption(option)} |`
+      `| ${code(option.flags)} | ${isRequiredOption(option) ? 'Yes' : /\brequired (?:when|with|unless|only)/i.test(option.description) ? 'Conditional' : 'No'} | ${describeOption(option)} |`
   )
 
   return [
@@ -303,6 +799,11 @@ const ACRONYMS = new Set([
   'SSO',
   'URL',
   'YAML',
+  'OIDC',
+  'SAML',
+  'PKCE',
+  'DNS',
+  'UTC',
 ])
 
 /**
@@ -319,23 +820,75 @@ const ACRONYMS = new Set([
  * outputs are included in JSON or YAML output)") and belong in the body, not in
  * a sidebar entry.
  */
-function headingFor(entry: DocumentedCommand): string {
-  const description = entry.command.description()
-  if (!description) return `sim ${entry.path.join(' ')}`
-
-  return description
-    .replace(/\s*\([^)]*\)\s*$/, '')
+function sentenceCase(value: string): string {
+  return value
     .trim()
     .split(' ')
     .map((word, index) => {
       if (ACRONYMS.has(word)) return word
       if (index === 0) return word.charAt(0).toUpperCase() + word.slice(1)
-      // Only fold words that look Title-Cased; `--tag` or `blockName` stay put.
       return /^[A-Z][a-z]+$/.test(word) ? word.toLowerCase() : word
     })
     .join(' ')
 }
 
+function headingFor(entry: DocumentedCommand): string {
+  const description = entry.command.description()
+  return description
+    ? sentenceCase(description.replace(/\s*\([^)]*\)\s*$/, ''))
+    : `sim ${entry.path.join(' ')}`
+}
+
+function orderedCommands(entries: DocumentedCommand[]): DocumentedCommand[] {
+  const rank = (entry: DocumentedCommand): number => {
+    const verb = entry.path.at(-1)
+    const index = VERB_ORDER.findIndex((candidate) => candidate === verb)
+    return index < 0 ? VERB_ORDER.length : index
+  }
+  return [...entries].sort(
+    (left, right) =>
+      rank(left) - rank(right) || compareStrings(left.path.join(' '), right.path.join(' '))
+  )
+}
+
+/** Reads command-specific help additions without emitting the root’s help epilogue. */
+function additionalHelp(command: Command): string[] {
+  const chunks: string[] = []
+  const context = { error: false, command, write: (value: string) => chunks.push(value) }
+  const helpEvents = command as Command & EventEmitter
+  helpEvents.emit('afterHelp', context)
+  const text = chunks.join('').trim()
+  if (!text) return []
+  const [prose = '', examples] = text.split(/\nExamples:\s*\n/, 2)
+  const lines = prose
+    .split(/\n\s*\n/)
+    .flatMap((paragraph) => [escapeProse(paragraph.replace(/\s*\n\s*/g, ' ').trim()), ''])
+  if (examples) {
+    lines.push(
+      '**Examples**',
+      '',
+      '```bash',
+      ...examples
+        .trim()
+        .split('\n')
+        .map((line) => line.trim().replace(/^\$ /, '')),
+      '```',
+      ''
+    )
+  }
+  return lines
+}
+
+function relatedDocs(documentation: GroupDocumentation | undefined): string[] {
+  if (!documentation?.related?.length) return []
+  return [
+    '## Related docs',
+    '',
+    ...documentation.related.map(([label, url]) => `- [${label}](${url})`),
+    '',
+  ]
+}
+
 interface RenderOptions {
   /** Markdown heading depth, so the master page can nest commands under groups. */
   level?: number
@@ -348,45 +901,64 @@ interface RenderOptions {
    * looking one up by name, not browsing by task.
    */
   commandHeadings?: boolean
+  referenceLinks?: ReadonlyMap<string, string>
 }
 
 function renderCommand(entry: DocumentedCommand, options: RenderOptions = {}): string[] {
-  const { level = 2, commandHeadings = false } = options
+  const { level = 2, commandHeadings = false, referenceLinks } = options
   const aliases = entry.command.aliases()
   const heading = commandHeadings ? `sim ${entry.path.join(' ')}` : headingFor(entry)
   const description = entry.command.description()
-
-  const lines = [`${'#'.repeat(level)} ${escapeProse(heading)}`, '']
-  if (commandHeadings && description) lines.push(escapeProse(description), '')
-  lines.push('```bash', usageLine(entry), '```')
-  // Only when the heading dropped something — otherwise this restates it.
-  if (
-    !commandHeadings &&
-    description &&
-    description !== heading &&
-    description.trimEnd().endsWith(')')
-  ) {
-    lines.push('', escapeProse(description))
+  const operation = operationOf(entry.command)
+  const spec = operation ? CLI_CONTRACT[operation] : undefined
+  const anchor = commandHeadings ? undefined : LEGACY_COMMAND_ANCHORS[entry.path.join(' ')]
+  const lines = [`${'#'.repeat(level)} ${escapeProse(heading)}${anchor ? ` [#${anchor}]` : ''}`, '']
+  if (commandHeadings && description) lines.push(escapeProse(sentenceCase(description)), '')
+  if (!commandHeadings) {
+    const qualifier = /\s*\(([^)]*)\)\s*$/.exec(description)?.[1]
+    if (qualifier)
+      lines.push(
+        escapeProse(asSentence(qualifier.charAt(0).toUpperCase() + qualifier.slice(1))),
+        ''
+      )
   }
+  if (spec?.confirm) lines.push(escapeProse(spec.confirm), '')
+  for (const note of COMMAND_NOTES[entry.path.join(' ')] ?? []) lines.push(escapeProse(note), '')
+  lines.push('```bash', usageLine(entry), '```')
   if (aliases.length > 0) {
-    const spelled = aliases.map(
-      (alias) => `\`sim ${[...entry.path.slice(0, -1), alias].join(' ')}\``
+    const spelled = aliases.map((alias) =>
+      code(`sim ${[...entry.path.slice(0, -1), alias].join(' ')}`)
     )
     lines.push('', `Also available as ${spelled.join(', ')}.`)
   }
-  lines.push(...renderArguments(entry), ...renderOptions(entry), '')
+  lines.push(
+    ...renderArguments(entry),
+    ...renderOptions(entry),
+    '',
+    ...additionalHelp(entry.command)
+  )
+  const references = operation ? [operation] : (calledOperations(entry.command) ?? [])
+  const links = references.flatMap((name) => {
+    const apiOperation = V2_OPERATIONS[name]
+    const url =
+      referenceLinks?.get(name) ??
+      referenceLinks?.get(
+        `${apiOperation.method} ${apiOperation.path.replace(/\[([^\]]+)\]/g, '{$1}')}`
+      )
+    return url ? [`[${name}](${url})`] : []
+  })
+  if (links.length) lines.push(`API request and response schemas: ${links.join(', ')}.`, '')
   return lines
 }
 
-function frontmatter(title: string, description: string, imports: string[] = []): string[] {
+function frontmatter(title: string, description: string, hasTables = true): string[] {
   return [
     '---',
     `title: ${title}`,
     `description: ${description}`,
     '---',
     '',
-    "import { CommandTable } from '@/components/ui/command-table'",
-    ...imports,
+    ...(hasTables ? ["import { CommandTable } from '@/components/ui/command-table'"] : []),
     '',
   ]
 }
@@ -431,21 +1003,24 @@ function assertDistinctHeadings(page: string, entries: DocumentedCommand[]): voi
 function renderReferencePage(
   program: Command,
   groups: Command[],
-  globals: DocumentedCommand[]
+  globals: DocumentedCommand[],
+  referenceLinks: ReadonlyMap<string, string>
 ): string {
   const lines = [
     ...frontmatter('Complete reference', 'Every sim command, argument, and flag on a single page'),
     'Every command on one page, generated from the CLI itself. Start at the',
     '[overview](/cli/commands) to browse; this page is for searching and for tools.',
     '',
-    'Append `.mdx` to any page for its raw Markdown —',
+    'Append `.mdx` to an authored guide or CLI reference page for its raw Markdown —',
     '[`/cli/reference.mdx`](/cli/reference.mdx) is this page as plain text. The docs',
     'are also published as [`/llms.txt`](/llms.txt) and',
     '[`/llms-full.txt`](/llms-full.txt).',
     '',
     '## Global options',
     '',
-    'These apply to every command, and may be written before or after it.',
+    'Place these options before or after the command. Each command uses the settings',
+    'relevant to its action. Telemetry commands always print text; workflow export',
+    'prints a portable JSON document, or YAML when selected.',
     // Deliberately unwrapped, like the same table on the overview page:
     // `CommandTable` sizes its second column for the `Required` cell of the
     // three-column tables, which on this two-column one would crush the
@@ -459,61 +1034,100 @@ function renderReferencePage(
     '',
   ]
 
-  for (const leaf of globals) lines.push(...renderCommand(leaf, { commandHeadings: true }))
+  lines.push(
+    'Use `--help` to inspect a command. `sim --version` prints the CLI version,',
+    'takes no value, and exits without running a command. Deployment-version commands',
+    'use their documented arguments or `--to-version`.',
+    '',
+    'API schema links describe HTTP payloads. See [CLI output formats](/cli/output)',
+    'for resource unwrapping, pagination envelopes, and display formats.',
+    ''
+  )
+
+  for (const leaf of globals)
+    lines.push(...renderCommand(leaf, { commandHeadings: true, referenceLinks }))
 
   for (const group of groups) {
     lines.push(`## sim ${group.name()}`, '')
+    const documentation = GROUP_DOCUMENTATION[group.name()]
+    if (documentation) lines.push(escapeProse(documentation.description), '')
+    for (const note of documentation?.notes ?? []) lines.push(escapeProse(note), '')
     const aliases = group.aliases()
     if (aliases.length > 0) {
       lines.push(`Also spelled ${aliases.map((alias) => `\`sim ${alias}\``).join(', ')}.`, '')
     }
     for (const leaf of collectLeaves(group, [group.name()])) {
-      lines.push(...renderCommand(leaf, { level: 3, commandHeadings: true }))
+      lines.push(...renderCommand(leaf, { level: 3, commandHeadings: true, referenceLinks }))
     }
   }
 
   return `${lines.join('\n').trimEnd()}\n`
 }
 
-function renderGroupPage(group: Command): string {
+function renderGroupPage(group: Command, referenceLinks: ReadonlyMap<string, string>): string {
   const name = group.name()
   const leaves = collectLeaves(group, [name])
   const aliases = group.aliases()
-
+  const documentation = GROUP_DOCUMENTATION[name]
+  const description = documentation?.description ?? sentenceCase(group.description())
   assertDistinctHeadings(`${name}.mdx`, leaves)
-
-  const lines = [
-    ...frontmatter(
-      titleFor(name),
-      `${group.description() || `The sim ${name} commands`} — every subcommand, argument, and flag`
-    ),
-  ]
-
+  const hasTables = leaves.some(
+    (entry) =>
+      entry.command.registeredArguments.length > 0 || documentedOptions(entry.command).length > 0
+  )
+  const lines = [...frontmatter(titleFor(name), description, hasTables), description, '']
+  for (const note of documentation?.notes ?? []) lines.push(escapeProse(note), '')
   if (aliases.length > 0) {
     lines.push(
       `\`sim ${name}\` is also spelled ${aliases.map((alias) => `\`sim ${alias}\``).join(', ')}.`,
       ''
     )
   }
-
-  lines.push(
-    'Every command below also accepts the [global options](/cli/commands#global-options).',
-    ''
-  )
-
-  for (const leaf of leaves) lines.push(...renderCommand(leaf))
-
+  lines.push('These commands accept the [global options](/cli/commands#global-options).', '')
+  const sections = GROUP_SECTIONS[name]
+  if (sections) {
+    const remaining = new Set(leaves)
+    for (const section of sections) {
+      const entries: DocumentedCommand[] = []
+      for (const prefix of section.prefixes) {
+        const matches = [...remaining].filter((entry) => {
+          const relative = entry.path.slice(1).join(' ')
+          return relative === prefix || relative.startsWith(`${prefix} `)
+        })
+        for (const entry of orderedCommands(matches)) {
+          entries.push(entry)
+          remaining.delete(entry)
+        }
+      }
+      if (!entries.length) continue
+      lines.push(`## ${section.title}`, '')
+      for (const entry of entries) lines.push(...renderCommand(entry, { level: 3, referenceLinks }))
+    }
+    if (remaining.size) {
+      lines.push('## Other commands', '')
+      for (const entry of orderedCommands([...remaining]))
+        lines.push(...renderCommand(entry, { level: 3, referenceLinks }))
+    }
+  } else {
+    for (const entry of orderedCommands(leaves))
+      lines.push(...renderCommand(entry, { referenceLinks }))
+  }
+  lines.push(...relatedDocs(documentation))
   return `${lines.join('\n').trimEnd()}\n`
 }
 
 function renderIndexPage(
   program: Command,
   groups: Command[],
-  globals: DocumentedCommand[]
+  globals: DocumentedCommand[],
+  referenceLinks: ReadonlyMap<string, string>
 ): string {
   const lines = [
-    ...frontmatter('CLI Commands', 'Global options, and every sim command group'),
-    'Every `sim` command follows the same shape:',
+    ...frontmatter(
+      'CLI commands',
+      'Find command groups, global options, and login, configuration, and Chat commands.'
+    ),
+    'Resource commands use this shape:',
     '',
     '```bash',
     'sim <resource> [sub-resource] <verb> [arguments] [options]',
@@ -521,11 +1135,15 @@ function renderIndexPage(
     '',
     'Some resource groups also accept a singular alias: `sim workflow get` and',
     '`sim workflows get` are the same command. `knowledge` also answers to `kb`.',
-    'Each group’s reference lists its supported aliases.',
+    'Each group’s reference lists its supported aliases. Login, configuration, and',
+    'Chat commands appear below. To find a command for a task, use',
+    '`sim cli search "describe your task"`.',
     '',
     '## Global options',
     '',
-    'These apply to every command, and may be written before or after it.',
+    'Place these options before or after the command. Each command uses the settings',
+    'relevant to its action. Telemetry commands always print text; workflow export',
+    'prints a portable JSON document, or YAML when selected.',
     '',
     '| Option | Description |',
     '| --- | --- |',
@@ -533,19 +1151,33 @@ function renderIndexPage(
       (option) => `| ${code(option.flags)} | ${describeOption(option)} |`
     ),
     '',
+    'Use `--help` to inspect a command. Run `sim --version` to print the CLI version;',
+    '`--version` takes no value and exits without running a command. Deployment-version',
+    'commands use their documented arguments or `--to-version` instead.',
+    '',
+    'See [output formats](/cli/output) for the JSON default and display formats.',
+    '',
     '## Command groups',
     '',
     '| Group | Description |',
     '| --- | --- |',
     ...groups.map(
       (group) =>
-        `| [${code(`sim ${group.name()}`)}](/cli/${group.name()}) | ${escapeCell(group.description()) || '—'} |`
+        `| [${code(`sim ${group.name()}`)}](/cli/${group.name()}) | ${escapeCell(GROUP_DOCUMENTATION[group.name()]?.description ?? sentenceCase(group.description())) || '—'} |`
     ),
     '',
   ]
 
-  for (const leaf of globals) lines.push(...renderCommand(leaf))
+  for (const leaf of globals) lines.push(...renderCommand(leaf, { referenceLinks }))
 
+  lines.push(
+    '## Related docs',
+    '',
+    '- [Complete command reference](/cli/reference)',
+    '- [Authentication](/cli/authentication)',
+    '- [Scripting](/cli/scripting)',
+    ''
+  )
   return `${lines.join('\n').trimEnd()}\n`
 }
 
@@ -672,11 +1304,13 @@ function build(): Map<string, string> {
     ...globals,
   ])
 
+  const referenceLinks = apiReferenceLinks()
   const files = new Map<string, string>()
   files.set('meta.json', renderMeta(groups))
-  files.set(`${OVERVIEW_PAGE}.mdx`, renderIndexPage(program, groups, globals))
-  files.set(`${REFERENCE_PAGE}.mdx`, renderReferencePage(program, groups, globals))
-  for (const group of groups) files.set(`${group.name()}.mdx`, renderGroupPage(group))
+  files.set(`${OVERVIEW_PAGE}.mdx`, renderIndexPage(program, groups, globals, referenceLinks))
+  files.set(`${REFERENCE_PAGE}.mdx`, renderReferencePage(program, groups, globals, referenceLinks))
+  for (const group of groups)
+    files.set(`${group.name()}.mdx`, renderGroupPage(group, referenceLinks))
   return files
 }
 
diff --git a/scripts/openapi/generator.ts b/scripts/openapi/generator.ts
index e94245c3605..66df8b9677c 100644
--- a/scripts/openapi/generator.ts
+++ b/scripts/openapi/generator.ts
@@ -377,7 +377,7 @@ function defaultSuccessContent(
     const generated = generateSchema(schema, 'output', components, `${label} response`)
     validateExamples(schema, generated.metadata.examples, 'output', `${label} response`)
     return {
-      'application/json': { schema: { $ref: `#/components/schemas/${generated.name}` } },
+      'application/json': schemaMediaFor(generated, 'Response'),
     }
   }
 
@@ -412,7 +412,7 @@ function statusSuccessContent(
   const generated = generateSchema(schema, 'output', components, `${label} response`)
   validateExamples(schema, generated.metadata.examples, 'output', `${label} response`)
   const content: JsonObject = {
-    'application/json': { schema: { $ref: `#/components/schemas/${generated.name}` } },
+    'application/json': schemaMediaFor(generated, 'Response'),
   }
   for (const contentType of success.additionalContentTypes ?? []) {
     invariant(contentType !== 'application/json', `${label} repeats the JSON content type`)
@@ -455,6 +455,24 @@ function validateExamples(schema: ApiSchema, examples: unknown, io: SchemaIo, la
   }
 }
 
+function schemaMediaFor(
+  generated: ReturnType<typeof generateSchema>,
+  exampleKind: 'Request' | 'Response'
+): JsonObject {
+  const examples = generated.metadata.examples
+    ? Object.fromEntries(
+        generated.metadata.examples.map((value, index) => [
+          `example${index + 1}`,
+          { summary: `${exampleKind} example ${index + 1}`, value },
+        ])
+      )
+    : undefined
+  return {
+    schema: { $ref: `#/components/schemas/${generated.name}` },
+    ...(examples ? { examples } : {}),
+  }
+}
+
 function requestBodyFor(
   route: OpenApiRouteDefinition,
   components: JsonObject,
@@ -478,10 +496,7 @@ function requestBodyFor(
     required: !schema.safeParse(undefined).success,
     description: generated.metadata.description,
     content: Object.fromEntries(
-      contentTypes.map((contentType) => [
-        contentType,
-        { schema: { $ref: `#/components/schemas/${generated.name}` } },
-      ])
+      contentTypes.map((contentType) => [contentType, schemaMediaFor(generated, 'Request')])
     ),
   }
 }