docs(workflows): connections gets its video, an FAQ, and accurate output examples

The reorg dropped two things from the old tags page that belonged on the
connections reference: the connections.mp4 walkthrough (restored after the
intro) and the FAQ (rebuilt in the robust JSX form — resolver order, name
normalization, env-var syntax pointer, didn't-run behavior, array indexing,
Function-block formatting; answers aligned with the since-verified resolver
facts, including unmatched-references-left-in-place).

Editorial/accuracy pass on the output-shape tabs while in there: stale gpt-4o
and gpt-5 examples now claude-sonnet-4-6, the Agent tokens shape corrected to
the verified { input, output, total } (the page contradicted blocks/agent), and
the dubious cost: [] line dropped — the example now matches the real run
inspector.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ouiliame

apps/docs/content/docs/en/workflows/connections.mdx

@@ -7,9 +7,15 @@ pageType: reference
 import { Callout } from 'fumadocs-ui/components/callout'
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 import { Card, Cards } from 'fumadocs-ui/components/card'
+import { Video } from '@/components/ui/video'
+import { FAQ } from '@/components/ui/faq'
 
 A **connection** wires one block to the next and sets the order they run in. [How blocks pass data](/workflows/data-flow) covers the concept: once a block runs, its output is remembered under the block's name, and any later block reads it by reference. This page is the reference for the **connection tag** syntax and the output shapes you'll reach into.
 
+<div className="mx-auto w-full overflow-hidden rounded-lg">
+  <Video src="connections.mp4" />
+</div>
+
 ## Tag syntax
 
 A connection tag references a value from an earlier block's output:
@@ -73,14 +79,13 @@ A tag's path depends on what the source block produced. These are the standard s
     ```json
     {
       "content": "The generated text response",
-      "model": "gpt-4o",
-      "tokens": { "prompt": 120, "completion": 85, "total": 205 },
-      "toolCalls": [],
-      "cost": []
+      "model": "claude-sonnet-4-6",
+      "tokens": { "input": 120, "output": 85, "total": 205 },
+      "toolCalls": []
     }
     ```
 
-    `content` is the main response. `tokens` is an object of usage counts. `toolCalls` and `cost` are present when the agent used tools. With a response format configured, the output matches your schema instead of this shape.
+    `content` is the main response. `tokens` is an object of usage counts. `toolCalls` lists the tools the agent called, with their inputs and results. With a response format configured, your schema's fields appear as their own outputs instead.
   </Tab>
   <Tab>
     ```json
@@ -122,8 +127,8 @@ A tag's path depends on what the source block produced. These are the standard s
     ```json
     {
       "content": "Routing decision",
-      "model": "gpt-4o",
-      "tokens": { "prompt": 120, "completion": 85, "total": 205 },
+      "model": "claude-sonnet-4-6",
+      "tokens": { "input": 120, "output": 85, "total": 205 },
       "selectedPath": {
         "blockId": "2acd9007-27e8-4510-a487-73d3b825e7c1",
         "blockType": "agent",
@@ -138,8 +143,8 @@ A tag's path depends on what the source block produced. These are the standard s
     ```json
     {
       "content": "Evaluation summary",
-      "model": "gpt-5",
-      "tokens": { "prompt": 120, "completion": 85, "total": 205 },
+      "model": "claude-sonnet-4-6",
+      "tokens": { "input": 120, "output": 85, "total": 205 },
       "metric1": 8.5,
       "metric2": 7.2
     }
@@ -151,6 +156,15 @@ A tag's path depends on what the source block produced. These are the standard s
 
 A Function's `result`, an API's `data`, and an Agent with a response format all return whatever your code, the remote service, or your schema produced, so check the output panel during development to confirm the path you're referencing.
 
+<FAQ items={[
+  { question: "How are tag references resolved at runtime?", answer: "The executor matches each angle-bracket reference against resolvers in a fixed order: loop and parallel context, then workflow variables, then block outputs. The first resolver that recognizes the reference handles it, and an unmatched reference is left in place unsubstituted." },
+  { question: "Does the block name in a tag need to match exactly?", answer: "Names are normalized before matching — lowercased, spaces removed — so <My Agent.content> and <myagent.content> resolve to the same block. The field path after the block name is case-sensitive." },
+  { question: "Can I reference environment variables with angle brackets?", answer: "No. Environment variables use double-brace syntax, {{MY_VAR}}, and resolve separately. Angle brackets read block outputs, workflow variables, and loop or parallel context. See the variables reference for both syntaxes." },
+  { question: "What happens if I reference a block that didn't run?", answer: "If the block was on a branch that wasn't taken, the reference resolves to an empty value — an empty string in most blocks, null in Function blocks. Check the failed block's Input tab in the logs to see what a reference actually resolved to." },
+  { question: "Can I access array elements inside a tag?", answer: "Yes. Use bracket indices in the path, like <api1.data.users[0].name>. Multiple levels of indexing such as items[0][1] work as well." },
+  { question: "Why does the same tag render differently in a Function block?", answer: "Function blocks receive resolved values as code literals — strings quoted, objects as JSON, null as null — so they drop straight into JavaScript or Python. In other blocks, objects are JSON-stringified and primitives become plain strings." },
+]} />
+
 ## Next
 
 <Cards>