@@ -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 -->
@@ -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.
@@ -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.