@blamejs/blamejs-shop 0.3.30 → 0.3.31

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.31 (2026-05-31) — **A public help center, authored from the admin console.** The knowledge-base backend was built but had no pages, so there was no way to publish help content or for a shopper to read it. There is now a Help center at /help: a browsable index of published articles grouped by category, and an article page that renders the article, shows a breadcrumb trail in search results, and lets a reader mark whether it was helpful. Operators get a Help center screen in the admin console to write articles, save them as drafts, publish them, and archive them. Article text is written in a small Markdown subset and is fully escaped on the page, and only published, non-archived articles are publicly reachable. **Added:** *Help center for shoppers* — A new /help section lists published articles by category and renders each article at /help/:slug with a breadcrumb (carried into search results as BreadcrumbList structured data) and a "Was this helpful?" control. Article bodies are written in a Markdown subset and escaped on output, and a draft, archived, or unknown article returns a clean 404 — only published articles are ever publicly reachable. · *Help center authoring in the admin console* — A Help center screen lets operators write articles (slug, title, category, body), keep them as drafts, publish or unpublish them, and archive ones that should no longer appear. The list filters by all/published/drafts and shows each article's view count and helpfulness tally, so the team can see what readers are using and which articles need work.
+
 - v0.3.30 (2026-05-31) — **An unrecognized automatic-discount type is now rejected instead of silently becoming free shipping.** When defining or editing an automatic discount over the API, an unrecognized discount type was silently turned into a free-shipping rule — the most generous kind — and accepted without any error. A discount sent over the API with a type outside the supported set (percent off, amount off the total, amount off each item, buy-X-get-Y, or free shipping) is now rejected with a clear error, so a typo can no longer create a store-wide free-shipping rule by accident. The admin form was never affected, because its type selector only offers the supported values. **Fixed:** *Automatic-discount type is validated* — Defining or editing an automatic discount with a discount type outside the supported set now returns a clear error instead of quietly defaulting to free shipping. Previously an unrecognized type sent over the JSON API was coerced into a free-shipping rule and saved with no warning, which could apply free shipping store-wide from a single typo. Free shipping remains a valid, explicitly chosen type; only unrecognized values are rejected. The admin console form was unaffected, since its selector is limited to the supported types.
 
 - v0.3.28 (2026-05-31) — **Customers can now see their store-credit balance and history.** Operators could grant or deduct a customer's store credit, but the customer had no way to see it — the balance only ever surfaced as a silent discount at checkout. A new Store credit page in the account area shows the current balance, a callout for any credit about to expire, and the full ledger of credits, deductions, and expirations with amounts, reasons, and dates. The page is read-only and shows only the signed-in customer's own balance. **Added:** *Store-credit wallet in the account area* — A Store credit page lists a customer's current balance, any credit expiring soon, and the full history of credits, deductions, and expirations — each with its amount, the reason, and the date. It is reachable from the account dashboard and reflects the store credit an operator grants from the customer screen, so a shopper can finally see credit they have been given instead of only discovering it at checkout. The page is read-only and scoped to the signed-in customer.

package/lib/admin.js

@@ -516,7 +516,7 @@ function mount(router, deps) {
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -4846,6 +4846,247 @@ function mount(router, deps) {
     _blogTransition("archive", function (s) { return blog.archive(s); });
   }
 
+  // ---- help center (knowledge base) -----------------------------------
+  // Author the operator's self-serve help articles. The storefront serves
+  // the customer-facing /help index + /help/:slug reader, reading ONLY
+  // published rows; this console writes them. An article is created as a
+  // DRAFT (published defaults off on defineArticle) and stays invisible to
+  // the storefront until it's published — publish / unpublish / archive move
+  // it through the lifecycle. Archive is a soft-delete tombstone: an archived
+  // article drops out of the editable list (the knowledgeBase primitive does
+  // not enumerate archived rows); re-publishing a known slug revives it.
+  // Content-negotiated like the other screens: bearer → the JSON contract;
+  // signed-in browser → the HTML list + author forms.
+  if (deps.knowledgeBase) {
+    var kb = deps.knowledgeBase;
+
+    // The editable list is drafts + published (the knowledgeBase primitive's
+    // listArticles excludes archived tombstones). The status filter narrows
+    // to one lifecycle state.
+    async function _kbRows(filter) {
+      var listing = await kb.listArticles({ published_only: false, limit: kb.MAX_LIST_LIMIT });
+      var rows = listing.rows || [];
+      if (filter === "published") return rows.filter(function (a) { return a.published === true; });
+      if (filter === "draft")     return rows.filter(function (a) { return a.published !== true; });
+      return rows;
+    }
+
+    router.get("/admin/help", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var status = (url && url.searchParams.get("status")) || null;
+        _json(res, 200, { rows: await _kbRows(status) });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var status = (url && url.searchParams.get("status")) || null;
+        var rows = await _kbRows(status);
+        _sendHtml(res, 200, renderAdminHelp({
+          shop_name: deps.shop_name, nav_available: navAvailable, articles: rows,
+          status_filter: status,
+          created:   url && url.searchParams.get("created"),
+          updated:   url && url.searchParams.get("updated"),
+          published: url && url.searchParams.get("published"),
+          archived:  url && url.searchParams.get("archived"),
+          notice:    (url && url.searchParams.get("err")) ? "That action couldn't be completed for the article." : null,
+        }));
+      },
+    ));
+
+    // The new-article form. A standalone GET so the "New article" button on
+    // the list has a target; the create POST lives at /admin/help.
+    router.get("/admin/help/new", _pageOrApi(true,
+      R(async function (_req, res) {
+        return _problem(res, 405, "use-canonical-endpoint", "POST /admin/help with a JSON body to create an article");
+      }),
+      async function (_req, res) {
+        _sendHtml(res, 200, renderAdminHelpDetail({
+          shop_name: deps.shop_name, nav_available: navAvailable, article: null,
+        }));
+      },
+    ));
+
+    // Create content-negotiates: bearer → JSON 201 (the article row); browser
+    // form → defineArticle, then PRG to the detail screen. Every article is
+    // born a DRAFT (defineArticle defaults published off) — never published on
+    // create — so it can't reach the storefront before the operator publishes.
+    router.post("/admin/help", _pageOrApi(false,
+      W("help.create", async function (req, res) {
+        var row = await kb.defineArticle(_kbFromForm(req.body || {}));
+        _json(res, 201, row);
+        return { id: row.slug };
+      }),
+      async function (req, res) {
+        var made;
+        try {
+          made = await kb.defineArticle(_kbFromForm(req.body || {}));
+        } catch (e) {
+          var n = _safeNotice(e, "help.create");
+          return _sendHtml(res, n.status, renderAdminHelpDetail({
+            shop_name: deps.shop_name, nav_available: navAvailable, article: null,
+            form_values: req.body || {},
+            notice: n.message.replace(/^knowledgeBase[.:]\s*/, ""),
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".help.create", outcome: "success", metadata: { slug: made.slug } });
+        _redirect(res, "/admin/help/" + encodeURIComponent(made.slug) + "?created=1");
+      },
+    ));
+
+    // Detail content-negotiates: bearer → JSON (the row); browser → the edit
+    // form + the lifecycle action buttons + the view/vote read. A bad /
+    // unknown slug is a 404 page, never a 500. (getArticle returns null for
+    // an archived tombstone too — an archived slug reads as "not here".)
+    router.get("/admin/help/:slug", _pageOrApi(true,
+      R(async function (req, res) {
+        var row;
+        try { row = await kb.getArticle({ slug: req.params.slug }); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 404, "help-article-not-found", e.message); throw e; }
+        if (!row) return _problem(res, 404, "help-article-not-found");
+        _json(res, 200, row);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var row;
+        try { row = await kb.getArticle({ slug: req.params.slug }); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; row = null; }
+        if (!row) return _sendHtml(res, 404, renderAdminHelp({
+          shop_name: deps.shop_name, nav_available: navAvailable, articles: [], notice: "Article not found.",
+        }));
+        // The helpfulness aggregate is a cheap, useful read to surface.
+        var aggregate = null;
+        try { aggregate = await kb.voteAggregateForArticle(row.slug); }
+        catch (_e) { aggregate = null; }
+        _sendHtml(res, 200, renderAdminHelpDetail({
+          shop_name: deps.shop_name, nav_available: navAvailable, article: row, aggregate: aggregate,
+          updated:   url && url.searchParams.get("updated"),
+          published: url && url.searchParams.get("published"),
+          notice:    (url && url.searchParams.get("err")) ? "That action couldn't be completed for the article." : null,
+        }));
+      },
+    ));
+
+    // Edit content-negotiates: bearer PATCH (the JSON contract) + browser
+    // POST /edit (HTML forms can't PATCH). Both patch the editable columns
+    // (title / body / category / tags). Status is NOT editable here — it
+    // moves via the lifecycle routes below.
+    router.patch("/admin/help/:slug", W("help.update", async function (req, res) {
+      var row;
+      try { row = await kb.updateArticle(req.params.slug, req.body || {}); }
+      catch (e) {
+        if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+        if (e && e.code === "KB_ARTICLE_NOT_FOUND") return _problem(res, 404, "help-article-not-found");
+        if (e && e.code === "KB_ARTICLE_ARCHIVED")  return _problem(res, 409, "conflict", e.message);
+        throw e;
+      }
+      _json(res, 200, row);
+      return { id: row.slug };
+    }));
+
+    router.post("/admin/help/:slug/edit", _pageOrApi(false,
+      W("help.update", async function (req, res) {
+        var row;
+        try { row = await kb.updateArticle(req.params.slug, req.body || {}); }
+        catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          if (e && e.code === "KB_ARTICLE_NOT_FOUND") return _problem(res, 404, "help-article-not-found");
+          if (e && e.code === "KB_ARTICLE_ARCHIVED")  return _problem(res, 409, "conflict", e.message);
+          throw e;
+        }
+        _json(res, 200, row);
+        return { id: row.slug };
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var enc  = encodeURIComponent(slug);
+        try {
+          await kb.updateArticle(slug, _kbPatchFromForm(req.body || {}));
+        } catch (e) {
+          if (e && (e.code === "KB_ARTICLE_NOT_FOUND")) return _redirect(res, "/admin/help?err=1");
+          var n = _safeNotice(e, "help.update");
+          var current = null;
+          try { current = await kb.getArticle({ slug: slug }); } catch (_e) { current = null; }
+          if (!current) return _redirect(res, "/admin/help?err=1");
+          return _sendHtml(res, n.status, renderAdminHelpDetail({
+            shop_name: deps.shop_name, nav_available: navAvailable, article: current,
+            notice: n.message.replace(/^knowledgeBase[.:]\s*/, ""),
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".help.update", outcome: "success", metadata: { slug: slug } });
+        _redirect(res, "/admin/help/" + enc + "?updated=1");
+      },
+    ));
+
+    // Lifecycle transitions. publish takes a draft live (now visible on the
+    // storefront /help); unpublish pulls it back to draft (gone from the
+    // storefront). publish also REVIVES an archived slug (the primitive
+    // clears the archive tombstone on publish). A missing slug is a ?err=1
+    // notice, never a 500.
+    function _kbTransition(action, fn, landsOnList) {
+      router.post("/admin/help/:slug/" + action, _pageOrApi(false,
+        W("help." + action, async function (req, res) {
+          var row;
+          try { row = await fn(req.params.slug); }
+          catch (e) {
+            if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+            if (e && e.code === "KB_ARTICLE_NOT_FOUND") return _problem(res, 404, "help-article-not-found");
+            throw e;
+          }
+          _json(res, 200, row);
+          return { id: row.slug };
+        }),
+        async function (req, res) {
+          var slug = req.params.slug;
+          var enc  = encodeURIComponent(slug);
+          try {
+            await fn(slug);
+          } catch (e) {
+            if (e instanceof TypeError || (e && e.code === "KB_ARTICLE_NOT_FOUND")) {
+              return _redirect(res, "/admin/help/" + enc + "?err=1");
+            }
+            throw e;
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".help." + action, outcome: "success", metadata: { slug: slug } });
+          // archive lands back on the list (the article left the editable set
+          // — it's a tombstone now); the others stay on the detail with a
+          // status banner.
+          if (landsOnList) return _redirect(res, "/admin/help?archived=1");
+          _redirect(res, "/admin/help/" + enc + (action === "publish" ? "?published=1" : "?updated=1"));
+        },
+      ));
+    }
+    _kbTransition("publish",   function (s) { return kb.publishArticle(s); }, false);
+    _kbTransition("unpublish", function (s) { return kb.unpublishArticle(s); }, false);
+
+    // Archive is destructive-ish (the article leaves the live storefront and
+    // the editable list — the primitive tombstones it), so the browser path
+    // confirms first (the CSP forbids a client confirm() dialog). Reached by
+    // a GET link from the detail screen; bearer clients POST /archive directly.
+    router.get("/admin/help/:slug/archive/confirm-page", _pageOrApi(true,
+      R(async function (_req, res) {
+        return _problem(res, 405, "use-canonical-endpoint", "POST /admin/help/:slug/archive directly for the JSON API");
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var enc  = encodeURIComponent(slug);
+        var row = null;
+        try { row = await kb.getArticle({ slug: slug }); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; }
+        if (!row) return _redirect(res, "/admin/help?err=1");
+        _sendHtml(res, 200, renderAdminConfirm({
+          shop_name: deps.shop_name, nav_available: navAvailable, active: "help",
+          heading: "Archive this article?",
+          consequence: "Archiving removes the article from the live help center and the editable list. Re-publishing the same slug later revives it.",
+          detail: "Article: " + (row.title || slug) + ".",
+          action: "/admin/help/" + _htmlEscape(enc) + "/archive",
+          confirm_label: "Archive article",
+          cancel_href: "/admin/help/" + enc,
+        }));
+      },
+    ));
+    _kbTransition("archive", function (s) { return kb.archiveArticle(s); }, true);
+  }
+
   // ---- storefront pages -----------------------------------------------
   // Author the operator's CMS content pages (About, Shipping, Returns,
   // Privacy, Terms, and the long tail every shop needs). The edge Worker
@@ -8123,6 +8364,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "pick-lists",   href: "/admin/pick-lists",   label: "Pick lists",   requires: "pickLists" },
   { key: "announcements", href: "/admin/announcements", label: "Announcements", requires: "announcementBar" },
   { key: "blog",         href: "/admin/blog",         label: "Blog",         requires: "blog" },
+  { key: "help",         href: "/admin/help",         label: "Help center",  requires: "knowledgeBase" },
   { key: "pages",        href: "/admin/pages",        label: "Pages",        requires: "storefrontPages" },
   { key: "surveys",      href: "/admin/surveys",      label: "Surveys",      requires: "customerSurveys" },
   { key: "hours",        href: "/admin/hours",        label: "Hours",        requires: "businessHours" },
@@ -11417,6 +11659,197 @@ function _blogStatusPill(status) {
   return "<span class=\"status-pill " + cls + "\">" + _htmlEscape(status) + "</span>";
 }
 
+// ---- help center (knowledge base) authoring ----------------------------
+
+// Coerce the create form into knowledgeBase.defineArticle's shape: trimmed
+// slug + category, the required title/body, the optional tags + locale (a
+// blank optional field is omitted so the primitive's default applies). The
+// primitive validates every field — this only shapes the form strings.
+function _kbFromForm(body) {
+  body = body || {};
+  var out = {
+    slug:     typeof body.slug === "string" ? body.slug.trim() : body.slug,
+    title:    body.title,
+    body:     body.body,
+    category: typeof body.category === "string" ? body.category.trim() : body.category,
+    locale:   (typeof body.locale === "string" && body.locale.trim()) ? body.locale.trim() : "en",
+  };
+  var tags = _csvTags(body.tags);
+  if (tags.length) out.tags = tags;
+  return out;
+}
+
+// Coerce the edit form into a knowledgeBase.updateArticle patch. Only the
+// columns the form carries are included; tags always ride (an empty list
+// clears them). Status / locale are NOT here — status moves via the
+// lifecycle routes, and the edit form patches the default-locale row.
+function _kbPatchFromForm(body) {
+  body = body || {};
+  var patch = { tags: _csvTags(body.tags) };
+  if (typeof body.title === "string")    patch.title = body.title;
+  if (typeof body.body === "string")     patch.body = body.body;
+  if (typeof body.category === "string" && body.category.trim()) patch.category = body.category.trim();
+  return patch;
+}
+
+// One status pill per lifecycle state. The knowledgeBase row exposes a
+// boolean `published` (not the blog's string FSM); an archived row never
+// reaches this renderer (the primitive tombstones it out of every read).
+function _kbStatusPill(article) {
+  var label = article && article.published === true ? "published" : "draft";
+  var cls = label === "published" ? "paid" : "pending";
+  return "<span class=\"status-pill " + cls + "\">" + _htmlEscape(label) + "</span>";
+}
+
+function renderAdminHelp(opts) {
+  opts = opts || {};
+  var rows = opts.articles || [];
+  var created   = opts.created   ? "<div class=\"banner banner--ok\">Article created as a draft.</div>" : "";
+  var updated   = opts.updated   ? "<div class=\"banner banner--ok\">Article saved.</div>" : "";
+  var published = opts.published ? "<div class=\"banner banner--ok\">Article published — it's live on the help center.</div>" : "";
+  var archived  = opts.archived  ? "<div class=\"banner banner--ok\">Article archived.</div>" : "";
+  var notice    = opts.notice    ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var sf = opts.status_filter;
+  var chips = "<div class=\"order-filters\">" +
+    "<a class=\"chip" + (sf == null ? " chip--on" : "") + "\" href=\"/admin/help\">All</a>" +
+    "<a class=\"chip" + (sf === "published" ? " chip--on" : "") + "\" href=\"/admin/help?status=published\">Published</a>" +
+    "<a class=\"chip" + (sf === "draft" ? " chip--on" : "") + "\" href=\"/admin/help?status=draft\">Drafts</a>" +
+    "</div>";
+
+  var bodyRows = rows.map(function (a) {
+    var enc = encodeURIComponent(a.slug);
+    var views = a.view_count != null ? String(a.view_count) : "0";
+    // Per-row lifecycle actions match the article's current state: a draft
+    // can publish; a published article can unpublish or archive. Edit is
+    // always offered.
+    var actions = "<a class=\"btn btn--ghost\" href=\"/admin/help/" + _htmlEscape(enc) + "\">Edit</a>";
+    if (a.published === true) {
+      actions += "<form method=\"post\" action=\"/admin/help/" + _htmlEscape(enc) + "/unpublish\" class=\"form-inline\">" +
+        "<button class=\"btn btn--ghost\" type=\"submit\">Unpublish</button></form>" +
+        "<a class=\"btn btn--danger\" href=\"/admin/help/" + _htmlEscape(enc) + "/archive/confirm-page\">Archive</a>";
+    } else {
+      actions += "<form method=\"post\" action=\"/admin/help/" + _htmlEscape(enc) + "/publish\" class=\"form-inline\">" +
+        "<button class=\"btn\" type=\"submit\">Publish</button></form>";
+    }
+    return "<tr>" +
+      "<td><a href=\"/admin/help/" + _htmlEscape(enc) + "\"><strong>" + _htmlEscape(a.title) + "</strong></a></td>" +
+      "<td><code class=\"order-id\">" + _htmlEscape(a.slug) + "</code></td>" +
+      "<td>" + _htmlEscape(a.category || "") + "</td>" +
+      "<td>" + _kbStatusPill(a) + "</td>" +
+      "<td>" + _htmlEscape(views) + "</td>" +
+      "<td><div class=\"actions-row\">" + actions + "</div></td>" +
+    "</tr>";
+  }).join("");
+
+  var table = rows.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Title</th><th scope=\"col\">Slug</th><th scope=\"col\">Category</th><th scope=\"col\">Status</th><th scope=\"col\">Views</th><th scope=\"col\">Actions</th></tr></thead><tbody>" + bodyRows + "</tbody></table></div>"
+    : "<p class=\"empty\">No articles" + (sf ? " " + _htmlEscape(sf) : " yet") + ". Write your first one.</p>";
+
+  var newBtn = "<div class=\"actions-row\"><a class=\"btn\" href=\"/admin/help/new\">New article</a></div>";
+
+  var bodyHtml = "<section><h2>Help center</h2>" +
+    created + updated + published + archived + notice +
+    "<p class=\"meta\">Self-serve help articles shown on the storefront help center (/help). An article is created as a draft and stays hidden until you publish it. Archiving removes it from the list; re-publishing the same slug revives it.</p>" +
+    newBtn + chips + table + "</section>";
+  return _renderAdminShell(opts.shop_name, "Help center", bodyHtml, "help", opts.nav_available);
+}
+
+// New-article form (article: null) or edit form (article set) for a single
+// help article, plus the lifecycle action row + the helpfulness aggregate
+// when editing. `form_values` re-fills a failed create so the operator
+// doesn't retype.
+function renderAdminHelpDetail(opts) {
+  opts = opts || {};
+  var a = opts.article || null;
+  var isNew = !a;
+  var fv = opts.form_values || {};
+  var updated   = opts.updated   ? "<div class=\"banner banner--ok\">Article saved.</div>" : "";
+  var published = opts.published ? "<div class=\"banner banner--ok\">Article published — it's live on the help center.</div>" : "";
+  var notice    = opts.notice    ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  function _val(col) {
+    if (a && a[col] != null) return a[col];
+    if (fv[col] != null) return fv[col];
+    return "";
+  }
+  var tagsVal = a && Array.isArray(a.tags) ? a.tags.join(", ")
+              : (typeof fv.tags === "string" ? fv.tags : "");
+
+  var action = isNew ? "/admin/help" : "/admin/help/" + encodeURIComponent(a.slug) + "/edit";
+  // Slug is the PK — editable only on create. On edit it shows read-only so
+  // the operator sees the storefront URL.
+  var slugField = isNew
+    ? _setupField("Slug", "slug", _val("slug"), "text", "Lowercase letters, digits, and hyphens — appears in /help/<slug>.", " maxlength=\"120\" required")
+    : "<label class=\"form-field\"><span>Slug</span><input type=\"text\" value=\"" + _htmlEscape(a.slug) + "\" readonly>" +
+        "<small>The storefront URL: <code>/help/" + _htmlEscape(a.slug) + "</code></small></label>";
+  // Category is editable on both create + edit (the primitive treats it as
+  // slug-wide). On create it's required; on edit the patch rewrites it.
+  var categoryField = _setupField(
+    "Category", "category", _val("category"), "text",
+    "Groups the article on the help index — lowercase, e.g. orders, shipping, returns.",
+    " maxlength=\"80\"" + (isNew ? " required" : "")
+  );
+
+  var form =
+    "<div class=\"panel mw-40\">" +
+      "<h3 class=\"subhead\">" + (isNew ? "New article" : "Article details") + "</h3>" +
+      "<form method=\"post\" action=\"" + _htmlEscape(action) + "\">" +
+        slugField +
+        _setupField("Title", "title", _val("title"), "text", "", " maxlength=\"200\" required") +
+        categoryField +
+        "<label class=\"form-field\"><span>Body (Markdown)</span>" +
+          "<textarea name=\"body\" rows=\"16\" maxlength=\"32000\" required>" + _htmlEscape(_val("body")) + "</textarea>" +
+          "<small>Headings, lists, links, bold/italic. Raw HTML is escaped — links are https-only.</small></label>" +
+        _setupField("Tags (optional)", "tags", tagsVal, "text", "Comma-separated, e.g. refunds, delivery.", " maxlength=\"1000\"") +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">" + (isNew ? "Create draft" : "Save") + "</button>" +
+          "<a class=\"btn btn--ghost\" href=\"/admin/help\">Back</a></div>" +
+      "</form>" +
+    "</div>";
+
+  var lifecycle = "";
+  if (!isNew) {
+    var enc = encodeURIComponent(a.slug);
+    var btns = "";
+    if (a.published === true) {
+      btns = "<form method=\"post\" action=\"/admin/help/" + _htmlEscape(enc) + "/unpublish\" class=\"form-inline\">" +
+        "<button class=\"btn btn--ghost\" type=\"submit\">Unpublish</button></form>" +
+        "<a class=\"btn btn--danger\" href=\"/admin/help/" + _htmlEscape(enc) + "/archive/confirm-page\">Archive</a>" +
+        "<span class=\"meta\">Unpublish pulls it back to a draft; archive removes it from the help center.</span>";
+    } else {
+      btns = "<form method=\"post\" action=\"/admin/help/" + _htmlEscape(enc) + "/publish\" class=\"form-inline\">" +
+        "<button class=\"btn\" type=\"submit\">Publish</button></form>" +
+        "<span class=\"meta\">Publishing makes the article live on the storefront help center.</span>";
+    }
+    // The helpfulness aggregate + view count — a cheap, useful read.
+    var agg = opts.aggregate;
+    var stats = "";
+    if (agg) {
+      var ratio = agg.helpfulness_ratio == null ? "—" : Math.round(agg.helpfulness_ratio * 100) + "%";
+      stats = "<p class=\"meta\">Views: " + _htmlEscape(String(a.view_count == null ? 0 : a.view_count)) +
+        " · Helpful: " + _htmlEscape(String(agg.helpful_count)) +
+        " / Not helpful: " + _htmlEscape(String(agg.not_helpful_count)) +
+        " (" + _htmlEscape(ratio) + " helpful)</p>";
+    }
+    lifecycle = "<div class=\"panel mt-1 mw-40\"><h3 class=\"subhead\">Status</h3>" +
+      "<p class=\"meta\">Current state: " + _kbStatusPill(a) + "</p>" + stats +
+      "<div class=\"actions-row\">" + btns + "</div></div>";
+  }
+
+  var head = isNew
+    ? "<p class=\"meta\"><a href=\"/admin/help\">&larr; Help center</a></p>"
+    : "<p class=\"meta\"><a href=\"/admin/help\">&larr; Help center</a> · " +
+        _kbStatusPill(a) +
+        (a.published === true
+          ? " · <a href=\"/help/" + _htmlEscape(encodeURIComponent(a.slug)) + "\" target=\"_blank\" rel=\"noreferrer\">View on storefront &rarr;</a>"
+          : "") +
+      "</p>";
+
+  var title = isNew ? "New article" : (a.title || a.slug);
+  var body = "<section><h2>" + _htmlEscape(title) + "</h2>" + updated + published + notice + head + form + "</section>" + lifecycle;
+  return _renderAdminShell(opts.shop_name, isNew ? "New article" : "Article " + a.slug, body, "help", opts.nav_available);
+}
+
 function renderAdminBlog(opts) {
   opts = opts || {};
   var rows = opts.articles || [];
@@ -12925,6 +13358,8 @@ module.exports = {
   renderAdminCollection:   renderAdminCollection,
   renderAdminBlog:         renderAdminBlog,
   renderAdminBlogDetail:   renderAdminBlogDetail,
+  renderAdminHelp:         renderAdminHelp,
+  renderAdminHelpDetail:   renderAdminHelpDetail,
   renderAdminPages:        renderAdminPages,
   renderAdminPageDetail:   renderAdminPageDetail,
   renderAdminGiftCards:    renderAdminGiftCards,

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.30",
+  "version": "0.3.31",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-1SIn6oAf1DjECbRfKENZasdKHJiywGdXR58wn0hsFGcdVHzUmvfgMkEz5ANIAZJ3",

package/lib/storefront.js

@@ -6953,6 +6953,171 @@ function renderHoursPage(opts) {
   });
 }
 
+// ---- help center (knowledge base) --------------------------------------
+//
+// The public /help reader: an index grouped by category, and a per-article
+// page with the safely-rendered body, a breadcrumb, BreadcrumbList JSON-LD,
+// and a "Was this helpful?" control. Container-rendered (not edge): the
+// article body is the knowledgeBase primitive's own `body_html`, which it
+// computes through the shared Markdown subset (every text run escaped via
+// b.template.escapeHtml, every link URL gated by b.safeUrl) — so the page
+// never emits unescaped operator HTML, and the renderer here only ever
+// interpolates already-rendered, already-escaped fragments. The vote POST
+// needs a per-session CSRF token, which the container already issues; the
+// edge serves no per-session forms.
+
+// The help index. `opts.groups` is an array of { category, articles: [...] }
+// (each article: { slug, title }); `opts.popular` is an optional array of
+// { slug, title }. An empty index renders a friendly notice. The body never
+// carries operator HTML — titles are escaped at the sink.
+function renderHelpIndex(opts) {
+  opts = opts || {};
+  var esc = function (s) { return b.template.escapeHtml(String(s == null ? "" : s)); };
+  var groups = opts.groups || [];
+  var shopName = opts.shop_name || "blamejs.shop";
+
+  var body;
+  if (!groups.length) {
+    body =
+      "<section class=\"help-page\"><div class=\"help-page__inner help-page__inner--msg\">" +
+        "<p class=\"eyebrow\">Help center</p>" +
+        "<h1 class=\"help-page__title\">Help center</h1>" +
+        "<p class=\"help-page__lede\">No help articles have been published yet. Check back soon.</p>" +
+        "<a class=\"btn-ghost\" href=\"/\">Back to the shop</a>" +
+      "</div></section>";
+  } else {
+    var popular = opts.popular || [];
+    var popularHtml = popular.length
+      ? "<aside class=\"help-popular\"><h2 class=\"help-popular__title\">Popular articles</h2><ul class=\"help-popular__list\">" +
+          popular.map(function (a) {
+            return "<li><a href=\"/help/" + esc(encodeURIComponent(a.slug)) + "\">" + esc(a.title) + "</a></li>";
+          }).join("") +
+        "</ul></aside>"
+      : "";
+    var sections = groups.map(function (g) {
+      var items = (g.articles || []).map(function (a) {
+        return "<li class=\"help-list__item\"><a href=\"/help/" + esc(encodeURIComponent(a.slug)) + "\">" + esc(a.title) + "</a></li>";
+      }).join("");
+      return "<section class=\"help-category\">" +
+               "<h2 class=\"help-category__title\">" + esc(g.category) + "</h2>" +
+               "<ul class=\"help-list\">" + items + "</ul>" +
+             "</section>";
+    }).join("");
+    body =
+      "<section class=\"help-page\"><div class=\"help-page__inner\">" +
+        "<p class=\"eyebrow\">Help center</p>" +
+        "<h1 class=\"help-page__title\">How can we help?</h1>" +
+        "<p class=\"help-page__lede\">Browse answers to common questions.</p>" +
+        popularHtml +
+        "<div class=\"help-categories\">" + sections + "</div>" +
+      "</div></section>";
+  }
+  return _wrap({
+    title:         "Help center",
+    shop_name:     shopName,
+    cart_count:    opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:     opts.theme_css,
+    og_description: "Help center for " + shopName + " — answers to common questions.",
+    canonical_url: opts.canonical_url,
+    og_url:        opts.og_url,
+    body:          body,
+  });
+}
+
+// A single help article. `opts.article` is the hydrated knowledgeBase row —
+// `body_html` is ALREADY the safely-rendered HTML (escaped + link-gated by
+// the primitive), so it's spliced verbatim into the page (via spliceRaw, so
+// a `$`-bearing body can't trip String.replace's dollar substitution). The
+// breadcrumb is Help -> [category] -> title with a matching BreadcrumbList
+// JSON-LD (mirrors the PDP / collection shape); the "Was this helpful?"
+// control POSTs to /help/:slug/vote and is CSRF-tokened by `_wrap`.
+function renderHelpArticle(opts) {
+  opts = opts || {};
+  var esc = function (s) { return b.template.escapeHtml(String(s == null ? "" : s)); };
+  var article = opts.article;
+  if (!article || typeof article !== "object") {
+    throw new TypeError("storefront.renderHelpArticle: opts.article required");
+  }
+  var shopName = opts.shop_name || "blamejs.shop";
+  var slugEnc  = esc(encodeURIComponent(article.slug));
+
+  var crumbHtml =
+    "<li><a href=\"/help\">Help</a></li>" +
+    (article.category ? "<li><a href=\"/help?category=" + esc(encodeURIComponent(article.category)) + "\">" + esc(article.category) + "</a></li>" : "") +
+    "<li aria-current=\"page\">" + esc(article.title) + "</li>";
+
+  // The vote control. The form posts to the container path /help/:slug/vote
+  // (never an edge-exempt prefix), so `_injectCsrfFields` stamps it with the
+  // per-request double-submit token. `voted` re-renders the confirmation
+  // after a vote; absent it, the two buttons render.
+  var voteHtml;
+  if (opts.voted) {
+    voteHtml = "<p class=\"help-vote__thanks\">Thanks for your feedback.</p>";
+  } else {
+    voteHtml =
+      "<form class=\"help-vote\" method=\"post\" action=\"/help/" + slugEnc + "/vote\">" +
+        "<p class=\"help-vote__q\">Was this helpful?</p>" +
+        "<div class=\"help-vote__actions\">" +
+          "<button class=\"btn-ghost\" type=\"submit\" name=\"vote\" value=\"helpful\">Yes</button>" +
+          "<button class=\"btn-ghost\" type=\"submit\" name=\"vote\" value=\"not_helpful\">No</button>" +
+        "</div>" +
+      "</form>";
+  }
+
+  var articleHtml =
+    "<article class=\"help-article\">" +
+      "<nav class=\"breadcrumb\" aria-label=\"Breadcrumb\"><ol>" + crumbHtml + "</ol></nav>" +
+      "<header class=\"help-article__head\">" +
+        "<p class=\"eyebrow\">Help</p>" +
+        "<h1 class=\"help-article__title\">" + esc(article.title) + "</h1>" +
+      "</header>" +
+      "<div class=\"help-article__body\">RAW_HELP_BODY_PLACEHOLDER</div>" +
+      "<footer class=\"help-article__foot\">" + voteHtml +
+        "<p class=\"help-article__back\"><a href=\"/help\">&larr; Back to help center</a></p>" +
+      "</footer>" +
+    "</article>";
+  // body_html is the primitive's already-escaped, already-link-gated render —
+  // splice it literally so a `$`-bearing body can't trip dollar substitution.
+  articleHtml = _spliceRaw(articleHtml, "RAW_HELP_BODY_PLACEHOLDER", String(article.body_html || ""));
+
+  // BreadcrumbList JSON-LD mirroring the on-page breadcrumb. The `item` URLs
+  // are absolute so the structured data is fully-qualified. Mirrors the PDP /
+  // collection breadcrumb shape.
+  var absoluteBase = _absoluteBase(opts.canonical_url, shopName);
+  var crumbItems = [
+    { "@type": "ListItem", "position": 1, "name": "Help", "item": absoluteBase + "/help" },
+  ];
+  var pos = 2;
+  if (article.category) {
+    crumbItems.push({
+      "@type": "ListItem", "position": pos, "name": article.category,
+      "item": absoluteBase + "/help?category=" + encodeURIComponent(article.category),
+    });
+    pos += 1;
+  }
+  crumbItems.push({
+    "@type": "ListItem", "position": pos, "name": article.title,
+    "item": absoluteBase + "/help/" + encodeURIComponent(article.slug),
+  });
+  var breadcrumbJsonLd = _jsonLdScript({
+    "@context":        "https://schema.org",
+    "@type":           "BreadcrumbList",
+    "itemListElement": crumbItems,
+  });
+
+  return _wrap({
+    title:         article.title,
+    shop_name:     shopName,
+    cart_count:    opts.cart_count == null ? 0 : opts.cart_count,
+    theme_css:     opts.theme_css,
+    og_description: "Help: " + article.title,
+    og_type:       "article",
+    canonical_url: opts.canonical_url,
+    og_url:        opts.og_url,
+    body:          articleHtml + breadcrumbJsonLd,
+  });
+}
+
 function mount(router, deps) {
   if (!router || typeof router.get !== "function") throw new TypeError("storefront.mount: router with .get() required");
   if (!deps || !deps.catalog || !deps.cart) throw new TypeError("storefront.mount: deps.catalog + deps.cart required");
@@ -7467,6 +7632,174 @@ function mount(router, deps) {
     });
   }
 
+  // ---- help center (knowledge base) -----------------------------------
+  // The public self-serve help reader. GET /help is the category-grouped
+  // index of PUBLISHED articles; GET /help/:slug is one article (its
+  // body_html is the primitive's escaped + link-gated render); POST
+  // /help/:slug/vote records a "was this helpful?" vote. Container-rendered
+  // (the vote form carries a per-request CSRF token `_wrap` injects).
+  // Resilient: a missing table / read failure renders the empty state or a
+  // clean 404/notice, never a 500.
+  if (deps.knowledgeBase) {
+    var kb = deps.knowledgeBase;
+
+    function _helpThemeCss() {
+      return (theme && theme.assetUrl) ? theme.assetUrl("css/main.css") : DEFAULT_THEME_CSS_URL;
+    }
+
+    // The published-only article gate. getArticle returns a row in ANY
+    // state (the primitive's getArticle is not status-filtered), so the
+    // public route MUST refuse anything that isn't published + non-archived
+    // — a draft or archived article is invisible to the storefront, exactly
+    // like the blog / CMS-page reader. Returns the hydrated row when it's
+    // publicly viewable, else null (the route 404s). A malformed slug throws
+    // a TypeError in the primitive, which the caller maps to a 404.
+    async function _kbPublishedArticle(slug, locale) {
+      var row = await kb.getArticle({ slug: slug, locale: locale });
+      if (!row) return null;
+      if (row.published !== true) return null;
+      if (row.archived_at != null) return null;
+      return row;
+    }
+
+    router.get("/help", async function (req, res) {
+      var urls = _requestUrls(req);
+      var rendered;
+      try {
+        var cartCount = await _cartCountForReq(req);
+        // Category filter (the breadcrumb links carry ?category=…). An
+        // invalid value just falls back to the full index (the primitive
+        // throws on a bad category, which we swallow to a no-filter list).
+        var category = null;
+        var q = req.query || {};
+        if (typeof q.category === "string" && q.category.length) category = q.category;
+        var listOpts = { published_only: true, limit: kb.MAX_LIST_LIMIT };
+        if (category) listOpts.category = category;
+        var listing;
+        try { listing = await kb.listArticles(listOpts); }
+        catch (_e) { listing = await kb.listArticles({ published_only: true, limit: kb.MAX_LIST_LIMIT }); }
+        var rows = listing.rows || [];
+        // Group by category, preserving the listArticles order (updated_at
+        // DESC) within each group; categories appear in first-seen order.
+        var order = [];
+        var byCat = {};
+        for (var i = 0; i < rows.length; i += 1) {
+          var a = rows[i];
+          var c = a.category || "general";
+          if (!byCat[c]) { byCat[c] = []; order.push(c); }
+          byCat[c].push({ slug: a.slug, title: a.title });
+        }
+        var groups = order.map(function (cc) { return { category: cc, articles: byCat[cc] }; });
+        // Popular block — best-effort over a 30-day window; any failure just
+        // drops the rail (it's a cheap nicety, not a contract).
+        var popular = [];
+        try {
+          var titleBySlug = {};
+          for (var pi = 0; pi < rows.length; pi += 1) titleBySlug[rows[pi].slug] = rows[pi].title;
+          var to = Date.now();
+          var from = to - b.constants.TIME.days(30);
+          var pop = await kb.popularArticles({ from: from, to: to, limit: 5 });
+          for (var k = 0; k < pop.length; k += 1) {
+            if (titleBySlug[pop[k].slug]) popular.push({ slug: pop[k].slug, title: titleBySlug[pop[k].slug] });
+          }
+        } catch (_e2) { popular = []; }
+        rendered = renderHelpIndex({
+          groups: groups, popular: popular, shop_name: shopName, cart_count: cartCount,
+          theme_css: _helpThemeCss(), canonical_url: urls.canonical_url, og_url: urls.og_url,
+        });
+      } catch (_e) {
+        // Table absent / read failure → the empty state, never a 500.
+        rendered = renderHelpIndex({
+          groups: [], shop_name: shopName, cart_count: 0, theme_css: _helpThemeCss(),
+          canonical_url: urls.canonical_url, og_url: urls.og_url,
+        });
+      }
+      _send(res, 200, rendered);
+    });
+
+    router.get("/help/:slug", async function (req, res) {
+      var slug = (req.params && req.params.slug) || "";
+      var urls = _requestUrls(req);
+      var cartCount = 0;
+      try { cartCount = await _cartCountForReq(req); } catch (_e) { cartCount = 0; }
+      var article = null;
+      try {
+        article = await _kbPublishedArticle(slug);
+      } catch (e) {
+        if (!(e instanceof TypeError)) throw e;   // a real error, not a bad slug
+        article = null;                           // malformed slug → 404
+      }
+      if (!article) {
+        return _send(res, 404, renderNotFound({
+          what: "help article", shop_name: shopName, cart_count: cartCount, theme_css: _helpThemeCss(),
+          canonical_url: urls.canonical_url, og_url: urls.og_url,
+        }));
+      }
+      // Record the view (best-effort, drop-silent — analytics, never blocks
+      // the render). A session id keys the per-session view namespace; absent
+      // one the view still counts (session_id is optional on recordView).
+      try {
+        var sid = _readSidCookie(req);
+        await kb.recordView(sid ? { slug: article.slug, session_id: sid } : { slug: article.slug });
+      } catch (_e) { /* drop-silent — view tracking never breaks the page */ }
+      _send(res, 200, renderHelpArticle({
+        article: article, shop_name: shopName, cart_count: cartCount, theme_css: _helpThemeCss(),
+        canonical_url: urls.canonical_url, og_url: urls.og_url,
+      }));
+    });
+
+    // Record a helpfulness vote. CSRF-safe via the per-request double-submit
+    // token `_wrap` injects into the form (the action is a container path,
+    // never an EDGE_POST_PATHS prefix, so it IS tokened + checked). The vote
+    // dedups per (slug, session) at the primitive's UNIQUE; a browser with no
+    // session cookie yet gets one minted here so the dedup has a key. A bad
+    // slug / unpublished article / bad vote value all degrade to a clean
+    // response, never a 500.
+    router.post("/help/:slug/vote", async function (req, res) {
+      var slug = (req.params && req.params.slug) || "";
+      var urls = _requestUrls(req);
+      var cartCount = 0;
+      try { cartCount = await _cartCountForReq(req); } catch (_e) { cartCount = 0; }
+      var body = req.body || {};
+      var vote = (typeof body.vote === "string") ? body.vote : "";
+
+      var article = null;
+      try { article = await _kbPublishedArticle(slug); }
+      catch (e) { if (!(e instanceof TypeError)) throw e; article = null; }
+      if (!article) {
+        return _send(res, 404, renderNotFound({
+          what: "help article", shop_name: shopName, cart_count: cartCount, theme_css: _helpThemeCss(),
+          canonical_url: urls.canonical_url, og_url: urls.og_url,
+        }));
+      }
+
+      // A session id keys the vote dedup. Mint + set one when the browser
+      // has none yet (a uuid v7 matches the session-id cookie shape), so a
+      // first-time voter still records exactly one distinct-session vote.
+      var sid = _readSidCookie(req);
+      if (!sid) { sid = b.uuid.v7(); _setSidCookie(req, res, sid); }
+
+      // Record the vote. An invalid vote value (neither helpful nor
+      // not_helpful) re-renders the article with the buttons (the primitive
+      // throws a TypeError); a duplicate vote collapses to a no-op at the
+      // UNIQUE. Either way the voter sees the thank-you confirmation — the
+      // page never leaks an error or a stack.
+      try {
+        await kb.recordVote({ slug: article.slug, session_id: sid, vote: vote });
+      } catch (e) {
+        if (!(e instanceof TypeError)) throw e;
+        return _send(res, 200, renderHelpArticle({
+          article: article, shop_name: shopName, cart_count: cartCount, theme_css: _helpThemeCss(),
+          canonical_url: urls.canonical_url, og_url: urls.og_url,
+        }));
+      }
+      _send(res, 200, renderHelpArticle({
+        article: article, voted: true, shop_name: shopName, cart_count: cartCount, theme_css: _helpThemeCss(),
+        canonical_url: urls.canonical_url, og_url: urls.og_url,
+      }));
+    });
+  }
+
   // Persist a locale choice. A GET form (works with JS off) from the
   // footer switcher submits `lang` (the chosen tag) + `to` (the path to
   // return to). We validate the tag against the active locale set, set

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.3.30",
+  "version": "0.3.31",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {