changes

components/osx/modules/ROOT/pages/how-it-works/framework-dao.adoc

@@ -1,8 +1,6 @@
----
-title: Protocol Governance
----
+= Protocol Governance
 
-## Governing the Aragon OSx Framework
+=== Governing the Aragon OSx Framework
 
 To govern the framework infrastructure, a **Framework DAO** was deployed.
 

components/osx/modules/ROOT/pages/how-it-works/framework/ens-names.adoc

@@ -1,14 +1,11 @@
----
-title: ENS Names
----
+= ENS Names
 
-## Unique DAO and Plugin Repo Names
+=== Unique DAO and Plugin Repo Names
 
-To make DAOs and plugin repositories easily identifiable in the Aragon OSx ecosystem, we assign unique ENS names to them upon registration during the [DAO creation](./01-dao-creation/index.md) and [plugin publishing](./02-plugin-management/01-plugin-repo/01-plugin-repo-creation.md) processes.
+To make DAOs and plugin repositories easily identifiable in the Aragon OSx ecosystem, we assign unique ENS names to them upon 
+registration during the xref:how-it-works/framework/dao-creation/index.adoc[DAO creation] and xref:how-it-works/framework/plugin-management/plugin-repo/plugin-repo-creation.md[plugin publishing] processes.
 
-:::info
-You can skip registering an ENS name for your DAO under the `dao.eth` by leaving the [`DAOSettings.subdomain` field](../../03-reference-guide/framework/dao/DAOFactory.md#public-struct-daosettings) empty when calling the [`createDao`](../../03-reference-guide/framework/dao/DAOFactory.md#external-function-createdao) function.
-:::
+TIP: You can skip registering an ENS name for your DAO under the `dao.eth` by leaving the TODO:GIORGI [`DAOSettings.subdomain` field](../../03-reference-guide/framework/dao/DAOFactory.md#public-struct-daosettings) empty when calling the [`createDao`](../../03-reference-guide/framework/dao/DAOFactory.md#external-function-createdao) function.
 
 ### Allowed Character Set
 

components/osx/modules/ROOT/pages/how-to-guides/dao/action-execution.adoc

@@ -1,33 +1,29 @@
----
-title: Executing actions on behalf of the DAO
----
+= Executing actions on behalf of the DAO
 
 ## Using the DAO Executor
 
-Executing actions on behalf of the DAO is done through the `execute` function from the `DAO.sol` contract. This function allows us to [pass an array of actions)](https://github.com/aragon/osx/blob/develop/packages/contracts/src/core/dao/DAO.sol) to be executed by the DAO contract itself.
+Executing actions on behalf of the DAO is done through the `execute` function from the `DAO.sol` contract. This function allows us to link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/core/dao/DAO.sol[pass an array of actions] to be executed by the DAO contract itself.
 
-However, for the `execute` call to work, the address calling the function (the `msg.sender`) needs to have the [`EXECUTE_PERMISSION`](../../01-how-it-works/01-core/02-permissions/index.md#permissions-native-to-the-dao-contract). This is to prevent anyone from being able to execute actions on behalf of the DAO and keep your assets safe from malicious actors.
+However, for the `execute` call to work, the address calling the function (the `msg.sender`) needs to have the xref:how-it-works/core/permissions/index.adoc#permissions-native-to-the-dao-contract[`EXECUTE_PERMISSION`]. This is to prevent anyone from being able to execute actions on behalf of the DAO and keep your assets safe from malicious actors.
 
 ## How to grant the Execute Permission
 
 Usually, the `EXECUTE_PERMISSION` is granted to a governance plugin of the DAO so that only the approved proposals can be executed. For example, we'd grant the `EXECUTE_PERMISSION` to the address of the Multisig Plugin. That way, when a proposal is approved by the required members of the multisig, the plugin is able to call the `execute` function on the DAO in order to get the actions executed.
 
-To grant the `EXECUTE_PERMISSION` to an address, you'll want to call on the `PermissionManager`'s [`grant` function](https://github.com/aragon/osx/blob/develop/packages/contracts/src/core/permission/PermissionManager.sol#L105) and pass it 4 parameters:
+To grant the `EXECUTE_PERMISSION` to an address, you'll want to call on the `PermissionManager`'s link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/core/permission/PermissionManager.sol#L105[grant function] and pass it 4 parameters:
 
 - `where`: the address of the contract containing the function `who` wants access to
 - `who`: the address (EOA or contract) receiving the permission
 - `permissionId`: the permission identifier the caller needs to have in order to be able to execute the action
 - `condition`: the address of the condition contract that will be asked (if any) before authorizing the call to happen
 
-:::caution
-You probably don't want to grant `EXECUTE_PERMISSION` to any random address, since this gives the address access to execute any action on behalf of the DAO. We recommend you only grant `EXECUTE_PERMISSION` to governance plugins to ensure the safety of your assets. Granting `EXECUTE_PERMISSION` to an externally owned account is considered an anti-pattern.
-:::
+CAUTION: You probably don't want to grant `EXECUTE_PERMISSION` to any random address, since this gives the address access to execute any action on behalf of the DAO. We recommend you only grant `EXECUTE_PERMISSION` to governance plugins to ensure the safety of your assets. Granting `EXECUTE_PERMISSION` to an externally owned account is considered an anti-pattern.
 
 ## Examples
 
 ### Calling a DAO Function
 
-Imagine you want to call an internal function inside the `DAO` contract, for example, to manually [grant or revoke a permission](../../01-how-it-works/01-core/02-permissions/index.md). The corresponding `Action` and `execute` function call look as follows:
+Imagine you want to call an internal function inside the `DAO` contract, for example, to manually xref:how-it-works/core/permissions/index.adoc[grant or revoke a permission]. The corresponding `Action` and `execute` function call look as follows:
 
 ```solidity
 function exampleGrantCall(
@@ -54,13 +50,11 @@ function exampleGrantCall(
 }
 ```
 
-Here we use the selector of the [`grant` function](../../03-reference-guide/core/permission/PermissionManager.md#external-function-grant). To revoke the permission, the selector of the [`revoke` function](../../03-reference-guide/core/permission/PermissionManager.md#external-function-revoke) must be used.
+Here we use the selector of the TODO:GIORGI [`grant` function](../../03-reference-guide/core/permission/PermissionManager.md#external-function-grant). To revoke the permission, the selector of the [`revoke` function](../../03-reference-guide/core/permission/PermissionManager.md#external-function-revoke) must be used.
 
-If the caller possesses the [`ROOT_PERMISSION_ID` permission](../../01-how-it-works/01-core/02-permissions/index.md#permissions-native-to-the-dao-contract) on the DAO contract, the call becomes simpler and cheaper:
+If the caller possesses the xref:how-it-works/core/permissions/index.adoc#permissions-native-to-the-dao-contract[`ROOT_PERMISSION_ID` permission] on the DAO contract, the call becomes simpler and cheaper:
 
-:::caution
-Granting the `ROOT_PERMISSION_ID` permission to other contracts other than the `DAO` contract is dangerous and considered as an anti-pattern.
-:::
+CAUTION: Granting the `ROOT_PERMISSION_ID` permission to other contracts other than the `DAO` contract is dangerous and considered as an anti-pattern.
 
 ```solidity
 function exampleGrantFunction(DAO dao, address _where, address _who, bytes32 _permissionId) {
@@ -123,7 +117,7 @@ function exampleFunctionCall(
 
 ### Calling a Payable Function
 
-Wrap `0.1 ETH` from the DAO treasury into `wETH` by depositing it into the [Goerli WETH9 contract](https://goerli.etherscan.io/token/0xb4fbf271143f4fbf7b91a5ded31805e42b2208d6#writeContract).
+Wrap `0.1 ETH` from the DAO treasury into `wETH` by depositing it into the link:https://goerli.etherscan.io/token/0xb4fbf271143f4fbf7b91a5ded31805e42b2208d6#writeContract[Goerli WETH9 contract].
 The corresponding `Action` and `execute` function call look as follows:
 
 ```solidity

components/osx/modules/ROOT/pages/how-to-guides/dao/best-practices.adoc

@@ -1,8 +1,6 @@
----
-title: Best Practices
----
+= Best Practices
 
-## Some Advice When Operating your DAO
+=== Some Advice When Operating your DAO
 
 ### DOs 👌
 

components/osx/modules/ROOT/pages/how-to-guides/dao/index.adoc

@@ -1,7 +1,4 @@
----
-title: How to Operate a DAO
-sidebar_label: Operating a DAO
----
+= How to Operate a DAO
 
 DAOs are decentralized autonomous organizations. They are a group of people managing on-chain assets through a set of smart contracts.
 
@@ -11,18 +8,13 @@ DAOs manage assets through collective decision-making mechanisms. Although a lot
 
 In Aragon OSx, DAOs are a treasury and a permission management system - all other functionality is enabled through "capsules of opt-in functionality allowing the DAO to work in custom ways". These are called Plugins.
 
-:::note
-Plugins are smart contracts which extend the functionality of what the DAO can do. They are able to execute actions on behalf of the DAO through permissions the DAO grants or revokes them.
-:::
+NOTE: Plugins are smart contracts which extend the functionality of what the DAO can do. They are able to execute actions on behalf of the DAO through permissions the DAO grants or revokes them.
 
 Decision-making mechanisms are one example of Plugins. Treasury management, action bundles, or connections to other smart contracts are others.
 
-<!-- To-do: add image here with use cases -->
-<!-- To-do: link to the project's dashboard showcasing all projects built using our stack -->
-
 In this section, we'll go through how to operate and maintain your DAO:
 
-- [A Summary of Best Practices](./01-best-practices.md)
-- [How to execute actions on behalf of the DAO](./02-action-execution.md)
-- [How to manage a DAO's plugins](./04-managing-plugins/index.md)
-- [How to upgrade your DAO to a future Aragon OSx Releases](./03-protocol-upgrades.md)
+- xref:how-to-guides/dao/best-practices.adoc[A Summary of Best Practices]
+- xref:how-to-guides/dao/action-execution.adoc[How to execute actions on behalf of the DAO]
+- xref:how-to-guides/dao/managing-plugins.adoc[How to manage a DAO's plugins]
+- xref:how-to-guides/dao/protocol-upgrades.adoc[How to upgrade your DAO to a future Aragon OSx Releases]

components/osx/modules/ROOT/pages/how-to-guides/dao/managing-plugins.adoc

@@ -1,50 +1,48 @@
----
-title: Manage your DAO's Plugins
----
+= Manage your DAO's Plugins
 
-## How to manage the Plugins within your DAO
+=== How to manage the Plugins within your DAO
 
-<!-- TODO This page needs improvements -->
+You can install, uninstall or update any plugin into your DAO. If you want to dive deeper into plugins, check out xref:how-it-works/core/plugins/index.adoc[how plugins work here].
 
-You can install, uninstall or update any plugin into your DAO. If you want to dive deeper into plugins, check out [how plugins work here](../../../01-how-it-works/01-core/03-plugins/index.md).
-
-Before diving deeper into this guide, make sure that you understand [permissions](../../../01-how-it-works/01-core/02-permissions/index.md) and know about the [DAO executor](../../../01-how-it-works/01-core/01-dao/index.md).
+Before diving deeper into this guide, make sure that you understand xref:how-it-works/core/permissions/index.adoc[permissions]and know about the xref:how-it-works/core/dao/index.adoc[DAO executor].
 
 #### How to create a DAO with Plugins
 
 When you create your DAO, you must **install at least one functioning governance plugin** (meaning one plugin having the `EXECUTION_PERMISSION`) so your have a mechanism of executing actions on behalf of your DAO.
 This is crucial because otherwise nobody can operate the DAO and it would become incapacitated right after it was created. You would have spent gas for nothing.
 
-:::info
-If you create your DAO through the [Aragon App](https://app.aragon.org) or the [Aragon SDK](https://devs.aragon.org/docs/sdk), this will be checked and you will be warned in case you have not selected a suitable Aragon plugin.
-:::
-
-Although the easiest (and recommended) way to create your DAO is through the [Aragon App](https://app.aragon.org) or the [Aragon SDK](https://devs.aragon.org/docs/sdk), you can also do it directly from the protocol through calling on the [`createDAO` function](https://github.com/aragon/osx/blob/develop/packages/contracts/src/framework/dao/DAOFactory.sol#L63) from the `DAOFactory` contract and passing it the calldata `DAOSettings` for your DAO as well as the `PluginSettings` array referencing the plugins and the settings to be installed upon DAO creation.
+NOTE: If you create your DAO through the link:https://app.aragon.org[Aragon App] or the link:https://devs.aragon.org/docs/sdk[Aragon SDK], this will be checked and you will be warned in case you have not selected a suitable Aragon plugin.
 
-<!-- TODO: Let's add a code example here on how the call to this function would look -->
+Although the easiest (and recommended) way to create your DAO is through the link:https://app.aragon.org[Aragon App] or 
+the link:https://devs.aragon.org/docs/sdk[Aragon SDK], you can also do it directly from the protocol through calling 
+on the link:https://github.com/aragon/osx/blob/develop/packages/contracts/src/framework/dao/DAOFactory.sol#L63[`createDAO` function] 
+from the `DAOFactory` contract and passing it the calldata `DAOSettings` for your DAO as well as the `PluginSettings` array 
+referencing the plugins and the settings to be installed upon DAO creation.
 
 #### How to change a DAO's Governance Setup after a DAO has been created
 
-After a DAO is created with at least one plugin installed with `EXECUTE_PERMISSION` on the DAO, it's likely you may want to change change your governance setup later on by [installing, updating, or uninstalling plugins](../../../01-how-it-works/02-framework/02-plugin-management/02-plugin-setup/index.md).
+After a DAO is created with at least one plugin installed with `EXECUTE_PERMISSION` on the DAO, it's likely you may want to change change your governance setup later 
+on by xref:how-it-works/framework/plugin-management/plugin-setup/index.adoc[installing, updating, or uninstalling plugins].
 
-Here, it is very important that you **maintain at least one functioning governance plugin** (a contract with `EXECUTE_PERMISSION` on the DAO) so that your assets are not locked in the future. In that regard, you want to be careful to not accidentally:
+Here, it is very important that you **maintain at least one functioning governance plugin** (a contract with `EXECUTE_PERMISSION` on the DAO) so that your 
+assets are not locked in the future. In that regard, you want to be careful to not accidentally:
 
 - uninstall every plugin within your DAO, or
 - update or upgrade the plugin or otherwise change the internal plugin settings.
 
-If you do that, nobody would be able to create proposals and execute actions on the DAO anymore. Accordingly, DAOs must review proposals requesting to change the governance setup with utmost care before voting for them. In the next section, we explain how to review a proposal properly and what to pay attention too.
-
-<!-- Make a separate section about the DAO executor -->
+If you do that, nobody would be able to create proposals and execute actions on the DAO anymore. Accordingly, DAOs must review 
+proposals requesting to change the governance setup with utmost care before voting for them. In the next section, 
+we explain how to review a proposal properly and what to pay attention too.
 
 ### How to maintain Execution Permission on the DAO
 
 A very important thing to consider when operating your DAO is to make sure that you do not lock it - meaning, you allow it into a state where the DAO cannot execute actions anymore.
 
-The accidental loss of the permission to execute actions on your DAO ([the `EXECUTION_PERMISSION_ID` permission](../../../01-how-it-works/01-core/02-permissions/index.md#permissions-native-to-the-dao-contract)) incapacitates your DAO. If this happens, you are not able to withdraw funds or act through the DAO, unless you have the `ROOT_PERMISSION_ID` on the DAO.
+The accidental loss of the permission to execute actions on your DAO (xref:how-it-works/core/permissions/index.adoc#permissions-native-to-the-dao-contract[the `EXECUTION_PERMISSION_ID` permission]) incapacitates your DAO. 
+If this happens, you are not able to withdraw funds or act through the DAO, unless you have the `ROOT_PERMISSION_ID` on the DAO.
 
-:::danger
-Do not interact directly with the smart contracts unless you know exactly what you are doing, **especially if this involves granting or revoking permissions**. Instead, use the Aragon App or Aragon SDK for creating and managing your DAO and interacting with the smart contracts.
-:::
+IMPORTANT: Do not interact directly with the smart contracts unless you know exactly what you are doing, **especially if this involves granting or revoking permissions**. 
+Instead, use the Aragon App or Aragon SDK for creating and managing your DAO and interacting with the smart contracts.
 
-If you interact with the Aragon OSx protocol through the Aragon App frontend or the Aragon SDK and use only audited and verified plugins, this will not happen.
-However, diligence and care is required in some situations.
+If you interact with the Aragon OSx protocol through the Aragon App frontend or the Aragon SDK and use only audited and verified plugins, 
+this will not happen. However, diligence and care is required in some situations.

components/osx/modules/ROOT/pages/how-to-guides/dao/protocol-upgrades.adoc

@@ -1,13 +1,11 @@
----
-title: Upgrade your DAO to future Aragon OSx Versions
----
+= Upgrade your DAO to future Aragon OSx Versions
 
-## Upgrading to Future Aragon OSx Protocol Versions
+=== Upgrading to Future Aragon OSx Protocol Versions
 
 At Aragon, we are constantly working on improving the Aragon OSx framework.
 
 To make it easy for your DAO to switch to future Aragon OSx protocol versions, we added the possibility to upgrade our protocol in the future.
 
 Whenever we provide a new Aragon OSx protocol version, it will be possible to upgrade your DAO and associated plugins through your DAO dashboard.
 
-[Add your email here](https://aragondevelopers.substack.com/) if you'd like to receive updates when this happens!
+link:https://aragondevelopers.substack.com/[Add your email here] if you'd like to receive updates when this happens!

components/osx/modules/ROOT/pages/how-to-guides/index.adoc

@@ -1,9 +1,6 @@
----
-title: Tutorials
-sidebar_label: Tutorials
----
+= Tutorials
 
-## Welcome to our Tutorials on Using the Aragon OSx Protocol!
+=== Welcome to our Tutorials on Using the Aragon OSx Protocol!
 
 With a few lines of code, the Aragon OSx protocol allows you create, manage, and change your on-chain organizations, through extending functionality for DAOs through the installation and uninstallation of plugins.
 
@@ -36,13 +33,14 @@ On the technical level, plugins are composed of two key contracts:
 - ⚡️ The Plugin implementation contract: containing all of the logic and functionality for your DAO, and
 - 👩🏻‍🏫 The Plugin Setup contract: containing the installation, uninstallation and upgrade instructions for your plugin.
 
-![Aragon OSx Plugins](/img/plugins/what_is_a_plugin.png)
+image::../../../../../_/images/img/plugins/what_is_a_plugin.png[align="center"]
+
 
 Through plugins, we provide a secure, flexible way for on-chain organizations to iterate as they grow.
 
 We enable everyone to experiment with governance at the speed of software!
 
 Check out our How-To-Guides on:
 
-- [How to Develop your own Plugin](./02-plugin-development/index.md)
-- [How to Operate your DAO](./01-dao/index.md)
+- xref:how-to-guides/plugin-development/index.adoc[How to Develop your own Plugin]
+- xref:how-to-guides/dao/index.adoc[How to Operate your DAO]