Conversation
🔐 Commit Signature Verification✅ All 9 commit(s) passed verification
Summary
Required key type: Last verified: 2026-04-14 09:10 UTC |
Greptile SummaryThis PR restructures the top navigation to introduce Vault Users, Vault Builders, and Vault Operators sections for the TBV launch, while consolidating existing staker/developer/operator content under a new Overview sidebar. Five substantive Vault Users pages are added covering the full vault lifecycle (creation, redemption, protocol actors, and fees); the Vault Builders and Vault Operators sections are placeholder stubs.
Confidence Score: 4/5Safe to merge after fixing the stage-count typo in vault-creation.mdx; remaining findings are non-blocking P2s. One P1 factual error exists (nine vs. seven stages) that should be corrected before publishing — it will mislead users reading the guide. All other findings are P2 quality/clarity improvements that don't block merge. docs/vault-users/vault-creation.mdx (stage count mismatch on line 27) Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Top Navigation] --> B[Overview]
A --> C[Vault Users]
A --> D[Vault Builders]
A --> E[Vault Operators]
A --> F[API]
B --> B1[guides sidebar]
B1 --> B2[Bitcoin Staking category]
B1 --> B3[Babylon Genesis category]
B2 --> B2a[stakers/]
B2 --> B2b[developers/bitcoin_staking/]
B3 --> B3a[developers/babylon_genesis_chain/]
B3 --> B3b[operators/]
C --> C1[vault-users sidebar]
C1 --> C2[Overview]
C1 --> C3[Vault Creation - 7 stages]
C1 --> C4[Vault Redemption]
C1 --> C5[Protocol Actors]
C1 --> C6[Fees]
D --> D1[Placeholder - Coming soon]
E --> E1[Placeholder - Coming soon]
Reviews (1): Last reviewed commit: "feat: restructure docs for TBV launch — ..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ## Overview of the Peg-In Flow | ||
|
|
||
| The peg-in process has nine stages: | ||
|
|
There was a problem hiding this comment.
The overview text says "The peg-in process has nine stages:" but the document only defines and describes 7 stages (Stage 1 through Stage 7). Readers following the guide will reach Stage 7 expecting two more stages and find none.
| The peg-in process has seven stages: |
| Aave-specific lending fees (interest rates, liquidation bonuses), see the | ||
| Aave v4 Fees page. | ||
|
|
There was a problem hiding this comment.
The text "see the Aave v4 Fees page" references a page that doesn't appear to exist in the vault-users section (and no relative link is provided). Readers have no way to navigate there. Either add a link once the page exists, or remove the reference until it's ready.
| 1. **Claim Transaction.** The authorized redeemer (vault provider or liquidator) | ||
| broadcasts a claim transaction on Bitcoin, spending from the vault's Taproot | ||
| output. This transaction includes a commitment to the ZK proof. | ||
|
|
||
| 2. **Payout (Optimistic Path).** If no challenge is raised within the timelock | ||
| period, the payout transaction is broadcast, releasing the BTC to the | ||
| depositor's Bitcoin address. This is the happy path — in a properly functioning | ||
| system, most redemptions follow this path. | ||
|
|
There was a problem hiding this comment.
The "Bitcoin Transaction Costs" section (line 166) lists three transactions for the normal redemption path: claim, proof, and payout. However, the numbered "Claim Process" steps above only mention (1) Claim Transaction and (2) Payout (Optimistic Path) — the proof transaction is never described in the flow. If a distinct proof transaction exists on Bitcoin, it should be added as a step here so users understand the full sequence.
| "type": "doc", | ||
| "id": "vault-builders/vault-builders" | ||
| } | ||
| } No newline at end of file |
There was a problem hiding this comment.
All three _category_.json files (vault-builders, vault-operators, vault-users) are missing a trailing newline. Many linters and editors expect files to end with a newline. Add a newline after the closing } in each file.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 553e4a48c6
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| { type: 'autogenerated', dirName: 'stakers' }, | ||
| { type: 'autogenerated', dirName: 'developers/bitcoin_staking' }, | ||
| ], |
There was a problem hiding this comment.
Adding stakers (and other legacy sections) under guides while also keeping standalone stakers/developers/operators sidebars duplicates the same doc IDs across sidebars. In Docusaurus, duplicated doc items are not valid unless they are added as ref, so this sidebar layout can fail docs loading/build when sidebar metadata is generated. Use ref links for cross-linking or keep each doc tree associated with only one sidebar.
Useful? React with 👍 / 👎.
…cumentation Restructures the docs site navigation to add Trustless Bitcoin Vault sections: - New top nav: Overview, Vault Users, Vault Builders, Vault Operators - Vault Users section with 5 pages: Overview, Vault Creation, Vault Redemption, Protocol Actors, Fees - Vault Builders and Vault Operators as placeholders for future content - Overview sidebar now includes Bitcoin Staking and Babylon Genesis sub-sections consolidating staker, developer, and operator content - All existing content preserved at original URLs for backward compatibility Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Remove networks sidebar icon CSS rules and className - Fix sidebar to prevent bitcoin_staking.mdx from appearing as top-level item - Nest operators and developers content under Babylon Genesis category - Fix Babylon Genesis child ordering: Architecture, BABY Tokens, Governance, Networks, then Specifications last - Add Mermaid architecture diagram to vault-users overview - Add Mermaid sequence diagram to vault-creation (7-stage peg-in flow) - Add Mermaid sequence diagram to vault-redemption (peg-out + challenge flow) - Add Mermaid actor relationship diagram to protocol-actors - Add Mermaid fee flow diagram to fees Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Bitcoin Staking was floating as a root-level sidebar item outside the Overview category. Now correctly nested inside Overview between Trustless Bitcoin Vault and Babylon Genesis, matching the intended structure. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The autogenerated directives were producing flat items without category headers. Wrapping them in explicit category blocks restores the Research, Security, and Support groupings in the sidebar. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…s, fix governance nesting - Add displayed_sidebar: guides to all .mdx files in stakers/, developers/bitcoin_staking/, developers/babylon_genesis_chain/, operators/, and developers top-level pages so they show the Overview sidebar instead of old standalone sidebars - Remove stakers/developers/operators standalone sidebar entries from sidebars-default.js - Add link properties to all _category_.json files to eliminate duplicate label/doc pairs - Fix governance.mdx sidebar_position from 4.1 to 0 - Rename operators category label from "BabylonOperators" to "Node Operators" - Add redirects for retired /stakers/, /developers/, /operators/ top nav pages Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Developer content (chain info, explorers, dApps, wallet setup) now grouped under "Build on Genesis" collapsible category. Operator content (Babylon Node, Validators, Finality Providers, Covenant Emulator) now grouped under "Run a Node" collapsible category. Reduces sidebar length significantly. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…erator placeholders Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…rnance, move vigilantes - Remove mainnet.mdx and testnet.mdx network pages (redundant with developers/bitcoin_staking/networks) - Move Vigilantes under BTC Staking Program in Architecture - Flatten governance proposal subfolders (reviewing_proposals, drafting_proposals, submit_proposals) directly into governance/ - Add redirects for all moved/removed URLs - Significantly reduces sidebar depth and clutter Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Codex review found and fixed: - Legacy governance redirects pointing at non-existent routes - Babylon Genesis network redirects pointing at removed pages - CometBFT navbar item using relative path - Internal implementation details exposed in public docs (SP1 CUDA, secure channels, internal state labels, ChallengeAssert terminology) - Unexplained jargon (fairness payment token, Core Spoke) simplified - Vault Builders placeholder referenced private APIs — generalized - Vault Operators placeholder locked in specific stack choices — generalized - Removed dead diagram placeholder comments - Rewrote sections to be user-facing rather than internal-ops style Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
web3jenks
force-pushed
the
feat/tbv-docs-restructure
branch
from
31e2254 to
867fabc
Compare
1 participant
Summary
Test plan
npm run build)/vault-users/and confirm all 5 pages render correctly/stakers/,/developers/,/operators/) still work/vault-builders/and/vault-operators/placeholder pages render🤖 Generated with Claude Code