feat: add container and python examples, and fix repo validation

[jahvon]

Important

The Python examples need a flow build carrying the interpreter field. CI installs flow from main, so they go green the moment flowexec/flow#439 lands. The container examples and the validation fix are independent and work today.

Summary

Two features shipped without examples, and the repo's own validation was checking one file.

container/ — running executables inside an image

Nothing here used exec's container block. The docker/ examples drive the docker CLI as the task, which is a different thing from running a task inside an image — so the feature was undiscoverable from examples.

container/toolchains.flow covers pinned toolchains, env/secret passing, extra volumes, workspace-mount and workdir overrides, and entrypoint selection.

Every executable in it was run against a real Docker daemon, not just schema-validated:

run container:with-env          → hello from the host, container / in container: true
run container:with-volumes      → read a read-only //assets mount
run container:custom-workdir    → mounted at /src, ran in /src/basics
run container:custom-entrypoint → bash 5.2.15, bash-only builtin ran
build container:pinned-toolchain → go1.26.7 linux/arm64
run container:pinned-node       → v22.23.2

That caught a bug in my first draft: I wrote cmd: "-c '...'" with entrypoint: sh, not realising flow already wraps cmd as sh -c. It failed with sh: illegal option. Schema validation would never have found it.

python/ — Python executables

python/basics.flow covers inline interpreter: python, params via os.environ, running a .py by extension, tracebacks reporting real line numbers, mixing shell and Python steps in one serial, and Python in a container. python/scripts.flow imports a .py through imports, using the same f: comment metadata shell scripts use.

All verified by running them. The traceback example asserts its own claim — the error really is reported at line 4:

File "/var/folders/.../flow-452924708.py", line 4, in <module>

Validation was checking one file

validate.flow ran flow schema validate *.flow --strict from the workspace root. That glob matches only validate.flow itself — every example lives in a subdirectory, so none had ever been checked, despite the README claiming "All .flow files in this repo are schema-validated in CI".

It now walks the tree (find, since flow schema validate takes explicit paths) and also validates the workspace config and the template. Coverage went from 1 file to 24.

That immediately surfaced four invalid files that had been passing CI:

File	Problem
basics/launch.flow	wait declared on a launch, which has no such field
docker/containers.flow	params on the executable instead of its type
go-project/release.flow	same
setup/database.flow	same

All four are fixed here — the params blocks moved under the serial they feed.

Testing

22 flow file(s) valid
1 workspace config valid
1 template valid

Plus the live runs above. Note the README's structure table now distinguishes docker/ (driving the CLI) from container/ (running inside an image), which is the point most likely to confuse someone browsing.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R328pa3FUUfga4gYah1iQi