bearings 0.3.4 → 0.5.0

package/templates/agents/skills/checklist/previewer/viewer.css

@@ -0,0 +1,93 @@
+:root {
+  color-scheme: light;
+  --ink: #17211f;
+  --muted: #5b6662;
+  --paper: #f1efe7;
+  --card: #fffefa;
+  --line: #d2cec1;
+  --pine: #164b3c;
+  --coral: #c64e32;
+  --gold: #a87013;
+  --danger: #9d3027;
+  --blocked: #684b88;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+* { box-sizing: border-box; }
+body { margin: 0; color: var(--ink); background: var(--paper); }
+button, select, input { font: inherit; }
+button, select { min-height: 40px; border: 1px solid var(--pine); border-radius: 4px; }
+button { padding: 8px 13px; color: var(--pine); background: transparent; font-weight: 750; cursor: pointer; }
+button:hover { color: white; background: var(--pine); }
+button:focus-visible, select:focus-visible, a:focus-visible { outline: 3px solid #e5952f; outline-offset: 3px; }
+
+.masthead { color: white; background: var(--pine); border-bottom: 6px solid var(--coral); }
+.masthead-inner, .toolbar-inner, main, .storage-warning, .status { width: min(1100px, calc(100% - 32px)); margin-inline: auto; }
+.masthead-inner { padding: 34px 0 29px; }
+.eyebrow { margin: 0 0 9px; color: #c7ded6; font: 800 11px/1.2 ui-monospace, monospace; letter-spacing: .13em; text-transform: uppercase; }
+h1 { max-width: 860px; margin: 0; font: 750 clamp(31px, 6vw, 58px)/1.04 Georgia, serif; letter-spacing: -.02em; overflow-wrap: anywhere; }
+.summary { max-width: 780px; margin: 12px 0 0; color: #e0ece8; line-height: 1.55; overflow-wrap: anywhere; }
+
+.toolbar { position: sticky; top: 0; z-index: 5; border-bottom: 1px solid var(--line); background: rgb(241 239 231 / 96%); backdrop-filter: blur(8px); }
+.toolbar-inner { min-height: 70px; display: flex; align-items: center; gap: 10px; }
+.picker-label { color: var(--muted); font: 800 11px/1 ui-monospace, monospace; letter-spacing: .08em; text-transform: uppercase; }
+#checklist-picker { min-width: 230px; max-width: 360px; padding: 8px 30px 8px 10px; color: var(--ink); background: var(--card); }
+.progress { min-width: 180px; flex: 1; display: grid; gap: 5px; color: var(--muted); font-size: 13px; font-weight: 700; }
+.progress-track { height: 7px; overflow: hidden; background: #d9d4c7; border-radius: 99px; }
+#progress-fill { display: block; width: 0; height: 100%; background: var(--pine); transition: width .2s ease; }
+.storage-warning, .status { margin-top: 14px; margin-bottom: 0; }
+.storage-warning { padding: 12px 15px; color: #6a3d00; background: #fff4d8; border: 1px solid #d9af58; }
+.status { min-height: 1.5em; color: var(--muted); font-size: 14px; }
+
+main { padding: 22px 0 80px; }
+.empty, .error { padding: 28px; background: var(--card); border: 1px dashed var(--line); text-align: center; white-space: pre-wrap; }
+.error { color: #751f18; background: #fff0ed; border-color: #d88f86; }
+.intro, .callout, .conventions { max-width: 880px; margin: 0 0 18px; line-height: 1.6; white-space: pre-wrap; overflow-wrap: anywhere; }
+.callout { padding: 17px 19px; background: #fff0e9; border-left: 6px solid var(--coral); }
+.conventions { padding: 17px 19px; background: #e4ede9; border-left: 5px solid var(--pine); }
+section { margin-top: 48px; }
+.section-heading { display: grid; grid-template-columns: auto 1fr; gap: 13px; align-items: baseline; padding-bottom: 11px; border-bottom: 2px solid var(--pine); }
+.section-number { color: var(--coral); font: 850 13px/1 ui-monospace, monospace; }
+h2 { margin: 0; font: 750 clamp(23px, 4vw, 32px)/1.1 Georgia, serif; overflow-wrap: anywhere; }
+.section-intro { max-width: 840px; color: var(--muted); line-height: 1.55; white-space: pre-wrap; }
+.items { display: grid; gap: 15px; margin-top: 20px; }
+.item { padding: 20px; background: var(--card); border: 1px solid var(--line); border-left: 6px solid var(--line); border-radius: 5px; box-shadow: 0 3px 0 rgb(23 33 31 / 5%); overflow-wrap: anywhere; }
+.item[data-state="complete"] { border-left-color: var(--pine); background: #f3faf6; }
+.item[data-state="failed"] { border-left-color: var(--danger); background: #fff5f3; }
+.item[data-state="blocked"] { border-left-color: var(--blocked); background: #f8f4fc; }
+.item[data-state="not-applicable"] { border-left-color: var(--muted); opacity: .76; }
+.item.info { border-left-color: var(--gold); }
+.item-head { display: flex; gap: 13px; justify-content: space-between; align-items: start; }
+.item-heading { min-width: 0; }
+h3, h4 { margin: 0; font-size: 18px; line-height: 1.35; }
+h4 { font-size: 16px; }
+.item-id { margin-right: 9px; color: var(--coral); font: 800 12px/1 ui-monospace, monospace; }
+.optional { display: inline-block; margin-left: 8px; padding: 2px 6px; color: var(--muted); border: 1px solid var(--line); border-radius: 3px; font: 750 10px/1.4 ui-monospace, monospace; text-transform: uppercase; }
+.state-label { flex: 0 0 auto; color: var(--muted); font-size: 12px; font-weight: 750; }
+.state-select { display: block; min-width: 150px; margin-top: 4px; padding: 6px 27px 6px 8px; color: var(--ink); background: white; }
+.instruction { margin: 14px 0 0; line-height: 1.6; white-space: pre-wrap; }
+.warning, .expected, .failure { margin: 15px 0 0; padding: 13px 15px; white-space: pre-wrap; }
+.warning { color: #692c1d; background: #fff0e9; border-left: 4px solid var(--coral); }
+.expected { background: #eaf4ef; border-left: 4px solid var(--pine); }
+.failure { background: #f4edf9; border-left: 4px solid var(--blocked); }
+.field-label { display: block; margin-bottom: 5px; font: 850 10px/1 ui-monospace, monospace; letter-spacing: .1em; text-transform: uppercase; }
+pre { overflow-x: auto; margin: 14px 0 0; padding: 15px; color: #e8f0ed; background: #13211d; border-radius: 4px; }
+pre code { font: 13px/1.55 ui-monospace, SFMono-Regular, Menlo, monospace; white-space: pre; }
+.language { display: block; margin-bottom: 8px; color: #9ebdb2; font: 750 10px/1 ui-monospace, monospace; letter-spacing: .09em; text-transform: uppercase; }
+.links { display: flex; flex-wrap: wrap; gap: 8px 15px; margin: 14px 0 0; padding: 0; list-style: none; }
+a { color: #075f7b; }
+.sub-items { display: grid; gap: 10px; margin-top: 16px; padding-left: 18px; border-left: 2px solid var(--line); }
+.sub-items .item { padding: 15px; box-shadow: none; }
+
+@media (max-width: 760px) {
+  .masthead-inner, .toolbar-inner, main, .storage-warning, .status { width: min(100% - 22px, 1100px); }
+  .toolbar-inner { flex-wrap: wrap; padding: 10px 0; }
+  .picker-label { width: 100%; }
+  #checklist-picker { max-width: none; flex: 1 1 100%; }
+  .progress { flex-basis: 100%; }
+  .item { padding: 16px 14px; }
+  .item-head { display: grid; }
+  .state-label { width: 100%; }
+  .state-select { width: 100%; }
+  section { margin-top: 37px; }
+}

package/templates/agents/skills/checklist/previewer/viewer.js

@@ -0,0 +1,340 @@
+(function () {
+  'use strict';
+
+  var STATES = ['not-started', 'complete', 'failed', 'blocked', 'not-applicable'];
+  var STATE_LABELS = {
+    'not-started': 'Not started',
+    complete: 'Complete',
+    failed: 'Failed',
+    blocked: 'Blocked',
+    'not-applicable': 'Not applicable',
+  };
+  var payload = window.BEARINGS_CHECKLISTS;
+  var currentEntry = null;
+  var currentStates = {};
+  var storageAvailable = true;
+  var refreshPending = false;
+
+  var picker = document.getElementById('checklist-picker');
+  var content = document.getElementById('content');
+  var status = document.getElementById('status');
+  var warning = document.getElementById('storage-warning');
+
+  function element(tag, className, text) {
+    var node = document.createElement(tag);
+    if (className) node.className = className;
+    if (text !== undefined) node.textContent = text;
+    return node;
+  }
+
+  function setStatus(message) {
+    status.textContent = message;
+  }
+
+  function reportStorageFailure() {
+    storageAvailable = false;
+    warning.hidden = false;
+    warning.textContent = 'Browser storage is unavailable. Progress works in this tab only; use Export to keep a copy.';
+  }
+
+  function storageKey(entry) {
+    return 'bearings-checklists:' + payload.repositoryId + ':' + entry.identity;
+  }
+
+  function executableIds(entry) {
+    var ids = [];
+    entry.checklist.sections.forEach(function (section) {
+      if (section.kind === 'info') return;
+      section.items.forEach(function (item) {
+        ids.push(item.id);
+        (item.subItems || []).forEach(function (subItem) { ids.push(subItem.id); });
+      });
+    });
+    return ids;
+  }
+
+  function normalizedStates(entry, candidate) {
+    var states = {};
+    executableIds(entry).forEach(function (id) {
+      if (candidate && STATES.indexOf(candidate[id]) !== -1 && candidate[id] !== 'not-started') {
+        states[id] = candidate[id];
+      }
+    });
+    return states;
+  }
+
+  function loadProgress(entry) {
+    if (!storageAvailable) return {};
+    try {
+      var saved = JSON.parse(localStorage.getItem(storageKey(entry)) || 'null');
+      if (!saved || saved.contentHash !== entry.contentHash) return {};
+      return normalizedStates(entry, saved.states);
+    } catch (error) {
+      reportStorageFailure();
+      return {};
+    }
+  }
+
+  function progressRecord() {
+    return {
+      repositoryId: payload.repositoryId,
+      checklistIdentity: currentEntry.identity,
+      contentHash: currentEntry.contentHash,
+      states: currentStates,
+      updatedAt: new Date().toISOString(),
+    };
+  }
+
+  function saveProgress() {
+    if (!currentEntry || !storageAvailable) return;
+    try {
+      localStorage.setItem(storageKey(currentEntry), JSON.stringify(progressRecord()));
+      setStatus('Progress saved in this browser.');
+    } catch (error) {
+      reportStorageFailure();
+      setStatus('Progress changed, but browser storage could not save it.');
+    }
+  }
+
+  function updateProgress() {
+    var ids = currentEntry ? executableIds(currentEntry) : [];
+    var resolved = ids.filter(function (id) {
+      return currentStates[id] && currentStates[id] !== 'not-started';
+    }).length;
+    document.getElementById('progress-copy').textContent = resolved + ' / ' + ids.length + ' resolved';
+    document.getElementById('progress-fill').style.width = (ids.length ? resolved / ids.length * 100 : 0) + '%';
+  }
+
+  function textBlock(className, label, value) {
+    var block = element('div', className);
+    block.append(element('span', 'field-label', label), document.createTextNode(value));
+    return block;
+  }
+
+  function safeLink(link) {
+    var item = element('li');
+    var anchor = element('a', '', link.label);
+    try {
+      var parsed = new URL(link.url);
+      if (['http:', 'https:', 'mailto:'].indexOf(parsed.protocol) === -1) throw new Error('unsupported protocol');
+      anchor.href = parsed.href;
+      anchor.rel = 'noreferrer';
+      if (parsed.protocol !== 'mailto:') anchor.target = '_blank';
+    } catch (error) {
+      anchor = element('span', '', link.label + ' (unsafe link omitted)');
+    }
+    item.append(anchor);
+    return item;
+  }
+
+  function stateControl(item, article) {
+    var label = element('label', 'state-label', 'State');
+    var select = element('select', 'state-select');
+    select.setAttribute('aria-label', 'State for ' + item.id + ': ' + item.title);
+    STATES.forEach(function (stateName) {
+      var option = element('option', '', STATE_LABELS[stateName]);
+      option.value = stateName;
+      select.append(option);
+    });
+    select.value = currentStates[item.id] || 'not-started';
+    article.dataset.state = select.value;
+    select.addEventListener('change', function () {
+      if (select.value === 'not-started') delete currentStates[item.id];
+      else currentStates[item.id] = select.value;
+      article.dataset.state = select.value;
+      saveProgress();
+      updateProgress();
+    });
+    label.append(select);
+    return label;
+  }
+
+  function renderItem(item, kind, isSubItem) {
+    var article = element('article', 'item' + (kind === 'info' ? ' info' : ''));
+    var head = element('div', 'item-head');
+    var headingWrap = element('div', 'item-heading');
+    var heading = element(isSubItem ? 'h4' : 'h3');
+    heading.append(element('span', 'item-id', item.id), document.createTextNode(item.title));
+    if (item.optional) heading.append(element('span', 'optional', 'Optional'));
+    headingWrap.append(heading);
+    head.append(headingWrap);
+    if (kind === 'checklist') head.append(stateControl(item, article));
+    article.append(head);
+
+    if (item.warning) article.append(textBlock('warning', 'Warning', item.warning));
+    if (item.instruction) article.append(element('p', 'instruction', item.instruction));
+    (item.codeBlocks || []).forEach(function (block) {
+      var pre = element('pre');
+      pre.append(element('span', 'language', block.language), element('code', '', block.content));
+      article.append(pre);
+    });
+    if (item.expectedResult) article.append(textBlock('expected', 'Expected result', item.expectedResult));
+    if (item.failureGuidance) article.append(textBlock('failure', 'If this fails', item.failureGuidance));
+    if (item.links && item.links.length) {
+      var links = element('ul', 'links');
+      item.links.forEach(function (link) { links.append(safeLink(link)); });
+      article.append(links);
+    }
+    if (item.subItems && item.subItems.length) {
+      var subItems = element('div', 'sub-items');
+      item.subItems.forEach(function (subItem) { subItems.append(renderItem(subItem, kind, true)); });
+      article.append(subItems);
+    }
+    return article;
+  }
+
+  function renderChecklist(entry, inMemoryStates) {
+    currentEntry = entry;
+    currentStates = inMemoryStates === undefined ? loadProgress(entry) : normalizedStates(entry, inMemoryStates);
+    var checklist = entry.checklist;
+    document.title = checklist.title + ' - Checklist';
+    document.getElementById('title').textContent = checklist.title;
+    document.getElementById('summary').textContent = checklist.summary;
+    content.className = '';
+    content.replaceChildren();
+    if (checklist.intro) content.append(element('p', 'intro', checklist.intro));
+    if (checklist.callout) content.append(element('div', 'callout', checklist.callout));
+    if (checklist.conventions) content.append(element('div', 'conventions', checklist.conventions));
+
+    checklist.sections.forEach(function (section) {
+      var sectionElement = element('section');
+      var heading = element('div', 'section-heading');
+      heading.append(element('span', 'section-number', section.number), element('h2', '', section.title));
+      sectionElement.append(heading);
+      if (section.intro) sectionElement.append(element('p', 'section-intro', section.intro));
+      var items = element('div', 'items');
+      section.items.forEach(function (item) { items.append(renderItem(item, section.kind, false)); });
+      sectionElement.append(items);
+      content.append(sectionElement);
+    });
+    updateProgress();
+    setStatus('Opened ' + entry.identity + '.');
+  }
+
+  function showMessage(message, isError) {
+    currentEntry = null;
+    currentStates = {};
+    document.title = 'Checklist library';
+    document.getElementById('title').textContent = 'Choose a checklist';
+    document.getElementById('summary').textContent = 'Browse the checklists generated from this repository.';
+    content.className = isError ? 'error' : 'empty';
+    content.textContent = message;
+    updateProgress();
+  }
+
+  function renderLibrary(selectedIdentity) {
+    document.documentElement.dataset.viewerReady = 'false';
+    picker.replaceChildren(element('option', '', payload && payload.checklists.length ? 'Choose a checklist...' : 'No checklists found'));
+    picker.firstChild.value = '';
+    if (!payload || !Array.isArray(payload.checklists)) {
+      showMessage('No generated payload was loaded. Run the checklist build script, then reload this page.', true);
+      document.documentElement.dataset.viewerReady = 'true';
+      return;
+    }
+
+    payload.categories.forEach(function (category) {
+      var group = element('optgroup');
+      group.label = category;
+      payload.checklists.filter(function (entry) { return entry.category === category; }).forEach(function (entry) {
+        var option = element('option', '', entry.checklist.title);
+        option.value = entry.identity;
+        group.append(option);
+      });
+      picker.append(group);
+    });
+    var selected = payload.checklists.find(function (entry) { return entry.identity === selectedIdentity; });
+    if (selected) {
+      picker.value = selected.identity;
+      renderChecklist(selected);
+    } else if (payload.checklists.length === 1) {
+      picker.value = payload.checklists[0].identity;
+      renderChecklist(payload.checklists[0]);
+    } else {
+      showMessage(payload.checklists.length ? 'Choose a checklist from the menu above.' : 'No checklist JSON files were found.');
+    }
+    document.documentElement.dataset.viewerReady = 'true';
+  }
+
+  function exportProgress() {
+    if (!currentEntry) return setStatus('Choose a checklist before exporting progress.');
+    var blob = new Blob([JSON.stringify(progressRecord(), null, 2) + '\n'], { type: 'application/json' });
+    var anchor = document.createElement('a');
+    anchor.href = URL.createObjectURL(blob);
+    anchor.download = currentEntry.identity.replaceAll('/', '-') + '.progress.json';
+    anchor.click();
+    URL.revokeObjectURL(anchor.href);
+    setStatus('Progress export created.');
+  }
+
+  function importProgress(file) {
+    if (!currentEntry || !file) return;
+    var reader = new FileReader();
+    reader.addEventListener('load', function () {
+      try {
+        var imported = JSON.parse(String(reader.result));
+        if (imported.repositoryId !== payload.repositoryId || imported.checklistIdentity !== currentEntry.identity) {
+          throw new Error('This progress file belongs to a different repository or checklist.');
+        }
+        if (imported.contentHash !== currentEntry.contentHash) throw new Error('This progress file is for different checklist content.');
+        currentStates = normalizedStates(currentEntry, imported.states);
+        saveProgress();
+        renderChecklist(currentEntry, currentStates);
+        setStatus('Progress imported.');
+      } catch (error) {
+        setStatus('Progress import failed: ' + error.message);
+      }
+    });
+    reader.addEventListener('error', function () { setStatus('Progress import failed: the file could not be read.'); });
+    reader.readAsText(file);
+  }
+
+  function refreshPayload() {
+    if (refreshPending) return;
+    refreshPending = true;
+    var previousGeneratedAt = payload && payload.generatedAt;
+    var selectedIdentity = currentEntry && currentEntry.identity;
+    var script = document.createElement('script');
+    script.src = './data.generated.js?' + Date.now();
+    script.addEventListener('load', function () {
+      refreshPending = false;
+      var refreshed = window.BEARINGS_CHECKLISTS;
+      if (refreshed && refreshed.generatedAt !== previousGeneratedAt) {
+        payload = refreshed;
+        renderLibrary(selectedIdentity);
+        setStatus('Checklist library refreshed.');
+      }
+      script.remove();
+    });
+    script.addEventListener('error', function () {
+      refreshPending = false;
+      script.remove();
+      setStatus('Could not refresh the generated checklist payload.');
+    });
+    document.head.append(script);
+  }
+
+  picker.addEventListener('change', function () {
+    var selected = payload.checklists.find(function (entry) { return entry.identity === picker.value; });
+    if (selected) renderChecklist(selected);
+    else showMessage('Choose a checklist from the menu above.');
+  });
+  document.getElementById('export-progress').addEventListener('click', exportProgress);
+  document.getElementById('import-progress').addEventListener('click', function () {
+    if (!currentEntry) return setStatus('Choose a checklist before importing progress.');
+    document.getElementById('import-file').click();
+  });
+  document.getElementById('import-file').addEventListener('change', function (event) {
+    importProgress(event.target.files[0]);
+    event.target.value = '';
+  });
+  document.getElementById('reset-progress').addEventListener('click', function () {
+    if (!currentEntry || !window.confirm('Clear progress for this checklist?')) return;
+    currentStates = {};
+    saveProgress();
+    renderChecklist(currentEntry);
+    setStatus('Progress reset.');
+  });
+  window.addEventListener('focus', refreshPayload);
+
+  renderLibrary('');
+}());

package/templates/agents/skills/checklist/schema.reference.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bearings.dev/schemas/checklist.json",
+  "title": "Checklist",
+  "$comment": "validate.mjs is the executable authority and additionally enforces globally unique item and sub-item IDs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["title", "summary", "sections"],
+  "properties": {
+    "title": { "type": "string", "pattern": "\\S" },
+    "summary": { "type": "string", "pattern": "\\S" },
+    "intro": { "type": "string" },
+    "callout": { "type": "string" },
+    "conventions": { "type": "string" },
+    "sections": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/section" }
+    }
+  },
+  "$defs": {
+    "codeBlock": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["language", "content"],
+      "properties": {
+        "language": { "type": "string", "pattern": "\\S" },
+        "content": { "type": "string" }
+      }
+    },
+    "link": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label", "url"],
+      "properties": {
+        "label": { "type": "string", "pattern": "\\S" },
+        "url": { "type": "string", "pattern": "\\S" }
+      }
+    },
+    "subItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title"],
+      "properties": {
+        "id": { "type": "string", "pattern": "\\S" },
+        "title": { "type": "string", "pattern": "\\S" },
+        "instruction": { "type": "string" },
+        "expectedResult": { "type": "string" },
+        "codeBlocks": { "type": "array", "items": { "$ref": "#/$defs/codeBlock" } },
+        "links": { "type": "array", "items": { "$ref": "#/$defs/link" } },
+        "optional": { "type": "boolean" },
+        "warning": { "type": "string" },
+        "failureGuidance": { "type": "string" }
+      }
+    },
+    "item": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title"],
+      "properties": {
+        "id": { "type": "string", "pattern": "\\S" },
+        "title": { "type": "string", "pattern": "\\S" },
+        "instruction": { "type": "string" },
+        "expectedResult": { "type": "string" },
+        "codeBlocks": { "type": "array", "items": { "$ref": "#/$defs/codeBlock" } },
+        "links": { "type": "array", "items": { "$ref": "#/$defs/link" } },
+        "optional": { "type": "boolean" },
+        "warning": { "type": "string" },
+        "failureGuidance": { "type": "string" },
+        "subItems": { "type": "array", "items": { "$ref": "#/$defs/subItem" } }
+      }
+    },
+    "section": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["number", "title", "kind", "items"],
+      "properties": {
+        "number": { "type": "string", "pattern": "\\S" },
+        "title": { "type": "string", "pattern": "\\S" },
+        "kind": { "enum": ["checklist", "info"] },
+        "intro": { "type": "string" },
+        "items": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/item" }
+        }
+      }
+    }
+  }
+}

package/templates/agents/skills/checklist/scripts/build.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { mkdir, readdir, realpath, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { loadAndValidateChecklist } from './validate.mjs';
+
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+async function checklistFiles(root) {
+  const files = [];
+  async function visit(directory) {
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === 'ENOENT' && directory === root) return;
+      throw error;
+    }
+    for (const entry of entries) {
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) await visit(path);
+      else if (entry.isFile() && entry.name.endsWith('.json')) files.push(path);
+    }
+  }
+  await visit(root);
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export async function buildChecklists(repoDir = process.cwd(), outputPath) {
+  const canonicalRepo = await realpath(repoDir);
+  const root = join(canonicalRepo, 'checklists');
+  const files = await checklistFiles(root);
+  const checklists = [];
+  const failures = [];
+
+  for (const path of files) {
+    const source = relative(root, path).split(sep).join('/');
+    const identity = source.slice(0, -'.json'.length);
+    const segments = identity.split('/');
+    if (segments.length < 2 || segments.some((segment) => !SLUG.test(segment))) {
+      failures.push(`${source}: path must be <category>/<slug>.json using lowercase slugs`);
+      continue;
+    }
+    const { checklist, errors } = await loadAndValidateChecklist(path);
+    if (errors.length > 0) {
+      failures.push(...errors.map((error) => `${source}: ${error}`));
+      continue;
+    }
+    const category = segments.slice(0, -1).join('/');
+    checklists.push({
+      identity,
+      category,
+      contentHash: `sha256:${sha256(JSON.stringify(checklist))}`,
+      checklist,
+    });
+  }
+
+  if (failures.length > 0) {
+    throw new Error(`Checklist build failed:\n${failures.map((failure) => `- ${failure}`).join('\n')}`);
+  }
+
+  const payload = {
+    generatedAt: new Date().toISOString(),
+    repositoryId: `sha256:${sha256(canonicalRepo)}`,
+    categories: [...new Set(checklists.map((entry) => entry.category))],
+    checklists,
+  };
+  const serialized = JSON.stringify(payload).replaceAll('<', '\\u003c');
+  const target = outputPath ?? resolve(dirname(fileURLToPath(import.meta.url)), '../previewer/data.generated.js');
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, `// Generated by bearings. Do not edit.\nwindow.BEARINGS_CHECKLISTS = ${serialized};\n`);
+  return payload;
+}
+
+async function main() {
+  const repoDir = process.argv[2] ?? process.cwd();
+  const outputPath = process.argv[3];
+  if (process.argv.length > 4) {
+    console.error('Usage: node build.mjs [repository] [output]');
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const payload = await buildChecklists(repoDir, outputPath);
+    console.log(`Built ${payload.checklists.length} checklist(s).`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main();