rework pam docs for structure

docs/docs.json

@@ -827,7 +827,20 @@
                 "group": "Infisical PAM",
                 "pages": [
                   "documentation/platform/pam/overview",
-                  "documentation/platform/pam/session-recording"
+                  {
+                    "group": "Getting Started",
+                    "pages": [
+                      "documentation/platform/pam/getting-started/resources",
+                      "documentation/platform/pam/getting-started/accounts"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Product Reference",
+                "pages": [
+                  "documentation/platform/pam/product-reference/auditing",
+                  "documentation/platform/pam/product-reference/session-recording"
                 ]
               }
             ]

docs/documentation/platform/pam/getting-started/accounts.mdx

@@ -0,0 +1,34 @@
+---
+title: "PAM Account"
+sidebarTitle: "Accounts"
+description: "Learn how to create and manage accounts in PAM to control access to resources like databases and servers."
+---
+
+An account represents a specific set of credentials (e.g., a username and password) used to access a [resource](/documentation/platform/pam/getting-started/resources).
+
+## Creating an Account
+
+<Info>
+    Before you can create an account, you must first [Create a Resource](/documentation/platform/pam/getting-started/resources#creating-a-resource).
+</Info>
+
+To add an account, navigate to the **Accounts** tab in your PAM project and click **Add Account**.
+
+![Add Account Button](/images/pam/getting-started/accounts/add-account-button.png)
+
+Next, select the resource where you want to add the account.
+
+![Select Resource](/images/pam/getting-started/accounts/select-resource.png)
+
+After selecting a resource, provide the necessary credentials. The required fields vary depending on the resource type. For example, an SSH resource needs the username and password for a Unix user.
+
+![Create Account](/images/pam/getting-started/accounts/create-account.png)
+
+Clicking **Create Account** triggers a validation check to verify the credentials. If the validation fails, an error message is displayed to help you troubleshoot.
+
+## Automated Credential Rotation
+
+Accounts for certain resources, such as PostgreSQL, support automated credential rotation.
+
+You can enable rotation when creating or editing an account and set a desired interval (e.g., every 30 days). This option is only available if a [rotation account is configured](/documentation/platform/pam/getting-started/resources#automated-credential-rotation) on the resource.
+![Rotate Credentials Account](/images/pam/getting-started/resources/rotate-credentials-account.png)

docs/documentation/platform/pam/getting-started/resources.mdx

@@ -0,0 +1,46 @@
+---
+title: "PAM Resource"
+sidebarTitle: "Resources"
+description: "Learn how to add and configure resources like databases and servers, and set up automated credential rotation."
+---
+
+A resource represents a target system, such as a database, server, or application, that you want to manage access to. Some examples of resources are:
+- PostgreSQL Database
+- MCP Server
+- Linux Server
+- Web Application
+
+## Creating a Resource
+
+<Warning>
+    Certain resources require you to have a Gateway deployed on the same network as your target resource. [Gateway Deployment Guide](/documentation/platform/gateways/gateway-deployment)
+</Warning>
+
+To add a resource, navigate to the **Resources** tab in your PAM project and click **Add Resource**.
+
+![Add Resource Button](/images/pam/getting-started/resources/add-resource-button.png)
+
+Next, select the type of resource you want to add.
+
+![Select Resource Type](/images/pam/getting-started/resources/select-resource-type.png)
+
+After selecting a resource type, provide the necessary connection details. The required fields vary depending on the resource type. In this PostgreSQL example, you need to provide details such as host, port, gateway, and database name.
+
+![Create Resource](/images/pam/getting-started/resources/create-resource.png)
+
+Clicking **Create Resource** will run a validation to check if your resource is reachable by the platform or Gateway. If the connection fails, an error message will be displayed to help you troubleshoot.
+
+## Automated Credential Rotation
+
+Some resources, such as PostgreSQL, support automated credential rotation to enhance your security posture. This requires configuration on both the resource and the accounts that use it.
+
+<Steps>
+    <Step title="Configure Rotation Account on Resource">
+        When creating or editing a resource, configure a "rotation account." This is a master or privileged account that has the necessary permissions to change the passwords of other accounts on that same resource.
+        ![Credential Rotation Account](/images/pam/getting-started/resources/credential-rotation-account.png)
+    </Step>
+    <Step title="Enable Rotation on Account">
+        For each individual account you want to rotate, enable rotation in the account's settings and set a desired interval (e.g., every 30 days). This option is only available if the account's resource has a rotation account configured.
+        ![Rotate Credentials Account](/images/pam/getting-started/resources/rotate-credentials-account.png)
+    </Step>
+</Steps>

docs/documentation/platform/pam/overview.mdx

@@ -1,45 +1,34 @@
 ---
-title: "Infisical PAM"
+title: "Overview"
 sidebarTitle: "Overview"
-description: "Learn how to manage access to resources like databases, servers, and accounts with policy-based controls and approvals."
+description: "Manage and secure access to critical infrastructure like databases and servers with policy-based controls and approvals."
 ---
 
 Infisical Privileged Access Management (PAM) provides a centralized way to manage and secure access to your critical infrastructure. It allows you to enforce fine-grained, policy-based controls over resources like databases, servers, and more, ensuring that only authorized users can access sensitive systems, and only when they need to.
 
-### How it Works
+Infisical PAM organizes access around your resources (e.g., databases, servers, web apps). This resource-centric approach makes it intuitive to manage permissions and scale your security policies as your infrastructure grows.
 
-Infisical PAM employs a resource-based model to organize and manage access. This model is designed to be intuitive and scalable.
+## Core Capabilities
 
-#### 1. Create a Resource
+- **[Auditing](/documentation/platform/pam/product-reference/auditing)**: Track and review a comprehensive log of all user actions and system events.
+- **[Session Recording](/documentation/platform/pam/product-reference/session-recording)**: Record and playback user sessions for security reviews, compliance, and troubleshooting.
+- **[Automated Credential Rotation](/documentation/platform/pam/getting-started/resources#automated-credential-rotation)**: Automatically rotate credentials for supported resources to minimize the risk of compromised credentials.
 
-The first step is to define a resource you want to manage. A resource represents a target system, such as a PostgreSQL database. When creating a resource, you'll provide the necessary connection details, like the host and port.
+## Getting Started
 
-![Create Resource](/images/pam/overview/create-resource.png)
-
-#### 2. Add Accounts to the Resource
-
-Once a resource is created, you can add accounts to it. An account represents a specific set of credentials (e.g., a username and password) that can be used to access the resource. This allows you to manage multiple sets of credentials for a single database or server from one place.
-
-![Create Account](/images/pam/overview/create-account.png)
-
-### Infisical PAM Features
-
-#### Session Logging and Auditing
-
--   **Session Logging**: All user sessions are extensively logged, providing a detailed and searchable record of activities performed during a session.
--   **Audit Logging**: Every significant event, such as a user starting a session or accessing an account's credentials, is recorded in audit logs. This gives you complete visibility over your project.
-
-![Session Page](/images/pam/overview/session-page.png)
-
-#### Automated Credential Rotation
-
-Infisical PAM can automatically rotate account credentials to enhance your security posture.
-
-Here’s how it works:
-1.  **Add a Rotation Account**: On the resource level, you configure a "rotation account." This is a master or privileged account that has the necessary permissions to change the passwords of other accounts on that same resource.
-![Credential Rotation Account](/images/pam/overview/credential-rotation-account.png)
-
-2.  **Configure Rotation on Accounts**: For each individual account you want to rotate, you can simply enable rotation and set a desired interval (e.g., every 30 days).
-![Rotate Credentials Account](/images/pam/overview/rotate-credentials-account.png)
-
-Infisical will then use the rotation account on the resource to automatically update the credentials of the target account at the specified interval, eliminating credential staleness.
+<Columns cols="2">
+    <Card
+        icon="box"
+        title="Creating a Resource"
+        href="/documentation/platform/pam/getting-started/resources#creating-a-resource"
+    >
+        Add and configure the databases, servers, and other infrastructure you want to protect.
+    </Card>
+    <Card
+        icon="user"
+        title="Creating an Account"
+        href="/documentation/platform/pam/getting-started/accounts#creating-an-account"
+    >
+        Create accounts that users will use to access your protected resources.
+    </Card>
+</Columns>

docs/documentation/platform/pam/product-reference/auditing.mdx

@@ -0,0 +1,23 @@
+---
+title: "Auditing"
+sidebarTitle: "Auditing"
+description: "Learn how Infisical audits all actions across your PAM project."
+---
+
+## What's Audited
+
+Infisical logs a wide range of actions to provide a complete audit trail for your PAM project. These actions include:
+
+- Session Start and End
+- Fetching session credentials
+- Creating, updating, or deleting resources, accounts, folders, and sessions
+
+<Info>
+    Please note: Audit logs track metadata about sessions (e.g., start/end times), but not the specific commands executed *within* them. For detailed in-session activity, check out [Session Recording](/documentation/platform/pam/product-reference/session-recording).
+</Info>
+
+## Viewing Audit Logs
+
+You can view, search, and filter all events from the **Audit Logs** page within your PAM project.
+
+![Audit Logs](/images/pam/product-reference/auditing/audit-logs.png)

docs/documentation/platform/pam/product-reference/session-recording.mdx

@@ -0,0 +1,60 @@
+---
+title: "Session Recording"
+sidebarTitle: "Session Recording"
+description: "Learn how Infisical records and stores session activity for auditing and monitoring."
+---
+
+Infisical PAM provides robust session recording capabilities to help you audit and monitor user activity across your infrastructure.
+
+## How It Works
+
+When a user initiates a session by accessing an account, a recording of the session begins. The Gateway securely caches all recording data in temporary encrypted files on its local system.
+
+Once the session concludes, the gateway transmits the complete recording to the Infisical platform for long-term, centralized storage. This asynchronous process ensures that sessions remain operational even if the connection to the Infisical platform is temporarily lost. After the upload is complete, administrators can search and review the session logs on the Infisical platform.
+
+## What's Captured
+
+The content captured during a session depends on the type of resource being accessed.
+
+<AccordionGroup>
+    <Accordion title="Database Sessions">
+        Infisical captures all queries executed and their corresponding responses, including timestamps for each action.
+    </Accordion>
+    <Accordion title="SSH Sessions">
+        Infisical captures all commands executed and their corresponding responses, including timestamps for each action.
+    </Accordion>
+</AccordionGroup>
+
+## Viewing Recordings
+
+To review session recordings:
+
+1. Navigate to the **Sessions** page in your PAM project.
+2. Click on a session from the list to view its details.
+
+![PAM Sessions](/images/pam/product-reference/session-recording/sessions-page.png)
+
+The session details page provides key information, including the complete session logs, connection status, the user who initiated it, and more.
+
+![PAM Individual Session](/images/pam/product-reference/session-recording/individual-session-page.png)
+
+### Searching Logs
+
+You can use the search bar to quickly find relevant information:
+
+**Sessions page:** Search across all session logs to locate specific queries or outputs.
+![PAM Sessions Search](/images/pam/product-reference/session-recording/sessions-page-search.png)
+
+**Individual session page:** Search within that specific session's logs to pinpoint activity.
+![PAM Individual Session Search](/images/pam/product-reference/session-recording/individual-session-page-search.png)
+
+## FAQ
+
+<AccordionGroup>
+    <Accordion title="Are session recordings encrypted?">
+        Yes. All session recordings are encrypted at rest by default, ensuring your data is always secure.
+    </Accordion>
+    <Accordion title="Why aren't recordings streamed in real-time?">
+        Currently, Infisical uses an asynchronous approach where the gateway records the entire session locally before uploading it. This design makes your PAM sessions more resilient, as they don't depend on a constant, active connection to the Infisical platform. We may introduce live streaming capabilities in a future release.
+    </Accordion>
+</AccordionGroup>

docs/documentation/platform/pam/session-recording.mdx

@@ -1,60 +0,0 @@
----
-title: "Session Recording"
-sidebarTitle: "Session Recording"
-description: "Learn how Infisical records and stores session activity for auditing and monitoring."
----
-
-Infisical's Privileged Access Management (PAM) provides robust session recording capabilities to help you audit and monitor user activity across your infrastructure.
-
-## How It Works
-
-When a user initiates a session through the Infisical Gateway, a recording of the session begins. The gateway securely caches all recording data in temporary encrypted files on its local system.
-
-Once the session concludes, the gateway transmits the complete recording to the Infisical platform for long-term, centralized storage. This asynchronous process ensures that sessions remain operational even if the connection to the Infisical platform is temporarily lost. After the upload is complete, administrators can search and review the session logs in the Infisical UI.
-
-## What's Captured
-
-The content captured during a session depends on the type of resource being accessed.
-
-### Database Sessions
-
-For database connections, Infisical captures all queries executed and their corresponding responses.
-
-<Note>
-Support for additional resource types like SSH, RDP, Kubernetes, and MCP is coming soon.
-</Note>
-
-## Viewing Recordings
-
-To review session recordings:
-
-1.  Navigate to the **PAM Sessions** page in your project.
-2.  Click on a session from the list to view its details.
-
-![PAM Sessions](/images/pam/session-recording/sessions-page.png)
-
-The session details page provides key information, including the complete session logs, connection status, the user who initiated it, and more.
-
-![PAM Individual Session](/images/pam/session-recording/individual-session-page.png)
-
-### Searching Logs
-
-You can use the search bar to quickly find relevant information:
-
--   **On the main Sessions page:** Search across all session logs to locate specific queries or outputs.
--   **On an individual session page:** Search within that specific session's logs to pinpoint activity.
-
-![PAM Sessions Search](/images/pam/session-recording/sessions-page-search.png)
-
-![PAM Individual Session Search](/images/pam/session-recording/individual-session-page-search.png)
-
-## FAQ
-
-<AccordionGroup>
-    <Accordion title="Are session recordings encrypted?">
-        Yes. All session recordings are encrypted at rest by default, ensuring your audit data is always secure.
-    </Accordion>
-    <Accordion title="Why aren't recordings streamed in real-time?">
-        Currently, Infisical uses an asynchronous approach where the gateway records the entire session locally before uploading it. This design makes your PAM sessions more resilient, as they don't depend on a constant, active connection to the Infisical platform. We may introduce live streaming capabilities in a future release.
-    </Accordion>
-</AccordionGroup>