Update the public pages to 0.2.1

2026-10-07 08:16:41 +00:00
10 changed files with 542 additions and 3 deletions
@@ -1,5 +1,39 @@
-# Nolimit News: releases
+# Nolimit News
-This repository holds the release zips for the Nolimit News WordPress plugin, and nothing else. WordPress reads it to offer updates.
+![Nolimit News — writing an issue with columns and shop products](assets/hero.png)
-Download the latest zip from Releases.
+Newsletters for WordPress and WooCommerce, without the monthly bill per
 subscriber. Write an issue in the block editor, keep your lists, put a signup
 form anywhere, send it through your own mail setup, and show every issue as an
 archive on your own site. **Nothing leaves your site** — no click tracking, no
 telemetry, no account, no paid tier.
 ## Install
 1. Download `nolimit-news.zip` from the [latest release](https://gitea.nolimit.dk/kw/nolimit-news-dist/releases/latest).
 2. **Plugins → Add New → Upload Plugin**, then activate.
 3. Set up a real mail sender before the first send — [the setup guide](docs/SETUP.md)
   says why, and walks through the first ten minutes.
 Later versions arrive in **Dashboard → Updates** like any other plugin.
 ## Documentation
 - [Overview](docs/README.md) — what it does, and what it deliberately does not
 - [Setting it up, and knowing it works](docs/SETUP.md) — mail, the first issue,
  importing from Mailchimp, and what to do when something is wrong
 - [Hooks and integration](docs/CONTRACT.md) — for developers: what the plugin
  offers to other plugins and themes, and what it stores
 ## More of it
 | | |
 |---|---|
 | ![Sending an issue](assets/screenshots/sending.png) | **Sending.** Preview, test, send now or schedule; how many were mailed and, if you switch it on, how many opened it. A send that fails stops itself and picks up where it left off. |
 | ![Lists](assets/screenshots/lists.png) | **Lists.** Public lists the signup form offers and private ones you fill yourself, with pending, subscribed and unsubscribed counted apart. |
 | ![Subscribers](assets/screenshots/subscribers.png) | **Subscribers.** Double opt-in, so *confirmed* means the person followed their own link — and an import from Mailchimp that asks people to confirm. |
 | ![Templates](assets/screenshots/templates.png) | **Templates.** Plain HTML files: use the shipped ones, drop your own in the theme, or paste one an AI designed from the guide the plugin hands you. |
 | ![The archive](assets/screenshots/archive.png) | **Archive.** Every sent issue on your own site, in your theme's frame, and a block that lists the latest anywhere. |
 Requires WordPress 5.9+ and PHP 7.4+. WooCommerce is not required; with it,
 an issue can carry live product cards.
@@ -0,0 +1,322 @@
 # The surface Nolimit News exposes
 <!-- nlnws:version 0.2.1 -->
 Everything another plugin, a theme or a site owner can bind to, store against,
 or break by changing. For developers; a site owner never needs to read it.
 "Shipped source" means the files in the plugin zip. Anything else in the
 project is not on a site and is not part of this contract.
 ## Hooks this plugin provides
 **None yet.** This plugin fires no `do_action()` and applies no
 `apply_filters()` of its own, so there is nothing here for anyone to hook.
 That is a state, not a promise. Every extension point outlives the reason it
 was added, so each goes into this table in the same commit as the code.
 `nlnws_` is the prefix, and the release checks fail if a hook with it exists
 in the code and not in this table, or the other way round.
 <!-- nlnws:hooks:start -->
 ## Hooks this plugin registers on
 Deliberately not headed "consumes": `add_filter()` is how you **answer** a
 filter, and reading it as consumption gets the direction of the promise
 backwards. For an action the word is *listens*; for a filter it is *answers*.
 Priority and accepted-argument count are given where they are not WordPress'
 defaults of `10` and `1`, because those two are what break silently.
 | Hook | Kind | Registered in | Why |
 | --- | --- | --- | --- |
 | `admin_init` | action | `includes/class-updater.php` | Drops the cached feed when the user presses "Check again". |
 | `admin_init` | action | `includes/class-privacy.php` | Offers a paragraph for Settings → Privacy → Policy Guide. |
 | `admin_enqueue_scripts` | action | `includes/class-admin.php` | Loads `assets/css/admin.css`, on this plugin's screen only. |
 | `admin_menu` | action | `includes/class-admin.php` | Registers the Newsletters screen, and a link to it in the shared Nolimit menu. |
 | `admin_post_nlnws_auto_update` | action | `includes/class-auto-update.php` | The auto-update toggle's form target. |
 | `admin_post_nlnws_export` | action | `includes/class-subscribers-screen.php` | Streams the subscriber CSV. A GET link carrying a nonce; nothing is written. |
 | `admin_post_nlnws_issue_action` | action | `includes/class-send-screen.php` | Send now, schedule, test send, stop, resume, or choose the template for one issue. |
 | `admin_post_nlnws_settings_save` | action | `includes/class-templates-screen.php` | Saves the brand colour, logo, postal address and default template. |
 | `admin_post_nlnws_template_delete` | action | `includes/class-templates-screen.php` | Removes one pasted-in template. |
 | `admin_post_nlnws_template_save` | action | `includes/class-templates-screen.php` | Checks a pasted-in template and stores it, or refuses it with the reasons. |
 | `admin_post_nlnws_list_delete` | action | `includes/class-lists-screen.php` | Deletes a list and its memberships. Subscribers stay. |
 | `admin_post_nlnws_list_save` | action | `includes/class-lists-screen.php` | Creates or renames a list. |
 | `admin_post_nlnws_forms_save` | action | `includes/class-forms-bridge.php` | Saves which Nolimit Forms form signs people up to which list. |
 | `admin_post_nlnws_import` | action | `includes/class-import.php` | Import a CSV file (a Mailchimp audience export, or any file with an address column): subscribed, unsubscribed or cleaned. |
 | `admin_post_nlnws_reconfirm` | action | `includes/class-import.php` | Mail the next 50 imported, unconfirmed people and ask whether they still want the newsletter. |
 | `admin_post_nopriv_nlnws_open` | action | `includes/class-opens.php` | The open-counting pixel, for a logged-out reader. Answers the same 1x1 GIF whether or not anything was recorded. A GET that records, deliberately: it changes no consent. |
 | `admin_post_nlnws_open` | action | `includes/class-opens.php` | The same, for a reader who happens to be logged in. |
 | `admin_post_nopriv_nlnws_confirm` | action | `includes/class-public.php` | The link in the confirmation mail, for a logged-out visitor. GET shows a button; only POST confirms. |
 | `admin_post_nlnws_confirm` | action | `includes/class-public.php` | The same, for a visitor who happens to be logged in. |
 | `admin_post_nopriv_nlnws_signup` | action | `includes/class-public.php` | The signup form's target, for a logged-out visitor. |
 | `admin_post_nlnws_signup` | action | `includes/class-public.php` | The same, for a logged-in visitor. |
 | `admin_post_nopriv_nlnws_unsubscribe` | action | `includes/class-public.php` | The unsubscribe link, and RFC 8058's one-click POST to it. GET shows a button; only POST unsubscribes. |
 | `admin_post_nlnws_unsubscribe` | action | `includes/class-public.php` | The same, for a logged-in visitor. |
 | `nlfrm_submission` | action, 3 args | `includes/class-forms-bridge.php` | Nolimit Forms' announcement of an accepted, non-spam submission. Acts only for a form the site owner mapped to a list, and only when `NLFRM_VERSION` is 0.1.7 or later. The person becomes pending and is mailed a confirmation. |
 | `admin_post_nlnws_subscriber_action` | action | `includes/class-subscribers-screen.php` | Unsubscribe, suppress, lift suppression, or delete one person. |
 | `admin_post_nlnws_subscriber_add` | action | `includes/class-subscribers-screen.php` | Adds one person by hand, as `subscribed` with no `confirmed_at`. |
 | `nlnws_t_paste_<user id>` | transient, 15 minutes | A refused template paste and the reasons, so the box on the Templates tab can be filled in again. Only the administrator who pasted it sees it. |
 | `nlnws_purge_pending` | action | `includes/class-plugin.php` | The daily purge of signups nobody confirmed in 30 days. Scheduled on load, cancelled on deactivate and on uninstall. |
 | `cron_schedules` | filter | `includes/class-send.php` | Adds a one-minute interval, `nlnws_minute`, because a mailing cannot wait an hour per batch. |
 | `nlnws_send_tick` | action | `includes/class-send.php` | The one-minute tick that starts due scheduled sends and mails one batch of the oldest send in progress. Scheduled on load, cancelled on deactivate and on uninstall. |
 | `init` | action | `includes/class-issues.php` | Registers the issue post type, and flushes the rewrite rules once per plugin version. |
 | `plugin_action_links_<basename>` | filter | `includes/class-admin.php` | The "Newsletters" link on the Plugins screen. |
 | `plugins_api` | filter, 3 args | `includes/class-updater.php` | The "View details" panel. Guarded on `$args->slug`. |
 | `plugins_loaded` | action | `includes/class-plugin.php` | Everything else is registered from here. |
 | `update_plugins_<hostname>` | filter, 3 args | `includes/class-updater.php` | Offers this plugin's own updates, and only its own: see below. |
 | `upgrader_process_complete` | action, 0 args | `includes/class-updater.php` | Forgets the cached feed after any update runs. |
 | `wp_privacy_personal_data_erasers` | filter | `includes/class-privacy.php` | Deletes a person's address and consent rows on an erasure request. |
 | `wp_privacy_personal_data_exporters` | filter | `includes/class-privacy.php` | Exports everything held about an address, with the consent dates. |
 ## The family's shared hooks
 These belong to the Nolimit family, not to this plugin.
 | Hook | This plugin's relationship | Where |
 | --- | --- | --- |
 | `wpmgr_dashboard_cards` | **answers**: supplies this plugin's card | `includes/class-admin.php` |
 | `wpmgr_dashboard_cards` | applied by the shared file this plugin ships | `includes/shared-menu.php` |
 | `wpmgr_menu_title` | applied by the shared file this plugin ships | `includes/shared-menu.php` |
 | `wpmgr_menu_glyph` | applied by the shared file this plugin ships | `includes/shared-menu.php` |
 <!-- nlnws:hooks:end -->
 Shipping a file is not owning its hooks. `includes/shared-menu.php` is
 byte-identical across the family and frozen by SHA256; whichever copy loads
 first declares the functions, so on a real site the three `wpmgr_*` filters
 are applied by *a* copy of that file, probably another plugin's.
 ### 🔴 `update_plugins_<hostname>` is shared by every plugin on that host
 The filter name is built from the hostname, not the repository, so every plugin
 whose `Update URI` is on gitea.nolimit.dk lands on the same one and
 WordPress runs every callback for every one of them. Answering unconditionally
 offers this plugin's release to a neighbour. The fix has two halves: register with three accepted arguments,
 **and** return early when `$plugin_file` is not this plugin. Leave the count at
 two and the argument never arrives, so the guard is dead code. Both halves are
 covered by a test that fails if either is removed.
 ### The public endpoints
 `admin-post.php?action=nlnws_confirm&t=<token>` and
 `admin-post.php?action=nlnws_unsubscribe&t=<token>[&l=<list id>]` are the two
 links in every mail this plugin sends. They need no login and no nonce, because
 the 32-hex-character token is the authority and it can only act on its owner's
 own subscription. **A GET never changes anything**: it draws a page with a
 button, and only a POST acts. A mail scanner fetches every link in a message,
 and a GET that confirmed would let it confirm people who never asked. An
 unsubscribe POST is also what RFC 8058's `List-Unsubscribe-Post` sends, so the
 same URL serves the mail client's own button. An unknown, malformed or
 suppressed token answers 404 with a page that says nothing about which.
 The signup form (`admin-post.php?action=nlnws_signup`) answers the same
 whether the address is new, already subscribed, suppressed or throttled, so it
 cannot be used to learn who is on a list. It accepts only lists marked public,
 whatever the request names, and mails one confirmation per address per hour.
 ### Shortcode
 `[nolimit_news_signup lists="slug,slug" name="yes" button="Subscribe"]` draws the
 signup form. All attributes are optional: with no `lists` every public list is
 offered, one list becomes a hidden field, and boxes are never pre-ticked. The
 notice after a signup is chosen by `?nlnws=sent|bad`; any other value shows
 nothing.
 ### Blocks for the website
 `nolimit-news/signup` draws the form `[nolimit_news_signup]` draws, from the
 same code, with attributes `lists` (slugs; none means every public list),
 `name` (ask for a name) and `button`. `nolimit-news/archive` lists published
 issues, newest first, with `count` (1 to 50), `dates` and `excerpt`. Both are
 dynamic and keep only their attributes. A draft or scheduled issue is never
 listed, whatever the block is told, and the editor script that registers them
 is not loaded on an issue's own screen. No hook is added.
 ### Signup from Nolimit Forms
 `NLNWS_Forms_Bridge` listens to `nlfrm_submission` (`$values`, `$form`,
 `$entry_id`).
 It never acts unless the site owner has mapped that form to a list, Nolimit
 Forms is loaded and `NLFRM_VERSION` is 0.1.7 or later (the hook is not fired
 for spam-filed entries from that version; earlier ones would hand a bot's
 address to a mailing list). The email comes from the mapped field, or the
 form's first `email` field. When a consent field is mapped its value must be
 `1`. The address goes through `NLNWS_Subscribers::subscribe()` with source
 `form`, so suppression, unsubscribed people and double opt-in behave exactly
 as they do for the signup form, and a mapping may point at a list the signup
 form does not offer. Nothing is stored beyond what a signup stores, and
 nothing is added to the form's own entry.
 ### Who may use the screens
 Every screen and every `admin_post_nlnws_*` handler requires `manage_options`
 (`NLNWS_Admin::CAP`), checked first and answered with a 403, and then a nonce.
 A logged-in user without the capability who posts to `admin-post.php` gets the
 403 and nothing is read or written; The test suite posts each handler as a
 subscriber-role user and asserts that. The CSV export is a subscriber list, so
 it is behind the same gate rather than being a lighter one for a read.
 ## Options and storage
 Everything here is removed by `uninstall.php` on **delete**, not on deactivate:
 switching the plugin off for ten seconds must not destroy a mailing list. The
 subscriber tables hold personal data with no other owner, so a deleted plugin
 takes them with it. The test suite runs `uninstall.php` and asserts every
 row of this table is gone.
 | Name | Kind | Holds |
 | --- | --- | --- |
 | `{prefix}nlnws_lists` | table | The lists: name, slug, description, whether the signup form offers it. |
 | `{prefix}nlnws_subscribers` | table | One row per address, stored lower-case: name, the secret token in that person's confirm and unsubscribe links, and a suppression reason. |
 | `{prefix}nlnws_memberships` | table | One row per person per list: status (`pending`, `subscribed`, `unsubscribed`), how they joined (`form`, `admin`, `import`), when they asked, when they confirmed, when they left. |
 | `{prefix}nlnws_opens` | table | Only when open counting is on: one row per person per issue with the two ids, the first and last time an image was loaded, and how many times. Deleted with the issue, with the person, and on uninstall. |
 | `nlnws_db_version` | option | The schema version the tables were last built at. |
 | `nlnws_rewrite_version` | option | The plugin version the rewrite rules were last flushed at, so the `/newsletters/` archive works after an update without a visit to Settings → Permalinks. |
 | `nlnws_settings` | option | Brand colour, logo URL and the postal address printed in every issue's footer. |
 | `nlnws_forms` | option | Which Nolimit Forms forms sign people up: form id => list id, email field id and consent field id (the last two may be empty). |
 | `nlnws_templates` | option | Email templates pasted in by an admin: slug => HTML. Each is validated on the way in and again when read. |
 | `_nlnws_template` | post meta on an issue | The slug of the template this issue is mailed in. Empty or unknown means the site default in `nlnws_settings`. |
 | `nlnws_send_lock` | option | The time a tick took the send lock, so two ticks never mail at once. A lock older than five minutes is taken over. Absent between ticks. |
 | `nlnws_send_tick` | WP-Cron event, every minute | Drives all sending and scheduled starts. |
 | `_nlnws_state`, `_nlnws_lists`, `_nlnws_send_at`, `_nlnws_cursor`, `_nlnws_total`, `_nlnws_sent`, `_nlnws_failed`, `_nlnws_started`, `_nlnws_finished`, `_nlnws_last_batch`, `_nlnws_error` | post meta on an issue | The send state: `''`, `scheduled`, `sending`, `stopped` or `sent`; the chosen lists; the start time; the id of the last subscriber mailed; the counts; the times; and the last mailer error. There is no per-message record. |
 | `nlnws_auto_update_seeded` | option | That the one-time auto-update offer was made. |
 | `nlnws_release_feed` | transient | The cached release feed. |
 | `nlnws_t_<32 hex>` | transient, one hour | "This address was just mailed a confirmation". The name is a keyed hash of the address, so the address is not written to the options table. |
 | `nlnws_purge_pending` | WP-Cron event, daily | Deletes a pending membership older than 30 days, and the person too when nothing else is left and they are not suppressed. |
 The admin screens store nothing of their own: they read and write the tables
 above. A notice after a save is carried in the redirect's query string as
 a short code and printed from a fixed list, so a crafted URL cannot put words
 on the screen.
 No IP address, user agent or referrer is stored anywhere, and no click is
 recorded. **Open counting is an option, off by default** (`track_opens` in
 `nlnws_settings`). When it is on, each mail to a person carries one 1x1 image at
 `admin-post.php?action=nlnws_open&i=<issue>&t=<token>`, and loading it writes
 that person's row in `nlnws_opens`. Nothing is read from the request except the
 issue and the token, so there is nothing else to store, and nothing leaves the
 site. Turning it off stops recording at once, for mail already sent too, and
 removes the pixel from every mail after it. A preview, a test send and the
 plain-text twin have no person and so no pixel. The number is an estimate: some
 mail programs load images for the reader and others never do. The suggested
 privacy text and the signup form's fine print change with the setting.
 `confirmed_at` is set only when the person followed the link in the
 confirmation mail; a row with `source = import` and no `confirmed_at` is
 visibly one nobody confirmed, which is the difference between consent you can
 show and consent you are asserting.
 ### Import
 Subscribers → Import reads a CSV export. Only the address and the name are
 read (`First Name` and `Last Name` are joined; Danish Mailchimp headers, our own
 export, and comma, semicolon or tab separators are understood). The IP address,
 location and rating columns Mailchimp adds are not read and not stored, and the
 file itself is never kept. The screen makes the person importing tick that the
 people agreed to receive the newsletter. Three kinds of file:
 * **Subscribed**: joined as `subscribed`, `source = import`, no `confirmed_at`.
  Somebody who unsubscribed here, or whose address is suppressed, is skipped and
  counted; an import can never undo a person's own decision.
 * **Unsubscribed**: recorded as already unsubscribed, so a later subscribed file
  cannot bring them back. An existing membership is never changed by it.
 * **Cleaned**: the addresses are suppressed as `bounced`, on no list.
 A request works for 20 seconds and then stops and says which row to start at;
 the file can be uploaded again from there, and rows already in are counted as
 "already there". Files over 10 MB are refused. Separately, "Ask the imported
 people" mails each imported, unconfirmed person once (50 per click, one mail per
 address per hour) with their own confirm link. They stay subscribed whether they
 answer or not; the link only stamps `confirmed_at`. The place it has reached is
 the option `nlnws_reconfirm_cursor`, removed on uninstall and when the last
 batch is done.
 A signup nobody confirms is deleted after 30 days; an address that is suppressed is
 never deleted by it, or it could be mailed again.
 ### Sending
 An issue is `''` until sent, then `scheduled` (waiting for `_nlnws_send_at`),
 `sending`, `stopped` (by hand, or by the mailer failing the first five
 messages in a row) or `sent`. A send mails the people who are `subscribed` to
 any chosen list and not suppressed, once each however many of the lists they
 are on, in id order from the cursor, so a resume never mails anybody twice. The
 audience is read each batch: somebody who unsubscribes after the send began is
 not mailed. A failed address is counted and passed over, never retried. Each
 message goes through `wp_mail()` as HTML with a plain-text alternative and
 carries `List-Unsubscribe` and `List-Unsubscribe-Post: List-Unsubscribe=One-Click`
 for that person. When the last batch is done the issue is published, which puts
 it in the public archive. WP-Cron on a quiet site fires only when somebody
 visits, so a scheduled time is "not before", never "at".
 ### The email template
 A template is one HTML file: a header comment (`Template:` is required;
 `Description:`, `Text:`, `Muted:`, `Line:` and `Font:` are optional), then a
 complete `<html>` document that uses `{{tokens}}`. `{{{content}}}` (three
 braces, unescaped) is the issue's body and `{{unsubscribe_url}}` is required.
 Sections `{{#token}}...{{/token}}` show when the value is not empty and
 `{{^token}}...{{/token}}` when it is. The full grammar, every token and a
 working example are in `templates/AUTHORING.md`, which is written to be handed
 to an AI that designs the template; a test keeps that guide and the token list
 in step.
 Templates come from `templates/*.html` in the plugin, then
 `nolimit-news/*.html` in the parent and child theme, then the pasted ones in
 `nlnws_templates`; a later source with the same slug replaces an earlier one.
 **A template that fails its checks is skipped and reported, never sent**: no
 script, iframe, form, link, `@import`, `javascript:`, PHP or `on*=` handler, no
 token that does not exist, no unclosed section, at most 40 000 bytes. The
 refusal is worded so that an AI can fix what it names. The shipped files are
 `default` and `minimal`; the token set may grow, and a token is never renamed.
 ### The composer
 Writing an issue is the block editor, narrowed. On an `nlnws_issue` screen only
 the blocks that survive a mail client are offered: paragraph, heading, list,
 quote, image, separator, and two of our own, `nolimit-news/product` and
 `nolimit-news/button`. Everything else is hidden there and untouched on every
 other post type. Both blocks are dynamic (the editor stores only their
 attributes, never markup), so a product's price and name are read when the mail
 is drawn and a template change reaches issues already written.
 `nolimit-news/product` shows a live WooCommerce product when `productId` names a
 published one, and otherwise the fields typed in by hand, so it works on a site
 without a shop; a draft, trashed or missing product draws nothing rather than a
 broken card. The button takes the issue's brand colour and picks black or white
 text by contrast. Both draw single-line tables with inline styles, which is
 what mail clients keep.
 The editor's product list is `GET /wp-json/nolimit-news/v1/products?search=`,
 which needs `manage_options` (`NLNWS_Admin::CAP`) and answers 401 or 403
 otherwise. It returns `woocommerce` (whether a shop is active) and at most 12
 published products. Dragging a product from that list into the text, or clicking
 it, inserts the block; image files are dropped onto the editor as on any post.
 No hook is added for any of this.
 ### The issue post type
 `nlnws_issue` is a public post type: a newsletter is a post, with a permalink,
 revisions and the block editor. Its archive is at `/newsletters/` and each
 issue at `/newsletters/<slug>/`. **A draft is never public; a published issue
 is.** Every primitive capability of the type is `manage_options`, so an editor
 who can write posts cannot write, publish or delete an issue; reading a
 published one needs only `read`. Issues appear as a submenu of the Newsletters
 page. The send state above is stored on it as protected post meta.
 Deleting the plugin deletes every issue, trashed ones and their revisions
 included. It leaves an ordinary post alone.
 ## Constants
 | Name | Meaning |
 | --- | --- |
 | `NLNWS_VERSION` | The version, equal to the header's. |
 | `NLNWS_COLOUR` | The card colour, `#4a4fc4`, measured 6.55:1 against white. It exists three times, here, as `--nlnws-accent` in `assets/css/admin.css` and as the tile fill in `assets/icon.svg`; the release checks assert all three agree. |
 | `NLNWS_PLUGIN_FILE`, `NLNWS_PLUGIN_DIR`, `NLNWS_PLUGIN_URL`, `NLNWS_PLUGIN_BASENAME` | Paths, for this plugin's own use. |
 ## What a consumer must not do
 Read this plugin's tables directly, once they exist: the schema is not part of
 the contract and will change. Call a class of ours; only the hooks above are
 promises.
@@ -0,0 +1,58 @@
 # Nolimit News
 <!-- nlnws:version 0.2.1 -->
 Newsletters for WordPress and WooCommerce: write an issue in the block editor,
 keep your lists, put a signup form anywhere, send it through your own mail
 setup, and show every issue as an archive on your own site. Written to replace
 Mailchimp for a shop that does not want a monthly bill per subscriber.
 ## What it does
 * **Write** an issue in the block editor, inside a template, with images,
  columns, buttons and products from your shop.
 * **Lists and subscribers**, with double opt-in, a one-click unsubscribe in every
  mail, and a CSV export whenever you want your list back.
 * **Sign-up** through a block or a shortcode, and from a Nolimit Forms form you
  connect to a list.
 * **Send** now or at a time you choose, to one list or several, to each person
  once. A test send goes to one address and changes nobody.
 * **An archive** of every sent issue on your own site, in your theme's own
  frame, and a block that lists the latest issues on any page.
 * **Templates** that are plain HTML files: use the two that come with it, drop
  your own into your theme, or paste one in that an AI designed from the guide
  the plugin hands you.
 * **Import** a Mailchimp export (subscribed, unsubscribed and cleaned files) and
  ask the imported people to confirm, so leaving Mailchimp is not a weekend.
 ## What it refuses to do
 * **No click tracking.** No link in a mail is rewritten, so no address is
  routed through anyone.
 * **No phone-home.** Nothing about your site or your subscribers is sent to
  anyone. There is no account and no paid tier.
 * **No opening-counting unless you switch it on.** It is an option, off by
  default. When it is on, it records who opened which issue in your own
  database and tells nobody else, and the suggested privacy text changes with
  it.
 * **Nothing is mailed to somebody who has not agreed.** A signup is pending until
  the person follows the link in the confirmation mail, and a pending signup
  nobody confirms is deleted after 30 days.
 ## Where to start
 1. Install it and set up your mail: [SETUP.md](SETUP.md).
 2. Make a list, put the signup block on a page, write an issue, send yourself a
   test, send it.
 3. Developers building on it: [CONTRACT.md](CONTRACT.md) lists every hook,
   option, table and constant, and what is deliberately not promised.
 ## Documentation
 | File | For |
 | --- | --- |
 | [SETUP.md](SETUP.md) | Installing it, the few settings that need a decision, and checking that it works. |
 | [CONTRACT.md](CONTRACT.md) | Developers: what it offers other plugins and themes, what it stores, and what it asks of them. |
 Requires WordPress 5.9+ and PHP 7.4+. WooCommerce is not required; with it
 active, an issue can carry live product cards.
@@ -0,0 +1,125 @@
 # Setting up Nolimit News
 <!-- nlnws:version 0.2.1 -->
 ## Installing it
 | Needs | Version |
 | --- | --- |
 | WordPress | 5.9 or newer |
 | PHP | 7.4 or newer |
 | WooCommerce | not needed |
 1. Download `nolimit-news.zip` from the
   [latest release](https://gitea.nolimit.dk/kw/nolimit-news-dist/releases/latest).
 2. **Plugins → Add New → Upload Plugin**, then activate.
 3. Open **Newsletters** in the admin menu.
 Later versions arrive in **Dashboard → Updates** like any other plugin: it
 checks its own release feed and is never looked up on wordpress.org. The first
 time you open its screen it offers to switch automatic updates on for it; that
 is WordPress' own setting, in WordPress' own place, and you can say no.
 ## Making mail actually leave
 This plugin hands every message to WordPress (`wp_mail()`), so mail leaves
 however the rest of your site's mail leaves. On most hosting that is the
 server's own mail function, which is often slow, rate-limited or marked as spam.
 For a newsletter, set up a real sender first: an SMTP account or a mail service,
 through any SMTP plugin, or Nolimit Send. Without that, a test send may arrive
 in a spam folder or not at all, and a large send may be cut off by your host's
 hourly limit. The screen tells you when mail fails: if the first five messages
 in a row are refused, the send stops by itself rather than working through your
 whole list.
 Sending runs from WordPress' background scheduler (WP-Cron), one batch a minute.
 On a quiet site that only runs when somebody visits, so a scheduled time means
 "not before", never "exactly at". If WP-Cron is switched off on your site, the
 Send screen says so, and your server has to call `wp-cron.php` itself.
 ## The first ten minutes
 1. **Templates → How every issue looks.** Set the brand colour, the address of
   a public logo image, and your postal address. The address is printed at the
   foot of every mail: marketing mail is expected to say who sent it and where
   they are. Pick the default template.
 2. **Lists → New list.** Give it a name and a line about what people are signing
   up for. Leave "Offer this list on signup forms" ticked for lists the public
   may join; untick it for one you only fill yourself.
 3. **Put the form on a page.** Add the *Newsletter signup* block, or the
   shortcode `[nolimit_news_signup]`. With no list named, it offers every public
   list.
 4. **Write an issue.** On the Send tab, **Write a new issue**. It is the block
   editor with only the blocks that survive an email program: paragraphs,
   headings, lists, quotes, images, separators, columns, a button and a product
   card. Open the *Add to the issue* panel and drag a product in, or click it.
 5. **Preview, then send a test** to your own address. Look at it on a phone.
 6. **Send now**, or **Send not before** a time. Pick the lists; a person on
   several of them is mailed once.
 When the last message has gone, the issue is published, which puts it in the
 archive at `/newsletters/` on your site. The *Newsletter archive* block lists
 the latest issues on any page.
 ## Checking that it works
 * **A signup arrives as pending**, and you receive the confirmation mail. Follow
  its link: a page with a button appears (a mail scanner that opens the link
  cannot confirm anyone by accident), and pressing it makes the person
  *subscribed*.
 * **The unsubscribe link in a test send goes nowhere**, by design. In a real send
  it takes one click, and the person is not mailed again.
 * **Mailed N of N** on the issue's Send panel counts what was handed to your mail
  system. It cannot know what the receiving servers did with it.
 ## Leaving Mailchimp
 **Subscribers → Import** reads the CSV files Mailchimp lets you export. Do the
 three separately:
 * **Subscribed** people join as subscribed. You tick a box to say they agreed to
  receive your newsletter.
 * **Unsubscribed** people are recorded as unsubscribed, so no later import can
  bring them back.
 * **Cleaned** addresses are suppressed and mailed nothing.
 Only the address and the name are read, and the file itself is not kept. A large
 file is handled in steps; the screen says which row to carry on from. Imported
 people stay visibly *not confirmed* until they follow a link, and **Ask the
 imported people** mails them in batches of 50 to do exactly that. They stay
 subscribed whether or not they answer.
 ## Opens, privacy and the law
 Counting opens is **off** until you switch it on under *How every issue looks*.
 Switching it on adds one invisible image to each mail and records, in your own
 database, that this person's copy was opened. It is an estimate: some mail
 programs load images for the reader and others never do. Switching it off stops
 recording at once and removes the image from later mail. Nothing is ever sent to
 anyone else.
 Settings → Privacy → Policy Guide gets a paragraph that matches your choice.
 Personal data exports and erasure requests from WordPress cover the lists: an
 export includes the dates the person asked and confirmed, and an erasure deletes
 the address and its consent records.
 You are responsible for having consent to mail your list. The plugin helps by
 keeping the proof: *confirmed* means the person followed their own link, and an
 imported person who has not is shown as one you are asserting rather than one
 you can show.
 ## Deleting it
 Deactivating keeps your lists, subscribers and issues. **Deleting** the plugin
 removes its tables, its settings and every issue, because the subscriber lists
 hold personal data with no other owner. Export what you want first
 (**Subscribers → Export these as CSV**).
 ## If something is wrong
 | You see | It means |
 | --- | --- |
 | A template "was found and not used" | It broke a rule (a script, a link tag, a missing unsubscribe token). The message says which; fix that and save again. |
 | *Stopped* with "The mail system said:" | Your mail setup refused the first messages. Fix it, then **Carry on where it stopped**; nobody is mailed twice. |
 | `/newsletters/` shows a 404 | Open Settings → Permalinks and press Save once. |
 | Scheduled issue did not go at the time | WP-Cron fires on a visit. Visit the site, or have the server call `wp-cron.php` every minute. |