feat: add use-cases page with 25 composed workflows

Generate site/use-cases.html from a new forgesworn-use-cases.json source: 25 end-to-end workflows across payments, identity, trust, coordination, and protocol/tooling. Each has a persona, a step-by-step flow, and the building blocks it uses, with stack chips linking back to repos via the catalogue.

Adds tested builder functions and buildUseCasesPage() to build-site.mjs (both pages build from the CLI), a self-contained use-cases template reusing the home design system with a category filter, and a Use Cases nav/hero link. Generated HTML is gitignored and rebuilt in CI.

Author: TheCryptoDonkey

.gitignore

@@ -1,4 +1,6 @@
 node_modules/
 site/index.html
+site/use-cases.html
 forgesworn-repos.json
 .DS_Store
+.playwright-mcp/

README.md

@@ -26,13 +26,24 @@ Current focus areas:
 - Protocol / Standards
 - Tooling / Demos
 
+## Use Cases
+
+The use-cases page (`/use-cases.html`) is generated from
+[forgesworn-use-cases.json](forgesworn-use-cases.json) — 25 end-to-end
+workflows that compose the catalogue libraries, each with a persona, the
+step-by-step flow, and the building blocks it uses. Stack links are resolved
+against `forgesworn-repos.json` at build time, so each block links back to its
+repo. Add or edit workflows in the JSON; no template changes needed.
+
 ## Development
 
 ```sh
-npm run build
+npm run build   # generates site/index.html and site/use-cases.html
 npm test
 ```
 
+Both pages are generated output (gitignored) and are rebuilt in CI on deploy.
+
 ## Licence
 
 MIT. See [LICENCE](LICENCE).

forgesworn-use-cases.json

@@ -278,6 +278,136 @@ export function buildFlowChain(category) {
   return chain.length >= 2 ? chain : null;
 }
 
+// ─── Use-cases page ──────────────────────────────────────────────────────────
+
+const USE_CASE_FALLBACK_COLOUR = '#888';
+
+/**
+ * Build a lookup of repo name -> { github, npm } from the catalogue data so the
+ * use-cases page can link each stack item back to its repo without duplicating URLs.
+ */
+export function buildRepoIndex(catalogueData) {
+  const index = {};
+  for (const cat of catalogueData.categories) {
+    for (const repo of cat.repos) {
+      index[repo.name] = { github: repo.github, npm: repo.npm };
+    }
+  }
+  return index;
+}
+
+/**
+ * Returns { useCases, categories, repos } counts for the use-cases hero.
+ */
+export function computeUseCaseStats(useCasesData) {
+  const repos = new Set();
+  for (const uc of useCasesData.useCases) {
+    for (const item of uc.stack) repos.add(item.repo);
+  }
+  return {
+    useCases: useCasesData.useCases.length,
+    categories: useCasesData.categories.length,
+    repos: repos.size,
+  };
+}
+
+/**
+ * Returns HTML for <!-- USE_CASES_HERO_STATS -->
+ */
+export function buildUseCasesHeroStatsHtml(useCasesData) {
+  const { useCases, categories, repos } = computeUseCaseStats(useCasesData);
+  const stat = (value, label) =>
+    `<div class="stat"><span class="stat-value">${value}</span><span class="stat-label">${label}</span></div>`;
+  return [
+    stat(useCases, 'end-to-end workflows'),
+    stat(categories, 'problem domains'),
+    stat(repos, 'building blocks used'),
+  ].join('\n');
+}
+
+/**
+ * Returns HTML for <!-- USE_CASE_FILTERS -->
+ */
+export function buildUseCaseFiltersHtml(useCasesData) {
+  const counts = {};
+  for (const uc of useCasesData.useCases) {
+    counts[uc.category] = (counts[uc.category] || 0) + 1;
+  }
+  const pill = (slug, label, count, colour) =>
+    `<button class="uc-filter" data-filter="${escHtml(slug)}"${colour ? ` style="--uc-colour: ${colour}"` : ''} type="button">${escHtml(label)} <span class="uc-filter-count">${count}</span></button>`;
+  const all = `<button class="uc-filter is-active" data-filter="all" type="button">All <span class="uc-filter-count">${useCasesData.useCases.length}</span></button>`;
+  const cats = useCasesData.categories
+    .filter(c => counts[c.slug])
+    .map(c => pill(c.slug, c.name, counts[c.slug], c.colour));
+  return [all, ...cats].join('\n');
+}
+
+/**
+ * Build one use-case card.
+ */
+function buildUseCaseCard(uc, colour, repoIndex) {
+  const steps = uc.steps.map(s => `      <li>${escHtml(s)}</li>`).join('\n');
+
+  const stack = uc.stack
+    .map(item => {
+      const meta = repoIndex[item.repo];
+      const inner = `<span class="uc-chip-name">${escHtml(item.repo)}</span><span class="uc-chip-role">${escHtml(item.role)}</span>`;
+      return meta && meta.github
+        ? `      <a class="uc-chip" href="${escHtml(meta.github)}" target="_blank" rel="noopener noreferrer">${inner}</a>`
+        : `      <span class="uc-chip">${inner}</span>`;
+    })
+    .join('\n');
+
+  const protos = (uc.protocols || [])
+    .map(p => `      <span class="uc-proto">${escHtml(p)}</span>`)
+    .join('\n');
+
+  return `<article class="uc-card" data-category="${escHtml(uc.category)}" id="${escHtml(uc.id)}" style="--uc-colour: ${colour}">
+  <div class="uc-card-accent"></div>
+  <span class="uc-persona">${escHtml(uc.persona)}</span>
+  <h3 class="uc-title">${escHtml(uc.title)}</h3>
+  <p class="uc-problem">${escHtml(uc.problem)}</p>
+  <p class="uc-outcome">${escHtml(uc.outcome)}</p>
+  <div class="uc-label">Workflow</div>
+  <ol class="uc-steps">
+${steps}
+  </ol>
+  <div class="uc-label">Built with</div>
+  <div class="uc-stack">
+${stack}
+  </div>
+  <div class="uc-protos">
+${protos}
+  </div>
+</article>`;
+}
+
+/**
+ * Returns HTML for <!-- USE_CASE_SECTIONS -->
+ */
+export function buildUseCaseSectionsHtml(useCasesData, repoIndex = {}) {
+  const byCat = {};
+  for (const uc of useCasesData.useCases) {
+    (byCat[uc.category] = byCat[uc.category] || []).push(uc);
+  }
+  return useCasesData.categories
+    .filter(cat => byCat[cat.slug] && byCat[cat.slug].length)
+    .map(cat => {
+      const colour = cat.colour || USE_CASE_FALLBACK_COLOUR;
+      const cards = byCat[cat.slug].map(uc => buildUseCaseCard(uc, colour, repoIndex)).join('\n');
+      return `<section class="uc-group" data-category="${escHtml(cat.slug)}" style="--uc-colour: ${colour}">
+  <div class="uc-group-head">
+    <span class="section-label" style="color: ${colour}">${escHtml(cat.name)}</span>
+    <p class="uc-group-desc">${escHtml(cat.description)}</p>
+  </div>
+  <div class="uc-grid">
+${cards}
+  </div>
+</section>`;
+    })
+    .join('\n\n');
+}
+
 // ─── Main build function ───────────────────────────────────────────────────────
 
 export async function build(jsonPath) {
@@ -299,10 +429,34 @@ export async function build(jsonPath) {
   console.log(`Built site/index.html -- ${repos} repos, ${stacks} categories, ${npmPackages} npm packages`);
 }
 
+/**
+ * Build site/use-cases.html from the use-cases JSON + the catalogue (for repo links).
+ */
+export async function buildUseCasesPage(catalogueJsonPath, useCasesJsonPath) {
+  const resolvedCatalogue = catalogueJsonPath || join(ROOT, 'forgesworn-repos.json');
+  const resolvedUseCases = useCasesJsonPath || join(ROOT, 'forgesworn-use-cases.json');
+  const templatePath = join(ROOT, 'site', 'use-cases-template.html');
+  const outputPath = join(ROOT, 'site', 'use-cases.html');
+
+  const catalogueData = JSON.parse(readFileSync(resolvedCatalogue, 'utf8'));
+  const useCasesData = JSON.parse(readFileSync(resolvedUseCases, 'utf8'));
+  const repoIndex = buildRepoIndex(catalogueData);
+
+  let template = readFileSync(templatePath, 'utf8');
+  template = template.replace('<!-- USE_CASES_HERO_STATS -->', buildUseCasesHeroStatsHtml(useCasesData));
+  template = template.replace('<!-- USE_CASE_FILTERS -->', buildUseCaseFiltersHtml(useCasesData));
+  template = template.replace('<!-- USE_CASE_SECTIONS -->', buildUseCaseSectionsHtml(useCasesData, repoIndex));
+
+  writeFileSync(outputPath, template, 'utf8');
+
+  const { useCases, categories } = computeUseCaseStats(useCasesData);
+  console.log(`Built site/use-cases.html -- ${useCases} use cases, ${categories} categories`);
+}
+
 // Only run when executed directly (not when imported by tests)
 const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
 if (isMain) {
-  build(process.argv[2]).catch(err => {
+  Promise.all([build(process.argv[2]), buildUseCasesPage()]).catch(err => {
     console.error(err);
     process.exit(1);
   });

scripts/build-site.mjs

@@ -948,6 +948,7 @@
       <button class="nav-toggle" id="navToggle" type="button" aria-label="Toggle navigation" aria-expanded="false">&#9776;</button>
       <ul class="nav-links" id="navLinks">
         <li><a href="#ecosystem">Ecosystem</a></li>
+        <li><a href="/use-cases.html">Use Cases</a></li>
         <li><a href="/forge-realms/">Forge Realms</a></li>
         <li><a href="https://bray.forgesworn.dev">Bray</a></li>
         <li><a href="https://github.com/forgesworn" class="btn-nav">GitHub</a></li>
@@ -965,6 +966,7 @@ <h1>Open-source building blocks for <em>sovereign commerce, identity, and trust<
         </p>
         <div class="hero-actions">
           <a href="#ecosystem" class="btn-primary">Explore the ecosystem</a>
+          <a href="/use-cases.html" class="btn-secondary">See 25 use cases</a>
           <a href="/forge-realms/" class="btn-secondary">Play Forge Realms</a>
           <a href="https://github.com/forgesworn" class="btn-secondary">
             <svg width="18" height="18" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>

site/index.html

@@ -948,6 +948,7 @@
       <button class="nav-toggle" id="navToggle" type="button" aria-label="Toggle navigation" aria-expanded="false">&#9776;</button>
       <ul class="nav-links" id="navLinks">
         <li><a href="#ecosystem">Ecosystem</a></li>
+        <li><a href="/use-cases.html">Use Cases</a></li>
         <li><a href="/forge-realms/">Forge Realms</a></li>
         <li><a href="https://bray.forgesworn.dev">Bray</a></li>
         <li><a href="https://github.com/forgesworn" class="btn-nav">GitHub</a></li>
@@ -965,6 +966,7 @@ <h1>Open-source building blocks for <em>sovereign commerce, identity, and trust<
         </p>
         <div class="hero-actions">
           <a href="#ecosystem" class="btn-primary">Explore the ecosystem</a>
+          <a href="/use-cases.html" class="btn-secondary">See 25 use cases</a>
           <a href="/forge-realms/" class="btn-secondary">Play Forge Realms</a>
           <a href="https://github.com/forgesworn" class="btn-secondary">
             <svg width="18" height="18" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>