# tldr-block: approved summaries at the top of long posts

[tldr-block](https://github.com/IndianOpinion/tldr-block) is a WordPress plugin that adds a short summary block at the top of long posts. A model writes a draft in the background, an editor approves it, and readers see only approved text. When the post changes materially, the approved summary is withdrawn and a fresh draft is queued for review. Licence MIT. Version v0.1.0, released 19 November 2026.

It was written from scratch from an idea, as one of the utilities described on the [engineering blog](https://indianopinion.org/blog/). It has not run on a live site, and its PRD carries no measured-result line.

## The problem

Long posts lose readers before the point. A short summary at the top helps the reader decide, helps a screen-reader user skim, and gives a quotable answer. Writing one by hand for every long post is a chore editors skip. Generating it with a model fixes the chore and creates three problems.

- Drift. The post is corrected or extended and the summary still describes the old version. On a news site a stale summary can repeat the error the correction removed.

- Unreviewed text on the page. A model can invent a figure, flip a negation, or follow an instruction hidden in the article. Nothing machine-written should reach readers without a human saying yes.

- Runaway spend. Every save of a long post is a potential paid call. An editor who saves forty times in an hour, a bulk edit of many posts or a cron loop can each burn a day's budget.

## What it does

- Generates a draft summary, as bullets or a paragraph, for posts above a minimum word count (600 by default), in categories where summaries are switched on.

- Holds each draft as pending. A user with edit_others_posts approves, edits and approves, writes their own, or rejects.

- Shows approved text through automatic insertion, the [tldr] shortcode, a server-rendered "Summary" block, a template function or a REST field.

- Withdraws the summary when the post changes materially, and queues a new candidate.

- Backfills old posts from WP-CLI, newest first, within the daily cap, and never approves anything.

## How it works

On wp_after_insert_post, Queue builds the source text and a fingerprint: a SHA-256 plus a 128-value bottom-k sketch of word three-shingles. The title is not part of it. The fingerprint is compared with the one the current summary was generated from, never with the previous save, so many small edits add up. A change is material when the hash differs and the estimated Jaccard distance is 0.10 or more. Status flips and meta updates cost nothing.

A material change marks the approved summary stale and, by default, hides it at once. One job per post is pushed back by every material save, a five-minute debounce. Generator re-checks eligibility, takes a lease, reserves a unit of the daily cap under a lock, checks the per-post limit, the cost cap and spend-meter when present, then makes one call through [llm-json-php](https://github.com/IndianOpinion/llm-json-php) or a caller you supply. The article goes in the user message between markers, and the system message says it is data, not instructions.

Validation checks the point count and length, rejects empty or duplicate points, URLs and instruction-like lines, and checks the script. Every number in the summary is checked against the article, and misses are shown to the editor as unverified figures. The result is a pending candidate, held in post meta.

The rendered markup is small and plain:

<aside class="tldr-block" aria-label="Summary">
<p class="tldr-block__heading">Summary</p>
<ul class="tldr-block__points"><li>...</li></ul>
</aside>

## Guard rails

- There is no setting that publishes a summary without review, and no bulk approve. Only Review writes the live summary, and every regeneration lands as pending.

- Automatic insertion happens on single views in the main loop only. Summaries are never in excerpts, archives, feeds or REST responses unless you turn those on.

- The default mode on a fresh install is off, and nothing runs until a key and a model are set. TLDR_BLOCK_DISABLED locks the kill switch on.

- The daily cap defaults to 50 generations. There is an optional cost cap and a per-post limit of 3 a day. The cap counter lock is one INSERT IGNORE on the options key.

- Failures retry after 5 minutes, 30 minutes and 2 hours, then stop as failed. An out-of-credit error holds all generation for an hour.

- Password-protected and private posts are not sent. The API key is never printed back, sent to the browser or logged.

## What review changed

An independent review of the build PR fixed these before the merge.

- Cap and lease races. add_option() checks and then upserts, so two runners could both win the lock. The lock is now a single INSERT IGNORE, and the per-post lease is taken under it.

- Approving a candidate that the post had since changed away from produced a visible summary of old text. It now produces a stale, hidden one.

- Prompt injection. Look-alikes of the data delimiters, in any case or spacing, are now removed from the article and the title, and the title is kept to one line.

- Secrets. The API key, bearer tokens and key-shaped strings are redacted from log lines, the last-errors list and a job's last error. Test connection refuses while the kill switch is on.

The review also corrected the spend-meter and gen-queue integrations to match the released contracts, and recorded a billed answer that fails validation as a billed error rather than a success.

## Limits and what is next

- Scripts without spaces, such as Chinese, Japanese and Thai, count one word per two characters.

- The figure check compares numbers only, not units or meaning. The editor is the check.

- The cost cap works only when the provider reports cost.

- Bracketed words such as [sic] are dropped from the source text along with real shortcode tags.

- The plugin clears the post cache but never purges a page cache or CDN. It fires tldr_block_display_changed so you can.

No issues are open on the repo. Test status: this is v0.1.0, tested on stubs and mocks, with model calls stubbed. 102 PHPUnit tests with 907 assertions pass, PHPStan reports no errors and phpcs is clean. CI has not yet run on GitHub, and the plugin has no production mileage.

## Install

It needs WordPress 6.4 or later and PHP 8.1 or later. The library is not on Packagist yet, so add both repositories. The release zip bundles llm-json-php.

{
"repositories": [
{"type": "vcs", "url": "https://github.com/IndianOpinion/llm-json-php"},
{"type": "vcs", "url": "https://github.com/IndianOpinion/tldr-block"}
],
"require": {"indianopinion/tldr-block": "^0.1"}
}

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [tldr-block on GitHub](https://github.com/IndianOpinion/tldr-block)

Canonical: https://indianopinion.org/blog/open-source/tldr-block/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
