bitspire/.claude/skills/docs.md

/docs - Documentation Agent

Purpose

Keep documentation synchronized with code, generate API docs, and maintain architecture diagrams.

Invocation

/docs [command] [target]

Commands:

• sync - Sync docs with code changes
• api - Generate API documentation
• diagram - Update architecture diagrams
• readme - Update package README
• changelog - Generate changelog entry

Documentation Structure

docs/
├── architecture/
│   ├── overview.md          # High-level architecture
│   ├── nostr-protocol.md    # Nostr integration details
│   ├── lightning-flow.md    # Payment flows
│   └── hardware-hal.md      # HAL documentation
├── api/
│   ├── nostr-client.md      # @bitSpire/nostr-client API
│   ├── lnbits.md            # @bitSpire/lnbits API (kind-21000 RPC surface)
│   ├── clink.md             # @bitSpire/clink API (dormant on dev; 21003 management still wired)
│   ├── state-machine.md     # @bitSpire/state-machine API
│   └── hal.md               # @bitSpire/hal API
├── guides/
│   ├── development.md       # Dev setup guide
│   ├── hardware-testing.md  # Testing with real hardware
│   └── deployment.md        # NixOS deployment guide
└── adrs/                    # Architecture Decision Records
    ├── 001-nostr-backbone.md
    ├── 002-clink-over-bolt12.md
    └── ...

Sync Tasks

Code → Docs Sync

When code changes:

1. Detect modified files
2. Check if related docs exist
3. Flag outdated documentation
4. Suggest updates

Doc → Code Validation

Ensure docs reference actual code:

• Function names match
• Parameter types correct
• Return types accurate
• Examples compile/run

API Documentation

TypeScript Packages

Generate from TSDoc comments:

/**
 * Create a CLINK offer for receiving payments
 *
 * @param identity - Machine identity (nsec/npub)
 * @param relays - Relay URLs to include in offer
 * @param priceType - 'fixed' | 'variable' | 'spontaneous'
 * @param amount - Amount in sats (required for fixed)
 * @returns Encoded noffer string
 *
 * @example
 * ```typescript
 * const offer = createOffer(identity, ['wss://relay.example'], 'fixed', 10000)
 * // Returns: noffer1...
 * ```
 */
export function createOffer(...): string

Rust Crate (HAL)

Generate from rustdoc comments:

/// Connect to a bill validator
///
/// # Arguments
/// * `port` - Serial port path (e.g., "/dev/ttyUSB0")
///
/// # Errors
/// Returns `ValidatorError::ConnectionFailed` if port unavailable
///
/// # Example
/// ```
/// let mut validator = Id003Validator::new("/dev/ttyUSB0", "USD");
/// validator.connect().await?;
/// ```
pub async fn connect(&mut self) -> Result<(), ValidatorError>

Diagram Updates

Mermaid Diagrams

Keep architecture diagrams current:

sequenceDiagram
    participant U as Customer Wallet
    participant A as ATM
    participant R as Relay (LNbits-bundled nostrrelay)
    participant L as LNbits (nostr-transport)

    Note over A,L: cash-out flow (customer pays ATM, gets cash)
    A->>R: kind-21000 RPC "create_invoice"
    R->>L: forward to LNbits server pubkey
    L->>R: kind-21000 ACK with BOLT11 invoice
    R->>A: forward ACK
    A->>U: display BOLT11 QR
    A->>R: kind-21000 "subscribe_payments" by payment_hash
    R->>L: forward
    L->>R: kind-21000 ACK with subscription_id
    R->>A: forward
    U->>L: pay BOLT11 via Lightning Network
    L->>R: kind-21000 push (settlement) tagged subscription_id
    R->>A: forward
    A->>A: dispense cash

Auto-update triggers

• New event kinds added → Update protocol diagram
• State machine changes → Update flow diagram
• New hardware driver → Update HAL diagram

Changelog Generation

Format (Keep a Changelog)

## [Unreleased]

### Added
- CLINK offer support for cash-in flow
- Puloon dispenser driver

### Changed
- Upgraded to XState v5 actor model

### Fixed
- Race condition in bill acceptance

### Security
- Added NIP-44 encryption for receipts

Auto-detection

From git commits since last release:

• feat: → Added
• fix: → Fixed
• refactor: → Changed
• security: → Security
• BREAKING: → Breaking Changes

Output Format

Sync Report

## Documentation Sync: [target]

### Outdated Docs
| Doc | Code Change | Status |
|-----|-------------|--------|
| api/clink.md | createOffer params | ⚠️ Outdated |
| guides/development.md | New env var | ⚠️ Missing |

### Suggested Updates
1. `api/clink.md:45` - Add `timeout` parameter to createOffer
2. `guides/development.md` - Add VITE_BITSPIRE_CASSETTES env var

### Missing Documentation
- `packages/cashu/src/wallet.ts` - No API docs

Generated Docs

## Generated: [file]

### API Reference

#### `createOffer(identity, relays, priceType, amount?)`

Creates a CLINK offer for receiving Lightning payments.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| identity | MachineIdentity | Machine nsec/npub |
| relays | string[] | Relay URLs |
| priceType | 'fixed' \| 'variable' | Pricing model |
| amount | number? | Amount in sats |

**Returns:** `string` - Encoded noffer

**Example:**
```typescript
const offer = createOffer(identity, ['wss://relay'], 'fixed', 10000)

## Example Usage

/docs sync packages/clink/

/docs api packages/nostr-client/src/

/docs changelog --since v0.1.0