freestruct 0.0.0-stage → 0.9.0

package/engine/seo.js

@@ -0,0 +1,331 @@
+// engine/seo.js - meta/OG/Twitter/JSON-LD injection + late passes (Phase 1.1)
+// Same observable behavior as 0.4.x with one deliberate fix:
+//  - the template's plain <meta name="description"> is now actually injected
+//    for pages without one (it was silently dropped in 0.4.x).
+// Late passes (reading-time / last-modified / lazy-load) are exported here and
+// fed by the orchestrator, 404 pages included (PRD 1.4 consistency).
+
+import fs from 'fs';
+import path from 'path';
+import { hasSeoType } from './scan.js';
+import { pageUrlFor } from './urls.js';
+
+function minifyHtml(html) {
+  // Conservative HTML minifier - removes unnecessary whitespace
+  // Preserves content inside <pre>, <textarea>, <script>, <style> tags
+  let inBlock = false;
+  let result = '';
+  let i = 0;
+  while (i < html.length) {
+    if (html.slice(i, i + 5) === '<pre>') inBlock = true;
+    else if (html.slice(i, i + 10) === '<textarea') inBlock = true;
+    else if (html.slice(i, i + 8) === '<script>') inBlock = true;
+    else if (html.slice(i, i + 7) === '<style>') inBlock = true;
+    else if (html.slice(i, i + 6) === '</pre>') inBlock = false;
+    else if (html.slice(i, i + 11) === '</textarea>') inBlock = false;
+    else if (html.slice(i, i + 9) === '</script>') inBlock = false;
+    else if (html.slice(i, i + 8) === '</style>') inBlock = false;
+
+    if (inBlock) result += html[i];
+    else if (html[i] === '\n' || html[i] === '\r' || html[i] === '\t') { /* skip */ }
+    else result += html[i];
+    i++;
+  }
+  return result
+    .replace(/>\s+</g, '><')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// ---------- injection value escaping ----------
+
+// HTML-attribute escaping for config/page values that land inside
+// content="..." or href="...": a raw " in a site description silently
+// truncates every generated tag (ported from prestruct's escapeHtmlAttr).
+// '&' is deliberately NOT escaped: the battery pins the raw ampersand in
+// canonical attributes as valid HTML, and escaping it would double-encode
+// legit URLs that already contain &amp; from the SSG.
+function escAttr(value) {
+  return String(value == null ? '' : value)
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+// JSON-safe embedding for values that go INSIDE the generated JSON-LD
+// literals (the attribute escaper would put &quot; into invalid JSON).
+// Backslash-escape JSON special characters via JSON.stringify semantics,
+// then render '<' as \u003c so a value can never close the script tag early.
+function escJson(value) {
+  return JSON.stringify(String(value == null ? '' : value)).slice(1, -1).replace(/</g, '\\u003c');
+}
+
+// ---------- per-page overrides ----------
+
+// Per-page override contract (ssr-config.md "Per-Page Options"): an HTML
+// comment in the built page tunes freestruct's own injected tags:
+//   <!-- freestruct: {"title": "My Page", "ogType": "article"} -->
+// Missing-only still wins: a page that already ships its own og/twitter
+// keeps them, and override attempts on that group warn loudly instead of
+// silently doing nothing.
+const PERPAGE_KEYS = Object.freeze([
+  'title', 'description', 'ogType', 'ogImage', 'twitterCard',
+  'publishedTime', 'author', 'section',
+]);
+
+function pageWarn(page, message) {
+  console.log('[freestruct] page warning: ' + page.rel + ': ' + message);
+}
+
+function readPageOverrides(html, page) {
+  const comment = /<!--\s*freestruct:([\s\S]*?)-->/.exec(html);
+  if (!comment) return null;
+  const body = comment[1].slice(comment[1].indexOf('{'), comment[1].lastIndexOf('}') + 1);
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch (e) {
+    pageWarn(page, 'malformed JSON in the freestruct per-page comment (' + e.message + '); ignoring it');
+    return null;
+  }
+  if (Array.isArray(parsed) || !parsed || typeof parsed !== 'object') {
+    pageWarn(page, 'freestruct per-page comment must be a flat {...} object; ignoring it');
+    return null;
+  }
+  const unknown = Object.keys(parsed).filter(k => !PERPAGE_KEYS.includes(k));
+  if (unknown.length > 0) {
+    pageWarn(page, 'unknown per-page key(s) "' + unknown.join('", "') + '" ignored (known: ' + PERPAGE_KEYS.join(', ') + ')');
+  }
+  return parsed;
+}
+
+/**
+ * Inject the SEO pipeline into one page (written to disk).
+ * Missing-only semantics against the PRE-INJECTION snapshot (page.html):
+ * pages that ship their own OG/Twitter/JSON-LD/canonical/description keep them.
+ * Page-level freestruct comments refine the injected tags (see PERPAGE_KEYS).
+ */
+export function injectPage(page, { config, template, buildHash, snippetDir }) {
+  let html = page.html;
+  const siteName = config.site.name;
+  const siteUrl = config.site.url;
+  const overrides = readPageOverrides(html, page);
+
+  let pageTitle = (page.title || siteName) + ' | ' + siteName;
+  let pageDescription = (page.description !== undefined && page.description !== null)
+    ? page.description
+    : config.site.description;
+  let ogType = config.og?.type || 'website';
+  let twitterCard = config.twitter?.card || 'summary';
+  if (overrides) {
+    if (overrides.title !== undefined && overrides.title !== '') pageTitle = String(overrides.title) + ' | ' + siteName;
+    if (overrides.description !== undefined) pageDescription = String(overrides.description);
+    if (overrides.ogType) ogType = String(overrides.ogType);
+    if (overrides.twitterCard) twitterCard = String(overrides.twitterCard);
+  }
+
+  const canonicalUrl = pageUrlFor(config, page.slug)
+    + (config.cacheBusting?.hashInCanonicalUrl === true ? '?v=' + buildHash : '');
+
+  // og image: the per-page comment wins over config; relative values are
+  // joined onto the site url, absolute HTTP(S) values pass through as-is.
+  // No image anywhere: no og:image/twitter:image ship at all (prestruct
+  // parity - a bare image tag pointing at the site root is a broken card).
+  const rawOgImage = (overrides?.ogImage !== undefined && overrides.ogImage !== '')
+    ? String(overrides.ogImage)
+    : config.og?.image || '';
+  const ogImageFull = rawOgImage && !/^(https?:)?\/\//i.test(rawOgImage)
+    ? siteUrl + rawOgImage
+    : rawOgImage;
+
+  // Add cache-busting query param to assets (css, js, images, fonts, ...)
+  if (config.cacheBusting?.assetQueryParam !== false) {
+    const assetExts = '.css.js.png.jpg.jpeg.gif.svg.webp.ico.woff.woff2.ttf.otf.wasm.json';
+    html = html.replace(/(href|src)=\"([^\"]+)\"/gi,
+      (match, attr, url) => {
+        const cleanUrl = url.replace(/\?v=[^"]*/, '');
+        const ext = cleanUrl.substring(cleanUrl.lastIndexOf('.'));
+        if (assetExts.includes(ext)) {
+          return attr + '=\"' + cleanUrl + '?v=' + buildHash + '\"';
+        }
+        return match;
+      });
+  }
+
+  const replacements = {
+    '{{pageTitle}}': escAttr(pageTitle),
+    '{{pageDescription}}': escAttr(pageDescription),
+    '{{pageUrl}}': escAttr(canonicalUrl),
+    '{{canonicalUrl}}': escAttr(canonicalUrl),
+    '{{siteUrl}}': escAttr(siteUrl),
+    '{{siteName}}': escAttr(siteName),
+    '{{siteDescription}}': escAttr(config.site.description),
+    '{{buildHash}}': buildHash,
+    '{{twitterUsername}}': escAttr(config.twitter?.username || ''),
+    '{{twitterCard}}': escAttr(twitterCard),
+    '{{ogImage}}': escAttr(rawOgImage),
+    '{{ogImageFull}}': escAttr(ogImageFull),
+    '{{ogType}}': escAttr(ogType),
+    '{{ogLocale}}': escAttr(config.og?.locale || 'en_US'),
+    // JSON-LD internals: JSON-escaped, not attribute-escaped (see escJson)
+    '{{siteNameJson}}': escJson(siteName),
+    '{{siteUrlJson}}': escJson(siteUrl),
+    '{{siteDescriptionJson}}': escJson(config.site.description),
+    // Conditional schema.org founder for the Organization block (config.author);
+    // expands to '' or a comma-led "founder": {...} fragment.
+    '{{authorJson}}': escJson(config.author?.name)
+      ? ',\n  "founder": { "@type": "Person", "name": "' + escJson(config.author.name) + '"'
+        + (config.author.url ? ', "url": "' + escJson(config.author.url) + '"' : '') + ' }'
+      : '',
+  };
+
+  // Custom JSON-LD hook (config.jsonLd): a single object or an array of
+  // objects appended after the built-in blocks. Ships through the same
+  // missing-only gate as the built-ins, and '<' is neutralized so a value
+  // cannot close the script tag early (same posture as the XML escape-or-fail).
+  let customJsonLd = '';
+  if (config.jsonLd !== undefined) {
+    const blocks = Array.isArray(config.jsonLd) ? config.jsonLd : [config.jsonLd];
+    for (let i = 0; i < blocks.length; i++) {
+      const block = blocks[i];
+      if (!block || typeof block !== 'object' || Array.isArray(block)) {
+        console.log('[freestruct] config warning: jsonLd[' + i + '] is not an object; block skipped');
+        continue;
+      }
+      const serialized = JSON.stringify(block).replace(/</g, '\\u003c');
+      customJsonLd += '\n<script type="application/ld+json">\n' + serialized + '\n</script>\n';
+    }
+  }
+
+  let seo = template;
+  for (const [k, v] of Object.entries(replacements)) seo = seo.split(k).join(v);
+  if (customJsonLd) seo += customJsonLd;
+  // image tags ship only when an og image exists (config-level or per-page)
+  if (!ogImageFull) {
+    seo = seo.replace(/^[^\n]*<meta (property="og:image"|name="twitter:image")[^\n]*>\n?/gim, '');
+  }
+  // Twitter identity tags ship only when a handle is configured: without this
+  // filter the template's {{twitterUsername}} resolves to '' and every page
+  // gets <meta name="twitter:site" content="">. No handle -> no tags; card
+  // type and twitter:title still inject.
+  if (!config.twitter?.username) {
+    seo = seo.replace(/^[^\n]*<meta name="twitter:(site|creator)"[^\n]*>\n?/gim, '');
+  }
+  seo = seo.replace(/<!--[\s\S]*?-->/g, '');
+
+  // Remove existing freestruct-build tag (always refresh)
+  html = html.replace(/<meta[^>]*name="freestruct-build"[^>]*>/gi, '');
+
+  // Only inject SEO if page doesn't have it from SSG/frontmatter
+  const hasOg = hasSeoType(html, 'og');
+  const hasTwitter = hasSeoType(html, 'twitter');
+  const hasJsonLd = hasSeoType(html, 'jsonld');
+  const hasCanonical = hasSeoType(html, 'canonical');
+
+  let seoInjection = '';
+  // FIX (was 0.4.x wart): plain description meta now really reaches bare pages
+  if (!hasSeoType(html, 'description')) {
+    const descMatch = seo.match(/<meta name="description"[^>]*>/i);
+    if (descMatch) seoInjection += '\n' + descMatch[0];
+  }
+  if (!hasOg) {
+    const ogMatch = seo.match(/<meta property="og:[^"]*"[^>]*>/gi);
+    if (ogMatch) seoInjection += '\n' + ogMatch.join('\n');
+    // article:* companions for per-page article facts
+    const articleTags = [];
+    if (overrides?.publishedTime) articleTags.push('<meta property="article:published_time" content="' + escAttr(overrides.publishedTime) + '">');
+    if (overrides?.author) articleTags.push('<meta property="article:author" content="' + escAttr(overrides.author) + '">');
+    if (overrides?.section) articleTags.push('<meta property="article:section" content="' + escAttr(overrides.section) + '">');
+    if (articleTags.length) seoInjection += '\n' + articleTags.join('\n');
+  } else if (overrides && [overrides.ogType, overrides.ogImage, overrides.publishedTime, overrides.author, overrides.section].some(v => v !== undefined)) {
+    pageWarn(page, 'page ships its own Open Graph tags; og/author per-page overrides were not applied');
+  }
+  if (!hasTwitter) {
+    const twMatch = seo.match(/<meta name="twitter:[^"]*"[^>]*>/gi);
+    if (twMatch) seoInjection += '\n' + twMatch.join('\n');
+  } else if (overrides && overrides.twitterCard !== undefined) {
+    pageWarn(page, 'page ships its own Twitter tags; the twitterCard override was not applied');
+  }
+  if (overrides && overrides.description !== undefined && hasSeoType(html, 'description')) {
+    pageWarn(page, 'page has its own description meta; the description override was not applied');
+  }
+  if (!hasJsonLd) {
+    const ldMatch = seo.match(/<script type="application\/ld\+json">[\s\S]*?<\/script>/gi);
+    if (ldMatch) seoInjection += '\n' + ldMatch.join('\n');
+  }
+  if (!hasCanonical) {
+    const canMatch = seo.match(/<link rel="canonical"[^>]*>/);
+    if (canMatch) seoInjection += '\n' + canMatch[0];
+  }
+
+  const versionTag = '<meta name="freestruct-build" content="' + buildHash + '">';
+  // Marker goes FIRST so the entire generated tail (seo block, later snippet
+  // and late-pass insertions land downstream of it) is one strippable region
+  // for computeBuildHash's stable view (scan.js) across reruns.
+  html = html.replace(/<\/head>/i, '<!-- freestruct -->\n' + seoInjection + '\n' + versionTag + '\n</head>');
+
+  // Custom snippet passes: comments stripped, advertised placeholders
+  // ({{siteName}}, {{siteUrl}}, {{buildHash}}, ...) substituted - FIX for
+  // issue #10: 0.4.x advertised placeholder substitution but never did it.
+  function readSnippet(name) {
+    const snippetPath = path.join(snippetDir, name);
+    if (!fs.existsSync(snippetPath)) return null;
+    let snippet = fs.readFileSync(snippetPath, 'utf8');
+    for (const [k, v] of Object.entries(replacements)) snippet = snippet.split(k).join(v);
+    return snippet.replace(/<!--[\s\S]*?-->/g, '');
+  }
+
+  // Custom header injection before </head>
+  const header = readSnippet('inject-header.html');
+  if (header) html = html.replace(/<\/head>/i, header + '\n</head>');
+
+  // Custom body-start injection after <body>
+  const bodyStart = readSnippet('inject-body-start.html');
+  if (bodyStart) html = html.replace(/<body[^>]*>/i, '$&' + bodyStart);
+
+  // Custom footer injection before </body>
+  const footer = readSnippet('inject-footer.html');
+  if (footer) html = html.replace(/<\/body>/i, footer + '\n</body>');
+
+  if (config.minify) html = minifyHtml(html);
+
+  page.html = html;
+  fs.writeFileSync(page.file, html);
+}
+
+/** Reading time (~200 wpm), based on the body word count. */
+export function addReadingTime(filePath) {
+  let html = fs.readFileSync(filePath, 'utf8');
+  html = html.replace(/<meta[^>]*name="reading-time"[^>]*>/gi, '');
+
+  const bodyMatch = html.match(/<body[^>]*>([\s\S]*)<\/body>/i);
+  if (!bodyMatch) return;
+
+  const text = bodyMatch[1].replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+  const words = text.split(/\s+/).filter(w => w.length > 0);
+  const minutes = Math.max(1, Math.ceil(words.length / 200));
+
+  html = html.replace(/<\/head>/i, `<meta name="reading-time" content="${minutes} min read">\n</head>`);
+  fs.writeFileSync(filePath, html);
+}
+
+/** Last-modified ISO timestamp meta. */
+export function addLastModified(filePath) {
+  let html = fs.readFileSync(filePath, 'utf8');
+  html = html.replace(/<meta[^>]*name="last-modified"[^>]*>/gi, '');
+
+  const now = new Date().toISOString();
+  html = html.replace(/<\/head>/i, `<meta name="last-modified" content="${now}">\n</head>`);
+  fs.writeFileSync(filePath, html);
+}
+
+/** Add loading="lazy" to images without it. */
+export function addLazyLoading(filePath) {
+  let html = fs.readFileSync(filePath, 'utf8');
+  html = html.replace(/(<img[^>]*(?<!loading)=)[^>]*>/gi, (match) => {
+    if (match.includes('loading=')) return match;
+    return match.replace(/>$/, ' loading="lazy">');
+  });
+  fs.writeFileSync(filePath, html);
+}

package/engine/urls.js

@@ -0,0 +1,28 @@
+// engine/urls.js - URL construction, basePath semantics (Phase 2)
+// FIX (freestruct issue #3, crashtest-class): 0.4.x stripped basePath from the
+// relative path and concatenated whatever site.url said, silently mapping
+// sub-path installs onto the wrong URLs (404s). The contract now:
+//   canonical = site.url + basePath + relSlug
+//   - basePath unset: canonical = site.url + relSlug (output tree root == site.url)
+//   - basePath set: it is the URL path prefix the output tree is served under.
+//     If the tree ALSO nests that directory, the nested pages win (no doubling).
+
+export function canonicalBase(config) {
+  return config.site.url.replace(/\/$/, '');
+}
+
+// lead-slash only: directory slugs keep their trailing '/' (it is canonical)
+const _norm = s => '/' + String(s).replace(/^\/+/, '');
+
+export function pageUrlFor(config, slug) {
+  const base = canonicalBase(config);
+  const basePath = config.basePath ? _norm(config.basePath) : '';
+  const slugPath = _norm(slug);
+
+  // rel path already carries the deploy directory (e.g. tree nests docs/) -
+  // trust the tree, never double the prefix
+  if (basePath && (slugPath + '/').startsWith(basePath + '/')) {
+    return base + slugPath;
+  }
+  return base + basePath + slugPath;
+}

package/engine/xmllike.js

@@ -0,0 +1,118 @@
+// engine/xmllike.js - escaping + sitemap + robots + RSS (Phase 1.3)
+// THE XML CORRECTNESS CLASS FIX (freestruct issue #9):
+//  - every generated XML value goes through escXml
+//  - sitemap gains a real <lastmod> per page (pre-injection mtime, i.e. the
+//    date the page content last actually changed, not the build time)
+//  - RSS pubDate comes from each page's own mtime, not one shared build stamp
+
+import fs from 'fs';
+import path from 'path';
+import { pageUrlFor } from './urls.js';
+
+/** Escape a value for XML text/attribute contexts. */
+export function escXml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Loud-fail contract (PRD: a value that still produces invalid XML is a build
+ * error, not a bad sitemap): escaping fixables &, <, >, "; characters that
+ * cannot appear in XML at all (control chars) abort the build loudly.
+ */
+export function assertXmlSafe(value, field) {
+  const text = String(value);
+  const bad = text.match(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/);
+  if (bad) {
+    throw new Error('XML safety: value for ' + field + ' contains control character U+'
+      + bad[0].charCodeAt(0).toString(16).padStart(4, '0') + ' which cannot be escaped - refusing to write invalid XML');
+  }
+  return escXml(text);
+}
+
+/** W3C date (YYYY-MM-DD) from a page's own pre-injection mtime. */
+function lastmodFor(page) {
+  return page.mtime.toISOString().slice(0, 10);
+}
+
+/**
+ * Sitemap with real per-page lastmod. Noindex pages are filtered upstream
+ * (owner decision: noindex honored by default, freestruct issue #5).
+ */
+export function generateSitemap(pages, config, outputDir) {
+  let urls = '';
+  for (const page of pages) {
+    urls += '  <url>\n'
+      + '    <loc>' + assertXmlSafe(pageUrlFor(config, page.slug), 'sitemap loc') + '</loc>\n'
+      + '    <lastmod>' + assertXmlSafe(lastmodFor(page), 'sitemap lastmod') + '</lastmod>\n'
+      + '    <changefreq>weekly</changefreq>\n'
+      + '  </url>\n';
+  }
+  const sitemap = '<?xml version="1.0" encoding="UTF-8"?>\n'
+    + '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n'
+    + urls
+    + '</urlset>';
+  fs.writeFileSync(path.join(outputDir, 'sitemap.xml'), sitemap);
+  console.log('sitemap.xml generated');
+}
+
+/**
+ * robots.txt with a sitemap pointer. The pointer is basePath-aware
+ * ('sitemap' artifacts follow the pageUrlFor contract - a raw site.url +
+ * '/sitemap.xml' points at a 404 on sub-path installs, the #3 bug class).
+ */
+export function generateRobots(config, outputDir) {
+  const sitemapUrl = pageUrlFor(config, 'sitemap.xml');
+  const robots = '# Robots.txt\nUser-agent: *\nAllow: /\n\nSitemap: ' + sitemapUrl + '\n';
+  fs.writeFileSync(path.join(outputDir, 'robots.txt'), robots);
+  console.log('robots.txt generated');
+}
+
+/**
+ * RSS with honest per-page pubDate (the date the page last changed, per its
+ * pre-injection mtime). channel.lastBuildDate stays the run stamp.
+ */
+export function generateFeed(pages, config, outputDir) {
+  const siteUrl = pageUrlFor(config, '/');
+  const siteName = config.site.name || 'Site';
+  const description = config.site.description || 'RSS Feed';
+  const feedUrl = pageUrlFor(config, 'feed.xml');
+  const now = new Date().toUTCString();
+
+  let items = '';
+  for (const page of pages) {
+    const html = fs.readFileSync(page.file, 'utf8');
+    const titleMatch = html.match(/<title>([^<]+)<\/title>/i);
+    const descMatch = html.match(/<meta[^>]*name="description"[^>]*content="([^"]+)"/i);
+    const title = titleMatch ? titleMatch[1].split(' | ')[0] : path.basename(page.file, '.html');
+    const desc = descMatch ? descMatch[1] : '';
+    const pageUrl = pageUrlFor(config, page.slug);
+    const pubDate = page.mtime.toUTCString();
+    items += '\n<item>\n'
+      + '  <title>' + assertXmlSafe(title, 'feed title') + '</title>\n'
+      + '  <link>' + assertXmlSafe(pageUrl, 'feed link') + '</link>\n'
+      + '  <description>' + assertXmlSafe(desc, 'feed description') + '</description>\n'
+      + '  <pubDate>' + assertXmlSafe(pubDate, 'feed pubDate') + '</pubDate>\n'
+      + '  <guid>' + assertXmlSafe(pageUrl, 'feed guid') + '</guid>\n'
+      + '</item>';
+  }
+
+  const feed = `<?xml version="1.0" encoding="UTF-8"?>\n`
+    + `<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">\n`
+    + `<channel>\n`
+    + `  <title>${assertXmlSafe(siteName, 'feed channel title')}</title>\n`
+    + `  <link>${assertXmlSafe(siteUrl, 'feed channel link')}</link>\n`
+    + `  <description>${assertXmlSafe(description, 'feed channel description')}</description>\n`
+    + `  <language>en-us</language>\n`
+    + `  <lastBuildDate>${assertXmlSafe(now, 'feed lastBuildDate')}</lastBuildDate>\n`
+    + `  <atom:link href="${assertXmlSafe(feedUrl, 'feed atom link')}" rel="self" type="application/rss+xml"/>\n`
+    + `${items}\n`
+    + `</channel>\n`
+    + `</rss>`;
+
+  fs.writeFileSync(path.join(outputDir, 'feed.xml'), feed);
+  console.log('feed.xml generated');
+}

package/init/README.md

@@ -0,0 +1,48 @@
+# Freestruct init kit
+
+This is the consumer scaffold kit (prestruct's `init/` pattern, sized to
+Freestruct): the minimum a brand-new project copies in to be Freestruct-ready
+in minutes. Freestruct runs AFTER your static site generator builds, so the
+kit is deliberately SSG-agnostic - your Jekyll/Hugo/Docusaurus/MkDocs setup
+stays untouched.
+
+## What's in the kit
+
+```
+init/
+  VERSION                  - the freestruct release this kit is stamped with
+  README.md                - this file
+  docs/
+    freestruct.config.yml  - starter config (site.name + site.url required)
+    _freestruct/           - template copies (synced from engine/_freestruct)
+```
+
+## Start (copy + go)
+
+From YOUR project root:
+
+```bash
+npm install --save-dev freestruct
+cp -r node_modules/freestruct/init/docs .
+```
+
+Then:
+
+1. Edit `docs/freestruct.config.yml`: `site.name` and `site.url` are required;
+   adjust `site.description` to fit.
+2. Let your SSG build. `npx freestruct` discovers the output dir
+   (default `docs/_site`; override via the `outputDir` config key or a
+   positional CLI argument).
+3. Verify: `docs/_site` gains `sitemap.xml`, `robots.txt`, `feed.xml` and
+   (when missing) a `404.html`; injected pages carry canonical/OG tags and a
+   `freestruct-build` marker.
+4. Customize templates only if you need to: the packaged engine templates are
+   used automatically when no staged copy exists. To customize, edit
+   `docs/_freestruct/` copies (which you just copied in) - a staged template
+   always wins over the package-shipped one.
+
+## Why a kit (not a lucky guess)
+
+Copying this kit means your first run exercises the exact shape the test
+battery and the tarball e2e verify: staged config + staged templates next to
+the docs folder, discovered by walking up from your project root.

package/init/VERSION

@@ -0,0 +1 @@
+0.9.0

package/init/docs/_freestruct/inject-body-start.html

@@ -0,0 +1,2 @@
+<!-- Custom body start - injected after <body> -->
+<!-- Placeholders: {{siteName}}, {{siteUrl}} -->

package/init/docs/_freestruct/inject-brand.html

@@ -0,0 +1,49 @@
+<!-- freestruct SEO template - post-build injection -->
+<!-- Placeholders: {{pageTitle}}, {{pageDescription}}, {{pageUrl}}, {{canonicalUrl}} -->
+<!-- Config: {{siteUrl}}, {{siteName}}, {{siteDescription}}, {{twitterUsername}}, {{twitterCard}}, {{ogImage}}, {{ogType}}, {{ogLocale}} -->
+
+<meta name="description" content="{{pageDescription}}">
+<link rel="canonical" href="{{canonicalUrl}}">
+
+<!-- Open Graph -->
+<meta property="og:title" content="{{pageTitle}}">
+<meta property="og:description" content="{{pageDescription}}">
+<meta property="og:url" content="{{pageUrl}}">
+<meta property="og:site_name" content="{{siteName}}">
+<meta property="og:type" content="{{ogType}}">
+<meta property="og:locale" content="{{ogLocale}}">
+<meta property="og:image" content="{{ogImageFull}}">
+
+<!-- Twitter -->
+<meta name="twitter:card" content="{{twitterCard}}">
+<meta name="twitter:title" content="{{pageTitle}}">
+<meta name="twitter:description" content="{{pageDescription}}">
+<meta name="twitter:site" content="{{twitterUsername}}">
+<meta name="twitter:creator" content="{{twitterUsername}}">
+<meta name="twitter:image" content="{{ogImageFull}}">
+
+<!-- JSON-LD -->
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "{{siteNameJson}}",
+  "url": "{{siteUrlJson}}",
+  "description": "{{siteDescriptionJson}}"{{authorJson}}
+}
+</script>
+
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "WebSite",
+  "name": "{{siteNameJson}}",
+  "url": "{{siteUrlJson}}",
+  "potentialAction": {
+    "@type": "SearchAction",
+    "target": "{{siteUrlJson}}/?s={search_term_string}"
+  }
+}
+</script>
+
+<!-- injected by freestruct: https://github.com/dhaupin/freestruct -->

package/init/docs/_freestruct/inject-footer.html

@@ -0,0 +1,13 @@
+<!-- Custom footer - injected into every page before </body> -->
+<!-- Placeholders: {{siteName}}, {{siteUrl}}, {{buildHash}} available -->
+
+<!-- Example: Analytics -->
+<!-- <script defer src="{{siteUrl}}/js/analytics.js"></script> -->
+
+<!-- Example: Community chat -->
+<!-- <script src="https://example.com/chat.js"></script> -->
+
+<!-- Example: Custom feedback widget (placeholders: {{siteName}}, {{siteUrl}}, {{buildHash}}) -->
+<!-- <div id="feedback"><a href="{{siteUrl}}/feedback">Feedback</a></div> -->
+
+<!-- freestruct footer: https://github.com/dhaupin/freestruct -->

package/init/docs/_freestruct/inject-header.html

@@ -0,0 +1,2 @@
+<!-- Custom header - injected before </head> -->
+<!-- Placeholders: {{siteName}}, {{siteUrl}} -->

package/init/docs/freestruct.config.yml

@@ -0,0 +1,14 @@
+# freestruct starter config (part of the init kit).
+# Copy this whole docs/ folder into your project, then fill in site.name and
+# site.url - they are required and everything else has a working default.
+
+site:
+  name: My Docs
+  url: https://example.com/docs
+  description: My documentation
+
+# The rest is optional; see the README Configuration table for the list.
+# basePath: /project-docs      # when the output tree is served under a prefix
+# searchIndex: true            # opt-in: generate search.json
+# outputDir: _site             # your SSG's output folder (relative to docs/)
+# minify: true                 # experimental HTML minifier