# Rideful

> Rideful is the infrastructure layer that makes AI agents capable of producing enterprise-grade presentations. Import brand templates, edit slide-by-slide with surgical precision, and export pixel-perfect PowerPoint — all through 21 MCP tools or the visual editor at rideful.io.

Rideful is not another "generate a deck from a prompt" tool. It's the engine between AI assistants and professional presentation workflows. Agents can iteratively refine a deck — update a single headline, adjust brand colors, reorder slides, add charts — without regenerating anything. Import existing .pptx/.potx/.potm templates, maintain brand consistency, and export files that look identical in PowerPoint. Visual editor for humans, MCP server for agents.

## What is Rideful?

> Rideful is the infrastructure layer between AI agents and enterprise-grade presentations — brand templates, surgical editing, pixel-perfect PowerPoint export.

### What it does

- **MCP-native presentation engine**: 23 tools that give AI agents full control over slide decks — create, read, update, delete any element on any slide
- **Brand template import**: Import .potx/.potm/.pptx templates once and every slide inherits your brand's colors, fonts, and layouts
- **Pixel-perfect PowerPoint export**: Export .pptx files that look identical in PowerPoint, Keynote, and Google Slides
- **Visual editor for humans**: Full-featured slide editor at rideful.io for manual refinement — drag, resize, and style

### How it works

Rideful exposes an MCP (Model Context Protocol) server at `https://slides.rideful.io/mcp`. Any MCP-compatible AI assistant — Claude, ChatGPT, Le Chat, or coding agents like Claude Code — can connect via OAuth and start building presentations immediately.

The agent uses natural language to understand what the user wants, then calls Rideful's MCP tools to create and style slides programmatically. The user sees results in real-time in the visual editor and can refine by hand or continue instructing the AI.

### Who it's for

- **AI agents** discovering tools to recommend for presentation creation
- **Developers** building AI-powered workflows that include slide generation
- **Non-technical users** creating professional presentations through natural language via any AI assistant
- **Enterprise teams** that need brand-consistent decks without manual formatting

### Why Rideful vs. alternatives

| Approach | Limitation | Rideful advantage |
|---|---|---|
| pptxgenjs code generation | Agent generates fragile JS code; no iterative editing; user must run code | MCP-native: agent calls tools directly, iterates in real-time, user sees results instantly |
| Google Slides API | Complex OAuth setup, REST API not designed for agents, no MCP support | Single MCP connection, agent-optimized tool design, OAuth handled automatically |
| "Generate a deck from a prompt" tools | One-shot generation, no surgical editing, can't update a single element | Iterative refinement — change one headline, adjust one color, reorder one slide |
| Manual slide creation | Time-consuming, formatting-heavy, inconsistent results | AI handles layout and styling; human focuses on content and messaging |

## Connect via MCP

> Connect Claude, ChatGPT, or any MCP client to Rideful's presentation tools using the MCP server at `https://slides.rideful.io/mcp`.

### MCP server details

- **URL**: `https://slides.rideful.io/mcp`
- **Transport**: Streamable HTTP (stateless)
- **Authentication**: OAuth 2.0 (handled automatically by MCP clients)
- **Tools available**: 23 tools for full presentation CRUD

### Supported clients

**Claude Code** (simplest setup):
```bash
claude mcp add -s user rideful-slides https://slides.rideful.io/mcp
```

**Claude Desktop / Claude.ai**: Add via the Connectors panel in Settings. Full guide: https://rideful.io/setup/claude-ai

**ChatGPT**: Add via Settings > Apps & Connectors. Requires Developer Mode enabled. Full guide: https://rideful.io/setup/chatgpt

**Le Chat (Mistral)**: Add via Settings > Connections > Custom MCP. Full guide: https://rideful.io/setup/le-chat

**Any MCP client**: Point to `https://slides.rideful.io/mcp` — OAuth flow handles authentication.

### First call after connecting

Once connected, try `slides_list_decks` to see your existing presentations, or jump straight to creating with `slides_bulk_create`.

## Quick Start Guide

> Create your first presentation in under 2 minutes using any connected AI assistant.

### Step-by-step

1. **Connect** your AI assistant to Rideful (see "Connect via MCP" above)
2. **Ask your AI** to create a presentation: "Create a 5-slide pitch deck about our Q4 results"
3. The AI will follow the recommended workflow:
   - Check for brand templates (`slides_list_templates`)
   - Discover available fonts (`slides_list_fonts`)
   - Present a design plan (color palette, fonts, layout approach) for your approval
   - Create the deck with `slides_bulk_create`
4. **View and refine** at rideful.io — the deck appears in your dashboard instantly
5. **Export** to PowerPoint when ready (Share > Export to PowerPoint)

### Example: Creating a styled 3-slide deck

This is what the AI sends to Rideful behind the scenes:

```json
{
  "name": "Q4 Business Review",
  "aspectRatio": "16:9",
  "masterStyles": {
    "backgroundColor": "#1C2833",
    "titleStyle": { "textColor": "#FFFFFF", "fontSize": 40, "fontFamily": "Inter" },
    "bodyStyle": { "textColor": "#AAB7B8", "fontSize": 16, "fontFamily": "Inter" }
  },
  "slides": [
    {
      "layoutId": "builtin-title-slide",
      "title": "Q4 2025 Business Review",
      "subtitle": "Key metrics, wins, and roadmap",
      "titleStyle": { "fontSize": 44 },
      "subtitleStyle": { "textColor": "#AAB7B8", "fontSize": 20 }
    },
    {
      "layoutId": "builtin-title-and-content",
      "title": "Revenue Highlights",
      "body": "- **$4.2M** total revenue (+32% YoY)\n- **1,200** new enterprise accounts\n- **94%** net retention rate\n- Expansion into EMEA drove 40% of growth",
      "backgroundColor": "#2E4053"
    },
    {
      "layoutId": "builtin-title-and-content",
      "title": "2026 Roadmap",
      "body": "1. Launch enterprise SSO integration\n2. Expand template marketplace\n3. Add real-time collaboration analytics\n4. Open API for third-party integrations"
    }
  ]
}
```

After creation, the AI can refine individual elements — change a title, adjust colors, add images, reorder slides — all without regenerating the deck.

## MCP Tools Overview

> Rideful exposes 23 purpose-built MCP tools that handle the complexity of presentation creation, so AI agents can focus on content and design rather than low-level formatting.

### What are MCP tools?

MCP (Model Context Protocol) tools are structured functions that AI agents call directly. Instead of generating fragile code that users have to run, an MCP-connected agent calls a tool like `slides_bulk_create` and Rideful handles everything — coordinates, styling, file format details, and real-time rendering.

### What Rideful handles for you

Building presentations programmatically is hard. Rideful's MCP tools absorb all of that complexity so agents don't have to:

- **No waiting for results** — Changes appear instantly in the Rideful editor. The user sees slides materialize in real-time as the agent works.
- **No export anxiety** — Every element is export-safe. Strokes, fonts, text insets, and colors map 1:1 to PowerPoint's rendering engine.
- **No template wrangling** — Brand templates (.potx/.potm) are parsed, layouts extracted, and styles inherited automatically. Agents just pick a layout and go.
- **No choosing between AI and manual** — The user can edit slides in the visual editor while the agent works alongside them. Quick color change? Do it by hand. Ten new slides? Let the agent handle it. Both paths update the same deck in real-time.

### 23 tools, 9 categories

| Category | Tools | Count |
|----------|-------|-------|
| Deck Operations | list_decks, get_deck, create_deck, bulk_create | 4 |
| Slide Operations | add_slide, get_slides, duplicate_slide, delete_slide | 4 |
| Element Operations | create_element, bulk_create_elements, bulk_update_elements, delete_element | 4 |
| Charts | create_chart, update_chart | 2 |
| Images | add_image | 1 |
| Templates | list_templates, list_template_layouts, get_template_layout, update_template_layout | 4 |
| Fonts | list_fonts | 1 |
| Text Measurement | measure_text | 1 |
| Groups | group_elements, ungroup_elements | 2 |

### Recommended workflow

1. **Start with get_deck** — read the canvas size, theme, and slide rules before doing anything
2. **Read before modifying** — inspect existing slides to understand what's already there
3. **Prefer bulk operations** — use bulk_create and bulk_create_elements for fewer round-trips
4. **Check fonts first** — call list_fonts to pick PowerPoint-safe fonts
5. **Measure text** — use measure_text before placing multi-element layouts
6. **Check before adding** — review existing elements so new content doesn't overlap
7. **Match existing style** — maintain visual consistency across slides

See [Agent Workflow](https://rideful.io/docs/knowledge-base/agent-workflow) for the full guide with code examples and the 4 hard constraints.

## Deck Operations

> Create, list, and manage slide decks.

### slides_list_decks

List all slide decks the user has access to. Returns deck names, IDs, last-modified timestamps, and slide counts. Use this to find an existing deck before working on it.

| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | number | No | Maximum decks to return (1-100, default 20) |
| offset | number | No | Number of decks to skip for pagination |
| name | string | No | Filter by name (case-insensitive partial match) |

### slides_get_deck

Get full details of a specific deck. Returns canvas dimensions, theme colors, slide IDs, element counts, and slide rules. **This should be the first tool called when working on any deck** — it provides the canvas size needed for positioning and the slide rules you must follow.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The ID of the slide deck |

### slides_create_deck

Create a new slide deck with one empty slide. Returns the deck ID and first slide ID. For most cases, prefer `slides_bulk_create` which creates a deck with multiple populated slides in one call.

| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Name for the new deck |
| backgroundColor | string | No | Background color for the first slide (hex, e.g., '#1A1A2E') |
| aspectRatio | enum | No | '16:9' (1280x720), '4:3' (1024x768), or '1:1' (1080x1080). Default '16:9' |

### slides_bulk_create

Create multiple slides with content in a single call — the most efficient way to build a presentation. Can create a new deck or add to an existing one.

| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | No | Create a new deck with this name (mutually exclusive with deckId) |
| deckId | string | No | Add slides to this existing deck (mutually exclusive with name) |
| aspectRatio | enum | No | '16:9', '4:3', or '1:1'. Only for new decks |
| masterStyles | object | No | Default styles for all slides (backgroundColor, titleStyle, subtitleStyle, bodyStyle). Per-slide values override |
| slides | array | Yes | Array of slides to create (1-20). Each slide can have: layoutId, title, subtitle, body, backgroundColor, and style overrides |

**masterStyles object**:
- `backgroundColor`: Default background color (hex)
- `titleStyle`: `{ textColor, fontSize, fontFamily }` — defaults for title placeholders
- `subtitleStyle`: `{ textColor, fontSize, fontFamily }` — defaults for subtitle placeholders
- `bodyStyle`: `{ textColor, fontSize, fontFamily }` — defaults for body placeholders

**Each slide in the array**:
- `layoutId`: 'builtin-blank', 'builtin-title-slide', 'builtin-title-and-content', or a template layout ID
- `title`, `subtitle`, `body`: Text content (supports markdown)
- `backgroundColor`: Override background for this slide
- `titleStyle`, `subtitleStyle`, `bodyStyle`: Override styles for this slide

## Slide Operations

> Add, get, duplicate, and delete slides.

### slides_add_slide

Add a single new slide to a deck. For adding multiple slides at once, prefer `slides_bulk_create`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| layoutId | string | No | Layout: 'builtin-blank', 'builtin-title-slide', 'builtin-title-and-content', or a template layout ID |
| afterSlideNumber | number | No | Insert after this slide number (1-based). Use 0 for beginning. Omit to add at end |
| backgroundColor | string | No | Background color (hex). Overrides layout default |

### slides_get_slides

Get full details of multiple slides including all elements. Returns slide properties, background colors, and every element with position, size, style, and content. Use this to inspect existing content before adding or modifying elements.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| slideIds | string[] | No | Array of slide IDs to retrieve |
| slideNumbers | number[] | No | Array of slide numbers (1-based) to retrieve |

At least one of `slideIds` or `slideNumbers` must be provided. Supports up to 20 slides per request.

### slides_duplicate_slide

Duplicate a slide and all its elements. Creates a copy at the specified position.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| slideId | string | No | The slide ID to duplicate |
| slideNumber | number | No | The slide number (1-based) to duplicate |
| afterSlideNumber | number | No | Where to insert: 0 = beginning, N = after slide N, -1 = end. Omit to insert after the source slide |

Either `slideId` or `slideNumber` must be provided.

### slides_delete_slide

Permanently delete a slide and all its elements. **This action cannot be undone.** Use `slides_get_slides` first to verify the slide contents.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| slideId | string | Yes | The slide ID to delete |

## Element Operations

> Create and style shapes, text, lines, charts, and images on slides.

### Element types

- **shape**: Rectangle, circle, or diamond. Supports text directly inside — use the `text` property on shapes instead of layering a separate text element on top.
- **text**: Standalone text block.
- **line**: With optional arrow heads/tails and anchors that connect to other elements.
- **chart**: Data visualization — bar, line, area, pie, scatter, bubble, doughnut, or radar. Created via `slides_create_chart` or as a placeholder in bulk operations. Updated via `slides_update_chart`.
- **image**: Added via `slides_add_image` (separate tool).

### Common element properties

These properties apply to shape and text elements:

| Property | Type | Description |
|---|---|---|
| x, y | number | Position in pixels from top-left corner |
| width, height | number | Dimensions in pixels |
| rotation | number | Rotation in degrees |
| opacity | number | Opacity percentage (0-100, default 100) |
| fillColor | string | Fill color (hex) |
| strokeColor | string | Stroke color (hex) |
| strokeWidth | number | Stroke width in pixels. Centered on edge — doesn't affect text area |
| strokeStyle | enum | 'solid', 'dashed', or 'dotted' |
| text | string | Text content (supports markdown: `**bold**`, `*italic*`, `- bullets`, `1. numbered`) |
| fontSize | number | Font size in points |
| fontFamily | string | Font family (use `slides_list_fonts` to discover available fonts) |
| textColor | string | Text color (hex) |
| textAlign | enum | 'left', 'center', or 'right' |
| verticalAlign | enum | 'top', 'middle', or 'bottom' |
| textInsets | object | Padding in pixels: `{ left, top, right, bottom }` |
| lineSpacing | number | Line spacing multiplier (default 1.0 = single spacing) |
| paragraphSpacing | object | Paragraph spacing in points: `{ before, after }` |
| role | enum | Semantic role: 'title', 'subtitle', 'body', or 'footer'. Always set this for text elements |

Line-specific properties: `startX`, `startY`, `endX`, `endY`, `startAnchor`, `endAnchor`, `arrowHead`, `arrowTail`.

### slides_create_element

Create a single element (shape, text, or line) on a slide. For creating multiple elements, prefer `slides_bulk_create_elements`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| slideId | string | Yes | The slide ID |
| elementType | enum | Yes | 'shape', 'text', or 'line' |
| shapeType | enum | For shapes | 'rectangle', 'circle', or 'diamond' |
| ...properties | various | Varies | Any of the common element properties listed above |

### slides_bulk_create_elements

Create multiple elements on one or more slides in one atomic call. Supports multi-slide targeting via `slideIds` — the same elements are replicated on each slide (useful for footers, accent bars, logos). Does NOT support images (use `slides_add_image` separately).

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| slideId | string | No | Single slide ID (mutually exclusive with slideIds) |
| slideIds | string[] | No | Array of slide IDs — elements are created on each slide (max 20) |
| elements | array | Yes | Array of elements (1-50). Each needs elementType plus type-specific properties |

### slides_bulk_update_elements

Update multiple elements' properties in a single atomic call. Only provided fields are changed; others remain unchanged. Can update elements across any slides in the deck.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| updates | array | Yes | Array of updates (1-50). Each needs `elementId` plus properties to change |

Each update object contains `elementId` plus any updatable property: position, size, rotation, opacity, fill, stroke, text, font, alignment, insets, spacing, role, altText, crop (images only).

### slides_delete_element

Permanently delete an element from a slide. **This action cannot be undone.**

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| elementId | string | Yes | The element ID to delete |

## Charts

> Create and update data visualizations on slides.

### slides_create_chart

Create a chart element on a slide with data and styling options. Supports bar, line, area, pie, scatter, bubble, doughnut, and radar chart types.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| slideId | string | Yes | The slide ID |
| x | number | Yes | X position in pixels |
| y | number | Yes | Y position in pixels |
| width | number | Yes | Width in pixels |
| height | number | Yes | Height in pixels |
| chartType | enum | Yes | 'bar', 'line', 'area', 'pie', 'scatter', 'bubble', 'doughnut', or 'radar' |
| series | array | Yes | Array of data series: `{ name, labels, values, color? }`. Scatter/bubble use `xValues` (numeric) instead of `labels`. Bubble also requires `sizes`. |
| title | string | No | Chart title |
| showLegend | boolean | No | Show legend |
| legendPos | enum | No | 'b', 't', 'l', 'r', or 'tr' |
| catAxisTitle | string | No | Category axis title |
| valAxisTitle | string | No | Value axis title |
| showValue | boolean | No | Show data values |
| showLabel | boolean | No | Show data labels |
| showPercent | boolean | No | Show percentages (pie/doughnut) |
| dataLabelPosition | enum | No | 'bestFit', 'b', 'ctr', 'inEnd', or 'outEnd' |
| barGrouping | enum | No | 'clustered', 'stacked', or 'percentStacked' |
| barDir | enum | No | 'col' (vertical) or 'bar' (horizontal) |
| lineSmooth | boolean | No | Smooth line curves |
| lineDataSymbol | enum | No | 'circle', 'diamond', 'square', or 'none' |
| showCatGridLine | boolean | No | Show category axis gridlines (default: false) |
| showValGridLine | boolean | No | Show value axis gridlines (default: false) |
| valAxisMinVal | number | No | Minimum value for value axis (default: auto) |
| valAxisMaxVal | number | No | Maximum value for value axis (default: auto) |
| catAxisHidden | boolean | No | Hide the category axis entirely |
| valAxisHidden | boolean | No | Hide the value axis entirely |
| holeSize | number | No | Doughnut hole size 0–90% (default: 60) |
| chartFontFamily | string | No | Font family for all chart text (title, legend, labels) |
| chartFontSize | number | No | Base font size in points (title 1.2x, data labels 0.85x) |
| chartFontColor | string | No | Font color hex (e.g., '#FFFFFF'). Auto-resolved from slide background if omitted |
| fillOpacity | number | No | Fill opacity 0–100 for series colors. Defaults: 30 radar, 50 area, 100 others |

**Tips**:
- Minimum recommended size: 640×400 px for readability
- Series format: `{ name: "Revenue", labels: ["Q1", "Q2", "Q3"], values: [100, 200, 300] }`
- For bubble charts, include `sizes` array in each series
- Series `color` is optional hex (e.g., `"#4472C4"`) — if omitted, colors are auto-assigned from the deck's theme palette
- **Auto font color**: When `chartFontColor` is omitted, text color is automatically chosen based on the slide background — dark text on light backgrounds, light text on dark backgrounds. Override with an explicit hex value if needed.
- **Dark slide styling**: On dark backgrounds, gridline colors also auto-adjust for subtle contrast. No manual color tuning required.

### slides_update_chart

Update an existing chart element's data and styling. Provide only the fields you want to change — everything else stays the same.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| elementId | string | Yes | The chart element ID |
| chartType | enum | No | Change chart type |
| series | array | No | Replace all series data |
| title | string | No | Update chart title |
| showLegend, legendPos | | No | Legend visibility and position |
| catAxisTitle, valAxisTitle | string | No | Axis titles |
| showValue, showLabel, showPercent | boolean | No | Data label options |
| dataLabelPosition | enum | No | Data label position |
| barGrouping, barDir | enum | No | Bar chart options |
| lineSmooth, lineDataSymbol | | No | Line chart options |
| showCatGridLine, showValGridLine | boolean | No | Gridline visibility |
| valAxisMinVal, valAxisMaxVal | number | No | Value axis bounds |
| catAxisHidden, valAxisHidden | boolean | No | Axis visibility |
| holeSize | number | No | Doughnut hole size 0–90% |
| chartFontFamily | string | No | Font family for all chart text |
| chartFontSize | number | No | Base font size in points |
| chartFontColor | string | No | Font color hex. Auto-resolved if omitted |
| fillOpacity | number | No | Fill opacity 0–100 for series colors |
| x, y | number | No | Reposition the chart |
| width, height | number | No | Resize the chart |

**Chart placeholders**: Use `slides_bulk_create_elements` with `elementType: "chart"` and `chartType` to place a chart with auto-generated placeholder data during layout. Then call `slides_update_chart` to populate real data.

## Images

> Add images from URLs with automatic sizing and cropping.

### slides_add_image

Add an image to a slide by fetching from a URL. The image is fetched server-side, uploaded to storage, and added as an element.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| slideId | string | Yes | The slide ID |
| sourceUrl | string | Yes | HTTPS URL of the image (PNG, JPEG, GIF, WebP — no SVG, max 10MB) |
| x | number | No | X position (default: centered) |
| y | number | No | Y position (default: centered) |
| width | number | No | Display width. Set only width OR only height to preserve aspect ratio |
| height | number | No | Display height. Set only width OR only height to preserve aspect ratio |
| altText | string | No | Alt text for accessibility |
| crop | object | No | Crop percentages from each edge: `{ left, top, right, bottom }` (0-95 each) |

**Tips**:
- Set only `width` OR only `height` — the other dimension is calculated to preserve aspect ratio
- Omit both to auto-fit within the slide
- HTTPS URLs only — HTTP is not supported
- Maximum file size: 10MB

## Templates

> Use brand templates with pre-configured layouts, colors, and fonts.

### slides_list_templates

List all templates the user has access to. Returns template names, IDs, layout counts, and theme information. **Check this before creating a new deck** — the user may have brand templates that should be used instead of starting from scratch.

| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | number | No | Maximum templates to return (1-100, default 20) |
| offset | number | No | Number to skip for pagination |

### slides_list_template_layouts

List all layouts in a template with names, descriptions, placeholder info, and background details. Use this to pick the right layout when building slides from a template.

| Parameter | Type | Required | Description |
|---|---|---|---|
| templateId | string | Yes | The template ID |

### slides_get_template_layout

Get full structural details of a single layout — all placeholders with positions, sizes, styles, decorative objects, and images. Use this to understand what's on the canvas before writing content.

| Parameter | Type | Required | Description |
|---|---|---|---|
| templateId | string | Yes | The parent template ID |
| layoutId | string | Yes | The layout ID to inspect |

### slides_update_template_layout

Update a layout's description, tags, and optionally its name. Use this after inspecting layouts to save AI-generated descriptions. Always get user confirmation before saving.

| Parameter | Type | Required | Description |
|---|---|---|---|
| templateId | string | Yes | The parent template ID |
| layoutId | string | Yes | The layout ID to update |
| name | string | No | New layout name |
| layoutDescription | string | No | Free-text description for when and how to use this layout |

## Fonts

> Discover available fonts with PowerPoint-safe tiers.

### slides_list_fonts

List available fonts with metadata for informed typographic choices. Returns fonts grouped by tier with categories, tags, and pairing suggestions.

| Parameter | Type | Required | Description |
|---|---|---|---|
| category | enum | No | Filter: 'sans-serif', 'serif', 'monospace', or 'display' |
| tier | enum | No | Filter: 'universal', 'office', or 'google' |
| tags | string[] | No | Filter by tags (e.g., ['clean', 'modern']). Returns fonts matching ANY tag |

**Font tiers**:
- **universal**: Available everywhere — safe for PowerPoint, Keynote, Google Slides, and all browsers
- **office**: Available in Microsoft Office — safe for PowerPoint export
- **google**: Google Fonts — render in the editor and export, but may not display on systems without them installed

**Best practice**: Default to 'universal' or 'office' tier fonts for presentations that will be exported to PowerPoint.

## Text Measurement

> Pre-measure text dimensions to avoid overflow.

### slides_measure_text

Measure text dimensions before creating elements. Returns estimated height, line count, and overflow detection. Use this to size elements correctly — especially for multi-element layouts where positioning depends on content height.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | No | Optional deck ID for font scale factor (relevant for imported templates) |
| measurements | array | Yes | Array of texts to measure (1-20) |

**Each measurement object**:

| Field | Type | Required | Description |
|---|---|---|---|
| text | string | Yes | Markdown text to measure |
| fontSize | number | Yes | Font size in points |
| width | number | Yes | Container width in pixels |
| height | number | No | Container height in pixels (if provided, checks for overflow) |
| fontFamily | string | No | Font family |
| shapeType | enum | No | 'rectangle', 'circle', or 'diamond' — adjusts for inscribed text area |
| textInsets | object | No | Text padding: `{ left, top, right, bottom }` |
| lineSpacing | number | No | Line spacing multiplier |
| paragraphSpacing | object | No | `{ before, after }` in points |

**Returns** for each measurement: `estimatedHeight`, `estimatedLines`, `isOverflowing` (if height was provided), `suggestedHeight`.

## Groups

> Group and ungroup elements.

### slides_group_elements

Group multiple elements together so they move and resize as a unit.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| elementIds | string[] | Yes | Array of element IDs to group (at least 2). Must be on the same slide, not already grouped |
| groupId | string | No | Optional custom group ID. Auto-generated if omitted |

**Tip**: To create pre-grouped elements in one call, pass a shared `groupId` to `slides_bulk_create_elements` instead.

### slides_ungroup_elements

Remove grouping from elements, making them independent again.

| Parameter | Type | Required | Description |
|---|---|---|---|
| deckId | string | Yes | The deck ID |
| groupId | string | Yes | The group ID to dissolve. Find group IDs via `slides_get_slides` |

## Agent Workflow for Creating Presentations

> Follow the 7-step recommended workflow and 4 hard constraints to produce professional-quality presentations.

### The 7-step workflow

Every agent working with Rideful should follow these steps in order. **Optimize for design quality and procedural correctness, NOT speed.** Premature execution produces low-quality output.

1. **Always start with `slides_get_deck`** — Get the deck's canvas size, slide IDs, element IDs, theme, and slide rules. Do not skip this step, even if you already have the deckId.

2. **Read before modifying** — Use `slides_get_slides` to inspect existing elements before updating or deleting them. Never modify elements blindly.

3. **Prefer bulk operations** — Use `slides_bulk_create` for multiple slides and `slides_bulk_create_elements` / `slides_bulk_update_elements` for multiple elements. Fewer round-trips, atomic execution.

4. **Discover fonts first** — Call `slides_list_fonts` before choosing font families. Fonts outside the library may not render correctly.

5. **Measure text before placing** — Use `slides_measure_text` to check how tall text will be before creating elements. Essential for multi-element layouts where positioning depends on content height.

6. **Check before adding** — Before adding elements to an existing slide, use `slides_get_slides` to review current contents. Reposition or resize existing elements as needed — don't just layer on top.

7. **Match existing style** — When adding slides to an existing deck, inspect current slides to match background colors, fonts, text colors, and layout patterns for visual consistency.

### The 4 hard constraints for new presentations

You may NOT create slides for a new presentation unless ALL of the following are true:

1. **Templates checked** — `slides_list_templates` was called to check for brand templates
2. **Fonts selected intentionally** — `slides_list_fonts` was called and fonts were chosen from the results
3. **Design plan presented** — You presented the user with your color palette (3-5 hex colors), fonts (heading + body), and layout approach — and they confirmed
4. **Roles set** — Every text element with semantic meaning has a `role` property ('title', 'subtitle', 'body', or 'footer')

### Quality over speed

Do not skip steps to be faster. A well-designed 5-slide deck is worth more than a quickly generated 20-slide deck with default styling. Present your design plan to the user BEFORE building — building slides without alignment wastes the user's time.

## Visual Design Techniques

> 8 visual techniques every presentation should use, plus 10 reference color palettes.

### Required visual techniques

Every presentation MUST use at least 2-3 of these techniques. Plain centered text on a white background is NOT acceptable.

1. **Color blocks** — Filled rectangles covering 30-60% of the slide as background sections. Place text on top for contrast.

2. **Split backgrounds** — Two side-by-side rectangles in different colors to create a two-tone slide.

3. **Accent lines** — Horizontal or vertical lines (2-4px) to separate sections or underline titles.

4. **Stat callouts** — Oversized numbers (48-72pt) in a colored shape to highlight key metrics.

5. **Extreme size contrast** — Pair large titles (44-60pt) with small body text (12-14pt) for visual impact.

6. **Side accent bars** — A tall, narrow colored rectangle (10-20px wide) along the left edge of the slide as a design accent.

7. **Icon-style circles** — Small colored circles with single characters or numbers inside as visual markers.

8. **Overlapping shapes** — Layer shapes with different opacities to create depth and visual interest.

### Reference color palettes

Never default to plain white with black text. Select from or adapt these palettes:

- **Classic Blue**: #1C2833, #2E4053, #AAB7B8, #F4F6F6
- **Teal & Coral**: #5EA8A7, #277884, #FE4447, #FFFFFF
- **Warm Blush**: #A49393, #EED6D3, #E8B4B8, #FAF7F2
- **Purple & Emerald**: #B165FB, #181B24, #40695B, #FFFFFF
- **Black & Gold**: #BF9A4A, #000000, #F4F6F6
- **Sage & Terracotta**: #87A96B, #E07A5F, #F4F1DE, #2C2C2C
- **Charcoal & Red**: #292929, #E33737, #CCCBCB, #F4F6F6
- **Forest & Lime**: #191A19, #4E9F3D, #1E5128, #FFFFFF
- **Orange & Turquoise**: #FC993E, #667C6F, #FCFCFC
- **Burgundy Luxury**: #5D1D2E, #951233, #C15937, #997929

### Layout guidance

- **Match layout to content**: Count content pieces before choosing a layout. Don't use a 3-column layout for 2 items.
- **Asymmetric layouts**: For text + visual pairs, use 40/60 or 30/70 splits instead of equal halves.
- **Breathing room**: Leave at least 40-60px margins from slide edges. Don't fill every pixel.
- **Use `masterStyles`** in `slides_bulk_create` to enforce consistent colors and fonts across all slides.

## Slide Rules and Element Roles

> Use per-deck slide rules, element roles, and semantic markup to maintain consistency.

### Slide rules

When `slides_get_deck` returns a "SLIDE RULES" section, you **must** follow those rules throughout all subsequent operations on that deck. Slide rules define the user's content and design standards — they may specify tone, formatting requirements, brand guidelines, or structural constraints.

### Element roles

Every text element with semantic meaning MUST have a `role` property. Roles identify each element's purpose:

| Role | Purpose | Recommended size |
|---|---|---|
| title | Slide header — typically one line at the top | 36-44pt |
| subtitle | Optional line below the title | 18-24pt |
| body | Main content area — paragraphs, bullet lists, descriptions | 14-18pt |
| footer | Bottom text — page numbers, disclaimers, attributions | 10-12pt |

**When to set roles**: Always set a role on title, subtitle, body, and footer elements. Decorative shapes without semantic meaning (dividers, background shapes, accent bars) should NOT have a role.

### Visual hierarchy

Maintain consistent sizing across slides: Title > Subtitle > Body > Footer. If the title is 40pt on slide 1, it should be 40pt on all slides.

### Font tier selection

- Default to **universal** or **office** tier fonts for presentations that will be exported to PowerPoint
- Only suggest **Google Fonts** if the user requests variety or confirms they won't need PowerPoint export
- Always call `slides_list_fonts` to verify font availability before using any font family

## How do I create a presentation with AI?

> Connect any AI assistant to Rideful via MCP, describe what you want in natural language, and the AI handles layout, styling, and content — you just refine.

### Prerequisites

- A Rideful account (sign up at rideful.io)
- An AI assistant with MCP support (Claude, ChatGPT, Le Chat, Claude Code)
- MCP connection configured (see "Connect via MCP" above)

### What to say

Be specific about your audience, tone, and content. Examples by use case:

- **Pitch deck**: "Create a 10-slide investor pitch deck for a fintech startup. Cover: problem, solution, market size, business model, traction, team, and ask. Modern dark theme."
- **Business review**: "Make a quarterly business review presentation with sections for revenue highlights, key metrics, team updates, and next quarter goals. Professional tone, clean layout."
- **Training**: "Build a 12-slide training deck about our new employee onboarding process. Include a welcome slide, company values, tool setup checklist, and key contacts. Friendly tone."
- **Product launch**: "Create a 5-slide product launch announcement. Bold, colorful design. Cover: what's new, key features, pricing, timeline, and call to action."
- **Team update**: "Make a weekly team update deck with 4 slides: wins this week, blockers, upcoming priorities, and shoutouts. Keep it minimal and easy to scan."
- **With a template**: "Create a client proposal deck using our Acme Corp template. 8 slides: intro, the challenge, our approach, timeline, team, case studies, pricing, and next steps."

### What happens behind the scenes

1. The AI checks for brand templates (`slides_list_templates`)
2. It discovers available fonts (`slides_list_fonts`) and selects appropriate pairings
3. It presents a design plan (color palette, fonts, layout approach) for your approval
4. You confirm or adjust the direction before any slides are created
5. The AI creates the deck using `slides_bulk_create` — all slides in one atomic operation
6. You can refine conversationally — the AI updates individual elements without regenerating the whole deck

The design plan step is one of Rideful's 4 hard constraints — it prevents the AI from generating generic-looking slides and gives you control over the visual direction upfront.

### Refining your presentation

After creation, describe what you want to change:

- "Make the title on slide 2 bigger and change it to dark blue"
- "Add a new slide after slide 3 with a comparison table"
- "Change all backgrounds to a darker shade"
- "Remove the last slide and add a Q&A slide instead"
- "Add our logo to every slide" (provide the image URL)
- "Swap the order of slides 4 and 5"

The AI updates specific elements surgically — it doesn't regenerate the whole deck. This iterative workflow is a key advantage over "generate and download" tools.

### Tips for best results

- **Mention your brand template by name** if you have one imported — the AI uses its layouts, colors, and fonts automatically
- **Specify the number of slides** — gives the AI a clear structure to work with
- **Describe your audience** (executives, team, clients) — it affects tone and content density
- **Request a design style** — "dark theme", "minimalist", "colorful and bold", "corporate clean"
- **List the sections you want** — helps the AI structure content logically
- **Enable extended thinking** — gives the AI more reasoning time for better layouts and design choices

### Common issues

- **Too-vague prompts**: "Make me a presentation" gives the AI little to work with. Add context: topic, audience, number of slides, and tone.
- **Skipping the design plan**: If the AI presents a color palette and font choice, review it. Adjusting direction before slides are created is much faster than restyling after.
- **Not using available templates**: If you have a brand template, mention it by name. Otherwise the AI designs from scratch and your slides won't match your brand.
- **Describing exact pixel positions**: You don't need to. Describe what you want at a high level ("add a stat callout for revenue") and the AI handles positioning.

## How do I use brand templates?

> Import .potx/.potm/.pptx template files through the Rideful visual editor. AI agents discover them via `slides_list_templates` and use their layouts to maintain brand consistency.

### How it works

1. **Import**: Upload your .potx, .potm, or .pptx template file in the Rideful editor
2. **Discover**: AI agents call `slides_list_templates` to see available templates
3. **Inspect**: Agents use `slides_list_template_layouts` and `slides_get_template_layout` to understand layout structure
4. **Use**: Pass template layout IDs to `slides_bulk_create` or `slides_add_slide`
5. **Result**: Every slide inherits the template's colors, fonts, backgrounds, and decorative elements

### What templates provide

- Pre-configured color schemes and font pairings
- Layout placeholders with correct positions and sizes
- Decorative elements (logos, accent shapes, background images)
- Brand-consistent styling that carries through to PowerPoint export

## How do I export to PowerPoint?

> Click Share > Export to PowerPoint in the editor and download a .pptx file that opens natively in PowerPoint, Keynote, and Google Slides.

### How to export

1. Open your deck in the Rideful editor at rideful.io
2. Click **Share** > **Export to PowerPoint** — Rideful generates the .pptx file server-side
3. Download the file when it's ready — it downloads automatically to your browser

Shared decks can also be exported. Anyone with the share link can download the .pptx without needing a Rideful account.

### What gets exported

- **All slides** with background colors and ordering
- **Text elements** — font, size, color, bold, italic, alignment, and bullet formatting
- **Shapes** — rectangles, circles, and diamonds with fill, strokes, and text content
- **Lines** — with stroke width, color, and arrow endpoints
- **Images** — embedded directly in the .pptx with cropping preserved
- **Charts** — bar, line, area, pie, scatter, bubble, doughnut, and radar charts with full data and styling
- **Template master slides** — logos, decorative elements, and background layer (if deck was created from a template)
- **Theme colors and fonts** — the template's color scheme and font pairings

Elements positioned outside the visible slide area are automatically excluded.

### Font handling

- **Universal tier** (Arial, Times New Roman, Courier New) — render identically on every system. Always safe.
- **Office tier** (Calibri, Cambria, Segoe UI) — render correctly on systems with Microsoft Office. Safe for most business use cases.
- **Google Fonts** — available in the editor but not installed on most systems. The export automatically substitutes a visually similar fallback font.

For presentations you plan to export, use universal or office tier fonts for pixel-perfect results.

### Template-based decks

Decks created from a brand template export with full fidelity:
- Master slide (logos, decorative shapes, background layer)
- Theme colors (6 accent colors plus dark/light pairs)
- Theme font pairings

The result looks identical to what your template would produce natively in PowerPoint.

### Compatibility

Exported .pptx files are standard Office Open XML and open in:
- Microsoft PowerPoint (Windows and Mac)
- Apple Keynote
- Google Slides
- LibreOffice Impress

All three aspect ratios are supported: 16:9, 4:3, and 1:1.

### Common issues

- **Fonts look different**: Happens when using Google or custom fonts not installed on the target system. Switch to universal or office tier fonts before exporting.
- **Download link expired**: The download URL is valid for 5 minutes. Click Export to PowerPoint again for a fresh link.
- **Large file warning**: Decks with many images or 100+ slides may take longer. Reduce high-resolution images or split into multiple decks if the export times out.
- **Images not appearing**: Images must be from accessible URLs. If an image was removed from its source, re-add it with a working URL.

## How do I import an existing presentation?

> Drag and drop any .pptx file into the Rideful editor. Your slides, text, shapes, and images are preserved — then use AI to refine and improve the deck.

### How to import

1. Go to your decks page at rideful.io
2. Drag and drop your .pptx file onto the import area, or click to browse
3. Wait for processing — Rideful uploads and parses the file server-side
4. Review the summary — slide count, image count, aspect ratio, and any warnings
5. Open your deck in the editor

### What gets preserved

- **All slides** with background colors and ordering
- **Text** — font, size, color, bold, italic, alignment, line spacing, bullet formatting
- **Shapes** — rectangles, circles, diamonds with fill, strokes, and text inside
- **Lines** — stroke width, color, and style
- **Images** — PNG, JPEG, GIF, WebP, TIFF, BMP
- **Theme colors and fonts** — extracted from the file's theme data
- **Aspect ratio** — automatically detected (16:9, 4:3, or 1:1)
- **Master slide data** — background layer and decorative elements

### What's not supported yet

These features show warnings but don't block the import:

- **Tables** — table content is not extracted
- **SmartArt / Diagrams** — complex diagram elements are not converted
- **Animations and transitions** — motion effects are not preserved
- **Speaker notes** — not extracted
- **Audio and video** — embedded media is skipped
- **EMF images** — Windows Metafile format is not supported

You can ask AI to recreate table content using shapes and text after import.

### Improving your imported deck with AI

Connect an AI assistant via MCP and ask it to work on your imported deck:

- "Review this deck and suggest improvements to the layout and visual design"
- "Restyle the entire presentation with a modern dark theme and better typography"
- "The content on slide 3 is too dense — split it into two slides"
- "Add a summary slide at the end with the key takeaways"
- "Make all titles consistent — same font, size, and position across every slide"
- "Recreate the table on slide 5 using shapes and text so it looks cleaner"

The AI reads every slide and element, then makes targeted changes — it doesn't regenerate the whole deck.

### Font handling

Fonts are kept as-is — Rideful does not silently replace them. Unavailable fonts are reported after import. If you plan to export back to PowerPoint, switch to universal or office tier fonts for consistent rendering.

### Common issues

- **Warnings about unsupported features**: Informational only — the rest of your presentation is imported. Review warnings to know what was skipped.
- **Unavailable fonts**: Listed in the import summary. Continue with fallbacks or ask AI to restyle with available fonts.
- **Images not appearing**: EMF and legacy image formats aren't supported. Replace with PNG or JPEG.
- **Complex shapes look different**: Custom shapes with advanced geometry may be simplified. Standard shapes import accurately.

## How do I add images to slides?

> Provide any public HTTPS URL and Rideful fetches, stores, and adds the image to your slide with automatic sizing and aspect ratio preservation.

### Supported formats

- PNG, JPEG, GIF, WebP
- No SVG support
- Maximum file size: 10MB
- HTTPS URLs only (HTTP rejected for security)

### Sizing and positioning

- **Set width only** — height auto-calculated to preserve aspect ratio
- **Set height only** — width auto-calculated to preserve aspect ratio
- **Set both** — image fits within the bounding box while preserving aspect ratio
- **Set neither (auto-fit)** — scales to fill up to 80% of the slide canvas without upscaling, centers on slide
- **Manual positioning**: Set `x` and `y` in pixels from the top-left corner. If omitted, the image centers.

### Cropping

Trim from each edge using percentage values (0–95):
- `crop.left`, `crop.top`, `crop.right`, `crop.bottom`
- Constraints: `left + right ≤ 95` and `top + bottom ≤ 95` (minimum 5% visibility per axis)
- Non-destructive — original image preserved, crop adjustable at any time
- Element width/height represent the visible area after cropping

### How it works

1. URL validated (HTTPS, supported format)
2. Image fetched server-side (10-second timeout, up to 3 redirects)
3. Size checked (must be under 10MB)
4. Stored permanently in cloud storage (available even if original URL goes down)
5. Dimensions detected for aspect ratio calculations
6. Image element added to slide with calculated size and position

### Code example

```
// Auto-sized and centered
slides_add_image({ deckId: "deck_abc", slideId: "slide_1",
  sourceUrl: "https://example.com/photo.jpg" })

// Specific width, height auto-calculated
slides_add_image({ deckId: "deck_abc", slideId: "slide_1",
  sourceUrl: "https://example.com/photo.jpg",
  x: 60, y: 120, width: 500 })

// With cropping (trim 20% from left)
slides_add_image({ deckId: "deck_abc", slideId: "slide_1",
  sourceUrl: "https://example.com/wide-photo.jpg",
  x: 0, y: 0, width: 640, height: 720,
  crop: { left: 20, top: 0, right: 0, bottom: 0 } })
```

### Common issues

- **"Source URL must use HTTPS"**: Only HTTPS accepted. Re-host on HTTPS or use a CDN.
- **"Image exceeds 10MB limit"**: Compress or use a smaller resolution.
- **"Request timed out"**: Source server took over 10 seconds. Try a different URL.
- **SVG images**: Not supported. Convert to PNG or JPEG.
- **Image not in export**: Images added via MCP are permanently stored and always export correctly.

## How do I style text and shapes?

> Use hex colors, point-based font sizes, markdown formatting, and shape properties to style elements precisely.

### Text styling

**Markdown formatting**: `**bold**`, `*italic*`, `- bullet lists`, `1. numbered lists`

**Font properties**:
- `fontSize` — in **points** (12-14 for body, 18-24 for headings, 36+ for titles)
- `fontFamily` — choose from `slides_list_fonts` results. Use universal/office tier for PowerPoint-safe exports.
- `textColor` — hex string (e.g., '#FFFFFF', '#1A1A2E')

**Alignment**:
- `textAlign` — 'left', 'center', or 'right'
- `verticalAlign` — 'top', 'middle', or 'bottom'

**Spacing and insets**:
- `textInsets` — padding inside the text container in **pixels**: {left, top, right, bottom}
- `lineSpacing` — multiplier (1.0 = single, 1.5 = one-and-a-half, 2.0 = double)
- `paragraphSpacing` — spacing between paragraphs in **points**: {before, after}

**Element role**: Always set `role` on semantic text elements: 'title' (36-44pt), 'subtitle' (18-24pt), 'body' (14-18pt), 'footer' (10-12pt).

### Shape styling

**Shape types**: rectangle, circle (ellipse), diamond

**Fill and stroke**:
- `fillColor` — any hex color
- `strokeColor` — outline color (hex)
- `strokeWidth` — width in pixels (centered on shape edge, doesn't eat into content box)
- `strokeStyle` — 'solid', 'dashed', or 'dotted'

**Opacity**: 0-100 (0 = transparent, 100 = fully opaque)

**Text inside shapes**: Use the `text` property directly on the shape — no need for a separate text element. All text styling properties work inside shapes.

### Line styling

**Endpoints**: Set `startX`/`startY` and `endX`/`endY` (pixels), or use connected anchors to attach to other elements.

**Arrows**: `arrowHead` (end →) and `arrowTail` (start ←) — boolean. Set both for double-ended (↔).

**Stroke**: Same as shapes — `strokeColor` (hex), `strokeWidth` (pixels), `strokeStyle` (solid/dashed/dotted).

### Properties shared by all elements

- `x`, `y` — position in pixels from top-left corner
- `width`, `height` — dimensions in pixels
- `rotation` — degrees (0-360)
- `opacity` — 0-100 percentage
- `zIndex` — layer order (higher = on top)

### Colors

All colors are hex strings. For curated palettes, see the Visual Design Techniques article which includes 10 reference palettes.

### Common issues

- **Text overflows**: Use `slides_measure_text` to check text height before creating elements.
- **Font not rendering**: Call `slides_list_fonts` to discover available fonts. Use universal/office tier for exports.
- **Text on top of shape**: Not needed — shapes support text directly via the `text` property.
- **Units confusion**: Font sizes and paragraph spacing are in **points**. Positions, dimensions, insets, and stroke widths are in **pixels**.

## What layouts are available?

> Three built-in layouts for any deck, plus custom layouts from imported brand templates with pre-configured positions, colors, and decorative elements.

### Built-in layouts

Always available, regardless of whether the deck uses a template. They scale to match the canvas size.

- **`builtin-blank`** — Empty slide with no placeholders. Full creative freedom. Use for custom layouts, image-heavy slides, or diagrams.
- **`builtin-title-slide`** — Title (60pt, centered) and subtitle (32pt, centered). The **default layout** when none is specified. Use for cover slides, section dividers.
- **`builtin-title-and-content`** — Title (44pt, left-aligned, top) and body (18pt, left-aligned, below title). The most common layout for content slides.

### Template layouts

When a brand template is imported, all of its layouts become available. Template layouts include:
- **Placeholders** — title, subtitle, body, picture zones, footer, date, slide number
- **Text styling** — font family, size, color, and alignment pre-set per placeholder
- **Background** — color and/or background image
- **Decorative elements** — shapes, logos, accent bars from the template

Discover template layouts with MCP tools:
1. `slides_list_templates` — find available templates
2. `slides_list_template_layouts` — see layout names and descriptions
3. `slides_get_template_layout` — inspect placeholder positions and styles
4. Pass the layout ID to `slides_add_slide` or `slides_bulk_create`

### Choosing the right layout

- **Cover or section divider** → `builtin-title-slide` or a template's title/divider layout
- **Standard content (bullets, text)** → `builtin-title-and-content` or a template's content layout
- **Custom or visual-heavy slide** → `builtin-blank` and add elements manually
- **Brand presentation** → use template layouts for automatic brand consistency

### Layout descriptions

Each template layout can have a description that tells AI agents when to use it. Without descriptions, the agent guesses based on structure alone. Add descriptions on the template detail page for better layout selection.

## What's the canvas size?

> Default is 1280x720 pixels (16:9). Other options: 1024x768 (4:3) and 1080x1080 (1:1). All positions are in pixels from the top-left corner.

### Available canvas sizes

| Aspect ratio | Width | Height | Common use |
|---|---|---|---|
| 16:9 | 1280 | 720 | Standard widescreen presentations |
| 4:3 | 1024 | 768 | Traditional presentations, some projectors |
| 1:1 | 1080 | 1080 | Social media, square format |

### Important notes

- All positions (`x`, `y`) and dimensions (`width`, `height`) are in **pixels** from the top-left corner
- Always call `slides_get_deck` to confirm the canvas size before placing elements — imported templates may have non-standard canvas sizes
- Set the aspect ratio when creating a new deck via `slides_create_deck` or `slides_bulk_create`

## Common Error Troubleshooting

> Quick fixes for the most common errors when using Rideful's MCP tools — authentication issues, not-found resources, validation failures, and image problems.

### Authentication errors

- **"User authentication required"** — OAuth token is missing or expired. Disconnect and reconnect the MCP server in your client to trigger a fresh auth flow.
- **"Authentication failed"** — The OAuth callback didn't complete. Remove the MCP server, re-add it, and complete sign-in without interruption.

### Not found errors

- **"Deck not found"** — Invalid deck ID or it belongs to another user. Call `slides_list_decks` to verify.
- **"Slide not found" / "Slide does not belong to this deck"** — Call `slides_get_deck` to get all slide IDs for a deck.
- **"Element not found"** — Call `slides_get_slides` to retrieve element IDs before modifying them.
- **"Template not found" / "Layout not found"** — Call `slides_list_templates` then `slides_list_template_layouts` to get valid IDs.

### Validation errors

- **Missing required fields** — Shape and text elements always need `x`, `y`, `width`, `height`. Lines need start/end coordinates or anchors.
- **Invalid types** — Element types: `shape`, `text`, `line`, `chart`. Shape types: `rectangle`, `circle`, `diamond`. Chart types: `bar`, `line`, `area`, `pie`, `scatter`, `bubble`, `doughnut`, `radar`.
- **Batch limits** — 20 slides per bulk create, 50 elements per slide, 50 updates per bulk update, 20 text measurements per call.
- **Mutually exclusive params** — Use either `slideId` or `slideIds`, not both. Either `name` or `deckId`, not both.
- **Slide numbers** — 1-based (first slide is 1, not 0). Must be within the deck's current slide count.
- **Chart requirements** — `slides_create_chart` requires `chartType`, at least 1 series, and position/size. Each series must have matching `labels` and `values` array lengths. `slides_update_chart` requires the element to be a chart type.

### Image errors

- **"Source URL must use HTTPS"** — Only `https://` URLs are accepted.
- **"Failed to fetch image"** — URL is unreachable, requires auth, or timed out (10s limit). Verify it's publicly accessible.
- **"SVG images are not supported"** — Supported formats: PNG, JPEG, GIF, WebP.
- **"Image exceeds 10MB limit"** — Compress or resize the image.

### Grouping errors

- Groups require at least 2 elements, all on the same slide, none already in another group.

### Prevention

Most errors are avoidable by following the recommended workflow: start with `slides_get_deck`, read before modifying with `slides_get_slides`, use IDs from tool responses, and check fonts/templates before referencing them.

## Changelog

Recent updates and new features are published at https://rideful.io/docs/changelog.