Async merge API docs

[skarim]

Adds a Merge API reference page documenting the asynchronous merge endpoints used to land stacked PRs (PUT / GET .../pulls/{n}/merge-async): the submit → poll flow, request parameters, response statuses (pending / merged / enqueued / failed), and current limitations.

• New reference/merge-api.md page, added to the docs sidebar
• FAQ entry on merging a stack programmatically
• Cross-link from the gh stack merge CLI reference

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[Copilot]

Pull request overview

Adds documentation for programmatic asynchronous stack merging.

Changes:

• Documents submit/poll endpoints, statuses, and limitations.
• Adds FAQ and CLI cross-links.
• Registers the page in the sidebar.

Show a summary per file

File	Description
docs/astro.config.mjs	Adds Merge API navigation.
docs/src/content/docs/faq.md	Adds programmatic merge guidance.
docs/src/content/docs/reference/cli.md	Links CLI merging to the API.
docs/src/content/docs/reference/merge-api.md	Adds the API reference.

Review details

Comments suppressed due to low confidence (3)

docs/src/content/docs/reference/merge-api.md:54

• The response table omits 422 Unprocessable Entity, even though the async client explicitly handles and tests that validation response (internal/github/merge_async_test.go:98-101). Document it so callers know invalid request fields or enum values produce the standard validation error rather than a {status, details} result.

| `400 Bad Request` | The pull request is not ready to be merged (for example, it is closed or a draft). | `failed` |
| `404 Not Found` | Async merge is not available for this repository, or the pull request was not found. | — |

docs/src/content/docs/reference/merge-api.md:150

• default is not a resolved action—it asks the server to choose between direct merge and merge queue—and the pending examples show that value being echoed unchanged. Calling this field “resolved” contradicts the request-field description and may lead clients to treat default as an actual routing outcome.

| `merge_action` | `string` | `pending` | The resolved action (`default`, `direct_merge`, or `merge_queue`). |

docs/src/content/docs/reference/merge-api.md:29

• This endpoint does not unconditionally return a UUID: the 200 merged response documented below is terminal and has only details.sha. Qualify this sentence so consumers do not reject a valid immediate result or attempt to poll without an identifier.

Merges the pull request (and, for a stacked PR, everything below it in the stack) into the base branch in the background. Returns a `uuid` used to fetch the result.

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Medium