Docs/readme clarity and diagram colors

.devcontainer/devcontainer.json

@@ -1,5 +1,5 @@
 {
-  "name": "AutoCloud Dev",
+  "name": "Git-Ape Dev",
   "image": "mcr.microsoft.com/devcontainers/python:3-3.12-bookworm",
 
   "features": {

.github/plugin/marketplace.json

@@ -2,7 +2,7 @@
   "name": "git-ape",
   "owner": {
     "name": "Microsoft",
-    "url": "https://github.com/Azure/git-ape-private"
+    "url": "https://github.com/Azure/git-ape"
   },
   "metadata": {
     "description": "Git-Ape — Intelligent Azure deployment agent and skill suite for GitHub Copilot. Onboard any repository with guided ARM template generation, security analysis, cost estimation, drift detection, and automated CI/CD pipelines.",

.github/skills/git-ape-onboarding/SKILL.md

@@ -219,7 +219,7 @@ The skill auto-detects this by calling:
 ```bash
 gh api "orgs/{org}/actions/oidc/customization/sub" --jq ".use_default"
 ```
-- Returns `true` → standard format: `repo:Azure/git-ape-private:pull_request`
+- Returns `true` → standard format: `repo:Azure/git-ape:pull_request`
 - Returns `false` → ID format: `repository_owner_id:6844498:repository_id:1184905165:pull_request`
 
 If OIDC login fails with `AADSTS700213: No matching federated identity record`, the
@@ -228,7 +228,7 @@ onboarding (the skill will auto-detect and use the correct format), or manually
 existing credentials:
 ```bash
 # Get repo/owner IDs
-gh api repos/Azure/git-ape-private --jq '{repo_id: .id, owner_id: .owner.id}'
+gh api repos/Azure/git-ape --jq '{repo_id: .id, owner_id: .owner.id}'
 
 # Update each federated credential with correct subject
 az ad app federated-credential update \

.github/skills/prereq-check/SKILL.md

@@ -7,12 +7,12 @@ user-invocable: true
 
 # Prerequisites Check
 
-Validates the local environment has the CLI tools and auth sessions needed to run AutoCloud skills.
+Validates the local environment has the CLI tools and auth sessions needed to run Git-Ape skills.
 
 ## When to Use
 
-- Before first-time onboarding (`/autocloud-onboarding`)
-- When any AutoCloud skill fails with a "command not found" error
+- Before first-time onboarding (`/git-ape-onboarding`)
+- When any Git-Ape skill fails with a "command not found" error
 - When switching machines or dev containers
 - When a user asks "what do I need to install?"
 
@@ -141,7 +141,7 @@ winget install GitHub.cli
 winget install jqlang.jq
 ```
 
-> **Windows note:** AutoCloud skills require a BASH shell. Install [Git for Windows](https://gitforwindows.org/) and use git-bash.
+> **Windows note:** Git-Ape skills require a BASH shell. Install [Git for Windows](https://gitforwindows.org/) and use git-bash.
 
 ### Step 5: Check Auth Sessions
 
@@ -165,7 +165,7 @@ fi
 
 Present a final verdict:
 
-- **✅ READY** — All tools installed, versions OK, auth sessions active. Proceed with any AutoCloud skill.
+- **✅ READY** — All tools installed, versions OK, auth sessions active. Proceed with any Git-Ape skill.
 - **⚠️ TOOLS MISSING** — List what to install. Do not proceed until resolved.
 - **⚠️ AUTH MISSING** — Tools OK but user needs to run `az login` and/or `gh auth login`.
 
@@ -174,4 +174,4 @@ Present a final verdict:
 1. Run Steps 1–5 by executing the commands in the terminal.
 2. Present the results table and install commands (if needed).
 3. Do NOT install anything automatically — show the commands and let the user run them.
-4. If everything passes, tell the user they're ready and suggest next steps (e.g., `/autocloud-onboarding`).
+4. If everything passes, tell the user they're ready and suggest next steps (e.g., `/git-ape-onboarding`).

README.md

@@ -6,36 +6,28 @@
 > EXPERIMENTAL PROJECT: Git-Ape is in active development and is not production-ready.
 > Use it for local development, demos, sandbox subscriptions, and learning only.
 
-
 **📖 Documentation:** [azure.github.io/git-ape](https://azure.github.io/git-ape/)
 
-Git-Ape is a **platform engineering framework** built on GitHub Copilot. It provides a structured, multi-agent system for planning, validating, and deploying Azure infrastructure — with security gates, cost analysis, and CI/CD pipeline integration built in.
-
-## What It Is
+Git-Ape is a **platform engineering framework** built on GitHub Copilot. It is a multi-agent system that plans, validates, and deploys Azure infrastructure — with security gates, cost analysis, and CI/CD pipeline integration built in.
 
-Git-Ape packages a set of Copilot agents and skills focused on Azure infrastructure work.
+Nothing is deployed without your explicit confirmation.
 
-- It helps you gather deployment requirements.
-- It generates ARM templates and supporting deployment artifacts.
-- It runs security, preflight, and cost checks before deployment.
-- It supports onboarding and post-deployment validation.
+## What Git-Ape Does
 
-## What It Does
+Git-Ape walks every deployment through the same four steps:
 
-Git-Ape is designed around a simple deployment flow:
+1. **Gather** requirements through a guided interview.
+2. **Generate** an ARM template, architecture diagram, cost estimate, and security report.
+3. **Confirm** with you (interactive) or via PR review (headless) before anything is created.
+4. **Deploy** to Azure and run post-deployment validation.
 
-1. Collect the inputs for the resources you want.
-2. Generate and review the template, naming, cost, and security results.
-3. Ask for confirmation before anything changes in Azure.
-4. Deploy and run follow-up validation.
+It is built for:
 
-Common tasks it supports:
+- Azure application stacks: Function Apps, Web Apps, Storage, SQL, Cosmos DB, Container Apps.
+- Repository onboarding: OIDC, RBAC, GitHub environments, and secrets.
+- Auditable deployments: every run is saved under `.azure/deployments/`.
+- Drift detection between live Azure state and stored deployment artifacts *(agentic workflow — coming soon)*.
 
-- Deploying Azure application stacks such as Function Apps, Web Apps, Storage, SQL, Cosmos DB, and Container Apps.
-- Bootstrapping repository onboarding for OIDC, RBAC, GitHub environments, and secrets.
-- Saving deployment artifacts under `.azure/deployments/` for audit and reuse.
-- Detecting configuration drift between Azure and stored deployment state (agentic workflow — coming soon).
-- 
 ## Git-Ape in action
 
 A short demo video of the onboarding and deploy experience using Git-Ape.
@@ -45,49 +37,69 @@ A short demo video of the onboarding and deploy experience using Git-Ape.
 
 ## Get Started
 
-### Prerequisite
-- Only tested with BASH shells (git-bash for windows)
-- Run `/prereq-check` in Copilot Chat to verify all required tools (`az`, `gh`, `jq`, `git`) and auth sessions
+### Prerequisites
+
+- A Bash-compatible shell (use `git-bash` on Windows). Other shells are untested.
+- Azure CLI (`az`), GitHub CLI (`gh`), `jq`, and `git` installed and authenticated.
+- Run `/prereq-check` in Copilot Chat to verify everything is in place.
 
 ### 1. Install the plugin
 
-Recommended:
+Git-Ape ships as a [VS Code agent plugin](https://code.visualstudio.com/docs/copilot/customization/agent-plugins) and as a GitHub Copilot CLI plugin. Pick the path that matches how you use Copilot.
+
+#### Option A: VS Code agent plugin (recommended for VS Code users)
+
+Prerequisites: VS Code with GitHub Copilot enabled and the `chat.plugins.enabled` setting set to `true` (managed at the organization level).
+
+1. Add the marketplace in your VS Code `settings.json`:
+
+   ```jsonc
+   "chat.plugins.marketplaces": [
+       "Azure/git-ape"
+   ]
+   ```
+
+2. Open the Extensions view (`⇧⌘X` on macOS, `Ctrl+Shift+X` on Windows/Linux), search for `@agentPlugins`, find **git-ape**, and select **Install**.
+3. Alternatively, open the Command Palette (`⇧⌘P` on macOS, `Ctrl+Shift+P` on Windows/Linux), run **Chat: Install Plugin From Source**, and enter `https://github.com/Azure/git-ape`.
+4. Verify the agents and skills appear in Copilot Chat (for example, type `@git-ape` or `/prereq-check`).
+
+#### Option B: Copilot CLI plugin
 
 ```bash
 copilot plugin marketplace add Azure/git-ape
 copilot plugin install git-ape@git-ape
+copilot plugin list   # Should show: git-ape@git-ape
 ```
 
-Verify the installation:
+#### Option C: Local development install
 
-```bash
-copilot plugin list   # Should show: git-ape@git-ape
-```
+Clone this repository and register the local checkout as a VS Code plugin in `settings.json`:
 
-Manual option:
+```jsonc
+"chat.pluginLocations": {
+    "/absolute/path/to/git-ape": true
+}
+```
 
-1. Clone this repository.
-2. Open it in VS Code with GitHub Copilot enabled.
-3. Confirm the agents appear in chat.
+Reload VS Code; the `@git-ape` agent and Git-Ape skills will appear in Copilot Chat.
 
 ### 2. Configure Azure access
 
-1. Install Azure CLI and sign in with `az login`.
-2. Configure the Azure MCP server in VS Code.
-3. Verify the required Azure services are enabled.
-
-Setup details are in [docs/AZURE_MCP_SETUP.md](docs/AZURE_MCP_SETUP.md).
+1. Sign in with `az login`.
+2. Configure the Azure MCP server in VS Code — see [docs/AZURE_MCP_SETUP.md](docs/AZURE_MCP_SETUP.md).
 
 ### 3. Use the agents
 
-Start with one of these prompts in Copilot Chat:
+In Copilot Chat, try one of:
 
 - `@git-ape deploy a Python function app`
 - `@git-ape deploy a web app with SQL database`
 - `@Git-Ape Onboarding set up this repo for Azure deployments`
 
-### 4. Tear Down
-Use @git-ape to clean up afterwards by using:
+### 4. Tear down
+
+When you're done, clean up with:
+
 - `@git-ape destroy Python function app`
 
 ## Where To Go Next
@@ -100,13 +112,14 @@ Use @git-ape to clean up afterwards by using:
 
 ## Architecture
 
-`@git-ape` is the central orchestrator. It coordinates a deployment pipeline of specialized subagents, enforces security gates, invokes skills, and manages deployment state. It does not deploy anything without explicit user confirmation.
+`@git-ape` is the central orchestrator. It coordinates a pipeline of specialized subagents, enforces security gates, invokes skills, and manages deployment state. It never deploys anything without explicit user confirmation.
 
 ### Agent & Skill Orchestration
 
 ```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
 graph TD
-    GA["<b>@git-ape</b><br/>Main Orchestrator Agent<br/><i>Coordinates deployment stages, enforces security gates,<br/>delegates to subagents, invokes skills</i>"]
+    GA["<b>@git-ape</b><br/>Main Orchestrator<br/><i>Coordinates stages, enforces gates,<br/>delegates to subagents, invokes skills</i>"]
 
     GA --> DP
     GA --> AD
@@ -131,6 +144,18 @@ graph TD
         IE["<b>IaC Exporter</b><br/>Import live resources"]
         OB["<b>Git-Ape Onboarding</b><br/>OIDC + RBAC<br/>GitHub envs & secrets"]
     end
+
+    classDef orchestrator fill:#1f6feb,stroke:#0b3d91,stroke-width:2px,color:#ffffff
+    classDef pipeline fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91
+    classDef gate fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12
+    classDef advisory fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95
+    classDef utility fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d
+
+    class GA orchestrator
+    class RG,TG,RD pipeline
+    class SG,UC gate
+    class WR,PA advisory
+    class IE,OB utility
 ```
 
 ### Skills
@@ -154,6 +179,7 @@ Skills are invoked by agents at specific stages. Each skill handles one focused
 ### Deployment Flow
 
 ```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
 graph TD
     U["User prompt:<br/><i>deploy a Python function app</i>"]
 
@@ -188,15 +214,30 @@ graph TD
     SK4["/azure-integration-tester<br/>/azure-resource-visualizer"]
 
     S4 -. skills .-> SK4
+
+    classDef user fill:#e0e7ff,stroke:#4338ca,stroke-width:2px,color:#1e1b4b
+    classDef stage fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91
+    classDef skill fill:#f1f5f9,stroke:#64748b,stroke-width:1px,color:#0f172a,stroke-dasharray: 4 2
+    classDef gate fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12
+    classDef fix fill:#fecaca,stroke:#b91c1c,stroke-width:1px,color:#7f1d1d
+    classDef deploy fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d
+
+    class U user
+    class S1,S2,WAF stage
+    class SK1,SK2,SK4 skill
+    class GATE,CONFIRM gate
+    class FIX fix
+    class S3,S4 deploy
 ```
 
 ### Execution Modes
 
-Git-Ape works in two modes — same agents and skills, different execution context.
+Git-Ape runs the same agents and skills in two different contexts.
 
 ```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
 graph LR
-    subgraph Interactive ["Interactive Mode (VS Code / Chat)"]
+    subgraph Interactive ["🧑‍💻 Interactive Mode — VS Code / Chat"]
         direction TB
         I1["User ↔ @git-ape"]
         I2["Real-time Q&A"]
@@ -206,7 +247,7 @@ graph LR
         I6["@git-ape destroy {id}"]
     end
 
-    subgraph Headless ["Headless Mode (Coding Agent / Actions)"]
+    subgraph Headless ["🤖 Headless Mode — Coding Agent / Actions"]
         direction TB
         H1["Issue → Agent on branch"]
         H2["Parse requirements from body"]
@@ -216,6 +257,12 @@ graph LR
         H6["git-ape-deploy.yml (merge)"]
         H7["git-ape-destroy.yml (merge)"]
     end
+
+    classDef interactive fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91
+    classDef headless fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95
+
+    class I1,I2,I3,I4,I5,I6 interactive
+    class H1,H2,H3,H4,H5,H6,H7 headless
 ```
 
 **Interactive** — you talk to `@git-ape` in VS Code Copilot Chat, authenticate via `az login`, and approve each step in real time.

docs/CODESPACES.md

@@ -1,12 +1,12 @@
 # GitHub Codespaces Dev Environment
 
-AutoCloud includes a ready-to-use [dev container](https://containers.dev/) configuration so you can start contributing or using the project instantly in GitHub Codespaces (or any dev container-compatible tool like VS Code Dev Containers).
+Git-Ape includes a ready-to-use [dev container](https://containers.dev/) configuration so you can start contributing or using the project instantly in GitHub Codespaces (or any dev container-compatible tool like VS Code Dev Containers).
 
 ## Quick Start
 
 ### Option 1: GitHub Codespaces (recommended)
 
-1. Navigate to the [AutoCloud repository](https://github.com/Azure/autocloud).
+1. Navigate to the [Git-Ape repository](https://github.com/Azure/git-ape).
 2. Click **Code** → **Codespaces** → **Create codespace on main**.
 3. Wait for the container to build and the post-create setup to finish.
 4. Sign in to Azure with `az login` when prompted.
@@ -69,7 +69,7 @@ Once the environment is ready:
 
 1. **Sign in to Azure**: Run `az login` to authenticate. For Codespaces, `az login --use-device-code` works best.
 2. **Verify the setup**: Run `az account show` to confirm your subscription.
-3. **Start using AutoCloud**: Open Copilot Chat and try `@autocloud deploy a Python function app`.
+3. **Start using Git-Ape**: Open Copilot Chat and try `@git-ape deploy a Python function app`.
 
 ## Customization
 

docs/DEPLOYMENT_STATE.md

@@ -15,6 +15,43 @@ Every deployment creates a timestamped directory under `.azure/deployments/` con
 - Test results and logs for debugging
 - Error information for failure analysis
 
+## Deployment Lifecycle
+
+A deployment moves through a defined set of states tracked in `metadata.json`. Valid `status` values are `initialized`, `gathering-requirements`, `generating-template`, `awaiting-confirmation`, `deploying`, `testing`, `succeeded`, `failed`, `rolled-back`, `destroy-requested`, and `destroyed`. Terminal states (`succeeded`, `failed`, `rolled-back`, `destroyed`) are persisted in git for audit.
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
+stateDiagram-v2
+    state "gathering-requirements" as gatheringRequirements
+    state "generating-template" as generatingTemplate
+    state "awaiting-confirmation" as awaitingConfirmation
+    state "rolled-back" as rolledBack
+    state "destroy-requested" as destroyRequested
+
+    [*] --> initialized: deployment dir created
+    initialized --> gatheringRequirements: Requirements Gatherer
+    gatheringRequirements --> generatingTemplate: Template Generator
+    generatingTemplate --> awaitingConfirmation: security gate passed
+    generatingTemplate --> generatingTemplate: security gate blocked<br/>(fix loop)
+    awaitingConfirmation --> deploying: user / PR approval
+    awaitingConfirmation --> [*]: declined
+    deploying --> testing: az deployment ok
+    deploying --> failed: deployment error
+    testing --> succeeded: tests pass
+    testing --> failed: tests fail
+    failed --> rolledBack: rollback initiated
+    succeeded --> destroyRequested: PR sets metadata
+    destroyRequested --> destroyed: git-ape-destroy.yml
+    succeeded --> [*]
+    rolledBack --> [*]
+    destroyed --> [*]
+
+    classDef terminal fill:#dcfce7,stroke:#15803d,color:#14532d
+    classDef error fill:#fecaca,stroke:#b91c1c,color:#7f1d1d
+    class succeeded,destroyed terminal
+    class failed,rolledBack error
+```
+
 ## Directory Structure
 
 ```