@stacklist-app/brandkit 1.2.3 → 1.3.0

package/README.md

@@ -32,6 +32,7 @@ npx brandkit build brand       # bake into static files for production
 | `brandkit dev [dir]` | Local dev server on `:4800` with SSE live reload |
 | `brandkit build [dir]` | Produce static `index.html` + `styles.css` + `engine.js` (theme baked in) **plus** the agent-native exports below |
 | `brandkit export [dir]` | Emit just the agent-native brand data (`--format json\|dtcg\|md\|all`, `--out <dir>`) |
+| `brandkit changelog "<msg>" [dir]` | Record a revision: prepend a changelog entry and bump `brand.version` (`--lock`, `--major`, `--version X.Y`, `--date`, `--dir`) |
 
 ## Agent-readable brand data
 
@@ -47,6 +48,22 @@ And for a person who wants to hand the guide to their own agent, the sidebar sho
 
 A JSON Schema for `config.json` ships at [`config.schema.json`](config.schema.json) — point your editor's `$schema` at it for validation and autocomplete.
 
+## Changelog
+
+A brand guide evolves, so brandkit keeps a history of its revisions. Record one with:
+
+```bash
+npx brandkit changelog "Swapped the accent to teal, refreshed the logo"
+```
+
+This prepends a `{ version, date, changes }` entry to `config.changelog` and bumps `brand.version`. A fresh guide starts at **0.1** and climbs with each change (`0.1 → 0.2 → …`); finalize the brand at **1.0** with `--lock`:
+
+```bash
+npx brandkit changelog --lock "Brand finalized"
+```
+
+The history renders on a standalone **`changelog.html`** page (linked from the bottom of the sidebar) and is included in `brand.json` / `brand.md` so agents see it too. `init` also scaffolds an **`AGENTS.md`** into the guide directory — a maintenance contract telling an AI agent the source of truth, to read from the exports, and to record changes with `brandkit changelog`.
+
 ## Framework integrations
 
 Serve the brand guide at `/brand` in your existing dev server and bundle it on build.
@@ -73,10 +90,26 @@ export default {
 
 **Next.js / plain HTML**: run `brandkit build brand` and serve the resulting directory as a static route.
 
+### Serving from a base path
+
+brandkit emits page-relative paths, which resolve only when the guide is served from the root or a **trailing-slash** directory URL (`/brand/`). If you serve it at `/brand` with **no** trailing slash — e.g. a Next.js rewrite that maps `/brand` to the built `/brand/index.html` — every relative path resolves against `/` instead, so `styles.css`, `engine.js`, and `config.json` all 404 and the guide renders an empty shell.
+
+Set `basePath` in `config.json` to fix this:
+
+```json
+{
+  "basePath": "/brand",
+  "brand": { "name": "Acme" }
+}
+```
+
+On `brandkit build`, the generated `index.html` then points its stylesheet, engine, and `brand.json` link at `${basePath}/…`, and the engine fetches `${basePath}/config.json` — so the guide loads fully whether or not the serving URL has a trailing slash. The value is normalized (leading slash added, trailing slash stripped). Omitting `basePath` keeps the original page-relative behavior, so existing setups are unaffected.
+
 ## Config
 
 `config.json` is the single source of truth. Top-level keys:
 
+- `basePath` — absolute path the guide is served from (e.g. `/brand`). Omit (or leave empty) when serving at the root or from a trailing-slash directory URL — output stays page-relative and unchanged. See [Serving from a base path](#serving-from-a-base-path).
 - `brand` — name, tagline, description, version, date; optional `guideLabel` (renames the "Web Style Guide" header/footer label), `headerLogo` and `sidebarLogo` (logo image paths that replace the text wordmark in the header and left menu)
 - `fonts` — display + body with Google Fonts import; each font takes an optional `fallback` web stand-in for brands whose official typeface isn't web-available (the rendered font stack becomes `'family', 'fallback', sans-serif`, while labels keep the clean family name)
 - `theme` — CSS variable map (colors, gradients, font vars)

package/bin/brandkit.js

@@ -19,6 +19,9 @@ switch (command) {
   case 'export':
     require('../cli/export')(args.slice(1));
     break;
+  case 'changelog':
+    require('../cli/changelog')(args.slice(1));
+    break;
   case 'help':
   case '--help':
   case '-h':
@@ -45,6 +48,7 @@ function printHelp() {
   console.log('    brandkit dev [dir]         Start dev server with live reload');
   console.log('    brandkit build [dir]       Build static files for production');
   console.log('    brandkit export [dir]      Emit agent-native brand data (brand.json, tokens.json, brand.md)');
+  console.log('    brandkit changelog "<msg>" Record a revision (bumps version, adds a changelog entry)');
   console.log('');
   console.log('  Options:');
   console.log('    --help, -h     Show this help message');

package/cli/build.js

@@ -28,7 +28,8 @@ module.exports = function build(args) {
   var brandName = (config.brand && config.brand.displayName) || 'Brand';
   console.log('    built   index.html   (' + brandName + ' title + fonts + embedded brand data)');
   console.log('    built   styles.css   (:root variables generated)');
-  console.log('    copied  engine.js');
+  console.log('    built   changelog.html (' + brandName + ' title + fonts)');
+  console.log('    copied  engine.js, changelog.js');
   if (exported && exported.written) {
     exported.written.forEach(function (f) {
       console.log('    wrote   ' + f + '   (agent-native export)');

package/cli/changelog.js

@@ -0,0 +1,172 @@
+var fs = require('fs');
+var path = require('path');
+
+/**
+ * brandkit changelog — record a brand-guide revision.
+ *
+ * Prepends a `{ version, date, changes }` entry to config.changelog (newest
+ * first) and bumps brand.version. A fresh guide starts at 0.1; each call
+ * minor-bumps (0.1 → 0.2 → …); --lock jumps to 1.0 when the brand is finalized.
+ *
+ *   brandkit changelog "Added gradients" "Tuned contrast"
+ *   brandkit changelog --lock "Brand locked"
+ *   brandkit changelog --major "v2 redesign"
+ *   brandkit changelog --version 0.5 "Set explicitly"
+ *   brandkit changelog --dir example "Update the demo"
+ */
+module.exports = function changelog(args) {
+  var opts = parseArgs(args);
+
+  if (opts.help) {
+    printUsage();
+    return;
+  }
+
+  if (opts.error) {
+    console.error('');
+    console.error('  ' + opts.error);
+    console.error('');
+    printUsage();
+    process.exit(1);
+  }
+
+  var targetDir = path.resolve(opts.dir || '.');
+  var configPath = path.join(targetDir, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    console.error('');
+    console.error('  No config.json found in ' + targetDir);
+    console.error('  Run: brandkit init ' + path.relative(process.cwd(), targetDir));
+    console.error('');
+    process.exit(1);
+  }
+
+  // Drop blank/whitespace-only messages so a stray empty arg can't create a
+  // blank bullet (and silently bump the version).
+  opts.messages = opts.messages.filter(function (m) { return String(m).trim() !== ''; });
+  if (!opts.messages.length) {
+    console.error('');
+    console.error('  Nothing to log — pass at least one change message.');
+    console.error('  Example: brandkit changelog "Added the gradient system"');
+    console.error('');
+    process.exit(1);
+  }
+
+  // Reject a malformed explicit --version so junk never lands in brand.version
+  // (which build/template.js consume downstream). The changelog scheme is
+  // strictly MAJOR.MINOR, so a patch (1.2.3) is rejected too — keeping the
+  // regex, the message, and parseVersion's bump logic consistent.
+  if (opts.version && !/^\d+\.\d+$/.test(opts.version)) {
+    console.error('');
+    console.error('  Invalid --version "' + opts.version + '" — expected MAJOR.MINOR (e.g. 0.3 or 1.0).');
+    console.error('');
+    process.exit(1);
+  }
+
+  var config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  config.brand = config.brand || {};
+  if (!Array.isArray(config.changelog)) config.changelog = [];
+
+  var prevVersion = config.brand.version || '0.1';
+
+  // The scheme is MAJOR.MINOR. If the stored version isn't clean (hand-edited,
+  // or a 3-part value like the demo's package version), warn rather than
+  // silently normalizing — the bump uses only its leading major.minor.
+  if (!opts.version && !/^\d+\.\d+$/.test(prevVersion)) {
+    console.error('  Note: brand.version "' + prevVersion +
+      '" is not MAJOR.MINOR — bumping from its leading major.minor.');
+  }
+
+  // --lock finalizes a pre-1.0 brand at 1.0; refuse to move a >=1.0 brand
+  // backward (which would also break the newest-first version ordering).
+  if (opts.lock && parseVersion(prevVersion).major >= 1) {
+    console.error('');
+    console.error('  Already at v' + prevVersion + ' — the brand is locked (>= 1.0).');
+    console.error('  Use --major or --version X.Y to bump further.');
+    console.error('');
+    process.exit(1);
+  }
+
+  var nextVersion = nextVersionFor(prevVersion, opts);
+  var date = opts.date || new Date().toLocaleDateString('en-US', { month: 'long', year: 'numeric' });
+
+  var entry = { version: nextVersion, date: date, changes: opts.messages.slice() };
+  config.changelog.unshift(entry);
+  config.brand.version = nextVersion;
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  console.log('');
+  console.log('  brandkit changelog');
+  console.log('');
+  console.log('  v' + prevVersion + ' → v' + nextVersion + ' · ' + opts.messages.length +
+    ' change' + (opts.messages.length === 1 ? '' : 's') + ' (' + date + ')');
+  opts.messages.forEach(function (m) {
+    console.log('    • ' + m);
+  });
+  console.log('');
+  console.log('  Updated ' + path.relative(process.cwd(), configPath));
+  console.log('  Run `brandkit build` (or `export`) to refresh the deployed page and agent exports.');
+  console.log('');
+};
+
+/**
+ * Decide the next version string from the previous one + flags.
+ *  --version X.Y  → explicit
+ *  --lock         → 1.0
+ *  --major        → next whole major, minor reset to 0
+ *  default        → minor + 1
+ */
+function nextVersionFor(prev, opts) {
+  if (opts.version) return opts.version;
+  if (opts.lock) return '1.0';
+
+  var parsed = parseVersion(prev);
+  if (opts.major) return (parsed.major + 1) + '.0';
+  return parsed.major + '.' + (parsed.minor + 1);
+}
+
+// "0.3" → { major: 0, minor: 3 }; tolerant of junk → { 0, 1 }.
+function parseVersion(v) {
+  var m = String(v == null ? '' : v).match(/^(\d+)\.(\d+)/);
+  if (!m) return { major: 0, minor: 1 };
+  return { major: parseInt(m[1], 10), minor: parseInt(m[2], 10) };
+}
+
+function parseArgs(args) {
+  var opts = { messages: [], dir: '.', lock: false, major: false, version: null, date: null, help: false, error: null };
+  var valueFlags = { '--version': 'version', '--date': 'date', '--dir': 'dir' };
+  for (var i = 0; i < args.length; i++) {
+    var a = args[i];
+    if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--lock') opts.lock = true;
+    else if (a === '--major') opts.major = true;
+    else if (valueFlags[a]) {
+      // A value flag at the end of argv would otherwise read undefined and be
+      // silently ignored — error instead.
+      if (i + 1 >= args.length) { opts.error = a + ' requires a value.'; break; }
+      opts[valueFlags[a]] = args[++i];
+    }
+    // Reject an unknown --flag (e.g. a "--majro" typo) rather than recording it
+    // as a changelog message. Single-dash args pass through so a message can
+    // still start with "-" (e.g. "-20% load time").
+    else if (a.indexOf('--') === 0) { opts.error = 'Unknown option: ' + a; break; }
+    else opts.messages.push(a);
+  }
+  return opts;
+}
+
+function printUsage() {
+  console.log('');
+  console.log('  brandkit changelog — record a brand-guide revision');
+  console.log('');
+  console.log('  Usage:');
+  console.log('    brandkit changelog "<message>" ["<message>" ...]');
+  console.log('');
+  console.log('  Options:');
+  console.log('    --lock           Mark the brand as finalized (version → 1.0)');
+  console.log('    --major          Bump the major version (e.g. 1.4 → 2.0)');
+  console.log('    --version X.Y    Set the version explicitly');
+  console.log('    --date "<text>"  Override the entry date (default: this month)');
+  console.log('    --dir <path>     Target guide directory (default: .)');
+  console.log('');
+}

package/cli/init.js

@@ -2,6 +2,7 @@ var fs = require('fs');
 var path = require('path');
 var resolve = require('../lib/resolve');
 var schema = require('../lib/config-schema');
+var agentsDoc = require('../lib/agents-doc').agentsDoc;
 
 module.exports = function init(args) {
   var targetDir = path.resolve(args[0] || 'brand');
@@ -27,7 +28,7 @@ module.exports = function init(args) {
   var isUpdate = args.indexOf('--update') !== -1;
 
   // Copy engine files from dist/
-  var files = ['engine.js', 'styles.css', 'index.html'];
+  var files = ['engine.js', 'styles.css', 'index.html', 'changelog.html', 'changelog.js'];
   for (var i = 0; i < files.length; i++) {
     var src = path.join(distDir, files[i]);
     var dest = path.join(targetDir, files[i]);
@@ -65,6 +66,16 @@ module.exports = function init(args) {
     console.log('    kept    config.json (already exists)');
   }
 
+  // Maintenance contract for agents/humans working in this dir — written when
+  // absent (so older guides pick it up on --update) and never clobbered.
+  var agentsPath = path.join(targetDir, 'AGENTS.md');
+  if (!fs.existsSync(agentsPath)) {
+    fs.writeFileSync(agentsPath, agentsDoc());
+    console.log('    created AGENTS.md');
+  } else {
+    console.log('    kept    AGENTS.md (already exists)');
+  }
+
   console.log('');
   if (isUpdate) {
     console.log('  Updated engine files. Config and logos preserved.');

package/config.schema.json

@@ -37,6 +37,7 @@
     }
   },
   "properties": {
+    "basePath": { "type": "string", "description": "Absolute base path the guide is served from (e.g. \"/brand\"). Empty = served at root / relative. Set this when serving from a non-trailing-slash URL (e.g. a framework rewrite)." },
     "brand": {
       "type": "object",
       "required": ["name"],
@@ -250,6 +251,18 @@
         "cards": { "type": "array" },
         "stats": { "type": "array" }
       }
+    },
+    "changelog": {
+      "type": "array",
+      "description": "Revision history for the brand guide, newest entry first. Rendered on the standalone changelog.html page and surfaced in the agent exports. Maintain it with `brandkit changelog`. The latest entry's version should match brand.version.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "version": { "type": "string", "description": "Revision label, e.g. '0.2'. Starts at 0.1 on a fresh guide; 1.0 = locked/finalized." },
+          "date": { "type": "string", "description": "Human-readable date, e.g. 'June 2026'." },
+          "changes": { "type": "array", "items": { "type": "string" }, "description": "Bullet list of what changed in this revision." }
+        }
+      }
     }
   }
 }

package/dist/changelog.html

@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Changelog</title>
+<link rel="stylesheet" href="styles.css">
+</head>
+<body>
+
+<div class="changelog-page">
+
+  <!-- Header -->
+  <div class="changelog-header">
+    <a class="changelog-back" href="index.html">&larr; Back to guide</a>
+    <div class="changelog-brand" id="changelog-brand"></div>
+    <h1 class="changelog-title">Changelog</h1>
+    <p class="changelog-lead" id="changelog-lead"></p>
+  </div>
+
+  <!-- Entries -->
+  <div class="changelog-list" id="changelog-list"></div>
+
+  <!-- Footer -->
+  <div class="changelog-footer" id="changelog-footer"></div>
+
+</div>
+
+<!-- Render script -->
+<script src="changelog.js"></script>
+
+</body>
+</html>

package/dist/changelog.js

@@ -0,0 +1,128 @@
+/**
+ * Brandkit Changelog Page
+ * Loads config.json → bootstraps theme → renders the version history.
+ *
+ * A small standalone companion to engine.js: it reuses the same config, the
+ * same theme/font bootstrap, and the same escaping, but renders only the
+ * changelog (cfg.changelog) so the guide can ship a dedicated history page.
+ */
+(function () {
+  // Base path the page is served from. The build injects
+  // window.__BRANDKIT_BASE__ when config.basePath is set (e.g. "/brand"), so a
+  // page served from a non-trailing-slash URL still resolves config.json.
+  var BASE = (typeof window !== 'undefined' && window.__BRANDKIT_BASE__)
+    ? (String(window.__BRANDKIT_BASE__).replace(/\/+$/, '') || '.') : '.';
+
+  fetch(BASE + '/config.json')
+    .then(function (res) { return res.json(); })
+    .then(function (config) { init(config); })
+    .catch(function () { renderError(); });
+
+  /* ================================================================
+     Helpers (kept in sync with dist/engine.js — no module system here)
+     ================================================================ */
+  function esc(s) {
+    return String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  }
+
+  function fontStack(f) {
+    if (!f || !f.family) return 'sans-serif';
+    function q(s) { return String(s).replace(/[\u0000-\u001F\u007F]/g, '').replace(/[\\']/g, '\\$&'); }
+    var stack = "'" + q(f.family) + "'";
+    if (f.fallback) stack += ", '" + q(f.fallback) + "'";
+    return stack + ', sans-serif';
+  }
+
+  /* ================================================================
+     Bootstrap — fonts + theme variables, mirroring engine.js
+     ================================================================ */
+  function bootstrap(cfg) {
+    if (cfg.fonts) {
+      var families = [];
+      if (cfg.fonts.display && cfg.fonts.display.googleImport) families.push(cfg.fonts.display.googleImport);
+      if (cfg.fonts.body && cfg.fonts.body.googleImport) families.push(cfg.fonts.body.googleImport);
+      if (families.length) {
+        var link = document.createElement('link');
+        link.rel = 'stylesheet';
+        link.href = 'https://fonts.googleapis.com/css2?family=' + families.join('&family=') + '&display=swap';
+        document.head.appendChild(link);
+      }
+    }
+
+    if (cfg.theme) {
+      var vars = [];
+      var keys = Object.keys(cfg.theme);
+      for (var i = 0; i < keys.length; i++) {
+        vars.push('  ' + keys[i] + ': ' + cfg.theme[keys[i]] + ';');
+      }
+      if (cfg.fonts) {
+        if (cfg.fonts.display) vars.push('  --font-display: ' + fontStack(cfg.fonts.display) + ';');
+        if (cfg.fonts.body) vars.push('  --font-body: ' + fontStack(cfg.fonts.body) + ';');
+      }
+      var style = document.createElement('style');
+      style.setAttribute('data-brandkit-theme', '');
+      style.textContent = ':root {\n' + vars.join('\n') + '\n}';
+      document.head.appendChild(style);
+    }
+
+    var name = cfg.brand && (cfg.brand.displayName || cfg.brand.name);
+    document.title = (name ? name + ' — ' : '') + 'Changelog';
+  }
+
+  /* ================================================================
+     Render
+     ================================================================ */
+  function init(cfg) {
+    bootstrap(cfg);
+    var brand = cfg.brand || {};
+
+    var brandEl = document.getElementById('changelog-brand');
+    if (brandEl) brandEl.textContent = brand.displayName || brand.name || 'Brand';
+
+    var leadEl = document.getElementById('changelog-lead');
+    if (leadEl) {
+      leadEl.textContent = 'A history of every revision to this brand guide — newest first.';
+    }
+
+    var list = document.getElementById('changelog-list');
+    if (!list) return;
+
+    var entries = cfg.changelog || [];
+    if (!entries.length) {
+      list.innerHTML = '<div class="changelog-empty">No changelog entries yet. ' +
+        'Run <code>brandkit changelog "your update"</code> to add one.</div>';
+      return;
+    }
+
+    list.innerHTML = entries.map(function (entry) {
+      var changes = (entry.changes || []).map(function (c) {
+        return '<li>' + esc(c) + '</li>';
+      }).join('');
+      return (
+        '<div class="changelog-entry">' +
+          '<div class="changelog-entry-head">' +
+            '<span class="changelog-version">v' + esc(entry.version) + '</span>' +
+            (entry.date ? '<span class="changelog-date">' + esc(entry.date) + '</span>' : '') +
+          '</div>' +
+          (changes ? '<ul class="changelog-changes">' + changes + '</ul>' : '') +
+        '</div>'
+      );
+    }).join('');
+
+    var footer = document.getElementById('changelog-footer');
+    if (footer) {
+      var label = brand.guideLabel || 'Web Style Guide';
+      footer.innerHTML = esc((brand.url || '') + (brand.url && brand.byline ? ' · ' : '') + (brand.byline || '')) +
+        '<br>' + esc(label) + (brand.version ? ' v' + esc(brand.version) : '');
+    }
+  }
+
+  function renderError() {
+    var list = document.getElementById('changelog-list');
+    if (list) {
+      list.innerHTML = '<div class="changelog-empty">Could not load config.json. ' +
+        'The changelog page needs to be served over HTTP (not opened from a file).</div>';
+    }
+  }
+})();

package/dist/engine.js

@@ -6,7 +6,13 @@
   /* ================================================================
      0. Load config
      ================================================================ */
-  var res = await fetch('./config.json');
+  // Base path the guide is served from. The build injects
+  // window.__BRANDKIT_BASE__ when config.basePath is set (e.g. "/brand"), so a
+  // guide served from a non-trailing-slash URL still resolves its assets.
+  // Default '.' keeps the original page-relative behavior (dev + root serving).
+  var BASE = (typeof window !== 'undefined' && window.__BRANDKIT_BASE__)
+    ? (String(window.__BRANDKIT_BASE__).replace(/\/+$/, '') || '.') : '.';
+  var res = await fetch(BASE + '/config.json');
   var config = await res.json();
   init(config);
 
@@ -139,7 +145,10 @@
       // Clear any userinfo so basic-auth creds in the page URL don't leak into
       // the copied prompt (a relative path already drops the page query/hash).
       function exportUrl(file) {
-        var u = new URL(file, location.href);
+        // When served from a base path, resolve against it so the prompt
+        // carries the real export URLs (page URL may have no trailing slash).
+        var ref = (BASE && BASE !== '.') ? BASE + '/' + file : file;
+        var u = new URL(ref, location.href);
         u.username = ''; u.password = '';
         return u.href;
       }
@@ -174,6 +183,29 @@
       box.hidden = false;
     }
 
+    /* ==============================================================
+       2c. Render changelog link — pinned to the bottom of the sidebar when
+       a changelog exists, pointing at the standalone changelog.html page.
+       ============================================================== */
+    function renderChangelogLink() {
+      var link = document.getElementById('sidebar-changelog');
+      if (!link) return;
+      if (!cfg.changelog || !cfg.changelog.length) return;
+
+      // Resolve against BASE so the link works when the guide is served from a
+      // non-trailing-slash base path (e.g. /brand → /brand/index.html).
+      var href = (BASE && BASE !== '.') ? BASE + '/changelog.html' : 'changelog.html';
+      link.setAttribute('href', href);
+      link.innerHTML =
+        '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true">' +
+          '<path stroke-linecap="round" stroke-linejoin="round" d="M12 8v4l3 2"/>' +
+          '<circle cx="12" cy="12" r="9"/>' +
+        '</svg>' +
+        '<span class="sidebar-changelog-label">Changelog</span>' +
+        '<span class="sidebar-changelog-version">v' + esc(cfg.brand && cfg.brand.version) + '</span>';
+      link.hidden = false;
+    }
+
     /* ==============================================================
        3. Render colors
        ============================================================== */
@@ -945,6 +977,7 @@
     renderShell();
     renderNav();
     renderAgentCallout();
+    renderChangelogLink();
     renderSectionIntros();
     renderColors();
     renderGradients();

package/dist/index.html

@@ -15,6 +15,7 @@
     <div class="sidebar-brand">brandkit</div>
     <ul class="sidebar-nav" id="nav"></ul>
     <div class="sidebar-agent" id="agent-callout" hidden></div>
+    <a class="sidebar-changelog" id="sidebar-changelog" href="changelog.html" hidden></a>
   </nav>
 
   <!-- Main Content -->

package/dist/styles.css

@@ -94,6 +94,9 @@ body {
   background: var(--white);
   border-right: 1px solid var(--mist);
   z-index: 100;
+  /* Column layout so the changelog link can pin to the bottom (margin-top:auto) */
+  display: flex;
+  flex-direction: column;
 }
 
 .sidebar-brand {
@@ -167,6 +170,34 @@ body {
 .sidebar-agent-btn:active { transform: translateY(1px); }
 .sidebar-agent-btn:focus-visible { outline: 2px solid var(--accent-text); outline-offset: 2px; }
 
+/* Changelog link — pinned to the bottom of the sidebar column */
+/* The author `display:flex` below would override the UA `[hidden]{display:none}`
+   (author beats UA), leaving an empty bordered box when JS hasn't un-hidden it
+   (no changelog, or before the engine runs) — so restore hidden explicitly. */
+.sidebar-changelog[hidden] { display: none; }
+.sidebar-changelog {
+  margin: auto 16px 4px;        /* auto top pushes it to the bottom */
+  padding-top: 16px;
+  border-top: 1px solid var(--mist);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--slate);
+  text-decoration: none;
+  transition: color 150ms ease;
+}
+.sidebar-changelog:hover { color: var(--accent-text); }
+.sidebar-changelog svg { width: 14px; height: 14px; flex: none; }
+.sidebar-changelog-label { flex: 1; }
+.sidebar-changelog-version {
+  font-size: 11px;
+  color: var(--haze);
+  font-variant-numeric: tabular-nums;
+}
+.sidebar-changelog:hover .sidebar-changelog-version { color: var(--slate); }
+
 /* ── Sidebar Grouped Navigation ── */
 .nav-group {
   padding: 20px 24px 6px;
@@ -1097,6 +1128,150 @@ body {
   justify-content: space-between;
 }
 
+/* ── Changelog page (standalone changelog.html) ── */
+.changelog-page {
+  max-width: 760px;
+  margin: 0 auto;
+  padding: 72px 32px 96px;
+}
+
+.changelog-header { margin-bottom: 56px; }
+
+.changelog-back {
+  display: inline-block;
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--slate);
+  text-decoration: none;
+  margin-bottom: 32px;
+  transition: color 150ms ease;
+}
+
+.changelog-back:hover { color: var(--accent-text); }
+
+.changelog-brand {
+  font-family: var(--font-body), sans-serif;
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--slate);
+  margin-bottom: 12px;
+}
+
+.changelog-title {
+  font-family: var(--font-display), sans-serif;
+  font-size: 44px;
+  font-weight: 700;
+  letter-spacing: -0.02em;
+  line-height: 1.1;
+  color: var(--ink);
+  margin: 0 0 12px;
+}
+
+.changelog-lead {
+  font-size: 15px;
+  line-height: 1.7;
+  color: var(--graphite);
+  margin: 0;
+}
+
+/* Each release — a vertical timeline with the version "ticked" on the rail */
+.changelog-list {
+  border-left: 2px solid var(--mist);
+  padding-left: 32px;
+}
+
+.changelog-entry {
+  position: relative;
+  padding-bottom: 40px;
+}
+
+.changelog-entry:last-child { padding-bottom: 0; }
+
+.changelog-entry::before {
+  content: "";
+  position: absolute;
+  left: -41px;
+  top: 6px;
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  background: var(--accent);
+  box-shadow: 0 0 0 4px var(--cloud);
+}
+
+.changelog-entry-head {
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+  margin-bottom: 14px;
+}
+
+.changelog-version {
+  font-family: var(--font-display), sans-serif;
+  font-size: 20px;
+  font-weight: 700;
+  letter-spacing: -0.01em;
+  color: var(--accent-text);
+}
+
+.changelog-date {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--slate);
+}
+
+.changelog-changes {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.changelog-changes li {
+  position: relative;
+  padding-left: 20px;
+  margin-bottom: 8px;
+  font-size: 15px;
+  line-height: 1.6;
+  color: var(--graphite);
+}
+
+.changelog-changes li::before {
+  content: "";
+  position: absolute;
+  left: 2px;
+  top: 9px;
+  width: 5px;
+  height: 5px;
+  border-radius: 50%;
+  background: var(--haze);
+}
+
+.changelog-empty {
+  font-size: 15px;
+  line-height: 1.7;
+  color: var(--slate);
+}
+
+.changelog-empty code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 13px;
+  background: var(--mist);
+  padding: 2px 6px;
+  border-radius: 6px;
+  color: var(--ink);
+}
+
+.changelog-footer {
+  margin-top: 64px;
+  padding-top: 28px;
+  border-top: 1px solid var(--mist);
+  font-size: 12px;
+  line-height: 1.6;
+  color: var(--slate);
+}
+
 /* ── Print ── */
 @media print {
   .sidebar, .copy-format-bar, .toast-container { display: none !important; }
@@ -1113,4 +1288,6 @@ body {
   .card-demo-grid, .dark-card-demo-grid, .a11y-grid { grid-template-columns: 1fr; }
   .voice-grid, .gradient-usage, .wordmark-display, .logo-grid { grid-template-columns: 1fr; }
   .type-row { grid-template-columns: 60px 1fr 140px; }
+  .changelog-page { padding: 48px 22px 64px; }
+  .changelog-title { font-size: 34px; }
 }

package/lib/agents-doc.js

@@ -0,0 +1,63 @@
+/**
+ * The AGENTS.md scaffolded into a brand-guide directory by `brandkit init`.
+ *
+ * It is a maintenance contract for AI agents (and humans) working in the host
+ * project's brand directory: where the source of truth is, how to read the
+ * brand, and — crucially — to record changes in the changelog. It is brand-
+ * agnostic (it points at config.json for specifics), so it never goes stale.
+ */
+function agentsDoc() {
+  return [
+    '# Working on this brand guide (for AI agents)',
+    '',
+    'This directory is a **[brandkit](https://github.com/The-Stack-Lab/brandkit) brand guide**.',
+    '`config.json` is the single source of truth — it drives the rendered guide (`index.html`) and',
+    'the machine-readable exports below.',
+    '',
+    '## Read the brand from the exports, not the page',
+    '',
+    '- `brand.json` — full structured brand: colors (roles + contrast), typography, voice, logos, spacing',
+    '- `tokens.json` — W3C design tokens (DTCG `$type`/`$value`) for code and design tooling',
+    '- `brand.md` — a brief on how to stay on-brand',
+    '',
+    'These are regenerated by `brandkit build` / `brandkit export`. If they look stale, rebuild.',
+    '',
+    '## When you change the brand, record it in the changelog',
+    '',
+    'Whenever you edit the brand — colors, type, logos, voice, spacing, or anything in `config.json` —',
+    'log what changed so the guide keeps an accurate history:',
+    '',
+    '```bash',
+    'npx brandkit changelog "what you changed"   # e.g. "Swapped accent to teal, refreshed the logo"',
+    '```',
+    '',
+    "This prepends an entry to `config.json`'s `changelog` and bumps `brand.version`.",
+    '',
+    '**Versioning:** a new guide starts at **0.1** and climbs with each change (0.1 → 0.2 → …). When',
+    'the brand is finalized, lock it at **1.0**:',
+    '',
+    '```bash',
+    'npx brandkit changelog --lock "Brand finalized"',
+    '```',
+    '',
+    'The changelog renders on its own page (`changelog.html`) and is included in `brand.json` / `brand.md`.',
+    '',
+    '## Commands',
+    '',
+    '```bash',
+    'npx brandkit dev .          # preview at http://localhost:4800 (live reload)',
+    'npx brandkit build .        # build static files + exports for deploy',
+    'npx brandkit export .       # regenerate brand.json / tokens.json / brand.md',
+    'npx brandkit changelog "…"  # record a brand change (see above)',
+    '```',
+    '',
+    '## Rules',
+    '',
+    '- Edit `config.json` — do **not** hand-edit `index.html`, `styles.css`, `engine.js`, or',
+    '  `changelog.html`. They are universal and overwritten on every rebuild.',
+    '- After changing `config.json`: run `brandkit changelog "…"`, then `brandkit build` (or `export`).',
+    ''
+  ].join('\n');
+}
+
+module.exports = { agentsDoc: agentsDoc };

package/lib/config-schema.js

@@ -19,7 +19,10 @@ function starterConfig() {
       description: 'Brandkit turns a single config.json into a complete, living brand guide — colors, typography, logos, voice, and components, all driven by design tokens. This is the default guide; swap the config and assets to make it your own.',
       url: 'github.com/The-Stack-Lab/brandkit',
       byline: 'Open source · MIT',
-      version: '1.0',
+      // A fresh guide starts at 0.1 and climbs as it's built out; lock it at 1.0
+      // when the brand is finalized (`brandkit changelog --lock`). The latest
+      // changelog entry's version mirrors this.
+      version: '0.1',
       date: new Date().toLocaleDateString('en-US', { month: 'long', year: 'numeric' }),
       // Renames the "Web Style Guide" label in the header + footer.
       guideLabel: 'Web Style Guide',
@@ -230,7 +233,17 @@ function starterConfig() {
         { value: '0', label: 'Runtime dependencies' },
         { value: '12', label: 'Sections, rendered from tokens' }
       ]
-    }
+    },
+    // Revision history, newest first — shown on changelog.html and exported for
+    // agents. A fresh guide starts with this single 0.1 entry; add more with
+    // `brandkit changelog "what changed"` as the brand evolves.
+    changelog: [
+      {
+        version: '0.1',
+        date: new Date().toLocaleDateString('en-US', { month: 'long', year: 'numeric' }),
+        changes: ['Initial brand guide scaffolded with brandkit.']
+      }
+    ]
   };
 }
 

package/lib/export.js

@@ -154,6 +154,13 @@ function buildBrandJson(config) {
         pair: (a.fgName || a.fg || '') + ' on ' + (a.bgName || a.bg || ''),
         fg: a.fg, bg: a.bg, ratio: a.ratio, rating: a.rating
       };
+    }),
+    changelog: (config.changelog || []).map(function (e) {
+      return prune({
+        version: e.version || null,
+        date: e.date || null,
+        changes: e.changes || []
+      });
     })
   };
 
@@ -328,6 +335,30 @@ function buildBrandMarkdown(config) {
     }
   }
 
+  // Changelog — emitted unconditionally so an agent reading this brief always
+  // learns the maintenance rule, then the history (if any). brand.md is the
+  // file agents are pointed at to "stay on-brand", so the instruction lives here.
+  L.push(''); L.push('## Changelog');
+  L.push('When you change this brand — colors, type, logos, voice, spacing, or anything in ' +
+    '`config.json` — record it so the guide keeps an accurate history: run ' +
+    '`brandkit changelog "what changed"`. It prepends an entry and bumps the version (a fresh ' +
+    'guide starts at 0.1 and climbs; add `--lock` to finalize the brand at 1.0).');
+  if (config.changelog && config.changelog.length) {
+    L.push(''); L.push('Revision history (newest first):'); L.push('');
+    config.changelog.forEach(function (e) {
+      var head = '- **v' + (e.version || '?') + '**' + (e.date ? ' (' + e.date + ')' : '');
+      var changes = (e.changes || []).filter(Boolean);
+      if (changes.length <= 1) {
+        // Single change reads cleanly inline.
+        L.push(head + (changes.length ? ': ' + changes[0] : ''));
+      } else {
+        // Multiple changes → nested bullets, so each keeps its own punctuation.
+        L.push(head + ':');
+        changes.forEach(function (c) { L.push('  - ' + c); });
+      }
+    });
+  }
+
   L.push('');
   return L.join('\n');
 }

package/lib/template.js

@@ -42,6 +42,32 @@ function generateRootCSS(config) {
   return lines.join('\n');
 }
 
+/**
+ * Escape a string for safe interpolation inside a double-quoted HTML attribute.
+ * A legitimate URL path never contains these chars, so real basePaths pass
+ * through unchanged; a hostile value can't break out of the attribute.
+ */
+function escapeAttr(s) {
+  return String(s).replace(/&/g, '&').replace(/"/g, '"')
+    .replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/**
+ * Normalize config.basePath into an absolute, no-trailing-slash prefix.
+ * "" / undefined / "/" → "" (served at root, page-relative — unchanged).
+ * "brand" or "/brand/" → "/brand".
+ */
+function normalizeBasePath(bp) {
+  if (!bp || typeof bp !== 'string') return '';
+  var s = bp.trim();
+  if (!s) return '';
+  // Exactly one leading slash: collapse "//brand" (a protocol-relative URL —
+  // browsers read it as a cross-origin host) and "brand" alike to "/brand".
+  s = '/' + s.replace(/^\/+/, '');
+  s = s.replace(/\/+$/, '');
+  return s;
+}
+
 /**
  * Generate a Google Fonts <link> tag from config.fonts.
  */
@@ -64,6 +90,11 @@ function generateFontsLink(config) {
  * Writes index.html and styles.css into the target directory.
  */
 function build(distDir, targetDir, config) {
+  // Absolute base path the guide is served from (e.g. "/brand"). Empty = root /
+  // page-relative, in which case nothing below is rewritten (byte-identical to
+  // the pre-basePath output). The "/" + file form (no trailing slash on basePath)
+  // is what lets a framework rewrite like /brand → /brand/index.html resolve.
+  var basePath = normalizeBasePath(config.basePath);
   // Build styles.css: append the config :root AFTER the stylesheet's default
   // tokens so brand overrides win the cascade (styles.css ships a baseline
   // :root; an earlier block would be overridden by it).
@@ -81,15 +112,41 @@ function build(distDir, targetDir, config) {
   var fontsLink = generateFontsLink(config);
   var brandName = (config.brand && config.brand.displayName) || 'Brand';
 
-  // Inject fonts link + a discovery <link> for the structured brand data
-  var headInject = (fontsLink ? fontsLink + '\n' : '') +
-    '<link rel="alternate" type="application/json" href="brand.json" title="Brand data">\n';
-  htmlTemplate = htmlTemplate.replace('</head>', headInject + '</head>');
+  // Inject fonts link + a discovery <link> for the structured brand data.
+  // When a basePath is set, prefix the brandkit-generated refs (stylesheet,
+  // engine, brand.json) so they resolve from a non-trailing-slash URL; also
+  // expose the base to the runtime engine via window.__BRANDKIT_BASE__.
+  // The Google Fonts link and author-supplied logo paths are left untouched.
+  // basePath is author-controlled config, so it's hardened before it lands in
+  // markup, each context with its own escaping:
+  //  - inline <script>: JSON.stringify + "<" → <, so a "</script>" in the
+  //    value can't break out of the script element (JS-string context).
+  //  - href/src attributes: HTML-attribute-escaped (basePathAttr), so a stray
+  //    quote can't break out of the attribute and inject a handler.
+  //  - all .replace() calls below use function replacers, so a "$" in the path
+  //    isn't interpreted as a $-replacement pattern.
+  var basePathLiteral = JSON.stringify(basePath).replace(/</g, '\\u003C');
+  var basePathAttr = escapeAttr(basePath);
+  var brandJsonHref = basePath ? basePathAttr + '/brand.json' : 'brand.json';
+  var headInject = (basePath ? '<script>window.__BRANDKIT_BASE__ = ' + basePathLiteral + ';</script>\n' : '') +
+    (fontsLink ? fontsLink + '\n' : '') +
+    '<link rel="alternate" type="application/json" href="' + brandJsonHref + '" title="Brand data">\n';
+  htmlTemplate = htmlTemplate.replace('</head>', function () { return headInject + '</head>'; });
 
-  // Set title
+  if (basePath) {
+    // Tolerant of quote style / whitespace around "=" so a future reformat of
+    // the template doesn't silently no-op and ship broken (root-relative) refs.
+    htmlTemplate = htmlTemplate
+      .replace(/href\s*=\s*["']styles\.css["']/, function () { return 'href="' + basePathAttr + '/styles.css"'; })
+      .replace(/src\s*=\s*["']engine\.js["']/, function () { return 'src="' + basePathAttr + '/engine.js"'; });
+  }
+
+  // Set title \u2014 escape the brand name so a hostile displayName can't break out
+  // of the <title> element (e.g. "</title><script>\u2026").
+  var brandNameHtml = escapeAttr(brandName);
   htmlTemplate = htmlTemplate.replace(
     '<title>Brand Guide</title>',
-    '<title>' + brandName + ' \u2014 Brand Guide</title>'
+    '<title>' + brandNameHtml + ' \u2014 Brand Guide</title>'
   );
 
   // Embed brand.json inline so an agent that fetches the page gets structured
@@ -104,11 +161,34 @@ function build(distDir, targetDir, config) {
 
   fs.writeFileSync(path.join(targetDir, 'index.html'), htmlTemplate);
 
-  // Copy engine.js as-is
+  // Build the standalone changelog page the same way: inject the base script +
+  // fonts link + title, and (when a basePath is set) prefix its own asset refs
+  // so it resolves them from a non-trailing-slash URL. It renders from
+  // config.json at runtime (like index.html), so no data is embedded here.
+  var changelogTemplate = fs.readFileSync(path.join(distDir, 'changelog.html'), 'utf8');
+  var changelogHead = (basePath ? '<script>window.__BRANDKIT_BASE__ = ' + basePathLiteral + ';</script>\n' : '') +
+    (fontsLink ? fontsLink + '\n' : '');
+  changelogTemplate = changelogTemplate.replace('</head>', function () { return changelogHead + '</head>'; });
+  if (basePath) {
+    changelogTemplate = changelogTemplate
+      .replace(/href\s*=\s*["']styles\.css["']/, function () { return 'href="' + basePathAttr + '/styles.css"'; })
+      .replace(/src\s*=\s*["']changelog\.js["']/, function () { return 'src="' + basePathAttr + '/changelog.js"'; });
+  }
+  changelogTemplate = changelogTemplate.replace(
+    '<title>Changelog</title>',
+    '<title>' + brandNameHtml + ' — Changelog</title>'
+  );
+  fs.writeFileSync(path.join(targetDir, 'changelog.html'), changelogTemplate);
+
+  // Copy engine.js + changelog.js as-is
   fs.copyFileSync(
     path.join(distDir, 'engine.js'),
     path.join(targetDir, 'engine.js')
   );
+  fs.copyFileSync(
+    path.join(distDir, 'changelog.js'),
+    path.join(targetDir, 'changelog.js')
+  );
 
   return exported;
 }
@@ -116,5 +196,6 @@ function build(distDir, targetDir, config) {
 module.exports = {
   generateRootCSS: generateRootCSS,
   generateFontsLink: generateFontsLink,
+  normalizeBasePath: normalizeBasePath,
   build: build
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacklist-app/brandkit",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Config-driven brand guide that bolts onto any website. Zero dependencies.",
   "main": "lib/resolve.js",
   "bin": {