docs: Advanced PSP docs 1st iteration

docs/advanced/psp/index.md

@@ -1,29 +1,32 @@
 ---
-title: Introduction
+title: Plugin Setup Processor
 sidebar_label: Introduction
 sidebar_position: 0
 ---
 
 ## Introduction to Plugin Setup Processor (PSP)
 
-The Plugin Setup Processor (PSP) is the component of the Aragon OSx framework which connects plugins and DAOs. Created and maintained by Aragon, the PSP is a non upgradeable smart contract and has undergone rigorous audits to ensure transparency and safety. This contracts governs how plugins are integrated into your DAO, handling the necessary permissions to install/uninstall/upgrade plugins into/from your DAO.
+The Plugin Setup Processor (PSP) is a crucial component of the Aragon OSx framework, facilitating the integration of plugins with DAOs. Created and maintained by Aragon, the PSP is a non-upgradeable smart contract that has undergone rigorous audits to ensure transparency and safety. This contract governs how plugins are managed within your DAO, handling the necessary permissions to install, uninstall, or upgrade plugins.
 
 ### Why is the PSP Important?
 
-The PSP ensures that any changes made to the DAO’s functionality via plugins are secure and transparent. It uses a prepared setup from the `PluginSetup.sol` contract to manage the installation process, granting or revoking permissions as needed to incorporate/drop the new functionality into/from the DAO. This method guarantees that DAO members are aware of the changes being made and can trust the process.
+Managing plugins is a delicate task that must be approached with utmost caution. The PSP ensures that any changes made to the DAO’s functionality via plugins are secure and transparent. It utilizes a prepared setup from the `PluginSetup.sol` contract to prepare the installation process. Then proceeds to the installation process granting or revoking permissions as needed to incorporate or remove functionalities within the DAO.
+This method guarantees that DAO members are aware of the changes being made and can trust the process.
 
 ## Interactions with the PSP
 
 ### During DAO Deployment
 
-When you deploy your DAO using the `DAOFactory.sol` contract, the PSP is utilized to install the necessary plugins. A DAO requires at least one plugin to function, and the `DAOFactory` simplifies this process by handling the setup for you. You simply provide an array of settings, where each position corresponds to a different plugin, and the `DAOFactory` takes care of the rest.
+When you deploy your DAO using the `DAOFactory.sol` contract, the PSP is utilized to install the necessary plugins. A DAO requires at least one plugin to function, and the `DAOFactory` expects you to install at least one plugin during the creation process.
 
-### After DAO Deployment
+During this process, the `ROOT_PERMISSION_ID` is granted to the PSP to allow it to prepare and apply the installation of your requested plugin. Once the plugin is installed, the `ROOT_PERMISSION_ID` is revoked from the PSP.
 
-Once your DAO is deployed, you might want to install additional plugins, or uninstall or upgrade existing ones. In these cases, the PSP comes into play again. Here, you need to have an approved proposal that includes actions for both the preparation and application phases of the installation process. Alternatively, you might need two separate proposals, one for each phase.
+### After DAO Deployment
 
-### Summary
+Once your DAO is deployed, you might want to install additional plugins, or uninstall or upgrade existing ones. In these cases, the PSP comes into play again. Here, you need to prepare the plugin using the `PluginSetup` and then have an approved proposal in your DAO to apply the prepared process.
 
-The PSP is a foundational element of the Aragon DAO ecosystem, ensuring that plugins can be managed in a secure and transparent manner. By leveraging the PSP, you can confidently extend the functionality of your DAO, knowing that the process is robust and reliable.
+:::note
+For the PSP to grant or revoke permissions within your DAO, it must have the `ROOT_PERMISSION_ID` permission. Therefore, the proposal for applying the plugin installation, uninstallation, or upgrade must include a first action granting `ROOT_PERMISSION_ID` to the PSP and a final action revoking this permission from it.
+:::
 
-For a detailed walkthrough of the plugin management process, including installation, uninstallation, and upgrades, please refer to the [Managing Plugins](./managing-plugins.md) section.
+For more details on how the two step process works in Aragon OSx using PSP and `PluginSetup` visit the next section [Managing Plugins](./managing-plugins.md)

docs/advanced/psp/managing-plugins.md

@@ -15,19 +15,19 @@ The following explanation will take as example the installation process, however
 This is why we see the installation process in two phases:
 
 1. **Preparation:** Defining the parameters to be set on the new plugin instance and helpers, as well as requesting the permissions needed for it to work properly. The `PluginSetup` contains the setup script where developers can perform any unprivileged operations. These will need a privileged confirmation in the next step.
-2. **Application:** The granting or revoking of the plugin's requested permissions (based on the preparation step above). This is a privileged action performed by Aragon's `PluginSetupProcessor` (you can understand it as the "installer"), so that the plugin becomes effectively installed or uninstalled. It gets executed whenever someone with `ROOT` privileges on the DAO applies it (most likely through a proposal).
+2. **Application:** The granting or revoking of the plugin's requested permissions (based on the preparation step above). This is a privileged action performed by Aragon's `PluginSetupProcessor` (you can understand it as the "installer"), so that the plugin becomes effectively installed. It gets executed whenever someone with `ROOT` privileges on the DAO applies it (most likely through a proposal).
 
 The `PluginSetupProcessor` is the Aragon contract in charge of invoking the `prepareInstallation()` function from your plugin's `PluginSetup` contract and use it to prepare the installation and (eventually) apply it once it has been approved by the DAO.
 
 #### What happens during the Plugin Preparation?
 
 The preparation of a `PluginSetup` contract proceeds as follows:
 
-1. A DAO builder selects a plugin to install, uninstall, or update.
+1. A DAO builder selects a plugin to install.
 
-2. The DAO builder defines the parameters and settings that he/she wants for their DAO. Depending on the case, the `prepareInstallation`, `prepareUpdate`, or `prepareUninstallation` method in the `PluginSetup` contract is called through the `PluginSetupProcessor` (and creates a unique setup ID).
+2. The DAO builder defines the parameters and settings that he/she wants for their DAO. The `prepareInstallation` method in the `PluginSetup` contract is called through the `PluginSetupProcessor` (and creates a unique setup ID).
 
-3. The [`PluginSetup`](https://github.com/aragon/osx/blob/develop/packages/contracts/src/framework/plugin/setup/PluginSetupProcessor.sol) contract deploys all the contracts and gathers addresses and other input arguments required for the installation/uninstallation/upgrade instructions.
+3. The [`PluginSetup`](https://github.com/aragon/osx/blob/develop/packages/contracts/src/framework/plugin/setup/PluginSetupProcessor.sol) contract deploys all the contracts and gathers addresses and other input arguments required for the installation instructions.
 
    Because the addresses of all associated contracts are now known, a static permission list can be emitted, hashed, and stored on-chain.
 
@@ -55,7 +55,7 @@ Once the proposal has passed, the actions specified in the `Action[]` array can
 This is processed as follows:
 
 1. The DAO temporarily grants the `ROOT_PERMISSION_ID` permission to the `PluginSetupProcessor`. This is needed so that the processor can modify the DAO's permissions settings to set up the plugin.
-2. This `Action` calls the `applyInstallation`, `applyUpdate`, or `applyUninstallation` method in the `PluginSetupProcessor`, containing the list of requested permissions as argument. The permissions hash is compared with the stored hash to make sure that no permission was changed.
+2. This `Action` calls the `applyInstallation` method in the `PluginSetupProcessor`, containing the list of requested permissions as argument. The permissions hash is compared with the stored hash to make sure that no permission was changed.
    In addition to the above, the update process also upgrades the logic contract to which the proxy points too.
 3. If the hash is valid, the list is processed and `PluginSetupProcessor` conducts the requested sequence of `grant`, `grantWithCondition` and `revoke` calls on the owning DAO.
    Finally, the `PluginSetupProcessor` asks the DAO to revoke the `ROOT_PERMISSION_ID` permission from itself.
@@ -64,8 +64,6 @@ This is processed as follows:
 The two-step setup procedure in Aragon OSx is not limited to the setup of only one plugin — you can **setup multiple plugins at once** by first preparing them in a single proposal and then processing the entire setup sequence in one transaction. This is powerful and allows you to **transform your entire DAO in one proposal**, for example, to install a new governance plugin (e.g., a gasless ZK-vote) and finance plugin (e.g., to stream loans to your members), while uninstalling your old ERC20 token vote in one go.
 :::
 
-In the next sections, you will learn about how plugins are curated on Aragon's repository.
-
 <div class="center-column">
 
 **a.** ![Schematic depiction of the plugin installation process.](/optimized-svg/plugins/plugin-installation.drawio.svg)