Restructure project documentation

Separate operator guides from development contracts, relocate
implementation notes under `docs/devel/`, and update cross-references
and
hardware tooling paths. Add getting-started, user administration, and
firmware update guides while preserving firmware behavior.

docs/user_administration.md

@@ -0,0 +1,118 @@
+# User administration
+
+Provision accounts locally first, then use the browser or authenticated admin SSH for routine administration.
+
+Related guides: [Web administration](web_administration.md), [firmware updates](firmware_update.md), [command reference](command_reference.md#role-based-users), [security operations](security_operations.md), and the [web development contract](devel/web_administration.md).
+
+## Choose roles and keep local recovery
+
+| Account role | HTTPS | SSH |
+|---|---|---|
+| `user` | Serial terminal and status | UART1 serial stream through the broker |
+| `admin` | Serial, Admin, and Settings | Device administration shell, not UART1 |
+
+Use a separate `user` account for ordinary SSH serial work. Account roles do not override the broker's one-writer/multiple-observer rule. Admin SSH is not a serial broker client.
+
+Keep physical **UART0 administration** available on a trusted computer. Native USB CDC is a different, network-independent UART1 data path, not an account-recovery console. Physical local access is not protected by network account authentication.
+
+## Create the first administrator
+
+A new device with missing user-database storage starts with a persisted empty database. There is no default shared login, credential import, or `user bootstrap` command. Existing valid user databases retain their accounts unchanged; an older role-`user` account is not silently promoted.
+
+On UART0:
+
+```text
+user status
+user list
+user add maint admin
+user show maint
+```
+
+Enter and confirm a unique password at the no-echo prompts. Passwords must contain **12–64 printable ASCII characters**. `Ctrl-C` cancels a prompt. Usernames must match `[a-z][a-z0-9_-]{0,15}`: 1–16 characters, starting with a lowercase letter, followed by lowercase letters, digits, underscore, or hyphen.
+
+To generate a password instead:
+
+```text
+user add maint admin --generate
+```
+
+Use one creation form, not both for the same name. Generated passwords are displayed once: save the value in a password manager, avoid terminal recording, and do not share the output. Successful account changes persist immediately; no separate Save command is needed.
+
+Before testing network login, compare `web certificate info` and `ssh host-key info` from trusted UART0 with the browser/SSH client's fingerprints. Follow [security operations](security_operations.md), then [sign in through HTTPS](web_administration.md#connect-and-sign-in). For SSH, connect using an interactive shell with the chosen account; exec/subsystem and file-transfer workflows are not supported.
+
+## Add and maintain accounts
+
+Examples for UART0 or an authenticated admin SSH shell:
+
+```text
+user add operator user
+user list
+user show operator
+user password operator
+```
+
+The database holds at most **eight accounts**. Account summaries expose roles and public-key fingerprints, not passwords, salts, or verifiers. Passwords cannot be recovered from status output; set a replacement when necessary.
+
+For an intentional role change or removal:
+
+```text
+user role operator admin --force
+user role operator user --force
+user delete operator --force
+```
+
+These are separate examples, not a sequence to run routinely. Check the target and intended access before using `--force`. The final administrator cannot be deleted or demoted. Password, role, key, and deletion changes invalidate the affected username's outstanding tickets and active web/SSH sessions; unrelated accounts are not intentionally revoked. Your own change may disconnect you before you see its result. Inspect state and test the intended login before repeating an uncertain operation.
+
+`user password <username> --generate` displays a replacement once. Admin SSH rejects generation for its own account to avoid losing the value during revocation; use trusted UART0 or the supported browser workflow instead.
+
+### Browser account management
+
+Sign in as `admin`, open **Settings → Accounts**, and select the intended account for password, role, deletion, or authorized-key operations. Changes commit on successful submission; they are not RAM-only drafts awaiting a global Save.
+
+The generated-password workflow first displays a new value without changing the account. Store it securely and acknowledge that it is saved, then explicitly submit the create/password change. Generation alone does not set a password; the saved acknowledgement is not proof that the subsequent operation succeeded. Self changes may end your login immediately.
+
+The browser **Admin shell** has narrower account permissions than Accounts settings: status/list/show and selected interactive changes to other accounts are supported, but self changes, generated passwords, key commands, and database recovery are denied there. Use typed Accounts controls or UART0 rather than trying to bypass these restrictions.
+
+## Authorize an SSH client key
+
+1. On a trusted client, generate or choose an OpenSSH **Ed25519** or **ECDSA P-256** key. Keep the private key on that client; import only the single-line `.pub` public key.
+2. On UART0 or authenticated admin SSH, run:
+
+   ```text
+   user key add operator
+   ```
+
+3. Paste the public-key line at the prompt. `Ctrl-C` cancels. Alternatively use the Accounts key-import controls in the browser.
+4. Run `user show operator` and compare the reported key type and `SHA256:` fingerprint with the client's public key. Test a new SSH login with the intended username before closing local recovery access.
+
+Each account supports **three keys**. Supported types are `ssh-ed25519` and `ecdsa-sha2-nistp256`; RSA and OpenSSH certificate keys are not supported. Duplicate keys within an account are rejected. The same key can be assigned to multiple accounts, but access then follows the username selected at login.
+
+Delete by the stable index shown in `user show`, not by its position in a displayed list:
+
+```text
+user key delete operator 0 --force
+```
+
+Use `user key clear operator --force` only when intentionally removing all that account's keys. Key changes persist immediately and revoke that account's sessions. Changing a password does **not** remove authorized keys; review both after compromise. Authorized client keys are separate from the device's SSH host identity.
+
+## Forgotten passwords and database failure
+
+For a healthy database, use UART0 and normal commands such as `user password maint` to restore access. First inspect `user status` and `user list`; do not erase flash or reset identities to repair a forgotten account password.
+
+Only if database initialization has failed and the database is **unavailable**, deliberate UART0 recovery is:
+
+```text
+user recover --force
+user status
+user add maint admin
+```
+
+**Recovery destroys the user database's contents and rebuilds it empty.** It refuses a healthy database, including a healthy empty database, and is unavailable over SSH/browser. It does not erase unrelated Wi-Fi/serial configuration or HTTPS/SSH identities. Recreate required accounts and authorized keys afterward. Check each command result; storage failures are not evidence of successful recovery.
+
+`web reset --force` and `ssh reset --force` recover their respective device identities, not user accounts. Neither is a whole-device factory reset.
+
+## Persistence and security limits
+
+Keep a private reprovisioning record of usernames/roles, public keys, settings, and verified device fingerprints; store passwords separately. There is no supported configuration/credential/identity backup-export command. Application-only [firmware updates](firmware_update.md) preserve stored bytes, but compatibility with the new firmware still matters.
+
+NVS credentials are not protected against physical extraction by this workflow. Password verifiers can be attacked offline, and logical replacement does not securely erase historical flash contents. Keep the device and local ports controlled, avoid Internet exposure, and follow the [security checklist](security_operations.md).