nudgebee
diff --git a/‎doc-server/README.md‎
Lines changed: 24 additions & 28 deletions b/‎doc-server/README.md‎
Lines changed: 24 additions & 28 deletions
diff --git a/‎doc-server/docs/FAQ.md‎
Lines changed: 53 additions & 71 deletions b/‎doc-server/docs/FAQ.md‎
Lines changed: 53 additions & 71 deletions
@@ -1,41 +1,37 @@
-# Website
+# NudgeBee Documentation
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This repository hosts the official documentation for [NudgeBee](https://nudgebee.com), built using [Docusaurus 3](https://docusaurus.io/).
 
-### Installation
+## Prerequisites
 
-```
-$ npm install
-```
+- **Node.js**: v18.0.0 or higher
+- **npm**: v9.0.0 or higher
 
-### Local Development
+## Local Development
 
-```
-$ npm start
-```
+1. **Install dependencies**:
+   ```bash
+   npm install
+   ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+2. **Start the local dev server**:
+   ```bash
+   npm start
+   ```
+   This command starts the local development server at `http://localhost:3000` (or `http://localhost:4000`). Edits in `docs/` reflect live via hot-reloading.
 
-### Build
-
-```
-$ npm run build
-```
+## Production Build
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+To verify and generate static assets:
 
-### Deployment
-
-Using SSH:
-
-```
-$ USE_SSH=true npm run deploy
+```bash
+npm run build
 ```
 
-Not using SSH:
+The compiled output will be generated inside the `build/` directory.
 
-```
-$ GIT_USER=<Your GitHub username> npm run deploy
-```
+To preview the production build locally:
 
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+```bash
+npm run serve
+```
@@ -7,15 +7,16 @@ sidebar_position: 100
 ### What are the open-source tools that NudgeBee uses?
 
 #### Agent
-- Prometheus (or VictoriaMetrics) - Metrics Collection and alerting
-- OpenCost for calculating cost metrics for Pods/Workloads etc.
-- Trivy for generating Docker image vulnerability related security recommendations
-- Popeye for generating best practices related recommendations
-- Kubewatch for K8s events collection
+- **Prometheus** (or VictoriaMetrics) — Metrics collection and alerting
+- **Logs Engine** (Loki / OpenObserve / Elasticsearch / Fluentbit) — Log querying and stream aggregation
+- **Distributed Tracing** (OpenTelemetry Collector / ClickHouse / Tempo) — Distributed tracing
+- **Trivy** — Container image vulnerability scanning
+- **Popeye** — Kubernetes cluster sanitizing and best practice audits
+- **Kubewatch** — Kubernetes event streaming and lifecycle capture
 
 ### What are the ML libraries that NudgeBee uses? What are the dependencies?
-- TensorFlow for recommendations for replicas
-- AWS Bedrock using LLAMA (optional) for AI-based recommendations on logs/errors
+- **TensorFlow & Scikit-learn** — Predictive analytics for workload replica and resource rightsizing
+- **Cortex & DAIR Router** — In-VPC Small Language Model serving (vLLM / Ollama) with optional routing to AWS Bedrock, OpenAI, Anthropic, or Google Gemini
 
 ### What are the hard dependencies for the NudgeBee Server?
 - **PostgreSQL**: Hard requirement. Stores cluster configurations, user metadata, alert rules, and workflow states. Queries and services fail without it.
@@ -27,128 +28,109 @@ sidebar_position: 100
 - **The Agent** is required inside each cluster to collect real-time workload metrics, stream pod logs, capture eBPF network telemetry, and perform automated AI root cause analysis.
 - For full AI troubleshooting and cost optimizations on a cluster, installing the Agent is required.
 
-### What are the pre-conditions(software/hardware) for installing NudgeBee on my cluster?
+### What are the pre-conditions (software/hardware) for installing NudgeBee on my cluster?
 
 #### For Agent:
-- Helm chart for installation
-- Prometheus, if already configured, else NudgeBee agent installs it
-- Currently, NudgeBee uses Loki for log queries. For log-specific features, we will require Loki running on the cluster. We don't provide Loki as part of the Agent Installer.
-- Permissions as specified in Helm charts
+- Helm 3.10+ and Kubernetes 1.24+
+- Existing Prometheus instance (or install bundled Prometheus via Helm)
+- For log-specific triage: Existing log aggregator (Loki, Elasticsearch, OpenObserve) or cluster log access
+- Standard cluster RBAC permissions as specified in the Helm chart
 
-### What is the typical system requirement for running NB on my cluster? What is the expected cost of operations for running the base NudgeBee
+### What is the typical system requirement for running NudgeBee?
 
 #### For Agent:
-Agent has multiple components. All of them combined take around 6GB memory and 3 core CPUs
-This also includes Prometheus(Alertmanager/KubestateMetrics)
-If we remove Prometheus components, then it takes around 3GB and 2 cores
+- **Core Agent (Runner + Collector)**: Lightweight — requests **~200m CPU** and **256 MiB RAM**.
+- **Optional In-Cluster Monitoring Stack (Prometheus / Alertmanager / KSM)**: **~1–2 CPU cores** and **2–4 GB RAM** depending on metric cardinality.
+- **Node Agent (DaemonSet)**: **~50m CPU** and **64 MiB RAM** per worker node for eBPF and node telemetry.
 
 #### For Server:
-All server components take around 12GB RAM and 4 core CPUs
-This includes running postgres/rabbitmq etc. If the customer is managing these dependencies, then it will take around 8GB RAM and 2 core CPUs
+- **Evaluation / Small Install (Bundled Postgres & RabbitMQ)**: **~4 CPU cores** and **8–12 GB RAM** across all backend pods.
+- **Production Install (External Managed Databases)**: **~2–4 CPU cores** and **4–8 GB RAM** for NudgeBee application pods.
 
 ### How NudgeBee Optimizations Work with GitOps
 
-Raise PRs from NudgeBee
-- We have added support for raising PRs from specific optimization screens in NudgeBee.
-
-GitOps(Flux/Argo) Reconciliation
-- Disable reconciliation for given resources.
-
-NudgeBee Autopilot Reconciliation
-- NudgeBee provides annotations which can be used to ignore specific resources.
-
-GitOps Way Of Configuring NudgeBee Optimizations -
-- We want to provide this as an option using CRDs, though it's part of the roadmap.
+- **Raise PRs from NudgeBee**: Create automated pull requests with rightsized resource limits directly to your Git repository.
+- **GitOps Reconciliation (Flux / Argo CD)**: Annotate manifests or configure automated PR merges to ensure GitOps state remains the single source of truth.
+- **NudgeBee Autopilot Reconciliation**: Apply `nudgebee.io/ignore: "true"` annotations to exclude specific workloads from automated rightsizing.
 
 ### Can NudgeBee work on K3s/Kind/Minikube?
-Yes, please refer to the Installation Guide for local testing.
+Yes, please refer to the [Server Installation Guide](/docs/installation/server/) and [Agent Installation Guide](/docs/installation/agent/installation/) for local evaluation instructions.
 
 ### How are NudgeBee Docker images secured?
-NudgeBee uses minimal Alpine-based images to reduce attack surface and image size. Images are scanned for known vulnerabilities as part of the release pipeline. To report a suspected vulnerability, see the [security policy](https://github.com/nudgebee/nudgebee-docs/blob/main/SECURITY.md).
+NudgeBee uses minimal Alpine and distroless base images to minimize the attack surface. All images are signed and scanned for known vulnerabilities as part of the release pipeline. To report a suspected vulnerability, see the [security policy](https://github.com/nudgebee/nudgebee-docs/blob/main/SECURITY.md).
 
 ### Is NudgeBee penetration tested?
-Yes. NudgeBee undergoes regular security testing, including automated and manual penetration testing, as part of its release process.
+Yes. NudgeBee undergoes regular security testing, including automated SAST/DAST and third-party penetration testing, as part of its release compliance.
 
 ### Can I configure multiple clusters within a single NudgeBee server?
-Yes, configure agents on each targeted cluster.
+Yes. A single NudgeBee Server can monitor dozens of Kubernetes clusters across multiple clouds and on-premises environments by deploying the lightweight Agent into each target cluster.
 
 ### What are the different NudgeBee distributions / editions?
-NudgeBee is available in three editions — see the [Editions page](./editions.md) for the full side-by-side comparison.
+NudgeBee is available in three editions — see the [Editions & Capabilities page](/docs/editions) for the full comparison:
 
-- **Community** — free, open-source (Apache 2.0), fully functional self-hosted. Pull public images from `ghcr.io/nudgebee`; no license key.
-- **Enterprise** — self-hosted with a commercial license. Adds SAML 2.0 SSO, NudgeBee's managed models (`nb-llm` / `nb-slm`), and commercial support.
-- **Cloud** (SaaS) — fully managed at [app.nudgebee.com](https://app.nudgebee.com). Fastest way to evaluate.
-
-Use Cloud for fastest evaluation; Community for a free, self-hosted deployment; Enterprise when you need SAML, managed models, or a commercial SLA while staying on-prem.
+- **Community** — Free self-hosted edition. Server is licensed under **BSL 1.1**; Agents are **Apache 2.0**. Pull public images from `ghcr.io/nudgebee` with no license key required.
+- **Enterprise** — Self-hosted with a commercial license. Adds SAML 2.0 SSO, NudgeBee-managed models (`nb-llm` / `nb-slm`), and commercial SLA support.
+- **Cloud (SaaS)** — Fully managed at [app.nudgebee.com](https://app.nudgebee.com). Passwordless signup with fastest time to evaluate.
 
 ### What is the NudgeBee release cycle?
-We target to have a weekly release cycle with hotfixes as per requirements. We follow SemVer for our versioning.
+We follow a weekly release cadence for server and agent enhancements, with hotfixes published as needed. All versions follow Semantic Versioning (`vMAJOR.MINOR.PATCH`).
 
 ### Can you provide more details on Data Retention Policies?
 
-Currently, NudgeBee stores most of the data in Agents which get deployed on the cluster, so data remains within the cluster. Data retention for Agent components (traces/metrics/logs) is configurable and can be managed by the customer.
+Currently, NudgeBee stores most telemetry data inside your cluster or dedicated VPC storage:
 
 #### Agents store the following data:
-
-Traces - Using ClickHouse, you can adjust how long you want to retain ClickHouse data. The default is 7 days.
-Metrics - Using Prometheus, you can adjust Prometheus data retention.
-Logs - We integrate with existing log services like Loki/ELK, so again, it depends on their data retention.
-
+- **Traces**: Stored in ClickHouse / Tempo. Configurable retention with a default of 7 days.
+- **Metrics**: Stored in Prometheus / VictoriaMetrics. Configurable retention based on your storage class.
+- **Logs**: Integrated with existing log services (Loki / Elasticsearch / OpenObserve).
 
 #### Servers store the following data:
-
-Aggregated Metrics - Aggregated on a daily basis and retained for long-term trend analysis.
-Events - Troubleshooting pages. Default retention is 60 days, and is configurable.
-Deleted Pods/Workloads etc. - Records of deleted workloads/pods are retained to support historical analysis.
-
-### Does NudgeBee support Anomaly Detection?
-No, this is part of the roadmap.
+- **Aggregated Metrics**: Daily rollups for long-term capacity planning and FinOps cost trend analysis.
+- **Events & Incidents**: Troubleshooting events with default configurable retention of 60 days.
+- **Workload Metadata**: Historical records of deleted pods and workloads to support post-incident analysis.
 
 ### Does NudgeBee support Predictive Analysis?
-Yes, NudgeBee uses predictive analytics for replica rightsizing and continuous rightsizing.
+Yes, NudgeBee uses predictive analytics for workload replica rightsizing, resource trend forecasting, and continuous FinOps optimization.
 
 ### How does NudgeBee discover cloud resources across AWS, Azure, and GCP?
-NudgeBee automatically discovers cloud resources when you onboard an account. It searches for common services like VMs, load balancers, databases, and storage. The platform syncs with daily billing data and performs periodic updates for continuous resource tracking. For AWS specifically, NudgeBee uses EventBridge to receive real-time notifications for resource updates, creation, and deletion events.
+NudgeBee automatically discovers cloud resources when you onboard an account. It scans common services like VMs, load balancers, managed databases, and object storage. The platform syncs with daily billing data and listens to real-time events (e.g. AWS EventBridge) to track resource creation, modification, and deletion.
 
 ### Does NudgeBee support Kubernetes resource discovery?
-Yes, NudgeBee agents automatically discover all Kubernetes resources across all namespaces in your cluster. The agent runs within your Kubernetes environment and uses the Kubernetes API to continuously track workloads.
+Yes, NudgeBee agents automatically discover all Kubernetes resources across all namespaces in your cluster via the Kubernetes API.
 
 ### What observability tools does NudgeBee integrate with?
-NudgeBee provides prebuilt, out-of-the-box connectors for major observability platforms. These include Datadog, Prometheus (and all variations), Chronosphere, Signoz, OpenObserve, ELK, AWS CloudWatch, Azure Monitor, and Google Cloud Monitoring. The integrations work seamlessly with your existing stack without requiring replacements.
+NudgeBee provides prebuilt connectors for Datadog, Prometheus, Chronosphere, SigNoz, OpenObserve, Elasticsearch, AWS CloudWatch, Azure Monitor, and Google Cloud Monitoring.
 
 ### Can I deploy NudgeBee with its own observability stack?
-Yes, for new deployments or greenfield environments, NudgeBee ships with a complete observability stack. This includes VictoriaMetrics for metrics collection, ClickHouse with OpenTelemetry for distributed traces, and Loki for log aggregation.
+Yes, for greenfield environments, NudgeBee can bundle Prometheus for metrics collection, ClickHouse with OpenTelemetry for distributed traces, and Loki for log aggregation.
 
 ### How does NudgeBee integrate with existing knowledge base systems?
-NudgeBee natively integrates with Atlassian Confluence and ServiceNow knowledge bases. You can also define custom knowledge base sources including Google Docs, Notion, and SharePoint. These sources are used by NudgeBee's AI agents during troubleshooting workflows.
+NudgeBee natively integrates with Atlassian Confluence, ServiceNow, Notion, Google Docs, and SharePoint. These sources are indexed into the Semantic Knowledge Graph to ground NuBi's root cause investigations in your team's existing runbooks.
 
 ### Does NudgeBee learn from resolved incidents automatically?
-Yes, NudgeBee automatically learns from issues it has resolved. User feedback can be configured to flow directly into the knowledge base, continuously improving the AI agent's troubleshooting capabilities over time.
+Yes, NudgeBee automatically learns from resolved incidents. Resolution notes and verified postmortems flow directly into the knowledge base to continually improve future triage accuracy.
 
 ### How does NudgeBee handle event deduplication and aggregation?
-NudgeBee generates unique fingerprints for each event it receives. These fingerprints form the foundation for intelligent aggregation and deduplication within the platform. This prevents alert fatigue by consolidating related events into single actionable incidents.
+NudgeBee generates unique fingerprints for each incoming alert. These fingerprints form the foundation for intelligent aggregation and deduplication, consolidating cascading alert storms into single, actionable incidents.
 
 ### What is NudgeBee's Knowledge Graph and how does it correlate events?
-NudgeBee uses a Knowledge Graph to establish linkages between entities like configurations, logs, metrics, traces, cloud bills, SLO/SLAs, tickets, code, and secrets. When an event occurs, the system searches for related entities and identifies recent events that may have caused the new issue. It then builds a comprehensive event timeline based on these correlations.
+NudgeBee uses a live Semantic Knowledge Graph to establish topological links between workloads, pods, nodes, cloud services, metrics, traces, git commits, and tickets. When an incident occurs, the system correlates dependent entities across the timeline to identify the precise triggering change.
 
 ### What event sources can NudgeBee consume for incident management?
-NudgeBee consumes events from Prometheus Alertmanager, Kubernetes, Datadog, PagerDuty, and ServiceNow. Users can also send custom events to NudgeBee's webhook endpoints for proprietary or internal monitoring systems.
-
-### How does NudgeBee's SRE Agent prioritize and analyze incidents?
-For each incoming event, NudgeBee's SRE Agent performs deduplication and urgency assessment based on historical incident data. Events are then automatically analyzed for root cause using an AI-based workflow system. Users can extend the analysis by providing custom instructions tailored to their environment.
+NudgeBee consumes events from Prometheus Alertmanager, Kubernetes events, Datadog, PagerDuty, ServiceNow, and custom webhooks.
 
 ### Where can I access NudgeBee's SRE Agent (NuBi)?
-NuBi, NudgeBee's SRE agent, is accessible through communication channels like Slack and Microsoft Teams, or directly through the NudgeBee UI. This enables ChatOps workflows where team members can ask questions about infrastructure, logs, and metrics.
+NuBi is accessible directly through the web dashboard, Slack, and Microsoft Teams for seamless ChatOps.
 
 ### What are the primary capabilities of NuBi for SRE teams?
-NuBi handles ChatOps by responding to user questions about infrastructure, logs, and metrics. It performs live debugging of active incidents and conducts root cause analysis using AI-driven workflows. Teams can create custom agents based on specific requirements, extend existing agent instructions, and provide global context for tenant or account-level behaviors.
+NuBi investigates live alerts, runs ad-hoc infrastructure queries, correlates logs and traces, hypothesizes root causes, and suggests actionable remediation commands.
 
 ### What types of automated resolutions does NudgeBee support?
-NudgeBee generates automated pull requests for code and CI/CD issues. For lower environments, it can automate configuration changes with approval workflows. The platform also handles quick fixes like pod restarts and memory/CPU adjustments automatically.
+NudgeBee can generate automated pull requests for GitOps and CI/CD configurations, trigger approved runbooks (e.g. pod restarts or cache flushes), and execute policy-gated right-sizing actions.
 
 ### Can I customize NudgeBee's automation workflows?
-Yes, users can create custom resolution workflows using NudgeBee's AI-Ops Workflow Builder. You can customize existing workflows or extend them with additional components, APIs, and integrations tailored to your infrastructure.
+Yes, users can compose custom automation DAGs using NudgeBee's visual AI-Ops Workflow Builder.
 
 ### What ITSM and ticketing systems does NudgeBee integrate with?
-NudgeBee provides out-of-the-box integration with GitHub Issues, Jira, and ServiceNow (available in the December 2025 release). These integrations support automated ticketing, incident management system integration for listening and responding to incidents, and CMDB/KB integration (Planned for future releases).
+NudgeBee provides out-of-the-box integrations with GitHub Issues, Jira, PagerDuty, and ServiceNow. These integrations support automated ticket creation, bidirectional incident status sync, and knowledge base grounding.