1.8.6

.env.example

@@ -21,6 +21,22 @@ ADMIN_DAEMON_SOCKET=tcp://127.0.0.1:9065
 # Telnet Daemon Configuration
 # TELNET_BIND_HOST=0.0.0.0
 # TELNET_PORT=2323
+# TLS is enabled by default on port 8023 with an auto-generated self-signed cert.
+# Set TELNET_TLS=false to disable TLS entirely.
+# TELNET_TLS=true
+# TELNET_TLS_PORT=8023
+# TELNET_TLS_CERT=/etc/ssl/certs/your-cert.pem
+# TELNET_TLS_KEY=/etc/ssl/private/your-key.pem
+
+# PubTerm Native Door Configuration
+# Host and port the PubTerm door connects to via telnet (defaults to BBS localhost telnet port)
+# PUBTERM_HOST=127.0.0.1
+# PUBTERM_PORT=2323
+# Path to telnet binary if not on PATH (Linux)
+# PUBTERM_TELNET_BIN=/usr/bin/telnet
+# Windows: PubTerm uses PuTTY plink in telnet mode (no escape character trap).
+# Install PuTTY: winget install PuTTY.PuTTY
+# PUBTERM_PLINK_BIN=C:\Program Files\PuTTY\plink.exe
 
 # Gemini Capsule Server Configuration (optional — only needed if running the daemon)
 # GEMINI_BIND_HOST=0.0.0.0
@@ -87,6 +103,16 @@ FILEAREA_RULE_ACTION_LOG=data/logs/filearea_rules.log
 # File action debugging (writes data/logs/file_action_debug.log)
 # FILE_ACTION_DEBUG=true
 
+# Echomail message date ordering field used by backend sorting and echomail UI date display.
+# received = use date_received (default), written = use date_written
+# ECHOMAIL_ORDER_DATE=received
+
+# i18n missing key logging (QA hardening)
+# Set to true to log translation keys that are missing from catalogs.
+# I18N_LOG_MISSING_KEYS=false
+# Optional explicit log file path. If unset, messages go to PHP error_log.
+# I18N_MISSING_KEYS_LOG_FILE=data/logs/i18n_missing_keys.log
+
 
 # DOS Emulator Selection (defaults to DOSBox)
 # dosbox = DOSBox (default, reliable, ~180MB RAM, works on Windows and Linux) - RECOMMENDED

.github/workflows/i18n-error-keys.yml

@@ -0,0 +1,25 @@
+name: i18n Coverage Checks
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+
+jobs:
+  check-i18n:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+
+      - name: i18n error key coverage
+        run: php scripts/check_i18n_error_keys.php
+
+      - name: i18n hardcoded UI strings
+        run: php scripts/check_i18n_hardcoded_strings.php

.gitignore

@@ -1,6 +1,7 @@
 composer.lock
 config/*.json
 !config/*.example
+config/i18n/overrides/
 config/*.json.*
 config/taglines.txt
 config/welcome.txt
@@ -28,12 +29,17 @@ backups/*
 *~
 .env
 .env.local
+tests/.env.test
 bbs_ads/*
 !bbs_ads/claudes1.ans
 
 # Windows utility scripts
 delnul.cmd
 node_modules/
+tests/playwright/.auth-state.json
+tests/playwright/.csrf-token.json
+tests/playwright-report/
+test-results/
 scripts/dosbox-bridge/package-lock.json
 
 # DOS Door files - only track manifests

CLAUDE.md

@@ -26,10 +26,12 @@ A modern web interface and mailer tool that receives and sends Fidonet message p
    - **IMPORTANT**: CLI scripts must include `src/functions.php` after autoload to access global functions like `generateTzutc()`: `require_once __DIR__ . '/../src/functions.php';`
    - Scripts should be made executable with `chmod +x` and marked as executable in git with `git update-index --chmod=+x scripts/filename.php`
  - templates/ - html templates
+   - **IMPORTANT**: Template resolution order is `templates/custom/` → `templates/shells/<activeShell>/` → `templates/`. The active shell (`web` or `bbs-menu`) has its own `base.twig` at `templates/shells/web/base.twig` and `templates/shells/bbs-menu/base.twig` which take priority over `templates/base.twig`. When adding nav links or modifying shared layout, you must update **both** `templates/base.twig` AND `templates/shells/web/base.twig` (and `bbs-menu` if applicable).
  - public_html/ - the web site files, static assets
  - tests/ - test scripts used in debugging and troubleshooting
  - vendor/ - 3rd party libraries managed by composer and should not be touched by Claude
  - data/ - runtime data (binkp.json, nodelists.json, logs, inbound/outbound packets)
+ - telnet/ - the telnet BBS server (separate from the web interface)
 
 ## Important Notes
  - User authentication is simple username and password with long lived cookie
@@ -127,9 +129,79 @@ return function($db) {
  - Avoid duplicating code.  Whenever possible centralize methods using a class.
  - **Git Workflow**: Do NOT stage or commit changes until explicitly instructed. Changes should be tested first before committing to git.
  - When writing out a proposal document state in the preamble that the proposal is a draft, was generated by AI and may not have been reviewed for accuracy.
- - **Service Worker Cache**: When making changes to CSS or JavaScript files, increment the CACHE_NAME version in public_html/sw.js (e.g., 'binkcache-v2' to 'binkcache-v3') to force clients to download fresh copies. The service worker handles all static asset caching to bypass aggressive browser caching on mobile devices.
+ - **Service Worker Cache**: When making changes to CSS or JavaScript files, or when updating i18n language strings in `config/i18n/`, increment the CACHE_NAME version in public_html/sw.js (e.g., 'binkcache-v2' to 'binkcache-v3') to force clients to download fresh copies. The service worker caches static assets and the i18n catalog (`/api/i18n/catalog`) to bypass aggressive browser caching on mobile devices.
  - Write phpDoc blocks when possible
 
+## Localization (i18n) Workflow
+
+The project uses key-based localization for both Twig and JavaScript. Translation catalogs live in:
+- `config/i18n/<locale>/common.php`
+- `config/i18n/<locale>/errors.php`
+
+Current baseline locales are `en` and `es`.
+
+### Core Rules
+- Never hardcode new user-facing UI text in templates/JS when adding or changing features.
+- Add a translation key first, then use it from Twig/JS.
+- Keep `en` and `es` in sync for every new key in normal feature work.
+- Prefer stable key names by page/feature area, e.g. `ui.settings.*`, `ui.polls.*`, `errors.polls.*`.
+- Do not change existing key names unless required (avoid breaking references).
+
+### Twig Translation
+- Use the global Twig function: `t(key, params, namespace)`.
+- Default namespace is `common`; pass `'errors'` when needed.
+- Example:
+```twig
+{{ t('ui.settings.title', {}, 'common') }}
+{{ t('ui.polls.create.submit', {'cost': poll_cost}, 'common') }}
+```
+
+### JavaScript Translation
+- Use `window.t(key, params, fallback)` (or a local wrapper like `uiT`).
+- Use placeholders in strings and pass params object:
+```js
+window.t('ui.polls.create.submit', { cost: 25 }, 'Create Poll ({cost} credits)')
+```
+- `window.i18n` supports lazy namespace loading via:
+  - `loadI18nNamespaces([...])`
+  - endpoint: `GET /api/i18n/catalog?ns=common,errors&locale=<locale>`
+- JS should always include a fallback string for resilience.
+
+### API Errors and `error_code`
+- API responses should use structured errors via `apiError(error_code, message, status, extra)` and return:
+  - `error_code` (translation key)
+  - `error` (human fallback)
+- Frontend should resolve display text with `window.getApiErrorMessage(payload, fallback)`.
+- Do not rely on matching raw error message text in frontend logic.
+- For new API errors:
+  1. Add/choose `errors.*` key in route code.
+  2. Add that key to `config/i18n/en/errors.php` (and `es/errors.php`).
+  3. Use `getApiErrorMessage` in UI handling.
+
+### Locale Resolution / Config
+- Locale is resolved server-side through `LocaleResolver`/`Translator`.
+- Supported locales are exposed to Twig as `supported_locales`.
+- Environment settings used by i18n:
+  - `I18N_DEFAULT_LOCALE`
+  - `I18N_SUPPORTED_LOCALES` (optional; auto-discovers locale folders if unset)
+  - `I18N_LOG_MISSING_KEYS`
+  - `I18N_MISSING_KEYS_LOG_FILE`
+
+### Required Validation After i18n Changes
+- Run:
+  - `php scripts/check_i18n_hardcoded_strings.php`
+  - `php scripts/check_i18n_error_keys.php`
+- Goal:
+  - no new hardcoded string violations
+  - no missing `errors.*` catalog keys used by `apiError(...)`
+
+### Practical Checklist for New UI/API Work
+1. Add new `ui.*`/`errors.*` keys to `en` and `es`.
+2. Replace literals in Twig with `t(...)`.
+3. Replace JS literals with `window.t(...)` (or `uiT(...)`) fallbacks.
+4. Ensure API errors return `error_code`.
+5. Run both i18n check scripts before commit.
+
 ## URL Construction
 When constructing full URLs for the application (e.g., share links, reset password links, meta tags), **always** use the centralized `Config::getSiteUrl()` method:
 

FAQ.md

@@ -152,6 +152,15 @@ When sending netmail, check the "Crash" option to attempt direct delivery.
 4. Run `php cli/binkp_poll.php --domain=<domain>` to poll your uplink
 5. Check `data/logs/packets.log` and `data/logs/binkp_poll.log` for errors
 
+### Q: If a packet contains multiple messages and one fails, are other messages affected?
+**A:** It depends on the failure type:
+
+- **Single message exception** (e.g. database error, malformed message data): Only that message is skipped. Processing continues normally for all remaining messages in the packet.
+- **Undeliverable netmail** (no matching local user found by address or name): The message is dropped with a detailed log entry (from/to/subject/date/MSGID) and processing continues. The original `.pkt` file is also preserved to `data/undeliverable/` for manual inspection.
+- **Echomail from an insecure session** (security rejection): Processing stops immediately — the rest of the packet is abandoned and moved to the error directory.
+
+In the first two cases the packet is still considered successfully processed even if individual messages were skipped.
+
 ---
 
 ## Binkp Server & Polling