fluid-telegram/docs/seeding-runbook.md

# Operator runbook — seeding platform access

Some platform access cannot be provisioned from a specification. Telegram will
not let software create the *first* credential: an account needs a phone and a
device, and `api_id` / `api_hash` come from a web form behind a login. No API
exists for either, and none is coming, because their purpose is to establish that
a person is on the other end.

This runbook is what we do instead. It is not a lowering of the bar. **A manual
step is acceptable when it is guided, repeatable, and bounded — and unacceptable
when it is merely undocumented.** The test each step below has to pass is that
an operator who has never done it can follow it once, get the same result as
anyone else, and hand the outcome to a tool that takes over from there.

## The rule this runbook operates under

> Automate everything that has an interface. Where a step exists specifically to
> prove a human is present, guide it — and record why it resisted automation, so
> the judgement can be revisited rather than inherited.

Every manual step below carries a **Why not automated** line. That line is the
thing to re-read when the platform changes. Some of them will stop being true;
the sooner that is noticed, the smaller the runbook gets.

There is a real distinction here worth keeping. A KYC identity check resists
automation *by design* — automating it would defeat what it is for, and a
component weak enough to allow it is a defect, not an opportunity. A web form
that mints an API key resists automation only *incidentally*, because nobody
built the endpoint. The first stays manual on principle. The second is a
candidate the moment anything changes.

Telegram's steps are all the second kind. None of them is a fraud control; they
are just interfaces that were never built.

---

## Before you start

Have these ready. Stopping halfway through to find one is how the session
becomes irreproducible.

- [ ] A phone number that can receive SMS, **not** a personal one
- [ ] A device with Telegram installed, to complete the first login
- [ ] Access to OpenBao (`bao.coulomb.social`) with write on the interface's path
- [ ] The campaign's presence spec merged (`pr-hall-of-helix/presence/telegram.yaml`)
- [ ] The avatar asset committed and referenced by the spec

Roughly 20 minutes, once.

---

## Step 1 — Register the operator account

**Why not automated:** Telegram requires a phone number and an SMS round trip.
There is no registration API at any tier. This is the step whose whole purpose
is to prove a person is present.

1. Install Telegram on the device and register with the operator phone number.
2. Set a display name that reads as an operator account, not a person.
3. Enable two-factor authentication and put the password in OpenBao at
   `<interface-path>/telegram/operator-2fa` immediately.

**Do not use a personal account.** If it is rate-limited or restricted — which
automation can cause — the loss should be a throwaway account, not someone's
messages.

**Record:** the phone number, in OpenBao at `<interface-path>/telegram/operator-phone`.

---

## Step 2 — Obtain `api_id` and `api_hash`

**Why not automated:** issued by a web form at my.telegram.org behind a login
code. No API. This one is incidental rather than principled — if Telegram ever
exposes it, Step 2 disappears.

1. Go to <https://my.telegram.org>, log in with the operator number.
2. **API development tools** → create an application.
   - App title: `helixforge-provisioner`
   - Platform: Other
3. Copy `api_id` and `api_hash`.

**Record:** both, in OpenBao at `<interface-path>/telegram/operator-app`.

They are shown once per application. Losing them means creating another.

---

## Step 3 — Mint the MTProto session

**Why not automated:** the login code arrives out of band, on the device. The
command is interactive by necessity — but *only this command*, and only once.

```bash
provision session bootstrap --campaign hall-of-helix
```

It prompts for the phone number, the login code, and the 2FA password, then
writes the session string to OpenBao at
`<interface-path>/telegram/operator-session`.

The session string is a **full-account credential** — it can do anything the
account can. It never leaves OpenBao, is never given to the adapter, and is used
only by the provisioner. Treat losing it as losing the account.

**Verify:**

```bash
provision session check --campaign hall-of-helix    # prints the account, no secrets
```

---

## Step 4 — Hand over to the provisioner

From here nothing is manual. The remaining work is `FT-WP-0002` T03–T06:

```bash
provision plan  --spec ../pr-hall-of-helix/presence/telegram.yaml   # read the diff
provision apply --spec ../pr-hall-of-helix/presence/telegram.yaml   # execute it
```

`apply` registers the bot through BotFather, sets its name, about text,
description and avatar, creates both channels, adds the bot as administrator with
`post_messages` only, generates the redaction salt if it is absent, and writes
`presence/resolved/hall-of-helix.yaml`.

**Read the plan before approving it.** That is the human judgement this design
keeps — not clicking through BotFather, but deciding whether the diff is what
was intended.

---

## Re-running this

Steps 1–2 are once per operator account, ever. Step 3 repeats only if the session
is revoked — by a password change, an explicit sign-out, or Telegram invalidating
it. When that happens, re-run Step 3 alone; nothing else is affected, because
resolved state and the bot token do not depend on the session that created them.

Step 4 is safe to repeat at any time. It is a converging reconciler, and a second
apply over an unchanged spec does nothing.

## When a step stops being necessary

Re-read the **Why not automated** lines whenever Telegram changes its API surface,
and delete the step if the reason has expired. A runbook nobody prunes becomes a
description of how things used to work, and the manual steps in it start looking
like requirements rather than gaps.