Working with files

Files are a core operational primitive in ACP. They can live on thread histories, inside computers, and across project workflows, which means file handling has to be part of state management, not an afterthought.

Use files as shared state across threads and computers.

Files on threads

Thread files let you attach or inspect artifacts directly in the execution history where they were produced or used. This is useful for briefings, generated assets, intermediate reports, and task-specific outputs.

Use thread files for execution-scoped artifacts.

Keep outputs attached to the run that created them.

Treat thread files as part of the execution record.

Files on computers

Computer files represent persistent working state. Repositories, generated code, package manifests, and runtime outputs can stay on the same computer across multiple threads.

Use computer files when outputs should persist across runs.

Keep code and runtime state on the same machine-like surface.

Use persistent file state to avoid repeated bootstrap work.

Choose the right file surface

The key question is whether a file belongs to the execution history, the persistent environment, or both. ACP gives you both surfaces because they serve different operational purposes.

Use thread files for auditability and run-specific artifacts.

Use environment files for persistent workspace state.

Decide file placement based on lifecycle, not convenience alone.