doc: added migration tips

docs/internals/permissions.mdx

@@ -3,7 +3,7 @@ title: "Permissions"
 description: "Infisical's permissions system provides granular access control."
 ---
 
-## Summary
+## Overview
 
 The Infisical permissions system is based on a role-based access control (RBAC) model. The system allows you to define roles and assign them to users and machines. Each role has a set of permissions that define what actions a user can perform.
 
@@ -140,3 +140,72 @@ The following operators are available for conditions:
 
 These details are especially useful if you're using the API to [create new project roles](../api-reference/endpoints/project-roles/create).
 The rules outlined on this page, also apply when using our Terraform Provider to manage your Infisical project roles, or any other of our clients that manage project roles.
+
+## Migrating from permission V1 to permission V2
+
+When upgrading to V2 permissions (i.e. when moving from using the `permissions` to `permissions_v2` field in your Terraform configurations, or upgrading to the V2 permission API), you'll need to update your permission structure as follows:
+
+Any permissions for `secrets` should be expanded to include equivalent permissions for:
+
+- `secret-imports`
+- `secret-folders` (except for read permissions)
+- `dynamic-secrets`
+
+For dynamic secrets, the actions need to be mapped differently:
+
+- `read` → `read-root-credential`
+- `create` → `create-root-credential`
+- `edit` → `edit-root-credential` (also adds `lease` permission)
+- `delete` → `delete-root-credential`
+
+Example:
+
+```hcl
+# Old V1 configuration
+resource "infisical_project_role" "example" {
+  name = "example"
+  permissions = [
+    {
+      subject = "secrets"
+      action = "read"
+    },
+    {
+      subject = "secrets"
+      action = "edit"
+    }
+  ]
+}
+
+# New V2 configuration
+resource "infisical_project_role" "example" {
+  name = "example"
+  permissions_v2 = [
+    # Original secrets permission
+    {
+      subject = "secrets"
+      action = ["read", "edit"]
+      inverted = false
+    },
+    # Add equivalent secret-imports permission
+    {
+      subject = "secret-imports"
+      action = ["read", "edit"]
+      inverted = false
+    },
+    # Add secret-folders permission (without read)
+    {
+      subject = "secret-folders"
+      action = ["edit"]
+      inverted = false
+    },
+    # Add dynamic-secrets permission with mapped actions
+    {
+      subject = "dynamic-secrets"
+      action = ["read-root-credential", "edit-root-credential", "lease"]
+      inverted = false
+    }
+  ]
+}
+```
+
+Note: When moving to V2 permissions, make sure to include all the necessary expanded permissions based on your original `secrets` permissions.