> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rheos.app/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP workflow recipes

> End-to-end recipes for driving Rheos from your AI chat — drafting from a URL, planning a week of content, generating images and rendering video.

<Warning>
  **Work in progress** — connector not yet publicly available. Email **[hello@rheos.app](mailto:hello@rheos.app)** for early access.
</Warning>

Concrete patterns for what Rheos-in-your-chat looks like. Each one is a natural-language prompt — your assistant figures out which tools to call. Use them as inspiration for your own workflows.

<Note>
  Every workflow starts the same way: `rheos_list_brands` to discover the brand, then `rheos_get_context` to load identity + pillars + formulas. We omit those two calls from the recipes below for brevity — assume they happen first.
</Note>

## 1. Draft a post from a URL

**Goal:** *"Read this article and write a LinkedIn post about it in my brand voice."*

<Steps>
  <Step title="Scrape the URL">
    Use `rheos_scrape_website` if it's the brand's own site, or have the assistant fetch the page text directly (most clients can fetch HTTP). For an article on rheos.app, `rheos_fetch_docs` returns clean markdown.
  </Step>

  <Step title="Pick a formula">
    Read the response from `rheos_get_formulas` (already loaded via `rheos_get_context`). Pick an `intent`, `hookId` and `ctaId` that fit the article.
  </Step>

  <Step title="Write the body">
    The assistant writes the post text itself — no tool call needed. Brand voice comes from the identity document loaded in step 0.
  </Step>

  <Step title="Persist the draft">
    Call `rheos_create` with `resource_type="posts"`:

    ```json theme={null}
    {
      "resource_type": "posts",
      "brand_id": "default_f7634e61",
      "fields": {
        "textBody": "Three lessons from how Stripe handled...",
        "intent": "educate",
        "hookId": "number-stat",
        "ctaId": "learn-more",
        "channels": ["linkedin"]
      }
    }
    ```
  </Step>

  <Step title="Review or schedule">
    The post is now visible in the dashboard. If the user is happy, call `rheos_schedule_post` with an ISO timestamp, or `rheos_publish_post` to go out immediately.
  </Step>
</Steps>

## 2. One-shot post from an image

**Goal:** *"Here's a photo from yesterday's event — draft an Instagram post."*

The fast path is `rheos_draft_post_from_image`, which uploads the image and
drafts a caption in a single call:

```json theme={null}
{
  "brand_id": "default_f7634e61",
  "image_base64": "iVBORw0KGgoAAAANS...",
  "topic": "team off-site, Friday",
  "hook_type": "Behind the Scenes"
}
```

The response includes the new `post_id` and `asset_id`. If the caption
needs tweaking, follow up with `rheos_update`. Then schedule or publish as in
workflow 1.

<Note>
  Use `rheos_upload_image` instead when you want to stage the image for later — for example, uploading a batch of product shots before deciding which one to pair with which post.
</Note>

## 3. Schedule a week of content

**Goal:** *"Plan five posts for next week — Mon/Wed/Fri on LinkedIn, Tue/Thu on Instagram."*

<Steps>
  <Step title="Generate the idea queue">
    Call `rheos_generate_ideas` with `count: 5` and any formula bias the user supplied. Returns five `idea_ids` as posts with `status="idea"`.

    ```json theme={null}
    {
      "brand_id": "default_f7634e61",
      "count": 5
    }
    ```
  </Step>

  <Step title="Present and refine">
    Show the ideas to the user. If they don't like one, call `rheos_refresh_idea` to regenerate it in place. If they want a totally different angle, call `rheos_generate_ideas` again with a different formula bias.
  </Step>

  <Step title="Accept the keepers">
    For each idea the user picks, call `rheos_accept_idea` — this flips the status to `draft`.
  </Step>

  <Step title="Write each body">
    For each accepted idea, the assistant writes the full post body in brand voice, then `rheos_update` saves it:

    ```json theme={null}
    {
      "resource_type": "posts",
      "id": "post_abc123",
      "fields": {
        "textBody": "...",
        "channels": ["linkedin"]
      }
    }
    ```
  </Step>

  <Step title="Schedule each one">
    Call `rheos_schedule_post` per post with the chosen `scheduled_at` ISO timestamp.

    ```json theme={null}
    {
      "post_id": "post_abc123",
      "scheduled_at": "2026-05-20T09:00:00Z"
    }
    ```
  </Step>
</Steps>

The dashboard calendar will show the full week — the user can drag posts
around there too, or come back to the MCP with *"cancel Wednesday's post"*
and the assistant will call `rheos_cancel_scheduled`.

## 4. Update the brand identity from a new website

**Goal:** *"We just relaunched our website — re-import the brand from there."*

<Steps>
  <Step title="Scrape the new site">
    ```json theme={null}
    {
      "brand_id": "default_f7634e61",
      "url": "https://acme.com"
    }
    ```

    `rheos_scrape_website` populates the brand's website source and versions the old one.
  </Step>

  <Step title="Re-synthesise the identity doc">
    ```json theme={null}
    {
      "brand_id": "default_f7634e61",
      "regenerate": true
    }
    ```

    `rheos_trigger_identity_doc_flow` reads every active source and writes a fresh identity document. Pass `regenerate: true` to bypass the cache.
  </Step>

  <Step title="Review">
    Call `rheos_view_brand_document` to read the new markdown. If metadata fields look off (tone, audiences), patch them with `rheos_update_brand_metadata` instead of re-running the full flow.
  </Step>
</Steps>

<Warning>
  Personal brands don't have a website source — use `rheos_update_ai_import` to feed in markdown directly instead of `rheos_scrape_website`.
</Warning>

## 5. Produce and review a short-form video

**Goal:** *"Here's a draft video session — render it, get AI feedback, and apply the fixes."*

This is the video-pipeline loop. Sessions are created in the dashboard; the
MCP picks up from "session exists, scenes drafted":

<Steps>
  <Step title="Inspect the session">
    `rheos_video_get_session` returns the current scene list.
  </Step>

  <Step title="Edit if needed">
    Use `rheos_video_update_scenes` to make changes — but only for explicit
    user edits. AI-suggested edits should go through
    `rheos_video_apply_suggestions` (preserves layer ids).
  </Step>

  <Step title="Render">
    `rheos_video_render` kicks off Lambda. Returns `render_id` and `bucket_name`.

    ```json theme={null}
    { "session_id": "vid_xyz" }
    ```
  </Step>

  <Step title="Poll progress">
    Call `rheos_video_render_progress` every 3–5 seconds. Typical render is
    30–90 s for a 15-second clip. When `done: true`, the response includes
    the MP4 URL.
  </Step>

  <Step title="AI review">
    `rheos_video_review` sends the MP4 to Gemini and returns text
    suggestions ("tighten the cut at 0:04, the hook subtitle reads after the
    visual change").
  </Step>

  <Step title="Apply suggestions and re-render">
    `rheos_video_apply_suggestions` patches the scenes from the review,
    then loop back to step 3.
  </Step>
</Steps>

Three iterations is usually enough. Once the user signs off, the final MP4
can be attached to a post via `rheos_create` (`assetIds`) or published
directly through the video session's own publish flow in the dashboard.

## 6. Connect a new social channel

**Goal:** *"Connect this brand's TikTok account."*

OAuth has to happen in a browser — the MCP can't complete it directly. The
flow is:

<Steps>
  <Step title="Generate the deep-link">
    `rheos_connect_platform` with `channel: "tiktok"` and the `brand_id`.
    Returns a `dashboard.rheos.app/settings/integrations?...` URL the user opens to
    complete OAuth (the response status is `url_handoff_required` — it does **not** mean
    the platform is connected yet).
  </Step>

  <Step title="User opens it">
    The assistant tells the user to open the URL. They sign in to TikTok and
    approve.
  </Step>

  <Step title="Verify">
    After approval, call `rheos_get_platforms` (or `rheos_get_context`) to
    confirm the channel is now connected. The new platform is then available
    as a `channels` value on `rheos_create`, `rheos_schedule_post`, and
    `rheos_publish_post`.
  </Step>
</Steps>

## Tips

* **Start every session with `rheos_list_brands` + `rheos_get_context`.** It seeds the assistant with brand voice, formulas, audiences and themes — everything else gets cheaper after that.
* **Prefer one-shot tools.** `rheos_draft_post_from_image` beats `rheos_upload_image` + `rheos_create`. `rheos_get_context` beats five separate reference calls.
* **Read the `next_step` hints.** Every Rheos tool response includes a `next_step` field nudging the caller toward the right follow-up tool. The assistant should treat it as a strong signal.
* **Credits are deducted on success.** Failed `rheos_image_generate` or `rheos_video_render` calls don't charge; check `rheos_get_credits` if you're worried about budget.