# PIXELFLOW-CLI KNOWLEDGE BASE

## OVERVIEW

Cross-crate layering lives in `crates/AGENTS.md`; below only edge UX/orchestration rules.
`pixelflow-cli` = package name in `Cargo.toml`; installed binary name = `pixelflow` via `[[bin]]`.
Single entry file: `src/main.rs`.
Crate depends on `pixelflow`, `pixelflow-script`, `pixelflow-filters`, plus `clap`.
Role: user-facing orchestration shell around library crates. Parse args, wire core, run script/render pipeline, report diagnostics.

## WHERE TO LOOK

- `crates/pixelflow-cli/Cargo.toml` — package/bin split, dependency surface, workspace lint inheritance.
- `crates/pixelflow-cli/src/main.rs` — all runtime behavior, tests, helpers.
- `parse_args` + `validate_cli_args` — render-vs-subcommand validation.
- `build_core` — core config, built-in filter registration, dynamic plugin load order.
- `run` — full happy-path orchestration.
- `output_media` + `render_y4m` — final-output checks, render loop, Y4M writer path.
- `print_version` — normal vs verbose version output.
- Inline tests near file end — current executable behavior spec.

## CONVENTIONS

- Keep CLI thin. Boundary logic belongs here; reusable semantics belong in library crates.
- Render mode requires both `SCRIPT` and `-o`; `version` subcommand bypasses those requirements.
- `--threads` must parse to positive non-zero `usize`.
- `build_core` disables auto plugin loading, applies optional worker-thread override, registers built-in filters first, then loads plugins from platform directories.
- `run` pipeline order matters: read script -> evaluate with `ScriptEngine` -> index reachable FFMS2 sources -> split graph/executors -> `graph.validate()` -> build builtin executors -> ensure reachable executors -> render Y4M.
- Output path `-` means raw Y4M to stdout; diagnostics/progress/timings/index messages go to stderr.
- File output uses `BufWriter`; stdout path locks stdout and stderr separately.
- Verbose `version` prints core version, enabled feature summary, plugin ABI, loaded plugin list.
- Y4M path only accepts fixed format, fixed resolution, finite frame count, CFR output, and Y4M-compatible final pixel format.

## ANTI-PATTERNS

- Do not move graph validation, filter semantics, source semantics, or executor semantics into CLI helpers because `main.rs` already large.
- Do not rely on `pixelflow::Core` auto plugin scanning here; current behavior intentionally disables it.
- Do not reorder built-in filter registration after plugin load without explicit compatibility reason.
- Do not mix progress/timing/index chatter into stdout; stdout may be pipe target for Y4M bytes.
- Do not widen CLI-only expectations into core contracts; keep clap errors and output-path UX at edge.
- Do not add second orchestration path that skips reachable-source indexing or executor reachability checks.

## NOTES

- `main.rs` currently ~700 lines because crate holds user-facing wiring plus inline tests.
- `script_dir` passes script parent into FFMS2 indexing context; relative source resolution depends on that boundary.
- `ensure_reachable_executors` guards runtime gaps after builtin/source executor assembly.
- `output_media` rejects unsupported final clips before render loop starts; error code `format.unsupported_y4m`.
- Tests lock current UX: help/version clap exits, zero-thread rejection, stdout/stderr separation, Y4M compatibility gate, half-open frame-range behavior.
