oh-my-opencode 5.0.0-beta.6 → 5.0.0-beta.62

package/packages/shared-skills/skills/debugging/references/scripts/dap.test.ts

@@ -0,0 +1,86 @@
+import { test, expect, describe } from "bun:test";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+
+const dir = import.meta.dir;
+const client = join(dir, "dap.mjs");
+const fixture = join(dir, "fixture-adapter.mjs");
+
+test("treats Windows drive-letter paths as executable specs, not host-port specs", async () => {
+  const { isTcpAdapterSpec } = await import("./dap.mjs");
+  expect(isTcpAdapterSpec("C:\\workspace\\fixture-adapter.mjs")).toBe(false);
+  expect(isTcpAdapterSpec("127.0.0.1:5678")).toBe(true);
+});
+
+function frame(message: unknown) {
+  const body = Buffer.from(JSON.stringify(message));
+  return Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`), body]);
+}
+
+describe("DAP framing", () => {
+  test("parses multiple frames and frames split across chunks", async () => {
+    const { DapFrameParser } = await import("./dap.mjs");
+    const parser = new DapFrameParser();
+    const first = frame({ type: "event", event: "one" });
+    const second = frame({ type: "event", event: "two", body: { ok: true } });
+    expect(parser.push(Buffer.concat([first, second]))).toEqual([{ type: "event", event: "one" }, { type: "event", event: "two", body: { ok: true } }]);
+    const third = frame({ type: "response", seq: 3 });
+    expect(parser.push(third.subarray(0, 9))).toEqual([]);
+    expect(parser.push(third.subarray(9, 17))).toEqual([]);
+    expect(parser.push(third.subarray(17))).toEqual([{ type: "response", seq: 3 }]);
+  });
+});
+
+function session(...fixtureArgs: string[]) {
+  // 300ms request timeout ONLY for the --no-answer session, whose test asserts the
+  // timeout classification and needs it to fire fast. Answering sessions get 5s:
+  // the vars-8 fixture response is ~130KB over a pipe, and on a loaded Windows CI
+  // runner that transfer exceeded 300ms, so the request timed out and TRUNCATED
+  // output could never appear (run 33065571760: byte-cap test burned its full
+  // 15s wait while vars-7's ~5KB response stayed under 300ms and passed).
+  const noAnswer = fixtureArgs.includes("--no-answer");
+  const child = spawn("bun", [client], { cwd: dir, env: { ...process.env, DAP_TIMEOUT_MS: noAnswer ? "300" : "5000", ...(noAnswer ? { DAP_FIXTURE_NO_ANSWER: "1" } : {}) } });
+  let output = "";
+  child.stdout.on("data", data => { output += data.toString(); });
+  const api = { child, get output() { return output; }, command(line: string) { child.stdin.write(`${line}\n`); } };
+  api.command(`launch ${fixture} /tmp/program.py`);
+  return api;
+}
+async function until(s: ReturnType<typeof session>, predicate: (out: string) => boolean) {
+  // 15s, not 3s: the file's first `spawn("bun", ...)` on a cold Windows CI runner
+  // (bun.exe cold launch + AV scan + fixture adapter spawn) was observed at just
+  // over 3s (dev run 33064234392: first READY wait failed at 3024ms while the
+  // warm sessions of later tests passed). `until` returns as soon as the
+  // predicate holds, so the raise costs nothing on the green path.
+  const deadline = Date.now() + 15_000;
+  while (!predicate(s.output) && Date.now() < deadline) await Bun.sleep(10);
+  expect(predicate(s.output)).toBe(true);
+}
+
+test("full session emits stop snapshot, stack and capped variables", async () => {
+  const s = session();
+  await until(s, out => out.includes("READY: launch"));
+  s.command("break /tmp/program.py:12"); await until(s, out => out.includes("BREAK:"));
+  s.command("continue"); await until(s, out => out.includes("STOP: stopped reason=breakpoint threadId=1 main at /tmp/program.py:12:3"));
+  s.command("stack"); await until(s, out => out.includes("FRAME\t"));
+  s.command("vars 7"); await until(s, out => out.includes("TRUNCATED: rows dropped=150"));
+  expect((s.output.match(/^v\d+\t/gm) ?? []).length).toBe(100);
+  s.command("terminate"); await until(s, out => out.includes("EXIT:"));
+  s.command("quit");
+}, 60_000);
+
+test("byte cap reports dropped bytes", async () => {
+  const s = session();
+  await until(s, out => out.includes("READY: launch"));
+  s.command("vars 8"); await until(s, out => out.includes("TRUNCATED: rows dropped=") && out.includes("bytes dropped="));
+  s.command("quit");
+}, 60_000);
+
+test("unverified breakpoint and timeout are classified", async () => {
+  const s = session();
+  await until(s, out => out.includes("READY: launch"));
+  s.command("break /tmp/unverified.py:9"); await until(s, out => out.includes("ERR: unverified-breakpoint"));
+  const t = session("--no-answer");
+  await until(t, out => out.includes("ERR: timeout"));
+  s.command("quit"); t.command("quit");
+}, 60_000);

package/packages/shared-skills/skills/debugging/references/scripts/fixture-adapter.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Deterministic DAP fixture used by dap.test.ts.
+import { stdin, stdout, argv } from "node:process";
+
+let seq = 1;
+let buffer = Buffer.alloc(0);
+const noAnswer = argv.includes("--no-answer") || process.env.DAP_FIXTURE_NO_ANSWER === "1";
+
+function send(message) {
+  const body = Buffer.from(JSON.stringify(message));
+  stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+  stdout.write(body);
+}
+function response(request, body = {}, success = true, message) {
+  send({ type: "response", seq: seq++, request_seq: request.seq, success, command: request.command, body, ...(message ? { message } : {}) });
+}
+function event(event, body = {}) { send({ type: "event", seq: seq++, event, body }); }
+function handle(request) {
+  if (noAnswer && request.command === "initialize") return;
+  switch (request.command) {
+    case "initialize":
+      response(request, { supportsConfigurationDoneRequest: true, supportsEvaluateForHovers: true });
+      event("initialized");
+      break;
+    case "setBreakpoints": {
+      const bps = request.arguments?.breakpoints ?? [];
+      response(request, { breakpoints: bps.map((bp, i) => ({ id: i + 1, verified: !request.arguments?.source?.path?.includes("unverified"), line: bp.line, column: bp.column ?? 1, message: "fixture" })) });
+      break;
+    }
+    case "configurationDone": response(request); break;
+    case "launch": response(request); break;
+    case "continue": response(request, { allThreadsContinued: true }); event("stopped", { reason: "breakpoint", threadId: 1, allThreadsStopped: true }); break;
+    case "next": case "stepIn": case "stepOut": response(request); event("stopped", { reason: "step", threadId: 1 }); break;
+    case "pause": response(request); event("stopped", { reason: "pause", threadId: 1 }); break;
+    case "threads": response(request, { threads: [{ id: 1, name: "main" }] }); break;
+    case "stackTrace": response(request, { stackFrames: [{ id: 42, name: "main", source: { path: "/tmp/program.py" }, line: 12, column: 3 }] }); break;
+    case "scopes": response(request, { scopes: [{ name: "Locals", variablesReference: 7, expensive: false }] }); break;
+    case "variables": response(request, { variables: Array.from({ length: 250 }, (_, i) => ({ name: `v${i + 1}`, value: request.arguments?.variablesReference === 8 ? `${String(i + 1)} ${"x".repeat(500)}` : String(i + 1), variablesReference: 0 })) }); break;
+    case "evaluate": response(request, { result: "42", type: "int", variablesReference: 0 }); break;
+    case "terminate": response(request); event("terminated", {}); break;
+    default: response(request, {}, false, `unsupported ${request.command}`);
+  }
+}
+stdin.on("data", chunk => {
+  buffer = Buffer.concat([buffer, chunk]);
+  while (true) {
+    const marker = buffer.indexOf(Buffer.from("\r\n\r\n"));
+    if (marker < 0) return;
+    const header = buffer.subarray(0, marker).toString();
+    const match = header.match(/Content-Length:\s*(\d+)/i);
+    if (!match) { buffer = buffer.subarray(marker + 4); continue; }
+    const length = Number(match[1]);
+    const start = marker + 4;
+    if (buffer.length < start + length) return;
+    const body = buffer.subarray(start, start + length);
+    buffer = buffer.subarray(start + length);
+    try { handle(JSON.parse(body.toString("utf8"))); } catch { /* fixture input is controlled */ }
+  }
+});

package/packages/shared-skills/skills/debugging/references/tools/dap.md

@@ -0,0 +1,103 @@
+# DAP Client (`dap.mjs`) — Drive the Debugger's Protocol, Not Its Text
+
+**Design modeled on the `debug` tool of oh-my-pi (https://github.com/can1357/oh-my-pi, branch omp2).** Their harness proved the shape: one structured debug surface with bounded output, stop snapshots, and classified errors. This script brings the same discipline to any agent with a shell — no harness tool registration required.
+
+Debuggers already speak the Debug Adapter Protocol (DAP), a machine-readable JSON protocol. Driving DAP beats screen-scraping a PTY for the same reason an API beats OCR: structured stops, structured variables, structured errors. **If the debugger speaks DAP, use this script instead of parsing `gdb`/`pdb` output.**
+
+The script is at `references/scripts/dap.mjs` — zero dependencies, runs under Bun or Node.
+
+---
+
+## When to use which interface
+
+| Situation | Use |
+|---|---|
+| Source-level debugging of Python / Go / Node / native code, and you need breakpoints, stepping, variables | `dap.mjs` (this file) |
+| Browser-served JS, or anything already in Chrome | Scripted CDP — see `references/runtimes/node.md` |
+| Stripped binary, no source, no symbols | Ghidra (static) + Frida (live) — see `references/tools/` |
+| The debugger has no DAP mode (plain gdb on an exotic target) | pwndbg, with the output-budget rule from `references/methodology/00-setup.md` |
+
+---
+
+## How to drive it
+
+`dap.mjs` is a **REPL**, not a one-shot command: a debug session is long-lived, so the script runs as a persistent process reading one command per line on stdin and writing bounded text on stdout. Run it as a background shell session, send commands to its stdin, and subscribe to its output.
+
+```
+bun references/scripts/dap.mjs
+```
+
+Every execution-control answer prints a single snapshot line beginning with `STOP:` — subscribe your watcher to that exact prefix so a breakpoint hit wakes you instead of you polling.
+
+### Commands
+
+| Command | Effect |
+|---|---|
+| `launch <adapter> <program> [args...]` | Spawn a stdio adapter (path to executable or `.mjs` adapter) and launch the program under it |
+| `attach <host:port>` | Connect to a listening adapter over TCP and attach |
+| `break <file>:<line>` / `rmbreak <file>:<line>` | Set / remove a source breakpoint |
+| `continue` / `step` / `next` / `stepin` / `stepout` / `pause` | Execution control; each prints a `STOP:` snapshot when the debuggee next stops |
+| `stack [limit]` | TSV backtrace, bounded |
+| `scopes` | Scopes of the top frame with their variablesReferences |
+| `vars <ref>` | Variables under a variablesReference from `scopes` — refs are session-scoped; always chain `scopes` first |
+| `eval <expr>` | Evaluate in the top frame |
+| `threads` / `sessions` | Thread list / session state |
+| `terminate` / `quit` | End the debuggee / exit the REPL |
+
+### Output contract (what keeps your context alive)
+
+- Tabular results are TSV with a header row.
+- Hard caps: `MAX_ROWS = 100`, `MAX_OUTPUT_BYTES = 32 KB`. Overflow prints an explicit `TRUNCATED: rows dropped=N bytes dropped=M` line — never a silent cut.
+- After every continue/step: `STOP: stopped reason=<why> threadId=<id> <frame> at <file>:<line>:<col>`. On debuggee exit: `EXIT: terminated`.
+- Errors are one line, classified: `ERR: invalid-args | no-session | adapter-failed | unverified-breakpoint | timeout | terminated | adapter-error`. The token tells you the recovery — see the failure taxonomy in `references/methodology/02-investigate.md`.
+- Every request times out after 15 s (override with `DAP_TIMEOUT_MS`) and the session stays alive.
+- `DAP_DEBUG=1` logs raw protocol traffic to stderr for diagnosing a misbehaving adapter.
+
+### Adapter quirks this client already handles
+
+- **debugpy** requires `console: "internalConsole"` in the launch request, and withholds the `initialized` event for unrecognized `adapterID`s — the client sends both correctly. It also flushes `initialized` lazily, so the client launches first and awaits the event after.
+- **lldb-dap** reports the launch response's `success` unreliably (`false` even when the process started and stopped) and reports `threadId: 0` on the entry stop. The events are the real signal; the client tolerates the response flag.
+
+---
+
+## Adapter matrix
+
+Translated from oh-my-pi's `builtin_adapters()` (omp2 `crates/docserver/src/dap_adapter.rs`). Install the one matching your runtime; the client speaks to all of them the same way.
+
+| Runtime | Adapter | Install | Launch mode |
+|---|---|---|---|
+| Python | debugpy | `pip install debugpy` | `python -m debugpy.adapter` (stdio) |
+| Go | dlv | `go install github.com/go-delve/delve/cmd/dlv@latest` | `dlv dap` (stdio) |
+| C/C++/Swift/Rust/Zig | lldb-dap | ships with Xcode CLT / LLVM | `lldb-dap` (stdio) |
+| C/C++/Rust/Zig | codelldb | VS Code extension binary | stdio |
+| C/C++/Rust | gdb | `brew install gdb` / apt | via gdb's DAP mode where available |
+| JS/TS | js-debug | `npm i -g @vscode/js-debug` | stdio |
+| .NET | netcoredbg | GitHub releases | stdio |
+| Ruby | rdbg | `gem install debug` | stdio |
+| Kotlin | kotlin-debug-adapter | GitHub releases | stdio |
+| PHP | php-debug-adapter | composer | stdio |
+| Bash | bash-debug-adapter | GitHub releases | stdio |
+| Dart/Flutter | dart debug adapter | ships with Dart SDK | `dart` (stdio) |
+| Elixir | elixir-ls debugger | GitHub releases | stdio |
+
+If an adapter is missing, the install line is the fix — do not fall back to scraping a REPL.
+
+---
+
+## Worked example (Python)
+
+```
+launch /path/to/python -m debugpy.adapter myscript.py   # or a wrapper script path
+break myscript.py:12
+continue
+STOP: stopped reason=breakpoint threadId=1 compute at myscript.py:12:1
+stack
+scopes
+vars 6          # the variablesReference scopes just printed for Locals
+eval total
+continue
+terminate
+quit
+```
+
+Cleanup is part of the session: `terminate` the debuggee, `quit` the REPL, and journal any wrapper scripts you created per the skill's cleanup phase.

package/packages/shared-skills/skills/debugging/references/tools/frida.md

@@ -0,0 +1,193 @@
+# Frida — Hook a Live Process and See Real Values at Runtime
+
+**https://frida.re**
+
+Frida injects a JavaScript engine into a running process and lets you intercept function calls, read arguments, patch return values, and trace execution without touching the binary on disk. **When static analysis in Ghidra shows you *what* a function does, Frida shows you what it does *right now*, with real inputs.** The two compose naturally: use Ghidra to find the target function and its offset, then use Frida to hook it and watch live traffic.
+
+Choose Frida over Ghidra when you need runtime values (actual arguments, return codes, heap contents) or when the binary's control flow is too obfuscated for static analysis to resolve.
+
+---
+
+## Install
+
+```bash
+pip install frida-tools            # Python 3 required
+frida --version                    # verify
+```
+
+On macOS, attaching to another user's process needs root (`sudo frida ...`). SIP-protected system binaries (`/usr/bin/*`, `/usr/sbin/*`) are off-limits entirely. On Linux, you may need `ptrace` permissions: run as root or set `kernel.yama.ptrace_scope=0`.
+
+---
+
+## Target discovery with `frida-ps`
+
+```bash
+frida-ps                         # list local processes
+frida-ps -U                      # USB-connected device (iOS/Android)
+frida-ps | grep -i target        # find your target by name
+```
+
+---
+
+## `frida-trace` — zero-code entry point
+
+`frida-trace` auto-generates JavaScript handler stubs for every matched function. You don't write any code to start.
+
+```bash
+frida-trace -p <pid> -i "recv*"                               # trace exported functions by glob
+frida-trace -p <pid> -m "-[NSURLSession dataTaskWithRequest:*]"  # Objective-C method
+frida-trace -U -p <pid> -j "com.example.App!login*"             # Java method (Android)
+frida-trace -f ./target -i "open"                               # spawn + trace from start
+```
+
+Generated handler files land in `__handlers__/`. Each looks like:
+
+```js
+// __handlers__/libSystem.B.dylib/open.js
+{
+  onEnter(log, args, state) {
+    // args[0] is the first argument (a pointer)
+    log(`open("${args[0].readUtf8String()}")`);
+  },
+  onLeave(log, retval, state) {
+    log(`  => ${retval}`);
+  }
+}
+```
+
+Edit that file, save, and `frida-trace` hot-reloads it. This is the fastest path from "I wonder what this function receives" to a concrete answer.
+
+---
+
+## The JS agent API
+
+When `frida-trace` isn't enough, you write a JS agent and load it with `frida` or from a Python host script. These are the building blocks.
+
+### Find a function
+
+```js
+// By exported symbol name
+const openPtr = Module.getExportByName(null, "open");  // null = any module
+const sslWritePtr = Module.getExportByName("libssl.so", "SSL_write");
+
+// By offset in a stripped binary (get the offset from Ghidra)
+const base = Module.getBaseAddress("target");
+const funcPtr = base.add(0x1a3c);
+```
+
+### Intercept calls
+
+```js
+Interceptor.attach(openPtr, {
+  onEnter(args) {
+    // args[0], args[1], ... are NativePointer objects
+    const path = args[0].readUtf8String();
+    const flags = args[1].toInt32();
+    send({ event: "open", path: path, flags: flags });
+  },
+  onLeave(retval) {
+    // retval is the return value as a NativePointer
+    send({ event: "open_ret", fd: retval.toInt32() });
+  }
+});
+```
+
+### Read memory
+
+```js
+args[0].readUtf8String()          // read a UTF-8 C string from a pointer
+args[0].readCString()             // read a raw C string (stops at null)
+args[1].readByteArray(len)        // read len raw bytes (returns ArrayBuffer)
+```
+
+### Replace / stub a function
+
+```js
+// Force a function to always return 0 (e.g. bypass a license check)
+Interceptor.replace(checkLicensePtr, new NativeCallback(function () {
+  return 0;
+}, 'int', []));
+```
+
+Use `Interceptor.replace` sparingly. It changes program behavior, so always note in your journal that you patched something and why.
+
+---
+
+## Python host script
+
+A host script lets you load a JS agent, receive `send()` messages, and post-process results from the Python side.
+
+```python
+import frida, sys
+
+with open("agent.js") as f:
+    agent_source = f.read()
+
+def on_message(message, data):
+    if message["type"] == "send":
+        print(f"[*] {message['payload']}")
+    else:
+        print(f"[!] {message}")
+
+session = frida.attach(int(sys.argv[1]))
+script = session.create_script(agent_source)
+script.on("message", on_message)
+script.load()
+
+try:
+    sys.stdin.read()                 # block until Ctrl+C
+except KeyboardInterrupt:
+    session.detach()
+```
+
+The agent runs inside the target; the host script stays in your terminal and prints structured output.
+
+---
+
+## Output-budget discipline
+
+**Hooking a hot function (e.g. `malloc`, `read`) will flood your context with thousands of lines.** Don't print every call. Aggregate in the agent and report a summary.
+
+```js
+// Count calls, report every 1000
+let callCount = 0;
+Interceptor.attach(mallocPtr, {
+  onEnter(args) {
+    callCount++;
+    if (callCount % 1000 === 0) {
+      send({ event: "malloc_summary", total_calls: callCount });
+    }
+  }
+});
+```
+
+Alternatives: filter by argument value, only log calls from a specific caller module, or batch into an array and `send()` on a timer.
+
+---
+
+## ⚠️ Gotchas
+
+**Attach vs. spawn.** `frida -p <pid>` attaches to an already-running process. If you need to catch early initialization (constructors, `main` entry), spawn the process with `frida -f ./target`. Frida pauses it at startup. Resume with `%resume` in the REPL or by calling `device.resume(pid)` from Python.
+
+**Stripped binaries have no symbol names.** `Module.getExportByName` returns null for internal functions. You must find the function offset in Ghidra, then compute the address at runtime:
+
+```js
+const addr = Module.getBaseAddress("target").add(0x4a20);
+Interceptor.attach(addr, { /* ... */ });
+```
+
+**A crashing target kills your session.** If the target segfaults or aborts, Frida's agent dies with it. Script a respawn loop on the Python side if you expect crashes.
+
+**Thread safety.** `onEnter`/`onLeave` fire on multiple threads. Keep shared state to simple counters.
+
+---
+
+## Cleanup
+
+```bash
+kill <pid>                         # kill any process you spawned with -f
+rm -rf __handlers__/               # remove generated handler stubs
+rm -f agent.js host.py             # remove session-specific scripts
+```
+
+Always note in your journal which processes you attached to and whether you replaced any functions. A forgotten `Interceptor.replace` in a long-running target will cause confusing behavior later.

package/packages/shared-skills/skills/frontend/ATTRIBUTION.md

@@ -217,6 +217,16 @@ documentation text, or component implementations are vendored. beui.dev names re
 property of their owner, and the guide instructs reading component source for mechanism
 extraction only, not vendoring it into references or projects.
 
+`frontend/references/design/ambience-skill.md` is a project-original, curl-only operating
+guide for consulting the react-bits (reactbits.dev) animated-component registry during hero
+atmosphere, background, typographic-motion, and card-surface work, written from live endpoint
+verification; no react-bits source code, documentation text, or component implementations are
+vendored. react-bits is distributed under MIT plus the Commons Clause, which permits use inside
+applications but forbids redistributing or porting the components themselves; the guide
+therefore instructs reading component source for mechanism extraction only and never vendoring
+it into references, design documents, or this repository. React Bits names remain the property
+of their owner.
+
 `frontend/references/design/clone-from-url.md` is a project-original runtime-extraction
 workflow guide. Its browser + `getComputedStyle` clone approach follows the same
 MIT-licensed `JCodesMore/ai-website-cloner-template` clone-website workflow that `aside.md`

package/packages/shared-skills/skills/frontend/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: frontend
-description: "MUST USE for frontend/web UI/UX/visual work: building, styling, redesigning pages/components, React setup, performance audits, visual QA, taste, and polish. Routes four rulesets: design taste router and brand references; perfection for Playwright/Chromium Lighthouse/Core Web Vitals; ui-ux-db palettes/fonts/guidelines; designpowers personas/accessibility/critique/handoff; plus curl-only lazyweb real-app-screen research and the beui.dev interaction catalog. Triggers: frontend, UI, UX, design, redesign, styling, layout, animation, motion, interaction, micro-interaction, make it feel alive, premium, luxury, minimal, brutalist, Awwwards, DESIGN.md, mockup, React, Lighthouse, accessibility, WCAG, Core Web Vitals, looks generic, make it pretty, like X brand, lazyweb, design research."
+description: "Builds, styles, and polishes web UI and UX. Use for any frontend, page, component, styling, layout, animation, or visual-quality task, or when asked to make an interface look or feel a certain way."
 ---
 
 # Frontend
 
-This file is a router, not a rulebook. The rules live in four rulesets under `references/`; your first job is to load the smallest set of files that covers the request, state which you loaded in one sentence, then execute under their guidance. Loading nothing and freestyling produces the generic AI-slop output this skill exists to prevent; loading everything wastes context and creates contradictory instructions.
+This file is a router, not a rulebook. The rules live in four rulesets under `references/`, and reading them is the work, not the preamble to it. Before touching any file, name the references the request routes to and the one reason each is needed, then read exactly those. Declaring the set first is what makes the choice reviewable: a reference you never named is one you decided to skip, and a reference you named but never opened is a gap you still owe. Freestyling past the routed set produces the generic AI-slop output this skill exists to prevent.
 
 **The bar is not clean-and-correct — it is work a senior designer at Linear, Stripe, or Supabase would ship.** Correct-but-flat is a failure, not a finish. Protect the surface as hard as you protect the build: design is a first-class deliverable, not a one-shot decision you lock and walk away from.
 
@@ -14,12 +14,15 @@ This file is a router, not a rulebook. The rules live in four rulesets under `re
 | Request involves… | Read |
 |---|---|
 | ANY UI implementation, styling, redesign, mockup, or visual decision | `references/design/README.md` FIRST. It enforces two mandatory gates — the Design System Gate (a `DESIGN.md` must exist before any component is written) and the React Dev Tooling Gate (react-grab / react-scan / react-doctor installed by default) — then routes to the taste and brand references below. |
+| Spatial structure — app shells, scroll ownership, "what goes where", "this layout breaks at X" | ALSO `references/design/layout-skill.md` for the mechanics, then `references/design/stylegallery.md` to fetch a named pattern contract for that exact spatial problem. Both stack on the style skill and add no visual direction. |
+| Paged output — a PDF report, a print stylesheet, a headless-Chrome print pipeline, an HTML deck printed to paper, or any "why is this page half empty" break defect | ALSO `references/design/print-paged-media.md` for the page box, the fragmentation properties, the atomic-block set, and the keep-together side effect that strands a block on a near-empty page. It adds no visual direction and stacks on the routed style skill. |
 | Interaction or motion work — micro-interactions, animated components, transitions, gestures, hover/press/state feedback, "make it feel alive" | ALSO `references/design/interaction-skill.md`. The beui.dev catalog is the mandatory interaction reference: find the nearest pattern, read its real source through the file's curl recipe, and adapt the mechanism to `DESIGN.md` motion tokens. It stacks on the routed style skill — never replaces it. |
+| Hero atmosphere or ambience — an animated, shader, particle, or grid background; a typographic reveal (split, blur, shimmer, typewriter, count-up, marquee); scroll storytelling; spotlight / tilt / glare / glowing-border card surfaces; "make the hero stunning", "add a living background", "animate the headline" | ALSO `references/design/ambience-skill.md`. The react-bits catalog is the mandatory ambience reference: find the nearest pattern in its intent map, read its real source through the file's curl recipe, extract the mechanism, and run its retrofit checklist (reduced motion, off-screen pause, compositor-only, tokens, budget) before shipping. It stacks on the routed style skill — never replaces it, and never vendors react-bits code. |
 | Writing or modifying frontend code, OR auditing performance / SEO / accessibility / quality | ALSO `references/perfection/README.md`. Lighthouse 100 in every category, measured on real Playwright Chromium (never the `lighthouse` CLI), achieved through architecture — never by dropping animations or hiding content. |
-| Looking up a concrete style, color palette, font pairing, chart type, landing-page structure, or UX guideline — or generating a project design system from keywords | `references/ui-ux-db/README.md`. A searchable CSV database with a CLI; a lookup tool, not a posture. Load on demand; `design` stays the source of truth for taste and the `DESIGN.md` contract. |
-| ANY implementation or redesign that creates or updates `DESIGN.md` — plus explicit operating-layer asks (personas, critique, debt, handoff, synthetic user testing) | `references/designpowers/README.md` + `references/designpowers/lane-c-review.md`. An internal frontend ruleset, not a separate skill: lane-c is the Phase Final flatness/critique reviewer, and its accessibility-constraints and accepted-debt language fills the required `DESIGN.md` sections. Load other lanes only when their phase applies. |
+| Looking up a concrete style, palette, font pairing, chart type, landing structure, or UX guideline — or generating a design system from keywords | `references/ui-ux-db/README.md`. A searchable CSV database with a CLI: a lookup tool, not a posture. `design` stays the source of truth for taste and the `DESIGN.md` contract. |
+| ANY implementation or redesign that creates or updates `DESIGN.md` — plus explicit operating-layer asks (personas, critique, debt, handoff, synthetic user testing) | `references/designpowers/README.md` + `lane-c-review.md`. lane-c is the Phase Final flatness/critique reviewer and fills the accessibility-constraint and accepted-debt sections `DESIGN.md` requires. Load other lanes only when their phase applies. |
 
-**For implementation work, design + perfection load together.** A page that hits Lighthouse 100 but looks like AI slop has failed; a page that looks beautiful but ships a 2 MB bundle has failed. Both win or neither does.
+**For implementation work, design + perfection load together.** Beauty with a 2 MB bundle fails; Lighthouse 100 that looks like AI slop fails. Both win or neither does.
 
 ## Design System and Component Workflow
 
@@ -32,12 +35,13 @@ Every implementation must choose one of these branches before UI code changes:
 2. **Greenfield or fresh setup:** if the user gave no concrete visual reference, design research is a build step with named deliverables — not exploration to be budgeted. Exploration-stop instincts ("enough exploration", two-wave caps) do not apply here. Fire every research lane IN PARALLEL before `DESIGN.md` is written, and open `DESIGN.md` with a `## 0. Research Log` section recording each lane's deliverable — a lane with no Research Log line did not run. Skip a lane only when its tool or network is genuinely unavailable, and name the skip in `DESIGN.md`:
    - **Embedded references:** use `references/design/_INDEX.md` to shortlist 2-3 plausible Layer B references, then read exactly one Layer A style skill and one Layer B reference in full — every line, no partial reads (they are 200-500 lines; a sliced read produces the flattened token set this gate exists to prevent). Log the shortlist, the pick, and why. Use `open-design` only when the curated set has no fit; add `ui-ux-db` lookups for palette/type/domain questions.
    - **Lazyweb real-product screens:** READ `references/design/lazyweb.md` FIRST and run its recipe verbatim — do not improvise curl calls against lazyweb.com; the recipe mints its own anonymous token. Log the queries run, how many screens you actually VIEWED, and the layout grammar harvested — never pixel copies.
+   - **StyleGallery spatial patterns:** read `references/design/stylegallery.md` and fetch the pattern whose primary spatial problem matches the screen. Log the pattern adopted and the element that owns the scroll.
    - **Imagen concept drafts:** generate 2-3 imagen concept drafts, each seeded with the loaded Layer A + Layer B tokens (palette, type, material); pick the strongest and treat the chosen draft as the reference-fidelity contract. Log the draft paths and the pick.
    Synthesize every lane into `DESIGN.md`. Treat sources as source material, not mood labels: extract tokens, layout grammar, component anatomy, interaction states, motion, and taste decisions, then recombine them into project-specific primitives. Before laying out sections, inventory the content blocks and assign each a job — hook, explain, prove, compare, convert, navigate, retain — then order sections by the visitor's decision path, not by visual symmetry. Never freestyle past the selected references, never copy logos or brand-specific copy. Then run the Primitive Showcase Gate (`references/design/README.md` Phase 0) before any product screen.
 3. **Existing project with `DESIGN.md` or a component system:** read it, follow it, and update it before implementation only when the requested work needs a new token, primitive, state, motion rule, accessibility constraint, accepted debt, or reference-fidelity requirement.
 4. **Existing project with UI but no `DESIGN.md` and no reusable component layer:** STOP and ask the user one focused question: should you preserve the current look with copy-nearby styling, or extract a real `DESIGN.md` plus reusable components before continuing? Do not silently choose.
 
-For implementation, redesign, or design-system work that creates or updates `DESIGN.md`, `references/designpowers/README.md` + `lane-c-review.md` are part of the default load — feed their personas, accessibility, critique, debt, handoff, and role-reference guidance into the branch above. The resulting `DESIGN.md` is the implementation contract: tokens, typography, spacing, primitives, motion, responsive behavior, accessibility constraints, and accepted debt must be named there before code uses them. Verify component primitives, states, and final screens with real visual QA evidence; pass design-system decisions, implementation evidence, and unresolved debt into `/review-work` for significant implementation work.
+The resulting `DESIGN.md` is the implementation contract: tokens, typography, spacing, primitives, motion, responsive behavior, accessibility constraints, and accepted debt must be named there before code uses them. Verify component primitives, states, and final screens with real visual QA evidence; pass design-system decisions, implementation evidence, and unresolved debt into `/review-work` for significant implementation work.
 
 ## Ruleset 1 — design (`references/design/`)
 
@@ -63,6 +67,7 @@ The reference library has one architecture file, 12 taste skills (Layer A — *h
 | `output-skill.md` | Stacks on any style skill when output is incomplete — placeholders, `// TODO`, half-done components. |
 | `stitch-skill.md` | Stacks on any style skill for Google Stitch compatibility or a `DESIGN.md` doc export. A complete worked export ships as `stitch-design-example.md`. |
 | `interaction-skill.md` | Stacks on any style skill when work adds or changes interaction or motion. beui.dev-anchored: read the mapped component's source before designing an interaction; reduced motion always. |
+| `ambience-skill.md` | Stacks on any style skill when work adds a hero atmosphere, animated background, typographic reveal, scroll chapter, or card surface effect. react-bits-anchored: read the mapped component's source, extract the mechanism, run the retrofit checklist; one atmosphere per hero, cursor effects quarantined. |
 | `imagegen-frontend-web.md` / `imagegen-frontend-mobile.md` / `imagegen-brandkit.md` | Image-only output (mockup, app-screen concepts, brand board). These NEVER write code — switch to `image-to-code-skill.md` if code is wanted. |
 
 ### Layer B — brand design systems (orthogonal to Layer A; stack freely)
@@ -104,7 +109,7 @@ Domains: `product` `style` `typography` `color` `landing` `chart` `ux` `react` `
 
 ## Ruleset 4 — designpowers (`references/designpowers/`)
 
-`README.md` routes design operating-layer guidance from the pinned `Owl-Listener/designpowers` reference corpus into the existing frontend workflow. Load it — together with `lane-c-review.md` — for every implementation or redesign that creates or updates `DESIGN.md`, and additionally when a task needs explicit personas, accessibility and cognitive constraints, design critique, design debt, handoff, synthetic user testing, motion guidance, or role-reference prompts. It does not replace this frontend skill, `/visual-qa`, `/ulw-plan`, `/start-work`, or `/review-work`; it supplies richer design context that must first be distilled into the project `DESIGN.md`, then used as the design-system contract for implementation and verification.
+`README.md` routes the pinned `Owl-Listener/designpowers` corpus into this workflow. It supplies design context — personas, accessibility and cognitive constraints, critique, debt, handoff, synthetic user testing, motion, role prompts — that must be distilled into `DESIGN.md` first, then used as the implementation contract. It replaces nothing: not this skill, not `/visual-qa`, `/ulw-plan`, `/ulw-execute`, or `/review-work`.
 
 ## Quick routes — most common requests
 
@@ -116,10 +121,12 @@ Domains: `product` `style` `typography` `color` `landing` `chart` `ux` `react` `
 | "Premium SaaS hero like Stripe" | `design/README.md` + `design/stripe.md` + `design/soft-skill.md` + `perfection/README.md` |
 | "Improve this existing dashboard" | `design/README.md` + `design/redesign-skill.md` + `perfection/README.md` |
 | "Add micro-interactions" / "animate this" / "make it feel alive" / "polish the interactions" | `design/README.md` + `design/interaction-skill.md` on top of the current style skill + `perfection/README.md` |
+| "Make the hero stunning" / "add an animated background" / "animate the headline" / "count-up / typewriter / marquee" / "spotlight or tilt cards" | `design/README.md` + `design/ambience-skill.md` on top of the current style skill + `perfection/README.md` |
 | "Build this screenshot / Imagen mock / Stitch output exactly" | `design/README.md` + `design/image-to-code-skill.md` + `perfection/README.md` + `/visual-qa` reference-fidelity mode |
 | "Audit my site" / "make this page faster" | `perfection/README.md` (+ `perfection/react-perf-tooling.md` if React) |
 | "Mockup image of a fintech app" — no code | `design/imagegen-frontend-mobile.md` (+ a Layer B brand if named) |
 | "What palette/fonts fit a wellness brand?" | `ui-ux-db/README.md` → search CLI |
+| "Where should this go?" / "the layout breaks" / scroll + containment | `design/layout-skill.md` + `design/stylegallery.md` on the current style skill |
 | "What do shipped apps in this space look like?" / design-direction research | `design/lazyweb.md` (curl-only) + `design/_INDEX.md` shortlist |
 | "Set up this React project" | `design/README.md` + `design/react-dev-tooling-skill.md` |
 | "Use designpowers", "make the design workflow stronger", "add personas/accessibility/debt/handoff" | `design/README.md` + `designpowers/README.md` (+ `perfection/README.md` if implementation or audit follows) |
@@ -127,7 +134,7 @@ Domains: `product` `style` `typography` `color` `landing` `chart` `ux` `react` `
 ## Shared axioms (all four rulesets agree — apply always)
 
 - **No design system = no UI work.** `DESIGN.md` exists before components do; every color, font size, and spacing value traces back to a token in it.
-- **Concrete reference = contract.** When a screenshot, generated mockup, overview, or annotated reference exists, the implementation must match its pixels, copy, component structure, and responsive intent unless the user explicitly accepts a deviation.
+- **Concrete reference = contract.** When a screenshot, mockup, or annotated reference exists, match its pixels, copy, component structure, and responsive intent unless the user accepts a deviation.
 - **Never weaken UX OR flatten the surface to buy points.** No dropping animations, hiding content, simplifying interactions, or replacing rendered/lit material with flat fills and flat geometric primitives for a Lighthouse score or a deadline. Hit 100 AND keep the surface dimensional — both, or neither.
 - **No emojis as icons.** SVG icon sets only (Lucide, Heroicons, Radix, Phosphor).
 - **GPU-composited animation only** — `transform`, `opacity`, `filter`; never animate layout properties.

package/packages/shared-skills/skills/frontend/references/design/README.md

@@ -7,7 +7,7 @@ You are an elite frontend design engineer. Your only job in this skill is to **r
 
 You are not done when it is clean and correct. You are done when a senior product designer at Linear, Stripe, or Supabase would ship it: surfaces read as real materials (depth, light, layering), color carries a story and a ramp, type has personality, and motion has intent. **Correct-but-flat is a failure, not a finish.** The most common way this skill fails is effort drain: the build, lint, file-size, and test gates eat all the attention and the surface ships at the floor. Spend on the surface like it is the deliverable, because for an expressive brief it is. When you render and find only bug-level issues, you are not done — you are at the start of the part that separates good from generic.
 
-Two things ship flat most often, and both read as "clean but generic": the **hero's focal object** and the **atmosphere**. Render the focal object as a real, lit, dimensional thing — a generated bitmap (imagegen) for a product/brand/object hero, or CSS/SVG art that carries light, shadow, gradient, and depth. Flat geometric primitives (plain circles and rounded rects) for a brand hero are the flat trap. Give the background depth too — gradient, glow, layered light, an atmospheric band, or a real image — not one flat fill. Glass is only one material: a dark glossy brand wants tint+blur+rim+sheen+glow, a bright playful brand wants gradient fills+soft depth shadows+a lit focal object. Pick what the brand calls for, but it must have dimension.
+Two things ship flat most often, and both read as "clean but generic": the **hero's focal object** and the **atmosphere**. Render the focal object as a real, lit, dimensional thing — a generated bitmap (imagegen) for a product/brand/object hero, or CSS/SVG art that carries light, shadow, gradient, and depth. Flat geometric primitives (plain circles and rounded rects) for a brand hero are the flat trap. Give the background depth too — gradient, glow, layered light, an atmospheric band, or a real image — not one flat fill. Glass is only one material: a dark glossy brand wants tint+blur+rim+sheen+glow, a bright playful brand wants gradient fills+soft depth shadows+a lit focal object. Pick what the brand calls for, but it must have dimension. The mechanisms for that atmosphere and for how the headline arrives come from `ambience-skill.md` (Step 10), not from memory.
 
 ## Why route at all
 
@@ -120,7 +120,7 @@ Do NOT let an expressive brief fall through to `taste-skill`. Then map the phras
 | "minimal", "clean", "Notion-like", "Linear-like", "editorial", "boring is good" | `minimalist-skill.md` |
 | "brutalist", "raw", "Swiss", "experimental", "industrial", "anti-design", "unstyled" | `brutalist-skill.md` |
 | "premium", "luxury", "calm", "expensive", "elegant", "spa", "boutique", "glossy", "glassy", "liquid glass", "startup-grade", "make it beautiful/pretty" | `soft-skill.md` + a high-craft Layer B (`supabase` / `linear.app` / `vercel` / `stripe`) |
-| "Awwwards-level", "wow factor", "magnetic", "scroll-triggered", "high-variance", "cinematic", "make it crazy" | `gpt-tasteskill.md` |
+| "Awwwards-level", "wow factor", "magnetic", "scroll-triggered", "high-variance", "cinematic", "make it crazy" | `gpt-tasteskill.md` + `ambience-skill.md` for the backgrounds and scroll scenes its sections 5 and 7 demand |
 | Neutral or operational — internal tool, dashboard, admin, "just make it usable" with no surface ambition | `taste-skill.md` as Layer A, plus the greenfield `_INDEX.md` shortlist → exactly one Layer B reference |
 
 You may also load a brand DESIGN.md from Layer B as a *concrete reference* if the user's mood maps cleanly (see the "Mood-based shortcuts" section in `_INDEX.md`).
@@ -181,6 +181,12 @@ Triggers: micro-interactions, animated components, transitions, gestures, hover/
 
 **Action:** Add `interaction-skill.md` on top of whatever style skill you selected. It anchors interaction design to the beui.dev catalog: find the nearest pattern, read its real source through the file's curl recipe, extract the mechanism (spring config, layout strategy, enter/exit order, reduced-motion path), and adapt the values to `DESIGN.md`. It owns interaction mechanics only — no visual direction — so it stacks cleanly, like `layout-skill.md`.
 
+### Step 10 — Does the work add a hero atmosphere, background, typographic reveal, or card surface effect?
+
+Triggers: an animated, shader, particle, or grid background; a hero that must feel atmospheric or dimensional; text that splits, blurs, shimmers, types, counts, scrambles, or loops; scroll-triggered chapters; spotlight / tilt / glare / glowing-border cards — or "make the hero stunning", "add a living background", "animate the headline".
+
+**Action:** Add `ambience-skill.md` on top of whatever style skill you selected. It anchors ambience to the react-bits catalog: find the nearest pattern in its intent map, read its real source through the file's curl recipe, extract the mechanism (render loop and its driver, shader uniforms or split strategy, sizing, dependencies), then run its retrofit checklist — reduced-motion static state, off-screen pause, no scroll listeners, compositor-only properties, `DESIGN.md` tokens, lazy-loaded budget. One atmosphere per hero; cursor effects stay quarantined to `gpt-tasteskill.md` briefs. It owns ambience mechanics only — no visual direction — and never vendors react-bits code.
+
 ## Stacking rules (read this once, internalize it)
 
 1. **At most one Layer A *style* skill at a time.** A layout cannot be both `minimalist-skill` and `brutalist-skill` simultaneously — they encode opposite spacing and typography philosophies. Pick one.
@@ -191,6 +197,7 @@ Triggers: micro-interactions, animated components, transitions, gestures, hover/
 6. **Layer B (brand DESIGN.md) is orthogonal to Layer A.** You can pair any Layer A skill with any Layer B brand. Use Layer B as the source of color/type/component tokens; let Layer A drive the execution discipline.
 7. **`layout-skill.md` stacks on top of any style skill** for app-shell / dashboard / split-pane work. It owns spatial structure and scroll ownership only — no visual direction — so it never conflicts with the style skill you picked.
 8. **`interaction-skill.md` stacks on top of any style skill** for interaction/motion work. It owns interaction mechanics — springs, layout morphs, enter/exit orchestration, reduced motion — and no visual direction, so it never conflicts with the style skill either.
+9. **`ambience-skill.md` stacks on top of any style skill** for hero atmosphere, backgrounds, typographic reveals, scroll chapters, and card surface effects. It owns ambience mechanics and their retrofit contract — no visual direction — so it stacks with the style skill and with `interaction-skill.md` at the same time.
 
 ## Anti-patterns — do not do these
 
@@ -235,6 +242,7 @@ Once references are loaded, before writing any UI code:
 | "Build a dashboard / settings / inbox / app shell" | one style skill (usually `taste-skill.md`) + `layout-skill.md` |
 | "Panel won't scroll / footer pushed off-screen / mobile overflow" | Add `layout-skill.md` to current stack |
 | "Add micro-interactions / animate this / make it feel alive" | Add `interaction-skill.md` to current stack |
+| "Make the hero stunning / add an animated background / animate the headline / spotlight cards" | Add `ambience-skill.md` to current stack |
 
 ## Phase Final — Design QA (MANDATORY, runs after implementation)
 

package/packages/shared-skills/skills/frontend/references/design/_INDEX.md

@@ -59,8 +59,10 @@ Beyond the 12-file Layer A library, the design ruleset carries project-original
 | File | Purpose | Load when |
 |---|---|---|
 | `interaction-skill.md` | Interaction mechanics anchored to the beui.dev catalog: find the nearest pattern, read its real source through the curl recipe, extract the mechanism (spring config, layout strategy, enter/exit order, reduced-motion path), and adapt it to `DESIGN.md` motion tokens. | Any work adding or changing interaction or motion — micro-interactions, animated components, transitions, gestures, hover/press/state feedback, loading/success/error morphs, "make it feel alive". |
+| `ambience-skill.md` | Ambience mechanics anchored to the react-bits catalog: hero atmosphere and animated backgrounds, typographic reveals, scroll chapters, card surface effects. Find the nearest pattern in its intent map, read the source through the curl recipe, extract the mechanism, and run the retrofit checklist (reduced-motion static state, off-screen pause, compositor-only, tokens, budget). Cursor effects are quarantined to `gpt-tasteskill.md` briefs. | Any work adding a hero atmosphere, animated or shader background, text reveal (split, blur, shimmer, typewriter, count-up, marquee), scroll storytelling, or spotlight / tilt / glare / glowing-border cards. |
 | `layout-skill.md` | Layout mechanics: scroll ownership, the two silent CSS contracts, named primitives, content-stress matrix. Zero visual direction. | App shells, dashboards, split panes, or a layout that breaks under real content. |
 | `lazyweb.md` | Curl-only real-product screen research for design direction. | Greenfield design research lanes. |
+| `stylegallery.md` | Curl-only lookup of named spatial pattern contracts: primary problem, constraints, scroll ownership, anti-patterns. | A concrete spatial problem needs a documented pattern, alongside `layout-skill.md` mechanics. |
 | `clone-from-url.md` | Runtime extraction workflow (browser + `getComputedStyle`) for cloning a named site. | A live site or URL is the visual reference. |
 
 ---