Skip to content

Open-source status page, incident response and uptime monitoring

feat(chat): add docs knowledge-base tools (search_docs + get_doc_page) (#2266)

Maximilian Kaske1135217598f6
diff --git a/.env.docker.example b/.env.docker.example
index 9dc891d85..938f6029b 100644
--- a/.env.docker.example
+++ b/.env.docker.example
@@ -139,6 +139,11 @@ SCREENSHOT_SERVICE_URL=
# External services
OPENSTATUS_INGEST_URL=https://openstatus-private-location.fly.dev
+# Docs knowledge base for the AI assistant / MCP server (optional)
+# The search_docs and get_doc_page tools query this site's /api/search and
+# /api/markdown endpoints. Defaults to the public openstatus.dev docs.
+# OPENSTATUS_WEB_BASE_URL=https://www.openstatus.dev
+
# DEVELOPMENT & TESTING
# ============================================================================
# Turbo build mode
diff --git a/apps/dashboard/src/components/chat/tool-renderers/index.tsx b/apps/dashboard/src/components/chat/tool-renderers/index.tsx
index f03370b68..66d00ba1d 100644
--- a/apps/dashboard/src/components/chat/tool-renderers/index.tsx
+++ b/apps/dashboard/src/components/chat/tool-renderers/index.tsx
@@ -29,6 +29,7 @@ import { listStatusPagesTable } from "./list-status-pages";
import { listStatusReportsTable } from "./list-status-reports";
import { resolveStatusReportChanges } from "./resolve-status-report";
import { ResultTable } from "./result-table";
+import { searchDocsTable } from "./search-docs";
import { updateStatusReportChanges } from "./update-status-report";
/**
@@ -195,6 +196,16 @@ export const toolRenderers: ToolRendererRegistry = {
),
summary: (o) => `${o.action} · #${o.id}`,
},
+ search_docs: {
+ renderResult: ({ output }) => <ResultTable {...searchDocsTable(output)} />,
+ summary: (o) => (o.error ? o.error : itemsCountSummary(o.results)),
+ },
+ // No renderResult — a full markdown page in the transcript is noise; the
+ // summary line plus the model's cited answer is the UX.
+ get_doc_page: {
+ summary: (o) =>
+ o.error ? o.error : `read ${o.url}${o.truncated ? " (truncated)" : ""}`,
+ },
};
function itemsCountSummary(items: unknown[] | undefined): string | undefined {
diff --git a/apps/dashboard/src/components/chat/tool-renderers/search-docs.tsx b/apps/dashboard/src/components/chat/tool-renderers/search-docs.tsx
new file mode 100644
index 000000000..d3005cab9
--- /dev/null
+++ b/apps/dashboard/src/components/chat/tool-renderers/search-docs.tsx
@@ -0,0 +1,30 @@
+import type { AgentToolOutput } from "@openstatus/services/agent-tools";
+
+import { TableCellLink } from "@/components/data-table/table-cell-link";
+import { TableCellText } from "@/components/data-table/table-cell-text";
+
+import type { ResultTableData } from "./result-table";
+
+type Output = AgentToolOutput<"search_docs">;
+
+export function searchDocsTable(
+ output: Output,
+): ResultTableData<"title" | "snippet"> {
+ const results = output?.results ?? [];
+ return {
+ empty: output?.error ?? "No results.",
+ columns: [
+ { key: "title", header: "Title" },
+ { key: "snippet", header: "Snippet" },
+ ],
+ rows: results.map((r) => ({
+ id: r.path,
+ cells: {
+ title: <TableCellLink href={r.url} value={r.title} />,
+ snippet: (
+ <TableCellText value={r.snippet} className="text-muted-foreground" />
+ ),
+ },
+ })),
+ };
+}
diff --git a/apps/web/src/content/pages/docs/guides/how-to-connect-openstatus-to-claude-code.mdx b/apps/web/src/content/pages/docs/guides/how-to-connect-openstatus-to-claude-code.mdx
index 07016108e..074f350fe 100644
--- a/apps/web/src/content/pages/docs/guides/how-to-connect-openstatus-to-claude-code.mdx
+++ b/apps/web/src/content/pages/docs/guides/how-to-connect-openstatus-to-claude-code.mdx
@@ -73,7 +73,7 @@ Open Claude Code and run:
/mcp
```
-You should see `openstatus` listed as **connected**, with the registered tools (`list_status_pages`, `list_page_components`, `list_status_reports`, `list_maintenances`, and — if your key has write scope — `create_status_report`, `add_status_report_update`, `update_status_report`, `resolve_status_report`, `create_maintenance`).
+You should see `openstatus` listed as **connected**, with the registered read tools (`list_status_pages`, `list_monitors`, `get_monitor_status`, `search_docs`, …) and — if your key has write scope — the mutation tools (`create_status_report`, `add_status_report_update`, `resolve_status_report`, `create_maintenance`, …). See the [MCP server reference](/docs/reference/mcp-server) for the full list.
If the server shows as disconnected, see [Troubleshooting](#troubleshooting) below.
@@ -112,7 +112,7 @@ If you have a write-scoped key, try drafting an incident — Claude Code will sh
### "Tool not available" when asking Claude Code to create an incident
-Your API key is read-only. Claude Code only sees the `list_*` tools — the server filters mutation tools out of `tools/list` for read-only keys. Issue a new key with **Read & write** scope and re-add the server.
+Your API key is read-only. Claude Code only sees the read tools — the server filters mutation tools out of `tools/list` for read-only keys. Issue a new key with **Read & write** scope and re-add the server.
### Audit log shows `actor_type = 'mcp'` for changes I made manually
diff --git a/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx b/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx
index 1690b7263..2d11ec966 100644
--- a/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx
+++ b/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx
@@ -26,6 +26,7 @@ openstatus provides a Docker Compose setup that makes self-hosting straightforwa
Self-hosting openstatus currently has these constraints:
- It only works with private locations. You have to deploy our probes to the cloud provider of your choice.
+- The AI assistant's docs knowledge base (the `search_docs` and `get_doc_page` tools) queries the public `https://www.openstatus.dev` docs by default. Set `OPENSTATUS_WEB_BASE_URL` if you mirror the marketing site and want the assistant to read your own copy.
- **IP Restriction is not secure outside Vercel.** The IP restriction feature for status pages relies on the `X-Forwarded-For` header, which [Vercel overwrites with the verified client IP](https://vercel.com/docs/headers/request-headers#x-forwarded-for). When self-hosting behind a different reverse proxy, clients can spoof this header to bypass IP restrictions. If you self-host and use IP restriction, ensure your reverse proxy strips and rewrites `X-Forwarded-For` with the real client IP before forwarding to openstatus.
## Step-by-step guide
diff --git a/apps/web/src/content/pages/docs/reference/mcp-server.mdx b/apps/web/src/content/pages/docs/reference/mcp-server.mdx
index 55bee02c7..d7a543d16 100644
--- a/apps/web/src/content/pages/docs/reference/mcp-server.mdx
+++ b/apps/web/src/content/pages/docs/reference/mcp-server.mdx
@@ -28,7 +28,7 @@ Get a key from the dashboard's **Settings → API Tokens**.
Each API key carries a scope that controls what tools the MCP server exposes:
-- **Read-only** — the server only registers read tools (`list_*` and `get_*`). Mutation tools (`create_*`, `update_*`, `add_*`, `resolve_*`) are not advertised in `tools/list` and cannot be called.
+- **Read-only** — the server only registers read tools (`list_*`, `get_*`, and `search_docs`). Mutation tools (`create_*`, `update_*`, `add_*`, `resolve_*`) are not advertised in `tools/list` and cannot be called.
- **Read & write** — every tool is available.
Scope is set at key creation time and is **immutable**. To change a key's scope, revoke it and issue a new one.
@@ -37,7 +37,7 @@ For AI agents that should only observe state — health summaries, paging on-cal
## Tools
-The server exposes 18 tools, grouped by resource and scoped to the workspace tied to your API key. Mutations write to the audit log with `actor_type = "mcp"` (see [Audit log](#audit-log)).
+The server exposes 20 tools, grouped by resource and scoped to the workspace tied to your API key. Mutations write to the audit log with `actor_type = "mcp"` (see [Audit log](#audit-log)).
### Pages
@@ -89,6 +89,15 @@ Registered only when the workspace plan includes the `audit-log` feature — oth
| `list_audit_logs` | read | List audit-log entries (mutating actions) newest-first, bounded to the last 14 days. Optional `entityType` + `entityId` filter. |
| `get_audit_log` | read | Full before/after snapshots and `changedFields` for a single audit-log entry. |
+### Docs
+
+These query the public openstatus documentation — not your workspace data — so the assistant can answer product and how-to questions grounded in the official docs.
+
+| Tool | Type | Purpose |
+|----------------|------|---------|
+| `search_docs` | read | Search the public documentation, guides, or changelog (`type: "docs" \| "guides" \| "changelog"`). Returns scored results with title, snippet, url, and a `path` to pass to `get_doc_page`. |
+| `get_doc_page` | read | Fetch the full markdown of a docs, guides, or changelog page by `path` (as returned by `search_docs`). Long pages are truncated with a marker linking to the full page. |
+
The MCP client gates every tool call behind your approval — the server does not gate again. Each tool also carries [MCP annotations](https://modelcontextprotocol.io/specification/server/tools#tool-annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so well-behaved clients can decide whether to confirm, cache, or surface differently.
### Notifying subscribers
diff --git a/packages/services/src/agent-tools/__tests__/docs.test.ts b/packages/services/src/agent-tools/__tests__/docs.test.ts
new file mode 100644
index 000000000..039400c36
--- /dev/null
+++ b/packages/services/src/agent-tools/__tests__/docs.test.ts
@@ -0,0 +1,154 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+import type { ServiceContext } from "../../context";
+import { getDocPageTool, searchDocsTool } from "../docs";
+
+// Both tools ignore ctx — public content, workspace-independent.
+const ctx = {} as ServiceContext;
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+ globalThis.fetch = originalFetch;
+});
+
+function mockFetch(response: Response) {
+ const fn = mock(async () => response);
+ globalThis.fetch = fn as unknown as typeof fetch;
+ return fn;
+}
+
+function searchFixture(i: number) {
+ return {
+ metadata: {
+ title: `Result ${i}`,
+ description: `Description ${i}`,
+ publishedAt: "2018-10-20T01:46:40.000Z",
+ category: "Concepts",
+ author: "openstatus",
+ },
+ content: `...snippet for result ${i}...`,
+ slug: `concept/page-${i}`,
+ href: `/docs/concept/page-${i}?q=monitor#some-heading`,
+ filePath: `/var/task/apps/web/src/content/pages/docs/concept/page-${i}.mdx`,
+ };
+}
+
+describe("search_docs", () => {
+ test("maps live response shape, strips query/hash/filePath", async () => {
+ mockFetch(Response.json([searchFixture(1), searchFixture(2)]));
+ const result = await searchDocsTool.run({
+ ctx,
+ input: { query: "monitor", type: "docs" },
+ });
+ const parsed = searchDocsTool.outputSchema.safeParse(result);
+ expect(parsed.success, parsed.error?.message).toBe(true);
+ expect(result.results).toHaveLength(2);
+ const first = result.results[0];
+ expect(first.title).toBe("Result 1");
+ expect(first.path).toBe("docs/concept/page-1");
+ expect(first.url).toBe(
+ "https://www.openstatus.dev/docs/concept/page-1?q=monitor#some-heading",
+ );
+ expect(JSON.stringify(result)).not.toContain("filePath");
+ });
+
+ test("returns error shape on non-OK response without throwing", async () => {
+ mockFetch(new Response("oops", { status: 500 }));
+ const result = await searchDocsTool.run({
+ ctx,
+ input: { query: "monitor", type: "docs" },
+ });
+ expect(result.results).toEqual([]);
+ expect(result.error).toBe("search unavailable (HTTP 500)");
+ expect(searchDocsTool.outputSchema.safeParse(result).success).toBe(true);
+ });
+
+ test("returns error shape when fetch throws", async () => {
+ globalThis.fetch = (async () => {
+ throw new Error("ECONNREFUSED");
+ }) as unknown as typeof fetch;
+ const result = await searchDocsTool.run({
+ ctx,
+ input: { query: "monitor", type: "docs" },
+ });
+ expect(result.results).toEqual([]);
+ expect(result.error).toBe("search unavailable (network error)");
+ expect(searchDocsTool.outputSchema.safeParse(result).success).toBe(true);
+ });
+
+ test("caps results at 8", async () => {
+ mockFetch(
+ Response.json(Array.from({ length: 12 }, (_, i) => searchFixture(i))),
+ );
+ const result = await searchDocsTool.run({
+ ctx,
+ input: { query: "monitor", type: "docs" },
+ });
+ expect(result.results).toHaveLength(8);
+ });
+});
+
+describe("get_doc_page", () => {
+ test("returns markdown body untruncated", async () => {
+ mockFetch(new Response("# Hello\n\nSome docs content."));
+ const result = await getDocPageTool.run({
+ ctx,
+ input: { path: "docs/concept/page-1" },
+ });
+ const parsed = getDocPageTool.outputSchema.safeParse(result);
+ expect(parsed.success, parsed.error?.message).toBe(true);
+ expect(result.markdown).toBe("# Hello\n\nSome docs content.");
+ expect(result.truncated).toBe(false);
+ expect(result.url).toBe("https://www.openstatus.dev/docs/concept/page-1");
+ });
+
+ test("truncates long pages with a marker", async () => {
+ mockFetch(new Response("x".repeat(30_000)));
+ const result = await getDocPageTool.run({
+ ctx,
+ input: { path: "docs/concept/page-1" },
+ });
+ expect(result.truncated).toBe(true);
+ expect(result.markdown.length).toBeLessThan(24_200);
+ expect(result.markdown).toEndWith(
+ "[truncated — content continues at https://www.openstatus.dev/docs/concept/page-1]",
+ );
+ });
+
+ test("returns error shape on 404", async () => {
+ mockFetch(new Response("Not Found", { status: 404 }));
+ const result = await getDocPageTool.run({
+ ctx,
+ input: { path: "docs/does-not-exist" },
+ });
+ expect(result.markdown).toBe("");
+ expect(result.error).toBe("page not found (HTTP 404)");
+ });
+
+ test("returns error shape when fetch throws", async () => {
+ globalThis.fetch = (async () => {
+ throw new Error("ECONNREFUSED");
+ }) as unknown as typeof fetch;
+ const result = await getDocPageTool.run({
+ ctx,
+ input: { path: "docs/concept/page-1" },
+ });
+ expect(result.markdown).toBe("");
+ expect(result.error).toBe("page unavailable (network error)");
+ expect(getDocPageTool.outputSchema.safeParse(result).success).toBe(true);
+ });
+
+ test("rejects non-allowlisted paths without fetching", async () => {
+ const fn = mockFetch(new Response("should not be called"));
+ for (const path of ["blog/foo", "../etc", "docs/../../etc"]) {
+ const result = await getDocPageTool.run({ ctx, input: { path } });
+ expect(result.markdown).toBe("");
+ expect(result.error).toBe(
+ "path must start with docs/, guides/ or changelog/",
+ );
+ expect(getDocPageTool.outputSchema.safeParse(result).success).toBe(true);
+ }
+ expect(fn).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/services/src/agent-tools/docs.ts b/packages/services/src/agent-tools/docs.ts
new file mode 100644
index 000000000..b88941428
--- /dev/null
+++ b/packages/services/src/agent-tools/docs.ts
@@ -0,0 +1,167 @@
+import { z } from "zod";
+
+import type { AgentTool } from "./types";
+
+// Public marketing-site content API; override for local/self-hosted setups.
+const WEB_BASE_URL =
+ process.env.OPENSTATUS_WEB_BASE_URL ?? "https://www.openstatus.dev";
+
+const MAX_RESULTS = 8;
+const FETCH_TIMEOUT_MS = 10_000;
+// ≈6k tokens — the free tier runs Haiku; a clipped page beats a blown context.
+const MAX_MARKDOWN_CHARS = 24_000;
+
+const DOC_PATH_PREFIXES = ["docs/", "guides/", "changelog/"];
+
+const SearchDocsInput = z
+ .object({
+ query: z.string().min(1),
+ type: z.enum(["docs", "guides", "changelog"]).default("docs"),
+ })
+ .strict();
+
+const SearchDocsOutput = z.object({
+ results: z.array(
+ z.object({
+ title: z.string(),
+ description: z.string().optional(),
+ snippet: z.string(),
+ url: z.string(),
+ path: z.string(),
+ }),
+ ),
+ error: z.string().optional(),
+});
+
+export const searchDocsTool: AgentTool<
+ z.infer<typeof SearchDocsInput>,
+ z.infer<typeof SearchDocsOutput>
+> = {
+ name: "search_docs",
+ description:
+ "Search the public openstatus documentation, guides, or changelog. Returns scored results with title, snippet, url, and a path usable with get_doc_page.",
+ scope: "read",
+ destructive: false,
+ inputSchema: SearchDocsInput,
+ outputSchema: SearchDocsOutput,
+ // A docs lookup failure should degrade the answer, not abort the chat turn.
+ async run({ input }) {
+ try {
+ const { query, type } = input;
+ const res = await fetch(
+ `${WEB_BASE_URL}/api/search?p=${type}&q=${encodeURIComponent(query)}`,
+ { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) },
+ );
+ if (!res.ok) {
+ return {
+ results: [],
+ error: `search unavailable (HTTP ${res.status})`,
+ };
+ }
+ const body = (await res.json()) as unknown;
+ if (!Array.isArray(body)) {
+ return {
+ results: [],
+ error: "search unavailable (unexpected response)",
+ };
+ }
+ // Pick fields defensively — the web app's response shape can drift.
+ const results = body
+ .flatMap((el) => {
+ const item = el as {
+ metadata?: { title?: unknown; description?: unknown };
+ content?: unknown;
+ href?: unknown;
+ };
+ const title = item.metadata?.title;
+ const href = item.href;
+ if (typeof title !== "string" || typeof href !== "string") return [];
+ return [
+ {
+ title,
+ description:
+ typeof item.metadata?.description === "string"
+ ? item.metadata.description
+ : undefined,
+ snippet: typeof item.content === "string" ? item.content : "",
+ url: `${WEB_BASE_URL}${href}`,
+ path: href.split(/[?#]/)[0].replace(/^\//, ""),
+ },
+ ];
+ })
+ .slice(0, MAX_RESULTS);
+ return { results };
+ } catch {
+ return { results: [], error: "search unavailable (network error)" };
+ }
+ },
+};
+
+const GetDocPageInput = z.object({ path: z.string().min(1) }).strict();
+
+const GetDocPageOutput = z.object({
+ url: z.string(),
+ markdown: z.string(),
+ truncated: z.boolean(),
+ error: z.string().optional(),
+});
+
+export const getDocPageTool: AgentTool<
+ z.infer<typeof GetDocPageInput>,
+ z.infer<typeof GetDocPageOutput>
+> = {
+ name: "get_doc_page",
+ description:
+ "Fetch the full markdown content of a documentation, guide, or changelog page by path (as returned by search_docs).",
+ scope: "read",
+ destructive: false,
+ inputSchema: GetDocPageInput,
+ outputSchema: GetDocPageOutput,
+ async run({ input }) {
+ const path = input.path.replace(/^\//, "");
+ const url = `${WEB_BASE_URL}/${path}`;
+ // Allowlist keeps this a docs reader, not a generic URL fetcher.
+ if (
+ !DOC_PATH_PREFIXES.some((prefix) => path.startsWith(prefix)) ||
+ path.includes("..")
+ ) {
+ return {
+ url,
+ markdown: "",
+ truncated: false,
+ error: "path must start with docs/, guides/ or changelog/",
+ };
+ }
+ try {
+ // No Accept: text/markdown header — the site middleware rewrites any
+ // request carrying it to /api/markdown/<path>, doubling the prefix → 404.
+ const res = await fetch(`${WEB_BASE_URL}/api/markdown/${path}`, {
+ signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+ });
+ if (!res.ok) {
+ return {
+ url,
+ markdown: "",
+ truncated: false,
+ error: `page not found (HTTP ${res.status})`,
+ };
+ }
+ const text = await res.text();
+ if (text.length <= MAX_MARKDOWN_CHARS) {
+ return { url, markdown: text, truncated: false };
+ }
+ return {
+ url,
+ markdown: `${text.slice(0, MAX_MARKDOWN_CHARS)}\n\n[truncated — content continues at ${url}]`,
+ truncated: true,
+ };
+ } catch {
+ return {
+ url,
+ markdown: "",
+ truncated: false,
+ error: "page unavailable (network error)",
+ };
+ }
+ },
+};
diff --git a/packages/services/src/agent-tools/index.ts b/packages/services/src/agent-tools/index.ts
index a243864f5..64db27174 100644
--- a/packages/services/src/agent-tools/index.ts
+++ b/packages/services/src/agent-tools/index.ts
@@ -1,6 +1,7 @@
import type { z } from "zod";
import { getAuditLogTool, listAuditLogsTool } from "./audit";
+import { getDocPageTool, searchDocsTool } from "./docs";
import { createMaintenanceTool, listMaintenancesTool } from "./maintenance";
import {
getMonitorStatusTool,
@@ -23,6 +24,7 @@ import {
import type { AnyAgentTool } from "./types";
export { getAuditLogTool, listAuditLogsTool } from "./audit";
+export { getDocPageTool, searchDocsTool } from "./docs";
export { createMaintenanceTool, listMaintenancesTool } from "./maintenance";
export {
getMonitorStatusTool,
@@ -86,6 +88,8 @@ export const agentTools = {
list_notifications: listNotificationsTool,
list_audit_logs: listAuditLogsTool,
get_audit_log: getAuditLogTool,
+ search_docs: searchDocsTool,
+ get_doc_page: getDocPageTool,
} satisfies Record<string, AnyAgentTool>;
// Multi-flag confirmation UX should be a modal, not 2^N buttons. Fail
diff --git a/packages/services/src/agent-tools/prompt.ts b/packages/services/src/agent-tools/prompt.ts
index 17e3c18b2..49dbeb237 100644
--- a/packages/services/src/agent-tools/prompt.ts
+++ b/packages/services/src/agent-tools/prompt.ts
@@ -31,9 +31,10 @@ export function buildAgentSystemPrompt(opts: AgentSystemPromptOptions): string {
opts.surface === "dashboard"
? `\n\nAfter a tool returns, the dashboard already renders a structured view of the result:
- Write tools (create_*, update_*, resolve_*, add_*) render a diff card with every input/output field (id, status, message, dates, notify outcome).
-- List tools (list_status_pages, list_page_components, list_status_reports, list_maintenances, list_monitors, list_notifications, list_response_logs, list_audit_logs) render a table with one row per result.
+- List tools (list_status_pages, list_page_components, list_status_reports, list_maintenances, list_monitors, list_notifications, list_response_logs, list_audit_logs, search_docs) render a table with one row per result.
- Detail tools (get_monitor, get_monitor_status, get_monitor_summary, get_response_log, get_audit_log) render a structured detail card.
-DO NOT restate that data in your reply — no markdown tables, no bullet recaps of the rows, no field-by-field summaries. A one-line acknowledgement ("You have 4 status reports — 3 active." / "Monitor 12 is healthy in 5/7 regions; failing in gru, fra." / "Incident resolved.") plus an optional next step is enough.`
+DO NOT restate that data in your reply — no markdown tables, no bullet recaps of the rows, no field-by-field summaries. A one-line acknowledgement ("You have 4 status reports — 3 active." / "Monitor 12 is healthy in 5/7 regions; failing in gru, fra." / "Incident resolved.") plus an optional next step is enough.
+Exception: after get_doc_page, DO synthesize an answer from the page content — the answer is the point; just don't paste the whole page.`
: "";
const preamble = opts.preamble ? `${opts.preamble}\n\n` : "";
@@ -50,7 +51,7 @@ DO NOT restate that data in your reply — no markdown tables, no bullet recaps
The current date and time is ${now} (UTC). Default timezone for any date you produce is UTC unless the user specifies otherwise — mention that you defaulted to UTC when relevant.
${surfaceLine}${dashboardPostToolRule}
-You help teams manage status pages, status reports, and maintenance windows, and answer SRE / on-call questions ("what's broken right now?") against monitors, response logs, and notification channels.
+You help teams manage status pages, status reports, and maintenance windows, answer SRE / on-call questions ("what's broken right now?") against monitors, response logs, and notification channels, and answer product / how-to questions from the official openstatus docs.
Anti-guess rules — these are absolute:
- You have NO knowledge of this workspace's data. NEVER invent or guess IDs (page id, status report id, maintenance id, page component id, monitor id, notification id, response log id).
@@ -72,6 +73,13 @@ Monitor diagnostics:
Notification channels:
- list_notifications shows what's configured, including which monitors each channel is wired to. Use it to advise the user ("PagerDuty is attached to monitor 17, so on-call will page"). The agent has NO send-notification tool — actually triggering an alert happens outside chat.
+Docs knowledge base:
+- For questions about how openstatus itself works (features, configuration, CLI, API, plans), call search_docs BEFORE answering — never answer product questions from memory.
+- Reformulate the question into keyword queries. If the first search misses, retry once with different terms or type: "guides". "When did X ship?" → type: "changelog".
+- For the best 1-2 hits, call get_doc_page and ground your answer in that content. ALWAYS cite the page URL(s) in your reply as markdown links.
+- If nothing relevant is found, say so plainly instead of guessing.
+- Do NOT use search_docs for workspace data questions — the list/get tools are the source of truth there.
+
Lifecycle:
- Status reports flow: create_status_report once → add_status_report_update repeatedly → resolve_status_report.
- "provide an update", "we found the cause", "still investigating" → add_status_report_update.