awwwards-mcp 1.0.0 → 1.2.0

package/README.md

@@ -4,6 +4,8 @@ Free, open-source MCP server that gives AI agents design inspiration from
 [Awwwards](https://www.awwwards.com/) — the Mobbin-style visual reference loop,
 sourced from the web's best award-winning websites.
 
+<a href="https://github.com/INSANE0777/Awwwards-mcp"><img src="assets/demo.gif" alt="awwwards-mcp in action: search results, design DNA, motion filmstrip, band map — real tool output" width="480"></a>
+
 Your agent searches in natural language ("dark 3D portfolio sites", "soft pastel
 e-commerce"), sees **real screenshots inline**, and can pull the **design DNA**
 of any site: color palette, tech stack, design elements, award history.
@@ -22,13 +24,65 @@ of any site: color palette, tech stack, design elements, award history.
 
 ## Setup
 
+Any MCP-compatible coding agent can use awwwards-mcp — no API key, no account.
+Requires Node ≥ 22.13 (`node -v` to check). Pick your agent:
+
+**Updates**: the server checks the npm registry once a day and prints an
+stderr notice when a newer `awwwards-mcp` exists (stdout stays clean for the
+JSON-RPC channel — your agent sees the notice as a log line). Set
+`AWWWARDS_AUTO_UPDATE=1` in the server's `env` to opt into background
+self-update; restart your agent afterwards to load it. Nothing is fetched
+more than once a day and serving never waits on the check.
+
 **Claude Code**
 
 ```bash
 claude mcp add awwwards -- npx -y awwwards-mcp
 ```
 
-**Claude Desktop / Cursor / Windsurf** (`mcpServers` in the config):
+**Codex CLI** (ChatGPT desktop app and the IDE extension share this config)
+
+```bash
+codex mcp add awwwards -- npx -y awwwards-mcp
+```
+
+or in `~/.codex/config.toml` (project-scoped: `.codex/config.toml`):
+
+```toml
+[mcp_servers.awwwards]
+command = "npx"
+args = ["-y", "awwwards-mcp"]
+```
+
+**OpenCode** (`opencode.json` — note the command is an array)
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "awwwards": {
+      "type": "local",
+      "command": ["npx", "-y", "awwwards-mcp"]
+    }
+  }
+}
+```
+
+**ZCode** (`~/.zcode/cli/config.json` — note servers nest under `"mcp": { "servers": ... }`)
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "awwwards": { "command": "npx", "args": ["-y", "awwwards-mcp"], "env": {} }
+    }
+  }
+}
+```
+
+**Claude Desktop / Cursor / Windsurf / Gemini CLI / Cline / Continue** — anything
+reading the common `mcpServers` JSON shape (e.g. `~/.claude/claude_desktop_config.json`
+or `~/.gemini/settings.json`):
 
 ```json
 {
@@ -38,25 +92,58 @@ claude mcp add awwwards -- npx -y awwwards-mcp
 }
 ```
 
-Optional full-page captures:
+**Anything else** — awwwards-mcp is a plain stdio MCP server: point your client
+at `npx -y awwwards-mcp` and it works. To pin a version, use
+`npx -y awwwards-mcp@1.0.0`.
+
+**pi coding agent** has no built-in MCP by design — it uses skills and
+extensions instead. Two options:
+
+1. Install the awwwards-inspiration skill (below). pi reads skills from
+   `~/.pi/agent/skills/` or `~/.agents/skills/` (the latter is shared across
+   agents following the Agent Skills standard). The skill teaches the workflow;
+   for it to reach the live data, add an MCP-supporting pi extension, or run
+   the queries in another agent and paste results.
+2. Skip MCP entirely: ask pi to build you a small CLI wrapper around
+   awwwards.com, or use a shared skills directory (`~/.agents/skills/`) so the
+   same skill file serves pi and every other agent.
+
+Optional full-page captures (needed by `capture_live_site`,
+`analyze_page_structure`, `record_site_motion`):
 
 ```bash
 npm install -g playwright && npx playwright install chromium
 ```
 
+`record_site_motion` additionally uses ffmpeg; it resolves the `ffmpeg-static`
+package automatically if present.
+
 ## Skills
 
-This package ships an agent skill that teaches the inspiration workflow —
-search, judge from screenshots, pull design DNA, state a design direction —
-using the awwwards MCP tools. Copy it into your agent's skills directory:
+This package ships three agent skills. Any agent that follows the
+[Agent Skills standard](https://agentskills.io) can load them; copy them into
+your agent's skills directory:
 
 ```bash
 npm install awwwards-mcp
-mkdir -p ~/.claude/skills && cp -r node_modules/awwwards-mcp/skills/awwwards-inspiration ~/.claude/skills/
+mkdir -p ~/.agents/skills && cp -r node_modules/awwwards-mcp/skills/awwwards-inspiration node_modules/awwwards-mcp/skills/awwwards-doctor node_modules/awwwards-mcp/skills/awwwards-motion-study ~/.agents/skills/
 ```
 
-For ZCode, copy to `~/.zcode/skills/` instead of `~/.claude/skills/`.
-Windows: run this from Git Bash, or copy `node_modules\awwwards-mcp\skills\awwwards-inspiration` manually.
+| Skill | What it teaches |
+|-------|-----------------|
+| `awwwards-inspiration` | The inspiration loop: search, judge from screenshots, pull design DNA, state a design direction, capture/motion-first builds. |
+| `awwwards-motion-study` | The full video chain: what to record from a live site (and what to skip), frame-by-frame review (video input or tile-per-element), the motion inventory, and build verification by re-recording. |
+| `awwwards-doctor` | Repair: run `npm run doctor`, apply its fixes, re-anchor parsers after real awwwards.com drift, recover the in-flight task that surfaced the failure. |
+
+| Agent | Skills directory |
+|-------|------------------|
+| Claude Code | `~/.claude/skills/` |
+| pi | `~/.pi/agent/skills/` (also reads `~/.agents/skills/`) |
+| ZCode | `~/.zcode/skills/` |
+| Agent Skills-standard agents | `~/.agents/skills/` |
+
+Windows: run this from Git Bash, or copy
+`node_modules\awwwards-mcp\skills\awwwards-inspiration` manually.
 
 ## Indexing (recommended)
 
@@ -94,6 +181,162 @@ and content remain the property of Awwwards and the credited creators — don't
 bulk-scrape, redistribute, or republish them. If you use this commercially,
 review awwwards.com's terms yourself.
 
+## Built with awwwards-mcp: three real sites
+
+Three complete sites were built through the full inspiration loop this MCP
+enables, using nothing but the server's tools plus the shipped
+`awwwards-inspiration` skill. Each one exercised a different corner of the
+loop — and every correction the loop caught on the way became doctrine in the
+skill.
+
+> **Built in one shot, by a model that can't watch video.** All three sites
+> were built in a single prompt run on **GLM 5.3-flash** — which does not
+> support video input. The loop's motion study worked entirely from
+> frame-tiled filmstrips (ffmpeg, 1–2 fps per element) instead of watching
+> the recordings. With a video-native model, those same `get_site_elements`
+> videos and `record_site_motion` .webm files could be watched directly —
+> timing, easing and overlap read at full fidelity — and the motion-true
+> results would be better still. The skill's frame-tile doctrine is what
+> closes that gap today.
+
+**1. [Fallow Press](fallow-press/index.html)**
+([source](fallow-press/)) — a flat-2D editorial journal, direction
+**Emergence Magazine** (SOTD): pink `#FF9398` on cream and black, torn-paper
+masthead (pure CSS `clip-path`, zero WebGL), giant grotesque display over
+grayscale photography, serif-italic brand, three pages with **separate
+horizontal** projects/about pages (GSAP ScrollTrigger pin +
+`containerAnimation`).
+
+| Torn-paper masthead (home) | Horizontal gallery (Fields) | Horizontal chapters (Practices) |
+|---|---|---|
+| ![Fallow Press home — torn-paper masthead over grayscale photography](assets/fallow-home.jpg) | ![Fallow Press Fields — pinned horizontal gallery panel](assets/fallow-fields.jpg) | ![Fallow Press Practices — pink quote chapter](assets/fallow-practices.jpg) |
+
+The loop as it ran:
+
+1. `search_sites` (magazine filters) → shortlist judged from inline
+   screenshots → `get_site_details` on Emergence Magazine.
+2. **Capture before building**: `capture_live_site` + `record_site_motion`
+   on the live site *first*; full-page PNG and motion .webm kept in
+   [fallow-press/ref-motion/](fallow-press/ref-motion/) as the evidence trail.
+3. Build, then verify: full-page capture plus **panel-center pin shots** of
+   both horizontal pages (13 stops each, in
+   [fallow-press/_qa/](fallow-press/_qa/) — `capture-qa.mjs` is reusable).
+4. The pin shots caught a real bug: horizontal-panel entrances used
+   `toggleActions: "play none none reverse"`, and 100vw panels hide content
+   at midpoints on the way back — copy disappeared mid-view. Fix
+   (one-shot play entrances) is now doctrine: **full-viewport panels get
+   one-shot entrances**; QA pin shots land at panel **centers**, not uniform
+   fractions, or you photograph empty transition zones.
+
+**2. Cerebrium recreation** (`C:/Users/Afjal/cerebrium-recreation/`) — a
+fidelity-first recreation of cerebrium.ai, pixel-checked against the live
+reference: full-page captures of both sides, `analyze_page_structure` band
+compare, and SVG icon/legend fixes until the build matched the reference to
+within 1px of total page height (10,871px vs 10,870px). This is the
+**structure-before-pixels** doctrine at its strictest — band maps compared,
+never just totals.
+
+![Cerebrium recreation — full-page build capture](assets/cerebrium-build.jpg)
+
+**3. The Meridian** (`C:/Users/Afjal/editorial-site/`) — an editorial journal
+built from ORDR/Hearst references: the first build to run the whole loop
+end-to-end. `analyze_page_structure` caught a masthead band bug by comparing
+the build's band map against the reference's; the reference captures,
+motion film, and the reusable pre-scroll capture script live in
+`editorial-site/_qa/`.
+
+![The Meridian editorial journal — full-page build capture](assets/meridian-build.jpg)
+
+![The Meridian — motion filmstrip from record_site_motion](assets/meridian-filmstrip.jpg)
+
+## Skills used to build these
+
+| Skill | Role in the builds |
+|---|---|
+| `awwwards-inspiration` | The 8-step loop itself (ships with this package): search → judge from screenshots → design DNA → capture/motion study → state direction → build → band-map verify. |
+| `gsap-scrolltrigger` | The horizontal pin + `containerAnimation` pattern (ease `"none"`, one-shot entrances) driving both Fallow Press horizontal pages. |
+| `gsap-core` / `gsap-timeline` | Tween composition and sequenced hero entrances (torn-paper drop, panel copy rises). |
+| `frontend-design` | Typography, palette and layout judgment applied when translating reference DNA into original pages. |
+| `lenis` (library, via skill guidance) | smooth scrolling synced to ScrollTrigger on the Fallow Press home page. |
+| `tailwindcss` / plain CSS | All builds are plain hand-rolled CSS — flat 2D, no frameworks needed. |
+
+Reduced-motion, JS-less visits, and capture tools all get graceful fallbacks
+(vertical stacks; progressive-enhancement reveals).
+
+**What the verification loop caught** — proof the structure-before-pixels
+doctrine is load-bearing:
+
+- Element **posters lie**: the first showcase build was designed from poster
+  frames alone and rendered a spinning 3D ring as *floating static cards*.
+  Downloading the element videos (`get_site_elements`) and frame-tiling them
+  revealed the motion truth — now the skill mandates studying motion before
+  animating.
+- Full-page captures of reveal-on-scroll builds showed blank sections: `.reveal`
+  animation state vs capture's no-scroll reality. Builds ship
+  content-visible-without-JS progressive enhancement.
+- Horizontal-panel copy vanished **mid-view** on the Fallow Press pages:
+  `toggleActions` reverse reverts entrances while a 100vw panel is still
+  holding the viewport (see above).
+- Band-map compare kept the references' rhythm instead of drifting on
+  section heights (Cerebrium, The Meridian).
+
+Prompt counts: **3** for the original showcase build (the build ask, the
+motion correction that exposed the poster-lie, the structure pass) and
+**1** for Fallow Press ("create a new website using our MCP and skills… no
+3D websites") — its two follow-ups were caught by the QA loop, not by the
+user. Each correction became doctrine in the shipped `awwwards-inspiration`
+skill: frame-study element videos before animating; judge page architecture
+from the studied passages; tile per element, not one giant filmstrip;
+capture live sites and animation **before** building.
+
+## Can awwwards-mcp crawl the sitemap? (robots.txt notes)
+
+The awwwards.com `robots.txt` advertises
+`Sitemap: https://www.awwwards.com/sitemap.xml` and — verified live
+2026-09-18 — **that sitemap URL returns a soft-404 HTML page** (as do common
+child names like `/sitemap-websites.xml`). So sitemap discovery isn't
+currently a path to more data; the polite crawl surface is exactly what the
+indexer uses:
+
+- **Allowed and used**: `/websites/`, `/websites/<filter>/`, `/sites/<slug>`
+  (one filter per URL; deep pagination stays un-crawled).
+- **Disallowed and never fetched**: `/tag/`, `/search-websites`,
+  `/websites/?` (query-string pagination), `/elements/*`, `/vote/`,
+  favourites/likes/follows, and the rest of the 33 rules.
+- Our client (`src/awwwards.ts` `buildFilterUrl`) constructs **only**
+  `/websites/…` paths at 1 request/second — the loop stays inside the
+  published rules by construction, not by convention.
+
+## Contributing
+
+PRs welcome! The project especially needs **parser-drift fixes** — when live
+awwwards.com markup changes, a fresh HTML snapshot attached to an issue often
+becomes the new test fixture and the fastest merged PR. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for the full guide:
+
+**Parser-drift is monitored automatically.** A probe script
+([scripts/parser-drift-probe.mjs](scripts/parser-drift-probe.mjs),
+`npm run drift`) checks every markup anchor the parsers depend on — the
+`split`/`indexOf`/regex literals in `src/parsers.ts` — against the live
+listing and detail pages (2 fetches, 1 request/second, same politeness as
+the client). A daily GitHub Action ([.github/workflows/parser-drift.yml](.github/workflows/parser-drift.yml))
+runs it and, on drift, opens/updates a single tracking issue with the exact
+anchors that changed (and auto-closes it when a later run is green). To run
+it yourself: `npm run drift` (live, exit code 0/1/2) or `npm run drift -- --fixture`
+(offline, checks the committed fixtures still feed every anchor). Raw HTML
+is never diffed or stored — anchors only fire when the parsers actually
+break, so there are no false alarms from cosmetic tweaks.
+
+- Development setup & project layout (offline fixture-tested, no network in tests)
+- How to create a PR: fork → `fix/`/`feat/`/`docs/` branch → typecheck + tests → PR template
+- The politeness constraints new code must keep (1 req/s, robots.txt paths, light runtime deps)
+
+Bugs and feature ideas start as
+[issues](https://github.com/INSANE0777/Awwwards-mcp/issues/new/choose) with
+templates. Security problems go privately — see
+[SECURITY.md](SECURITY.md). By participating you agree to the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -12,6 +12,7 @@ import { Cache } from "./cache.js";
 import { createHandlers } from "./server.js";
 import { captureLiveSite } from "./capture.js";
 import { runIndexer, shouldAutoIndex } from "./indexer.js";
+import { checkForUpdate } from "./version-check.js";
 // The handlers return ToolResponse, which is structurally identical to the
 // SDK's CallToolResult at runtime ({ content, isError? }). CallToolResult's
 // schema additionally carries a [k: string]: unknown index signature that a
@@ -100,4 +101,7 @@ if (shouldAutoIndex(cache)) {
         console.error(`awwwards-mcp: background index failed: ${err instanceof Error ? err.message : String(err)}`);
     });
 }
+// Update notice: once a day, compare against the npm registry; stderr-only,
+// never blocks serving. AWWWARDS_AUTO_UPDATE=1 opts into background install.
+checkForUpdate(pkgJson.version);
 await server.connect(new StdioServerTransport());

package/dist/parsers.js

@@ -148,9 +148,12 @@ export function parseElements(html) {
             continue;
         }
         const mediaPath = blob?.collectableImage;
-        // Only element media (videos/posters live under element/); other blobs
-        // (site card, collections) must not leak in if the end bound is missing.
-        if (typeof mediaPath === "string" && mediaPath.startsWith("element/")) {
+        // Only element media; other blobs (site card, collections) must not leak
+        // in if the end bound is missing. Media paths come in two schemes: modern
+        // sites store them under element/YYYY/MM/..., 2018-era sites under
+        // external/YYYY/MM/... (both verified live 2026-09-18 — the CDN serves
+        // both prefixes and their _static.jpeg posters).
+        if (typeof mediaPath === "string" && /^(element|external)\//.test(mediaPath)) {
             elements.push({
                 title: decodeEntities(String(blob.collectableTitle ?? "")),
                 mediaPath,

package/dist/version-check.js

@@ -0,0 +1,118 @@
+// Update notification: once a day, compare the running version against the
+// npm registry and (optionally) self-update. Designed around the constraints
+// of a stdio MCP server:
+//   - stdout is the JSON-RPC channel → every notice goes to stderr only
+//   - serving must never wait on this → fire-and-forget, 3s timeout,
+//     every failure swallowed (registry unreachable / package unpublished)
+//   - at most one registry hit per day per machine (state in the cache dir)
+// Auto-update is strictly opt-in: AWWWARDS_AUTO_UPDATE=1 runs
+// `npm install -g awwwards-mcp@<latest>` detached, then asks the user to
+// restart their agent; without the env var, the notice just tells the agent.
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const REGISTRY_URL = "https://registry.npmjs.org/awwwards-mcp/latest";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export function parseVersion(v) {
+    const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!m)
+        return [0, 0, 0];
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/** 1 when a > b, -1 when a < b, 0 when equal. Unparseable sorts as oldest. */
+export function compareVersions(a, b) {
+    const [pa, pb] = [parseVersion(a), parseVersion(b)];
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] !== pb[i])
+            return pa[i] > pb[i] ? 1 : -1;
+    }
+    return 0;
+}
+function stateFile() {
+    const cacheRoot = process.env.AWWWARDS_CACHE_DIR ?? join(homedir(), ".awwwards-mcp");
+    return join(cacheRoot, "version-check.json");
+}
+function readState() {
+    try {
+        if (!existsSync(stateFile()))
+            return null;
+        return JSON.parse(readFileSync(stateFile(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeState(state) {
+    try {
+        mkdirSync(join(stateFile(), ".."), { recursive: true });
+        writeFileSync(stateFile(), JSON.stringify(state));
+    }
+    catch {
+        // notification is best-effort; an unwritable cache dir is fine
+    }
+}
+export function buildUpdateNotice(current, latest, autoUpdateEnabled) {
+    if (compareVersions(latest, current) <= 0)
+        return null;
+    const lines = [
+        `awwwards-mcp: update available — v${latest} (running v${current}).`,
+        autoUpdateEnabled
+            ? `awwwards-mcp: v${latest} is being installed in the background; restart your agent to load it.`
+            : `awwwards-mcp: update with \`npm install -g awwwards-mcp@latest\` (or clear your npx cache), or set AWWWARDS_AUTO_UPDATE=1 to self-update on startup.`,
+    ];
+    return lines.join("\n");
+}
+/**
+ * Fire-and-forget update check. Never throws, never blocks the caller:
+ * registry errors, timeouts, and unwritable state files are all swallowed.
+ */
+export function checkForUpdate(currentVersion) {
+    const auto = process.env.AWWWARDS_AUTO_UPDATE === "1";
+    // Skip the daily gate when auto-update is on but no latest is known yet?
+    // No: state gates the fetch itself, so a fresh install always has a shot.
+    const state = readState();
+    if (state && Date.now() - state.checkedAt < CHECK_INTERVAL_MS) {
+        // within the interval: reuse the known latest to (re)warn without fetching
+        if (state.latest) {
+            const notice = buildUpdateNotice(currentVersion, state.latest, auto);
+            if (notice)
+                console.error(notice);
+        }
+        return;
+    }
+    void (async () => {
+        try {
+            const res = await fetch(REGISTRY_URL, {
+                signal: AbortSignal.timeout(3000),
+                headers: { accept: "application/json" },
+            });
+            if (!res.ok)
+                return; // unpublished / registry hiccup → silent
+            const data = (await res.json());
+            if (!data?.version)
+                return;
+            writeState({ checkedAt: Date.now(), latest: data.version });
+            const notice = buildUpdateNotice(currentVersion, data.version, auto);
+            if (notice)
+                console.error(notice);
+            if (notice && auto)
+                startSelfUpdate(data.version);
+        }
+        catch {
+            // offline / timeout / JSON garbage — never surface, never block
+        }
+    })();
+}
+function startSelfUpdate(version) {
+    try {
+        const child = spawn(process.platform === "win32" ? "npm.cmd" : "npm", ["install", "-g", `awwwards-mcp@${version}`], { detached: true, stdio: "ignore" });
+        child.on("error", () => {
+            console.error(`awwwards-mcp: background self-update failed to start — install manually with \`npm install -g awwwards-mcp@${version}\``);
+        });
+        child.unref();
+    }
+    catch {
+        // self-update is best-effort; the notice already told the user what to do
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "awwwards-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Free MCP server giving AI agents design inspiration from Awwwards: search award-winning sites with inline screenshots and extract design DNA.",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,24 @@
     "README.md",
     "skills"
   ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "awwwards",
+    "design",
+    "inspiration",
+    "web-design",
+    "screenshots",
+    "agent-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/INSANE0777/Awwwards-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/INSANE0777/Awwwards-mcp/issues"
+  },
+  "homepage": "https://github.com/INSANE0777/Awwwards-mcp#readme",
   "engines": {
     "node": ">=22.13.0"
   },
@@ -22,6 +40,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "smoke": "tsx test/live-smoke.ts",
+    "drift": "node scripts/parser-drift-probe.mjs",
+    "doctor": "node scripts/doctor.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {

package/skills/awwwards-doctor/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: awwwards-doctor
+description: Use when awwwards-mcp scraping or tools stop working — BlockedError, "layout may have changed" parser errors, empty results, failed captures, stale searches — or when the user reports the MCP behaving oddly. Guides running the doctor/drift/index scripts, applying their fixes, re-anchoring parsers after real awwwards.com drift, and recovering the in-flight task that surfaced the failure.
+---
+
+# Awwwards MCP Doctor
+
+You are repairing the awwwards-mcp toolchain or working around it mid-task.
+Work in this order: **diagnose → fix mechanically → fix parsers (if drift) →
+recover the user's task**. Never delete user data; the only destructive step
+(cache DB moved aside) preserves the old file in the OS temp dir.
+
+## 1. Run the doctor (repo checkout)
+
+```bash
+npm run doctor             # diagnose only
+npm run doctor -- --fix    # diagnose AND apply available fixes
+npm run doctor -- --json   # machine-readable report
+```
+
+The doctor checks five things and knows how to fix the mechanical ones:
+
+| Check | Failure meaning | What --fix does |
+|---|---|---|
+| network | awwwards.com blocked/challenged the request | nothing to fix locally — wait, retry later; never retry in a loop |
+| parser-drift | awwwards.com markup changed under the parsers | captures the raw live page into `docs/drift-<timestamp>/` (gitignored) as the fixture for the fix |
+| playwright-chromium / ffmpeg-static | optional capture deps missing or broken | installs them (dev deps + `npx playwright install chromium`) |
+| cache | SQLite DB corrupt/locked, or index older than 30 days | moves an unreadable DB aside (kept in temp) and rebuilds via `npm run index` |
+| boot | `dist/cli.js` doesn't start | `npm run build` |
+
+Re-run the doctor after fixing; the verdict must be HEALTHY before you claim
+the MCP is repaired.
+
+## 2. Fixing real parser drift (the only code-level failure)
+
+If the doctor reports parser-drift, the anchor probes say which parser broke.
+Repair sequence — keep it mechanical, verify at each step:
+
+1. **Capture the evidence**: the `--fix` snapshot in `docs/drift-*/` IS the
+   new truth. (The daily GitHub Action also opens/updates a `parser-drift`
+   tracking issue with the drifted anchor names.)
+2. **Locate the new anchors**: open the captured HTML and find the markup
+   that replaced the old anchor (search the old anchor's *purpose*, e.g. the
+   card JSON blob, the Elements section heading, the og:image meta).
+3. **Re-anchor the parsers** in `src/parsers.ts` — change the minimum needed
+   (one split/indexOf/regex literal), not the surrounding logic.
+4. **Update the probe list** in `scripts/parser-drift-probe.mjs`
+   (`PROBE_GROUPS`) so the same failure is detectable next time.
+5. **Refresh the fixture**: download the live page with the same UA the
+   client uses and replace `test/fixtures/listing.html` (or the detail
+   fixture). The offline tests run against fixtures only — a refreshed
+   fixture proves the re-anchor against reality.
+6. `npm run typecheck && npm test` — all tests must pass.
+7. Commit as `fix: re-anchor <parser> after awwwards.com markup change`,
+   reference the tracking issue.
+
+## 3. End users (installed via npm, not a repo checkout)
+
+The doctor scripts live in the repo, so for an npm-installed server:
+
+1. Check the version notice: stderr at startup prints when a newer
+   `awwwards-mcp` exists. Update with `npm install -g awwwards-mcp@latest`
+   (or clear the npx cache) and restart the agent — a surprising share of
+   "broken" reports are old parsers fixed in a newer release.
+   `AWWWARDS_AUTO_UPDATE=1` in the MCP server env opts into background
+   self-update on startup.
+2. Reset local state: `rm -rf ~/.awwwards-mcp` is safe (cache + index +
+   version-check state rebuild automatically; nothing user-authored lives
+   there).
+3. If it still fails, it's upstream (block or drift): open an issue at the
+   awwwards-mcp repo attaching the raw HTML of the failing URL.
+
+## 4. Recovering the in-flight task (the reason you noticed)
+
+The user's build/research doesn't wait for the repair. Degrade gracefully:
+
+- **Stale cache is your friend**: `search_sites`/`get_site_details` serve
+  cached data when live fetches fail — say so in the reply ("7-day-old
+  cached data").
+- **BlockedError means stop, not retry**: the client never retries through
+  blocks; tell the user and continue with cached/alternate data.
+- **Capture tools down** (playwright missing): fall back to
+  `get_site_details` screenshots (CDN-served, no browser needed) until
+  `npm run doctor -- --fix` restores chromium.
+- **Parser drift mid-task**: results may be partially empty (e.g. details
+  without palette). Surface which part is missing; don't silently present
+  degraded data as complete.
+- After the MCP is healthy again, **re-run the failed calls** and reconcile
+  with whatever the fallback produced.
+
+## Anti-patterns
+
+- Retrying blocked requests in a loop — politeness rules and block
+  detection exist precisely so this doesn't hammer awwwards.com.
+- Diffing raw HTML to detect drift — cosmetic page changes would false-alarm
+  daily; only parser-anchor probes matter.
+- "Fixing" parsers by loosening them to return empty results quietly — a
+  parse that can't find its anchors must error loudly (that is the drift
+  signal).
+- Treating the doctor's UNHEALTHY verdict as done because one check passed.

package/skills/awwwards-inspiration/SKILL.md

@@ -44,14 +44,27 @@ Run this loop before building anything visual:
    reports a layout-drift error, fall back to judging the shortlisted
    screenshots, `get_site_elements` (which uses a different parser), or a
    `capture_live_site` of the site's URL for a first-hand full-page view.
-6. **Get component-level visuals (when building).** Call `get_site_elements`
-   on shortlisted sites to see individual design elements — 3D models, video
-   content, mobile layouts, microcopy — with poster images inline and video
-   URLs. Treat element posters as texture, not structure: they are video
-   frames (often mid-animation or near-black), not full-section layouts.
+6. **Study MOTION before building (element videos, not posters).** Call
+   `get_site_elements` on shortlisted sites — it returns per-element video
+   URLs (preloader, page transition, case study, about…). **Download those
+   videos and tile them at 1–2 fps BEFORE writing any animation code**:
+   `curl -o e.mp4 <video-url> && ffmpeg -i e.mp4 -vf "fps=2,scale=480:-1,tile=6x4" -frames:v 1 tile-e.jpg`,
+   then Read the tile. (The full capture→review→build procedure — what to record, what to skip, motion inventories, build verification — is the `awwwards-motion-study` skill.) Element **posters are single frames** — they show
+   layout, not motion; a 3D carousel looks like floating static cards in a
+   poster (this exact mis-build happened). One tile per element shows you the
+   whole animation arc (easing, overlap, entrance order). If a marquee
+   animation needs finer study, re-tile that video at higher fps. The motion
+   IS the design: every reference animation you ship must trace to frames
+   you actually studied, and reference videos pass through
+   `showcase/ref-motion/` as the design's evidence trail.
 7. **State the design direction before writing code.** In prose: palette
-   (hexes from the references), type mood, layout patterns, and tech choices,
-   each traceable to a reference. Then build.
+   (hexes from the references), type mood, layout patterns, page
+   architecture (one page vs separate horizontal sections — judge this from
+   the reference passages you studied in steps 4–6, not habit), and tech
+   choices, each traceable to a reference. Then build. For a site's own
+   marquee frontend skills, prefer proven patterns (GSAP ScrollTrigger for
+   horizontal scroll chapters, Lenis for smooth scroll) over hand-rolled
+   scroll math.
 8. **Verify structure, then polish.** After building, capture your own build
    full-page (`capture_live_site` on its `file://` or served URL) and run
    `analyze_page_structure` on BOTH the reference and the build. Compare band
@@ -69,8 +82,14 @@ Run this loop before building anything visual:
 - **Dumping raw tool output at the user** — curate: show the shortlist, the
   chosen direction, and why.
 - **Designing from a thumbnail or element poster** — thumbnails are hero-only
-  crops and posters are video frames; neither shows the page's real
-  structure. When the reference URL is known, capture it full-page (step 4).
+  crops, posters are single video frames, and neither shows real structure OR
+  motion. When the reference URL is known, capture it full-page (step 4);
+  when an element has motion, tile its video (step 6) — never animate from
+  posters.
+- **One filmstrip for everything** — a single N×N tiling of the *whole
+  recording* makes late tiles tiny and animation arcs illegible. Tile per
+  element/per passage at 1–2 fps instead; re-tile finer passages at higher
+  fps when easing or overlap matters.
 - **Padding empty bands to match total height** — if your build's total height
   matches the reference but a spacer/background band is far taller than the
   reference's equivalent, the height was stolen from real content sections.

package/skills/awwwards-motion-study/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: awwwards-motion-study
+description: Use when building a site whose reference has animation — before writing any motion code, and again when verifying a build. Teaches what to record from a live site (and what to skip), how to study the recordings frame-by-frame (video input or ffmpeg tile-per-element), how to turn the study into a motion inventory, and how to verify the build's motion against the reference. Complements awwwards-inspiration (step 6) with the full capture→review→build procedure.
+---
+
+# Awwwards Motion Study — capture, review, build
+
+Motion is design: an award-site hero that "looks the same" in a screenshot
+can be a spinning 3D ring, a scrubbed pin, or a staggered reveal. Static
+captures hide it; element posters (single frames) lie about it. This skill
+covers the whole chain: **record → review → inventory → build → re-record**.
+
+The one rule everything serves: **never write animation code from memory or
+posters — every shipped animation must trace to frames you actually studied.**
+
+## 1. What to capture
+
+Record a **motion-through pass**: load, dwell, slow scroll, hover tour.
+Three animation classes must all be on camera:
+
+| Class | How it gets captured | Typical duration |
+|---|---|---|
+| Preloader / entrance | initial dwell after `load` | 5–8 s |
+| Scroll-triggered + pinned/scrubbed | slow stepped scroll (~450 px / ~600 ms) | length of page |
+| Hover / click / micro-interactions | virtual cursor visits interactive elements and dwells | 10–20 s |
+
+**Capture these** — they are design:
+
+- Preloader/entrance sequences and hero reveals
+- Scroll-triggered reveals, parallax, horizontal pins, scrubbed timelines
+- Hover states (cards, nav, buttons, image rollovers) and click effects
+- Page transitions if the site has them, sticky/nav behaviors on scroll
+- Marquees, tickers, counters — anything time-driven
+
+**Skip these** — they are content, noise, or traps:
+
+- **Content videos** (film hero backgrounds, stock footage, showreels):
+  they're the site's *media*, not its *interaction* — you'd be styling
+  someone's footage, not learning the motion design.
+- **Loading states**: capture *after* they resolve. A half-loaded page
+  records lazy placeholders as if they were the design. Dwell first, then
+  scroll; if a section is still empty in the recording, it's a capture bug,
+  not a design feature.
+- Cookie banners / newsletter modals: dismiss them early (unless you're
+  specifically building one) or they eat the first seconds of footage.
+- Ads, tracking iframes, user-generated widgets.
+- **Don't redistribute recordings**: captures are local study artifacts
+  (keep them in `ref-motion/` or `_qa/`). Awwwards content and site media
+  belong to their creators — study them, don't republish them.
+
+## 2. How to capture
+
+Fast path first, fall back when it can't:
+
+1. **`record_site_motion`** (MCP tool): inline filmstrip + saved .webm path.
+   Best default. Known ceiling: ~30 s — heavy sites may time out.
+2. **`scripts/record-scrollthrough.mjs`** (repo checkout, playwright):
+   `node scripts/record-scrollthrough.mjs <url> <outDir> <name>.webm` —
+   full-control recorder: 7 s preloader dwell, 450 px/600 ms stepped scroll,
+   injected virtual cursor (playwright video doesn't render the real one)
+   that visits and dwells on interactive elements. Use when the MCP tool
+   times out or when you need to customize the tour.
+3. **Direct playwright**: `chromium.launch()` + `newContext({ recordVideo })`
+   when neither fits (custom viewports, login flows, multi-page tours).
+
+Capture rules that prevent re-shoots:
+
+- **Capture BEFORE building** — the doctrine step. Review first, code second.
+- Use a **consistent viewport** (1440×900 matches the QA scripts) so your
+  reference tiles and build tiles are comparable.
+- **Pre-scroll** to fire lazy content, scroll back to top, then record —
+  otherwise reveal-on-scroll sections record as blank boxes.
+- For multi-page sites, record **each page** you'll rebuild (home, projects,
+  about), not just the hero.
+- On the 30 s MCP ceiling: fall back to the script; never shorten the scroll
+  so much that sections get skipped.
+
+## 3. How to review the video
+
+Posters are frames; you need frames **in sequence**. Two paths:
+
+**Path A — direct video input.** `Read` the .webm first. If your model
+supports video, watching the pass gives timing, easing, and transitions no
+filmstrip can. If the read comes back "media omitted / not supported",
+use Path B.
+
+**Path B — tile per element at 1–2 fps.** One tiling *per element/passage*,
+never one mega-strip of the whole recording (late tiles go thumbnail-size
+and easing becomes unreadable — a mis-build happened exactly this way):
+
+```bash
+ffmpeg -i reference.webm -vf "fps=2,scale=480:-1,tile=6x4" -frames:v 1 tile-hero.jpg
+```
+
+Cut the video into per-element segments first (by timestamp from watching
+the strip), then tile each segment. **Re-tile finer at higher fps** when
+easing or overlap matters: `fps=6` on a 3 s passage shows whether an ease
+is `power2.out` vs `expo.out`; overlap ordering needs ~200 ms granularity.
+
+While reading tiles, extract per element:
+
+| Field | What to look for |
+|---|---|
+| trigger | load / scroll-enter / scroll-scrub / hover / click |
+| transform | opacity, y/x, scale, clip-path, blur — which properties move |
+| duration + easing | count frames between first and last movement; fast-out = expo/power4, soft = power2, linear = scrub |
+| stagger | siblings entering in sequence → measure the delay between them |
+| overlap | does the next element start before the previous ends? |
+
+Write the result as a **motion inventory** — a table per page — and build
+from the table, not from impressions:
+
+```markdown
+| Element | Trigger | Transform | Duration | Easing | Overlap |
+|---|---|---|---|---|---|
+| Hero paper | load | yPercent -104→0 | ~1.2 s | power4.out | photo fades under at -1.0 s |
+| Story cards | scroll 86% | opacity + y 56 | ~0.85 s | power3.out | stagger 0.09 |
+```
+
+## 4. Build from the inventory
+
+- Every shipped animation cites an inventory row. If you can't name the
+  frames an animation came from, you're inventing — stop and study.
+- Use proven motion primitives, not hand-rolled scroll math: GSAP
+  ScrollTrigger (pins, `containerAnimation` with `ease: "none"` for
+  horizontal, `scrub` for scrubbed timelines), Lenis for smooth scroll.
+- Full-viewport horizontal panels get **one-shot entrances**
+  (`toggleActions: "play none none none"`) — reverse-on-leave hides copy
+  mid-view (caught by QA pin shots).
+- Ship `prefers-reduced-motion` fallbacks and progressive enhancement
+  (content visible without JS) — a capture tool or JS-less visit must never
+  see blank sections.
+
+## 5. Close the loop: re-record your build
+
+Verification is the same skill pointed at yourself:
+
+1. Record your build exactly as you recorded the reference (same viewport,
+   same pass shape — `record_site_motion` works on `file://` URLs too).
+2. Tile your build's key passages and **compare tile-to-tile** against the
+   reference tiles: same trigger order? similar durations? easing in the
+   same family?
+3. QA captures for scroll builds must land at **panel/section centers**, not
+   uniform scroll fractions — mid-transition shots photograph empty
+   transition zones and look broken when they aren't.
+4. Fix what mismatches, re-record, repeat — one loop, not ten.
+
+## Anti-patterns
+
+- **Designing from posters or thumbnails** — posters are single frames; the
+  3D carousel reads as "floating static cards" (a real mis-build).
+- **One filmstrip for the whole recording** — element-level detail dies in
+  an N×N mega-grid.
+- **Capturing only the hero** — the distinctive motion usually lives below
+  the fold.
+- **Recording over a half-loaded page** — lazy placeholders captured as
+  design.
+- **Studying nothing, animating from vibes** — "it probably fades in" is
+  how builds drift from references.
+- **Republishing recordings** — captures are local study evidence.