docs(falcon-ai): add Imagine feature page

src/lib/navigation.ts

@@ -321,6 +321,7 @@ export const tabNavigation: NavTab[] = [
             title: 'Features',
             items: [
               { title: 'Using Falcon AI', href: '/docs/falcon-ai/features/chat' },
+              { title: 'Imagine', href: '/docs/falcon-ai/features/imagine' },
               { title: 'Skill Builder', href: '/docs/falcon-ai/features/skills' },
               { title: 'MCP Connectors', href: '/docs/falcon-ai/features/mcp-connectors' },
             ]

src/pages/docs/falcon-ai/features/imagine.mdx

@@ -0,0 +1,200 @@
+---
+title: "Imagine"
+description: "Chat with Falcon AI to turn any trace into a custom view of charts, tables, and metric cards, then save it to apply to any other trace."
+slug: "imagine"
+page_type: "feature-deep-dive"
+products:
+  - "Falcon AI"
+feature_area: "Trace visualization"
+feature_status: "beta"
+audience:
+  - "engineer"
+difficulty: "intermediate"
+status: "review"
+owner: "futureagi-engineering"
+reviewers:
+  - "falcon-ai-owner"
+last_tested: "2026-05-25"
+last_screenshotted: "2026-05-25"
+schema_type: "TechArticle"
+seo:
+  title: "Imagine: AI-built Trace Views in Future AGI"
+  description: "Build a custom widget view over any trace by chatting with Falcon AI, then save the view to apply to any other trace in the project."
+  primary_keyword: "trace visualization"
+  direct_answer: true
+geo:
+  answer_target: "how to build a custom trace dashboard with Falcon AI"
+  llm_summary: "Imagine is Future AGI's chat-driven view builder for traces. Falcon AI assembles charts, tables, and metric cards on a 12-column canvas and lets you save the layout to reuse on any trace."
+canonical: "https://docs.futureagi.com/docs/falcon-ai/features/imagine"
+related:
+  - "/docs/falcon-ai/features/chat"
+  - "/docs/falcon-ai/features/skills"
+  - "/docs/falcon-ai/features/mcp-connectors"
+  - "/docs/observe"
+---
+
+import Mermaid from '../../../../components/docs/Mermaid.astro';
+
+## About
+
+Imagine is a custom view builder inside Falcon AI's chat panel. Open any trace from the Tracing dashboard, describe what you want to see in plain English, and Falcon AI assembles widgets, charts, tables, metric cards, span trees, and markdown summaries, on a 12-column canvas. Save the view and it applies to any other trace in the same project, including ones that already exist. Imagine replaces the loop of exporting trace JSON to a notebook and hand-coding plots for every investigation.
+
+---
+
+## When to use
+
+- You keep exporting trace data into a notebook just to chart per-span latency, token usage, or cost split.
+- Your team debugs the same failure pattern across many traces and wants one saved layout that lights up the relevant signals on every new trace.
+- A trace has 15 or more spans and the default tree view buries the bottleneck you need to surface.
+- On-call engineers need a one-tab summary view (*agent overview*, *cost and latency*, *tool-call health*) that opens against any trace they touch.
+- You want a narrative summary ("what went wrong here") regenerated on demand for every trace, without writing custom code.
+- A reviewer asks for a chart in a Slack post-mortem, and you need the chart fast against the exact trace they linked.
+
+---
+
+## When not to use
+
+- For static dashboards across many traces or over time, use [Dashboards](/docs/observe/features/dashboard) instead. Imagine views are anchored to one trace at a time.
+- For one-off questions like "did this trace error?", just ask Falcon AI in the [chat panel](/docs/falcon-ai/features/chat). Building widgets is overhead when prose suffices.
+- For voice and Retell traces that lack per-span data, the canvas will be sparse because the agent has nothing to bind charts to. Inspect the **Voice** tab in the trace drawer instead.
+- For batch scoring across many traces, run an [evaluation](/docs/evaluation) rather than building a per-trace view.
+- For diffing two traces side by side, Imagine renders one trace at a time. Open the traces in separate browser tabs.
+
+---
+
+## How it works internally
+
+The Imagine canvas lives inside the trace detail drawer. When you send a message, Falcon AI runs in **imagine** mode with tracing and visualization tools loaded automatically. The agent reads spans from the current trace, decides what visualizations to emit, then issues one or more `render_widget` tool calls. Each call places a widget on a 12-column CSS grid, so widgets sit side by side or stack across rows. Tool calls and responses stream into the chat panel; widgets appear on the canvas as they are emitted.
+
+<Mermaid code={`flowchart TD
+  prompt[Your prompt] --> agent[Falcon AI reads spans, emits render_widget calls]
+  agent --> canvas[Widgets on 12-column canvas]
+  canvas --> saved[Saved view: project or workspace scope]
+  saved --> live[Charts and tables: re-bind to new trace, no agent call]
+  saved --> dynamic[Markdown summaries: re-run via Temporal, cached per view+widget+trace]
+`} />
+
+Two execution boundaries matter:
+
+- **Build time** (this conversation): Falcon AI reads spans from the current trace, decides what visualizations to emit, and returns widget JSON streamed into the chat panel.
+- **Replay time** (saved view opened on a different trace): widgets bound to trace fields re-render immediately against the new trace's data. Widgets marked for dynamic analysis run through a Temporal workflow and cache their result keyed by `(saved_view, widget, trace_id)`.
+
+Inspect the tool-call cards in the chat panel to see exactly which spans the agent read before emitting each widget.
+
+---
+
+## Widget catalog
+
+Imagine ships with 17 widget types defined in the `render_widget` tool. Falcon AI picks types based on your request, and you can also name a type explicitly in your prompt.
+
+| Category | Widgets |
+|----------|---------|
+| **Charts** | Line, bar, area, pie, donut, radar |
+| **Tables** | Data table, key-value list |
+| **Metrics** | Metric card, heatmap |
+| **Trace structure** | Span tree, timeline, agent graph |
+| **Data inspection** | JSON tree, code block |
+| **Annotations** | Markdown, screenshot annotated |
+
+Each widget either binds directly to live trace data or captures the output of a Falcon analysis. Live-data widgets re-render against any trace without a new agent call. Analysis-backed widgets re-run on demand (see [Dynamic analysis](#dynamic-analysis)).
+
+---
+
+## Opening Imagine
+
+Open any trace from the Tracing dashboard, then click the **Imagine** tab in the trace detail drawer. The toolbar shows **Save View** on the left for persisting layouts and a **Falcon** toggle on the right that hides or shows the chat panel.
+
+![Future AGI Falcon AI Imagine tab on a trace, empty canvas with six suggested prompt chips](/screenshot/product/falcon/10.png)
+
+Confirm the toolbar shows **Save View** and the **Falcon** toggle. If the Imagine tab is missing, the trace's project is on an older deployment that has not received the feature yet.
+
+On a fresh trace, suggested prompt chips appear on the empty canvas: *"Show me where the latency is"*, *"Visualize token usage by span"*, *"Show the agent execution flow"*, *"What's the cost breakdown?"*, *"Compare the LLM calls"*, *"Summarize this trace"*. Click a chip to send it to the chat panel, or type your own request.
+
+---
+
+## Saving views
+
+A canvas built for one trace becomes more valuable when it applies to any trace. Save it as a view to make it reusable.
+
+<Steps>
+  <Step title="Build the view">
+    Use the chat panel to assemble the widgets you want. A specific prompt like *"Render a bar chart of latency per span, a donut for token usage by model, and metric cards for total duration and cost"* forces explicit `render_widget` calls instead of a prose answer.
+
+    ![Future AGI Imagine canvas with four metric cards, a per-span latency bar chart, and a latency-share donut on the left and a Falcon chat panel on the right](/screenshot/product/falcon/11.png)
+
+    Verify each widget references real span names and metrics from the trace, not placeholder values. If Falcon answered in prose without rendering anything, re-ask with explicit widget framing.
+  </Step>
+
+  <Step title="Save the view">
+    Click **Save View** in the Imagine toolbar. A small popover appears with a name pre-filled from your conversation. Edit the name to something teammates will recognize on any trace ("Latency split", "Cost overview"), then confirm.
+
+    ![Future AGI Imagine Save view popover with a pre-filled name from the chat conversation](/screenshot/product/falcon/12.png)
+
+    The name is what teammates see as a tab on every trace, so prefer task-oriented names over the chat phrasing Falcon picked.
+  </Step>
+
+  <Step title="Reopen on any trace">
+    The saved view appears as a tab next to the default Imagine tab. Open any trace in the same project, click the saved view's tab, and the same widgets render against that trace's data.
+  </Step>
+</Steps>
+
+Saved views can be scoped to the project or kept private to the workspace. Project-scoped views are visible to everyone in the project who has access to the trace.
+
+<Note>
+  The **Save View** button is disabled until at least one widget is on the canvas.
+</Note>
+
+---
+
+## Dynamic analysis
+
+Charts, tables, and metric widgets bind to trace data through field paths, so they update on a new trace without any agent call. Narrative widgets like markdown summaries cannot do this; they need fresh analysis each time. Imagine handles them with **dynamic analysis**.
+
+When you open a saved view on a new trace:
+
+- Widgets with live bindings render immediately.
+- Widgets marked for dynamic analysis show a skeleton loader and the message *"Falcon is analyzing this trace..."* while the analysis runs.
+- Each completed widget is cached per `(saved_view, widget, trace_id)`, so reopening the same view on the same trace skips the agent call.
+
+![Future AGI Imagine saved view named LLM Latency reopened on a different trace, with bar chart, donut, and metric cards re-rendering against the new trace's spans](/screenshot/product/falcon/13.png)
+
+Inspect the metric cards and bar chart: they reference the new trace's spans and durations, not the values from the trace the view was built on. The agent did not run; the widgets re-resolved their field-path bindings against the new trace data. A **Rerun** button appears in each dynamic widget's title bar once analysis completes. Click it to discard the cached result and run the analysis again.
+
+---
+
+## Reliability and limits
+
+Dynamic analysis runs through a Temporal workflow with built-in retries, so transient failures from the model provider do not surface in the UI.
+
+| Step | Timeout | Retry policy |
+|------|---------|--------------|
+| Fetch trace data | 30 s | Up to 2 attempts |
+| Agent analysis | 90 s | Up to 5 attempts with exponential backoff (5 s to 30 s) |
+| Save result | 10 s | Default |
+
+If the agent step exhausts its retries, the widget records a failure state in the database. Click **Rerun** to try again.
+
+The chat panel shares Falcon AI's rate limit of 10 messages per 60 seconds per user. Dynamic analysis re-runs do not count against this limit; they go through a dedicated single-shot endpoint with a 45-second timeout.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| **Save View** button stays disabled | No widgets on the canvas yet | Send at least one prompt; the button enables as soon as one `render_widget` tool call returns. |
+| Widget never appears after Falcon replies | Falcon answered in prose instead of calling `render_widget` | Re-ask with explicit framing, e.g. *"Render a bar chart widget showing latency per span using the render_widget tool."* |
+| Dynamic widget stuck on skeleton loader | Temporal workflow still running or agent step retrying | Wait up to 90 s; if it persists, click **Rerun** in the widget's title bar. |
+| Saved view shows empty widgets on a new trace | Trace is missing the fields the widget was bound to (for example a voice trace with no LLM spans) | Open a trace from a project with matching span shape. Views are not portable across projects with different instrumentation. |
+| Falcon hits *"rate limit reached"* mid-build | More than 10 messages in 60 s in the chat panel | Wait 60 s and resume. Dynamic analysis re-runs do not share this limit. |
+| Widget renders but data looks wrong | Falcon misread an attribute name or used the wrong span filter | Open the tool-call card in chat to see the read path, then ask Falcon to re-render with the correct field. |
+
+---
+
+## Related
+
+- To save a view that your team can reuse on every trace, see [Saving views](#saving-views) above.
+- To open Falcon without a specific trace in context, use [Falcon AI chat](/docs/falcon-ai/features/chat).
+- To turn a recurring Imagine prompt into a one-click action, build a [Skill](/docs/falcon-ai/features/skills).
+- To pull external context (Linear, Slack, GitHub) into the same chat, configure an [MCP Connector](/docs/falcon-ai/features/mcp-connectors).
+- To monitor metrics across many traces or over time, use [Dashboards](/docs/observe/features/dashboard) instead of a per-trace view.