From ef47f64ffbc7dcb17774a0b90fb1e60cc929e2b5 Mon Sep 17 00:00:00 2001 From: Jason Kuhrt Date: Fri, 30 Oct 2026 21:01:10 -0400 Subject: [PATCH 1/2] docs: make deployed revisions discoverable to agents --- .../content/docs/getting-started/ai-agents.md | 44 ++++++++++++++++++- apps/landing/src/pages/llms.txt.ts | 10 ++++- 2 files changed, 51 insertions(+), 3 deletions(-) diff --git a/apps/landing/src/content/docs/getting-started/ai-agents.md b/apps/landing/src/content/docs/getting-started/ai-agents.md index 9228a70021..33aac4c133 100644 --- a/apps/landing/src/content/docs/getting-started/ai-agents.md +++ b/apps/landing/src/content/docs/getting-started/ai-agents.md @@ -1,6 +1,6 @@ --- title: "Use Maple with AI agents" -description: "Connect Claude Code, Cursor, Windsurf or any MCP client to Maple, then let the agent debug production errors, chase latency, build dashboards, set up alerts and instrument your code." +description: "Connect Claude Code, Cursor, Windsurf or any MCP client to Maple to debug errors, chase latency, build dashboards and alerts, instrument code and check which Maple Cloud revision is deployed." group: "Getting Started" order: 2 navLabel: "AI agents" @@ -8,11 +8,12 @@ navLabel: "AI agents" Your coding agent can work with Maple directly. Connected to the [Maple MCP server](/docs/reference/mcp), it reads the same traces, logs, metrics and error issues you see in the dashboard, and it can act on them: triage an issue, build a dashboard, create an alert rule. Paired with the [GitHub integration](/docs/integrations/github), it can go from an exception to the line of code that raised it. -There are three ways agents fit in: +There are four ways agents fit in: - **Query and operate Maple** through the MCP server. This page covers it. - **Instrument your code** with the `maple-onboard` and `maple-audit` skills. See [Instrument with a coding agent](#instrument-with-a-coding-agent). - **Monitor your own AI agents** in [Agent Sessions](/docs/agent-sessions/overview). +- **Check what Maple Cloud runs** in your region. See [Check whether a Maple Cloud fix is deployed](#check-whether-a-maple-cloud-fix-is-deployed). ## Connect your agent @@ -111,6 +112,45 @@ For heavier dashboard work, give your agent the [maple-dashboard-widgets](https: When no tool fits, `describe_warehouse_tables` lists the tables and columns, and `run_sql` runs a read-only query scoped to your organization. See [SQL](/docs/reference/sql). +## Check whether a Maple Cloud fix is deployed + +To check whether a fix is serving your organization, query its region's deployed revisions. These are public HTTP requests; no sign-in or browser is needed. + +| Region | Dashboard build | API Worker | +| ------ | --------------------------------------- | --------------------------------- | +| US | `https://app.maple.dev/version.json` | `https://api.maple.dev/health` | +| EU | `https://app.eu.maple.dev/version.json` | `https://api.eu.maple.dev/health` | + +Send `GET` to both endpoints: + +- The dashboard returns JSON with a `commit` field identifying its asset build. When polling, append a fresh query value, such as `?t=`, to avoid reusing a cached response. +- The API returns `OK` with its running commit in the `x-maple-revision` response header. A `200` without that header leaves the API revision unknown. Use `GET`, not `HEAD`. + +For the US region, these requests print the dashboard commit and the API response headers: + +```bash +curl -fsS "https://app.maple.dev/version.json?t=$(date +%s)" +curl -fsS -D - -o /dev/null https://api.maple.dev/health +``` + +Read `x-maple-revision` from the second response. Use the EU hosts from the table for an EU organization. + +After the PR merges, use its actual upstream merge commit. Do not assume the PR branch's commits reached `main`: GitHub can squash-merge them. Replace the placeholders below with the PR number, that merge SHA and each relevant serving SHA: + +```bash +repo=https://api.github.com/repos/MapleTechLabs/maple +curl -fsS "$repo/pulls/" \ + | jq -r 'select(.merged) | .merge_commit_sha' +curl -fsS "$repo/compare/..." \ + | jq -r '.status' +``` + +For a successful PR response, empty `jq` output means it is not merged. Never use an open PR's `merge_commit_sha`: it describes a test merge. A comparison status of `identical` or `ahead` means the serving revision includes the merge; `behind` or `diverged` means it does not. Other responses or request failures leave inclusion unknown. Report the dashboard and API separately if only one has updated. These public GitHub requests need no sign-in; unauthenticated requests share a 60-per-hour limit per IP address. See [GitHub's rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api). + +These signals identify the dashboard and API. They do not identify separately deployed services such as ingest or the AI Worker behind MCP. Once the affected code is deployed, check the expected behavior against the organization's real data. + +The [changelog](/changelog) provides product announcements, also available as [Markdown](/changelog.md) and [RSS](/changelog/rss.xml). A changelog entry, GitHub release or merged PR alone does not establish which revision a Maple Cloud service is running. + ## Instrument with a coding agent Open-source skills teach a coding agent how to set up OpenTelemetry for Maple: diff --git a/apps/landing/src/pages/llms.txt.ts b/apps/landing/src/pages/llms.txt.ts index 2cbddd7881..40f8d278bf 100644 --- a/apps/landing/src/pages/llms.txt.ts +++ b/apps/landing/src/pages/llms.txt.ts @@ -43,6 +43,13 @@ export const GET: APIRoute = ({ site }) => { `- Example: [${url("/docs/getting-started/introduction.md")}](${url("/docs/getting-started/introduction.md")})`, "", + "## Use Maple with an AI agent", + "", + "Query and operate Maple through MCP, find instrumentation skills, and check the dashboard and API revisions deployed to your region without a browser.", + "", + `- [AI agent guide: connection, workflows, deployed revisions and skills](${url("/docs/getting-started/ai-agents.md")})`, + "", + "## Pricing", "", "One plan: $39 a month with 100 GB each of logs, traces and metrics included, then $0.30 per GB per signal; 5,000 browser sessions included, then $0.002 per session; 1M product events included, then $5 per million (page views not counted).", @@ -59,7 +66,8 @@ export const GET: APIRoute = ({ site }) => { "## Changelog", "", - `Maple product updates, one entry per shipped change. The index enumerates every entry. ${CONVENTION("changelog")}`, + `Maple product announcements, one entry per announced change. The index enumerates every entry. ${CONVENTION("changelog")}`, + `An entry does not show which commit a region is running. To check the deployed dashboard and API revisions, see the [AI agent guide](${url("/docs/getting-started/ai-agents.md#check-whether-a-maple-cloud-fix-is-deployed")}).`, "", ...both("Changelog index", "/changelog"), `- [RSS feed](${url("/changelog/rss.xml")})`, From af9582551334a1043d3b708d0d1787c4657dc201 Mon Sep 17 00:00:00 2001 From: Makisuo Date: Sat, 31 Oct 2026 18:15:00 +0100 Subject: [PATCH 2/2] docs: tighten the deployed-revision check section --- .../content/docs/getting-started/ai-agents.md | 36 +++++++------------ 1 file changed, 12 insertions(+), 24 deletions(-) diff --git a/apps/landing/src/content/docs/getting-started/ai-agents.md b/apps/landing/src/content/docs/getting-started/ai-agents.md index 33aac4c133..8fffe7f054 100644 --- a/apps/landing/src/content/docs/getting-started/ai-agents.md +++ b/apps/landing/src/content/docs/getting-started/ai-agents.md @@ -1,6 +1,6 @@ --- title: "Use Maple with AI agents" -description: "Connect Claude Code, Cursor, Windsurf or any MCP client to Maple to debug errors, chase latency, build dashboards and alerts, instrument code and check which Maple Cloud revision is deployed." +description: "Connect Claude Code, Cursor, Windsurf or any MCP client to Maple, then let the agent debug production errors, chase latency, build dashboards, set up alerts and instrument your code." group: "Getting Started" order: 2 navLabel: "AI agents" @@ -8,12 +8,11 @@ navLabel: "AI agents" Your coding agent can work with Maple directly. Connected to the [Maple MCP server](/docs/reference/mcp), it reads the same traces, logs, metrics and error issues you see in the dashboard, and it can act on them: triage an issue, build a dashboard, create an alert rule. Paired with the [GitHub integration](/docs/integrations/github), it can go from an exception to the line of code that raised it. -There are four ways agents fit in: +There are three ways agents fit in: - **Query and operate Maple** through the MCP server. This page covers it. - **Instrument your code** with the `maple-onboard` and `maple-audit` skills. See [Instrument with a coding agent](#instrument-with-a-coding-agent). - **Monitor your own AI agents** in [Agent Sessions](/docs/agent-sessions/overview). -- **Check what Maple Cloud runs** in your region. See [Check whether a Maple Cloud fix is deployed](#check-whether-a-maple-cloud-fix-is-deployed). ## Connect your agent @@ -114,42 +113,31 @@ When no tool fits, `describe_warehouse_tables` lists the tables and columns, and ## Check whether a Maple Cloud fix is deployed -To check whether a fix is serving your organization, query its region's deployed revisions. These are public HTTP requests; no sign-in or browser is needed. +Each region reports the commit its dashboard and API are running. Both are public `GET` requests, no sign-in needed. -| Region | Dashboard build | API Worker | +| Region | Dashboard | API | | ------ | --------------------------------------- | --------------------------------- | | US | `https://app.maple.dev/version.json` | `https://api.maple.dev/health` | | EU | `https://app.eu.maple.dev/version.json` | `https://api.eu.maple.dev/health` | -Send `GET` to both endpoints: - -- The dashboard returns JSON with a `commit` field identifying its asset build. When polling, append a fresh query value, such as `?t=`, to avoid reusing a cached response. -- The API returns `OK` with its running commit in the `x-maple-revision` response header. A `200` without that header leaves the API revision unknown. Use `GET`, not `HEAD`. - -For the US region, these requests print the dashboard commit and the API response headers: - ```bash -curl -fsS "https://app.maple.dev/version.json?t=$(date +%s)" -curl -fsS -D - -o /dev/null https://api.maple.dev/health +curl -fsS https://app.maple.dev/version.json | jq -r .commit +curl -fsS -D - -o /dev/null https://api.maple.dev/health | grep -i x-maple-revision ``` -Read `x-maple-revision` from the second response. Use the EU hosts from the table for an EU organization. +The dashboard and API deploy separately, so compare each one. No `x-maple-revision` header means the API revision is unknown. -After the PR merges, use its actual upstream merge commit. Do not assume the PR branch's commits reached `main`: GitHub can squash-merge them. Replace the placeholders below with the PR number, that merge SHA and each relevant serving SHA: +To check whether a serving commit includes a merged PR, compare it with the PR's merge commit, not the branch's own commits (PRs are squash-merged): ```bash repo=https://api.github.com/repos/MapleTechLabs/maple -curl -fsS "$repo/pulls/" \ - | jq -r 'select(.merged) | .merge_commit_sha' -curl -fsS "$repo/compare/..." \ - | jq -r '.status' +curl -fsS "$repo/pulls/" | jq -r 'select(.merged) | .merge_commit_sha' +curl -fsS "$repo/compare/..." | jq -r .status ``` -For a successful PR response, empty `jq` output means it is not merged. Never use an open PR's `merge_commit_sha`: it describes a test merge. A comparison status of `identical` or `ahead` means the serving revision includes the merge; `behind` or `diverged` means it does not. Other responses or request failures leave inclusion unknown. Report the dashboard and API separately if only one has updated. These public GitHub requests need no sign-in; unauthenticated requests share a 60-per-hour limit per IP address. See [GitHub's rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api). - -These signals identify the dashboard and API. They do not identify separately deployed services such as ingest or the AI Worker behind MCP. Once the affected code is deployed, check the expected behavior against the organization's real data. +Empty output from the first request means the PR is not merged yet. A status of `identical` or `ahead` means the fix is deployed; `behind` or `diverged` means it is not. -The [changelog](/changelog) provides product announcements, also available as [Markdown](/changelog.md) and [RSS](/changelog/rss.xml). A changelog entry, GitHub release or merged PR alone does not establish which revision a Maple Cloud service is running. +Ingest and the MCP server deploy on their own and are not covered by these checks. A [changelog](/changelog) entry or a merged PR does not show what a region is running. ## Instrument with a coding agent