@hybridlabor-api/aos 4.6.6 → 4.7.1

package/skills/global_config/bdb-security-audit/references/skylos-guide.md

@@ -0,0 +1,139 @@
+# Skylos Guide — Diff & AST Security Scanning
+
+Skylos is pillar 1 of the BDB Security Audit skill: a static security analyzer that
+works at the **AST level** (it parses code structure, not text) and supports
+**diff mode**, so it can gate exactly the lines a PR or staging area touches.
+Its role is a pre-commit and Shipping quality-gate check — the automated half of
+`bdb-security-audit`, before the human-driven checklists run.
+
+This guide covers installation, running, gate integration, and interpretation.
+Command surface below reflects the two core entrypoints (`skylos scan`,
+`skylos diff`); **always confirm flags against `skylos --help` for the installed
+version** — do not assume flags from this document alone.
+
+## 1. Installation
+
+Skylos ships as a Python CLI package. Install it as an isolated tool so it does
+not pollute project environments:
+
+```sh
+# Preferred: isolated tool install
+pipx install skylos
+# or
+uv tool install skylos
+
+# Verify
+command -v skylos
+skylos --help
+```
+
+If `command -v skylos` finds nothing, the pillar is **absent**: report
+"could not check" for the scan step. Never fake a pass, and never hardcode an
+install location into scripts or skills — install via the standard tool manager
+so it lands on `$PATH`.
+
+## 2. Running
+
+### Diff mode — PRs and staged changes (primary use)
+
+Diff mode scans only what changed, which keeps the signal high and the runtime low:
+
+```sh
+skylos diff                 # staged / uncommitted changes vs the baseline
+```
+
+Typical review flow:
+
+```sh
+git checkout feature-branch
+skylos diff                 # security view of the branch's changes
+```
+
+Run it before every push and as the first step of any PR security review.
+Findings on diff mode are gate-relevant by default — the change introduced them.
+
+### Full-tree mode — audits and baselines
+
+```sh
+skylos scan .               # whole project, from the repo root
+```
+
+Use full scans for: first-time audits, release preparation, and re-scanning after
+a dependency or architecture change. Full scans surface legacy findings the diff
+never touched; triage those into tickets rather than blocking the current PR on them.
+
+### Version pinning in CI
+
+Pin the version in CI/workflows so a scanner upgrade cannot silently change gate
+behavior mid-release. Update the pin deliberately, review the new findings, then
+bump.
+
+## 3. Integration into the Shipping Quality Gate
+
+Position Skylos as a **blocking** gate step, after lint/typecheck and before the
+release decision:
+
+```text
+Build → Lint → Typecheck → [Skylos security scan] → Tests → Reviewer → Shipping
+```
+
+Gate rules:
+
+1. **Non-zero exit = gate failure.** A scanner that exits with findings must stop
+   the gate. Do not wrap the command in a way that swallows the exit code, and do
+   not `|| true` it. A discarded exit code is a swallowed failure.
+2. **Empty output on a run that claims to have run is a failure**, not a pass —
+   the same rule as delegated CLIs: verify the finding list exists and names real
+   files, never trust a bare success status.
+3. **Disposition every finding.** Each finding ends as `fixed`, `ticketed (link)`,
+   or `accepted risk (who accepted, why)`. An untriaged finding blocks the gate.
+4. **"Could not check" is reported, not skipped.** If skylos is unavailable in the
+   gate environment, the gate report lists the step as `could not check` and the
+   release decision accounts for it — it must not read as green.
+5. **Fixes re-scan.** After remediation, re-run the same scan command; the fix is
+   proven by the new scan output, not by the edit having been made.
+
+## 4. Interpreting Findings: AST Security vs Style Lints
+
+Skylos reads the AST, so its findings differ in kind from style-linter output.
+Keep the two categories separate — they have different severities and different
+dispositions:
+
+| | Style lint | AST security finding |
+|---|---|---|
+| Source | Textual/format conventions | Code structure: data flow, call patterns, definitions |
+| Examples | Naming, formatting, unused imports as a tidiness matter | Credential material in source, dangerous call patterns, dead code paths that retain secrets |
+| Default severity | Advisory | Gate-blocking until dispositioned |
+| Suppression | Fine, with a reason | Only via the scanner's explicit ignore mechanism **with an inline justification comment**; never by weakening lint config or filtering output |
+
+Interpretation rules:
+
+- **Hardcoded credential findings are always blocking.** Even test fixtures:
+  real-looking keys in tests train the habit and leak via public fixtures. Replace
+  with placeholders and rotate anything that was ever committed.
+- **Dead-code findings are security-relevant, not cosmetic.** An unused function
+  that contains a connection string or an obsolete auth path is attack surface and
+  residue; removal is the fix, suppression is not.
+- **Dangerous-call findings** (execution/serialization primitives reachable with
+  untrusted input) are validated against the checklist item that matches them —
+  see `references/audit-checklists.md` §3 and §4. The scanner says *where*;
+  the checklist decides *how bad, given the data flow*.
+- **False positives:** suppress in the code at the finding site with a reason
+  (`# skylos: ignore — <why this input is trusted>`), never globally, never by
+  post-processing the report. A global filter hides tomorrow's real finding.
+- **Findings vs the diff:** in diff mode, a finding means *this change* introduced
+  or reactivated the issue — treat it as belonging to the PR author's gate. A
+  finding that predates the branch is triaged out of the PR and ticketed.
+
+## 5. Reporting to Reviewer/Shipping
+
+The scan result enters the gate report as:
+
+```text
+Skylos: <pass | fail | could not check>  (command: skylos diff, exit: N)
+Findings:
+  - <file>:<line> — <rule/summary> — severity — disposition
+```
+
+One line per finding, every finding dispositioned, secrets redacted (name the
+file and line, never the value).

package/skills/global_config/bdb-security-audit/references/xalgorix-bridge.md

@@ -0,0 +1,110 @@
+# Xalgorix Bridge — Decoupled Automated Security Suite
+
+Xalgorix is pillar 3 of the BDB Security Audit skill: an **external, decoupled**
+automated security suite. The bridge is deliberately thin — this skill contains no
+xalgorix installation logic, no baked-in endpoints, and no machine-specific
+configuration. The suite is *discovered at runtime*; if it is not there, the audit
+proceeds without it and reports the gap honestly.
+
+## 1. Runtime Discovery
+
+The bridge resolves the suite in exactly two ways, checked in this order:
+
+```sh
+# 1) Local CLI on PATH?
+command -v xalgorix
+
+# 2) Remote endpoint configured?
+echo "${XALGORIX_URL:-}"
+```
+
+- If `command -v xalgorix` resolves, invoke the local CLI.
+- Else, if `XALGORIX_URL` is set and non-empty, talk to the suite over HTTP at
+  that endpoint (authentication via whatever credential variable the operator
+  has already exported — the bridge reads it, never writes it).
+- Else: **the suite is absent.** Report `xalgorix: could not check` in the gate
+  report and stop. Absence is a distinct reported state — never a silent pass,
+  never an error that aborts the whole audit.
+
+Discovery happens **per invocation**, not at skill-load time and not in config
+files. A machine that gains or loses the suite is picked up on the next run.
+
+## 2. Decoupled Configuration Rules
+
+These are hard rules; they are what keeps the bridge portable across machines:
+
+1. **Never hardcode paths.** No absolute paths anywhere in skills, agents, CI
+   files, or docs — no home-directory-specific paths, no install prefixes.
+   Discovery is `$PATH` + environment variables, always.
+2. **Environment over files.** Endpoint and credentials come from the process
+   environment (`XALGORIX_URL`, auth variables), supplied by the operator's shell
+   profile or the CI secret store. The bridge never reads credentials from files
+   in the repo and never writes them anywhere.
+3. **No credential echo.** Logs and reports show that the bridge authenticated,
+   never the credential itself. Redact everything matching secret shapes in scan
+   output before it enters a report.
+4. **Graceful absence.** Every code path that uses the bridge must handle all
+   three states: local CLI present, remote endpoint present, absent. Same rule as
+   the rest of AOS tooling: a check that could not run is `could not check`,
+   distinguishable from `pass`.
+5. **Flag discipline.** CLI surface may change between suite versions. Verify
+   available commands and flags with `xalgorix --help` before scripting against
+   it; do not encode flags this document does not guarantee.
+
+## 3. Running Automated Scans
+
+Typical sweep, once discovery succeeded:
+
+```sh
+if command -v xalgorix >/dev/null 2>&1; then
+  xalgorix --help                      # confirm subcommands/flags of this version
+  xalgorix scan ./path-to-target       # target = repo root or the module under audit
+else
+  echo "xalgorix: could not check (not on PATH, XALGORIX_URL=${XALGORIX_URL:+set}${XALGORIX_URL:-unset})"
+fi
+```
+
+Scope the scan to what the audit covers — the repo root for a release sweep, the
+touched module for a change-driven sweep. Scan targets are passed as **relative
+paths from the working directory** (or `$HOME`-anchored variables if a home-level
+target is genuinely required), never absolute machine paths.
+
+For the remote variant, the equivalent request goes to `XALGORIX_URL` with the
+same scoping rule; verify the response contains an actual findings payload —
+a 2xx status with an empty body is a failed check, not a clean one (the same
+"verify the body, not the status" discipline as delegated CLIs).
+
+Exit-code and evidence rules:
+
+- Non-zero exit = scan found issues or failed to run; either way the report
+  records it, and findings-vs-error is distinguished before dispositioning.
+- An unexplained empty result is treated as a failure of the check.
+- Every finding must name `file:line` and a class; findings without locatable
+  evidence go back to the suite's own logs, not into the gate report as fact.
+
+## 4. Reporting Findings to Reviewer/Shipping
+
+Xalgorix findings enter the same consolidated report as Skylos and the
+checklists, with the origin labeled so Reviewer/Shipping can weigh them:
+
+```text
+Xalgorix: <pass | fail | could not check>  (source: PATH | XALGORIX_URL, exit: N)
+Findings:
+  - <file>:<line> — <class/summary> — severity — disposition
+```
+
+Disposition flow:
+
+1. **Deduplicate against Skylos and checklist results** — one defect found by two
+   pillars is one finding with two origins, not two findings.
+2. **Map each class to its checklist section** in
+   `references/audit-checklists.md` so the fix follows the defensive guidance,
+   not just the scanner's hint.
+3. **Disposition every finding**: `fixed`, `ticketed (link)`, or
+   `accepted risk (who, why)`. Blocking/high dispositions gate the release.
+4. **Re-scan after fixes** and attach the second scan as evidence. The fix is
+   proven by the new output, never by the edit having been made.
+
+The bridge reports; it does not decide. The gate verdict belongs to Reviewer and
+Shipping, on evidence from all pillars — including the honest `could not check`
+rows.

package/skills/global_config/bdbdesignpro/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: bdbdesignpro
-description: "Use when choosing an animation engine, defining motion tokens, adding scroll effects or micro-interactions, or auditing motion for accessibility and performance in BDB projects. Covers engine selection (GSAP, Motion.dev, Anime.js, React-Spring, Three.js, CSS Native), BDB brand-locked motion tokens, and the anti-slop/a11y quality gate."
+description: "Use when choosing an animation engine, defining motion tokens, adding scroll effects or micro-interactions, or auditing motion for accessibility and performance. Covers engine selection (GSAP, Motion.dev, Anime.js, React-Spring, Three.js, CSS Native), DTCG motion tokens, and the anti-slop/a11y quality gate."
 category: design-ui-ux
 user-invocable: true
 risk: safe
 date_added: "2026-09-05"
 ---
 
-# `/bdbdesignpro` — Motion Engine Router & BDB Anti-Slop Gate
+# `/bdbdesignpro` — Motion Engine Router & Anti-Slop Gate
 
-Routes creative-motion decisions to the right engine and enforces BDB-specific motion policy (brand tokens, accessibility, anti-slop). It does not teach any third-party library's API — that's the vendor's job, or an installed upstream skill's (see [engine-routing.md](./references/engine-routing.md)).
+Routes creative-motion decisions to the right engine and enforces motion quality policy (timing tokens, spring physics, accessibility, anti-slop). It does not teach any third-party library's API — that's the vendor's job, or an installed upstream skill's (see [engine-routing.md](./references/engine-routing.md)).
 
 ---
 
 ## 🎯 When to Use
 - Choosing between GSAP, Motion.dev, Anime.js, React-Spring, Three.js, or CSS Native for a specific interaction.
-- Defining or applying BDB-branded motion tokens (durations, easing, brand-locked colors).
+- Defining or applying DTCG motion tokens (durations, easing, spring curves).
 - Auditing existing motion for `prefers-reduced-motion`, layout thrashing, or cleanup leaks.
 - Scaffolding the **Interaction & Motion Strategy** section of a `01_frontend_spec.md` during `/startcycle`.
 

package/skills/global_config/bdbdesignpro/references/bdb-motion-tokens.md

@@ -1,6 +1,7 @@
-# BDB Motion Tokens
+# Motion & Design Tokens
 
-Brand-locked timing, easing, and color tokens for any animation built under `/bdbdesignpro`. Values are sourced from `~/dev/assets/bdb-brand/bdbagentOS/00_MASTER_BRANDING_SPEC.md` — if that spec changes, update here, not the other way around.
+Standard timing, easing, and token architecture for animations built under `/bdbdesignpro`.
+Tokens are brand-agnostic by default and bind dynamically to project-level design tokens (`DESIGN.md`).
 
 ---
 
@@ -10,48 +11,68 @@ Brand-locked timing, easing, and color tokens for any animation built under `/bd
 |---|---|---|
 | `--duration-fast` | `150ms` | Micro-interactions: hover, click, toggle |
 | `--duration-normal` | `300ms` | State transitions: dialogs, drawers, tabs |
-| `--duration-slow` | `400ms` | Upper bound for any standard UI transition — see `antislop-gate.md` |
-| Scroll-driven narrative | scrubbed to viewport delta, no fixed duration | Bind directly to scroll progress, not a timer |
+| `--duration-slow` | `400ms` | Upper bound for standard UI transitions |
+| Scroll-driven narrative | scrubbed to viewport delta | Bind directly to scroll progress, no fixed timer |
 
-## 🌊 Easing
+---
+
+## 🌊 Easing Curves
 
 ```css
---ease-standard: cubic-bezier(0.16, 1, 0.3, 1);
---ease-spring: linear(0, 0.006, 0.025, 0.057, 0.1, 0.155, 0.22, 0.294, 0.375, 0.461,
-  0.549, 0.637, 0.723, 0.803, 0.875, 0.936, 0.984, 1.018, 1.037, 1.042,
-  1.035, 1.019, 0.999, 0.982, 0.971, 0.967, 0.97, 0.978, 0.989, 1);
+:root {
+  --ease-standard: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+  --ease-spring: linear(0, 0.006, 0.025, 0.057, 0.1, 0.155, 0.22, 0.294, 0.375, 0.461,
+    0.549, 0.637, 0.723, 0.803, 0.875, 0.936, 0.984, 1.018, 1.037, 1.042,
+    1.035, 1.019, 0.999, 0.982, 0.971, 0.967, 0.97, 0.978, 0.989, 1);
+}
 ```
 
-## 🎨 Brand-Locked Palette (do not substitute)
+---
+
+## 🎨 Neutral Token Architecture (DTCG Compatible)
 
 ```css
 :root {
-  --bdb-white: #FFFFFF;       /* primary fill, plates, typography */
-  --bdb-obsidian: #0a0a0a;    /* dark UI background */
-  --bdb-elevated: #141414;    /* elevated card surface */
-  --bdb-panel: #1e1e1e;       /* structural body panel */
-  --bdb-panel-alt: #2a2a2a;
-  --bdb-accent: #9b30c4;      /* Vibrant Orchid — the ONLY accent color */
-  --bdb-accent-shadow: #51116F; /* Deep Plum — accent depth/shadow only */
-  --bdb-pill-interior: #180524; /* the one permitted purple-tinted surface */
+  --surface-base: #09090b;
+  --surface-elevated: #18181b;
+  --surface-panel: #27272a;
+  --surface-border: #3f3f46;
+  
+  --text-primary: #fafafa;
+  --text-secondary: #a1a1aa;
+  --text-muted: #71717a;
+
+  /* Accent tokens are populated by Phase 0 Brand Discovery (DESIGN.md) */
+  --accent-primary: var(--brand-accent, oklch(0.65 0.22 260));
+  --accent-muted: var(--brand-accent-muted, oklch(0.45 0.15 260));
+  --accent-contrast: #ffffff;
 }
 ```
 
-### Hard prohibitions (from the master spec — enforce, do not soften)
-- **No mint/cyan** highlight color, anywhere
-- **No neon rainbow gradients** or per-module rainbow theming
-- **No heartbeat lines**, no ambient glow/aura halos
-- **No heavy blur / glassmorphism**
-- Accent (`#9b30c4` / `#51116F`) may appear on rings, pills, borders, or a single highlight stroke — **never as the largest shape's fill.** The largest shapes render in black or white.
+---
 
-**Lint check before shipping any BDB-branded motion work:**
-```bash
-grep -inE "#?(06b6d4|22d3ee|2dd4bf|00ffff|cyan|mint)" path/to/file.css path/to/file.html
-```
-A hit is a blocking finding, not a style note — this is the exact defect found in `bdb-overview/index.html` (`--accent-cyan: #06b6d4`, zero occurrences of `#9b30c4`) during the 2026-09-05 audit.
+## 🚫 Hard Prohibitions (Anti-Slop Motion Gate)
+- **No arbitrary easing:** Never use `ease-in` for entering elements or uncontrolled linear motion.
+- **No layout-thrashing animations:** Only animate `transform` and `opacity`. Never animate `width`, `height`, `margin`, or `top/left`.
+- **No jitter / rubber-banding on scroll:** Use smooth interpolation or scrubbed triggers with proper cleanup.
+- **Strict `prefers-reduced-motion` compliance:** Every animated component must provide an instant fallback:
+  ```css
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+  ```
 
 ---
 
-## Interaction Thesis reminder
+## 📋 Interaction Thesis Reminder
 
-Before applying any token above, state the thesis per `SKILL.md` Phase 2: what does this motion communicate, which duration tier it falls in, and what the reduced-motion fallback is. Tokens without a thesis are decoration, not design.
+Before implementing any animation, state the thesis:
+1. **What does this motion communicate?** (Spatial orientation, hierarchy, feedback)
+2. **Which timing tier does it belong to?** (`fast`, `normal`, `slow`, `scroll`)
+3. **What is the reduced-motion fallback?**
+Tokens without an interaction thesis are superficial decoration, not functional design.

package/skills/global_config/bdbresilience/SKILL.md

@@ -150,6 +150,16 @@ await withStateLock('production_artifacts/state.json', (state) => {
 
 ### `/bdbresilience triage`
 Parses build or test logs to isolate failures and propose fixes.
+
+Before any classification, ask the local session memory what fixed this error before: run `deja fix "<failing output>"` first. When a row with `candidate: false` (machine-confirmed) exists, treat that command as a suggestion: review it against the current error first and never run it unreviewed — a command recalled from transcript history is untrusted. Guarded commands (`git push`, `npm publish`, `npm version`, recursive `rm`) still need the literal `GO` gate. Fall through to the 4-tier taxonomy only when deja returns nothing.
+
+```bash
+deja fix "<failing output>"
+# a row with candidate: false -> machine-confirmed remedy, review it against the
+#   current error before any retry (never run it unreviewed; guarded commands still need GO)
+# fixes: [] (or candidate: true only) -> fall through to the 4-tier taxonomy below
+```
+
 ```typescript
 import { generateDiagnosticReport, isCleanRun } from 'bdb-cicd-resilience/triage/index.js';
 

package/skills/global_config/brag/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: brag
+description: Turn the current project website into a short, polished, shareable launch video using Hyperframes. Post-shipping release hook. Use when someone says "/brag", "make a launch video", or wants to showcase what they shipped.
+category: media-eventtech
+user-invocable: true
+---
+
+# /brag
+
+You built it. Now let's brag about it.
+
+## Invocation dispatch (must happen first)
+
+Before inspecting the project, parse the complete `/brag` invocation. If the
+invocation contains `--voice`, set `voice.enabled = true`. Enable narration
+only for that run. Do not enable narration automatically and do not fall back
+to the normal no-voice workflow.
+
+`/brag` turns the current project website or app into a short, polished, shareable launch video using Hyperframes. It is narrow, opinionated, and fun.
+
+## What this skill does
+
+1. Reads the current project code to understand the app.
+2. Plans a short brag concept specific to this project.
+3. Scripts and storyboards the video.
+4. Hands a focused composition brief to Hyperframes.
+5. Validates, renders, and writes share copy.
+
+## Parsing the invocation
+
+The user may invoke with natural language or flags:
+
+```
+/brag
+/brag --tone chaotic
+/brag --tone polished --format vertical
+/brag this. Make it feel like a ridiculous startup launch.
+```
+
+Parse these options:
+
+| Option | Values | Default |
+|---|---|---|
+| `--tone` | preset or freeform description | inferred |
+| `--format` | `landscape`, `vertical`, `square` | `landscape` |
+| `--duration` | seconds | auto (15-25s) |
+| `--no-music` | flag | music on |
+| `--no-sfx` | flag | sfx on |
+| `--title` | string | inferred from project |
+| `--voice` | flag | narration off |
+
+Voice is opt-in. If `--voice` is present, use Kokoro via Hyperframes and do
+not add any provider-selection logic. The voice workflow is intentionally
+single-provider.
+
+Tone can be a preset (`default`, `polished`, `yc-parody`, `chaotic`, `deadpan`, `cinematic`, `app-store`) or a creative direction such as "fake Series A launch from 2016", "museum exhibit", or "overproduced mobile game ad".
+
+When the user gives freeform tone direction, map it to the nearest preset for pacing and structure, but preserve the user's direction in the plan and composition brief.
+
+## Narration guidance
+
+When `--voice` is enabled, write narration that complements the visuals, does
+not simply read visible text, matches scene pacing, sounds natural and
+conversational, and moves smoothly between scenes. Keep the script concise and
+specific to the product so the voice feels like part of the edit rather than a
+separate narration track.
+
+---
+
+## Output directory
+
+By default, output goes to `brag-output/`. To avoid overwriting previous runs, use a timestamped directory:
+
+```
+brag-output-2026-05-04-143022/
+```
+
+Use a timestamp when:
+- The user explicitly asks for a new run without overriding previous results
+- A `brag-output/` directory already exists in the project
+
+Generate the timestamp at the start of the run (`YYYY-MM-DD-HHmmss`) and use it consistently for all output paths in that run: plan, brief, composition, render, and share copy.
+
+## Skill directory
+
+`<skill-dir>` is the directory containing this `SKILL.md`. Claude Code prints it as "Base directory for this skill" when the skill loads; for other agents it's wherever the skill was installed. Bundled assets are under `<skill-dir>/assets/` and scripts under `<skill-dir>/scripts/`. Don't guess an install path: a plugin install, a `~/.claude/skills/` copy, and this repo all put it somewhere different.
+
+---
+
+## Step 1: Inspect the project
+
+**Read:** [references/step-1-inspect.md](references/step-1-inspect.md)
+
+Scan the project directory and extract the information needed to plan the brag video.
+
+**Gate:** You can answer all 9 questions in the brag planning rubric.
+
+---
+
+## Step 2: Plan and storyboard
+
+**Read:** [references/step-2-plan.md](references/step-2-plan.md)
+
+Write `<output-dir>/brag-plan.md` (where `<output-dir>` is `brag-output/` or the timestamped variant chosen above). Answer the planning rubric. Commit to a creative angle. Write the beat-by-beat storyboard including scenes, text, timing, transitions, and SFX cues.
+
+When music is selected, include a compact `Music cue guidance` section: read the bundled track's cue preset from `<skill-dir>/assets/music/cues/` if present, otherwise note cues will be detected at composition time (any track now supports beat sync — see `references/audio.md`). Cue metadata is optional timing guidance only: story, readability, pacing, and product clarity stay primary.
+
+**Gate:** `<output-dir>/brag-plan.md` exists with a full storyboard. Scene durations sum to 15–25 seconds.
+
+---
+
+## Step 3: Hand off to Hyperframes
+
+**Read:** The Hyperframes domain skills — `hyperframes-core`, `hyperframes-animation`, `hyperframes-creative`, `hyperframes-keyframes`, `hyperframes-cli`. /brag is its own workflow: do not enter the `hyperframes` entry-point intent interview or route into its generic promo / launch-video workflow.
+**Read:** [references/step-3-compose.md](references/step-3-compose.md)
+**Read:** [references/audio.md](references/audio.md)
+
+Write the composition brief and use Hyperframes to create the video implementation in `<output-dir>/composition/`.
+
+`/brag` owns the product angle, source material, storyboard, tone, format, audio selection, music cue guidance, and delivery expectations. Hyperframes owns the concrete composition structure, exact animation timing, animation mechanics, runtime choices, linting rules, and render workflow.
+
+**Gate:** `npx hyperframes check` passes with zero errors inside `<output-dir>/composition/` (the single browser gate before render — see hyperframes-cli for what it audits).
+
+---
+
+## Step 4: Validate, render, and deliver
+
+**Read:** [references/step-4-deliver.md](references/step-4-deliver.md)
+
+Validate, preview, render to `<output-dir>/brag.mp4`, pick the best poster frame into `<output-dir>/brag.jpg`, bake that poster as the video's frame 0 so it's the idle thumbnail everywhere, and write `<output-dir>/share-copy.txt`.
+
+**Gate:** `<output-dir>/brag.mp4` exists. A best-frame poster `<output-dir>/brag.jpg` is picked (not an arbitrary frame) and baked as frame 0 of `brag.mp4`. Share copy is written.
+
+---
+
+## Tone system
+
+Seven tone presets ship with `/brag`. Each changes scripting energy, pacing, typography personality, and transition style. Presets are defaults, not limits.
+
+Full definitions: [references/tones.md](references/tones.md)
+
+| Tone | Energy | One-liner |
+|---|---|---|
+| `default` | Playful, clean, postable | The good-vibes default |
+| `polished` | Serious, elegant | For projects that are not jokes |
+| `yc-parody` | Deadpan startup energy | Fake seriousness applied to absurd projects |
+| `chaotic` | Fast, loud, aggressive | Over-the-top and unhinged |
+| `deadpan` | Calm, dry, understated | The joke is that nothing is a joke |
+| `cinematic` | Dramatic, trailer-scale | Big motion, bigger claims |
+| `app-store` | Smooth, feature-card clean | Corporate but not boring |
+
+Always allow a freeform creative direction to refine or override the preset.
+
+---
+
+## Creative laws
+
+These apply to every brag video regardless of tone.
+
+**Short.** 15–25 seconds. Not one second more without a reason.
+
+**Readable.** Keep the pace high through motion and cuts, never by flashing text. Every line a viewer must read holds long enough to read it (short label ~0.8s settled; a sentence ~0.3s per word). Fast-in, then hold — never fast-in, then gone.
+
+**Specific.** The video must feel like it was made for this exact project, not any project.
+
+**Show the thing.** At least one scene must display actual UI, copy, or a key visual from the product. No abstract filler.
+
+**No generic SaaS language.** "Streamline your workflow" is banned. Use the project's actual copy and claims.
+
+**The hook is everything.** The first 2 seconds determine whether someone keeps watching. Plan the hook before anything else.
+
+**Funny earns its place.** Humor should come from the project's absurdity, not from trying to be funny.
+
+**Pattern:**
+```
+Hook (2-3s) → Reveal (2-4s) → 2-3 sharp highlights (5-12s) → Punchline/outro (2-4s)
+```
+
+Adapt this. Not every project needs exactly 3 highlights. The pattern is a starting shape, not a template.

package/skills/global_config/brag/assets/music/README.md

@@ -0,0 +1,20 @@
+# Music
+
+Bundled tracks:
+
+- `happy-beats-business-moves-vol-1-by-ende-dot-app.mp3` (2:44)
+- `happy-beats-business-moves-vol-9-by-ende-dot-app.mp3` (1:54)
+- `happy-beats-business-moves-vol-10-by-ende-dot-app.mp3` (1:00)
+- `happy-beats-business-moves-vol-11-by-ende-dot-app.mp3` (1:28)
+- `happy-beats-business-moves-vol-12-by-ende-dot-app.mp3` (1:58)
+
+Source: [ende.app](https://ende.app/en) "Happy Beats / Business Moves" series.
+
+Cue presets live in `cues/`:
+
+- `<track-stem>.music-cues.json` contains full-track beat and strong-cue metadata.
+- `<track-stem>.music-cues.md` contains compact planning guidance for the first 20-25 seconds.
+
+These files are generated by `skills/brag/scripts/analyze_music_cues.py` and are intended for `/brag` planning. Normal skill runs should read the presets when present and continue without beat/cue sync when they are missing.
+
+Before publishing or redistributing the skill, verify and document the exact music license terms alongside these files.