automatic 26.08 → 26.09

data/doc/PLUGINS.md

@@ -158,8 +158,8 @@ The value is stored and is read correctly, because plugins read their settings
 by string key rather than as a property. This is noise, not breakage, and a
 Recipe using such a key needs no change.
 
-Two shipped plugins have such a name, from before this was understood, and they
-keep it: `FilterSort`'s `sort` and `PublishMemcached`'s `key`. Renaming them
+The existing collisions retained for compatibility are `FilterSort`'s `sort`
+and `PublishMemcached`'s `key`. Renaming them
 would break every Recipe using them, which is not a trade worth making for a
 warning. **A new plugin should not introduce one**: prefer `max_length` to
 `max`, `item_count` to `count`, `cache_key` to `key`.
@@ -265,7 +265,7 @@ found.
 
 ### 3.3 Discovery and precedence
 
-Two search roots, in this order:
+Search roots, in this order:
 
 1. `~/.automatic/plugins/<category>/<rest>.rb`
 2. `<installation>/plugins/<category>/<rest>.rb`
@@ -276,7 +276,7 @@ plugin's behaviour without editing the installation.
 
 Creating a new category is creating a directory. `~/.automatic/plugins/mine/`
 plus a class named `MineSomething` works with no change to the framework, though
-staying inside the seven categories is preferred, because their names tell a
+staying inside the established categories listed in section 3.2 is preferred, because their names tell a
 reader where in a pipeline the plugin belongs.
 
 Loading is lazy: the loader registers an `autoload`, so the file is read when
@@ -313,9 +313,10 @@ Rules that follow from the shape:
 
 - **Return the shape, always.** Returning `nil`, a string or a bare array of
   items ends the pipeline for everything after it.
-- **`link` may be `nil`, and so may any other field.** Filters signal "not
-  applicable" by setting `link` to `nil`, so a plugin that dereferences a field
-  without checking will be handed `nil` sooner or later.
+- **`link` may be `nil`, and so may any other field.** A missing field is data,
+  not a framework-wide drop signal: `FeedMaker.create_pipeline` preserves an
+  item whose link is `nil`. A plugin that requires a link must check it itself;
+  a plugin that does not may keep processing the item.
 - **Guard the feed itself.** `@pipeline.each { |feeds| next if feeds.nil? }` is
   the prevailing idiom, because a subscription plugin that failed may have put a
   `nil` in the array.
@@ -558,11 +559,11 @@ Section 6 lists every plugin shipped in the gem. Each carries a status:
 | **Supported (external)** | The plugin is current, but it needs something the operator provides — a running service, an installed command, a credential, a data file. |
 | **Needs rework** | The service and the capability still exist, but this plugin speaks an interface that has been replaced. It will not work as written, and restoring it is a self-contained piece of work. |
 
-There is no fourth row. There used to be one, holding plugins whose service had
-shut down, and the plugins that were in it have been removed rather than kept:
-see section 8.
+No status is used for an integration whose service or capability is
+permanently unavailable. Such plugins are removed rather than retained; see
+section 8.
 
-Two rules govern this table, and they are the reason it exists at all:
+The rules that govern this table are the reason it exists at all:
 
 - **Nothing is faked.** A plugin is not stubbed, mocked or simulated to make a
   test pass or a catalogue entry look better. Where a plugin's gem is absent
@@ -584,15 +585,13 @@ its spec as part of the ordinary suite, which is also what the separate
 plugin is not demoted for needing a gem, and is not promoted by a test that CI
 never executes.
 
-**This classification is a snapshot taken in August 2026,** based on the
-published status of each service and on what each plugin's code actually calls.
-The statuses that depend on an outside service can change without any commit
-here. Where a status was reached from published information rather than from a
+**Statuses involving an outside service are snapshots of external state.**
+They can change without any commit here. Where a status was reached from published information rather than from a
 live check, the entry says so. To verify one yourself, run its Recipe from
 `test/integration` by hand; those are not part of CI and never will be.
 
-Restoring the one **Needs rework** plugin is a self-contained piece of work and
-a good first contribution.
+Restoring a plugin classified as **Needs rework** is a self-contained piece
+of work and a good first contribution.
 
 ---
 
@@ -670,10 +669,13 @@ no network, which makes it the plugin to test a Recipe's later half with.
 | `titles` | sequence | One item per title, no link |
 | `urls` | sequence | One item per URL, no title |
 | `feeds` | sequence | Mappings of `title`, `url`, `description`, `author`, `comments` |
-| `files` | sequence | TSV paths; columns are title, url, description, author, comments |
+| `files` | sequence | UTF-8 TSV paths; positional columns are title, url, description, author, comments |
 
-The TSV separator is a tab, the file is read as UTF-8, and `~` is expanded. Any
-combination of the four keys may be given.
+The TSV separator is a tab and `~` is expanded. Empty columns supply no value
+for that field without shifting later columns; blank or all-empty rows produce
+no item. Only the first five columns are used. Line endings are removed before
+splitting, but other field whitespace is preserved. Any combination of the four
+keys may be given.
 
 #### SubscriptionTumblr — **Supported (external)**
 
@@ -866,6 +868,34 @@ match. Same three keys, same substring rule. An item whose field is missing is
 not matched, and says so; it used to end the run with a `NoMethodError`, which
 is not what its complement does with the same item.
 
+#### FilterPresent — **Supported**
+
+`filter/present.rb`. Keeps only items for which every configured field is
+present. It is an AND filter over field presence, not a keyword matcher.
+
+Recipe:
+
+```yaml
+  - module: FilterPresent
+    config:
+      fields:
+        - title
+        - description
+```
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `fields` | sequence | Fields that must all be present. Required and non-empty. |
+
+The fields that may be checked are `title`, `link`, `description`, `author`,
+`comments`, `source` and `content_encoded`. A field the item has no accessor
+for, a `nil` value, an empty string and a whitespace-only string are all
+absent; an RSS field that responds to `#content` — a parsed source, for
+instance — is judged on that content rather than on the element itself. An
+item is kept only when every configured field is present. An unknown field or
+a field named twice is a settings error, raised when the plugin is
+constructed. No network access, and no dependency on another plugin.
+
 #### FilterSort — **Supported**
 
 `filter/sort.rb`. Sorts each feed's items by date.
@@ -887,6 +917,31 @@ setting works; see section 2.6.1.
 | --- | --- | --- |
 | `pick` | string | `last` takes the last item. Anything else, including absent, takes the first. |
 
+#### FilterLimit — **Supported**
+
+`filter/limit.rb`. Limits how many items the whole pipeline passes downstream.
+The limit is shared across feeds rather than applied once per feed.
+
+Recipe:
+
+```yaml
+  - module: FilterLimit
+    config:
+      max_items: 20
+```
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `max_items` | integer | Maximum items passed by the whole pipeline. Required; must be greater than zero. |
+
+Items are selected in feed order, then item order, up to `max_items`; the
+grouping of the input feeds is kept in the output, and a feed that contributed
+no item under the limit is left out of it. Once the limit is reached, later
+feeds are not walked at all. Anything other than a positive integer —
+including zero, a negative number, and a non-numeric or fractional string — is
+a settings error, raised when the plugin is constructed; a numeric string such
+as `"20"` is accepted. No network access, and no dependency on another plugin.
+
 #### FilterRand — **Supported**
 
 `filter/rand.rb`. Shuffles each feed's items. Combined with `FilterOne`, picks
@@ -899,9 +954,10 @@ plugin has done the work, so that later plugins publish nothing. No settings.
 
 #### FilterImage — **Supported**
 
-`filter/image.rb`. Sets `link` to `nil` unless it names an image. Note that it
-does not remove the items — it blanks their links, and the plugins after it
-skip items whose link is `nil`. No settings.
+`filter/image.rb`. Sets `link` to `nil` unless it names an image. It does not
+remove the item: a later plugin that requires a link skips it under that
+plugin's own rules, while a link-independent plugin may continue to use it. No
+settings.
 
 The extensions are `.jpg`, `.jpeg`, `.gif`, `.png`, `.tif`, `.tiff`, `.webp`
 and `.avif`, and the test is on the URL's **path**. Both of those changed:
@@ -914,7 +970,16 @@ this filter will therefore keep links it used to blank.
 
 `filter/image_source.rb`. Replaces each item with one item per image found: the
 images in the description, or, if there are none, the images on the page the
-link points at. Fetching pages means network access. No settings.
+link points at. Fetching pages means network access.
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `interval` | integer | Seconds to wait after each page fetch attempt. Default `0`. |
+
+An item whose images come from the description is never fetched, and
+`interval` does not apply to it. Where a page is fetched, the wait follows the
+actual fetch attempt whether it succeeded or failed. A non-positive or
+non-numeric `interval` — including it being absent — means no wait at all.
 
 Needs `nokogiri`: `gem install nokogiri`, or the `html` group in a checkout.
 
@@ -974,9 +1039,14 @@ the body.
 | --- | --- | --- |
 | `clear_description` | `1` | Empty the description afterwards. Any other value leaves it. |
 | `get_title` | `1` | Fetch the new link and use its `<title>`. Any other value skips it. |
+| `interval` | integer | Seconds to wait after each title-page fetch attempt when `get_title` is `1`. Default `0`. |
 
 `get_title` makes one request per item; use `FilterOne` or a store plugin before
-it on a large feed.
+it on a large feed. When `get_title` is not `1`, no title page is fetched and
+`interval` does not apply. A URL that is not fetchable is not read either, and
+does not wait. Where a title page is read, the wait follows the actual fetch
+attempt whether it succeeded or failed. A non-positive or non-numeric
+`interval` — including it being absent — means no wait at all.
 
 **Both settings were being ignored in every real run.** The test that guarded
 them asked whether the settings mapping was a `Hash`, and the framework hands a
@@ -999,37 +1069,36 @@ page.
 | Key | Type | Meaning |
 | --- | --- | --- |
 | `siteinfo` | string | File name under the assets directory. Required. |
+| `interval` | integer | Seconds to wait after each article-page fetch attempt. Default `0`. |
+
+An item whose link matches no siteinfo record is never fetched, and `interval`
+does not apply to it. Where a link does match, the wait follows the actual
+fetch attempt whether it succeeded or failed. A non-positive or non-numeric
+`interval` — including it being absent — means no wait at all.
 
 Needs `nokogiri`: `gem install nokogiri`, or the `html` group in a checkout.
 
-The shipped `assets/siteinfo/items_all.json` is a snapshot of the LDRFullFeed
-database taken from `wedata.net`, which no longer operates, so the file cannot
-be refreshed from its origin and its newest entries are from 2013. The plugin
-works; how well it works depends on whether the sites you read are in that
-snapshot and still laid out the same way. Supplying your own file in
-`~/.automatic/assets/siteinfo/` is the way to keep it useful.
-
-Three things follow from the database being that old, and the plugin now
-accounts for each:
-
-- **A link matches under either scheme.** 3,448 of the 3,504 usable records
-  anchor on a scheme and all but twenty of those say `^http://`. The sites they
-  name have since moved to HTTPS, which is what a feed hands over, so matching
-  the link as it stands matched almost nothing and the filter quietly did
-  nothing at all. A record describes a site's layout, not how it is
-  transported, so the link is tried under both. Only the match is rewritten;
-  the page is fetched from the link the feed gave.
-- **A record that selects nothing leaves the summary alone.** A site redesigned
-  since its XPath was written selects no nodes, and putting that empty result
-  into the item replaced a perfectly good summary with an empty description.
-  The item keeps what it arrived with, and the miss is logged at `warn` with
-  the XPath that missed.
-- **The page's own encoding is believed before the record's.** The page is
-  parsed from the stream, so a charset in a `meta` tag is read even when the
-  response declared none. A record's `enc` is the fallback for a page that
-  declares nothing anywhere — 1,186 records carry one, mostly EUC-JP and
-  Shift_JIS — and an `enc` naming an encoding Ruby does not have is ignored
-  rather than raised. What comes out is UTF-8 either way.
+The shipped `assets/siteinfo/items_all.json` is a bundled LDRFullFeed-compatible
+siteinfo snapshot. Its coverage is a snapshot rather than a guarantee that a
+site is present or still uses the recorded layout. The bundled file may be
+replaced from a newer upstream snapshot, as recorded in
+[`VERSIONS`](VERSIONS); an operator can also supply a siteinfo file under
+`~/.automatic/assets/siteinfo/`.
+
+The plugin's behavior does not depend on the bundled snapshot having a
+particular record count, date, scheme distribution, or encoding distribution:
+
+- **A link matches under either HTTP scheme.** A stored URL pattern can name
+  `http://` while a current feed supplies `https://`, or the reverse. Matching
+  therefore tries both schemes while fetching the page from the original item
+  link.
+- **A record that selects nothing leaves the summary alone.** If the recorded
+  XPath no longer selects content, the existing description is preserved and
+  the miss is logged at `warn`.
+- **The page's own encoding is believed before the record's.** Response or
+  document declarations take precedence; the record's `enc` is only a fallback,
+  and an encoding Ruby does not recognize is ignored rather than raised. The
+  selected body is normalized to UTF-8.
 
 A record with no URL pattern, no XPath, or a pattern that is not a regular
 expression is dropped when the file is loaded rather than being allowed to fail
@@ -1045,6 +1114,35 @@ pipeline expects. Needed because GitHub publishes Atom, not RSS. No settings.
 A field that is already a string is taken as it stands, so a pipeline that has
 been through another filter first is no longer a `NoMethodError`.
 
+#### FilterBatch — **Supported**
+
+`filter/batch.rb`. Groups all items in the pipeline into fixed-size batches.
+Feed boundaries are intentionally discarded; each batch becomes one item in one
+output feed.
+
+Recipe:
+
+```yaml
+  - module: FilterBatch
+    config:
+      batch_items: 5
+```
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `batch_items` | integer | Maximum source items in one batch. Required; must be greater than zero. |
+
+The whole pipeline is collected in feed order, then item order, and sliced
+into batches of `batch_items` source items. Each batch becomes one item titled
+`Batch N`; a batch item carries no link. Its description lists the source
+items as `ARTICLE N`, `Title:`, `URL:` and the body, with the `ARTICLE`
+numbering starting over at 1 in every batch. An empty pipeline produces an
+empty pipeline. Anything other than a positive integer — including zero, a
+negative number, and a non-numeric or fractional string — is a settings error,
+raised when the plugin is constructed; a numeric string such as `"5"` is
+accepted. It is independent of `FilterJoin` — it does not require it, call it,
+or depend on it in any way — and reaches no network and no external service.
+
 #### FilterJoin — **Supported**
 
 `filter/join.rb`. Joins every item in the pipeline into one item. Many items
@@ -1101,9 +1199,10 @@ next.
       title: Daily Digest
 ```
 
-**The four AI filters.** The plugins that follow each send an item's
+**The AI filters.** The plugins that follow each send an item's
 description to one AI service and put the answer back in its place. They are
-four plugins rather than one with a `provider` setting, and that is the design
+separate service-specific plugins rather than one plugin with a
+`provider` setting, and that is the design
 rather than an accident: the services differ in endpoint, authentication,
 request body, answer shape, error format and available models; each of those
 moves without asking the others; and a Recipe naming `FilterClaude` says on its
@@ -1114,11 +1213,10 @@ Changing service is changing that one line.
 the item's description is the text it applies to, so summarizing, translating,
 extracting, reformatting and classifying are the same plugin with a different
 prompt. There is no default prompt: a Recipe without one is refused with an
-`ArgumentError` rather than being given a purpose it did not ask for. The two
-are sent as separate fields — a system instruction and a user turn — so that
+`ArgumentError` rather than being given a purpose it did not ask for. The instruction and the item text are sent as separate fields — a system instruction and a user turn — so that
 what an article says is text to be worked on, never an instruction to obey.
 
-What the four have in common:
+What the AI filters have in common:
 
 | Point | What it is |
 | --- | --- |
@@ -1156,16 +1254,16 @@ for new integrations, and authenticates with the token as a bearer token.
 | `retry` | integer | Attempts after a failure. Default `0`. |
 | `interval` | integer | Seconds between attempts. Default `0`. |
 
-The endpoint is not a setting: there is one, an operator has no version of this
-plugin that talks to a different host, and a setting for it would be a way to
-send the token somewhere else. The answer is read out of the typed `output`
+The endpoint is fixed by this plugin rather than exposed as a setting. An
+operator has no version of this plugin that talks to a different host, and a
+setting for the endpoint would provide a way to send the token somewhere else. The answer is read out of the typed `output`
 array, from the `output_text` of the assistant's message.
 
 ```yaml
   - module: FilterOpenAI
     config:
       token: sk-...
-      model: gpt-5.6
+      model: <OpenAI model>
       prompt: |
         Summarize the following articles as one digest, in Japanese.
       retry: 2
@@ -1178,7 +1276,8 @@ array, from the `output_text` of the assistant's message.
 API, `https://api.anthropic.com/v1/messages`, and replaces it with the answer.
 Anthropic authenticates with an `x-api-key` header rather than a bearer token,
 requires an API version header, and requires a `max_tokens` — so this plugin
-sends all three, and has one setting the others do not.
+sends those required values and exposes the required `max_tokens` setting in
+addition to the shared settings.
 
 | Key | Type | Meaning |
 | --- | --- | --- |
@@ -1198,7 +1297,7 @@ blocks of other kinds are passed over.
   - module: FilterClaude
     config:
       token: sk-ant-...
-      model: claude-opus-5
+      model: <Anthropic model>
       prompt: |
         Summarize the following articles as one digest, in Japanese.
       max_tokens: 2048
@@ -1219,7 +1318,7 @@ URL and out of anything that logs one.
 | Key | Type | Meaning |
 | --- | --- | --- |
 | `token` | string | Gemini API key, sent as `x-goog-api-key`. Required. |
-| `model` | string | Model name, bare — `gemini-3.5-flash`, not `models/gemini-3.5-flash`. Required. |
+| `model` | string | Bare model name without the `models/` prefix. Required. |
 | `prompt` | string | The instruction, sent as `system_instruction`. Required. |
 | `retry` | integer | Attempts after a failure. Default `0`. |
 | `interval` | integer | Seconds between attempts. Default `0`. |
@@ -1234,7 +1333,7 @@ description.
   - module: FilterGemini
     config:
       token: AIza...
-      model: gemini-3.5-flash
+      model: <Gemini model>
       prompt: |
         Summarize the following articles as one digest, in Japanese.
       retry: 2
@@ -1266,7 +1365,46 @@ Recipe that says where the text goes for a Recipe that does not.
   - module: FilterSakuraAI
     config:
       token: ...
-      model: gpt-oss-120b
+      model: <Sakura AI Engine model>
+      prompt: |
+        以下の記事群について、個別記事の要約を羅列するのではなく、
+        全体を一つのダイジェストとして日本語で要約してください。
+      retry: 2
+      interval: 2
+```
+
+#### FilterKimi — **Supported (external)**
+
+`filter/kimi.rb`. Sends each item's description to Moonshot AI's Kimi,
+`https://api.moonshot.ai/v1/chat/completions`, and replaces it with the
+answer. The token is a bearer token, and the request is the chat completions
+form: the prompt as a `system` message, the description as a `user` message.
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `token` | string | Kimi API key. Required. |
+| `model` | string | Model name, as Moonshot names it (e.g. `kimi-k3`). Required. |
+| `prompt` | string | The instruction, sent as the `system` message. Required. |
+| `retry` | integer | Attempts after a failure. Default `0`. |
+| `interval` | integer | Seconds between attempts. Default `0`. |
+
+**This interface is OpenAI-compatible, and this is still its own plugin.** It is
+a different service: a different endpoint, a different account, a different set
+of models, its own limits and its own errors, any of which may move without
+OpenAI moving. Folding it into `FilterOpenAI` behind a setting would trade a
+Recipe that says where the text goes for a Recipe that does not, the same
+reasoning that already keeps Sakura AI in a plugin of its own.
+
+Kimi may return a `reasoning_content` alongside the answer's `content`. That
+reasoning is never read, logged or written anywhere; only `content` is used,
+and only once `finish_reason` is `"stop"` -- any other value, or a missing or
+empty `content`, is an error rather than an empty description.
+
+```yaml
+  - module: FilterKimi
+    config:
+      token: YOUR_KIMI_API_KEY
+      model: kimi-k3
       prompt: |
         以下の記事群について、個別記事の要約を羅列するのではなく、
         全体を一つのダイジェストとして日本語で要約してください。
@@ -1301,7 +1439,7 @@ plugins:
   - module: FilterSakuraAI
     config:
       token: ...
-      model: gpt-oss-120b
+      model: <Sakura AI Engine model>
       prompt: |
         以下の記事群について、個別記事の要約を羅列するのではなく、
         全体を一つのダイジェストとして日本語で要約してください。
@@ -1315,8 +1453,8 @@ plugins:
 ```
 
 Changing service is changing the one entry: `FilterSakuraAI` for
-`FilterOpenAI`, `FilterClaude` or `FilterGemini`, with that plugin's own
-settings. Nothing before or after it changes.
+`FilterOpenAI`, `FilterClaude`, `FilterGemini` or `FilterKimi`, with that
+plugin's own settings. Nothing before or after it changes.
 
 ### 6.4 Store
 
@@ -1350,9 +1488,10 @@ look new again.
 #### StoreFullText — **Supported**
 
 `store/full_text.rb`. Records title, link, description and `content_encoded`,
-and passes on only what is new. Deduplicates on link **or** title, so a
-republished article with a new URL is not stored twice. Pair with
-`FilterFullFeed` to archive article bodies.
+and passes on only items whose new record was saved successfully. Deduplicates
+on link **or** title, so a republished article with a new URL is not stored
+twice. A database write failure ends the run; the unsaved item is not passed
+downstream. Pair with `FilterFullFeed` to archive article bodies.
 
 | Key | Type | Meaning |
 | --- | --- | --- |
@@ -1478,12 +1617,14 @@ headline edited between runs no longer republishes the article.
 
 #### StoreFile — **Supported**
 
-`store/file.rb`. Downloads what each link points at and rewrites the link to a
-`file://` URI, which is how `PublishAmazonS3` later knows it has a local file.
+`store/file.rb`. Downloads what each link points at and rewrites the link to an
+absolute `file:` URI for the saved file, which is how `PublishAmazonS3` later
+knows it has a local file. URI-reserved characters in the saved path are
+percent-encoded.
 
 | Key | Type | Meaning |
 | --- | --- | --- |
-| `path` | string | Directory to save into; created if absent. Required. |
+| `path` | string | Directory to save into; relative paths use the process working directory; created if absent. Required. |
 | `retry` | integer | Attempts after the first. Default `0`. |
 | `interval` | integer | Seconds between downloads. Default `0`. |
 | `access_key` | string | S3 only. Omit to use the SDK's own credential chain. |
@@ -1782,8 +1923,9 @@ timeout, so an unanswered request ends rather than hanging a `cron` job.
 
 #### PublishAmazonS3 — **Supported (external)**
 
-`publish/amazon_s3.rb`. Uploads files whose link is a `file://` URI to S3,
-normally after `StoreFile`.
+`publish/amazon_s3.rb`. Uploads files whose link is a `file:` URI to S3,
+normally after `StoreFile`. A percent-encoded URI path is decoded back to the
+local filesystem path before upload.
 
 | Key | Type | Meaning |
 | --- | --- | --- |
@@ -1832,21 +1974,19 @@ is a claim that the plugin works.
 
 ---
 
-## 7. Summary
-
-| Status | Count | Plugins |
-| --- | --- | --- |
-| Supported | 26 | `SubscriptionFeed`, `SubscriptionLink`, `SubscriptionXml`, `SubscriptionText`, `CustomFeedWeb`, `FilterIgnore`, `FilterAccept`, `FilterSort`, `FilterOne`, `FilterRand`, `FilterClear`, `FilterImage`, `FilterImageSource`, `FilterAbsoluteURI`, `FilterSanitize`, `FilterTumblrResize`, `FilterDescriptionLink`, `FilterGithubFeed`, `FilterJoin`, `StorePermalink`, `StoreFullText`, `StoreDigest`, `StoreFile`, `PublishMarkdown`, `PublishConsole`, `PublishConsoleLink` |
-| Supported (external) | 14 | `SubscriptionTumblr`, `CustomFeedSVNLog`, `FilterFullFeed`, `FilterOpenAI`, `FilterClaude`, `FilterGemini`, `FilterSakuraAI`, `ProvideFluentd`, `NotifyIkachan`, `PublishEject`, `PublishMemcached`, `PublishFluentd`, `PublishInstapaper`, `PublishAmazonS3` |
-| Needs rework | 1 | `PublishHatenaBookmark` |
+## 7. Catalogue maintenance
 
-Forty-one plugins. Every one of them either runs, or names the one thing it
-needs from the operator; the single exception says what is wrong with it and
-what fixing it would take.
+Section 6 is the single source of truth for the set of plugins that ship and
+for each plugin's current status. Current plugin totals, per-status totals and
+duplicate current plugin-name lists are not maintained here or in `README.md`;
+adding or removing a plugin changes its implementation, its specification and
+its Section 6 catalogue entry, not a second summary that has to be kept in
+sync.
 
-`spec/doc/plugins_catalogue_spec.rb` holds this table to the files in
-`plugins/`: an entry with no file, a file with no entry, and a count that has
-been left behind by an edit are all failures of the ordinary test suite.
+`spec/doc/plugins_catalogue_spec.rb` verifies that every shipped plugin has
+exactly one Section 6 entry, every Section 6 entry has a shipped plugin at the
+loader-derived path, and every entry uses one of the statuses defined in
+section 5.
 
 ## 8. Plugins that were removed