add mermaid charts and apply suggestions

Author: brozorec

content/stellar-contracts/accounts/authorization-flow.mdx

@@ -5,6 +5,41 @@ title: Authorization Flow
 Authorization in smart accounts is determined by matching the current context against the account's context rules. Rules are gathered, ordered by recency, and evaluated until one satisfies the requirements. If a matching rule is found, its policies (if any) are enforced. Otherwise, authorization fails.
 
 ## Detailed Flow
+```mermaid
+sequenceDiagram
+    participant User
+    participant SmartAccount
+    participant ContextRule
+    participant DelegateSigner
+    participant Verifier
+    participant Policy
+
+    User->>SmartAccount: Signatures
+    SmartAccount->>ContextRule: Match context<br/>(CallContract, Default, ...)
+    ContextRule->>ContextRule: Filter expired rules<br/>Sort newest first
+
+    loop Each rule until match
+        Note over ContextRule,DelegateSigner: Built-in authorization <br/>for delegate signers
+        ContextRule->>DelegateSigner: require_auth_for_args()
+        DelegateSigner-->>ContextRule: Authorized
+        Note over ContextRule,Verifier: Signature verification for external signers
+        ContextRule->>Verifier: verify()
+        Verifier-->>ContextRule: Valid
+        Note over ContextRule,Policy: Policy pre-checks
+        ContextRule->>Policy: can_enforce()
+        Policy-->>ContextRule: True/False
+
+        alt All checks pass
+            ContextRule->>Policy: enforce()
+            Policy->>Policy: Update state
+            ContextRule-->>SmartAccount: ✓ Authorized
+        else Any check fails
+            ContextRule->>ContextRule: Try next rule
+        end
+    end
+
+    SmartAccount-->>User: Success
+```
 
 ### 1. Rule Collection
 

content/stellar-contracts/accounts/context-rules.mdx

@@ -87,6 +87,8 @@ graph TD
     SA --- CR2
     SA --- CR3
     SA --- CR4
+
+    style SA fill:#E8E8E8,stroke:#333,stroke-width:2px
 ```
 
 

content/stellar-contracts/accounts/signers-and-verifiers.mdx

@@ -39,9 +39,9 @@ graph TD
     C1 --> SA2
     G2 --> SA2
     
-    style G1 fill:#6B9BD1,stroke:#333,stroke-width:2px
-    style G2 fill:#6B9BD1,stroke:#333,stroke-width:2px
-    style C1 fill:#F4D03F,stroke:#333,stroke-width:2px
+    style G1 fill:#6B9BD1
+    style G2 fill:#6B9BD1
+    style C1 fill:#F4D03F
     style SA1 fill:#E8E8E8,stroke:#333,stroke-width:2px
     style SA2 fill:#E8E8E8,stroke:#333,stroke-width:2px
     style SA3 fill:#E8E8E8,stroke:#333,stroke-width:2px
@@ -100,9 +100,9 @@ graph LR
     TC --> |"require_auth()"| SA1
     SA1 --> |"require_auth_for_args()"| G1
     
-    style G1 fill:#6B9BD1,stroke:#333,stroke-width:2px
+    style G1 fill:#6B9BD1
     style SA1 fill:#E8E8E8,stroke:#333,stroke-width:2px
-    style TC fill:#C8D9A3,stroke:#333,stroke-width:2px
+    style TC fill:#C8D9A3
 ```
 
 When simulating this transaction, the following authorization entry is returned. Note that `"auth"` contains a single element and the delegated signer address (G-account) is not present at all:
@@ -376,9 +376,9 @@ graph LR
     TC --> |"require_auth()"| SA1
     SA1 --> |"verify()"| V
     
-    style V fill:#16D9AA1,stroke:#333,stroke-width:2px
+    style V fill:#16D9AA1
     style SA1 fill:#E8E8E8,stroke:#333,stroke-width:2px
-    style TC fill:#C8D9A3,stroke:#333,stroke-width:2px
+    style TC fill:#C8D9A3
 ```
 
 In contrast to `Delegated` signers, constructing the auth entry for an `External` signer is straightforward:
@@ -501,7 +501,7 @@ The trait uses associated types to allow different verifiers to define their own
 
 ### Advantages of the Verifier Pattern
 
-**No Setup Costs**: Once a verifier is deployed, new keys can be used immediately without any on-chain setup or deployment expenses. Users simply reference the verifier address and provide their public key when creating signers.
+**No Setup Costs**: Once a verifier is deployed, new keys can be used immediately without any on-chain setup. Users simply reference the verifier address and provide their public key when creating signers.
 
 **Cryptographic Flexibility**: The verifier pattern supports diverse cryptographic schemes from standard curves to emerging authentication methods like zero-knowledge proofs and email-based signing. Developers can implement custom verifiers for specialized cryptographic schemes.
 

content/stellar-contracts/accounts/smart-account.mdx

@@ -4,15 +4,15 @@ title: Smart Accounts
 
 [Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/accounts)
 
-Smart accounts in Soroban are contracts that manage the composition of authorization intents from multiple sources, such as policies and signing keys from different cryptographic curves. They enable flexible combinations and allow multiple authorization mechanisms to work together seamlessly.
+Smart accounts are contracts that manage the composition of authorization intents coming from multiple sources, such as policies, signing keys from different cryptographic curves or other Soroban accounts. This lays the ground for flexible combinations where multiple authorization mechanisms work together seamlessly.
 
 ## Overview
 
-The [accounts](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/accounts) package provides a comprehensive smart account framework for Soroban, enabling flexible, programmable authorization. Instead of hard-coding signature checks, smart accounts organize authorization as a composition of context rules, signers, and policies.
+The [accounts](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/accounts) package provides a comprehensive smart account framework, enabling programmable authorization. Rather than hard-coding signature checks directly into the account contract, this framework organizes authorization as a composition of three core elements: context rules, signers, and policies.
 
-Smart accounts in Soroban implement `CustomAccountInterface` and define authorization as data and behavior that can evolve over time. The framework is context-centric: it distinguishes who is allowed to act (signers), what they are allowed to do (scope), and how those permissions are enforced (policies).
+To achieve this composability, smart accounts implement the `CustomAccountInterface` and define authorization as data and behavior that can evolve over time. The framework takes a context-centric approach, separating three distinct concerns: who is allowed to act (signers), what they are allowed to do (scope or context rules), and how those permissions are enforced (policies).
 
-The framework externalizes some parts of the logic and state to separate contracts. Policies are external contracts that manage enforcement rules and can maintain their own state, while verifiers are external contracts that handle signature validation logic. This separation of concerns enables modularity and flexibility, and allows multiple smart accounts to share well-audited verification and policy logic. Protocol 23 improvements make this modular design practical, with substantially cheaper cross-contract calls enabling efficient composition of multiple external components.
+This separation is made practical by externalizing parts of the logic and state to dedicated contracts. Specifically, policies are external contracts that enforce constraints and can maintain their own state, while verifiers are external contracts that handle signature validation logic. This modular architecture enables flexibility and allows multiple smart accounts to share well-audited verification and policy logic. The Protocol 23 improvements make this design efficient, with substantially cheaper cross-contract calls enabling practical composition of multiple external contracts.
 
 ## Core Components
 
@@ -22,13 +22,51 @@ The framework separates three distinct concerns:
 - **Who** (Signers): Identifies the authorized entities
 - **How** (Policies): Enforces business logic and constraints
 
+```mermaid
+graph LR
+    P1((Policy)) --- CR1
+    P2((Policy)) --- CR2
+    P2((Policy)) --- CR3
+    P3((Policy)) --- CR3
+
+    subgraph SA[Smart Account]
+        CR1[Context Rule]
+        CR2[Context Rule]
+        CR3[Context Rule]
+    end
+
+    S1["Delegated Signer<br/><i><small>G-account</small></i>"]
+    S2["Delegated Signer<br/><i><small>G-account</small></i>"]
+    S3["Delegated Signer<br/><i><small>C-account</small></i>"]
+    S4["External Signer<br/><i><small>Verifier Contract || Pubkey</small></i>"]
+    S5["External Signer<br/><i><small>Verifier Contract || Pubkey</small></i>"]
+
+    CR1 --- S1
+    CR1 --- S2
+    CR2 --- S3
+    CR3 --- S4
+    CR3 --- S5
+
+    style SA fill:#E8E8E8,stroke:#333,stroke-width:2px
+    style S1 fill:#6B9BD1
+    style S2 fill:#6B9BD1
+    style S3 fill:#F4D03F
+    style S4 fill:#A9DA9B
+    style S5 fill:#A9DA9B
+```
+
 ### Context Rules
 Context rules function like routing tables for authorization. For each context, they specify scope, lifetime, and the conditions (signers and policies) that must be satisfied before execution proceeds.
 
+#### Examples
+1. Subscription: A dapp public key (signer) can withdraw 100 USDC every month (policy) for one year (lifetime)
+2. Deployment: 2-of-3 (policy) Ed25519 keys (signers) can deploy a new contract
+3. Vote: 3-of-3 P256 keys (signers) can cast a vote at a specific voting contract
+
 For detailed documentation, see [Context Rules](/stellar-contracts/accounts/context-rules).
 
 ### Signers and Verifiers
-Signers define who can authorize operations. The framework supports both delegated signers (any Soroban address) and external signers that use specialized verifier contracts for signature validation. Verifiers are cryptographic oracles that validate signatures for external signers.
+Signers define who can authorize operations. The framework supports both **delegated** signers (any Soroban address) and **external** signers that use specialized verifier contracts for signature validation. Verifiers can be seen as some sort of cryptographic oracles that validate signatures for external signers.
 
 For detailed documentation, see [Signers and Verifiers](/stellar-contracts/accounts/signers-and-verifiers).