Add troubleshooting guide for cache-clear recovery

[Miracle656]

Background

When a user clears their browser cache, the Veil wallet enters a degraded state: the contract address is gone from localStorage but the passkey and on-chain funds still exist. The recovery flow is already implemented, but there's no user-facing or developer-facing documentation explaining it.

What to build

A troubleshooting guide in the Nextra docs site covering the cache-clear recovery scenario from both a user and developer perspective.

Key files

• frontend/docs/pages/troubleshooting.mdx — create this file
• frontend/wallet/app/lock/page.tsx — the recovery UI entry point
• frontend/wallet/lib/deriveFeePayer.ts — the deterministic derivation logic

Suggested execution

git checkout -b docs/cache-clear-troubleshooting-guide

1. Create frontend/docs/pages/troubleshooting.mdx
2. Add a section: "What happens when I clear my browser cache?"
3. Explain: passkey stays on device, contract still on-chain, fee-payer keypair is re-derived from credential ID
4. Add step-by-step recovery instructions (tap "Set up fee-payer" on dashboard)
5. Add a developer section explaining deriveFeePayerKeypair(credentialId)
6. Link from the docs navigation (theme.config.tsx or sidebar)

Example commit message:
docs: add troubleshooting guide for cache-clear wallet recovery

Acceptance criteria

• Guide covers user-facing recovery steps
• Guide covers developer-facing explanation of deriveFeePayer.ts
• Linked from docs navigation
• Renders correctly in the Nextra docs site locally

---

Drips Wave · Complexity: Trivial · 100 points
Comment below to request assignment. PR must include Closes #[this issue].

[samad13]

@samad13 has applied to work on this issue as part of the Stellar Wave Program's 4th wave.

hi, let me work on this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @samad13 to this issue.

[drips-wave]

Congratulations, @samad13! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on April 29, 2026.

🧑‍💻 @samad13: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊