docs: Replace vteam references with ACP naming

.gitignore

@@ -136,3 +136,7 @@ e2e/langfuse/.env.langfuse-keys
 # Test Reporting
 logs/
 reports/
+
+# Security scan artifacts (transient)
+.security-scan/
+.security-scan.zip

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 The **Ambient Code Platform** is a Kubernetes-native AI automation platform that orchestrates intelligent agentic sessions through containerized microservices. The platform enables AI-powered automation for analysis, research, development, and content creation tasks via a modern web interface.
 
-> **Note:** This project was formerly known as "vTeam". Technical artifacts (image names, namespaces, API groups) still use "vteam" for backward compatibility.
+> **Note:** This project was formerly known as "vTeam". Technical artifacts (image names, namespaces, API groups, routes) still use "vteam" for backward compatibility. The docs use ACP naming.
 
 ### Amber Background Agent
 

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
 
 ```

docs/SECURITY_DEV_MODE.md

@@ -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
+        "vteam-dev",         // Local dev namespace
     }
 
     namespace := os.Getenv("NAMESPACE")

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

docs/api/gitlab-endpoints.md

@@ -1,6 +1,6 @@
 # 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
 
@@ -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**:
@@ -53,7 +53,7 @@ Authorization: Bearer <vteam-auth-token>
 ```bash
 curl -X POST http://vteam-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>"
+  -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>"
+  -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
@@ -372,7 +372,7 @@ When GitLab token validation fails, error messages include specific remediation:
 
 ```bash
 curl -X GET http://vteam-backend:8080/api/auth/gitlab/status \
-  -H "Authorization: Bearer $VTEAM_TOKEN"
+  -H "Authorization: Bearer $ACP_TOKEN"
 ```
 
 Response:
@@ -385,7 +385,7 @@ Response:
 ```bash
 curl -X POST http://vteam-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"
@@ -408,7 +408,7 @@ Response:
 
 ```bash
 curl -X GET http://vteam-backend:8080/api/auth/gitlab/status \
-  -H "Authorization: Bearer $VTEAM_TOKEN"
+  -H "Authorization: Bearer $ACP_TOKEN"
 ```
 
 Response:
@@ -425,7 +425,7 @@ Response:
 
 ```bash
 curl -X POST http://vteam-backend:8080/api/auth/gitlab/disconnect \
-  -H "Authorization: Bearer $VTEAM_TOKEN"
+  -H "Authorization: Bearer $ACP_TOKEN"
 ```
 
 Response:
@@ -444,7 +444,7 @@ Response:
 # Connect to self-hosted instance
 curl -X POST http://vteam-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"

docs/build-metadata.md

@@ -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:    [email protected]
 ==============================================

docs/component-structure.mmd

@@ -0,0 +1,69 @@
+---
+title: Ambient Code Platform - Component Structure & Development Flow
+---
+
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor': '#e5e7eb', 'primaryTextColor': '#1f2937', 'primaryBorderColor': '#9ca3af', 'lineColor': '#6b7280', 'secondaryColor': '#f3f4f6', 'tertiaryColor': '#f9fafb'}}}%%
+
+graph LR
+    subgraph "📁 components/"
+        Frontend[frontend/<br/>NextJS + Shadcn UI<br/>🎨 Web Interface]
+        Backend[backend/<br/>Go API Service<br/>⚡ CRD Management]
+        Operator[operator/<br/>Kubernetes Operator<br/>⚙️ Go]
+        Runners[runners/<br/>AI Runner Services]
+        Manifests[manifests/<br/>K8s Deployments<br/>📋 YAML Files]
+
+        subgraph "runners/"
+            ClaudeRunner[claude-code-runner/<br/>Python Service<br/>🤖 MCP Integration]
+        end
+    end
+
+    subgraph "Development Commands"
+        DevStart[make dev-start<br/>🚀 Complete Stack]
+        DevSync[make dev-sync<br/>♻️ Hot Reloading]
+        Deploy[make deploy<br/>📦 Production]
+        BuildPush[make build-all push-all<br/>🏗️ Container Images]
+    end
+
+    subgraph "Environments"
+        Local[Local Development<br/>Minikube + OpenShift]
+        Prod[Production<br/>OpenShift/K8s Cluster]
+    end
+
+    subgraph "Access Points"
+        FrontendURL[Frontend URL<br/>https://vteam-frontend-vteam-dev.apps-crc.testing]
+        BackendAPI[Backend API<br/>Authenticated]
+        Console[OpenShift Console<br/>Admin Access]
+    end
+
+    %% Development flow
+    DevStart --> Local
+    Local --> FrontendURL
+    Local --> BackendAPI
+    Local --> Console
+    DevSync -.->|File Sync| Local
+
+    %% Production flow
+    BuildPush --> Prod
+    Deploy --> Prod
+
+    %% Component relationships
+    Frontend <-->|API Calls| Backend
+    Backend <-->|Manages| Operator
+    Operator -->|Schedules| ClaudeRunner
+    Manifests -->|Defines| Frontend
+    Manifests -->|Defines| Backend
+    Manifests -->|Defines| Operator
+    Manifests -->|Defines| ClaudeRunner
+
+    %% Styling
+    classDef component fill:#ddd6fe,stroke:#9333ea,stroke-width:2px,color:#1f2937
+    classDef command fill:#fed7aa,stroke:#ea580c,stroke-width:2px,color:#1f2937
+    classDef env fill:#bbf7d0,stroke:#16a34a,stroke-width:2px,color:#1f2937
+    classDef access fill:#bfdbfe,stroke:#2563eb,stroke-width:2px,color:#1f2937
+    classDef runner fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#1f2937
+
+    class Frontend,Backend,Operator,Manifests component
+    class ClaudeRunner runner
+    class DevStart,DevSync,Deploy,BuildPush command
+    class Local,Prod env
+    class FrontendURL,BackendAPI,Console access