docs: rewrite README with hero framing, badges, architecture diagram, and cross-repo links (AG-01 AG-04 AG-05)

Author: OgeonX-Ai

README.md

@@ -1,256 +1,62 @@
-# Microsoft Agent Framework Starter
+# autogen
 
-This repo now runs as a Microsoft Agent Framework starter instead of the previous AutoGen-first setup.
+[![CI](https://github.com/Coding-Autopilot-System/autogen/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Coding-Autopilot-System/autogen/actions/workflows/ci.yml)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue)](https://www.python.org/)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-It is configured for:
+Part of the [Coding-Autopilot-System](https://github.com/Coding-Autopilot-System) ecosystem:
+[gsd-orchestrator](https://github.com/Coding-Autopilot-System/gsd-orchestrator) | [Promptimprover](https://github.com/Coding-Autopilot-System/Promptimprover)
 
-- Microsoft Agent Framework Python SDK
-- Operator Workbench as the primary local product UI
-- Microsoft DevUI for local interactive testing
-- Gemini API through Google's OpenAI-compatible endpoint
-- Gemini CLI fallback when the Gemini API returns quota errors
-- local repo inspection tools so the agent can reason over files in this repo
-- human approval before the agent treats a proposed action as approved
+autogen is a Python multi-agent orchestration runtime built on Microsoft Agent Framework — combining a Gemini/Claude provider fallback chain, AG-UI observability, and a local operator workbench for end-to-end autonomous engineering workflows.
 
-The current entrypoint is [main.py](/C:/repo/autogen/main.py), which now dispatches to the MAF CLI in [maf_starter/cli.py](/C:/repo/autogen/maf_starter/cli.py).
+## Features
 
-## What Is Included
+- **Provider fallback chain** — Gemini API (primary) -> Anthropic API -> local CLI fallback; routing policy classifies prompt complexity and selects provider automatically
+- **Multi-agent team orchestration** — sequential planner->researcher->implementer->reviewer chain with FileCheckpointStorage for resumable runs
+- **Bounded repo tools** — read/list/search/write with enforced scope limits; agents cannot access paths outside the configured repo root
+- **AG-UI observability** — DevUI-discoverable workflows expose run state, specialist handoffs, and pause/approval events
+- **Human-in-the-loop approvals** — approval policy gates destructive writes; operators review before execution proceeds
 
-- `entities/repo_copilot`
-  A repo-aware Gemini agent discovered by DevUI.
+## Architecture
 
-- `entities/repo_copilot_auto`
-  Auto-routing repo assistant with ordered API and CLI fallback.
-
-- `entities/repo_copilot_pro`
-- `entities/repo_copilot_flash`
-- `entities/repo_copilot_flash_lite`
-  Model-pinned assistants so the DevUI entity dropdown acts like a model selector.
-
-- `entities/repo_copilot_workflow`
-  A checkpointed workflow wrapper around the same agent.
-
-- `entities/repo_team`
-  A true multi-agent sequential workflow: planner -> researcher -> implementer -> reviewer, with request-info pauses.
-
-- `maf_starter/tools.py`
-  Safe local tools for:
-  - repo overview
-  - file listing
-  - file reading
-  - text search
-  - human approval requests
-
-- `maf_starter/cli.py`
-  Local commands for:
-  - config checks
-  - smoke tests
-  - Gemini model probing
-  - launching DevUI
-
-## Quick Start
-
-### 1. Create and activate a virtual environment
-
-```powershell
-python -m venv .venv
-.\.venv\Scripts\Activate.ps1
-```
-
-### 2. Install dependencies
-
-```powershell
-python -m pip install -U pip
-python -m pip install -r requirements.txt
-```
-
-### 3. Copy the env template
-
-```powershell
-Copy-Item .env.example .env
-```
-
-Then fill in `GEMINI_API_KEY`.
-
-### 4. Check configuration
-
-```powershell
-python main.py doctor
-```
-
-### 5. Run a smoke test
-
-```powershell
-python main.py smoke --message "Reply with exactly READY"
-```
-
-### 6. Probe Gemini models
-
-This is useful if you want to see which Gemini models work with your current key/project before picking a default.
-
-```powershell
-python main.py probe-models
-```
-
-### 7. Launch Operator Workbench
-
-```powershell
-python -m uvicorn autogen_dashboard.app:create_app --factory --host 127.0.0.1 --port 8000
-```
-
-Then open:
-
-- `http://127.0.0.1:8000`
-
-The Operator Workbench is the polished local UI for daily use. The active run workspace is organized into:
-
-- `Overview`
-- `Timeline`
-- `Agents`
-- `Routing`
-- `Artifacts`
-
-Operator Workbench manual spot checks:
-
-- confirm human, manager, specialist, approval, and event messages are visually distinct at a glance
-- confirm the active route and active stage strips stay visible above the transcript
-- confirm Timeline shows approvals, route attempts, validation steps, and stage changes without reading raw logs
-- confirm Artifacts shows changed files, diff artifacts, validation results, and saved stage outputs
-- confirm the selected run stays visually dominant and the create-run panel becomes secondary once a run is active
-- confirm the rail and workspace stack cleanly on narrower laptop widths
-
-### 8. Launch DevUI
-
-```powershell
-python main.py devui --host 127.0.0.1 --port 8080 --no-open
-```
-
-Then open:
-
-- `http://127.0.0.1:8080`
-
-DevUI will discover the entities under [entities](/C:/repo/autogen/entities).
-
-On Windows, the easiest way to keep the server alive is:
-
-```powershell
-.\start_devui.ps1
+```mermaid
+flowchart LR
+    Op["Operator\n(DevUI / Workbench)"] -->|"prompt"| MAF["autogen\n(MAF Runtime)"]
+    MAF --> Gemini["Gemini API\n(primary)"]
+    MAF --> Anthropic["Anthropic API\n(fallback)"]
+    MAF --> CLI["Local CLIs\n(gemini-cli / claude)"]
+    MAF --> Entities["Entities\n(repo_team, copilots)"]
+    MAF --> Tools["Repo Tools\n(read / write / search)"]
+    MAF --> Checkpoints["Checkpoints\n(FileCheckpointStorage)"]
+    Entities --> Out["Run Output\n+ Artifacts"]
+    Tools --> Out
+    Checkpoints --> Out
 ```
 
-That opens a dedicated PowerShell window and keeps DevUI running there.
-
-To stop it later:
+## Quickstart
 
-```powershell
-.\stop_devui.ps1
+```bash
+git clone https://github.com/Coding-Autopilot-System/autogen.git
+cd autogen
+python -m venv .venv
+# Windows: .\.venv\Scripts\Activate.ps1
+# macOS/Linux: source .venv/bin/activate
+pip install agent-framework python-dotenv
 ```
 
-Runtime logs are written to `.maf-devui.out.log` and `.maf-devui.err.log`.
-
-## Commands
-
-- `python main.py doctor`
-  Prints the effective MAF config without exposing the API key.
-
-- `python main.py smoke --message "..."`
-  Runs the repo copilot once through Agent Framework and prints the response.
-
-- `python main.py probe-models`
-  Tries the configured Gemini model candidates with a short prompt and prints success/failure per model.
-
-- `python main.py devui --host 127.0.0.1 --port 8080 --no-open`
-  Starts Microsoft Agent Framework DevUI using directory discovery.
-
-- `python -m uvicorn autogen_dashboard.app:create_app --factory --host 127.0.0.1 --port 8000`
-  Starts the Operator Workbench product UI over the existing dashboard runtime.
-
-## Human In The Loop
-
-This starter currently uses tool approval as the first HITL mechanism.
-
-The agent has a `request_human_approval` tool marked with mandatory approval. In DevUI, when the model decides it needs confirmation for a proposed action, DevUI will pause and ask you to approve or reject the tool call before the run continues.
-
-That is the simplest supported MAF path for a practical local setup. A richer request/response workflow gate can be added next if you want explicit pause states separate from tool approval.
-
-## Gemini Quota Fallback
-
-The main auto-routing MAF agent now uses an ordered fallback chain.
-
-Default chain:
-
-1. `gemini:gemini-2.5-pro`
-2. `anthropic:claude-sonnet-4-6` when `ANTHROPIC_API_KEY` is configured
-3. `gemini:gemini-2.5-flash`
-4. `gemini:gemini-2.5-flash-lite`
-5. `claude-cli`
-6. `codex-cli`
-7. `gemini-cli:gemini-2.5-pro`
-
-That means DevUI can keep answering even when the free-tier Gemini project is exhausted.
-
-Important limitation:
-
-- when a turn falls back to a CLI provider, tool calling is unavailable for that turn
-- the response is prefixed so you can see that fallback was used
-
-You can override the chain in `.env` with:
-
-```env
-MAF_FALLBACK_CHAIN=gemini:gemini-2.5-pro,anthropic:claude-sonnet-4-6,gemini:gemini-2.5-flash,gemini:gemini-2.5-flash-lite,claude-cli,codex-cli,gemini-cli:gemini-2.5-pro
-```
+Copy `.env.example` to `.env` and set `GEMINI_API_KEY`. See the [Setup Guide](https://github.com/Coding-Autopilot-System/autogen/wiki/Setup-Guide) for full configuration instructions.
 
 ## Configuration
 
-The loader in [maf_starter/config.py](/C:/repo/autogen/maf_starter/config.py) reads `.env` from the repo root.
-
-Primary variables:
-
-```env
-MAF_MODEL=gemini-2.5-flash
-MAF_REPO_ROOT=C:\repo\autogen
-MAF_ENTITIES_DIR=entities
-MAF_CHECKPOINT_DIR=state\maf-checkpoints
-MAF_FALLBACK_CHAIN=gemini:gemini-2.5-pro,gemini:gemini-2.5-flash,gemini:gemini-2.5-flash-lite,claude-cli,codex-cli,gemini-cli:gemini-2.5-pro
-GEMINI_API_KEY=...
-GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
-```
-
-Compatibility fallbacks:
-
-- `MAF_MODEL` falls back to `GEMINI_MODEL`
-- `MAF_BASE_URL` falls back to `GEMINI_BASE_URL`
-- `MAF_API_KEY` falls back to `GEMINI_API_KEY`
-
-Optional extra API:
-
-```env
-ANTHROPIC_API_KEY=
-ANTHROPIC_MODEL=claude-sonnet-4-6
-```
-
-## Notes
-
-- `autogen_dashboard` is now the primary operator-facing product UI. DevUI remains useful for framework-level inspection, but the workbench is the surface intended for daily run management.
-- `autogen_starter` remains legacy code.
-- Gemini model availability and quota are project-specific. Use `python main.py probe-models` if you want a real answer for your current key instead of guessing from docs.
-
-## DevUI UI Development
-
-This repo treats DevUI as a local sample app, not a long-term product UI.
-
-The practical customization seams are:
-
-- [maf_starter/routing_policy.py](/C:/repo/autogen/maf_starter/routing_policy.py) for model/provider selection
-- [maf_starter/devui_patches.py](/C:/repo/autogen/maf_starter/devui_patches.py) for route metadata and trace payloads
-- [maf_starter/devui_overrides.py](/C:/repo/autogen/maf_starter/devui_overrides.py) for injected CSS/JS presentation changes
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GEMINI_API_KEY` | Yes | -- | Gemini API key for primary model |
+| `MAF_MODEL` | No | `gemini-2.5-flash` | Primary model for agent runs |
+| `MAF_FALLBACK_CHAIN` | No | Auto | Comma-separated provider fallback order |
+| `ANTHROPIC_API_KEY` | No | -- | Anthropic API key for Claude fallback |
 
-For the full repo-specific guide, see [docs/DEVUI_CUSTOMIZATION.md](/C:/repo/autogen/docs/DEVUI_CUSTOMIZATION.md).
+See the [Configuration Reference](https://github.com/Coding-Autopilot-System/autogen/wiki/Configuration-Reference) for the full variable list.
 
-## Official References
+## License
 
-- [Microsoft Agent Framework Overview](https://learn.microsoft.com/en-us/agent-framework/overview/?pivots=programming-language-python)
-- [AutoGen to Microsoft Agent Framework Migration Guide](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-autogen/)
-- [DevUI Directory Discovery](https://learn.microsoft.com/en-us/agent-framework/devui/directory-discovery)
-- [DevUI Security](https://learn.microsoft.com/en-us/agent-framework/user-guide/devui/security)
-- [DevUI Samples](https://learn.microsoft.com/en-us/agent-framework/user-guide/devui/samples)
-- [Human in the Loop](https://learn.microsoft.com/en-us/agent-framework/workflows/human-in-the-loop)
+MIT -- see [LICENSE](LICENSE)