human-machine-swapper 1.2.0 → 1.3.0

package/AGENTS.md

@@ -98,3 +98,9 @@ A: ...
 ## Docs
 
 <https://advancelabs.dev/human-machine-swapper>
+
+## Make this permanent in your repo
+
+Drop-in rule files for Cursor, Claude Code and Copilot are in [`agent/`](agent/README.md).
+They say the same four things this file does, in each tool's own format, so the next agent
+to touch the repo does not have to rediscover them.

package/agent/README.md

@@ -0,0 +1,31 @@
+# Drop-in rules for coding agents
+
+Copy one of these into your repo and your agent will reach for the right command instead of
+hand-editing three files and getting the guard wrong.
+
+All of them say the same four things, in each tool's own format:
+
+1. Run `npm create llms-txt` rather than editing by hand.
+2. The site needs an `llms.txt` or the pill renders nothing.
+3. `human-machine-swapper:not(:defined) { display: none }` is not optional.
+4. Read the exit code: `0` done, `1` unrecognised project, `2` needs a human.
+
+| File | Tool | Where it goes |
+| --- | --- | --- |
+| [`AGENTS.md`](../AGENTS.md) | Anything that reads AGENTS.md | repo root |
+| [`cursor.mdc`](./cursor.mdc) | Cursor | `.cursor/rules/llms-txt.mdc` |
+| [`claude-skill/SKILL.md`](./claude-skill/SKILL.md) | Claude Code | `.claude/skills/llms-txt/SKILL.md` |
+| [`copilot-instructions.md`](./copilot-instructions.md) | GitHub Copilot | `.github/copilot-instructions.md` |
+
+## Why a rules file rather than hoping
+
+An agent asked to "make this site readable by AI" will usually improvise: write an `llms.txt`
+by hand from whatever it can see, skip the discovery link, and never add the CSS guard. The
+result looks installed and is broken in a way that only shows up on a slow connection.
+
+A rules file costs four lines and removes the guessing.
+
+## Nothing here is required
+
+The component and the CLI work with no rules file at all. These exist because the cheapest
+moment to get an install right is before it happens.

package/agent/claude-skill/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: llms-txt
+description: Add or update an llms.txt for a website, and optionally a Human/Machine view pill. Use when asked to publish an llms.txt, make a site readable by AI or by language models, improve AEO or GEO or AI search visibility, or add a human/machine toggle to a site.
+---
+
+# llms.txt for a website
+
+## Run the command, do not hand-edit
+
+From the project root:
+
+```bash
+npm create llms-txt
+```
+
+That is the whole install. It detects the framework, reads the site's own routes, writes the
+file, declares it, and offers the pill. Hand-editing gets the CSS guard wrong and invents
+routes.
+
+Flags:
+
+- `--dry-run` — show every change, write nothing
+- `--no-pill` — write only the `llms.txt`, leave the markup alone
+- `--dir <path>` — run against a project elsewhere
+
+## Read the exit code before reporting success
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Done. |
+| `1` | Could not identify the project. **Nothing was changed.** Fall back to the manual install below. |
+| `2` | Written, but something needs a human. The output names it. |
+
+It also prints how many `TODO`s remain in the generated file. Say that number in your report
+rather than implying the file is finished.
+
+## Then improve the file
+
+The generated `llms.txt` is a starting point and says so in its own text. Machine view shows
+it **verbatim**, so it is literally what a model will read about this site. Offer to fill in
+the `TODO`s from what you know of the project, and never invent a fact to clear one.
+
+## If the command cannot identify the project
+
+Four things, and the last is the one people skip:
+
+1. `<link rel="llms" href="/llms.txt" />` in the head.
+2. `<script src="https://unpkg.com/human-machine-swapper" defer></script>`.
+3. `<human-machine-swapper data-position="bottom-center"></human-machine-swapper>` in the body.
+4. **This CSS, which is not optional:**
+
+```css
+human-machine-swapper:not(:defined) { display: none; }
+```
+
+Until the script loads, the browser treats the unknown element as an ordinary in-flow box,
+measures it at about 50px tall, and pushes the rest of the page down. A page cannot be styled
+by a script that has not loaded, so the host site has to declare this itself.
+
+Note the manual snippet uses the floating CDN url, which cannot carry an integrity hash. The
+command writes a **pinned** tag with a `sha384` instead, which is one more reason to prefer
+it over hand-editing.
+
+## Rules
+
+- **Never overwrite an existing `llms.txt`.** It is the site's real machine reading and beats
+  anything generated.
+- **Never add the pill to a site with no `llms.txt`.** It renders nothing by design, and the
+  change will look broken to whoever asked for it. Write the file first.
+- **Never invent routes.** If you are writing the file by hand, list only pages you have
+  confirmed exist.
+- A site's `llms.txt` is public. Do not put anything in it that is not already on the site.
+
+## What llms.txt is
+
+A plain-text file at the site root, written for language models rather than people. A
+convention, not a standard: <https://llmstxt.org>. No engine is obliged to read it.
+
+Reference: <https://advancelabs.dev/tools/llms-txt/llms.txt>

package/agent/copilot-instructions.md

@@ -0,0 +1,21 @@
+# llms.txt and the Human/Machine pill
+
+When the task is to add an `llms.txt`, make the site readable by AI, improve AEO or GEO, or
+add a Human/Machine toggle, use the command instead of editing files by hand:
+
+```bash
+npm create llms-txt
+```
+
+It detects the framework, reads the site's routes, writes the `llms.txt`, declares it, and
+offers the pill. `--no-pill` writes only the file. `--dry-run` previews.
+
+Exit codes: `0` done, `1` could not identify the project (nothing changed), `2` written but
+something needs a human.
+
+Three things that silently break a site if you do this by hand instead:
+
+1. The site must serve an `llms.txt`, or the pill renders nothing by design.
+2. `human-machine-swapper:not(:defined) { display: none; }` is required. Without it the
+   element is laid out in flow at ~50px until the script loads.
+3. Never overwrite an existing `llms.txt`.

package/agent/cursor.mdc

@@ -0,0 +1,37 @@
+---
+description: Adding an llms.txt or a Human/Machine view to this site
+globs:
+alwaysApply: false
+---
+
+# llms.txt and the Human/Machine pill
+
+When asked to add an `llms.txt`, make the site readable by AI, improve AEO/GEO, or add a
+Human/Machine toggle, run the command rather than editing files by hand:
+
+```bash
+npm create llms-txt
+```
+
+It detects the framework (Next app/pages router, Astro, SvelteKit, Nuxt, WordPress theme,
+plain HTML), reads the site's routes, writes `llms.txt`, declares it with
+`<link rel="llms">`, and offers the Human/Machine pill.
+
+Use `--no-pill` if only the file was asked for, and `--dry-run` to preview.
+
+## Read the exit code
+
+- `0` done
+- `1` could not identify the project, nothing was changed
+- `2` written, but something needs a human. Read the output.
+
+## Do not
+
+- Do not hand-write the `llms.txt` when the command can read the real routes. A file listing
+  routes that do not exist is worse than no file.
+- Do not add `<human-machine-swapper>` without
+  `human-machine-swapper:not(:defined) { display: none; }`. Until the script loads the
+  browser lays the unknown element out in flow at about 50px tall and pushes the page down.
+- Do not add the pill to a site with no `llms.txt`. It renders nothing by design, and the
+  change will look broken to whoever asked for it.
+- Do not overwrite an existing `llms.txt`. It is the site's real machine reading.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "human-machine-swapper",
-  "version": "1.2.0",
+  "version": "1.3.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",
@@ -40,6 +40,7 @@
   "files": [
     "bin",
     "src",
+    "agent",
     "llms.txt",
     "AGENTS.md",
     "README.md",

package/src/init/apply.mjs

@@ -73,18 +73,27 @@ 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>`
+  const before = source.slice(lineStart, at);
+  const indent = before.match(/^\s*/)[0];
+
+  // Indent every line of the snippet one level in from the closing tag, keeping the
+  // snippet's own relative indentation so a multi-line tag's `></script>` does not end up
   // deeper than the tag it closes.
   const body = snippet
     .split("\n")
-    .map((l) => (l.trim() ? indent + l : l))
+    .map((l) => (l.trim() ? indent + "  " + l : l))
     .join("\n");
-  return source.slice(0, lineStart) + body + "\n" + source.slice(lineStart);
+
+  // Two shapes, and getting this wrong writes broken HTML into somebody's repo.
+  //
+  // When the closing tag starts its own line, insert a line above it. When it does NOT -
+  // `<head><meta /><title>x</title></head>` all on one line - inserting "before the line"
+  // puts the tags OUTSIDE the element entirely, above <head>. That is what happened to the
+  // first Astro site this ran on. Split the line instead and keep the content inside.
+  if (before.trim() === "") {
+    return source.slice(0, lineStart) + body + "\n" + source.slice(lineStart);
+  }
+  return source.slice(0, at) + "\n" + body + "\n" + indent + source.slice(at);
 }
 
 /** Already installed? Then there is nothing to do and we say so instead of doubling up. */