Improve documentation formatting and consistency

docs/concepts/components.md

@@ -5,11 +5,13 @@ A2UI uses an **adjacency list model** for component hierarchies. Instead of nest
 ## Why Flat Lists?
 
 **Traditional nested approach:**
+
 - LLM must generate perfect nesting in one pass
 - Hard to update deeply nested components
 - Difficult to stream incrementally
 
 **A2UI adjacency list:**
+
 - ✅ Flat structure, easy for LLMs to generate
 - ✅ Send components incrementally
 - ✅ Update any component by ID
@@ -39,7 +41,7 @@ Components reference children by ID, not by nesting.
 
 Every component has:
 
-1. **ID**: Unique identifier (`"welcome-message"`)
+1. **ID**: Unique identifier (`"welcome"`)
 2. **Type**: Component type (`Text`, `Button`, `Card`)
 3. **Properties**: Configuration specific to that type
 
@@ -76,8 +78,8 @@ For each item in `/items`, render the `item-template`. See [Data Binding](data-b
 
 Components get their values two ways:
 
-**Literal** - Fixed value: `{"text": {"literalString": "Welcome"}}`
-**Data-bound** - From data model: `{"text": {"path": "/user/name"}}`
+- **Literal** - Fixed value: `{"text": {"literalString": "Welcome"}}`
+- **Data-bound** - From data model: `{"text": {"path": "/user/name"}}`
 
 LLMs can generate components with literal values or bind them to data paths for dynamic content.
 
@@ -94,9 +96,9 @@ A surface is a complete, cohesive UI (form, dashboard, chat, etc.).
 
 ## Incremental Updates
 
-**Add** - Send new `surfaceUpdate` with new component IDs
-**Update** - Send `surfaceUpdate` with existing ID and new properties
-**Remove** - Update parent's `children` list to exclude removed IDs
+- **Add** - Send new `surfaceUpdate` with new component IDs
+- **Update** - Send `surfaceUpdate` with existing ID and new properties
+- **Remove** - Update parent's `children` list to exclude removed IDs
 
 The flat structure makes all updates simple ID-based operations.
 

docs/concepts/data-binding.md

@@ -64,8 +64,8 @@ Components bound to data paths automatically update when the data changes:
 {"id": "status", "component": {"Text": {"text": {"path": "/order/status"}}}}
 ```
 
-**Initial:** `/order/status` = "Processing..." → displays "Processing..."
-**Update:** Send `dataModelUpdate` with `status: "Shipped"` → displays "Shipped"
+- **Initial:** `/order/status` = "Processing..." → displays "Processing..."
+- **Update:** Send `dataModelUpdate` with `status: "Shipped"` → displays "Shipped"
 
 No component updates needed—just data updates.
 
@@ -99,8 +99,8 @@ Inside a template, paths are scoped to the array item:
 {"id": "product-name", "component": {"Text": {"text": {"path": "/name"}}}}
 ```
 
-For `/products/0`, `/name` resolves to `/products/0/name` → "Widget"
-For `/products/1`, `/name` resolves to `/products/1/name` → "Gadget"
+- For `/products/0`, `/name` resolves to `/products/0/name` → "Widget"
+- For `/products/1`, `/name` resolves to `/products/1/name` → "Gadget"
 
 Adding/removing items automatically updates the rendered components.
 

docs/concepts/data-flow.md

@@ -22,7 +22,9 @@ A2UI defines a sequence of JSON messages that describe the UI. When streamed, th
 {"beginRendering":{"surfaceId":"main","root":"root-component"}}
 ```
 
-**Why this format?** A sequence of self-contained JSON objects is streaming-friendly, easy for LLMs to generate incrementally, and resilient to errors.
+**Why this format?**
+
+A sequence of self-contained JSON objects is streaming-friendly, easy for LLMs to generate incrementally, and resilient to errors.
 
 ## Lifecycle Example: Restaurant Booking
 
@@ -80,11 +82,11 @@ Users see UI building in real-time instead of staring at a spinner.
 
 ## Error Handling
 
-**Malformed messages:** Skip and continue, or send error back to agent for correction
-**Network interruptions:** Display error state, reconnect, agent resends or resumes
+- **Malformed messages:** Skip and continue, or send error back to agent for correction
+- **Network interruptions:** Display error state, reconnect, agent resends or resumes
 
 ## Performance
 
-**Batching:** Buffer updates for 16ms, batch render together
-**Diffing:** Compare old/new components, update only changed properties
-**Granular updates:** Update `/user/name` not entire `/` model
+- **Batching:** Buffer updates for 16ms, batch render together
+- **Diffing:** Compare old/new components, update only changed properties
+- **Granular updates:** Update `/user/name` not entire `/` model

docs/introduction/who-is-it-for.md

@@ -52,15 +52,15 @@ Do you ship your agent into other apps you don't necessarily control?
 
 ## When to Use A2UI
 
-✅ **Agent-generated UI** - Core purpose
-✅ **Multi-agent systems** - Standard protocol across trust boundaries
-✅ **Cross-platform apps** - One agent, many renderers (web/mobile/desktop)
-✅ **Security critical** - Declarative data, no code execution
-✅ **Brand consistency** - Client controls styling
-
-❌ **Static websites** - Use HTML/CSS
-❌ **Simple text-only chat** - Use Markdown
-❌ **Remote widgets not integrated with client** - Use iframes, like MCP Apps
+- ✅ **Agent-generated UI** - Core purpose
+- ✅ **Multi-agent systems** - Standard protocol across trust boundaries
+- ✅ **Cross-platform apps** - One agent, many renderers (web/mobile/desktop)
+- ✅ **Security critical** - Declarative data, no code execution
+- ✅ **Brand consistency** - Client controls styling
+
+- ❌ **Static websites** - Use HTML/CSS
+- ❌ **Simple text-only chat** - Use Markdown
+- ❌ **Remote widgets not integrated with client** - Use iframes, like MCP Apps
 <!-- TODO: figure out when to use AG UI vs when to use A2UI -->
-❌ **Rapid UI + Agent app built together** - Use AG UI / CopilotKit
+- ❌ **Rapid UI + Agent app built together** - Use AG UI / CopilotKit
 <!-- TODO: Document styling constraints - agents use semantic hints (usageHint), not pixel-perfect control -->

docs/transports.md

@@ -71,8 +71,6 @@ You can use any transport that sends JSON:
 // TODO: Add an example
 ```
 
-```
-
 ## Next Steps
 
 - **[A2A Protocol Docs](https://a2a-protocol.org)**: Learn about A2A