FAQ

Why not a visual canvas?

LightFlow does not reject visual feedback. It rejects making a canvas the workflow source of truth. Complex workflows often need control flow, validation, reuse, and API contracts.

A visual UI can still exist later. It should read and write through the backend contract, not become the only place where workflow structure is understandable.

Why Rust assets?

Rust assets give agents and engineers a reviewable, typed, tool-friendly authoring format. Current discovery reads a limited AST and does not execute arbitrary asset code.

This makes workflow changes closer to ordinary software changes: diffable, reviewable, testable, and easy for coding agents to edit.

Why no sidecar JSON?

Sidecar metadata creates drift. A single self-contained asset is easier to copy, delete, review, and modify.

If metadata and definition live in separate files, an agent has to update both correctly. Keeping them together reduces that failure mode.

Is CortexFS optional?

No. CortexFS is required for the Linux runtime path.

LightFlow intentionally delegates provider, model, tool, MCP, thread, policy, and audit surfaces to CortexFS. Duplicating those concepts in LightFlow would create two sources of truth.

Can non-Linux clients use LightFlow?

Yes, through a Linux-hosted LightFlow server and its HTTP/OpenAPI surface. Non-Linux local runtime is not an initial goal.

This keeps the runtime model simple: execution happens where XDG paths, Unix file semantics, and /ctx are available. Clients can still be browser-based, desktop-based, or remote.

Why no scheduler yet?

The foundation must first make discovery, preview, create, submit, refresh, events, and traces reliable. A scheduler should automate that path later.

Building the scheduler first would hide the core state transitions behind automation. LightFlow needs those transitions to be explicit before it can safely automate them.

Where should UI logic live?

A UI should treat LightFlow as a backend. It should call API endpoints, display records, submit explicit actions, and inspect run state. It should not parse Rust assets or write CortexFS request files directly.

What should agents edit?

Agents should edit project assets under lightflow/, documentation under docs-site/content/, and API-facing contracts when asked. They should avoid modifying generated run state, CortexFS outboxes, build outputs, and local cache directories.

What makes a workflow ready to run?

A workflow is ready when preview can resolve its asset references, input contract, request templates, planned step ids, and CortexFS paths. Runtime success still depends on provider availability and policy, but LightFlow should catch authoring errors first.