docs: analog phones (ATAs) set up by hand; the ATA plan in the roadmap

docs/admin-guide/README.md

@@ -9,6 +9,7 @@ keeping the system safe, legal and up to date.
 4. [Emergency calls and recording law](legal.md): E911 duties and call recording consent
 5. [Troubleshooting](troubleshooting.md)
 6. [Updating, backups and monitoring](maintenance.md)
+7. [Analog phones (ATAs)](ata.md)
 
 ---
 

docs/admin-guide/ata.md

@@ -0,0 +1,74 @@
+# Analog phones (ATAs)
+
+An analog telephone adapter (ATA) connects ordinary phones, with a phone cord, to SelfPhoneNG.
+Each port of the ATA is one user's phone. Calls, voicemail (with the stutter dial tone when a
+message waits), `*` codes, transfer with the hook flash, and 911 all work.
+
+For now you set an ATA up by hand, in its own web page. Automatic setup, like the desk phones
+get, is planned for the Grandstream HT802 V2 first.
+
+Field names below are from Grandstream's HT802 V2 guide; other HT80x/HT81x models and firmware
+versions may name them a little differently.
+
+## 1. In SelfPhoneNG
+
+1. **Users**: one user for each port you'll use (port 2 can stay empty).
+2. Open the user, **Credentials** tab, **Reveal password**. Keep the server, port, username and
+   password at hand. Viewing it is recorded in the audit log.
+
+You don't need to add the ATA on the Phones page: "Other (set up by hand)" there shows the same
+settings, and is only for one line per device.
+
+## 2. On the ATA (Grandstream HT802 V2)
+
+Plug the ATA into the office network and find its address (in the router's list of devices, or
+dial `***` then `02` on the analog phone to hear it). Open `http://<its address>`. The admin
+password is on the label underneath; change it after you sign in.
+
+On **FXS PORT 1** (and **FXS PORT 2** with the second user):
+
+| Field | Value |
+|---|---|
+| Profile Active | Yes |
+| Primary SIP Server | the server and port from the Credentials tab, for example `pbx.example.com:5060` |
+| Outbound Proxy | empty |
+| SIP Transport | UDP |
+| SIP User ID | the username (the extension number) |
+| Authenticate ID | the username again |
+| Authenticate Password | the password |
+| Name | the person's name (shown to the people they call) |
+| SIP Registration | Yes |
+| Allow Incoming SIP Messages from SIP Proxy Only | Yes: nobody but SelfPhoneNG can ring the phone |
+| DTMF | RFC2833 first |
+| Preferred Vocoder | PCMU first |
+| Dial Plan | see below |
+
+Click **Apply**. On the **Status** page the port should say **Registered** within a minute, and on
+the server `pjsip show contacts` ([Troubleshooting](troubleshooting.md)) lists the extension.
+
+### Dial plan
+
+An analog phone has no send button: the ATA decides when you've finished dialing. Without a dial
+plan it waits a few seconds after the last digit, which works for everything. To make the usual
+calls go at once, set **Dial Plan** to:
+
+```
+{ 911 | 9911 | [2-9]xxxxxxxxx | 1[2-9]xxxxxxxxx | 011x+ | *x+ | **x+ | x+ }
+```
+
+- 911 and 9911 go out at once (US law requires 911 to work without a prefix).
+- 10- and 11-digit numbers go out at once; international numbers after a pause.
+- Internal numbers (1 to 6 digits), `*` codes and pickup (`**`) go after a pause, or press **#**
+  to send now.
+
+## 3. Things to know
+
+- **911:** each port's user has its own emergency caller ID, like any phone (Users →
+  Emergency). An ATA that moves to another address needs the E911 address updated at voip.ms.
+- **Fax:** not supported. Many fax machines still work through an ATA with Fax Mode set to
+  **Pass-Through** and only PCMU allowed, but expect failures on long faxes. T.38 isn't set up on
+  the SIP trunk.
+- **Not on analog phones:** busy lights, the company phonebook, the browser phone features.
+- **Caller ID** shows on analog phones that support it (US: Bellcore, the ATA's default).
+- **Away from the office:** an ATA works anywhere a desk phone works. The phone network limit
+  (Settings → Security) applies to it the same way.

docs/spec/09-roadmap.md

@@ -259,6 +259,21 @@ Quick hits: **Telnyx, Flowroute, Twilio**, as presets beside voip.ms with their
 - Flowroute's tech prefix (`12345678*`) in a route's prepend: check it fits.
 Each one checked against a real account before it's called supported (06's verify rule).
 
+## Analog phone adapters (owner, 2026-10-21: wanted; the owner is buying an HT802 V2)
+1. Done: admin guide page for setting one up by hand (`docs/admin-guide/ata.md`).
+2. A dial plan in the setup files, made from the numbering: 911/9911 at once, 10/11 digits at once,
+   internal numbers and `*` codes after the inter-digit pause or `#`. For ATAs and desk phones.
+   Check on the real unit that a full match sends at once while `x+` is also in the plan.
+3. Several lines on one device (`device_lines`: device, port, extension; the setup file lists every
+   line of that MAC) and a `grandstream-ata.ts` template for the HT802 V2. Its port 2 P-values
+   differ from the desk phones' account 2: take them from Grandstream's config template or an
+   export of the real unit, not from memory. Fax: Pass-Through and PCMU only; T.38 stays out
+   (00 §2).
+4. Later (Cisco): `cisco-ata.ts` for ATA 191/192 (multiplatform firmware) and SPA112/122
+   (end of support 2025-05-31): `<flat-profile>` XML, `_1_`/`_2_` per line, served at
+   `/prov/<mac>.xml`. No DHCP login, so the Phones page shows the `Profile_Rule` to paste
+   (`[--uid <mac> --pwd <password>] https://<host>/prov/$MA.xml`). Needs a real unit.
+
 ---
 
 ## M12 — Nice to have (after v1.0)