feat: Apply linter and update notes block

Signed-off-by: jdiaconu <[email protected]>

Author: jadiaconu

docs/_static/ioa_stack.png

@@ -35,9 +35,9 @@ Similarly, as a starting point, the [`AGNTCY`](https://agntcy.org/) supports one
 
 <br />
 
-:::tip[IMPORTANT]
+```{IMPORTANT}
 Independently of whether the identity is assigned following a convention or a standardized framework, at this stage the main focus of the [`AGNTCY`](https://agntcy.org/) is to provide a common and trustworthy mechanism to **present identifiers** and to **verify them**. More specifically, the [`AGNTCY`](https://agntcy.org/) not only supports various (and heterogeneous) identifiers that are universally unique but also proposes a standard way of presenting and verifying such identifiers, thereby enabling freedom in the selection of interoperable identities in an IoA.
-:::
+```
 
 ## Identity for Agents
 
@@ -49,15 +49,16 @@ Independently of whether the identity is assigned following a convention or a st
 
 The figure above depicts the main elements of an Agent's subject identifier:
 
-- Each Agent subject has a universally unique identifier named [`ID`](./id/definitions.md).
-- Each `ID` is associated 1:1 to a [`ResolverMetadata`](./id/definitions.md) object, enabling automated resolution and trustworthy verification of Agent IDs.
-- Each `ID` is also associated 1:n to an [`Agent Badge`](./vc/intro.md).
+- Each Agent subject has a universally unique identifier named [`ID`](#identifiers).
+- Each `ID` is associated 1:1 to a [`ResolverMetadata`](#identifiers) object, enabling automated resolution and trustworthy verification of Agent IDs.
+- Each `ID` is also associated 1:n to an [`Agent Badge`](#verifiable-credentials).
 
 Hence, in the [`AGNTCY`](https://agntcy.org/), an Agent subject is tied to a unique identifier linked to one or more `Verifiable Credentials (VCs)`, which contain information about the Agent, such as its ID, a schema definition (e.g., an OASF schema), and other metadata used for defining locators, authentication, MFA, etc. Agents can use this Badge for secure presentation, verification, and enabling trusted communications across multi-agent systems.
 
 Note that the same approach applies to MCP Servers and MASs, giving rise to ResolverMetadata and Badges also for MCP Servers and MASs.
 
 # Identifiers
+
 ## Definitions
 
 The [`AGNTCY`](https://agntcy.org/) supports various types of identities, referred to as IDs, which serve as universally unique identifiers for the main entities or subjects operated by the [`AGNTCY`](https://agntcy.org/), including Agents and Multi-Agent Systems (MAS).
@@ -71,6 +72,7 @@ ResolverMetadata: Metadata, represented in the form of a JSON-LD object, contain
 Concrete examples with various IDs and associated ResolverMetadata can be found [`here`](https://spec.identity.agntcy.org/docs/id/examples)
 
 # Verifiable Credentials
+
 ## Definitions
 
 The [`AGNTCY`](https://agntcy.org/) supports various types of verifiable credentials, referred to as VCs. A verifiable credential is a specific way to express and present a set of claims made by an issuer, such as an agent definition (e.g., an [`OASF Definition`](https://schema.oasf.agntcy.org/objects/agent), or an [`A2A Agent Card`](https://github.com/google/A2A/blob/main/specification/json/a2a.json#AgentCard)), a deployment configuration, or an authorization claim that could be used during a MFA process.
@@ -86,27 +88,28 @@ One of the key `VCs` within the [`AGNTCY`](https://agntcy.org/) is the following
 
   - An n:1 relationship between Agent Badges and an Agent Passport
   - A 1:1 relationship between an Agent Passport and an Agent `ID`
-  - A common element that binds Agent Badges and an Agent Passport, which is the same Agent `ID`. 
+  - A common element that binds Agent Badges and an Agent Passport, which is the same Agent `ID`.
 
-More specifically, the role of the "Agent Passport" is to cryptographically bind an Agent ID to an ISSUER, a public key and a proof of provenance, while the role of the Agent Badges is to enable the binding of the same Agent `ID` to different definitions of the core Agent, including different schemas, versions, locators, etc., as well as to additional `VCs` that may be used during Multi-Factor AuthN/AuthZ (MFA) processes. A concrete example of an Agent Passport can be found [`here`](../vc/agent-passport.md). 
+More specifically, the role of the "Agent Passport" is to cryptographically bind an Agent ID to an ISSUER, a public key and a proof of provenance, while the role of the Agent Badges is to enable the binding of the same Agent `ID` to different definitions of the core Agent, including different schemas, versions, locators, etc., as well as to additional `VCs` that may be used during Multi-Factor AuthN/AuthZ (MFA) processes. A concrete example of an Agent Passport can be found [`here`](../vc/agent-passport.md).
 
 -->
 
-The identity framework conceived by the `AGNTCY` allows not only to cryptographically bind an Agent ID to an ISSUER, a public key and a proof of provenance but also to enable the binding of the same Agent `ID` to different definitions of the core Agent, including different schemas, versions, locators, etc., as well as to additional `VCs` that may be used during Multi-Factor AuthN/AuthZ (MFA) processes. 
+The identity framework conceived by the `AGNTCY` allows not only to cryptographically bind an Agent ID to an ISSUER, a public key and a proof of provenance but also to enable the binding of the same Agent `ID` to different definitions of the core Agent, including different schemas, versions, locators, etc., as well as to additional `VCs` that may be used during Multi-Factor AuthN/AuthZ (MFA) processes.
 
 <br />
 
-:::tip[IMPORTANT]
+```{IMPORTANT}
 As detailed in the [`Agent Badge Examples`](https://spec.identity.agntcy.org/docs/vc/agent-badge), the combined use of an `Agent Badge` with `ResolverMetadata` objects enables the automatic and trustworthy discovery not only of the PubKey associated to the Agent issuer but also of the verification material to prove the authenticity and integrity of the Agent Badge, according to the assertionMethod defined in the `ResolverMetadata` object.
 
 Furthermore, the use of Agent Badges provides a set of key properties in an IoA:
 
-1) It addresses the problem of **Agent impersonation**, by avoiding scenarios where one organization could offer rogue Agents as if they were created by another (trusted) company.
-2) It enables **trustworthy origination, traceability, and lineage of Agents**. Note that Agents will end up having different versions and releases (e.g., due to security patches and updates), so while a  company might be using version 2.08 of Agent `ID` = X, another company might be using version 2.1 of Agent Agent `ID` = X. Knowing that there is a key vulnerability and recommended upgrade for Agent `ID` = X, version 2.08, would allow the first company to migrate to version 2.1, while inform the second company that the upgrade is not needed.    
-3) It **enables more sophisticated AuthN and AuthZ processes among agents with and without a human in the loop**, including the **capacity to build trust even before an Agent is selected and used**. In subsequent updates to this documentation, the [`AGNTCY`](https://agntcy.org/) will provide examples involving MFA and how to build trust dynamically among Agents. 
-:::
+1. It addresses the problem of **Agent impersonation**, by avoiding scenarios where one organization could offer rogue Agents as if they were created by another (trusted) company.
+2. It enables **trustworthy origination, traceability, and lineage of Agents**. Note that Agents will end up having different versions and releases (e.g., due to security patches and updates), so while a company might be using version 2.08 of Agent `ID` = X, another company might be using version 2.1 of Agent Agent `ID` = X. Knowing that there is a key vulnerability and recommended upgrade for Agent `ID` = X, version 2.08, would allow the first company to migrate to version 2.1, while inform the second company that the upgrade is not needed.
+3. It **enables more sophisticated AuthN and AuthZ processes among agents with and without a human in the loop**, including the **capacity to build trust even before an Agent is selected and used**. In subsequent updates to this documentation, the [`AGNTCY`](https://agntcy.org/) will provide examples involving MFA and how to build trust dynamically among Agents.
+```
 
 # Flow Diagrams
+
 ## Agntcy - User Flows
 
 ### Create a New Agent
@@ -181,4 +184,4 @@ Agent Consumer->>Identity CLI: Search for the Agent Badge<br/>for the Agent ID +
 Agent Consumer->>Identity CLI: Verify the Agent Badge
 ```
 
-Additional flow diagrams can be found [`AGNTCY`](https://spec.identity.agntcy.org/docs/category/sequence-flows)
+Additional flow diagrams can be found in the [`Identity Spec`](https://spec.identity.agntcy.org/docs/category/sequence-flows).

docs/pages/identity/identity.md

@@ -37,7 +37,7 @@ The initial set of IoA components and architecture is outlined below. This is a
 :align: center
 ```
 
-1. **Identity**: To ensure open, collision-free, and secure agent authentication and metadata validation, fostering trust and reliability across Agents, MCP Servers, and Multi-Agent Systems.
+1. **Identity**: To ensure open, collision-free, secure agent authentication and metadata validation, fostering trust and reliability across Agents, MCP Servers, and Multi-Agent Systems.
 1. **Open Agent Schema Framework (OASF)**: An OCI based extensible data model allowing to describe agents' attributes and ensuring unique identification of agents. Current OASF repo can be found [here](https://github.com/agntcy/oasf), OASF schema documentation can be found [here](https://schema.oasf.agntcy.org).
 1. **Agent Directory**: Allows to announce and discover agents or multi-agent applications. Any organization can run its directory and keep it in sync with others, forming the Internet of Agents inventory.
 1. **Agent Manifest**: A standard format to describes agents, their capabilities, their dependencies, and how to deploy or consume them. The manifest is designed to be used by ACP and the Workflow Server and stored in the Agent Directory with the corresponding OASF extensions.