`files` Provider¶

runtime files <operation> <path> [content...]

Auth provider: none. The files provider never touches a network or a credential, so the Auth Engine is skipped entirely.

It still passes through the same lifecycle as every other operation: Bootstrap → Context → Policy → Execution → Audit. It exists so the runtime has exactly one dispatch path — there is no "local" shortcut around governance.

Operations¶

Operation	Transport	Notes
`read <path>`	file
`write <path> <content...>`	file	Overwrites
`append <path> <content...>`	file
`list <path>`	file	Directory listing
`delete <path>`	file	Denied by the seeded policy

runtime files write ./notes.txt hello world
runtime files read ./notes.txt
runtime files append ./notes.txt another line
runtime files list .
runtime --output json files read ./notes.txt

`delete` is denied by default¶

providers:
  files:
    enabled: true
    denied:
      - delete

runtime files delete ./notes.txt      # refused by policy

Remove the rule from policy-config.yaml to allow it. For files under version control, runtime command run git rm is often the better answer — it is recoverable from history, which a filesystem delete is not.

The runtime will not write its own configuration¶

The File Engine refuses write, append and delete on these paths inside the Runtime Home:

config.yaml
policy-config.yaml
context.yaml
version
specs/
commands/

files write is an allowed operation, so without this refusal a single command could rewrite policy and the next command would run under the new rules.

Unaffected: reads of any of the above, the capabilities directory, logs/, cache/, and everything outside the Runtime Home.

Auth-free capabilities¶

The files provider is the right place to start with capabilities — no token, no network, no external state:

ls ~/.engineering-runtime/capabilities/files/

runtime capability validate files/notes-roundtrip
runtime capability execute files/notes-roundtrip \
  --input path=./hello.txt --input message="first run"

The shipped examples demonstrate the patterns:

Capability	Demonstrates
`notes-roundtrip`	write → read
`log-rotate`	append + list
`scaffold-service-docs`	multi-write into a directory, then list
`incident-log-lifecycle`	write → append → read
`directory-snapshot-report`	multi-directory list + write a report

In a capability:

workflow:
  - provider: files
    args: [write, "${path}", "${message}"]

  - provider: files
    args: [read, "${path}"]

Known limitations¶

Limitation	Workaround
No `mkdir` operation. `write` fails when a parent directory is missing	Create the path some other way first. In a GitHub workflow, seeding a placeholder file through the Contents API makes Git create the path components; locally, `runtime command run git` or an existing directory works
No encoding primitive. No base64 or hashing operation	Write literal content. Where a platform API requires base64, embed the encoded string directly in the capability
`delete` denied by default	Change policy deliberately, or use `git rm`

These are properties of a small, deterministic operation surface. The provider exposes five operations because five is what the runtime can guarantee identically everywhere — not because more were forgotten.

files Provider¶