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:

```typescript
/**
 * 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:

```rust
/// 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:

```mermaid
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)
```markdown
## [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
```markdown
## 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
```markdown
## 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
```