human-machine-swapper 1.0.1 → 1.1.0

package/AGENTS.md

@@ -7,7 +7,27 @@ Instructions for coding agents adding this component to a site.
 A dependency-free web component that adds a Human / Machine pill. Machine shows the site's
 `llms.txt` rendered in place. One script tag, one custom element, no build step.
 
-## Install it in three steps, all three required
+## Do this first
+
+```bash
+npx human-machine-swapper init
+```
+
+It detects the framework, writes a starter `llms.txt` if the site has none, declares it,
+loads the component pinned to a version with an integrity hash, mounts the element, and adds
+the `:not(:defined)` guard. It is idempotent, so running it twice is safe, and it never
+overwrites an existing `llms.txt`.
+
+Add `--dry-run` to see the changes without writing them.
+
+**Read the output.** It reports anything it could not work out rather than guessing, and it
+tells you how many `TODO`s are left in the generated `llms.txt`. Exit codes: `0` installed,
+`1` could not identify the project, `2` installed but something needs a human.
+
+If the command cannot identify the project, or you are editing a site by hand, the install
+is these three things plus one CSS rule.
+
+## By hand, if you have to
 
 1. **Load the script.**
 
@@ -30,8 +50,8 @@ A dependency-free web component that adds a Human / Machine pill. Machine shows
    human-machine-swapper:not(:defined) { display: none; }
    ```
 
-   Without it, the element is laid out in flow at ~50px tall until the script loads and pushes
-   the rest of the page down.
+   Without it, the element is laid out in flow at ~50px tall until the script loads and
+   pushes the rest of the page down.
 
 ## The site must have an llms.txt
 

package/README.md

@@ -16,6 +16,20 @@ and one custom element.
 
 ## Install
 
+### One command
+
+```bash
+npx human-machine-swapper init
+```
+
+Detects your framework, writes a starter `llms.txt` if you have none, declares it, loads the
+component **pinned to a version with an integrity hash**, mounts the element, and adds the
+`:not(:defined)` guard below. Idempotent, never overwrites an existing `llms.txt`, and
+`--dry-run` shows the changes without making them.
+
+Knows Next (app and pages router), Astro, SvelteKit, Nuxt, WordPress themes and plain HTML.
+If it cannot identify your project it changes nothing and prints the manual steps.
+
 ### Script tag
 
 ```html
@@ -38,7 +52,8 @@ import "human-machine-swapper";
 
 ## Required setup
 
-Three things. Skip any one of them and the pill will not appear, or will appear broken.
+Three things. `init` does all of them; this is what it is doing, and what to do by hand.
+Skip any one and the pill will not appear, or will appear broken.
 
 ### 1. Publish an `llms.txt`
 
@@ -268,12 +283,31 @@ curl -s https://unpkg.com/human-machine-swapper@1.0.0/src/human-machine-swapper.
   | openssl dgst -sha384 -binary | openssl base64 -A
 ```
 
+### Provenance
+
+From 1.0.2 this package is published by GitHub Actions through npm's trusted publishing, with
+no long-lived token anywhere. Every release carries a signed attestation naming the commit and
+the workflow that built it, so you can check the tarball came from this repo rather than from
+somebody's credentials:
+
+```bash
+npm audit signatures
+```
+
+That is a stronger claim than an integrity hash. A hash says the bytes did not change in
+transit; the attestation says where the bytes came from.
+
 A pinned build does not update, so you take on watching for releases. Self-hosting the file is
 the third option and works identically: it is one dependency-free script with no network calls
 of its own beyond reading your `llms.txt`.
 
 ---
 
+## Contributing
+
+Releases are cut by pushing a tag; see [RELEASING.md](RELEASING.md). There is no npm token —
+publishing uses trusted publishing, and every release carries a provenance attestation.
+
 ## Licence
 
 Apache-2.0.

package/bin/cli.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { detect, readSiteFacts } from "../src/init/detect.mjs";
+import { buildLlmsTxt, countTodos } from "../src/init/llms.mjs";
+import { apply, buildScriptTag, isJsxLayout, ELEMENT_TAG, LINK_TAG, CSS_GUARD } from "../src/init/apply.mjs";
+
+/**
+ * `npx human-machine-swapper init`
+ *
+ * Non-interactive on purpose. The most common caller is a coding agent that was told "add a
+ * human/machine toggle to this site", and a prompt it cannot answer is a hang. Everything
+ * is decided from what is on disk; anything undecidable is reported as manual rather than
+ * guessed at.
+ *
+ * Exit codes are meaningful, because an agent reads them:
+ *   0  installed, or already installed
+ *   1  could not tell what this project is
+ *   2  installed, but something needs a human
+ */
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG = JSON.parse(readFileSync(join(HERE, "../package.json"), "utf8"));
+const DOCS = "https://advancelabs.dev/human-machine-swapper";
+
+const C = process.stdout.isTTY && !process.env.NO_COLOR
+  ? { dim: "\x1b[2m", b: "\x1b[1m", g: "\x1b[32m", y: "\x1b[33m", r: "\x1b[31m", x: "\x1b[0m" }
+  : { dim: "", b: "", g: "", y: "", r: "", x: "" };
+
+function usage() {
+  console.log(`${C.b}human-machine-swapper${C.x} ${PKG.version}
+
+  npx human-machine-swapper init [options]
+
+Adds the Human/Machine pill to this project: writes a starter llms.txt, declares it,
+loads the component, mounts it, and adds the :not(:defined) guard that stops the
+element being laid out in flow before the script arrives.
+
+Options
+  --dry-run     Show what would change, write nothing
+  --latest      Use the floating CDN url instead of pinning this version with an
+                integrity hash. Auto-updates, but cannot be verified
+  --dir <path>  Project root (default: cwd)
+  --help        This
+
+Docs: ${DOCS}`);
+}
+
+function parseArgs(argv) {
+  // The first NON-flag is the command. Taking argv[0] blindly made `--help` an unknown
+  // command, which is the first thing anybody types.
+  const args = { cmd: null, dryRun: false, pin: true, dir: process.cwd() };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--dry-run" || a === "-n") args.dryRun = true;
+    else if (a === "--latest") args.pin = false;
+    else if (a === "--dir") args.dir = argv[++i];
+    else if (a === "--help" || a === "-h") args.help = true;
+    else if (!a.startsWith("-") && !args.cmd) args.cmd = a;
+  }
+  return args;
+}
+
+/** sha384 of the file this very package will have published. Verifiable, not asserted. */
+function integrityOfSelf() {
+  try {
+    const bytes = readFileSync(join(HERE, "../src/human-machine-swapper.js"));
+    return "sha384-" + createHash("sha384").update(bytes).digest("base64");
+  } catch {
+    return null;
+  }
+}
+
+function report(actions) {
+  const mark = { done: `${C.g}+${C.x}`, skipped: `${C.dim}=${C.x}`, manual: `${C.y}!${C.x}` };
+  for (const a of actions) {
+    const where = a.file ? ` ${C.dim}${a.file}${C.x}` : "";
+    const note = a.note ? ` ${C.dim}(${a.note})${C.x}` : "";
+    console.log(`  ${mark[a.status]} ${a.what}${where}${note}`);
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help || !args.cmd) {
+    usage();
+    process.exit(0);
+  }
+  if (args.cmd !== "init") {
+    console.error(`Unknown command "${args.cmd}". Try: npx human-machine-swapper init`);
+    process.exit(1);
+  }
+
+  const framework = detect(args.dir);
+  if (!framework) {
+    console.error(`${C.r}Could not tell what kind of project this is.${C.x}
+
+Looked for a Next, Astro, SvelteKit, Nuxt or WordPress project, or an index.html.
+Nothing matched, so nothing was changed.
+
+Install it by hand, which is three things:
+
+  1. ${LINK_TAG}
+  2. ${buildScriptTag({ pin: false })}
+  3. ${ELEMENT_TAG}
+
+and this CSS, which is not optional:
+
+${CSS_GUARD.split("\n").map((l) => "  " + l).join("\n")}
+
+Then make sure the site serves an llms.txt. Full docs: ${DOCS}`);
+    process.exit(1);
+  }
+
+  const facts = readSiteFacts(args.dir);
+  const llmsTxt = buildLlmsTxt(facts, { framework: framework.name });
+  const scriptTag = buildScriptTag({
+    version: PKG.version,
+    integrity: integrityOfSelf(),
+    pin: args.pin,
+    jsx: isJsxLayout(framework.layout),
+  });
+
+  console.log(`\n${C.b}${framework.name}${C.x}${args.dryRun ? `  ${C.y}(dry run, nothing written)${C.x}` : ""}\n`);
+
+  const { actions, wrote } = apply({ dir: args.dir, framework, llmsTxt, scriptTag, dryRun: args.dryRun });
+  report(actions);
+
+  const todos = countTodos(llmsTxt);
+  const needsHuman = actions.filter((a) => a.status === "manual");
+  const wroteLlms = actions.some((a) => a.what === "llms.txt" && a.status === "done");
+
+  console.log("");
+  if (wroteLlms && todos) {
+    console.log(
+      `${C.y}The llms.txt is a starting point and has ${todos} TODO${todos === 1 ? "" : "s"} in it.${C.x}\n` +
+        `Machine view shows that file verbatim, so whatever is in it is what an agent reads\n` +
+        `about this site. Ten minutes editing it is the whole value of installing this.\n`
+    );
+  }
+  if (needsHuman.length) {
+    console.log(`${C.y}${needsHuman.length} thing${needsHuman.length === 1 ? "" : "s"} still need${needsHuman.length === 1 ? "s" : ""} you:${C.x}`);
+    for (const a of needsHuman) console.log(`  ! ${a.what}: ${a.note}`);
+    console.log("");
+  }
+  if (args.pin) {
+    console.log(
+      `${C.dim}Pinned to ${PKG.version} with an integrity hash, so the tag cannot change under you.\n` +
+        `Re-run with --latest if you would rather auto-update. Docs: ${DOCS}${C.x}`
+    );
+  }
+
+  if (args.dryRun) console.log(`\n${C.dim}Dry run. ${wrote.length} file${wrote.length === 1 ? "" : "s"} would change.${C.x}`);
+  process.exit(needsHuman.length ? 2 : 0);
+}
+
+main();

package/llms.txt

@@ -7,6 +7,19 @@
 
 ## Install
 
+One command, from the project root:
+
+    npx human-machine-swapper init
+
+It detects the framework, writes a starter llms.txt if there is none, declares it, loads the
+component pinned with an integrity hash, mounts the element, and adds the :not(:defined)
+guard. Idempotent; never overwrites an existing llms.txt. Add --dry-run to preview.
+
+Exit codes: 0 installed, 1 could not identify the project, 2 installed but something needs a
+human.
+
+By hand instead:
+
     <script src="https://unpkg.com/human-machine-swapper" defer></script>
     <human-machine-swapper data-position="bottom-center"></human-machine-swapper>
 
@@ -56,9 +69,10 @@ A: An Apache-2.0 web component published by Advance Labs Inc. that puts a Human
 toggle on a website, where Machine shows the site's llms.txt rendered in place.
 
 Q: How do I add a human machine toggle to a website?
-A: Add the script tag, add the <human-machine-swapper> element, add the
-human-machine-swapper:not(:defined){display:none} CSS rule, and make sure the site serves an
-llms.txt.
+A: Run `npx human-machine-swapper init` in the project root. It does all of it: writes a
+starter llms.txt, declares it, loads the component, mounts the element and adds the required
+CSS guard. By hand it is a script tag, a <human-machine-swapper> element, the
+human-machine-swapper:not(:defined){display:none} rule, and an llms.txt the site serves.
 
 Q: Why is the pill not showing up?
 A: Almost always because the site has no llms.txt. The component hides itself when it has

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "human-machine-swapper",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "A web component that adds a Human / Machine pill to any website. Machine shows the site's llms.txt, the plain-text reading written for language models, rendered in place. One file, about 6 KB gzipped, no dependencies and no build step.",
   "keywords": [
     "llms.txt",
@@ -37,6 +37,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "bin",
     "src",
     "llms.txt",
     "AGENTS.md",
@@ -52,5 +53,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "bin": {
+    "human-machine-swapper": "bin/cli.mjs"
   }
 }

package/src/init/apply.mjs

@@ -0,0 +1,213 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * The three edits, applied to whatever the detector found.
+ *
+ * Everything here is idempotent and additive. `init` runs inside somebody else's
+ * repository, so the rules are: never overwrite a file that already has content we did not
+ * write, never touch a line we did not add, and when a file does not look the way we
+ * expect, report it as manual rather than guessing. A wrong guess here breaks a stranger's
+ * layout and reads as our bug.
+ */
+
+/**
+ * The script tag init writes into somebody else's repository.
+ *
+ * Pinned with an integrity hash by default, because a floating CDN URL cannot be pinned at
+ * all and this command is writing into a repo whose owner never chose to trust unpkg. The
+ * hash is computed from the bytes on disk in the very package doing the writing, so it is
+ * verifiable rather than asserted. `--latest` opts into auto-updating instead.
+ */
+export function buildScriptTag({ version, integrity, pin = true, jsx = false }) {
+  // JSX is not HTML: React wants crossOrigin, and the lowercase spelling is not the DOM
+  // property. Emitting the HTML spelling into a .jsx file is a real bug, not a nit.
+  const cross = jsx ? "crossOrigin" : "crossorigin";
+  if (!pin || !version || !integrity) {
+    return '<script src="https://unpkg.com/human-machine-swapper" defer></script>';
+  }
+  const src = `https://unpkg.com/human-machine-swapper@${version}/src/human-machine-swapper.js`;
+  return (
+    `<script\n` +
+    `  src="${src}"\n` +
+    `  integrity="${integrity}"\n` +
+    `  ${cross}="anonymous"\n` +
+    `  defer\n` +
+    `></script>`
+  );
+}
+
+/** JSX-flavoured layouts, where attribute spelling differs from HTML. */
+export function isJsxLayout(path) {
+  return /\.(jsx|tsx)$/.test(path || "") || /\.vue$/.test(path || "");
+}
+export const LINK_TAG = '<link rel="llms" href="/llms.txt" />';
+export const ELEMENT_TAG = '<human-machine-swapper data-position="bottom-center"></human-machine-swapper>';
+export const CSS_GUARD = `/* Until the script loads the browser lays this unknown element out in flow, about
+   50px tall, and pushes the page down. Added by human-machine-swapper init. */
+human-machine-swapper:not(:defined) {
+  display: none;
+}`;
+
+/** One entry per thing init tried to do, so the CLI can print an honest report. */
+const done = (what, file, note) => ({ what, file, status: "done", note });
+const skip = (what, file, note) => ({ what, file, status: "skipped", note });
+const manual = (what, note) => ({ what, file: null, status: "manual", note });
+
+function read(dir, rel) {
+  return readFileSync(join(dir, rel), "utf8");
+}
+
+function write(dir, rel, text, { dryRun }) {
+  if (dryRun) return;
+  const abs = join(dir, rel);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, text);
+}
+
+/**
+ * Inserts `snippet` on its own line before the first occurrence of `marker`, matching the
+ * marker line's indentation so the result does not look bolted on.
+ */
+function insertBefore(source, marker, snippet) {
+  const at = source.indexOf(marker);
+  if (at === -1) return null;
+  const lineStart = source.lastIndexOf("\n", at) + 1;
+  // The marker is a CLOSING tag, so its own indentation is the parent's. Children sit one
+  // level in, and every line of a multi-line snippet gets the same treatment or the
+  // continuation lines land wherever they happened to be authored.
+  const indent = source.slice(lineStart, at).match(/^\s*/)[0] + "  ";
+  // Keep the snippet's OWN relative indentation: a multi-line tag authors its attributes
+  // one level in and its closing bracket flush, and flattening that puts `></script>`
+  // deeper than the tag it closes.
+  const body = snippet
+    .split("\n")
+    .map((l) => (l.trim() ? indent + l : l))
+    .join("\n");
+  return source.slice(0, lineStart) + body + "\n" + source.slice(lineStart);
+}
+
+/** Already installed? Then there is nothing to do and we say so instead of doubling up. */
+const hasElement = (s) => s.includes("<human-machine-swapper");
+const hasScript = (s) => s.includes("human-machine-swapper") && /<script[^>]+unpkg\.com\/human-machine-swapper/.test(s);
+const hasLink = (s) => /rel=["']llms["']/.test(s);
+const hasGuard = (s) => s.includes("human-machine-swapper:not(:defined)");
+
+/**
+ * Where `</head>` effectively is for this framework. SvelteKit's app.html has no literal
+ * head close in some templates, and WordPress puts wp_head() where the tags belong.
+ */
+function headMarker(source, frameworkId) {
+  if (frameworkId === "sveltekit" && source.includes("%sveltekit.head%")) return "%sveltekit.head%";
+  if (frameworkId === "wordpress-theme" && source.includes("wp_head()")) return "<?php wp_head(); ?>";
+  if (source.includes("</head>")) return "</head>";
+  return null;
+}
+
+function bodyMarker(source) {
+  if (source.includes("</body>")) return "</body>";
+  return null;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.dir         project root
+ * @param {object} opts.framework   from detect()
+ * @param {string} opts.llmsTxt     generated llms.txt contents
+ * @param {string} opts.scriptTag   from buildScriptTag(); pinned + hashed by default
+ * @param {boolean} opts.dryRun
+ * @returns {{actions: Array, wrote: string[]}}
+ */
+export function apply({ dir, framework, llmsTxt, scriptTag, dryRun = false }) {
+  const SCRIPT = scriptTag || buildScriptTag({ pin: false });
+  const actions = [];
+  const wrote = [];
+
+  // 1. llms.txt. Never overwritten: an existing one is the site's own machine reading and
+  //    is certainly better than anything generated from a README.
+  const llmsPath = join(framework.public === "." ? "" : framework.public, "llms.txt").replace(/^\//, "");
+  if (existsSync(join(dir, llmsPath))) {
+    actions.push(skip("llms.txt", llmsPath, "already exists, left untouched"));
+  } else {
+    write(dir, llmsPath, llmsTxt, { dryRun });
+    wrote.push(llmsPath);
+    actions.push(done("llms.txt", llmsPath, "starter file, edit before shipping"));
+  }
+
+  // 2. The markup: link, script, element.
+  if (!framework.layout) {
+    actions.push(manual("markup", "no layout file found; add the link, script and element by hand"));
+  } else {
+    let source = read(dir, framework.layout);
+    const before = source;
+
+    const head = headMarker(source, framework.id);
+    if (!head) {
+      actions.push(manual("head tags", `no <head> found in ${framework.layout}`));
+    } else {
+      if (hasLink(source)) {
+        actions.push(skip("link rel=llms", framework.layout, "already declared"));
+      } else {
+        source = insertBefore(source, head, LINK_TAG) ?? source;
+        actions.push(done("link rel=llms", framework.layout));
+      }
+      if (hasScript(source)) {
+        actions.push(skip("script tag", framework.layout, "already loaded"));
+      } else {
+        source = insertBefore(source, head, SCRIPT) ?? source;
+        actions.push(done("script tag", framework.layout));
+      }
+    }
+
+    const body = bodyMarker(source);
+    if (hasElement(before)) {
+      actions.push(skip("<human-machine-swapper>", framework.layout, "already mounted"));
+    } else if (!body) {
+      actions.push(manual("element", `no </body> in ${framework.layout}; mount the element by hand`));
+    } else {
+      source = insertBefore(source, body, ELEMENT_TAG) ?? source;
+      actions.push(done("<human-machine-swapper>", framework.layout));
+    }
+
+    if (source !== before) {
+      write(dir, framework.layout, source, { dryRun });
+      wrote.push(framework.layout);
+    }
+  }
+
+  // 3. The guard. This is the one that silently breaks a layout if it is missing, so when
+  //    there is no stylesheet to put it in we inline a <style> rather than skipping it.
+  if (framework.styles && existsSync(join(dir, framework.styles))) {
+    const css = read(dir, framework.styles);
+    if (hasGuard(css)) {
+      actions.push(skip(":defined guard", framework.styles, "already present"));
+    } else {
+      write(dir, framework.styles, css.trimEnd() + "\n\n" + CSS_GUARD + "\n", { dryRun });
+      wrote.push(framework.styles);
+      actions.push(done(":defined guard", framework.styles));
+    }
+  } else if (framework.layout) {
+    const source = read(dir, framework.layout);
+    if (hasGuard(source)) {
+      actions.push(skip(":defined guard", framework.layout, "already present"));
+    } else {
+      const head = headMarker(source, framework.id);
+      if (!head) {
+        actions.push(manual(":defined guard", "add human-machine-swapper:not(:defined){display:none} to your CSS"));
+      } else {
+        const styled = insertBefore(source, head, `<style>\n${CSS_GUARD}\n</style>`);
+        if (styled) {
+          write(dir, framework.layout, styled, { dryRun });
+          if (!wrote.includes(framework.layout)) wrote.push(framework.layout);
+          actions.push(done(":defined guard", framework.layout, "inlined, no global stylesheet found"));
+        } else {
+          actions.push(manual(":defined guard", "could not find a place for it"));
+        }
+      }
+    }
+  } else {
+    actions.push(manual(":defined guard", "add human-machine-swapper:not(:defined){display:none} to your CSS"));
+  }
+
+  return { actions, wrote };
+}

package/src/init/detect.mjs

@@ -0,0 +1,208 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Works out what kind of project this is, and where its three insertion points live.
+ *
+ * Detection is by file, never by dependency name: a project can list `next` in
+ * devDependencies and not be a Next app, and plenty of real sites have no package.json at
+ * all. What is on disk is the truth.
+ *
+ * Every framework resolves to the same three answers, because the install is always the
+ * same three edits:
+ *   head    - where <link rel="llms"> goes
+ *   body    - where <human-machine-swapper> goes
+ *   styles  - where the :not(:defined) guard goes
+ */
+
+const exists = (dir, ...parts) => existsSync(join(dir, ...parts));
+
+/** The first of these that exists, or null. Order is the preference order. */
+function firstFile(dir, candidates) {
+  for (const c of candidates) if (exists(dir, c)) return c;
+  return null;
+}
+
+/** Where a framework serves static files from, which is where llms.txt has to land. */
+function publicDir(dir, candidates) {
+  for (const c of candidates) if (exists(dir, c)) return c;
+  return candidates[0];
+}
+
+/**
+ * Finds the stylesheet a framework actually loads globally. Guessing wrong here is the
+ * worst outcome the CLI has: the guard lands in a file nothing imports, the element is
+ * laid out in flow at ~50px, and the page breaks in a way that looks like our fault.
+ * When nothing matches we say so rather than picking one.
+ */
+function globalStylesheet(dir, candidates) {
+  const found = firstFile(dir, candidates);
+  return found;
+}
+
+const DETECTORS = [
+  {
+    id: "next-app",
+    name: "Next.js (App Router)",
+    test: (dir) =>
+      firstFile(dir, ["next.config.js", "next.config.mjs", "next.config.ts"]) &&
+      firstFile(dir, ["app/layout.js", "app/layout.jsx", "app/layout.tsx", "src/app/layout.js", "src/app/layout.jsx", "src/app/layout.tsx"]),
+    resolve: (dir) => ({
+      layout: firstFile(dir, [
+        "app/layout.tsx", "app/layout.jsx", "app/layout.js",
+        "src/app/layout.tsx", "src/app/layout.jsx", "src/app/layout.js",
+      ]),
+      styles: globalStylesheet(dir, [
+        "app/globals.css", "src/app/globals.css", "styles/globals.css", "app/global.css",
+      ]),
+      public: publicDir(dir, ["public"]),
+    }),
+  },
+  {
+    id: "next-pages",
+    name: "Next.js (Pages Router)",
+    test: (dir) =>
+      firstFile(dir, ["next.config.js", "next.config.mjs", "next.config.ts"]) &&
+      firstFile(dir, ["pages/_document.js", "pages/_document.jsx", "pages/_document.tsx", "src/pages/_document.tsx"]),
+    resolve: (dir) => ({
+      layout: firstFile(dir, [
+        "pages/_document.tsx", "pages/_document.jsx", "pages/_document.js",
+        "src/pages/_document.tsx",
+      ]),
+      styles: globalStylesheet(dir, ["styles/globals.css", "src/styles/globals.css"]),
+      public: publicDir(dir, ["public"]),
+    }),
+  },
+  {
+    id: "astro",
+    name: "Astro",
+    test: (dir) => firstFile(dir, ["astro.config.mjs", "astro.config.js", "astro.config.ts"]),
+    resolve: (dir) => ({
+      layout: firstFile(dir, [
+        "src/layouts/Layout.astro", "src/layouts/BaseLayout.astro", "src/pages/index.astro",
+      ]),
+      styles: globalStylesheet(dir, ["src/styles/global.css", "src/styles/globals.css"]),
+      public: publicDir(dir, ["public"]),
+    }),
+  },
+  {
+    id: "sveltekit",
+    name: "SvelteKit",
+    test: (dir) => firstFile(dir, ["svelte.config.js"]) && exists(dir, "src/app.html"),
+    resolve: (dir) => ({
+      layout: "src/app.html",
+      styles: globalStylesheet(dir, ["src/app.css", "src/routes/styles.css"]),
+      public: publicDir(dir, ["static"]),
+    }),
+  },
+  {
+    id: "nuxt",
+    name: "Nuxt",
+    test: (dir) => firstFile(dir, ["nuxt.config.ts", "nuxt.config.js"]),
+    resolve: (dir) => ({
+      layout: firstFile(dir, ["app.vue", "layouts/default.vue"]),
+      styles: globalStylesheet(dir, ["assets/css/main.css", "assets/main.css"]),
+      public: publicDir(dir, ["public"]),
+    }),
+  },
+  {
+    id: "wordpress-theme",
+    name: "WordPress theme",
+    test: (dir) => exists(dir, "functions.php") && exists(dir, "style.css"),
+    resolve: (dir) => ({
+      layout: firstFile(dir, ["header.php"]),
+      styles: "style.css",
+      public: publicDir(dir, ["."]),
+    }),
+  },
+  {
+    id: "html",
+    name: "Static HTML",
+    test: (dir) => firstFile(dir, ["index.html", "public/index.html", "src/index.html"]),
+    resolve: (dir) => {
+      const layout = firstFile(dir, ["index.html", "public/index.html", "src/index.html"]);
+      // For a plain page the markup carries its own styles; we inject a <style> block
+      // rather than hunting for a stylesheet that may not exist.
+      return {
+        layout,
+        styles: null,
+        public: publicDir(dir, [layout && layout.includes("/") ? layout.split("/")[0] : "."]),
+      };
+    },
+  },
+];
+
+/**
+ * @returns {{id:string,name:string,layout:string|null,styles:string|null,public:string}|null}
+ */
+export function detect(dir = process.cwd()) {
+  for (const d of DETECTORS) {
+    if (!d.test(dir)) continue;
+    return { id: d.id, name: d.name, ...d.resolve(dir) };
+  }
+  return null;
+}
+
+/**
+ * Facts about the site, scavenged from whatever this project happens to have. Everything
+ * is optional; llms.txt generation degrades rather than failing, because a half-filled
+ * llms.txt a human then edits is worth far more than an error telling them to write one.
+ */
+export function readSiteFacts(dir = process.cwd()) {
+  const facts = { name: null, description: null, url: null, headings: [] };
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    if (pkg.name) facts.name = titleise(pkg.name);
+    if (pkg.description) facts.description = pkg.description;
+    if (typeof pkg.homepage === "string") facts.url = pkg.homepage;
+  } catch {}
+
+  // An index.html usually states the real title and description, which beats a package name.
+  for (const p of ["index.html", "public/index.html", "src/index.html"]) {
+    if (!exists(dir, p)) continue;
+    try {
+      const html = readFileSync(join(dir, p), "utf8");
+      const title = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+      if (title) facts.name = title[1].trim();
+      const desc = html.match(/<meta[^>]+name=["']description["'][^>]+content=["']([^"']+)["']/i);
+      if (desc) facts.description = desc[1].trim();
+    } catch {}
+    break;
+  }
+
+  // A README's first heading and first real paragraph are usually the best prose on disk.
+  for (const p of ["README.md", "readme.md"]) {
+    if (!exists(dir, p)) continue;
+    try {
+      const md = readFileSync(join(dir, p), "utf8");
+      const h1 = md.match(/^#\s+(.+)$/m);
+      if (h1 && !facts.name) facts.name = h1[1].trim();
+      if (!facts.description) {
+        const para = md
+          .split("\n")
+          .find((l) => l.trim() && !l.startsWith("#") && !l.startsWith("!") && !l.startsWith("["));
+        if (para) facts.description = para.trim();
+      }
+      facts.headings = [...md.matchAll(/^##\s+(.+)$/gm)].map((m) => m[1].trim()).slice(0, 8);
+    } catch {}
+    break;
+  }
+
+  return facts;
+}
+
+function titleise(slug) {
+  return String(slug)
+    .replace(/^@[^/]+\//, "")
+    .split(/[-_]/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+/** Only used by the report, to say what we looked at. */
+export function listDetectors() {
+  return DETECTORS.map((d) => ({ id: d.id, name: d.name }));
+}
+
+export { exists, firstFile, readdirSync };

package/src/init/llms.mjs

@@ -0,0 +1,94 @@
+/**
+ * Builds a starter llms.txt from whatever the project told us about itself.
+ *
+ * This is deliberately a *starter*. A generated llms.txt that nobody edits is a worse
+ * machine reading than a short one somebody wrote, so the file says so in its own text and
+ * marks what it could not work out. The goal is to get the site from "no machine reading,
+ * so the pill cannot render" to "a real file that a human improves in ten minutes".
+ *
+ * Offline by design. An agent running `npx human-machine-swapper init` is often in a
+ * sandbox with no network; a generator that needs one fails exactly where it matters most.
+ */
+
+const TODO = "TODO";
+
+export function buildLlmsTxt(facts = {}, { framework } = {}) {
+  const name = facts.name || "This site";
+  const summary = facts.description || `${TODO}: one sentence on what this site is.`;
+
+  const lines = [];
+  lines.push(`# ${name}`);
+  lines.push("");
+  lines.push(`> ${wrapOne(summary)}`);
+  lines.push("");
+  lines.push("## About");
+  lines.push("");
+  if (facts.description) {
+    lines.push(wrap(facts.description));
+  } else {
+    lines.push(`${TODO}: a paragraph or two a language model can quote about ${name}.`);
+  }
+  lines.push("");
+
+  if (facts.headings && facts.headings.length) {
+    lines.push("## Sections");
+    lines.push("");
+    for (const h of facts.headings) lines.push(`- ${h}`);
+    lines.push("");
+  }
+
+  lines.push("## Key facts");
+  lines.push("");
+  lines.push(`Q: What is ${name}?`);
+  lines.push(`A: ${facts.description ? wrapOne(facts.description) : `${TODO}`}`);
+  lines.push("");
+  lines.push(`Q: What can I do on ${name}?`);
+  lines.push(`A: ${TODO}`);
+  lines.push("");
+
+  if (facts.url) {
+    lines.push("## Links");
+    lines.push("");
+    lines.push(`- Website: ${facts.url}`);
+    lines.push("");
+  }
+
+  lines.push("---");
+  lines.push("");
+  lines.push(
+    wrap(
+      `This file was generated by human-machine-swapper init${
+        framework ? ` from a ${framework} project` : ""
+      }. It is a starting point, not a finished machine reading: replace every ${TODO} and cut anything that is not true. The convention is documented at https://llmstxt.org`
+    )
+  );
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/** How many TODOs a human still owes this file. The CLI reports it rather than pretending. */
+export function countTodos(text) {
+  return (text.match(new RegExp(TODO, "g")) || []).length;
+}
+
+function wrap(text, width = 92) {
+  const words = String(text).split(/\s+/).filter(Boolean);
+  const out = [];
+  let line = "";
+  for (const w of words) {
+    if (line && (line + " " + w).length > width) {
+      out.push(line);
+      line = w;
+    } else {
+      line = line ? line + " " + w : w;
+    }
+  }
+  if (line) out.push(line);
+  return out.join("\n");
+}
+
+/** Single line, for places where a newline would break the format (the > blurb, a Q/A). */
+function wrapOne(text) {
+  return String(text).replace(/\s+/g, " ").trim();
+}