taste-lint 0.0.1 → 0.0.3

package/README.md

@@ -1,141 +1,60 @@
 <div align="center">
 
-# [taste-lint](https://github.com/mblode/taste-lint)
+# Taste Lint
 
-**Taste rules from [Agent Skills](https://github.com/mblode/agent-skills) and [Taste Training](https://blode.co/taste-training), run as a linter**
+**Catch AI slop before you ship.**
 
-Point it at Markdown, MDX, TSX or a rendered page and get findings with a severity and a probability.
+Scan your project with local checks and [Jev by TypeSafe AI](https://docs.typesafe.ai/introduction).
 
-</div>
+<p align="center">
+  <a href="https://www.npmjs.com/package/taste-lint"><img alt="npm version" src="https://img.shields.io/npm/v/taste-lint?style=flat&colorA=000000&colorB=000000" /></a>
+  <a href="https://github.com/mblode/taste-lint/blob/main/LICENSE.md"><img alt="MIT license" src="https://img.shields.io/npm/l/taste-lint?style=flat&colorA=000000&colorB=000000" /></a>
+</p>
 
-## Quickstart
+</div>
 
-Requires Node 24.11 or later. Bring your own [Vercel AI Gateway API key](https://vercel.com/docs/ai-gateway/authentication-and-byok/api-keys): open **AI Gateway → API Keys → Create Key** in your Vercel dashboard.
+## Install
 
 ```bash
 npm install -g taste-lint
-export AI_GATEWAY_API_KEY="your-vercel-ai-gateway-key"
-
-# Run from your project directory
-taste-lint scan .
-```
-
-No taste-lint account or configuration file is required. Model usage is billed to your Vercel AI Gateway account. Taste-lint reads the key from your environment and sends selected text and rule context directly to the gateway.
-
-Preview scope and estimated cost with `taste-lint scan . --dry-run`. Try local checks without a key using `taste-lint scan . --mechanical-only`. The default scan focuses on product interfaces; use `--profile writing` for documentation or `--profile instructions` for agent instructions.
-
-Semantic rules remain advisory until calibrated against independent holdout evidence. Mechanical checks can fail a run immediately.
-
-## Where the rules come from
-
-[Agent Skills](https://github.com/mblode/agent-skills) provides reusable instructions for coding agents. [Taste Training](https://blode.co/taste-training) teaches people to spot and fix problems in typography, copy, interaction, and motion. Taste-lint turns applicable guidance into repeatable checks, with source references attached to individual rules.
-
-## Example findings
-
-```text
-PASS: 161 active rules in data/rules
-
-notes.md
-[MINOR] typography-straight-quotes (p=1.00) notes.md:3:1
-    Straight quotes in rendered copy
-    2 matches: "'", "'"
-    Fix: Replace with the matching curly mark. Opening after whitespace or at the start, closing otherwise; an apostrophe is always the right single quote.
-[MINOR?] copywriting-claim-without-evidence (p=0.95) notes.md:3:1
-    Quality claimed, nothing the reader could check
-    3 matches: "fast", "powerful", "seamless"; p=0.95
-    Fix: Replace the adjective with the mechanism, the number or the standard it stands for. If none exists, cut the sentence.
-
-Units: 3  |  Rules: 161  |  Act: 1  |  Review: 4  |  Unknown: 0
-Jev: 2 requests, 0 cached answers, 7238 input tokens, $0.0003
-FAIL - 1 finding in the act band
 ```
 
-## Two answers per finding
-
-- **Severity:** how bad the finding is if real, `major` or `minor`. Set by the rule, never by the model.
-- **Band:** how sure the tool is. `act` fails the run (mechanical hits, or Jev at or above the rule's act threshold), `review` prints a note with a `?`, below that is silent.
-- **Cost:** eligible questions about one unit are batched into requests. Preview estimated cost with `--dry-run`; runs report usage and reuse cached answers. Current rates are listed in the [Vercel AI Gateway model catalog](https://vercel.com/ai-gateway/models).
-
-## Rule packs
+Requires Node 24.11 or later.
 
-- **Typography:** straight quotes, dashes, ellipses, primes and units from `typography-audit`, plus size, weight, tracking and line-height checks over resolved Tailwind classes or computed styles.
-- **Copywriting:** claims without evidence, vague errors, friction CTAs, hedges and register shifts from `docs-writing` and the ui-design copy guideline, and Every's published AI-tell checker: 19 of its 21 questions, one rule each, with phrase candidates from the MIT `cw-ai-check` skill where it has them. Not ported: `uniform_cadence` (sentence-length arithmetic) and `formatting_overuse` (needs headings and bullets a paragraph never sees). The two authorship verdicts are excluded on purpose: taste-lint reports defects, not authorship.
-- **Interaction and craft:** the static checks of `ui-design/rules` as whole-file patterns (focus traps, error and empty states, target size, i18n, lazy loading) plus the shadcn/lint class hygiene rules (raw palette colours, arbitrary values, interpolated class strings).
-- **Motion and product:** the `ui-animation` flag-on-sight table (ease-in, linear easing, transitions over 300ms, `transition-all`, entrances from scale zero, no reduced-motion variant) and the two deterministic `product-design` rules.
-
-Every rule names the file and line of the skill or lesson it came from, and `taste-lint rules list` prints tier, status and category per rule.
+## Quickstart
 
-## Rendered mode
+Create a [Vercel AI Gateway key](https://vercel.com/docs/ai-gateway/authentication-and-byok/api-keys). From your project directory, set your key and run:
 
 ```bash
-taste-lint lint --url https://example.com/pricing --selector main
-```
-
-Runs [style-capture](https://www.npmjs.com/package/style-capture) in headless Chromium and lints computed styles: real pixel sizes, line heights, weights and letter-spacing, so the typography rules judge what the reader sees rather than what the class list implies. `--capture file.json` lints a saved capture.
-
-## API
-
-```typescript
-import { runLint } from "taste-lint";
-
-const result = await runLint({ root: process.cwd(), targets: ["content"] });
-console.log(result.scorecard.byDomain, result.usage.costUsd);
+export AI_GATEWAY_API_KEY="your-vercel-ai-gateway-key"
+taste-lint scan .
 ```
 
-`runLint` takes the same options as the `lint` command and returns findings, unknowns, the scorecard and usage. `taste-lint schema` prints every command, flag and default as JSON, and `--output json` turns an error into a `{ error, code, message }` envelope on stdout.
+No account or config for taste-lint. AI checks send selected text and rule context to Vercel AI Gateway, billed to your account. Answers are cached for repeat runs.
 
-## Agent skill
+## What it checks
 
-```bash
-npx skills add mblode/taste-lint
-```
+- **Product interfaces:** copy, typography, interaction, and motion in JSX, TSX, and CSS.
+- **Writing:** Markdown, MDX, and READMEs with `--profile writing`.
+- **Agent instructions:** AGENTS.md and skills with `--profile instructions`.
 
-Installs the `taste-lint` skill for Claude Code, Codex, Cursor and OpenCode: how to read a finding, the dry-run-first workflow, and the gotchas. Source: [skills/taste-lint/SKILL.md](skills/taste-lint/SKILL.md).
+Rules draw on [Agent Skills](https://github.com/mblode/agent-skills) and [Taste Training](https://blode.co/taste-training). Local checks handle measurable rules. Jev judges meaning and returns probabilities. Uncalibrated AI rules stay advisory; active findings can fail a run.
 
-## Options
+## Useful options
 
-| Flag | Default | Description |
-| --- | --- | --- |
-| `--dry-run` |  | Plan and print units, requests and estimated cost without calling Jev |
-| `--mechanical-only` |  | Skip every Jev-backed rule; no key needed |
-| `--only <ids>` |  | Comma-separated rule ids |
-| `--exclude <globs>` |  | Comma-separated globs to skip, added to `taste-lint.config.json` |
-| `--fail-on <severity>` | `minor` | Lowest severity that fails the run |
-| `--fix` |  | Apply deterministic fixes (curly quotes, ellipsis, multiplication sign, unit spaces) to act-band findings |
-| `--output <format>` | `tty` | `tty`, `json` or `sarif` |
-| `--url <url>` |  | Lint a rendered page through style-capture |
+| Option              | What it does                                         |
+| ------------------- | ---------------------------------------------------- |
+| `--dry-run`         | Preview scope and estimated cost without model calls |
+| `--mechanical-only` | Run local checks without an API key                  |
+| `--output json`     | Save findings for scripts and agents                 |
+| `--output sarif`    | Export findings for code review tools                |
 
-`taste-lint eval` scores every rule against its labelled corpus (precision, recall, Wilson intervals, a calibration table) and `taste-lint tune` picks act thresholds from the dev split, promoting a rule only when the fixed threshold also clears the precision lower bound on an independent holdout. Both label classes, enough evaluated items, complete scoring, and source/text separation are required. `taste-lint eval coverage` reports class balance and split leakage without API calls; add `--output json` to coverage or evaluation for structured results.
+Run `taste-lint scan --help` for all options. See the [scan guide](https://github.com/mblode/taste-lint/blob/main/docs/SCANS.md), [usage reference](https://github.com/mblode/taste-lint/blob/main/docs/USAGE.md), and [changelog](https://github.com/mblode/taste-lint/blob/main/CHANGELOG.md) for more.
 
 ## License
 
 MIT
 
-## Reading a repository run
-
-The default text report summarizes scope, top rules and up to 30 examples. Use `--verbose` for the full list; every completed or incomplete run also saves a complete JSON report and prints its path. JSON v1 keeps the original grouped `findings`; `ruleFindings` preserves every rule's evidence and `coverage` counts eligible checks. `summary.failing` respects `--fail-on`, and determines the exit code together with run completeness.
-
-```bash
-taste-lint lint --root ../my-site apps/web --dry-run
-taste-lint lint --root ../my-site apps/web --progress --output json > audit.json
-```
-
-Progress goes to stderr. A fully cached run needs no API key. An incomplete report includes a retry command that reuses successful answers. Cost is reported from known usage, excluding any unreported provider billing for failures.
-
-Configuration is optional at `taste-lint.config.json` in the scan root. Its editor schema ships at `node_modules/taste-lint/data/config.schema.json`. Unknown fields and invalid types fail before evaluation. Select the scope explicitly: documentation and agent instructions remain included when you request a whole repository.
-
-```json
-{
-  "$schema": "./node_modules/taste-lint/data/config.schema.json",
-  "exclude": ["docs/archive/**"],
-  "docTypes": [
-    { "glob": "apps/web/content/writing/**/*.mdx", "type": "explanation" }
-  ]
-}
-```
-
-See [TypeSafe contracts](docs/TYPESAFE.md) and the [review-rule evaluation](docs/evaluations/blode-co-review.md) for the implementation evidence and current calibration limits.
-
-See [skill packs](docs/SKILL-PACKS.md) for repository checks, architecture policy, personal-writing context, and source discovery.
+---
 
-Use `taste-lint scan . --profile product --dry-run` to preview a focused scan. The [scan workflow](docs/SCANS.md) covers profiles, baselines, review decisions, changed-code SARIF, calibration samples, graph-tool reports, and remediation exports.
+Crafted by [<img src="https://blode.co/avatar-circle.png" width="20" align="top" alt="" />](https://blode.co) [Matthew Blode](https://blode.co)

package/data/{rules → rule-drafts}/craft/craft-affordance-mismatch.yaml

@@ -1,3 +1,4 @@
+# Disabled after real-project review: this pattern lacks evidence of a defect.
 # Ported from mblode/agent-skills skills/ui-design/rules/slop-affordance-mismatch.md by scripts/port-rules.ts.
 # Keys listed in handWritten are preserved on re-run; everything else is regenerated.
 id: craft-affordance-mismatch
@@ -20,4 +21,4 @@ mechanical:
 severity: minor
 fix:
   hint: A card lifts on hover, the cursor turns into a hand, the border brightens, and clicking does nothing. The user has already committed to the click by the time they learn it was a decoration; they click again, assume the page is broken or slow, and then trust the next hover state less. This is worse t
-status: review-only
+status: draft

package/data/{rules → rule-drafts}/craft/craft-virtualize-large-lists.yaml

@@ -1,3 +1,4 @@
+# Disabled after real-project review: this pattern lacks evidence of a defect.
 # Ported from mblode/agent-skills skills/ui-design/rules/perf-virtualize-large-lists.md by scripts/port-rules.ts.
 # Keys listed in handWritten are preserved on re-run; everything else is regenerated.
 id: craft-virtualize-large-lists
@@ -21,4 +22,4 @@ mechanical:
 severity: minor
 fix:
   hint: Large lists (roughly >50 visible items) should use virtualization/windowing. Rendering the whole dataset stalls scrolling and grows memory with the list.
-status: review-only
+status: draft

package/data/rules/typography/typography-title-case-heading.yaml

@@ -14,13 +14,13 @@ scope:
     - "**/README.md"
 unit: [heading, jsx-text, attr-string]
 mechanical:
-  # Three or more consecutive capitalised words. Proper nouns also match, so Jev decides.
-  regex: "\\b[A-Z][a-z]+(?: (?:[A-Z][a-z]+|of|the|and|for|to|a|in|on|with)){2,}\\b"
-  flags: gu
+  # Whole-label candidate: embedded capitalised names in a sentence are not Title Case.
+  regex: "^(?:[A-Z][a-z]+|of|the|and|for|to|a|in|on|with)(?: (?:[A-Z][a-z]+|of|the|and|for|to|a|in|on|with)){2,}[?!:.]?$"
+  flags: u
 question:
   context: [role]
   instructions: >-
-    The TEXT is a heading, button label, tab or field label. Return true when most of its words start with a capital letter because it is set in Title Case, not because those words are names of people, products, places or organisations. Return false when the capitals are proper nouns or acronyms, when the TEXT is a single word, or when it is an ordinary sentence with one capital at the start.
+    Evaluate capitalisation of ordinary words only. Ignore the initial word and all words belonging to a product, person, place or organisation name. An imperative followed by a product name is sentence case, even when every word begins with a capital. If the supplied text does not establish that a capitalised phrase is ordinary words rather than a name, return false. The TEXT is a heading, button label, tab or field label. Return true when most of its words start with a capital letter because it is set in Title Case, not because those words are names of people, products, places or organisations. Return false when the capitals are proper nouns or acronyms, when the TEXT is a single word, or when it is an ordinary sentence with one capital at the start.
   criteria:
     true:
       what: Ordinary words capitalised as a heading style.
@@ -34,6 +34,8 @@ question:
         - "Connect Google Drive and Microsoft Teams"
         - "Manage your team settings"
         - "New York office hours"
+        - "Open Cedar Notes"
+        - "Ask River Desk"
 thresholds: { review: 0.4, act: 0.75 }
 severity: minor
 fix:

package/dist/cli.js

@@ -10,12 +10,13 @@ import { fromMarkdown } from "mdast-util-from-markdown";
 import { gfmFromMarkdown } from "mdast-util-gfm";
 import { gfm } from "micromark-extension-gfm";
 import { parseSync } from "oxc-parser";
+import { parse as parse$1 } from "parse5";
 import { mdxFromMarkdown } from "mdast-util-mdx";
 import { mdxjs } from "micromark-extension-mdxjs";
 import { styleText } from "node:util";
 import os from "node:os";
 //#region package.json
-var version = "0.0.1";
+var version = "0.0.3";
 //#endregion
 //#region src/lib/stats.ts
 const makePRNG = (seed) => {
@@ -115,6 +116,11 @@ const calibrationTable = (pairs, buckets = 10) => Array.from({ length: buckets }
 //#endregion
 //#region src/rules/taxonomy.ts
 const CATEGORIES = [
+	{
+		domain: "seo",
+		id: "search-discovery",
+		label: "Search discovery"
+	},
 	{
 		domain: "architecture",
 		id: "repository-contracts",
@@ -2470,7 +2476,7 @@ const codeRule = (spec, module) => {
 };
 //#endregion
 //#region src/rules/code/architecture.ts
-const make$3 = (name, title, check, hint) => codeRule({
+const make$4 = (name, title, check, hint) => codeRule({
 	categoryId: "repository-contracts",
 	check,
 	hint,
@@ -2486,7 +2492,7 @@ const make$3 = (name, title, check, hint) => codeRule({
 	unit: ["source"]
 }, "src/rules/code/architecture.ts");
 const ARCHITECTURE_RULES = [
-	make$3("declared-import-boundary", "Import violates a declared module boundary", (u) => {
+	make$4("declared-import-boundary", "Import violates a declared module boundary", (u) => {
 		const boundaries = u.facts?.repository.policy?.boundaries?.filter((b) => matchesAny(u.file, [b.from]));
 		if (!boundaries?.length) return none;
 		if (!u.facts?.imports) throw new UnresolvedError(u.facts?.parseError ?? "Import facts unavailable");
@@ -2501,7 +2507,7 @@ const ARCHITECTURE_RULES = [
 		}
 		return none;
 	}, "Use the declared public interface or change the explicit architecture policy with its owner. Patterns match import specifiers and repository-relative paths for relative imports."),
-	make$3("deprecated-import", "Import uses a declared deprecated API", (u) => {
+	make$4("deprecated-import", "Import uses a declared deprecated API", (u) => {
 		const deprecated = u.facts?.repository.policy?.deprecatedImports;
 		if (!deprecated || Object.keys(deprecated).length === 0) return none;
 		if (!u.facts?.imports) throw new UnresolvedError(u.facts?.parseError ?? "Import facts unavailable");
@@ -2515,7 +2521,7 @@ const ARCHITECTURE_RULES = [
 		}
 		return none;
 	}, "Use the replacement named in the repository's deprecation contract."),
-	make$3("generated-regeneration-hint", "Declared generated file has no regeneration guidance", (u) => {
+	make$4("generated-regeneration-hint", "Declared generated file has no regeneration guidance", (u) => {
 		const generated = u.facts?.repository.policy?.generated;
 		if (!generated?.length || !matchesAny(u.file, generated)) return none;
 		const banner = u.text.split("\n").slice(0, 12).join("\n");
@@ -2638,15 +2644,16 @@ const CLASS_RULES = [
 			const classes = unit.classes ?? [];
 			const animated = classes.map(baseClass).filter((c) => c.startsWith("animate-") && c !== "animate-none");
 			if (animated.length === 0) return none;
-			return classes.some((c) => c.startsWith("motion-reduce:") || c.startsWith("motion-safe:")) ? none : hit(animated.join(" "));
+			return classes.includes("motion-reduce:animate-none") || classes.filter((c) => baseClass(c).startsWith("animate-") && baseClass(c) !== "animate-none").every((c) => c.split(":").includes("motion-safe")) ? none : hit(animated.join(" "));
 		},
-		hint: "Gate the animation with motion-safe:animate-* or pair it with motion-reduce:animate-none so users who asked for less motion get less.",
+		hint: "Check shared CSS and component policy first. If no reduced-motion handling exists, use motion-safe:animate-* or motion-reduce:animate-none.",
 		id: "motion-animate-without-reduced-motion",
 		source: {
 			line: 57,
 			path: `${ANIMATION}/live-tuning.md`
 		},
-		title: "Animation with no reduced-motion variant"
+		status: "review-only",
+		title: "Animation has no local reduced-motion guard"
 	}),
 	shadcn({
 		categoryId: "colour-system",
@@ -2680,6 +2687,30 @@ const CLASS_RULES = [
 	})
 ];
 //#endregion
+//#region src/analysis/html.ts
+const text = (node) => "value" in node ? node.value : "childNodes" in node ? node.childNodes.map(text).join("") : "";
+const htmlElements = (source) => {
+	const output = [];
+	const visit = (node, inHead = false) => {
+		const head = inHead || "tagName" in node && node.tagName === "head";
+		if ("tagName" in node && node.namespaceURI === "http://www.w3.org/1999/xhtml" && node.sourceCodeLocation && [
+			"title",
+			"meta",
+			"link",
+			"script"
+		].includes(node.tagName)) output.push({
+			attrs: Object.fromEntries(node.attrs.map((a) => [a.name, a.value])),
+			inHead: head,
+			offset: node.sourceCodeLocation.startOffset,
+			tag: node.tagName,
+			text: text(node)
+		});
+		if ("childNodes" in node) for (const child of node.childNodes) visit(child, head);
+	};
+	visit(parse$1(source, { sourceCodeLocationInfo: true }));
+	return output;
+};
+//#endregion
 //#region src/analysis/repository.ts
 const descendants = (node) => [node, ...(node.children ?? []).flatMap(descendants)];
 const nodeText = (node) => node.value ?? (node.children ?? []).map(nodeText).join("");
@@ -2763,7 +2794,8 @@ const importsFrom = (value, output) => {
 };
 const sourceFacts = (file, text, repository) => {
 	const facts = { repository };
-	if (/\.mdx?$/.test(file)) facts.document = fromMarkdown(text.replace(/^---\r?\n[\s\S]*?\r?\n---(?=\r?\n|$)/, (m) => m.replaceAll(/[^\r\n]/g, " ")), {
+	if (/\.html?$/.test(file)) facts.html = htmlElements(text);
+	if (/\.mdx?$/.test(file) || /(?:^|\/)llms(?:-full)?\.txt$/.test(file)) facts.document = fromMarkdown(text.replace(/^---\r?\n[\s\S]*?\r?\n---(?=\r?\n|$)/, (m) => m.replaceAll(/[^\r\n]/g, " ")), {
 		extensions: [gfm()],
 		mdastExtensions: [gfmFromMarkdown()]
 	});
@@ -2780,6 +2812,94 @@ const sourceFacts = (file, text, repository) => {
 	return facts;
 };
 //#endregion
+//#region src/rules/code/discovery.ts
+const at$2 = (evidence, offset = 0) => ({
+	evidence,
+	fired: true,
+	offset
+});
+const html = (u) => {
+	if (!u.facts?.html || !/<!doctype\s+html\b|<html(?:\s|>)/i.test(u.text)) throw new UnresolvedError("Needs a complete HTML document; framework metadata and fragments require rendered evidence");
+	return u.facts.html;
+};
+const make$3 = (id, title, include, source, check, hint) => codeRule({
+	categoryId: id.startsWith("seo-") ? "search-discovery" : "instruction-quality",
+	check,
+	hint,
+	id,
+	scope: {
+		exclude: [
+			"**/supabase/templates/**",
+			"**/emails/**",
+			"**/email/**"
+		],
+		include
+	},
+	source: {
+		line: 1,
+		path: `skills/${source}`,
+		repo: "mblode/agent-skills"
+	},
+	status: "review-only",
+	title,
+	unit: ["source"]
+}, "src/rules/code/discovery.ts");
+const HTML = ["**/*.html", "**/*.htm"];
+const SEO = "seo/references/audit.md";
+const LLM = "agent-ready/references/docs-afdocs.md";
+const canonical = (u) => html(u).filter((n) => n.inHead && n.tag === "link" && n.attrs.rel?.toLowerCase().split(/\s+/).includes("canonical"));
+const DISCOVERY_RULES = [
+	make$3("seo-document-title", "HTML document needs one nonempty title", HTML, SEO, (u) => {
+		const titles = html(u).filter((n) => n.inHead && n.tag === "title");
+		return titles.length !== 1 || !titles[0].text.trim() ? at$2(`Found ${titles.length} HTML head titles${titles.length === 1 ? "; title is empty" : ""}`, titles[0]?.offset) : none;
+	}, "Provide one meaningful title in the HTML head. SVG titles do not name the page."),
+	make$3("seo-empty-description", "Declared meta description is empty", HTML, SEO, (u) => {
+		const empty = html(u).find((n) => n.inHead && n.tag === "meta" && n.attrs.name?.toLowerCase() === "description" && !n.attrs.content?.trim());
+		return empty ? at$2("Empty meta description", empty.offset) : none;
+	}, "Write a page-specific description, or omit a deliberately unspecified description."),
+	make$3("seo-conflicting-canonicals", "HTML declares conflicting canonical destinations", HTML, SEO, (u) => {
+		const links = canonical(u);
+		return new Set(links.map((n) => n.attrs.href?.trim()).filter(Boolean)).size > 1 ? at$2("Multiple distinct canonical destinations", links[1].offset) : none;
+	}, "Declare a single intended canonical destination; verify the deployed URL and HTTP headers."),
+	make$3("seo-empty-canonical", "Canonical link has no destination", HTML, SEO, (u) => {
+		const empty = canonical(u).find((n) => !n.attrs.href?.trim());
+		return empty ? at$2("Canonical link has an empty or missing href", empty.offset) : none;
+	}, "Set the intended canonical URL or remove an unintended canonical declaration."),
+	make$3("seo-jsonld-syntax", "JSON-LD script is not valid JSON", HTML, SEO, (u) => {
+		for (const node of html(u).filter((n) => n.tag === "script" && n.attrs.type?.trim().toLowerCase() === "application/ld+json")) try {
+			JSON.parse(node.text);
+		} catch {
+			return at$2("JSON-LD cannot be parsed as JSON", node.offset);
+		}
+		return none;
+	}, "Fix the JSON syntax. Valid JSON alone does not establish schema validity or rich-result eligibility."),
+	make$3("seo-robots-sitemap-url", "Robots sitemap directive needs an absolute HTTP URL", ["**/robots.txt"], "seo/references/indexing-policy.md", (u) => {
+		for (const match of u.text.matchAll(/^\s*sitemap\s*:\s*([^\r\n]*)/gim)) {
+			const value = match[1].split("#")[0].trim();
+			try {
+				const url = new URL(value);
+				if (["http:", "https:"].includes(url.protocol) && url.hostname && !/\s/.test(value)) continue;
+			} catch {}
+			return at$2("Sitemap directive is not an absolute HTTP(S) URL", match.index);
+		}
+		return none;
+	}, "Use the deployed sitemap's absolute URL. Fetch it separately to verify status and content."),
+	make$3("authoring-llms-title", "Agent index must start with an H1", ["**/llms.txt"], LLM, (u) => {
+		const document = u.facts?.document;
+		if (!document) throw new UnresolvedError("Markdown structure unavailable");
+		const first = document.children?.[0];
+		return first?.type === "heading" && first.depth === 1 ? none : at$2("llms.txt does not begin with an H1");
+	}, "Start llms.txt with the site's name as an H1, then describe and link its real documentation."),
+	make$3("authoring-llms-links", "Agent index has no documentation links", ["**/llms.txt"], LLM, (u) => {
+		if (!u.facts?.document) throw new UnresolvedError("Markdown structure unavailable");
+		return descendants(u.facts.document).some((n) => ["link", "definition"].includes(n.type) && n.url?.trim()) ? none : at$2("No Markdown link destinations in llms.txt");
+	}, "Link the existing documentation pages that an agent should read."),
+	make$3("authoring-llms-size", "Agent index exceeds the recommended character budget", ["**/llms.txt"], LLM, (u) => {
+		const count = [...u.text].length;
+		return count > 5e4 ? at$2(`llms.txt contains ${count} characters; recommended maximum is 50000`) : none;
+	}, "Keep the index small and link separate documents or nested indexes.")
+];
+//#endregion
 //#region src/rules/code/documents.ts
 const at$1 = (node, evidence) => ({
 	evidence,
@@ -3088,6 +3208,14 @@ const make = (id, title, categoryId, source, check, hint) => codeRule({
 	unit: ["class-list"]
 }, "src/rules/code/skill-classes.ts");
 const SKILL_CLASS_RULES = [
+	make("motion-reduced-motion-animation", "Continuous animation explicitly targets reduced-motion users", "motion-restraint", "ui-animation/references/live-tuning.md", (u) => {
+		const found = u.classes?.find((c) => c.split(":").includes("motion-reduce") && [
+			"animate-spin",
+			"animate-ping",
+			"animate-bounce"
+		].includes(baseClass(c)));
+		return found ? hit(found) : none;
+	}, "Check the rendered reduced-motion state. Prefer a static indicator or motion-safe animation for continuous motion."),
 	make("typography-justify-without-hyphens", "Justified text explicitly disables hyphenation", "reading-comfort", "typography-audit/rules/layout-justified-text.md", (u) => {
 		const list = u.classes ?? [];
 		return list.includes("text-justify") && list.includes("hyphens-none") ? hit("text-justify with hyphens-none") : none;
@@ -3103,7 +3231,7 @@ const SKILL_CLASS_RULES = [
 		return distorted ? hit(distorted) : none;
 	}, "Use a condensed/extended font or supported width axis; inspect intentional animation transforms separately."),
 	make("motion-layout-property-transition", "Transition explicitly animates layout properties", "motion-restraint", "ui-animation/references/performance-deep-dive.md", (u) => {
-		const cls = u.classes?.find((c) => /^transition-\[(?:[^\]]*,)?(?:width|height|top|left|right|bottom|margin|padding)(?:,|\])/.test(c));
+		const cls = u.classes?.find((c) => /^transition-\[(?:[^\]]*,)?(?:width|height|top|left|right|bottom|margin|padding)(?:,|\])/.test(baseClass(c)));
 		return cls ? hit(cls) : none;
 	}, "Prefer transform/opacity for frequent motion; measure deliberate container resizing before changing it.")
 ];
@@ -3336,6 +3464,7 @@ const CODE_RULES = [
 	],
 	...CLASS_RULES,
 	...DOCUMENT_RULES,
+	...DISCOVERY_RULES,
 	...REPOSITORY_RULES,
 	...SKILL_CLASS_RULES,
 	...ARCHITECTURE_RULES
@@ -4387,6 +4516,11 @@ const extractSource = (config, file, source, repository) => {
 	return [...units, whole];
 };
 const SUPPORTED_GLOBS = [
+	"**/*.html",
+	"**/*.htm",
+	"**/llms.txt",
+	"**/llms-full.txt",
+	"**/robots.txt",
 	"**/*.md",
 	"**/*.mdx",
 	"**/*.tsx",
@@ -5412,6 +5546,7 @@ const PROFILE_NAMES = [
 	"writing",
 	"instructions",
 	"architecture",
+	"discovery",
 	"all"
 ];
 const profileFor = (name) => {
@@ -5423,6 +5558,23 @@ const profileFor = (name) => {
 		name
 	};
 	switch (name) {
+		case "discovery": return {
+			...common,
+			exclude: [
+				...artifacts,
+				"**/supabase/templates/**",
+				"**/emails/**",
+				"**/email/**"
+			],
+			include: [
+				"**/*.html",
+				"**/*.htm",
+				"**/robots.txt",
+				"**/llms.txt",
+				"**/llms-full.txt"
+			],
+			objective: "Validate static search and agent discovery artifacts"
+		};
 		case "product": return {
 			...common,
 			exclude: [
@@ -5475,6 +5627,7 @@ const profileFor = (name) => {
 };
 const profileRules = (profile, rules) => rules.filter((rule) => {
 	if (profile.name === "all") return true;
+	if (profile.name === "discovery") return rule.domain === "seo" || rule.id.startsWith("authoring-llms-");
 	if (profile.name === "architecture") return ["architecture", "dx"].includes(rule.domain);
 	if (profile.name === "instructions") return rule.domain === "authoring" || rule.id.startsWith("copywriting-document-");
 	if (profile.name === "writing") return ["copywriting", "typography"].includes(rule.domain);