docs: polishing documentation (#515)

Co-authored-by: essbante-io <esteban.garcia@iohk.io>

docs/decisions/20221005-using-tapir-library-as-a-dsl-for-openapi-specification.md

@@ -8,14 +8,14 @@
 Related ADR/AIP: [Introduce REST HTTP for existing Node services](https://input-output.atlassian.net/wiki/spaces/AV2/pages/3454500948/AIP+-+001)
 
 ## Context and Problem Statement
-Prism Platform v2 will contain the REST API. The decision was made by team consensus during the first AOH meeting to follow "OpenAPI specification first" approach and generate stubs, server side and client side code based on OAS.
+PRISM Platform v2 will contain the REST API. The decision was made by team consensus during the first AOH meeting to follow "OpenAPI specification first" approach and generate stubs, server side and client side code based on OAS.
 Following this strategy we currently have 4-5 OAS files (Castor, Pollux, Mercury, Configuration).
 
 The following tool was selected for code generation: [OpenAPI Tools](https://github.com/OpenAPITools/openapi-generator)
 
 Instead of using the yaml file as OpenAPI specification and openapi-generator for server and client stub generation - this ADR proposes to use [Tapir](https://tapir.softwaremill.com/en/latest/index.html) Scala library as DSL for OpenAPI specification, `interpret` the endpoint defitions as Scala server and client stub, generate the yaml file, and use openapi-generator for client stubs.
 
-Technology stack that is going to be used in Prism v2 backend: Scala 3 + ZIO ecosystem
+Technology stack that is going to be used in PRISM v2 backend: Scala 3 + ZIO ecosystem
 
 Akka framework after version 2.6.x cannot be used because [Lightbend changed the license type to BSL 1.1](https://www.lightbend.com/blog/why-we-are-changing-the-license-for-akka). 
 

docs/decisions/20221006-store-private-keys-of-issuers-inside-prism-agent.md

@@ -6,7 +6,7 @@
 
 ## Context and Problem Statement
 
-While each holder has its own wallet application on the phone (edge agent) to store private keys, contacts and credentials that have been issued to them, prism 2.0 will provide a custodial solution to Issuers and Verifiers, thus they won't be having their own wallets and won't be storing/managing keys on their side, There needs to be a storage for private keys of issuers nad Verifiers on Prism side.
+While each holder has a wallet application on the phone (edge agent) to store private keys, contacts, and credentials, PRISM 2.0 will provide a custodial solution to Issuers and Verifiers. Thus they won't have their wallets or store/manage keys. There needs to be storage for the private keys of issuers and Verifiers on the PRISM side.
 
 
 ## Considered Options

docs/decisions/20230118-quill-library-for-sql-statement-generation.md

@@ -7,11 +7,11 @@
 
 ## Context and Problem Statement
 
-PostgreSQL is essential to the Atala Prism technology stack, where most entities are stored.
+PostgreSQL is essential to the Atala PRISM technology stack, where most entities are stored.
 
-Backend services: Prism Agent, Prism Mediator, and Prism Node use PostgreSQL.
+Backend services: PRISM Agent, PRISM Mediator, and PRISM Node use PostgreSQL.
 
-[Doobie](https://tpolecat.github.io/doobie/index.html) llibrary is currently used in Scala code to communicate with Postgresql. Quotes from the website
+[Doobie](https://tpolecat.github.io/doobie/index.html) library is currently used in Scala code to communicate with Postgresql. Quotes from the website
 
 ```
 Doobie is a pure functional JDBC layer for Scala and Cats. It is not an ORM, nor is it a relational algebra; 

docs/docusaurus/connections/connection.md

@@ -2,21 +2,19 @@
 
 A connection is a stateful relationship between two parties that enables secure communication.
 
-The **Connection protocol** is required to establish secure connections between agents,
+The [Connection protocol](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#connection-protocol) is required to establish secure connections between agents,
 allowing them to exchange information and interact.
 
-The protocol provides endpoints for creating and managing connections, as well as for accepting invitations.
-
 ## Roles
 
 The connection protocol has two roles:
 
-1.  **Inviter**: A subject that initiates a connection request by sending a *connection invitation*.
-2.  **Invitee**: A subject that receives a connection invitation and accepts it by sending a *connection request*.
+1.  [Inviter](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#inviter): A subject that initiates a connection request by sending a [connection invitation](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#connection-invitation).
+2.  [Invitee](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#invitee): A subject that receives a connection invitation and accepts it by sending a [connection request](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#connection-request).
 
 ## Prerequisites
 
-1. **Inviter** and **Invitee** PRISM Agents up and running
+1. Inviter and Invitee PRISM Agents up and running
 
 ## PRISM Agent endpoints overview
 
@@ -29,17 +27,17 @@ The protocol uses the following REST API endpoints:
 3. [`POST /connection-invitations`](/agent-api/#tag/Connections-Management/operation/acceptConnectionInvitation): Accepts an externally received invitation
 
 :::info
-For more detailed information, please, check the full **[PRISM Agent API](/agent-api).**
+Please check the full [PRISM Agent API](/agent-api) specification for more detailed information.
 :::
 
 ## Inviter Flow
 
-1.  Generate and share a new Out-of-Band (OOB) invitation (connection is created in `InvitationGenerated` state)
-2.  Receive a connection request from the **Invitee** (connection is moved to `ConnectionRequestReceived` state)
-3.  Accept the connection request (connection is moved to `ConnectionResponsePending` state)
+1.  Generate and share a new Out-of-Band (OOB) invitation (connection gets created in `InvitationGenerated` state)
+2.  Receive a connection request from the Invitee (connection moves to `ConnectionRequestReceived` state)
+3.  Accept the connection request (connection moves to `ConnectionResponsePending` state)
 4.  Send the connection response via the DIDComm Agent (connection achieves `ConnectionResponseSent` state)
 
-The **Inviter**'s state transitions are represented by the following Mermaid diagram:
+The following diagram represents the Inviter's Connection state transitions:
 ```mermaid
 ---
 title: Inviter Connection State
@@ -57,10 +55,10 @@ ConnectionResponseSent --> [*]
 
 1.  Receive the OOB invitation (`InvitationReceived` state)
 2.  Accept the invitation (connection is created in `ConnectionRequestPending` state)
-3.  Send the connection request via DIDComm (connection achieves `ConnectionRequestSent` state)
+3.  Send the connection request via [DIDComm](https://github.com/input-output-hk/atala-prism-docs/blob/main/documentation/docs/concepts/glossary.md#didcomm) (connection achieves `ConnectionRequestSent` state)
 4.  Receive the connection response (connection achieves `ConnectionResponseReceived` state)
 
-The **Invitee**'s state transitions are represented by the following Mermaid diagram:
+The following diagram represents the Invitee's Connection state transitions:
 ```mermaid
 ---
 title: Invitee Connection State
@@ -81,14 +79,15 @@ The following diagram shows the end-to-end flow for establishing a connection be
 
 ## Command line example
 
-The following example demonstrates on how you could use two PRISM Agents API to set up connection between them.
+The following example demonstrates how you could use two PRISM Agent APIs to set up a connection between them.
 
-### **Inviter** creates an invitation
+### Inviter creates an invitation
 
 ```shell
 curl -X 'POST' \
 	'http://localhost:8080/prism-agent/connections' \
 	-H 'Content-Type: application/json' \
+	-H "apiKey: $API_KEY" \
 	-d '{ "label": "Connect with Alice" }' | jq
 ```
 
@@ -117,6 +116,7 @@ Replace `{RAW_INVITATION}` with the value of the '_oob' query string parameter f
 curl -X 'POST' \
 	'http://localhost:8090/prism-agent/connection-invitations' \
 	-H 'Content-Type: application/json' \
+	-H "apiKey: $API_KEY" \
 	-d '{ "invitation": "{RAW_INVITATION}" }' | jq
 ```
 
@@ -140,10 +140,11 @@ Example response:
 }
 ```
 
-### **Invitee** retrieves the list of connections
+### Invitee retrieves the list of connections
 
 ```shell
-curl -X 'GET' 'http://localhost:8090/prism-agent/connections' | jq
+curl -X 'GET' 'http://localhost:8090/prism-agent/connections' \
+    -H "apiKey: $API_KEY" | jq
 ```
 
 Example output:
@@ -172,10 +173,11 @@ Example output:
 }
 ```
 
-### **Inviter** retrieves the list of connections
+### Inviter retrieves the list of connections
 
 ```shell
-curl -X 'GET' 'http://localhost:8080/prism-agent/connections' | jq
+curl -X 'GET' 'http://localhost:8080/prism-agent/connections' \
+    -H "apiKey: $API_KEY" | jq
 ```
 
 Example response:
@@ -206,5 +208,5 @@ Example response:
 ```
 
 :::info
-For more detailed information, please, check the full **[PRISM Agent API](/agent-api).**
+Please check the full [PRISM Agent API](/agent-api) specification for more detailed information.
 :::