Enhance PDP documentation with Edge and Cloud distinctions

- Introduced clear definitions and distinctions between Managed Cloud PDP and Edge PDP deployment types.
- Updated sections to emphasize the benefits of Edge PDP for latency-sensitive and advanced scenarios.
- Revised documentation to reflect terminology changes, including the use of "Edge PDP" for self-hosted deployments.
- Added guidance for users on when to choose Edge PDP over Managed Cloud PDP, including specific use cases and deployment models.

Author: omer9564

docs/concepts/pdp/overview.mdx

@@ -16,6 +16,16 @@ Like all of Permit's customer deployed components, the [Permit PDP is open-sourc
 ## Use the PDP
 There are several ways you can use the PDP for testing and enforcement:
 
+### PDP deployment types: Cloud vs Edge
+
+When we talk about PDP deployment, we distinguish between:
+
+- **Managed Cloud PDP** – A fully managed, multi-tenant PDP hosted by Permit.io at `https://cloudpdp.api.permit.io`.  
+  Ideal for **fast onboarding**, **low-ops production workloads**, and **standard RBAC/ReBAC** authorization at scale.
+- **Edge PDP (self-hosted PDP)** – PDP containers you run as a **sidecar**, **centralized service**, or **cluster** inside your own VPC, Kubernetes cluster, or VMs.  
+  Ideal when you need **tight latency within your own network**, **ABAC**, **custom data sources**, **read-your-own-writes**, or **PDP-level callbacks and healthchecks**.
+
+Most teams **start** with the Managed Cloud PDP to get value quickly, and then **introduce Edge PDPs** for latency-sensitive or advanced scenarios.
 
 ### Managed Cloud PDP
 
@@ -112,11 +122,11 @@ Cloud PDP supports **RBAC and ReBAC** policy models. **ABAC is not supported** o
 
 For detailed capabilities and limits, see [Cloud PDP Capabilities](/concepts/pdp/cloud-pdp-capabilities).
 
-We recommend deploying a local PDP inside your network for ABAC policies and for specialized or latency-sensitive production deployments.
+We recommend deploying an **Edge PDP (self-hosted PDP)** inside your network for **ABAC** policies, **read-your-own-writes** semantics, and specialized or latency-sensitive production deployments.
 :::
 
-### Run a Local PDP With Docker
-You can run a PDP on your local machine as a container on [Docker Desktop](https://docs.docker.com/get-docker/). You will need this to use ABAC / ReBAC policies.
+### Run an Edge PDP With Docker
+You can run an **Edge PDP** on your local machine as a container on [Docker Desktop](https://docs.docker.com/get-docker/). You will need this to use **ABAC** / advanced policies, custom data sources, and consistency features such as **Send Consistent Updates (read-your-own-writes)**.
 
 To run the PDP use the following command:
 
@@ -214,7 +224,27 @@ permit = Permit.new(
 
 ## Production Deployment Models
 
-Permit.io supports all PDP layouts and provides the missing layers on-top of open-source PDP solutions (such as OpenPolicyAgent). These layers include policy delivery and updating, supporting data collection, application level SDKs, application level instrumentation and more.
+Permit.io supports all **Edge PDP** layouts and provides the missing layers on-top of open-source PDP solutions (such as OpenPolicyAgent).  
+These layouts describe **self-hosted PDPs that you run inside your own infrastructure**.  
+These layers include policy delivery and updating, supporting data collection, application level SDKs, application level instrumentation and more.
+
+:::info New to PDPs?
+If you're just getting started, follow this journey:
+
+- **Step 1** – [Run your First Policy Check (Managed Cloud PDP)](/overview/perform-policy-check-with-cloud-pdp) to see Permit in action with the Managed Cloud PDP.
+- **Step 2** – [Run Local Authorization Microservice (Edge PDP)](/overview/local-authorization-microservice) to deploy an Edge PDP in your own environment.
+:::
+
+:::warning Cloud PDP – when not to use it
+The Managed Cloud PDP is powerful and production-ready for many RBAC/ReBAC workloads, but you should **prefer an Edge PDP** when you need:
+
+- **ABAC** policies or custom external data sources
+- **Read-your-own-writes** guarantees using [Send Consistent Updates](/how-to/manage-data/local-facts-uploader)
+- **PDP-level callbacks / health-based consistency hooks** into your infrastructure
+- **Hard latency SLOs strictly within your own VPC or on-prem network**
+
+For these cases, deploy an **Edge PDP (self-hosted PDP)** as a sidecar, centralized service, or cluster close to your applications.
+:::
 
 :::info
 Custom cloud PDP deployments are available to enterprise tier customers.
@@ -224,7 +254,7 @@ Please reach out to us at [support@permit.io](mailto:support@permit.io), or sche
 :::
 
 
-### Hosted as a Sidecar
+### Hosted as an Edge PDP Sidecar
 
 The simplest way to integrate PDPs into a microservices architecture is as sidecars;
 meaning each microservice has a sidecar container next to it which it can query for policy.
@@ -246,7 +276,7 @@ flowchart LR
     style pdp fill:#f76808,color:#fff;
 ```
 
-### Centralized PDP
+### Centralized Edge PDP
 
 You can deploy a centralized PDP to handle authorization queries from multiple services.
 
@@ -269,7 +299,7 @@ flowchart LR
     style pdp fill:#f76808,color:#fff;
 ```
 
-### Cluster of PDPs
+### Cluster of Edge PDPs
 
 For high availability and scalability, you can deploy a cluster of PDPs behind a load balancer.
 
@@ -300,7 +330,7 @@ flowchart LR
     style lb fill:#4e7ef2,color:#fff;
 ```
 
-### Sharded PDPs
+### Sharded Edge PDPs
 
 For truly massive data sets needed in the PDP, you can apply sharding to split the data between multiple PDPs within the same cluster.
 

docs/how-to/deploy/overview.mdx

@@ -35,8 +35,8 @@ The updates happen asynchronously in the background - they are not part of the a
 Like all Permit customer deployed components, the [Permit PDP is open-source](https://github.com/permitio/PDP).
 :::
 
-We often refer to the cloud-hosted PDP option as full-SaaS or cloud-PDP, and the local PDP option as [hybrid SaaS](/concepts/control-plane-and-data-plane).
-Hybrid SaaS is the default recommended layout.
+We refer to customer-hosted PDPs (sidecar, cluster, or centralized in your VPC) as **Edge PDPs**, and the cloud-hosted PDP option as the **Managed Cloud PDP**.  
+Running an **Edge PDP** is our **default recommendation for production**, while the Managed Cloud PDP is ideal for fast onboarding and low-ops workloads.
 
 ### Cloud PDP
 
@@ -58,7 +58,7 @@ Custom Hosted PDP deployments (e.g. different AWS regions, different clouds, dif
 Please reach out to us at [support@permit.io](mailto:support@permit.io), or schedule a call via this link: [https://calendly.com/permitio/](https://calendly.com/permitio/)
 :::
 
-### Sidecar
+### Sidecar (Edge PDP)
 
 ```mermaid
 flowchart LR
@@ -71,12 +71,12 @@ flowchart LR
   end
 ```
 
-The most common way to deploy the PDP locally is as a sidecar (or daemon-set) - i.e. you run one PDP container next to each
+The most common way to deploy an **Edge PDP** locally is as a sidecar (or daemon-set) - i.e. you run one PDP container next to each
 of your own microservices.
 This is also the easiest way to scale your authorization layer with your application.
 
 In this layout you of course enjoy zero-latency between your application and the PDP - this together with
-improved stability and security (no dependency on other clouds) is the main reason to use a local PDP compared to a cloud pdp.
+improved stability and security (no dependency on other clouds) is the main reason to use an **Edge PDP** compared to the Managed Cloud PDP.
 
 #### Running the sidecar in Kubernetes?
 
@@ -103,7 +103,8 @@ healthcheck:
 In Kubernetes, use a readiness probe as detailed in [this guide](/how-to/deploy/cloud-hosts/kubernetes-raw/#readiness-probe).
 :::
 
-If you need more advanced policy level healthchecks, you can read more about them as part of OPAL [here](https://docs.opal.ac/tutorials/healthcheck_policy_and_update_callbacks/).
+If you need more advanced policy level healthchecks, you can read more about them as part of OPAL [here](https://docs.opal.ac/tutorials/healthcheck_policy_and_update_callbacks/).  
+These advanced healthchecks and callbacks apply to **Edge PDPs (self-hosted PDPs)** and are **not available on the Managed Cloud PDP**.
 
 ### Cluster
 

docs/overview/perform-policy-check-with-cloud-pdp.mdx

@@ -1,13 +1,21 @@
 ---
 sidebar_position: 3
-title: Run your First Policy Check
+title: Run your First Policy Check (Managed Cloud PDP)
 timeline: true
 ---
 
 Performing your first **policy check** is a key step in understanding and validating the policies you've configured.
 The policy decision point (PDP) lies at the heart of Permit's Authorization system, determining whether a user is authorized
 to perform specific actions on a resource. This ensures that your access control model is working as intended.
 
+:::info Which PDP is this using?
+This guide uses the **Managed Cloud PDP** hosted by Permit.io at `https://cloudpdp.api.permit.io`.  
+It is **fully managed and eventually consistent**, and is great for quickly trying out Permit and for many production workloads that don't require strict read-your-own-writes guarantees.
+
+If you already know you need **ABAC policies**, **strict read-your-own-writes consistency**, or to keep all authorization traffic **inside your own VPC**, you can skip ahead to  
+**[Run Local Authorization Microservice (Edge PDP)](/overview/local-authorization-microservice)**.
+:::
+
 import CodeBlock from "../../src/components/code-block/CodeBlock";
 import WhatsNext from "../../src/components/whats-next/WhatsNext";
 import TimelineStep from "../../src/components/timeline/TimelineStep";