openbriefing 0.3.0 → 0.5.0

package/README.md

@@ -21,6 +21,59 @@ npx openbriefing check https://example.com/sitemap.xml --sitemap
 
 Fetching is bounded: `http` and `https` only, 10 seconds, 5 MB, 5 redirects, and it names itself `openbriefing-check/<version>`.
 
+## Write your tags
+
+A briefing file is a few lines of YAML that you, or your assistant, write for a post. `tags` turns it into escaped tags.
+
+```yaml
+url: https://example.com/a-post/
+headline: One or two lines to hear before going further.
+summary: |
+  Your summary, in plain text. Around 200 to 350 words.
+
+  A blank line is a paragraph break.
+keep:
+  - The one sentence every version must get across.
+highlights:
+  - text: A passage from the post, word for word.
+    label: On control
+attribution: From Example Blog
+status: approved
+```
+
+```sh
+npx openbriefing tags a-post.yaml                 # meta tags for the page's head
+npx openbriefing tags a-post.yaml --format feed   # elements for an RSS item or Atom entry
+npx openbriefing tags content/a-post.md           # the same keys under obs: in a post's front matter
+```
+
+A file whose `status` is not `approved` is refused (exit 1) unless you pass `--allow-draft`, so a build cannot publish a draft by accident. A drafting prompt for your assistant, and a builder that does the same in the browser, are at [openbriefingstandard.org/publish](https://openbriefingstandard.org/publish).
+
+### Ghost
+
+```sh
+export GHOST_URL=https://your-site.example
+export GHOST_ADMIN_API_KEY=…   # Ghost Admin → Integrations → add a custom integration
+
+npx openbriefing ghost pull posts/             # one file per published post, with its text
+npx openbriefing ghost push posts/ --dry-run   # say what would be written
+npx openbriefing ghost push posts/             # write the approved ones
+```
+
+`pull` never changes Ghost and never overwrites a file. `push` writes only approved files, only between `<!-- obs:start -->` and `<!-- obs:end -->` in the post's Code injection header, and skips a post whose tags have not changed. The folder holds your posts: keep it out of public repositories.
+
+To have the tags written when a post is published, run the hook where Ghost can reach it:
+
+```bash
+export GHOST_WEBHOOK_SECRET=…                   # any long random text
+export ANTHROPIC_API_KEY=…
+export OBS_HOOK_URL=https://your-hook.example   # registers the two webhooks on start
+npx openbriefing ghost hook                     # POST /ghost, GET /healthz, on PORT or 8080
+npx openbriefing ghost draft --dry-run          # the same for posts already published
+```
+
+The hook drafts with Claude (`OBS_MODEL` picks the model), keeps only highlights it finds in the post, and stamps its block `<!-- obs:auto … -->`. Edit the tags in the post's Code injection and they are yours: the hook never writes to that post again. It leaves members-only posts and posts under 200 words alone. These tags are published before you read them; use `pull` and `push` if you would rather approve each one.
+
 ## Use the parser
 
 ```ts

package/dist/briefing.d.ts

@@ -0,0 +1,46 @@
+import { type ObsBrief } from "./obs.js";
+export type BriefingStatus = "draft" | "approved";
+export interface Briefing {
+    /** "draft" unless the file says `status: approved`. */
+    status: BriefingStatus;
+    /** Absent when the file has no usable summary. */
+    brief?: ObsBrief;
+    errors: string[];
+    warnings: string[];
+    /** The post's slug, from the file's front matter, when given. */
+    slug?: string;
+    /** The post's own text, when the file is a post with front matter. */
+    body?: string;
+}
+/** Reads a briefing file, or a post whose front matter has an `obs:` key. Never throws. */
+export declare function parseBriefing(text: string): Briefing;
+/** Marks each highlight found or not found in the post's text, as `check` does for a page (§7). */
+export declare function checkHighlights(brief: ObsBrief, postText: string, warnings: string[]): void;
+export declare function escapeAttr(value: string): string;
+export type TagFormat = "html" | "feed";
+/**
+ * A brief written as tags, every character escaped: meta tags for a page's
+ * head, or the elements of §14 for an RSS item or Atom entry.
+ */
+export declare function renderTags(brief: ObsBrief, format?: TagFormat): string;
+export declare const MARK_START = "<!-- obs:start -->";
+export declare const MARK_END = "<!-- obs:end -->";
+export declare const DRAFT_NOTE = "<!-- obs: a draft, not yet approved by the author -->";
+/** Tags between the obs:start and obs:end comments. */
+export declare function markTags(tags: string, draft?: boolean): string;
+/** The marked block in a field, markers included, when there is one. */
+export declare function readMarked(field: string): string | undefined;
+/**
+ * Puts a marked block into a field. An existing block is replaced where it
+ * stands; otherwise the block goes at the end. Nothing outside the markers
+ * changes.
+ */
+export declare function replaceMarked(field: string, block: string): string;
+/** The briefing-file keys for a brief, in the order a person reads them. */
+export declare function briefingFields(brief: ObsBrief, status: BriefingStatus): Record<string, unknown>;
+/** A briefing file's YAML for the given keys. */
+export declare function briefingYaml(fields: Record<string, unknown>): string;
+/** A post file: front matter with the post's details and an `obs:` key, then the post's text. */
+export declare function postFile(front: Record<string, unknown>, body: string): string;
+/** The same keys as front matter for a static site: an `obs:` block to paste into a post. */
+export declare function frontMatterBlock(brief: ObsBrief): string;

package/dist/briefing.js

@@ -0,0 +1,343 @@
+/**
+ * The briefing file: a small YAML file (or the same keys under `obs:` in a
+ * post's front matter) that a person or an assistant writes, and the tags it
+ * turns into. A tool convention, not part of the standard.
+ *
+ * Browser-safe: no platform API, so the site's tag builder runs the same code.
+ */
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { looseText, validateObs } from "./obs.js";
+const KEYS = new Set([
+    "url",
+    "title",
+    "headline",
+    "summary",
+    "summary_short",
+    "summary_medium",
+    "summary_long",
+    "keep",
+    "highlights",
+    "attribution",
+    "derive",
+    "translate",
+    "combine",
+    "preference",
+    "lang",
+    "modified",
+    "status",
+]);
+const FRONT_MATTER = /^?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/u;
+/** A block of text as one value: a wrapped line is a space, a blank line is a paragraph break. */
+function paragraphs(v) {
+    return v
+        .replace(/\r\n?/gu, "\n")
+        .split(/\n[ \t]*\n+/u)
+        .map((p) => p.replace(/\s*\n\s*/gu, " ").trim())
+        .filter((p) => p !== "")
+        .join("\n\n");
+}
+const yesNo = (v) => {
+    if (typeof v === "boolean")
+        return v;
+    if (typeof v === "string") {
+        const s = v.trim().toLowerCase();
+        if (s === "yes" || s === "true")
+            return true;
+        if (s === "no" || s === "false")
+            return false;
+    }
+    return undefined;
+};
+/** Reads a briefing file, or a post whose front matter has an `obs:` key. Never throws. */
+export function parseBriefing(text) {
+    const out = { status: "draft", errors: [], warnings: [] };
+    let data;
+    let fields;
+    try {
+        const fm = FRONT_MATTER.exec(text);
+        if (fm) {
+            data = parseYaml(fm[1]);
+            const body = (fm[2] ?? "").trim();
+            if (body !== "")
+                out.body = body;
+            const rec = data !== null && typeof data === "object" ? data : {};
+            if (rec.obs === undefined || rec.obs === null) {
+                out.errors.push("The front matter has no obs: key");
+                return out;
+            }
+            fields = rec.obs;
+            if (typeof rec.slug === "string" && rec.slug.trim() !== "")
+                out.slug = rec.slug.trim();
+        }
+        else {
+            data = parseYaml(text);
+            fields = data !== null && typeof data === "object" && !Array.isArray(data) && "obs" in data && Object.keys(data).length === 1 ? data.obs : data;
+        }
+    }
+    catch (err) {
+        out.errors.push(`The file is not valid YAML: ${err instanceof Error ? (err.message.split("\n")[0] ?? err.message) : String(err)}`);
+        return out;
+    }
+    if (fields === null || typeof fields !== "object" || Array.isArray(fields)) {
+        out.errors.push("Expected keys such as summary: and headline:");
+        return out;
+    }
+    const f = fields;
+    for (const key of Object.keys(f))
+        if (!KEYS.has(key))
+            out.warnings.push(`${key}: is not a briefing file key; it is ignored`);
+    const status = typeof f.status === "string" ? f.status.trim().toLowerCase() : undefined;
+    if (status === "approved")
+        out.status = "approved";
+    else if (status !== undefined && status !== "draft")
+        out.warnings.push(`status: "${String(f.status)}" is not draft or approved; the file is treated as a draft`);
+    const text1 = (key) => {
+        const v = f[key];
+        if (v === undefined || v === null)
+            return undefined;
+        if (typeof v === "string")
+            return paragraphs(v);
+        if (typeof v === "number" || typeof v === "boolean")
+            return String(v);
+        if (v instanceof Date)
+            return v.toISOString();
+        out.warnings.push(`${key}: is not text; it is ignored`);
+        return undefined;
+    };
+    const shape = { version: 1 };
+    for (const key of ["url", "title", "headline", "attribution", "preference", "lang", "modified"]) {
+        const v = text1(key);
+        if (v !== undefined && v !== "")
+            shape[key] = v;
+    }
+    const summaries = [];
+    const plain = text1("summary");
+    if (plain)
+        summaries.push({ text: plain, from: "inferred" });
+    for (const tier of ["short", "medium", "long"]) {
+        const v = text1(`summary_${tier}`);
+        if (v)
+            summaries.push({ tier, text: v, from: "tiered" });
+    }
+    shape.summaries = summaries;
+    const keep = f.keep;
+    if (typeof keep === "string")
+        shape.keep = [paragraphs(keep)];
+    else if (Array.isArray(keep))
+        shape.keep = keep.filter((k) => typeof k === "string").map(paragraphs);
+    else if (keep !== undefined && keep !== null)
+        out.warnings.push("keep: is not a list of lines; it is ignored");
+    const highlights = f.highlights;
+    if (Array.isArray(highlights)) {
+        shape.highlights = highlights.flatMap((h) => {
+            if (typeof h === "string")
+                return [{ text: paragraphs(h) }];
+            if (h !== null && typeof h === "object" && typeof h.text === "string") {
+                const rec = h;
+                return [typeof rec.label === "string" ? { text: paragraphs(rec.text), label: paragraphs(rec.label) } : { text: paragraphs(rec.text) }];
+            }
+            out.warnings.push("A highlight has no text; it is ignored");
+            return [];
+        });
+    }
+    else if (highlights !== undefined && highlights !== null)
+        out.warnings.push("highlights: is not a list; it is ignored");
+    const derive = {};
+    const mode = text1("derive");
+    if (mode !== undefined)
+        derive.mode = mode;
+    for (const key of ["translate", "combine"]) {
+        if (f[key] === undefined || f[key] === null)
+            continue;
+        const v = yesNo(f[key]);
+        if (v === undefined)
+            out.warnings.push(`${key}: is not yes or no; it is ignored`);
+        else
+            derive[key] = v;
+    }
+    if (Object.keys(derive).length > 0)
+        shape.derive = derive;
+    const result = validateObs(shape);
+    out.errors.push(...result.errors);
+    out.warnings.push(...result.warnings);
+    if (result.brief) {
+        out.brief = result.brief;
+        // The briefing file states the language or leaves it out; there is no page to fall back on.
+        if (shape.lang === undefined)
+            delete out.brief.lang;
+        if (out.body !== undefined)
+            checkHighlights(out.brief, out.body, out.warnings);
+    }
+    return out;
+}
+/** Marks each highlight found or not found in the post's text, as `check` does for a page (§7). */
+export function checkHighlights(brief, postText, warnings) {
+    const body = looseText(postText);
+    if (body === "")
+        return;
+    for (const h of brief.highlights) {
+        h.inContent = body.includes(looseText(h.text));
+        if (!h.inContent) {
+            const head = h.text.split(/\s+/u).slice(0, 6).join(" ");
+            warnings.push(`obs:highlight "${head}…" is not in the post's text (§7)`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Writing tags
+export function escapeAttr(value) {
+    return value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;").replace(/\n/gu, "&#10;");
+}
+const escapeXml = (value) => value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+const escapeXmlAttr = (value) => escapeXml(value).replace(/"/gu, "&quot;").replace(/\n/gu, "&#10;");
+/** One [property, value] pair per tag, in the order the tags are written. Defaults are left out. */
+function pairs(brief) {
+    const out = [];
+    if (brief.version !== 1)
+        out.push(["obs:version", String(brief.version)]);
+    if (brief.title !== undefined)
+        out.push(["obs:title", brief.title]);
+    if (brief.headline !== undefined)
+        out.push(["obs:headline", brief.headline]);
+    for (const s of brief.summaries)
+        out.push([s.from === "tiered" ? `obs:summary:${s.tier}` : "obs:summary", s.text]);
+    for (const k of brief.keep)
+        out.push(["obs:keep", k]);
+    for (const h of brief.highlights) {
+        out.push(["obs:highlight", h.text]);
+        if (h.label !== undefined)
+            out.push(["obs:highlight:label", h.label]);
+    }
+    if (brief.derive.mode !== "anchor")
+        out.push(["obs:derive", brief.derive.mode]);
+    if (!brief.derive.translate)
+        out.push(["obs:derive:translate", "no"]);
+    if (!brief.derive.combine)
+        out.push(["obs:derive:combine", "no"]);
+    if (brief.attribution !== undefined)
+        out.push(["obs:attribution", brief.attribution]);
+    if (brief.preference !== "summary")
+        out.push(["obs:preference", brief.preference]);
+    if (brief.lang !== undefined)
+        out.push(["obs:lang", brief.lang]);
+    if (brief.url !== undefined)
+        out.push(["obs:url", brief.url]);
+    if (brief.modified !== undefined && brief.modifiedFrom === "obs")
+        out.push(["obs:modified", brief.modified]);
+    return out;
+}
+/**
+ * A brief written as tags, every character escaped: meta tags for a page's
+ * head, or the elements of §14 for an RSS item or Atom entry.
+ */
+export function renderTags(brief, format = "html") {
+    const list = pairs(brief);
+    if (format === "html")
+        return list.map(([k, v]) => `<meta property="${k}" content="${escapeAttr(v)}">`).join("\n");
+    const out = [];
+    const derive = [];
+    let mode = "";
+    for (let i = 0; i < list.length; i++) {
+        const [k, v] = list[i];
+        const name = k.slice(4);
+        if (k === "obs:highlight") {
+            const next = list[i + 1];
+            const label = next && next[0] === "obs:highlight:label" ? ` label="${escapeXmlAttr(next[1])}"` : "";
+            out.push(`<obs:highlight${label}>${escapeXml(v)}</obs:highlight>`);
+        }
+        else if (k === "obs:highlight:label")
+            continue;
+        else if (k.startsWith("obs:summary:"))
+            out.push(`<obs:summary length="${k.slice(12)}">${escapeXml(v)}</obs:summary>`);
+        else if (k === "obs:derive")
+            mode = v;
+        else if (k === "obs:derive:translate" || k === "obs:derive:combine")
+            derive.push(` ${k.slice(11)}="${v}"`);
+        else
+            out.push(`<obs:${name}>${escapeXml(v)}</obs:${name}>`);
+    }
+    if (mode !== "" || derive.length > 0) {
+        const at = out.findIndex((l) => l.startsWith("<obs:attribution>") || l.startsWith("<obs:preference>") || l.startsWith("<obs:lang>") || l.startsWith("<obs:url>") || l.startsWith("<obs:modified>"));
+        const line = `<obs:derive${derive.join("")}>${mode === "" ? "anchor" : mode}</obs:derive>`;
+        if (at === -1)
+            out.push(line);
+        else
+            out.splice(at, 0, line);
+    }
+    return out.join("\n");
+}
+// ---------------------------------------------------------------------------
+// The marked block, for a CMS field that holds other code too
+export const MARK_START = "<!-- obs:start -->";
+export const MARK_END = "<!-- obs:end -->";
+export const DRAFT_NOTE = "<!-- obs: a draft, not yet approved by the author -->";
+const MARKED = /<!--\s*obs:start\s*-->[\s\S]*?<!--\s*obs:end\s*-->/u;
+/** Tags between the obs:start and obs:end comments. */
+export function markTags(tags, draft = false) {
+    return [MARK_START, ...(draft ? [DRAFT_NOTE] : []), tags, MARK_END].join("\n");
+}
+/** The marked block in a field, markers included, when there is one. */
+export function readMarked(field) {
+    return MARKED.exec(field)?.[0];
+}
+/**
+ * Puts a marked block into a field. An existing block is replaced where it
+ * stands; otherwise the block goes at the end. Nothing outside the markers
+ * changes.
+ */
+export function replaceMarked(field, block) {
+    if (MARKED.test(field))
+        return field.replace(MARKED, () => block);
+    if (field.trim() === "")
+        return block;
+    return `${field.replace(/\s+$/u, "")}\n${block}`;
+}
+// ---------------------------------------------------------------------------
+// Writing a briefing file
+/** The briefing-file keys for a brief, in the order a person reads them. */
+export function briefingFields(brief, status) {
+    const f = {};
+    if (brief.url !== undefined)
+        f.url = brief.url;
+    if (brief.title !== undefined)
+        f.title = brief.title;
+    if (brief.headline !== undefined)
+        f.headline = brief.headline;
+    for (const s of brief.summaries)
+        f[s.from === "tiered" ? `summary_${s.tier}` : "summary"] = s.text;
+    if (brief.keep.length > 0)
+        f.keep = [...brief.keep];
+    if (brief.highlights.length > 0)
+        f.highlights = brief.highlights.map((h) => (h.label === undefined ? { text: h.text } : { text: h.text, label: h.label }));
+    if (brief.attribution !== undefined)
+        f.attribution = brief.attribution;
+    if (brief.derive.mode !== "anchor")
+        f.derive = brief.derive.mode;
+    if (!brief.derive.translate)
+        f.translate = false;
+    if (!brief.derive.combine)
+        f.combine = false;
+    if (brief.preference !== "summary")
+        f.preference = brief.preference;
+    if (brief.lang !== undefined)
+        f.lang = brief.lang;
+    if (brief.modified !== undefined && brief.modifiedFrom === "obs")
+        f.modified = brief.modified;
+    f.status = status;
+    return f;
+}
+const YAML_OPTIONS = { lineWidth: 0, blockQuote: "literal" };
+/** A briefing file's YAML for the given keys. */
+export function briefingYaml(fields) {
+    return stringifyYaml(fields, YAML_OPTIONS);
+}
+/** A post file: front matter with the post's details and an `obs:` key, then the post's text. */
+export function postFile(front, body) {
+    return `---\n${stringifyYaml(front, YAML_OPTIONS)}---\n\n${body.trim()}\n`;
+}
+/** The same keys as front matter for a static site: an `obs:` block to paste into a post. */
+export function frontMatterBlock(brief) {
+    const fields = briefingFields(brief, "approved");
+    delete fields.status;
+    return stringifyYaml({ obs: fields }, YAML_OPTIONS).trimEnd();
+}

package/dist/cli.js

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
 /**
+ * openbriefing tags <file.yaml | post.md | -> [--format html | feed | json] [--marked] [--allow-draft]
+ * openbriefing ghost pull <folder> [--slug <slug>]
+ * openbriefing ghost push <folder> [--slug <slug>] [--dry-run]
+ * openbriefing ghost draft [--slug <slug>] [--limit <n>] [--dry-run]
+ * openbriefing ghost hook [--port <n>]
  * openbriefing check <url | file | -> [--url <page url>] [--json]
  * openbriefing check <feed url | file> --feed [--pages]
  * openbriefing check <sitemap url | file> --sitemap [--limit <n>]
@@ -11,6 +16,7 @@ import { readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { JSDOM } from "jsdom";
+import { markTags, parseBriefing, renderTags } from "./briefing.js";
 import { DEFAULT_LIMITS, fetchText, isHttpUrl, mapLimit, userAgent } from "./fetch.js";
 import { countWords, fingerprint, mergeObs, parseFeedObs, parseObs, SIZES } from "./obs.js";
 const VERSION = (() => {
@@ -23,11 +29,29 @@ const VERSION = (() => {
 })();
 const LIMITS = { ...DEFAULT_LIMITS, userAgent: userAgent(VERSION) };
 const USAGE = `Usage:
+  openbriefing tags <file.yaml | post.md | -> [--format html | feed | json] [--marked] [--allow-draft]
+  openbriefing ghost pull <folder> [--slug <slug>]
+  openbriefing ghost push <folder> [--slug <slug>] [--dry-run]
+  openbriefing ghost draft [--slug <slug>] [--limit <n>] [--dry-run]
+  openbriefing ghost hook [--port <n>]
   openbriefing check <url | file | -> [--url <page url>] [--json]
   openbriefing check <feed url | file> --feed [--pages]
   openbriefing check <sitemap url | file> --sitemap [--limit <n>]
 
-Checks a page, a feed or a sitemap for Open Briefing Standard tags.
+tags turns a briefing file into escaped tags. ghost pull writes one file per
+published post; ghost push writes each approved file's tags into its post
+(GHOST_URL and GHOST_ADMIN_API_KEY in the environment). ghost draft writes
+tags, drafted by Claude (ANTHROPIC_API_KEY), for each published post that has
+none. ghost hook does the same when a post is published: it serves Ghost's
+webhooks (GHOST_WEBHOOK_SECRET; OBS_HOOK_URL registers them). The author edits
+the tags in the post's Code injection, and an edited post is left alone.
+check reads a page, a feed or a sitemap and prints what a reader sees.
+  --format   html (meta tags, the default), feed (RSS and Atom elements) or json
+  --marked   wrap the tags in the obs:start and obs:end comments
+  --allow-draft  write tags for a file whose status is not approved
+  --slug     with ghost: one post only
+  --dry-run  with ghost push or draft: say what would be written, and write nothing
+  --port     with ghost hook: the port to listen on (PORT, or 8080)
   --url      the page's address, when checking a file with no canonical link
   --feed     treat the input as an RSS or Atom feed (detected when omitted)
   --pages    with a feed: also fetch each item's page and say which one stands
@@ -36,7 +60,7 @@ Checks a page, a feed or a sitemap for Open Briefing Standard tags.
   --json     print the parsed result as JSON
 Spec: https://openbriefingstandard.org`;
 function parseArgs(argv) {
-    const args = { json: false, feed: false, pages: false, sitemap: false };
+    const args = { json: false, feed: false, pages: false, sitemap: false, rest: [], marked: false, allowDraft: false, dryRun: false };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--json")
@@ -47,6 +71,21 @@ function parseArgs(argv) {
             args.pages = true;
         else if (a === "--sitemap")
             args.sitemap = true;
+        else if (a === "--marked")
+            args.marked = true;
+        else if (a === "--allow-draft")
+            args.allowDraft = true;
+        else if (a === "--dry-run")
+            args.dryRun = true;
+        else if (a === "--format" || a === "--slug") {
+            const v = argv[++i];
+            if (v === undefined)
+                args.bad = `${a} needs a value`;
+            else if (a === "--format")
+                args.format = v;
+            else
+                args.slug = v;
+        }
         else if (a === "--url") {
             const v = argv[++i];
             if (v === undefined)
@@ -54,6 +93,13 @@ function parseArgs(argv) {
             else
                 args.url = v;
         }
+        else if (a === "--port") {
+            const n = Number.parseInt(argv[++i] ?? "", 10);
+            if (!Number.isInteger(n) || n < 1 || n > 65535)
+                args.bad = "--port needs a port number";
+            else
+                args.port = n;
+        }
         else if (a === "--limit") {
             const n = Number.parseInt(argv[++i] ?? "", 10);
             if (!Number.isInteger(n) || n < 1)
@@ -71,6 +117,8 @@ function parseArgs(argv) {
             args.command = a;
         else if (args.target === undefined)
             args.target = a;
+        else
+            args.rest.push(a);
     }
     return args;
 }
@@ -303,10 +351,113 @@ async function check(args) {
     console.log(args.json ? JSON.stringify(r, null, 2) : describe(loaded.label, r));
     return r.brief ? 0 : 1;
 }
+function usage(args) {
+    if (args.bad)
+        console.error(`${args.bad}\n`);
+    console.error(USAGE);
+    return 2;
+}
+function tags(args) {
+    const format = args.format ?? "html";
+    if (!args.target || args.bad || !["html", "feed", "json"].includes(format)) {
+        if (!args.bad && args.target)
+            args.bad = `--format is html, feed or json, not ${format}`;
+        return usage(args);
+    }
+    let text;
+    try {
+        text = readFileSync(args.target === "-" ? 0 : args.target, "utf8");
+    }
+    catch (err) {
+        console.error(`Cannot read ${safe(args.target)}: ${err instanceof Error ? err.message : String(err)}`);
+        return 2;
+    }
+    const b = parseBriefing(text);
+    for (const e of b.errors)
+        console.error(`error    ${safe(e)}`);
+    for (const w of b.warnings)
+        console.error(`warning  ${safe(w)}`);
+    if (!b.brief)
+        return 1;
+    if (b.status !== "approved" && !args.allowDraft) {
+        console.error("This file is a draft. Set status: approved once the author has read every line, or pass --allow-draft.");
+        return 1;
+    }
+    if (format === "json") {
+        console.log(JSON.stringify({ status: b.status, fingerprint: fingerprint(b.brief), brief: b.brief, warnings: b.warnings }, null, 2));
+        return 0;
+    }
+    const draft = b.status !== "approved";
+    const out = renderTags(b.brief, format);
+    if (args.marked && format === "html")
+        console.log(markTags(out, draft));
+    else
+        console.log(draft ? `<!-- obs: a draft, not yet approved by the author -->\n${out}` : out);
+    return 0;
+}
+const printLine = (l) => console.log(`${l.state.padEnd(12)} ${safe(l.slug)}${l.note ? `  (${safe(l.note)})` : ""}`);
+function tally(lines) {
+    const count = (s) => lines.filter((l) => l.state === s).length;
+    const states = [...new Set(lines.map((l) => l.state))];
+    console.log(lines.length === 0 ? "Nothing to do." : `\n${states.map((s) => `${count(s)} ${s}`).join(", ")}`);
+    return count("error") > 0 ? 1 : 0;
+}
+async function ghost(args) {
+    const action = args.target;
+    const folder = args.rest[0];
+    const filed = action === "pull" || action === "push";
+    if (args.bad || !(filed || action === "draft" || action === "hook") || (filed && !folder))
+        return usage(args);
+    const url = process.env.GHOST_URL;
+    const key = process.env.GHOST_ADMIN_API_KEY;
+    if (!url || !key) {
+        console.error("Set GHOST_URL (the site's address) and GHOST_ADMIN_API_KEY (Ghost Admin, Integrations, a custom integration's Admin API key).");
+        return 2;
+    }
+    const { Ghost, pull, push } = await import("./ghost.js");
+    const client = new Ghost({ url, key });
+    if (action === "draft" || action === "hook") {
+        const { claudeDrafter, draftAll, hookServer, registerWebhooks } = await import("./hook.js");
+        const model = process.env.OBS_MODEL;
+        const drafter = claudeDrafter(model ? { model } : {});
+        if (action === "draft") {
+            const opts = { dryRun: args.dryRun, onLine: printLine };
+            if (args.slug !== undefined)
+                opts.slug = args.slug;
+            if (args.limit !== undefined)
+                opts.limit = args.limit;
+            return tally(await draftAll(client, drafter, opts));
+        }
+        const secret = process.env.GHOST_WEBHOOK_SECRET;
+        if (!secret) {
+            console.error("Set GHOST_WEBHOOK_SECRET: any long random text. Ghost signs each webhook with it.");
+            return 2;
+        }
+        const target = process.env.OBS_HOOK_URL;
+        if (target)
+            for (const line of await registerWebhooks(client, `${target.replace(/\/+$/u, "")}/ghost`, secret))
+                console.log(line);
+        const port = args.port ?? (Number(process.env.PORT) || 8080);
+        await new Promise((done) => hookServer({ ghost: client, secret, drafter }).listen(port, done));
+        console.log(`openbriefing ghost hook is listening on ${port}`);
+        return new Promise(() => { });
+    }
+    const opts = { dryRun: args.dryRun };
+    if (args.slug !== undefined)
+        opts.slug = args.slug;
+    const lines = action === "pull" ? await pull(client, folder, args.slug) : await push(client, folder, opts);
+    for (const l of lines)
+        printLine(l);
+    return tally(lines);
+}
 async function main(argv) {
     const args = parseArgs(argv);
     if (args.command === "check")
         return check(args);
+    if (args.command === "tags")
+        return tags(args);
+    if (args.command === "ghost")
+        return ghost(args);
     if (args.command === "version") {
         console.log(VERSION);
         return 0;

package/dist/ghost.d.ts

@@ -0,0 +1,67 @@
+import { type ObsBrief } from "./obs.js";
+export interface GhostPost {
+    id: string;
+    slug: string;
+    title: string;
+    url: string;
+    updated_at: string;
+    codeinjection_head: string | null;
+    plaintext?: string | null;
+    /** "public", or who may read it. */
+    visibility?: string;
+}
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+export interface GhostConfig {
+    /** The site's address, such as https://example.com. */
+    url: string;
+    /** An Admin API key, "id:secret". */
+    key: string;
+    fetch?: FetchLike;
+    now?: () => number;
+}
+/** A short-lived token for Ghost's Admin API, signed with the key's secret. */
+export declare function ghostToken(key: string, nowMs?: number): string;
+export declare class Ghost {
+    private readonly config;
+    private readonly base;
+    private readonly fetcher;
+    constructor(config: GhostConfig);
+    private call;
+    /** Every published post, with its plain text. */
+    posts(slug?: string): Promise<GhostPost[]>;
+    /** Adds a webhook to the integration this key belongs to. */
+    addWebhook(event: string, target: string, secret: string): Promise<void>;
+    /** Writes a post's Code injection header and nothing else. `updated_at` is Ghost's guard against overwriting a newer edit. */
+    setHead(post: GhostPost, head: string): Promise<void>;
+}
+/** The brief a post's Code injection header carries now, when it has usable tags. */
+export declare function briefInHead(head: string, url: string): ObsBrief | undefined;
+/**
+ * The header with the new block in place. Tags written by hand outside the
+ * markers are taken out first, so the page never carries two sets. Returns
+ * undefined when hand-written tags remain that this cannot safely move.
+ */
+export declare function headWith(head: string, block: string): string | undefined;
+/** Ghost's slug shape. Anything else is never used as a file name or in a query. */
+export declare const SLUG: RegExp;
+export interface Line {
+    slug: string;
+    state: "written" | "would write" | "unchanged" | "draft" | "skipped" | "pulled" | "kept" | "error";
+    note?: string;
+}
+/** Writes one file per published post into `folder`. A file that already exists is never touched. */
+export declare function pull(ghost: Ghost, folder: string, slug?: string): Promise<Line[]>;
+/** Writes each approved file's tags into its post. A draft is never written. */
+export declare function push(ghost: Ghost, folder: string, options?: {
+    slug?: string;
+    dryRun?: boolean;
+}): Promise<Line[]>;

package/dist/ghost.js

@@ -0,0 +1,186 @@
+/**
+ * `openbriefing ghost pull` and `ghost push`: briefing files to and from a
+ * Ghost site, through its Admin API. Push writes one thing, the block between
+ * the obs:start and obs:end comments in a post's Code injection header.
+ *
+ * The key comes from the environment and is never printed.
+ */
+import { createHmac } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { JSDOM } from "jsdom";
+import { briefingFields, markTags, parseBriefing, postFile, readMarked, renderTags, replaceMarked } from "./briefing.js";
+import { fingerprint, parseObs } from "./obs.js";
+const b64url = (input) => Buffer.from(input).toString("base64url");
+/** A short-lived token for Ghost's Admin API, signed with the key's secret. */
+export function ghostToken(key, nowMs = Date.now()) {
+    const [id, secret] = key.split(":");
+    if (!id || !secret || !/^[0-9a-f]+$/iu.test(secret))
+        throw new Error("GHOST_ADMIN_API_KEY should look like id:secret, as Ghost shows it");
+    const iat = Math.floor(nowMs / 1000);
+    const head = b64url(JSON.stringify({ alg: "HS256", typ: "JWT", kid: id }));
+    const body = b64url(JSON.stringify({ iat, exp: iat + 300, aud: "/admin/" }));
+    const sig = createHmac("sha256", Buffer.from(secret, "hex")).update(`${head}.${body}`).digest("base64url");
+    return `${head}.${body}.${sig}`;
+}
+export class Ghost {
+    config;
+    base;
+    fetcher;
+    constructor(config) {
+        this.config = config;
+        this.base = `${config.url.replace(/\/+$/u, "")}/ghost/api/admin`;
+        this.fetcher = config.fetch ?? ((url, init) => fetch(url, init));
+    }
+    async call(method, path, body) {
+        const headers = {
+            authorization: `Ghost ${ghostToken(this.config.key, this.config.now?.() ?? Date.now())}`,
+            "accept-version": "v5.0",
+            accept: "application/json",
+        };
+        const init = { method, headers };
+        if (body !== undefined) {
+            headers["content-type"] = "application/json";
+            init.body = JSON.stringify(body);
+        }
+        const res = await this.fetcher(`${this.base}${path}`, init);
+        if (!res.ok) {
+            let detail = "";
+            try {
+                const err = (await res.json());
+                detail = err.errors?.[0]?.message ?? "";
+            }
+            catch {
+                /* the status says enough */
+            }
+            throw new Error(`Ghost answered ${res.status}${detail ? `: ${detail}` : ""}`);
+        }
+        return res.json();
+    }
+    /** Every published post, with its plain text. */
+    async posts(slug) {
+        const out = [];
+        const filter = slug ? `status:published+slug:${slug}` : "status:published";
+        for (let page = 1; page <= 200; page++) {
+            const res = (await this.call("GET", `/posts/?filter=${encodeURIComponent(filter)}&formats=plaintext&limit=50&page=${page}&order=${encodeURIComponent("published_at desc")}`));
+            out.push(...(res.posts ?? []));
+            if (page >= (res.meta?.pagination?.pages ?? 1))
+                break;
+        }
+        return out;
+    }
+    /** Adds a webhook to the integration this key belongs to. */
+    async addWebhook(event, target, secret) {
+        await this.call("POST", "/webhooks/", { webhooks: [{ event, target_url: target, secret, name: `Open Briefing: ${event}` }] });
+    }
+    /** Writes a post's Code injection header and nothing else. `updated_at` is Ghost's guard against overwriting a newer edit. */
+    async setHead(post, head) {
+        await this.call("PUT", `/posts/${post.id}/`, { posts: [{ codeinjection_head: head, updated_at: post.updated_at }] });
+    }
+}
+const META_OBS = /[ \t]*<meta\s+(?:property|name)\s*=\s*"obs:[^"]*"\s+content\s*=\s*"[^"]*"\s*\/?>[ \t]*\r?\n?/giu;
+/** The brief a post's Code injection header carries now, when it has usable tags. */
+export function briefInHead(head, url) {
+    if (!/obs:/u.test(head))
+        return undefined;
+    return parseObs(new JSDOM(`<!doctype html><html><head>${head}</head><body></body></html>`, { url }).window.document, url).brief;
+}
+/**
+ * The header with the new block in place. Tags written by hand outside the
+ * markers are taken out first, so the page never carries two sets. Returns
+ * undefined when hand-written tags remain that this cannot safely move.
+ */
+export function headWith(head, block) {
+    const marked = readMarked(head);
+    if (marked !== undefined) {
+        const outside = head.replace(marked, "");
+        if (/obs:(?!start|end)/u.test(outside.replace(META_OBS, "")))
+            return undefined;
+        return replaceMarked(head.replace(marked, "\u0000").replace(META_OBS, "").replace("\u0000", () => marked), block);
+    }
+    const cleaned = head.replace(META_OBS, "");
+    if (/obs:/u.test(cleaned))
+        return undefined;
+    return replaceMarked(cleaned, block);
+}
+/** Ghost's slug shape. Anything else is never used as a file name or in a query. */
+export const SLUG = /^[a-z0-9][a-z0-9_-]*$/iu;
+const briefingFiles = (folder) => readdirSync(folder)
+    .filter((f) => /\.(md|markdown|ya?ml)$/iu.test(f))
+    .sort();
+/** Writes one file per published post into `folder`. A file that already exists is never touched. */
+export async function pull(ghost, folder, slug) {
+    mkdirSync(folder, { recursive: true });
+    const lines = [];
+    if (slug !== undefined && !SLUG.test(slug))
+        return [{ slug, state: "error", note: "not a post slug" }];
+    for (const post of await ghost.posts(slug)) {
+        if (typeof post.slug !== "string" || !SLUG.test(post.slug)) {
+            lines.push({ slug: String(post.slug), state: "error", note: "the post's slug is not a plain slug, so no file is written" });
+            continue;
+        }
+        const path = join(folder, `${post.slug}.md`);
+        if (existsSync(path)) {
+            lines.push({ slug: post.slug, state: "kept", note: "the file is already here" });
+            continue;
+        }
+        // Tags already live on the post were approved by whoever put them there.
+        const live = briefInHead(post.codeinjection_head ?? "", post.url);
+        const obs = live ? briefingFields({ ...live, url: live.url ?? post.url }, "approved") : { url: post.url, status: "draft" };
+        writeFileSync(path, postFile({ slug: post.slug, title: post.title, obs }, post.plaintext ?? ""));
+        lines.push({ slug: post.slug, state: "pulled", note: live ? "with the tags the post already carries, as approved" : "a draft to fill in" });
+    }
+    return lines;
+}
+/** Writes each approved file's tags into its post. A draft is never written. */
+export async function push(ghost, folder, options = {}) {
+    const lines = [];
+    const files = briefingFiles(folder).filter((f) => options.slug === undefined || f.replace(/\.[^.]+$/u, "") === options.slug);
+    if (files.length === 0)
+        return lines;
+    const only = files.length === 1 ? files[0].replace(/\.[^.]+$/u, "") : undefined;
+    const posts = new Map((await ghost.posts(only !== undefined && SLUG.test(only) ? only : undefined)).map((p) => [p.slug, p]));
+    for (const file of files) {
+        const briefing = parseBriefing(readFileSync(join(folder, file), "utf8"));
+        const slug = briefing.slug ?? file.replace(/\.[^.]+$/u, "");
+        if (briefing.status !== "approved") {
+            lines.push({ slug, state: "draft", note: "not approved, so not written" });
+            continue;
+        }
+        if (!briefing.brief) {
+            lines.push({ slug, state: "error", note: briefing.errors.join("; ") });
+            continue;
+        }
+        const post = posts.get(slug);
+        if (!post) {
+            lines.push({ slug, state: "error", note: "no published post has this slug" });
+            continue;
+        }
+        const head = post.codeinjection_head ?? "";
+        const marked = readMarked(head);
+        const live = marked === undefined ? undefined : briefInHead(marked, post.url);
+        const next = headWith(head, markTags(renderTags(briefing.brief)));
+        if (next === undefined) {
+            lines.push({ slug, state: "skipped", note: "the post has obs: code outside the markers that is not a plain meta tag; move it by hand" });
+            continue;
+        }
+        const outside = marked === undefined ? head : head.replace(marked, "");
+        const stray = outside.replace(META_OBS, "") !== outside;
+        if (live && !stray && fingerprint(live) === fingerprint(briefing.brief)) {
+            lines.push({ slug, state: "unchanged" });
+            continue;
+        }
+        if (options.dryRun) {
+            lines.push({ slug, state: "would write" });
+            continue;
+        }
+        try {
+            await ghost.setHead(post, next);
+            lines.push({ slug, state: "written" });
+        }
+        catch (err) {
+            lines.push({ slug, state: "error", note: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return lines;
+}

package/dist/hook.d.ts

@@ -0,0 +1,61 @@
+import { type Server } from "node:http";
+import { type Ghost, type GhostPost, type Line } from "./ghost.js";
+import { type ObsBrief } from "./obs.js";
+/** Writes a briefing file (YAML) for a post. */
+export type Drafter = (post: {
+    title: string;
+    url: string;
+    text: string;
+}) => Promise<string>;
+/** A post shorter than this has nothing for a 200-word summary to shorten. */
+export declare const MIN_WORDS = 200;
+/** The drafting prompt, the kit's `prompt.md`. */
+export declare function draftingPrompt(): string;
+/** A drafter that asks Claude. The key comes from ANTHROPIC_API_KEY. */
+export declare function claudeDrafter(options?: {
+    model?: string;
+}): Drafter;
+/** The marked block for a brief the hook wrote, with its stamp. */
+export declare function autoBlock(brief: ObsBrief, url: string): string;
+export type Decision = {
+    act: "draft" | "redraft";
+} | {
+    act: "leave";
+    why: string;
+};
+/** What the hook does for a post, from the post alone. */
+export declare function decide(post: GhostPost): Decision;
+/** A drafted brief for a post, with any highlight the post does not contain taken out. */
+export declare function draftBrief(post: GhostPost, drafter: Drafter): Promise<ObsBrief>;
+/** Drafts and writes one post's tags, when the post is the hook's to write. */
+export declare function autoTag(ghost: Ghost, slug: string, drafter: Drafter, options?: {
+    dryRun?: boolean;
+}): Promise<Line>;
+/** Drafts tags for every published post that has none. One post at a time. */
+export declare function draftAll(ghost: Ghost, drafter: Drafter, options?: {
+    slug?: string;
+    limit?: number;
+    dryRun?: boolean;
+    onLine?: (line: Line) => void;
+}): Promise<Line[]>;
+/** Ghost signs a webhook as `sha256=<hex HMAC of body + t>, t=<ms>`. */
+export declare function verifySignature(body: string, header: string | undefined, secret: string, now?: number): boolean;
+/** The slug a webhook is about. The payload is untrusted; the post itself is read from Ghost. */
+export declare function slugOf(body: string): string | undefined;
+export declare const HOOK_EVENTS: readonly ["post.published", "post.published.edited"];
+/** Registers the hook's webhooks on the integration the Admin API key belongs to. Safe to repeat. */
+export declare function registerWebhooks(ghost: Ghost, target: string, secret: string): Promise<string[]>;
+export interface HookOptions {
+    ghost: Ghost;
+    secret: string;
+    drafter: Drafter;
+    log?: (message: string) => void;
+    now?: () => number;
+}
+/**
+ * An HTTP server for Ghost's webhooks: POST /ghost and GET /healthz. Ghost
+ * gives up after two seconds, so the hook answers 202 and then does the work.
+ */
+export declare function hookServer(options: HookOptions): Server & {
+    idle(): Promise<void>;
+};

package/dist/hook.js

@@ -0,0 +1,272 @@
+/**
+ * `openbriefing ghost hook` and `ghost draft`: tags written for a post when it
+ * is published, with no step for the author.
+ *
+ * The hook drafts the summary with a model, checks every highlight against the
+ * post's text, and writes the marked block into the post's Code injection
+ * header. The block carries a stamp, `<!-- obs:auto <fingerprint> -->`. While
+ * the tags still match the stamp the block is the hook's; once the author
+ * edits them it is theirs, and the hook never writes to that post again.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { checkHighlights, MARK_END, MARK_START, parseBriefing, readMarked, renderTags } from "./briefing.js";
+import { briefInHead, headWith, SLUG } from "./ghost.js";
+import { countWords, fingerprint } from "./obs.js";
+/** A post shorter than this has nothing for a 200-word summary to shorten. */
+export const MIN_WORDS = 200;
+const STAMP = /<!--\s*obs:auto\s+([0-9a-f]{16})\s*-->/u;
+const MAX_AGE_MS = 5 * 60 * 1000;
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+/** The drafting prompt, the kit's `prompt.md`. */
+export function draftingPrompt() {
+    // Packed beside dist/ when published; at the repository's root when run from source.
+    for (const rel of ["../kit/prompt.md", "../../../kit/prompt.md"]) {
+        const path = new URL(rel, import.meta.url);
+        if (existsSync(path))
+            return readFileSync(path, "utf8");
+    }
+    throw new Error("The drafting prompt (kit/prompt.md) is missing from this install");
+}
+/** A drafter that asks Claude. The key comes from ANTHROPIC_API_KEY. */
+export function claudeDrafter(options = {}) {
+    const system = draftingPrompt();
+    return async (post) => {
+        const { default: Anthropic } = await import("@anthropic-ai/sdk");
+        // A key that is not tied to one workspace needs the workspace named.
+        const workspace = process.env.ANTHROPIC_WORKSPACE_ID;
+        const client = new Anthropic(workspace ? { defaultHeaders: { "anthropic-workspace-id": workspace } } : {});
+        const response = await client.beta.messages.create({
+            model: options.model ?? "claude-opus-5-5",
+            max_tokens: 16000,
+            thinking: { type: "adaptive" },
+            betas: ["server-side-fallback-2026-07-01"],
+            fallbacks: "default",
+            system,
+            messages: [{ role: "user", content: `Address: ${post.url}\nTitle: ${post.title}\n\n${post.text}` }],
+        });
+        if (response.stop_reason === "refusal")
+            throw new Error("the model declined to draft this post");
+        if (response.stop_reason === "max_tokens")
+            throw new Error("the draft was cut off");
+        return response.content.flatMap((block) => (block.type === "text" ? [block.text] : [])).join("");
+    };
+}
+/** The marked block for a brief the hook wrote, with its stamp. */
+export function autoBlock(brief, url) {
+    const tags = renderTags(brief);
+    // The stamp is taken from the tags as a reader parses them, so it holds for exactly what is on the page.
+    const read = briefInHead(tags, url);
+    return [MARK_START, `<!-- obs:auto ${fingerprint(read ?? brief)} -->`, tags, MARK_END].join("\n");
+}
+/** What the hook does for a post, from the post alone. */
+export function decide(post) {
+    if (post.visibility !== undefined && post.visibility !== "public")
+        return { act: "leave", why: "the post is not public" };
+    const text = post.plaintext ?? "";
+    if (countWords(text) < MIN_WORDS)
+        return { act: "leave", why: `the post is under ${MIN_WORDS} words` };
+    const head = post.codeinjection_head ?? "";
+    if (!/obs:/u.test(head))
+        return { act: "draft" };
+    const marked = readMarked(head);
+    const stamp = marked === undefined ? undefined : STAMP.exec(marked)?.[1];
+    const live = marked === undefined ? undefined : briefInHead(marked, post.url);
+    if (stamp === undefined || !live || fingerprint(live) !== stamp || head.replace(marked, "").includes("obs:"))
+        return { act: "leave", why: "the author's own tags" };
+    // Still the hook's block. It is redone only when the post changed under a quote.
+    checkHighlights(live, text, []);
+    if (live.highlights.some((h) => h.inContent === false))
+        return { act: "redraft" };
+    return { act: "leave", why: "the tags are current" };
+}
+const unfence = (text) => text
+    .trim()
+    .replace(/^```[a-z]*\r?\n/iu, "")
+    .replace(/\r?\n```$/u, "");
+/** A drafted brief for a post, with any highlight the post does not contain taken out. */
+export async function draftBrief(post, drafter) {
+    const text = post.plaintext ?? "";
+    let problem = "";
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const briefing = parseBriefing(unfence(await drafter({ title: post.title, url: post.url, text })));
+        if (!briefing.brief) {
+            problem = briefing.errors.join("; ") || "no summary";
+            continue;
+        }
+        const brief = briefing.brief;
+        checkHighlights(brief, text, []);
+        brief.highlights = brief.highlights.filter((h) => h.inContent !== false);
+        // The address is the post's, whatever the draft said.
+        const withUrl = parseBriefing(JSON.stringify({ ...draftFields(brief), url: post.url })).brief;
+        return withUrl ?? brief;
+    }
+    throw new Error(`the draft was not usable: ${problem}`);
+}
+function draftFields(brief) {
+    const out = {};
+    if (brief.title)
+        out.title = brief.title;
+    if (brief.headline)
+        out.headline = brief.headline;
+    for (const s of brief.summaries)
+        out[s.from === "inferred" ? "summary" : `summary_${s.tier}`] = s.text;
+    if (brief.keep.length > 0)
+        out.keep = brief.keep;
+    if (brief.highlights.length > 0)
+        out.highlights = brief.highlights.map((h) => (h.label ? { text: h.text, label: h.label } : { text: h.text }));
+    return out;
+}
+/** Drafts and writes one post's tags, when the post is the hook's to write. */
+export async function autoTag(ghost, slug, drafter, options = {}) {
+    if (!SLUG.test(slug))
+        return { slug, state: "error", note: "not a post slug" };
+    try {
+        let post = (await ghost.posts(slug))[0];
+        if (!post)
+            return { slug, state: "skipped", note: "no published post has this slug" };
+        const decision = decide(post);
+        if (decision.act === "leave")
+            return { slug, state: "kept", note: decision.why };
+        if (options.dryRun)
+            return { slug, state: "would write" };
+        const brief = await draftBrief(post, drafter);
+        for (let attempt = 0;; attempt++) {
+            const next = headWith(post.codeinjection_head ?? "", autoBlock(brief, post.url));
+            if (next === undefined)
+                return { slug, state: "kept", note: "the author's own tags" };
+            try {
+                await ghost.setHead(post, next);
+                return { slug, state: "written", note: decision.act === "redraft" ? "redone, the post changed under a quote" : "drafted" };
+            }
+            catch (err) {
+                // The post was saved while the draft was being written: read it again, once.
+                if (attempt > 0 || !(err instanceof Error) || !err.message.includes("409"))
+                    throw err;
+                const fresh = (await ghost.posts(slug))[0];
+                if (!fresh || decide(fresh).act === "leave")
+                    return { slug, state: "kept", note: "the post changed while the draft was written" };
+                post = fresh;
+            }
+        }
+    }
+    catch (err) {
+        return { slug, state: "error", note: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Drafts tags for every published post that has none. One post at a time. */
+export async function draftAll(ghost, drafter, options = {}) {
+    const lines = [];
+    let written = 0;
+    for (const post of await ghost.posts(options.slug)) {
+        if (options.limit !== undefined && written >= options.limit)
+            break;
+        const opts = options.dryRun === undefined ? {} : { dryRun: options.dryRun };
+        const line = await autoTag(ghost, post.slug, drafter, opts);
+        if (line.state === "written" || line.state === "would write")
+            written++;
+        lines.push(line);
+        options.onLine?.(line);
+    }
+    return lines;
+}
+/** Ghost signs a webhook as `sha256=<hex HMAC of body + t>, t=<ms>`. */
+export function verifySignature(body, header, secret, now = Date.now()) {
+    const match = /^sha256=([0-9a-f]{64}), t=(\d+)$/u.exec(header ?? "");
+    if (!match || secret === "")
+        return false;
+    const [, sig, ts] = match;
+    if (Math.abs(now - Number(ts)) > MAX_AGE_MS)
+        return false;
+    const expected = createHmac("sha256", secret).update(`${body}${ts}`).digest();
+    return timingSafeEqual(Buffer.from(sig, "hex"), expected);
+}
+/** The slug a webhook is about. The payload is untrusted; the post itself is read from Ghost. */
+export function slugOf(body) {
+    try {
+        const slug = JSON.parse(body).post?.current?.slug;
+        return typeof slug === "string" && SLUG.test(slug) ? slug : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export const HOOK_EVENTS = ["post.published", "post.published.edited"];
+/** Registers the hook's webhooks on the integration the Admin API key belongs to. Safe to repeat. */
+export async function registerWebhooks(ghost, target, secret) {
+    const out = [];
+    for (const event of HOOK_EVENTS) {
+        try {
+            await ghost.addWebhook(event, target, secret);
+            out.push(`${event}: registered`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // Ghost answers 422 when this address already has the event.
+            out.push(message.includes("422") ? `${event}: already registered` : `${event}: ${message}`);
+        }
+    }
+    return out;
+}
+/**
+ * An HTTP server for Ghost's webhooks: POST /ghost and GET /healthz. Ghost
+ * gives up after two seconds, so the hook answers 202 and then does the work.
+ */
+export function hookServer(options) {
+    const log = options.log ?? ((m) => console.log(m));
+    // One post at a time per slug: a publish and the edit that follows it never race.
+    const busy = new Map();
+    const run = (slug) => {
+        const next = (busy.get(slug) ?? Promise.resolve())
+            .then(() => autoTag(options.ghost, slug, options.drafter))
+            .then((line) => log(`${line.state} ${slug}${line.note ? ` (${line.note})` : ""}`))
+            .catch((err) => log(`error ${slug} (${err instanceof Error ? err.message : String(err)})`))
+            .finally(() => {
+            if (busy.get(slug) === next)
+                busy.delete(slug);
+        });
+        busy.set(slug, next);
+    };
+    const server = createServer((req, res) => {
+        if (req.method === "GET" && req.url === "/healthz") {
+            res.writeHead(200, { "content-type": "text/plain" }).end("ok");
+            return;
+        }
+        if (req.method !== "POST" || req.url !== "/ghost") {
+            res.writeHead(404).end();
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > MAX_BODY_BYTES) {
+                res.writeHead(413).end();
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", () => {
+            if (size > MAX_BODY_BYTES)
+                return;
+            const body = Buffer.concat(chunks).toString("utf8");
+            const header = req.headers["x-ghost-signature"];
+            if (!verifySignature(body, typeof header === "string" ? header : undefined, options.secret, options.now?.() ?? Date.now())) {
+                res.writeHead(401).end();
+                return;
+            }
+            const slug = slugOf(body);
+            if (slug === undefined) {
+                res.writeHead(400).end();
+                return;
+            }
+            res.writeHead(202).end();
+            run(slug);
+        });
+    });
+    server.headersTimeout = 10_000;
+    server.requestTimeout = 15_000;
+    return Object.assign(server, { idle: async () => void (await Promise.all([...busy.values()])) });
+}

package/kit/prompt.md

@@ -0,0 +1,40 @@
+You are drafting an author's own summary of their post, in the Open Briefing Standard's briefing-file format. Tools that brief or read posts aloud will use these words in place of a summary they would otherwise write themselves, and they will credit the author. So the draft must sound like the author and say only what the post says.
+
+Return one YAML briefing file and nothing else: no preface, no code fence, no notes after it.
+
+```yaml
+url: <the post's address, if you were given it; leave the key out if not>
+headline: <one or two sentences, 40 words or fewer>
+summary: |
+  <200 to 350 words, in two to four paragraphs, with a blank line between paragraphs>
+keep:
+  - <the one sentence every shorter version must get across>
+highlights:
+  - text: <a passage copied from the post, word for word>
+    label: <what it is about, 6 words or fewer>
+status: draft
+```
+
+How to write each part:
+
+**summary.** 200 to 350 words. Use the author's own sentences where they serve, and their voice everywhere: first person if the post is first person, their vocabulary, their level of formality. Say what the post argues or reports and the reasons or evidence it gives, in the order a listener needs. The first two sentences must stand on their own, because a tool that needs something shorter will often use just those. The summary must make sense to someone who has not seen the title.
+
+**headline.** A line someone might hear before deciding whether to listen further. It carries the post's main point, not a teaser for it.
+
+**keep.** Up to three lines, most important first. The first is the post's core message in one sentence. Add a second or third only for something a shorter version must not lose, such as a number, a caveat or a name. Each line should also appear in the summary, in the same words.
+
+**highlights.** Up to four passages the author might be glad to see quoted on their own. Copy each one from the post exactly, word for word and with its punctuation, 60 words or fewer. Do not join passages from different places, trim words from the middle, or fix the author's wording. If a passage ends in the post with a comma before a closing quotation mark, end your copy before the comma. If nothing in the post reads well alone, leave `highlights` out.
+
+**title.** Leave it out, unless the post's own title is longer than 12 words. Then add `title:` with a shorter one.
+
+Rules for every line:
+
+- Plain text that works both read and heard. No Markdown, no HTML, no emoji, no bullet lists inside a value.
+- No web addresses in any line you write (the `url:` key is the one exception), and no "click here", "see below", "in this post" or "pictured above". No reference to images, tables or layout.
+- Spell out an abbreviation the first time, unless it is normally said as a word.
+- In the lines you write yourself, prefer a single quotation mark to a double one wherever either reads as well. The words end up inside an HTML attribute, where a double quotation mark has to be escaped. A highlight keeps the post's own marks.
+- Say nothing the post does not support. Do not add background, opinion, praise or a conclusion the author did not draw. If the post is unclear on a point, leave the point out.
+- Write in the post's language.
+- Always end the file with `status: draft`. Only the author approves it.
+
+The post follows.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openbriefing",
-  "version": "0.3.0",
-  "description": "Open Briefing Standard (OBS): the reference parser and checker for publishers' own summaries.",
+  "version": "0.5.0",
+  "description": "Open Briefing Standard (OBS): the reference parser, the checker and the publisher's tag tools for publishers' own summaries.",
   "keywords": [
     "open-briefing-standard",
     "obs",
@@ -26,6 +26,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./briefing": {
+      "types": "./dist/briefing.d.ts",
+      "import": "./dist/briefing.js"
+    },
     "./fetch": {
       "types": "./dist/fetch.d.ts",
       "import": "./dist/fetch.js"
@@ -38,6 +42,7 @@
   "files": [
     "dist",
     "fixtures",
+    "kit",
     "README.md"
   ],
   "engines": {
@@ -49,10 +54,12 @@
     "test": "vitest run",
     "fixtures": "node ../../scripts/make-fixtures.mjs",
     "expected": "tsx scripts/write-expected.ts",
-    "prepack": "rm -rf fixtures && cp -R ../../spec/fixtures fixtures && npm run build"
+    "prepack": "rm -rf fixtures kit && cp -R ../../spec/fixtures fixtures && mkdir kit && cp ../../kit/prompt.md kit/prompt.md && npm run build"
   },
   "dependencies": {
-    "jsdom": "^26.1.0"
+    "@anthropic-ai/sdk": "^1.8.0",
+    "jsdom": "^26.1.0",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@types/jsdom": "^21.1.7",