Improve SEO metadata and code block quality across docs

about-these-docs.mdx

@@ -9,13 +9,13 @@
 
 | Section | Contents |
 |---|---|
 | **CoW Protocol** | Overview, Explanation (How It Works, Benefits, Order Types, Flash Loans, CoW AMM, Architecture), CoW Swap (Trading Tutorials, Widget, Hook dApps), CoW Explorer, Integration (API, Quickstarts, Testing), Reference (APIs, Core, Auctions) |
 | **Developer SDKs** | TypeScript SDK, Python SDK |
 | **Contracts** | Core Contracts, Hooks Trampoline, ComposableCoW, Contracts SDK, Flash Loan Router |
 | **Infrastructure** | BFF, Services, Watch Tower |
 | **Governance** | Mission & Token, Grants, Fees |
 
 ## Framework: Diataxis
 
 Every section follows the [Diataxis framework](https://diataxis.fr), which organizes content into four quadrants based on what readers need:
 
@@ -56,7 +56,7 @@
 | Persona | Entry Point | Primary Sections |
 |---|---|---|
 | **Trader** | [CoW Swap tutorials](/cow-swap/tutorials/swap) | Order types, CoW Swap, CoW Explorer |
 | **Integrator** | [Integration overview](/cow-protocol/explanation/integration-overview) | Widget, SDK, API, quickstarts |
 | **Solver Operator** | [Test a solver locally](/cow-protocol/tutorials/solvers/local_test) | Solver tutorials, auction reference |
 | **Smart Contract Dev** | [Contracts reference](/cow-protocol/reference/contracts/core) | ComposableCoW, Hooks, Flash Loans |
 | **Backend Contributor** | [Services](/services/introduction) | BFF, Services, Watch Tower |
@@ -144,14 +144,14 @@
 
 | Gap | What's needed | Priority |
 |---|---|---|
 | **Flash loan SDK guide** | Programmatic flash loan order creation via SDK. The current [tutorial](/cow-swap/tutorials/flash-loans) is UI-focused with a Sepolia walkthrough but lacks an SDK-first guide. | Low |
 | **Batch order creation** | How to create and manage multiple orders in a single session — useful for market makers and automated strategies. | Low |
 
 ### Structural weaknesses
 
 | Area | Issue |
 |---|---|
 | **Multi-chain specifics** | Docs are Ethereum-centric. Gnosis Chain, Arbitrum, and Base have different liquidity profiles, gas dynamics, and solver participation, but chain-specific guidance is sparse. |
 | **Code freshness** | Static code snippets can go stale as the SDK evolves. The [interactive tutorials at learn.cow.fi](https://learn.cow.fi) mitigate this, but in-docs examples need periodic review against latest SDK versions. |
 | **API reference depth** | The [Orderbook API reference](/cow-protocol/reference/apis/orderbook) links to the external [api.cow.fi/docs](https://api.cow.fi/docs) for full specs. Inline parameter documentation within the docs would reduce context-switching. |
 | **Solver docs** | The solver tutorials cover creation and deployment, but advanced topics (custom routing strategies, gas optimization, competition dynamics) are thin. |
@@ -190,7 +190,7 @@
 
 | Component | When to use |
 |---|---|
 | `<Steps>` / `<Step>` | Sequential procedures (quickstarts, tutorials) |
 | `<CardGroup>` / `<Card>` | Navigation grids, feature showcases |
 | `<Accordion>` | Expandable details, FAQ items |
 | `<Note>` | Supplementary information |
@@ -201,7 +201,7 @@
 
 ### File naming conventions
 
-```
+```text
 section/
 ├── explanation/          # Conceptual content ("why")
 │   ├── topic-name.mdx
@@ -241,7 +241,7 @@
 
 ### When protocol changes land
 
 1. **API changes** — Update the OpenAPI spec, then update any quickstarts or guides that reference affected endpoints
 2. **New features** — Add explanation page (what/why), tutorial (how to use), and reference (specs)
 3. **Contract deployments** — Update `snippets/core-contract-addresses.mdx` and any per-chain address tables
 
@@ -261,6 +261,6 @@
 |---|---|
 | `community-links.mdx` | Discord, GitHub, Forum, Snapshot cards |
 | `core-contract-addresses.mdx` | Settlement contract addresses per chain |
 | `supported-networks.mdx` | Supported blockchain networks |
 | `sdk-install.mdx` | SDK installation command |
 | `settlement-contract.mdx` | Settlement contract reference |

bff/api-reference/authentication.mdx

@@ -102,7 +102,7 @@
 1. **EOA (Externally Owned Account)**: Standard ECDSA signature verification
 2. **Smart Contract Wallets**: ERC-1271 signature verification
 
 The signature is verified on Ethereum Mainnet (chainId: 1) for all affiliate registrations, regardless of the chain where trades occur.
 
 ### Making Authenticated Requests
 
@@ -122,7 +122,7 @@
 
 The API supports Cross-Origin Resource Sharing (CORS) for browser-based applications:
 
-```
+```http
 Access-Control-Allow-Origin: *
 Access-Control-Allow-Headers: Cache-Control
 ```

bff/api-reference/endpoints/accounts.mdx

@@ -17,14 +17,14 @@
 
 | Type  | Name        | Required | Details                                           |
 | ----- | ----------- | -------- | ------------------------------------------------- |
 | Path  | chainId     | Yes      | Network identifier (e.g., `1`, `100`, `11155111`) |
 | Path  | userAddress | Yes      | User's wallet address                             |
 | Query | tokens      | Yes      | Comma-separated token contract addresses          |
 
 ### Response Fields
 
 - **balance**: Token quantity in base units (wei-like format)
 - **allowance**: CoW Protocol vault relayer approval amount
 - **token**: Object containing token metadata
   - **address**: Contract address
   - **decimals**: Decimal places (typically 18)
@@ -99,8 +99,8 @@
 
 | Type  | Name        | Required | Details                                  |
 | ----- | ----------- | -------- | ---------------------------------------- |
 | Path  | chainId     | Yes      | Network identifier                       |
 | Path  | userAddress | Yes      | User's wallet address                    |
 | Query | tokens      | Yes      | Comma-separated token addresses to monitor |
 
 ### Response Behavior
@@ -112,20 +112,20 @@
 ### Event Examples
 
 **Balance Update:**
-```
+```text
 event: message
 data: [{"balance":"5000000000000000000","allowance":"115792089237316195423570985008687907853269984665640564039457584007913129639935","token":{"address":"0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2","decimals":18,"symbol":"WETH","name":"Wrapped Ether"}}]
 ```
 
 **Keep-Alive Ping:**
-```
+```text
 event: ping
 data: {}
 ```
 
 ### Response Headers
 
-```
+```http
 Content-Type: text/event-stream
 Cache-Control: no-cache
 Connection: keep-alive
@@ -190,7 +190,7 @@
 
 ### Allowance Context
 
 The allowance returned is specifically for the CoW Protocol vault relayer contract. This represents the approval amount verified during order placement. A typical maximum approval value is `115792089237316195423570985008687907853269984665640564039457584007913129639935`.
 
 ### Balance Format Details
 

bff/api-reference/endpoints/markets.mdx

@@ -15,7 +15,7 @@
 
 ### Path Parameters
 
 - **chainId** (string, required): The blockchain network ID (e.g., `1`, `100`, `11155111`)
 - **baseTokenAddress** (string, required): Currency that is being bought or sold (the token you're trading)
 - **quoteTokenAddress** (string, required): Currency in which the price of the base token is quoted (the token you're trading for)
 
@@ -23,18 +23,18 @@
 
 | Parameter                 | Type    | Description                              |
 | ------------------------- | ------- | ---------------------------------------- |
 | orderKind                 | string  | Type of order: `buy` or `sell`           |
 | partiallyFillable         | boolean | Whether the order can be partially filled |
 | sellAmount                | string  | Amount to sell in token units            |
 | buyAmount                 | string  | Amount to buy in token units             |
 | expirationTimeInSeconds   | number  | Order expiration time in seconds         |
 | feeAmount                 | string  | Fee amount in token units                |
 
 ### Response
 
 | Field       | Type   | Description                                     |
 | ----------- | ------ | ----------------------------------------------- |
 | slippageBps | number | Slippage tolerance in basis points. Min: 0, Max: 10000 |
 
 ### Code Examples
 
@@ -131,7 +131,7 @@
 
 Slippage tolerance responses are cached for **120 seconds** (2 minutes):
 
-```
+```http
 Cache-Control: public, max-age=120
 ```
 
@@ -153,7 +153,7 @@
 
 ### Best Practices
 
 1. **Use recommended slippage**: The API's recommendation balances trade success vs. slippage cost
 2. **Adjust for urgency**: Increase slippage for faster execution in volatile markets
 3. **Consider order size**: Larger orders may need higher slippage tolerance
 4. **Cache responsibly**: Respect cache headers to reduce API load

bff/api-reference/endpoints/notifications.mdx

@@ -15,7 +15,7 @@
 
 ### Path Parameters
 
 - **account** (string, required): Ethereum wallet address to retrieve notifications for
 
 ### Response
 
@@ -25,7 +25,7 @@
 | --------- | ------ | ----------------------------------------------------- |
 | id        | string | Unique notification identifier                        |
 | account   | string | The account address this notification is for          |
 | type      | string | Type of notification (e.g., "order_filled")           |
 | message   | string | Human-readable notification message                   |
 | timestamp | string | ISO 8601 timestamp when the notification was created  |
 | metadata  | object | Additional notification-specific data                 |
@@ -121,7 +121,7 @@
 
 Notification responses are cached for **5 minutes** (300 seconds):
 
-```
+```http
 Cache-Control: public, max-age=300
 ```
 
@@ -193,7 +193,7 @@
 | ---------------- | ------------------- | ------------------------------ |
 | CMS disabled     | Service unavailable | Enable CMS configuration       |
 | Invalid address  | 400 Bad Request     | Verify address format          |
 | Database error   | 500 Internal Error  | Retry with exponential backoff |
 | No notifications | Empty array `[]`    | Normal response, no error      |
 
 ### Best Practices

bff/api-reference/introduction.mdx

@@ -11,19 +11,19 @@
 
 The API is accessible at:
 
-```
+```text
 https://api.cow.fi
 ```
 
 For local development:
 
-```
+```text
 http://localhost:3001
 ```
 
 ## API Architecture
 
 The BFF API is built on Fastify and provides endpoints organized into several key areas:
 
 * **Tokens**: Token information, pricing, and holder data
 * **Accounts**: User balances and allowances with real-time updates
@@ -37,17 +37,17 @@
 
 ## Chain Support
 
 The API supports multiple blockchain networks. Chain IDs are specified in the path for most endpoints:
 
 * `1` - Ethereum Mainnet
 * `100` - Gnosis Chain
 * `11155111` - Sepolia Testnet
 
 Alternatively, you can use chain slugs:
 
 * `mainnet` - Ethereum Mainnet
 * `gnosis` - Gnosis Chain
 * `sepolia` - Sepolia Testnet
 
 ## Response Format
 

bff/development/creating-services.mdx

@@ -1,11 +1,12 @@
 ---
 title: "Creating Services and Libraries"
+sidebarTitle: "Creating Services"
 description: "Guide to scaffolding new services, applications, and libraries in the CoW Protocol BFF monorepo using NX generators"
 ---
 
 # Creating Services and Libraries
 
 The CoW Protocol BFF monorepo uses NX generators to scaffold new projects with proper TypeScript, Docker, and configuration setup.
 
 ## Available Generators
 
@@ -17,13 +18,13 @@
 | `yarn new:node`   | Background workers, CLI tools |
 | `yarn new:lib`    | Shared libraries             |
 
 ## Fastify API Services
 
 ```bash
 yarn new:fastify
 ```
 
 Running the Fastify generator creates a complete API structure with:
 
 - App configuration (`src/app/app.ts`)
 - Entry point (`src/main.ts`)

bff/development/testing.mdx

@@ -44,9 +44,9 @@
 - Unit tests: `*.spec.ts`
 - E2E tests: `*.e2e-spec.ts`
 
 Test files should be colocated with the code they test:
 
-```
+```text
 libs/repositories/src/
 ├── usd/
 │   ├── UsdRepository.ts
@@ -180,7 +180,7 @@
 });
 ```
 
 ### Testing API Endpoints (Fastify)
 
 ```typescript
 describe('GET /about', () => {
@@ -221,7 +221,7 @@
 
 ## CI Integration
 
 GitHub Actions automatically runs tests on commits. The CI configuration uses NX's affected command to only test changed projects:
 
 ```bash
 nx affected --target=test
@@ -233,7 +233,7 @@
 2. **Use descriptive test names** - Describe the scenario being tested
 3. **One assertion concept per test** - Keep tests focused
 4. **Follow Given-When-Then** - Structure tests clearly
 5. **Colocate tests with code** - Keep test files next to implementation
 6. **Use factory functions** for test data creation
 7. **Clean up resources** in `afterAll`/`afterEach` hooks
 8. **Avoid testing private methods** - Test through public interfaces

bff/services/api.mdx

@@ -1,17 +1,17 @@
 ---
 title: "API Service"
-description: "Documentation for the BFF API service, a Fastify-based HTTP server that aggregates data from multiple sources to provide unified endpoints for trading, tokens, and balances"
+description: "Documentation for the CoW Protocol BFF API service — a Fastify server providing unified trading, token, and balance endpoints."
 ---
 
 # API Service
 
 The API service is the main HTTP API server that provides a unified interface for CoW Protocol frontend applications. Built with Fastify, it aggregates data from multiple sources and provides RESTful endpoints for trading, tokens, balances, and more.
 
 ## Purpose and Responsibilities
 
 The API service serves as the Backend For Frontend (BFF) layer with the following responsibilities:
 
 * **Unified API Gateway**: Aggregates data from CoW Protocol APIs, blockchain nodes, and external services
 * **Token Information**: Provides token prices, balances, and metadata
 * **Trading Data**: Exposes yield pool information, market slippage, and trade simulations
 * **Affiliate Program**: Manages affiliate program data and exports
@@ -84,8 +84,8 @@
 | ----------------------- | -------------------------------- |
 | `COINGECKO_API_KEY`     | CoinGecko API key for price data |
 | `GOLD_RUSH_API_KEY`     | Covalent GoldRush API key        |
 | `ETHPLORER_API_KEY`     | Ethplorer API key for token data |
 | `MORALIS_API_KEY`       | Moralis API key                  |
 | `TENDERLY_API_KEY`      | Tenderly API key for simulations |
 | `TENDERLY_PROJECT_NAME` | Tenderly project name            |
 | `TENDERLY_ORG_NAME`     | Tenderly organization name       |
@@ -154,7 +154,7 @@
 
 - **CoW Analytics Database** - PostgreSQL database for analytics data (read-only access). Configuration: `COW_ANALYTICS_DATABASE_*` variables
 
 - **Blockchain RPC Nodes** - HTTP or WebSocket endpoints for supported chains (Ethereum, Gnosis, etc.). Configuration: `RPC_URL_1`, `RPC_URL_100`, etc.
 
 ### External APIs
 
@@ -168,7 +168,7 @@
 
 ### Plugin System
 
 The API uses Fastify's plugin system to organize functionality:
 
 * **env.ts** - Environment variable validation
 * **cors.ts** - CORS configuration
@@ -185,7 +185,7 @@
 
 Routes are organized hierarchically and auto-loaded:
 
-```
+```text
 routes/
 ├── about.ts              # Health/version endpoint
 ├── hooks.ts              # Dune Analytics hooks
@@ -205,7 +205,7 @@
 
 * **Affiliate Program Export Poller** - Periodically exports affiliate program data
 
 ## Nx Commands
 
 ```bash
 # Development server

bff/services/notification-producer.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Notification Producer"
 description: "Background service that monitors blockchain events and generates push notifications for CoW Protocol users across multiple chains"
 ---
 
 # Notification Producer
 
 The Notification Producer is a background service that monitors blockchain events and generates push notifications for users subscribed to CoW Protocol updates. It tracks trades, expired orders, and CMS notifications across multiple chains.
 
 ## Purpose and Responsibilities
 
@@ -135,7 +135,7 @@
 
 **How it works**:
 
 * Polls blockchain for new blocks
 * Queries CoW Protocol settlement events
 * Matches trades to subscribed user accounts
 * Enriches notifications with token information and USD values
@@ -145,7 +145,7 @@
 
 * Batch processing (up to 5000 blocks per batch)
 * State persistence for crash recovery
 * Handles blockchain reorgs gracefully
 
 ### 2. Expired Orders Notification Producer
 
@@ -289,7 +289,7 @@
 2. Send it to the RabbitMQ queue
 3. Be delivered by connected consumers (e.g., Telegram bot)
 
 ## Nx Commands
 
 ```bash
 # Development server
@@ -312,7 +312,7 @@
 
 The producer outputs structured logs with prefixes:
 
-```
+```log
 [notification-producer:main] Start notification producer for networks: 1, 100
 [TradeNotificationProducer:1] Indexing from block 18500000 to 18500100: 101 blocks
 [TradeNotificationProducer:1] Sending 5 notifications

changelog.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Changelog"
-description: "Latest updates to CoW DAO documentation."
+description: "Latest updates and changes to CoW Protocol and CoW DAO documentation — new features, guides, and improvements."
 ---
 
 <Update label="Documentation migrated to Mintlify" description="2025-03-04">

composable-cow/api/composable-cow.mdx

@@ -5,13 +5,13 @@
 
 # ComposableCoW Contract
 
 The `ComposableCoW` contract enables creation and management of programmatic orders on CoW Protocol, supporting both single orders and merkle tree-based authorization for automated trading strategies.
 
 ## Deployment
 
 Deployed identically across six networks (Ethereum Mainnet, Gnosis Chain, Arbitrum One, Base, Optimism, and Polygon) at address:
 
-```
+```text
 0xfdaFc9d1902f4e0b84f65F49f244b32b31013b74
 ```
 
@@ -20,7 +20,7 @@
 | Variable | Description |
 |----------|-------------|
 | `domainSeparator` | EIP-712 signature domain from GPv2Settlement |
 | `roots` | Mapping storing merkle roots for programmatic orders |
 | `singleOrders` | Tracking individual authorized orders |
 | `swapGuards` | Additional order restriction mechanisms |
 | `cabinet` | On-chain storage for context-specific data |
@@ -32,9 +32,9 @@
 - `create()` - Authorize a single programmatic order
 - `createWithContext()` - Authorize with value factory context storage
 
 ### Merkle Tree Management
 
 - `setRoot()` - Set merkle root for batch authorization
 - `setRootWithContext()` - Set root with value factory context
 
 ### Order Retrieval
@@ -48,10 +48,10 @@
 
 ## Critical Requirements
 
 - Safe multisig wallets must use `ExtensibleFallbackHandler`
 - Handler contracts must implement `IConditionalOrderGenerator`
 - Token approvals required for the GPv2 Vault Relayer
 
 ## Authorization Models
 
 Orders may be authorized individually via `create()` or in batches using merkle proofs, enabling efficient management of multiple programmatic orders.

composable-cow/api/extensible-fallback-handler.mdx

@@ -9,9 +9,9 @@
 
 ## Deployment
 
 Deployed at the same address across multiple networks (Ethereum Mainnet, Gnosis Chain, Arbitrum One, Base, Optimism, and Polygon):
 
-```
+```text
 0x2f55e8b20D0B9FEFA187AA7d00B6Cbe563605bF5
 ```
 

composable-cow/api/orders/good-after-time.mdx

@@ -24,7 +24,7 @@
 
 When enabled, the price checker validates that:
 
-```
+```text
 buyAmount >= (expectedOut * (MAX_BPS - allowedSlippage)) / MAX_BPS
 ```
 
@@ -35,7 +35,7 @@
 | Error | Condition |
 |-------|-----------|
 | `PollTryAtEpoch` | Block timestamp precedes `startTime` ("too early") |
 | `OrderNotValid` | Owner lacks required sellToken balance ("balance insufficient") |
 | `PollTryNextBlock` | Insufficient expected output given slippage tolerance ("price checker failed") |
 
 The implementation supports flexible buy amounts while maintaining replay protection through balance verification.

composable-cow/api/orders/perpetual-stable-swap.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Perpetual Stable Swap API"
 description: "API reference for the Perpetual Stable Swap programmatic order type for automated stablecoin rebalancing."
 ---
 
 # Perpetual Stable Swap API
@@ -24,7 +24,7 @@
 2. Identifies which token has greater value
 3. Creates a sell order for the entire balance of the higher-value token
 4. Applies the spread formula:
-   ```
+   ```text
    buyAmount = convertedAmount * (10000 + halfSpreadBps) / 10000
    ```
 5. Returns tokens to the owner automatically (`receiver = address(0)`)
@@ -35,7 +35,7 @@
 
 ## Design Considerations
 
 - Orders utilize time-bucketing to prevent orderbook spam
 - Remain non-partially-fillable
 - Charge zero protocol fees
 - The spread parameter prevents order collision unless intentionally set to zero

composable-cow/guides/debugging.mdx

@@ -9,7 +9,7 @@
 
 ## Why didn't my order execute?
 
-```
+```text
 Order not executing
 ├── Is the tx confirmed on-chain?
 │   └── No → Wait for confirmation or check if tx reverted
@@ -29,17 +29,17 @@
 ## Step 1: Check the transaction
 
 Verify the `ComposableCoW.create()` transaction was confirmed:
 - Check the tx hash on Etherscan/block explorer
 - Look for the `ConditionalOrderCreated` event in the logs
 - If the tx reverted, check the revert reason (usually setup issues — see [Troubleshooting](/composable-cow/guides/troubleshooting))
 
 ## Step 2: Check watch-tower indexing
 
 The [watch-tower](/watch-tower/introduction) monitors on-chain events and posts discrete orders to the orderbook.
 
 **Is the public watch-tower monitoring your chain?**
 
 Supported: Ethereum, Gnosis Chain, Arbitrum One, Base, Polygon, Avalanche, BNB Chain, Linea, Plasma, Ink, Sepolia
 
 **Check via the watch-tower API:**
 
@@ -95,7 +95,7 @@
 
 | Status | Meaning | Action |
 |---|---|---|
 | `open` | Order is in the orderbook, waiting for solvers | Check if balance/allowance is sufficient |
 | `fulfilled` | Order was filled | Success |
 | `expired` | `validTo` passed without fill | Widen slippage or increase validity |
 | `cancelled` | Order was cancelled | Check if it was intentional |
@@ -125,9 +125,9 @@
 - The part amount may be too small to be profitable
 - The Safe may not have enough balance for the remaining parts
 
 ### Order works on mainnet but not testnet
 
 Sepolia has limited solver participation. See the [testing guide](/cow-protocol/howto/integrate/testing) for testnet-specific advice.
 
 ### Order executes once but not again
 

composable-cow/guides/signature-construction.mdx

@@ -16,7 +16,7 @@
 
 When the CoW Protocol settlement contract executes a trade for a ComposableCoW order, the following verification chain runs:
 
-```
+```text
 GPv2Settlement
   │
   ├─ calls isValidSignature(orderDigest, signature) on the Safe
@@ -42,7 +42,7 @@
   └─ returns EIP-1271 magic value (0x1626ba7e) if valid
 ```
 
 The signature you construct is what gets passed through this entire chain. ComposableCoW decodes it to recover the `ConditionalOrderParams` and any offchain input, then uses these to regenerate the expected order and verify it matches.
 
 ## Signature encoding
 
@@ -50,7 +50,7 @@
 
 | Component | Type | Description |
 |-----------|------|-------------|
 | `params` | `ConditionalOrderParams` | The handler address, salt, and staticInput used when creating the order |
 | `offchainInput` | `bytes` | Any additional off-chain data the handler needs (empty bytes if none) |
 
 The `ConditionalOrderParams` struct consists of:
@@ -79,15 +79,15 @@
 The params must match exactly. Even a single byte difference in `staticInput` produces a different order hash, and ComposableCoW will reject the signature because the order was never authorized.
 </Warning>
 
 ### Prepare offchain input
 
 Determine whether your handler requires offchain input. Most standard handlers (TWAP, StopLoss) use empty bytes (`0x`). Custom handlers may require additional data that is not stored on-chain but is needed to generate the tradeable order.
 
 If your handler's `getTradeableOrder()` function uses the `offchainInput` parameter, you must provide the expected value. Otherwise, pass empty bytes.
 
 ### ABI-encode the signature
 
 Encode the `ConditionalOrderParams` struct and offchain input together:
 
 <CodeGroup>
 
@@ -242,7 +242,7 @@
 | Wrong `from` address | `isValidSignature` is called on the wrong contract | Use the Safe address, not an EOA signer address |
 | Mismatched `ConditionalOrderParams` | ComposableCoW cannot find the order in `singleOrders` mapping | Ensure `handler`, `salt`, and `staticInput` exactly match what was passed to `create()` |
 | Handler returns unexpected order | Order digest mismatch during verification | Verify the handler's `getTradeableOrder()` output matches the order you are submitting |
 | Missing offchain input | Handler reverts when generating the tradeable order | Provide the offchain data your handler expects, or empty bytes if none |
 | Safe not configured | `isValidSignature` reverts or returns wrong value | Ensure ExtensibleFallbackHandler is set and ComposableCoW is registered as domain verifier ([Setup guide](/composable-cow/guides/setup)) |
 
 ## Verifying locally

composable-cow/introduction.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Introduction"
-description: "ComposableCoW is the contract that implements programmatic orders on CoW Protocol — orders that execute automatically when predefined on-chain conditions are satisfied."
+description: "ComposableCoW implements programmatic orders on CoW Protocol — orders that execute automatically when on-chain conditions are met."
 ---
 
 # Introduction to ComposableCoW
@@ -22,7 +22,7 @@
 Two approaches are available:
 
 1. **Individual order creation** via `ComposableCoW.create()` for simpler scenarios
 2. **Merkle tree-based authorization** for efficiently managing numerous programmatic orders with reduced on-chain storage requirements
 
 ## Technical Infrastructure
 
@@ -38,4 +38,4 @@
 
 ## Security Status
 
 The system underwent audits by Ackee Blockchain and Gnosis teams, with reports available in the repository's audit directory.

composable-cow/order-types/good-after-time.mdx

@@ -25,7 +25,7 @@ The off-chain input accepts varying `buyAmount` values, meaning different `buyAm
 
 Optional Milkman price checkers validate that provided buy amounts meet minimum requirements. The acceptable minimum calculates as:
 
-```
+```text
 expectedOut * (10000 - allowedSlippage) / 10000
 ```
 

composable-cow/order-types/perpetual-stable-swap.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Perpetual Stable Swap"
 description: "Automatic rebalancing between two stablecoins by continuously trading whichever token has higher balance."
 ---
 
 # Perpetual Stable Swap
 
 This programmatic order type enables automatic rebalancing between two stablecoins by continuously trading whichever token you hold more of. The mechanism adds a configurable spread to generate profit from rebalancing activities.
 
 ## Core Mechanism
 
@@ -15,20 +15,20 @@
 
 | Parameter | Description |
 |-----------|-------------|
 | `tokenA` / `tokenB` | The two assets for swapping, typically stablecoins like USDC and DAI |
 | `validityBucketSeconds` | Controls order validity duration by bucketing time into fixed windows. Recommended: 604800 (one week) or 1209600 (two weeks) |
 | `halfSpreadBps` | Basis point markup above 1:1 parity. 10 = 0.1% markup, 100 = 1% markup |
 | `appData` | IPFS hash associated with the order |
 
 ### Validity Bucket Calculation
 
-```
+```text
 validTo = ((currentTime / validityBucketSeconds) * validityBucketSeconds) + validityBucketSeconds
 ```
 
 ### Buy Amount Formula
 
-```
+```text
 buyAmount = convertAmount(sellAmount) * (10000 + halfSpreadBps) / 10000
 ```
 
@@ -42,7 +42,7 @@
 
 Different token decimals receive automatic conversion. For example, converting 1000 USDC (6 decimals) to DAI (18 decimals):
 
-```
+```text
 1000 * 10^6 * 10^(18-6) = 1000 * 10^18
 ```
 
@@ -61,16 +61,16 @@
 
 ### Liquidity Provision
 
 Maintain equal stablecoin amounts while automatically rebalancing as supplies deplete, earning spread on each trade.
 
 ### Yield Capture
 
 Exploit minor stablecoin peg deviations with modest spreads (0.1-0.5%) while maintaining original position exposure.
 
 ### Portfolio Diversification
 
 Distribute holdings across multiple stablecoins with automatic equilibration to mitigate single-asset depeg risk.
 
 ## Implementation Note
 
 The validity bucket system ensures identical `orderUid` values when queried within the same time window, preventing orderbook spam on CoW Protocol.

composable-cow/order-types/stop-loss.mdx

@@ -11,7 +11,7 @@ Stop Loss orders are oracle-based programmatic orders that automatically trigger
 
 The system monitors price ratios between two tokens. When the calculated exchange rate reaches or falls below the strike price, the order becomes executable:
 
-```
+```text
 (sellTokenPrice / buyTokenPrice) <= strike
 ```
 

composable-cow/tutorials/custom-order-type.mdx

@@ -12,7 +12,7 @@ A `TradeAboveThreshold` programmatic order that:
 - When the balance exceeds a threshold, generates a sell order for the excess
 - Automatically repeats until cancelled
 
-```
+```text
 Safe balance: 15,000 USDC (threshold: 10,000)
 → Generates order: sell 5,000 USDC for WETH
 → Watch Tower submits it to CoW Protocol
@@ -36,7 +36,7 @@ forge install cowprotocol/composable-cow
 
 Create `remappings.txt`:
 
-```
+```text
 @cowprotocol/=lib/composable-cow/
 @openzeppelin/=lib/composable-cow/lib/openzeppelin-contracts/
 safe/=lib/composable-cow/lib/safe-contracts/contracts/
@@ -348,7 +348,7 @@ revert IConditionalOrder.PollNever("Order permanently invalid");
 
 ## Architecture
 
-```
+```text
 Safe Wallet
   └── ComposableCoW (fallback handler)
         └── Your Handler (TradeAboveThreshold)

cow-amm.mdx

@@ -1,23 +1,24 @@
 ---
 title: "CoW AMM: The First MEV-capturing AMM"
-description: "CoW AMM protects LPs from LVR so they can provide liquidity with less risk and more return. CoW AMM achieves close to 5% more in TVL compared to reference pools, protects millions from LVR, and has captured over $100,000 in surplus for LPs to date."
+sidebarTitle: "CoW AMM"
+description: "CoW AMM protects liquidity providers from LVR with less risk and more return — the first MEV-capturing AMM built on CoW Protocol."
 hidden: true
 ---
 
 ## AMMs don't want you to know about LVR
 
 Liquidity providers expect their tokens to earn yield, but the dirty little secret of AMMs is that most liquidity pools lose money. In fact, hundreds of millions of dollars of LP funds are stolen by arbitrageurs every year. These losses are known as loss-versus-rebalancing (LVR). LVR is a bigger source of MEV than frontrunning and sandwich attacks combined.
 
 ## An AMM designed with LPs in mind
 
 CoW AMM eliminates LVR once and for all by using batch auctions to send surplus to LPs
 
 1. Liquidity providers deposit tokens into protected CoW AMM liquidity pools, where traders can access the liquidity
 2. Solvers bid to rebalance CoW AMM pools whenever there is an arbitrage opportunity
 3. The solver that offers the most surplus to the pool wins the right to rebalance the pool
 4. CoW AMM eliminates LVR by capturing arbitrage value for LPs and shielding it from MEV bots
 
 ## Deploy liquidity on CoW AMM
 
 Thanks to CoW AMM's integration with Balancer, LPs can now [deploy their liquidity or create a brand new pool in just a few clicks](https://balancer.fi/pools/cow).
 

cow-amm/explanation/how-cow-amms-work.mdx

@@ -1,5 +1,6 @@
 ---
 title: "How CoW AMMs Work"
+description: "Learn how CoW AMM uses the Function-Maximizing AMM mechanism to eliminate LVR and protect liquidity providers from MEV."
 ---
 
 ## FM-AMMs
@@ -14,27 +15,27 @@
 
 ## Contract architecture
 
 CoW AMM is built as a set of contracts that integrate natively with Balancer's infrastructure and CoW Protocol's solver competition:
 
 - **`BCoWPool`**: The AMM pool contract, which extends Balancer's `BPool`. Each CoW AMM pool is a `BCoWPool` instance that holds liquidity and defines the trading function. It implements the `IConditionalOrder` interface from [ComposableCoW](/cow-protocol/reference/contracts/periphery/composable-cow), which allows the CoW Protocol watchtower to poll the pool for tradeable orders.
 - **`BCoWFactory`**: The factory contract used to deploy new CoW AMM pools. It creates `BCoWPool` instances with the correct configuration for CoW Protocol integration.
 - **`BCoWHelper`**: A helper contract for solvers. Given a pool and the current on-chain state, it generates valid order parameters that solvers can include in their settlement batches.
 
 The end-to-end flow works as follows:
 
 1. **Pool deployment** — An LP deploys a new pool via `BCoWFactory` and adds liquidity.
 2. **Watchtower polling** — The CoW Protocol watchtower periodically calls each pool's `getTradeableOrderWithSignature` (via the `IConditionalOrder` interface) to discover when the pool has a tradeable order.
 3. **Solver queries** — When a solver identifies a CoW AMM order, it can use `BCoWHelper` to compute valid order parameters that move the AMM curve higher.
 4. **Batch settlement** — The solver includes the CoW AMM order in its settlement batch alongside user orders, enabling coincidence of wants.
 5. **Pool rebalances** — After settlement, the pool's reserves are updated and the AMM curve moves to reflect the new balances.
 
 <Note>
   CoW AMMs are **not** based on Safe (the old architecture). They are native Balancer pools with direct CoW Protocol integration via the ComposableCoW programmatic order framework.
 </Note>
 
 ## Getting Started with CoW AMM
 
 To facilitate easy liquidity providing, CoW DAO has partnered with Balancer to implement CoW AMMs into the Balancer ecosystem. LPs can [use the Balancer app](https://balancer.fi/pools/cow) to LP direclty on one of over a dozen liquidity pools.
 
 In the next section, LPs can learn how to create their own CoW AMM pools for brand new assets either on Balancer or outside the platform.
 

cow-amm/explanation/the-problem-of-lvr.mdx

@@ -1,21 +1,22 @@
 ---
 title: "The Problem of LVR (Loss-versus-rebalancing)"
-description: "First coined by a team of researchers from  LVR is a form of arbitrage that occurs whenever an AMM has an outdated (stale) price in comparison to some other trading venue."
+sidebarTitle: "The Problem of LVR"
+description: "Loss-versus-rebalancing (LVR) is arbitrage exploiting stale AMM prices — learn how it impacts LPs and how CoW AMM eliminates it."
 ---
 
 Arbitrageurs exploit this difference by trading from the AMM to the more liquid exchange (usually a centralized exchange like Binance), correcting the arbitrage and extracting value from LPs in the process.
 
 # How LVR Works
 
 Most AMMs (such as Uniswap) are examples of constant function automated market makers—CF-AMMs. These AMMs take in two assets and automatically re-calculate prices after each trade to ensure ample liquidity at all times. This means the AMMs experience asset price discovery as they are being traded against.
 
 However, since crypto assets trade on various platforms including centralized exchanges, the prices on a CF-AMM may be outdated compared to the more liquid prices on a centralized exchange. This discrepancy allows arbitrageurs to trade between the liquid exchange and the outdated AMM, correcting prices and capturing arbitrage in the process.
 
 "Loss-versus-rebalancing" is the scenario where an LP provides liquidity to a CF-AMM whose prices are stale compared to a more liquid venue like a centralized exchange. By leaving their funds in the liquidity pool, they are not making as much money as they could be if they were to constantly "rebalance" between the AMM and the exchange. Thus, they incur a "loss" compared to what they would have in a "rebalancing" strategy.
 
 # The Impact of LVR on LPs
 
 Many liquidity providers haven’t even heard of LVR, but it costs them 5–7% of their liquidity, resulting in hundreds of millions lost each year. In fact, when accounting for LVR, many of the largest liquidity pools are not profitable for LPs at all.
 
 Due to these losses, LVR is a type of MEV (maximal extractable value) that accounts for more price exploitation than frontrunning and sandwich attacks combined.
 

cow-amm/tutorials/cow-amm-for-solvers.mdx

@@ -1,34 +1,35 @@
 ---
 title: "CoW AMM Liquidity for Solvers"
+description: "How CoW Protocol solvers can access and route through CoW AMM liquidity pools, including integration details and surplus optimization."
 ---
 
 ## I'm a solver. How do I use CoW AMM liquidity?
 
 CoW AMM orders already appear in the CoW Protocol orderbook, so you're already using its liquidity. However, CoW AMMs allow solvers to specify custom buy and sell amounts, as long as the order preserves or increases the constant product invariant of the token reserves.
 
 CoW AMMs can be treated as a liquidity source akin to Uniswap or Balancer weighted pools with uniform weights. Each CoW AMM is a pair that trades two tokens.
 
 Importantly, surplus for a CoW AMM order is measured differently when computing the solver reward payout.
 
 ### Indexing Balancer CoW AMMs
 
 CoW AMM pairs can be detected by listening to the `COWAMMPoolCreated` events emitted by the `BCowFactory` instance for the current chain (see the [official contract repository](https://github.com/balancer/cow-amm) for the current deployment addresses). All addresses of Balancer CoW AMMs are sent as part of the auction instance as `surplusCapturingJitOrderOwners`.
 
 The AMM reserves are the balance of the two tokens traded by the AMM.
 
 ### Creating CoW AMM orders with the helper contract
 
 Integrating CoW AMM orders requires adding a JitOrder with the CoW AMM. This order should be described from the CoW AMM pool's perspective. So if a user wants to sell token A to buy token B and you would like to settle (part of) this order with a CoW AMM, then you would need to add a JitOrder from the CoW AMM's perspective to match (part of) this order. In other words, you would be adding a JitOrder for the CoW AMM to sell token B to buy token A. You can do this by calling the `orderFromBuyAmount` because the user’s amount is exactly how much you would want the pool to receive, asking for the amount of tokens in exchange.
 
 [The source code for the helper contract can be found here.](https://github.com/balancer/cow-amm/blob/main/src/contracts/BCoWHelper.sol) The `orderFromBuyAmount` and 'orderFromSellAmount' methods return the order, preInteractions, postInteractions, and signature. This can be used to generate the order (JitOrder) and check prices.
 
 This order generated by the BCoWHelper contract will contain the limit prices for which the CoW AMM is willing to trade. Trading at exactly these limit prices will not generate surplus for the CoW AMM, any price improvement from these limit prices will be surplus captured by the CoW AMM.
 
 One thing to keep in mind when using the helper contract to generate these JitOrders is that both the `orderFromSellAmount` and `orderFromBuyAmount` methods return an order where the `partiallyFillable` field is marked as true. However, since the driver does not support partially fillable JitOrders, it replaces the partiallyFillable field with false. This means that the `partiallyFillable` field must be set to false before passing the solution to the driver and the signature of both the JitOrder and the commit hash in the pre-interaction should be updated accordingly.
 
 Doing this will generate additional surplus in the solver competition (assuming you trade at a better price than the provided limit price). For example, if a solver would like to settle a user using outside liquidity that trades a pair for which there is a CoW AMM, then that solver can compare those prices with that of the CoW AMM. This (or part of this) interaction can then be replaced with the CoW AMM to generate additional surplus. This way the solver can integrate CoW AMMs by solving as if these CoW AMM's do not exist, and then check whether some of the outside interactions can be replaced by CoW AMMs (note: UPC and EBBO apply to CoW AMMs as well).
 
 Another way that a solver can use CoW AMM's is by using outside liquidity from the competition/auction to trade with the CoW AMM, thereby re-balancing the AMM and receiving an additional surplus for doing so if the prices of the CoW AMM is off relative to the outside world.
 
 The helper contracts are deployed here:
 
@@ -39,7 +40,7 @@
 * Avalanche N/A
 * Polygon N/A
 * BNB N/A
 * Linea N/A
 * Plasma N/A
 
 ### Settling a custom order
@@ -87,7 +88,7 @@
 
 If we call `X` (resp. `Y`) the reserves of sell (resp. buy) token, and `x` (resp. `y`) the executed sell (resp. buy) amount, then the minimal buy amount is `x Y / (X - x)` and the order surplus with that choice for the limit amount is:
 
-```
+```text
                  x Ysurplus =  y -  ----- .                X - x
 ```
 

cow-contracts/api/contracts/settlement.mdx

@@ -60,7 +60,7 @@
 | `tokens` | `IERC20[]` | Array of tokens involved in the settlement |
 | `clearingPrices` | `uint256[]` | Clearing prices for each token (aligned with tokens array) |
 | `trades` | `GPv2Trade.Data[]` | Encoded trade data |
 | `interactions` | `GPv2Interaction.Data[][3]` | Pre, intra, and post-settlement interactions |
 
 ### swap
 
@@ -73,7 +73,7 @@
 ) external nonReentrant onlySolver returns (int256);
 ```
 
 ### invalidateOrder
 
 Allows order owners to cancel orders on-chain.
 
@@ -101,7 +101,7 @@
 
 The contract enforces that clearing prices respect order limits:
 
-```
+```text
 order.sellAmount * sellPrice >= order.buyAmount * buyPrice
 ```
 

cow-contracts/api/ts/deploy.mdx

@@ -79,7 +79,7 @@ function deterministicDeploymentAddress(
 
 The computation follows:
 
-```
+```text
 address = keccak256(0xff ++ deployerAddress ++ salt ++ keccak256(initCode))[12:]
 ```
 

cow-contracts/concepts/settlement.mdx

@@ -9,7 +9,7 @@
 
 ## Uniform Pricing Model
 
 Unlike AMMs where each trade impacts the next price, CoW Protocol uses a **price vector** where all trades in a batch settle at predetermined rates, ensuring equitable execution across participants.
 
 This eliminates MEV opportunities within batches, as all participants receive the same price for the same token pair.
 
@@ -31,14 +31,14 @@
 Settlement involves three interaction phases:
 
 1. **Pre-interactions** - Setup tasks (e.g., permit approvals, token wrapping)
 2. **Intra-interactions** - DEX trades for liquidity sourcing (e.g., Uniswap, Balancer swaps)
 3. **Post-interactions** - Cleanup operations (e.g., token unwrapping, fee distribution)
 
 ## Price Verification
 
 Orders validate through the equation:
 
-```
+```text
 sellAmount * sellPrice >= buyAmount * buyPrice
 ```
 
@@ -70,7 +70,7 @@
 | **Limit Price Compliance** | Clearing prices must respect order limits |
 | **Overfill Prevention** | `filledAmount` mapping prevents double-execution |
 | **Atomicity** | Entire settlement reverts if any trade fails |
 | **Reentrancy Protection** | `nonReentrant` modifier on all entry points |
 
 <Warning>
 Interactions cannot target the VaultRelayer to prevent exploitation of user token approvals.

cow-protocol/explanation/architecture/autopilot.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Autopilot"
+description: "How the Autopilot orchestrates CoW Protocol batch auctions — collecting orders, coordinating solvers, and submitting settlements."
 ---
 
 ## Overview
@@ -32,7 +33,7 @@
 
 The autopilot builds an auction that includes all tradable orders. To handle this, it needs to maintain a complete overview of the protocol.
 
 Much of the order data it needs is collected through the database, which is shared with the orderbook. The database stores the vast majority of available order information, including user signatures.
 
 Other information can only be retrieved on-chain and is updated every time a new block is mined. For example, it needs to know from the protocol:
 
@@ -43,13 +44,13 @@
 
 Retrieved information isn't limited to the CoW Protocol itself. The autopilot needs to provide a reference price for each token in an order (a numéraire); the reference price is used to normalize the value of the [surplus](/cow-protocol/reference/core/auctions/the-problem), since the surplus must be comparable for all orders and two orders could use the most disparate `ERC-20` tokens. The reference token is usually the chain's native token, since it's the token used to pay for the gas needed when executing a transaction. Orders whose price can't be fetched are discarded and won't be included in an auction.
 
 Native token price fetching is handled by an integrated price estimator in the autopilot. The price is fetched from multiple sources and may change based on the current configurations. Prices are both queried from a list of selected existing solvers as well as retrieved internally by the autopilot (for example, by querying some external parties like Paraswap and 1inch, but also by reading on-chain pool data as Uniswap).
 
 Orders that can't be settled are filtered out. This is the case if, for example:
 
 * an order is expired
 * for fill-or-kill orders the user's balance isn't enough to settle the order
 * the approval to the vault relayer is missing
 * the involved tokens aren't supported by the protocol
 
 The autopilot also checks that [`ERC-1271`](/cow-protocol/reference/core/signing-schemes#erc-1271) signatures are currently valid.

cow-protocol/explanation/architecture/driver.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Driver"
-description: "People interested in running a solver to participate in CoW Protocol mainly want to focus on implementing the most efficient solver engine. However, there are also many mundane tasks that may not seem like a competitive advantage but have to be done regardless."
+description: "The Driver handles operational tasks for CoW Protocol solvers, letting solver engines focus on finding the most efficient execution."
 ---
 
 ## Overview
@@ -13,7 +13,7 @@
 
 The `driver` sits between the [autopilot](/cow-protocol/explanation/architecture/autopilot) and a [solver engine](/cow-protocol/explanation/architecture/solver-engine) and acts as a intermediary between the two. In case you decide to run the driver for a solver engine the lifecycle of an auction looks like this.
 
 Splitting the driver from the solver engine is just a design decision to keep the barrier of entry for new solvers low. However, there is nothing preventing you from patching, forking or reimplementing the driver. You can even merge the responsibilities of the driver and solver engine into one if you want to build the most optimal solver possible; the only hard requirement is that the component the autopilot interfaces with implements this [interface](/cow-protocol/reference/apis/driver).
 
 ## Methodology
 
@@ -27,9 +27,9 @@
 
 ### Fetching liquidity
 
 Unless you find a perfect CoW you'll need some sort of liquidity to settle an order with. To get your solver started with a good set of base liquidity the driver is able to index and encode a broad range of fundamental AMMs. These include `UniswapV2` and its derivatives, `UniswapV3` as well as several liquidity sources from the `BalancerV2` family. All of these can be individually configured or completely disabled if your solver engine manages liquidity on its own.
 
 ### Postprocessing solutions
 
 The driver expects the solver engine to return a recipe on how to solve a set of orders but the recipe itself could not be submitted on-chain. In the post-processing step the driver applies multiple sanity checks to the solution, encodes it into a transaction that can be executed on-chain and verifies that it actually simulates successfully before it considers the solution valid. All this is done because solvers can get slashed for misbehaving so the reference driver checks all it can to reduce the risk of running a solver as much as possible.
 
@@ -41,22 +41,22 @@
 
 ### Submitting settlements
 
 If a solver provided the best solution the autopilot will tell the driver to actually submit it on-chain. This is not as straight forward as it sounds when the blockchain is congested and liquidity sources are volatile. To protect the solver from losing ETH by submitting solutions that revert the driver continuously verifies that the solution still works while it submits it on-chain. As soon as it would revert the driver cancels the transaction to cut the losses to a minimum.
 
 The driver can be configured to use different submission strategies which it dynamically choses based on the potential of MEV for a settlement. If the settlement does not expose any MEV (e.g. it executes all trades without AMMs) it's safe and most efficient to directly submit to the public mempool. However, if a settlement exposes MEV the driver would submit to an MEV-protected RPC like [MEVBlocker](https://mevblocker.io).
 
 ### Flash Loans
 
 The user is able to create a flash loan order's hint by attaching to the `appData` the specified metadata. The autopilot reads the order and cuts it into a [fair combinatorial batch auction](/cow-protocol/explanation/introduction/fair-combinatorial-auction). Then the driver fetches the `appData` by calling the orderbook with `GET /v1/app_data/<app_data_hash>` for every order and caches them in memory. The driver should include the flash loan information into the batch auction's order before sending it to the solver(s).
 
 #### Flash Loans Encoding
 
 If a solver decides to encode the transaction without the help of the reference driver, the solver must call the `IFlashLoanRouter` contract's [flashLoanAndSettle](/cow-protocol/reference/contracts/periphery/flashloans#flashloanandsettle) function instead of the settlement contract's [settle](/cow-protocol/reference/contracts/core/settlement#settle) function. The solver must provide all necessary flash loan inputs for the settlement, as well as the settle calldata, which will be executed within the same context by the `IFlashLoanRouter` contract. The `IFlashLoanRouter` contract will then request the specified flash loans and, once received, execute the settlement as instructed.
 
 The entry point to the router contract ([IFlashLoanRouter](/cow-protocol/reference/contracts/periphery/flashloans#iflashloanrouter-contract)) is the function `flashLoanAndSettle`. It takes a list of loans with the following entries for each loan:
 
 * The loaned amount and ERC-20 token.
 * The flash-loan lender (e.g., Balancer, Aave, Maker, ...).
 * The *borrower*, which is an adapter contract that makes the specific lender implementation compatible with the router.
 
 Only CoW-Protocol solvers can call this function. It also takes the exact call data for a call to `settle`. The flash-loan router is a solver for CoW Protocol and calls `settle` directly once the flash loans have been obtained.
@@ -81,9 +81,9 @@
 
 As you can see the driver has many responsibilities and discussing all of them in detail would be beyond the scope of this documentation but it's worth mentioning one guiding principle that applies to most of them: make the driver do as *little* work as possible in the hot path when processing an auction.
 
 Because having more time for the solver to compute a solution leads to a more competitive solver every process in the driver should introduce as little latency as possible. Also the blockchain is obviously the single source of truth for a lot of the state in the driver and fetching state from the network can be quite slow.
 
 To reconcile these aspects many internal components listen for new blocks getting appended to the blockchain. Whenever that happens the driver fetches all the relevant information and caches it. When the next auction comes in and the driver actually needs that data it's already up-to-date and ready to be used.
 
 ### Dependencies
 

cow-protocol/explanation/architecture/solver-engine.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Solver Engine"
-description: "The Solver Engine implements the  of the CoW Protocol batch auction. As part of the auction lifecycle, it receives a request from the  containing a potentially pre-processed auction instance and returns information about which order to execute together with instructions on how to achieve the desired execution using on-chain liquidity \"interactions\"."
+description: "The Solver Engine implements core solving logic for CoW Protocol batch auctions — optimizing order execution and on-chain interactions."
 ---
 
 <Note>
@@ -28,7 +28,7 @@
 
 ### Baseline
 
 For each order in the problem set, this solver implements a greedy single-path output maximization algorithm in a weighted graph where vertices correspond to tokens and edges correspond to AMMs providing liquidity between tokens with their output equal to the exchange rate as defined by AMM function given the input amount. Outputs are adjusted to consider the execution cost of updating the AMM when used, using fixed gas amount estimates but taking into account the gas price provided in the auction input. The graph originates over a set of "base tokens" plus the buy and sell token of the order. It aims to find the single path from buy to sell token that maximizes the output for sell orders and minimizes the input for buy orders. It handles partially fillable attempting to first fill the entire order. If the resulting output doesn't satisfy the limit price, it re-attempts filling the order to 50% and keeps halving its amount until a match is found. It does not produce Coincidences of Wants.
 
 ## Flash Loans
 

cow-protocol/explanation/benefits/trade-any-intent.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Trade any intent"
-description: "CoW Protocol allows users to express any type of trade intent on Ethereum and EVM-compatible chains, leveraging  to execute the transactions through the most optimal route."
+description: "CoW Protocol lets users express any trade intent on Ethereum and EVM chains, with solvers finding the most optimal execution route."
 ---
 
 The protocol supports any order logic which includes standard market and limit orders, but also advanced order types such as [TWAP](/cow-protocol/explanation/order-types/twap-orders). Thanks to `ERC-1271`, smart contracts can also submit intents, paving the way for the [Programmatic Order Framework](/cow-protocol/explanation/order-types/programmatic-orders) and contracts like [Milkman](/cow-protocol/explanation/order-types/milkman-orders).

cow-protocol/explanation/fee-model.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Fee Model"
-description: "How fees work in CoW Protocol — from the quote response to on-chain settlement. Everything you need to understand protocol fees, network costs, partner fees, and how to retrieve fee data for accounting."
+description: "How fees work in CoW Protocol — protocol fees, network costs, partner fees, and retrieving fee data from quotes to settlement."
 ---
 
 <Note>
@@ -29,7 +29,7 @@ There is no separate fee transfer, no gas token deduction, and no invoice. If yo
 
 Fees are applied in a specific order, transforming the raw spot price into the final signed amounts:
 
-```
+```text
 Spot Price (beforeAllFees)
   → after Protocol Fee
     → after Network Costs

cow-protocol/explanation/flash-loans/integrators.mdx

@@ -1,11 +1,12 @@
 ---
 title: "How to specify an order with flash loan"
-description: "The flash loan is encoded into the 's metadata as an optional object. This information serves as a hint for the solver, but the solver ultimately can decide for a different approach in order to make the operation more optimal."
+sidebarTitle: "Flash Loan Orders"
+description: "How to encode flash loan parameters in CoW Protocol order metadata so solvers can leverage borrowed liquidity for execution."
 ---
 
 It is important to ensure that the flash loan gas overhead is added to the slippage tolerance when creating the order.
 
-```
+```json
 {  "flashloan": {    "lender": "0x1111111111111111111111111111111111111111",    "borrower": "0x2222222222222222222222222222222222222222",    "token": "0xdAC17F958D2ee523a2206206994597C13D831ec7",    "amount": "1000000"  }}
 ```
 

cow-protocol/explanation/how-it-works/coincidence-of-wants.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Coincidence of Wants"
-description: "CoW (Coincidence of Wants): An economic phenomenon where two parties - each holding the asset that the other needs - exchange assets directly in an equivalent barter."
+description: "Coincidence of Wants (CoW) — how CoW Protocol matches traders who hold each other's desired assets for direct peer-to-peer exchange."
 ---
 
 Thanks to CoW Protocol's batching mechanism, users can make peer-to-peer swaps in cases where they're trading the same assets.