# Ticket 6.3 — Documentation

**Phase**: 6 — Testing & Polish
**Priority**: Medium
**Depends on**: All prior tickets

## Description

User-facing documentation covering setup, configuration, troubleshooting, and architecture. The README is the primary document, supplemented by detailed docs in the `docs/` directory.

## Acceptance Criteria

### AC1: README covers quick start

```gherkin
Given a new user finds the project on GitHub
When they read the README
Then they can get the relay running in under 5 minutes with:
  1. Prerequisites (Node.js 18+, OpenCode installed)
  2. Install: npx conduit
  3. Open the displayed URL on their phone
  4. Enter the PIN
  5. Start chatting
```

### AC2: Configuration reference

```gherkin
Given a user wants to customise the relay
When they read docs/configuration.md
Then they find documentation for:
  - All CLI flags with examples
  - Port configuration
  - PIN management
  - HTTPS/certificate setup
  - Tailscale integration
  - Push notification setup
  - OpenCode connection options
```

### AC3: Architecture documentation

```gherkin
Given a developer wants to contribute
When they read docs/architecture.md
Then they understand:
  - System architecture diagram
  - Component responsibilities
  - Message flow (browser → relay → OpenCode)
  - Event translation layer
  - Session management approach
  - How it differs from claude-relay
```

### AC4: Troubleshooting guide

```gherkin
Given a user encounters an issue
When they read docs/troubleshooting.md
Then they find solutions for common problems:
  - "Can't connect from phone" → check firewall, same network, etc.
  - "Certificate error" → mkcert setup instructions
  - "Push notifications not working" → HTTPS requirement, service worker
  - "OpenCode not found" → installation instructions
  - "Port already in use" → --port flag
  - "Session lost" → reconnection and recovery
```

## Testable Components

| Component | Test Type | What to Assert |
|-----------|-----------|----------------|
| README completeness | Unit | Quick start section present, all sections non-empty |
| CLI flag docs | Unit | All flags documented with defaults |
| Architecture diagram | Unit | Architecture doc file exists and is non-empty |
| Troubleshooting | Unit | Covers common error scenarios listed in AC4 |

## Files to Create

- `README.md` (update existing)
- `docs/architecture.md`
- `docs/configuration.md`
- `docs/troubleshooting.md`
- `docs/contributing.md`

## Notes

- Keep README concise — link to docs/ for details
- Include screenshots/GIFs of the mobile UI
- Document the WebSocket protocol for potential third-party clients
