diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index dd89602..088c16e 100644
--- a/.devcontainer/devcontainer.json
+++ b/.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": {
diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json
index 9fb621d..9b5979a 100644
--- a/.github/plugin/marketplace.json
+++ b/.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.",
diff --git a/.github/skills/git-ape-onboarding/SKILL.md b/.github/skills/git-ape-onboarding/SKILL.md
index 69a5097..caa1537 100644
--- a/.github/skills/git-ape-onboarding/SKILL.md
+++ b/.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 \
diff --git a/.github/skills/prereq-check/SKILL.md b/.github/skills/prereq-check/SKILL.md
index 8ef78f7..91c2519 100644
--- a/.github/skills/prereq-check/SKILL.md
+++ b/.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`).
diff --git a/README.md b/README.md
index 96b73f5..5aaa41b 100644
--- a/README.md
+++ b/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.
diff --git a/docs/CODESPACES.md b/docs/CODESPACES.md
index 090062b..1b9a003 100644
--- a/docs/CODESPACES.md
+++ b/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
 
diff --git a/docs/DEPLOYMENT_STATE.md b/docs/DEPLOYMENT_STATE.md
index 8f3db7b..ec8b41c 100644
--- a/docs/DEPLOYMENT_STATE.md
+++ b/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
 
 ```
diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md
index 0b8f84e..a6c0525 100644
--- a/docs/ONBOARDING.md
+++ b/docs/ONBOARDING.md
@@ -14,6 +14,56 @@ Git-Ape supports two onboarding modes:
 | **Single environment** | One Azure subscription for all deployments | `azure-deploy`, `azure-destroy` | Repository-level |
 | **Multi-environment** | Separate subscriptions per stage (dev/staging/prod) | `azure-deploy-dev`, `azure-deploy-staging`, `azure-deploy-prod`, `azure-destroy` | Environment-level |
 
+## How OIDC Authentication Works
+
+Git-Ape uses OpenID Connect (OIDC) federation between GitHub Actions and Microsoft Entra ID. No client secrets are stored — GitHub mints a short-lived token at workflow runtime, and Entra exchanges it for an Azure access token based on a trust relationship you configure once.
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
+sequenceDiagram
+    autonumber
+    participant GH as GitHub Actions<br/>(workflow run)
+    participant Entra as Microsoft Entra ID<br/>(App Registration)
+    participant ARM as Azure Resource Manager
+
+    GH->>GH: Mint OIDC token<br/>subject: repo:org/repo:ref:refs/heads/main
+    GH->>Entra: Exchange token<br/>(client_id + federated credential)
+    Entra->>Entra: Verify subject matches<br/>federated credential
+    Entra-->>GH: Azure access token<br/>(short-lived, ~1h)
+    GH->>ARM: az deployment sub create<br/>Authorization: Bearer [token]
+    ARM->>ARM: Check RBAC role assignment<br/>on subscription
+    ARM-->>GH: Deployment result
+```
+
+**Trust components you configure during onboarding:**
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
+graph LR
+    GH["<b>GitHub Repo</b><br/>org/repo"]
+    FC["<b>Federated Credential</b><br/>subject: repo:org/repo:..."]
+    APP["<b>Entra App Registration</b><br/>client_id + tenant_id"]
+    SP["<b>Service Principal</b><br/>object_id"]
+    SUB["<b>Azure Subscription</b><br/>subscription_id"]
+    ROLE["<b>RBAC Role</b><br/>Contributor / UAA"]
+
+    GH -->|trusts| FC
+    FC -->|attached to| APP
+    APP -->|backed by| SP
+    SP -->|assigned| ROLE
+    ROLE -->|scoped to| SUB
+
+    classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91
+    classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95
+    classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d
+
+    class GH,FC gh
+    class APP,SP entra
+    class SUB,ROLE azure
+```
+
+The **Quick Start** below automates all of this. The **Manual Setup** section walks through each component individually.
+
 ## Quick Start (Automated)
 
 You can run onboarding from Copilot Chat with:
@@ -110,7 +160,7 @@ winget install GitHub.cli
 winget install jqlang.jq
 ```
 
-> **Note:** AutoCloud skills require a BASH shell. Install [Git for Windows](https://gitforwindows.org/) and use git-bash.
+> **Note:** Git-Ape skills require a BASH shell. Install [Git for Windows](https://gitforwindows.org/) and use git-bash.
 </details>
 
 You must be logged in to both:
@@ -618,109 +668,97 @@ Environment creation requires admin access to the repository. Ask a repo admin t
 
 ### Single Environment Mode
 
-```
-┌──────────────────────────────────────────────────────────────────────┐
-│                        GitHub Repository                             │
-│                                                                      │
-│  Secrets (repo-level):           Environments:                       │
-│  ┌─────────────────────┐         ┌──────────────┐  ┌───────────────┐ │
-│  │ AZURE_CLIENT_ID     │         │ azure-deploy │  │ azure-destroy │ │
-│  │ AZURE_TENANT_ID     │         │ (main only)  │  │ (any branch)  │ │
-│  │ AZURE_SUBSCRIPTION_ID│        └──────┬───────┘  └──────┬────────┘ │
-│  │ SLACK_WEBHOOK_URL ⁽¹⁾│              │                  │          │
-│  └──────────┬──────────┘               │                  │          │
-│             │                          │                  │          │
-│  Workflows: │                          │                  │          │
-│  ┌──────────┴──────────────────────────┴──────────────────┴────────┐ │
-│  │  git-ape-plan.yml     → OIDC token (PR subject)               │ │
-│  │  git-ape-deploy.yml   → OIDC token (main / azure-deploy env)  │ │
-│  │  git-ape-destroy.yml  → OIDC token (azure-destroy env)        │ │
-│  │  git-ape-verify.yml   → OIDC token (workflow_dispatch)        │ │
-│  └──────────┬──────────────────────────────────────────────────────┘ │
-└─────────────┼────────────────────────────────────────────────────────┘
-              │ OIDC token exchange
-              ▼
-┌──────────────────────────────────────────────────────────────────────┐
-│                         Entra ID (Azure AD)                          │
-│                                                                      │
-│  App Registration: sp-git-ape-{repo}                               │
-│  ┌────────────────────────────────────────────┐                      │
-│  │ Client ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxx  │                      │
-│  │                                            │                      │
-│  │ Federated Credentials:                     │                      │
-│  │   • repo:org/repo:ref:refs/heads/main      │                      │
-│  │   • repo:org/repo:pull_request             │                      │
-│  │   • repo:org/repo:environment:azure-deploy │                      │
-│  │   • repo:org/repo:environment:azure-destroy│                      │
-│  └────────────────────┬───────────────────────┘                      │
-└───────────────────────┼──────────────────────────────────────────────┘
-                        │ Service Principal
-                        ▼
-┌──────────────────────────────────────────────────────────────────────┐
-│                       Azure Subscription                              │
-│                                                                       │
-│  RBAC: Contributor (+ User Access Administrator if RBAC in templates) │
-│                                                                       │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                  │
-│  │ rg-app-dev  │  │ rg-api-prod │  │ rg-data-stg │  ...             │
-│  └─────────────┘  └─────────────┘  └─────────────┘                  │
-└──────────────────────────────────────────────────────────────────────┘
-
-⁽¹⁾ Optional
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
+graph TD
+    subgraph GH["GitHub Repository"]
+        direction TB
+        SEC["<b>Repo Secrets</b><br/>AZURE_CLIENT_ID<br/>AZURE_TENANT_ID<br/>AZURE_SUBSCRIPTION_ID<br/>SLACK_WEBHOOK_URL (optional)"]
+        ENVD["<b>azure-deploy</b><br/>main branch only"]
+        ENVX["<b>azure-destroy</b><br/>main branch only"]
+        WF["<b>Workflows</b><br/>git-ape-plan.yml (PR)<br/>git-ape-deploy.yml (main / azure-deploy)<br/>git-ape-destroy.yml (azure-destroy)<br/>git-ape-verify.yml (dispatch)"]
+        SEC --- WF
+        ENVD --- WF
+        ENVX --- WF
+    end
+
+    subgraph ENTRA["Microsoft Entra ID"]
+        APP["<b>App Registration</b><br/>sp-git-ape-{repo}<br/>client_id + tenant_id"]
+        FC["<b>Federated Credentials</b><br/>• repo:org/repo:ref:refs/heads/main<br/>• repo:org/repo:pull_request<br/>• repo:org/repo:environment:azure-deploy<br/>• repo:org/repo:environment:azure-destroy"]
+        APP --- FC
+    end
+
+    subgraph AZ["Azure Subscription"]
+        ROLE["<b>RBAC</b><br/>Contributor<br/>(+ UAA if templates assign roles)"]
+        RG1["rg-app-dev"]
+        RG2["rg-api-prod"]
+        RG3["rg-data-stg"]
+        ROLE --- RG1
+        ROLE --- RG2
+        ROLE --- RG3
+    end
+
+    WF -->|"OIDC token exchange"| FC
+    APP -->|"Service Principal"| ROLE
+
+    classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91
+    classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95
+    classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d
+
+    class SEC,ENVD,ENVX,WF gh
+    class APP,FC entra
+    class ROLE,RG1,RG2,RG3 azure
 ```
 
 ### Multi-Environment Mode
 
-```
-┌──────────────────────────────────────────────────────────────────────────────────┐
-│                              GitHub Repository                                    │
-│                                                                                   │
-│  Repo-level Secrets:              Environment Secrets:                            │
-│  ┌───────────────────┐            ┌─ azure-deploy-dev ──────────────────────────┐ │
-│  │ AZURE_CLIENT_ID   │            │  AZURE_CLIENT_ID, AZURE_TENANT_ID           │ │
-│  │ AZURE_TENANT_ID   │            │  AZURE_SUBSCRIPTION_ID → Dev Sub            │ │
-│  └───────────────────┘            └─────────────────────────────────────────────┘ │
-│                                   ┌─ azure-deploy-staging ──────────────────────┐ │
-│                                   │  AZURE_CLIENT_ID, AZURE_TENANT_ID           │ │
-│                                   │  AZURE_SUBSCRIPTION_ID → Staging Sub        │ │
-│                                   └─────────────────────────────────────────────┘ │
-│                                   ┌─ azure-deploy-prod ─────────────────────────┐ │
-│                                   │  AZURE_CLIENT_ID, AZURE_TENANT_ID           │ │
-│                                   │  AZURE_SUBSCRIPTION_ID → Prod Sub           │ │
-│                                   │  ⚠️ Required reviewers                      │ │
-│                                   └─────────────────────────────────────────────┘ │
-│                                   ┌─ azure-destroy ─────────────────────────────┐ │
-│                                   │  AZURE_CLIENT_ID, AZURE_TENANT_ID           │ │
-│                                   │  AZURE_SUBSCRIPTION_ID → Default Sub        │ │
-│                                   └─────────────────────────────────────────────┘ │
-└──────────────────────────┬───────────────────────────────────────────────────────┘
-                           │ OIDC token exchange
-                           ▼
-┌──────────────────────────────────────────────────────────────────────────────────┐
-│                            Entra ID (Azure AD)                                    │
-│                                                                                   │
-│  App Registration: sp-git-ape-{repo}                                            │
-│  ┌────────────────────────────────────────────────────────┐                       │
-│  │ Federated Credentials:                                 │                       │
-│  │   • repo:org/repo:ref:refs/heads/main                  │                       │
-│  │   • repo:org/repo:pull_request                         │                       │
-│  │   • repo:org/repo:environment:azure-deploy-dev         │                       │
-│  │   • repo:org/repo:environment:azure-deploy-staging     │                       │
-│  │   • repo:org/repo:environment:azure-deploy-prod        │                       │
-│  │   • repo:org/repo:environment:azure-destroy            │                       │
-│  └────────────────────┬───────────────────────────────────┘                       │
-└───────────────────────┼──────────────────────────────────────────────────────────┘
-                        │ Service Principal (shared)
-          ┌─────────────┼─────────────┐
-          ▼             ▼             ▼
-┌──────────────┐ ┌──────────────┐ ┌──────────────┐
-│  Dev Sub     │ │ Staging Sub  │ │  Prod Sub    │
-│  Contributor │ │ Contributor  │ │ Contributor + │
-│              │ │              │ │ UAA           │
-│ ┌──────────┐ │ │ ┌──────────┐ │ │ ┌──────────┐ │
-│ │ rg-*-dev │ │ │ │ rg-*-stg │ │ │ │ rg-*-prod│ │
-│ └──────────┘ │ │ └──────────┘ │ │ └──────────┘ │
-└──────────────┘ └──────────────┘ └──────────────┘
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
+graph TD
+    subgraph GH["GitHub Repository"]
+        direction TB
+        REPO["<b>Repo-level Secrets</b><br/>AZURE_CLIENT_ID<br/>AZURE_TENANT_ID"]
+        EDEV["<b>azure-deploy-dev</b><br/>SUBSCRIPTION_ID → Dev"]
+        ESTG["<b>azure-deploy-staging</b><br/>SUBSCRIPTION_ID → Staging"]
+        EPRD["<b>azure-deploy-prod</b><br/>SUBSCRIPTION_ID → Prod<br/>⚠️ Required reviewers"]
+        EDST["<b>azure-destroy</b><br/>SUBSCRIPTION_ID → Default"]
+    end
+
+    subgraph ENTRA["Microsoft Entra ID"]
+        APP["<b>App Registration</b><br/>sp-git-ape-{repo}"]
+        FC["<b>Federated Credentials</b><br/>• ref:refs/heads/main<br/>• pull_request<br/>• environment:azure-deploy-dev<br/>• environment:azure-deploy-staging<br/>• environment:azure-deploy-prod<br/>• environment:azure-destroy"]
+        APP --- FC
+    end
+
+    DEV["<b>Dev Subscription</b><br/>Contributor<br/>rg-*-dev"]
+    STG["<b>Staging Subscription</b><br/>Contributor<br/>rg-*-stg"]
+    PRD["<b>Prod Subscription</b><br/>Contributor + UAA<br/>rg-*-prod"]
+
+    REPO --- EDEV
+    REPO --- ESTG
+    REPO --- EPRD
+    REPO --- EDST
+
+    EDEV -->|"OIDC"| FC
+    ESTG -->|"OIDC"| FC
+    EPRD -->|"OIDC"| FC
+    EDST -->|"OIDC"| FC
+
+    APP -->|"Service Principal"| DEV
+    APP -->|"Service Principal"| STG
+    APP -->|"Service Principal"| PRD
+
+    classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91
+    classDef ghprod fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12
+    classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95
+    classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d
+    classDef azureprod fill:#fecaca,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d
+
+    class REPO,EDEV,ESTG,EDST gh
+    class EPRD ghprod
+    class APP,FC entra
+    class DEV,STG azure
+    class PRD azureprod
 ```
 
 ---
diff --git a/scripts/generate-docs.js b/scripts/generate-docs.js
index bd90b7b..b450727 100644
--- a/scripts/generate-docs.js
+++ b/scripts/generate-docs.js
@@ -58,6 +58,31 @@ function toTitleCase(str) {
     .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
+// Rewrite sibling `*.agent.md` markdown links to docusaurus-friendly slug links.
+// Source agents reference each other by filename (e.g. `[git-ape.agent.md](git-ape.agent.md)`),
+// but the generated docusaurus pages live as `<slug>.md`, so the link target must drop
+// the `.agent.md` extension and use the slug.
+function rewriteAgentLinks(body) {
+  return body.replace(/(\[[^\]\n]+\])\(([^)\s]+\.agent\.md)\)/g, (_match, label, url) => {
+    // Skip absolute URLs (they aren't broken)
+    if (/^https?:\/\//i.test(url)) return `${label}(${url})`;
+    const filename = url.split('/').pop().replace(/\.agent\.md$/, '');
+    const slug = slugify(filename);
+    return `${label}(${slug})`;
+  });
+}
+
+// Rewrite skill-relative resource links (scripts, references) to absolute GitHub URLs,
+// since those files are not copied into the docusaurus site.
+function rewriteSkillLinks(body, skillDir) {
+  const githubBase = `https://github.com/Azure/git-ape/blob/main/.github/skills/${skillDir}`;
+  return body.replace(/(\[[^\]\n]+\])\((\.?\.?\/?(?:scripts|references)\/[^)\s]+)\)/g, (_match, label, url) => {
+    if (/^https?:\/\//i.test(url)) return `${label}(${url})`;
+    const cleaned = url.replace(/^\.\//, '');
+    return `${label}(${githubBase}/${cleaned})`;
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Agent doc generation
 // ---------------------------------------------------------------------------
@@ -87,7 +112,7 @@ function generateAgentDocs() {
     agents.push({ name, slug, description, userInvocable, file });
 
     // Extract meaningful body (skip the frontmatter warning section, keep substance)
-    const bodyTrimmed = body.trim();
+    const bodyTrimmed = rewriteAgentLinks(body.trim());
 
     let content = `---
 title: "${name}"
@@ -215,7 +240,7 @@ function generateSkillDocs() {
 
     skills.push({ name, slug, description, userInvocable, phase, dir });
 
-    const bodyTrimmed = body.trim();
+    const bodyTrimmed = rewriteSkillLinks(body.trim(), dir);
 
     let content = `---
 title: "${toTitleCase(name)}"
diff --git a/website/docs/agents/azure-iac-exporter.md b/website/docs/agents/azure-iac-exporter.md
index 2274f59..8d188eb 100644
--- a/website/docs/agents/azure-iac-exporter.md
+++ b/website/docs/agents/azure-iac-exporter.md
@@ -50,7 +50,7 @@ Analyze existing Azure resources and produce ARM templates, requirements files,
 ## Output Styling
 
 Follow the shared presentation style defined in Git-Ape:
-see [git-ape.agent.md](git-ape.agent.md).
+see [git-ape.agent.md](git-ape).
 
 ## Workflow
 
diff --git a/website/docs/agents/azure-principal-architect.md b/website/docs/agents/azure-principal-architect.md
index 4525b78..7ef8a47 100644
--- a/website/docs/agents/azure-principal-architect.md
+++ b/website/docs/agents/azure-principal-architect.md
@@ -48,7 +48,7 @@ Evaluate Azure deployments against the 5 WAF pillars. Provide actionable archite
 ## Output Styling
 
 Follow the shared presentation style defined in Git-Ape:
-see [git-ape.agent.md](git-ape.agent.md).
+see [git-ape.agent.md](git-ape).
 
 ## WAF Pillar Assessment
 
diff --git a/website/docs/agents/azure-requirements-gatherer.md b/website/docs/agents/azure-requirements-gatherer.md
index 11c8f23..0053667 100644
--- a/website/docs/agents/azure-requirements-gatherer.md
+++ b/website/docs/agents/azure-requirements-gatherer.md
@@ -43,7 +43,7 @@ Interview users to gather ALL necessary information for Azure resource deploymen
 ## Output Styling
 
 Follow the shared presentation style defined in Git-Ape:
-see [git-ape.agent.md](git-ape.agent.md).
+see [git-ape.agent.md](git-ape).
 
 ## Execution Context Adaptation
 
diff --git a/website/docs/agents/azure-resource-deployer.md b/website/docs/agents/azure-resource-deployer.md
index 8c5da22..e2f3c9b 100644
--- a/website/docs/agents/azure-resource-deployer.md
+++ b/website/docs/agents/azure-resource-deployer.md
@@ -43,7 +43,7 @@ Execute ARM template deployments to Azure subscriptions, monitor real-time progr
 ## Output Styling
 
 Follow the shared presentation style defined in Git-Ape:
-see [git-ape.agent.md](git-ape.agent.md).
+see [git-ape.agent.md](git-ape).
 
 Use the shared progress bar and status line patterns for polling updates and summaries.
 
diff --git a/website/docs/agents/azure-template-generator.md b/website/docs/agents/azure-template-generator.md
index 3fcd25f..1e38c77 100644
--- a/website/docs/agents/azure-template-generator.md
+++ b/website/docs/agents/azure-template-generator.md
@@ -44,7 +44,7 @@ Transform deployment requirements into validated, secure ARM templates. Show use
 ## Output Styling
 
 Follow the shared presentation style defined in Git-Ape:
-see [git-ape.agent.md](git-ape.agent.md).
+see [git-ape.agent.md](git-ape).
 
 ## Approach
 
diff --git a/website/docs/agents/git-ape-onboarding.md b/website/docs/agents/git-ape-onboarding.md
index 10b5324..710b154 100644
--- a/website/docs/agents/git-ape-onboarding.md
+++ b/website/docs/agents/git-ape-onboarding.md
@@ -62,13 +62,41 @@ Always use the `/git-ape-onboarding` skill for procedure and command patterns.
 7. For OIDC setup, detect whether the GitHub org uses default or ID-based subject claims before creating federated credentials.
 8. Ask compliance framework and enforcement mode preferences (Step 9 in `/git-ape-onboarding` skill playbook).
 9. Update the `## Compliance & Azure Policy` section in `.github/copilot-instructions.md` with the user's choices.
-10. Summarize created/updated artifacts and next checks.
+10. Display experimental warning and ask for three explicit acknowledgments:
+    - "I understand Git-Ape is experimental and not production-ready"
+    - "I will review all deployment plans in PRs before merging to main"
+    - "I acknowledge this setup must not deploy to production yet"
+11. Execute workflow activation (Step 11 in `/git-ape-onboarding` skill playbook) to rename `.exampleyml` files to `.yml` only if all acknowledgments are confirmed.
+12. Summarize created/updated artifacts and next checks.
+
+## Acknowledgment Phase
+
+Before activating workflows, you MUST collect explicit acknowledgments using `vscode_askQuestions`. Present three questions:
+
+1. **Question 1:**
+   - Header: `experimental-status`
+   - Question: "Do you understand that Git-Ape is currently experimental and not production-ready?"
+   - Options: Yes / No
+
+2. **Question 2:**
+   - Header: `review-plans`
+   - Question: "Will you review all deployment plans in PRs before merging to main?"
+   - Options: Yes / No
+
+3. **Question 3:**
+   - Header: `no-production`
+   - Question: "Do you acknowledge that this setup must not be used to deploy to production environments yet?"
+   - Options: Yes / No
+
+If ANY answer is "No", report: "Workflow activation cancelled. You can enable workflows later by renaming `.exampleyml` files to `.yml` in `.github/workflows/` when ready."  
+If ALL answers are "Yes", proceed to Step 11 (workflow activation via skill).
 
 ## Output Requirements
 
 - Keep output concise and stage-based: prerequisites, confirmation, execution, summary.
 - Never print secret values.
 - If onboarding fails, report the failing stage and recommended fix.
+- Display workflow activation status (activated or deferred) in final summary.
 
 ## Validation After Onboarding
 
diff --git a/website/docs/deployment/state.md b/website/docs/deployment/state.md
index 29e7ba8..6721ec6 100644
--- a/website/docs/deployment/state.md
+++ b/website/docs/deployment/state.md
@@ -24,6 +24,43 @@ Each deployment directory contains:
 - 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
 
 ### Azure
diff --git a/website/docs/getting-started/azure-setup.md b/website/docs/getting-started/azure-setup.md
index 5e2e100..30cd395 100644
--- a/website/docs/getting-started/azure-setup.md
+++ b/website/docs/getting-started/azure-setup.md
@@ -300,8 +300,8 @@ The agent will use whichever subscription is currently active in Azure CLI.
 After configuration:
 
 1. Test the agent with a simple deployment: `@git-ape deploy a resource group`
-2. Review the [README.md](../../README.md) for example workflows
-3. Customize workspace instructions in [copilot-instructions.md](../copilot-instructions.md)
+2. Review the [project README](https://github.com/Azure/git-ape/blob/main/README.md) for example workflows
+3. Customize workspace instructions in [`.github/copilot-instructions.md`](https://github.com/Azure/git-ape/blob/main/.github/copilot-instructions.md)
 4. Add your organization's naming conventions and policies
 
 ## Resources
diff --git a/website/docs/getting-started/codespaces.md b/website/docs/getting-started/codespaces.md
index 05ede6b..15d38f2 100644
--- a/website/docs/getting-started/codespaces.md
+++ b/website/docs/getting-started/codespaces.md
@@ -7,13 +7,13 @@ description: "Dev container and Codespaces setup"
 
 # 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.
@@ -76,7 +76,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
 
diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md
index 4dcab55..56ce775 100644
--- a/website/docs/getting-started/installation.md
+++ b/website/docs/getting-started/installation.md
@@ -9,27 +9,49 @@ description: "Install Git-Ape and verify prerequisites"
 
 ## Prerequisites
 
-- **Bash shell** (Git Bash on Windows)
-- **Azure CLI** (`az`) — signed in with `az login`
-- **GitHub CLI** (`gh`) — authenticated
-- **jq** and **git**
-
-Run `/prereq-check` in Copilot Chat to verify all tools and auth sessions automatically.
+- 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.
 
 ## Install the Plugin
 
-### Option 1: Marketplace (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 Azure/git-ape
+copilot plugin install git-ape@git-ape
+copilot plugin list   # Should show: git-ape@git-ape
 ```
 
-### Option 2: Manual
+### Option C: Local development install
+
+Clone this repository and register the local checkout as a VS Code plugin in `settings.json`:
+
+```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 Copilot Chat
+Reload VS Code; the `@git-ape` agent and Git-Ape skills will appear in Copilot Chat.
 
 ## Verify Installation
 
diff --git a/website/docs/getting-started/onboarding.md b/website/docs/getting-started/onboarding.md
index d1271dd..9f0688a 100644
--- a/website/docs/getting-started/onboarding.md
+++ b/website/docs/getting-started/onboarding.md
@@ -21,6 +21,56 @@ Git-Ape supports two onboarding modes:
 | **Single environment** | One Azure subscription for all deployments | `azure-deploy`, `azure-destroy` | Repository-level |
 | **Multi-environment** | Separate subscriptions per stage (dev/staging/prod) | `azure-deploy-dev`, `azure-deploy-staging`, `azure-deploy-prod`, `azure-destroy` | Environment-level |
 
+## How OIDC Authentication Works
+
+Git-Ape uses OpenID Connect (OIDC) federation between GitHub Actions and Microsoft Entra ID. No client secrets are stored — GitHub mints a short-lived token at workflow runtime, and Entra exchanges it for an Azure access token based on a trust relationship you configure once.
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
+sequenceDiagram
+    autonumber
+    participant GH as GitHub Actions<br/>(workflow run)
+    participant Entra as Microsoft Entra ID<br/>(App Registration)
+    participant ARM as Azure Resource Manager
+
+    GH->>GH: Mint OIDC token<br/>subject: repo:org/repo:ref:refs/heads/main
+    GH->>Entra: Exchange token<br/>(client_id + federated credential)
+    Entra->>Entra: Verify subject matches<br/>federated credential
+    Entra-->>GH: Azure access token<br/>(short-lived, ~1h)
+    GH->>ARM: az deployment sub create<br/>Authorization: Bearer [token]
+    ARM->>ARM: Check RBAC role assignment<br/>on subscription
+    ARM-->>GH: Deployment result
+```
+
+**Trust components you configure during onboarding:**
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
+graph LR
+    GH["<b>GitHub Repo</b><br/>org/repo"]
+    FC["<b>Federated Credential</b><br/>subject: repo:org/repo:..."]
+    APP["<b>Entra App Registration</b><br/>client_id + tenant_id"]
+    SP["<b>Service Principal</b><br/>object_id"]
+    SUB["<b>Azure Subscription</b><br/>subscription_id"]
+    ROLE["<b>RBAC Role</b><br/>Contributor / UAA"]
+
+    GH -->|trusts| FC
+    FC -->|attached to| APP
+    APP -->|backed by| SP
+    SP -->|assigned| ROLE
+    ROLE -->|scoped to| SUB
+
+    classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91
+    classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95
+    classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d
+
+    class GH,FC gh
+    class APP,SP entra
+    class SUB,ROLE azure
+```
+
+The **Quick Start** below automates all of this. The **Manual Setup** section walks through each component individually.
+
 ## Quick Start (Automated)
 
 You can run onboarding from Copilot Chat with:
@@ -625,109 +675,97 @@ Environment creation requires admin access to the repository. Ask a repo admin t
 
 ### Single Environment Mode
 
-```
-┌──────────────────────────────────────────────────────────────────────┐
-│                        GitHub Repository                             │
-│                                                                      │
-│  Secrets (repo-level):           Environments:                       │
-│  ┌─────────────────────┐         ┌──────────────┐  ┌───────────────┐ │
-│  │ AZURE_CLIENT_ID     │         │ azure-deploy │  │ azure-destroy │ │
-│  │ AZURE_TENANT_ID     │         │ (main only)  │  │ (any branch)  │ │
-│  │ AZURE_SUBSCRIPTION_ID│        └──────┬───────┘  └──────┬────────┘ │
-│  │ SLACK_WEBHOOK_URL ⁽¹⁾│              │                  │          │
-│  └──────────┬──────────┘               │                  │          │
-│             │                          │                  │          │
-│  Workflows: │                          │                  │          │
-│  ┌──────────┴──────────────────────────┴──────────────────┴────────┐ │
-│  │  git-ape-plan.yml     → OIDC token (PR subject)               │ │
-│  │  git-ape-deploy.yml   → OIDC token (main / azure-deploy env)  │ │
-│  │  git-ape-destroy.yml  → OIDC token (azure-destroy env)        │ │
-│  │  git-ape-verify.yml   → OIDC token (workflow_dispatch)        │ │
-│  └──────────┬──────────────────────────────────────────────────────┘ │
-└─────────────┼────────────────────────────────────────────────────────┘
-              │ OIDC token exchange
-              ▼
-┌──────────────────────────────────────────────────────────────────────┐
-│                         Entra ID (Azure AD)                          │
-│                                                                      │
-│  App Registration: sp-git-ape-{repo}                               │
-│  ┌────────────────────────────────────────────┐                      │
-│  │ Client ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxx  │                      │
-│  │                                            │                      │
-│  │ Federated Credentials:                     │                      │
-│  │   • repo:org/repo:ref:refs/heads/main      │                      │
-│  │   • repo:org/repo:pull_request             │                      │
-│  │   • repo:org/repo:environment:azure-deploy │                      │
-│  │   • repo:org/repo:environment:azure-destroy│                      │
-│  └────────────────────┬───────────────────────┘                      │
-└───────────────────────┼──────────────────────────────────────────────┘
-                        │ Service Principal
-                        ▼
-┌──────────────────────────────────────────────────────────────────────┐
-│                       Azure Subscription                              │
-│                                                                       │
-│  RBAC: Contributor (+ User Access Administrator if RBAC in templates) │
-│                                                                       │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                  │
-│  │ rg-app-dev  │  │ rg-api-prod │  │ rg-data-stg │  ...             │
-│  └─────────────┘  └─────────────┘  └─────────────┘                  │
-└──────────────────────────────────────────────────────────────────────┘
-
-⁽¹⁾ Optional
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
+graph TD
+    subgraph GH["GitHub Repository"]
+        direction TB
+        SEC["<b>Repo Secrets</b><br/>AZURE_CLIENT_ID<br/>AZURE_TENANT_ID<br/>AZURE_SUBSCRIPTION_ID<br/>SLACK_WEBHOOK_URL (optional)"]
+        ENVD["<b>azure-deploy</b><br/>main branch only"]
+        ENVX["<b>azure-destroy</b><br/>main branch only"]
+        WF["<b>Workflows</b><br/>git-ape-plan.yml (PR)<br/>git-ape-deploy.yml (main / azure-deploy)<br/>git-ape-destroy.yml (azure-destroy)<br/>git-ape-verify.yml (dispatch)"]
+        SEC --- WF
+        ENVD --- WF
+        ENVX --- WF
+    end
+
+    subgraph ENTRA["Microsoft Entra ID"]
+        APP["<b>App Registration</b><br/>sp-git-ape-{repo}<br/>client_id + tenant_id"]
+        FC["<b>Federated Credentials</b><br/>• repo:org/repo:ref:refs/heads/main<br/>• repo:org/repo:pull_request<br/>• repo:org/repo:environment:azure-deploy<br/>• repo:org/repo:environment:azure-destroy"]
+        APP --- FC
+    end
+
+    subgraph AZ["Azure Subscription"]
+        ROLE["<b>RBAC</b><br/>Contributor<br/>(+ UAA if templates assign roles)"]
+        RG1["rg-app-dev"]
+        RG2["rg-api-prod"]
+        RG3["rg-data-stg"]
+        ROLE --- RG1
+        ROLE --- RG2
+        ROLE --- RG3
+    end
+
+    WF -->|"OIDC token exchange"| FC
+    APP -->|"Service Principal"| ROLE
+
+    classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91
+    classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95
+    classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d
+
+    class SEC,ENVD,ENVX,WF gh
+    class APP,FC entra
+    class ROLE,RG1,RG2,RG3 azure
 ```
 
 ### Multi-Environment Mode
 
-```
-┌──────────────────────────────────────────────────────────────────────────────────┐
-│                              GitHub Repository                                    │
-│                                                                                   │
-│  Repo-level Secrets:              Environment Secrets:                            │
-│  ┌───────────────────┐            ┌─ azure-deploy-dev ──────────────────────────┐ │
-│  │ AZURE_CLIENT_ID   │            │  AZURE_CLIENT_ID, AZURE_TENANT_ID           │ │
-│  │ AZURE_TENANT_ID   │            │  AZURE_SUBSCRIPTION_ID → Dev Sub            │ │
-│  └───────────────────┘            └─────────────────────────────────────────────┘ │
-│                                   ┌─ azure-deploy-staging ──────────────────────┐ │
-│                                   │  AZURE_CLIENT_ID, AZURE_TENANT_ID           │ │
-│                                   │  AZURE_SUBSCRIPTION_ID → Staging Sub        │ │
-│                                   └─────────────────────────────────────────────┘ │
-│                                   ┌─ azure-deploy-prod ─────────────────────────┐ │
-│                                   │  AZURE_CLIENT_ID, AZURE_TENANT_ID           │ │
-│                                   │  AZURE_SUBSCRIPTION_ID → Prod Sub           │ │
-│                                   │  ⚠️ Required reviewers                      │ │
-│                                   └─────────────────────────────────────────────┘ │
-│                                   ┌─ azure-destroy ─────────────────────────────┐ │
-│                                   │  AZURE_CLIENT_ID, AZURE_TENANT_ID           │ │
-│                                   │  AZURE_SUBSCRIPTION_ID → Default Sub        │ │
-│                                   └─────────────────────────────────────────────┘ │
-└──────────────────────────┬───────────────────────────────────────────────────────┘
-                           │ OIDC token exchange
-                           ▼
-┌──────────────────────────────────────────────────────────────────────────────────┐
-│                            Entra ID (Azure AD)                                    │
-│                                                                                   │
-│  App Registration: sp-git-ape-{repo}                                            │
-│  ┌────────────────────────────────────────────────────────┐                       │
-│  │ Federated Credentials:                                 │                       │
-│  │   • repo:org/repo:ref:refs/heads/main                  │                       │
-│  │   • repo:org/repo:pull_request                         │                       │
-│  │   • repo:org/repo:environment:azure-deploy-dev         │                       │
-│  │   • repo:org/repo:environment:azure-deploy-staging     │                       │
-│  │   • repo:org/repo:environment:azure-deploy-prod        │                       │
-│  │   • repo:org/repo:environment:azure-destroy            │                       │
-│  └────────────────────┬───────────────────────────────────┘                       │
-└───────────────────────┼──────────────────────────────────────────────────────────┘
-                        │ Service Principal (shared)
-          ┌─────────────┼─────────────┐
-          ▼             ▼             ▼
-┌──────────────┐ ┌──────────────┐ ┌──────────────┐
-│  Dev Sub     │ │ Staging Sub  │ │  Prod Sub    │
-│  Contributor │ │ Contributor  │ │ Contributor + │
-│              │ │              │ │ UAA           │
-│ ┌──────────┐ │ │ ┌──────────┐ │ │ ┌──────────┐ │
-│ │ rg-*-dev │ │ │ │ rg-*-stg │ │ │ │ rg-*-prod│ │
-│ └──────────┘ │ │ └──────────┘ │ │ └──────────┘ │
-└──────────────┘ └──────────────┘ └──────────────┘
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#64748b','textColor':'#1e293b','primaryTextColor':'#0f172a','edgeLabelBackground':'#f8fafc','tertiaryColor':'#f1f5f9'}}}%%
+graph TD
+    subgraph GH["GitHub Repository"]
+        direction TB
+        REPO["<b>Repo-level Secrets</b><br/>AZURE_CLIENT_ID<br/>AZURE_TENANT_ID"]
+        EDEV["<b>azure-deploy-dev</b><br/>SUBSCRIPTION_ID → Dev"]
+        ESTG["<b>azure-deploy-staging</b><br/>SUBSCRIPTION_ID → Staging"]
+        EPRD["<b>azure-deploy-prod</b><br/>SUBSCRIPTION_ID → Prod<br/>⚠️ Required reviewers"]
+        EDST["<b>azure-destroy</b><br/>SUBSCRIPTION_ID → Default"]
+    end
+
+    subgraph ENTRA["Microsoft Entra ID"]
+        APP["<b>App Registration</b><br/>sp-git-ape-{repo}"]
+        FC["<b>Federated Credentials</b><br/>• ref:refs/heads/main<br/>• pull_request<br/>• environment:azure-deploy-dev<br/>• environment:azure-deploy-staging<br/>• environment:azure-deploy-prod<br/>• environment:azure-destroy"]
+        APP --- FC
+    end
+
+    DEV["<b>Dev Subscription</b><br/>Contributor<br/>rg-*-dev"]
+    STG["<b>Staging Subscription</b><br/>Contributor<br/>rg-*-stg"]
+    PRD["<b>Prod Subscription</b><br/>Contributor + UAA<br/>rg-*-prod"]
+
+    REPO --- EDEV
+    REPO --- ESTG
+    REPO --- EPRD
+    REPO --- EDST
+
+    EDEV -->|"OIDC"| FC
+    ESTG -->|"OIDC"| FC
+    EPRD -->|"OIDC"| FC
+    EDST -->|"OIDC"| FC
+
+    APP -->|"Service Principal"| DEV
+    APP -->|"Service Principal"| STG
+    APP -->|"Service Principal"| PRD
+
+    classDef gh fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91
+    classDef ghprod fill:#fde68a,stroke:#b45309,stroke-width:2px,color:#7c2d12
+    classDef entra fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#4c1d95
+    classDef azure fill:#dcfce7,stroke:#15803d,stroke-width:1px,color:#14532d
+    classDef azureprod fill:#fecaca,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d
+
+    class REPO,EDEV,ESTG,EDST gh
+    class EPRD ghprod
+    class APP,FC entra
+    class DEV,STG azure
+    class PRD azureprod
 ```
 
 ---
diff --git a/website/docs/intro.md b/website/docs/intro.md
index 71a541f..ef26676 100644
--- a/website/docs/intro.md
+++ b/website/docs/intro.md
@@ -25,6 +25,7 @@ Git-Ape is a **platform engineering framework** built on GitHub Copilot. It prov
 ## 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/>deploy a Python function app"]
     U --> S1
@@ -41,6 +42,18 @@ graph TD
     S3["Stage 3: Deploy"]
     S3 --> S4
     S4["Stage 4: Validate & Test"]
+
+    classDef user fill:#e0e7ff,stroke:#4338ca,stroke-width:2px,color:#1e1b4b
+    classDef stage fill:#dbeafe,stroke:#1f6feb,stroke-width:1px,color:#0b3d91
+    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 stage
+    class GATE,CONFIRM gate
+    class FIX fix
+    class S3,S4 deploy
 ```
 
 ## Execution Modes
diff --git a/website/docs/skills/azure-integration-tester.md b/website/docs/skills/azure-integration-tester.md
index e229187..f11a9f6 100644
--- a/website/docs/skills/azure-integration-tester.md
+++ b/website/docs/skills/azure-integration-tester.md
@@ -48,7 +48,7 @@ Parse deployment outputs to identify resource types:
 
 **For Function Apps:**
 
-Execute [test-function-app.sh](./scripts/test-function-app.sh):
+Execute [test-function-app.sh](https://github.com/Azure/git-ape/blob/main/.github/skills/azure-integration-tester/scripts/test-function-app.sh):
 ```bash
 ./scripts/test-function-app.sh \
   --url "https://func-api-dev-eastus.azurewebsites.net" \
@@ -66,7 +66,7 @@ Tests performed:
 
 **For Storage Accounts:**
 
-Execute [test-storage.sh](./scripts/test-storage.sh):
+Execute [test-storage.sh](https://github.com/Azure/git-ape/blob/main/.github/skills/azure-integration-tester/scripts/test-storage.sh):
 ```bash
 ./scripts/test-storage.sh \
   --account-name "stwebappdev8k3m" \
@@ -83,7 +83,7 @@ Tests performed:
 
 **For Databases:**
 
-Execute [test-database.sh](./scripts/test-database.sh):
+Execute [test-database.sh](https://github.com/Azure/git-ape/blob/main/.github/skills/azure-integration-tester/scripts/test-database.sh):
 ```bash
 ./scripts/test-database.sh \
   --type "sqldb" \
@@ -182,13 +182,13 @@ Your Azure resources are deployed and verified. You can now:
 
 All test scripts are located in the `./scripts/` directory:
 
-- [test-function-app.sh](./scripts/test-function-app.sh) - Function App health checks
-- [test-storage.sh](./scripts/test-storage.sh) - Storage Account connectivity
-- [test-database.sh](./scripts/test-database.sh) - Database connection tests
+- [test-function-app.sh](https://github.com/Azure/git-ape/blob/main/.github/skills/azure-integration-tester/scripts/test-function-app.sh) - Function App health checks
+- [test-storage.sh](https://github.com/Azure/git-ape/blob/main/.github/skills/azure-integration-tester/scripts/test-storage.sh) - Storage Account connectivity
+- [test-database.sh](https://github.com/Azure/git-ape/blob/main/.github/skills/azure-integration-tester/scripts/test-database.sh) - Database connection tests
 
 ## Common Test Patterns
 
-See [test-patterns.md](./references/test-patterns.md) for detailed test patterns including:
+See [test-patterns.md](https://github.com/Azure/git-ape/blob/main/.github/skills/azure-integration-tester/references/test-patterns.md) for detailed test patterns including:
 - Retry logic for transient failures
 - Health endpoint formats
 - Connection string handling
diff --git a/website/docs/skills/azure-naming-research.md b/website/docs/skills/azure-naming-research.md
index 67b3f29..da5e348 100644
--- a/website/docs/skills/azure-naming-research.md
+++ b/website/docs/skills/azure-naming-research.md
@@ -53,7 +53,7 @@ Find the section matching the resource provider namespace from step 1. Extract:
 
 ### 3. Derive field values
 
-See [references/regex-patterns.md](references/regex-patterns.md) for the regex conversion tables.
+See [references/regex-patterns.md](https://github.com/Azure/git-ape/blob/main/.github/skills/azure-naming-research/references/regex-patterns.md) for the regex conversion tables.
 
 - **scope** mapping: "globally unique"→`"global"`, "resource group"→`"resourceGroup"`, "within parent"→`"parent"`, "subscription"→`"subscription"`
 - **dashes**: `true` if hyphens allowed
diff --git a/website/docs/skills/git-ape-onboarding.md b/website/docs/skills/git-ape-onboarding.md
index c27de71..afa6b8a 100644
--- a/website/docs/skills/git-ape-onboarding.md
+++ b/website/docs/skills/git-ape-onboarding.md
@@ -112,7 +112,9 @@ OIDC_PREFIX="repository_owner_id:<OWNER_ID>:repository_id:<REPO_ID>"
 7. Set GitHub repo or environment secrets.
 8. Create GitHub environments and branch policies when permissions allow.
 9. Capture compliance and Azure Policy preferences (see below).
-10. Verify federated credentials, role assignments, and secrets.
+10. Collect explicit acknowledgments for experimental status and production safety.
+11. Activate workflows by renaming `.exampleyml` to `.yml` (only if all acknowledgments confirmed; see Step 11 section below).
+12. Verify federated credentials, role assignments, secrets, and workflow activation.
 
 ### Step 9: Compliance & Azure Policy Preferences
 
@@ -139,13 +141,75 @@ After RBAC and environment setup, ask the user about compliance requirements and
    - Set the `### Policy Enforcement Mode` default to the user's choice
    - Commit the update as part of the onboarding changes
 
+### Step 11: Activate GitHub Workflows
+
+After collecting acknowledgments for experimental status and production safety (see agent's "Acknowledgment Phase"), activate the Git-Ape workflows by renaming `.exampleyml` files to `.yml` in the `.github/workflows/` directory.
+
+**Files to activate:**
+- `git-ape-plan.exampleyml` → `git-ape-plan.yml` (validates template and shows what-if)
+- `git-ape-deploy.exampleyml` → `git-ape-deploy.yml` (executes deployments)
+- `git-ape-destroy.exampleyml` → `git-ape-destroy.yml` (tears down resources)
+- `git-ape-verify.exampleyml` → `git-ape-verify.yml` (runs verification steps)
+
+**Rename commands (Unix/macOS/Linux):**
+```bash
+cd .github/workflows
+for f in *.exampleyml; do
+  target="${f%.exampleyml}.yml"
+  mv "$f" "$target"
+  echo "Renamed: $f -> $target"
+done
+```
+
+**Rename commands (Windows PowerShell):**
+```powershell
+cd .github\workflows
+Get-ChildItem *.exampleyml | ForEach-Object {
+  $newName = $_.Name -replace '\.exampleyml$', '.yml'
+  Rename-Item -Path $_.FullName -NewName $newName
+  Write-Host "Renamed: $($_.Name) -> $newName"
+}
+```
+
+**Verification (all platforms):**
+```bash
+ls .github/workflows/git-ape-*.yml
+```
+
+Should output:
+```
+git-ape-deploy.yml
+git-ape-destroy.yml
+git-ape-plan.yml
+git-ape-verify.yml
+```
+
+**Output after activation:**
+Display summary:
+```
+✅ Workflows activated:
+  - git-ape-plan.yml (validates and plans deployments)
+  - git-ape-deploy.yml (executes deployments and integration tests)
+  - git-ape-destroy.yml (tears down resources when requested)
+  - git-ape-verify.yml (runs post-deployment verification)
+
+Next steps:
+1. Review .github/workflows/git-ape-*.yml for familiarity
+2. Push changes to a feature branch and open a PR
+3. Verify the plan workflow runs and shows what-if analysis in the PR comment
+4. For first deployment, merge to main and monitor git-ape-deploy.yml execution
+```
+
 ## Safe-Execution Rules
 
 1. Echo target repository and subscription(s) before execution.
 2. Require explicit user confirmation before running onboarding.
 3. Never print secret values in chat output.
-4. Summarize what was created or updated (app registration, federated credentials, role assignments, GitHub environments).
-5. If onboarding fails, surface the failing step and command context, then stop.
+4. **Require explicit acknowledgments before activating workflows** — User must confirm Git-Ape is experimental, will review plans, and won't deploy to production.
+5. **Only activate workflows if ALL acknowledgments are confirmed** — Renaming happens only after explicit "Yes" to all three questions.
+6. If user refuses any acknowledgment, complete onboarding but skip workflow activation. User can enable later manually.
+7. Summarize what was created or updated (app registration, federated credentials, role assignments, GitHub environments, workflows activated).
+8. If onboarding fails, surface the failing step and command context, then stop.
 
 ## Suggested Agent Flow
 
@@ -153,10 +217,13 @@ After RBAC and environment setup, ask the user about compliance requirements and
 2. Confirm target repo URL, onboarding mode, and role model.
 3. Validate current Azure/GitHub auth context (subscription, tenant, GitHub org).
 4. Ask for final confirmation.
-5. Execute the required Azure CLI and GitHub CLI commands directly from this playbook.
+5. Execute the required Azure CLI and GitHub CLI commands directly from this playbook (Steps 1-8).
 6. Ask compliance framework and enforcement mode preferences (Step 9 in playbook).
 7. Update `copilot-instructions.md` with compliance preferences.
-8. Summarize outcome and suggest verification commands.
+8. **Display experimental warning and collect acknowledgments** (three explicit "Yes" answers required).
+9. If all acknowledgments confirmed, execute workflow activation (Step 11 in playbook).
+10. If any acknowledgment refused, skip workflow activation (workflows remain `.exampleyml`).
+11. Summarize outcome, activated workflows (if any), and suggest verification commands.
 
 ## Known Gotchas
 
diff --git a/website/docs/skills/prereq-check.md b/website/docs/skills/prereq-check.md
index 9b87ea7..9c86994 100644
--- a/website/docs/skills/prereq-check.md
+++ b/website/docs/skills/prereq-check.md
@@ -24,12 +24,12 @@ description: "Check that all required CLI tools are installed, meet minimum vers
 
 # 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?"
 
@@ -158,7 +158,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
 
@@ -182,7 +182,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`.
 
@@ -191,4 +191,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`).
diff --git a/website/docs/workflows/overview.md b/website/docs/workflows/overview.md
index ae39b00..2204329 100644
--- a/website/docs/workflows/overview.md
+++ b/website/docs/workflows/overview.md
@@ -15,10 +15,8 @@ Git-Ape provides GitHub Actions workflows for automated deployment lifecycle man
 
 | Workflow | File | Triggers | Jobs |
 |----------|------|----------|------|
-| [Git-Ape: Deploy](./git-ape-deploy) | `git-ape-deploy.yml` | push, issue_comment | check-comment-trigger, detect-deployments, deploy |
-| [Git-Ape: Destroy](./git-ape-destroy) | `git-ape-destroy.yml` | push, workflow_dispatch | detect-destroys, destroy |
-| [Git-Ape: Plan](./git-ape-plan) | `git-ape-plan.yml` | pull_request | detect-deployments, plan-local, plan-azure, plan-comment |
-| [Git-Ape: Verify Setup](./git-ape-verify) | `git-ape-verify.yml` | workflow_dispatch | verify |
+| [Git-Ape: Docs Check](./git-ape-docs-check) | `git-ape-docs-check.yml` | pull_request | check-docs |
+| [Git-Ape: Docs Deploy](./git-ape-docs) | `git-ape-docs.yml` | push | build, deploy |
 
 ## Pipeline Architecture