docs: document starting admin MCP branches from another branch

agent-context/context/skills/mintlify/SKILL.md

@@ -94,7 +94,7 @@ Use this server when the user wants to edit their Mintlify content, restructure
 Workflow: use `read`/`search`/`edit_page`/`write_page`/`list_nodes`/`create_node`/`update_node`/`move_node`/`delete_node`/`update_config` with a `branch` to make changes, then call `publish` with the `branch` and a `title` to publish (or `discard` to abandon). Pass the deploy branch to edit it directly. If the project requires a pull request (**Push directly to your deploy branch** is off, branch protection requires pull requests, deploy branch editing is locked, or the connection uses a client or machine-to-machine token), edits to the deploy branch are refused with the reason and change nothing. Call `create_branch` and pass its `branchName` as `branch` instead. Projects with auto publish turned on have no branches: pass the deploy branch, where edits are committed automatically. `create_branch` and other branches are refused there, and pull request requirements don't apply.
 
 Key tools:
-- **`create_branch`** — Start a new branch off the deploy branch with a `title` that also names its pull request. Returns `branchName` and a branch-level `editorUrl` to preview changes live. On a branch, Mintlify commits edits automatically about 15 seconds after the last change, and the first commit opens a pull request.
+- **`create_branch`** — Start a new branch off the deploy branch with a `title` that also names its pull request. Pass `from` to start off another existing branch instead: `create_branch { title: "Add tips page", from: "docs-refresh" }`. On GitHub, GitLab, and Azure Repos, its pull request then targets the `from` branch. Returns `branchName` and a branch-level `editorUrl` to preview changes live. On a branch, Mintlify commits edits automatically about 15 seconds after the last change, and the first commit opens a pull request.
 - **`list_branches`** — List existing branches; pass any of them as `branch`. Branches that don't exist are refused.
 - **`list_deployments`** — Discover which project(s) this connection can access.
 - **`read`** / **`search`**: Fetch a page's MDX or search across pages. `search` returns the most relevant pages with matching `snippets`, plus the full `content` of a confident top result, so `read` a page only when the results are not enough; pass `mode: "all"` (or `regex: true`) to list every page containing a phrase. `read`, `edit_page` and `write_page` take a page path (such as `guides/setup`) or the last segment of an editor URL, which is the page ID with an optional title in front of it. With a page ID from an editor URL, pass that URL's branch as `branch`. `read` returns a `filePath` to pass as `path` to `edit_page` and `write_page`, and a `version`; pass `forEdit: true` to read the live page instead of its saved copy.

ai/mintlify-mcp.mdx

@@ -123,7 +123,7 @@
 
 The AI tool acts as you on the deploy branch:
 
 - **Edits are live to collaborators.** Anyone else editing the deploy branch in the dashboard sees the AI's changes as they happen.
 - **`publish` publishes only your changes.** It commits your pending changes straight to the deploy branch, like clicking **Publish** in the editor. Other people's unpublished changes stay pending. Your own unpublished edits from the dashboard editor publish too.
 - **`discard` reverts only your changes.** It returns `discardedChanges` with the number of changes it reverted. Other people's changes and the branch itself stay untouched.
 - **`status` lists only your changes.**
@@ -136,10 +136,10 @@
 
 - **Push directly to your deploy branch** is off in your [publishing settings](#publishing).
 - Branch protection on your deploy branch requires pull requests, or Mintlify can't check your branch protection rules.
 - Editing the deploy branch is locked in the dashboard editor.
 - You connected with a client or machine-to-machine token instead of an OAuth login. These tokens aren't tied to a user, so they have no "own" changes.
 
 Mintlify checks these conditions on every edit and caches your branch protection rules for up to 30 seconds. Comment tools still work on the deploy branch when edits to it are refused. If your deploy branch starts requiring a pull request after you edit it, `publish` returns `branch_protected` and your changes stay pending. Open the dashboard editor to move them to a new branch.
 
 ### Projects with auto publish
 
@@ -147,7 +147,7 @@
 
 Mintlify refuses `create_branch` and calls on any other branch in these projects, and changes nothing. If your connection covers only that project, the admin MCP doesn't list `create_branch` or `list_branches`.
 
 **Push directly to your deploy branch** and branch protection don't block deploy branch edits in a project with auto publish. Mintlify refuses edits when editing the deploy branch is locked in the dashboard editor or when you connected with a client or machine-to-machine token.
 
 ### Projects that require review
 
@@ -161,11 +161,15 @@
 
 Call `create_branch` with a `title` when your project requires a pull request, or when you want one anyway. Mintlify starts a new branch off your deploy branch, names it `<your-name>/<title-slug>` the same way the dashboard editor names branches, and seeds it from your published content. The pull request opens with this title. For example, `create_branch { subdomain: "acme", title: "Add tips page" }`.
 
+To start from another existing branch instead, such as a feature branch for a large update, pass its name as `from`. For example, `create_branch { subdomain: "acme", title: "Add tips page", from: "docs-refresh" }`. Mintlify refuses `from` branches that don't exist and creates nothing.
+
+If your repository is on GitHub, GitLab, or Azure Repos, a branch you start from a branch other than your deploy branch becomes a [sub-branch](/editor/publish#sub-branches), and its pull request targets the `from` branch instead of your deploy branch.
+
 `create_branch` returns the `branchName`, the `baseBranch` and `baseSha` it started from, a `note`, and an `editorUrl` you can open to follow along in the dashboard editor. Pass the `branchName` as `branch` in every later call.
 
 To work on an existing branch, pass its name as `branch`. Call `list_branches` to discover branches in a project's repository. Mintlify refuses calls on branches that don't exist.
 
-On a branch, Mintlify commits your edits automatically, about 15 seconds after the last change. This includes page content, navigation changes, and `docs.json` updates. The first commit opens a pull request against your deploy branch. The pull request opens as a draft if [Create draft pull requests by default](/editor/settings#create-draft-pull-requests-by-default) is on. Nothing reaches your deploy branch until someone merges the pull request.
+On a branch, Mintlify commits your edits automatically, about 15 seconds after the last change. This includes page content, navigation changes, and `docs.json` updates. The first commit opens a pull request against your deploy branch, or against the `from` branch for a sub-branch. The pull request opens as a draft if [Create draft pull requests by default](/editor/settings#create-draft-pull-requests-by-default) is on. Nothing reaches your deploy branch until someone merges the changes into it.
 
 `discard` on a branch other than your deploy branch deletes the branch and closes its pull request, even if the branch has commits. This matches deleting a branch in the dashboard editor. `discard` only deletes branches you created in Mintlify. For any other branch, it refuses and changes nothing.
 
@@ -175,7 +179,7 @@
 
 This toggle shares the same `agentReviewProcess` setting as the Slack and dashboard agent, so any change here also applies to those flows.
 
 The toggle is disabled in three cases:
 
 - **Your deploy branch requires a pull request.** If branch protection rules or required approvals prevent direct pushes, MCP changes always go through a pull request regardless of this setting.
 - **Mintlify hosts your project.** For Mintlify-hosted sites, MCP changes always push directly, unless branch protection still requires a pull request.
@@ -204,7 +208,7 @@
 ### Content
 
 - **`read`**: Fetch the full MDX of any page on `branch`, or on your deploy branch when you omit it. Pass a page path, such as `guides/setup`, or the last segment of an editor URL, which is the page ID with an optional title in front of it. When you use a page ID from an editor URL, pass the branch from that URL as `branch`. The response includes a `filePath` that you can pass as `path` to `edit_page` and `write_page`, and a `version` of the content it returned. Pass `forEdit: true` to read the live page instead of its saved copy. Use `forEdit: true` before you overwrite the page with `write_page`. To read a [private page](/editor/pages#private-pages), pass its `private-page-<uuid>` node ID from `list_nodes` with `visibility: "private"`. Private reads don't need a `branch` and require an OAuth session. The admin MCP rejects client and machine-to-machine tokens for private-page access.
 - **`search`**: Search the pages on `branch` by meaning and exact wording, or your deploy branch when you omit it. Pass a question, topic, name, or exact phrase as `query`. By default, `search` returns the most relevant pages first as `results`. Each result has the page's `path` and `title`, and `snippets` with the matching lines. When `search` is confident in the top result, that result also includes the page's full `content`, up to 16 KB. The next results include the `section` around their best match. Pass `limit` to return up to 20 pages (default 6). To list every page that contains a phrase, such as before a rename, pass `mode: "all"` (default `limit` 100, maximum 500). Passing `regex: true` treats `query` as a regular expression and always uses `mode: "all"`.
 - **`edit_page`**: Apply a targeted edit to a page. Pass `path` in the same forms as `read`. Pass `oldString` and `newString` for one replacement, or pass an `edits` list of up to 100 replacements to change several parts of a page in one call. Mintlify applies the edits in order, each to the result of the previous one. If any edit fails, none of them apply. Like `write_page`, `edit_page` returns `notRendered` for markup the edit adds that the editor drops. It doesn't report markup that was already on the page. To edit a [private page](/editor/pages#private-pages), pass its `private-page-<uuid>` node ID as `path`. Private edits require an OAuth session with an editor role or higher on the page and don't need a `branch`.
 - **`write_page`**: Overwrite a page's full MDX content. Pass `path` in the same forms as `read`. Before you overwrite a page, call `read` with `forEdit: true` and pass the returned `version` to `write_page` as `baseVersion`. If the page changed since that read, Mintlify refuses the write, changes nothing, and returns `page_changed`. Read the page again and reapply your change. If you omit `baseVersion` on a page that has content, `write_page` returns `base_version_required`. A page with only frontmatter doesn't need a `baseVersion`. Also accepts a `private-page-<uuid>` node ID to overwrite a private page under the same OAuth and role requirements as `edit_page`. Use `create_node` to create a new private page. If the content includes markup the Mintlify editor drops, such as `<script>` tags, `<style>` blocks, event handlers like `onClick`, or JavaScript expressions, the response includes a `notRendered` field. Each entry lists the dropped `element`, its `line`, `why` the editor drops it, and what to use `instead`, such as Tailwind classes, inline `style={{}}` objects with literal values, or Mintlify components like accordions and tabs.
 - **`read_page_history`**: List a page's saved [version history](/editor/pages#version-history) on `branch`, or on your deploy branch when you omit it. Pass `path` in the same forms as `read`, including a `private-page-<uuid>` node ID. Returns `versions`, newest first, and a `nextCursor`. Each version has a `versionId`, `createdAt`, and `authors`, each with a `name` and a `type` of `user`, `git`, or `system`. Pass `limit` to return 1 to 50 versions per call (default 20), and pass `nextCursor` back as `cursor` to list older versions. Pass a `versionId` to get that version's full MDX as `content`. The tool is read-only. To restore an earlier version, call `read` on the page with `forEdit: true`, then pass the earlier version's `content` to `write_page` with that read's `version` as `baseVersion`. If that version contains [inline data](#inline-data) that's no longer on the page, `write_page` can't restore it. Restore that version from [version history](/editor/pages#version-history) in the editor instead. Errors include `page_not_found`, `version_not_found`, and `invalid_cursor`.
@@ -320,7 +324,7 @@
 ### Branches and publishing
 
 - **`list_deployments`**: List the projects your connection can access, returning each `{subdomain, name, projectType}`. `projectType` is `site` for a docs site or `workspace` for a base. Call this to discover which `subdomain` to pass.
-- **`create_branch`**: Start a new branch off your deploy branch with a `title` that also names its pull request. Returns the `branchName` to pass as `branch`. See [Work on a branch](#work-on-a-branch). You don't need it to [edit the deploy branch directly](#edit-the-deploy-branch-directly).
+- **`create_branch`**: Start a new branch off your deploy branch, or off the existing branch you pass as `from`, with a `title` that also names its pull request. Returns the `branchName` to pass as `branch`. See [Work on a branch](#work-on-a-branch). You don't need it to [edit the deploy branch directly](#edit-the-deploy-branch-directly).
 - **`list_branches`**: List Git branches available for a project's repository, with optional `query` filtering. Returns the branch names, total count, and the deploy branch. Pass any of them as `branch`.
 - **`status`**: List the edited files, changed `docs.json` keys, and pending navigation diff on `branch`, or on your deploy branch when you omit it. On the deploy branch, lists only your changes.
 - **`diff`**: List all changes between `branch` and your deploy branch. Each changed file and `docs.json` entry includes `authors` and `byYou`. `authors` lists the members whose unpublished edits the entry contains. `byYou` is `true` when the entry includes your own edits. Use `byYou` to tell your changes apart from a colleague's on a shared branch.

skill.md

@@ -96,7 +96,7 @@ Use this server when the user wants to edit their Mintlify content, restructure
 Workflow: use `read`/`search`/`edit_page`/`write_page`/`list_nodes`/`create_node`/`update_node`/`move_node`/`delete_node`/`update_config` with a `branch` to make changes, then call `publish` with the `branch` and a `title` to publish (or `discard` to abandon). Pass the deploy branch to edit it directly. If the project requires a pull request (**Push directly to your deploy branch** is off, branch protection requires pull requests, deploy branch editing is locked, or the connection uses a client or machine-to-machine token), edits to the deploy branch are refused with the reason and change nothing. Call `create_branch` and pass its `branchName` as `branch` instead. Projects with auto publish turned on have no branches: pass the deploy branch, where edits are committed automatically. `create_branch` and other branches are refused there, and pull request requirements don't apply.
 
 Key tools:
-- **`create_branch`** — Start a new branch off the deploy branch with a `title` that also names its pull request. Returns `branchName` and a branch-level `editorUrl` to preview changes live. On a branch, Mintlify commits edits automatically about 15 seconds after the last change, and the first commit opens a pull request.
+- **`create_branch`** — Start a new branch off the deploy branch with a `title` that also names its pull request. Pass `from` to start off another existing branch instead: `create_branch { title: "Add tips page", from: "docs-refresh" }`. On GitHub, GitLab, and Azure Repos, its pull request then targets the `from` branch. Returns `branchName` and a branch-level `editorUrl` to preview changes live. On a branch, Mintlify commits edits automatically about 15 seconds after the last change, and the first commit opens a pull request.
 - **`list_branches`** — List existing branches; pass any of them as `branch`. Branches that don't exist are refused.
 - **`list_deployments`** — Discover which project(s) this connection can access.
 - **`read`** / **`search`**: Fetch a page's MDX or search across pages. `search` returns the most relevant pages with matching `snippets`, plus the full `content` of a confident top result, so `read` a page only when the results are not enough; pass `mode: "all"` (or `regex: true`) to list every page containing a phrase. `read`, `edit_page` and `write_page` take a page path (such as `guides/setup`) or the last segment of an editor URL, which is the page ID with an optional title in front of it. With a page ID from an editor URL, pass that URL's branch as `branch`. `read` returns a `filePath` to pass as `path` to `edit_page` and `write_page`, and a `version`; pass `forEdit: true` to read the live page instead of its saved copy.