compounding-loop 0.0.0-stage → 0.1.0

package/templates/static-site/.ai/loop-prompt.md

@@ -0,0 +1,10 @@
+You are one run of an unattended build loop for this repository. Nobody is watching. Follow CLAUDE.md exactly, especially "Unattended mode".
+
+0. Run `git checkout main && git pull --ff-only`. Every commit in this run goes to `main` and is pushed with `git push origin main`. Never push to a `claude/` branch: the next run starts from `main` and would never see it.
+1. If `.ai/session.lock` holds a UTC time less than 90 minutes old, another session owns the repo: reply "Nothing to do" and stop. If `DONE.md` or `BLOCKED.md` exists, reply "Nothing to do" and stop.
+2. Run `npm install`, then `npx playwright install chromium`. If the download is blocked, see "Commands" in CLAUDE.md.
+3. If `.ai/task.md` exists, run the resume protocol (.ai/method.md §9.2) and add 1 to its `Run: N / 30` counter. If the counter has reached its limit, follow "Run budget" in CLAUDE.md. Otherwise start the task from IDEA.md.
+4. Do one unit of work, then run `npm test`.
+5. Green: commit, have a reviewer subagent check the diff, fix any blockers, run `npm test` again, then push to `main`. Red: write the attempt and the reason under Tried in `.ai/task.md`, then discard the unit's uncommitted changes to the site and tests.
+6. Repeat 4–5 with the next unit while your context is under ~50% full.
+7. Then run the handoff (.ai/method.md §9.1): update `.ai/task.md` so a fresh run with zero memory of this one can continue at full quality. Commit it, push it to `main`, and stop.

package/templates/static-site/.ai/task.md

@@ -0,0 +1,27 @@
+# TASK: Build v1 of the site described in IDEA.md  (window 1)
+
+Run: 0 / 30
+
+## Contract
+<Window 1 writes this from IDEA.md before writing any site code.>
+- Goal:
+- Done when: `npm test` passes, including a feature test in `tests/` for every "Must have" in IDEA.md, unit tests for every file in `site/js/lib/`, and one page per keyword cluster in IDEA.md.
+- Constraints: see CLAUDE.md hard rules.
+- Out of scope: everything under "Nice to have" in IDEA.md.
+
+## Current state  (rewrite every window)
+- Fresh repo from the starter kit. Nothing built yet.
+- Next step: confirm `npm install` and `npm test` work in this environment (GUESS: Playwright's browser download may be blocked in cloud sandboxes; the config then falls back to a system Chrome. If neither works, record it under Decisions and use `npm run check && npm run unit` as the gate). Then write the contract and a plan in `.ai/plans/v1.md` (have a reviewer subagent attack the plan), then build page by page, the main tool first.
+- Read first: IDEA.md, CLAUDE.md.
+
+## Decisions  (made without the owner: decision → reason)
+
+## Confirmed  (with how we know)
+
+## Guesses  (test before building on them)
+
+## Tried  (append-only: approach → result → why)
+
+## Don't
+
+## promote?  (for the retro)

package/templates/static-site/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

package/templates/static-site/CLAUDE.md

@@ -0,0 +1,113 @@
+# CLAUDE.md
+
+## Project core
+
+**What this is:** a static niche website built by an unattended AI loop. The goal, audience and keywords are in [IDEA.md](IDEA.md). The owner's aim is organic search traffic.
+
+**Why this site can win:** in 2026 every tool niche already has 5–10 AI-built sites, most with a handful of thin, unchecked tools, abandoned after launch. This site wins on three things they skip: **depth** (the complete set of tools and answers for the niche, cross-linked), **verified correctness** (every number unit-tested against a cited source) and **honest, useful pages**. Every rule below serves one of those three.
+
+**Commands**
+- Install: `npm install`, then `npx playwright install chromium`. If Chrome then fails to launch over missing system libraries, run `npx playwright install-deps chromium`. If the browser download is blocked (it is in Claude's cloud sandbox), `playwright.config.js` automatically uses the preinstalled Chromium in `/opt/pw-browsers` or a system Chrome, so just run `npm test`. If neither works, record it under Decisions and use `npm run check && npm run unit` as the gate.
+- Run locally: `npm start` (serves `site/` at http://localhost:4173 with the production headers, read from `vercel.json`)
+- Test (the only judge of "done"): `npm test` = `check` + `unit` + browser tests
+- Fast checks only: `npm run check` (SEO, quality, security), `npm run unit` (calculation tests)
+
+**Hard rules**
+- Everything the public sees lives in `site/`. The site is hosted on Netlify, which publishes only that folder (`publish = "site"` in `netlify.toml`; `vercel.json` says the same with `"outputDirectory": "site"`), so `CLAUDE.md`, `.ai/` and `IDEA.md` stay private. Never move them into `site/` and never change `publish` or `outputDirectory`; `npm run check` fails if `outputDirectory` changes.
+- Plain HTML, CSS and ES modules, with no build step, unless IDEA.md needs something more. If it does, record the decision and the reason in `.ai/task.md` under Decisions.
+- One page per search intent: each target keyword cluster gets its own URL, `<title>`, meta description, `<h1>` and JSON-LD. Cross-link the pages. Update `site/sitemap.xml` whenever a page is added.
+- Mobile first. No horizontal scroll at 375px wide. The main tool must be usable without scrolling on a 633px-tall laptop screen.
+- Pushing to `main` publishes the site (Netlify deploys every push to `main`), and the owner has approved auto-publishing. Push only when `npm test` passes and the reviewer found no blockers (see Unattended mode).
+
+**URLs**
+- The home page is `site/index.html`. Every other page is `site/<slug>/index.html`, linked as `/<slug>/`, with canonical `https://<domain>/<slug>/`. Slugs are lowercase, hyphenated and keyword-first.
+- Use the address from IDEA.md's Domain section in every canonical, the sitemap and robots.txt. For now it's a free `<name>.netlify.app` address, because the owner hasn't bought the domain yet. Never use any other address, such as a `<hash>--<name>.netlify.app` deploy URL, a `vercel.app` address or the unbought domain. `npm run check` fails if a canonical uses a different host. Only the owner changes the address.
+- Keep any `<meta name="google-site-verification">` tag on the home page. It proves ownership to Google Search Console.
+- Never change a published URL. If you must, add a permanent (301) redirect to both `netlify.toml` (`[[redirects]]`) and `redirects` in `vercel.json`.
+
+**Correctness** (the main edge over competitors)
+- Every formula, conversion or lookup is a pure function in `site/js/lib/<topic>.js`, with no DOM access. Page scripts import it.
+- Each lib file has `tests/unit/<topic>.test.mjs` (`node:test`), and `npm run check` fails without it. Each function needs at least two reference cases taken from an authoritative source: a manufacturer, a standards body, a textbook or a well-known reference chart. Put the source URL in a comment above each case. A test that only re-derives your own formula proves nothing.
+- Also test the edges: zero, empty input, unit conversion both ways, impossible inputs. The page shows a clear message for bad input, never `NaN`, `Infinity` or `undefined`.
+- Show units everywhere. Support imperial and metric when the audience uses both. Round only for display.
+
+**Facts and data**
+- Product specs, constants and reference tables go in `site/data/*.json`. Every entry has `source` (URL) and `checked` (YYYY-MM-DD). Find primary sources with WebSearch and WebFetch. If you can't verify a value, leave the entry out rather than guess.
+- In the cloud sandbox, WebFetch is blocked for most websites by the network allowlist (CONFIRMED, October 2026), but WebSearch works and its results quote the source pages. A value counts as verified when a search result from the authoritative source itself states it, or when two independent reputable sources agree. Give the entry the source's URL and `"via": "search"`. Never use a value only because it seems plausible, and don't stop the build over one unverifiable value: leave it out and move on.
+- Where real-world values vary (appliance wattage, fish adult size), say so on the page and give the typical range.
+
+**Content quality** (Google's spam policies)
+- Each page fully answers its search intent with original writing: the tool, how to use it, how it's calculated, a worked example and a short FAQ. `npm run check` requires 300+ visible words and fails pages that share more than 60% of their phrasing.
+- No doorway pages: never make pages that differ only by a swapped word. A page earns its URL with its own data, examples or advice.
+- No fake authority: no invented reviews, testimonials, user counts, "as seen on" badges or author bios, and no claims of hands-on testing.
+- Where the topic touches safety (chemicals, electricity, animal health), add the relevant safety note and point to the authoritative source.
+
+**Security**
+- `netlify.toml` and `vercel.json` send the same strict Content-Security-Policy (keep their headers identical): same-origin scripts only, no inline scripts, no inline event handlers and no iframes. `npm start` sends the same headers, so the browser tests catch violations, and `npm run check` flags them earlier.
+- Never put user input or URL parameters into `innerHTML`. Use `textContent` or build elements.
+- No runtime npm packages and no CDN scripts. The only dependencies are the dev-only test tools in `package.json`.
+
+**Design**
+- Fast: system font stack, images under 100 KB each, no layout shift.
+- Accessible: a label on every input, visible focus, AA contrast, fully usable by keyboard.
+- Remember the visitor's last inputs and units in `localStorage` (wrapped in try/catch).
+- Results print cleanly (a print stylesheet): hobby visitors print their numbers.
+
+---
+
+## Operating Card (the Compounding Loop)
+
+> The full method is in `.ai/method.md`. The § numbers point to Part B there.
+
+**Objective:** the most verified-correct results per minute of the owner's attention. Tokens are the cheapest resource. A wrong result that looks right is the most expensive one.
+
+**Start of every session**
+1. Read `.ai/index.md`. Open a knowledge entry only when it's relevant to what you're doing.
+2. If `.ai/task.md` exists, run the resume protocol (§9.2) before anything else.
+
+**Before work**
+3. Size the task. Tiny: just do it. Medium: contract + checks. Large or unclear: plan, then loop.
+4. For medium and large tasks, write the contract (§5): goal, done-when (checkable by a command), constraints, out of scope.
+
+**During work**
+5. One unit of work at a time. Run the checks after each unit. You never declare done; the checks do.
+6. Write a note the moment you learn something, marked CONFIRMED or GUESS. Don't save it for the end.
+7. After any error, search `.ai/index.md` for the error text before trying a fix.
+8. Before editing a file, check the index for entries about that path.
+9. Send reading-heavy work (search, docs, logs, review) to subagents that report back in 10 lines or fewer. Keep code-writing in one thread.
+10. Same failure twice: stop and run the stuck protocol (§9.3). Don't retry a variant.
+11. If reality contradicts the plan or contract, stop and record it (see Unattended mode). Don't silently work around it.
+12. Point to code and docs (`path:line`). Never copy them into notes.
+
+**Context**
+13. At ~50–60% context, or when a unit is done and the next one is big: run the handoff (§9.1) and end the run.
+
+**Finishing**
+14. When the checks pass, run the retro (§12), log the task and delete `.ai/task.md`.
+
+**Never**
+- Mark your own work done without the checks passing.
+- Treat a GUESS from an earlier window as fact.
+- Delete or rewrite CONFIRMED knowledge without new evidence.
+- Change this card.
+
+---
+
+## Unattended mode
+
+No human is watching. The owner reads the results later. These rules replace "ask the human":
+
+- **Git:** work on `main` and push to `main`, never to a `claude/` branch. The next run starts from `main` and would never see work left anywhere else. Start every run with `git checkout main && git pull --ff-only`. If a push is rejected, run `git pull --rebase` once and push again. If that conflicts, run `git rebase --abort`, record it under Tried, and stop.
+- **Questions:** decide using IDEA.md and common sense, write the decision and the reason under **Decisions** in `.ai/task.md`, then keep going. Pick the option that's easiest to reverse.
+- **Plan approval:** for large tasks, write the plan in `.ai/plans/`, have a reviewer subagent attack it ("what are the 3 most likely ways this plan fails?"), fix the plan, then build.
+- **Review before every push to `main`:** `npm test` must pass. Then a reviewer subagent that didn't write the code checks the diff with the brief: "Find the three most likely ways this is wrong for a real visitor, and check each one." Fix any blocker first.
+- **Stuck protocol, last step:** there's no human to ask. Write `BLOCKED.md` (what you tried, the specific question, your best guess), commit it, push it, and stop.
+- **Run budget:** `.ai/task.md` holds `Run: N / LIMIT`. Add 1 at the start of every run. When N reaches LIMIT, write `BLOCKED.md` saying "run budget reached", push it, and stop.
+- **Finished:** when every done-when in the contract passes and the reviewer finds no blockers, run the retro, write `DONE.md`, delete `.ai/task.md`, push and stop. `DONE.md` holds: what was built (each page and its target keyword), test results, anything you were unsure of, and the owner's launch checklist: check that the Netlify site serves the address in IDEA.md, add that address to Search Console as a URL-prefix property, submit `/sitemap.xml`, and buy the domain named in IDEA.md once there's budget for it. End with the 10 best next pages to build, ranked by search demand and how weak the current results are.
+- **If `DONE.md` or `BLOCKED.md` exists at the start of a run:** do nothing and stop.
+
+**Never, even if it seems helpful**
+- Spend money, sign up for anything, or create accounts.
+- Add API keys, secrets, ads, analytics or tracking code. The owner adds those later.
+- Copy text, images or code from competitor sites. Write original content and use original or properly licensed assets.
+- Force-push, rewrite git history, or touch anything outside this repository.

package/templates/static-site/IDEA.md

@@ -0,0 +1,36 @@
+# IDEA
+
+> The owner fills this in. It's the only input the loop gets, so the more specific, the better.
+
+## The site in one sentence
+<e.g. "A free online unit converter for cooks, with printable charts.">
+
+## Domain
+{{name}}.netlify.app
+
+<Free until you buy a domain. Replace it with e.g. "example.com" before launch if you can. Canonical URLs use it, and moving domains later costs rankings.>
+
+## Who it's for
+<e.g. "Home cooks who want quick, reliable conversions while following a recipe.">
+
+## Target keywords (from my research)
+| Keyword | Monthly searches | Difficulty | Page it belongs on |
+|---|---|---|---|
+| <unit converter> | <…> | <…> | / |
+| <…> | | | |
+
+## Must have (v1)
+- <the main tool or feature>
+- <…>
+
+## Nice to have (only after v1 is live)
+- <…>
+
+## Look and feel
+<e.g. "Dark, fast, minimal. Like a clean reference sheet.">
+
+## Competitors to beat (for reference only, never copy them)
+- <url>: <what they do badly>
+
+## Run budget
+30

package/templates/static-site/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+test-results/
+playwright-report/
+.env*
+.ai/runs.jsonl
+.ai/session.lock

package/templates/static-site/netlify.toml

@@ -0,0 +1,14 @@
+# Netlify hosting: publish only site/ (CLAUDE.md, IDEA.md and .ai/ stay private).
+# Headers must match vercel.json, which scripts/serve.mjs uses for local tests.
+[build]
+  publish = "site"
+  command = ""
+
+[[headers]]
+  for = "/*"
+  [headers.values]
+    Content-Security-Policy = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'"
+    X-Content-Type-Options = "nosniff"
+    Referrer-Policy = "strict-origin-when-cross-origin"
+    Permissions-Policy = "camera=(), microphone=(), geolocation=(), payment=(), usb=()"
+    X-Frame-Options = "DENY"

package/templates/static-site/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "{{name}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node scripts/serve.mjs",
+    "check": "node scripts/check.mjs",
+    "unit": "node --test \"tests/unit/**/*.test.mjs\"",
+    "test": "node scripts/test.mjs"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.48.0"
+  }
+}

package/templates/static-site/playwright.config.js

@@ -0,0 +1,27 @@
+import { defineConfig, devices, chromium } from '@playwright/test';
+import { existsSync, readdirSync } from 'node:fs';
+
+// Cloud sandboxes can block Playwright's own browser download. If that browser is missing, use a preinstalled
+// Playwright Chromium (Claude's cloud VMs have one in /opt/pw-browsers) or a system Chrome.
+const bundled = (() => { try { return chromium.executablePath(); } catch { return ''; } })();
+const preinstalled = ['/opt/pw-browsers', `${process.env.HOME}/.cache/ms-playwright`].flatMap((dir) => {
+  try {
+    return readdirSync(dir).filter((d) => /^chromium-\d+$/.test(d)).sort((a, b) => b.localeCompare(a, 'en', { numeric: true }))
+      .flatMap((d) => [`${dir}/${d}/chrome-linux64/chrome`, `${dir}/${d}/chrome-linux/chrome`]);
+  } catch { return []; }
+});
+const systemChrome = [process.env.CHROME_PATH, ...preinstalled, '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/opt/google/chrome/chrome']
+  .find((p) => p && existsSync(p));
+const launchOptions = bundled && existsSync(bundled) ? {} : systemChrome ? { executablePath: systemChrome } : {};
+
+export default defineConfig({
+  testDir: 'tests',
+  testIgnore: 'unit/**',
+  timeout: 20_000,
+  use: { baseURL: 'http://localhost:4173', launchOptions },
+  webServer: { command: 'npm start', url: 'http://localhost:4173', reuseExistingServer: true },
+  projects: [
+    { name: 'laptop', use: { ...devices['Desktop Chrome'], viewport: { width: 1366, height: 633 } } },
+    { name: 'phone', use: { ...devices['Pixel 7'] } },
+  ],
+});

package/templates/static-site/scripts/check.mjs

@@ -0,0 +1,188 @@
+// Fast structural, SEO, quality and security checks for everything in site/. No dependencies, no browser.
+// Every failure message says how to fix it, because the agent reads them at exactly the right moment.
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative, dirname, resolve, sep, basename } from 'node:path';
+
+const SITE = resolve(process.argv[2] ?? 'site');
+const ROOT = dirname(SITE);
+const MIN_WORDS = 300; // visible words per page; thin pages don't rank and invite "scaled content" penalties
+const MAX_SIMILARITY = 0.6; // share of 5-word phrases two pages may have in common
+const errors = [];
+const fail = (file, msg) => errors.push(`${file}: ${msg}`);
+
+function walk(dir) {
+  return readdirSync(dir).flatMap((name) => {
+    const p = join(dir, name);
+    return statSync(p).isDirectory() ? walk(p) : [p];
+  });
+}
+
+if (!existsSync(SITE)) {
+  console.error(`No ${SITE} folder. Put every public file in site/ (Vercel publishes only that folder).`);
+  process.exit(1);
+}
+
+const files = walk(SITE);
+const rel = (p) => relative(SITE, p).split(sep).join('/');
+const pages = files.filter((f) => f.endsWith('.html'));
+
+// Private files must never be published.
+for (const f of files) {
+  if (/(^|\/)(CLAUDE\.md|IDEA\.md|DONE\.md|BLOCKED\.md|\.ai\/|\.env)/.test(rel(f))) {
+    fail(rel(f), 'private file inside site/. Move it out: site/ is served publicly.');
+  }
+}
+
+// Secrets must never be committed anywhere public.
+const SECRET = /(\bsk-(ant-)?[A-Za-z0-9_-]{20,}|\bAKIA[0-9A-Z]{16}|\bAIza[0-9A-Za-z_-]{35}|\bgh[pousr]_[A-Za-z0-9]{30,}|\bxox[baprs]-[A-Za-z0-9-]{10,}|-----BEGIN [A-Z ]*PRIVATE KEY-----)/;
+for (const f of files) {
+  if (!/\.(html|js|mjs|css|json|txt|xml|svg|webmanifest)$/.test(f)) continue;
+  if (SECRET.test(readFileSync(f, 'utf8'))) fail(rel(f), 'looks like it contains an API key or private key. Remove it; secrets never go in site/.');
+}
+
+if (pages.length === 0) fail('site/', 'no HTML pages. Build site/index.html first.');
+
+const canonicals = [];
+const titles = new Map();
+const shingles = new Map();
+
+const visibleText = (html) =>
+  html
+    .replace(/<(script|style|noscript|svg|template)[\s\S]*?<\/\1>/gi, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&[a-z#0-9]+;/gi, ' ')
+    .toLowerCase()
+    .split(/[^a-z0-9%°]+/)
+    .filter(Boolean);
+
+for (const page of pages) {
+  const name = rel(page);
+  const html = readFileSync(page, 'utf8');
+  const one = (re) => html.match(re)?.[1]?.trim();
+  const isErrorPage = /^404\.html$/.test(name);
+
+  if (!/<html[^>]*\slang="[a-z-]+"/i.test(html)) fail(name, 'add a lang attribute: <html lang="en">.');
+  if (!/<meta[^>]+name="viewport"/i.test(html)) fail(name, 'add <meta name="viewport" content="width=device-width, initial-scale=1">.');
+
+  const title = one(/<title>([^<]*)<\/title>/i);
+  if (!title) fail(name, 'add a <title> containing the page\'s main keyword.');
+  else if (title.length < 10 || title.length > 65) fail(name, `<title> is ${title.length} chars; keep it 10–65 so Google shows it whole.`);
+  else if (titles.has(title)) fail(name, `<title> duplicates ${titles.get(title)}. Each page needs its own.`);
+  else titles.set(title, name);
+
+  if (/lorem ipsum|REPLACE_ME|\bTODO\b/i.test(html)) fail(name, 'contains placeholder text (lorem ipsum, REPLACE_ME or TODO). Write the real content.');
+
+  // Security: the CSP in vercel.json only allows same-origin scripts, so these would break in production anyway.
+  for (const [tag] of html.matchAll(/<script\b[^>]*>/gi)) {
+    if (/type="application\/ld\+json"/i.test(tag)) continue;
+    const src = tag.match(/\ssrc="([^"]+)"/i)?.[1];
+    if (!src) fail(name, 'inline <script> code. Move it to a .js file in site/ and load it with <script type="module" src="...">; the CSP blocks inline scripts.');
+    else if (/^(https?:)?\/\//i.test(src)) fail(name, `third-party script "${src}". Self-host it in site/ (or leave it out); ads and analytics are the owner's call.`);
+  }
+  if (/<iframe\b/i.test(html)) fail(name, 'contains an <iframe>. Embeds load third-party code; leave them out.');
+  if (/\son[a-z]+\s*=\s*["']/i.test(html.replace(/<script[\s\S]*?<\/script>/gi, ''))) fail(name, 'inline event handler (onclick="..." etc.). Use addEventListener in a .js file; the CSP blocks inline handlers.');
+
+  // Internal links and assets must exist.
+  for (const [, url] of html.matchAll(/(?:href|src)="([^"#?]+)[^"]*"/gi)) {
+    if (/^(https?:|mailto:|tel:|data:|\/\/)/i.test(url)) continue;
+    let target = url.startsWith('/') ? join(SITE, url) : join(dirname(page), url);
+    if (url.endsWith('/')) target = join(target, 'index.html');
+    if (!existsSync(target) && !existsSync(`${target}.html`)) fail(name, `broken link or asset "${url}". Create the file or fix the path.`);
+  }
+
+  if (isErrorPage) continue; // 404 needs no SEO tags, canonical or sitemap entry
+
+  const desc = one(/<meta[^>]+name="description"[^>]+content="([^"]*)"/i);
+  if (!desc) fail(name, 'add <meta name="description" content="..."> (70–160 chars, written for searchers).');
+  else if (desc.length < 70 || desc.length > 160) fail(name, `meta description is ${desc.length} chars; keep it 70–160.`);
+
+  const h1s = html.match(/<h1[\s>]/gi)?.length ?? 0;
+  if (h1s !== 1) fail(name, `has ${h1s} <h1> elements; use exactly one, containing the main keyword.`);
+
+  const canonical = one(/<link[^>]+rel="canonical"[^>]+href="([^"]+)"/i);
+  if (!canonical) fail(name, 'add <link rel="canonical" href="https://<domain>/<path>"> with the full URL.');
+  else if (!/^https:\/\//.test(canonical)) fail(name, `canonical "${canonical}" must be an absolute https:// URL.`);
+  else canonicals.push(canonical);
+
+  if (!/<script[^>]+type="application\/ld\+json"/i.test(html)) fail(name, 'add JSON-LD structured data (WebApplication, FAQPage or BreadcrumbList).');
+
+  // Quality: enough original text, and not a near-copy of another page.
+  const words = visibleText(html);
+  if (words.length < MIN_WORDS) fail(name, `only ${words.length} visible words; write at least ${MIN_WORDS} (how to use it, how it's calculated, worked example, FAQ).`);
+  const set = new Set();
+  for (let i = 0; i + 5 <= words.length; i++) set.add(words.slice(i, i + 5).join(' '));
+  shingles.set(name, set);
+}
+
+// Near-duplicate pages (the classic programmatic-SEO failure).
+const named = [...shingles.entries()].filter(([, s]) => s.size > 50);
+for (let i = 0; i < named.length; i++) {
+  for (let j = i + 1; j < named.length; j++) {
+    const [a, sa] = named[i];
+    const [b, sb] = named[j];
+    let shared = 0;
+    for (const s of sa) if (sb.has(s)) shared++;
+    const similarity = shared / Math.min(sa.size, sb.size);
+    if (similarity > MAX_SIMILARITY) {
+      fail(a, `${Math.round(similarity * 100)}% of its 5-word phrases also appear in ${b}. Rewrite one of them with page-specific content, or merge them into one page. Keep shared nav and footer text short so it does not dominate.`);
+    }
+  }
+}
+
+// One domain everywhere.
+const origins = new Set(canonicals.map((c) => new URL(c).origin));
+if (origins.size > 1) fail('site/', `canonicals use ${origins.size} different domains (${[...origins].join(', ')}). Use the one domain from IDEA.md everywhere.`);
+// ...and it is the address in IDEA.md's Domain section (the first word under the heading).
+const ideaPath = join(ROOT, 'IDEA.md');
+const host = existsSync(ideaPath) ? readFileSync(ideaPath, 'utf8').match(/^## Domain[^\n]*\n+([a-z0-9_-]+(?:\.[a-z0-9_-]+)+)/im)?.[1].toLowerCase() : null;
+if (host) {
+  if (!host.split('.').every((l) => /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(l))) fail('IDEA.md', `the Domain "${host}" is not a valid hostname (letters, digits and hyphens only, no leading or trailing hyphen, 63 characters per part). Fix it here and in every canonical.`);
+  for (const o of origins) if (o !== `https://${host}`) fail('site/', `canonicals use ${o}, but IDEA.md's Domain section says https://${host}. Use that address in every canonical, sitemap.xml and robots.txt.`);
+  const robots = existsSync(join(SITE, 'robots.txt')) ? readFileSync(join(SITE, 'robots.txt'), 'utf8') : '';
+  if (robots && !robots.includes(`Sitemap: https://${host}/sitemap.xml`)) fail('robots.txt', `its Sitemap line must be "Sitemap: https://${host}/sitemap.xml".`);
+}
+
+// Hosting: vercel.json publishes only site/ and sends the security headers.
+let vercel = null;
+try { vercel = JSON.parse(readFileSync(join(ROOT, 'vercel.json'), 'utf8')); } catch { /* reported below */ }
+if (!vercel) fail('vercel.json', 'missing or not valid JSON. It must set "outputDirectory": "site" and send the security headers (copy it from the starter kit).');
+else {
+  if (vercel.outputDirectory !== 'site') fail('vercel.json', '"outputDirectory" must be "site". Anything else publishes private files such as CLAUDE.md and IDEA.md.');
+  const sent = (vercel.headers ?? []).find((r) => r.source === '/(.*)')?.headers?.map((h) => h.key) ?? [];
+  for (const h of ['Content-Security-Policy', 'X-Content-Type-Options', 'Referrer-Policy', 'X-Frame-Options']) {
+    if (!sent.includes(h)) fail('vercel.json', `the "/(.*)" headers rule must send ${h}.`);
+  }
+}
+
+// Netlify is the live host: netlify.toml must publish only site/ and send the same CSP.
+const toml = existsSync(join(ROOT, 'netlify.toml')) ? readFileSync(join(ROOT, 'netlify.toml'), 'utf8') : '';
+if (!/^\s*publish\s*=\s*"site\/?"\s*$/m.test(toml)) fail('netlify.toml', 'missing, or does not set publish = "site". Anything else publishes private files such as CLAUDE.md and IDEA.md.');
+else if (!toml.includes('Content-Security-Policy')) fail('netlify.toml', 'must send the same security headers as vercel.json (copy it from the starter kit).');
+
+// Sitemap and robots.
+const sitemapPath = join(SITE, 'sitemap.xml');
+if (!existsSync(sitemapPath)) fail('sitemap.xml', 'missing. List every page\'s canonical URL in site/sitemap.xml.');
+else {
+  const sitemap = readFileSync(sitemapPath, 'utf8');
+  for (const c of canonicals) if (!sitemap.includes(`<loc>${c}</loc>`)) fail('sitemap.xml', `missing <loc>${c}</loc>. Every page must be listed.`);
+  for (const [, loc] of sitemap.matchAll(/<loc>([^<]+)<\/loc>/g)) if (!canonicals.includes(loc)) fail('sitemap.xml', `lists ${loc}, but no page has that canonical. Remove it or fix the page's canonical.`);
+}
+const robotsPath = join(SITE, 'robots.txt');
+if (!existsSync(robotsPath) || !/^Sitemap:\s*https:\/\//im.test(readFileSync(robotsPath, 'utf8'))) {
+  fail('robots.txt', 'missing, or has no "Sitemap: https://<domain>/sitemap.xml" line.');
+}
+
+// Correctness: every calculation module has unit tests.
+const libDir = join(SITE, 'js', 'lib');
+if (existsSync(libDir)) {
+  for (const f of walk(libDir).filter((p) => /\.m?js$/.test(p))) {
+    const test = join(ROOT, 'tests', 'unit', basename(f).replace(/\.m?js$/, '.test.mjs'));
+    if (!existsSync(test)) fail(rel(f), `has no unit tests. Create tests/unit/${basename(test)} with reference values from a cited source (see CLAUDE.md "Correctness").`);
+  }
+}
+
+if (errors.length) {
+  console.error(`check: ${errors.length} problem(s)\n- ${errors.join('\n- ')}`);
+  process.exit(1);
+}
+console.log(`check: OK (${pages.length} page(s))`);

package/templates/static-site/scripts/serve.mjs

@@ -0,0 +1,44 @@
+// Serves site/ the way Vercel does (folder URLs, trailing-slash redirects, 404.html, the headers from vercel.json), so the browser
+// tests see what production sends. No dependencies.
+import { createServer } from 'node:http';
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join, extname, resolve, sep } from 'node:path';
+
+const SITE = resolve('site');
+const PORT = Number(process.env.PORT ?? 4173);
+const TYPES = {
+  '.html': 'text/html; charset=utf-8', '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.avif': 'image/avif', '.ico': 'image/x-icon',
+  '.xml': 'application/xml', '.txt': 'text/plain; charset=utf-8', '.webmanifest': 'application/manifest+json',
+  '.woff2': 'font/woff2',
+};
+
+// Reads the headers vercel.json sends on every path (the single `"source": "/(.*)"` rule the starter uses).
+function vercelHeaders() {
+  if (!existsSync('vercel.json')) return {};
+  const rule = (JSON.parse(readFileSync('vercel.json', 'utf8')).headers ?? []).find((r) => r.source === '/(.*)');
+  return Object.fromEntries((rule?.headers ?? []).map((h) => [h.key, h.value]));
+}
+
+const isFile = (p) => existsSync(p) && statSync(p).isFile();
+const isDir = (p) => existsSync(p) && statSync(p).isDirectory();
+
+createServer((req, res) => {
+  const headers = { ...vercelHeaders(), 'Cache-Control': 'no-cache' };
+  let path;
+  try { path = decodeURIComponent(new URL(req.url, 'http://x').pathname); } catch { path = '/'; }
+  const target = resolve(join(SITE, path));
+  if (target !== SITE && !target.startsWith(SITE + sep)) { res.writeHead(400, headers).end('Bad path'); return; }
+
+  if (isDir(target) && !path.endsWith('/')) { res.writeHead(308, { ...headers, Location: `${path}/` }).end(); return; }
+  const file = [target, join(target, 'index.html'), `${target}.html`].find(isFile);
+  if (file) {
+    res.writeHead(200, { ...headers, 'Content-Type': TYPES[extname(file)] ?? 'application/octet-stream' });
+    res.end(readFileSync(file));
+    return;
+  }
+  const notFound = join(SITE, '404.html');
+  res.writeHead(404, { ...headers, 'Content-Type': 'text/html; charset=utf-8' });
+  res.end(isFile(notFound) ? readFileSync(notFound) : 'Not found');
+}).listen(PORT, () => console.log(`Serving site/ at http://localhost:${PORT}`));

package/templates/static-site/scripts/test.mjs

@@ -0,0 +1,59 @@
+// `npm test`: runs each test step in order (stopping at the first failure, like `&&`) and writes the
+// totals to .ai/last-test.json, which the Compounding Loop dashboard's "failing tests" health check reads.
+// Commit that file with your work so the dashboard sees it whichever machine ran the tests.
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Totals from test-runner output: node:test (`ℹ pass 3` or TAP `# pass 3`) and Playwright (`12 passed`, `1 failed`). */
+export function countResults(output) {
+  const plain = output.replace(/\x1b\[[0-9;]*m/g, '');
+  const sum = (re) => [...plain.matchAll(re)].reduce((n, m) => n + Number(m[1]), 0);
+  const passed = sum(/^\s*(?:ℹ|#) pass (\d+)\s*$/gm) + sum(/^\s*(\d+) passed\b/gm);
+  const failed = sum(/^\s*(?:ℹ|#) fail (\d+)\s*$/gm) + sum(/^\s*(\d+) failed\b/gm);
+  return passed + failed > 0 ? { passed, failed } : undefined;
+}
+
+/** Steps this repo has, as [label, node arguments]. Node runs them directly, so no shell or .cmd shim is involved. */
+function steps() {
+  const list = [['check', ['scripts/check.mjs']]];
+  if (existsSync('tests/unit')) list.push(['unit', ['--test', 'tests/unit/**/*.test.mjs']]);
+  if (existsSync('playwright.config.js')) list.push(['browser', [path.join('node_modules', '@playwright', 'test', 'cli.js'), 'test', ...process.argv.slice(2)]]);
+  return list;
+}
+
+function run(args) {
+  return new Promise((resolve) => {
+    let output = '';
+    const child = spawn(process.execPath, args, { stdio: ['inherit', 'pipe', 'pipe'] });
+    child.stdout.on('data', (chunk) => { output += chunk; process.stdout.write(chunk); });
+    child.stderr.on('data', (chunk) => { output += chunk; process.stderr.write(chunk); });
+    child.on('error', (error) => { output += String(error); resolve({ code: 1, output }); });
+    child.on('close', (code) => resolve({ code: code ?? 1, output }));
+  });
+}
+
+async function main() {
+  const total = { passed: 0, failed: 0 };
+  let code = 0;
+  for (const [label, args] of steps()) {
+    const result = await run(args);
+    // A step without countable output (the check script) counts as one test.
+    const counts = countResults(result.output) ?? (result.code === 0 ? { passed: 1, failed: 0 } : { passed: 0, failed: 1 });
+    if (result.code !== 0 && counts.failed === 0) counts.failed = 1;
+    total.passed += counts.passed;
+    total.failed += counts.failed;
+    if (result.code !== 0) {
+      console.error(`\n${label} failed (exit ${result.code}); later steps skipped.`);
+      code = result.code;
+      break;
+    }
+  }
+  mkdirSync('.ai', { recursive: true });
+  writeFileSync(path.join('.ai', 'last-test.json'), `${JSON.stringify({ ...total, at: new Date().toISOString() })}\n`);
+  console.log(`\n${total.passed} passed, ${total.failed} failed (written to .ai/last-test.json)`);
+  process.exitCode = code;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/templates/static-site/site/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{name}} | Free online tools</title>
+  <meta name="description" content="{{name}} is a fast, free, privacy-friendly website built and verified by an unattended Compounding Loop.">
+  <link rel="icon" href="data:,">
+  <link rel="canonical" href="https://{{name}}.netlify.app/">
+  <script type="application/ld+json">{"@context":"https://schema.org","@type":"WebSite","name":"{{name}}","url":"https://{{name}}.netlify.app/"}</script>
+</head>
+<body>
+  <main>
+  <h1>{{name}}</h1>
+  <p>This is the starting page for {{name}}. It is a small, fast, static website: plain HTML, one stylesheet and no third-party code. Every page you add lives in the site folder, and the checks that ship with this project refuse to pass until each page is complete, original and safe to publish.</p>
+  <p>The loop that builds this site works in short, verified units. It reads the brief in IDEA.md, writes a contract for the next unit of work, builds it, and runs the full test suite. Only when the checks pass does it commit and push. If a check fails, the attempt is recorded so the next run does not repeat the same mistake. Nothing counts as finished because the agent says so; it counts when a test proves it.</p>
+  <p>What the checks look at: every page needs a title, a description written for searchers, exactly one main heading, a canonical address on the domain named in the brief, structured data, and enough real text to be useful. Pages that copy each other are rejected. Links and assets must exist. Scripts must come from the same origin, because the security policy blocks everything else. Private files such as the brief and the notes folder must never end up inside the published folder.</p>
+  <p>How to use this starter: open IDEA.md and describe the site in one sentence, name the domain, list the audience and the keywords, and say what the first version must do. Then run the loop. The first run replaces this page with the real home page, adds the pages for each keyword cluster, and writes a browser test for every must-have feature, so a broken tool is caught before a visitor sees it.</p>
+  <p>Frequently asked questions. Can I edit pages by hand? Yes, the checks run the same way for people and for the loop. Does the site track visitors? No analytics, ads or tracking code are added unless the owner decides to. Where is it hosted? Any static host works; the configuration for Netlify and Vercel is included and publishes only the site folder. How do I see it locally? Run npm start and open the address it prints.</p>
+  <p>When the brief is complete and every check passes, the loop writes a short report listing what was built, what was tested, and the ten most valuable pages to build next. Replace this text with your own content as soon as the first real page exists, and keep each page focused on one question that a searcher would actually ask.</p>
+  </main>
+</body>
+</html>

package/templates/static-site/site/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://{{name}}.netlify.app/sitemap.xml

package/templates/static-site/site/sitemap.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>https://{{name}}.netlify.app/</loc></url>
+</urlset>

package/templates/static-site/tests/pages.spec.js

@@ -0,0 +1,21 @@
+// Checks every page in the sitemap in a real browser. Feature tests for the site's tools go in their own files.
+import { test, expect } from '@playwright/test';
+import { readFileSync } from 'node:fs';
+
+const paths = [...readFileSync('site/sitemap.xml', 'utf8').matchAll(/<loc>https:\/\/[^/]+(\/[^<]*)<\/loc>/g)].map((m) => m[1]);
+
+for (const path of paths) {
+  test(`${path} loads cleanly`, async ({ page }) => {
+    const problems = [];
+    page.on('pageerror', (e) => problems.push(`JS error: ${e.message}`));
+    page.on('console', (m) => m.type() === 'error' && problems.push(`console error: ${m.text()}`));
+
+    const res = await page.goto(path);
+    expect(res.status(), `${path} should return 200`).toBe(200);
+    await expect(page.locator('h1')).toBeVisible();
+
+    const overflow = await page.evaluate(() => document.documentElement.scrollWidth - window.innerWidth);
+    expect(overflow, 'page scrolls sideways: find the element wider than the screen').toBeLessThanOrEqual(0);
+    expect(problems, 'fix these errors').toEqual([]);
+  });
+}