@softure-ai/blog 0.0.0-stage → 0.1.6

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+Newest first. Each version lists what changed for an app that uses `@softure-ai/blog`. When an app has run a version in
+production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
+"Definition of done"). Versions before the first one below are described in their GitHub Releases (`blog@x.y.z`).
+
+## 0.1.6
+
+- Adapters and commands use the configured database handle.
+- `@softure-ai/ui` is a peer dependency; the package keeps its own CSS.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOFTURE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,605 @@
-# Temporary Holding Version
+# @softure-ai/blog
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Articles and glossary terms kept as Markdown files in the app's repository, and a publish command that
+brings the module's tables to the state of those files. The files are the source of truth: there is no
+editor and no CMS, a text changes only through a commit and `softure-blog publish`.
+
+## 1. What it provides
+
+- A strict article file format: a YAML frontmatter with English keys (an unknown key is an error),
+  extendable by the app's own fields, then the Markdown body.
+- `blog.articles` and `blog.slug_history` with database constraints for every invariant that fits one.
+- `softure-blog publish`: a dry run by default; with `--commit`, all files or none; unchanged files are
+  skipped by their content hash; a slug change keeps the old slug as a redirect; one pillar per cluster.
+- Read functions for the pages: `getPublishedArticle`, `findArticleBySlug`, `findSlugRedirect`,
+  `listArticles`.
+- `renderArticle(markdown, options)`: the body as safe HTML on the server (no raw HTML, safe link
+  schemes only, marked external links, images under the app's image policy), heading ids and an
+  optional table of contents, glossary links on the first mention of a term, block plugins for the
+  app's own fenced blocks, reading time.
+- Pages, each mounted with one re-export line (`@softure-ai/blog/next`): the listing grouped by cluster
+  with the pillar first, an article (dates, summary, contents, FAQ, sources, signature, disclaimer,
+  `BlogPosting`/`BreadcrumbList`/`FAQPage` JSON-LD), the glossary index and a term page (`DefinedTerm`,
+  the articles that explain it), the optional "how our texts are made" page, an article's OG card.
+  Their canonical, Open Graph, JSON-LD and feed URLs follow `@softure-ai/seo`'s origin, host and
+  trailing-slash rule when the app lists `seo()` (core's `getSiteUrls`), and `appOrigin` otherwise.
+- `createBlogRedirects` (`@softure-ai/blog/proxy`): 301 from an old slug, 410 for a withdrawn text,
+  in the app's `proxy.ts`.
+- `@softure-ai/blog/styles.css`: the pages and the rendered body on the `--sft-*` tokens.
+- Discovery: an RSS 2.0 feed (`serveBlogRss`), "read next" under every article (its cluster first, the
+  pillar on top), and, with `@softure-ai/seo` (optional): sitemap entries with each text's real
+  `lastmod` (`blogSitemap()`) and an IndexNow submit of the changed addresses after
+  `softure-blog publish --commit` (`submitBlogChanges` for an app's own publishing path).
+- A cache refresh route (`refreshBlogCache`, rate-limited through `@softure-ai/security`, a secret from
+  `BLOG_REFRESH_SECRET`): `softure-blog publish --commit` calls it before the IndexNow submit, so the
+  running app shows the change at once instead of after `revalidateSeconds`.
+- A text quality gate: `softure-blog check` reports structure, link, style, voice and YMYL findings
+  with file and line, and `publish` refuses a text going public with an error. Language rulesets
+  (`en`, `pl`), severity overrides and rule plugins for the app's own domain.
+- `softure-blog skill install`: an agent skill for writing the texts, generated from the gate's rules
+  and the app's config, with `--check` for CI.
+
+## 2. Installation
+
+```bash
+npm install @softure-ai/blog @softure-ai/ui
+```
+
+`@softure-ai/ui` is a peer dependency (any 0.1.x), like the optional `@softure-ai/security` and
+`@softure-ai/seo`: the app installs it once, so the theme tokens come from one copy. Importing
+`@softure-ai/blog/styles.css` from JavaScript is safe with tree-shaking, because the package marks its CSS as a side
+effect.
+
+Then add `blog()` to the modules of `softure.config.ts` and run `softure migrate`.
+
+## 3. Configuration
+
+```ts
+import { blog } from "@softure-ai/blog";
+import { pl } from "./messages/pl";
+import { z } from "zod";
+
+blog({
+  // The folder `softure-blog publish` reads when no path is given. Default: "content/blog".
+  contentDir: "content/blog",
+  // Extra slugs an article may not take. The routes' own segments (the glossary, the method page
+  // when on) are reserved by themselves. Default: none.
+  reservedSlugs: [],
+  // The app's own frontmatter keys, checked by the app's schema. Default: none.
+  fields: z.object({ scenario: z.string().regex(/^[a-z]=\d+(&[a-z]=\d+)*$/).optional() }),
+  // The pages' brand: title suffix, signature, JSON-LD author and publisher, OG card colours (hex)
+  // and fonts (§8). Default: none (no suffix, no author, the ui theme's dark colours, next/og's font).
+  brand: { name: "FIRE Tracker", colors: { background: "#0b0b0c", foreground: "#f5f5f5", accent: "#7aa2f7" } },
+  // Mount the method page at routes.method. Default: false (the route answers 404).
+  methodPage: true,
+  // A note under every article and term, per locale (en required). Default: none.
+  disclaimer: { en: "Education, not financial advice.", pl: pl.blog.disclaimer },
+  // The heading of each cluster on the listing, per locale; a missing key shows the key. Default: {}.
+  clusters: { "investing-basics": { en: "Investing basics", pl: pl.blog.investingBasics } },
+  // Block plugins of renderArticle, used by the pages. Default: [].
+  blocks: [],
+  // Hosts of the app besides APP_ORIGIN's and seo's canonical host, whose links are not external. Default: [].
+  siteHosts: ["www.example.com"],
+  // Which images bodies may show: site paths and https images on these hosts (subdomains included),
+  // with a width and height the app knows. Used by the pages and the quality gate. Default: none
+  // (every image renders as its alt text and the gate refuses it).
+  images: { hosts: ["cdn.example.com"], dimensions: (src) => imageSizes[src] ?? null },
+  // How long the cached reads hold; keep equal to the pages' `revalidate`. Default: 300.
+  revalidateSeconds: 300,
+  // The app's own sections of the generated writing skill (see "The writing skill"). Default: none.
+  skill: { sections: [] },
+  // Every route can move: blog({ routes: { index: "/articles" } }).
+});
+```
+
+Routes: `index` `/blog` (articles at `/blog/<slug>`), `glossary` `/blog/glossary` (terms at
+`/blog/glossary/<slug>`), `method` `/blog/how-we-write`.
+
+`fields` may not reuse a key of the module (`FRONTMATTER_KEYS`). Its parsed value is stored in
+`articles.fields`, enters the content hash and must be plain JSON.
+
+### The quality gate
+
+On by default with the `en` ruleset; `quality: false` turns it off. Every key is optional:
+
+```ts
+blog({
+  quality: {
+    language: "pl",                        // the ruleset: "en" (default) or "pl"
+    ymyl: { ownCalculationMark: "our calculation" }, // or true / false (default): sources, sourced numbers, no profit promises
+    voice: {
+      forbidFirstPersonSingular: true,     // texts signed by the editors: no "I", "my"
+      // a global RegExp; wordPattern (from @softure-ai/blog) adds the i flag and word edges in any alphabet
+      phrases: [{ id: "finance-cliche", pattern: wordPattern("in the world of finance"), message: "say what happens instead" }],
+    },
+    limits: { words: { article: { min: 600, max: 4000 } }, answerWords: 70 }, // FIRE's values are the defaults
+    severity: { exclamation: "error", "lead-number": "off" }, // per rule: "error", "warning" or "off"
+    paths: { articles: "/blog", terms: "/blog/glossary" },    // where internal links to texts point
+    ownOrigins: ["https://www.example.com"], // absolute links that count as internal, besides appOrigin and seo's origin
+    appDir: "src/app",                     // routes for internal links; default src/app, else app
+    privateRouteSegments: ["api", "(app)"], // route folders that are no link target; default ["api"]
+    plugins: [factsPlugin],                // the app's own rules, see Hooks
+    blocks: [chartBlock],                  // the block plugins of renderArticle: their requires are checked
+  },
+});
+```
+
+The rules, by group (`listQualityRules(getQualitySettings(config))` lists them with their effective
+severity; the writing skill is kept in step with it):
+
+| Group | Rules (errors **bold**) |
+| --- | --- |
+| file | **`file`**: the frontmatter parses and the slug equals the file name |
+| structure | `title-length`, `description-length`, **`as-of-future`**, `stale`, **`summary-missing`**, **`lead`** (a paragraph first), `lead-length`, **`lead-number`**, **`heading-h1`**, **`heading-order`**, **`sections`** (two `##`), **`section-question`**, **`section-answer`**, `section-answer-length`, **`length`** (a warning above the maximum), **`footnote-undefined`**, `footnote-unused` |
+| links | **`internal-links`** (a warning for a term), **`internal-link-target`** (`check` only), `external-link-https`, **`external-link-dead`** (`--external` only), **`term-form-conflict`** (`check` only: a checked published term shares a form with another published term; `publish` refuses it whatever its severity) |
+| images | **`image-source`** (a site path or a host of `blog({ images })`; every image while the app has no policy), **`image-alt`**, **`image-dimensions`** (the policy's `dimensions` knows it) |
+| style (ruleset) | **`announcement`**, **`these-days`**, **`not-only-but-also`**, **`not-x-but-y`**, **`meta-commentary`**, **`throat-clearing`**, **`empty-conclusion`**, **`crucial`**, **`plays-a-role`**, **`puffery`**, **`chatbot-phrases`**, **`emoji`**, `filler-words`, `exclamation`, `straight-quotes` (`pl`), `title-case-heading` (`pl`) |
+| style (rhythm) | **`dashes`**, `dashes-paragraph`, `bold-density`, `bold-labels`, `triads`, `long-sentences`, `monotone-rhythm`, `repeated-openings` |
+| voice | **`first-person-singular`** and the app's phrases, when configured |
+| ymyl | **`sources-missing`**, **`source-https`**, **`number-source`**, **`footnote-source`**, **`footnote-not-in-sources`**, **`profit-promise`**, when `ymyl` is on |
+| blocks | **`block-requires`**: a fenced block of a block plugin has the frontmatter keys it `requires`, when `blocks` is set |
+| plugin | the plugins' rules, **`plugin-failed`**, **`plugin-rule-undeclared`** |
+
+Style patterns match the prose of the body and the title, description and summary (errors only
+there). A warning pattern is reported once per text with its count. A significant number is an
+amount, a percentage or a number from 1000 up, in the ruleset's notation; years, ages, small counts
+and legal references ("art. 27", "section 401") need no source. Messages are English: they are read
+by developers and by the agents that write the texts.
+
+### The article file
+
+One file per text, named `<slug>.md`:
+
+```markdown
+---
+id: index-funds            # stable key, given once; never change it
+slug: index-funds          # the address; equals the file name without .md
+kind: article              # article | term (a glossary definition); default article
+forms: [tax wrapper]       # term only, required: the phrases that link to the definition
+cluster: investing-basics  # the topic for "read next" lists; optional
+pillar: true               # the main text of its cluster: one per cluster, needs cluster; default false
+title: Index funds in plain words
+description: One or two sentences for search results and the social card.
+summary: A few sentences with numbers for the "in short" box; optional.
+status: published          # draft | published | withdrawn
+current_as_of: 2026-10-01  # the day the facts were checked
+published_at: 2026-10-01   # optional; a day (midnight UTC) or a moment with an offset; default: first publication
+sources:
+  - name: Fund factsheet
+    url: https://example.com/factsheet
+faq:
+  - question: Is it safe?
+    answer: It follows the market, up and down.
+---
+
+The Markdown body.
+```
+
+Rules:
+
+- **Slug change:** change `slug` and rename the file, keep `id`. The old slug goes to the slug history
+  and redirects to the new one. A slug another article has now, or had before, is refused.
+- **Glossary forms:** a form belongs to one published term (forms equal up to a capital first letter
+  are one). `publish` refuses a run that leaves a form with two terms, one of them in the run, naming
+  the form and both slugs; a conflict only between stored terms is a warning. `check` reports it as
+  `term-form-conflict`. The renderer links such a form to the first term it was given.
+- **Withdrawal:** `status: withdrawn`. The row stays and its address answers 410. Do not delete the
+  file: a deleted file changes nothing in the database.
+- **Update date:** `updated_at` moves by itself when the content of a published text changes (title,
+  description, summary, body, date of the facts, sources, FAQ, cluster, forms, fields), never on a
+  status, slug, publication date or pillar change alone.
+
+## 4. Mounting
+
+Each page is one file in the app. Next reads `dynamic` and `revalidate` only as literals in the app's
+own file, so they stay there; `revalidate` should equal `revalidateSeconds`.
+
+```tsx
+// app/blog/page.tsx: the listing, rendered per request over cached reads
+export { BlogIndexPage as default, generateBlogIndexMetadata as generateMetadata } from "@softure-ai/blog/next";
+export const dynamic = "force-dynamic";
+
+// app/blog/[slug]/page.tsx: an article, kept for 300 s (ISR); slots take the app's components
+import { BlogArticlePage, type BlogArticlePageProps } from "@softure-ai/blog/next";
+export { generateArticleMetadata as generateMetadata, generateBlogStaticParams as generateStaticParams } from "@softure-ai/blog/next";
+export const revalidate = 300;
+export default function Page({ params }: Pick<BlogArticlePageProps, "params">) {
+  return <BlogArticlePage params={params} cta={<MyCta />} afterArticle={<Waitlist placement="blog" />} />;
+}
+
+// app/blog/[slug]/opengraph-image.tsx
+export { BlogArticleOgImage as default, generateBlogStaticParams as generateStaticParams } from "@softure-ai/blog/next";
+export const size = { width: 1200, height: 630 };
+export const contentType = "image/png";
+export const revalidate = 300;
+
+// app/blog/glossary/page.tsx          GlossaryIndexPage, generateGlossaryIndexMetadata; dynamic = "force-dynamic"
+// app/blog/glossary/[slug]/page.tsx   GlossaryTermPage, generateTermMetadata, generateBlogStaticParams; revalidate
+// app/blog/how-we-write/page.tsx      BlogMethodPage, generateMethodMetadata (with methodPage: true)
+
+// app/blog/rss.xml/route.ts: the feed of published articles and terms, linked from the listing and articles
+export { serveBlogRss as GET } from "@softure-ai/blog/next";
+export const dynamic = "force-dynamic";
+```
+
+With `@softure-ai/seo`, the blog joins its sitemap through a contributor; `app/sitemap.ts` must then be
+`force-dynamic` (the contributor reads the database):
+
+```ts
+// softure.config.ts (the root entry: this file also loads in plain Node and in bundles outside Next)
+import { blog, blogSitemap } from "@softure-ai/blog";
+seo({ sitemap: { contributors: [blogSitemap()] }, indexNow: { key: "..." } });
+```
+
+The entries are the listing, the articles, the glossary and its terms, each dated by its last content
+change (`updated_at`, else `published_at`), and the method page without a date; an empty listing or
+glossary is left out (it is `noindex`). Paths only: seo makes them absolute with its canonical rule.
+The contributor reads with one query per sitemap request, not through the pages' Next cache.
+
+A publish from the command runs outside the app and cannot reach its cache. To show the change at once
+instead of after `revalidateSeconds`, mount the refresh route, list `security()` with the blog's bucket,
+and set one secret (32+ characters, e.g. `openssl rand -base64 32`) as `BLOG_REFRESH_SECRET` for both the
+running app and the command:
+
+```ts
+// app/api/blog/refresh/route.ts (routes.refresh, default /api/blog/refresh)
+export { refreshBlogCache as POST } from "@softure-ai/blog/next";
+
+// softure.config.ts
+import { BLOG_RATE_LIMIT_BUCKETS, blog } from "@softure-ai/blog";
+security({ clientIp: cloudflareIp(), buckets: { ...BLOG_RATE_LIMIT_BUCKETS } });
+```
+
+The route counts every request in the `blog-refresh` bucket (10 per 15 minutes per client address;
+callers without one, such as the command on a private network name, share one count) before it checks
+`Authorization: Bearer <secret>`, then expires the blog's cache tag at once (`revalidateTag(BLOG_CACHE_TAG,
+{ expire: 0 })`: the next request reads the tables, the cached pages included). Answers: 204 refreshed,
+401 a missing or wrong secret, 429 over the bucket (`retry-after`), 503 when counting fails, 500 when
+`BLOG_REFRESH_SECRET` is unset or short (logged by name). Without `security()` or its bucket the route
+throws a setup error naming the fix.
+
+301 and 410 are answered before the page, in `proxy.ts` (Node.js runtime, Next 16):
+
+```ts
+import { createBlogRedirects } from "@softure-ai/blog/proxy";
+const blogRedirects = createBlogRedirects(softureConfig);
+
+export async function proxy(request: NextRequest) {
+  return (await blogRedirects(request)) ?? NextResponse.next();
+}
+```
+
+It handles GET and HEAD on the blog's text paths only, keeps the query on a redirect, remembers a
+decision for 60 s (`ttlMs`) and passes a request on when the database fails. Import the styles after
+ui's: `@import "@softure-ai/blog/styles.css";`. A data change shows after `revalidateSeconds`, or at
+once with `revalidateTag(BLOG_CACHE_TAG, { expire: 0 })` (the refresh route above, for the command). Custom OG fonts: an own `opengraph-image.tsx` calling `renderArticleOgImage({ title, label, brand, fonts })`.
+
+The quality gate resolves internal links through `quality.paths` (default `/blog` and
+`/blog/glossary`, the default routes); an app that moves `routes` sets `quality.paths` to match.
+
+The commands:
+
+```bash
+softure-blog publish [<path>...] [--commit] [--withdraw] [--no-indexnow] [--app-url <origin>] [--config <file>]
+softure-blog check [<path>...] [--external] [--today <YYYY-MM-DD>] [--config <file>]
+softure-blog skill install [--dir <path>] [--command <cmd>] [--check] [--config <file>]
+```
+
+- `<path>` is a file or a folder (every `*.md` but `README.md`, by name); without one, `contentDir`.
+- `--commit` writes; without it the command prints what it would do and writes nothing.
+- `--withdraw` publishes the one given file as `withdrawn` (taking a text down at once); set the file's
+  status too, or the next full publish brings the text back.
+- A done run prints one `cache:` line. With `BLOG_REFRESH_SECRET` set, a commit that changed a text
+  posts to the app's refresh route on `appOrigin` (`--app-url <origin>` for another way in, such as
+  `http://web:3000` in a container network; redirects are not followed) before the IndexNow submit; a
+  dry run prints the address. Without the secret the line says the app shows the change after
+  `revalidateSeconds`. A failed refresh is a warning naming the answer: the publish stays written, the
+  IndexNow submit still goes out and the exit code stays 0. `--no-indexnow` does not skip it.
+- With `seo({ indexNow: { key } })` enabled, a run ends with one `indexnow:` line. A commit submits the
+  addresses whose answer changed (a text public before or after, its old slug after a rename, the
+  listing or the glossary of its kind) as canonical URLs on seo's origin; a dry run prints them;
+  `--no-indexnow` skips the submit (e.g. a local or CI database). A failed submit is a warning: the
+  publish stays written and the exit code stays 0.
+- Exit codes: 0 done, 1 refused or failed (nothing written), 2 usage error.
+
+Output, one line per text, then a summary:
+
+```text
+added index-funds none -> published/index-funds
+changed bonds draft/bonds -> published/bonds
+moved bonds bond-basics -> bonds
+summary: added 1, changed 1, unchanged 12
+dry run: nothing written; pass --commit to write
+```
+
+Like `softure migrate`, the bin loads `softure.config.(ts|mts|js|mjs)` with Node and opens
+`database.handle` when the config sets one, otherwise `database.url`. When Node cannot load the config (path aliases, a bundled container), call
+`runBlogCli` from an app script:
+
+```ts
+// scripts/blog.ts
+import { runBlogCli } from "@softure-ai/blog/cli";
+import config from "../softure.config";
+
+process.exitCode = await runBlogCli({ config, argv: process.argv.slice(2) });
+```
+
+`publish` runs the quality gate on every file going public (status `published`, not `--withdraw`);
+one error refuses the run. The gate in `publish` does not resolve internal link targets, since a
+container that publishes may hold no app folder; run `check` in CI for those. `runBlogCli({ gate })`
+replaces the gate; `runBlogPublish` in `@softure-ai/blog/server` is the same run without a command line.
+After an app's own run, `submitBlogChanges(config, run.changes, { commit: run.committed })` submits the
+same addresses; inside Next, call `revalidateTag(BLOG_CACHE_TAG, { expire: 0 })` first, and outside it
+`requestBlogRefresh(config, run.changes, { commit: run.committed })` (`@softure-ai/blog/server`), so a
+crawler that answers the ping at once gets the new text.
+
+`check` and `skill install` need no database, nor a database URL: the bin loads the config with the
+database optional for them (`@softure-ai/core`'s `withDatabaseOptional`), so a CI job without
+`DATABASE_URL` runs them. An app script that runs them wraps its own import the same way:
+`const { default: config } = await withDatabaseOptional(() => import("../softure.config"))`. `check` reads the
+files (default: `contentDir`), resolves internal links against the app's routes and the published texts
+of `contentDir`, compares the glossary forms of the checked terms with every published term there, reads
+every `brand.fonts` source as the OG card's route does (a path from the working directory, an `https`
+URL fetched, so a job with such a font needs network), and prints one line per finding:
+
+```text
+content/blog/index-funds.md:12: error [crucial] "crucial": a favourite word of language models; name what depends on the thing
+content/blog/bonds.md: OK
+check: 2 file(s), 1 error(s), 0 warning(s): red, do not publish
+```
+
+Exit codes: 0 green (warnings allowed), 1 an error, 2 usage error. `--external` also requests every
+external link (HEAD, then GET when a server refuses HEAD; 2xx after redirects). Run it weekly with the
+reusable workflow of this repository, `.github/workflows/blog-links.yml` (its header holds the
+snippet for the app).
+
+### The writing skill
+
+`softure-blog skill install` writes an agent skill for writing the blog's texts into
+`.claude/skills/blog-write/` (`--dir` to change). It walks the agent through a text: the question,
+facts with sources, a draft by an answer-first structure, a rewrite by the rules, `check`, a
+sceptical second agent with its own prompt, `check --external`, and `publish`. The package ships the
+templates in `skill/`; the command fills them from the app's config:
+
+- the language of the texts, the content folder, the article and glossary paths and every limit;
+- `references/rules.md`: exactly the rules the app's gate enforces (`listQualityRules`), each with
+  its effective severity, what the gate looks for and what to write instead; the app's voice
+  phrases and plugin rules with their own descriptions; a rule set to `"off"` is left out;
+- the YMYL passages (sources, footnotes, the own calculation mark) only when `ymyl` is on, and the
+  editors' "we" when `voice.forbidFirstPersonSingular` is on;
+- the app's own sections from `blog({ skill: { sections } })` (below).
+
+The app adds its own procedure (where its numbers come from, its block plugins, its fields) as sections
+in the config, so a reinstall keeps them and `--check` covers them:
+
+```ts
+blog({
+  skill: {
+    sections: [
+      { title: "Engine numbers", body: "Every number of an example comes from `npm run engine -- <inputs>`." },
+      { title: "Chart block", body: "One `::chart{scenario=\"…\"}` block after the lead, with the frontmatter's `scenario`." },
+    ],
+  },
+});
+```
+
+Install writes them to `references/app.md` (`## <title>` and the body, verbatim, never filled like the
+templates) and `SKILL.md` names them; with no sections the file is not written. A title is one line, unique,
+up to 80 characters; a body holds no `#` or `##` heading outside fenced code (use `###`). An app with long
+sections keeps them in a module of its own and imports them into the config.
+
+`--command` sets how the skill runs the commands (default `npx softure-blog`; an app with a
+`runBlogCli` script passes e.g. `--command "npm run blog --"`). Commit the folder, so agents in a
+fresh clone have it, and run `softure-blog skill install --check` (with the same options) in CI, with no
+`DATABASE_URL` needed: it writes nothing and exits 1, naming the files, when the folder differs from what
+the config gives.
+Install overwrites only a folder whose `SKILL.md` it generated, so it never replaces a skill the app
+wrote itself. That folder belongs to the command: install removes a `.md` file in it that the config no
+longer gives (`references/app.md` once the sections are gone), logging `removed <path>`, and `--check`
+names such a file. With `quality: false` it refuses: the skill is built on the gate.
+
+### Rendering an article
+
+```ts
+import { getPublishedArticle, listArticles, renderArticle, toGlossary } from "@softure-ai/blog/server";
+
+const article = await getPublishedArticle(ctx, slug);
+const glossary = toGlossary(await listArticles(ctx, { kind: "term" }));
+const body = renderArticle(article.bodyMarkdown, {
+  glossary,
+  selfSlug: article.kind === "term" ? article.slug : undefined,
+  termHref: (term) => `/blog/glossary/${term}`, // the default
+  siteHosts: ["example.com"], // subdomains included; other hosts are external
+  images: { hosts: ["cdn.example.com"], dimensions: (src) => imageSizes[src] ?? null }, // see Images below
+  toc: true, // or { maxLevel: 4 }; h2 and h3 by default
+  messages: blogMessages.pl.render, // English by default
+  blocks: [chartBlock],
+  article: { currentAsOf: article.currentAsOf, fields: article.fields },
+});
+// body.html (null when a block returned a node), body.segments, body.headings, body.toc,
+// body.linkedTerms, body.readingMinutes
+```
+
+- **Allowlist by construction:** raw HTML in the text is escaped, so the output holds only the
+  elements Markdown produces. Links keep `http(s)`, `mailto`, relative and `#` targets; any other
+  scheme (`javascript:`, `data:`, entity-encoded or split by whitespace) stays text.
+- **Images** (`![alt](src "title")`) follow the image policy (`images`): the source is a site path
+  (`/images/x.png`; never `//host` or a path relative to the page) or an `https:` URL on a host in
+  `images.hosts` (subdomains included), the alt text is not empty, and `images.dimensions(src)` returns
+  positive whole `{ width, height }`. Such an image renders as `<img class="blog-image">` with its
+  `width`, `height`, `loading="lazy"` and `decoding="async"`; any other renders as its alt text, and
+  without `images` every image does. `src` is the URL the page requests (percent-encoded: a space is
+  `%20`). A throwing `dimensions` fails the render (a bug); the gate reports it as `image-dimensions`.
+  `checkArticleImage` and `findArticleImages` give the same verdict and the images of a text.
+- **External links** (`http(s)` or `//` to a host outside `siteHosts`) get `rel="noopener noreferrer"`,
+  `target="_blank"`, a `↗` marker hidden from screen readers and a visually hidden "(opens in a new tab)".
+- **Headings** get ids from their text (letters folded to ASCII, `-2` for a repeat, `section` without
+  letters); `toc` renders `<nav class="blog-toc">` with nested lists.
+- **Glossary:** the first mention of each term form links to its definition; never inside headings,
+  links, code or footnotes, never a term page to itself. The longest form wins, word bounds are
+  Unicode-aware, case is as written (plus a capital first letter). A hand-written link to a term counts.
+- **Footnotes** (`[^id]`) become numbered references and a notes section with links back.
+
+**Block plugins.** A top-level fence whose type an app registers is rendered by the app:
+
+````md
+```chart wealth
+scenario: early-retirement
+```
+````
+
+```ts
+const chartBlock: BlockPlugin = {
+  type: "chart",
+  requires: ["current_as_of", "scenario"], // frontmatter keys the block reads, for the quality gate
+  render: ({ info, content, article }) => ({ kind: "html", html: renderChart(info, content, article) }),
+  // or { kind: "node", node: <Chart … /> } for a React server component
+};
+```
+
+Plugin output is the app's own code and is trusted as is: escape what goes into its HTML. A plugin
+that throws fails the render (a bug, not content). Without the plugin the same fence renders as a code
+block. `findArticleBlocks(markdown, plugins)` lists the blocks a text uses with their line and
+`requires`, without rendering. When any block returns a node, `html` is `null`: render `segments` in
+order (`html` segments as HTML, `node` segments as they are).
+
+## 5. Migrations and tables
+
+Schema `blog`, migration `0001_create_articles.sql`:
+
+| Table | Holds |
+| --- | --- |
+| `blog.articles` | one row per text: id, slug, kind, cluster, pillar, title, description, summary, body, status, `current_as_of`, `published_at`, `updated_at`, sources, FAQ, term forms, the app's fields, content hash, `created_at` |
+| `blog.slug_history` | each old slug with its article (the 301 target); removed with the article |
+
+Constraints: id, slug, cluster and old slug kebab-case (at most 100 characters); kind and status
+closed lists; text lengths; a published text has a publication date; an update date needs one; a
+pillar has a cluster; a term has forms and an article has none; a unique slug; one pillar per cluster
+among texts not withdrawn (an exclusion constraint deferred to commit, so one run can move the pillar).
+"A slug is not in another article's history" stays in the code, under a row lock; the check reads the current
+slugs before the old ones, so a slug that another run is renaming away from is refused, naming that article,
+whether the rename has committed or not. A run that loses a race for
+a slug (another run committed it between the read and the write) is refused with `blog.slug_taken`,
+naming the article that took it, like any other taken slug.
+
+## 6. Environment variables
+
+| Variable | Required | Read by |
+| --- | --- | --- |
+| `BLOG_REFRESH_SECRET` | no | the refresh route (`refreshBlogCache`) and `softure-blog publish`: the shared secret, 32+ characters; without it a publish shows after `revalidateSeconds` |
+
+The command reads the database URL from the app's config.
+
+## 7. Switches
+
+None.
+
+## 8. Appearance
+
+`styles.css` styles every `blog-*` class of the pages and of the rendered body (`blog-external`,
+`blog-external-marker`, `blog-visually-hidden`, `blog-term`, `blog-toc`, `blog-footnote-ref`,
+`blog-footnotes`, `blog-footnote-back`) with the `--sft-*` tokens of `@softure-ai/ui`, in the
+`softure` layer, so the app's own rules win. The OG card takes `brand.colors`, else ui's dark theme.
+
+The OG card writes in `brand.fonts`, else in `next/og`'s default font:
+
+```ts
+blog({
+  brand: {
+    name: "FIRE Tracker",
+    fonts: [
+      // weight: 100…900 (default 400), style: "normal" | "italic" (default "normal")
+      { name: "Inter", weight: 400, src: "assets/fonts/inter-latin-400-normal.woff" },
+      { name: "Inter", weight: 700, src: "assets/fonts/inter-latin-700-normal.woff" },
+      // a second file of one weight (a latin-ext subset) under its own name: the card lists every name
+      // in order, so it draws the characters the first file lacks
+      { name: "Inter Ext", weight: 700, src: "https://cdn.example.com/inter-latin-ext-700-normal.woff" },
+    ],
+  },
+});
+```
+
+- `src` is a `.ttf`, `.otf` or `.woff` file (Satori does not read `.woff2`): a path from the app's root,
+  an absolute path, or an `https` URL. Marketing-kit's subset files (`brand.fonts` of `marketing.json`)
+  fit as they are.
+- The card's route reads each file on its first card and keeps it for the life of the process. A file
+  that cannot be read, or is not such a font, fails the card with a message naming `brand.fonts[i]` and
+  the file; the next card tries again. `softure-blog check` reads the same sources, so CI reports such a
+  file first (`softure-blog check: Blog OG card: brand.fonts[0] …`, one error, exit 1).
+- Paths are read on the Node.js runtime (the route's default). With `output: "standalone"`, list the
+  folder in `outputFileTracingIncludes` (`{ "/blog/[slug]/opengraph-image": ["./assets/fonts/**"] }`);
+  a route moved to the edge runtime takes `https` URLs only.
+- With brand fonts the card has no other font: a character none of them has is not drawn.
+
+## 9. Copy
+
+`src/messages/`: labels of the kinds (`kinds.article`, `kinds.term`) and statuses (`statuses.*`) in
+`en` and `pl`; the renderer's copy under `render.*` (notes heading, footnote label with `{number}`,
+back to text, opens in a new tab, contents label), passed as `renderArticle({ messages })`; the pages'
+copy under `pages.*`, `glossary.*`, `method.*`, `gone.*` (the 410 page), `og.*` and `feed.*` (the feed's 503 body); "read next" is `pages.readNext`. Override any of it
+with `blog({ messages: { pl: { pages: { readMore: "..." } } } })`. Command output and file errors are developer output, in English.
+
+## 10. Hooks
+
+- `blog({ fields })`: the app's frontmatter schema (FIRE_TRACKER's calculator scenario lives here).
+- `gate` of `runBlogPublish` and `runBlogCli`: `(file, article) => problems`, called only for files
+  going public; any problem refuses the whole run. Default in `runBlogCli`: `createQualityGate`.
+- `blog({ quality: { plugins } })`: the app's domain rules. A plugin declares its rules and checks one
+  text at a time; it is pure (no network, no file system) and its findings take part in severity
+  overrides and the catalog. A throw becomes `plugin-failed`, an undeclared rule id
+  `plugin-rule-undeclared`.
+
+```ts
+import type { QualityPlugin } from "@softure-ai/blog/server";
+
+export const tickerPlugin: QualityPlugin = {
+  name: "tickers",
+  rules: [{ id: "ticker-format", severity: "error", description: "tickers are written in capitals" }],
+  check: ({ blocks }) =>
+    blocks
+      .filter((block) => /\$[a-z]{2,5}\b/.test(block.text))
+      .map((block) => ({ rule: "ticker-format", severity: "error", message: "write the ticker in capitals", line: block.line })),
+};
+```
+
+  The context holds the parsed `article` (with the app's `fields`), the body `blocks` with file lines
+  (directives such as `::chart{…}` are blocks of their own), the fenced `pluginBlocks` of the block
+  plugins in `quality.blocks` (type, info, fence line, `requires`), `today` and the language `ruleset` (for
+  its number notation); the text helpers (`toProse`, `splitSentences`, `findSignificantNumbers`, …) are
+  exported from `@softure-ai/blog/server`.
+- `renderArticle({ blocks })` and `blog({ blocks })`: block plugins for the app's fenced blocks
+  (FIRE_TRACKER's engine chart).
+- The pages' `cta` and `afterArticle` slots: the app's call to action and blocks (a waitlist form).
+
+## 11. GDPR
+
+Articles hold editorial content, no personal data: nothing to export or delete.
+
+## 12. Limitations
+
+- Two runs that rename one article away from a slug and give it to another at the same moment can leave the
+  slug both current and in the slug history (BF-12).
+- The content hash is part of the contract: a field added later enters it only when present.
+- No `--stdin` (a deploy transport).
+- The refresh route expires the cache of the instance that answers it. With several instances and Next's
+  default (in-memory) cache handler, the others show a publish after `revalidateSeconds`; a shared cache
+  handler covers them.
+- The renderer has no raw HTML and no figures: an image has no caption, and the app hosts and sizes its
+  images itself (no `next/image`). A plugin fence inside a list or a quote stays a code
+  block (a block node cannot sit inside a list's HTML).
+- The gate reads Markdown line by line (blocks, not a syntax tree): enough for the rules, not a
+  renderer. Fenced code and HTML comments are skipped.
+- **Adopting FIRE_TRACKER's gate:** `language: "pl"`, `ymyl: { ownCalculationMark }` with its calculation
+  footnote's phrase, `voice.forbidFirstPersonSingular: true` plus its finance phrases, its domain as
+  `ownOrigins`, `privateRouteSegments: ["api", "(app)"]`, and `rules-facts.ts` and `rules-chart.ts`
+  as plugins (the package's tests hold stand-ins of both). Rule ids are English now (`kluczowy` →
+  `crucial`, `myslniki` → `dashes`, …; the map is in the change archive), and the writing skill
+  (`skill install`, replacing FIRE's `blog-pisz`) names them; FIRE's engine numbers, calculator scenario
+  and chart block go into `blog({ skill: { sections } })`.
+- **Adopting from FIRE_TRACKER:** rename the frontmatter keys once (`typ` → `kind` with `artykul` →
+  `article` and `termin` → `term`, `formy` → `forms`, `klaster` → `cluster`, `filar` → `pillar`,
+  `tytul` → `title`, `opis` → `description`, `w_skrocie` → `summary`, `aktualne_na` →
+  `current_as_of`, `opublikowano` → `published_at`, `zrodla` → `sources` with `nazwa` → `name`,
+  `faq` items `pytanie` → `question` and `odpowiedz` → `answer`), move `scenariusz` into the app's
+  `fields`, and copy the rows into `blog.articles` with the hash the package computes from the renamed
+  files, or the first publish marks every published text as updated.

package/dist/cli/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":""}

package/dist/cli/bin.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The `softure-blog` executable. All logic lives in command.ts and run.ts, which the tests call directly.
+import { runBlogCommand } from "./command.js";
+process.exitCode = await runBlogCommand({ argv: process.argv.slice(2), cwd: process.cwd() });
+//# sourceMappingURL=bin.js.map