feat: docs improve heading and content on pages

packages/contracts/docs/antora.yml

@@ -1,5 +1,5 @@
 name: osx-contracts
-title: Core
+title: OSX Contracts
 version: 1.x
 prerelease: false
 nav:

packages/contracts/docs/config.js

@@ -8,7 +8,7 @@ const helpers = require(path.resolve(__dirname, './templates/helpers'));
 // overwrite the functions.
 helpers.version = () => version;
 helpers.githubURI = () => repository.url;
-helpers.readmePath = (opts) => {
+helpers['readme-path'] = opts => {
   return 'src/' + opts.data.root.id.replace(/\.adoc$/, '') + '/README.adoc';
 };
 

packages/contracts/docs/modules/ROOT/pages/core/dao.adoc

@@ -6,48 +6,50 @@ In this section, you will learn about the core functionality of every Aragon OSx
 
 The `DAO` contract is the identity and basis of your organization. It is the address carrying the DAO’s ENS name, metadata, and holding the funds. Furthermore, it has **six base functionalities** being commonly found in other DAO frameworks in the ecosystem.
 
-### 1. Execution of Arbitrary Actions
+=== 1. Execution of Arbitrary Actions
 
 The most important and basic functionality of your DAO is the **execution of arbitrary actions**, which allows you to execute the DAO's own functions as well as interacting with the rest of the world, i.e., calling methods in other contracts and sending assets to other addresses.
 
-NOTE: Typically, actions are scheduled in a proposal in a governance - xref:core/plugins.adoc[plugin installed to your DAO]
+NOTE: Actions are typically executed through governance proposals. These proposals can implement various decision-making mechanisms, such as token-weighted voting or multisig requirements, and may include execution delays to ensure proper governance oversight before actions are executed.
 
 Multiple `Action` structs can be put into one `Action[]` array and executed in a single transaction via the `execute` function. To learn more about actions and advanced features of the DAO executor, visit the xref:core/actions.adoc[A Deep Dive Into Actions].
 
-### 2. Asset Management
+=== 2. Asset Management
 
-The DAO provides basic **asset management** functionality to deposit, withdraw, and keep track of
+The DAO provides basic **asset management** functionality to deposit, withdraw, and keep track of:
 
-- native
-- link:https://eips.ethereum.org/EIPS/eip-20[ERC-20 (Token Standard)]
-- link:https://eips.ethereum.org/EIPS/eip-721[ERC-721 (NFT Standard)], and
-- link:https://eips.ethereum.org/EIPS/eip-1155[ERC-1155 (Multi Token Standard)]
+* native ETH
+* link:https://eips.ethereum.org/EIPS/eip-20[ERC-20 (Token Standard)]
+* link:https://eips.ethereum.org/EIPS/eip-721[ERC-721 (NFT Standard)]
+* link:https://eips.ethereum.org/EIPS/eip-1155[ERC-1155 (Multi Token Standard)]
 
 tokens in the treasury.
-In the future, more advanced asset management and finance functionality can be added to your DAO in the form of xref:core/plugins.adoc[plugins].
+In the future, more advanced asset management and finance functionality can be added to your DAO by installing additional plugins.
 
-### 3. Upgradeability
+NOTE: Don't worry if you're not familiar with plugins yet - they will be explained in detail in a later section. For now, you can think of them just like plugins in other software: modular pieces that provide new features and can be plugged in or removed as needed.
+
+=== 3. Upgradeability
 
 Your DAO contract has the ability to be upgraded to a newer version (see xref:guide-develop-plugin/upgrade-plugin.adoc[Upgrade your DAO]) if a new version of Aragon OSx is released in the future. These upgrades allow your DAO to smoothly transition to a new protocol version unlocking new features.
 
 
-### 4. Callback Handling
+=== 4. Callback Handling
 
 To interact with the DAO, external contracts might require certain callback functions to be present.
 Examples are the `onERC721Received` and `onERC1155Received` / `onERC1155BatchReceived` functions required by the link:https://eips.ethereum.org/EIPS/eip-721[ERC-721 (NFT Standard)] and link:https://eips.ethereum.org/EIPS/eip-1155[ERC-1155 (Multi Token Standard)] tokens.
 Our `CallbackHandler` allows to register the required callback responses dynamically so that the DAO contract does not need to be upgraded.
 
-### 5. Signature Validation
+=== 5. Signature Validation
 
-Currently, externally owned accounts (EOAs) can sign messages with their associated private keys, but contracts cannot.
+Currently, Externally Owned Accounts (EOAs) can sign messages with their associated private keys, but contracts cannot.
 An exemplary use case is a decentralized exchange with an off-chain order book, where buy/sell orders are signed messages.
 To accept such a request, both, the external service provider and caller need to follow a standard with which the signed message of the caller can be validated.
 
 By supporting the link:https://eips.ethereum.org/EIPS/eip-721[ERC-721 (NFT Standard)], your DAO can validate signatures via its `isValidSignature` function that forwards the call to a signature validator contract.
 
-### 6. Permission Management
+=== 6. Permission Management
 
-Lastly, it is essential that only the right entities (e.g., the DAO itself or trusted addresses) have permission to use the above-mentioned functionalities. This is why Aragon OSx DAOs contain a flexible and battle-tested **permission manager** being able to assign permissions for the above functionalities to specific addresses.
+Lastly, it is essential that only the right entities (e.g., the DAO itself or trusted addresses) have permission to use the above-mentioned functionalities. This is why Aragon OSx DAOs contain a flexible and battle-tested **Permission Manager** being able to assign permissions for the above functionalities to specific addresses.
 Although possible, the permissions to execute arbitrary actions or upgrade the DAO should not be given to EOAs as this poses a security risk to the organization if the account is compromised or acts adversarial. Instead, the permissions for the above-mentioned functionalities are better restricted to the `DAO` contract itself and triggered through governance xref:core/plugins.adoc[plugins] that you can install on your DAO.
 
-To learn more, visit the xref:core/permissions.adoc[permission manager] section.
+To learn more about permissions and how they work in detail, check out the xref:core/permissions.adoc[Permission Manager] section.

packages/contracts/docs/modules/ROOT/pages/core/index.adoc

@@ -1,22 +1,27 @@
-= The Smart Contracts behind DAOs
+= The Contracts behind DAOs
 
-== The Contracts Constituting Your DAO
+In a nutshell, your Aragon OSx DAO consists of three pieces **DAO**, **Permission Manager**, and **Plugins**.
 
-In a nutshell, your Aragon OSx DAO consists of three pieces:
 
-1. **The DAO contract:** The DAO contract is where the **core functionality** of the protocol lies. It is in charge of:
+== The DAO contract
 
-   - Representing the identity of the DAO (ENS name, logo, description, other metadata)
-   - Keeping the treasury
-   - Executing arbitrary actions to
-     - Transfer assets
-     - Call its own functions
-     - Call functions in external contracts
-   - Providing general technical utilities (signature validation, callback handling)
+The DAO contract is where the **core functionality** of the protocol lies. 
+It is in charge of:
+   * Representing the identity of the DAO (ENS name, logo, description, other metadata)
+   * Keeping the treasury
+   * Executing arbitrary actions to
+     ** Transfer assets
+     ** Call its own functions
+     ** Call functions in external contracts
+   * Providing general technical utilities (signature validation, callback handling)
 
-2. **The Permission Manager:** The permission manager is part of the DAO contract and the center of our protocol architecture. It **manages permissions for your DAO** by specifying which addresses have permission to call distinct functions on contracts associated with your DAO.
+== The Permission Manager
 
-3. **Plugins:** Any custom functionality can be added or removed through plugins, allowing you to **fully customize your DAO**. These plugins can be related to
+The permission manager is part of the DAO contract and the center of our protocol architecture. It **manages permissions for your DAO** by specifying which addresses have permission to call distinct functions on contracts associated with your DAO.
+
+== Plugins
+
+Any custom functionality can be added or removed through plugins, allowing you to **fully customize your DAO**. These plugins can be related to
 
    - Governance (e.g., token voting, one-person one-vote)
    - Asset management (e.g., ERC-20 or NFT minting, token streaming, DeFi)
@@ -29,6 +34,8 @@ image::dao-plugin.drawio.svg[align="center"]
 An exemplary DAO setup showing interactions between the three core contract pieces triggered by different user groups: The `DAO` contract in blue containing the `PermissionManager` in red, respectively, as well as two `Plugin` contracts in green.
 Function calls are visualized as black arrows and require permission checks (red, dashed arrow). In this example, the permission manager determines whether the token voting plugin can execute actions on the DAO, a member can change its settings, or if a DeFi-related plugin is allowed to invest in a certain, external contract.
 
+
+== Walkthrough
 In the upcoming sections, you will learn about each of them in more depth.
 
 // reorder if the nav bar is updated

packages/contracts/docs/modules/ROOT/pages/core/permissions.adoc

@@ -7,23 +7,23 @@ Permissions between contracts and wallets allow a DAO to manage and govern its a
 
 Here, you will learn how the permissions in Aragon OSx work, how they can be granted and revoked from wallets and contracts, and how they are managed through the DAO.
 
-As we mentioned earlier, it is essential that only the right person or contract can execute a certain action. As a developer, you might have seen or used link:https://docs.openzeppelin.com/contracts/2.x/api/ownership#Ownable[modifiers such as onlyOwner] in contracts. This `onlyOwner` modifier provides basic access control to your DAO: only the `owner` address is permitted to execute the function to which the modifier is attached.
+As we mentioned earlier, it is essential that only the right person or contract can execute a certain action. As a developer, you might have seen or used link:https://docs.openzeppelin.com/contracts/2.x/api/ownership#Ownable[modifiers such as `onlyOwner`] in contracts. This `onlyOwner` modifier provides basic access control to your DAO: only the `owner` address is permitted to execute the function to which the modifier is attached.
 
 In Aragon OSx, we follow the same approach but provide more advanced functionality:
 Each `DAO` contracts includes a `PermissionManager` contract allowing to flexibly, securely, and collectively manage permissions through the DAO and, thus, govern its actions.
 This `PermissionManager`, called `ACL` in previous Aragon OS versions, was one big reason why our protocol never got hacked.
 The code and configuration of a DAO specifies which wallets or contracts (`who`) are allowed to call which authorized functions on a target contract (`where`).
 Identifiers, permissions, and modifiers link everything together.
 
-### Permission Identifiers
+=== Permission Identifiers
 
 To differentiate between different permissions, permission **identifiers** are used that you will frequently find at the top of Aragon OSx contracts. They look something like this:
 
 ```solidity
 bytes32 public constant EXECUTE_PERMISSION_ID = keccak256("EXECUTE_PERMISSION");
 ```
 
-### Permissions
+=== Permissions
 
 A permission specifies an address `who` being allowed to call certain functions on a contract address `where`. In the `PermissionManager` contract, permissions are defined as the concatenation of the word `"PERMISSION"` with the `who` and `where` address, as well as the `bytes32` permission identifier `permissionId`.
 
@@ -45,7 +45,7 @@ mapping(bytes32 => address) internal permissionsHashed;
 
 Here, the `bytes32` keys are the permission hashes and the `address` values are either zero-address flags, such as `ALLOW_FLAG = address(2)` and `UNSET_FLAG = address(0)` indicating if the permission is set, or an actual address pointing to a `PermissionCondition` contract, which is discussed in the next section of this guide.
 
-### Authorization Modifiers
+=== Authorization Modifiers
 
 Using **authorization modifiers** is how we make functions permissioned. Permissions are associated with functions by adding the `auth` modifier, which includes the permission identifier in the function’s definition header.
 
@@ -63,11 +63,11 @@ function execute(
   returns (bytes[] memory execResults, uint256 failureMap);
 ```
 
-### Managing Permissions
+=== Managing Permissions
 
 To manage permissions, the DAO contract has the `grant`, `revoke` and `grantWithCondition` functions in its public interface.
 
-#### Granting and Revoking Permissions
+==== Granting and Revoking Permissions
 
 The `grant` and `revoke` functions are the main functions we use to manage permissions.
 Both receive the `_permissionId` identifier of the permission and the `_where` and `_who` addresses as arguments.
@@ -93,7 +93,7 @@ This means, that these functions can only be called through the DAO’s `execute
 NOTE: Typically, the `EXECUTE_PERMISSION_ID` permission is granted to governance contracts (such as a majority voting plugin owned by the DAO or a multi-sig). Accordingly, a proposal is often required to change permissions.
 Exceptions are, again, the xref:framework/dao-factory-registry.adoc[DAO creation] and xref:framework/plugin-setup-processor.adoc[plugin setup] processes.
 
-#### Granting Permission with Conditions
+==== Granting Permission with Conditions
 
 Aragon OSx supports relaying the authorization of a function call to another contract inheriting from the `IPermissionCondition` interface. This works by granting the permission with the `grantWithCondition` function
 
@@ -106,13 +106,11 @@ function grantWithCondition(
 ) external auth(_where, ROOT_PERMISSION_ID) {}
 ```
 
-and specifying the `_condition` contract address. This provides full flexibility to customize the conditions under which the function call is allowed.
-
-Typically, conditions are written specifically for and installed together with xref:core/plugins.adoc[plugins]
+and specifying the `_condition` contract address. This provides full flexibility to customize the conditions under which the function call is allowed. Typically, conditions are written specifically for and installed together with xref:core/plugins.adoc[plugins].
 
 To learn more about this advanced topic and possible applications, visit the xref:guide-set-up-dao/custom-permission-condition.adoc[permission conditions].
 
-#### Granting Permission to `ANY_ADDR`
+==== Granting Permission to `ANY_ADDR`
 
 In combination with conditions, the arguments `_where` and `_who` can be set to `ANY_ADDR = address(type(uint160).max)`.
 Granting a permission with `_who: ANY_ADDR` has the effect that any address can now call the function so that it behaves as if the `auth` modifier is not present.
@@ -137,7 +135,7 @@ Moreover, if a condition is set, we return its `isGranted` result and do not fal
 2. Condition with generic `_who: ANY_ADDR` and specific `_where`.
 3. Condition with specific `_where` and generic `_who: ANY_ADDR`.
 
-### Permissions Native to the `DAO` Contract
+=== Permissions Native to the DAO Contract
 
 The following functions in the DAO are permissioned:
 

packages/contracts/docs/modules/ROOT/pages/core/plugins.adoc

@@ -15,7 +15,7 @@ Plugins can be related to:
 
 - And **anything** else that comes to mind!
 
-## Understanding Plugins
+== Understanding Plugins
 
 Whenever a DAO installs a plugin, an instance of that plugin's base template is deployed using the configuration parameters defined by the DAO. For example, you may want to use a specific token for your DAO's voting process, which means you have to determine this within your plugin's configuration parameters.
 
@@ -25,7 +25,7 @@ TIP: Learn more about the different xref:guide-develop-plugin/design-your-plugin
 
 This raises questions on how the DAO manages plugins and who actually owns plugins.
 
-### How Does the DAO Manage a Plugin?
+=== How Does the DAO Manage a Plugin?
 
 A DAO manages plugins and interactions between them. In more detail, its permission manager:
 
@@ -39,6 +39,6 @@ image::dao-plugin.drawio.svg[align="center"]
 An exemplary DAO setup showing interactions between the three core contract pieces triggered by different user groups: The `DAO` contract in blue containing the `PermissionManager` in red, respectively, as well as two `Plugin` contracts in green.
   Function calls are visualized as black arrows and require permission checks (red, dashed arrow). In this example, the permission manager determines whether the token voting plugin can execute actions on the DAO, a member can change its settings, or if a DeFi-related plugin is allowed to invest in a certain, external contract.
 
-Whereas deployed plugin instances belong to the DAO, the developer of the original plugin implementation owns the implementation 
-and setup contract of the plugin. The plugin developer is the maintainer of an Aragon OSx xref:framework/plugin-repos.adoc[plugin repo]. 
+Whereas deployed plugin instances belong to the DAO, the developer of the original plugin implementation owns the implementation and setup contract of the plugin. The plugin developer is the maintainer of an Aragon OSx xref:framework/plugin-repos.adoc[plugin repo]. 
+
 Finally, the Aragon OSx protocol manages the registry in which the plugin repositories are listed, which is required to install a plugin using the Aragon OSx framework infrastructure to your DAO.