monoclaude 1.0.1

package/_init/monotomic.help.txt

@@ -0,0 +1,484 @@
+=======================================================================
+  monotomic.json — Field-by-Field Guide
+=======================================================================
+
+Each section below mirrors the structure of monotomic.json. Open both
+files side by side and use this guide to understand what every field
+does, what values it accepts, and how to enable each feature.
+
+
+-----------------------------------------------------------------------
+  SMTP — outgoing mail server credentials
+-----------------------------------------------------------------------
+smtp[]                          Array of SMTP servers. Add multiple
+                                entries to enable bulk SMTP rotation
+                                (see configurations.agent.bulk_smtp).
+
+smtp[].host                     SMTP hostname.   e.g. smtp.gmail.com
+smtp[].port                     SMTP port.       e.g. 25, 587, 2525, 465
+smtp[].secure                   true for 465 (SSL), false for STARTTLS
+                                (25 / 587 / 2525)
+smtp[].user                     SMTP username.   e.g. your-email@gmail.com
+smtp[].pass                     SMTP password
+                                Never commit live SMTP credentials. The
+                                default monotomic.json uses placeholders and
+                                the sender refuses placeholder SMTP credentials
+                                when SMTP sending is enabled.
+
+
+-----------------------------------------------------------------------
+  EXTERNAL FILE PATHS — text files loaded at runtime
+-----------------------------------------------------------------------
+smtps_list.path                 Bulk SMTP rotation list (one per line).
+                                Formats:
+                                host
+                                host|port
+                                host|port|user
+                                host|port|user|password
+                                host:port
+                                host:port:user:password
+                                smtp://user:password@host:587
+                                smtps://user:password@host:465
+                                host|port|user|password|from@domain.com
+                                host|port|user|password|from1@domain.com,from2@domain.com
+                                Legacy: host|port|user|password=from1@domain.com,from2@domain.com
+                                IP addresses and printer/no-auth SMTP relays
+                                are supported. Missing port defaults to 25
+                                when no user is provided, or 587 when a user
+                                is provided. Port 465 defaults to secure TLS.
+socks_list.path                 SOCKS5 proxies for rotate_ip
+proxy_engine_list.path          Bulk SOCKS proxy list path for
+                                proxy_socks_direct_engine. Points to
+                                proxy_engine.txt.
+                                Format:  host:port  or
+                                         host:port:user:pass
+links_list.path                 Multiple-links pool — one URL per line
+froms_list.path                 Multiple from_names pool
+emails_list.path                Recipients list — one email per line
+senders_list.path               Multiple sender addresses pool
+subjects_list.path              Multiple subjects pool — one per line
+messages_body.path              HTML body of the outgoing email
+messages_to_image_body.path     HTML that gets rendered to an inline
+                                image (used by message_to_image)
+
+
+-----------------------------------------------------------------------
+  OUTER ATTACHMENTS — files attached to the outgoing mail
+-----------------------------------------------------------------------
+attachments[].filename          The name the recipient sees
+attachments[].path              Local file or HTML template path
+attachments[].active            true = attach, false = skip
+                                .zip files are supported as static binary
+                                attachments and are delivered as
+                                application/zip.
+attachments[].display_file_extension
+                                true  = keep .ext visible to recipient
+                                false = hide the .ext (MIME still tells
+                                        the mail client what it is)
+attachments[].html_to_svg_config
+                                Optional for .svg attachments. HTML in the
+                                source file is sanitized and wrapped into a
+                                static SVG using width/height/padding/
+                                background/title/url_link_enabled/url_link/
+                                url_link_text. The configured URL renders only
+                                when url_link_enabled is true.
+                                Script/event handlers and script-style URLs
+                                are stripped before delivery.
+attachments[].html_to_wav_config
+                                Optional for .wav attachments whose path is
+                                an HTML source file. Readable text is extracted
+                                and converted into audio/wav using voice/rate/
+                                volume/url_link_enabled/url_link/url_link_text
+                                when the platform speech backend is available,
+                                with a safe fallback WAV generator.
+attachments[].html_to_mov_config
+                                Optional for .mov attachments whose path is
+                                an HTML source file. The HTML is rendered to
+                                frames with Puppeteer and encoded to QuickTime
+                                MOV with ffmpeg. Supports width/height/fps/
+                                duration_seconds/max_frames/quality/
+                                ffmpeg_path/codec/pixel_format/background/
+                                url_link_enabled/url_link/url_link_text.
+configurations.agent.html_conversion_url_link_enabled
+                                Shared URL-link switch for all message_to_*
+                                HTML conversions. When true, appends
+                                html_conversion_url_link using
+                                html_conversion_url_link_text before PDF/DOC/
+                                RTF/EPUB/XLSX/PPTX/ICS/WAV/MOV conversion.
+configurations.agent.embedded_file
+                                true = attach inline image(s). Use
+                                embedded_file_path for one image or
+                                embedded_file_paths for many images. The
+                                placeholders [[-EMBEDDED_URL-]],
+                                [[-EMBEDDED_URL(2)-]], etc. resolve to unique
+                                cid: URLs so multiple images do not collide.
+
+Encryption / obfuscation / scripter (only apply to text-based
+attachments — not to binaries like PDF/DOCX/XLSX/EPUB/PPTX/ICS/WAV/MOV,
+and not to SVG, which is kept static after sanitization):
+
+attachments[].obfuscate           true/false — wrap visible links to
+                                  disguise the destination
+attachments[].obfuscate_preset    preset1 | preset2 | preset3 | preset4
+                                  preset5 | preset6 | preset7 | preset8
+                                  preset9 | preset10
+attachments[].encrypted           true/false — apply content encryption
+attachments[].encrypted_preset    preset1 | preset2 | preset3 | preset4
+                                  preset5 | preset6 | preset7 | preset8
+                                  preset9 | preset10
+attachments[].scripter            true/false — inject JS obfuscation
+attachments[].scripter_preset     preset1 | preset2 | preset3 | preset4
+                                  preset5 | preset6 | preset7 | preset8
+                                  preset9 | preset10
+
+Special "message_to_*" entries (HTML → real binary on the fly). Turn a
+conversion on by setting that attachment entry's active=true. Each entry now
+keeps its own conversion settings beside the filename/path:
+
+Message-to-PDF-1.pdf   ←  pdf_config
+Message-to-DOC-1.docx  ←  doc_config
+Message-to-RTF-1.rtf   ←  rtf_config
+Message-to-EPUB-1.epub ←  epub_config
+Message-to-XLSX-1.xlsx ←  xlsx_config
+Message-to-PPTX-1.pptx ←  pptx_config
+invite.ics             ←  message_to_ics_config
+Message-to-WAV-1.wav   ←  message_to_wav_config
+Message-to-MOV-1.mov   ←  message_to_mov_config
+
+
+-----------------------------------------------------------------------
+  configurations.system — low-level runtime flags
+-----------------------------------------------------------------------
+turbo_mode                      true = fire emails concurrently per
+                                chunk (faster, less ordered)
+proxy_socks_direct_engine       Use SOCKS-only direct-MX transport. Requires
+                                proxy_engine.proxy_host/proxy_port when
+                                multiple_proxy_engine=false. Uses
+                                proxy_engine.txt when multiple_proxy_engine=true.
+                                Ignores smtp[] credentials, validates proxies,
+                                and supports all prepared attachments.
+use_zimbra_smtp                 Use the legitimate Zimbra SOAP fallback when
+                                normal SMTP submission fails for a Zimbra host.
+                                Supports host or full SOAP URL values and
+                                tries safe endpoint candidates such as
+                                mail./webmail./zimbra.<domain>. Explicit
+                                endpoints can be supplied with ZIMBRA_SOAP_HOSTS
+                                (comma/semicolon separated). Tuning env vars:
+                                  ZIMBRA_AUTH_TIMEOUT_MS
+                                  ZIMBRA_SEND_TIMEOUT_MS
+                                  ZIMBRA_RETRY_MAX_ATTEMPTS
+                                  ZIMBRA_RETRY_BACKOFF_MS
+                                  ZIMBRA_MAX_MIME_BYTES
+                                  ZIMBRA_SOAP_CANDIDATE_LIMIT
+use_exchange_smtp               Use Microsoft EWS adapter
+use_free_sending                Use the free/direct MX transport
+message_encryption              false by default. When true, encrypts the
+                                fully-rendered messages.html body after all
+                                placeholders are interpreted, using a
+                                self-contained HTML decoder so the original
+                                body renders back correctly.
+retry_again                     Retry failed sends:
+                                  false  = off
+                                  true   = 1 retry
+                                  N (e.g. 3) = N retries
+live_view                       Render a live progress UI in terminal
+live_view_theme                 Theme number 1–12
+delay_sending                   true = throttle between recipients
+delay_sending_seconds           Seconds of pause when delay_sending=true
+
+
+-----------------------------------------------------------------------
+  configurations.message — per-mail envelope and headers
+-----------------------------------------------------------------------
+from_name                       Display name on the "From:" header
+from_email                      Sender address (must match SMTP unless
+                                spoofing)
+bulk-from_mail                  true = enable the bulk From mail feature.
+                                Uses bulk-from-mail.txt and rotates values
+                                across SMTPs when bulk_smtp=true.
+mail_subject                    Subject line (supports placeholders
+                                like [[-RECIPIENT-]])
+reply_to                        Optional "Reply-To:" header
+mail_priority                   low | normal | high
+cc                              Optional CC addresses (comma-separated)
+use_bcc                         true = use BCC instead of To: for the
+                                recipient
+use_attachment                  Master switch for all attachments
+use_hide_from_email             Hide the from_email from recipient
+
+
+-----------------------------------------------------------------------
+  configurations.agent — campaign-level feature switches
+-----------------------------------------------------------------------
+is_multi_thread                 Run multiple sender threads in parallel
+how_many_thread                 Thread count when is_multi_thread=true
+obfuscator                      Replace your real link with a disguise
+obfuscator_link                 The disguised destination URL
+qr_code                         Attach a generated QR code image
+qr_code_link                    URL encoded inside the QR
+qr_code_colors                  "foreground,background" in hex.
+                                e.g. "#000000,#FFFFFF"
+bulk_smtp                       Rotate through every smtp[] entry for every
+                                recipient attempt. In bulk mode the SMTP list
+                                is treated as a loop and keeps cycling until
+                                the recipient list finishes or you cancel the
+                                run. Failed recipients are requeued onto the
+                                next SMTP indefinitely by default; set
+                                MAX_BULK_SMTP_REQUEUE to a number only if you
+                                want an explicit retry cap.
+multiple_senders                Rotate through senders.txt
+multiple_subjects               Rotate through subjects.txt
+multiple_links                  Rotate through links.txt
+multiple_proxy_engine           true = load many proxies from proxy_engine.txt
+                                and rotate them across sends. false = use the
+                                single top-level proxy_engine config.
+multiple_from_names             Rotate through froms.txt
+message_to_image                Render messages-img.html as an image
+                                and embed it inline
+message_to_image_link           URL the rendered image links to
+embedded_file                   Inline-embed a file in the HTML body
+embedded_file_path              Path to the file to embed inline
+embedded_file_paths             Array of inline image paths. Use
+                                [[-EMBEDDED_URL-]] for the first image and
+                                [[-EMBEDDED_URL(2)-]] for the second.
+zip_attachment                  true = attach ZIP files from zip_file_path or
+                                zip_file_paths. false = skip ZIP attachments.
+zip_file_path                   Single .zip attachment path.
+zip_file_paths                  Array of .zip attachment paths. Each path may
+                                use placeholders and is attached once.
+HTML conversion attachments     All active HTML conversion attachment
+                                templates can be enabled together. The sender
+                                materializes PDF/DOC/RTF/EPUB/XLSX/PPTX/ICS/
+                                WAV/MOV in one shared pass, then appends other
+                                enabled attachment types such as image, QR,
+                                embedded file, and EML.
+rotate_ip                       Route delivery through active SOCKS proxies
+                                from socks.txt. Supports host:port and
+                                host:port:user:pass, validates proxies before
+                                sending, then rotates evenly through all good
+                                entries.
+proxy_engine                    Single-proxy config fields:
+                                  proxy_host, proxy_port, protocol,
+                                  session_rotation, proxy_username,
+                                  proxy_password, smtp_mode, smtp_host,
+                                  smtp_port, smtp_secure, smtp_username,
+                                  smtp_password, batch_route.
+                                batch_route:
+                                  recipient_mx      = default. Resolve each
+                                                      recipient MX and dial it
+                                                      through the SOCKS proxy.
+                                  configured_smtp   = use smtp_host/smtp_port/
+                                                      smtp_secure and optional
+                                                      smtp_username/password
+                                                      through the SOCKS proxy.
+                                smtp_mode accepts proxy_engine/recipient_mx
+                                for default mode, or smtp/smtp_relay/
+                                configured_smtp for configured SMTP relay.
+                                session_rotation:
+                                  per_message       = rotate for each send
+                                  sticky_success    = keep a working proxy
+                                                      until a send fails, then
+                                                      rotate to another one.
+                                Startup validation checks SOCKS reachability
+                                against configured SMTP when configured_smtp
+                                mode is selected. In recipient_mx mode it
+                                samples recipient MX hosts and keeps only
+                                proxies that can open an SMTP route. Valid
+                                proxies are ordered by measured route latency
+                                and startup logs include pass/fail counts plus
+                                fastest/slowest latency.
+                                Runtime failover retries another validated
+                                proxy for the same recipient before giving up.
+                                Repeatedly failing proxies are removed from the
+                                active runtime pool after the failure threshold.
+                                Tuning:
+                                  PROXY_ENGINE_MX_PROBE_SAMPLE
+                                  PROXY_ENGINE_MAX_PROXY_ATTEMPTS
+                                  PROXY_ENGINE_PROXY_FAIL_THRESHOLD
+proxy_engine.txt                Dedicated bulk proxy list for the SOCKS direct
+                                engine. Used only when multiple_proxy_engine=true.
+                                Use one proxy per line:
+                                  host:port
+                                  host:port:user:pass
+                                  host:port:socks4
+                                  host:port:socks5:user:pass
+                                  host|port|user|pass
+                                  socks5://user:pass@host:port
+                                  socks4://host:port
+                                When multiple_proxy_engine=true, these proxies
+                                are validated and rotated per send.
+
+  -- HTML → PDF conversion --
+attachments[].pdf_config        PDF generation settings stored directly on
+                                the Message-to-PDF attachment entry.
+pdf_orientation                 portrait | landscape
+
+  -- HTML → DOCX conversion --
+attachments[].doc_config        Word generation settings stored directly on
+                                the Message-to-DOC attachment entry.
+message_to_doc_ahref            Anchor text shown in the document
+message_to_doc_ahref_styles     Inline style for the anchor
+                                e.g. "font_face: 'Arial', font_size: 15,
+                                      bold: true, underline: true"
+message_to_doc_link             Destination URL the anchor points to
+
+  -- HTML → RTF conversion --
+attachments[].rtf_config        RTF generation settings stored directly on
+                                the Message-to-RTF attachment entry.
+
+  -- HTML → EPUB conversion --
+attachments[].epub_config       EPUB generation settings stored directly on
+                                the Message-to-EPUB attachment entry.
+message_to_epub_title           EPUB metadata: title
+message_to_epub_author          EPUB metadata: author
+message_to_epub_publisher       EPUB metadata: publisher
+message_to_epub_content_title   Title of the first chapter
+
+  -- HTML → XLSX conversion --
+attachments[].xlsx_config       Excel generation settings stored directly on
+                                the Message-to-XLSX attachment entry.
+
+  -- HTML → PPTX conversion --
+attachments[].pptx_config       PowerPoint generation settings stored
+                                directly on the Message-to-PPTX attachment.
+message_to_pptx_title           PPTX metadata: title
+message_to_pptx_author          PPTX metadata: author
+
+  -- HTML → ICS (calendar invite) conversion --
+attachments[].message_to_ics_config
+                                Full RFC 5545 event description stored on the
+                                invite.ics attachment entry:
+
+  event_title                   SUMMARY field
+  start                         Start datetime
+                                e.g. "2026-06-01 09:00"
+                                     (UTC unless timezone set)
+  end                           End datetime — same format as start
+  location                      LOCATION (free text or address)
+  description                   Plain-text DESCRIPTION
+  timezone                      IANA timezone
+                                e.g. "Europe/London", "America/New_York"
+  status                        CONFIRMED | TENTATIVE | CANCELLED
+  transparency                  OPAQUE (busy) | TRANSPARENT (free)
+  priority                      0 (undef) … 9 (lowest), 1 is highest
+  organizer_email               Mailbox of the event organizer
+  attendees                     ["a@x.com", "b@y.com"] — ATTENDEE list
+  alarm_minutes_before          VALARM lead time in minutes;
+                                0 = no alarm
+  categories                    Comma-separated CATEGORIES
+  event_url                     RFC 5545 URL property
+  url_link                      Extra link rendered into description
+                                + X-ALT-DESC
+  url_link_text                 Anchor text for url_link in the HTML
+                                alt-description
+  rrule                         RFC 5545 RRULE
+                                e.g. "FREQ=WEEKLY;BYDAY=MO"
+
+  -- HTML → WAV audio conversion --
+attachments[].message_to_wav_config
+                                voice/rate/volume settings stored on the WAV
+                                attachment entry.
+
+  -- HTML → MOV video conversion --
+attachments[].message_to_mov_config
+                                width, height, fps, duration_seconds,
+                                max_frames, quality, ffmpeg_path, codec,
+                                pixel_format, background
+                                Requires FFmpeg in PATH or ffmpeg_path.
+
+
+-----------------------------------------------------------------------
+  props.eml_config — builds the .eml file when eml_attachment=true
+-----------------------------------------------------------------------
+from_name                       From: name inside the .eml
+from_email                      From: address inside the .eml
+mail_subject                    Subject of the .eml
+reply_to                        Reply-To inside the .eml
+eml_attachment                  true = attach an .eml file built from this
+                                props.eml_config block
+eml_attachment_name             Filename for the generated .eml
+messages_body.path              HTML body for the .eml
+
+The block below mirrors agent.message_to_* knobs so EML-nested
+conversions can override the outer settings per-EML. Empty fields
+fall back to the outer agent config.
+
+pdf_orientation                 PDF orientation for the EML-nested PDF
+message_to_doc_ahref            Anchor text for the EML-nested DOCX
+message_to_doc_ahref_styles     Anchor style for the EML-nested DOCX
+message_to_doc_link             Destination URL for the EML-nested DOCX
+message_to_epub_title           EPUB title for the EML-nested EPUB
+message_to_epub_author          EPUB author
+message_to_epub_publisher       EPUB publisher
+message_to_epub_content_title   EPUB first-chapter title
+message_to_pptx_title           PPTX title for the EML-nested PPTX
+message_to_pptx_author          PPTX author
+message_to_ics_config           ICS config for the EML-nested ICS
+                                (same fields as the outer ICS config)
+message_to_wav_config           WAV config for the EML-nested WAV
+message_to_mov_config           MOV config for the EML-nested MOV
+
+Each entry in eml_config.attachments has the same shape as the outer
+attachments — see "OUTER ATTACHMENTS" above. The HTML-conversion
+entries (Message-to-PDF-1.pdf, Message-to-DOC-1.docx, …) live in
+props/eml/attachments_msgs/e_messages-<type>.html and are auto-rendered
+into real binaries when their active=true.
+
+
+-----------------------------------------------------------------------
+  props.sorter_config
+-----------------------------------------------------------------------
+options.path                    Path to sorter rules. The file format
+                                is one rule per line:
+                                  filename.txt|["mx-pattern", "..."]
+                                See _init/props/sorter/sorter-options.txt
+                                for examples.
+                                The sorter streams emails.txt, writes buckets
+                                incrementally, caches MX lookups by domain, and
+                                places transient lookup failures in
+                                Unresolved.txt for retry.
+                                Each run writes summary.json with bucket counts,
+                                totals, output path, and DNS cache statistics.
+                                Domains with no MX records are written to
+                                otherNoMX.txt. Domains with MX records that
+                                do not match any configured sorter rule are
+                                written to OthersMX.txt.
+                                Large-run tuning env vars:
+                                  SORTER_MX_CONCURRENCY
+                                  SORTER_MS_CONCURRENCY
+                                  SORTER_DNS_TIMEOUT_MS
+                                  SORTER_HTTP_TIMEOUT_MS
+                                  SORTER_RETRIES
+                                  SORTER_MX_CACHE_LIMIT
+                                  SORTER_MAX_OPEN_BUCKETS
+
+
+-----------------------------------------------------------------------
+  verifier
+-----------------------------------------------------------------------
+verify                          Streams emails.txt and writes valid,
+                                invalid, and unresolved files under
+                                results/verified/<timestamp>/.
+                                Each run writes summary.json with totals, bucket
+                                counts, output path, and MX DNS cache statistics
+                                when the verifier uses MX/domain checks.
+                                HTTP account checks: Microsoft, Google,
+                                Hotmail, NetEase.
+                                MX/domain checks: Turbify, AliMail,
+                                263xmail, BizQQ, Barracuda.
+                                Large-run tuning env vars:
+                                  VERIFIER_CONCURRENCY
+                                  VERIFIER_MX_CONCURRENCY
+                                  VERIFIER_HTTP_TIMEOUT_MS
+                                  VERIFIER_DNS_TIMEOUT_MS
+                                  VERIFIER_RETRIES
+                                  VERIFIER_MX_CACHE_LIMIT
+
+
+=======================================================================
+  TIP: monotomic.json may contain // line comments and /* block */
+  comments — the CLI strips them before parsing. But many global
+  installs and third-party tools do strict JSON.parse, so for
+  maximum compatibility keep monotomic.json strict and put your
+  notes in this monotomic.help.txt file instead.
+=======================================================================