From 6db566768c85694f060a2d2365f4179b65385a65 Mon Sep 17 00:00:00 2001 From: "@mrubens" <2600+mrubens@users.noreply.github.com> Date: Mon, 9 Nov 2026 17:17:47 +0000 Subject: [PATCH] docs: correct provider and setup guidance after accuracy audit --- apps/docs/custom-automations.mdx | 2 +- apps/docs/how-roomote-works.mdx | 30 ++++++++++--------- apps/docs/integrations/granola.mdx | 8 +++-- apps/docs/integrations/index.mdx | 10 +++++-- apps/docs/models.mdx | 11 +++---- .../providers/communications/agentmail.mdx | 7 +++-- apps/docs/providers/inference/chatgpt.mdx | 7 +++-- .../providers/inference/zai-coding-plan.mdx | 4 ++- apps/docs/providers/inference/zai.mdx | 6 ++-- 9 files changed, 52 insertions(+), 33 deletions(-) diff --git a/apps/docs/custom-automations.mdx b/apps/docs/custom-automations.mdx index aca56850d9..357451046a 100644 --- a/apps/docs/custom-automations.mdx +++ b/apps/docs/custom-automations.mdx @@ -184,4 +184,4 @@ provider-supported thinking budget. See [Schedule maintenance](/cookbook/scheduled-housekeeping) for copyable custom automation prompts, or [Draft product updates](/cookbook/product-updates-newsletter) -for a custom MCP server and a natural-language schedule. +for a Resend draft workflow and a natural-language schedule. diff --git a/apps/docs/how-roomote-works.mdx b/apps/docs/how-roomote-works.mdx index d302277678..c57b8893c9 100644 --- a/apps/docs/how-roomote-works.mdx +++ b/apps/docs/how-roomote-works.mdx @@ -4,20 +4,21 @@ icon: workflow description: Understand where work starts, how Roomote runs, and how results come back. --- -Roomote is designed to act like a shared teammate inside the workflow your team -already has. It is not an IDE, a local copilot, or a desktop app. It is a -reviewable cloud agent that is most at home in chat, where teammates can ask -questions, assign work, and review updates from the conversations they already -use. +Roomote agents answer questions, investigate problems, and carry out reviewable +work. Use the web dashboard to configure Roomote, start a session, and follow +its results. You can also connect chat, source control, or Linear to bring +Roomote into workflows your team already uses. -Roomote also works from your source-control provider, Linear, and the web -dashboard, but a chat surface such as Slack is the primary day-to-day surface -for most teams. +A session holds the conversation and can answer directly using connected tools, +including supported source-control API reads. When work needs a local checkout, +code changes, or command execution, Roomote delegates a task to an isolated +sandbox. The session keeps the conversation and task results together. ## Shared engineering work -Most natural-language work starts as a Roomote session. The recommended first -path is to mention Roomote in chat with a scoped ask. Use it for +Most natural-language work starts as a Roomote session. For your first +repository task, follow [Run your first task](/first-task) in the web dashboard; +chat connections are optional. Use Roomote for implementation, debugging, investigation, small refactors, test fixes, documentation updates, planning, and codebase questions. @@ -70,10 +71,11 @@ session lives. | Bitbucket | Pull request events or `@`-mentions when configured | Bitbucket activity and session view | | Azure DevOps | Repository or pull request follow-up when configured | Azure DevOps activity and session view | -Chat is the recommended surface for the first session after setup because it -makes Roomote visible inside an existing team conversation. Use the dashboard -when you want to continue a session or open delegated task details such as -logs, diffs, and previews. +Choose the surface that fits the work. You can start and continue sessions +entirely in the dashboard, or use a connected chat provider when the request +belongs in an existing team conversation. Open delegated task details in the +dashboard to inspect logs, diffs, and previews. See +[Communications](/communications) when you are ready to connect chat or email. ## How Roomote stays reviewable diff --git a/apps/docs/integrations/granola.mdx b/apps/docs/integrations/granola.mdx index 5e629e4ce6..3cc7c3fea5 100644 --- a/apps/docs/integrations/granola.mdx +++ b/apps/docs/integrations/granola.mdx @@ -25,8 +25,12 @@ do not expire, and cannot read ordinary private notes. They can read: - notes visible to everyone in the workspace, including the Team space - notes in spaces where **Allow Granola API access** is enabled -Granola enables API access by default for newly created spaces. Review -**Settings > Spaces** and turn it off anywhere Roomote should not read notes. +Granola enables API access by default for newly created spaces. Review that +choice when creating a space. For an existing space, open **Integrations > +Granola API** in the space header and turn off **Allow access with a workspace +API key** anywhere Roomote should not read notes. Only workspace admins can +change this setting. See [Granola's workspace API key +guide](https://docs.granola.ai/help-center/sharing/integrations/granola-api#workspace-api-keys). If a workspace key is not available, create a personal key from **Settings > Connectors > API keys** and select only **Public notes**, leaving **Personal diff --git a/apps/docs/integrations/index.mdx b/apps/docs/integrations/index.mdx index ac9f6e9487..3350b8fc30 100644 --- a/apps/docs/integrations/index.mdx +++ b/apps/docs/integrations/index.mdx @@ -157,9 +157,9 @@ general API or admin access. For most teams, this order works well: -1. the required providers: - [Comms](/communications), [Source Control](/source-control), - [Inference](/models), and [Sandboxes](/compute) +1. [Inference](/models) for conversations, plus [Source Control](/source-control) + and [Sandboxes](/compute) for repository tasks; follow + [Run your first task](/first-task) to verify this path in the dashboard 2. one task-tracking integration, such as Linear, Jira, or Asana, if your team already works there 3. one monitoring or deployment integration, such as Sentry, Grafana, Railway, @@ -174,3 +174,7 @@ For most teams, this order works well: After each connection, run a small task that uses the new context. For example, ask Roomote to summarize a linked issue, inspect a monitoring alert, or explain which environment a support thread belongs to. + +[Communications providers](/communications) are optional. Connect one when you +want to start work from chat or email, or deliver automation reports there; +you can use Roomote entirely from the web dashboard. diff --git a/apps/docs/models.mdx b/apps/docs/models.mdx index e72e453b1b..530196ed18 100644 --- a/apps/docs/models.mdx +++ b/apps/docs/models.mdx @@ -331,11 +331,12 @@ list. - **Models** controls the provider/model pairs that are available, the default model, and specialized model roles. -When you connect an inference provider in setup, Roomote tests the candidate -credentials and selected model before saving them. Authentication, quota, -model-access, endpoint, and timeout failures are reported during setup so you -can correct the connection before starting a task. Providers configured through -environment variables are validated by the deployment at startup instead. +API-key connections in setup use the same pre-save credential check described +above: rejected credentials block saving, while exhausted credit or quota +produces a warning without blocking setup. Model-access, rate-limit, endpoint, +and timeout failures do not block that save. A saved connection is not proof +that its model can run; follow the provider's verification steps and complete +a small task, including when credentials are managed through environment variables. For subscription-based providers (ChatGPT, GitHub Copilot, Kimi for Coding, xAI Grok / SuperGrok, and Z.AI Coding Plan), the provider row also shows current diff --git a/apps/docs/providers/communications/agentmail.mdx b/apps/docs/providers/communications/agentmail.mdx index a6684d1e7f..900e957fd9 100644 --- a/apps/docs/providers/communications/agentmail.mdx +++ b/apps/docs/providers/communications/agentmail.mdx @@ -42,9 +42,10 @@ then: 1. **Create the inbox** Roomote should receive mail at (or pick an existing one). AgentMail's free tier includes 3 inboxes and 100 emails per day and - adds a "Sent via AgentMail" footer to outbound mail; custom domains, with - AgentMail-managed SPF/DKIM/DMARC, need a paid plan and are recommended for - production. + adds a "Sent via AgentMail" footer to outbound mail. The free tier also + includes one custom domain with DKIM, SPF, and DMARC support; paid plans + remove the footer and provide higher limits. Review [AgentMail's current + pricing](https://www.agentmail.to/pricing) before choosing a production plan. 2. **Create an API key from inside that inbox**, so the key is scoped to it. Give it these permissions (or full access): `inbox_read`, `inbox_update`, `webhook_read`, `webhook_create`, `webhook_update`, `webhook_delete`, diff --git a/apps/docs/providers/inference/chatgpt.mdx b/apps/docs/providers/inference/chatgpt.mdx index b898ea04a5..e42b24957b 100644 --- a/apps/docs/providers/inference/chatgpt.mdx +++ b/apps/docs/providers/inference/chatgpt.mdx @@ -41,5 +41,8 @@ on [ChatGPT pricing](https://chatgpt.com/pricing). flow with the same eligible ChatGPT account. - **Usage is not displayed.** The unofficial usage endpoint may be unavailable; this does not necessarily mean model access is disconnected. -- **A plan limit is reached.** Wait for the displayed window to reset or connect - the OpenAI API provider for separately billed capacity. +- **A plan limit is reached.** Wait for the displayed window to reset, or connect + the [OpenAI API provider](/providers/inference/openai) and disconnect ChatGPT + Subscription to use separately billed capacity. Connecting an API key alone + does not change the route: the subscription takes precedence for `openai/` + models while both are connected. diff --git a/apps/docs/providers/inference/zai-coding-plan.mdx b/apps/docs/providers/inference/zai-coding-plan.mdx index cf9992b1ac..db720abc96 100644 --- a/apps/docs/providers/inference/zai-coding-plan.mdx +++ b/apps/docs/providers/inference/zai-coding-plan.mdx @@ -24,7 +24,9 @@ ZAI_CODING_PLAN_API_KEY=... ZAI_CODING_PLAN_REGION=global # or china ``` -Both values are required. Models use the `zai-coding-plan/` prefix, keeping +The configuration form requires a region selection. For environment-variable +configuration, `ZAI_CODING_PLAN_REGION` defaults to `global` when unset; set it +to `china` for a China-region membership key. Models use the `zai-coding-plan/` prefix, keeping their membership quota separate from metered `zai/` model IDs. ## Cost behavior diff --git a/apps/docs/providers/inference/zai.mdx b/apps/docs/providers/inference/zai.mdx index a13862caf9..3a64a9b6d5 100644 --- a/apps/docs/providers/inference/zai.mdx +++ b/apps/docs/providers/inference/zai.mdx @@ -24,8 +24,10 @@ ZAI_API_KEY=... ZAI_REGION=global # or china ``` -Both values are required. Models use the `zai/` prefix; Roomote can also map a -supported GLM image-capable model to the media role. Check audio and video input +The configuration form requires a region selection. For environment-variable +configuration, `ZAI_REGION` defaults to `global` when unset; set it to `china` +for a BigModel key. Models use the `zai/` prefix; Roomote can also map a +supported GLM image-capable model to the vision role. Check audio and video input support separately if you use those attachments. ## Cost behavior