codeply-cli 0.2.0 → 0.3.1

package/lib/typecheck-worker.js

@@ -0,0 +1,147 @@
+/**
+ * Type-checks single files with the project's own TypeScript, in a separate
+ * process so a slow first build never blocks the app. One worker per project
+ * root; it keeps a LanguageService warm, so after the first file each check
+ * only re-reads what changed.
+ *
+ * Messages in:  { id, file }            Messages out: { id, problems: string[] } | { id, error }
+ * Started with: argv[2] = project root (folder with tsconfig/jsconfig), argv[3] = typescript module path
+ */
+const fs = require('fs');
+const path = require('path');
+
+const root = process.argv[2];
+const ts = require(process.argv[3]);
+const MAX = 10;
+
+const configPath = ts.findConfigFile(root, ts.sys.fileExists, 'tsconfig.json') || ts.findConfigFile(root, ts.sys.fileExists, 'jsconfig.json');
+let options = { allowJs: true, noEmit: true, skipLibCheck: true };
+let fileNames = [];
+if (configPath) {
+  const cfg = ts.readConfigFile(configPath, ts.sys.readFile);
+  const parsed = ts.parseJsonConfigFileContent(cfg.config || {}, ts.sys, path.dirname(configPath));
+  options = { ...parsed.options, noEmit: true };
+  fileNames = parsed.fileNames;
+}
+const extra = new Set(); // files checked that the config doesn't list
+
+const versions = new Map();
+const version = (f) => {
+  try { return String(fs.statSync(f).mtimeMs); } catch { return '0'; }
+};
+
+const host = {
+  getScriptFileNames: () => [...fileNames, ...extra],
+  getScriptVersion: (f) => version(f),
+  getScriptSnapshot: (f) => {
+    if (!fs.existsSync(f)) return undefined;
+    return ts.ScriptSnapshot.fromString(fs.readFileSync(f, 'utf8'));
+  },
+  getCurrentDirectory: () => root,
+  getCompilationSettings: () => options,
+  getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),
+  fileExists: ts.sys.fileExists,
+  readFile: ts.sys.readFile,
+  readDirectory: ts.sys.readDirectory,
+  directoryExists: ts.sys.directoryExists,
+  getDirectories: ts.sys.getDirectories,
+};
+const service = ts.createLanguageService(host, ts.createDocumentRegistry());
+
+function check(file) {
+  const abs = path.resolve(file);
+  const norm = abs.replace(/\\/g, '/');
+  if (!fileNames.some((f) => path.resolve(f) === abs)) extra.add(norm);
+  versions.set(abs, version(abs));
+  const diags = [...service.getSyntacticDiagnostics(norm), ...service.getSemanticDiagnostics(norm)]
+    .filter((d) => d.category === ts.DiagnosticCategory.Error);
+  return diags.slice(0, MAX).map((d) => {
+    const line = d.file && d.start != null ? d.file.getLineAndCharacterOfPosition(d.start).line + 1 : null;
+    return `${line ? `line ${line}: ` : ''}TS${d.code}: ${ts.flattenDiagnosticMessageText(d.messageText, ' ')}`;
+  });
+}
+
+// ── Code navigation (the lsp tool): definition, references, hover, symbols ──
+const rel = (f) => path.relative(root, f).replace(/\\/g, '/') || f;
+function place(fileName, start) {
+  const sf = service.getProgram().getSourceFile(fileName);
+  if (!sf) return `${rel(fileName)}`;
+  const { line, character } = sf.getLineAndCharacterOfPosition(start);
+  return `${rel(fileName)}:${line + 1}:${character + 1}`;
+}
+function lineText(fileName, start) {
+  const sf = service.getProgram().getSourceFile(fileName);
+  if (!sf) return '';
+  const { line } = sf.getLineAndCharacterOfPosition(start);
+  return sf.text.split('\n')[line].trim().slice(0, 160);
+}
+let navFile = null;
+function flattenTree(node, out, depth = 0) {
+  for (const c of node.childItems || []) {
+    const line = c.spans[0] ? navFile.getLineAndCharacterOfPosition(c.spans[0].start).line + 1 : '?';
+    if (c.kind !== 'alias') out.push(`${'  '.repeat(depth)}${c.kind} ${c.text}  (line ${line})`);
+    flattenTree(c, out, depth + 1);
+  }
+}
+
+function navigate(msg) {
+  const abs = path.resolve(msg.file || root);
+  const norm = abs.replace(/\\/g, '/');
+  if (msg.file && fs.existsSync(abs) && !fileNames.some((f) => path.resolve(f) === abs)) extra.add(norm);
+  const op = msg.op;
+  if (op === 'workspaceSymbol') {
+    const items = (service.getNavigateToItems(msg.query || '', 200) || [])
+      .filter((i) => !/[\\/]node_modules[\\/]/.test(i.fileName) && !/[\\/]typescript[\\/]lib[\\/]/.test(i.fileName))
+      .slice(0, 40);
+    return items.map((i) => `${i.kind} ${i.name}  ${place(i.fileName, i.textSpan.start)}`).join('\n') || 'No symbols match.';
+  }
+  const sf = service.getProgram().getSourceFile(norm);
+  if (!sf) return `${msg.file} is not part of a TypeScript/JavaScript project this checker can see.`;
+  if (op === 'documentSymbol') {
+    navFile = sf;
+    const out = [];
+    flattenTree(service.getNavigationTree(norm), out);
+    return out.join('\n') || 'No symbols in this file.';
+  }
+  // Position-based: 1-based line/character from the caller.
+  const lines = sf.text.split('\n');
+  const li = Math.min(Math.max((msg.line || 1) - 1, 0), lines.length - 1);
+  let col = msg.character ? msg.character - 1 : -1;
+  if (col < 0 && msg.symbol) {
+    const at = lines[li].indexOf(msg.symbol);
+    col = at >= 0 ? at : -1;
+    if (col < 0) {
+      const whole = new RegExp(`\\b${msg.symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).exec(sf.text);
+      if (whole) return navigateAt(op, norm, whole.index);
+      return `Could not find "${msg.symbol}" in ${msg.file}.`;
+    }
+  }
+  if (col < 0) col = Math.max(0, lines[li].search(/\S/));
+  const pos = sf.getPositionOfLineAndCharacter(li, col);
+  return navigateAt(op, norm, pos);
+}
+function navigateAt(op, norm, pos) {
+  if (op === 'hover') {
+    const info = service.getQuickInfoAtPosition(norm, pos);
+    if (!info) return 'No type information at that position.';
+    const sig = ts.displayPartsToString(info.displayParts);
+    const doc = ts.displayPartsToString(info.documentation);
+    return doc ? `${sig}\n\n${doc}` : sig;
+  }
+  let locs;
+  if (op === 'definition') locs = service.getDefinitionAtPosition(norm, pos) || [];
+  else if (op === 'implementation') locs = service.getImplementationAtPosition(norm, pos) || [];
+  else if (op === 'references') locs = service.getReferencesAtPosition(norm, pos) || [];
+  else return `Unknown operation "${op}".`;
+  if (!locs.length) return `No ${op} found at that position.`;
+  const shown = locs.slice(0, 40).map((l) => `${place(l.fileName, l.textSpan.start)}  ${lineText(l.fileName, l.textSpan.start)}`);
+  return `${locs.length} ${op === 'references' ? 'reference' : 'location'}${locs.length === 1 ? '' : 's'}${locs.length > 40 ? ' (first 40)' : ''}:\n${shown.join('\n')}`;
+}
+
+process.on('message', (msg) => {
+  try {
+    if (msg.op) process.send({ id: msg.id, text: navigate(msg) });
+    else process.send({ id: msg.id, problems: check(msg.file) });
+  } catch (e) { process.send({ id: msg.id, error: e.message }); }
+});
+process.send({ ready: true, hasConfig: !!configPath });

package/lib/web-tools.js

@@ -0,0 +1,158 @@
+/**
+ * Web access for the agent: fetch a page as readable text, and search the web.
+ *
+ * Search uses Exa's public MCP endpoint (the same one opencode's websearch tool
+ * talks to; no key needed) and falls back to DuckDuckGo's HTML results when
+ * Exa is unreachable. Fetching converts HTML to plain markdown-ish text so the
+ * model gets the content, not the markup.
+ */
+
+const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36 Codeply';
+const MAX_BYTES = 5 * 1024 * 1024;
+const FETCH_TIMEOUT_MS = 30000;
+const SEARCH_TIMEOUT_MS = 25000;
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', ndash: '-', mdash: '-', hellip: '...', rsquo: "'", lsquo: "'", rdquo: '"', ldquo: '"', copy: '(c)' };
+
+function decodeEntities(s) {
+  return s
+    .replace(/&#(\d+);/g, (_, n) => { try { return String.fromCodePoint(Number(n)); } catch { return ''; } })
+    .replace(/&#x([0-9a-f]+);/gi, (_, n) => { try { return String.fromCodePoint(parseInt(n, 16)); } catch { return ''; } })
+    .replace(/&([a-z]+);/gi, (m, n) => (ENTITIES[n.toLowerCase()] ?? m));
+}
+
+/** HTML -> readable text: headings, links, lists, code and paragraphs survive; the rest goes. */
+function htmlToText(html, baseUrl) {
+  let s = String(html);
+  s = s.replace(/<!--[\s\S]*?-->/g, '');
+  s = s.replace(/<(script|style|noscript|template|svg|iframe|head)\b[\s\S]*?<\/\1>/gi, '');
+  s = s.replace(/<pre\b[^>]*>([\s\S]*?)<\/pre>/gi, (_, code) => '\n```\n' + code.replace(/<[^>]+>/g, '') + '\n```\n');
+  s = s.replace(/<code\b[^>]*>([\s\S]*?)<\/code>/gi, (_, c) => '`' + c.replace(/<[^>]+>/g, '') + '`');
+  s = s.replace(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi, (_, n, t) => `\n\n${'#'.repeat(Number(n))} ${t.replace(/<[^>]+>/g, '').trim()}\n\n`);
+  s = s.replace(/<a\b[^>]*href\s*=\s*["']([^"']*)["'][^>]*>([\s\S]*?)<\/a>/gi, (_, href, t) => {
+    const label = t.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+    if (!label) return '';
+    if (!href || href.startsWith('#') || /^(javascript|mailto):/i.test(href)) return label;
+    let abs = href;
+    try { abs = new URL(href, baseUrl).href; } catch {}
+    return `[${label}](${abs})`;
+  });
+  s = s.replace(/<li\b[^>]*>/gi, '\n- ');
+  s = s.replace(/<br\s*\/?>/gi, '\n');
+  s = s.replace(/<\/(p|div|section|article|header|footer|main|nav|ul|ol|table|tr|blockquote|figure)>/gi, '\n');
+  s = s.replace(/<\/t[dh]>/gi, ' | ');
+  s = s.replace(/<[^>]+>/g, '');
+  s = decodeEntities(s);
+  s = s.replace(/[ \t\f\v]+/g, ' ').replace(/ *\n */g, '\n').replace(/\n{3,}/g, '\n\n');
+  return s.trim();
+}
+
+/**
+ * @param {string} url
+ * @param {{format?:'text'|'html'|'raw', signal?:AbortSignal, maxChars?:number}} [opts]
+ * @returns {Promise<{ok:boolean, text?:string, error?:string, status?:number, contentType?:string, finalUrl?:string}>}
+ */
+async function fetchPage(url, opts = {}) {
+  let parsed;
+  try { parsed = new URL(url); } catch { return { ok: false, error: `Not a valid URL: ${url}` }; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return { ok: false, error: 'web_fetch only supports http:// and https:// URLs.' };
+  const signals = [AbortSignal.timeout(FETCH_TIMEOUT_MS)];
+  if (opts.signal) signals.push(opts.signal);
+  let res;
+  try {
+    res = await fetch(parsed.href, {
+      redirect: 'follow',
+      signal: AbortSignal.any(signals),
+      headers: { 'User-Agent': UA, Accept: 'text/html,application/xhtml+xml,application/json,text/plain,text/markdown;q=0.9,*/*;q=0.5', 'Accept-Language': 'en-US,en;q=0.9' },
+    });
+  } catch (e) {
+    return { ok: false, error: `Could not reach ${parsed.href}: ${e.name === 'TimeoutError' ? 'timed out' : e.message}` };
+  }
+  if (!res.ok) return { ok: false, status: res.status, error: `${parsed.href} returned HTTP ${res.status}.` };
+  const contentType = (res.headers.get('content-type') || '').split(';')[0].trim().toLowerCase();
+  const declared = Number(res.headers.get('content-length') || 0);
+  if (declared > MAX_BYTES) return { ok: false, error: `The page is ${(declared / 1e6).toFixed(1)}MB, over the ${MAX_BYTES / 1e6}MB limit.` };
+  if (/^(image|video|audio)\//.test(contentType) || /^application\/(zip|octet-stream|pdf|gzip)/.test(contentType)) {
+    return { ok: false, contentType, error: `${parsed.href} is ${contentType}, not text. Use fetch_image for images or run curl to download a file.` };
+  }
+  let buf;
+  try { buf = Buffer.from(await res.arrayBuffer()); } catch (e) { return { ok: false, error: `Failed reading ${parsed.href}: ${e.message}` }; }
+  if (buf.length > MAX_BYTES) return { ok: false, error: `The page is over the ${MAX_BYTES / 1e6}MB limit.` };
+  const body = buf.toString('utf8');
+  const format = opts.format || 'text';
+  const isHtml = contentType.includes('html') || (!contentType && /^\s*<(!doctype|html)/i.test(body));
+  let text = body;
+  if (isHtml && format === 'text') text = htmlToText(body, res.url || parsed.href);
+  else if (contentType.includes('json') && format !== 'raw') {
+    try { text = JSON.stringify(JSON.parse(body), null, 2); } catch {}
+  }
+  return { ok: true, text, contentType, finalUrl: res.url || parsed.href, status: res.status };
+}
+
+// ─── Search ──────────────────────────────────────────────────────────────────
+
+async function exaSearch(query, num, signal) {
+  const signals = [AbortSignal.timeout(SEARCH_TIMEOUT_MS)];
+  if (signal) signals.push(signal);
+  const res = await fetch('https://mcp.exa.ai/mcp', {
+    method: 'POST',
+    signal: AbortSignal.any(signals),
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' },
+    body: JSON.stringify({
+      jsonrpc: '2.0', id: 1, method: 'tools/call',
+      params: { name: 'web_search_exa', arguments: { query, numResults: num, type: 'auto', livecrawl: 'fallback' } },
+    }),
+  });
+  if (!res.ok) throw new Error(`Exa returned HTTP ${res.status}`);
+  const raw = await res.text();
+  // The reply is either plain JSON or an SSE stream of "data: {...}" lines.
+  const payloads = [];
+  if (raw.trimStart().startsWith('{')) payloads.push(raw);
+  else for (const line of raw.split('\n')) if (line.startsWith('data:')) payloads.push(line.slice(5).trim());
+  for (const p of payloads) {
+    let j;
+    try { j = JSON.parse(p); } catch { continue; }
+    if (j.error) throw new Error(j.error.message || 'Exa error');
+    const text = (j.result?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('\n').trim();
+    if (text) return text;
+  }
+  throw new Error('Exa returned no results');
+}
+
+async function ddgSearch(query, num, signal) {
+  const signals = [AbortSignal.timeout(SEARCH_TIMEOUT_MS)];
+  if (signal) signals.push(signal);
+  const res = await fetch('https://html.duckduckgo.com/html/', {
+    method: 'POST',
+    signal: AbortSignal.any(signals),
+    headers: { 'User-Agent': UA, 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: `q=${encodeURIComponent(query)}`,
+  });
+  if (!res.ok) throw new Error(`DuckDuckGo returned HTTP ${res.status}`);
+  const html = await res.text();
+  const out = [];
+  const re = /<a[^>]+class="result__a"[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?(?:<a[^>]+class="result__snippet"[^>]*>([\s\S]*?)<\/a>)?/gi;
+  let m;
+  while ((m = re.exec(html)) && out.length < num) {
+    let href = decodeEntities(m[1]);
+    const u = /[?&]uddg=([^&]+)/.exec(href);
+    if (u) { try { href = decodeURIComponent(u[1]); } catch {} }
+    const title = decodeEntities(m[2].replace(/<[^>]+>/g, '')).trim();
+    const snippet = decodeEntities((m[3] || '').replace(/<[^>]+>/g, '')).trim();
+    if (title && /^https?:/.test(href)) out.push(`Title: ${title}\nURL: ${href}${snippet ? `\n${snippet}` : ''}`);
+  }
+  if (!out.length) throw new Error('DuckDuckGo returned no results');
+  return out.join('\n\n');
+}
+
+/** @returns {Promise<{ok:boolean, text?:string, error?:string, via?:string}>} */
+async function webSearch(query, opts = {}) {
+  const num = Math.min(Math.max(Number(opts.num) || 8, 1), 20);
+  const errors = [];
+  try { return { ok: true, text: await exaSearch(query, num, opts.signal), via: 'exa' }; } catch (e) { errors.push(e.message); }
+  if (opts.signal?.aborted) return { ok: false, error: 'Search cancelled.' };
+  try { return { ok: true, text: await ddgSearch(query, num, opts.signal), via: 'duckduckgo' }; } catch (e) { errors.push(e.message); }
+  return { ok: false, error: `Web search failed (${errors.join('; ')}).` };
+}
+
+module.exports = { fetchPage, webSearch, htmlToText };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codeply-cli",
-  "version": "0.2.0",
-  "description": "Codeply from the terminal — an interactive AI coding agent, or a single apply <instruction> --file <path> command.",
+  "version": "0.3.1",
+  "description": "Codeply from the terminal: an interactive AI coding agent, a local server (codeply serve), and a GitHub agent that runs in your own Actions runner.",
   "main": "bin/codeply.js",
   "bin": {
     "codeply": "bin/codeply.js"
@@ -9,7 +9,8 @@
   "files": [
     "bin",
     "lib",
-    "skills"
+    "skills",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "engines": {
     "node": ">=18"

package/skills/premium-web-design/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: premium-web-design
+description: Codeply's default visual bar for any website, landing page, or UI it generates — vanilla HTML/CSS/JS techniques (type, color, depth, scroll-triggered motion, subtle 3D) that make even a trivial brief (a tea shop, a local plumber, a one-page portfolio) read as an expensive, art-directed build instead of a templated AI scaffold. Use for every "build me a website / page / landing site" request, no matter how small the business sounds — small brief is not license for a flat result.
+metadata:
+  origin: codeply
+---
+
+# Premium Web Design
+
+The gap between "a website" and "a website that looks like it cost $10k" is not
+more content. It is five things done deliberately instead of by default: type,
+color, depth, motion, and restraint. This skill is the checklist that turns a
+plain-HTML brief — a tea shop, a barber, a two-person agency — into something
+that reads as art-directed. Apply it **even when the user's request is one
+sentence and sounds trivial.** The size of the brief is not license for a flat
+result; a tea shop site gets the same craft pass as a SaaS landing page.
+
+## When to Use
+
+Any time you are about to write or restyle HTML/CSS for a page a human will
+look at: landing pages, marketing sites, portfolios, small-business sites,
+dashboards, docs, artifacts. If the deliverable renders in a browser and has
+no explicit "keep it minimal/utilitarian" instruction from the user, this
+skill applies by default — do not wait to be asked for "premium" or
+"animated."
+
+## The Five Levers
+
+### 1. Type — pick a pairing, not a default
+
+Never ship `system-ui` / Arial as the whole identity. Pick ONE deliberate
+pairing and commit:
+- Editorial: a serif display (Fraunces, Playfair Display, Instrument Serif) +
+  a clean grotesk body (Inter, General Sans, Geist).
+- Technical/modern: one variable grotesk (Inter, Geist, Söhne-alike) at two
+  weights, huge size contrast between hero and body.
+- Warm/local business (cafés, shops, studios): a humanist serif or friendly
+  display headline + a quiet sans body — avoid corporate SaaS grotesk here,
+  it reads generic for a tea shop.
+
+Rules: headline sizes should feel oversized relative to instinct (clamp with
+`clamp(2.5rem, 6vw, 5.5rem)`), line-height tight on display type (1.0–1.1),
+loose on body (1.5–1.7), and letter-spacing slightly negative on large type
+(`-0.02em` to `-0.04em`). Import via `@font-face`/Google Fonts `<link>` —
+never leave it at the browser default.
+
+### 2. Color — a system, not a palette guess
+
+Ban: purple-to-blue gradient hero, pure `#000`/`#fff` with a single accent
+blue, "AI slop" default (indigo #6366f1 / violet #8b5cf6 on white cards).
+Instead build a small token system from the domain:
+- 1 base neutral (often warm, not pure gray — `#f7f4ee`, `#111014`)
+- 1 ink color for text (rarely pure black — try a near-black with a hue lean)
+- 1–2 brand colors pulled from the actual subject (a tea shop: terracotta,
+  moss, cream, not tech-blue)
+- 1 accent used sparingly (links, one CTA, one highlight) — not on every card
+
+Define them as CSS custom properties on `:root` and reuse everywhere; that
+alone makes a page look designed instead of assembled.
+
+### 3. Depth — layered, not flat-card-grid
+
+Avoid the default "grid of identical white cards with a drop-shadow" — it is
+the single most recognizable AI-generated-site tell. Instead:
+- Vary section backgrounds (alternate base/ink/tinted sections) so the page
+  has rhythm when you scroll, not one long white column.
+- Use large background shapes, subtle grain/noise texture, or a soft radial
+  glow behind hero content instead of a flat solid fill.
+- Layer real photography or generated imagery behind translucent panels
+  (`backdrop-filter: blur(16px)`, semi-opaque background) for a glass feel
+  where it fits the brand — skip it for utilitarian dashboards.
+- Give the hero one asymmetric or oversized element (an oversized product
+  shot bleeding off-canvas, an angled image, a big pull-quote) instead of
+  centered text + centered image every time.
+
+**Imagery must be on-topic, not just present.** A hero image is worse than no
+image if it's unrelated to the subject — a beach photo on a tea brand's
+"Our Heritage" section reads as more broken than a placeholder color block,
+because it actively contradicts the copy next to it. When fetching stock
+imagery with `fetch_image`, use a keyword-searchable source
+(`https://loremflickr.com/<w>/<h>/<keyword1>,<keyword2>`) and pick keywords
+per-section from that section's actual subject — never a fully-random source
+like picsum.photos on a themed site. A tea shop's hero gets `tea,leaves` or
+`teapot,ceremony`, a product card for oolong gets `oolong,tea`, not one
+generic keyword reused everywhere or no keyword at all. If no source can be
+made reliably on-topic for a given spot (an odd or very specific subject),
+prefer a solid-color/gradient placeholder panel over a wrong photo, and say
+so to the user.
+
+### 4. Motion — scroll-triggered, physical, restrained
+
+A static page reads cheap even with good type/color. Add motion with plain
+CSS/JS (no framework required):
+
+```css
+.reveal { opacity: 0; transform: translateY(24px); transition: opacity .7s cubic-bezier(.16,1,.3,1), transform .7s cubic-bezier(.16,1,.3,1); }
+.reveal.is-visible { opacity: 1; transform: translateY(0); }
+@media (prefers-reduced-motion: reduce) { .reveal { transition: none; opacity: 1; transform: none; } }
+```
+
+```js
+const io = new IntersectionObserver((entries) => {
+  for (const e of entries) if (e.isIntersecting) e.target.classList.add('is-visible');
+}, { threshold: 0.15 });
+document.querySelectorAll('.reveal').forEach((el) => io.observe(el));
+```
+
+Layer in: a subtle parallax on the hero image (`transform: translateY()`
+tied to scroll position, small range like 20–40px), a hover tilt on cards
+(`transform: perspective(800px) rotateX() rotateY()` from pointer position,
+a cheap but convincing "3D" feel), and a smooth `scroll-behavior: smooth` for
+anchor nav. Stagger reveal delays across siblings (`transition-delay` +
+`nth-child`) instead of everything fading in at once — staggering is what
+makes a section feel choreographed rather than triggered.
+
+Always respect `prefers-reduced-motion`. Keep transitions 200–700ms;
+snappy for hover/press, slower for scroll reveals.
+
+### 5. Restraint — the difference between premium and busy
+
+- One hero move, one card-hover move, one scroll-reveal pattern — reused
+  consistently, not five different animation styles competing.
+  `frontend-design-direction` has the anti-pattern list (no cards-in-cards,
+  no gradient blobs, no vague hero copy) — use_skill it too on larger builds.
+- Whitespace is a design choice, not leftover space: generous section
+  padding (`clamp(4rem, 10vw, 8rem)` vertical), generous gaps in grids.
+  Cramped sections are the second most common AI-slop tell after flat cards.
+- Real, specific copy beats generic copy: name the actual product (single-
+  origin oolong, not "our amazing products"), and if there's no CMS/content
+  yet, write copy that sounds like this specific business, not a template.
+
+## Quick Pre-Ship Checklist
+
+- Is there a real font pairing, or did I leave system defaults?
+- Is the palette pulled from the subject, or is it default-AI indigo/violet?
+- Does the hero have one asymmetric/oversized visual idea, or is everything
+  centered and evenly sized?
+- Does anything move on scroll or hover, or is the page fully static?
+- Are sections visually differentiated (background/rhythm), or one flat
+  white column of same-size cards?
+- Would this specific business (a tea shop, not "a company") recognize
+  itself in the copy and color choices?
+
+If any answer is "no," the build is not done — go back and apply the lever
+before calling it finished.
+
+## Related Skills
+
+- `frontend-design-direction` — direction-setting discipline (purpose,
+  audience, tone, anti-patterns) for larger or more product-y builds.
+- `motion-ui`, `motion-foundations`, `motion-patterns` — deeper motion system
+  for React/Next.js projects specifically (this skill's motion section is the
+  framework-free equivalent for plain HTML/CSS/JS builds).
+- `frontend-a11y` — accessibility pass once the visual direction is set.