brane-docs

Golden Rule: Documentation that misleads is worse than no documentation.

When to Use

Invoke /brane-docs after completing implementation that affects:

• New public classes, methods, or types
• Changes to existing public API behavior
• New features users need to know about

---

Workflow

1. Identify What Changed

git diff --name-only HEAD~1 | grep '\.java$'

Focus on public API changes in:

• brane-core/src/main/java/sh/brane/core/...
• brane-rpc/src/main/java/sh/brane/rpc/...
• brane-contract/src/main/java/sh/brane/contract/...

2. Update Javadoc

Update source files directly. Required elements:

• Summary sentence (imperative: "Sends", "Creates", "Binds")
• @param for every parameter (state nullability)
• @return for non-void (state empty/null semantics)
• @throws for all exceptions (state condition)
• Working {@code} examples for public entry points

3. Update Website Docs

Docs location: website/docs/pages/docs/

website/docs/pages/docs/
├── quickstart.mdx
├── architecture.mdx
├── performance.mdx
├── reader/           # Brane.Reader methods
│   ├── api.mdx
│   ├── simulate.mdx
│   └── subscriptions.mdx
├── signer/           # Brane.Signer methods
│   ├── api.mdx
│   ├── signers.mdx
│   ├── hd-wallets.mdx
│   ├── eip712.mdx
│   ├── blobs.mdx
│   └── custom-signers.mdx
├── contracts/
│   ├── bindings.mdx
│   ├── interaction.mdx
│   └── multicall.mdx
├── testing/          # Brane.Tester methods
│   ├── overview.mdx
│   ├── setup.mdx
│   ├── state.mdx
│   ├── impersonation.mdx
│   ├── mining-time.mdx
│   └── accounts.mdx
├── providers/
│   ├── http.mdx
│   └── websocket.mdx
├── utilities/
│   ├── types.mdx
│   ├── abi.mdx
│   ├── errors.mdx
│   ├── threading.mdx
│   └── metrics.mdx
└── chains/
    └── profiles.mdx

4. Which Page to Update?

| Feature Type | Update These Pages | |--------------|-------------------| | New Reader method | reader/api.mdx | | New Signer method | signer/api.mdx | | New type (Address, Wei, etc.) | utilities/types.mdx | | Contract feature | contracts/bindings.mdx or contracts/interaction.mdx | | Provider changes | providers/http.mdx or providers/websocket.mdx | | Error handling | utilities/errors.mdx | | Testing feature | testing/ appropriate file | | New major feature | May need new page |

5. Evaluate CLAUDE.md Updates

After updating Javadoc and website docs, decide whether CLAUDE.md files need updates.

Update CLAUDE.md when:

• New public class added that users will interact with → Add to "Key Classes" section
• New usage pattern that differs from existing examples → Add to "Patterns" section
• Discovered a gotcha or pitfall → Add to "Gotchas" section
• Significant behavioral change that affects documented patterns

Skip CLAUDE.md when:

• Minor method additions that follow existing patterns
• Internal implementation changes
• Bug fixes that don't affect documented behavior
• Changes already well-represented by existing documentation

Which CLAUDE.md to update:

| Change Location | CLAUDE.md File | |-----------------|----------------| | brane-primitives | brane-primitives/CLAUDE.md | | brane-core types, ABI, crypto | brane-core/CLAUDE.md | | brane-kzg | brane-kzg/CLAUDE.md | | brane-rpc clients, providers | brane-rpc/CLAUDE.md | | brane-contract | brane-contract/CLAUDE.md | | Cross-cutting patterns | Root CLAUDE.md |

When updating, follow existing structure:

• Key Classes: Brief description, key methods/purpose
• Patterns: Working code examples with realistic scenarios
• Gotchas: Specific class/method, clear issue, resolution

---

Accuracy Checklist

Before finishing, verify:

Javadoc:

• [ ] Summary matches actual behavior (re-read implementation)
• [ ] All parameters documented with correct types
• [ ] All thrown exceptions listed
• [ ] Example code actually works

Website Docs:

• [ ] Code examples include imports
• [ ] Method signatures match actual API
• [ ] No stale examples from previous versions

Cross-Reference:

• [ ] Javadoc and website docs say the same thing
• [ ] No contradictions between sources

CLAUDE.md (if applicable):

• [ ] Key classes table includes new public classes
• [ ] Patterns section has working examples for new patterns
• [ ] Gotchas are specific and actionable
• [ ] Module-level and root CLAUDE.md are consistent