supervaize · alain-sv · May 17, 2026 · May 15, 2026 · May 15, 2026 · May 15, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -5,6 +5,7 @@ This is the canonical agent guide for the Supervaizer controller repo. Supervaiz
 ## Working Rules
 
 - Prefer simple, typed Python changes that match existing FastAPI/Pydantic patterns.
+- **No guessing / no implicit fallbacks:** when protocol versions, workspace identity, action/resource contracts, authentication, or transport configuration are missing or inconsistent, fail with a clear error that names the missing configuration. Do not infer another context, broaden scope, or silently fall back.
 - Use `just` recipes from this repo for local commands.
 - Use `uv` for Python environment and package operations.
 - Add or update targeted tests for changed behavior.
@@ -40,6 +41,8 @@ Reference specific personas when requesting work:
 - In `9agents/agent_interviewer`, empty `MANAGE_ALLOWED_IPS` still requires `MANAGE_AUTH_TOKEN` when that env is set; supervaizer’s admin IP middleware has no equivalent token fallback when the allowlist is empty.
 - CI (`python-package` workflow): the pre-commit job checks **Ruff** formatting (`ruff format --check`) and **YAML** in `.github/workflows` via `yamllint` (not Black).
 - In the matrix **build** job, `astral-sh/setup-uv` sets `cache-suffix: py-${{ matrix.python-version }}` so parallel Python versions do not race on the same GitHub Actions cache reservation.
+- `@singleton` (from `supervaizer.common`) replaces the decorated class name with a function at import time; modules that annotate with that class in unions (e.g. `StorageManager | None` in `storage.py`) need `from __future__ import annotations` or class-body evaluation raises `TypeError`.
+- `UTC` lives on the `datetime` module (`from datetime import UTC`), not on `datetime.datetime`; use `datetime.now(UTC)`, not `datetime.now(datetime.UTC)` (the latter raises `AttributeError` at runtime).
 
 ## Security and Supply-Chain Rules
 

diff --git a/README.md b/README.md
@@ -1,5 +1,9 @@
 # SUPERVAIZER
 
+
+> **Created:** 2024-12-28
+> **Updated:** 2026-05-16
+
 [Operate AI Agents with confidence]
 
 A Python toolkit for building, managing, and connecting AI agents with full [Agent-to-Agent (A2A)](https://a2a-protocol.org/) protocol support.
@@ -23,6 +27,7 @@ A Python toolkit for building, managing, and connecting AI agents with full [Age
     - [What's next?](#whats-next)
   - [Features](#features)
   - [Protocol Support](#protocol-support)
+    - [Supervaizer v2](#supervaizer-v2)
   - [Cloud Deployment](#cloud-deployment)
     - [Quick Start](#quick-start-1)
     - [Deployment Commands](#deployment-commands)
@@ -45,6 +50,7 @@ With comprehensive support for the A2A protocol specification, SUPERVAIZER allow
 
 - Enhance the capabilities of your agents, making them automatically discoverable by other A2A compatible systems
 - Expose standardized agent capabilities through agent cards
+- Expose typed Supervaizer v2 surfaces and actions so Studio can operate the agent through generic UI primitives
 - Monitor agent health and status through dedicated endpoints
 - Connect your agents to the growing ecosystem of A2A-compatible tools
 
@@ -147,6 +153,7 @@ export SUPERVAIZE_MAX_HTTP_RETRIES=3  # Will attempt up to 4 times total (1 orig
 
 - Add more **custom methods** (`chat`, `custom`) to extend control
 - Turn on **A2A** discovery for interoperability
+- Add a **Supervaizer v2 registration** when Studio should manage resources, datasets, job start surfaces, HITL steps, and artifact rendering through the generic SDK contract
 - Hook your controller into Supervaize to **monitor, audit, and operate** the agent
 
 For detailed instructions on customizing your controller, see the [Controller Setup Guide](https://doc.supervaize.com/docs/supervaizer-controller/controller-setup)
@@ -159,6 +166,7 @@ For detailed instructions on customizing your controller, see the [Controller Se
 - **Custom Routes**: Agents can mount their own FastAPI routers under `/api/agents/{slug}/...` for tool endpoints, webhooks, or custom APIs
 - **Scheduled Steps**: Defer step execution to a future time with automatic background polling and workbench controls (execute now, cancel, reschedule)
 - **Human-in-the-Loop (HITL)**: Form-based and dialog-based interactive content review with chat interface
+- **Supervaizer v2 SDK contract**: Typed resources, datasets, A2UI surfaces, actions, job snapshots, case lanes, steps, awaiting state, and artifact references for generic Studio operation
 - **Agent Workbench**: Built-in testing interface with real-time monitoring, job control, HITL forms, and live console
 - **🚀 Cloud Deployment**: Automated deployment to GCP Cloud Run, AWS App Runner, and DigitalOcean App Platform
 - **A2A Protocol Support**: Full integration with the Agent-to-Agent protocol for standardized agent discovery and interaction
@@ -167,7 +175,18 @@ For detailed instructions on customizing your controller, see the [Controller Se
 
 ## Protocol Support
 
-SUPERVAIZER provides comprehensive support for the A2A agent communication protocol. See [Protocol Documentation](docs/PROTOCOLS.md) for complete details.
+SUPERVAIZER provides comprehensive support for the A2A agent communication protocol. See [Protocol Documentation](docs/2025_08_PROTOCOLS.md) for complete details.
+
+### Supervaizer v2
+
+Supervaizer v2 is the Studio operation contract layered on top of A2A discovery/transport and A2UI surface payloads. It lets an agent declare:
+
+- generic business resources and datasets Studio can list, edit, import, and query
+- agent-owned A2UI surfaces such as `job.start`, `case.step.awaiting`, `case.step.detail`, `mission.analytics`, and mounted resource views
+- typed actions such as `job.start`, `job.stop`, `job.sync`, `step.awaiting.submit`, `resource.<id>.<operation>`, and `dataset.<id>.query`
+- convergent job state snapshots made of Jobs, Cases, Steps, awaiting forms, and artifact references
+
+Start with [Supervaizer v2 Concepts](docs/2026_05_SUPERVAIZER_v2.md) for the new model and [Protocol Documentation](docs/2025_08_PROTOCOLS.md) for the A2A/A2UI transport layer.
 
 ## Cloud Deployment
 
@@ -211,23 +230,23 @@ supervaizer deploy up --platform do-app-platform --region nyc
 
 ### Documentation
 
-- [RFC-001: Cloud Deployment CLI](docs/rfc/001-cloud-deployment-cli.md) - Complete specification
-- [Local Testing Guide](docs/LOCAL_TESTING.md) - Docker testing documentation
+- [RFC-001: Cloud Deployment CLI](docs/rfc/2025_10_001-cloud-deployment-cli.md) - Complete specification
+- [Local Testing Guide](docs/2025_10_LOCAL_TESTING.md) - Docker testing documentation
 
 ## Using the CLI
 
-SUPERVAIZER includes a command-line interface to simplify setup and operation. See [CLI Documentation](docs/CLI.md) for complete details.
+SUPERVAIZER includes a command-line interface to simplify setup and operation. See [CLI Documentation](docs/2025_08_CLI.md) for complete details.
 
-Also, check the list of [Environment variables](CLI.md#environment-variables).
+Also, check the list of [Environment variables](docs/2025_08_CLI.md#environment-variables).
 
 ## API Documentation & User Interfaces
 
-SUPERVAIZER provides multiple ways to interact with and explore the API. See [REST API Documentation](docs/REST_API.md) for complete details.
+SUPERVAIZER provides multiple ways to interact with and explore the API. See [REST API Documentation](docs/2025_08_REST_API.md) for complete details.
 
 ### Admin Interface (`/admin`)
 
 A comprehensive web-based admin interface for managing your SUPERVAIZER instance
-See [Admin documentation](docs/ADMIN_README.md)
+See [Admin documentation](docs/2025_08_ADMIN_README.md)
 
 #### Quick Start
 

diff --git a/docs/API_REFERENCE.md → docs/2025_04_API_REFERENCE.md b/docs/API_REFERENCE.md → docs/2025_04_API_REFERENCE.md
@@ -1,5 +1,9 @@
 # SUPERVAIZER API Reference
 
+
+> **Created:** 2025-04-15
+> **Updated:** 2025-08-05
+
 This document provides details about the core components and APIs of SUPERVAIZER.
 
 ## Core Components

diff --git a/docs/ADMIN_README.md → docs/2025_08_ADMIN_README.md b/docs/ADMIN_README.md → docs/2025_08_ADMIN_README.md
@@ -1,5 +1,9 @@
 # Supervaizer Admin Interface
 
+
+> **Created:** 2025-08-05
+> **Updated:** 2026-03-23
+
 A lightweight web-based admin interface for managing WorkflowEntity objects (Jobs and Cases) using FastAPI, TinyDB, and HTMX.
 
 ## Features

diff --git a/docs/CLI.md → docs/2025_08_CLI.md b/docs/CLI.md → docs/2025_08_CLI.md
@@ -1,5 +1,9 @@
 # SUPERVAIZER CLI
 
+
+> **Created:** 2025-08-06
+> **Updated:** 2026-03-16
+
 SUPERVAIZER includes a command-line interface to simplify setup, operation, and deployment:
 
 ```bash
@@ -234,8 +238,8 @@ supervaizer deploy clean --verbose
 
 For detailed deployment documentation, see:
 
-- [RFC-001: Cloud Deployment CLI](rfc/001-cloud-deployment-cli.md) - Complete specification
-- [Local Testing Guide](LOCAL_TESTING.md) - Docker testing documentation
+- [RFC-001: Cloud Deployment CLI](rfc/2025_10_001-cloud-deployment-cli.md) - Complete specification
+- [Local Testing Guide](2025_10_LOCAL_TESTING.md) - Docker testing documentation
 
 ## Environment Variables
 

diff --git a/docs/PARAMETER_VALIDATION_IMPLEMENTATION.md → ...08_PARAMETER_VALIDATION_IMPLEMENTATION.md b/docs/PARAMETER_VALIDATION_IMPLEMENTATION.md → ...08_PARAMETER_VALIDATION_IMPLEMENTATION.md
@@ -1,5 +1,9 @@
 # Parameter Validation Guide
 
+
+> **Created:** 2025-08-12
+> **Updated:** 2025-08-12
+
 This document provides instructions for implementing parameter validation in the Supervaize web application to leverage the new parameter validation system.
 
 ## Overview

diff --git a/docs/PERSISTENCE.md → docs/2025_08_PERSISTENCE.md b/docs/PERSISTENCE.md → docs/2025_08_PERSISTENCE.md
@@ -1,5 +1,9 @@
 # TinyDB Persistence Layer
 
+
+> **Created:** 2025-08-05
+> **Updated:** 2026-02-04
+
 The Supervaizer TinyDB persistence layer provides thread-safe, local storage for WorkflowEntity instances (Jobs, Cases, Missions) across sessions and processes.
 
 ## Features

diff --git a/docs/2025_08_PROTOCOLS.md b/docs/2025_08_PROTOCOLS.md
@@ -0,0 +1,169 @@
+# Protocol Support
+
+> **Created:** 2025-08-06
+> **Updated:** 2026-05-16
+
+SUPERVAIZER uses several protocol layers. They are related, but they do different jobs:
+
+| Layer              | Role in Supervaizer                                                                                                                  | Current status                                                                                           |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| **A2A**            | Transport and discovery: Agent Cards, controller URL, JSON-RPC method calls, and event streams.                                      | Implemented for discovery, `supervaizer/action.invoke`, `supervaizer/surface.load`, and SSE observation. |
+| **A2UI**           | Surface payloads: declarative UI documents for Studio-rendered forms, dashboards, detail views, and mounted resource workflows.      | Implemented as the payload format returned by `supervaizer/surface.load`.                                |
+| **AG-UI**          | Live agent-user runtime: bidirectional event flow for streaming messages, tool calls, state updates, and interactive agent sessions. | Not part of the MVP runtime; v2 registration only carries optional `ag_ui_version` metadata.             |
+| **Supervaizer v2** | Application semantics: Jobs, Cases, Steps, Resources, Datasets, Surfaces, Actions, Artifacts, and sync/offline policy.               | Implemented as the Studio operation contract layered on A2A and A2UI.                                    |
+
+The detailed Supervaizer v2 model is documented in [2026_05_SUPERVAIZER_v2.md](2026_05_SUPERVAIZER_v2.md).
+
+## Agent-to-Agent (A2A) Protocol
+
+### Overview
+
+SUPERVAIZER implements the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/) for standardized agent discovery and interaction.
+
+### Implemented A2A Features
+
+- **Agent Discovery**: `/.well-known/agents.json` endpoint for listing all available agents
+  Note: the current version of the A2A protocol does not support yet multiple agents.
+- **Agent Cards**: Detailed agent information available at `/.well-known/agents/v{version}/{agent_slug}_agent.json`
+- **Health Monitoring**: Real-time system and agent health data at `/.well-known/health`
+- **Versioned Endpoints**: Support for agent versioning with backward compatibility
+- **OpenAPI Integration**: Direct links to OpenAPI specifications and documentation
+- **Version Information**: Comprehensive version tracking with changelog access
+- **JSON-RPC Controller Endpoint**: `/a2a` supports Supervaizer v2 methods including `supervaizer/action.invoke` and `supervaizer/surface.load`
+- **Server-Sent Events**: `/a2a/events` streams Supervaizer v2 action effects for observers that need a live feed
+
+### Supervaizer v2 Agent Card Extension
+
+When an agent declares `supervaizer_v2_registration`, its A2A Agent Card includes a `supervaizer.v2` extension. Studio reads this extension to validate protocol compatibility and discover:
+
+- pinned protocol versions: `supervaizer_contract_version`, `a2a_version`, `a2ui_version`, optional `ag_ui_version`, and agent-specific `a2ui_catalog_version`
+- controller URLs and transport support
+- supported surfaces and actions
+- case lanes and artifact types
+- resource and dataset contracts
+- job policy, including `job.sync` support and offline behavior
+
+This extension does **not** replace the existing Studio server-registration trust model. Studio registration still owns server identity, public key exchange, and encrypted payload handling. The A2A Agent Card advertises the v2 operational contract after the controller is known.
+
+### Supervaizer v2 JSON-RPC Methods
+
+Supervaizer v2 currently exposes two A2A JSON-RPC methods:
+
+| Method                      | Purpose                                                                                                                                              |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `supervaizer/surface.load`  | Load an agent-owned A2UI document for a known surface such as `job.start`, `case.step.awaiting`, or `mission.analytics`.                             |
+| `supervaizer/action.invoke` | Invoke a typed agent action such as `job.start`, `job.sync`, `step.awaiting.submit`, `resource.contacts.create`, or `dataset.session_metrics.query`. |
+
+Both methods are scoped by `agent_slug`. In multi-agent controllers, handlers must be registered for the correct agent slug.
+
+### Transport Status
+
+The current MVP advertises:
+
+- `json_rpc: true`
+- `sse: true`
+- `push_notifications: false`
+
+A2A push notifications are intentionally not advertised until they are implemented. External A2A interop flags, such as inbound tasks and outbound delegation, default to `false` and should be enabled only when a controller actually implements those flows.
+
+### A2UI Version Pinning
+
+Supervaizer v2 registrations include a frozen A2UI protocol version and an agent-owned A2UI catalog version. This is separate from the Python package version:
+
+- `SUPERVAIZER_V2_CONTRACT_VERSION` identifies the Supervaizer v2 semantic contract.
+- `SUPERVAIZER_V2_A2A_VERSION` identifies the supported A2A protocol version.
+- `SUPERVAIZER_V2_A2UI_VERSION` identifies the supported A2UI payload version.
+- `a2ui_catalog_version` identifies the agent's own surface-document catalog.
+
+Studio should reject incompatible protocol versions explicitly instead of attempting best-effort rendering.
+
+## Agent-to-User Interface (A2UI) Protocol
+
+SUPERVAIZER uses the [A2UI protocol](https://a2ui.org/) for agent-driven interface documents. A2UI is a declarative UI protocol: agents return structured component descriptions, and clients render those descriptions with their own native widgets instead of executing arbitrary agent-provided code.
+
+Useful source links:
+
+- [A2UI home](https://a2ui.org/)
+- [What is A2UI?](https://a2ui.org/introduction/what-is-a2ui/)
+- [A2UI v0.8 specification](https://a2ui.org/specification/v0.8-a2ui/)
+- [A2UI v0.9 specification](https://a2ui.org/specification/v0.9-a2ui/)
+
+In Supervaizer v2, A2UI is used for surface payloads:
+
+- `job.start` forms
+- `case.step.awaiting` HITL forms or review UIs
+- `case.step.detail` rich step/artifact detail views
+- `mission.analytics` dashboards
+- `mission.agent.overview` pages
+- mounted resource views such as prompt editors, scenario builders, or contact import flows
+
+SUPERVAIZER does not render A2UI. The controller transports A2UI documents through `supervaizer/surface.load`; Studio validates the declared `a2ui_version` and renders the document.
+
+## Agent-User Interaction (AG-UI) Protocol
+
+AG-UI is the [Agent-User Interaction Protocol](https://docs.ag-ui.com/introduction). It is an event-based protocol for connecting agent backends to user-facing applications when the interaction is live, streaming, and bidirectional.
+
+Useful source links:
+
+- [AG-UI documentation](https://docs.ag-ui.com/introduction)
+- [AG-UI core architecture](https://docs.ag-ui.com/concepts/architecture)
+- [AG-UI agents concept](https://docs.ag-ui.com/concepts/agents)
+- [AG-UI GitHub repository](https://github.com/ag-ui-protocol/ag-ui)
+
+AG-UI is a good fit for:
+
+- streaming assistant messages and partial outputs
+- exposing tool calls and tool results while they happen
+- synchronizing live agent state into a frontend
+- collaborative chat-style workflows
+- interrupt, approval, or live human-in-the-loop interactions
+
+In the Supervaizer v2 MVP, AG-UI is **not** the runtime used for Studio job management. Studio currently operates agents through A2A JSON-RPC actions, A2UI surface documents, and `job.sync` snapshots. The v2 registration has an optional `ag_ui_version` field so an agent can later advertise a compatible AG-UI runtime without changing the rest of the v2 contract.
+
+The intended division is:
+
+| Need                                                             | Use            |
+| ---------------------------------------------------------------- | -------------- |
+| Discover an agent and call controller methods                    | A2A            |
+| Render a stable Studio form, dashboard, detail view, or workflow | A2UI           |
+| Run a live streaming agent-user session                          | AG-UI          |
+| Persist and reconcile Studio operational state                   | Supervaizer v2 |
+
+### A2A Examples
+
+```bash
+# Discovering Agents
+curl https://your-server/.well-known/agents.json
+
+# Agent card
+curl https://your-server/.well-known/agents/v1.0.0/myagent_agent.json
+```
+
+Full documentation of A2A endpoints can be found at [local A2A](http://127.0.0.1:8001/docs#/Protocol%20A2A)
+
+### Future A2A Enhancements
+
+- **Webhooks**: Event subscription for real-time updates
+- **Rich Authentication**: OAuth2 and API key options with scope control
+- **Tool Streaming**: Support for streaming responses in long-running operations
+- **Extended Metadata**: Licensing, pricing, and usage limit information
+- **Localization**: Multi-language support for agent interfaces
+- **A2A Push Notifications**: push delivery for environments that need callback delivery instead of JSON-RPC polling/SSE observation
+- **AG-UI Runtime Integration**: optional bidirectional streaming UI runtime for live agent interactions; current v2 registrations only carry `ag_ui_version` metadata
+
+## Enabling Protocol Support
+
+A2A endpoints are enabled by default. You can control protocol support when creating your server:
+
+```python
+server = Server(
+    agents=[agent],
+    a2a_endpoints=True,  # Enable A2A protocol support (default: True)
+)
+```
+
+## Protocol Evolution
+
+The A2A protocol has evolved to incorporate features from multiple agent communication standards, including the former Agent Communication Protocol (ACP). This unified approach provides a comprehensive standard for agent interoperability across different systems and platforms.
+
+For the latest protocol specifications and updates, visit [a2a-protocol.org](https://a2a-protocol.org/).
diff --git a/docs/REST_API.md → docs/2025_08_REST_API.md b/docs/REST_API.md → docs/2025_08_REST_API.md
@@ -1,5 +1,9 @@
 # REST API Documentation
 
+
+> **Created:** 2025-08-06
+> **Updated:** 2025-08-06
+
 SUPERVAIZER provides multiple ways to interact with and explore the API:
 
 ## Interactive REST API Documentation

diff --git a/docs/LOCAL_TESTING.md → docs/2025_10_LOCAL_TESTING.md b/docs/LOCAL_TESTING.md → docs/2025_10_LOCAL_TESTING.md
@@ -1,5 +1,9 @@
 # Local Docker Testing
 
+
+> **Created:** 2025-10-07
+> **Updated:** 2026-01-29
+
 This document describes how to test Supervaizer deployments locally using Docker before deploying to cloud platforms.
 
 ## Overview