From ca684df082c4ede6b38a51724a0a0ad2db2f9eee Mon Sep 17 00:00:00 2001 From: Roomote Date: Mon, 3 Aug 2026 16:03:06 +0000 Subject: [PATCH 01/13] docs: add Roomote Cookbook recipes --- apps/docs/automations.mdx | 12 ++ apps/docs/cookbook/ci-failure-auto-fix.mdx | 64 ++++++++++ apps/docs/cookbook/index.mdx | 37 ++++++ .../cookbook/product-updates-newsletter.mdx | 76 ++++++++++++ apps/docs/cookbook/scheduled-housekeeping.mdx | 88 +++++++++++++ apps/docs/cookbook/support-channel.mdx | 116 ++++++++++++++++++ apps/docs/cookbook/template.mdx | 63 ++++++++++ apps/docs/cookbook/vendor-outage-triage.mdx | 98 +++++++++++++++ apps/docs/docs.json | 12 ++ apps/docs/integrations/better-stack.mdx | 4 + apps/docs/integrations/grafana.mdx | 4 + apps/docs/integrations/neon.mdx | 4 + apps/docs/integrations/sentry.mdx | 4 + apps/docs/integrations/snowflake.mdx | 4 + apps/docs/integrations/supabase.mdx | 4 + apps/docs/skills.mdx | 3 + 16 files changed, 593 insertions(+) create mode 100644 apps/docs/cookbook/ci-failure-auto-fix.mdx create mode 100644 apps/docs/cookbook/index.mdx create mode 100644 apps/docs/cookbook/product-updates-newsletter.mdx create mode 100644 apps/docs/cookbook/scheduled-housekeeping.mdx create mode 100644 apps/docs/cookbook/support-channel.mdx create mode 100644 apps/docs/cookbook/template.mdx create mode 100644 apps/docs/cookbook/vendor-outage-triage.mdx diff --git a/apps/docs/automations.mdx b/apps/docs/automations.mdx index 185bc476a..7cfe5e0dc 100644 --- a/apps/docs/automations.mdx +++ b/apps/docs/automations.mdx @@ -93,6 +93,11 @@ automation to test it immediately. The deployment cap is 25 custom automations. +See [Put maintenance on a schedule and off your mind](/cookbook/scheduled-housekeeping) +for three copyable custom automation prompts, or +[draft a product-updates newsletter](/cookbook/product-updates-newsletter) with +a custom MCP server and a natural-language schedule. + The **Scheduling timezone** setting is available on both the Automations and Deployment settings pages. It applies to all scheduled automations and to natural-language schedule interpretation. Existing deployments continue using @@ -136,6 +141,10 @@ Start with a low-risk channel first. Auto-response can feel noisy if the channel mixes casual discussion with requests that should become Roomote tasks. +See how channel instructions and launch criteria work together in the +[vendor outage triage](/cookbook/vendor-outage-triage) and +[support channel](/cookbook/support-channel) recipes. + ## Manager automations The manager section controls the shared Manager Channel plus recurring @@ -228,6 +237,9 @@ For Gitea, repository webhook resync includes the `workflow_run` event so Actions completions reach Roomote; host matching uses the deployment `GITEA_BASE_URL`. +Follow the [CI failure auto-fix recipe](/cookbook/ci-failure-auto-fix) for a +copyable noise-control configuration. + ## Add instructions to reduce noise Several automations include an **Additional instructions** field. Use it to diff --git a/apps/docs/cookbook/ci-failure-auto-fix.mdx b/apps/docs/cookbook/ci-failure-auto-fix.mdx new file mode 100644 index 000000000..e729f5391 --- /dev/null +++ b/apps/docs/cookbook/ci-failure-auto-fix.mdx @@ -0,0 +1,64 @@ +--- +title: Turn a red default branch into a fix PR +description: Have Roomote verify persistent default-branch CI failures, reproduce them, and open a focused fix PR. +icon: git-pull-request +--- + +`Webhook` · `Setup: about 10 minutes` · `Requires: admin, source control, Manager Channel` · `Serves: engineers` + +When CI fails on your default branch, Roomote reacts immediately. It checks +that the failure is real, reproduces the failing job inside the repository's +environment, finds the root cause, opens a PR with the fix, and posts one +summary to the Manager Channel. The team finds a green PR waiting instead of a +red branch. This is a built-in automation, so the recipe is one toggle plus +clear instructions. + +## Ingredients + +- [CI Failure Triage](/automations#manager-automations) +- A Manager Channel destination configured under **Automation output** +- An environment for every repository you want triaged. Repositories outside an environment are skipped. + +## Steps + +1. Set the Manager Channel under **Settings > Automations > Automation output**. +2. Enable **CI Failure Triage**. +3. Confirm each repository you care about belongs to a configured environment. +4. Add the noise-control instructions below. +5. Use **Run now** to test the configuration, or wait for the next default-branch failure. + +## Additional instructions + +Paste this into the automation's **Additional instructions** field: + +```text +Only triage failures in build and test jobs. Ignore the nightly performance +suite and deploy jobs; deploys are handled by on-call. + +Treat a failure as persistent if the same job also failed in the previous run. + +Prefer the smallest change that makes CI green. Never skip, disable, or delete +a test to get there. If the test is wrong, fix the test and say so in the PR +description. +``` + +## When it fires + +> **Roomote** (`#roomote-managers`): **CI failure on `main` fixed.** `typecheck` +> failed after a component's props were renamed. I reproduced it in the web +> environment and found a stale import in the task list. Opened **PR #1033** +> with the two-line fix; typecheck and the affected tests pass. The failure +> persisted across two runs, so it was not a flake. + +## Variations + +- Keep experimental repositories out of environments to exclude them from triage. +- Route the summary to a dedicated `#ci-triage` channel instead of the shared Manager Channel. + +CI Failure Triage reacts only to failures on the default branch. It supports +GitHub Actions, GitLab Pipelines, Azure DevOps builds, Bitbucket Pipelines, and +Gitea Actions. GitLab requires Pipeline Hooks on the webhook, and Bitbucket +requires the Pipelines OAuth scope. + +**Pairs well with:** [scheduled housekeeping](/cookbook/scheduled-housekeeping) · +[vendor outage triage](/cookbook/vendor-outage-triage) diff --git a/apps/docs/cookbook/index.mdx b/apps/docs/cookbook/index.mdx new file mode 100644 index 000000000..779b81d9d --- /dev/null +++ b/apps/docs/cookbook/index.mdx @@ -0,0 +1,37 @@ +--- +title: Cookbook +icon: cooking-pot +description: Copyable recipes for turning Roomote automations, skills, and integrations into standing team systems. +--- + +A recipe is a complete, copyable way to combine Roomote features around an +outcome your team wants to keep achieving. Each one includes the ingredients, +setup steps, paste-ready configuration, and an example of what happens when it +runs. Start with the recipe closest to an existing team habit, test it with real +inputs, and tune the instructions as your process changes. + + + + Compare vendor incidents with the services, regions, and features your code + actually uses. + + + Give support escalations a repeatable, evidence-backed triage path. + + + Reproduce persistent CI failures and leave the team with a reviewable fix. + + + Turn merged product work into a customer-ready Resend draft every week. + + + Give recurring engineering chores a prompt, cadence, and replyable report. + + + +## Contribute a recipe + +Have a Roomote workflow other teams could reuse? Start with the +[recipe template](/cookbook/template), fill in every section, and open a normal +pull request. Keep credentials and private operational details out of the +example, and state permissions and limitations plainly. diff --git a/apps/docs/cookbook/product-updates-newsletter.mdx b/apps/docs/cookbook/product-updates-newsletter.mdx new file mode 100644 index 000000000..118718f5a --- /dev/null +++ b/apps/docs/cookbook/product-updates-newsletter.mdx @@ -0,0 +1,76 @@ +--- +title: Send a product-updates newsletter written from what actually shipped +description: Turn the week's merged product work into a customer-ready Resend draft on a schedule. +icon: mail +--- + +`Schedule` · `Setup: about 30 minutes` · `Requires: admin, custom Resend MCP server` · `Serves: PMs, founders, marketing` + +Product-update emails are chronically late because someone has to remember what +shipped, translate commit-speak into customer language, and then fight the +email tool. This automation does all three: every week it reads merged PRs +across your product repositories, writes the newsletter, and creates a draft in +Resend through a custom MCP server, ready for review. This is based on Bruno's +setup at Roo. + +## Ingredients + +- A [custom automation](/automations#custom-automations) +- An environment covering the product repositories +- A custom Resend MCP server configured under **Settings > Integrations**, with a Resend API key +- A report destination such as `#product-updates`, so the draft lands in a replyable thread + +## Steps + +1. Add the Resend MCP server as a custom integration and confirm its tools are available in the environment. +2. Create a custom automation named **Product Updates Newsletter**. Choose **Custom schedule**, enter `Mondays at 9am`, and select the environment. +3. Paste the prompt below. +4. Set the report destination to `#product-updates`. +5. Use **Run now** to generate the first draft, then calibrate its tone by replying in the thread. + +## Automation prompt + +```text +Write this week's product-updates newsletter. + +1. Collect the PRs merged to the default branch in the last 7 days across the + product repositories. +2. Keep only customer-visible changes: features, improvements, and fixes a + user would notice. Skip refactors, internal tooling, and dependency bumps. +3. Write the newsletter: + - a one-line subject + - a two-sentence introduction + - one short section per change: what is new, why it matters, how to try it + Use plain language. Do not include ticket numbers or internal codenames. +4. Using the Resend MCP server, create a DRAFT broadcast with this content for + the "Product updates" audience. Do not send it. +5. Post the draft content and the Resend draft link in this thread for review. + +If nothing customer-visible shipped this week, say so in the thread and skip +the draft. Do not pad the newsletter. +``` + +## When it fires + +> **Roomote** (`#product-updates`): **This week's newsletter draft is ready.** +> Three customer-visible changes: scheduling timezones for automations, Discord +> forum-channel support, and faster environment starts. Draft created in Resend +> but not sent. Reply here with edits, or send it directly from Resend. +> +> **Bruno:** Lead with the timezone setting, and mention that it applies to +> existing automations too. +> +> **Roomote:** Reordered and updated the Resend draft. The timezone section now +> opens the email and notes that it applies retroactively. Same draft link. + +## Variations + +- Without Resend, remove step 4 and post ready-to-paste Markdown for any email tool. +- Run monthly with `first Monday of the month at 9am`. +- Use separate automations for customer notes and a technical internal changelog. + +This recipe showcases custom MCP servers, natural-language scheduling, and +replyable automation threads. Review the draft before sending it; the automation +is deliberately instructed to create a draft, not send a broadcast. + +**Pairs well with:** [scheduled housekeeping](/cookbook/scheduled-housekeeping) diff --git a/apps/docs/cookbook/scheduled-housekeeping.mdx b/apps/docs/cookbook/scheduled-housekeeping.mdx new file mode 100644 index 000000000..38d8e4571 --- /dev/null +++ b/apps/docs/cookbook/scheduled-housekeeping.mdx @@ -0,0 +1,88 @@ +--- +title: Put maintenance on a schedule and off your mind +description: Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. +icon: calendar-check +--- + +`Schedule` · `Setup: about 15 minutes` · `Requires: admin` · `Serves: engineers, leads` + +Every team has maintenance work that only happens when someone feels guilty: +flaky tests, stale feature flags, and aging dependencies. A custom automation +turns each chore into a standing appointment: a prompt, a cadence, and a channel +where results land in a replyable thread. Once you have built one, you will +start spotting more work that fits the pattern. + +## Ingredients + +- One [custom automation](/automations#custom-automations) per chore, within the deployment cap of 25 +- One environment per automation +- A report destination such as `#eng-maintenance` + +## Steps + +1. Under **Settings > Automations > Custom automations**, create an automation. +2. Pick a prompt below, choose a cadence, and select the environment. Natural-language schedules such as `weekdays at 9am` are supported under **Custom schedule**. +3. Set a report destination so results become a conversation rather than a log line. +4. Use **Run now** to check the first report, then let the schedule take over. +5. Reply in the thread to steer a run, for example `Open the PR for item 2`, without changing the automation. + +## Prompt: flaky tests + +Run weekly: + +```text +Find flaky tests. Look at recent CI runs for tests that failed and then passed +with no related code change. For each suspect, read the test and identify the +likely cause: timing, shared state, network, or ordering. Report the top 3 with +evidence. If one has an obvious, safe fix, open a PR for that one only. +``` + +## Prompt: stale feature flags + +Run weekly or monthly: + +```text +Audit feature flags. List every flag defined in the codebase. Flag the ones +that are fully rolled out and effectively always on, referenced nowhere, or +whose code paths are dead. Report which can be removed and what removing them +simplifies. Open a cleanup PR for at most one clearly dead flag per run. +``` + +## Prompt: dependency review + +Run weekly: + +```text +Review our dependencies for updates worth taking: security patches first, +then major versions of core frameworks. For each candidate, summarize what +changed upstream and the migration risk for our codebase specifically. Do not +open PRs. End with a ranked shortlist of updates worth scheduling this sprint. +``` + +## When it fires + +> **Roomote** (`#eng-maintenance`): **Weekly flaky-test report: two suspects.** +> 1. `task-queue.test.ts` > `retries stale jobs` failed in three recent runs +> with no related changes. It races a real timer against queue polling. Opened +> **PR #1041** replacing the sleep with a fake timer. +> 2. `preview-proxy.test.ts` > `streams logs` failed twice because a fixed port +> collides with parallel CI shards. Decision needed: random port or dedicated +> shard. Reply if you want the PR. +> +> **Dana:** Random port, please. Open the PR. +> +> **Roomote:** Opened **PR #1042** to bind the test proxy to an ephemeral port +> and pass its address through. Both flaky suspects now have fixes. + +## Variations + +- Create a Monday briefing that summarizes open PRs, stale branches, and work waiting on review. +- Compare `apps/docs` with customer-visible changes shipped in the last week and report documentation drift. +- Use a model override for heavyweight audits and the deployment default for cheaper checks. + +Custom automations also support five-field cron expressions, **Run now**, and +replyable result threads. Without a report destination, runs are silent and +their results appear only in the task view. + +**Pairs well with:** [CI failure auto-fix](/cookbook/ci-failure-auto-fix) · +[product-updates newsletter](/cookbook/product-updates-newsletter) diff --git a/apps/docs/cookbook/support-channel.mdx b/apps/docs/cookbook/support-channel.mdx new file mode 100644 index 000000000..780b75d6a --- /dev/null +++ b/apps/docs/cookbook/support-channel.mdx @@ -0,0 +1,116 @@ +--- +title: Resolve customer issues before an engineer sees them +description: Give support escalations a repeatable path through production evidence, data, and code. +icon: headset +--- + +`Channel event` · `Setup: about 45 minutes` · `Requires: admin, Slack or Discord, observability or data integration` · `Serves: support, engineers` + +Customer-facing teams post escalations into an operations channel, often from a +ticketing system. A custom skill teaches Roomote your triage procedure: check +logs, inspect data, read code, and classify the problem as a product bug, a +data-state issue, or expected behavior. Roomote answers in the thread with +evidence, and a PR when the resolution is a code fix. Engineers only see what +survives triage. + +## Ingredients + +- A channel receiving support escalations, such as `#support-inbound`, with Roomote invited +- [Auto-respond channels](/automations#channel-automations), or a ticketing workflow that mentions Roomote +- A [custom skill](/skills#when-to-use-a-custom-skill), enabled for the product environment +- Observability and data integrations such as [Sentry](/integrations/sentry), [Grafana](/integrations/grafana), [Better Stack](/integrations/better-stack), [Supabase](/integrations/supabase), [Neon](/integrations/neon), or [Snowflake](/integrations/snowflake), or a custom MCP server for your stack +- An environment for the product repositories, with read-only production credentials where integrations do not cover the required system + +## Steps + +1. Connect the integrations your triage needs under **Settings > Integrations**. +2. Under **Settings > Skills**, add the custom skill below and enable it for the environment your product runs in. +3. Add the escalation channel under **Settings > Automations > Auto-respond to channels** and paste the launch criteria. +4. Repost a resolved historical ticket and compare Roomote's triage with what actually happened. +5. Tighten the skill with what you learn. The skill is the control you will keep tuning. + +## Custom skill + +Create a custom skill with these field values. The Roomote UI stores the slug, +description, and content separately. + +**Slug** + +```text +support-investigation +``` + +**Description** + +```text +Use when a customer issue or support escalation needs triage: classify it as a +product bug, a data-state problem, or expected behavior, then resolve it or +prepare the escalation. +``` + +**Content** + +```markdown +When a support escalation arrives: + +1. Restate the problem: which customer, which feature, what they expected, + and what actually happened. +2. Check errors first: search Sentry for exceptions matching the feature and + time window. Note anything correlated. +3. Check the data: query the production database with read-only access to + inspect the customer's relevant records. Never write to production. +4. Read the code path involved, then classify: + - Product bug: implement the fix and open a PR; link it in the thread. + - Data-state problem: identify the exact records and describe the + corrective action for an operator. Do not modify data yourself. + - Expected behavior or user error: draft a reply the support agent can + send, citing the relevant docs. +5. Reply in the thread with the classification, evidence (queries run, error + links, and code references), and the PR, proposed data fix, or reply draft. + +Escalate to an engineer only when the fix needs a product decision or a +production data change. +``` + +## Launch criteria + +```text +Launch for messages describing a specific customer-reported problem or support +escalation, usually posted by the ticketing bot or a support teammate. + +Do not launch for general questions, internal discussion, status updates on +tickets already being worked, or messages that only link a ticket without +describing the problem. + +If an earlier message about the same ticket already launched, launch again +only if the customer reports the problem recurring after it was thought +resolved. +``` + +## When it fires + +> **Ticketbot** (app, `#support-inbound`): ACME-4321 · Priority: High. Customer +> reports the Q3 CSV export downloads as an empty file. Started yesterday. +> +> **Roomote** (in thread): **Data-state problem, not a bug.** The export +> pipeline ran clean, but this workspace's Q3 report rows are soft-deleted. The +> export correctly renders zero rows. +> +> **Fix for an operator:** restore the affected report rows after confirming +> with the customer. **Draft reply:** "The Q3 rows were deleted by a workspace +> admin. We can restore them; reply to confirm." + +## Variations + +- Ask Roomote to propose, but not run, a data-repair script as a reviewed PR against an operations repository. +- Create separate skills by product area, each with a sharper description so the right one activates. +- On Teams, have the ticketing workflow mention Roomote and name `support-investigation`; auto-respond is not available there today. + +This recipe is most valuable with real log and read-only database access. Grant +scoped, read-only credentials through integrations or environment variables. +The skill says never to write to production; admins should also enforce the +boundary with database roles and MCP tool policies. A prompt is not a security +boundary. + +**Pairs well with:** [vendor outage triage](/cookbook/vendor-outage-triage) · +[CI failure auto-fix](/cookbook/ci-failure-auto-fix) diff --git a/apps/docs/cookbook/template.mdx b/apps/docs/cookbook/template.mdx new file mode 100644 index 000000000..4de4dd647 --- /dev/null +++ b/apps/docs/cookbook/template.mdx @@ -0,0 +1,63 @@ +--- +title: Recipe template +description: A contributor-ready skeleton for documenting a reusable Roomote system. +icon: file-text +--- + +Use this skeleton when contributing a Cookbook recipe. Replace every placeholder +and remove the comments before opening a pull request. If the recipe comes from +another team, add a short attribution after the metadata line, such as +`Recipe from the team at Example.` + +````markdown +--- +title: Outcome-first recipe title +description: One sentence explaining the finished system and why it matters. +icon: lucide-icon-name +--- + +`Trigger` · `Setup: about N minutes` · `Requires: ...` · `Serves: ...` + + + +## Ingredients + + + +- Ingredient + +## Steps + + + +1. First step. + +## Paste-ready configuration + + + +```text +Configuration or prompt +``` + +## When it fires + + + +> **Source:** Trigger message +> +> **Roomote:** Evidence-backed result + +## Variations + + + +- Variation + + + +**Pairs well with:** [Related recipe](/cookbook/example) +```` + +Before submitting, test every paste block against the current product and make +sure the recipe never relies on a prompt alone to enforce a security boundary. diff --git a/apps/docs/cookbook/vendor-outage-triage.mdx b/apps/docs/cookbook/vendor-outage-triage.mdx new file mode 100644 index 000000000..321bc41e5 --- /dev/null +++ b/apps/docs/cookbook/vendor-outage-triage.mdx @@ -0,0 +1,98 @@ +--- +title: Know within minutes whether a vendor outage affects you +description: Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. +icon: siren +--- + +`Channel event` · `Setup: about 20 minutes` · `Requires: admin, Slack or Discord` · `Serves: on-call, support` + +Every vendor you depend on publishes status updates, and almost none of them +affect you, until one does. Pipe them into one channel and let Roomote read each +incident against your actual code: which SDKs you call, which regions you run +in, and which features you use. You stop triaging vendor noise by hand and only +hear about the outages that matter. This is how we run it at Roo. + +## Ingredients + +- A Slack or Discord channel such as `#vendor-status` receiving vendor status + feeds. Most vendors offer Subscribe via Slack, RSS-to-channel, or + email-to-channel. +- [Auto-respond channels](/automations#channel-automations) +- An [environment](/environments) covering the repositories that use these + vendors +- Roomote invited to the channel on Slack, or able to see it on Discord + +## Steps + +1. Create `#vendor-status` and subscribe it to every upstream status page you care about. +2. Invite Roomote to the channel. +3. Under **Settings > Automations > Auto-respond to channels**, add the channel. +4. Paste the launch criteria and instructions below. +5. Post a fake incident and confirm a task launches. Then post a scheduled-maintenance notice and confirm it does not. + +## Launch criteria + +Paste this into the channel's **Launch criteria** field: + +```text +Launch only for messages reporting a new incident, a worsening incident, or an +incident that regressed after being resolved, from one of our upstream vendors. + +Do not launch for scheduled-maintenance announcements, "monitoring" or +"resolved" updates to an incident already investigated, changelog or marketing +posts, or duplicate notifications about the same incident. + +Treat a message as an escalation when it adds affected components, expands +impact, or reports a worse status than before. When unsure whether an incident +could plausibly touch something we depend on in production, launch: a wasted +check is cheaper than a missed outage. +``` + +## Instructions + +Paste this into the channel's **Instructions** field. Roomote gives these +instructions to every task launched from the channel. + +```text +A vendor has posted a status incident. Determine whether it affects us: + +1. Identify the vendor and the affected components, regions, and features + from the message. +2. Search the codebase for how we actually use this vendor: SDKs, API + endpoints, features, and regions we depend on. +3. Compare our real usage against what the incident says is affected. +4. Reply in the thread with a clear verdict: + - "Affects us": which features or code paths, likely user impact, and a + suggested action. + - "Safe to ignore": why our usage is not touched. + +Keep it short. The on-call engineer reads this thread. Do not page anyone. +``` + +## When it fires + +> **Acme Status** (app, `#vendor-status`): Investigating: elevated error rates +> on Object Storage API (`us-east-1`). Some requests may fail with 5xx. +> +> **Roomote** (in thread): **Safe to ignore.** We use Acme Object Storage only +> in `eu-west-1`; the affected `us-east-1` endpoints are not referenced in the +> codebase. Uploads and signed URLs are unaffected. No action needed. +> +> **Acme Status** (app): Update: impact expanded to CDN edge in EU regions. +> +> **Roomote** (in thread): **Affects us.** EU CDN edge is now impacted. Public +> asset delivery routes through Acme CDN, so users may see slow or missing +> images. Suggested action: serve assets from origin until the incident is +> resolved. + +## Variations + +- Name the vendors explicitly in the criteria to ignore feeds subscribed to just in case. +- Ask Roomote to describe how to verify recovery whenever the verdict is **Affects us**. +- Use a multi-repository environment so the usage search covers every service. + +Auto-respond channels support Slack and Discord today. On Teams or Telegram, +forward status events to a supported channel or mention Roomote from a workflow. + +**Pairs well with:** [CI failure auto-fix](/cookbook/ci-failure-auto-fix) · +[support channel](/cookbook/support-channel) diff --git a/apps/docs/docs.json b/apps/docs/docs.json index b9229ce28..883789ee3 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -48,6 +48,18 @@ "group": "Using Roomote", "pages": ["how-roomote-works", "use-cases", "tasks", "file-attachments"] }, + { + "group": "Cookbook", + "pages": [ + "cookbook/index", + "cookbook/vendor-outage-triage", + "cookbook/support-channel", + "cookbook/ci-failure-auto-fix", + "cookbook/product-updates-newsletter", + "cookbook/scheduled-housekeeping", + "cookbook/template" + ] + }, { "group": "Provider Configuration", "pages": [ diff --git a/apps/docs/integrations/better-stack.mdx b/apps/docs/integrations/better-stack.mdx index 7778e3eef..c0866589f 100644 --- a/apps/docs/integrations/better-stack.mdx +++ b/apps/docs/integrations/better-stack.mdx @@ -23,3 +23,7 @@ Admins connect Better Stack once from **Settings > Integrations**. Roomote uses Better Stack as task context for investigation and triage. Code changes, validation, and review still happen through the normal Roomote task and repository workflow. + +## Recipes using this + +- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) diff --git a/apps/docs/integrations/grafana.mdx b/apps/docs/integrations/grafana.mdx index c1147bdd0..74a1c1698 100644 --- a/apps/docs/integrations/grafana.mdx +++ b/apps/docs/integrations/grafana.mdx @@ -25,3 +25,7 @@ instance URL and a shared service account token. The current Grafana integration is read-only. It gives Roomote monitoring context during a task, but it does not create dashboards, edit alerts, or change Grafana configuration. + +## Recipes using this + +- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) diff --git a/apps/docs/integrations/neon.mdx b/apps/docs/integrations/neon.mdx index e7236bcf8..5709f7b60 100644 --- a/apps/docs/integrations/neon.mdx +++ b/apps/docs/integrations/neon.mdx @@ -23,3 +23,7 @@ need it. Neon gives Roomote database context inside the task. Keep any repository changes and human review on the normal Roomote and Git workflow. + +## Recipes using this + +- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) diff --git a/apps/docs/integrations/sentry.mdx b/apps/docs/integrations/sentry.mdx index bd4e5c7c9..eee2c6947 100644 --- a/apps/docs/integrations/sentry.mdx +++ b/apps/docs/integrations/sentry.mdx @@ -22,3 +22,7 @@ Admins connect Sentry once from **Settings > Integrations**. Sentry gives Roomote incident and performance context during a task. It can also support scheduled read-only Sentry triage. The final decision, code change, and review still happen in the normal task and repository flow. + +## Recipes using this + +- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) diff --git a/apps/docs/integrations/snowflake.mdx b/apps/docs/integrations/snowflake.mdx index 1490ab1c0..ffa6e0d9f 100644 --- a/apps/docs/integrations/snowflake.mdx +++ b/apps/docs/integrations/snowflake.mdx @@ -32,3 +32,7 @@ when the key is encrypted. Snowflake provides shared data warehouse context inside Roomote tasks. Engineering changes and approvals still happen through your normal task and repository review flow. + +## Recipes using this + +- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) diff --git a/apps/docs/integrations/supabase.mdx b/apps/docs/integrations/supabase.mdx index fbc8ec20e..96443e96e 100644 --- a/apps/docs/integrations/supabase.mdx +++ b/apps/docs/integrations/supabase.mdx @@ -23,3 +23,7 @@ when they need it. Supabase gives Roomote read-only database context during a task. Code changes, migrations, and review still go through your normal engineering workflow. + +## Recipes using this + +- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) diff --git a/apps/docs/skills.mdx b/apps/docs/skills.mdx index 91318deca..d8be6d2fd 100644 --- a/apps/docs/skills.mdx +++ b/apps/docs/skills.mdx @@ -47,6 +47,9 @@ Good custom skills include: - a database migration review guide - a customer-escalation triage playbook +The [support channel recipe](/cookbook/support-channel) shows a complete custom +skill with launch criteria and a production-safe investigation flow. + If the instruction is only one sentence, it probably belongs in [Agent Guidance](/agent-guidance), [environment guidance](/environments), or the task prompt instead. From 590eac8c3fe27c88277448926eed3122b4e379f9 Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 17:31:31 +0100 Subject: [PATCH 02/13] docs: add cookbook recipe issue flow --- .github/ISSUE_TEMPLATE/cookbook-recipe.yml | 52 ++++++++++++++++++++++ apps/docs/cookbook/index.mdx | 16 +++---- apps/docs/cookbook/template.mdx | 14 +++--- apps/docs/docs.json | 10 +---- 4 files changed, 68 insertions(+), 24 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/cookbook-recipe.yml diff --git a/.github/ISSUE_TEMPLATE/cookbook-recipe.yml b/.github/ISSUE_TEMPLATE/cookbook-recipe.yml new file mode 100644 index 000000000..b23616f9d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/cookbook-recipe.yml @@ -0,0 +1,52 @@ +name: Cookbook recipe +description: Propose a reusable Roomote workflow for the public Cookbook. +title: "[Cookbook]: " +labels: ["documentation", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Use this form to propose a complete, reusable Roomote workflow for the Cookbook. + Start with the [contributing recipes guide](https://docs.roomote.dev/cookbook/template), + paste the completed recipe below, and keep credentials, customer data, and + private operational details out of the example. + - type: checkboxes + id: preflight + attributes: + label: Preflight + options: + - label: I searched the existing Cookbook and docs for a duplicate or closely related recipe. + required: true + - label: I removed secrets, tokens, private keys, customer data, and private repository details. + required: true + - label: I stated provider support, permission boundaries, and other limitations plainly. + required: true + - type: textarea + id: recipe + attributes: + label: Recipe + description: Paste the completed Markdown recipe from the contributing recipes guide. + placeholder: | + --- + title: Outcome-first recipe title + description: One sentence explaining the finished system and why it matters. + icon: lucide-icon-name + --- + + Describe the recipe here... + validations: + required: true + - type: textarea + id: validation + attributes: + label: Validation and limitations + description: Explain what you tested, which providers or integrations it requires, and any known limitations. + validations: + required: true + - type: input + id: attribution + attributes: + label: Attribution + description: If this recipe comes from another team, name them here. Otherwise leave this blank. + validations: + required: false diff --git a/apps/docs/cookbook/index.mdx b/apps/docs/cookbook/index.mdx index 779b81d9d..9be49e931 100644 --- a/apps/docs/cookbook/index.mdx +++ b/apps/docs/cookbook/index.mdx @@ -4,11 +4,9 @@ icon: cooking-pot description: Copyable recipes for turning Roomote automations, skills, and integrations into standing team systems. --- -A recipe is a complete, copyable way to combine Roomote features around an -outcome your team wants to keep achieving. Each one includes the ingredients, -setup steps, paste-ready configuration, and an example of what happens when it -runs. Start with the recipe closest to an existing team habit, test it with real -inputs, and tune the instructions as your process changes. +Roomote's abilities go way beyond ad hoc prompt → PR interactions. With integrations and automations, you can put many of your team's workflows on autopilot, from investigation to resolution and beyond. + +This cookbook collects proven recipets to help you boost your team's productivity and the quality of your output. @@ -31,7 +29,7 @@ inputs, and tune the instructions as your process changes. ## Contribute a recipe -Have a Roomote workflow other teams could reuse? Start with the -[recipe template](/cookbook/template), fill in every section, and open a normal -pull request. Keep credentials and private operational details out of the -example, and state permissions and limitations plainly. +Have a Roomote workflow other teams could reuse? Start with +[contributing recipes](/cookbook/template), fill in every section, and open a +[Cookbook recipe issue](https://github.com/RooCodeInc/Roomote/issues/new?template=cookbook-recipe.yml) +on the Roomote repository. diff --git a/apps/docs/cookbook/template.mdx b/apps/docs/cookbook/template.mdx index 4de4dd647..6a6e1d0d2 100644 --- a/apps/docs/cookbook/template.mdx +++ b/apps/docs/cookbook/template.mdx @@ -1,12 +1,14 @@ --- -title: Recipe template -description: A contributor-ready skeleton for documenting a reusable Roomote system. -icon: file-text +title: Contributing recipes +description: Propose a reusable Roomote system for the Cookbook through a repository issue. +icon: plus --- -Use this skeleton when contributing a Cookbook recipe. Replace every placeholder -and remove the comments before opening a pull request. If the recipe comes from -another team, add a short attribution after the metadata line, such as +Use this skeleton when proposing a Cookbook recipe. Replace every placeholder +and remove the comments before opening a +[Cookbook recipe issue](https://github.com/RooCodeInc/Roomote/issues/new?template=cookbook-recipe.yml). +Do not open a pull request unless a maintainer invites you to. If the recipe +comes from another team, add a short attribution after the metadata line, such as `Recipe from the team at Example.` ````markdown diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 883789ee3..c369d0646 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -50,15 +50,7 @@ }, { "group": "Cookbook", - "pages": [ - "cookbook/index", - "cookbook/vendor-outage-triage", - "cookbook/support-channel", - "cookbook/ci-failure-auto-fix", - "cookbook/product-updates-newsletter", - "cookbook/scheduled-housekeeping", - "cookbook/template" - ] + "pages": ["cookbook/index", "cookbook/template"] }, { "group": "Provider Configuration", From 0eea9c5473c17040cbd3b60e9fc407e057c9f2ca Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 17:39:11 +0100 Subject: [PATCH 03/13] docs: refine cookbook recipes --- .github/ISSUE_TEMPLATE/cookbook-recipe.yml | 27 ++++++++++++++++-- apps/docs/automations.mdx | 2 +- apps/docs/cookbook/ci-failure-auto-fix.mdx | 9 +++++- apps/docs/cookbook/index.mdx | 28 ++++++------------- .../cookbook/product-updates-newsletter.mdx | 9 +++++- apps/docs/cookbook/scheduled-housekeeping.mdx | 9 +++++- apps/docs/cookbook/support-channel.mdx | 9 +++++- apps/docs/cookbook/template.mdx | 9 ++++++ apps/docs/cookbook/vendor-outage-triage.mdx | 9 +++++- apps/docs/integrations/better-stack.mdx | 2 +- apps/docs/integrations/grafana.mdx | 2 +- apps/docs/integrations/neon.mdx | 2 +- apps/docs/integrations/sentry.mdx | 2 +- apps/docs/integrations/snowflake.mdx | 2 +- apps/docs/integrations/supabase.mdx | 2 +- 15 files changed, 89 insertions(+), 34 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/cookbook-recipe.yml b/.github/ISSUE_TEMPLATE/cookbook-recipe.yml index b23616f9d..8dc3f1b35 100644 --- a/.github/ISSUE_TEMPLATE/cookbook-recipe.yml +++ b/.github/ISSUE_TEMPLATE/cookbook-recipe.yml @@ -44,9 +44,30 @@ body: validations: required: true - type: input - id: attribution + id: contributor attributes: - label: Attribution - description: If this recipe comes from another team, name them here. Otherwise leave this blank. + label: Contributor + description: Name the person or team contributing this recipe. + validations: + required: true + - type: input + id: contributor_url + attributes: + label: Contributor URL + description: Link to the contributor's public profile or website, if available. + validations: + required: false + - type: input + id: contributor_company + attributes: + label: Contributor company + description: Name of the contributor's company, if applicable. + validations: + required: false + - type: input + id: contributor_company_url + attributes: + label: Contributor company URL + description: Link to the contributor's company website, if available. validations: required: false diff --git a/apps/docs/automations.mdx b/apps/docs/automations.mdx index 7cfe5e0dc..fdcb6e86a 100644 --- a/apps/docs/automations.mdx +++ b/apps/docs/automations.mdx @@ -93,7 +93,7 @@ automation to test it immediately. The deployment cap is 25 custom automations. -See [Put maintenance on a schedule and off your mind](/cookbook/scheduled-housekeeping) +See [Schedule maintenance](/cookbook/scheduled-housekeeping) for three copyable custom automation prompts, or [draft a product-updates newsletter](/cookbook/product-updates-newsletter) with a custom MCP server and a natural-language schedule. diff --git a/apps/docs/cookbook/ci-failure-auto-fix.mdx b/apps/docs/cookbook/ci-failure-auto-fix.mdx index e729f5391..f3c6409cc 100644 --- a/apps/docs/cookbook/ci-failure-auto-fix.mdx +++ b/apps/docs/cookbook/ci-failure-auto-fix.mdx @@ -1,11 +1,18 @@ --- -title: Turn a red default branch into a fix PR +title: Fix CI failures description: Have Roomote verify persistent default-branch CI failures, reproduce them, and open a focused fix PR. icon: git-pull-request +contributor: Bruno +contributor_url: https://github.com/brunobergher +contributor_company: Roomote +contributor_company_url: https://roomote.dev --- `Webhook` · `Setup: about 10 minutes` · `Requires: admin, source control, Manager Channel` · `Serves: engineers` +**Contributor:** [Bruno](https://github.com/brunobergher) +**Contributor company:** [Roomote](https://roomote.dev) + When CI fails on your default branch, Roomote reacts immediately. It checks that the failure is real, reproduces the failing job inside the repository's environment, finds the root cause, opens a PR with the fix, and posts one diff --git a/apps/docs/cookbook/index.mdx b/apps/docs/cookbook/index.mdx index 9be49e931..9a55f68f8 100644 --- a/apps/docs/cookbook/index.mdx +++ b/apps/docs/cookbook/index.mdx @@ -6,26 +6,16 @@ description: Copyable recipes for turning Roomote automations, skills, and integ Roomote's abilities go way beyond ad hoc prompt → PR interactions. With integrations and automations, you can put many of your team's workflows on autopilot, from investigation to resolution and beyond. -This cookbook collects proven recipets to help you boost your team's productivity and the quality of your output. +This cookbook collects proven recipes to help you boost your team's productivity +and the quality of your output. - - - Compare vendor incidents with the services, regions, and features your code - actually uses. - - - Give support escalations a repeatable, evidence-backed triage path. - - - Reproduce persistent CI failures and leave the team with a reviewable fix. - - - Turn merged product work into a customer-ready Resend draft every week. - - - Give recurring engineering chores a prompt, cadence, and replyable report. - - +| Recipe | Description | Contributor | Contributor company | +| --- | --- | --- | --- | +| [Check vendor outages](/cookbook/vendor-outage-triage) | Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. | [Bruno](https://github.com/brunobergher) | [Roomote](https://roomote.dev) | +| [Triage customer issues](/cookbook/support-channel) | Give support escalations a repeatable path through production evidence, data, and code. | [Bruno](https://github.com/brunobergher) | [Roomote](https://roomote.dev) | +| [Fix CI failures](/cookbook/ci-failure-auto-fix) | Have Roomote verify persistent default-branch CI failures, reproduce them, and open a focused fix PR. | [Bruno](https://github.com/brunobergher) | [Roomote](https://roomote.dev) | +| [Draft product updates](/cookbook/product-updates-newsletter) | Turn the week's merged product work into a customer-ready Resend draft on a schedule. | [Bruno](https://github.com/brunobergher) | [Roomote](https://roomote.dev) | +| [Schedule maintenance](/cookbook/scheduled-housekeeping) | Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. | [Bruno](https://github.com/brunobergher) | [Roomote](https://roomote.dev) | ## Contribute a recipe diff --git a/apps/docs/cookbook/product-updates-newsletter.mdx b/apps/docs/cookbook/product-updates-newsletter.mdx index 118718f5a..1ffc82c66 100644 --- a/apps/docs/cookbook/product-updates-newsletter.mdx +++ b/apps/docs/cookbook/product-updates-newsletter.mdx @@ -1,11 +1,18 @@ --- -title: Send a product-updates newsletter written from what actually shipped +title: Draft product updates description: Turn the week's merged product work into a customer-ready Resend draft on a schedule. icon: mail +contributor: Bruno +contributor_url: https://github.com/brunobergher +contributor_company: Roomote +contributor_company_url: https://roomote.dev --- `Schedule` · `Setup: about 30 minutes` · `Requires: admin, custom Resend MCP server` · `Serves: PMs, founders, marketing` +**Contributor:** [Bruno](https://github.com/brunobergher) +**Contributor company:** [Roomote](https://roomote.dev) + Product-update emails are chronically late because someone has to remember what shipped, translate commit-speak into customer language, and then fight the email tool. This automation does all three: every week it reads merged PRs diff --git a/apps/docs/cookbook/scheduled-housekeeping.mdx b/apps/docs/cookbook/scheduled-housekeeping.mdx index 38d8e4571..bbf37ba84 100644 --- a/apps/docs/cookbook/scheduled-housekeeping.mdx +++ b/apps/docs/cookbook/scheduled-housekeeping.mdx @@ -1,11 +1,18 @@ --- -title: Put maintenance on a schedule and off your mind +title: Schedule maintenance description: Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. icon: calendar-check +contributor: Bruno +contributor_url: https://github.com/brunobergher +contributor_company: Roomote +contributor_company_url: https://roomote.dev --- `Schedule` · `Setup: about 15 minutes` · `Requires: admin` · `Serves: engineers, leads` +**Contributor:** [Bruno](https://github.com/brunobergher) +**Contributor company:** [Roomote](https://roomote.dev) + Every team has maintenance work that only happens when someone feels guilty: flaky tests, stale feature flags, and aging dependencies. A custom automation turns each chore into a standing appointment: a prompt, a cadence, and a channel diff --git a/apps/docs/cookbook/support-channel.mdx b/apps/docs/cookbook/support-channel.mdx index 780b75d6a..ae436d9d6 100644 --- a/apps/docs/cookbook/support-channel.mdx +++ b/apps/docs/cookbook/support-channel.mdx @@ -1,11 +1,18 @@ --- -title: Resolve customer issues before an engineer sees them +title: Triage customer issues description: Give support escalations a repeatable path through production evidence, data, and code. icon: headset +contributor: Bruno +contributor_url: https://github.com/brunobergher +contributor_company: Roomote +contributor_company_url: https://roomote.dev --- `Channel event` · `Setup: about 45 minutes` · `Requires: admin, Slack or Discord, observability or data integration` · `Serves: support, engineers` +**Contributor:** [Bruno](https://github.com/brunobergher) +**Contributor company:** [Roomote](https://roomote.dev) + Customer-facing teams post escalations into an operations channel, often from a ticketing system. A custom skill teaches Roomote your triage procedure: check logs, inspect data, read code, and classify the problem as a product bug, a diff --git a/apps/docs/cookbook/template.mdx b/apps/docs/cookbook/template.mdx index 6a6e1d0d2..67115fa40 100644 --- a/apps/docs/cookbook/template.mdx +++ b/apps/docs/cookbook/template.mdx @@ -2,6 +2,10 @@ title: Contributing recipes description: Propose a reusable Roomote system for the Cookbook through a repository issue. icon: plus +contributor: Name or team +contributor_url: https://example.com/contributor +contributor_company: Company +contributor_company_url: https://example.com/company --- Use this skeleton when proposing a Cookbook recipe. Replace every placeholder @@ -20,6 +24,11 @@ icon: lucide-icon-name `Trigger` · `Setup: about N minutes` · `Requires: ...` · `Serves: ...` +**Contributor:** Name or team +**Contributor URL:** https://example.com/contributor +**Contributor company:** Company +**Contributor company URL:** https://example.com/company + ## Ingredients diff --git a/apps/docs/cookbook/vendor-outage-triage.mdx b/apps/docs/cookbook/vendor-outage-triage.mdx index 321bc41e5..01d55f4c3 100644 --- a/apps/docs/cookbook/vendor-outage-triage.mdx +++ b/apps/docs/cookbook/vendor-outage-triage.mdx @@ -1,11 +1,18 @@ --- -title: Know within minutes whether a vendor outage affects you +title: Check vendor outages description: Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. icon: siren +contributor: Bruno +contributor_url: https://github.com/brunobergher +contributor_company: Roomote +contributor_company_url: https://roomote.dev --- `Channel event` · `Setup: about 20 minutes` · `Requires: admin, Slack or Discord` · `Serves: on-call, support` +**Contributor:** [Bruno](https://github.com/brunobergher) +**Contributor company:** [Roomote](https://roomote.dev) + Every vendor you depend on publishes status updates, and almost none of them affect you, until one does. Pipe them into one channel and let Roomote read each incident against your actual code: which SDKs you call, which regions you run diff --git a/apps/docs/integrations/better-stack.mdx b/apps/docs/integrations/better-stack.mdx index c0866589f..62cc38b66 100644 --- a/apps/docs/integrations/better-stack.mdx +++ b/apps/docs/integrations/better-stack.mdx @@ -26,4 +26,4 @@ repository workflow. ## Recipes using this -- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) +- [Triage customer issues](/cookbook/support-channel) diff --git a/apps/docs/integrations/grafana.mdx b/apps/docs/integrations/grafana.mdx index 74a1c1698..32c0c0a91 100644 --- a/apps/docs/integrations/grafana.mdx +++ b/apps/docs/integrations/grafana.mdx @@ -28,4 +28,4 @@ Grafana configuration. ## Recipes using this -- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) +- [Triage customer issues](/cookbook/support-channel) diff --git a/apps/docs/integrations/neon.mdx b/apps/docs/integrations/neon.mdx index 5709f7b60..08c2a3310 100644 --- a/apps/docs/integrations/neon.mdx +++ b/apps/docs/integrations/neon.mdx @@ -26,4 +26,4 @@ and human review on the normal Roomote and Git workflow. ## Recipes using this -- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) +- [Triage customer issues](/cookbook/support-channel) diff --git a/apps/docs/integrations/sentry.mdx b/apps/docs/integrations/sentry.mdx index eee2c6947..3d63d153e 100644 --- a/apps/docs/integrations/sentry.mdx +++ b/apps/docs/integrations/sentry.mdx @@ -25,4 +25,4 @@ review still happen in the normal task and repository flow. ## Recipes using this -- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) +- [Triage customer issues](/cookbook/support-channel) diff --git a/apps/docs/integrations/snowflake.mdx b/apps/docs/integrations/snowflake.mdx index ffa6e0d9f..dfc1bc6be 100644 --- a/apps/docs/integrations/snowflake.mdx +++ b/apps/docs/integrations/snowflake.mdx @@ -35,4 +35,4 @@ repository review flow. ## Recipes using this -- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) +- [Triage customer issues](/cookbook/support-channel) diff --git a/apps/docs/integrations/supabase.mdx b/apps/docs/integrations/supabase.mdx index 96443e96e..8581ff3c9 100644 --- a/apps/docs/integrations/supabase.mdx +++ b/apps/docs/integrations/supabase.mdx @@ -26,4 +26,4 @@ migrations, and review still go through your normal engineering workflow. ## Recipes using this -- [Resolve customer issues before an engineer sees them](/cookbook/support-channel) +- [Triage customer issues](/cookbook/support-channel) From 8babcf6e04b2d1a0af6e9107e8bc90cf89410dcb Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 17:57:58 +0100 Subject: [PATCH 04/13] docs: generate cookbook index from recipes --- .github/workflows/docs.yml | 44 +++++++ apps/docs/cookbook/index.mdx | 16 +-- apps/docs/cookbook/support-channel.mdx | 2 +- apps/docs/cookbook/vendor-outage-triage.mdx | 4 +- apps/docs/package.json | 12 +- apps/docs/scripts/generate-cookbook-index.mjs | 111 ++++++++++++++++++ pnpm-lock.yaml | 6 +- 7 files changed, 181 insertions(+), 14 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 apps/docs/scripts/generate-cookbook-index.mjs diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..d568c003e --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,44 @@ +name: Docs + +on: + push: + branches: [main, develop] + paths: + - "apps/docs/**" + - "pnpm-lock.yaml" + - "pnpm-workspace.yaml" + - ".github/actions/setup-environment/**" + - ".github/workflows/docs.yml" + pull_request: + branches: [main, develop] + paths: + - "apps/docs/**" + - "pnpm-lock.yaml" + - "pnpm-workspace.yaml" + - ".github/actions/setup-environment/**" + - ".github/workflows/docs.yml" + +permissions: + contents: read + +env: + NODE_VERSION: 24.13.1 + PNPM_VERSION: 10.29.3 + +jobs: + docs: + name: Validate docs + runs-on: blacksmith-4vcpu-ubuntu-2404 + steps: + - name: Checkout code + uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + - name: Setup environment + uses: ./.github/actions/setup-environment + with: + frozen-lockfile: 'true' + node-version: ${{ env.NODE_VERSION }} + pnpm-version: ${{ env.PNPM_VERSION }} + - name: Check generated Cookbook index + run: pnpm --filter @roomote/docs check-cookbook-index + - name: Validate docs and links + run: pnpm --filter @roomote/docs check diff --git a/apps/docs/cookbook/index.mdx b/apps/docs/cookbook/index.mdx index 9a55f68f8..efae81f8a 100644 --- a/apps/docs/cookbook/index.mdx +++ b/apps/docs/cookbook/index.mdx @@ -9,13 +9,15 @@ Roomote's abilities go way beyond ad hoc prompt → PR interactions. With integr This cookbook collects proven recipes to help you boost your team's productivity and the quality of your output. -| Recipe | Description | Contributor | Contributor company | -| --- | --- | --- | --- | -| [Check vendor outages](/cookbook/vendor-outage-triage) | Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. | [Bruno](https://github.com/brunobergher) | [Roomote](https://roomote.dev) | -| [Triage customer issues](/cookbook/support-channel) | Give support escalations a repeatable path through production evidence, data, and code. | [Bruno](https://github.com/brunobergher) | [Roomote](https://roomote.dev) | -| [Fix CI failures](/cookbook/ci-failure-auto-fix) | Have Roomote verify persistent default-branch CI failures, reproduce them, and open a focused fix PR. | [Bruno](https://github.com/brunobergher) | [Roomote](https://roomote.dev) | -| [Draft product updates](/cookbook/product-updates-newsletter) | Turn the week's merged product work into a customer-ready Resend draft on a schedule. | [Bruno](https://github.com/brunobergher) | [Roomote](https://roomote.dev) | -| [Schedule maintenance](/cookbook/scheduled-housekeeping) | Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. | [Bruno](https://github.com/brunobergher) | [Roomote](https://roomote.dev) | +{/* cookbook-recipes:start */} +| Recipe | Description | By | +| --- | --- | --- | +| [Check vendor outages](/cookbook/vendor-outage-triage) | Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. | [Matt](https://github.com/mrubens) ([Roomote](https://roomote.dev)) | +| [Draft product updates](/cookbook/product-updates-newsletter) | Turn the week's merged product work into a customer-ready Resend draft on a schedule. | [Bruno](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | +| [Fix CI failures](/cookbook/ci-failure-auto-fix) | Have Roomote verify persistent default-branch CI failures, reproduce them, and open a focused fix PR. | [Bruno](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | +| [Schedule maintenance](/cookbook/scheduled-housekeeping) | Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. | [Bruno](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | +| [Triage customer issues](/cookbook/support-channel) | Give support escalations a repeatable path through production evidence, data, and code. | [Matt](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | +{/* cookbook-recipes:end */} ## Contribute a recipe diff --git a/apps/docs/cookbook/support-channel.mdx b/apps/docs/cookbook/support-channel.mdx index ae436d9d6..26886ca68 100644 --- a/apps/docs/cookbook/support-channel.mdx +++ b/apps/docs/cookbook/support-channel.mdx @@ -2,7 +2,7 @@ title: Triage customer issues description: Give support escalations a repeatable path through production evidence, data, and code. icon: headset -contributor: Bruno +contributor: Matt contributor_url: https://github.com/brunobergher contributor_company: Roomote contributor_company_url: https://roomote.dev diff --git a/apps/docs/cookbook/vendor-outage-triage.mdx b/apps/docs/cookbook/vendor-outage-triage.mdx index 01d55f4c3..8f43efea7 100644 --- a/apps/docs/cookbook/vendor-outage-triage.mdx +++ b/apps/docs/cookbook/vendor-outage-triage.mdx @@ -2,8 +2,8 @@ title: Check vendor outages description: Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. icon: siren -contributor: Bruno -contributor_url: https://github.com/brunobergher +contributor: Matt +contributor_url: https://github.com/mrubens contributor_company: Roomote contributor_company_url: https://roomote.dev --- diff --git a/apps/docs/package.json b/apps/docs/package.json index 8723bb0ca..a02f5e95a 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -3,9 +3,15 @@ "version": "0.0.3", "private": true, "scripts": { - "dev": "mint dev", - "validate": "mint validate", + "generate-cookbook-index": "node scripts/generate-cookbook-index.mjs", + "check-cookbook-index": "node scripts/generate-cookbook-index.mjs --check", + "dev": "pnpm run generate-cookbook-index && mint dev", + "validate": "pnpm run generate-cookbook-index && mint validate", "check-links": "mint broken-links", - "check": "mint validate && mint broken-links" + "check": "pnpm run validate && pnpm run check-links", + "build": "pnpm run generate-cookbook-index && mint validate" + }, + "dependencies": { + "yaml": "^2.9.0" } } diff --git a/apps/docs/scripts/generate-cookbook-index.mjs b/apps/docs/scripts/generate-cookbook-index.mjs new file mode 100644 index 000000000..c76eadd4f --- /dev/null +++ b/apps/docs/scripts/generate-cookbook-index.mjs @@ -0,0 +1,111 @@ +import { readdir, readFile, writeFile } from 'node:fs/promises'; +import { basename, dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parse } from 'yaml'; + +const scriptDirectory = dirname(fileURLToPath(import.meta.url)); +const cookbookDirectory = join(scriptDirectory, '..', 'cookbook'); +const indexPath = join(cookbookDirectory, 'index.mdx'); +const tableStart = '{/* cookbook-recipes:start */}'; +const tableEnd = '{/* cookbook-recipes:end */}'; + +const requiredFields = ['title', 'description', 'contributor']; + +function parseFrontmatter(source, fileName) { + const match = source.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/); + + if (!match) { + throw new Error(`Missing frontmatter in ${fileName}`); + } + + const metadata = parse(match[1]); + + for (const field of requiredFields) { + if (typeof metadata[field] !== 'string' || metadata[field].trim() === '') { + throw new Error(`Missing ${field} in ${fileName}`); + } + } + + return metadata; +} + +function escapeTableCell(value) { + return value.replaceAll('|', '\\|').replaceAll('\n', ' ').trim(); +} + +function escapeRegExp(value) { + return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); +} + +function renderLinkedValue(value, url) { + const text = escapeTableCell(value); + return url ? `[${text}](${url})` : text; +} + +async function readRecipe(fileName) { + const source = await readFile(join(cookbookDirectory, fileName), 'utf8'); + const metadata = parseFrontmatter(source, fileName); + const slug = `/cookbook/${basename(fileName, '.mdx')}`; + + return { + title: metadata.title, + description: metadata.description, + contributor: metadata.contributor, + contributorUrl: metadata.contributor_url, + contributorCompany: metadata.contributor_company, + contributorCompanyUrl: metadata.contributor_company_url, + slug, + }; +} + +function renderTable(recipes) { + const rows = recipes + .sort((left, right) => left.title.localeCompare(right.title)) + .map((recipe) => { + const contributor = renderLinkedValue( + recipe.contributor, + recipe.contributorUrl, + ); + const company = recipe.contributorCompany + ? ` (${renderLinkedValue(recipe.contributorCompany, recipe.contributorCompanyUrl)})` + : ''; + + return `| [${escapeTableCell(recipe.title)}](${recipe.slug}) | ${escapeTableCell(recipe.description)} | ${contributor}${company} |`; + }); + + return ['| Recipe | Description | By |', '| --- | --- | --- |', ...rows].join( + '\n', + ); +} + +const recipeFiles = (await readdir(cookbookDirectory)) + .filter((fileName) => fileName.endsWith('.mdx')) + .filter((fileName) => !['index.mdx', 'template.mdx'].includes(fileName)) + .sort(); +const recipes = await Promise.all(recipeFiles.map(readRecipe)); +const indexSource = await readFile(indexPath, 'utf8'); +const tablePattern = new RegExp( + `${escapeRegExp(tableStart)}[\\s\\S]*?${escapeRegExp(tableEnd)}`, +); + +if (!tablePattern.test(indexSource)) { + throw new Error('Cookbook index is missing the generated table markers'); +} + +const generatedTable = `${tableStart}\n${renderTable(recipes)}\n${tableEnd}`; +const nextIndexSource = indexSource.replace(tablePattern, generatedTable); +const checkOnly = process.argv.includes('--check'); + +if (nextIndexSource !== indexSource) { + if (checkOnly) { + console.error( + 'Cookbook index is out of date; run generate-cookbook-index.', + ); + process.exitCode = 1; + } else { + await writeFile(indexPath, nextIndexSource); + console.log(`Updated cookbook index with ${recipes.length} recipes`); + } +} else { + console.log(`Cookbook index is up to date with ${recipes.length} recipes`); +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b785dcc49..4219f5bc3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -451,7 +451,11 @@ importers: specifier: ^4.1.1 version: 4.1.1(@edge-runtime/vm@3.2.0)(@opentelemetry/api@1.9.1)(@types/node@24.13.1)(jsdom@26.1.0(bufferutil@4.1.0)(utf-8-validate@6.0.6))(vite@7.3.5(@types/node@24.13.1)(jiti@2.7.0)(lightningcss@1.32.0)(terser@5.48.0)(tsx@4.20.4)(yaml@2.9.0)) - apps/docs: {} + apps/docs: + dependencies: + yaml: + specifier: ^2.9.0 + version: 2.9.0 apps/preview-proxy: dependencies: From 3b70faed39958ef1d9a452fa957283db7fbed803 Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 18:12:25 +0100 Subject: [PATCH 05/13] docs: standardize cookbook recipe format --- .github/ISSUE_TEMPLATE/cookbook-recipe.yml | 38 ++++++++++++++++++- apps/docs/cookbook/ci-failure-auto-fix.mdx | 11 ++++-- .../cookbook/product-updates-newsletter.mdx | 11 ++++-- apps/docs/cookbook/scheduled-housekeeping.mdx | 12 ++++-- apps/docs/cookbook/support-channel.mdx | 11 ++++-- apps/docs/cookbook/template.mdx | 26 ++++++++----- apps/docs/cookbook/vendor-outage-triage.mdx | 11 ++++-- 7 files changed, 90 insertions(+), 30 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/cookbook-recipe.yml b/.github/ISSUE_TEMPLATE/cookbook-recipe.yml index 8dc3f1b35..e83b4553a 100644 --- a/.github/ISSUE_TEMPLATE/cookbook-recipe.yml +++ b/.github/ISSUE_TEMPLATE/cookbook-recipe.yml @@ -31,9 +31,45 @@ body: title: Outcome-first recipe title description: One sentence explaining the finished system and why it matters. icon: lucide-icon-name + contributor: Name or team + contributor_url: https://example.com/contributor + contributor_company: Company + contributor_company_url: https://example.com/company --- - Describe the recipe here... + ## Overview + + Explain the recurring problem and the outcome this recipe creates. + + - **Trigger**: Trigger type + - **Setup time**: About N minutes + - **Requires**: Product access, integrations, permissions + - **Serves**: Teams or roles + - **Contributor**: Name or team from Company + + ## Ingredients + + - Ingredient + + ## Steps + + 1. First step. + + ## Paste-ready configuration + + ```text + Configuration or prompt + ``` + + ## When it fires + + > **Source:** Trigger message + > + > **Roomote:** Evidence-backed result + + ## Variations + + - Variation validations: required: true - type: textarea diff --git a/apps/docs/cookbook/ci-failure-auto-fix.mdx b/apps/docs/cookbook/ci-failure-auto-fix.mdx index f3c6409cc..cdc4b83d0 100644 --- a/apps/docs/cookbook/ci-failure-auto-fix.mdx +++ b/apps/docs/cookbook/ci-failure-auto-fix.mdx @@ -8,10 +8,7 @@ contributor_company: Roomote contributor_company_url: https://roomote.dev --- -`Webhook` · `Setup: about 10 minutes` · `Requires: admin, source control, Manager Channel` · `Serves: engineers` - -**Contributor:** [Bruno](https://github.com/brunobergher) -**Contributor company:** [Roomote](https://roomote.dev) +## Overview When CI fails on your default branch, Roomote reacts immediately. It checks that the failure is real, reproduces the failing job inside the repository's @@ -20,6 +17,12 @@ summary to the Manager Channel. The team finds a green PR waiting instead of a red branch. This is a built-in automation, so the recipe is one toggle plus clear instructions. +- **Trigger**: Webhook +- **Setup time**: About 10 minutes +- **Requires**: Admin access, source control, Manager Channel +- **Serves**: Engineers +- **Contributor**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) + ## Ingredients - [CI Failure Triage](/automations#manager-automations) diff --git a/apps/docs/cookbook/product-updates-newsletter.mdx b/apps/docs/cookbook/product-updates-newsletter.mdx index 1ffc82c66..e0a823e97 100644 --- a/apps/docs/cookbook/product-updates-newsletter.mdx +++ b/apps/docs/cookbook/product-updates-newsletter.mdx @@ -8,10 +8,7 @@ contributor_company: Roomote contributor_company_url: https://roomote.dev --- -`Schedule` · `Setup: about 30 minutes` · `Requires: admin, custom Resend MCP server` · `Serves: PMs, founders, marketing` - -**Contributor:** [Bruno](https://github.com/brunobergher) -**Contributor company:** [Roomote](https://roomote.dev) +## Overview Product-update emails are chronically late because someone has to remember what shipped, translate commit-speak into customer language, and then fight the @@ -20,6 +17,12 @@ across your product repositories, writes the newsletter, and creates a draft in Resend through a custom MCP server, ready for review. This is based on Bruno's setup at Roo. +- **Trigger**: Schedule +- **Setup time**: About 30 minutes +- **Requires**: Admin access, custom Resend MCP server +- **Serves**: PMs, Founders, Marketing +- **Contributor**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) + ## Ingredients - A [custom automation](/automations#custom-automations) diff --git a/apps/docs/cookbook/scheduled-housekeeping.mdx b/apps/docs/cookbook/scheduled-housekeeping.mdx index bbf37ba84..d3289d301 100644 --- a/apps/docs/cookbook/scheduled-housekeeping.mdx +++ b/apps/docs/cookbook/scheduled-housekeeping.mdx @@ -8,10 +8,7 @@ contributor_company: Roomote contributor_company_url: https://roomote.dev --- -`Schedule` · `Setup: about 15 minutes` · `Requires: admin` · `Serves: engineers, leads` - -**Contributor:** [Bruno](https://github.com/brunobergher) -**Contributor company:** [Roomote](https://roomote.dev) +## Overview Every team has maintenance work that only happens when someone feels guilty: flaky tests, stale feature flags, and aging dependencies. A custom automation @@ -19,6 +16,13 @@ turns each chore into a standing appointment: a prompt, a cadence, and a channel where results land in a replyable thread. Once you have built one, you will start spotting more work that fits the pattern. +- **Trigger**: Schedule +- **Setup time**: About 15 minutes +- **Requires**: Admin access +- **Serves**: Engineers, Leads +- **Contributor**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) + + ## Ingredients - One [custom automation](/automations#custom-automations) per chore, within the deployment cap of 25 diff --git a/apps/docs/cookbook/support-channel.mdx b/apps/docs/cookbook/support-channel.mdx index 26886ca68..56e6e8484 100644 --- a/apps/docs/cookbook/support-channel.mdx +++ b/apps/docs/cookbook/support-channel.mdx @@ -8,10 +8,7 @@ contributor_company: Roomote contributor_company_url: https://roomote.dev --- -`Channel event` · `Setup: about 45 minutes` · `Requires: admin, Slack or Discord, observability or data integration` · `Serves: support, engineers` - -**Contributor:** [Bruno](https://github.com/brunobergher) -**Contributor company:** [Roomote](https://roomote.dev) +## Overview Customer-facing teams post escalations into an operations channel, often from a ticketing system. A custom skill teaches Roomote your triage procedure: check @@ -20,6 +17,12 @@ data-state issue, or expected behavior. Roomote answers in the thread with evidence, and a PR when the resolution is a code fix. Engineers only see what survives triage. +- **Trigger**: Channel event +- **Setup time**: About 45 minutes +- **Requires**: Admin access, Slack or Discord, observability or data integration +- **Serves**: Support, Engineers +- **Contributor**: [Matt](https://github.com/brunobergher) from [Roomote](https://roomote.dev) + ## Ingredients - A channel receiving support escalations, such as `#support-inbound`, with Roomote invited diff --git a/apps/docs/cookbook/template.mdx b/apps/docs/cookbook/template.mdx index 67115fa40..61419b7b0 100644 --- a/apps/docs/cookbook/template.mdx +++ b/apps/docs/cookbook/template.mdx @@ -11,26 +11,34 @@ contributor_company_url: https://example.com/company Use this skeleton when proposing a Cookbook recipe. Replace every placeholder and remove the comments before opening a [Cookbook recipe issue](https://github.com/RooCodeInc/Roomote/issues/new?template=cookbook-recipe.yml). -Do not open a pull request unless a maintainer invites you to. If the recipe -comes from another team, add a short attribution after the metadata line, such as -`Recipe from the team at Example.` +Do not open a pull request unless a maintainer invites you to. Fill in the +contributor fields in the frontmatter and repeat the contributor in the +Overview metadata. If the recipe comes from another team, use those fields for +the attribution. ````markdown --- title: Outcome-first recipe title description: One sentence explaining the finished system and why it matters. icon: lucide-icon-name +contributor: Name or team +contributor_url: https://example.com/contributor +contributor_company: Company +contributor_company_url: https://example.com/company --- -`Trigger` · `Setup: about N minutes` · `Requires: ...` · `Serves: ...` - -**Contributor:** Name or team -**Contributor URL:** https://example.com/contributor -**Contributor company:** Company -**Contributor company URL:** https://example.com/company +## Overview +Overview paragraph. + +- **Trigger**: Trigger type +- **Setup time**: About N minutes +- **Requires**: Product access, integrations, permissions +- **Serves**: Teams or roles +- **Contributor**: [Name or team](https://example.com/contributor) from [Company](https://example.com/company) + ## Ingredients diff --git a/apps/docs/cookbook/vendor-outage-triage.mdx b/apps/docs/cookbook/vendor-outage-triage.mdx index 8f43efea7..dd4fc49f3 100644 --- a/apps/docs/cookbook/vendor-outage-triage.mdx +++ b/apps/docs/cookbook/vendor-outage-triage.mdx @@ -8,10 +8,7 @@ contributor_company: Roomote contributor_company_url: https://roomote.dev --- -`Channel event` · `Setup: about 20 minutes` · `Requires: admin, Slack or Discord` · `Serves: on-call, support` - -**Contributor:** [Bruno](https://github.com/brunobergher) -**Contributor company:** [Roomote](https://roomote.dev) +## Overview Every vendor you depend on publishes status updates, and almost none of them affect you, until one does. Pipe them into one channel and let Roomote read each @@ -19,6 +16,12 @@ incident against your actual code: which SDKs you call, which regions you run in, and which features you use. You stop triaging vendor noise by hand and only hear about the outages that matter. This is how we run it at Roo. +- **Trigger**: Channel event +- **Setup time**: About 20 minutes +- **Requires**: Admin access, Slack or Discord +- **Serves**: On-call, Support +- **Contributor**: [Matt](https://github.com/mrubens) + ## Ingredients - A Slack or Discord channel such as `#vendor-status` receiving vendor status From 627b7ba79957ca0e4986d5775e24564e755424eb Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 18:20:17 +0100 Subject: [PATCH 06/13] docs: refine cookbook metadata --- apps/docs/cookbook/ci-failure-auto-fix.mdx | 2 +- apps/docs/cookbook/index.mdx | 10 +++++----- apps/docs/cookbook/product-updates-newsletter.mdx | 2 +- apps/docs/cookbook/support-channel.mdx | 9 +++++---- apps/docs/cookbook/vendor-outage-triage.mdx | 2 +- apps/docs/scripts/generate-cookbook-index.mjs | 2 +- 6 files changed, 14 insertions(+), 13 deletions(-) diff --git a/apps/docs/cookbook/ci-failure-auto-fix.mdx b/apps/docs/cookbook/ci-failure-auto-fix.mdx index cdc4b83d0..bc51be919 100644 --- a/apps/docs/cookbook/ci-failure-auto-fix.mdx +++ b/apps/docs/cookbook/ci-failure-auto-fix.mdx @@ -1,6 +1,6 @@ --- title: Fix CI failures -description: Have Roomote verify persistent default-branch CI failures, reproduce them, and open a focused fix PR. +description: Keep the build green by having Roomote verify and fix CI breakages automatically. icon: git-pull-request contributor: Bruno contributor_url: https://github.com/brunobergher diff --git a/apps/docs/cookbook/index.mdx b/apps/docs/cookbook/index.mdx index efae81f8a..e5835fdc2 100644 --- a/apps/docs/cookbook/index.mdx +++ b/apps/docs/cookbook/index.mdx @@ -10,13 +10,13 @@ This cookbook collects proven recipes to help you boost your team's productivity and the quality of your output. {/* cookbook-recipes:start */} -| Recipe | Description | By | +| Recipe | Use to | By | | --- | --- | --- | -| [Check vendor outages](/cookbook/vendor-outage-triage) | Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. | [Matt](https://github.com/mrubens) ([Roomote](https://roomote.dev)) | -| [Draft product updates](/cookbook/product-updates-newsletter) | Turn the week's merged product work into a customer-ready Resend draft on a schedule. | [Bruno](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | -| [Fix CI failures](/cookbook/ci-failure-auto-fix) | Have Roomote verify persistent default-branch CI failures, reproduce them, and open a focused fix PR. | [Bruno](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | +| [Draft product updates](/cookbook/product-updates-newsletter) | Turn recent product work into a customer-ready draft | [Bruno](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | +| [Evaluate outage impact](/cookbook/vendor-outage-triage) | Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. | [Matt](https://github.com/mrubens) ([Roomote](https://roomote.dev)) | +| [Fix CI failures](/cookbook/ci-failure-auto-fix) | Keep the build green by having Roomote verify and fix CI breakages automatically. | [Bruno](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | | [Schedule maintenance](/cookbook/scheduled-housekeeping) | Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. | [Bruno](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | -| [Triage customer issues](/cookbook/support-channel) | Give support escalations a repeatable path through production evidence, data, and code. | [Matt](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | +| [Triage customer issues](/cookbook/support-channel) | Give support escalations a repeatable path through production evidence, data, and code. | John Stearns ([Roo Vet](https://roo.vet)) | {/* cookbook-recipes:end */} ## Contribute a recipe diff --git a/apps/docs/cookbook/product-updates-newsletter.mdx b/apps/docs/cookbook/product-updates-newsletter.mdx index e0a823e97..253f7023e 100644 --- a/apps/docs/cookbook/product-updates-newsletter.mdx +++ b/apps/docs/cookbook/product-updates-newsletter.mdx @@ -1,6 +1,6 @@ --- title: Draft product updates -description: Turn the week's merged product work into a customer-ready Resend draft on a schedule. +description: Turn recent product work into a customer-ready draft icon: mail contributor: Bruno contributor_url: https://github.com/brunobergher diff --git a/apps/docs/cookbook/support-channel.mdx b/apps/docs/cookbook/support-channel.mdx index 56e6e8484..b12e5772a 100644 --- a/apps/docs/cookbook/support-channel.mdx +++ b/apps/docs/cookbook/support-channel.mdx @@ -2,10 +2,9 @@ title: Triage customer issues description: Give support escalations a repeatable path through production evidence, data, and code. icon: headset -contributor: Matt -contributor_url: https://github.com/brunobergher -contributor_company: Roomote -contributor_company_url: https://roomote.dev +contributor: John Stearns +contributor_company: Roo Vet +contributor_company_url: https://roo.vet --- ## Overview @@ -99,6 +98,7 @@ resolved. ## When it fires +``` > **Ticketbot** (app, `#support-inbound`): ACME-4321 · Priority: High. Customer > reports the Q3 CSV export downloads as an empty file. Started yesterday. > @@ -109,6 +109,7 @@ resolved. > **Fix for an operator:** restore the affected report rows after confirming > with the customer. **Draft reply:** "The Q3 rows were deleted by a workspace > admin. We can restore them; reply to confirm." +``` ## Variations diff --git a/apps/docs/cookbook/vendor-outage-triage.mdx b/apps/docs/cookbook/vendor-outage-triage.mdx index dd4fc49f3..0117f066c 100644 --- a/apps/docs/cookbook/vendor-outage-triage.mdx +++ b/apps/docs/cookbook/vendor-outage-triage.mdx @@ -1,5 +1,5 @@ --- -title: Check vendor outages +title: Evaluate outage impact description: Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. icon: siren contributor: Matt diff --git a/apps/docs/scripts/generate-cookbook-index.mjs b/apps/docs/scripts/generate-cookbook-index.mjs index c76eadd4f..96f1d4154 100644 --- a/apps/docs/scripts/generate-cookbook-index.mjs +++ b/apps/docs/scripts/generate-cookbook-index.mjs @@ -73,7 +73,7 @@ function renderTable(recipes) { return `| [${escapeTableCell(recipe.title)}](${recipe.slug}) | ${escapeTableCell(recipe.description)} | ${contributor}${company} |`; }); - return ['| Recipe | Description | By |', '| --- | --- | --- |', ...rows].join( + return ['| Recipe | Use to | By |', '| --- | --- | --- |', ...rows].join( '\n', ); } From 1c126fef619ddfbb6907b19450f737c6685839f4 Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 18:22:28 +0100 Subject: [PATCH 07/13] docs: simplify cookbook recipes --- .github/ISSUE_TEMPLATE/cookbook-recipe.yml | 6 ------ apps/docs/automations.mdx | 4 ++++ apps/docs/cookbook/ci-failure-auto-fix.mdx | 8 -------- .../docs/cookbook/product-updates-newsletter.mdx | 13 ------------- apps/docs/cookbook/scheduled-housekeeping.mdx | 15 --------------- apps/docs/cookbook/support-channel.mdx | 15 --------------- apps/docs/cookbook/template.mdx | 8 -------- apps/docs/cookbook/vendor-outage-triage.mdx | 16 ---------------- 8 files changed, 4 insertions(+), 81 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/cookbook-recipe.yml b/.github/ISSUE_TEMPLATE/cookbook-recipe.yml index e83b4553a..8fd816283 100644 --- a/.github/ISSUE_TEMPLATE/cookbook-recipe.yml +++ b/.github/ISSUE_TEMPLATE/cookbook-recipe.yml @@ -61,12 +61,6 @@ body: Configuration or prompt ``` - ## When it fires - - > **Source:** Trigger message - > - > **Roomote:** Evidence-backed result - ## Variations - Variation diff --git a/apps/docs/automations.mdx b/apps/docs/automations.mdx index fdcb6e86a..1dbb83c80 100644 --- a/apps/docs/automations.mdx +++ b/apps/docs/automations.mdx @@ -12,6 +12,10 @@ or a communications provider when an automation depends on those services. Automations are most useful when your team already trusts the normal task review flow and wants Roomote to keep an eye on repeated work. + + Unsure of how Automations can help? Get inspiration from the [Cookbook](/cookbook). + + ## Before you turn them on Make sure the basics are in place: diff --git a/apps/docs/cookbook/ci-failure-auto-fix.mdx b/apps/docs/cookbook/ci-failure-auto-fix.mdx index bc51be919..4e35f46f3 100644 --- a/apps/docs/cookbook/ci-failure-auto-fix.mdx +++ b/apps/docs/cookbook/ci-failure-auto-fix.mdx @@ -52,14 +52,6 @@ a test to get there. If the test is wrong, fix the test and say so in the PR description. ``` -## When it fires - -> **Roomote** (`#roomote-managers`): **CI failure on `main` fixed.** `typecheck` -> failed after a component's props were renamed. I reproduced it in the web -> environment and found a stale import in the task list. Opened **PR #1033** -> with the two-line fix; typecheck and the affected tests pass. The failure -> persisted across two runs, so it was not a flake. - ## Variations - Keep experimental repositories out of environments to exclude them from triage. diff --git a/apps/docs/cookbook/product-updates-newsletter.mdx b/apps/docs/cookbook/product-updates-newsletter.mdx index 253f7023e..693c81a76 100644 --- a/apps/docs/cookbook/product-updates-newsletter.mdx +++ b/apps/docs/cookbook/product-updates-newsletter.mdx @@ -60,19 +60,6 @@ If nothing customer-visible shipped this week, say so in the thread and skip the draft. Do not pad the newsletter. ``` -## When it fires - -> **Roomote** (`#product-updates`): **This week's newsletter draft is ready.** -> Three customer-visible changes: scheduling timezones for automations, Discord -> forum-channel support, and faster environment starts. Draft created in Resend -> but not sent. Reply here with edits, or send it directly from Resend. -> -> **Bruno:** Lead with the timezone setting, and mention that it applies to -> existing automations too. -> -> **Roomote:** Reordered and updated the Resend draft. The timezone section now -> opens the email and notes that it applies retroactively. Same draft link. - ## Variations - Without Resend, remove step 4 and post ready-to-paste Markdown for any email tool. diff --git a/apps/docs/cookbook/scheduled-housekeeping.mdx b/apps/docs/cookbook/scheduled-housekeeping.mdx index d3289d301..cb3c792f3 100644 --- a/apps/docs/cookbook/scheduled-housekeeping.mdx +++ b/apps/docs/cookbook/scheduled-housekeeping.mdx @@ -70,21 +70,6 @@ changed upstream and the migration risk for our codebase specifically. Do not open PRs. End with a ranked shortlist of updates worth scheduling this sprint. ``` -## When it fires - -> **Roomote** (`#eng-maintenance`): **Weekly flaky-test report: two suspects.** -> 1. `task-queue.test.ts` > `retries stale jobs` failed in three recent runs -> with no related changes. It races a real timer against queue polling. Opened -> **PR #1041** replacing the sleep with a fake timer. -> 2. `preview-proxy.test.ts` > `streams logs` failed twice because a fixed port -> collides with parallel CI shards. Decision needed: random port or dedicated -> shard. Reply if you want the PR. -> -> **Dana:** Random port, please. Open the PR. -> -> **Roomote:** Opened **PR #1042** to bind the test proxy to an ephemeral port -> and pass its address through. Both flaky suspects now have fixes. - ## Variations - Create a Monday briefing that summarizes open PRs, stale branches, and work waiting on review. diff --git a/apps/docs/cookbook/support-channel.mdx b/apps/docs/cookbook/support-channel.mdx index b12e5772a..43da1167c 100644 --- a/apps/docs/cookbook/support-channel.mdx +++ b/apps/docs/cookbook/support-channel.mdx @@ -96,21 +96,6 @@ only if the customer reports the problem recurring after it was thought resolved. ``` -## When it fires - -``` -> **Ticketbot** (app, `#support-inbound`): ACME-4321 · Priority: High. Customer -> reports the Q3 CSV export downloads as an empty file. Started yesterday. -> -> **Roomote** (in thread): **Data-state problem, not a bug.** The export -> pipeline ran clean, but this workspace's Q3 report rows are soft-deleted. The -> export correctly renders zero rows. -> -> **Fix for an operator:** restore the affected report rows after confirming -> with the customer. **Draft reply:** "The Q3 rows were deleted by a workspace -> admin. We can restore them; reply to confirm." -``` - ## Variations - Ask Roomote to propose, but not run, a data-repair script as a reviewed PR against an operations repository. diff --git a/apps/docs/cookbook/template.mdx b/apps/docs/cookbook/template.mdx index 61419b7b0..5596bca84 100644 --- a/apps/docs/cookbook/template.mdx +++ b/apps/docs/cookbook/template.mdx @@ -59,14 +59,6 @@ Overview paragraph. Configuration or prompt ``` -## When it fires - - - -> **Source:** Trigger message -> -> **Roomote:** Evidence-backed result - ## Variations diff --git a/apps/docs/cookbook/vendor-outage-triage.mdx b/apps/docs/cookbook/vendor-outage-triage.mdx index 0117f066c..8b2fbd0fd 100644 --- a/apps/docs/cookbook/vendor-outage-triage.mdx +++ b/apps/docs/cookbook/vendor-outage-triage.mdx @@ -79,22 +79,6 @@ A vendor has posted a status incident. Determine whether it affects us: Keep it short. The on-call engineer reads this thread. Do not page anyone. ``` -## When it fires - -> **Acme Status** (app, `#vendor-status`): Investigating: elevated error rates -> on Object Storage API (`us-east-1`). Some requests may fail with 5xx. -> -> **Roomote** (in thread): **Safe to ignore.** We use Acme Object Storage only -> in `eu-west-1`; the affected `us-east-1` endpoints are not referenced in the -> codebase. Uploads and signed URLs are unaffected. No action needed. -> -> **Acme Status** (app): Update: impact expanded to CDN edge in EU regions. -> -> **Roomote** (in thread): **Affects us.** EU CDN edge is now impacted. Public -> asset delivery routes through Acme CDN, so users may see slow or missing -> images. Suggested action: serve assets from origin until the incident is -> resolved. - ## Variations - Name the vendors explicitly in the criteria to ignore feeds subscribed to just in case. From 13dea3a53476aef4ad54b42b42423d3bfc40cf60 Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 18:23:52 +0100 Subject: [PATCH 08/13] docs: format cookbook contributor links --- apps/docs/cookbook/index.mdx | 10 +++++----- apps/docs/scripts/generate-cookbook-index.mjs | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/apps/docs/cookbook/index.mdx b/apps/docs/cookbook/index.mdx index e5835fdc2..32f5ccf6e 100644 --- a/apps/docs/cookbook/index.mdx +++ b/apps/docs/cookbook/index.mdx @@ -12,11 +12,11 @@ and the quality of your output. {/* cookbook-recipes:start */} | Recipe | Use to | By | | --- | --- | --- | -| [Draft product updates](/cookbook/product-updates-newsletter) | Turn recent product work into a customer-ready draft | [Bruno](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | -| [Evaluate outage impact](/cookbook/vendor-outage-triage) | Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. | [Matt](https://github.com/mrubens) ([Roomote](https://roomote.dev)) | -| [Fix CI failures](/cookbook/ci-failure-auto-fix) | Keep the build green by having Roomote verify and fix CI breakages automatically. | [Bruno](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | -| [Schedule maintenance](/cookbook/scheduled-housekeeping) | Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. | [Bruno](https://github.com/brunobergher) ([Roomote](https://roomote.dev)) | -| [Triage customer issues](/cookbook/support-channel) | Give support escalations a repeatable path through production evidence, data, and code. | John Stearns ([Roo Vet](https://roo.vet)) | +| [Draft product updates](/cookbook/product-updates-newsletter) | Turn recent product work into a customer-ready draft | [Bruno](https://github.com/brunobergher)
[Roomote](https://roomote.dev) | +| [Evaluate outage impact](/cookbook/vendor-outage-triage) | Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. | [Matt](https://github.com/mrubens)
[Roomote](https://roomote.dev) | +| [Fix CI failures](/cookbook/ci-failure-auto-fix) | Keep the build green by having Roomote verify and fix CI breakages automatically. | [Bruno](https://github.com/brunobergher)
[Roomote](https://roomote.dev) | +| [Schedule maintenance](/cookbook/scheduled-housekeeping) | Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. | [Bruno](https://github.com/brunobergher)
[Roomote](https://roomote.dev) | +| [Triage customer issues](/cookbook/support-channel) | Give support escalations a repeatable path through production evidence, data, and code. | John Stearns
[Roo Vet](https://roo.vet) | {/* cookbook-recipes:end */} ## Contribute a recipe diff --git a/apps/docs/scripts/generate-cookbook-index.mjs b/apps/docs/scripts/generate-cookbook-index.mjs index 96f1d4154..5ee8cfcad 100644 --- a/apps/docs/scripts/generate-cookbook-index.mjs +++ b/apps/docs/scripts/generate-cookbook-index.mjs @@ -67,7 +67,7 @@ function renderTable(recipes) { recipe.contributorUrl, ); const company = recipe.contributorCompany - ? ` (${renderLinkedValue(recipe.contributorCompany, recipe.contributorCompanyUrl)})` + ? `
${renderLinkedValue(recipe.contributorCompany, recipe.contributorCompanyUrl)}` : ''; return `| [${escapeTableCell(recipe.title)}](${recipe.slug}) | ${escapeTableCell(recipe.description)} | ${contributor}${company} |`; From a616ce8c6dee753e9202f95a634965831abe0672 Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 18:29:52 +0100 Subject: [PATCH 09/13] docs: polish cookbook presentation --- .github/ISSUE_TEMPLATE/cookbook-recipe.yml | 2 +- apps/docs/cookbook/ci-failure-auto-fix.mdx | 3 +-- apps/docs/cookbook/index.mdx | 14 +++++++------- apps/docs/cookbook/product-updates-newsletter.mdx | 3 +-- apps/docs/cookbook/scheduled-housekeeping.mdx | 3 +-- apps/docs/cookbook/support-channel.mdx | 3 +-- apps/docs/cookbook/template.mdx | 2 +- apps/docs/cookbook/vendor-outage-triage.mdx | 3 +-- apps/docs/scripts/generate-cookbook-index.mjs | 12 ++---------- 9 files changed, 16 insertions(+), 29 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/cookbook-recipe.yml b/.github/ISSUE_TEMPLATE/cookbook-recipe.yml index 8fd816283..8f12a7dba 100644 --- a/.github/ISSUE_TEMPLATE/cookbook-recipe.yml +++ b/.github/ISSUE_TEMPLATE/cookbook-recipe.yml @@ -45,7 +45,7 @@ body: - **Setup time**: About N minutes - **Requires**: Product access, integrations, permissions - **Serves**: Teams or roles - - **Contributor**: Name or team from Company + - **Cooked By**: Name or team from Company ## Ingredients diff --git a/apps/docs/cookbook/ci-failure-auto-fix.mdx b/apps/docs/cookbook/ci-failure-auto-fix.mdx index 4e35f46f3..02a38030e 100644 --- a/apps/docs/cookbook/ci-failure-auto-fix.mdx +++ b/apps/docs/cookbook/ci-failure-auto-fix.mdx @@ -1,7 +1,6 @@ --- title: Fix CI failures description: Keep the build green by having Roomote verify and fix CI breakages automatically. -icon: git-pull-request contributor: Bruno contributor_url: https://github.com/brunobergher contributor_company: Roomote @@ -21,7 +20,7 @@ clear instructions. - **Setup time**: About 10 minutes - **Requires**: Admin access, source control, Manager Channel - **Serves**: Engineers -- **Contributor**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) +- **Cooked By**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) ## Ingredients diff --git a/apps/docs/cookbook/index.mdx b/apps/docs/cookbook/index.mdx index 32f5ccf6e..d2172a276 100644 --- a/apps/docs/cookbook/index.mdx +++ b/apps/docs/cookbook/index.mdx @@ -10,13 +10,13 @@ This cookbook collects proven recipes to help you boost your team's productivity and the quality of your output. {/* cookbook-recipes:start */} -| Recipe | Use to | By | -| --- | --- | --- | -| [Draft product updates](/cookbook/product-updates-newsletter) | Turn recent product work into a customer-ready draft | [Bruno](https://github.com/brunobergher)
[Roomote](https://roomote.dev) | -| [Evaluate outage impact](/cookbook/vendor-outage-triage) | Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. | [Matt](https://github.com/mrubens)
[Roomote](https://roomote.dev) | -| [Fix CI failures](/cookbook/ci-failure-auto-fix) | Keep the build green by having Roomote verify and fix CI breakages automatically. | [Bruno](https://github.com/brunobergher)
[Roomote](https://roomote.dev) | -| [Schedule maintenance](/cookbook/scheduled-housekeeping) | Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. | [Bruno](https://github.com/brunobergher)
[Roomote](https://roomote.dev) | -| [Triage customer issues](/cookbook/support-channel) | Give support escalations a repeatable path through production evidence, data, and code. | John Stearns
[Roo Vet](https://roo.vet) | +| Recipe | Use to | +| --- | --- | +| [Draft product updates](/cookbook/product-updates-newsletter) | Turn recent product work into a customer-ready draft | +| [Evaluate outage impact](/cookbook/vendor-outage-triage) | Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. | +| [Fix CI failures](/cookbook/ci-failure-auto-fix) | Keep the build green by having Roomote verify and fix CI breakages automatically. | +| [Schedule maintenance](/cookbook/scheduled-housekeeping) | Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. | +| [Triage customer issues](/cookbook/support-channel) | Give support escalations a repeatable path through production evidence, data, and code. | {/* cookbook-recipes:end */} ## Contribute a recipe diff --git a/apps/docs/cookbook/product-updates-newsletter.mdx b/apps/docs/cookbook/product-updates-newsletter.mdx index 693c81a76..543ad013d 100644 --- a/apps/docs/cookbook/product-updates-newsletter.mdx +++ b/apps/docs/cookbook/product-updates-newsletter.mdx @@ -1,7 +1,6 @@ --- title: Draft product updates description: Turn recent product work into a customer-ready draft -icon: mail contributor: Bruno contributor_url: https://github.com/brunobergher contributor_company: Roomote @@ -21,7 +20,7 @@ setup at Roo. - **Setup time**: About 30 minutes - **Requires**: Admin access, custom Resend MCP server - **Serves**: PMs, Founders, Marketing -- **Contributor**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) +- **Cooked By**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) ## Ingredients diff --git a/apps/docs/cookbook/scheduled-housekeeping.mdx b/apps/docs/cookbook/scheduled-housekeeping.mdx index cb3c792f3..8436966e2 100644 --- a/apps/docs/cookbook/scheduled-housekeeping.mdx +++ b/apps/docs/cookbook/scheduled-housekeeping.mdx @@ -1,7 +1,6 @@ --- title: Schedule maintenance description: Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. -icon: calendar-check contributor: Bruno contributor_url: https://github.com/brunobergher contributor_company: Roomote @@ -20,7 +19,7 @@ start spotting more work that fits the pattern. - **Setup time**: About 15 minutes - **Requires**: Admin access - **Serves**: Engineers, Leads -- **Contributor**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) +- **Cooked By**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) ## Ingredients diff --git a/apps/docs/cookbook/support-channel.mdx b/apps/docs/cookbook/support-channel.mdx index 43da1167c..6de79ddf5 100644 --- a/apps/docs/cookbook/support-channel.mdx +++ b/apps/docs/cookbook/support-channel.mdx @@ -1,7 +1,6 @@ --- title: Triage customer issues description: Give support escalations a repeatable path through production evidence, data, and code. -icon: headset contributor: John Stearns contributor_company: Roo Vet contributor_company_url: https://roo.vet @@ -20,7 +19,7 @@ survives triage. - **Setup time**: About 45 minutes - **Requires**: Admin access, Slack or Discord, observability or data integration - **Serves**: Support, Engineers -- **Contributor**: [Matt](https://github.com/brunobergher) from [Roomote](https://roomote.dev) +- **Cooked By**: [Matt](https://github.com/brunobergher) from [Roomote](https://roomote.dev) ## Ingredients diff --git a/apps/docs/cookbook/template.mdx b/apps/docs/cookbook/template.mdx index 5596bca84..111564f89 100644 --- a/apps/docs/cookbook/template.mdx +++ b/apps/docs/cookbook/template.mdx @@ -37,7 +37,7 @@ Overview paragraph. - **Setup time**: About N minutes - **Requires**: Product access, integrations, permissions - **Serves**: Teams or roles -- **Contributor**: [Name or team](https://example.com/contributor) from [Company](https://example.com/company) +- **Cooked By**: [Name or team](https://example.com/contributor) from [Company](https://example.com/company) ## Ingredients diff --git a/apps/docs/cookbook/vendor-outage-triage.mdx b/apps/docs/cookbook/vendor-outage-triage.mdx index 8b2fbd0fd..4aa00c536 100644 --- a/apps/docs/cookbook/vendor-outage-triage.mdx +++ b/apps/docs/cookbook/vendor-outage-triage.mdx @@ -1,7 +1,6 @@ --- title: Evaluate outage impact description: Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. -icon: siren contributor: Matt contributor_url: https://github.com/mrubens contributor_company: Roomote @@ -20,7 +19,7 @@ hear about the outages that matter. This is how we run it at Roo. - **Setup time**: About 20 minutes - **Requires**: Admin access, Slack or Discord - **Serves**: On-call, Support -- **Contributor**: [Matt](https://github.com/mrubens) +- **Cooked By**: [Matt](https://github.com/mrubens) ## Ingredients diff --git a/apps/docs/scripts/generate-cookbook-index.mjs b/apps/docs/scripts/generate-cookbook-index.mjs index 5ee8cfcad..dd85ff042 100644 --- a/apps/docs/scripts/generate-cookbook-index.mjs +++ b/apps/docs/scripts/generate-cookbook-index.mjs @@ -62,18 +62,10 @@ function renderTable(recipes) { const rows = recipes .sort((left, right) => left.title.localeCompare(right.title)) .map((recipe) => { - const contributor = renderLinkedValue( - recipe.contributor, - recipe.contributorUrl, - ); - const company = recipe.contributorCompany - ? `
${renderLinkedValue(recipe.contributorCompany, recipe.contributorCompanyUrl)}` - : ''; - - return `| [${escapeTableCell(recipe.title)}](${recipe.slug}) | ${escapeTableCell(recipe.description)} | ${contributor}${company} |`; + return `| [${escapeTableCell(recipe.title)}](${recipe.slug}) | ${escapeTableCell(recipe.description)} |`; }); - return ['| Recipe | Use to | By |', '| --- | --- | --- |', ...rows].join( + return ['| Recipe | Use to |', '| --- | --- |', ...rows].join( '\n', ); } From b98b6770fceefe2a71fd1d34bb007f25d461f50a Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 18:31:41 +0100 Subject: [PATCH 10/13] docs: update cookbook contributors --- apps/docs/cookbook/ci-failure-auto-fix.mdx | 6 +++--- apps/docs/cookbook/product-updates-newsletter.mdx | 9 +++++---- apps/docs/cookbook/scheduled-housekeeping.mdx | 4 ++-- apps/docs/cookbook/vendor-outage-triage.mdx | 4 ++-- 4 files changed, 12 insertions(+), 11 deletions(-) diff --git a/apps/docs/cookbook/ci-failure-auto-fix.mdx b/apps/docs/cookbook/ci-failure-auto-fix.mdx index 02a38030e..61a3a4779 100644 --- a/apps/docs/cookbook/ci-failure-auto-fix.mdx +++ b/apps/docs/cookbook/ci-failure-auto-fix.mdx @@ -1,8 +1,8 @@ --- title: Fix CI failures description: Keep the build green by having Roomote verify and fix CI breakages automatically. -contributor: Bruno -contributor_url: https://github.com/brunobergher +contributor: Matt Rubens +contributor_url: https://github.com/mrubens contributor_company: Roomote contributor_company_url: https://roomote.dev --- @@ -20,7 +20,7 @@ clear instructions. - **Setup time**: About 10 minutes - **Requires**: Admin access, source control, Manager Channel - **Serves**: Engineers -- **Cooked By**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) +- **Cooked By**: [Matt Rubens](https://github.com/mrubens) from [Roomote](https://roomote.dev) ## Ingredients diff --git a/apps/docs/cookbook/product-updates-newsletter.mdx b/apps/docs/cookbook/product-updates-newsletter.mdx index 543ad013d..229ed8803 100644 --- a/apps/docs/cookbook/product-updates-newsletter.mdx +++ b/apps/docs/cookbook/product-updates-newsletter.mdx @@ -1,7 +1,7 @@ --- title: Draft product updates description: Turn recent product work into a customer-ready draft -contributor: Bruno +contributor: Bruno Bergher contributor_url: https://github.com/brunobergher contributor_company: Roomote contributor_company_url: https://roomote.dev @@ -13,14 +13,15 @@ Product-update emails are chronically late because someone has to remember what shipped, translate commit-speak into customer language, and then fight the email tool. This automation does all three: every week it reads merged PRs across your product repositories, writes the newsletter, and creates a draft in -Resend through a custom MCP server, ready for review. This is based on Bruno's -setup at Roo. +Resend through a custom MCP server, ready for review. + +It's how we actually generate the ones we send every Friday. - **Trigger**: Schedule - **Setup time**: About 30 minutes - **Requires**: Admin access, custom Resend MCP server - **Serves**: PMs, Founders, Marketing -- **Cooked By**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) +- **Cooked By**: [Bruno Bergher](https://github.com/brunobergher) from [Roomote](https://roomote.dev) ## Ingredients diff --git a/apps/docs/cookbook/scheduled-housekeeping.mdx b/apps/docs/cookbook/scheduled-housekeeping.mdx index 8436966e2..ba7d5f47e 100644 --- a/apps/docs/cookbook/scheduled-housekeeping.mdx +++ b/apps/docs/cookbook/scheduled-housekeeping.mdx @@ -1,7 +1,7 @@ --- title: Schedule maintenance description: Turn flaky-test scans, feature-flag audits, and dependency reviews into recurring Roomote work. -contributor: Bruno +contributor: Bruno Bergher contributor_url: https://github.com/brunobergher contributor_company: Roomote contributor_company_url: https://roomote.dev @@ -19,7 +19,7 @@ start spotting more work that fits the pattern. - **Setup time**: About 15 minutes - **Requires**: Admin access - **Serves**: Engineers, Leads -- **Cooked By**: [Bruno](https://github.com/brunobergher) from [Roomote](https://roomote.dev) +- **Cooked By**: [Bruno Bergher](https://github.com/brunobergher) from [Roomote](https://roomote.dev) ## Ingredients diff --git a/apps/docs/cookbook/vendor-outage-triage.mdx b/apps/docs/cookbook/vendor-outage-triage.mdx index 4aa00c536..a2a8627dc 100644 --- a/apps/docs/cookbook/vendor-outage-triage.mdx +++ b/apps/docs/cookbook/vendor-outage-triage.mdx @@ -1,7 +1,7 @@ --- title: Evaluate outage impact description: Filter vendor status noise by comparing each incident with your real code, regions, and feature usage. -contributor: Matt +contributor: Matt Rubens contributor_url: https://github.com/mrubens contributor_company: Roomote contributor_company_url: https://roomote.dev @@ -19,7 +19,7 @@ hear about the outages that matter. This is how we run it at Roo. - **Setup time**: About 20 minutes - **Requires**: Admin access, Slack or Discord - **Serves**: On-call, Support -- **Cooked By**: [Matt](https://github.com/mrubens) +- **Cooked By**: [Matt Rubens](https://github.com/mrubens) ## Ingredients From eb2d72543e5af9b7b7b8d14b9242d0d80e7f1328 Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 18:32:58 +0100 Subject: [PATCH 11/13] fixes --- apps/docs/cookbook/ci-failure-auto-fix.mdx | 16 ---------------- .../docs/cookbook/product-updates-newsletter.mdx | 4 ++-- 2 files changed, 2 insertions(+), 18 deletions(-) diff --git a/apps/docs/cookbook/ci-failure-auto-fix.mdx b/apps/docs/cookbook/ci-failure-auto-fix.mdx index 61a3a4779..93c459e67 100644 --- a/apps/docs/cookbook/ci-failure-auto-fix.mdx +++ b/apps/docs/cookbook/ci-failure-auto-fix.mdx @@ -33,24 +33,8 @@ clear instructions. 1. Set the Manager Channel under **Settings > Automations > Automation output**. 2. Enable **CI Failure Triage**. 3. Confirm each repository you care about belongs to a configured environment. -4. Add the noise-control instructions below. 5. Use **Run now** to test the configuration, or wait for the next default-branch failure. -## Additional instructions - -Paste this into the automation's **Additional instructions** field: - -```text -Only triage failures in build and test jobs. Ignore the nightly performance -suite and deploy jobs; deploys are handled by on-call. - -Treat a failure as persistent if the same job also failed in the previous run. - -Prefer the smallest change that makes CI green. Never skip, disable, or delete -a test to get there. If the test is wrong, fix the test and say so in the PR -description. -``` - ## Variations - Keep experimental repositories out of environments to exclude them from triage. diff --git a/apps/docs/cookbook/product-updates-newsletter.mdx b/apps/docs/cookbook/product-updates-newsletter.mdx index 229ed8803..982015f05 100644 --- a/apps/docs/cookbook/product-updates-newsletter.mdx +++ b/apps/docs/cookbook/product-updates-newsletter.mdx @@ -27,12 +27,12 @@ It's how we actually generate the ones we send every Friday. - A [custom automation](/automations#custom-automations) - An environment covering the product repositories -- A custom Resend MCP server configured under **Settings > Integrations**, with a Resend API key +- The Resend MCP server configured under **Settings > Integrations**, with a Resend API key - A report destination such as `#product-updates`, so the draft lands in a replyable thread ## Steps -1. Add the Resend MCP server as a custom integration and confirm its tools are available in the environment. +1. Add the Resend MCP server and confirm its tools are available in the environment. 2. Create a custom automation named **Product Updates Newsletter**. Choose **Custom schedule**, enter `Mondays at 9am`, and select the environment. 3. Paste the prompt below. 4. Set the report destination to `#product-updates`. From e51860c62b6059eb99c0637560f3a260b45b2c7e Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 19:21:42 +0100 Subject: [PATCH 12/13] fix: run docs scripts with pinned Mintlify CLI --- apps/docs/README.md | 4 ++-- apps/docs/package.json | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/apps/docs/README.md b/apps/docs/README.md index dcaaea11e..b7098508c 100644 --- a/apps/docs/README.md +++ b/apps/docs/README.md @@ -20,10 +20,10 @@ and assets all live in this directory and do not depend on `@roomote/web`. ## Local development -Install the Mintlify CLI (`mint`) globally, then run the dev server: +The docs scripts download a pinned Mintlify CLI automatically, so no global +install is required. Run the dev server with: ```bash -npm install -g mint pnpm --filter @roomote/docs dev ``` diff --git a/apps/docs/package.json b/apps/docs/package.json index a02f5e95a..8ce330940 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -5,11 +5,11 @@ "scripts": { "generate-cookbook-index": "node scripts/generate-cookbook-index.mjs", "check-cookbook-index": "node scripts/generate-cookbook-index.mjs --check", - "dev": "pnpm run generate-cookbook-index && mint dev", - "validate": "pnpm run generate-cookbook-index && mint validate", - "check-links": "mint broken-links", + "dev": "pnpm run generate-cookbook-index && pnpm dlx --package mint@4.2.650 mint dev", + "validate": "pnpm run generate-cookbook-index && pnpm dlx --package mint@4.2.650 mint validate", + "check-links": "pnpm dlx --package mint@4.2.650 mint broken-links", "check": "pnpm run validate && pnpm run check-links", - "build": "pnpm run generate-cookbook-index && mint validate" + "build": "pnpm run generate-cookbook-index && pnpm dlx --package mint@4.2.650 mint validate" }, "dependencies": { "yaml": "^2.9.0" From 8d9864b9e0de412bcaa83fd553f1bce8411291b2 Mon Sep 17 00:00:00 2001 From: Bruno Bergher Date: Mon, 3 Aug 2026 20:04:14 +0100 Subject: [PATCH 13/13] fix --- apps/docs/cookbook/support-channel.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/cookbook/support-channel.mdx b/apps/docs/cookbook/support-channel.mdx index 6de79ddf5..9dcf8d3ac 100644 --- a/apps/docs/cookbook/support-channel.mdx +++ b/apps/docs/cookbook/support-channel.mdx @@ -19,7 +19,7 @@ survives triage. - **Setup time**: About 45 minutes - **Requires**: Admin access, Slack or Discord, observability or data integration - **Serves**: Support, Engineers -- **Cooked By**: [Matt](https://github.com/brunobergher) from [Roomote](https://roomote.dev) +- **Cooked By**: John Stearns from [Roo Vet](https://roo.vet) ## Ingredients