@prismer/runtime 2.2.55 → 2.2.64

package/built-in-skills/prismer-apple-reminders/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: prismer-apple-reminders
+scope: common
+description: "Apple Reminders via remindctl: add, list, complete."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [ macos ]
+metadata:
+  nativeReplaces: [ apple-reminders ]
+  hermes:
+    tags: [ Reminders, tasks, todo, macOS, Apple ]
+  requiresExplicitGrant: true
+prerequisites:
+  commands: [ remindctl ]
+---
+
+## Prismer execution contract
+
+This is the uniquely named `prismer-apple-reminders` skill, adapted from Hermes.
+Use the actual tools exposed by the executing host; examples using terminal,
+process, delegate_task, vision_analyze or browser_* are not tool registrations.
+Missing dependencies do not hide this skill. Report command startup, version,
+account/permissions and task-specific live verification separately. Use task-owned
+artifact paths and existing user authorization; do not change shared accounts,
+Runtime/provider configuration, global security settings or unrelated work.
+See NOTICE.md and LICENSE for resource provenance. Runtime availability and
+upstream-entry suppression are owned by the integration layer.
+
+
+# Apple Reminders
+
+Use `remindctl` to manage Apple Reminders directly from the terminal. Tasks sync across all Apple devices via iCloud.
+
+## Prerequisites
+
+Resolve SKILL_ROOT to this installed directory and run
+`python3 "$SKILL_ROOT/scripts/readiness.py" reminders`, then `remindctl --version`.
+The startup probe does not authorize EventKit or verify iCloud/notifications.
+The audited 0.1.1 lacks --alarm: enable the alarm examples below only when the
+installed add/edit help explicitly supports that flag. Otherwise report the
+early-notification requirement blocked; do not silently substitute a due date.
+
+- **macOS** with Reminders.app
+- Install: `brew install steipete/tap/remindctl`
+- Grant Reminders permission when prompted
+- Check: `remindctl status` / Request: `remindctl authorize`
+
+## When to Use
+
+- User mentions "reminder" or "Reminders app"
+- Creating personal to-dos with due dates that sync to iOS
+- Managing Apple Reminders lists
+- User wants tasks to appear on their iPhone/iPad
+
+## When NOT to Use
+
+- Scheduling agent alerts → use the actual Prismer task scheduler, not an invented cronjob tool
+- Calendar events → use Apple Calendar or Google Calendar
+- Project task management → use GitHub Issues, Notion, etc.
+- If user says "remind me" but means an agent alert → clarify first
+
+## Quick Reference
+
+### View Reminders
+
+```bash
+remindctl                    # Today's reminders
+remindctl today              # Today
+remindctl tomorrow           # Tomorrow
+remindctl week               # This week
+remindctl overdue            # Past due
+remindctl all                # Everything
+remindctl 2026-01-04         # Specific date
+```
+
+### Manage Lists
+
+```bash
+remindctl list               # List all lists
+remindctl list Work          # Show specific list
+remindctl list Projects --create    # Create list
+remindctl list Work --delete        # Delete list
+```
+
+### Create Reminders
+
+```bash
+remindctl add "Buy milk"
+remindctl add --title "Call mom" --list Personal --due tomorrow
+remindctl add --title "Meeting prep" --due "2026-02-15 09:00"
+```
+
+### Due Time vs Alarm / Early Nudge
+
+When the installed version supports both, `--due` and `--alarm` are different fields:
+
+- `--due` sets the reminder's due date/time.
+- `--alarm` sets the EventKit alarm/notification trigger. Timed due reminders may default to an alarm at the due time, but pass `--alarm` explicitly when the user asks for an earlier nudge.
+
+For a reminder due at 2:00 PM with a notification 30 minutes earlier:
+
+```bash
+remindctl add --title "Hairdresser" --due "2026-05-15 14:00" --alarm "2026-05-15 13:30"
+```
+
+To edit an existing reminder:
+
+```bash
+remindctl edit 87354 --due "2026-05-15 14:00" --alarm "2026-05-15 13:30"
+```
+
+The Reminders UI may show or group the item by the alarm time because that is when the notification fires. Verify with JSON instead of assuming the due time moved:
+
+```bash
+remindctl today --json
+```
+
+Read the actual version's JSON schema; the following fields are version-dependent:
+
+- `dueDate`: actual due time
+- `alarmDate`: notification / early nudge time
+
+Apple's public `EKReminder` docs list only reminder-specific properties. Alarm support comes from inherited `EKCalendarItem` behavior exposed by remindctl's `--alarm` flag.
+
+### Complete / Delete
+
+```bash
+remindctl complete 1 2 3          # Complete by ID
+remindctl delete 4A83 --force     # Delete by ID
+```
+
+### Output Formats
+
+```bash
+remindctl today --json       # JSON for scripting
+remindctl today --plain      # TSV format
+remindctl today --quiet      # Counts only
+```
+
+## Date Formats
+
+Accepted by `--due` and date filters:
+- `today`, `tomorrow`, `yesterday`
+- `YYYY-MM-DD`
+- `YYYY-MM-DD HH:mm`
+- ISO 8601 (`2026-01-04T12:34:56Z`)
+
+## Rules
+
+1. Clarify Apple Reminders versus an agent scheduled task only when intent is ambiguous.
+2. Use the user's stated content/time authorization; clarify only missing fields.
+3. Use `--json` for programmatic parsing
+4. Record host timezone and resolved timestamp. Read back the exact created ID;
+   help/JSON success alone does not prove the notification was delivered.

package/built-in-skills/prismer-apple-reminders/scripts/readiness.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Read-only CLI startup probes. Never opens apps, TCC prompts or account data."""
+import argparse
+import json
+import platform
+import shutil
+import subprocess
+
+
+COMMANDS = {'notes': ['memo', 'notes', '--help'],
+            'reminders': ['remindctl', 'add', '--help'],
+            'imessage': ['imsg', 'send', '--help'],
+            'findmy': ['screencapture', '-h']}
+
+
+def probe(kind, run=subprocess.run):
+    result = {'kind': kind, 'os': platform.system(), 'binary': False,
+              'startup': False, 'account': 'untested', 'permissions': 'untested',
+              'live_operation': 'untested'}
+    if result['os'] != 'Darwin':
+        return {**result, 'reason': 'macOS execution host required'}
+    argv = COMMANDS[kind]
+    result['binary'] = bool(shutil.which(argv[0]))
+    if not result['binary']:
+        return {**result, 'reason': 'missing-command'}
+    try:
+        response = run(argv, capture_output=True, text=True, timeout=10, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        return {**result, 'reason': 'startup-failed'}
+    text = response.stdout + response.stderr
+    result['startup'] = response.returncode == 0 or (kind == 'findmy' and 'screencapture' in text and '-l' in text)
+    result['exit_code'] = response.returncode
+    if kind == 'reminders':
+        result['alarm_supported'] = '--alarm' in text
+    if kind == 'imessage':
+        result['send_flags_supported'] = all(flag in text for flag in ('--to', '--file', '--service'))
+    result['reason'] = 'help-only-not-ready-for-live-operation' if result['startup'] else 'startup-failed'
+    return result
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('kind', choices=COMMANDS)
+    args = parser.parse_args()
+    result = probe(args.kind)
+    print(json.dumps(result))
+    raise SystemExit(0 if result['startup'] else 1)

package/built-in-skills/prismer-ascii-video/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/built-in-skills/prismer-ascii-video/LICENSE.hermes

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/built-in-skills/prismer-ascii-video/PROVENANCE.md

@@ -0,0 +1,7 @@
+# Resource provenance
+
+Imported from hermes-agent skills/creative/ascii-video at 1a1f4a59e252e1dc0137e7b2e7bcc8b0381d19c4.
+
+Prismer receiver: prismer-ascii-video. Native replacement: ascii-video; this is not an alias. Preserve all source resources at their relative paths; merge packs live under references/ascii-video/. Source file hashes and content review: docs/bugfix223/audit-creative-media-coverage.json. Local corrections and remaining live acceptance: docs/bugfix223/implementation-creative.md.
+
+LICENSE.hermes preserves Nous Research MIT terms. External libraries, fonts, services and media have separate licenses; no third-party binary assets were included.

package/built-in-skills/prismer-ascii-video/README.md

@@ -0,0 +1,290 @@
+# ☤ ASCII Video
+
+Renders any content as colored ASCII character video. Audio, video, images, text, or pure math in, MP4/GIF/PNG sequence out. Full RGB color per character cell, 1080p 24fps default. No GPU.
+
+Built for [Hermes Agent](https://github.com/NousResearch/hermes-agent). Usable in any coding agent. Canonical source lives here; synced to [`NousResearch/hermes-agent/skills/creative/ascii-video`](https://github.com/NousResearch/hermes-agent/tree/main/skills/creative/ascii-video) via PR.
+
+## What this is
+
+A skill that teaches an agent how to build single-file Python renderers for ASCII video from scratch. The agent gets the full pipeline: grid system, font rasterization, effect library, shader chain, audio analysis, parallel encoding. It writes the renderer, runs it, gets video.
+
+The output is actual video. Not terminal escape codes. Frames are computed as grids of colored characters, composited onto pixel canvases with pre-rasterized font bitmaps, post-processed through shaders, piped to ffmpeg.
+
+## Modes
+
+| Mode | Input | Output |
+|------|-------|--------|
+| Video-to-ASCII | A video file | ASCII recreation of the footage |
+| Audio-reactive | An audio file | Visuals driven by frequency bands, beats, energy |
+| Generative | Nothing | Procedural animation from math |
+| Hybrid | Video + audio | ASCII video with audio-reactive overlays |
+| Lyrics/text | Audio + timed text (SRT) | Karaoke-style text with effects |
+| TTS narration | Text quotes + API key | Narrated video with typewriter text and generated speech |
+
+## Pipeline
+
+Every mode follows the same 6-stage path:
+
+```
+INPUT --> ANALYZE --> SCENE_FN --> TONEMAP --> SHADE --> ENCODE
+```
+
+1. **Input** loads source material (or nothing for generative).
+2. **Analyze** extracts per-frame features. Audio gets 6-band FFT, RMS, spectral centroid, flatness, flux, beat detection with exponential decay. Video gets luminance, edges, motion.
+3. **Scene function** returns a pixel canvas directly. Composes multiple character grids at different densities, value/hue fields, pixel blend modes. This is where the visuals happen.
+4. **Tonemap** does adaptive percentile-based brightness normalization with per-scene gamma. ASCII on black is inherently dark. Linear multipliers don't work. This does.
+5. **Shade** runs a `ShaderChain` (38 composable shaders) plus a `FeedbackBuffer` for temporal recursion with spatial transforms.
+6. **Encode** pipes raw RGB frames to ffmpeg for H.264 encoding. Segments concatenated, audio muxed.
+
+## Grid system
+
+Characters render on fixed-size grids. Layer multiple densities for depth.
+
+| Size | Font | Grid at 1080p | Use |
+|------|------|---------------|-----|
+| xs | 8px | 400x108 | Ultra-dense data fields |
+| sm | 10px | 320x83 | Rain, starfields |
+| md | 16px | 192x56 | Default balanced |
+| lg | 20px | 160x45 | Readable text |
+| xl | 24px | 137x37 | Large titles |
+| xxl | 40px | 80x22 | Giant minimal |
+
+Rendering the same scene on `sm` and `lg` then screen-blending them creates natural texture interference. Fine detail shows through gaps in coarse characters. Most scenes use two or three grids.
+
+## Character palettes (24)
+
+Each sorted dark-to-bright, each a different visual texture. Validated against the font at init so broken glyphs get dropped silently.
+
+| Family | Examples | Feel |
+|--------|----------|------|
+| Density ramps | ` .:-=+#@█` | Classic ASCII art gradient |
+| Block elements | ` ░▒▓█▄▀▐▌` | Chunky, digital |
+| Braille | ` ⠁⠂⠃...⠿` | Fine-grained pointillism |
+| Dots | ` ⋅∘∙●◉◎` | Smooth, organic |
+| Stars | ` ·✧✦✩✨★✶` | Sparkle, celestial |
+| Half-fills | ` ◔◑◕◐◒◓◖◗◙` | Directional fill progression |
+| Crosshatch | ` ▣▤▥▦▧▨▩` | Hatched density ramp |
+| Math | ` ·∘∙•°±×÷≈≠≡∞∫∑Ω` | Scientific, abstract |
+| Box drawing | ` ─│┌┐└┘├┤┬┴┼` | Structural, circuit-like |
+| Katakana | ` ·ｦｧｨｩｪｫｬｭ...` | Matrix rain |
+| Greek | ` αβγδεζηθ...ω` | Classical, academic |
+| Runes | ` ᚠᚢᚦᚱᚷᛁᛇᛒᛖᛚᛞᛟ` | Mystical, ancient |
+| Alchemical | ` ☉☽♀♂♃♄♅♆♇` | Esoteric |
+| Arrows | ` ←↑→↓↔↕↖↗↘↙` | Directional, kinetic |
+| Music | ` ♪♫♬♩♭♮♯○●` | Musical |
+| Project-specific | ` .·~=≈∞⚡☿✦★⊕◊◆▲▼●■` | Themed per project |
+
+Custom palettes are built per project to match the content.
+
+## Color strategies
+
+| Strategy | How it maps hue | Good for |
+|----------|----------------|----------|
+| Angle-mapped | Position angle from center | Rainbow radial effects |
+| Distance-mapped | Distance from center | Depth, tunnels |
+| Frequency-mapped | Audio spectral centroid | Timbral shifting |
+| Value-mapped | Brightness level | Heat maps, fire |
+| Time-cycled | Slow rotation over time | Ambient, chill |
+| Source-sampled | Original video pixel colors | Video-to-ASCII |
+| Palette-indexed | Discrete lookup table | Retro, flat graphic |
+| Temperature | Warm-to-cool blend | Emotional tone |
+| Complementary | Hue + opposite | Bold, dramatic |
+| Triadic | Three equidistant hues | Psychedelic, vibrant |
+| Analogous | Neighboring hues | Harmonious, subtle |
+| Monochrome | Fixed hue, vary S/V | Noir, focused |
+
+Plus 10 discrete RGB palettes (neon, pastel, cyberpunk, vaporwave, earth, ice, blood, forest, mono-green, mono-amber).
+
+Full OKLAB/OKLCH color system: sRGB↔linear↔OKLAB conversion pipeline, perceptually uniform gradient interpolation, and color harmony generation (complementary, triadic, analogous, split-complementary, tetradic).
+
+## Value field generators (21)
+
+Value fields are the core visual building blocks. Each produces a 2D float array in [0, 1] mapping every grid cell to a brightness value.
+
+### Trigonometric (12)
+
+| Field | Description |
+|-------|-------------|
+| Sine field | Layered multi-sine interference, general-purpose background |
+| Smooth noise | Multi-octave sine approximation of Perlin noise |
+| Rings | Concentric rings, bass-driven count and wobble |
+| Spiral | Logarithmic spiral arms, configurable arm count/tightness |
+| Tunnel | Infinite depth perspective (inverse distance) |
+| Vortex | Twisting radial pattern, distance modulates angle |
+| Interference | N overlapping sine waves creating moire |
+| Aurora | Horizontal flowing bands |
+| Ripple | Concentric waves from configurable source points |
+| Plasma | Sum of sines at multiple orientations/speeds |
+| Diamond | Diamond/checkerboard pattern |
+| Noise/static | Random per-cell per-frame flicker |
+
+### Noise-based (4)
+
+| Field | Description |
+|-------|-------------|
+| Value noise | Smooth organic noise, no axis-alignment artifacts |
+| fBM | Fractal Brownian Motion — octaved noise for clouds, terrain, smoke |
+| Domain warp | Inigo Quilez technique — fBM-driven coordinate distortion for flowing organic forms |
+| Voronoi | Moving seed points with distance, edge, and cell-ID output modes |
+
+### Simulation-based (4)
+
+| Field | Description |
+|-------|-------------|
+| Reaction-diffusion | Gray-Scott with 7 presets: coral, spots, worms, labyrinths, mitosis, pulsating, chaos |
+| Cellular automata | Game of Life + 4 rule variants with analog fade trails |
+| Strange attractors | Clifford, De Jong, Bedhead — iterated point systems binned to density fields |
+| Temporal noise | 3D noise that morphs in-place without directional drift |
+
+### SDF-based
+
+7 signed distance field primitives (circle, box, ring, line, triangle, star, heart) with smooth boolean combinators (union, intersection, subtraction, smooth union/subtraction) and infinite tiling. Render as solid fills or glowing outlines.
+
+## Hue field generators (9)
+
+Determine per-cell color independent of brightness: fixed hue, angle-mapped rainbow, distance gradient, time-cycled rotation, audio spectral centroid, horizontal/vertical gradients, plasma variation, perceptually uniform OKLCH rainbow.
+
+## Coordinate transforms (11)
+
+UV-space transforms applied before effect evaluation: rotate, scale, skew, tile (with mirror seaming), polar, inverse-polar, twist (rotation increasing with distance), fisheye, wave displacement, Möbius conformal transformation. `make_tgrid()` wraps transformed coordinates into a grid object.
+
+## Particle systems (9)
+
+| Type | Behavior |
+|------|----------|
+| Explosion | Beat-triggered radial burst with gravity and life decay |
+| Embers | Rising from bottom with horizontal drift |
+| Dissolving cloud | Spreading outward with accelerating fade |
+| Starfield | 3D projected, Z-depth stars approaching with streak trails |
+| Orbit | Circular/elliptical paths around center |
+| Gravity well | Attracted toward configurable point sources |
+| Boid flocking | Separation/alignment/cohesion with spatial hash for O(n) neighbors |
+| Flow-field | Steered by gradient of any value field |
+| Trail particles | Fading lines between current and previous positions |
+
+14 themed particle character sets (energy, spark, leaf, snow, rain, bubble, data, hex, binary, rune, zodiac, dot, dash).
+
+## Temporal coherence
+
+10 easing functions (linear, quad, cubic, expo, elastic, bounce — in/out/in-out). Keyframe interpolation with eased transitions. Value field morphing (smooth crossfade between fields). Value field sequencing (cycle through fields with crossfade). Temporal noise (3D noise evolving smoothly in-place).
+
+## Shader pipeline
+
+38 composable shaders, applied to the pixel canvas after character rendering. Configurable per section.
+
+| Category | Shaders |
+|----------|---------|
+| Geometry | CRT barrel, pixelate, wave distort, displacement map, kaleidoscope, mirror (h/v/quad/diag) |
+| Channel | Chromatic aberration (beat-reactive), channel shift, channel swap, RGB split radial |
+| Color | Invert, posterize, threshold, solarize, hue rotate, saturation, color grade, color wobble, color ramp |
+| Glow/Blur | Bloom, edge glow, soft focus, radial blur |
+| Noise | Film grain (beat-reactive), static noise |
+| Lines/Patterns | Scanlines, halftone |
+| Tone | Vignette, contrast, gamma, levels, brightness |
+| Glitch/Data | Glitch bands (beat-reactive), block glitch, pixel sort, data bend |
+
+12 color tint presets: warm, cool, matrix green, amber, sepia, neon pink, ice, blood, forest, void, sunset, neutral.
+
+7 mood presets for common shader combos:
+
+| Mood | Shaders |
+|------|---------|
+| Retro terminal | CRT + scanlines + grain + amber/green tint |
+| Clean modern | Light bloom + subtle vignette |
+| Glitch art | Heavy chromatic + glitch bands + color wobble |
+| Cinematic | Bloom + vignette + grain + color grade |
+| Dreamy | Heavy bloom + soft focus + color wobble |
+| Harsh/industrial | High contrast + grain + scanlines, no bloom |
+| Psychedelic | Color wobble + chromatic + kaleidoscope mirror |
+
+## Blend modes and composition
+
+20 pixel blend modes for layering canvases: normal, add, subtract, multiply, screen, overlay, softlight, hardlight, difference, exclusion, colordodge, colorburn, linearlight, vividlight, pin_light, hard_mix, lighten, darken, grain_extract, grain_merge. Both sRGB and linear-light blending supported.
+
+**Feedback buffer.** Temporal recursion — each frame blends with a transformed version of the previous frame. 7 spatial transforms: zoom, shrink, rotate CW/CCW, shift up/down, mirror. Optional per-frame hue shift for rainbow trails. Configurable decay, blend mode, and opacity per scene.
+
+**Masking.** 16 mask types for spatial compositing: shape masks (circle, rect, ring, gradients), procedural masks (any value field as a mask, text stencils), animated masks (iris open/close, wipe, dissolve), boolean operations (union, intersection, subtraction, invert).
+
+**Transitions.** Crossfade, directional wipe, radial wipe, dissolve, glitch cut.
+
+## Scene design patterns
+
+Compositional patterns for making scenes that look intentional rather than random.
+
+**Layer hierarchy.** Background (dim atmosphere, dense grid), content (main visual, standard grid), accent (sparse highlights, coarse grid). Three distinct roles, not three competing layers.
+
+**Directional parameter arcs.** The defining parameter of each scene ramps, accelerates, or builds over its duration. Progress-based formulas (linear, ease-out, step reveal) replace aimless `sin(t)` oscillation.
+
+**Scene concepts.** Scenes built around visual metaphors (emergence, descent, collision, entropy) with motivated layer/palette/feedback choices. Not named after their effects.
+
+**Compositional techniques.** Counter-rotating dual systems, wave collision, progressive fragmentation (voronoi cells multiplying over time), entropy (geometry consumed by reaction-diffusion), staggered layer entry (crescendo buildup).
+
+## Hardware adaptation
+
+Auto-detects CPU count, RAM, platform, ffmpeg. Adapts worker count, resolution, FPS.
+
+| Profile | Resolution | FPS | When |
+|---------|-----------|-----|------|
+| `draft` | 960x540 | 12 | Check timing/layout |
+| `preview` | 1280x720 | 15 | Review effects |
+| `production` | 1920x1080 | 24 | Final output |
+| `max` | 3840x2160 | 30 | Ultra-high |
+| `auto` | Detected | 24 | Adapts to hardware + duration |
+
+`auto` estimates render time and downgrades if it would take over an hour. Low-memory systems drop to 720p automatically.
+
+### Render times (1080p 24fps, ~180ms/frame/worker)
+
+| Duration | 4 workers | 8 workers | 16 workers |
+|----------|-----------|-----------|------------|
+| 30s | ~3 min | ~2 min | ~1 min |
+| 2 min | ~13 min | ~7 min | ~4 min |
+| 5 min | ~33 min | ~17 min | ~9 min |
+| 10 min | ~65 min | ~33 min | ~17 min |
+
+720p roughly halves these. 4K roughly quadruples them.
+
+## Known pitfalls
+
+**Brightness.** ASCII characters are small bright dots on black. Most frame pixels are background. Linear `* N` multipliers clip highlights and wash out. Use `tonemap()` with per-scene gamma instead. Default gamma 0.75, solarize scenes 0.55, posterize 0.50.
+
+**Render bottleneck.** The per-cell Python loop compositing font bitmaps runs at ~100-150ms/frame. Unavoidable without Cython/C. Everything else must be vectorized numpy. Python for-loops over rows/cols in effect functions will tank performance.
+
+**ffmpeg deadlock.** Never `stderr=subprocess.PIPE` on long-running encodes. Buffer fills at ~64KB, process hangs. Redirect stderr to a file.
+
+**Font cell height.** Pillow's `textbbox()` returns wrong height on macOS. Use `font.getmetrics()` for `ascent + descent`.
+
+**Font compatibility.** Not all Unicode renders in all fonts. Palettes validated at init, blank glyphs silently removed.
+
+## Requirements
+
+◆ Python 3.10+
+◆ NumPy, Pillow, SciPy (audio modes)
+◆ ffmpeg on PATH
+◆ A monospace font (Menlo, Courier, Monaco, auto-detected)
+◆ Optional: OpenCV, ElevenLabs API key (TTS mode)
+
+## File structure
+
+```
+├── SKILL.md                 # Modes, workflow, creative direction
+├── README.md                # This file
+└── references/
+    ├── architecture.md      # Grid system, fonts, palettes, color, _render_vf()
+    ├── effects.md           # Value fields, hue fields, backgrounds, particles
+    ├── shaders.md           # 38 shaders, ShaderChain, tint presets, transitions
+    ├── composition.md       # Blend modes, multi-grid, tonemap, FeedbackBuffer
+    ├── scenes.md            # Scene protocol, SCENES table, render_clip(), examples
+    ├── design-patterns.md   # Layer hierarchy, directional arcs, scene concepts
+    ├── inputs.md            # Audio analysis, video sampling, text, TTS
+    ├── optimization.md      # Hardware detection, vectorized patterns, parallelism
+    └── troubleshooting.md   # Broadcasting traps, blend pitfalls, diagnostics
+```
+
+## Projects built with this
+
+✦ 85-second highlight reel. 15 scenes (14×5s + 15s crescendo finale), randomized order, directional parameter arcs, layer hierarchy composition. Showcases the full effect vocabulary: fBM, voronoi fragmentation, reaction-diffusion, cellular automata, dual counter-rotating spirals, wave collision, domain warping, tunnel descent, kaleidoscope symmetry, boid flocking, fire simulation, glitch corruption, and a 7-layer crescendo buildup.
+
+✦ Audio-reactive music visualizer. 3.5 min, 8 sections with distinct effects, beat-triggered particles and glitch, cycling palettes.
+
+✦ TTS narrated testimonial video. 23 quotes, per-quote ElevenLabs voices, background music at 15% wide stereo, per-clip re-rendering for iterative editing.