ambient-code · bobbravo2 · Dec 18, 2025
diff --git a/components/README.md b/components/README.md
@@ -4,6 +4,14 @@ This directory contains the core components of the Ambient Code Platform.
 
 See the main [README.md](../README.md) for complete documentation, deployment instructions, and usage examples.
 
+## 📊 Architecture Diagrams
+
+View the platform architecture in detail:
+- [Platform Architecture](../docs/platform-architecture.mmd) - Overall system architecture and data flow
+- [Component Structure](../docs/component-structure.mmd) - Directory structure and development workflow
+- [Agentic Session Flow](../docs/agentic-session-flow.mmd) - Detailed sequence diagram of session execution
+- [Deployment Stack](../docs/deployment-stack.mmd) - Technology stack and deployment options
+
 ## Component Directory Structure
 
 ```
@@ -41,7 +49,7 @@ make dev-start
 
 **What you get:**
 - ✅ Complete OpenShift development environment
-- ✅ Frontend: `https://vteam-frontend-vteam-dev.apps-crc.testing`
+- ✅ Frontend: `https://acp-frontend-acp-dev.apps-crc.testing`
 - ✅ Backend API working with authentication
 - ✅ OpenShift console access
 - ✅ Ready for project creation and agentic sessions

diff --git a/docs/LOCAL_DEVELOPMENT.md b/docs/LOCAL_DEVELOPMENT.md
@@ -140,10 +140,10 @@ make local-delete            # Delete minikube cluster
 2. Rebuild images:
    ```bash
    # Build with Podman (default)
-   podman build -t vteam-backend:latest components/backend
+   podman build -t acp-backend:latest components/backend
 
    # Load into minikube
-   minikube image load vteam-backend:latest
+   minikube image load acp-backend:latest
    ```
 3. Restart deployment:
    ```bash

diff --git a/docs/SECURITY_DEV_MODE.md b/docs/SECURITY_DEV_MODE.md
@@ -64,13 +64,13 @@ func isLocalDevEnvironment() bool {
 
 ### 🟢 **MITIGATED: Allow-List Namespace Validation**
 
-**Current:** Uses allow-list of specific namespaces (ambient-code, vteam-dev)
+**Current:** Uses allow-list of specific namespaces (ambient-code, acp-dev)
 
 **Protection:**
 ```bash
 # Would PASS (correctly enable dev mode):
 NAMESPACE=ambient-code DISABLE_AUTH=true ENVIRONMENT=local  # ✅ Allowed
-NAMESPACE=vteam-dev DISABLE_AUTH=true ENVIRONMENT=local     # ✅ Allowed
+NAMESPACE=acp-dev DISABLE_AUTH=true ENVIRONMENT=local     # ✅ Allowed
 
 # Would FAIL (correctly reject):
 NAMESPACE=staging DISABLE_AUTH=true ENVIRONMENT=local       # ❌ Rejected
@@ -109,7 +109,7 @@ func isLocalDevEnvironment() bool {
     // ALLOW-LIST approach instead of DENY-LIST
     allowedNamespaces := []string{
         "ambient-code",    // Default minikube namespace
-        "vteam-dev",       // Legacy local dev namespace
+        "acp-dev",         // Local dev namespace
     }
 
     namespace := os.Getenv("NAMESPACE")

diff --git a/docs/adr/0003-multi-repo-support.md b/docs/adr/0003-multi-repo-support.md
@@ -71,7 +71,7 @@ Chosen option: "Multiple repos with mainRepoIndex", because:
 **AgenticSession Spec Structure:**
 
 ```yaml
-apiVersion: vteam.ambient-code/v1alpha1
+apiVersion: acp.ambient-code/v1alpha1
 kind: AgenticSession
 metadata:
   name: multi-repo-session

diff --git a/docs/agentic-session-flow.mmd b/docs/agentic-session-flow.mmd
@@ -0,0 +1,57 @@
+---
+title: Agentic Session Flow - Sequence Diagram
+---
+
+%%{init: {'theme':'dark', 'sequence': {'actorMargin': 50, 'participantMargin': 30, 'messageMargin': 30}}}%%
+
+sequenceDiagram
+    participant User as 👤 User
+    participant UI as 🎨 Frontend<br/>(NextJS)
+    participant API as ⚡ Backend API<br/>(Go)
+    participant K8s as ☸️ Kubernetes
+    participant Op as ⚙️ Operator<br/>(Go)
+    participant Job as 📋 K8s Job
+    participant Pod as 🏃 Execution Pod
+    participant AI as 🤖 Claude Runner<br/>(Python + MCP)
+    participant CR as 📄 Custom Resource<br/>(AgenticSession)
+
+    User->>UI: Create new agentic session
+    Note over UI: User specifies task<br/>and parameters
+
+    UI->>API: POST /sessions<br/>(session details)
+    Note over API: Validate request<br/>Create session object
+
+    API->>K8s: Create AgenticSession CR
+    K8s->>CR: Store Custom Resource
+    CR-->>API: CR created successfully
+    API-->>UI: Session ID returned
+    UI-->>User: Session created<br/>(show status)
+
+    Note over Op: Watching for new CRs
+    Op->>CR: Detect new AgenticSession
+    Op->>K8s: Create Kubernetes Job
+    K8s->>Job: Job scheduled
+
+    Job->>K8s: Request Pod creation
+    K8s->>Pod: Spawn execution pod
+    Note over Pod: Container with:<br/>- AI CLI<br/>- Playwright MCP server
+
+    Pod->>AI: Initialize Claude Runner
+    AI->>AI: Setup MCP capabilities
+    Note over AI: Browser automation<br/>Code execution<br/>File operations
+
+    AI->>Pod: Execute specified task
+    Note over Pod: Task execution<br/>using MCP tools
+
+    Pod->>CR: Store execution results
+    CR->>CR: Update status: completed
+
+    Op->>CR: Detect status change
+    Op->>K8s: Clean up Job
+
+    API->>CR: Poll for updates
+    CR-->>API: Return results
+    API-->>UI: Send results via WebSocket/polling
+    UI-->>User: Display completed session<br/>with results
+
+    Note over User: View results<br/>Download artifacts<br/>Create follow-up tasks
diff --git a/docs/api/gitlab-endpoints.md b/docs/api/gitlab-endpoints.md
@@ -1,11 +1,11 @@
 # GitLab Integration API Endpoints
 
-This document describes the GitLab integration API endpoints available in vTeam.
+This document describes the GitLab integration API endpoints available in ACP.
 
 ## Base URL
 
 ```
-http://vteam-backend:8080/api
+http://acp-backend:8080/api
 ```
 
 For production deployments, replace with your actual backend URL.
@@ -15,7 +15,7 @@ For production deployments, replace with your actual backend URL.
 All endpoints require authentication via Bearer token in the Authorization header:
 
 ```http
-Authorization: Bearer <your-vteam-auth-token>
+Authorization: Bearer <your-acp-auth-token>
 ```
 
 ---
@@ -24,14 +24,14 @@ Authorization: Bearer <your-vteam-auth-token>
 
 ### 1. Connect GitLab Account
 
-Connect a GitLab account to vTeam by providing a Personal Access Token.
+Connect a GitLab account to ACP by providing a Personal Access Token.
 
 **Endpoint**: `POST /auth/gitlab/connect`
 
 **Request Headers**:
 ```http
 Content-Type: application/json
-Authorization: Bearer <vteam-auth-token>
+Authorization: Bearer <acp-auth-token>
 ```
 
 **Request Body**:
@@ -51,9 +51,9 @@ Authorization: Bearer <vteam-auth-token>
 
 **Example Request**:
 ```bash
-curl -X POST http://vteam-backend:8080/api/auth/gitlab/connect \
+curl -X POST http://acp-backend:8080/api/auth/gitlab/connect \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer <vteam-token>" \
+  -H "Authorization: Bearer <acp-token>" \
   -d '{
     "personalAccessToken": "glpat-xyz123abc456",
     "instanceUrl": "https://gitlab.com"
@@ -114,13 +114,13 @@ Check if user has a GitLab account connected and retrieve connection details.
 
 **Request Headers**:
 ```http
-Authorization: Bearer <vteam-auth-token>
+Authorization: Bearer <acp-auth-token>
 ```
 
 **Example Request**:
 ```bash
-curl -X GET http://vteam-backend:8080/api/auth/gitlab/status \
-  -H "Authorization: Bearer <vteam-token>"
+curl -X GET http://acp-backend:8080/api/auth/gitlab/status \
+  -H "Authorization: Bearer <acp-token>"
 ```
 
 **Success Response (Connected)** (`200 OK`):
@@ -162,19 +162,19 @@ curl -X GET http://vteam-backend:8080/api/auth/gitlab/status \
 
 ### 3. Disconnect GitLab Account
 
-Disconnect GitLab account from vTeam and remove stored credentials.
+Disconnect GitLab account from ACP and remove stored credentials.
 
 **Endpoint**: `POST /auth/gitlab/disconnect`
 
 **Request Headers**:
 ```http
-Authorization: Bearer <vteam-auth-token>
+Authorization: Bearer <acp-auth-token>
 ```
 
 **Example Request**:
 ```bash
-curl -X POST http://vteam-backend:8080/api/auth/gitlab/disconnect \
-  -H "Authorization: Bearer <vteam-token>"
+curl -X POST http://acp-backend:8080/api/auth/gitlab/disconnect \
+  -H "Authorization: Bearer <acp-token>"
 ```
 
 **Success Response** (`200 OK`):
@@ -254,7 +254,7 @@ interface ConnectGitLabResponse {
 ```
 
 **Fields**:
-- `userId`: vTeam user ID
+- `userId`: ACP user ID
 - `gitlabUserId`: GitLab user ID (from GitLab API)
 - `username`: GitLab username
 - `instanceUrl`: GitLab instance URL (GitLab.com or self-hosted)
@@ -331,7 +331,7 @@ All error responses follow this format:
 | Status Code | Meaning | Common Causes |
 |-------------|---------|---------------|
 | 400 | Bad Request | Invalid request body, missing required fields |
-| 401 | Unauthorized | vTeam authentication token missing or invalid |
+| 401 | Unauthorized | ACP authentication token missing or invalid |
 | 500 | Internal Server Error | GitLab token validation failed, database error, network error |
 
 ### GitLab-Specific Errors
@@ -371,8 +371,8 @@ When GitLab token validation fails, error messages include specific remediation:
 #### 1. Check if Connected
 
 ```bash
-curl -X GET http://vteam-backend:8080/api/auth/gitlab/status \
-  -H "Authorization: Bearer $VTEAM_TOKEN"
+curl -X GET http://acp-backend:8080/api/auth/gitlab/status \
+  -H "Authorization: Bearer $ACP_TOKEN"
 ```
 
 Response:
@@ -383,9 +383,9 @@ Response:
 #### 2. Connect Account
 
 ```bash
-curl -X POST http://vteam-backend:8080/api/auth/gitlab/connect \
+curl -X POST http://acp-backend:8080/api/auth/gitlab/connect \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $VTEAM_TOKEN" \
+  -H "Authorization: Bearer $ACP_TOKEN" \
   -d '{
     "personalAccessToken": "'"$GITLAB_TOKEN"'",
     "instanceUrl": "https://gitlab.com"
@@ -407,8 +407,8 @@ Response:
 #### 3. Verify Connection
 
 ```bash
-curl -X GET http://vteam-backend:8080/api/auth/gitlab/status \
-  -H "Authorization: Bearer $VTEAM_TOKEN"
+curl -X GET http://acp-backend:8080/api/auth/gitlab/status \
+  -H "Authorization: Bearer $ACP_TOKEN"
 ```
 
 Response:
@@ -424,8 +424,8 @@ Response:
 #### 4. Disconnect (if needed)
 
 ```bash
-curl -X POST http://vteam-backend:8080/api/auth/gitlab/disconnect \
-  -H "Authorization: Bearer $VTEAM_TOKEN"
+curl -X POST http://acp-backend:8080/api/auth/gitlab/disconnect \
+  -H "Authorization: Bearer $ACP_TOKEN"
 ```
 
 Response:
@@ -442,9 +442,9 @@ Response:
 
 ```bash
 # Connect to self-hosted instance
-curl -X POST http://vteam-backend:8080/api/auth/gitlab/connect \
+curl -X POST http://acp-backend:8080/api/auth/gitlab/connect \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $VTEAM_TOKEN" \
+  -H "Authorization: Bearer $ACP_TOKEN" \
   -d '{
     "personalAccessToken": "glpat-selfhosted-token",
     "instanceUrl": "https://gitlab.company.com"
@@ -489,7 +489,7 @@ Required GitLab token scopes:
 2. **Rotate Tokens**: Encourage users to rotate GitLab tokens every 90 days
 3. **Minimum Scopes**: Only request required scopes
 4. **Token Expiration**: Set expiration dates on GitLab tokens
-5. **Secure vTeam Tokens**: Protect vTeam authentication tokens
+5. **Secure ACP Tokens**: Protect ACP authentication tokens
 
 ---
 
@@ -504,9 +504,9 @@ Required GitLab token scopes:
 
 Limits configured by GitLab administrator (may differ from GitLab.com).
 
-### vTeam Behavior
+### ACP Behavior
 
-- No rate limit enforcement on vTeam side
+- No rate limit enforcement on ACP side
 - GitLab API errors (429 Too Many Requests) passed through to user
 - Error messages include wait time recommendation
 
@@ -550,11 +550,11 @@ See examples throughout this document.
 
 ### "User not authenticated"
 
-**Cause**: vTeam authentication token missing or invalid
+**Cause**: ACP authentication token missing or invalid
 
 **Solution**:
 - Include `Authorization: Bearer <token>` header
-- Verify vTeam token is valid
+- Verify ACP token is valid
 - Check token hasn't expired
 
 ### "GitLab token validation failed: 401"

diff --git a/docs/build-metadata.md b/docs/build-metadata.md
@@ -44,7 +44,7 @@ podman build \
   --build-arg GIT_VERSION=v1.2.3-dirty \
   --build-arg BUILD_DATE=2025-12-15T10:30:00Z \
   --build-arg BUILD_USER=gkrumbac@MacBook \
-  -t vteam-backend:latest .
+  -t acp-backend:latest .
 ```
 
 ### 2. Build Time: Dockerfiles Embed Metadata as Environment Variables
@@ -131,7 +131,7 @@ Backend API - Build Information
 Version:     v1.2.3-dirty
 Commit:      abc123def456789...
 Branch:      feature/build-metadata
-Repository:  https://github.com/ambient-code/vteam.git
+Repository:  https://github.com/ambient-code/platform.git
 Built:       2025-12-15T10:30:45Z
 Built by:    gkrumbac@MacBook-Pro.local
 ==============================================
@@ -161,7 +161,7 @@ oc logs job/session-abc123 -n project-namespace | head -20
 
 ```bash
 # Using podman/docker
-podman run --rm vteam-backend:latest env | grep GIT
+podman run --rm acp-backend:latest env | grep GIT
 
 # In Kubernetes
 kubectl exec deployment/backend-api -n ambient-code -- env | grep GIT
@@ -172,7 +172,7 @@ kubectl exec deployment/backend-api -n ambient-code -- env | grep GIT
 You can also add this metadata as image labels for inspection without running the container:
 
 ```bash
-podman inspect vteam-backend:latest | jq '.[0].Config.Labels'
+podman inspect acp-backend:latest | jq '.[0].Config.Labels'
 ```
 
 ## Development Workflow