@softure-ai/blog 0.0.0-stage → 0.1.6

package/dist/ui/blog-listing.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The listing: articles as cards in groups by cluster, the pillar of a cluster as a lead card before
+// the grid. A whole card is one link (its title's anchor stretches over the card in CSS), so a screen
+// reader hears one link named after the text and a finger can hit anywhere.
+import { formatMessage } from "@softure-ai/core";
+import { formatDay, getArticleDates } from "../pages/dates.js";
+import { getClusterAnchor } from "../pages/listing.js";
+import { getArticlePath } from "../pages/paths.js";
+import { getReadingMinutes } from "../render/reading-time.js";
+import { BlogFooterNote, BlogLayout } from "./blog-layout.js";
+function CardMeta({ article, context, timezone }) {
+    const copy = context.messages.pages;
+    const dates = getArticleDates(article, timezone);
+    const shownDay = dates.updated ?? dates.published;
+    const date = formatDay(shownDay, context.locale);
+    return (_jsxs("p", { className: "blog-card-meta", children: [_jsx("time", { dateTime: shownDay, children: dates.updated === null ? date : formatMessage(copy.updatedOn, { date }) }), _jsx("span", { "aria-hidden": "true", children: " · " }), _jsx("span", { children: formatMessage(copy.readingTime, { minutes: getReadingMinutes(article.bodyMarkdown) }) })] }));
+}
+function ArticleCard({ article, context, timezone, isLead }) {
+    return (_jsxs("article", { className: isLead ? "blog-card blog-card-lead" : "blog-card", "data-slug": article.slug, children: [isLead ? _jsx("p", { className: "blog-badge", children: context.messages.pages.startHere }) : null, _jsx("h3", { className: "blog-card-title", children: _jsx("a", { className: "blog-card-link", href: getArticlePath(context.routes, article.slug), children: article.title }) }), _jsx("p", { className: "blog-card-description", children: article.description }), _jsx(CardMeta, { article: article, context: context, timezone: timezone })] }));
+}
+export function BlogListingView({ context, groups, termCount, timezone, cta }) {
+    const copy = context.messages.pages;
+    return (_jsxs(BlogLayout, { context: context, title: copy.blogTitle, lead: copy.blogDescription, children: [groups.length === 0 ? (_jsx("p", { className: "blog-empty", children: copy.empty })) : (_jsx("div", { className: "blog-groups", children: groups.map((group) => {
+                    const id = group.cluster === null ? undefined : getClusterAnchor(group.cluster);
+                    const headingId = `${id ?? "cluster-other"}-heading`;
+                    return (_jsxs("section", { id: id, "aria-labelledby": headingId, className: "blog-group", children: [_jsx("h2", { id: headingId, className: "blog-group-title", children: group.label }), group.lead === null ? null : _jsx(ArticleCard, { article: group.lead, context: context, timezone: timezone, isLead: true }), group.rest.length === 0 ? null : (_jsx("ul", { className: "blog-cards", children: group.rest.map((article) => (_jsx("li", { children: _jsx(ArticleCard, { article: article, context: context, timezone: timezone, isLead: false }) }, article.id))) }))] }, group.cluster ?? ""));
+                }) })), cta === undefined ? null : _jsx("div", { className: "blog-slot", children: cta }), termCount > 0 ? (_jsxs("p", { className: "blog-glossary-teaser", children: [_jsx("a", { href: context.routes.glossary, children: copy.glossaryLink }), ": ", copy.glossaryTeaser] })) : null, _jsx(BlogFooterNote, { context: context })] }));
+}
+//# sourceMappingURL=blog-listing.js.map

package/dist/ui/blog-listing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blog-listing.js","sourceRoot":"","sources":["../../src/ui/blog-listing.tsx"],"names":[],"mappings":"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"}

package/dist/ui/blog-method.d.ts

@@ -0,0 +1,5 @@
+import type { BlogPageContext } from "./page-context.js";
+export declare function BlogMethodView({ context }: {
+    readonly context: BlogPageContext;
+}): import("react").JSX.Element;
+//# sourceMappingURL=blog-method.d.ts.map

package/dist/ui/blog-method.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blog-method.d.ts","sourceRoot":"","sources":["../../src/ui/blog-method.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAUzD,wBAAgB,cAAc,CAAC,EAAE,OAAO,EAAE,EAAE;IAAE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAE,+BAmBhF"}

package/dist/ui/blog-method.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// "How our texts are made": who writes, where facts come from, sources, checks and corrections. The
+// copy is the module's default in `messages.method`; an app states its own method through
+// `blog({ messages: { en: { method: { … } } } })`.
+import { BlogFooterNote, BlogLayout } from "./blog-layout.js";
+const SECTIONS = [
+    ["who", "whoTitle", "whoBody"],
+    ["facts", "factsTitle", "factsBody"],
+    ["sources", "sourcesTitle", "sourcesBody"],
+    ["checks", "checksTitle", "checksBody"],
+    ["corrections", "correctionsTitle", "correctionsBody"],
+];
+export function BlogMethodView({ context }) {
+    const copy = context.messages.method;
+    const crumbs = [
+        { name: context.messages.pages.blogTitle, path: context.routes.index },
+        { name: copy.title, path: context.methodPath ?? context.routes.index },
+    ];
+    return (_jsx(BlogLayout, { context: context, title: copy.title, lead: copy.description, crumbs: crumbs, children: _jsxs("div", { className: "blog-article", children: [SECTIONS.map(([id, title, body]) => (_jsxs("section", { id: id, "aria-labelledby": `${id}-heading`, className: "blog-section", children: [_jsx("h2", { id: `${id}-heading`, children: copy[title] }), _jsx("p", { children: copy[body] })] }, id))), _jsx(BlogFooterNote, { context: { ...context, methodPath: null } })] }) }));
+}
+//# sourceMappingURL=blog-method.js.map

package/dist/ui/blog-method.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blog-method.js","sourceRoot":"","sources":["../../src/ui/blog-method.tsx"],"names":[],"mappings":";AAAA,oGAAoG;AACpG,0FAA0F;AAC1F,mDAAmD;AACnD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9D,MAAM,QAAQ,GAAG;IACf,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,CAAC;IAC9B,CAAC,OAAO,EAAE,YAAY,EAAE,WAAW,CAAC;IACpC,CAAC,SAAS,EAAE,cAAc,EAAE,aAAa,CAAC;IAC1C,CAAC,QAAQ,EAAE,aAAa,EAAE,YAAY,CAAC;IACvC,CAAC,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;CAC9C,CAAC;AAEX,MAAM,UAAU,cAAc,CAAC,EAAE,OAAO,EAAyC;IAC/E,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACrC,MAAM,MAAM,GAAG;QACb,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE;QACtE,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE;KACvE,CAAC;IACF,OAAO,CACL,KAAC,UAAU,IAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,YACrF,eAAK,SAAS,EAAC,cAAc,aAC1B,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CACnC,mBAAkB,EAAE,EAAE,EAAE,qBAAmB,GAAG,EAAE,UAAU,EAAE,SAAS,EAAC,cAAc,aAClF,aAAI,EAAE,EAAE,GAAG,EAAE,UAAU,YAAG,IAAI,CAAC,KAAK,CAAC,GAAM,EAC3C,sBAAI,IAAI,CAAC,IAAI,CAAC,GAAK,KAFP,EAAE,CAGN,CACX,CAAC,EACF,KAAC,cAAc,IAAC,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,GAAI,IACzD,GACK,CACd,CAAC;AACJ,CAAC"}

package/dist/ui/index.d.ts

@@ -0,0 +1,7 @@
+export { ArticleBody, ArticleDatesList, BlogArticleView, SourceList, type BlogArticleViewProps, type RenderedBody } from "./blog-article.js";
+export { GlossaryIndexView, GlossaryTermView, type GlossaryIndexViewProps, type GlossaryTermViewProps } from "./blog-glossary.js";
+export { BlogFooterNote, BlogLayout, Breadcrumbs, JsonLdScript, type BlogLayoutProps } from "./blog-layout.js";
+export { BlogListingView, type BlogListingViewProps } from "./blog-listing.js";
+export { BlogMethodView } from "./blog-method.js";
+export type { BlogPageContext } from "./page-context.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/ui/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,KAAK,oBAAoB,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC7I,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAClI,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC/G,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/ui/index.js

@@ -0,0 +1,8 @@
+// Server components of the blog's pages. They take ready data and copy and import nothing from Next,
+// so an app can compose its own page from them; `@softure-ai/blog/next` wires them to the config.
+export { ArticleBody, ArticleDatesList, BlogArticleView, SourceList } from "./blog-article.js";
+export { GlossaryIndexView, GlossaryTermView } from "./blog-glossary.js";
+export { BlogFooterNote, BlogLayout, Breadcrumbs, JsonLdScript } from "./blog-layout.js";
+export { BlogListingView } from "./blog-listing.js";
+export { BlogMethodView } from "./blog-method.js";
+//# sourceMappingURL=index.js.map

package/dist/ui/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,kGAAkG;AAClG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAgD,MAAM,mBAAmB,CAAC;AAC7I,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAA2D,MAAM,oBAAoB,CAAC;AAClI,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAwB,MAAM,kBAAkB,CAAC;AAC/G,OAAO,EAAE,eAAe,EAA6B,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/ui/page-context.d.ts

@@ -0,0 +1,15 @@
+import type { Locale } from "@softure-ai/core";
+import type { BlogMessages } from "../messages/index.js";
+import type { BlogRoutes } from "../pages/paths.js";
+export interface BlogPageContext {
+    readonly messages: BlogMessages;
+    readonly locale: Locale;
+    readonly routes: BlogRoutes;
+    /** The method page's path; `null` when the app does not mount it (nothing links to it then). */
+    readonly methodPath: string | null;
+    /** The site's name for the signature; `null` without a brand. */
+    readonly brand: string | null;
+    /** The note under every text in the locale; `null` without one. */
+    readonly disclaimer: string | null;
+}
+//# sourceMappingURL=page-context.d.ts.map

package/dist/ui/page-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-context.d.ts","sourceRoot":"","sources":["../../src/ui/page-context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC"}

package/dist/ui/page-context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=page-context.js.map

package/dist/ui/page-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-context.js","sourceRoot":"","sources":["../../src/ui/page-context.ts"],"names":[],"mappings":""}

package/migrations/0001_create_articles.sql

@@ -0,0 +1,67 @@
+-- Blog articles and glossary terms, a copy of the app's Markdown files (`softure-blog publish`), and
+-- the history of their old slugs (301 targets). The files are the source of truth; rows change only
+-- through the publish command. A withdrawn article keeps its row (the page answers 410, not 404).
+-- Rollback: DROP TABLE blog.slug_history; DROP TABLE blog.articles; DROP FUNCTION blog.is_kebab(text);
+--   then DELETE FROM softure.migrations WHERE module = 'blog' AND version = 1;
+
+-- A stable key or address segment: lowercase letters and digits joined by single hyphens, at most
+-- 100 characters.
+CREATE FUNCTION is_kebab(value text) RETURNS boolean LANGUAGE sql IMMUTABLE AS $$
+  SELECT char_length(value) <= 100 AND value ~ '^[a-z0-9]+(-[a-z0-9]+)*$'
+$$;
+
+CREATE TABLE articles (
+  -- The file's `id`: given once and never changed, so a slug can change.
+  id text PRIMARY KEY CHECK (is_kebab(id)),
+  -- The address segment; the file is named `<slug>.md`.
+  slug text NOT NULL CHECK (is_kebab(slug)),
+  kind text NOT NULL CHECK (kind IN ('article', 'term')),
+  -- The topic for "read next" lists; the pillar is the main text of its cluster.
+  cluster text CHECK (cluster IS NULL OR is_kebab(cluster)),
+  is_pillar boolean NOT NULL DEFAULT false,
+  title text NOT NULL CHECK (char_length(title) BETWEEN 1 AND 200),
+  description text NOT NULL CHECK (char_length(description) BETWEEN 1 AND 320),
+  -- The "in short" box above the body; NULL for none.
+  summary text CHECK (summary IS NULL OR char_length(summary) BETWEEN 1 AND 600),
+  body_markdown text NOT NULL CHECK (body_markdown <> ''),
+  status text NOT NULL CHECK (status IN ('draft', 'published', 'withdrawn')),
+  -- The day the facts in the text were checked.
+  current_as_of date NOT NULL,
+  published_at timestamptz,
+  -- Moves only when the content of an already published text changes.
+  updated_at timestamptz,
+  -- [{ "name": ..., "url": ... }]
+  sources jsonb NOT NULL DEFAULT '[]' CHECK (jsonb_typeof(sources) = 'array'),
+  -- [{ "question": ..., "answer": ... }]
+  faq jsonb NOT NULL DEFAULT '[]' CHECK (jsonb_typeof(faq) = 'array'),
+  -- The phrases that link to a term's definition (["tax wrapper", "tax wrappers"]); empty for articles.
+  term_forms jsonb NOT NULL DEFAULT '[]' CHECK (jsonb_typeof(term_forms) = 'array'),
+  -- The app's own frontmatter fields (blog({ fields })), as parsed.
+  fields jsonb NOT NULL DEFAULT '{}' CHECK (jsonb_typeof(fields) = 'object'),
+  -- sha256 (hex) of the content the reader sees; unchanged files are skipped by it.
+  content_sha256 text NOT NULL CHECK (content_sha256 ~ '^[0-9a-f]{64}$'),
+  created_at timestamptz NOT NULL,
+  CONSTRAINT articles_slug_key UNIQUE (slug),
+  CONSTRAINT articles_published_has_date CHECK (status <> 'published' OR published_at IS NOT NULL),
+  CONSTRAINT articles_updated_after_publication CHECK (updated_at IS NULL OR published_at IS NOT NULL),
+  CONSTRAINT articles_pillar_has_cluster CHECK (NOT is_pillar OR cluster IS NOT NULL),
+  CONSTRAINT articles_term_forms_by_kind CHECK (
+    (kind = 'term' AND jsonb_array_length(term_forms) > 0) OR (kind = 'article' AND jsonb_array_length(term_forms) = 0)
+  ),
+  -- One pillar per cluster among the texts that are not withdrawn. Deferred to the end of the
+  -- transaction, so a publish run can move the pillar from one article to another.
+  CONSTRAINT articles_one_pillar_per_cluster EXCLUDE USING btree (cluster WITH =)
+    WHERE (is_pillar AND status <> 'withdrawn') DEFERRABLE INITIALLY DEFERRED
+);
+
+-- Lists of published texts, newest first.
+CREATE INDEX articles_published_idx ON articles (published_at DESC, slug) WHERE status = 'published';
+
+CREATE TABLE slug_history (
+  -- A slug the article had before; it redirects to the article's current slug.
+  old_slug text PRIMARY KEY CHECK (is_kebab(old_slug)),
+  article_id text NOT NULL REFERENCES articles (id) ON DELETE CASCADE,
+  changed_at timestamptz NOT NULL
+);
+
+CREATE INDEX slug_history_article_idx ON slug_history (article_id);

package/migrations/README.md

@@ -0,0 +1,8 @@
+# Migrations
+
+Plain SQL, forward only: `NNNN_<description>.sql`, each starting with a comment that states the
+rollback plan (docs/02-module-standard.md §4). The tables live in the `blog` schema.
+
+| File | What it does |
+| --- | --- |
+| `0001_create_articles.sql` | `blog.articles` and `blog.slug_history` with their constraints |

package/module.json

@@ -0,0 +1,28 @@
+{
+  "id": "blog",
+  "version": "0.1.6",
+  "dependsOn": { "seo": "^0.1.0?", "security": "^0.1.0?" },
+  "dbSchema": "blog",
+  "tables": ["articles", "slug_history"],
+  "env": [
+    {
+      "name": "BLOG_REFRESH_SECRET",
+      "required": false,
+      "description": "Shared secret (at least 32 characters) of the cache refresh route refreshBlogCache, set for the running app and for softure-blog publish; without it a publish shows after revalidateSeconds."
+    }
+  ],
+  "switches": [],
+  "routes": { "index": "/blog", "glossary": "/blog/glossary", "method": "/blog/how-we-write", "rss": "/blog/rss.xml", "refresh": "/api/blog/refresh" },
+  "mount": [
+    { "kind": "page", "path": "app/blog/page.tsx", "export": "BlogIndexPage" },
+    { "kind": "page", "path": "app/blog/[slug]/page.tsx", "export": "BlogArticlePage" },
+    { "kind": "route-handler", "path": "app/blog/[slug]/opengraph-image.tsx", "export": "BlogArticleOgImage" },
+    { "kind": "page", "path": "app/blog/glossary/page.tsx", "export": "GlossaryIndexPage" },
+    { "kind": "page", "path": "app/blog/glossary/[slug]/page.tsx", "export": "GlossaryTermPage" },
+    { "kind": "page", "path": "app/blog/how-we-write/page.tsx", "export": "BlogMethodPage" },
+    { "kind": "route-handler", "path": "app/blog/rss.xml/route.ts", "export": "serveBlogRss" },
+    { "kind": "route-handler", "path": "app/api/blog/refresh/route.ts", "export": "refreshBlogCache" },
+    { "kind": "middleware", "path": "proxy.ts", "export": "createBlogRedirects" }
+  ],
+  "privacy": { "exports": false, "deletes": false }
+}

package/package.json

@@ -1,6 +1,104 @@
 {
   "name": "@softure-ai/blog",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.6",
+  "description": "SOFTURE AI blog module: articles and glossary terms kept as Markdown files with a strict YAML frontmatter (extendable by the app's own fields), stored in the module's Postgres schema by the softure-blog publish command (dry run by default, all or nothing, content hash, slug history, one pillar per cluster), a server-side Markdown renderer (no raw HTML, safe links, glossary links, block plugins), a text quality gate (softure-blog check, run before every publish) with language rulesets and rule plugins, the blog's pages ready to mount in Next.js (listing, article, glossary, method page, OG image, JSON-LD) with a proxy piece for 301 and 410, an article writing skill (softure-blog skill install) generated from the gate's rules, and discovery: an RSS feed, read next, sitemap entries and an IndexNow submit on publish through the optional @softure-ai/seo, with a rate-limited cache refresh route the publish calls first (through the optional @softure-ai/security).",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SOFTURE/AI.git",
+    "directory": "modules/blog"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "migrations",
+    "module.json",
+    "skill",
+    "styles.css"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "softure-blog": "./dist/cli/bin.js"
+  },
+  "exports": {
+    ".": {
+      "@softure-ai/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "@softure-ai/source": "./src/server/index.ts",
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./next": {
+      "@softure-ai/source": "./src/next/index.ts",
+      "types": "./dist/next/index.d.ts",
+      "default": "./dist/next/index.js"
+    },
+    "./ui": {
+      "@softure-ai/source": "./src/ui/index.ts",
+      "types": "./dist/ui/index.d.ts",
+      "default": "./dist/ui/index.js"
+    },
+    "./proxy": {
+      "@softure-ai/source": "./src/proxy/index.ts",
+      "types": "./dist/proxy/index.d.ts",
+      "default": "./dist/proxy/index.js"
+    },
+    "./cli": {
+      "@softure-ai/source": "./src/cli/index.ts",
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@softure-ai/core": "^0.1.0",
+    "@softure-ai/db": "^0.1.0",
+    "markdown-it": "^15.0.2",
+    "markdown-it-footnote": "^4.0.0",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@softure-ai/security": "^0.1.0",
+    "@softure-ai/seo": "^0.1.0",
+    "@softure-ai/ui": "^0.1.0",
+    "drizzle-orm": "^0.45.2",
+    "next": "^16.0.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@fontsource/inter": "^5.3.0",
+    "@softure-ai/security": "^0.1.0",
+    "@softure-ai/seo": "^0.1.0",
+    "@softure-ai/ui": "^0.1.7",
+    "@types/markdown-it": "^14.2.0",
+    "@types/markdown-it-footnote": "^3.0.4"
+  },
+  "peerDependenciesMeta": {
+    "@softure-ai/security": {
+      "optional": true
+    },
+    "@softure-ai/seo": {
+      "optional": true
+    }
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: blog-write
+description: Write or revise a blog article or glossary term in {{contentDir}} so that it answers in the first paragraph, sources its numbers, reads like a person wrote it and passes `{{command}} check`. Use for every blog text and before every publish. Triggers - "write an article", "blog post", "revise the article", "refresh the numbers", "add a glossary term".
+---
+
+<!-- Generated by `softure-blog skill install` from @softure-ai/blog and the app's blog() config. Do not edit: change the config and run the command again. -->
+
+# blog-write: blog texts that pass the gate
+
+Texts may reach production without a human read. The only controls are this skill and the gate,
+`{{command}} check`. Search engines punish mass content without value, and AI assistants quote
+texts that carry a number, a source and the answer up front.
+
+Write in **{{languageName}}**.
+{{#firstPersonSingular}}
+The texts are signed by the editors: write "we" (the editors) and "you" (the reader), never "I".
+{{/firstPersonSingular}}
+Tone: calm and concrete, no exclamations, no selling.
+
+## Procedure
+
+1. **Topic and question.** One text answers one question. Write it down in one sentence, the way a
+   person would ask an AI assistant.
+2. **Facts first, text second.** Collect the numbers with their primary sources (laws, official
+   statistics, the issuer's own documents), each with its address. Work out one example for a
+   concrete case: inputs, result. Keep the inputs: they go into a footnote.
+3. **Draft by the structure** in [references/structure.md](references/structure.md): the lead with
+   the answer and a number, `##` sections as questions answered in their first sentence, footnotes
+   on numbers, internal links. The file format is in
+   [references/template.md](references/template.md); save the file as `{{contentDir}}/<slug>.md` with
+   `status: draft`.
+4. **Rewrite by the rules** in [references/rules.md](references/rules.md). Do not patch phrases one
+   by one: when a sentence stays stiff, rewrite the paragraph around its one thought. Never add a fact
+   you do not have from a source or your own calculation. `references/rules.md` lists the rules of
+   this app; where another file mentions a rule, it wins.
+5. **The gate:** `{{command}} check {{contentDir}}/<slug>.md`. Fix every error in the text, never in
+   the gate. Read every warning and fix it unless you have a reason.
+6. **The sceptical reviewer.** Start a separate agent with the prompt in
+   [references/reviewer.md](references/reviewer.md) and only the file, without your context and
+   without this skill. A total below 35/50 or any blocking item: rewrite and go back to step 5.
+7. **The gate with the network:** `{{command}} check {{contentDir}}/<slug>.md --external` from a
+   machine with network access. Where outbound requests are blocked, the app's scheduled links
+   workflow checks them.
+8. **Publish:** set `status: published`, then `{{command}} publish {{contentDir}}/<slug>.md` (a dry
+   run that shows the change) and the same with `--commit`. Publish runs the gate again and refuses an
+   error. Never work around the gate: if a rule is wrong, the fix is a separate change to the rule,
+   with a test.
+
+{{#appSections}}
+## The app's own sections
+
+`references/app.md` adds this app's own procedure: {{appSectionTitles}}. Read it
+before step 2; it adds to the procedure above and never switches off a rule of the gate.
+
+{{/appSections}}
+## Refreshing a text
+
+When a number in a text changes at its source, fix the text, check every other number against its
+source, then move `current_as_of` and publish again. A text whose `current_as_of` is older than
+{{staleAfterDays}} days gets a `stale` warning.
+
+## What we never do
+
+- Mass pages for every combination of inputs, texts without a number of their own, rewrites of
+  other sites' articles.
+{{#ymyl}}
+- Promises of a gain, "no risk", orders to buy a product.
+{{/ymyl}}
+- Keyword stuffing.
+
+Sources of the patterns: `blader/humanizer` (MIT) and `hardikpandya/stop-slop` (MIT), by way of
+FIRE_TRACKER's writing skill: reading, not a dependency.

package/skill/references/reviewer.md

@@ -0,0 +1,39 @@
+# The sceptical reviewer: a prompt for a second agent
+
+Start a separate agent (the Agent tool, a general-purpose agent) with the prompt below and only the
+path of the file. No skill, no author's notes: it must read the way a stranger reads. Keep its answer
+in your scratch notes, not in the repository.
+
+---
+
+You are a sceptical reader of a {{languageName}} guide. You know the topic roughly, you have read
+many texts that sound generated, and you do not trust them. Read the file `<path>` (skip the
+frontmatter and footnotes when judging style, but check that the footnotes support the sentences).
+
+Answer in this order:
+
+1. **The answer in 15 seconds.** What is the text's question, and did you get the answer, with a
+   number, in the first two paragraphs? Quote the sentence.
+2. **Sentences that sound like AI:** literal quotes (at most 10), each with one word for what gives
+   it away (generality, moral, staging, rhythm, inflation, explaining the obvious, borrowed
+   authority).
+3. **Claims without cover:** sentences that state a fact or a number that no footnote supports.
+4. **What is here that is nowhere else?** Does the text have its own number (a worked example for a
+   concrete case), or does it summarize what every other site says?
+5. **Risk for the reader:** does anything read as advice to buy, a promise, or play down a risk?
+6. **Scores 1 to 10** on five axes: directness (states or announces), rhythm (varied or a
+   metronome), trust in the reader, authenticity (sounds like a person), density (can anything be
+   cut). Total out of 50.
+7. **Blocking:** what must be fixed before the text goes out. Empty only when nothing really blocks.
+
+Do not rewrite the text. Do not praise. Be concrete: quote, problem, why.
+
+---
+
+## How to use the answer
+
+- A total below **35/50**, or a non-empty blocking list: rewrite, then run the reviewer again (a new
+  agent, not the same one).
+- An objection under point 3 or 5 always blocks, whatever the score.
+- An objection that comes back text after text is a candidate for a new rule of the gate (a separate
+  change with a test, through the developers).

package/skill/references/rules.md

@@ -0,0 +1,122 @@
+# The rules of the gate
+
+These are the rules `{{command}} check` enforces in this app, with the severity the app gave them.
+An **error** stops the publish at one hit. A warning is reported once per text with a count: fix it
+unless you have a reason. The gate reads {{languageName}} texts; its message names what it found.
+
+The principle behind the style rules: a model writes for the widest possible reader, so it writes
+in generalities. A person writes for one reader about one matter, concretely and unevenly. Every
+sentence that stays adds something the reader did not have yet. When a sentence trips a rule,
+rewrite the paragraph around its one thought; do not swap a word for a synonym.
+
+## File and structure
+
+| Rule | Severity | What the gate looks for | What to write instead |
+| --- | --- | --- | --- |
+| `file` | | | Fix the frontmatter as the message says; the template is in [template.md](template.md). |
+| `title-length` | | | A title up to {{titleChars}} characters, with the question or the number. |
+| `description-length` | | | A description of {{descriptionCharsMin}} to {{descriptionCharsMax}} characters that holds the answer. |
+| `as-of-future` | | | `current_as_of` is the day you checked the facts, never a later one. |
+| `stale` | | | Check every number against its source, then move `current_as_of` (older than {{staleAfterDays}} days warns). |
+| `summary-missing` | | | Add `summary`: a few sentences with the answer and its number, quotable on their own. |
+| `lead` | | | Open with a paragraph that answers the title's question, not with a heading, a list or a quote. |
+| `lead-length` | | | Keep the first paragraph to {{leadWordsArticle}} words in an article, {{leadWordsTerm}} in a term. |
+| `lead-number` | | | Put a concrete number, with its footnote, in the first two paragraphs. |
+| `heading-h1` | | | No `#` heading in the body: the page takes its title from `title`. |
+| `heading-order` | | | Go `##` then `###`; never skip a level. |
+| `sections` | | | At least two `##` sections in an article. |
+| `section-question` | | | Phrase at least one `##` heading as the question a reader asks an assistant. |
+| `section-answer` | | | Under a question heading, a paragraph whose first sentence answers it. |
+| `section-answer-length` | | | Keep the answer paragraph to {{answerWords}} words. |
+| `length` | | | An article of {{articleWordsMin}} to {{articleWordsMax}} words, a term of {{termWordsMin}} to {{termWordsMax}}. |
+| `footnote-undefined` | | | Define every `[^id]` at the end of the file. |
+| `footnote-unused` | | | Remove a footnote definition nothing refers to, or refer to it. |
+| `block-requires` | | | A fenced block of the app's block plugins needs its frontmatter keys; add them. |
+
+## Links
+
+| Rule | Severity | What the gate looks for | What to write instead |
+| --- | --- | --- | --- |
+| `internal-links` | | | At least {{internalLinksArticle}} internal links in an article ({{internalLinksTerm}} in a term): related texts under `{{articlesPath}}/`, glossary terms under `{{termsPath}}/`, the app's pages. |
+| `internal-link-target` | | | Link only to pages, texts and terms that exist (a draft does not count as a target). |
+| `external-link-https` | | | Use the `https://` address of the source. |
+| `external-link-dead` | | | Replace a link that does not answer with the source's current address (checked only with `--external`). |
+| `term-form-conflict` | | | Give each phrase to one term: remove a form from every other term's `forms`, or link the other term by hand where it is meant. |
+
+## Images
+
+| Rule | Severity | What the gate looks for | What to write instead |
+| --- | --- | --- | --- |
+| `image-source` | | | Use an image from the site's own paths or an allowed host; without an image policy the app shows no images, so leave them out. |
+| `image-alt` | | | Give every image an alt text that says what it shows (`![Monthly costs by category](/images/costs.png)`). |
+| `image-dimensions` | | | Use only images the app knows the size of; ask for a new one to be added rather than linking a file. |
+
+## Style
+
+| Rule | Severity | What the gate looks for | What to write instead |
+| --- | --- | --- | --- |
+| `announcement` | | | State the fact itself: not "it is worth noting that the limit grows", but "the limit grows". |
+| `these-days` | | | Start with the number or the answer, not with "these times". |
+| `not-only-but-also` | | | Name both things plainly: "cheap and simple". |
+| `not-x-but-y` | | | Say Y right away; the contrast with X nobody claimed is a template. |
+| `meta-commentary` | | | Remove "in this article", "let us look at", "as mentioned": the text moves forward by itself. |
+| `throat-clearing` | | | Cut the run-up ("the truth is", "interestingly") and keep the claim. |
+| `empty-conclusion` | | | End with the last concrete fact, without "in summary" and a repeat. |
+| `crucial` | | | Name what depends on the thing instead of calling it crucial. |
+| `plays-a-role` | | | Write what the thing does. |
+| `puffery` | | | Replace the inflated phrase ("comprehensive", "game changer", "it depends on many factors") with a fact or a conditional answer with a number. |
+| `chatbot-phrases` | | | Remove leftovers of a chat ("I hope this helps", "great question"). |
+| `emoji` | | | Remove it. |
+| `filler-words` | | | Check whether the sentence says the same without the word; usually it does. |
+| `exclamation` | | | Say it calmly, with a full stop. |
+| `straight-quotes` | | | Use the language's own quotation marks. |
+| `title-case-heading` | | | Capitalize only the first word of a heading (and proper names). |
+| `dashes` | | | At most one dash per {{wordsPerDash}} words: use a full stop, a comma, a colon or brackets. |
+| `dashes-paragraph` | | | At most one dash per paragraph. |
+| `bold-density` | | | Bold at most one phrase per {{wordsPerBold}} words; let the sentence carry the weight. |
+| `bold-labels` | | | Write prose, not lists of "**Label:** text" items. |
+| `triads` | | | Enumerate two things, or four; lists of three in a row read as a template. |
+| `long-sentences` | | | Split sentences longer than {{sentenceWords}} words. |
+| `monotone-rhythm` | | | Mix short and long sentences. |
+| `repeated-openings` | | | Do not start three sentences in a row with the same word. |
+
+## Voice
+
+| Rule | Severity | What the gate looks for | What to write instead |
+| --- | --- | --- | --- |
+| `first-person-singular` | | | Write "we" (the editors) and "you" (the reader), never "I". |
+{{#ymyl}}
+
+## YMYL: sources and claims
+
+| Rule | Severity | What the gate looks for | What to write instead |
+| --- | --- | --- | --- |
+| `sources-missing` | | | List every source in `sources` (name and address). |
+| `source-https` | | | Give every source its `https://` address. |
+| `number-source` | | | Put a footnote on every paragraph, list item or table with an amount, a percentage or a number from 1000 up. |
+| `footnote-source` | | | Give every footnote a source address{{#ownCalculationMark}} or the phrase "{{ownCalculationMark}}" with its inputs{{/ownCalculationMark}}. |
+| `footnote-not-in-sources` | | | Add every address a footnote cites to `sources`. |
+| `profit-promise` | | | Describe the risk and the condition; never promise a gain or tell the reader to buy. |
+{{/ymyl}}
+{{#plugins}}
+
+## Plugins
+
+| Rule | Severity | What the gate looks for | What to write instead |
+| --- | --- | --- | --- |
+| `plugin-failed` | | | A plugin of the app crashed on the text: report it to the developers, do not work around it. |
+| `plugin-rule-undeclared` | | | A plugin reported a rule it does not declare: report it to the developers. |
+{{/plugins}}
+
+## The app's own rules
+
+{{appRules}}
+
+## What the gate cannot catch: check it yourself and ask the reviewer
+
+- A one-sentence moral after every paragraph, golden lines written to be quoted.
+- An argument with nobody ("many people think…"), borrowed authority ("experts say").
+- Explaining the obvious to a reader who came for the number.
+- Vague links ("is related to") instead of naming the relation.
+- Participle tails (", highlighting the importance of…", ", which shows…").
+- Avoiding "is" and "has": "serves as", "constitutes", "offers".