human-machine-swapper 1.2.1 → 1.4.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/custom-elements.json

@@ -0,0 +1,75 @@
+{
+  "schemaVersion": "2.1.0",
+  "readme": "README.md",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/human-machine-swapper.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "customElement": true,
+          "tagName": "human-machine-swapper",
+          "name": "HumanMachineSwapper",
+          "description": "A Human / Machine pill. Machine shows the site's llms.txt, the plain-text reading written for language models, rendered in place over the page. Renders nothing at all when the site has no llms.txt to offer.",
+          "attributes": [
+            {
+              "name": "data-position",
+              "description": "Which edge the pill is fixed to.",
+              "type": { "text": "'bottom-center' | 'top-center'" },
+              "default": "'bottom-center'"
+            },
+            {
+              "name": "data-llms",
+              "description": "The machine reading to link to. 'auto' reads <link rel=\"llms\">, then probes /llms.txt and /llms-full.txt. When nothing answers, the component renders nothing and explains why in the console.",
+              "type": { "text": "'auto' | string" },
+              "default": "'auto'"
+            },
+            {
+              "name": "data-accent",
+              "description": "Accent colour for the current dot and hover state.",
+              "type": { "text": "string" },
+              "default": "'#a8f326'"
+            },
+            {
+              "name": "data-labels-human",
+              "description": "Overrides the Human label.",
+              "type": { "text": "string" },
+              "default": "'Human'"
+            },
+            {
+              "name": "data-labels-machine",
+              "description": "Overrides the Machine label.",
+              "type": { "text": "string" },
+              "default": "'Machine'"
+            }
+          ],
+          "cssProperties": [
+            {
+              "name": "--hms-top",
+              "description": "Distance from the top edge. Set this AND --hms-bottom together when overriding: a fixed box with both set and height auto stretches. Use when the site's own chrome occupies the default edge.",
+              "default": "calc(14px + env(safe-area-inset-top)) when data-position is top-center, otherwise auto"
+            },
+            {
+              "name": "--hms-bottom",
+              "description": "Distance from the bottom edge. See --hms-top.",
+              "default": "calc(20px + env(safe-area-inset-bottom)) when data-position is bottom-center, otherwise auto"
+            }
+          ],
+          "members": [],
+          "events": []
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "human-machine-swapper",
+          "declaration": {
+            "name": "HumanMachineSwapper",
+            "module": "src/human-machine-swapper.js"
+          }
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "human-machine-swapper",
-  "version": "1.2.1",
+  "version": "1.4.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,8 @@
   "files": [
     "bin",
     "src",
+    "agent",
+    "custom-elements.json",
     "llms.txt",
     "AGENTS.md",
     "README.md",
@@ -47,7 +49,8 @@
   ],
   "sideEffects": true,
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "test:wp": "php wordpress/test/generator-test.php"
   },
   "engines": {
     "node": ">=18"
@@ -57,5 +60,6 @@
   },
   "bin": {
     "human-machine-swapper": "bin/cli.mjs"
-  }
+  },
+  "customElements": "custom-elements.json"
 }