================================================================================
  SitRepTools — Program Overview
  Version 1.1.0
  Stephen Clay McGehee, KN4AM  |  SitRepNet.com
================================================================================

PURPOSE
-------
A utility for net operators to consolidate, clean, and filter JS8Call
area assessment and situation report records so they can be imported
into JS8Reporter for display on a map.


TWO FORM TYPES SUPPORTED
-------------------------
  F!505  Area Assessment
           32-field infrastructure condition scores (0–3 per field)

  F!104  Situation Report
           3-character CSA status code:
             Char 1 — Status:  1 = Normal  2 = Degraded  3 = Problems
             Char 2 — Sitrep: 0 = none  E = active
             Char 3 — Alert:  0 = none  E = active


FIVE OPERATIONS  (Operations menu)
-----------------------------------
  Combine F!505 Records
    Reads all .txt/.csv files in a folder.  Validates, deduplicates,
    sorts by timestamp, writes a single merged F!505 output file.
    Use when merging export files received from multiple stations.

  Extract F!505 Records
    Reads one F!505 file.  Filters by date/time range and/or
    Maidenhead grid prefix.  Writes filtered output.
    Use when a subset of a larger collection is needed.

  Combine F!104 Records
    Same as Combine F!505 Records, but for F!104 Situation Reports.

  Extract F!104 Records
    Same as Extract F!505 Records, but for F!104 Situation Reports.

  NCS Check-In Tools
    Interactive tool for logging and organizing net check-ins in
    real time.  See NCS CHECK-IN TOOLS section below.


PROCESSING PIPELINE  (same for both form types)
-------------------------------------------------
  1. Parse plain-text or CSV input files
  2. Validate records
       F!505 — must have a 32-char score string and at least one of:
               grid square, state, or city
       F!104 — must have a CSA status code and at least one of:
               grid square or state
  3. Apply IGNORE.TXT callsign filter  (CSV input only)
  4. Remove duplicates
       F!505 — duplicate key: score string + grid + datecode
       F!104 — duplicate key: CSA code + grid + datecode
  5. Apply date/time and grid prefix filters  (Extract only)
  6. Sort by timestamp  (records with no timestamp go to the end)
  7. Write output file


THREE EXPORT FORMATS  (Preferences > Output — applies to both types)
----------------------------------------------------------------------
  Minimal  (default)
    Compact format optimized for JS8Reporter import and radio use.
    F!505 — no marker:  33333333333333333333333333333333 GR[EL99HC] #CTKP
    F!104 — marker always included:  F!104 200 GR[EL99HC]

  Minimal + Date Decode
    Same as Minimal, but appends a decoded human-readable UTC timestamp.
    F!505:  33333333333333333333333333333333 GR[EL99HC] #CTKP 2026-05-18 14:30 UTC
    F!104:  F!104 200 GR[EL99HC] 2026-05-18 14:30 UTC

  Full
    All fields preserved, including the form marker, state, grid,
    city (F!505 only), and datecode.
    F!505:  F!505 33333333333333333333333333333333 ST[FL] GR[EL99HC] CT[VOLUSIA] #CTKP
    F!104:  F!104 200 ST[FL] GR[EL99HC] #CTKP


OUTPUT SUMMARY  (shown in log after every run)
-----------------------------------------------
  Both form types:
    Records processed    Duplicates removed    IGNORE.TXT removed
    Invalid / skipped    Records in output     Date range
    Grid squares covered

  F!104 additionally shows a status breakdown:
    1 Normal count    2 Degraded count    3 Problems count
    ALERT active count  (records where CSA char 3 = E)


NCS CHECK-IN TOOLS  (Operations > NCS Check-In Tools…)
-------------------------------------------------------
  A persistent window used throughout a net operation to log
  check-ins as they are received and maintain an organized output
  file updated after each entry.

  Workflow
    1. Browse to (or type) the path of a Received check-in file and
       a Processed check-in file.  Default paths are saved in
       Preferences.
    2. Paste or type one or more received check-in lines into the
       input area.
    3. Click Process.
       — Each line is appended to the Received file (the permanent log).
       — The Processed file is rewritten with the current organized view.
       — The input area is cleared; a status line reports the counts.
    4. Repeat for each check-in or batch received during the net.

  Received file
    A plain-text log of every check-in line, in the order received.
    Lines are appended; the file is never overwritten.

  Processed file
    Rewritten after every Process action.  Two sections:

      ===== With Traffic
        Lines where the TFC field contains a number.
        Format:  CS / N / ST / <number>

      ===== No Traffic
        Lines where the TFC field contains no number.
        Format:  CS / N / ST

    Within each section, check-ins appear in the order they were
    added to the Received file.

  Callsign (CS) validation
    The format includes the callsign two or three times.  All CS
    entries are compared; if at least two agree the consensus value
    is used.  If no two entries agree the entire raw line is kept
    and prefixed with "? " to flag it for manual review.

  TFC field
    If the field contains a number, only the number is kept and any
    surrounding text is discarded.  If no number is present, the
    field is treated as blank and the check-in goes to No Traffic.

  TXT field (format 2 only)
    Discarded; not included in output.

  Check-in formats  (Preferences > NCS Check-In Tools)
    Two formats are supported, selectable per net:

      CS CS / N / ST / TFC / CS   (3 callsign entries; TFC before last CS)
      CS CS / N / ST / TXT / TFC  (2 callsign entries; free text before TFC)

    Field key:
      CS  = Callsign      N  = Name
      ST  = State         TFC = Traffic count
      TXT = Free text (discarded)


OTHER FEATURES
--------------
  IGNORE.TXT       Optional callsign exclusion list; applies to all
                   four operations (CSV input only)

  Preferences      Default input/output folders; export format;
                   save Combine summary to a .txt file;
                   NCS Check-In default file paths and format

  Include ALERT    F!505 only — optionally appends ALERT to output
                   lines where the keyword was present on import;
                   F!104 alert status is always in the CSA string

  Auto-update      Optional startup check for new releases at
                   SitRepNet.com; fails silently when offline

  Output files     Directly importable into JS8Reporter:
                   File > Import F505 File…   for F!505 output
                   File > Import F!104 File…  for F!104 output


DEFAULT OUTPUT FILENAMES
-------------------------
  Combine F!505 Records:   f505_combined_YYYYMMDD_HHMMSS.txt
  Extract F!505 Records:   f505_extract_YYYYMMDD_HHMMSS.txt
  Combine F!104 Records:   f104_combined_YYYYMMDD_HHMMSS.txt
  Extract F!104 Records:   f104_extract_YYYYMMDD_HHMMSS.txt


================================================================================
  End of SitRepTools Program Overview
================================================================================
