# Brane Docs

> Update Javadoc and public documentation after implementing features. Use when finishing implementation to ensure both internal (Javadoc) and external (website docs) documentation are accurate and complete. Use when this capability is needed.

- Skill: `tomevault-io/brane-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/brane-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/brane-docs/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/brane-docs

---


# Brane Documentation (Post-Implementation)

**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

```bash
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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/noise-xyz) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->