1.8.7

.env.docker.example

@@ -28,6 +28,9 @@ DOSDOOR_WS_PORT=6001
 # Credits System
 CREDITS_ENABLED=true
 
+# Experimental FREQ UI controls
+ENABLE_FREQ_EXPERIMENTAL=false
+
 # DOS Door Configuration
 DOSDOOR_DEBUG_KEEP_FILES=false
 DOSDOOR_WS_BIND_HOST=0.0.0.0

.env.example

@@ -69,6 +69,11 @@ SMTP_ENABLED=true
 # This setting is used by the 'Terminal' web door.
 TERMINAL_ENABLED=false
 
+# Experimental FREQ UI controls.
+# false = hide file-area FREQ controls and nodelist file-request actions
+# true = expose file-area FREQ controls and sysop-only nodelist file requests
+ENABLE_FREQ_EXPERIMENTAL=false
+
 # The first host listed will be this host, and could be your BBS or other favourite system
 TERMINAL_HOST=your.ssh.server.com
 TERMINAL_PORT=22
@@ -89,6 +94,11 @@ PERF_LOG_SLOW_MS=500
 # Use {archive} and {dest} placeholders.
 # ARCMAIL_EXTRACTORS=["7z x -y -o{dest} {archive}","unzip -o {archive} -d {dest}"]
 
+# BinkP socket tuning
+# Disable Nagle's algorithm by default to reduce latency for small handshake/control frames.
+# Set to false only if you need to troubleshoot interoperability with a specific peer/network stack.
+# BINKP_TCP_NODELAY=true
+
 
 # PID File locations (defaults to data/run)
 # ADMIN_DAEMON_PID_FILE=data/run/admin_daemon.pid
@@ -117,6 +127,12 @@ FILEAREA_RULE_ACTION_LOG=data/logs/filearea_rules.log
 # received = use date_received (default), written = use date_written
 # ECHOMAIL_ORDER_DATE=received
 
+# Licensing
+# Path to the license file (default: data/license.json)
+# LICENSE_FILE=data/license.json
+# Log invalid license states to PHP error_log (useful for troubleshooting)
+# LICENSE_LOG_INVALID=false
+
 # i18n missing key logging (QA hardening)
 # Set to true to log translation keys that are missing from catalogs.
 # I18N_LOG_MISSING_KEYS=false

CLAUDE.md

@@ -33,19 +33,26 @@ A modern web interface and mailer tool that receives and sends Fidonet message p
  - data/ - runtime data (binkp.json, nodelists.json, logs, inbound/outbound packets)
  - telnet/ - the telnet BBS server (separate from the web interface)
 
+## Credits
+
+ - **CREDITS.md must be kept up to date**: When merging commits from a new contributor, add them to the Contributors table. When adding a new vendor library via composer, add it to the Third-Party Libraries section with its license and authors.
+
 ## Important Notes
  - User authentication is simple username and password with long lived cookie
  - Both usernames and Real Names are considered unique. Two users cannot have the same username or real name
  - The web interface should use ajax requests by api for queries
  - This is for FTN style networks and forums
  - Always write out schema changes. A database will need to be created from scratch and schema/migrations are how it needs to be done. Migration scripts follow the naming convention v<VERSION>_<description>.sql, eg: v1.7.5_description.sql
  - When adding features to netmail and echomail, keep in mind feature parity. Ask for clarification about whether a feature is appropriate to both
+ - **Premium features**: When implementing a feature that requires a valid license (`License::isValid()` or `License::hasFeature()`), update the "Currently Implemented Premium Features" table in `docs/proposals/PremiumFeatures.md` and remove it from the future ideas list if it was listed there.
  - Leave the vendor directory alone. It's managed by composer only
  - **Composer Dependencies**: When adding a new required package to composer.json, the UPGRADING_x.x.x.md document for that version MUST include instructions to run `composer install` before `php scripts/setup.php`. Without this, the upgrade will fail because `vendor/autoload.php` is loaded before setup.php runs.
+ - **Upgrade docs TOC**: When creating or maintaining an `UPGRADING_x.y.z.md` document, always add or update its table of contents so the headings in that file remain navigable and in sync with the document.
  - When updating style.css, also update the theme stylesheets: amber.css, dark.css, greenterm.css, and cyberpunk.css
  - Database migrations are handled through scripts/setup.php.  setup.php will also call upgrade.php which handles other upgrade related tasks.
  - Migrations can be SQL or PHP. Use the naming convention vX.Y.Z_description (e.g., v1.9.1.6_migrate_file_area_dirs.sql or .php).
  - **Migration version numbers**: Before creating a new migration, always check the highest existing version in `database/migrations/` (e.g., `ls database/migrations/ | sort -V | tail -5`). The new migration must be one increment higher than the highest version found — do NOT guess or use a version from a different branch of the version tree. For example, if the latest is `v1.11.0.5_*`, the next is `v1.11.0.6_*`, not `v1.10.19_*`.
+ - **No duplicate indexes**: Do NOT create an explicit `CREATE INDEX` on a column that already has a `UNIQUE` constraint — PostgreSQL automatically creates a unique index for every `UNIQUE` constraint, which serves lookups identically to a plain index. Adding a second index on the same column wastes disk space and doubles write overhead with no benefit.
  - setup.php must be called when upgrading - this is to ensure certain things like file permissions are correct.
 
 ### PHP Migration Patterns
@@ -131,6 +138,7 @@ return function($db) {
  - **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, 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.
+ - **Timezone Display**: Dates and times are generally stored as UTC in the database. When presenting them to users, translate them to the user's own timezone unless there is a specific reason to show raw UTC.
  - Write phpDoc blocks when possible
 
 ## Localization (i18n) Workflow

CREDITS.md

@@ -0,0 +1,42 @@
+# Credits
+
+## Project Author
+
+**Matthew Asham** — creator and primary developer of BinktermPHP.
+
+## Contributors
+
+| Contributor | Contribution |
+|-------------|-------------|
+| Agent 57951 | QWK/QWKE offline mail support |
+| Errol Casey | Extensive testing |
+
+## Third-Party Libraries
+
+### pecee/simple-router
+- **License:** MIT
+- **Author:** Simon Sessingø
+- PHP router library used for all web and API routing.
+
+### twig/twig
+- **License:** BSD 3-Clause
+- **Authors:** Fabien Potencier, Twig Team, Armin Ronacher
+- Template engine used for all HTML rendering.
+
+### phpmailer/phpmailer
+- **License:** LGPL 2.1
+- **Authors:** Marcus Bointon, Jim Jagielski, Andy Prevost, Brent R. Matzelle
+- Email library used for password reset and notification emails.
+
+### phpunit/phpunit *(dev)*
+- **License:** BSD 3-Clause
+- **Author:** Sebastian Bergmann
+- Unit testing framework.
+
+## AI Tooling
+
+BinktermPHP was developed with the assistance of AI language models. We gratefully acknowledge:
+
+- **Anthropic** — Claude (claude.ai / Claude Code)
+- **OpenAI** — ChatGPT / GPT-4
+- **Google** — Gemini

FAQ.md

@@ -1,5 +1,45 @@
 # BinktermPHP Frequently Asked Questions
 
+## Troubleshooting
+
+### Q: The page looks broken after an upgrade — missing features, broken menus, or "loadI18nNamespaces is not defined" errors
+
+**A:** This is a stale service worker cache issue. The old service worker is still serving cached JavaScript and CSS from before the upgrade. You need to unregister the service worker so the browser fetches fresh files.
+
+**Desktop browsers (Chrome / Edge)**
+
+1. Open DevTools — press `F12` or right-click → Inspect
+2. Go to **Application** → **Service Workers**
+3. Click **Unregister** next to the BinktermPHP service worker
+4. Reload the page (`F5`)
+
+**Desktop browsers (Firefox)**
+
+1. Open `about:debugging#/runtime/this-firefox` in the address bar
+2. Find the BinktermPHP worker and click **Unregister**
+3. Reload the page
+
+**Desktop — quick alternative (all browsers)**
+
+A hard refresh bypasses the cache without unregistering the service worker:
+- Windows/Linux: `Ctrl + Shift + R`
+- Mac: `Cmd + Shift + R`
+
+**Mobile (Chrome on Android)**
+
+1. Open Chrome's menu (three dots) → **Settings** → **Privacy and security** → **Clear browsing data**
+2. Select **Cached images and files** and **Cookies and site data** for the BinktermPHP site
+3. Tap **Clear data**, then reload
+
+**Mobile (Safari on iOS)**
+
+1. Go to **Settings** → **Safari** → **Clear History and Website Data**
+2. Reload the BinktermPHP site
+
+**Note:** After clearing, you will be logged out and will need to sign in again. This is normal.
+
+---
+
 ## Support
 
 ### Q: Where can I get support?
@@ -436,6 +476,31 @@ Public nodes can also poll as a fallback, though the hub will deliver mail direc
 
 ---
 
+## Database
+
+### Q: The database stats page shows high sequential scan counts on some tables. Is this a problem?
+**A:** Not necessarily. PostgreSQL uses sequential scans when they are more efficient than index scans, which is often the case for small tables or queries where a large fraction of rows would be returned. Here are the common cases you may see in BinktermPHP:
+
+**Small tables (users_meta, user_settings, mrc_state)**
+For tables with only a few hundred or thousand rows, PostgreSQL's query planner will almost always prefer a sequential scan — the overhead of walking an index is greater than simply reading the table directly. High seq scan counts here are expected and correct behaviour, not an indexing gap.
+
+**High-frequency daemon tables (mrc_outbound, mrc_state)**
+The MRC daemon polls these tables continuously (multiple times per second). Because these tables are very small, every poll results in a sequential scan. The counts look alarming but reflect normal operation.
+
+**OR-condition queries (chat_messages, shared_messages)**
+Queries that filter on `col_a = ? OR col_b = ?` cannot use a single B-tree index to satisfy both conditions simultaneously. PostgreSQL must either do a seq scan or merge two separate index scans (bitmap OR). For moderate table sizes or if the planner estimates a large result set, it will choose a seq scan even when indexes exist on both columns individually. This is a structural query pattern — adding more indexes will not change the planner's decision.
+
+**When to investigate further**
+A high seq scan ratio is worth investigating when:
+- The table is large (tens of thousands of rows or more)
+- The query is selecting a small, specific subset of rows (highly selective filter)
+- You can see a long-running or slow query in the Query Performance tab that targets that table
+- `pg_stat_user_tables.seq_tup_read` is very large relative to `idx_tup_fetch`
+
+In those cases, review the actual queries and consider adding a targeted index. For the tables listed above, no additional indexing is needed.
+
+---
+
 ## WebDoors
 
 ### Q: How do I add a connection to my text-based BBS?