docs: split AI Insights into index page and Build Insights sub-page (#1254)

arcappcircle · claude · web-flow · commit a33f875b8228 · 2026-07-01T14:19:11.000+03:00
Convert docs/appcircle-ai/ai-insights.md into a category folder: index.md
is a general AI Insights overview, and the Build Insights Report detail
moves to a build-insights.md sub-page. Repoint the 'full metric
reference' links in the Claude Assistant and MCP Server pages to the new
sub-page. The /appcircle-ai/ai-insights URL is unchanged.

Co-authored-by: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/docs/appcircle-ai/ai-assistants/appcircle-claude-assistant.md b/docs/appcircle-ai/ai-assistants/appcircle-claude-assistant.md
@@ -16,7 +16,7 @@ The plugin registers the [Appcircle MCP Server](/appcircle-ai/appcircle-mcp-serv
 | Skill | Purpose |
 |-------|---------|
 | `appcircle:doc-assistant` | Answers Appcircle questions using official sources (`docs.appcircle.io` and `appcircle.io`) |
-| `appcircle:build-insights-report` | Renders a visual Build Insights Report (health & trends, root cause, workflow quality, artifact health, queue time, and CI maturity) from the `get_build_insights_report` MCP tool. See [AI Insights](/appcircle-ai/ai-insights) for the full metric reference |
+| `appcircle:build-insights-report` | Renders a visual Build Insights Report (health & trends, root cause, workflow quality, artifact health, queue time, and CI maturity) from the `get_build_insights_report` MCP tool. See [Build Insights](/appcircle-ai/ai-insights/build-insights) for the full metric reference |
 
 Claude Code and claude.ai install the plugin differently, so follow the steps for the surface you use. MCP tools are only available in Claude Code for now; installing the plugin in claude.ai gets you the `doc-assistant` skill, not the MCP tools.
 
diff --git a/docs/appcircle-ai/ai-insights/_category_.json b/docs/appcircle-ai/ai-insights/_category_.json
@@ -0,0 +1,6 @@
+{
+  "label": "AI Insights",
+  "position": 4,
+  "collapsed": true,
+  "collapsible": true
+}
diff --git a/docs/appcircle-ai/ai-insights/build-insights.md b/docs/appcircle-ai/ai-insights/build-insights.md
@@ -1,22 +1,18 @@
 ---
-title: AI Insights
+title: Build Insights
 description: Understand the Appcircle Build Insights Report - every section and metric returned by the get_build_insights_report MCP tool, and how to generate the visual report with the Appcircle Claude Assistant.
 tags: [appcircle ai, ai insights, build insights]
-sidebar_position: 4
+sidebar_position: 1
 ---
 
 import ContentRef from '@site/src/components/ContentRef';
 import Screenshot from '@site/src/components/Screenshot';
 
-# AI Insights
-
-Turn your build history into answers. AI Insights reads your CI data and generates the Build Insights Report: trends, root causes, and a maturity score at a glance.
-
-## Build Insights Report
+# Build Insights Report
 
 The **Build Insights Report** gives you a snapshot of your CI health: build trends, failure root causes, workflow quality, artifact health, queue time, and an overall maturity score. Use the [Appcircle Claude Assistant](/appcircle-ai/ai-assistants/appcircle-claude-assistant) to get a visual report, or use the [Appcircle MCP client](/appcircle-ai/appcircle-mcp-server) directly.
 
-### How to Generate a Report
+## How to Generate a Report
 
 **With the Appcircle Claude Assistant**
 
@@ -28,11 +24,11 @@ The **Build Insights Report** gives you a snapshot of your CI health: build tren
 - Call `get_build_insights_report` directly from any MCP-compatible client (Cursor, VS Code, Codex, and so on).
 - You get the same metrics as structured JSON, which you can read, feed into another tool, or visualize yourself.
 
-### Report Sections
+## Report Sections
 
 The report has six sections.
 
-#### Maturity Assessment
+### Maturity Assessment
 
 A single CI maturity score (0-100) for the period, with a label of **Developing**, **Practicing**, **Advancing**, or **Optimizing**, and the delta against the previous period. The overall score rolls up four weighted dimensions:
 
@@ -53,7 +49,7 @@ Below the scores, a ranked **Top Improvements** list surfaces the highest-impact
 
 <Screenshot url='https://cdn.appcircle.io/docs/assets/AI-110-Build-Insights-Maturity-Assessment.png'/>
 
-#### Health Snapshot & Trends
+### Health Snapshot & Trends
 
 **Health Snapshot** is a point-in-time view of the period:
 
@@ -74,7 +70,7 @@ Below the scores, a ranked **Top Improvements** list surfaces the highest-impact
 
 <Screenshot url='https://cdn.appcircle.io/docs/assets/AI-110-Build-Insights-Trends.png'/>
 
-#### Root Cause
+### Root Cause
 
 Failure analysis for the period:
 
@@ -86,7 +82,7 @@ Failure analysis for the period:
 
 <Screenshot url='https://cdn.appcircle.io/docs/assets/AI-110-Build-Insights-Root-Cause.png'/>
 
-#### Workflow Quality
+### Workflow Quality
 
 How well each profile's workflows match Appcircle's recommended flow:
 
@@ -96,12 +92,12 @@ How well each profile's workflows match Appcircle's recommended flow:
 
 <Screenshot url='https://cdn.appcircle.io/docs/assets/AI-110-Build-Insights-Trends-Workflow-Quality.png'/>
 
-#### Artifact Health
+### Artifact Health
 
 - Average primary artifact size per profile for the period, as a ranked bar chart.
 - Call-outs for the profile whose artifact grew the most and the one that shrank the most compared to the previous period (when a previous-period baseline exists).
 
-#### Queue Time
+### Queue Time
 
 How long builds waited before starting, tree-wide for the period:
 
@@ -111,24 +107,24 @@ How long builds waited before starting, tree-wide for the period:
 
 <Screenshot url='https://cdn.appcircle.io/docs/assets/AI-110-Build-Insights-Artifact-Queue.png'/>
 
-### FAQ
+## FAQ
 
-#### What's the Default Time Range?
+### What's the Default Time Range?
 
 The last 30 days, compared against the 30 days before that for deltas. Pass `start_date` and `end_date` to the tool to use a different window; the tool compares it against a preceding period of the same length.
 
-#### Can I Get This Report Outside the Appcircle Claude Assistant?
+### Can I Get This Report Outside the Appcircle Claude Assistant?
 
 Yes, for the underlying data. Any MCP client can call `get_build_insights_report` and get the same metrics as JSON. The visual HTML report rendering shown on this page is produced by the `appcircle:build-insights-report` skill, which is currently exclusive to the [Appcircle Claude Assistant](/appcircle-ai/ai-assistants/appcircle-claude-assistant).
 
-#### Why Is a Section Missing From My Report?
+### Why Is a Section Missing From My Report?
 
 A section can be absent because there was not enough build activity to compute it for the requested period (for example, no builds, no queued builds, or no profiles with a comparable previous period), which is not an error and not a zero value. It can also be absent because your [access token](/appcircle-ai/appcircle-mcp-server#authentication) lacks the required permission for the data that section depends on. Generating the full report requires a token with at least the **Manager** role. Check your token's role permissions if a section you expect to see is consistently absent.
 
-#### Does the Report Include Builds From Sub-Organizations?
+### Does the Report Include Builds From Sub-Organizations?
 
 Only if you set `include_sub_orgs` to `true` when calling the tool. It defaults to `false`.
 
-#### Why Might Workflow Quality Section Be Missing?
+### Why Might Workflow Quality Section Be Missing?
 
 Workflow Quality is computed from profiles that have at least one Push or PR trigger configured. If no profiles in the organization have Push or PR triggers set up, the section is omitted from the report.
diff --git a/docs/appcircle-ai/ai-insights/index.md b/docs/appcircle-ai/ai-insights/index.md
@@ -0,0 +1,20 @@
+---
+title: AI Insights
+description: AI Insights turns your Appcircle build history into answers - trends, root causes, and a maturity score, generated from your CI data.
+tags: [appcircle ai, ai insights, build insights]
+sidebar_position: 4
+---
+
+import ContentRef from '@site/src/components/ContentRef';
+
+# AI Insights
+
+Turn your build history into answers. AI Insights reads your Appcircle CI data and turns it into clear, actionable reports: trends, root causes, and a maturity score at a glance, without building dashboards yourself.
+
+You generate these reports with the [Appcircle Claude Assistant](/appcircle-ai/ai-assistants/appcircle-claude-assistant) for a visual view, or through the [Appcircle MCP client](/appcircle-ai/appcircle-mcp-server) for the same data as structured JSON.
+
+## [Build Insights Report](/appcircle-ai/ai-insights/build-insights)
+
+The Build Insights Report gives you a snapshot of your CI health: build trends, failure root causes, workflow quality, artifact health, queue time, and an overall maturity score.
+
+<ContentRef url="/appcircle-ai/ai-insights/build-insights">Build Insights Report</ContentRef>
diff --git a/docs/appcircle-ai/appcircle-mcp-server.md b/docs/appcircle-ai/appcircle-mcp-server.md
@@ -92,7 +92,7 @@ You can exclude one or more toolsets when running the server (via environment va
 | Tool | Description | Permission |
 |------|-------------|------------|
 | `get_build_history_report` | Get build history report with pagination and optional filters (date range, build profile, organization). | Viewer |
-| `get_build_insights_report` | Get an aggregated Build Insights Report over build history: health snapshot and trends, root cause, artifact health, workflow quality, queue time, and maturity assessment. Defaults to the last 30 days; supports optional date range, section filtering, and sub-organization scope. See [AI Insights](/appcircle-ai/ai-insights) for the full metric reference. | Viewer |
+| `get_build_insights_report` | Get an aggregated Build Insights Report over build history: health snapshot and trends, root cause, artifact health, workflow quality, queue time, and maturity assessment. Defaults to the last 30 days; supports optional date range, section filtering, and sub-organization scope. See [Build Insights](/appcircle-ai/ai-insights/build-insights) for the full metric reference. | Viewer |
 | `get_signing_report` | Get signing report with pagination and optional filters (date range, organization, OS, build status). | Viewer |
 | `get_distribution_app_version_report` | Get daily usage report for distributed app versions with pagination and filters (date range, profile, OS, organization). | Viewer |
 | `get_distribution_sent_report` | Get daily usage report for distributed app sharing with pagination and filters (date range, profile, OS, organization). | Viewer |
