Add workflow docs

agent/index.mdx

@@ -33,11 +33,12 @@
 
 ## Where you can use the agent
 
 - **Dashboard**: From any page in your dashboard, use the keyboard shortcut <kbd>⌘</kbd>+<kbd>I</kbd> (macOS) or <kbd>Ctrl</kbd>+<kbd>I</kbd> (Windows/Linux) to open the agent panel. Or click **Ask agent** on the [Overview](https://dashboard.mintlify.com/) page.
   <Frame>
     <img src="/images/agent/dashboard-light.png" alt="The agent panel open in the dashboard." className="block dark:hidden" />
     <img src="/images/agent/dashboard-dark.png" alt="The agent panel open in the dashboard." className="hidden dark:block" />
   </Frame>
+- **Workflows**: Create workflows to run the agent automatically on a schedule or when an event you specify happens in one of your repositories. See [Workflows](/agent/workflows) for more information.
 - **Slack**: Add the agent to your Slack workspace and mention `@mintlify` in any channel. You can attach files and images directly to your messages for the agent to process.
 - **API**: Embed the agent in custom applications using the [agent endpoints](/api/agent/create-agent-job).
 

agent/use-cases.mdx

@@ -0,0 +1,71 @@
+---
+title: "Use cases"
+description: "Examples of using the agent in your documentation process."
+keywords: ["agent workflows", "documentation workflows", "automation examples"]
+---
+
+The agent assists with many different documentation tasks. These examples show some of the ways you can integrate the agent into your documentation process. Try an approach that fits how your team currently works and adapt it to your specific needs.
+
+## Iterate on a prompt in a Slack thread
+
+Prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates.
+
+For example: `@mintlify Our quickstart page needs a new section on inviting collaborators`. Then `@mintlify The new section should be called "Inviting collaborators"`. Followed by any other iterations.
+
+## Start with the agent, finish manually
+
+Prompt the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task.
+
+For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method.
+
+## Update docs when merging feature changes
+
+When you merge a feature pull request, share the PR link with the agent to update relevant docs.
+
+For example: `@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`.
+
+## Generate release notes from a pull request
+
+Prompt the agent with a specific pull request to generate release notes or changelog updates based on the commit history.
+
+For example: `@mintlify Generate release notes for this PR: [PR link]`.
+
+## Address pull request review feedback
+
+Share a pull request link with the agent to address reviewer comments and code review feedback on documentation pull requests.
+
+For example: `@mintlify Address the review comments on this PR: [PR link]`.
+
+## Generate code examples
+
+Prompt the agent to generate code examples for features throughout your docs or on specific pages.
+
+For example: `@mintlify Generate a code example to make the authentication method easier to understand`.
+
+## Add images or files to your docs
+
+Attach files or images directly to your Slack message when prompting the agent. The agent processes the attachment and includes it in the documentation.
+
+For example: `@mintlify Add this diagram to the architecture overview page` with the image attached to the message.
+
+## Review existing content
+
+Prompt the agent to review existing content for technical accuracy, style, grammar, or other issues.
+
+For example: `@mintlify Review the API rate limiting section. We changed limits last month`.
+
+## Respond to user feedback
+
+Prompt the agent with feedback from your users to make focused updates to your docs.
+
+For example: `@mintlify Users are getting confused by step 3 in the setup guide. What might be making it unclear?`.
+
+## Automate with the API
+
+Integrate the agent into your existing automation tools to automatically update documentation when code changes occur, trigger content reviews, or sync documentation updates across multiple repositories.
+
+Use the agent endpoints to [create jobs](/api-reference/agent/create-agent-job), [get a specific job](/api-reference/agent/get-agent-job), and [get all jobs](/api-reference/agent/get-all-jobs).
+
+When creating jobs via the API, you can control whether pull requests open in draft mode using the `asDraft` parameter (defaults to `true`). Set `asDraft: false` to create non-draft pull requests ready for immediate review and merging in automated workflows.
+
+Learn how to set up API automation in the [Auto-update documentation when code is merged](/guides/automate-agent) tutorial.

agent/workflows.mdx

@@ -1,71 +1,116 @@
 ---
 title: "Workflows"
-description: "Examples of using the agent in your documentation process."
-keywords: ["agent workflows", "documentation workflows", "automation examples"]
+description: "Automate documentation maintenance with scheduled or event-triggered agent tasks."
+keywords: ["automation", "automate", "cron", "auto-update"]
 ---
 
-The agent assists with many different documentation tasks. These workflows show some of the ways you can integrate the agent into your documentation process. Try an approach that fits how your team currently works and adapt it to your specific needs.
+<Info>
+  Workflows are available on [Pro and Enterprise plans](https://mintlify.com/pricing?ref=agent).
 
-## Iterate on a prompt in a Slack thread
+  Pro plans can have up to two active workflows. Enterprise plans can have up to 10 active workflows.
+</Info>
 
-Prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates.
+Workflows run the agent automatically on a schedule or when an event you specify happens in one of your repositories. Each workflow defines a prompt for the agent and a trigger for when to run it.
 
-For example: `@mintlify Our quickstart page needs a new section on inviting collaborators`. Then `@mintlify The new section should be called "Inviting collaborators"`. Followed by any other iterations.
+When a workflow runs, the agent follows the prompt, makes changes to your documentation, then either opens a pull request or pushes changes directly to your deploy branch depending on how you configure the workflow.
 
-## Start with the agent, finish manually
+## Create a workflow file
 
-Prompt the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task.
+Create `.md` files in a `.mintlify/workflows/` directory at the root of your documentation repository. Each file defines one workflow.
 
-For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method.
+Workflow files use YAML frontmatter to configure the workflow, followed by a Markdown prompt for the agent.
 
-## Update docs when merging feature changes
+```markdown .mintlify/workflows/update-changelog.md
+---
+name: Update changelog
+on:
+  cron: "0 9 * * 1"
+context:
+  - repo: your-org/your-product
+automerge: false
+---
+
+Review all changes since the last changelog update. Draft a new
+changelog post with any new features, bug fixes, or breaking changes.
 
-When you merge a feature pull request, share the PR link with the agent to update relevant docs.
+Include information about what a change is and how it affects users.
 
-For example: `@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`.
+Do not include any internal-only information or minor changes
+like bumping package versions or updating documentation.
+```
 
-## Generate release notes from a pull request
+### Frontmatter fields
 
-Prompt the agent with a specific pull request to generate release notes or changelog updates based on the commit history.
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Display name shown in the dashboard. |
+| `on` | Yes | Trigger configuration. |
+| `context` | No | Repositories cloned as reference when the workflow runs. |
+| `automerge` | No | Defaults to `false`, which opens a pull request. If `true`, pushes changes directly to your deployment branch. |
 
-For example: `@mintlify Generate release notes for this PR: [PR link]`.
+You must have the Mintlify GitHub App installed on every repository listed in the `context` or `on.push.repo` fields. See [GitHub](/deploy/github) for more information on how to install the app.
 
-## Address pull request review feedback
+The content below the frontmatter is the prompt the agent follows when the workflow runs.
 
-Share a pull request link with the agent to address reviewer comments and code review feedback on documentation pull requests.
+## Triggers
 
-For example: `@mintlify Address the review comments on this PR: [PR link]`.
+Each workflow must define exactly one trigger using the `on` field.
 
-## Generate code examples
+### On schedule (cron)
 
-Prompt the agent to generate code examples for features throughout your docs or on specific pages.
+Run a workflow on a recurring schedule using a cron expression. All schedules run in UTC.
 
-For example: `@mintlify Generate a code example to make the authentication method easier to understand`.
+```yaml
+on:
+  cron: "0 9 * * 1"
+```
 
-## Add images or files to your docs
+The value is a standard 5-field cron expression in `minute hour day-of-month month day-of-week` format. Use a tool like [crontab.guru](https://crontab.guru) to build and validate schedules.
 
-Attach files or images directly to your Slack message when prompting the agent. The agent processes the attachment and includes it in the documentation.
+| Expression | Schedule |
+|------------|----------|
+| `"0 9 * * 1"` | Every Monday at 9:00 AM UTC |
+| `"0 0 1 * *"` | First day of each month at midnight UTC |
+| `"0 8 * * 1-5"` | Weekdays at 8:00 AM UTC |
 
-For example: `@mintlify Add this diagram to the architecture overview page` with the image attached to the message.
+### On merge
 
-## Review existing content
+Run a workflow when a pull request merges to a specific repository and branch.
 
-Prompt the agent to review existing content for technical accuracy, style, grammar, or other issues.
+```yaml
+on:
+  push:
+    - repo: your-org/your-product
+      branch: main
+```
 
-For example: `@mintlify Review the API rate limiting section. We changed limits last month`.
+- `repo`: The GitHub repository in `owner/repo` format.
+- `branch`: The branch to watch for merges. Omit to trigger on merges to the repository's default branch.
 
-## Respond to user feedback
+A workflow can watch for merges in multiple repositories or branches.
 
-Prompt the agent with feedback from your users to make focused updates to your docs.
+```yaml
+on:
+  push:
+    - repo: your-org/your-product
+    - repo: your-org/another-repo
+      branch: release
+```
 
-For example: `@mintlify Users are getting confused by step 3 in the setup guide. What might be making it unclear?`.
+## Reference repositories
 
-## Automate with the API
+Use `context` to give the agent read access to additional repositories when the workflow runs. This is useful when your prompt requires reviewing code or content outside your documentation repository.
 
-Integrate the agent into your existing automation tools to automatically update documentation when code changes occur, trigger content reviews, or sync documentation updates across multiple repositories.
+```yaml
+context:
+  - repo: your-org/your-product
+  - repo: your-org/design-system
+```
 
-Use the agent endpoints to [create jobs](/api-reference/agent/create-agent-job), [get a specific job](/api-reference/agent/get-agent-job), and [get all jobs](/api-reference/agent/get-all-jobs).
+## Auto-merge changes
 
-When creating jobs via the API, you can control whether pull requests open in draft mode using the `asDraft` parameter (defaults to `true`). Set `asDraft: false` to create non-draft pull requests ready for immediate review and merging in automated workflows.
+By default, the agent opens a pull request for each workflow run so you can review changes before they go live. Set `automerge: true` to push changes directly to your deploy branch without a pull request.
 
-Learn how to set up API automation in the [Auto-update documentation when code is merged](/guides/automate-agent) tutorial.
+```yaml
+automerge: true
+```

docs.json

@@ -82,10 +82,11 @@
                     "pages": [
                       "agent/quickstart",
                       "agent/slack",
+                      "agent/workflows",
                       "agent/suggestions",
                       "agent/customize",
                       "agent/effective-prompts",
-                      "agent/workflows"
+                      "agent/use-cases"
                     ]
                   },
                   {