docs: review fixes, Mermaid architecture diagrams, licensing details, and troubleshooting playbooks

doc-server/docs/api-docs/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "API Docs",
-  "position": 5
+  "position": 8
 }

doc-server/docs/architecture.md

@@ -0,0 +1,143 @@
+---
+sidebar_position: 2
+sidebar_label: Architecture & System Design
+---
+
+# Architecture & System Design
+
+NudgeBee is an enterprise-grade AI observability, incident triage, and automation platform designed around a core philosophy: **"Install Once, Build Forever"** — where the marginal cost of running your $N$-th agent trends toward zero, and the compounding intelligence of the platform increases with every incident, metric, and workflow.
+
+---
+
+## 1. Platform Reference Architecture
+
+![NudgeBee Platform Reference Architecture](/img/platform_reference_architecture.png)
+
+---
+
+### Platform Architecture Reference (9-Layer Model)
+
+| Layer | Functional Domain | Key Capabilities & Components | Deployment Boundary |
+|---|---|---|---|
+| **Layer 1** | **Personas & Access** | SRE, DevOps, FinOps, SecOps, Platform, CFO via Web Dashboard, Slack/Teams ChatOps, CLI, REST/GraphQL APIs, and SSO. | User Interface |
+| **Layer 2** | **Role-Based Agents** | **AI-SRE** (RCA & triage), **AI-FinOps** (cost & rightsizing), **AI-K8sOps** (workload reliability), **AI-CloudOps** (cloud drift & scans), and Custom Agents. | In-VPC Control Plane |
+| **Layer 3** | **Builders** | **AI-Ops Automation Builder** (visual runbook/DAG composer) and **AI-Agent Builder** (agent definition & prompt harness). | In-VPC Control Plane |
+| **Layer 4** | **Control Plane (The Brain)** | • **Cortex Intelligence**: Knowledge Graph Engine, Multi-Tier Memory (Redis + Graph DB), RAG Vector Retrieval, Continuous Grounding.<br/>• **DAIR Router**: 8-Signal Model Router, Semantic Prompt Cache, PII/DLP Redaction Gate.<br/>• **Runtime & Guardrails**: Agent Harness (*Plan-Act-Observe*), Policy Engine, HITL Approval Surface, Immutable Audit Logs. | In-VPC Control Plane |
+| **Layer 5** | **Libraries ("Install Once, Build Forever")** | Library of Pre-Built Agents, Library of Diagnostic Tools/Skills, and Library of Automated Runbooks. | In-VPC Control Plane |
+| **Layer 6** | **In-VPC Data Plane** | PostgreSQL (metadata/config), Redis (sessions/cache), ClickHouse (runs/traces), Qdrant (RAG vectors), Graph DB (topology/ownership), Object Store (S3-compatible artifacts), RabbitMQ (event bus). | In-VPC Customer Data Plane |
+| **Layer 7** | **Self-Hosted SLM Serving** | Local private Small Language Model serving via **vLLM / Ollama / TGI** (Qwen 3+, Llama 3+, Gemma 4, Nemotron, Granite, BYOM GPU pools). | In-VPC Model Layer |
+| **Layer 8** | **Collectors & Ingress** | Relay Server (:8080), `k8s-collector`, `cloud-collector`, OpenTelemetry Collector, and Ticketing/GitOps Sync. | In-VPC & In-Cluster |
+| **Layer 9** | **Categorized External Egress** | Collaboration (Slack, Teams), ITSM (Jira, ServiceNow), SCM (GitHub, GitLab), Cloud APIs (AWS, GCP, Azure), Observability backends, and Frontier LLMs (via DAIR + PII Gate). | External Egress |
+
+---
+
+### Layer Deep-Dive
+
+#### Cortex • The Intelligence Layer
+Cortex is NudgeBee's semantic reasoning engine. Instead of passing massive, unstructured context to expensive LLMs, Cortex maintains a continuously updated model of your infrastructure:
+- **Knowledge Graph Engine**: Maps service dependencies, network topologies, infrastructure layers, and engineering team ownership.
+- **Multi-Tier Memory**: Combines millisecond short-term memory (Redis) for live alert context with persistent Graph DB memory for long-term historical incident learning.
+- **RAG Retrieval**: Combines dense vector search (Qdrant) with cross-encoder rerankers to ground AI responses in relevant runbooks, docs, and postmortems.
+- **Continuous Grounding**: Automatically updates context as pods deploy, git commits merge, or alert rules fire.
+
+#### DAIR • Dynamic Adaptive Inference Router
+DAIR optimizes every model invocation across 8 real-time signals: **task complexity, latency SLO, token cost, data sensitivity, cache hit status, model availability, context window size, and reasoning depth**.
+- **In-VPC SLM Serving First**: Simple tasks (log summarization, event classification, metric anomaly detection) are routed locally to private Small Language Models (e.g. Qwen 3+, Llama 3+, Gemma) running inside your cluster or VPC GPU pool.
+- **Semantic Prompt Cache**: Deduplicates repetitive prompts and queries to prevent redundant model calls.
+- **PII / DLP Redaction Gate**: Any query escalated to external frontier models (e.g. AWS Bedrock, OpenAI, Anthropic) passes through an inline DLP sanitizer to redact secrets, tokens, IPs, and user PII before leaving the VPC boundary.
+
+#### Runtime & Guardrails
+- **Agent Orchestrator**: Executes structured *Plan → Act → Observe → Evaluate* loops with bounded iteration limits.
+- **Policy Engine**: Enforces strict RBAC, blast-radius constraints, and mandatory dry-run execution for mutating operations.
+- **Human-In-The-Loop (HITL)**: Provides interactive approval gates directly within Slack, Microsoft Teams, and the Web UI before any remediation action is executed in production.
+- **Immutable Audit Log**: Every prompt, tool execution, intermediate reasoning step, and user approval is recorded immutably in PostgreSQL/ClickHouse.
+
+---
+
+## 2. Runtime Microservices Architecture ("What Runs Where")
+
+The diagram below illustrates how NudgeBee's core microservices, datastores, and collectors interact at runtime:
+
+```mermaid
+flowchart TB
+    classDef browser fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#78350f,rx:8,ry:8;
+    classDef app fill:#bae6fd,stroke:#0284c7,stroke-width:2px,color:#0369a1,rx:8,ry:8;
+    classDef backend fill:#bbf7d0,stroke:#16a34a,stroke-width:2px,color:#14532d,rx:8,ry:8;
+    classDef datastore fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#1e293b,rx:8,ry:8;
+    classDef collector fill:#ddd6fe,stroke:#7c3aed,stroke-width:2px,color:#4c1d95,rx:8,ry:8;
+    classDef agent fill:#fecdd3,stroke:#e11d48,stroke-dasharray: 5 5,stroke-width:2px,color:#881337,rx:8,ry:8;
+
+    BROWSER["<b>Browser</b>"]:::browser
+    APP["<b>app</b><br/><small>Next.js UI + auth boundary</small>"]:::app
+
+    subgraph SERVICES["Microservices (Internal RPC with tenant + user context stamped on every call)"]
+        direction TB
+        SERVICES_SERVER["<b>services-server</b><br/><small>Go core backend & GraphQL</small>"]:::backend
+        LLM_SERVER["<b>llm-server</b> (AI Engine)<br/><small>NuBi SRE Agents, RAG & AI Gateway</small>"]:::backend
+        WORKFLOW_SERVER["<b>workflow-server</b><br/><small>Autopilot & Runbook Automations</small>"]:::backend
+        NOTIFICATIONS["<b>notifications</b><br/><small>Slack / Teams / Email Dispatcher</small>"]:::backend
+        TICKET_SERVER["<b>ticket-server</b><br/><small>Jira / ServiceNow / PagerDuty</small>"]:::backend
+    end
+
+    subgraph STORAGE["Storage & Caching Layer (Shared by ALL services)"]
+        POSTGRES["<b>Postgres</b><br/><small>State & Audit</small>"]:::datastore
+        REDIS["<b>Redis</b><br/><small>Cache Layer</small>"]:::datastore
+    end
+
+    subgraph INFRA["Messaging, Vector & Durable Execution"]
+        RABBITMQ["<b>RabbitMQ</b><br/><small>Event Bus & Signal Broker</small>"]:::datastore
+        QDRANT["<b>Qdrant</b><br/><small>RAG Vectors & Knowledge Embeddings</small>"]:::datastore
+        TEMPORAL["<b>Temporal</b><br/><small>Durable Workflow Execution</small>"]:::datastore
+    end
+
+    subgraph COLLECTORS["Collectors & Ingress Hub"]
+        K8S_COLLECTOR["<b>k8s-collector</b><br/><small>Cluster state & metrics</small>"]:::collector
+        CLOUD_COLLECTOR["<b>cloud-collector</b><br/><small>AWS / Azure / GCP scans</small>"]:::collector
+        RELAY_SERVER["<b>relay-server</b><br/><small>WebSocket Gateway (:8080)</small>"]:::collector
+    end
+
+    AGENT["<b>nudgebee-agent (in YOUR cluster)</b><br/><small>kubectl • Prometheus • Logs & Traces</small>"]:::agent
+
+    BROWSER --> APP
+    APP --> SERVICES_SERVER
+    APP --> LLM_SERVER
+    APP --> WORKFLOW_SERVER
+    APP --> NOTIFICATIONS
+    APP --> TICKET_SERVER
+
+    SERVICES_SERVER -.-> STORAGE
+    LLM_SERVER -.-> STORAGE
+    WORKFLOW_SERVER -.-> STORAGE
+    NOTIFICATIONS -.-> STORAGE
+    TICKET_SERVER -.-> STORAGE
+
+    LLM_SERVER -->|vector search| QDRANT
+    WORKFLOW_SERVER -->|durable execution| TEMPORAL
+
+    K8S_COLLECTOR -->|signals| RABBITMQ
+    CLOUD_COLLECTOR -->|signals| RABBITMQ
+    RELAY_SERVER -->|signals| RABBITMQ
+    RABBITMQ --> SERVICES_SERVER
+
+    K8S_COLLECTOR -.-> STORAGE
+    CLOUD_COLLECTOR -.-> STORAGE
+    RELAY_SERVER -.-> STORAGE
+
+    AGENT -.->|"outbound only (WSS :443)"| RELAY_SERVER
+```
+
+---
+
+## 3. Data Privacy & Network Isolation
+
+- **Zero Inbound Ports**: Monitored agents connect to the Control Plane exclusively via outbound HTTPS / WSS (TCP port 443). No firewall openings or public IPs are required in monitored environments.
+- **In-VPC Data Sovereignty**: All cluster metrics, logs, traces, knowledge graph topologies, and audit trails remain within your dedicated storage cluster.
+- **Air-Gapped & Offline Ready**: NudgeBee can be deployed entirely air-gapped using local container registries, internal PostgreSQL/Redis, and in-VPC SLMs served by vLLM or Ollama.
+
+---
+
+## Next Steps
+
+- **[Server Installation Guide](/docs/installation/server/)** — Deploy the complete NudgeBee Control Plane onto your Kubernetes cluster using Helm.
+- **[Agent Installation Guide](/docs/installation/agent/)** — Install the lightweight NudgeBee Agent into target Kubernetes clusters.
+- **[Editions & Pricing](/docs/editions)** — Compare Community, Enterprise, and Cloud SaaS capabilities.

doc-server/docs/editions.md

@@ -1,20 +1,20 @@
 ---
-sidebar_position: 2
-sidebar_label: Editions & Pricing
+sidebar_position: 3
+sidebar_label: Editions & Capabilities
 ---
 
-# Editions
+# Editions & Capabilities
 
 NudgeBee is available in three editions. They share the same codebase and
 documentation — this page is the source of truth for what each one includes.
 
 | | **Community** <Community/> | **Enterprise** <Enterprise/> | **Cloud** <Cloud/> |
 |---|---|---|---|
-| **What it is** | Free, open-source (Apache 2.0), self-hosted. Fully functional. | Self-hosted with a commercial license. Adds enterprise features and support. | Fully managed SaaS, hosted and operated by NudgeBee. |
+| **What it is** | Free self-hosted edition. Server is licensed under **BSL 1.1**; Agents are **Apache 2.0**. Fully functional. | Self-hosted with a commercial license. Adds enterprise features and SLA support. | Fully managed SaaS, hosted and operated by NudgeBee. |
 | **Where it runs** | Your own Kubernetes cluster | Your own Kubernetes cluster | [app.nudgebee.com](https://app.nudgebee.com) |
 | **Container images** | Public — `ghcr.io/nudgebee` (no authentication) | Licensed — `registry.nudgebee.com` | Managed for you |
-| **License key** | Not required | Required | Not applicable |
-| **Cost** | Free | Paid (per-license) | Paid (subscription) |
+| **License key** | Not required | Required | Managed in cloud account |
+| **Licensing** | Free for internal production & operations | Commercial enterprise license | Commercial SaaS subscription |
 | **Best for** | Teams that want full control and a zero-cost, self-hosted deployment. | Organizations that need SAML SSO, NudgeBee's managed models, and commercial support while self-hosting. | Teams that want to start in minutes without managing infrastructure. |
 | **Support** | Community ([GitHub Issues & Discussions](https://github.com/nudgebee)) | Commercial support (SLA) | Commercial support (SLA) |
 
@@ -25,7 +25,7 @@ the Workflow Builder, and Autopilot all work out of the box. You can move to
 Enterprise or Cloud later without losing your configuration.
 :::
 
-## What's in the open-source (Community) edition
+## What's in the Community edition
 
 The Community edition is **fully functional** for self-hosted Kubernetes
 operations. It includes:
@@ -64,10 +64,14 @@ per-feature badges are updated together so the docs always reflect what's
 actually gated.
 :::
 
-## Trademarks
+## Licensing & Trademarks
 
-NudgeBee is open source under the Apache 2.0 license, but the **NudgeBee name
-and logo are trademarks**. The Apache license does not grant trademark rights —
-in particular, modified builds and forks must be renamed. See the
-[trademark policy](https://github.com/nudgebee/nudgebee-docs/blob/main/TRADEMARKS.md)
-for what's allowed.
+- **NudgeBee Server**: Licensed under the **Business Source License 1.1 (BSL 1.1)**. Free for non-competing production and internal operations, automatically converting to open source under Apache 2.0 after its change date.
+- **NudgeBee Agents & Ecosystem**: The Kubernetes Agent ([k8s-agent](https://github.com/nudgebee/k8s-agent)) and Proxy Agent ([forager](https://github.com/nudgebee/forager)) are licensed under the **Apache 2.0 License**.
+- **Trademarks**: The **NudgeBee name and logo are trademarks**. The licenses do not grant trademark rights — modified builds and forks must be renamed. See the [trademark policy](https://github.com/nudgebee/nudgebee-docs/blob/main/TRADEMARKS.md) for what is allowed.
+
+---
+
+## Commercial Inquiries & Pricing
+
+For commercial licensing, enterprise SLAs, volume discounts, and Cloud subscription pricing, visit the [NudgeBee Pricing Page](https://nudgebee.com/pricing) or contact our sales team at [sales@nudgebee.com](mailto:sales@nudgebee.com).

doc-server/docs/features/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Features",
-  "position": 2
+  "position": 6
 }

doc-server/docs/features/optimizations.md

@@ -50,8 +50,8 @@ graph LR
 
 ### How to Raise Automated PRs
 
-1. Connect your repository under **Admin $\rightarrow$ Integrations $\rightarrow$ Code Repositories** ([GitHub](../integrations/Code%20Repository/GitHub/github-integration.md) or [GitLab](../integrations/Code%20Repository/GitLab/gitlab-integration.md)).
-2. Navigate to **Optimizations $\rightarrow$ Workload Right-Sizing**.
+1. Connect your repository under **Admin → Integrations → Code Repositories** ([GitHub](../integrations/Code%20Repository/GitHub/github-integration.md) or [GitLab](../integrations/Code%20Repository/GitLab/gitlab-integration.md)).
+2. Navigate to **Optimizations → Workload Right-Sizing**.
 3. Select the target deployment or StatefulSet.
 4. Click **Create Pull Request**.
 5. NudgeBee creates a new branch, updates the Helm `values.yaml` or Terraform manifest with the recommended CPU/memory requests and limits, and opens a Pull Request with a clear rationale table for your engineering team to review.

doc-server/docs/index.md

@@ -87,6 +87,26 @@ NudgeBee has two components, both packaged as Helm charts that deploy natively o
 **Self-hosted users**: You need a dedicated Kubernetes cluster (or namespace) to run the NudgeBee Server before connecting your monitored clusters. Sizing typically requires a 2-node cluster with 16 GB RAM and 4 cores per node. If you do not have Kubernetes clusters to run the server on, choose **Cloud SaaS**.
 :::
 
+### Architecture at a Glance
+
+```mermaid
+flowchart LR
+    classDef infra fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af,rx:8,ry:8;
+    classDef platform fill:#f5f3ff,stroke:#8b5cf6,stroke-width:2px,color:#5b21b6,rx:8,ry:8;
+    classDef integ fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#065f46,rx:8,ry:8;
+
+    INFRA["<b>Monitored Infrastructure</b><br/><small>• Kubernetes Clusters<br/>• VMs & Bare Metal<br/>• Cloud Provider Accounts</small>"]:::infra
+    PLATFORM["<b>NudgeBee Platform</b><br/><small>• Cortex Intelligence & Graph<br/>• DAIR Adaptive Router & SLMs<br/>• SRE Agents & Autopilot Runbooks</small>"]:::platform
+    INTEG["<b>Actions & Integrations</b><br/><small>• Slack / Teams Incident Triage<br/>• Jira / PagerDuty Sync<br/>• Automated GitOps PRs</small>"]:::integ
+
+    INFRA -->|"Outbound Telemetry (WSS :443)"| PLATFORM
+    PLATFORM -->|"Alerts, Insights & Auto-PRs"| INTEG
+```
+
+:::tip Deep-Dive: Platform Reference Architecture
+For an in-depth breakdown of the 9-layer enterprise architecture (including the **Cortex Intelligence Layer**, **DAIR Adaptive Model Router**, in-VPC data plane, and runtime microservices), explore our dedicated **[Architecture & System Design Guide](./architecture.md)**.
+:::
+
 ### Connecting Your Infrastructure
 
 Once the server is running (or you have signed up for SaaS), connect your infrastructure:

doc-server/docs/installation/_category_.json

@@ -1 +1 @@
-{"label": "Installation", "position": 3}
+{"label": "Installation", "position": 5}