featherChat/warzone/docs/LLM_HELP.md

# featherChat Help Reference

featherChat (codename: warzone) = E2E encrypted messenger. TUI client, web client (WASM), federated servers. Crypto: X3DH key exchange + Double Ratchet. Identity = Ed25519 keypair from 24-word seed.

## Commands

cmd | action | example
--- | --- | ---
/help, /? | show help | /help
/info | show your fp | /info
/eth | show ETH addr | /eth
/seed | show 24-word recovery mnemonic | /seed
/peer <addr>, /p | set DM peer | /peer abc123 or /peer @alice
/reply, /r | reply to last DM sender | /r
/dm | switch to DM mode (clear peer) | /dm
/contacts, /c | list contacts + msg counts | /c
/history, /h [fp] | show conversation history (50 msgs) | /h abc123
/alias <name> | register alias for yourself | /alias alice
/aliases | list all registered aliases | /aliases
/unalias | remove your alias | /unalias
/friend | list friends + online status | /friend
/friend <addr> | add friend | /friend @bob
/unfriend <addr> | remove friend | /unfriend @bob
/devices | list active device sessions | /devices
/kick <id> | kick a device session | /kick dev_abc
/g <name> | switch to group (auto-join) | /g ops
/gcreate <name> | create group | /gcreate ops
/gjoin <name> | join group | /gjoin ops
/glist | list all groups | /glist
/gleave | leave current group | /gleave
/gkick <fp> | kick member (creator only) | /gkick abc123
/gmembers | list group members + status | /gmembers
/file <path> | send file (max 10MB, 64KB chunks) | /file ./doc.pdf
/quit, /q | exit | /q

Navigation: PageUp/PageDown scroll msgs, Up/Down scroll by 1 (empty input), Ctrl+C or Esc quit.

## Addressing

Format | Example | Notes
--- | --- | ---
Fingerprint | abc123def456... | hex string, derived from Ed25519 pubkey
ETH address | 0x742d35Cc... | derived from same seed, checksum format
@alias | @alice | 1-32 alphanum chars, globally unique, 365d TTL

All 3 formats work in /peer. Aliases resolve to fp via server. One alias per user. Register with /alias, recover with recovery key.

## Quick Start

1. `warzone init` -- generates seed, saves identity.seed, prints 24-word mnemonic. WRITE IT DOWN.
2. `warzone register --server https://srv.example.com` -- uploads prekey bundle to srv
3. `warzone tui --server https://srv.example.com` -- opens TUI, connects WebSocket
4. `/peer @alice` or `/peer <fingerprint>` -- set recipient
5. Type msg, press Enter -- encrypted + sent

Recovery: `warzone recover` -- enter 24 words to restore identity on new device.

## Groups

- /gcreate <name> -- create, you become creator + first member
- /gjoin <name> -- join existing (or auto-join via /g <name>)
- type msg in group mode -- fan-out encrypted per-member (sender keys)
- /gleave -- leave current group
- /gmembers -- shows fp, alias, online status, creator flag
- /gkick <fp> -- creator only, removes member

Groups auto-create on join if they don't exist. Server fans out per-member encrypted msgs.

## Files

/file <path> -- sends to current peer/group. Max 10MB. Auto-chunked at 64KB. Includes filename, size, SHA-256 hash. Receiver auto-reassembles.

## Friends

- /friend -- list all friends with online/offline status
- /friend <addr> -- add (fp, ETH, or @alias)
- /unfriend <addr> -- remove
- Friend list stored encrypted on srv (only you can decrypt with your seed)
- Shows alias resolution + presence status

## Devices

- /devices -- list active WS connections (device_id, connected_at)
- /kick <device_id> -- revoke specific device
- Max 5 concurrent device sessions
- /devices/revoke-all API endpoint = panic button (kills all except current)

## Security

- Seed = 24-word BIP39 mnemonic = master key. Derives Ed25519 identity + ETH wallet.
- NEVER share seed. Only way to recover account.
- X3DH key exchange establishes sessions. Double Ratchet provides forward secrecy.
- All DMs E2E encrypted. Group msgs encrypted per-member.
- Server sees: metadata (who talks to whom, timestamps), encrypted blobs, presence.
- Server cannot read msg content.
- Pre-keys: signed pre-key + 10 one-time pre-keys uploaded on register.
- Bot API msgs are NOT E2E encrypted (plaintext JSON envelopes).

## Federation

- 2 servers connected via persistent WebSocket
- Config: JSON file with server_id, shared_secret, peer URL
- Messages auto-route across servers (srv checks remote presence)
- Aliases globally unique across federation
- @alias resolution checks local first, then federated peer
- Same client commands work regardless of which srv peer is on
- Auto-reconnects on connection failure

## Web Client

- Browser access at server root URL (/)
- WASM-compiled client, same crypto as TUI
- PWA: installable, offline-capable (service worker caches shell)
- Same E2E encryption as native client
- Deep links: navigate to specific peers/groups via URL

## Troubleshooting

Problem | Cause | Fix
--- | --- | ---
"peer not registered" | recipient hasn't run register yet | they need to `warzone register`
"session reset" | crypto session re-established | normal after key rotation or recovery, msgs continue
"connection lost" | WS disconnected | auto-reconnects, no action needed
"alias already taken" | someone else has it | pick different name or wait for 365d expiry + 30d grace
"not a member" | sending to group you left | /gjoin <name> first
"invalid token" | bot token expired or wrong | re-register bot
"file too large" | over 10MB | split file manually
no prekeys available | recipient's one-time prekeys exhausted | they need to re-register or come online

## Bot API

Telegram-compatible REST API. Base: /v1/

Endpoint | Method | Body | Returns
--- | --- | --- | ---
/bot/register | POST | {"name":"mybot","fingerprint":"abc..."} | {"token":"...","name":"..."}
/bot/:token/getMe | GET | -- | bot info
/bot/:token/getUpdates | POST | {"timeout":5} | array of Update objects
/bot/:token/sendMessage | POST | {"chat_id":"<fp>","text":"hello"} | msg confirmation

- Token format: fp_prefix:random_hex
- getUpdates: long-poll (max 5s), returns then deletes queued msgs
- sendMessage: plaintext JSON, NOT E2E encrypted
- Updates include: messages, key exchanges, call signals, file headers
- Bot msgs delivered via same routing (WS push or DB queue)

## Server API (other endpoints)

- POST /v1/register -- upload prekey bundle
- GET /v1/keys/:fp -- fetch prekeys for peer
- POST /v1/send -- send encrypted msg
- GET /v1/receive/:fp -- poll msgs (WS preferred)
- WS /v1/ws?fp=<fp>&token=<tok> -- real-time connection
- GET /v1/presence/:fp -- check online status
- GET/POST /v1/friends -- encrypted friend list
- GET /v1/devices -- list sessions
- POST /v1/devices/:id/kick -- kick device
- Alias routes under /v1/alias/*
- Group routes under /v1/groups/*