BOT PLATFORM — ADMIN CHEAT-SHEET
================================
Quick reference for operators. Reachable at /admin-cheatsheet.txt.
(Contains no secrets — the actual codes/keys live in the server .env, never here.)


PAGES
-----
/                  Collection / public home page (lists only approved bots)
/login.html        Register or log in (admins and builders)
/dashboard.html    A builder's own bots (create, edit, share)
/admin.html        Admin console (login as admin) — manage everything
/builder.html?edit=<code>   Edit one bot (capability link; no login needed)
/?bot=<code>       Run/share a published bot (works for not-listed bots too)
/help.html         How-to guide for builders (EN/DE)
/impressum.html    Legal notice


ACCOUNTS & ROLES (no email collected)
-------------------------------------
- Two roles: admin and builder. End users need no account to chat.
- Self-registration at /login.html requires a code:
    admin code   -> registers an admin
    builder code -> registers a builder (e.g. a student / class)
- The codes live in the server .env:
    REGISTER_CODE_ADMIN=...
    REGISTER_CODE_BUILDER=...
- AFTER CHANGING ANY .env VALUE you must restart the service to load it:
    sudo systemctl restart bot-platform
- Treat the builder code as a per-course secret and rotate it between courses.
- Forgot password? Any admin can issue a one-time password on /admin.html
  (Accounts table -> "Reset (one-time pw)"). Read the shown temp out to the
  person; they are forced to choose a new password at next login.
  Works for builders AND other admins. There is no email-based reset.


ADMIN CONSOLE (/admin.html)
---------------------------
- Child-safe mode (whole platform): tick to force EVERY bot to be child-safe
  (school deployment). Leave off for a company. Boot default can be set with
  CHILD_SAFE_MODE=1 in .env; an explicit tick in the console overrides it.
- Bots table: each row has Run and Edit links + a "Listed" checkbox.
    Listed  = appears on the public home page. Only a PUBLISHED + PUBLIC bot
              can be listed. Approving = ticking the box (reversible).
    Not listed / not approved bots are still usable via their Run link.
- "+ New chatbot" / "Upload project" create bots you own.
- Accounts table: see all accounts; issue one-time passwords (see above).


HOW BUILDING & SHARING WORKS
----------------------------
- A builder logs in -> dashboard -> "+ New chatbot" -> the builder opens.
- Each bot has two secret codes (capability links, no login required):
    Edit link:  /builder.html?edit=<edit_code>   (full edit rights — share only
                with co-editors; treat like a password)
    Run link:   /?bot=<public_code>               (chat with the published bot)
- A bot is reachable by its Run link as soon as it is PUBLISHED, whether or not
  it is listed on the home page. Listing is an admin decision.
- Conversations auto-delete after 90 days of inactivity. User messages are sent
  to the LLM provider (OpenAI) to generate replies.


SAFETY
------
- Child-safe mode is a strong INSTRUCTION to the model, not a hard filter.
  For a stricter school setup, a separate moderation pass is planned (see the
  spec, backlog). Do not rely on it as a guarantee.


DEPLOY (on the server, as root)
-------------------------------
- Build the zip on the laptop:  .\package.ps1
- Upload + install:
    scp <zip> root@chat.ubicomp.net:/tmp/
    ssh  root@chat.ubicomp.net
    cd /srv && unzip -o /tmp/<zip>          # -> /srv/chat ; keeps .env + node_modules
    cd /srv/chat && bash deploy/install.sh --domain chat.ubicomp.net
- install.sh runs DB migrations, (re)installs the nginx site, re-applies TLS,
  restarts the service, and runs a /health smoke test. It is idempotent.
- Page-only changes (anything under public/) can just be unzipped — nginx serves
  them; no restart needed. Changes to server code, dependencies, the nginx
  template, or a new SQL migration REQUIRE install.sh.
- Do NOT pass --bootstrap-db on an existing install (the database already exists).


SERVICE OPERATIONS
------------------
  sudo systemctl restart bot-platform        # apply .env / code changes
  sudo systemctl status  bot-platform
  journalctl -u bot-platform -f              # live logs
  curl -s https://chat.ubicomp.net/health    # expect "status":"ok"


SECURITY NOTES
--------------
- The site is public; access control is in the app (account sessions + per-bot
  edit codes). There is no longer a site-wide password.
- Edit/run codes appear in URLs (browser history, referrers) — treat edit links
  as secrets and only share them with people who should edit that bot.
- Never put real codes, keys or passwords in files under public/ (this file
  included) — they belong only in the server .env (mode 640, not in git).