freestruct 1.0.0 → 1.2.0

package/engine/inject.js

@@ -8,12 +8,14 @@
 //   notfound.js  404 pipeline
 //   linkcheck.js link validation
 //   search.js    opt-in search.json
-//   hooks.js     purge hooks
+//   hooks.js     purge hooks + postBuild hooks
+//   audit.js     the `freestruct audit` post-build verifier (issue #18)
+//   indexnow.js  IndexNow key emission + submission (issue #19)
 //
 // CLI (Phase 0/2 contract):
 //   --version   print the package.json version and exit 0 (works configless;
 //               resolved one level up: engine/ is the package root's sibling dir)
-//   validate | init [dir] | help   subcommands (see the helpers below)
+//   validate | init [dir] | audit [--json] [--external] [outputDir] | help  subcommands
 //   --strict    opt-in: broken internal links exit 1 instead of
 //               shipping green
 //   --tolerant  opt-out for CI tolerance: fatal config errors log and exit 0
@@ -22,6 +24,7 @@
 //
 // FAST_FAIL exit codes (PRD Phase 2, config-first diagnostics):
 //   0 success | 1 config fatal | 2 template missing | 3 output dir missing
+//   4 postBuild hook failure (issue #21: nonzero hook exits fail the build)
 //
 // Root resolution (Phase 1.2): the config is discovered by walking UP from
 // the cwd; templates/snippets resolve next to the config file; the output
@@ -32,13 +35,17 @@ import path from 'path';
 import { pathToFileURL, fileURLToPath } from 'url';
 
 import { loadConfig } from './config.js';
-import { getHtmlFiles, buildPages, computeBuildHash, htmlIsNoindex } from './scan.js';
-import { injectPage, addReadingTime, addLastModified, addLazyLoading } from './seo.js';
+import { getHtmlFiles, buildPages, computeBuildHash, htmlIsNoindex, hasSeoType, dedupeBySlug } from './scan.js';
+import { injectPage, addReadingTime, addLastModified, addLazyLoading, addTableWrap } from './seo.js';
 import { generateSitemap, generateRobots, generateFeed } from './xmllike.js';
 import { generate404, pipeline404 } from './notfound.js';
 import { checkLinks } from './linkcheck.js';
 import { generateSearchIndex } from './search.js';
-import { runPurgeHooks } from './hooks.js';
+import { generateLlms } from './llms.js';
+import { runPurgeHooks, runPostBuildHooks } from './hooks.js';
+import { auditOutput, auditExternalLinks } from './audit.js';
+import { resolveIndexNowKey, emitIndexNowKeyFile, submitIndexNow, isValidIndexNowKey } from './indexnow.js';
+import { resolveOgImageGeneration, renderPageOgImage } from './ogimage.js';
 
 const FLAG_VALUES = new Set(['--version', '--strict', '--tolerant']);
 const _argv = process.argv.slice(2);
@@ -46,14 +53,43 @@ const _flags = _argv.filter(a => FLAG_VALUES.has(a));
 // Subcommands before the positional output-dir: the first bare word decides
 // what the run is (validate/init/help mirror prestruct's command surface);
 // any other bare word stays the outputDir override it always was.
-const COMMANDS = new Set(['validate', 'init', 'help']);
+const COMMANDS = new Set(['validate', 'init', 'help', 'audit', 'indexnow']);
 const _firstArg = _argv.find(a => !a.startsWith('--'));
-const _positional = _firstArg && !COMMANDS.has(_firstArg) ? _firstArg : undefined;
+// Args that follow a subcommand word (`_argv` minus the command itself).
+const afterCommand = (name) => _argv.slice(_argv.indexOf(name) + 1);
+
+// Pass 26.16 + 26.44: dash-shaped args are FLAGS, never output dirs, and each
+// command's flag/positional surface is CLOSED. An unknown flag or a surplus
+// positional is a typo, refused with the supported set instead of silently
+// ignored - before this, `init --bogus` scaffolded into a directory literally
+// named `--bogus`, `init a b c` dropped `b`/`c`, `audit -x` rode as an output
+// dir (exit 3, "not found") and `validate --bogus` ran as if clean.
+const GLOBAL_FLAGS = ['-h', '--help', '--version', '--strict', '--tolerant'];
+function parseArgs(args, { command, flags = [], maxPositionals = 0 }) {
+  const allowed = new Set([...GLOBAL_FLAGS, ...flags]);
+  const seen = new Set();
+  const positionals = [];
+  for (const a of args) {
+    if (a.startsWith('-')) {
+      if (!allowed.has(a)) {
+        fail(command + ': unknown flag ' + a + ' - run freestruct --help for the flag list (supported: ' + (flags.length ? flags.join(' ') : 'none') + ')');
+      }
+      seen.add(a);
+    } else {
+      positionals.push(a);
+    }
+  }
+  if (positionals.length > maxPositionals) {
+    fail(command + ': too many arguments (got ' + positionals.length + ', expected at most ' + maxPositionals + ')');
+  }
+  return { positionals, flags: seen };
+}
 
 export const EXIT_OK = 0;
 export const EXIT_CONFIG = 1;
 export const EXIT_TEMPLATE = 2;
 export const EXIT_OUTPUT = 3;
+export const EXIT_HOOK = 4;
 
 function fail(message, code = EXIT_CONFIG) {
   console.error('[freestruct] ' + message);
@@ -84,10 +120,23 @@ freestruct -- post-build SEO layer for static doc sites
   freestruct init [dir]     Scaffold the consumer kit (starter config +
                             template copies) into <dir>/docs; the default dir
                             is the cwd. Existing files are never clobbered.
+  freestruct audit [--json] [--external] [outputDir]
+                            Verify the BAKED output (per-page head hygiene +
+                            sitemap/robots/404-noindex contract) without
+                            touching it; exit 0 clean / 1 findings. Works
+                            against any SSG's build (issue #18). --external
+                            also HEAD-checks up to 50 unique external hrefs
+                            (warn-grade; needs a live network).
+  freestruct indexnow [--dry-run] [outputDir]
+                            POST the baked sitemap URL list to api.indexnow.
+                            org (Bing/Seznam/Yandex). POST-deploy step: the
+                            key file emitted during the run must be live.
+                            --dry-run prints the request body for CI.
   freestruct help (--help)  This text.
 
 Flags: --version | --strict | --tolerant
 Exit codes: 0 ok | 1 config fatal | 2 template missing | 3 output dir missing
+            | 4 hook failure | 1 audit findings (audit subcommand)
 `;
 
 function printHelp() {
@@ -100,6 +149,7 @@ function printHelp() {
  * exits EXIT_CONFIG, honoring --tolerant like every other fatal.
  */
 function cmdValidate() {
+  parseArgs(afterCommand('validate'), { command: 'validate' });
   let loaded;
   try {
     loaded = loadConfig(process.cwd());
@@ -116,7 +166,9 @@ function cmdValidate() {
  * clobbering an existing file. Mirrors the manual `cp -r node_modules/
  * freestruct/init/docs .` shape the init kit README describes.
  */
-function cmdInit(dirArg) {
+function cmdInit() {
+  const { positionals } = parseArgs(afterCommand('init'), { command: 'init', maxPositionals: 1 });
+  const dirArg = positionals[0];
   const targetRoot = path.resolve(process.cwd(), dirArg || '.');
   const docsDir = path.join(targetRoot, 'docs');
   // engine/inject.js -> package root -> init/docs (files list ships init/)
@@ -145,6 +197,17 @@ function cmdInit(dirArg) {
 const STRICT = _flags.includes('--strict');
 
 export function runInject(options = {}) {
+  // Subcommand exclusivity: validate/init/help/audit/indexnow dispatch and
+  // exit during the module body - the full pass must never run alongside
+  // them (with --external the only path that lives past the import, this
+  // guard is what keeps the engine from re-injecting mid-audit).
+  if (_firstArg && COMMANDS.has(_firstArg)) return;
+  // The default run's own closed surface (Pass 26.44): flags are the three
+  // run-shaping ones, and at most ONE positional (the output-dir override).
+  // An unknown flag or a surplus positional is refused with the usage hint
+  // instead of riding as a directory (Pass 26.16's typo class, closed).
+  const { positionals: defaultPositionals } = parseArgs(_argv, { command: 'freestruct', flags: ['--strict', '--tolerant'], maxPositionals: 1 });
+  const _positional = defaultPositionals[0];
   const cwd = options.cwd || process.cwd();
   console.log('freestruct: Loading config...');
 
@@ -161,7 +224,29 @@ export function runInject(options = {}) {
     ? path.resolve(cwd, _positional)
     : path.resolve(configDir, config.outputDir || '_site');
 
+  // File-at-path hardening (Pass 26.13): the existence check alone let an
+  // outputDir pointing at a FILE through, and the tree walk crashed with an
+  // uncaught ENOTDIR stack - fatal errors need a named cause + exit code.
   if (!fs.existsSync(outputDir)) fail('Output directory not found: ' + outputDir, EXIT_OUTPUT);
+  else if (!fs.statSync(outputDir).isDirectory()) fail('Output directory is not a directory: ' + outputDir, EXIT_OUTPUT);
+  // Source-tree hardening (Pass 26.15, tightened after CI): the outputDir
+  // positional accepts any directory, and pointing it at an SSG SOURCE tree
+  // (this repo's docs/, today - committed template copies and layout HTML
+  // injected in place) poisons files silently. Sentinels are ONLY staging
+  // dirs: Jekyll never exports underscore dirs into _site, but it DOES copy
+  // bare files like the config into it (CI hit the over-fire), so config
+  // files are not evidence. Staging dirs inside a built tree mean the
+  // caller aimed at source: abort loudly with the fix spelled out.
+  const sourceMarkers = [
+    ['_layouts', '_layouts/ staging'],
+    ['_freestruct', 'template staging'],
+  ];
+  for (const [marker, meaning] of sourceMarkers) {
+    if (fs.existsSync(path.join(outputDir, marker))) {
+      fail('Refusing to inject: ' + outputDir + ' looks like an SSG source tree (' + meaning +
+        ' found inside). Point freestruct at the BUILT output instead (e.g. docs/_site).', EXIT_OUTPUT);
+    }
+  }
   // Template resolution: user-staged first (docs/_freestruct next to the
   // config), then the PACKAGE-shipped copy (npm install ships engine/_freestruct
   // - repo-shaped runs always hit the staged one, fresh-machine installs fall
@@ -179,6 +264,22 @@ export function runInject(options = {}) {
   if (!fs.existsSync(templatePath)) {
     fail('Template not found: ' + templatePath + ' (shipped copy also missing at ' + packageTemplateDir + ')', EXIT_TEMPLATE);
   }
+  // Template-shape warning (issue #46): a STAGED inject-brand.html REPLACES
+  // the packaged default outright (it is the whole head template, not a
+  // per-slot merge), so a partial file silently drops every slot it does not
+  // list - the packaged default carries canonical + the full og/twitter set +
+  // identity JSON-LD, and a host that stages "just the layer the layout lacks"
+  // loses the rest on EVERY page. Name the core slots a staged template omits.
+  const stagedTemplatePath = path.join(configDir, '_freestruct', 'inject-brand.html');
+  if (fs.existsSync(stagedTemplatePath)) {
+    const stagedTemplate = fs.readFileSync(stagedTemplatePath, 'utf8');
+    const CORE_SLOTS = ['{{canonicalUrl}}', '{{pageTitle}}'];
+    const missingSlots = CORE_SLOTS.filter(k => !stagedTemplate.includes(k));
+    if (missingSlots.length) {
+      console.log('[freestruct] config warning: staged docs/_freestruct/inject-brand.html REPLACES the packaged head template (it is not merged per slot) and omits '
+        + missingSlots.join(', ') + ' - those head slots ship missing on every page. Carry the full default set, or delete the file to use the packaged template.');
+    }
+  }
   const template = fs.readFileSync(templatePath, 'utf8');
 
   const htmlFiles = getHtmlFiles(outputDir);
@@ -195,20 +296,45 @@ export function runInject(options = {}) {
     const pages = pagesForHash;
     const sitePages = pages.filter(p => !p.is404);
 
-    // SEO pipeline over every regular page
-    const injectCtx = { config, template, buildHash, snippetDir };
+    // Per-page OG image generation (issue #22) runs BEFORE injection so the
+    // SEO pipeline can wire the fresh PNGs into og/twitter (missing-only:
+    // pages with their own og:image or a per-page override keep theirs).
+    const generation = resolveOgImageGeneration(config, configDir);
+    const generatedImages = {};
+    if (generation) {
+      for (const page of sitePages) {
+        // Noindex pages are excluded from all artifacts (issue #5 posture):
+        // a robots-blocked page needs no share preview.
+        if (htmlIsNoindex(page.html)) continue;
+        // Pages that ship their own og:image keep theirs (missing-only,
+        // the pitch's own rule); a per-page ogImage override also wins
+        // because the seo seam resolves overrides before generation.
+        if (hasSeoType(page.html, 'og')) continue;
+        const rendered = renderPageOgImage(generation, page, config, outputDir);
+        if (rendered) generatedImages[page.slug] = rendered;
+      }
+    }
+
+    // SEO pipeline over every regular page. The injectWarnings array is the
+    // shuttle for per-page image-policy offenses (issue #20): report-only by
+    // default, graduated to build failures by the --strict block below.
+    const injectCtx = { config, template, buildHash, snippetDir, injectWarnings: [], generatedImages };
     for (const page of sitePages) injectPage(page, injectCtx);
 
     // 404 pipeline: generated when absent, user-supplied folded into the
     // same full treatment (Phase 1.4). Runs after regular pages so a 404
-    // already present in the tree is not double-processed above.
+    // already present in the tree is not double-processed above. EVERY 404
+    // file gets the treatment: a tree carrying both 404.html and 404.htm (a
+    // valid pair on hosts that serve either) had only the FIRST processed, so
+    // the second shipped with no noindex meta and the audit failed the run's
+    // own output.
     const processed404s = [];
     if (config.generate404 !== false) {
-      let page404 = pages.find(p => p.is404);
-      if (!page404) {
+      const found404s = pages.filter(p => p.is404);
+      if (found404s.length === 0) {
         const file404 = generate404(config, outputDir, buildHash, template, snippetDir);
         const html404 = fs.readFileSync(file404, 'utf8');
-        page404 = {
+        found404s.push({
           file: file404,
           rel: '404.html',
           slug: '/404',
@@ -217,9 +343,9 @@ export function runInject(options = {}) {
           mtime: new Date(),
           title: html404.match(/<title>([^<]+)<\/title>/i)?.[1]?.split(' | ')[0] || null,
           description: html404.match(/<meta name="description" content="([^"]+)"/i)?.[1] || null,
-        };
+        });
       }
-      processed404s.push(pipeline404(page404, injectCtx));
+      for (const page404 of found404s) processed404s.push(pipeline404(page404, injectCtx));
     }
 
     // Late passes over every processed page, 404s included (Phase 1.4)
@@ -227,32 +353,70 @@ export function runInject(options = {}) {
     if (config.readingTime !== false) for (const page of latePages) addReadingTime(page.file);
     if (config.lastModified !== false) for (const page of latePages) addLastModified(page.file);
     if (config.lazyLoad !== false) for (const page of latePages) addLazyLoading(page.file);
+    // table guard (issue #35): wrap wide tables so every downstream site is
+    // mobile-safe by construction. Default-on; `tableWrap: false` opts out.
+    if (config.tableWrap !== false) for (const page of latePages) addTableWrap(page.file);
+
+    // Restore each page's pre-injection mtime after our writes. freestruct
+    // rewrites every page it decorates, so without this the NEXT run's
+    // buildPages snapshot captures freestruct's own write as the page mtime -
+    // and feed pubDate / sitemap lastmod (both derived from that mtime, the
+    // issue #9 honest-date contract: "the date the page last actually
+    // changed, not the build time") churned on every rerun with no content
+    // change. Restoring makes the dates stable across reruns and still
+    // advances when the SSG rebuilds the page. The generated 404 is excluded
+    // (freestruct owns it; it never reaches the feed/sitemap).
+    for (const page of latePages) {
+      try { fs.utimesSync(page.file, page.mtime, page.mtime); } catch (e) { /* mtime best-effort */ }
+    }
 
     // noindex is honored by default (owner decision, issue #5):
     // noindex pages never ship into sitemap/feed/search
-    const indexablePages = pages.filter(p => !p.is404 && !htmlIsNoindex(p.html));
+    // Dedupe by slug first: a tree with both `a.html` and `a.htm` (or
+    // `index.html`/`index.htm` in one dir) maps two files onto ONE url, and
+    // without this the artifact lists that url twice (duplicate <loc>/<item>).
+    // Both files still get decorated above; only the url listings collapse.
+    const indexablePages = dedupeBySlug(pages.filter(p => !p.is404 && !htmlIsNoindex(p.html)));
 
     if (config.generateSitemap !== false) generateSitemap(indexablePages, config, outputDir);
     if (config.generateRobots !== false) generateRobots(config, outputDir);
     if (config.generateFeed !== false) generateFeed(indexablePages, config, outputDir);
 
-    // link check over regular pages (404 targets excluded by design)
-    const brokenLinks = config.linkCheck !== false ? checkLinks(sitePages.map(p => p.file), outputDir) : [];
+    // link check over regular pages (404 targets excluded by design).
+    // basePath threads through so root-absolute hrefs on a baseurl'd site
+    // (which carry the deploy prefix) resolve against the tree, not the
+    // prefix as a directory (issue #32).
+    const brokenLinks = config.linkCheck !== false
+      ? checkLinks(sitePages.map(p => p.file), outputDir, config.basePath)
+      : [];
 
     // opt-in search index (owner decision: search.json is opt-in as of Phase 2)
     if (config.searchIndex === true) generateSearchIndex(indexablePages, config, outputDir);
 
+    // opt-in llms.txt (SEO-gap pass, config.llms): the AI-consumable docs
+    // summary, built from the same indexable page set sitemap/feed honor
+    // (noindex stays honored everywhere). Missing-only: an existing file
+    // is never overwritten.
+    if (config.llms === true) generateLlms(indexablePages, config, outputDir);
+
     // --strict: report-only classes become build failures (Phase 0 contract)
     if (STRICT) {
       const problems = [];
       if (brokenLinks.length > 0) {
         problems.push(brokenLinks.length + ' broken internal link(s)');
       }
+      // issue #20: SVG og:image offenses collected by the SEO pipeline (the
+      // 404 pipeline included, same ctx) - report-only classes graduate here,
+      // same as broken links.
+      if (injectCtx.injectWarnings.length > 0) {
+        problems.push(injectCtx.injectWarnings.length + ' SVG og:image value(s) (share previews blank; use a raster image or allowSvg: true)');
+      }
       // noindex cannot leak into generated artifacts anymore (filtered above);
       // the gate stays as a defensive tripwire for future artifact changes.
       if (problems.length > 0) {
         console.log('[freestruct] strict mode: build failed:');
         for (const problem of problems) console.log('  - ' + problem);
+        for (const w of injectCtx.injectWarnings) console.log('  - [issue #20] ' + w);
         for (const b of brokenLinks) console.log('  BROKEN: ' + b.file + ' -> ' + b.link);
         process.exit(1);
       }
@@ -262,6 +426,20 @@ export function runInject(options = {}) {
   // purge hooks, if configured (gated by runHooks)
   if (config.cacheBusting?.purge) runPurgeHooks(config, buildHash, outputDir);
 
+  // indexnow key file (issue #19): emitted during the run so the deployed
+  // keyLocation resolves (the engine that owns the sitemap ships the key
+  // file next to it). Submission is a separate subcommand - post-deploy.
+  const indexNowContext = resolveIndexNowKey(config, configDir);
+  if (indexNowContext) emitIndexNowKeyFile(indexNowContext.key, outputDir);
+
+  // postBuild hooks (issue #21): general commands chained after the pass,
+  // same runHooks gate as the purges. Unlike purges, a nonzero hook exit is
+  // a build failure: exit 4, the first failing hook wins.
+  const hookFailures = runPostBuildHooks(config, buildHash, outputDir);
+  if (hookFailures.length > 0) {
+    fail(hookFailures.length + ' postBuild hook(s) failed (exit ' + hookFailures.map(f => f.status).join(', ') + ')', EXIT_HOOK);
+  }
+
   console.log('freestruct: Done (' + buildHash + ')');
 }
 
@@ -270,10 +448,113 @@ export function runInject(options = {}) {
 // (the pre-change --version module-level check had the same shape). Library
 // importers pass no such argv and simply skip all of these.
 if (_flags.includes('--version')) { printVersion(); process.exit(0); }
-// `help` is the subcommand; --help is the flag alias (both print the same text)
-if (_firstArg === 'help' || _argv.includes('--help')) { printHelp(); process.exit(EXIT_OK); }
+// `help` is the subcommand; --help and -h are the flag aliases (all print the
+// same text). -h must be handled HERE: it is listed in KNOWN_DEFAULT_DASHES,
+// so without this branch it passes the unknown-flag guard and then rides as
+// the positional output dir (the run then dies with "Output directory not
+// found: .../-h").
+if (_firstArg === 'help' || _argv.includes('--help') || _argv.includes('-h')) { printHelp(); process.exit(EXIT_OK); }
+// ---------- audit subcommand (issue #18) ----------
+
+// `freestruct audit [outputDir] [--json]`: verify the BAKED output (heads +
+// site artifacts) after any freestruct run. Reads only the directory, so it
+// works against any SSG's build. Exit 0 clean / exit 1 findings; a missing
+// output dir is the familiar exit 3. The config is discovered the same way
+// the run walks up from cwd (it maps basePath for the on-disk asset checks);
+// a configless audit just runs without the disk-mapping extras.
+async function cmdAudit() {
+  const { positionals, flags } = parseArgs(afterCommand('audit'), {
+    command: 'audit', flags: ['--json', '--external'], maxPositionals: 1,
+  });
+  const useJson = flags.has('--json');
+  const useExternal = flags.has('--external');
+  const explicitDir = positionals[0];
+
+  let config = null;
+  let configDir = process.cwd();
+  try {
+    const loaded = loadConfig(process.cwd());
+    config = loaded.config;
+    configDir = loaded.configDir;
+  } catch (e) {
+    console.log('[freestruct] audit: config not discoverable (' + e.message.split('\n')[0] + ') - running without the on-disk asset mapping');
+  }
+
+  const outputDir = explicitDir
+    ? path.resolve(process.cwd(), explicitDir)
+    : path.resolve(configDir, (config && config.outputDir) || '_site');
+
+  if (!fs.existsSync(outputDir) || !fs.statSync(outputDir).isDirectory()) {
+    fail('Output directory not found (or not a directory): ' + outputDir, EXIT_OUTPUT);
+  }
+
+  const result = auditOutput({ outputDir, config, json: useJson && !useExternal, capture: useJson && useExternal });
+  // The no-external path exits HERE, synchronously, exactly like the pre-
+  // --external audit: a sync-crashing auditOutput must never let the
+  // engine's own full pass run on an audit invocation.
+  if (!useExternal) process.exit(result.fails.length > 0 ? 1 : EXIT_OK);
+  // External mode is the only async path: collect the network warn rows
+  // after the local audit, then decide the exit code.
+  const { warns: externalWarns } = await auditExternalLinks({ outputDir, json: useJson });
+  if (useJson) {
+    console.log(JSON.stringify({ ok: result.fails.length === 0, pages: result.pages, fails: result.fails, warns: [...result.warns, ...externalWarns] }));
+  } else {
+    const totalWarns = result.warns.length + externalWarns.length;
+    console.log(result.fails.length === 0
+      ? '[freestruct] audit: 0 failures, ' + totalWarns + ' warning(s) - clean'
+      : '[freestruct] audit: ' + result.fails.length + ' failure(s), ' + totalWarns + ' warning(s) - exiting 1');
+  }
+  process.exit(result.fails.length > 0 ? 1 : EXIT_OK);
+}
+
+// ---------- indexnow subcommand (issue #19) ----------
+
+// `freestruct indexnow [--dry-run] [outputDir]`: read the baked sitemap.xml
+// and POST its URL list to api.indexnow.org. POST-deploy by design - the
+// keyLocation file emitted during the run must be LIVE for the engines to
+// verify ownership, so this is documented as the post-deploy step (CI often
+// wants --dry-run at build time). Exit 0 accepted/dry-run | 1 failure.
+async function cmdIndexNow() {
+  const { positionals, flags } = parseArgs(afterCommand('indexnow'), {
+    command: 'indexnow', flags: ['--dry-run'], maxPositionals: 1,
+  });
+  const dryRun = flags.has('--dry-run');
+  const explicitDir = positionals[0];
+
+  let config = null;
+  let configDir = process.cwd();
+  try {
+    const loaded = loadConfig(process.cwd());
+    config = loaded.config;
+    configDir = loaded.configDir;
+  } catch (e) {
+    fail(e.message, EXIT_CONFIG);
+  }
+  if (config.indexNow === undefined || config.indexNow === null || config.indexNow === false) {
+    fail('indexnow: indexNow is not configured in the config (set indexNow: true or { key: "<32-hex>" })', EXIT_CONFIG);
+  }
+  if (typeof config.indexNow === 'string' || (config.indexNow && typeof config.indexNow === 'object' && config.indexNow.key !== undefined)) {
+    const key = typeof config.indexNow === 'string' ? config.indexNow : config.indexNow.key;
+    if (!isValidIndexNowKey(key)) {
+      fail('indexnow: the configured key is not 32 lowercase hex chars - refusing to submit a broken ownership signal', EXIT_CONFIG);
+    }
+  }
+
+  const outputDir = explicitDir
+    ? path.resolve(process.cwd(), explicitDir)
+    : path.resolve(configDir, config.outputDir || '_site');
+  if (!fs.existsSync(outputDir) || !fs.statSync(outputDir).isDirectory()) {
+    fail('Output directory not found (or not a directory): ' + outputDir + ' - run freestruct first (indexnow reads the baked sitemap)', EXIT_OUTPUT);
+  }
+
+  const result = await submitIndexNow({ config, configDir, outputDir, dryRun });
+  process.exit(result.ok ? EXIT_OK : 1);
+}
+
 if (_firstArg === 'validate') cmdValidate();
-if (_firstArg === 'init') cmdInit(_argv[_argv.indexOf('init') + 1]);
+if (_firstArg === 'init') cmdInit();
+if (_firstArg === 'audit') cmdAudit().catch((e) => fail('audit: ' + (e && e.message ? e.message : e)));
+if (_firstArg === 'indexnow') { cmdIndexNow(); }
 
 // Main-module detection: npm's .bin shim is a symlink, but import.meta.url
 // resolves the target's real path. Comparing only the raw argv[1] made real

package/engine/linkcheck.js

@@ -7,31 +7,103 @@ import path from 'path';
 /**
  * Check internal links across every page. Returns [{file, link}] for broken
  * targets and prints the human-readable report (same output as 0.4.x).
+ *
+ * Two route shapes (Pass 26.10 - the old check acknowledged only literal
+ * files): a target WITH an .html/.htm extension is checked as the file;
+ * an extension-less (pretty-URL) target resolves through the same route
+ * model the walker owns - directory index first (index.html / index.htm),
+ * then the .html/.htm sibling file. Assets stay out of the checker's
+ * purview (see the shape test above the flags).
  */
-export function checkLinks(files, outputDir) {
+export function checkLinks(files, outputDir, basePath = '') {
   const broken = [];
 
+  // basePath is the URL path prefix the output tree is SERVED under (same
+  // semantics urls.js owns for canonical/sitemap). A root-absolute href on a
+  // baseurl'd site carries that prefix ("/myrepo/guides/cli"), but inside the
+  // output tree the prefix is not a directory - resolving it literally turned
+  // every nav link into a miss and failed --strict for every baseurl'd site
+  // (issue #32). Strip the EXACT prefix before resolving; an href carrying a
+  // DIFFERENT prefix stays broken (the strip must match the configured
+  // basePath, not "any leading segment").
+  const prefix = basePath
+    ? ('/' + String(basePath).replace(/^\/+/, '')).replace(/\/+$/, '')
+    : '';
+
   for (const file of files) {
-    const html = fs.readFileSync(file, 'utf8');
+    // Payload stripping (Pass 26.14): inline JS template strings
+    // ("<a href=" + url + ">" shapes) are NOT links; rouge-fenced code
+    // TEACHES link shapes (the style guide's <a href="guides/foo">) -
+    // neither is a route. Scan the document with script, style, pre and
+    // code payloads removed (real nav hrefs never live in any of them).
+    const html = fs.readFileSync(file, 'utf8')
+      .replace(/<script[\s\S]*?<\/script>/gi, '')
+      .replace(/<style[\s\S]*?<\/style>/gi, '')
+      .replace(/<pre[\s\S]*?<\/pre>/gi, '')
+      .replace(/<code[\s\S]*?<\/code>/gi, '');
     const baseDir = path.dirname(file);
 
-    const linkRegex = /href="([^"#]+)(?:#[^"]*)?"/g;
+    // Both quote styles (bug fix): the old /href="..."/ only saw
+    // double-quoted hrefs, so a single-quoted broken link (`href='/gone/'`,
+    // valid HTML) sailed through --strict. The backreference keeps the pair
+    // consistent; the fragment is stripped from the checked target either way.
+    // Case-insensitive (HTML attribute names are): an upper-case `HREF=`
+    // (valid markup) was skipped entirely, so a broken link shipped green.
+    const linkRegex = /href=(["'])([^"'#]+)(?:#[^"']*)?\1/gi;
     let match;
     while ((match = linkRegex.exec(html)) !== null) {
-      const link = match[1];
+      const link = match[2];
 
-      // Skip external, mailto, tel
-      if (link.startsWith('http') || link.startsWith('mailto:') || link.startsWith('tel:') || link.startsWith('//')) continue;
+      // Skip external, absolute-protocol, and ANY scheme-shaped target
+      // (data:, javascript:, tel:, mailto:, ...): schemes are not routes.
+      if (/^[a-z][a-z0-9+.-]*:/i.test(link) || link.startsWith('//')) continue;
 
-      const absPath = path.join(baseDir, link);
+      // Root-relative hrefs (the whole nav menu: "/guides/cli") resolve
+      // against the OUTPUT ROOT - path.join(baseDir, '/x') APPENDS, it never
+      // resets, which turned every menu link on a nested page into a miss
+      // (the CI --strict run caught it). Relative hrefs stay page-relative.
+      // A root-absolute href that carries the configured basePath has that
+      // prefix stripped first (issue #32); one with a different prefix keeps
+      // it and resolves (correctly) as broken.
+      let target = link;
+      // A query string is not part of the route: '/guide?foo=bar' serves the
+      // same page as '/guide'. Resolving the raw value looked for a file
+      // literally named 'guide?foo=bar' and reported a valid link broken
+      // (failing --strict on any site whose nav carries query params, e.g. a
+      // utm-tagged or search-fed link). Strip it before resolving.
+      const q = target.indexOf('?');
+      if (q !== -1) target = target.slice(0, q);
+      if (target.startsWith('/') && prefix && (target === prefix || target.startsWith(prefix + '/'))) {
+        target = target.slice(prefix.length) || '/';
+      }
+      const absPath = target.startsWith('/')
+        ? path.join(outputDir, target)
+        : path.join(baseDir, target);
       const normalized = path.normalize(absPath);
 
-      let checkPath = normalized;
-      if (fs.existsSync(path.join(normalized, 'index.html'))) {
-        checkPath = path.join(normalized, 'index.html');
+      // Targeted file link: extension decides the check shape (case-
+      // insensitive .html/.htm - Pass 26.10, mixed-case SSG output is a
+      // page like any other).
+      if (/\.html?$/i.test(normalized)) {
+        if (!fs.existsSync(normalized)) {
+          broken.push({ file: path.relative(outputDir, file), link });
+        }
+        continue;
       }
 
-      if (normalized.endsWith('.html') && !fs.existsSync(normalized)) {
+      // Pretty-URL link: resolve like the route model - directory index
+      // first, then the .html/.htm sibling. Asset-like targets (their last
+      // segment carries an extension that is not a page route: .css, .js,
+      // .png, .json, ...) are the host's business and stay out of the
+      // link checker.
+      const lastSegment = normalized.split(path.sep).pop() || '';
+      if (lastSegment.includes('.')) continue;
+
+      const dirIndex = fs.existsSync(path.join(normalized, 'index.html'))
+        || fs.existsSync(path.join(normalized, 'index.htm'));
+      const prettySibling = fs.existsSync(path.join(normalized + '.html'))
+        || fs.existsSync(path.join(normalized + '.htm'));
+      if (!dirIndex && !prettySibling) {
         broken.push({ file: path.relative(outputDir, file), link });
       }
     }

package/engine/llms.js

@@ -0,0 +1,63 @@
+// engine/llms.js - llms.txt emission (the SEO-gap pass, config.llms)
+// The AI-consumable docs-summary convention (llmstxt.org shape): one H1, a
+// blockquote tagline, then a Docs section listing every indexable page's
+// title, absolute URL and description. Natural to this engine: the scan
+// pass already carries every page's slug/title/description and the run
+// already owns the indexable (non-noindex) page set - zero new scanning.
+// Generated-only: never overwrites, same contract as sitemap/feed/robots.
+
+import fs from 'fs';
+import path from 'path';
+import { pageUrlFor } from './urls.js';
+
+/**
+ * One line of plain text, whatever it was given: a newline (or CR) inside a
+ * title/description would split a list entry into two, silently corrupting
+ * the summary's shape, and an XML-era control character would ride into the
+ * plain-text file as garbage. Bad bytes drop, whitespace collapses.
+ */
+function oneline(value) {
+  return String(value)
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '')
+    .replace(/[\r\n]+/g, ' ')
+    .trim();
+}
+
+/**
+ * A markdown link LABEL: `[` and `]` inside it would close the label early,
+ * so the emitted link renders as broken text (a title like 'Foo] bar' or a
+ * '[preview]' tag produced '- [Foo] bar](url)' - the URL spilled into the
+ * prose and the link broke). Escape the brackets, and the backslash itself,
+ * so the label always renders as the literal title.
+ */
+function mdLabel(value) {
+  return oneline(value).replace(/([\\\[\]])/g, '\\$1');
+}
+
+/**
+ * Write llms.txt into the output dir. Pages only: indexable = non-404,
+ * non-noindex (the same gate sitemap/feed honor, so noindex stays honored
+ * everywhere). Missing-only: an existing llms.txt (hand-rolled or
+ * SSG-written) is never touched.
+ */
+export function generateLlms(indexablePages, config, outputDir) {
+  const target = path.join(outputDir, 'llms.txt');
+  if (fs.existsSync(target)) {
+    console.log('[freestruct] llms.txt exists - leaving it untouched');
+    return null;
+  }
+  const lines = [];
+  lines.push('# ' + oneline(config.site.name));
+  if (config.site.description) lines.push('', '> ' + oneline(config.site.description));
+  lines.push('', '## Docs', '');
+  for (const page of indexablePages) {
+    const url = pageUrlFor(config, page.slug);
+    const title = mdLabel(page.title || page.slug);
+    const desc = page.description ? ': ' + oneline(page.description) : '';
+    lines.push('- [' + title + '](' + url + ')' + desc);
+  }
+  fs.writeFileSync(target, lines.join('\n') + '\n');
+  const count = indexablePages.length;
+  console.log('[freestruct] llms.txt: emitted for ' + count + ' page(s)');
+  return target;
+}