Merge remote-tracking branch 'origin' into service-token-v3

docs/documentation/getting-started/introduction.mdx

@@ -2,7 +2,8 @@
 title: "Introduction"
 ---
 
-Infisical is an [open-source](https://opensource.com/resources/what-open-source), [end-to-end encrypted](https://en.wikipedia.org/wiki/End-to-end_encryption) secret management platform that enables teams to easily manage and sync their environment variables.
+Infisical is an [open-source](https://opensource.com/resources/what-open-source), [end-to-end encrypted](https://en.wikipedia.org/wiki/End-to-end_encryption) secret management platform for storing, managing, and syncing
+application configuration and secrets like API keys, database credentials, and environment variables across applications and infrastructure. 
 
 Start syncing environment variables with [Infisical Cloud](https://app.infisical.com) or learn how to [host Infisical](/self-hosting/overview) yourself.
 

docs/documentation/getting-started/platform.mdx

@@ -2,24 +2,47 @@
 title: "Platform"
 ---
 
-Infisical is an [open-source](https://opensource.com/resources/what-open-source), [end-to-end encrypted](https://en.wikipedia.org/wiki/End-to-end_encryption) secret management platform that enables teams to easily store, manage, and sync secrets like API keys, database credentials, and environment variables across their apps and infrastructure.
+This quickstart provides an overview of functionalities offered by Infisical.
 
-This quickstart provides an overview of the functionalities offered by Infisical.
+## Managing your Organization
 
-## Projects
+When you first make an account with Infisical, you also create a new **organization** where you are assigned the `admin` role by default.
+From there, you can invite external members to the organization and start creating **projects** to house secrets.
 
-Projects hold secrets for applications, which are further organized into environments such as development, testing and production.
+### Projects
+
+The **Projects** page shows you all the projects that you have access to within your organization.
+Here, you can also create a new project. 
+
+![organization overview](../../images/organization-overview.png)
+
+### Members
+
+The **Members** page lets you add or remove external members to your organization. 
+Note that you can configure your organization in Infisical to have members authenticate with the platform via protocols like SAML 2.0.
+
+![organization members](../../images/organization-members.png)
+
+## Managing your Projects
+
+As mentioned before, projects house secrets which are further organized into environments such as development, testing and production.
+A project can be anything from a single application to a collection of micro-services that you wish to manage secrets for.
 
 ### Secrets Overview
 
-The secrets overview provides a bird's-eye view of all the secrets in a project and is particularly useful for identifying missing secrets across environments.
+The **Secrets Overview** screen provides a bird's-eye view of all the secrets in a project and is useful for comparing secrets and identifying missing ones across environments.
 
 ![dashboard secrets overview](../../images/dashboard-secrets-overview.png)
 
-### Secrets Dashboard
+In the above image, you can already see that:
+- `STRIPE_API_KEY` is missing from the **Staging** environment.
+- `JWT_SECRET` is missing from the **Production** environment.
+- `BAR` is `EMPTY` in the **Production** environment.
+
+### Dashboard
 
 The secrets dashboard lets you manage secrets for a specific environment in a project. 
-Here, developers can [override secrets](//project#personal-overrides), [version secrets](/documentation/platform/secret-versioning), [rollback projects to any point in time](/documentation/platform/pit-recovery), and much more.
+Here, developers can override secrets, version secrets, rollback projects to any point in time and much more.
 
 ![dashboard](../../images/dashboard.png)
 
@@ -27,31 +50,15 @@ Here, developers can [override secrets](//project#personal-overrides), [version
 
 The integrations page provides native integrations to sync secrets from a project environment to a [host of ever-expanding integrations](/integrations/overview).
 
-<Tip>
-    Depending on your infrastructure setup and compliance requirements, you may or may not prefer to use these native integrations since they break end-to-end encryption (E2EE).
-    
-    You will learn about various ways to integrate with Infisical and maintain E2EE in subsequent quickstart sections.
-</Tip>
-
 ![integrations](../../images/integrations.png)
 
-### Access Control
+### Members
 
-The members page lets you add/remove members for a project and provision them access to environments (access levels include `No Access`, `Read Only`, and `Read and Write`).
+The members page lets you add/remove members to/from a project and provision them access to environments via roles. By default, Infisical provides the `admin`, `developer`, and `viewer` roles
+which you can assign to members.
 
 ![project members](../../images/project-members.png)
 
-## Organizations
-
-Organizations house projects and members.
-
-### Organization Settings
-
-At the organization-level, you can add/remove members and manage their access to projects.
-
-![organization name modal open](../../images/dashboard-name-modal-organization.png)
-![organization name modal open](../../images/organization.png)
-
 That's it for the platform quickstart! — We encourage you to continue exploring the documentation to gain a deeper understanding of the extensive features and functionalities that Infisical has to offer.
 
 Next, head back to [Getting Started > Introduction](/documentation/getting-started/overview) to explore ways to fetch secrets from Infisical to your apps and infrastructure.

docs/documentation/getting-started/sdks.mdx

@@ -9,137 +9,11 @@ Prerequisites:
 - Have a project with secrets ready in [Infisical Cloud](https://app.infisical.com).
 - Create an [Infisical Token](/documentation/platform/token) scoped to an environment in your project in Infisical.
 
-## Installation
+## Usage
 
-Follow the instructions for your language to install the SDK for it.
+Follow the instructions for your language use the SDK for it:
 
-<Tabs>
-    <Tab title="Node">
+- [Node SDK](https://github.com/Infisical/infisical-node)
+- [Python SDK](https://github.com/Infisical/infisical-python)
 
-        Run `npm` to add [infisical-node](https://github.com/Infisical/infisical-node) to your project.
-
-        ```console
-        $ npm install infisical-node --save
-        ```
-
-        ## Configuration
-
-        Import the SDK and create a client instance with your [Infisical Token](/documentation/platform/token).
-
-        <Tabs>
-            <Tab title="ES6">
-                ```js
-                import InfisicalClient from "infisical-node";
-                
-                const client = new InfisicalClient({
-                    token: "your_infisical_token"
-                });
-                ```
-
-            </Tab>
-            <Tab title="ES5">
-                ```js
-                const InfisicalClient = require("infisical-node");
-                
-                const client = new InfisicalClient({
-                    token: "your_infisical_token"
-                });
-                ````
-            </Tab>
-        </Tabs>
-        ## Get a Secret
-        
-        ```js
-        const secret = await client.getSecret("API_KEY");
-        const value = secret.secretValue; // get its value
-        ```
-        
-        ## Basic Usage
-
-        ```js
-        import express from "express";
-        import InfisicalClient from "infisical-node";
-        const app = express();
-        const PORT = 3000;
-
-        const client = new InfisicalClient({
-            token: "YOUR_INFISICAL_TOKEN"
-        });
-
-        app.get("/", async (req, res) => {
-            // access value
-            const name = await client.getSecret("NAME");
-            res.send(`Hello! My name is: ${name.secretValue}`);
-        });
-
-        app.listen(PORT, async () => {
-            console.log(`App listening on port ${port}`);
-        });
-        ```
-
-        This example demonstrates how to use the Infisical Node SDK with an Express application. The application retrieves a secret named "NAME" and responds to requests with a greeting that includes the secret value.
-    </Tab>
-    <Tab title="Python">
-
-        ## Installation
-
-        Run `pip` to add [infisical-python](https://github.com/Astropilot/infisical-python) to your project
-
-        ```console
-        $ pip install infisical
-        ```
-
-        Note: You need Python 3.7+.
-
-        ## Configuration
-
-        Import the SDK and create a client instance with your [Infisical Token](/documentation/platform/token).
-
-        ```py
-        from infisical import InfisicalClient
-
-        client = InfisicalClient(token="your_infisical_token")
-        ```
-        
-        ## Get a Secret
-
-        ```py
-        secret = client.get_secret("API_KEY")
-        value = secret.secret_value # get its value
-        ```
-
-        ## Basic Usage
-
-        ```py
-        from flask import Flask
-        from infisical import InfisicalClient
-
-        app = Flask(__name__)
-
-        client = InfisicalClient(token="your_infisical_token")
-
-        @app.route("/")
-        def hello_world():
-            # access value
-            name = client.get_secret("NAME")
-            return f"Hello! My name is: {name.secret_value}"
-        ```
-
-        This example demonstrates how to use the Infisical Python SDK with a Flask application. The application retrieves a secret named "NAME" and responds to requests with a greeting that includes the secret value.
-    </Tab>
-    <Tab title="Other">
-        We're currently working on SDKs for other languages. Follow the GitHub issue for your needed language below:
-        - [Java](https://github.com/Infisical/infisical/issues/434)
-        - [Ruby](https://github.com/Infisical/infisical/issues/435)
-        - [Go](https://github.com/Infisical/infisical/issues/436)
-        - [Rust](https://github.com/Infisical/infisical/issues/437)
-        - [PHP](https://github.com/Infisical/infisical/issues/531)
-
-        Missing a language? [Throw in a request](https://github.com/Infisical/infisical/issues).
-    </Tab>
-</Tabs>
-
-See also:
-
-- Explore the [Node SDK](https://github.com/Infisical/infisical-node)
-- Explore the [Python SDK](https://github.com/Infisical/infisical-python)
+Missing a language? [Throw in a request](https://github.com/Infisical/infisical/issues).

docs/documentation/platform/audit-logs.mdx

@@ -3,10 +3,25 @@ title: "Audit Logs"
 description: "See which events are triggered within your Infisical project."
 ---
 
-Audit logs record all actions going through Infisical including who performed which CRUD operations on environment variables and from what IP address. They help answer questions like:
+<Info>
+    Note that Audit Logs is a paid feature.
 
-- Who added or updated environment variables recently?
-- Did Bob read environment variables last week (if at all)?
-- What IP address was used for that action?
+    If you're using Infisical Cloud, then it is available under the **Team Tier**, **Pro Tier**,
+    and **Enterprise Tier** with varying retention periods. If you're self-hosting Infisical,
+    then you should contact team@infisical.com to purchase an enterprise license to use it.
+</Info>
 
-![Audit logs](../../images/activity-logs.png)
+Infisical provides audit logs for security and compliance teams to monitor information access. 
+With this feature, teams can track 25+ different events; 
+filter audit logs by event, actor, source, date or any combination of these filters;
+and inspect extensive metadata in the event of any suspicious activity or incident review.
+
+![Audit logs](../../images/platform/audit-logs/audit-logs-table.png)
+
+Each log contains the following data:
+
+- Event: The underlying action such as create, list, read, update, or delete secret(s).
+- Actor: The entity responsible for performing or causing the event; this can be a user or service.
+- Timestamp: The date and time at which point the event occured.
+- Source (User agent + IP): The software (user agent) and network address (IP) from which the event was initiated.
+- Metadata: Additional data to provide context for each event. For example, this could be the path at which a secret was fetched from etc.

docs/documentation/platform/folder.mdx

@@ -3,28 +3,50 @@ title: "Folders"
 description: "Organize your secrets with folders"
 ---
 
-Folders provide a powerful and intuitive way to structure your secrets.
-They offer a system to keep your secrets organized and easily accessible, which becomes increasingly important as your collection of secrets grows.
+Infisical's folder feature lets you store secrets at a specific folder; we also call this **path-based secret storage**. 
+This is great for organizing secrets around hierarchies when multiple services, types of secrets, etc. are involved at great quantities. 
+With folders that can go infinitely deep, you can mirror your application architecture (be it microservices or monorepos) 
+or any logical grouping that best suits your needs.
 
-With folders in Infisical, you can now create a hierarchy of folders to organize your secrets, mirroring your application's architecture or any logical grouping that suits your needs. 
-Whether you follow a microservices architecture or work with monorepos, folders make it simpler to locate, manage and collaborate between teams.
+Consider the following structure for a microservice architecture:
 
+```
+| service1
+|---- envars
+|---- users
+|-------- tokens1
+|-------- tokens2
+| service2
+|---- envars
+...
+```
 
-## Creating a folder
+In this example, we store environment variables for each microservice under each respective `/envars` folder. 
+We also store user-specific secrets for micro-service 1 under `/service1/users`. With this folder structure in place, your applications only need to specify a path like `/microservice1/envars` to fetch secrets from there.
+By extending this example, you can see how path-based secret storage provides a versatile approach to manage secrets for any architecture.
 
-To create a folder, head over to the environment where you'd like to create the folder. Once there, click the `Add folder` button as shown below.
-If you wish to create nested folders, simply click into the folder of choice and click `Add folder` button again.
+## Folders
 
-![dashboard add folders](../../images/dashboard-add-folder.png)
+### Managing folders
+
+To add a folder, press the downward chevron to the right of the **Add Secret** button; then press on the **Add Folder** button.
 
 <Info>
   Folder names can only contain alphabets, numbers, and dashes
 </Info>
 
-## Compare folders across environments
+![add folder](../../images/platform/folder/folders-add.png)
 
-The overview screen provides a comprehensive view of all your secrets and folders, organized by environment. 
+To delete a folder, hover over it and press the **X** button that appears on the right side.
 
-![dashboard secret overview with folders](../../images/dashboard-folder-overview.png)
+![delete folder](../../images/platform/folder/folders-delete.png)
 
-When you click on a folder, the overview will be updated to show only the secrets and folders in that folder. This allows you to compare secrets across environment regardless of how deeply nested your folders are.
+### Comparing folders
+
+It's possible to compare the contents of folders across environments in the **Secrets Overview** page.
+When you click on a folder, the table will display the items within it across environments.
+
+In the image below, you can see that the **Development** environment is the only one that contains items 
+in the `/users` folder, being other folders `/user-a`, `/user-b`, ... `/user-f`.
+
+![comparing folders](../../images/platform/folder/folders-secrets-overview.png)

docs/documentation/platform/ip-allowlisting.mdx

@@ -3,6 +3,20 @@ title: "IP Allowlisting"
 description: "Restrict access to your secrets in Infisical using trusted IPs"
 ---
 
+<Warning>
+  IP allowlisting at the project-level is being replaced with IP allowlisting at the token-level now available with the Service Token V3 authentication method.
+  
+  Instead of providing trusted IPs (specific IPs and CIDR ranges) to be applied across all service tokens, 
+  you can now specify trusted IPs at the token-level.
+  
+</Warning>
+<Info>
+  Note that IP Allowlisting is a paid feature.
+
+  If you're using Infisical Cloud, then it is available under the **Pro Tier**. If you're self-hosting Infisical,
+  then you should contact team@infisical.com to purchase an enterprise license to use it.
+</Info>
+
 Projects in Infisical can be configured to restrict client access to specific IP addresses or CIDR ranges. This applies to any client using service tokens and
 can be useful, for example, for limiting access to traffic coming from corporate networks.
 
@@ -13,7 +27,7 @@ For enhanced security, we strongly recommend replacing the default entry with yo
   You must be a project `admin` to manage your project's IP whitelist.
 </Note>
 
-![IP whitelist](../../images/project-ip-whitelist.png)
+![IP whitelist](../../images/platform/ip-allowlisting/ip-allowlisting-table.png)
 
 ## Creating a trusted IP entry
 
@@ -21,4 +35,4 @@ To create a trusted IP entry, head over to the **IP Whitelist** tab in your proj
 you can specify either a specific IP address like `192.0.2.1` or a CIDR range like `2001:db8::/32`; both IPv4 and IPv6
 formats are accepted.
 
-![IP whitelist add](../../images/project-ip-whitelist-add.png)
+![IP whitelist add](../../images/platform/ip-allowlisting/ip-allowlisting-modal.png)

docs/documentation/platform/organization.mdx

@@ -5,37 +5,63 @@ description: "How Infisical structures its organizations."
 
 An organization houses projects and members.
 
-By default, Infisical creates an organization under your name. You can manage your organization in your organization settings.
+## Projects
 
-![organization name modal open](../../images/dashboard-name-modal-organization.png)
-![organization name modal open](../../images/organization.png)
+The **Projects** page is where you can view the projects that you have access to within your organization
+as well as create a new project.
+
+![organization](../../images/platform/organization/organization-projects.png)
+
+## Settings
+
+The **Settings** page lets you manage information about your organization including:
+
+- Name: The name of your organization.
+- Incident contacts: Emails that should be alerted if anything abnormal is detected within the organization.
+- SAML Authentication: The SAML SSO configuration of the organization (if applicable); Infisical currently
+supports Okta, Azure, and JumpCloud identity providers.
+
+![organization settings general](../../images/platform/organization/organization-settings-general.png)
+![organization settings auth](../../images/platform/organization/organization-settings-auth.png)
 
 ## Members
 
-Members of an organization can create and add other members to projects within that organization.
-
-To add a member to your organization, scroll down to the "Organization Members" section and invite the member via email. They'll receive an email to confirm their organization invitation. If the member is an existing user on the platform, they will be automatically added to the organization.
+The **Members** page is where you can manage members and their permissions within the organization.
+In the **Members** tab, you can add external members to your organization or remove them; you can also
+change their role.
 
 ![organization members](../../images/organization-members.png)
 
-<Note>
-  Note that access to projects must be provisioned to new members after they've
-  accepted their organization invitation, and they will not be added to any
-  projects by default.
-</Note>
+In the **Roles** tab, you can manage roles for members within the organization. 
 
-## Service Accounts
+<Info>
+  Note that Role-Based Access Management (RBAC) is partly a paid feature.
+  
+  Infisical provides immutable roles like `admin`, `member`, etc.
+  at the organization and project level for free.
 
-Service accounts represent machine identities such as VMs or application clients that can authenticate with Infisical. They can be provisioned read/write permissions for project(s) and environment(s).
+  If you're using Infisical Cloud, the ability to create custom roles is available under the **Pro Tier**. 
+  If you're self-hosting Infisical, then you should contact team@infisical.com to purchase an enterprise license to use it.
+</Info>
 
-To add a service account to your organization, scroll down to the "Service Accounts" section and create a service account. Afterwards, you can press on the edit button beside the service account to provision it permissions.
+![organization roles](../../images/platform/organization/organization-members-roles.png)
 
-![organization service accounts](../../images/organization-service-accounts.png)
+As you can see next, Infisical supports granular permissions that you can tailor to each role. So,
+if you need certain members to only be able to access billing details, for example, then you can
+assign them that permission only.
 
-## Incident contacts
+![organization role permissions](../../images/platform/organization/organization-members-roles-add-perm.png)
 
-Incident contacts of an organization are alerted if anything abnormal is detected within the operations of an organization.
+## Usage & Billing
 
-To add an incident contact to your organization, scroll down to the "Incident Contacts" section and add their email.
+The **Usage & Billing** page applies only to [Infisical Cloud](https://app.infisical.com) and is where you can
+manage your plan and billing information.
 
-![organization incident contacts](../../images/organization-ic.png)
+This includes the following items:
+
+- Current plan: The current plan information such as what tier your organization is on and what features/limits apply to this tier.
+- Licenses: The license keys for self-hosted instances of Infisical (if applicable).
+- Receipts: The receipts of monthly/annual invoices.
+- Billing: The billing details of your organization including payment methods on file, tax IDs (if applicable), etc.
+
+![organization usage and billing](../../images/platform/organization/organization-usage-billing.png)

docs/documentation/platform/pit-recovery.mdx

@@ -3,26 +3,37 @@ title: "Point-in-Time Recovery"
 description: "How to rollback secrets and configs to any commit with Infisical."
 ---
 
-Point-in-time recovery allows secrets to be rolled back to any point in time. 
-It's powered by snapshots that get created after every mutations to a secret within a given [folder](./folder) and environment.
+<Info>
+  Point-in-Time Recovery is a paid feature.
+   
+  If you're using Infisical Cloud, then it is available under the **Team Tier**. If you're self-hosting Infisical,
+  then you should contact team@infisical.com to purchase an enterprise license to use it.
+</Info>
 
-## Commits
+Infisical's point-in-time recovery feature allows secrets to be rolled back to any point in time for any given [folder](./folder).
+Under the hood, snapshots, capturing the state of the folder, get taken after any mutation an item within that folder.
 
-Similar to Git, a commit in Infisical is a snapshot of your project's secrets at a specific point in time scoped to the environment and [folder](./folder) it is in. You can browse and view your project's snapshots via the "Point-in-Time Recovery" sidebar.
+## Snapshots
 
-![PIT commits](../../images/pit-commits.png)
-![PIT snapshots](../../images/pit-snapshots.png)
+Similar to Git, a commit (aka snapshot) in Infisical is the state of your project's secrets at a specific point in time scoped to 
+an environment and [folder](./folder) within it.
+
+To view a list of snapshots for the current folder, press the **Commits** button.
+
+![PIT commits](../../images/platform/pit-recovery/pit-recovery-commits.png)
+
+This opens up a sidebar from which you can select to view a particular snapshot:
+
+![PIT snapshots](../../images/platform/pit-recovery/pit-recovery-commits-drawer.png)
 
 ## Rolling back
 
-Secrets can be rolled back to any point in time via the "Rollback to this snapshot" button. This will roll back the changes within the given [folder](./folder) and environment to the chosen time.
+After pressing on a snapshot from the sidebar, you can view it and even roll back the state
+of the folder to that point in time by pressing the **Rollback** button. 
 
-It's important to note that this rollback action is localized and does not affect other folders within the same environment. This means each [folder](./folder) maintains its own independent history of changes, offering precise and isolated control over rollback actions.
-In essence, every [folder](./folder) possesses a distinct and separate timeline, providing granular control when managing your secrets. 
+![PIT snapshot](../../images/platform/pit-recovery/pit-recovery-rollback.png)
 
-![PIT snapshot](../../images/pit-snapshot.png)
+Rolling back secrets to a past snapshot creates a creates a snapshot at the top of the stack and updates secret versions.
 
-<Note>
-  Rolling back secrets to a past snapshot creates a new commit,
-  creates a snapshot at the top of the stack and updates secret versions.
-</Note>
+Note that rollbacks are localized to not affect other folders within the same environment. This means each [folder](./folder) maintains its own independent history of changes, offering precise and isolated control over rollback actions.
+Put differently, every [folder](./folder) possesses a distinct and separate timeline, providing granular control when managing your secrets. 

docs/documentation/platform/project.mdx

@@ -3,53 +3,101 @@ title: "Project"
 description: "How Infisical organizes secrets into projects."
 ---
 
-A project houses environment variables for an application.
+A project houses application configuration and secrets for an application.
 
-## Dashboard
+## Secrets Overview
 
-The dashboard page is where you can manage environment variables for a given project.
+The **Secrets Overview** page captures a birds-eye-view of secrets and folders across environments like development, staging, or production. 
+This is useful for comparing secrets, identifying if anything is missing, and making quick changes.
+
+![project secrets overview](../../images/platform/project/project-secrets-overview-open.png)
+
+## Secrets Dashboard
+
+The **Secrets Dashboard** page appears when you press to manage the secrets of a specific environment.
 
 ![project dashboard](../../images/dashboard.png)
 
-### Environment variables
+### Secrets
 
-Environment variables can be added or removed from a project. By default, they are pre-populated in your first project for demonstration. For any subsequent project, it can be convenient to import existing environment variables by dragging and dropping a .env file containing them.
+To add a secret, press **Add Secret** button at the top of the dashboard.
 
-Here's what dragging and dropping a .env looks like:
+![project add secret](../../images/platform/project/project-secrets-add.png)
 
-![project drag and drop](../../images/project-drag-drop.png)
+For a new project, it can be convenient to populate the dashboard by dropping a `.env` file into the provided pane as shown below:
 
-### Environments
+![project drop env file](../../images/platform/project/project-secrets-drop-env.png)
 
-In most cases, environment variables belong to specific environments: development, staging, testing, and production. You can input environment variables for each environment that your project uses.
+To delete a secret, hover over it and press the **X** button that appears on the right side.
 
-![project environment](../../images/project-environment.png)
+![project delete secret](../../images/platform/project/project-secrets-delete.png)
 
-### Personal overrides
+To delete multiple secrets at once, hover over and select the secrets you'd like to delete
+and press the **Delete** button that appears at the top.
 
-Every environment variable value can be overridden with a custom value.
-
-- An overridden value can only be read and accessed by the user that overrode the original shared value.
-- A (default) shared value can be read and accessed by other users in a project.
-
-You can turn overrides on/off by toggling the override/branch icon:
-
-![project variable toggle open](../../images/project-envar-override.png)
+![project delete secret batch](../../images/platform/project/project-secrets-delete-batch.png)
 
 ### Search
 
-You can search for any environment variable by its key.
+To search for specific secrets by their key name, you can use the search bar.
 
-![project search](../../images/project-search.png)
+![project search](../../images/platform/project/project-secrets-search.png)
+
+To assist you with finding secrets, you can also group them by similar prefixes and filter them by tags (if applicable).
+
+![project filter](../../images/platform/project/project-secrets-filter.png)
 
 ### Hide/Un-hide
 
-You can hide or un-hide the values of your environment variables. By default, the values are hidden for your privacy.
+To view/hide all secrets at once, toggle the hide or un-hide button.
 
-![project hide](../../images/project-hide.png)
+![project filter](../../images/platform/project/project-secrets-unhide.png)
 
 ### Download as .env
 
-You can download your environment variables back in a .env file.
+To download/export secrets back into a `.env` file, press the download button.
+
+![project download back env](../../images/platform/project/project-secrets-download-env.png)
+
+### Tags
+
+To better organize similar secrets, hover over them and label them with a tag.
+
+![project tag secret](../../images/platform/project/project-secrets-tag.png)
+
+### Comments
+
+To provide more context about a given secret, especially for your team, hover over it and press the comment button.
+
+![project comment secret](../../images/platform/project/project-secrets-comment.png)
+
+### Personal overrides
+
+Infisical employs the concept of **shared** and **personal** secrets to address the need
+for common and custom secret values, or branching, amongst members of a team during software development.
+To provide a helpful analogy: A shared value is to a `main` branch as a personal value is to a custom branch.
+
+Consider:
+
+- A team with users A, B, user C.
+- A project with an environment containing a shared secret called D with the value E.
+
+Suppose user A overrides the value of secret D with the value F.
+
+Then:
+
+- If user A fetches the secret D back, they get the value F.
+- If users B and C fetch the secret D back, they both get the value E.
+
+![project override secret](../../images/platform/project/project-secrets-override.png)
+
+### Drawer
+
+To view the full details of each secret, you can hover over it and press on the ellipses button.
+
+![project secrets ellipses](../../images/platform/project/project-secrets-ellipses.png)
+
+This opens up a side-drawer:
+
+![project secrets drawer](../../images/platform/project/project-secrets-drawer.png)
 
-![project download](../../images/project-download.png)

docs/documentation/platform/secret-reference.mdx

@@ -1,23 +1,39 @@
 ---
-title: "Reference and Import Secrets"
+title: "Secret Referencing / Importing"
 description: "How to use reference secrets in Infisical"
 ---
 
-Secret referencing is a powerful feature that allows you to values of other secrets. This way, you just need to update the secret value once for it to be propagated to all the references. 
+## Secret Referencing
 
-Consider a scenario where you have a database password. In order to utilize this password, you may need to incorporate it into a database connection string. 
-With secret referencing, you can easily construct these more intricate secrets by directly referencing the base secret.
-This centralizes the management of your base secret, as any updates made to it will automatically propagate to all the secrets that depend on it. 
+Infisical's secret referencing feature lets you reference the value of a "base" secret when defining the value of another secret.
+This means that updating the value of a base secret propagates directly to other secrets whose values depend on the base secret.
 
-## Referencing syntax
-<img src="../../images/example-secret-referencing.png" />
+<Note>
+    Currently, the secret referencing feature is only supported by the 
+    [Infisical CLI](/cli/overview) and [native integrations](/integrations/overview).
 
-Secret referencing relies on interpolation syntax. This syntax allows you to reference a secret in any environment or [folder](./folder). 
+    We intend to add support for it to the [Node SDK](https://github.com/Infisical/infisical-node)
+    and [Python SDK](https://github.com/Infisical/infisical-python) this quarter.
+</Note>
 
-To reference a secret named 'mysecret' in the same [folder](./folder) and environment, you'd use `${mysecret}`.
-However, to reference the same secret at the root of a different environment, for instance `dev` environment, you'd use `${dev.mysecret}`.
+![secret referencing](../../images/platform/secret-references-imports/secret-reference.png)
 
-Here are a few more examples to help you understand how to reference secrets in different contexts:
+Since secret referencing works by reconstructing values back on the client side, the client, be it a user or service token, fetching back secrets 
+must be permissioned access to all base and dependent secrets.
+
+For example, to access some secret `A` whose values depend on secrets `B` and `C` from different scopes, a client must have `read` access to the scopes of secrets `A`, `B`, and `C`.
+
+### Syntax
+
+When defining a secret reference, interpolation syntax is used to define references to secrets in other environments and [folders](./folder).
+
+Suppose you have some secret `MY_SECRET` at the root of some environment and want to reference part of its value from another base secret `BASE_SECRET` located elsewhere.
+Then consider the following scenarios:
+
+- If `BASE_SECRET` is in the same environment and folder as `MY_SECRET`, then you'd reference it using `${BASE_SECRET}`.
+- If `BASE_SECRET` is at the root of another environment with the slug `dev`, then you'd reference it using `${dev.MY_SECRET}`.
+
+Here are a few more helpful examples for how to reference secrets in different contexts:
 
 | Reference syntax                | Environment | Folder       | Secret Key |
 | --------------------- | ----------- | ------------ | ---------- |
@@ -25,29 +41,29 @@ Here are a few more examples to help you understand how to reference secrets in
 | `${dev.KEY2}`           | `dev`         | `/` (root of dev environment)            | KEY2       |
 | `${prod.frontend.KEY2}` | `prod`        | `/frontend`    | KEY2       |
 
-## Fetching fully constructed values
+## Secret Imports
 
-Secret referencing combines multiple secrets into one unified value, reconstructed only on the client side. To retrieve this value, you need access to read the environment and [folder](./folder) from where the secrets originate. 
-For instance, to access a secret 'A' composed of secrets 'B' and 'C' from different environments, you must have read access to both 'A' and 'B' 
+Infisical's secret imports feature lets you import the items of another environment or folder into the current folder context.
+This can be useful if you have common secrets that need to be available across multiple environments/folders.
 
-When using [service tokens](./token) to fetch referenced secrets, ensure the service token has read access to all referenced environments and folders. 
-Without proper permissions, the final secret value may be incomplete.
+To add a secret import, press the downward chevron to the right of the **Add Secret** button; then press on the **Add Import** button.
 
-## Import entire folders/environments
+![add secret import](../../images/platform/secret-references-imports/secret-import-add.png)
 
-While secret referencing effectively minimizes duplication, there might be instances where you need to import or replicate an entire folder's secrets into another. This can be achieved using the 'Import' feature.
+Once added, a secret import will show up with a green import icon on the secrets dashboard.
+In the example below, you can see that the items in the path `/some-folder` are being imported into
+the current folder context.
 
-This feature allows you to link secrets from one environment/folder into another environment/folder. It proves beneficial when you have common secrets that need to be available across multiple environments/folders.
+![added secret import](../../images/platform/secret-references-imports/secret-import-added.png)
 
-To add an import, simply click on the `Add import` button and provide the environment and secret path from where the secrets should be imported.
+To delete a secret import, hover over it and press the **X** button that appears on the right side.
 
-![secret import change order](../../images/secret-import-add.png)
+![delete secret import](../../images/platform/secret-references-imports/secret-import-delete.png)
 
-The hierarchy of importing secrets is governed by a "last-one-wins" rule. This means the sequence in which you import matters - the final folder imported will override secrets from any prior folders. 
-Additionally, any secrets you define directly in your environment will override any secrets that are imported with the same name.
+Lastly, note that the order of secret imports matters. If two secret imports contain secrets with the same name, then the secret value from the bottom-most secret import is taken — "the last one wins."
 
-You can modify the order of folders to control overrides using the `Change Order` drag handle.
+To reorder a secret import, hover over it and drag the arrows handle to the position you want.
 
-![secret import change order](../../images/secret-import-change-order.png)
+![reorder secret import](../../images/platform/secret-references-imports/secret-import-reorder.png)
 
 <iframe width="560" height="315" src="https://www.youtube.com/embed/o11bMU0pXRs?si=dCprt3xLWPrSOJxy" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>