User Pairing

kern uses a code-based pairing system. No allowlists — every user pairs through the agent.

Flow

1. Unknown user messages the bot (Telegram DM or Slack DM)
2. Bot responds with a pairing code: KERN-XXXX
3. User shares the code with the operator out-of-band (text, email, in person)
4. Operator tells the agent who this person is:

   "pair KERN-7X4M — that's Sarah, my cofounder, she handles finance but shouldn't see personal stuff"

5. Agent calls kern({ action: "pair", code: "KERN-7X4M" })
6. Agent updates USERS.md with identity, role, and access notes
7. User is now paired and can chat

Pairing codes

• Format: KERN-XXXX (4 uppercase chars, no ambiguous characters I/O/0/1)
• Stored in .kern/pairing.json (gitignored)
• One code per user — if they message again, same code is returned
• Codes survive until paired or agent restarts

USERS.md

After pairing, the agent writes user info to USERS.md. This is a kern-specific file (not part of agent-kernel).

Example:

# Users

## Sarah
- Telegram: 12345678
- Role: cofounder
- Access: financials, not personal
- Paired: 2026-03-24
- Notes: handles quarterly reports

## Igor
- Telegram: 5292022513
- Role: friend, testing
- Access: general
- Paired: 2026-03-24

The agent manages this file — reads it to know who people are, updates it as it learns more about users.

Operator

The first person to message the bot is auto-paired as the operator — no code needed, silent. The TUI is also always the operator.

Every subsequent user goes through the pairing code flow.

Approving users

Three ways to approve:

1. Through the agent — tell it "pair KERN-XXXX — that's Sarah"
2. CLI — kern pair <agent> <code> (no agent interaction needed)
3. kern tool — agent calls kern({ action: "pair", code: "KERN-XXXX" })

Checking users

kern({ action: "users" })

Returns all paired users and pending pairing codes.

Storage

• .kern/pairing.json — pending codes and paired user IDs with chat IDs
• USERS.md — human-readable user directory managed by the agent