docs: Add schema browser and why page

.gitignore

@@ -24,4 +24,7 @@ yarn-error.log*
 
 # typescript
 *.tsbuildinfo
-next-env.d.ts
+next-env.d.ts
+
+# local demo backups
+.demo-backups/

app/docs/_components/schema-explorer.tsx

@@ -0,0 +1,106 @@
+"use client"
+
+import { useMemo, useState } from "react"
+import { Icons } from "./icons"
+import { publishedSchemas } from "../_data/generated/schemas"
+
+const latestVersionOption = "latest"
+
+export function SchemaExplorer() {
+  const [query, setQuery] = useState("")
+  const [selectedVersion, setSelectedVersion] = useState(latestVersionOption)
+
+  const versionOptions = useMemo(() => {
+    const versions = new Set<string>()
+
+    for (const schema of publishedSchemas) {
+      for (const version of schema.versions) {
+        versions.add(version)
+      }
+    }
+
+    return Array.from(versions).sort((left, right) => Number(right) - Number(left))
+  }, [])
+
+  const filteredSchemas = useMemo(() => {
+    const normalizedQuery = query.trim().toLowerCase()
+
+    return publishedSchemas.filter((schema) => {
+      const matchesQuery = normalizedQuery
+        ? schema.name.toLowerCase().includes(normalizedQuery)
+        : true
+      const hasSelectedVersion =
+        selectedVersion === latestVersionOption || schema.versions.includes(selectedVersion)
+
+      return matchesQuery && hasSelectedVersion
+    })
+  }, [query, selectedVersion])
+
+  return (
+    <>
+      <div className="tools-controls">
+        <div className="search-wrap">
+          <div className="si">
+            <Icons.Search size={14} />
+          </div>
+          <input
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+            placeholder={`Filter ${publishedSchemas.length} schemas…`}
+          />
+        </div>
+        <label className="schema-version">
+          <span>Version</span>
+          <select
+            value={selectedVersion}
+            onChange={(event) => setSelectedVersion(event.target.value)}
+          >
+            <option value={latestVersionOption}>Latest</option>
+            {versionOptions.map((version) => (
+              <option key={version} value={version}>
+                v{version}
+              </option>
+            ))}
+          </select>
+        </label>
+      </div>
+
+      <div className="tool-grid">
+        {filteredSchemas.map((schema) => {
+          const resolvedVersion =
+            selectedVersion === latestVersionOption ? schema.latest : selectedVersion
+          const href = `/schemas/structured-output/${encodeURIComponent(
+            schema.name,
+          )}/${encodeURIComponent(resolvedVersion)}.schema.json`
+          const versionLabel =
+            selectedVersion === latestVersionOption
+              ? `latest · v${schema.latest}`
+              : `v${resolvedVersion}`
+
+          return (
+            <a key={schema.name} className="tool-card schema-card" href={href}>
+              <div>
+                <div className="tc-name">{schema.name}</div>
+                <div className="tc-sub">{versionLabel}</div>
+              </div>
+              <span className="tc-badge">JSON schema</span>
+            </a>
+          )
+        })}
+        {filteredSchemas.length === 0 ? (
+          <div
+            style={{
+              padding: "24px 14px",
+              color: "var(--fg-muted)",
+              textAlign: "center",
+              border: "1px dashed var(--border-primary)",
+              borderRadius: 6,
+            }}
+          >
+            No schemas match the current filter and version.
+          </div>
+        ) : null}
+      </div>
+    </>
+  )
+}

app/docs/_content/index.ts

@@ -10,6 +10,7 @@ import WorkflowsPage from "./workflows.mdx"
 import ToolsPage from "./tools.mdx"
 import MCPProtocolSupportPage from "./mcp-protocol-support.mdx"
 import OutputFormatsPage from "./output-formats.mdx"
+import SchemasPage from "./schemas.mdx"
 import ConfigurationPage from "./configuration.mdx"
 import SessionDefaultsPage from "./session-defaults.mdx"
 import EnvVarsPage from "./env-vars.mdx"
@@ -46,6 +47,7 @@ export const PAGE_COMPONENTS: Record<DocSlug, ComponentType> = {
   tools: ToolsPage,
   "mcp-protocol-support": MCPProtocolSupportPage,
   "output-formats": OutputFormatsPage,
+  schemas: SchemasPage,
   configuration: ConfigurationPage,
   "session-defaults": SessionDefaultsPage,
   "env-vars": EnvVarsPage,

app/docs/_content/output-formats.mdx

@@ -320,10 +320,7 @@ Parameterized Swift Testing groups currently surface as a single aggregate entry
 
 ## Response schema reference
 
-Canonical JSON schemas live in the source repository under [`schemas/structured-output/`](https://github.com/getsentry/XcodeBuildMCP/tree/main/schemas/structured-output). Concrete examples:
-
-- [`xcodebuildmcp.output.simulator-list/2.schema.json`](https://github.com/getsentry/XcodeBuildMCP/blob/main/schemas/structured-output/xcodebuildmcp.output.simulator-list/2.schema.json)
-- [`xcodebuildmcp.output.build-result/2.schema.json`](https://github.com/getsentry/XcodeBuildMCP/blob/main/schemas/structured-output/xcodebuildmcp.output.build-result/2.schema.json)
+Canonical JSON schemas are published at stable website URLs under `/schemas/structured-output/...`. Browse the full list, including available versions for each schema family, in [Published Schemas](/docs/schemas).
 
 ## Examples
 
@@ -455,4 +452,5 @@ Canonical JSON schemas live in the source repository under [`schemas/structured-
 - [MCP Server Mode](/docs/mcp-mode), stdio server behavior
 - [Tools Reference](/docs/tools), generated tool catalog
 - [Rendering & Output](/docs/architecture-rendering-output), contributor-level rendering model
+- [Published Schemas](/docs/schemas), browsable JSON Schema list with version links
 - [Tool Authoring](/docs/tool-authoring), adding schemas and structured results

app/docs/_content/schemas.mdx

@@ -0,0 +1,32 @@
+import { PageHeader } from "../_components/page-header"
+import { SchemaExplorer } from "../_components/schema-explorer"
+
+<PageHeader
+  breadcrumbs={["Docs", "Reference", "Schemas"]}
+  title="Published Schemas"
+  lede="Browse the structured-output JSON Schemas published with the website. Each schema family keeps old versions available at stable URLs."
+/>
+
+XcodeBuildMCP tool results include a `schema` identifier and a `schemaVersion` string. Use those fields together to choose the published schema that validates the `data` payload returned by CLI JSON output or MCP `structuredContent`.
+
+Each link below points at the raw JSON Schema served from `/schemas/structured-output/...`.
+
+<SchemaExplorer />
+
+## URL format
+
+```text
+https://xcodebuildmcp.com/schemas/structured-output/<schema>/<version>.schema.json
+```
+
+For example:
+
+```text
+https://xcodebuildmcp.com/schemas/structured-output/xcodebuildmcp.output.build-result/2.schema.json
+```
+
+## Related
+
+- [Output Formats](/docs/output-formats), where structured output appears in CLI and MCP responses
+- [Schema Versioning](/docs/schema-versioning), how schema changes are versioned and published
+- [Tool Authoring](/docs/tool-authoring), how schemas fit into tool changes

app/docs/_data/generated/schemas.ts

@@ -0,0 +1,41 @@
+export type PublishedSchema = {
+  name: string
+  versions: string[]
+  latest: string
+}
+
+export const publishedSchemas: PublishedSchema[] = [
+  { name: "xcodebuildmcp.output.app-path", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.build-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.build-run-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.build-settings", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.bundle-id", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.capture-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.coverage-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.debug-breakpoint-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.debug-command-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.debug-session-action", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.debug-stack-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.debug-variables-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.device-list", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.doctor-report", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.error", versions: ["1"], latest: "1" },
+  { name: "xcodebuildmcp.output.install-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.launch-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.process-list", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.project-list", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.scaffold-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.scheme-list", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.session-defaults", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.session-profile", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.simulator-action-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.simulator-list", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.stop-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.test-result", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.ui-action-result", versions: ["1", "2", "3"], latest: "3" },
+  { name: "xcodebuildmcp.output.workflow-selection", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.xcode-bridge-call-result", versions: ["1", "2", "3"], latest: "3" },
+  { name: "xcodebuildmcp.output.xcode-bridge-status", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.xcode-bridge-sync", versions: ["1", "2"], latest: "2" },
+  { name: "xcodebuildmcp.output.xcode-bridge-tool-list", versions: ["1", "2", "3"], latest: "3" },
+]

app/docs/_data/routes.ts

@@ -11,6 +11,7 @@ export type DocSlug =
   | "tools"
   | "mcp-protocol-support"
   | "output-formats"
+  | "schemas"
   | "configuration"
   | "session-defaults"
   | "env-vars"
@@ -66,6 +67,7 @@ export const PAGES_ORDER: DocSlug[] = [
   "workflows",
   "mcp-protocol-support",
   "output-formats",
+  "schemas",
   "configuration",
   "session-defaults",
   "env-vars",
@@ -156,6 +158,12 @@ export const PAGE_META: Record<DocSlug, DocRoute> = {
     group: "Reference",
     description: "Machine-readable CLI output and MCP structuredContent envelopes.",
   },
+  schemas: {
+    slug: "schemas",
+    title: "Published Schemas",
+    group: "Reference",
+    description: "Browse versioned structured-output JSON Schemas published at stable website URLs.",
+  },
   configuration: {
     slug: "configuration",
     title: "Configuration",
@@ -330,6 +338,7 @@ export const SIDEBAR_GROUPS: SidebarGroup[] = [
       { slug: "workflows" },
       { slug: "mcp-protocol-support" },
       { slug: "output-formats" },
+      { slug: "schemas" },
       {
         slug: "configuration",
         children: ["session-defaults", "env-vars"],

app/docs/_styles/scraps.css

@@ -1237,6 +1237,27 @@ html[data-docs-theme='dark'] .docs-root .tool-card .tc-badge.beta {
   color: #ff93ce;
 }
 
+/* -------- Schema cards -------- */
+.docs-root a.tool-card,
+.docs-root a.tool-card:hover {
+  text-decoration: none;
+}
+.docs-root .tool-card.schema-card {
+  grid-template-columns: 1fr auto;
+}
+.docs-root .tool-card.schema-card > div {
+  min-width: 0;
+}
+.docs-root .tool-card.schema-card .tc-name {
+  overflow-wrap: anywhere;
+}
+.docs-root .tool-card.schema-card .tc-sub {
+  margin-top: 2px;
+  font-family: var(--font-mono);
+  font-size: 10px;
+  color: var(--fg-muted);
+}
+
 /* -------- Params list -------- */
 .docs-root .params {
   margin: 0 0 20px;
@@ -1606,6 +1627,27 @@ html[data-docs-theme='dark'] .docs-root .tool-card .tc-badge.beta {
   color: var(--fg-primary);
   outline: none;
 }
+.docs-root .tools-controls .schema-version {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+.docs-root .tools-controls .schema-version span {
+  font-size: 12px;
+  color: var(--fg-muted);
+}
+.docs-root .tools-controls select {
+  height: 32px;
+  padding: 0 10px;
+  font-family: var(--font-mono);
+  font-size: 12px;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-primary);
+  border-radius: 6px;
+  color: var(--fg-primary);
+  outline: none;
+  cursor: pointer;
+}
 .docs-root .tools-controls .seg {
   flex-wrap: wrap;
 }

app/page.tsx

@@ -118,6 +118,12 @@ export default function XcodeBuildMCPLanding() {
                   {item}
                 </a>
               ))}
+              <Link
+                href="/why-xcodebuildmcp"
+                className="text-sm text-sentry-text-secondary hover:text-white transition-colors"
+              >
+                Why XcodeBuildMCP?
+              </Link>
               <Link
                 href="/docs"
                 className="text-sm text-sentry-text-secondary hover:text-white transition-colors"
@@ -162,6 +168,13 @@ export default function XcodeBuildMCPLanding() {
                     {item}
                   </a>
                 ))}
+                <Link
+                  href="/why-xcodebuildmcp"
+                  onClick={() => setIsMobileMenuOpen(false)}
+                  className="text-sentry-text-secondary hover:text-white transition-colors"
+                >
+                  Why XcodeBuildMCP?
+                </Link>
                 <Link
                   href="/docs"
                   onClick={() => setIsMobileMenuOpen(false)}
@@ -209,6 +222,13 @@ export default function XcodeBuildMCPLanding() {
               <Download className="w-4 h-4" />
               Get Started
             </a>
+            <Link
+              href="/why-xcodebuildmcp"
+              className="inline-flex items-center gap-2 px-6 py-3 rounded-lg border border-sentry-dark-600 hover:border-sentry-dark-700 text-sentry-text-primary hover:bg-sentry-dark-400/50 transition-colors"
+            >
+              <Zap className="w-4 h-4" />
+              Why XcodeBuildMCP?
+            </Link>
             <Link
               href="https://github.com/getsentry/XcodeBuildMCP"
               className="inline-flex items-center gap-2 px-6 py-3 rounded-lg border border-sentry-dark-600 hover:border-sentry-dark-700 text-sentry-text-primary hover:bg-sentry-dark-400/50 transition-colors"