shellfie 0.1.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2aa4926f71fb587dd2ec442e5257a849e8af9b7fbbb7fb62e0ef1a840cd8dac6
-  data.tar.gz: 6dbfb90a504e732089a68548970c1ac17879338793612c50872b2cc762572b7f
+  metadata.gz: 0dbccd8edad54ded2bda6b8da245ab3f4ab3c9527ffd4bc75ef04cf7b6fc8713
+  data.tar.gz: 5fa83b5f80fae2d6281adc4ef685271af2b8c8f303d4116cbe26904ecf12c2a4
 SHA512:
-  metadata.gz: 278e0eabca9c70c2284ca9ccbcba74933fe14e24e6c1050c0a2b635a058fb01d22d353f854083bc8edd4531c7565dbb4e47f84eebc286a33721c238bc025e568
-  data.tar.gz: 2712539d09a9d2fe1e2149d6786f230ba68b230ea2f3fa3f885c081f52985d4437d0020a702fa9af2c2eed4fdb781dd0d4fa68d251fb1d11338ae090014eea1a
+  metadata.gz: 473c51c3384978e8bc493b0a27cc1b5e9949c99c9f14d2cd6516cae963648c07bd281650175713f4028c09be1ce5d0140c119a4ffd7336da92e8a80075c43f30
+  data.tar.gz: fc061b6f9bff4c8f5bf7f512891ed8c13b39bf3342a14a5b98b967b15ac68a7d0dafc582ac884ea402e9d4ba61a0e549ca19d1883575c3af69a4e7e556b1d063

data/CHANGELOG.md

@@ -1,6 +1,60 @@
 # Changelog
 
-## Unreleased
+## 1.1.0 - 2026-08-29
+
+### Added
+
+- Add executable version 2 sessions with `run`, `record`, and `replay`; PTY sessions support command and key input, waits, assertions, hidden steps, redaction, named captures, editable recordings, and offline cassettes.
+- Add native selectable-text SVG, accessible HTML, MP4, WebM, event-duration PNG sequences, plain and ANSI-preserving text, structured JSON, and asciinema v2 output. Legacy raster-backed SVG remains available as `svg-raster`.
+- Add multiple configured outputs and capture-specific outputs from one session.
+- Add JSON Schemas, file/line/column diagnostics, typo suggestions, and `new`, `format`, `compile`, `schema`, `completion`, and include-aware `watch` authoring commands.
+- Add typed session variables, reusable and repeated step sets, and OS, shell, Ruby, and configured-environment step conditions.
+- Add inferred output names, collision-checked output templates, common aspect presets, bounded parallel batch rendering with `--jobs`, and non-mutating output verification with `generate --check`.
+- Add reproducibility manifests and JSON, SARIF, and JUnit validation reports for CI and editor integrations.
+- Add a reusable GitHub Action for generating or checking outputs and Docker packaging for a consistent rendering environment.
+- Add deterministic animation seeds, separate typing rate, frame timing, and playback speed controls, reverse and ping-pong playback, loop offsets, and format-specific GIF, WebP, and APNG controls.
+- Add configurable East Asian Ambiguous width and report the active Unicode and width-table profile through inspection and manifests.
+- Add broader terminal behavior for cursor movement, erase and insertion controls, alternate screens, scroll regions, colon-form colors, extended underline styles and colors, blink, conceal, and safe OSC 8 links.
+
+### Changed
+
+- Treat every frame `delay` as a post-action delay; a `type` frame's delay now overrides the global command delay, and `lines` initialize the screen when `frames` are also present.
+- Treat an explicit WebP format as static unless the input has frames or `--animate` is supplied.
+- Deprecate `--fps` in favor of `--framerate`; use `--typing-rate` to control input speed independently.
+
+### Fixed
+
+- Correct terminal tab stops, backspace behavior, wide-cell overwrites, grapheme-cluster typing, split Unicode input, line feeds, autowrap, and scroll-region editing.
+- Correct animation duration rounding, duplicate-frame timing, APNG tail duration, playback-speed timing, and minimum video duration.
+- Prevent output collisions before rendering, stream stdout without an output-sized memory copy, preserve existing outputs on failure, and remove partial animation files after errors or interruption.
+- Improve live-session prompt and exit synchronization, preserve asynchronous output, honor PTY dimensions and working directories, and terminate leftover child processes.
+- Improve `doctor` and dependency checks with real rendering, format delegates, fonts, security policy, and temporary-storage diagnostics.
+
+### Security and reliability
+
+- Add include cycle and chain diagnostics, per-file and aggregate size limits, and an optional symlink-aware root policy for includes and session working directories.
+- Add environment allowlists, total and per-step timeouts, bounded regular-expression evaluation, output and control-sequence limits, and rendering workload and temporary-disk budgets.
+- Add opt-in rejection of unsupported terminal graphics and an explicit policy for preserving only bounded `http`, `https`, and `mailto` OSC 8 links.
+
+## 1.0.0 - 2026-05-20
+
+### Added
+
+- Add static SVG and WebP output plus animated WebP and APNG output, with format selection by extension or `--format` and binary output through stdout.
+- Add batch generation from multiple files and glob patterns, directory outputs, automatic output-directory creation, and `--quiet` and `--verbose` modes.
+- Add `inspect` for resolved configuration and output dimensions, and `doctor` for Ruby, ImageMagick, output-directory, and encoding checks.
+- Add custom themes, Dracula, One Dark, Solarized Dark, and Catppuccin Mocha color schemes, configurable colors and window decorations, background gradients, font fallbacks, and block, bar, or underline cursors.
+- Add reusable YAML includes, line selection and semantic prompt, command, and output colors.
+- Add clip, wrap, and scroll overflow modes, exact-size and trimmed canvases, maximum height and line controls, configurable tab width, and per-line or persistent ANSI state.
+- Add animation typing jitter and chunking, output and final delays, frame limits, global, adaptive, or theme palettes, optional dithering, and configurable scroll easing.
+- Add public Ruby APIs for parsing, validating, rendering, and inspecting configurations.
+
+### Changed
+
+- Correct xterm 256-color values and malformed extended colors, and add dim, reverse, strikethrough, and overline styles plus carriage return, backspace, cursor movement, erase, and tab handling.
+- Improve line measurement, clipping, wrapping, fixed-height scrolling, trailing-line preservation, stable animation dimensions, and Windows, Ubuntu, macOS, and headless window rendering.
+- Refuse to replace an existing output unless `--force` is supplied, write outputs atomically, report errors on stderr, and distinguish filesystem failures with their own exit code.
+- Reject unknown keys, invalid types, unsupported values, excessive lines, frames, characters, pixels, and rendered frames with clearer validation errors before rendering.
 
 ## 0.1.1 - 2026-01-12
 
@@ -8,4 +62,4 @@
 
 ## 0.1.0 - 2026-01-12
 
-- Initial release.
+- Initial release.

data/README.md

@@ -1,333 +1,353 @@
 <p align="center">
-  <img src="assets/logo-header.svg" alt="shellfie header logo">
-  <p align="center">
-    <strong>Generate beautiful terminal screenshots from YAML</strong>
-  </p>
-  <p align="center">
-    <a href="https://rubygems.org/gems/shellfie"><img src="https://img.shields.io/gem/v/shellfie.svg?colorB=319e8c" alt="Gem Version"></a>
-    <a href="https://rubygems.org/gems/shellfie"><img src="https://img.shields.io/gem/dt/shellfie.svg" alt="Downloads"></a>
-    <img src="https://img.shields.io/badge/ruby-%3E%3D%203.0-ruby.svg" alt="Ruby Version">
-    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
-  </p>
+  <img src="assets/logo-header.svg" alt="Shellfie header logo">
 </p>
 
 <p align="center">
-  <a href="#features">Features</a> •
-  <a href="#installation">Installation</a> •
-  <a href="#usage">Usage</a> •
-  <a href="#configuration">Configuration</a> •
-  <a href="#themes">Themes</a>
+  <strong>Deterministic terminal visuals and executable sessions from YAML</strong>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/shellfie"><img src="https://img.shields.io/gem/v/shellfie.svg?colorB=319e8c" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/shellfie"><img src="https://img.shields.io/gem/dt/shellfie.svg" alt="Downloads"></a>
+  <img src="https://img.shields.io/badge/ruby-%3E%3D%203.0-ruby.svg" alt="Ruby Version">
+  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#terminal-sessions">Terminal Sessions</a> ·
+  <a href="#configuration">Configuration</a> ·
+  <a href="#automation">Automation</a>
 </p>
 
 ---
 
-**Shellfie** (Shell + Selfie) creates stunning terminal screenshot-style images from simple YAML configuration files. Perfect for documentation, README files, tutorials, and presentations — without actually taking screenshots.
+Shellfie compiles YAML into deterministic terminal images, animations, and semantic transcripts. When explicitly requested, it can also run real PTY sessions, assert their output, record cassettes, and replay them offline.
 
 <p align="center">
-  <img src="examples/demo.gif" alt="Shellfie Demo" width="550">
+  <img src="examples/demo.gif" alt="Shellfie generating and validating an animated terminal demo" width="720">
+  <br>
+  <sub>Generated by Shellfie from <a href="examples/demo_animation.yml">examples/demo_animation.yml</a>.</sub>
 </p>
 
 ## Features
 
-### Multiple Themes
-
-Generate images with different terminal styles:
+- Deterministic compose mode that never executes configuration content
+- Optional PTY execution with waits, assertions, captures, and redaction
+- Editable recordings and offline cassette replay
+- PNG, WebP, native SVG, HTML, GIF, APNG, MP4, WebM, and PNG sequence output
+- Plain text, ANSI, JSON, and asciinema v2 semantic transcripts
+- macOS, Ubuntu, Windows, and custom window styles, plus a headless mode
+- ANSI colors and controls, Unicode grapheme handling, and configurable ambiguous width
+- JSON Schemas, source-aware diagnostics, formatting, compilation, completion, and watch commands
+- Resource limits, path policies, dependency preflight, and atomic output replacement
 
-<table>
-  <tr>
-    <th>macOS</th>
-    <th>Ubuntu</th>
-    <th>Windows</th>
-  </tr>
-  <tr>
-    <td><img src="examples/theme_macos.png" width="280" alt="macOS theme"></td>
-    <td><img src="examples/theme_ubuntu.png" width="280" alt="Ubuntu theme"></td>
-    <td><img src="examples/theme_windows.png" width="280" alt="Windows theme"></td>
-  </tr>
-</table>
-
-### Animated GIFs
+## Installation
 
-Create typing animations with realistic effects:
+Add Shellfie to your Gemfile:
 
-```yaml
-animation:
-  typing_speed: 50    # Milliseconds per character
-  command_delay: 500  # Pause after command
-  loop: true          # Loop animation
+```ruby
+gem "shellfie"
 ```
 
-### Full ANSI Color Support
-
-- Standard 8 colors + bright variants
-- 256-color palette
-- True color (24-bit RGB)
-- Bold, italic, underline styles
+Then install:
 
-### Flexible Output Options
+```bash
+bundle install
+```
 
-- **High DPI support** — Generate 2x or 3x scaled images for Retina displays
-- **Headless mode** — Output without window decorations
-- **Shadow effects** — Beautiful drop shadows
-- **Transparent backgrounds** — Perfect for overlays
-- **Fixed height with scrolling** — Consistent GIF dimensions
+Or install it directly:
 
-## Installation
+```bash
+gem install shellfie
+```
 
 ### Requirements
 
 - Ruby 3.0+
-- ImageMagick 7.0+
+- ImageMagick
+- ffmpeg for MP4, WebM, and APNG output
 
-```bash
-# Install ImageMagick first
-brew install imagemagick      # macOS
-sudo apt install imagemagick  # Ubuntu/Debian
-choco install imagemagick     # Windows
-```
-
-### Install the gem
+Install media dependencies on macOS:
 
 ```bash
-gem install shellfie
+brew install imagemagick ffmpeg
 ```
 
-Or add to your Gemfile:
+On Ubuntu or Debian:
 
-```ruby
-gem 'shellfie'
+```bash
+sudo apt install imagemagick ffmpeg
 ```
 
-## Usage
+Static and animated composition works on macOS, Linux, and Windows. Live PTY sessions are not supported on native Windows.
 
-### Quick Start
+## Quick Start
 
-1. Create a configuration file:
+Create `terminal.yml`:
 
 ```yaml
-# terminal.yml
+version: 1
 theme: macos
-title: "Terminal — zsh"
-
-window:
-  width: 600
-  padding: 20
+title: "Terminal"
 
 lines:
   - prompt: "$ "
-    command: "echo 'Hello, World!'"
-  - output: "Hello, World!"
+    command: "echo hello"
+  - output: "hello"
 ```
 
-2. Generate an image:
+Generate an image:
 
 ```bash
-shellfie generate terminal.yml -o output.png
+shellfie generate terminal.yml -o terminal.png
 ```
 
-### Commands
+Without `-o`, Shellfie writes `terminal.png` beside the input. `shf` is available as a short alias for `shellfie`.
 
-| Command | Description |
-|---------|-------------|
-| `shellfie generate <file> -o <output>` | Generate image from config |
-| `shellfie init` | Output sample configuration |
-| `shellfie themes` | List available themes |
-| `shellfie validate <file>` | Validate configuration |
-| `shellfie version` | Show version |
-| `shellfie help` | Show help |
+### Output Formats
 
-> [!TIP]
-> Use `shf` as a shorter alias for `shellfie`
+| Kind | Formats |
+| --- | --- |
+| Static | PNG, WebP, native selectable-text SVG, accessible HTML |
+| Animated | GIF, WebP, APNG, MP4, WebM, event-duration PNG sequence with `timeline.json` |
+| Semantic | TXT, ANSI, JSON, asciinema v2 (`asciicast` or `cast`) |
 
-### Generate Options
+Use `svg-raster` only when the legacy PNG-backed SVG behavior is required.
 
-```bash
-shellfie generate config.yml -o output.png [options]
-```
+## CLI
 
-| Option | Description |
-|--------|-------------|
-| `-o, --output PATH` | Output file path (required) |
-| `-t, --theme NAME` | Override theme (`macos`, `ubuntu`, `windows`) |
-| `-a, --animate` | Generate animated GIF |
-| `-s, --scale FACTOR` | Output scale (1, 2, 3) for HiDPI |
-| `-w, --width PIXELS` | Override width |
-| `--no-shadow` | Disable shadow effect |
-| `--no-header` | Disable window header (headless mode) |
-| `--transparent` | Transparent background |
+| Command | Purpose |
+| --- | --- |
+| `generate` | Render a version 1 compose configuration |
+| `run` | Execute and render a version 2 terminal session |
+| `record` | Execute a session and save a cassette or editable YAML |
+| `replay` | Render a cassette without executing its commands |
+| `new` / `init` | Create or print starter configuration |
+| `format` | Normalize YAML formatting |
+| `compile` | Print the resolved configuration or session IR |
+| `validate` | Validate input as text, JSON, SARIF, or JUnit |
+| `inspect` | Show resolved settings, dimensions, fonts, and resource estimates |
+| `schema` | Print the version 1 or version 2 JSON Schema |
+| `completion` | Print bash, zsh, fish, or PowerShell completion |
+| `watch` | Regenerate when a configuration or include changes |
+| `themes` | List available themes and color schemes |
+| `doctor` | Check media tools, formats, fonts, policies, and storage |
+| `version` | Show the installed Shellfie version |
 
-### Examples
+## Terminal Sessions
 
-```bash
-# Basic PNG
-shellfie generate config.yml -o terminal.png
+Version 2 sessions execute commands only through `run` or `record`; review a session before running it. A minimal session looks like this:
 
-# Animated GIF
-shellfie generate config.yml -o demo.gif --animate
+```yaml
+version: 2
+mode: run
+title: "Recorded shell"
+theme: macos
 
-# Retina-ready (2x scale)
-shellfie generate config.yml -o terminal@2x.png --scale 2
+terminal:
+  shell: /bin/sh
+  columns: 80
+  rows: 16
+  timeout: 10s
+
+steps:
+  - type: printf 'hello from shellfie\n'
+    speed: 30cps
+  - key: enter
+  - expect:
+      screen_contains: hello from shellfie
+      exit_status: 0
+  - capture: complete
+
+outputs:
+  - path: session.svg
+    format: svg
+    capture: complete
+  - path: session.txt
+    format: txt
+```
 
-# Headless (no window decorations)
-shellfie generate config.yml -o code.png --no-header
+Run, record, or replay it:
 
-# Ubuntu theme with custom width
-shellfie generate config.yml -o ubuntu.png -t ubuntu -w 800
+```bash
+shellfie run session.yml
+shellfie record session.yml --cassette session.json
+shellfie record session.yml --yaml editable-recording.yml
+shellfie replay session.json -o session.gif --animate
 ```
 
-## Configuration
+### Session Actions
 
-### Basic Structure
+| Action | Purpose |
+| --- | --- |
+| `run` | Execute a command directly, hidden by default |
+| `type` | Type visible text at a configurable rate |
+| `key` | Send Enter, arrows, modifiers, and other terminal keys |
+| `sleep` | Add a deterministic presentation pause |
+| `wait` | Wait for screen, line, prompt, exit, or stable-screen conditions |
+| `expect` | Assert screen text, lines, exit status, cursor, elapsed time, or a text golden |
+| `hide` / `show` | Control whether preparation and cleanup are recorded |
+| `capture` | Name an intermediate screen for a specific output |
 
-```yaml
-theme: macos              # Theme: macos, ubuntu, windows
-title: "Terminal — zsh"   # Window title
-headless: false           # Hide window decorations
+Sessions also support `requires`, step-level working directories, multiple outputs, reusable includes, environment allowlists, total and per-step timeouts, and redaction patterns. Set `terminal.cwd_policy: root` to confine working directories to the session root. Use `async: true` before interacting with a long-running or full-screen process, then synchronize with `wait`.
 
-window:
-  width: 600              # Window width in pixels
-  padding: 20             # Content padding
-  visible_lines: 10       # Fixed line count (for scrolling GIFs)
+Variables use `{{name}}` placeholders. Reusable `step_sets` expand through `use`, `repeat` repeats a step or set, and `if` can select steps by OS, shell, Ruby requirement, or explicitly configured environment values. Expansion is bounded and cycles are rejected.
 
-font:
-  family: "Monaco"        # Font family
-  size: 14                # Font size
-  line_height: 1.4        # Line height multiplier
+## Authoring
 
-lines:                    # Static content
-  - prompt: "$ "
-    command: "echo hello"
-  - output: "hello"
+Create and inspect configurations without rendering them:
+
+```bash
+shellfie new terminal.yml --template static
+shellfie new demo.yml --template animation
+shellfie new session.yml --template run
+shellfie format terminal.yml
+shellfie compile terminal.yml --format json
+shellfie validate terminal.yml --format sarif
+shellfie inspect terminal.yml --json
+shellfie watch terminal.yml -o terminal.png
 ```
 
-### Static Images
+Templates include `static`, `animation`, `run`, `tui`, `ci`, and `theme-gallery`. JSON Schemas live in [`schema/`](schema/); add the following directive for editor validation:
 
 ```yaml
-theme: macos
-title: "Terminal"
-
-lines:
-  - prompt: "$ "
-    command: "gem install shellfie"
-
-  - output: |
-      Fetching shellfie-0.1.0.gem
-      Successfully installed shellfie-0.1.0
-      1 gem installed
-
-  - prompt: "$ "
-    command: ""
+# yaml-language-server: $schema=../schema/shellfie-v1.schema.json
 ```
 
-### Animated GIFs
+Use schema version 2 for executable sessions. Run `shellfie schema 1` or `shellfie schema 2` to print either schema, and `shellfie completion zsh` to generate shell completion.
 
-```yaml
-theme: macos
-title: "Demo"
+## Automation
 
-animation:
-  typing_speed: 50      # ms per character
-  command_delay: 500    # ms after command execution
-  cursor_blink: true    # Show blinking cursor
-  loop: true            # Loop the animation
-
-frames:
-  - prompt: "$ "
-    type: "echo 'Hello!'"   # Text to type (animated)
-    delay: 500              # Pause after this frame
+Use the Docker-based GitHub Action to generate an output or fail when a committed output is stale:
 
-  - output: "Hello!"
-    delay: 1000
+```yaml
+- uses: ydah/shellfie@main
+  with:
+    input: examples/simple.yml
+    output: docs/terminal.png
+    check: "true"
 ```
 
-### ANSI Colors
+Or build and run the included container locally:
 
-```yaml
-lines:
-  - prompt: "\e[32muser@host\e[0m:\e[34m~/project\e[0m$ "
-    command: "ls"
-
-  - output: "\e[34mdir1\e[0m  \e[32mfile.txt\e[0m  \e[31merror.log\e[0m"
+```bash
+docker build -t shellfie .
+docker run --rm -v "$PWD:/work" shellfie \
+  generate /work/examples/simple.yml -o /work/terminal.png --force
 ```
 
-**Supported escape codes:**
+Use `--manifest manifest.json` during generation to record configuration and output hashes, Ruby, OS, ImageMagick, ffmpeg, and resolved font fingerprints.
 
-| Code | Effect |
-|------|--------|
-| `\e[0m` | Reset |
-| `\e[1m` | Bold |
-| `\e[3m` | Italic |
-| `\e[4m` | Underline |
-| `\e[30-37m` | Foreground colors |
-| `\e[40-47m` | Background colors |
-| `\e[90-97m` | Bright foreground |
-| `\e[38;5;Nm` | 256-color foreground |
-| `\e[38;2;R;G;Bm` | RGB foreground |
-
-### Fixed Height with Scrolling
+## Configuration
 
-For GIFs with many lines, use `visible_lines` to maintain consistent dimensions:
+### Compose Configuration
+
+| Key | Purpose |
+| --- | --- |
+| `theme` | `macos`, `ubuntu`, `windows`, or `custom` |
+| `window_theme` | Window chrome to use with a custom theme |
+| `color_scheme` | Built-in palette: `dracula`, `one_dark`, `solarized_dark`, or `catppuccin_mocha` |
+| `colors` | Individual color overrides |
+| `window` | Width, height, padding, wrapping, clipping, scrolling, and terminal policies |
+| `font` | Family, fallback families, size, and line height |
+| `animation` | Typing, timing, playback, loop, palette, and encoder controls |
+| `cursor` | Cursor style and color |
+| `headless` | Hide window chrome |
+| `lines` | Initial or static terminal content |
+| `frames` | Animated terminal events |
+| `limits` | Source, output-frame, pixel, and temporary-storage ceilings |
+
+Static content uses `lines`; animations add `frames`:
 
 ```yaml
+version: 1
+theme: macos
+title: "Demo"
+
 window:
   width: 600
-  visible_lines: 8    # Show only last 8 lines
+  padding: 20
+  visible_lines: 8
+  overflow: clip
+
+animation:
+  typing_speed: 50
+  framerate: 30
+  playback_speed: 1.0
+  cursor_blink: true
+  loop: true
+  seed: 1
+
+lines:
+  - output: "Ready"
 
 frames:
   - prompt: "$ "
-    type: "for i in {1..20}; do echo $i; done"
-  # Lines will scroll as content exceeds visible_lines
+    type: "echo hello"
+    delay: 500
+  - output: "hello"
+    delay: 1000
 ```
 
-## Themes
-
-### macOS (default)
-
-Classic macOS Terminal appearance with traffic light buttons (red, yellow, green) on the left side.
-
-### Ubuntu
-
-GNOME Terminal style with window controls on the right side and Ubuntu's signature purple background.
-
-### Windows Terminal
-
-Modern Windows Terminal design with flat styling and square corners.
-
-### Headless Mode
+A frame `delay` is applied after its action; on a `type` frame it overrides `animation.command_delay`. When both `lines` and `frames` are present, `lines` initialize the screen before animated events run.
 
-No window decorations — just the terminal content. Perfect for embedding in documentation.
-
-<p align="center">
-  <img src="examples/headless.png" alt="Headless mode" width="500">
-</p>
-
-```bash
-shellfie generate config.yml -o output.png --no-header
-```
-
-Or in YAML:
+### Generate Options
 
-```yaml
-headless: true
-```
+| Option | Description |
+| --- | --- |
+| `-o, --output PATH` | Output path or `{name}-{theme}-{scale}.{format}` template |
+| `--preset NAME` | Exact `readme`, `ogp`, `widescreen`, `standard`, or `vertical` canvas |
+| `-t, --theme NAME` | Override the theme |
+| `-a, --animate` | Render animation |
+| `-s, --scale FACTOR` | Output scale: `1`, `2`, or `3` |
+| `-w, --width PIXELS` | Override width |
+| `--format FORMAT` | Select an output format |
+| `--check` | Fail if an existing output is stale without replacing it |
+| `--jobs N` | Render up to 32 inputs in parallel after preflight |
+| `--typing-rate CPS` | Override typing rate in characters per second |
+| `--framerate FPS` | Set output timing precision |
+| `--seed N` | Set the deterministic animation seed |
+| `--playback-speed FACTOR` | Scale the final timeline |
+| `--overflow MODE` | `clip`, `wrap`, or `scroll` |
+| `--no-shadow` | Disable the window shadow |
+| `--transparent` | Use a transparent background |
+| `--no-header` | Hide window chrome |
+| `--force` | Replace an existing output |
+
+### Advanced Controls
+
+- Set `animation.direction` to `forward`, `reverse`, or `ping_pong`; `animation.loop_offset` selects a different initial frame.
+- Tune GIF colors and optimization, WebP quality and lossless mode, APNG prediction and loop count, and scroll easing under `animation`.
+- Set `window.ambiguous_width` to `1` or `2`; inspection and manifests report the active Unicode and width-table profile.
+- Set `window.osc_policy: preserve` to keep bounded `http`, `https`, and `mailto` OSC 8 links in SVG and HTML.
+- Set `window.graphics_policy: error` to reject SIXEL, Kitty, or iTerm2 graphics instead of discarding them.
+- Use `include` for shared YAML. Set `include_policy: root` to reject paths outside the root configuration directory, including symlink escapes.
+- Set resource ceilings under `limits`; Shellfie checks source size, pixels, frame work, and temporary storage before expensive rendering.
+
+## How It Works
+
+1. Configuration parsing resolves includes, validates input, and reports source locations.
+2. Compose, live PTY, or cassette input is normalized into terminal events.
+3. The terminal screen applies Unicode, ANSI, cursor, erase, alternate-screen, and scroll behavior.
+4. Raster, SVG, HTML, video, or semantic renderers produce the requested outputs.
+5. Output files are written atomically after dependency, collision, and resource preflight.
+
+`generate` is deterministic and never runs configuration content. `run` and `record` opt into PTY execution. `replay` uses a cassette and does not execute the recorded commands.
 
 ## Development
 
 ```bash
-git clone https://github.com/yourusername/shellfie.git
-cd shellfie
-
 bundle install
-bundle exec rspec      # Run tests
+bundle exec rspec
+gem build shellfie.gemspec
 ```
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -am 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before submitting changes or security reports.
 
 ## License