Reorganize docs to keep 0.8 and 0.9 separate.

docs: add mkdocs-redirects to requirements

Fixes CI build error by adding missing dependency `mkdocs-redirects`, which is used in `mkdocs.yaml` for URL redirection.

Author: gspencergoog

docs/index.md

@@ -27,9 +27,17 @@ A2UI enables AI agents to generate rich, interactive user interfaces that render
 > foster collaboration, gather feedback, and solicit contributions (e.g., on client renderers).
 > Expect changes.
 
+**Documentation Versions:**
+
+This site hosts documentation for:
+
+- **[v0.8 (Previous)](v0.8/quickstart.md)**: The previous stable version, available for reference.
+- **[v0.9 (Current)](v0.9/quickstart.md)**: The current specification.
+- **[v0.10 (Draft)](v0.10/specification/docs/v0.10-a2ui.md)**: The draft of the next specification.
+
 ## At a Glance
 
-A2UI is currently [v0.9](specification/v0.9-a2ui.md),
+A2UI is currently [v0.9](v0.9/specification/docs/v0.9-a2ui.md),
 Apache 2.0 licensed,
 created by Google with contributions from CopilotKit and the open source community,
 and is in active development [on GitHub](https://github.com/google/A2UI).
@@ -39,10 +47,10 @@ The problem A2UI solves is: **how can AI agents safely send rich UIs across trus
 Instead of text-only responses or risky code execution, A2UI lets agents send **declarative component descriptions** that clients render using their own native widgets. It's like having agents speak a universal UI language.
 
 In this repo you will find
-[A2UI specifications](specification/v0.9-a2ui.md)
+[A2UI specifications](v0.9/specification/docs/v0.9-a2ui.md)
 and implementations for
-[renderers](renderers.md) (eg: Angular, Flutter, etc.) on the client side,
-and [transports](transports.md) (eg: A2A, etc.) which communicate A2UI messages between agents and clients.
+[renderers](v0.9/renderers.md) (eg: Angular, Flutter, etc.) on the client side,
+and [transports](v0.9/transports.md) (eg: A2A, etc.) which communicate A2UI messages between agents and clients.
 
 <div class="grid cards" markdown>
 
@@ -76,37 +84,37 @@ and [transports](transports.md) (eg: A2A, etc.) which communicate A2UI messages
 
 <div class="grid cards" markdown>
 
-- :material-clock-fast:{ .lg .middle } **[Quickstart Guide](quickstart.md)**
+- :material-clock-fast:{ .lg .middle } **[Quickstart Guide](v0.9/quickstart.md)**
 
     ---
 
     Run the restaurant finder demo and see A2UI in action with Gemini-powered agents.
 
-    [:octicons-arrow-right-24: Get started](quickstart.md)
+    [:octicons-arrow-right-24: Get started](v0.9/quickstart.md)
 
-- :material-book-open-variant:{ .lg .middle } **[Core Concepts](concepts/overview.md)**
+- :material-book-open-variant:{ .lg .middle } **[Core Concepts](v0.9/concepts/overview.md)**
 
     ---
 
     Understand surfaces, components, data binding, and the adjacency list model.
 
-    [:octicons-arrow-right-24: Learn concepts](concepts/overview.md)
+    [:octicons-arrow-right-24: Learn concepts](v0.9/concepts/overview.md)
 
-- :material-code-braces:{ .lg .middle } **[Developer Guides](guides/client-setup.md)**
+- :material-code-braces:{ .lg .middle } **[Developer Guides](v0.9/guides/client-setup.md)**
 
     ---
 
     Integrate A2UI renderers into your app or build agents that generate UIs.
 
-    [:octicons-arrow-right-24: Start building](guides/client-setup.md)
+    [:octicons-arrow-right-24: Start building](v0.9/guides/client-setup.md)
 
-- :material-file-document:{ .lg .middle } **[Protocol Reference](specification/v0.9-a2ui.md)**
+- :material-file-document:{ .lg .middle } **[Protocol Reference](v0.9/specification/docs/v0.9-a2ui.md)**
 
     ---
 
     Dive into the complete technical specification and message types.
 
-    [:octicons-arrow-right-24: Read the spec](specification/v0.9-a2ui.md)
+    [:octicons-arrow-right-24: Read the spec](v0.9/specification/docs/v0.9-a2ui.md)
 
 </div>
 

docs/introduction/faq.md

@@ -0,0 +1,13 @@
+# Frequently Asked Questions
+
+## General
+
+### What is the difference between v0.8 and v0.9?
+**v0.8** is the previous stable version of the A2UI specification. It is preserved for reference for existing implementations.
+**v0.9** is the current version, introducing significant improvements such as the "Prompt-First" design, better streaming support, and decoupled architecture. We recommend all new projects start with v0.9.
+
+### Can I mix versions?
+No, A2UI versions are distinct. An agent speaking v0.9 should communicate with a client supporting v0.9. The protocol version is negotiated or specified in the message envelope.
+
+### Where can I find the v0.8 documentation?
+You can access the [v0.8 documentation](../v0.8/quickstart.md) via the navigation menu under "Specifications > v0.8" or by browsing the v0.8 section in the sidebar.

docs/introduction/how-to-use.md

@@ -24,7 +24,7 @@ npm install @a2ui/angular
 
 Connect to agent messages (SSE, WebSockets, or A2A) and customize styling to match your brand.
 
-**Next:** [Client Setup Guide](../guides/client-setup.md) | [Theming](../guides/theming.md)
+**Next:** [Client Setup Guide](../v0.9/guides/client-setup.md) | [Theming](../v0.9/guides/theming.md)
 
 ---
 
@@ -39,7 +39,7 @@ Create an agent that generates A2UI responses for any compatible client.
 
 Include the A2UI schema in your LLM prompts, generate JSONL messages, and stream to clients over SSE, WebSockets, or A2A.
 
-**Next:** [Agent Development Guide](../guides/agent-development.md)
+**Next:** [Agent Development Guide](../v0.9/guides/agent-development.md)
 
 ---
 

docs/introduction/where-is-it-used.md

@@ -134,16 +134,16 @@ The A2UI community is building exciting projects:
 
 ### Community Contributions
 
-Have you built something with A2UI? [Share it with the community!](../community.md)
+Have you built something with A2UI? [Share it with the community!](../v0.9/community.md)
 
 ---
 
 ## Next Steps
 
-- [Quickstart Guide](../quickstart.md) - Try the demo
-- [Agent Development](../guides/agent-development.md) - Build an agent
-- [Client Setup](../guides/client-setup.md) - Integrate a renderer
-- [Community](../community.md) - Join the community
+- [Quickstart Guide](../v0.9/quickstart.md) - Try the demo
+- [Agent Development](../v0.9/guides/agent-development.md) - Build an agent
+- [Client Setup](../v0.9/guides/client-setup.md) - Integrate a renderer
+- [Community](../v0.9/community.md) - Join the community
 
 ---
 

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

@@ -16,7 +16,7 @@ Build multi-agent platforms, enterprise assistants, or cross-platform apps where
 - Cross-platform: web, mobile, desktop
 - Interoperable: open source, same spec with multiple renderers
 
-**Get started:** [Client Setup](../guides/client-setup.md) | [Theming](../guides/theming.md) | [Custom Components](../guides/custom-components.md)
+**Get started:** [Client Setup](../v0.9/guides/client-setup.md) | [Theming](../v0.9/guides/theming.md) | [Custom Components](../v0.9/guides/custom-components.md)
 
 ### 2. Agent Developers (Backend/AI)
 
@@ -30,7 +30,7 @@ Build agents that generate forms, dashboards, and interactive workflows.
 - Portable: one agent response works across all A2UI clients
 - Streamable: progressive rendering as you generate
 
-**Get started:** [Agent Development](../guides/agent-development.md)
+**Get started:** [Agent Development](../v0.9/guides/agent-development.md)
 
 ### 3. Platform Builders (SDK Creators)
 
@@ -46,7 +46,7 @@ Do you ship your agent into other apps you don't necessarily control?
 - Extensible: custom component catalogs
 - Open source (Apache 2.0)
 
-**Get started:** [Community](../community.md) | [Roadmap](../roadmap.md)
+**Get started:** [Community](../v0.9/community.md) | [Roadmap](../v0.9/roadmap.md)
 
 ---
 

docs/scripts/README.md

@@ -2,20 +2,18 @@
 
 This directory contains utility scripts to prepare our documentation for the **MkDocs** build process.
 
-## Purpose
+## Alert/Admonition Conversion (`convert_docs.py`)
 
-To ensure a great reading experience both on GitHub and the hosted site, we use **GitHub-flavored Markdown** as our primary source of truth. This script transforms GitHub's native syntax into **MkDocs-compatible syntax** (specifically for the `pymdown-extensions`) during the build pipeline.
+### Purpose
 
-## Supported Conversions (Uni-directional)
+To ensure a great reading experience both on GitHub and the hosted site, we use **GitHub-flavored Markdown** as our primary source of truth. This script transforms GitHub's native syntax into **MkDocs-compatible syntax** (specifically for the `pymdown-extensions`) during the build pipeline.
 
 The script performs a uni-directional transformation: **GitHub Markdown → MkDocs Syntax**.
 
-### Alert/Admonition Conversion
-
 - GitHub uses a blockquote-based syntax for alerts.
 - MkDocs requires the `!!!` or `???` syntax to render colored callout boxes.
 
-## Running the Conversion
+### Running the Conversion
 
 The conversion is run as part of the build pipeline. No additional steps are required. If you need to run the conversion manually, you can run the `convert_docs.py` script in the repository root.
 
@@ -37,3 +35,35 @@ python docs/scripts/convert_docs.py
   !!! warning "Attention"
       This is an alert.
   ```
+
+## Specification Preparation (`prepare_docs.py`)
+
+This script prepares the raw specification files for the build.
+
+### Purpose
+
+- **Copies Source Files**: Moves specs from `specification/v0_X` to `docs/v0.X/specification`.
+- **Flattens JSON**: Moves JSON files to the root of the versioned spec directory.
+- **Rewrites Links**: Adjusts internal links to work in the new location.
+
+### Usage
+
+```bash
+python docs/scripts/prepare_docs.py
+```
+
+## Wrapper Migration (`migrate_wrappers.py`)
+
+This script manages the "wrapper" files that include the raw specification content.
+
+### Purpose
+
+- **Generates Wrappers**: Reads templates from `docs/wrappers_source/`.
+- **Updates Includes**: Rewrites `--8<--` includes to point to the `prepare_docs.py` output.
+- **Fixes Cross-Version Links**: Ensures links between different versions (e.g. v0.9 -> v0.8) are correct.
+
+### Usage
+
+```bash
+python docs/scripts/migrate_wrappers.py
+```

docs/scripts/migrate_wrappers.py

@@ -0,0 +1,91 @@
+
+import os
+import shutil
+import re
+
+"""
+Generates and migrates "wrapper" Markdown files for the A2UI specification documentation.
+
+This script manages the documentation pages that wrap the raw specification content:
+1.  **Generates Wrappers**: Reads template/wrapper files from `docs/wrappers_source/`. These files contain metadata headers and include directives (e.g., `--8<--`) that pull in the raw specification content prepared by `prepare_docs.py`.
+2.  **Version Filtering**: Identifies which version each wrapper corresponds to based on its filename (e.g., `v0.9-a2ui.md` belongs to `v0.9`).
+3.  **Updates Include Paths**: Dynamically rewrites the include directives to point to the correct location of the raw specification files in the build directory (e.g., changing `docs/specification/v0_9/...` to `docs/v0.9/specification/...`).
+4.  **Fixes Cross-Version Links**: Rewrites links within the wrapper files to ensure they point to the correct versioned documentation pages. For example, it converts links like `(v0.8-a2ui.md)` to relative paths like `(../../../v0.8/specification/docs/v0.8-a2ui.md)` when linking across versions.
+5.  **Deploys to Documentation**: Places the processed wrapper files into the appropriate versioned specification directory (e.g., `docs/v0.9/specification/docs/`).
+
+Usage:
+    Run this script after `prepare_docs.py` and before `mkdocs build`.
+    `python3 docs/scripts/migrate_wrappers.py`
+"""
+
+def migrate_wrappers(repo_root):
+    source_dir = os.path.join(repo_root, 'docs', 'wrappers_source')
+
+    if not os.path.exists(source_dir):
+        print(f"Source dir {source_dir} does not exist.")
+        return
+
+    files = [f for f in os.listdir(source_dir) if f.endswith('.md')]
+
+    for filename in files:
+        version = None
+        if filename.startswith('v0.8'):
+            version = 'v0.8'
+        elif filename.startswith('v0.9'):
+            version = 'v0.9'
+        elif filename.startswith('v0.10'):
+            version = 'v0.10'
+
+        if not version:
+            continue
+
+        dest_dir = os.path.join(repo_root, 'docs', version, 'specification', 'docs')
+        if not os.path.exists(dest_dir):
+            os.makedirs(dest_dir, exist_ok=True)
+
+        source_path = os.path.join(source_dir, filename)
+        dest_path = os.path.join(dest_dir, filename)
+
+        with open(source_path, 'r') as f:
+            content = f.read()
+
+        # Update include paths
+        # Old: "docs/specification/v0_8/docs/..."
+        # New: "docs/v0.8/specification/docs/..."
+        # Note the underscore to dot change for versions in the path if needed
+        # The snippet path needs to match where the file ACTUALLY is relative to mkdocs root (repo root usually)
+
+        # Regex for includes
+        # --8<-- "docs/specification/v0_([0-9]+)/
+        # Replace with docs/v0.\1/specification/
+        content = re.sub(r'docs/specification/v0_(\d+)/', r'docs/v0.\1/specification/', content)
+
+        # Update links
+        # We need to fix links to other versions.
+        # Links usually look like: (v0.8-a2ui.md)
+
+        def link_replacer(match):
+            link_target = match.group(1) # e.g. v0.8-a2ui.md
+            if link_target.startswith(version):
+                return f"({link_target})" # Same version, same dir
+
+            # Different version
+            target_ver = link_target.split('-')[0] # v0.8
+            return f"(../../../{target_ver}/specification/docs/{link_target})"
+
+        content = re.sub(r'\((v0\.\d+-[^)]+\.md)\)', link_replacer, content)
+
+        with open(dest_path, 'w') as f:
+            f.write(content)
+
+        print(f"Migrated {filename} into {dest_path}")
+        # os.remove(source_path) # verify first
+
+
+def main():
+    repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
+    migrate_wrappers(repo_root)
+
+
+if __name__ == '__main__':
+    main()