Using the gadget

The day-to-day flows: setting up a contact, sending a message, receiving one, and the things you can do when something goes wrong.

Key exchange

A fresh gadget can't message anyone yet. Before you can talk to a person, the two devices need to share a one-time pad. This is a one-time, in-person ceremony per contact.

You and your partner need:

Two powered-on, set-up gadgets (each has its own PIN and own card).
A way to physically move A's own MicroSD card to B's gadget and back.

The flow:

A taps Contacts → + Add contact. Enters a name (the label they'll see on their own device for this person) and prepares the exchange.
A's gadget writes fresh random bytes (X_A) to A's own card.
A ejects A's card and hands it to B.
B inserts A's card into B's guest slot. B adds the contact on their own gadget and gives A their own local contact name.
B's gadget reads X_A, generates its own random bytes (X_B), and combines them on A's card. The combined data is the shared one-time pad.
B's gadget saves B's encrypted copy of the split pad onto B's own card, then hands A's card back.
A inserts A's card again and finalises the exchange. A's gadget verifies the combined pad, saves A's encrypted copy, and wipes the temporary exchange files.

The two gadgets do not need a cable or wireless link. The exchange is complete only after A gets A's card back and finalises it.

Encrypting a message

From the home screen:

Tap Send.
Pick a contact. Only contacts whose key exchange has completed show up here.
Type your message. For v1, use printable ASCII text plus newlines.
Tap Send. The gadget encrypts the message using the next unused bytes of that contact's send pad, displays the ciphertext as a QR code on the screen, and also shows it as hex underneath in case the QR doesn't scan cleanly.

That's it. The receiving end now needs to read the QR.

Decrypting a message

When someone sends you a message:

Tap Receive on the home screen.
Pick the input method: QR scan or manual hex entry.
For QR scan: point your gadget's scanner at the other person's screen. The scanner reads it once and decodes.
For manual hex: type the hex string they read to you (or texted you, or wrote on paper, or whatever).
The gadget figures out which contact sent the message by trying each contact's receive pad against the ciphertext's MAC tag. The right one authenticates; the wrong ones fail silently.
The decoded message appears with the sender's name ("From: Alice"), the original text, and is added to in-RAM history.

If the MAC doesn't authenticate against any contact, you see "Message authentication failed" — the message either was corrupted in transit, came from a contact you don't have, or was tampered with.

Message history

Decoded and sent messages stay in RAM for the current session. They're shown in the contact's thread (Contacts → tap a contact), line-wrapped and paginated.

History is cleared automatically on:

Auto-lock (5 minutes idle on any screen).
Manual lock (the lock icon in the home screen's top-left corner).
Power-off.

There is no on-device persistent plaintext message log. The card keeps the encrypted pads, contacts, settings, and bookkeeping for which pad ranges have been consumed. If you need to keep a record of the conversation, write it down.

There's also a Burn after reading setting (Settings → toggle). When it's on, a newly received message is shown once, is not added to the in-RAM thread, and the receive-pad bytes used for that message are scrubbed after successful authentication.

Error recovery

A handful of things can go sideways. The gadget is designed to tell you what happened and recover gracefully.

Wrong PIN or forgotten PIN. The PIN screen has a ? button. From there, Restore using device secret backup lets you scan or type your saved device_secret, set a new PIN, and keep the card's pads and contacts.

Own card removed or changed. If the gadget cannot safely read the own card, it clears the in-RAM key, returns to PIN entry, and asks you to reinsert the card and unlock again.

Mid-exchange interrupted. If A's card only has the first exchange file, the pending contact stays in Contacts with a Waiting... badge and can be discarded there. If A's card already has the combined pad from B, A sees "Incomplete exchange with [name]. Finalize or Discard?" after PIN entry.