Add TBV agent runbook

docs/trustless-bitcoin-vault/reference/agent-runbook.mdx

@@ -0,0 +1,140 @@
+---
+title: Agent runbook
+sidebar_position: 3
+---
+
+# Agent runbook
+
+This page is for AI and automation agents working with the Babylon Trustless Bitcoin Vault (TBV) public Testnet. It summarizes the public workflow, safety boundaries, and evidence expectations for agents that operate either through a browser with wallets or through BabyTester CLI UATs.
+
+Use this only for public Testnet flows on Bitcoin signet and Ethereum Sepolia. Do not use it for mainnet funds, wallet creation, seed handling, faucet account management, or private deployment operations.
+
+## Safety boundaries
+
+Agents must:
+
+* Use only `https://btc-vaults.testnet.babylonlabs.io/` for browser testing.
+* Treat wallet prompts as real user-profile actions, even when assets are testnet-only.
+* Stop before confirming if the wallet domain, network, contract, amount, or action differs from the expected TBV Testnet flow.
+* Never request, store, repeat, screenshot intentionally, or commit seed phrases, private keys, passwords, wallet unlock material, cookies, or recovery artifact contents.
+* Record recovery artifact file paths only. Do not copy artifact contents into notes, chat logs, repos, or tickets.
+
+## Public Testnet target
+
+Use the values from [Setup](../testnet-info/setup.mdx) as canonical. At a high level:
+
+| Item | Value |
+| --- | --- |
+| Test app | `https://btc-vaults.testnet.babylonlabs.io/` |
+| Bitcoin network | signet |
+| Ethereum network | Sepolia, chain ID `11155111` |
+| Primary faucet | `https://tbv-faucet.testnet.babylonlabs.io/` |
+| Bitcoin explorer | `https://mempool.space/signet` |
+| Ethereum explorer | `https://sepolia.etherscan.io/` |
+
+The Bitcoin wallet must use Taproot (P2TR) before connecting. UniSat on signet is the documented browser-wallet path. Ethereum wallet actions occur on Sepolia.
+
+## Browser and computer-use agents
+
+Browser agents should use the user's real Chrome profile when wallet extensions are required. Clean automation profiles generally cannot operate installed UniSat or MetaMask sessions, and extension popups often require desktop-control tooling.
+
+Before wallet-affecting actions, confirm:
+
+* deposit amount
+* borrow amount and asset
+* full or partial repay intent
+* fresh run or resume
+* whether recovery artifacts should be downloaded before activation
+
+Do not invent default amounts for wallet actions. If funded test assets are missing, pause and ask the user to fund through the public Testnet faucet process.
+
+### Expected browser lifecycle
+
+1. Open the TBV Testnet app.
+2. Inspect current app state before starting or resuming.
+3. Connect the Bitcoin wallet on signet using Taproot.
+4. Connect the Ethereum wallet on Sepolia.
+5. Create a vault with the confirmed deposit amount.
+6. Complete UniSat and Ethereum wallet signing steps.
+7. Wait for Bitcoin confirmations and provider-side verification.
+8. Complete payout and recovery signing checkpoints when prompted.
+9. Download recovery artifacts if requested.
+10. Activate the vault.
+11. Borrow the confirmed asset and amount.
+12. Repay the intended amount, using max/full only when requested.
+13. Select the relevant vault row if withdraw controls are disabled.
+14. Initiate withdraw and record the final app-side state.
+
+Report app-side withdraw initiation separately from BTC-side settlement. `Withdraw Initiated`, `Pending Withdraw`, and final Bitcoin payout are different states.
+
+### Resume guidance
+
+Inspect before acting. A resumed peg-in can be safer than starting over.
+
+* If a pending deposit shows a signing-required state, continue with payout or recovery signing.
+* If the app shows provider verification or ACK collection, wait and refresh before retrying actions.
+* Ready to activate is not active collateral; activation still requires an Ethereum transaction.
+* If debt is repaid but withdraw is unavailable, check whether the target vault row must be selected.
+
+## BabyTester CLI agents
+
+BabyTester is the UAT executor for TBV lifecycle validation. Use only public-facing commands and behavior from BabyTester when preparing agent instructions. It supports ad-hoc CLI runs, scheduled server mode, SQLite persistence, read-only HTTP APIs, and a dashboard showing UAT status, runs, step timelines, evidence, and logs.
+
+Public CLI commands:
+
+```bash
+pnpm dev -- list
+pnpm dev -- test pegin --verbose
+pnpm dev -- test --all
+pnpm dev -- test --all --parallel --concurrency 2
+pnpm dev -- serve --config environments/devnet.toml --verbose
+pnpm dev -- serve --no-scheduler --verbose
+```
+
+Use environment files only by named reference. Do not publish or paste private key variables, RPC credentials, deployment secrets, or private `.env` content.
+
+BabyTester stores run results and logs locally and writes JSON/Markdown reports under `results/`. Its API listens on `http://127.0.0.1:3100` by default and exposes public run-inspection surfaces such as health, UAT list, run list, run detail, and logs.
+
+### Public UAT surfaces
+
+BabyTester exposes UAT modules for:
+
+* `pegin`: end-to-end vault creation, WOTS generation, Ethereum registration, Bitcoin transaction submission, presigning, verification, and activation.
+* `batch-pegin`: multi-vault peg-in flow.
+* `lending-flow`: active collateral, borrow, interest accrual, repay, max repay, and over-repay refund behavior.
+* `pegout-happy-path`: repay debt, withdraw collateral, redeem vaults, and monitor peg-out.
+* peg-out challenge paths: wrongly challenged and challenger-wins scenarios.
+* liquidation paths: Vault Swap liquidation, fairness checks, direct redemption, and BTC payout monitoring.
+* `vault-reordering`: position vault-order updates and on-chain ordering verification.
+* `cap-policy`: cap read paths, cap lowering, activation effects, and auto-redeem behavior.
+* pause/freeze state machines for protocol-level and application-level controls.
+* AML early-reject behavior.
+
+## Evidence expectations
+
+For browser runs, create a dated evidence folder and capture screenshots before critical wallet approvals, after success modals, before activation, after activation, after repay, and on the final dashboard state.
+
+For CLI runs, preserve the BabyTester run ID, command, selected UAT name, environment name, report path, and relevant transaction hashes.
+
+Final reports should state whether these passed:
+
+* deposit activation
+* borrow
+* repay, including full or partial
+* withdraw initiation, if attempted
+
+Also include:
+
+* evidence folder or report path
+* recovery artifact path, if downloaded
+* any wallet/app divergence from the expected path
+* whether BTC-side settlement is still pending
+
+## Related pages
+
+* [Setup](../testnet-info/setup.mdx)
+* [Quickstart](../use-for-lending/quickstart.mdx)
+* [Create a vault](../use-for-lending/create-a-vault.mdx)
+* [Borrow & repay](../use-for-lending/borrow-and-repay.mdx)
+* [Withdraw & redeem](../use-for-lending/withdraw-and-redeem.mdx)
+* [Liquidation risk](../use-for-lending/liquidation-risk.mdx)

sidebars-default.js

@@ -314,6 +314,7 @@ const sidebars = {
       items: [
         'trustless-bitcoin-vault/reference/glossary',
         'trustless-bitcoin-vault/reference/community-and-support',
+        'trustless-bitcoin-vault/reference/agent-runbook',
       ],
     },
     ...trustlessBitcoinVaultSecuritySection,

static/robots.txt

@@ -2,5 +2,9 @@ User-agent: *
 Allow: /
 Allow: /llms.txt
 Allow: /llms-ctx.txt
+Allow: /llms-full.txt
+Allow: /llms-tbv.txt
+Allow: /llms-tbv-ctx.txt
+Allow: /llms-tbv-full.txt
 
 Sitemap: https://docs.babylonlabs.io/sitemap.xml