[Docs] Add a Progressive, Standalone "Getting Started" Path

[devchas]

While many core A2UI concepts are explained across various existing guides, onboarding and getting started as a new developer remains a challenge. The current "Quick Start" section functions primarily as a monorepo demo launcher, guiding developers on how to run existing samples inside the framework's own codebase rather than demonstrating how to integrate the SDKs into an independent project.

The individual pieces of the puzzle exist across the documentation, but the developer onboarding experience can be made significantly better by organizing these resources into a single, cohesive path that mirrors a real-world developer journey. This proposal outlines the addition of a clear, step-by-step Getting Started Path split into two distinct phases (Agent and Client) designed to lower cognitive load and get developers up and running in their own projects.

Proposed Architecture & Content Map

Phase 1: Progressive Agent Development

Goal: Build an A2UI-compliant backend agent from scratch, adding capabilities incrementally.

• Overview Page: An introductory roadmap outlining what will be accomplished in this section, serving to prime developers for the setup ahead.
  • The Escape Hatch (Fast-Track): Include a prominent callout right here on the overview page: "Just want to evaluate the frontend? You can skip backend development for now. Run the pre-configured restaurant_finder sample agent with this command..." to give pure front-end developers an immediate path forward.
• 1.1 The Bare-Bones Agent:
  • Initialize a minimal agent using the foundations in the existing Agent Development Guide.
  • Crucial Addition: Explicitly document the local execution command so developers know how to expose their agent to a local client (a critical step currently omitted from the guide):
  • Shell

adk api_server --host 0.0.0.0 --port 10002 --allow_origins http://localhost:8080

• 1.2 Few-Shot Component Prompting: Introduce how to add static component examples to the agent's context so the LLM learns how to reliably structure valid UI component JSON payloads.
• 1.3 Handling User Actions & Tooling: Provide a short, practical code recipe showing how client-side UI actions and backend tools work together by directly linking to and contextualizing the lifecycle outlined in the Agent Processing documentation and the Actions Guide.
• 1.4 Registering a Custom Catalog: Define a custom structural schema registry on the agent side to handle unique component properties beyond basic default layout tags.

Phase 2: Standalone Client Setup

Goal: Integrate the A2UI client SDK into an independent application, process the message stream, and render components.

• Overview Page: An introductory roadmap outlining what will be accomplished in this section, detailing how the client application hooks into the agent backend and prepares to receive data.
• 2.1 Initializing the Client & Message Processing:
  • Establish initial client setup based on the information provided in the Client Setup Guide.
  • New Content Block: Bridge a major documentation gap by pulling out and documenting the vital transport-layer implementation details currently hidden deep in sample code, such as the Angular restaurant sample's server.ts and client.ts. Even if framework-specific, the documentation must provide explicit code snippets with short descriptions explaining how to configure a client application to listen to, ingest, and process raw A2UI message streams.
• 2.2 Applied Theming: A practical walkthrough of mapping design system tokens using the principles laid out in the Theming Guide.
• 2.3 Consuming Custom Components: An applied guide walking through how to add custom components from a custom catalog. This page will assume the developer has either completed Step 1.4 or is running a provided sample agent equipped with a custom catalog.

Structural Gaps Addressed

1. Refocuses on the Target Developer Journey: Acknowledge that the core pieces of information exist across pages like guides/agent-development/, guides/client-setup/, concepts/actions/, and guides/theming/. Gathering them into a progressive onboarding journey naturally uncovers hidden holes and reduces developer friction.
2. Improves Transport Configuration Clarity: Centralizing the client-side streaming event listeners and message processing loops directly within this guide makes it much easier for developers to connect the dots, reducing the need to look through disconnected directories inside /samples/.
3. Lowers Friction via Progressive Complexity: By breaking the agent phase into progressive milestones, developers can build momentum without being overwhelmed by advanced schema syntax, custom prompt builders, and tool-wrappers all at once.
4. Enhances Existing Content Discoverability: Linking this new path back to the existing literature contextualizes the foundational guides, validating that work while making it significantly more discoverable to developers in real-world contexts.

While there are other distinct critical developer journeys that can be mapped out and addressed over time, prioritizing this core onboarding path is the most critical next step for accelerating external adoption.

[ditman]

/cc @zeroasterisk, @vpm238