> Draft ? This proposal was generated by AI and may not have been reviewed for accuracy.

File Area Echomail Comments

Overview

A file area can be linked to an echomail area to enable threaded comments on individual files. This is a community edition feature available to all installations.

Because the backing store is real echomail, FTN users on other systems participate transparently ? their replies appear as comments in the file area view with no special configuration required on either end.

How It Works

• Each file area has an optional linked echomail area configured by the sysop
• When a user posts the first comment on a file, a new echomail post is created in the linked area with: - Subject set to the filename, so the thread is human-readable on any FTN software - Kludge line `^AFILEREF: <area_tag>@<domain> <filename> <sha256>` embedded in the message, carrying the fully qualified networked file area identifier, filename, and a SHA-256 hash of the file content as defined by `docs/LSC/LSC2 - FILEREF Kludge.txt`
• Subsequent comments are standard echomail replies to that thread root, building the comment tree naturally using normal FTN threading

Comment Display ? Matching Messages to Files

The file detail page queries the linked echomail area using a two-tier strategy:

1. Kludge match (authoritative): messages whose `^AFILEREF` kludge matches the area tag, filename, and SHA-256 hash of the local file ? precise, no false positives
2. Subject match (fallback): messages whose subject equals the filename ? catches replies and posts from nodes that propagated the thread without generating the kludge

BinktermPHP-to-BinktermPHP comment linking is exact via the kludge. Threads from other FTN software still display correctly as long as they follow the subject convention.

Network Behaviour

The ^AFILEREF kludge travels with the thread root message through the FTN network. Any BinktermPHP node that carries both the same networked file area and the same networked echomail area can parse the kludge, verify the file hash, and display comments correctly without any out-of-band coordination.

Nodes running other BBS software ignore the kludge and see a normal echomail thread. Their replies propagate back through the network and appear as comments on BinktermPHP nodes via the subject fallback.

Configuration

Configured per file area. The sysop selects a linked echomail area from the file area admin page. All files in that file area share the same linked echomail area for comments.

A file area with no linked echomail area simply has no comment functionality ? the comment UI is not shown.

Schema

No dedicated comment mapping table is required. The file area ? echomail area linkage is stored in the file areas configuration (a new nullable comment_echoarea_id foreign key column on the file areas table).

Message-to-file association is resolved at query time via the kludge and subject matching described above.

The files table should include a sha256 column for hash-based kludge matching if not already present.

Required migrations

• Add `comment_echoarea_id` (nullable FK to `echoareas.id`) to the file areas table
• Add `sha256` column to the `files` table (populated on upload and on a one-time backfill for existing files)

UI

File listing

A comment count badge (speech bubble icon + count) is shown on file rows where the linked echomail area has at least one matching message. Files with no comments show no badge, keeping the listing clean. Clicking the badge opens the file info modal scrolled to the comments section.

File info modal

The canonical place to read and post comments. A mini echomail thread is displayed below the file metadata.

Thread display: - Shows the 5 most recent comments by default; a "Show all N comments" control expands the full thread - No per-branch collapse ? once expanded, the full thread is visible - Threaded display with indentation, capped at 3 levels deep; replies beyond level 3 render flat at level 3 - Per message: author name, date, and plain text body only ? no kludge lines, no tearlines, no ANSI rendering - Author name follows the name policy of the linked echomail area (real name or username), consistent with how the area handles regular echomail

Reply form: - Hidden behind a "Leave a comment" button; expands inline when clicked - Body textarea only ? subject is inherited from the thread root, to-address is implicit - Visible to logged-in users only - Guests see a blurred mock comment thread with a "Login to read" overlay instead of the real comments and reply form

File preview

Comments are not shown in the file preview ? users are focused on the file content there and the comment UI would be out of place.

File area admin

Two options for linking a comments area: The UI uses a combobox-style control ? the sysop can either select an existing echomail area from the dropdown or type a new tag to create one:

• Selecting an existing area ? links it directly, no area is created
• Typing a new tag ? creates the area. New areas are local by default, with one exception: if the file area's domain is `lovlynet` and the tag is `LVLY_FILECHAT`, the area is created with domain `lovlynet` (never local)

The pre-filled suggested tag when the sysop opens the control: - LVLY_FILECHAT if the file area's domain is lovlynet - <FILEAREATAG>-COMMENTS if the file area tag is 31 characters or fewer - <FILEAREATAG> otherwise The linked echomail area can also be cleared to disable comments for that file area.

Echomail area view

Messages posted via file comments appear as normal echomail and are readable in the echomail area view on any node.

Permissions

Posting comments requires the user to be logged in. Posting permissions otherwise follow the linked echomail area ? if the area is sysop-only, only sysops can comment.

Guests see a blurred mock comment section with a "Login to read" overlay in place of the real thread and reply form.

Moderation

Comment moderation is handled through the echomail area itself ? sysops delete unwanted comments via the normal echomail admin interface. There is no dedicated moderation UI in the file area view at this time; this may be revisited in a future iteration.

SHA-256 Hashing

• Computed and stored on file upload
• Computed and stored on TIC file ingest
• One-time backfill migration for existing files; files that cannot be read during backfill fall back to subject matching only

Comment Count Caching

The comment count badge in the file listing must not query the echomail table live per file row. Counts are cached ? either as a denormalised column on the files table or in a small summary table ? and updated when:

• A new comment is posted via the file area UI
• Echomail is received from the network and matched to a file via kludge or subject

Cache invalidation strategy and storage details to be determined at implementation time.

Scope and Limitations

• One echomail area per file area (all files share it). Per-file echomail areas are not supported.
• The comment thread is only as complete as the local echomail store ? messages not yet received from uplinks won't appear.
• SHA-256 backfill for existing files is a best-effort operation; files that cannot be read during backfill will fall back to subject matching only.