Hrom131 · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -23,9 +23,6 @@ jobs:
   build:
     name: Build
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      actions: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4

diff --git a/docs/docs/borrower/cancel-offer.md b/docs/docs/borrower/cancel-offer.md
@@ -1,19 +1,15 @@
+---
+description: Take the collateral back from an offer that nobody has funded, burning both role tokens.
+---
+
 # Cancel an offer
 
 The borrower can cancel an offer while it is still pending and take the collateral back. Funding is not required, and the deadline does not close this action. [Actions](../protocol/actions.md) covers what stays possible after the deadline block.
 
 The transaction spends the pending [lending](../contracts/lending.md) output, the lender NFT held by [script auth](../contracts/script-auth.md), and the borrower NFT from the wallet. Both tokens are burned. The collateral is paid to the borrower. tL-BTC inputs from the wallet pay the network fee, and the remainder comes back.
 
-<details>
-<summary>Transaction structure</summary>
+<TxDiagram>
 
 ![Offer cancellation transaction](../schemas/borrower/cancel-offer.svg)
 
-<details>
-<summary>Legend</summary>
-
-![Transaction diagram legend](../schemas/schemas-legend.svg)
-
-</details>
-
-</details>
+</TxDiagram>
diff --git a/docs/docs/borrower/claim-principal.md b/docs/docs/borrower/claim-principal.md
@@ -1,20 +1,15 @@
+---
+description: Move the principal a lender paid from its asset auth output into the borrower's wallet.
+---
+
 # Claim the principal
 
 When a lender funds the offer, the principal is paid into an output the borrower does not hold yet. It stays locked to the borrower NFT, under [asset auth](../contracts/asset-auth.md), until the borrower claims it. The claim spends that output and the borrower NFT together, pays the principal to the borrower's wallet, and returns the borrower NFT. The token is not burned, because the borrower still needs it to [repay](./repay.md).
 
 The offer has to be active, or already liquidated if the principal was never claimed. Until the claim is done, the app offers no repayment action. tL-BTC inputs from the wallet pay the network fee, and the remainder comes back.
 
-<details>
-<summary>Transaction structure</summary>
+<TxDiagram>
 
 ![Claim principal transaction](../schemas/borrower/claim-principal.svg)
 
-<details>
-<summary>Legend</summary>
-
-![Transaction diagram legend](../schemas/schemas-legend.svg)
-
-</details>
-
-
-</details>
+</TxDiagram>
diff --git a/docs/docs/borrower/create-account.md b/docs/docs/borrower/create-account.md
@@ -1,3 +1,7 @@
+---
+description: Set up the issuance factory a borrower needs before publishing a first offer.
+---
+
 # Create an account
 
 A borrower creates an account before publishing an offer. The account is an [issuance factory](../contracts/issuance-factory.md): one output that can issue the assets later offers need, and a token of the same asset that authorizes it.
@@ -6,16 +10,8 @@ The app creates one account for a wallet. The transaction spends a confirmed tL-
 
 Whatever tL-BTC is not spent on the network fee comes back to the wallet. The fee input has to be larger than the reserve the app keeps for that fee.
 
-<details>
-<summary>Transaction structure</summary>
+<TxDiagram>
 
 ![IssuanceFactory creation transaction](../schemas/borrower/create-account.svg)
 
-<details>
-<summary>Legend</summary>
-
-![Transaction diagram legend](../schemas/schemas-legend.svg)
-
-</details>
-
-</details>
+</TxDiagram>
diff --git a/docs/docs/borrower/create-offer.md b/docs/docs/borrower/create-offer.md
@@ -1,3 +1,7 @@
+---
+description: "Publish an offer: lock the collateral and fix the principal, fee, and deadline in a new lending output."
+---
+
 # Create an offer
 
 The borrower publishes an offer and locks the collateral that backs it. The collateral stays in the [lending](../contracts/lending.md) output until the offer is repaid, cancelled, or liquidated. The principal is paid out only after a lender funds the offer.
@@ -8,16 +12,8 @@ The transaction spends the account's authorization token and the factory output,
 
 The collateral inputs are tL-BTC from the wallet, and they also cover the network fee. Anything above the locked collateral comes back to the wallet.
 
-<details>
-<summary>Transaction structure</summary>
+<TxDiagram>
 
 ![Offer creation transaction](../schemas/borrower/create-offer.svg)
 
-<details>
-<summary>Legend</summary>
-
-![Transaction diagram legend](../schemas/schemas-legend.svg)
-
-</details>
-
-</details>
+</TxDiagram>
diff --git a/docs/docs/borrower/repay.md b/docs/docs/borrower/repay.md
@@ -1,37 +1,25 @@
+---
+description: Pay back the principal and the fee, and release the collateral locked in the offer.
+---
+
 # Repay
 
 Once the loan is active and the principal has been [claimed](./claim-principal.md), the borrower pays the debt down with the principal asset. The fee is settled before the principal. Of the fee paid in a transaction, ten percent goes to the protocol fee vault and the rest goes to the lender's vault, together with any principal in that same payment. [Offer parameters](../protocol/offer-parameters.md) defines the fee, and [asset auth vault](../contracts/asset-auth-vault.md) is the output that holds each share.
 
 A partial repayment pays less than the remaining debt. It spends the borrower NFT and the active [lending](../contracts/lending.md) output. The borrower NFT comes back, and the offer stays active. A share of the collateral, in proportion to the payment against the debt still owed, is paid back to the borrower, and the rest stays locked in the offer. The two vaults are left active. The first payment creates them. A later one spends the vaults already on chain and recreates them.
 
-<details>
-<summary>Transaction structure</summary>
+<TxDiagram>
 
 ![Partial repayment transaction](../schemas/borrower/partial-repay.svg)
 
-<details>
-<summary>Legend</summary>
-
-![Transaction diagram legend](../schemas/schemas-legend.svg)
-
-</details>
-
-</details>
+</TxDiagram>
 
 A full repayment pays whatever debt is left. It spends the same borrower NFT and the active offer. The borrower NFT is burned, and the collateral still in the offer is paid back to the borrower. The lender's vault is finalized. The protocol fee vault is finalized once this payment covers the rest of its share. When the whole debt is paid in a single transaction, both vaults are created already finalized. That is the transaction the app's repay action builds. Any principal above the debt, and the tL-BTC used for the network fee, comes back to the wallet.
 
-<details>
-<summary>Transaction structure</summary>
+<TxDiagram>
 
 ![Full repayment transaction](../schemas/borrower/final-repay.svg)
 
-<details>
-<summary>Legend</summary>
-
-![Transaction diagram legend](../schemas/schemas-legend.svg)
-
-</details>
-
-</details>
+</TxDiagram>
 
 After the deadline block, repayment and liquidation are both valid, as [Actions](../protocol/actions.md) describes.
diff --git a/docs/docs/lender/claim-repayment.md b/docs/docs/lender/claim-repayment.md
@@ -1,35 +1,23 @@
+---
+description: Withdraw the lender's share of the repayment from the asset auth vault.
+---
+
 # Claim repayment
 
 The lender's share of each [repayment](../borrower/repay.md) sits in an [asset auth vault](../contracts/asset-auth-vault.md): the lender's part of the fee first, then the principal. The protocol fee stays in its own vault.
 
 A partial claim withdraws less than the balance of an active vault. It spends that vault and the lender NFT. The NFT comes back, and the vault stays active with whatever remains. The withdrawn amount is paid to the lender. The first repayment creates the vault. A later repayment spends it and recreates it, and a partial claim is what takes funds out in between.
 
-<details>
-<summary>Transaction structure</summary>
+<TxDiagram>
 
 ![Partial repayment claim](../schemas/lender/partial-claim.svg)
 
-<details>
-<summary>Legend</summary>
-
-![Transaction diagram legend](../schemas/schemas-legend.svg)
-
-</details>
-
-</details>
+</TxDiagram>
 
 A full claim withdraws the whole balance of a finalized vault. It spends that vault and the same lender NFT. The NFT is burned, and the balance is paid to the lender. That is the transaction the app's claim action builds, once the offer is [repaid](../protocol/actions.md). tL-BTC inputs from the wallet pay the network fee, and the remainder comes back.
 
-<details>
-<summary>Transaction structure</summary>
+<TxDiagram>
 
 ![Full repayment claim](../schemas/lender/final-claim.svg)
 
-<details>
-<summary>Legend</summary>
-
-![Transaction diagram legend](../schemas/schemas-legend.svg)
-
-</details>
-
-</details>
+</TxDiagram>
diff --git a/docs/docs/lender/fund-offer.md b/docs/docs/lender/fund-offer.md
@@ -1,3 +1,7 @@
+---
+description: Pay the principal into a pending offer, turning it into an active loan and taking the lender NFT.
+---
+
 # Fund an offer
 
 A lender funds a pending offer by paying the principal. The offer becomes an active loan. The principal is paid into an [asset auth](../contracts/asset-auth.md) output locked to the borrower NFT, and the borrower [claims it](../borrower/claim-principal.md) from there. The collateral stays in the [lending](../contracts/lending.md) output at the same amount, now marked active.
@@ -6,16 +10,8 @@ The transaction spends the pending offer and the lender NFT held by [script auth
 
 The contract accepts this at any block height. The app hides the action once the deadline block has passed. [Actions](../protocol/actions.md) describes what that leaves open.
 
-<details>
-<summary>Transaction structure</summary>
+<TxDiagram>
 
 ![Offer funding transaction](../schemas/lender/accept-offer.svg)
 
-<details>
-<summary>Legend</summary>
-
-![Transaction diagram legend](../schemas/schemas-legend.svg)
-
-</details>
-
-</details>
+</TxDiagram>
diff --git a/docs/docs/lender/liquidate.md b/docs/docs/lender/liquidate.md
@@ -1,3 +1,7 @@
+---
+description: Claim the collateral of an active loan that was not repaid by its deadline.
+---
+
 # Liquidate
 
 Once an active loan reaches its deadline block, the lender can take the collateral. This is the only lending path that reads the deadline. Repayment stays valid at the same moment, and [Actions](../protocol/actions.md) describes how the first confirmed transaction wins.
@@ -6,16 +10,8 @@ The transaction spends the active [lending](../contracts/lending.md) output and
 
 The app offers this action on an active loan after the deadline block.
 
-<details>
-<summary>Transaction structure</summary>
+<TxDiagram>
 
 ![Liquidation transaction](../schemas/lender/liquidate-offer.svg)
 
-<details>
-<summary>Legend</summary>
-
-![Transaction diagram legend](../schemas/schemas-legend.svg)
-
-</details>
-
-</details>
+</TxDiagram>
diff --git a/docs/docs/lender/review-offer.md b/docs/docs/lender/review-offer.md
@@ -1,3 +1,7 @@
+---
+description: What a lender reads in an offer before funding it. Reviewing moves no funds.
+---
+
 # Review an offer
 
 A lender reads an open offer before sending principal: collateral, loan amount, fee, and term. The app also shows the loan-to-value. Those are defined in [Offer parameters](../protocol/offer-parameters.md).

diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -47,6 +47,17 @@ const config: Config = {
     ],
   ],
 
+  themes: [
+    [
+      '@easyops-cn/docusaurus-search-local',
+      {
+        hashed: true,
+        indexBlog: false,
+        highlightSearchTermsOnTargetPage: true,
+      },
+    ],
+  ],
+
   themeConfig: {
     colorMode: {
       defaultMode: 'light',

diff --git a/docs/package.json b/docs/package.json
@@ -19,6 +19,7 @@
     "@docusaurus/core": "3.10.2",
     "@docusaurus/faster": "3.10.2",
     "@docusaurus/preset-classic": "3.10.2",
+    "@easyops-cn/docusaurus-search-local": "0.55.3",
     "@fontsource-variable/inter": "5.2.8",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",