feat(docs): add operational flow diagrams for Firelight and Upshift vaults

Author: fassko

docs/fxrp/firelight/_firelight.mdx

@@ -6,6 +6,40 @@ It provides [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) compliant vault
 Firelight vaults operate on a [period-based logic](https://docs.firelight.finance/technical-documents#period-based-logic), where deposits and withdrawals are processed at specific intervals.
 Users receive vault shares representing their proportional ownership of the vault's assets.
 
+## How Firelight Vaults Work
+
+This diagram shows the flow of operations for a user interacting with a Firelight vault.
+
+```mermaid
+flowchart TB
+  UserFXRP[("User's FXRP")]
+  Deposit[deposit]
+  Mint[mint]
+  Shares[("Vault shares")]
+  UserFXRP --> Deposit --> Shares
+  UserFXRP --> Mint --> Shares
+
+  Shares --> Withdraw[withdraw]
+  Shares --> Redeem[redeem]
+  Withdraw --> Request["Withdrawal request(current period)"]
+  Redeem --> Request
+  Request --> Wait["Wait for period end"]
+  Wait --> Claim[claimWithdraw]
+  Claim --> FXRP[("FXRP to user")]
+```
+
+The flow of operations for a user interacting with a Firelight vault is as follows:
+
+- **Deposit / Mint:** Two ways to get vault shares.
+  Call `deposit(assets)` to deposit FXRP and receive the corresponding shares, or `mint(shares)` to specify the shares you want and pay the required FXRP.
+
+- **Withdraw / Redeem:** Both create a withdrawal request for the current period.
+  Call `withdraw(assets)` to request a given amount of assets, or `redeem(shares)` to burn shares and request the equivalent assets.
+  Shares are burned when you redeem.
+
+- **Claim:** After the period ends, call `claimWithdraw()` to receive your FXRP.
+  Use the [Get Vault Status](/fxrp/firelight/status) and [Claim Withdrawals](/fxrp/firelight/claim) guides to find and claim completed periods.
+
 <DocCardList
   items={[
     {

docs/fxrp/upshift/_upshift.mdx

@@ -15,6 +15,41 @@ It inherits the transparency model of the [FAssets](/fassets/overview) system: m
 - **Instruction flow is auditable:** XRPL-triggered actions are executed on Flare via [Smart Accounts](/smart-accounts/overview) with [Flare Data Connector](/fdc/overview) backed verification and onchain execution.
   You can verify all smart account activity on the [Flare Systems Explorer](https://flare-systems-explorer.flare.network/smart-accounts).
 
+## How Upshift Vaults Work
+
+This diagram shows the flow of operations for a user interacting with an Upshift vault.
+
+```mermaid
+flowchart TB
+  UserFXRP[("User's FXRP")]
+  Deposit[deposit]
+  LP[("LP Tokens (vault shares)")]
+  UserFXRP --> Deposit --> LP
+
+  LP --> InstantRedeem[instantRedeem]
+  InstantRedeem -->|"instant redemption fee applies"| InstantFXRP[("FXRP to user")]
+
+  LP --> RequestRedeem[requestRedeem]
+  RequestRedeem --> Epoch["Withdrawal request(epoch: year, month, day)"]
+  Epoch --> Wait["Wait lag duration"]
+  Wait --> Claim[claim]
+  Claim -->|"withdrawal fee applies"| RequestedFXRP[("FXRP to user")]
+```
+
+The flow of operations for a user interacting with an Upshift vault is as follows:
+
+- **Deposit:** Transfer FXRP to the vault and receive the corresponding LP tokens (shares).
+  Yield accrues as share value increases.
+
+- **Instant redeem:** Burn the corresponding LP tokens and receive FXRP immediately via the `instantRedeem()` function.
+  In this case you need to pay the instant redemption fee.
+  Use this option when you need liquidity right away.
+
+- **Requested redeem:** Lock the LP tokens with `requestRedeem()` and create a withdrawal request for the current epoch.
+  After the lag duration, call `claim(year, month, day, receiver)` to receive FXRP.
+  Lower fee than instant redeem.
+  Use this option when you can wait.
+
 <DocCardList
   items={[
     {

src/css/custom.css

@@ -578,3 +578,14 @@ div[class^="searchBar_"] div[class*="hitFooter"] a:hover {
   background: var(--ifm-color-emphasis-300);
   border-color: var(--ifm-color-emphasis-400);
 }
+
+/* ============================================================
+   Mermaid diagrams
+   ============================================================ */
+.markdown .mermaid,
+.theme-doc-markdown .mermaid,
+.markdown .docusaurus-mermaid-container,
+.theme-doc-markdown .docusaurus-mermaid-container {
+  margin-bottom: 2rem;
+  margin-top: 2rem;
+}