From 68181d7fc4e6ee17aff44812358e099b64a5e189 Mon Sep 17 00:00:00 2001 From: ukimsanov Date: Fri, 12 Jun 2026 12:12:02 -0700 Subject: [PATCH] docs(skill): operational footguns subsection in SKILL.md (env / shell / preview) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Real-AI-test factual log from the heygen-showcase build called out six operational issues that ate real cycles (every one a working-as- intended-but-surprising behavior): #3 music add → "Unknown music id" because search ran in repo root, add ran in project subdir — per-cwd cache #4 HEYGEN_API_KEY in .env but not in shell env — child processes don't see it #5 `timeout 180 ...` failed (macOS zsh has no timeout) #7 sfx search --json parser hit the wrong JSON key (used results/ sounds instead of the actual items) #16 preview registered the wrong project (stale process on port 5190 from a prior session held the port) #17 second preview returned exit 144 (SIGTERM) — port still held #18 ~3 preview start/kill rounds before getting a clean server Plus #6 dead -70 LUFS catalog clips (already in step-5 landmine #12, but worth restating in the same place since it's the same class). None of these are framework bugs to fix in code — they're shell / macOS / process-management ergonomics that surface in every w2h run. A 6-line cheat sheet in SKILL.md saves the next agent equivalent churn instead of re-discovering each one. Added to SKILL.md as a new "Operational footguns" subsection right under the existing CLI footguns block. Each bullet: - .env not auto-exported into shell (run from project root, OR `set -a; source .env; set +a` once) - macOS zsh has no `timeout` (use gtimeout or skip) - sfx search cache is per-cwd (search + add in same dir) - music add same rule - sfx search --json key is `items` not results/sounds - preview port-stickiness (stale processes hold ports; pgrep + kill -9) - silent SFX clips ~-70 LUFS (also in step-5 #12; restated here for discoverability) Format mirrors the existing CLI footguns block: opens with the one-line symptom + the recovery move. Goal is grep-ability + density, not coverage of every shell variant. No code change. Doc-only addition. --- skills/website-to-hyperframes/SKILL.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/skills/website-to-hyperframes/SKILL.md b/skills/website-to-hyperframes/SKILL.md index bc121a2376..17807a2f51 100644 --- a/skills/website-to-hyperframes/SKILL.md +++ b/skills/website-to-hyperframes/SKILL.md @@ -213,6 +213,18 @@ Beat count is not in this table intentionally — it should come from the storyb - ❌ `hyperframes lint index.html` — takes a directory, not a file. - ❌ `--quality medium` — not a valid value (use `draft | standard | high`). +### Operational footguns (env, shell, ports — saw all of these eat real cycles) + +The CLI itself works; the shell and surrounding environment have a stable set of papercuts that cost cycles on every real run. Each line below comes from an observed time-sink in a recent build: + +- **`.env` is not auto-exported into the shell** — even if you have `HEYGEN_API_KEY=...` in `.env`, running `hyperframes sfx search` from the shell may report "API key required" because the CLI loads `.env` but child processes / piped commands don't. Either run from the project root (where the CLI's auto-load fires) or `set -a; source .env; set +a` once at the top of the session before the SFX / music / capture-video commands. +- **macOS zsh has no `timeout`** — prefixing a command with `timeout 180 ...` produces `command not found`. Use `gtimeout` (from coreutils) if installed, or skip the timeout and rely on the command's own timeouts. +- **`sfx search` cache is per-cwd** — `sfx search "..."` writes a per-project cache; `sfx add ` reads that cache to resolve the id → URL. If you `search` from the repo root and then `cd` into the project before `add`, the add can't find the cached id. Always search + add in the SAME cwd (the project root is the right one). +- **`music add` is the same — search + add in the same cwd.** +- **`sfx search --json` returns `{items: [...]}` not `{results: [...]}` or `{sounds: [...]}`** — the parser key is `items`. Common LLM intuition picks the wrong key and the first parse silently fails. +- **`preview` registers a project by cwd; stale preview processes hold ports** — a previous session's preview server still running on port 5190 will show its OWN project at `http://localhost:5190`, NOT yours. Symptoms: the project list returned by `/api/projects` doesn't include your project, OR you see a different video than you expect. Fix: `pgrep -f "hyperframes preview"` to find the stale processes, `kill -9` them, then re-run from your project dir. Or use a different port (`preview --port 5200`). +- **Some catalog SFX clips are silent (~-70 LUFS dead)** — `sfx add` prints the loudness analysis. If you see `peak ~-70 dBFS` or `loudness ~-70 LUFS`, the clip is dead — re-search and pick another id. Per step-5 landmine #12. + ### Reference Files | File | When to read |