rebuild the README (#276)

Author: sethladd

README.md

@@ -1,19 +1,158 @@
-# A2UI (Agent to UI) Protocol
+# A2UI: Agent-to-User Interface
 
-This repository contains the specification for the A2UI protocol, a JSONL-based, streaming UI protocol designed to be easily generated by Large Language Models (LLMs).
+A2UI is an open-source project, complete with a format
+optimized for representing updateable agent-generated
+UIs and an initial set of renderers, that allows agents
+to generate or populate rich user interfaces.
 
-## Project Overview
+<img src="docs/assets/a2ui_composer_gallery.png" alt="Gallery of A2UI components" height="400">
 
-The A2UI protocol enables a server to stream a platform-agnostic, abstract UI definition to a client, which then renders it progressively using a native widget set. The core design principles are:
+*A gallery of UIs composed by A2UI and rendered by TODO(confirm).*
 
-- **LLM-Friendly**: The protocol uses a simple, declarative, and flat structure that is easy for LLMs to generate.
-- **Progressive Rendering**: The UI is streamed as a series of JSONL messages, allowing the client to render the UI as it arrives, improving perceived performance.
-- **Platform-Agnostic**: The protocol defines an abstract component tree, and the client is responsible for mapping these abstract components to its native widget implementations.
-- **Separation of Concerns**: The protocol separates the UI structure (components), the application state (data model), and the client-side widget rendering.
+## ⚠️ Status: Experimental
 
-## Repository Layout
+> **Note:** A2UI is currently in **v0.8 (Public Preview)**. The specification and
+implementations are functional but evolving. We are opening the project to gather
+feedback on the format and collaborate on client renderers. Expect changes.
 
-The repository is structured as follows:
+## Summary
 
-- `docs/`: This directory contains general information about the A2UI protocol .
-- `specification/`: Contains formal specification documents and JSON schemas for the protocol.
+Generative AI excels at creating text and code, but agents can struggle to
+present rich, interactive interfaces to users, especially when those agents
+are remote or running across trust boundaries.
+
+**A2UI** is an open standard and set of libraries that allows agents to
+"speak UI." Agents send a declarative JSON format describing the *intent* of
+the UI. The client application then renders this using its own native
+component library (Flutter, Angular, Lit, etc.).
+
+This approach ensures that agent-generated UIs are
+**safe like data, but expressive like code**.
+
+## High-Level Philosophy
+
+A2UI was designed to address the specific challenges of interoperable,
+cross-platform, generative or template-based UI responses from agents.
+
+The project's core philosophies:
+
+* **Security first**: Running arbitrary code generated by an LLM may present a
+security risk. A2UI is a declarative data format, not executable
+code. Your client application maintains a "catalog" of trusted, pre-approved
+UI components (e.g., Card, Button, TextField), and the agent can only request
+to render components from that catalog. 
+* **LLM-friendly and incrementally updateable**: The UI is represented as a flat
+list of components with ID references which is easy for LLMs to generate
+incrementally, allowing for progressive rendering and a responsive user
+experience. An agent can efficiently make incremental changes to the UI based
+on new user requests as the conversation progresses.
+* **Framework-agnostic and portable**: A2UI separates the UI structure from
+the UI implementation. The agent sends a description of the component tree
+and its associated data model. Your client application is responsible for
+mapping these abstract descriptions to its native widgets—be it web components,
+Flutter widgets, React components, SwiftUI views or something else entirely.
+The same A2UI JSON payload from an agent can be rendered on multiple different
+clients built on top of different frameworks.
+* **Flexibility**: A2UI also features an open registry pattern that allows
+developers to map server-side types to custom client implementations, from
+native mobile widgets to React components. By registering a "Smart Wrapper,"
+you can connect any existing UI component—including secure iframe containers
+for legacy content—to A2UI's data binding and event system.  Crucially, this
+places security firmly in the developer's hands, enabling them to enforce
+strict sandboxing policies and "trust ladders" directly within their custom
+component logic rather than relying solely on the core system.
+
+## Use Cases
+
+Some of the use cases include:
+
+*   **Dynamic Data Collection:** An agent generates a bespoke form (date pickers,
+sliders, inputs) based on the specific context of a conversation (e.g.,
+booking a specialized reservation).
+*   **Remote Sub-Agents:** An orchestrator agent delegates a task to a
+remote specialized agent (e.g., a travel booking agent) which returns a
+UI payload to be rendered inside the main chat window.
+*   **Adaptive Workflows:** Enterprise agents that generate approval
+dashboards or data visualizations on the fly based on the user's query.
+
+## Architecture
+
+The A2UI flow disconnects the generation of UI from the execution of UI:
+
+1.  **Generation:** An Agent (using Gemini or another LLM) generates or uses
+a pre-generated `A2UI Response`, a JSON payload describing the composition
+of UI components and their properties.
+2.  **Transport:** This message is sent to the client application
+(via A2A, AG UI, etc.).
+3.  **Resolution:** The Client's **A2UI Renderer** parses the JSON.
+4.  **Rendering:** The Renderer maps the abstract components
+(e.g., `type: 'text-field'`) to the concrete implementation in the client's codebase.
+
+
+## Dependencies
+
+A2UI is designed to be a lightweight format, but it fits into a larger ecosystem:
+
+*   **Transports:** Compatible with **A2A Protocol** and **AG UI**.
+*   **LLMs:** Can be generated by any model capable of generating JSON output.
+*   **Host Frameworks:** Requires a host application built in a supported framework
+(currently: Web or Flutter).
+
+## Getting Started
+
+The best way to understand A2UI is to run the samples.
+
+### Prerequisites
+*   Node.js (for web clients)
+*   Python (for agent samples)
+*   A valid [Gemini API Key](https://aistudio.google.com/) is required for the samples.
+
+### Running the Restaurant Finder Demo
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/google/A2UI.git
+    cd A2UI
+    ```
+
+2.  **Set your API Key:**
+    ```bash
+    export GEMINI_API_KEY="your_gemini_api_key"
+    ```
+
+3.  **Run the Agent (Backend):**
+    ```bash
+    cd samples/agent/adk/restaurant_finder
+    uv run .
+    ```
+
+4.  **Run the Client (Frontend):**
+    Open a new terminal window:
+    ```bash
+    cd samples/client/lit/shell
+    npm install
+    npm run dev
+    ```
+
+For Flutter developers, check out the [GenUI SDK](https://github.com/flutter/genui),
+which uses A2UI under the hood.
+
+CopilotKit has a public [A2UI Widget Builder](https://go.copilotkit.ai/A2UI-widget-builder)
+to try out as well.
+
+
+## Roadmap
+
+We hope to work with the community on the following:
+
+*   **Spec Stabilization:** Moving towards a v1.0 specification.
+*   **More Renderers:** Adding official support for React, Jetpack Compose, iOS (SwiftUI), and more.
+*   **Additional Transports:** Support for REST and more.
+*   **Additional Agent Frameworks:** Genkit, LangGraph, and more.
+
+## Contribute
+
+A2UI is an **Apache 2.0** licensed project. We believe the future of UI is agentic,
+and we want to work with you to help build it.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.