AFS recipes

Each recipe names its version, mutation risk, and assumptions. Paths like /modules/project are examples from the verification host, not universal defaults. Substitute mounts from your own arc afs mount list.

Version: arc 2.0.0-beta.28

Recipe 1 — Read-only root and mount survey

Goal: Learn what this instance exposes without changing data.
Mutates: No
Assumes: Local CLI can reach your AFS surface (typically a running daemon)

arc --version
arc afs explain
arc afs mount list   # redact secrets before sharing
arc afs mount validate
arc afs ls / -l
arc afs stat /
arc afs ls /.actions

Observed (truncated, host-specific):

2.0.0-beta.28

Configuration is valid

PATH=/
CHILDREN=108
ACTIONS=mount,unmount,read,list,write,query,aggregate,delete

/.actions/unmount
/.actions/read
/.actions/list
/.actions/write
/.actions/query
/.actions/aggregate
/.actions/delete
/.actions/mount

Done when: You can name at least one mount path you are willing to inspect further.

Recipe 2 — Inspect a known mount (list / stat / read / capabilities / search)

Goal: Verify routing and capabilities on one existing mount.
Mutates: No
Assumes: A mount already serves data (verification host used /modules/project → fs://…)

MOUNT=/modules/project   # replace with your path

arc afs ls "$MOUNT"
arc afs stat "$MOUNT"
arc afs explain "$MOUNT"
arc afs read "$MOUNT/.meta/.capabilities"
arc afs search "$MOUNT" RELEASING

Observed (truncated):

PATH=/modules/project
KIND=fs:directory
CHILDREN=185
MODIFIED=2026-07-30T21:14:23.150Z

Capabilities JSON included "provider": "fs" with search: true and write features such as ifMatch (full blob on local inspection).

Search returned paths under the mount, for example /modules/project/RELEASING.md.

Failure check:

arc afs read /this-path-does-not-exist-xyz
# ERROR: Path not found: /this-path-does-not-exist-xyz  (exit 5)

Done when: You know whether search/write appear in that mount's capabilities and you have read one real file.

Recipe 3 — Disposable write / read / delete on a pre-mounted writable path

Goal: Exercise mutation only where you already have a writable mount.
Mutates: Yes (creates and deletes one file)
Assumes: An already mounted writable path you control. On the verification host this was /modules/memory (fs://…/test-mem). Do not copy that path blindly.
Does not assume: That arc afs mount add just succeeded—see Runtime boundaries.

W=/modules/memory/afs-doc-recipe.txt   # replace prefix with YOUR writable mount

arc afs write "$W" --content 'Hello from AFS recipe' --mode create
arc afs read "$W"
arc afs stat "$W"
arc afs write "$W" --content ' — append' --mode append
arc afs read "$W"
arc afs delete "$W"
arc afs read "$W"   # expect not found

Observed:

OK /modules/memory/afs-doc-recipe.txt
Hello from AFS recipe
PATH=/modules/memory/afs-doc-recipe.txt
KIND=fs:file
SIZE=21
MODIFIED=2026-08-11T06:47:04.762Z
OK /modules/memory/afs-doc-recipe.txt
Hello from AFS recipe — append
delete
ERROR: Path not found: …

Optional negative checks (do not invent success):

MOUNT=/modules/project   # replace with your path (recipe stands alone; do not rely on Recipe 2)
arc afs exec /.actions/query --args "{\"path\":\"$MOUNT\",\"limit\":2}"
# On the verification fs mount: ERROR: Collection query is not available on this surface

Done when: Create, read, append, and delete all behaved as expected on your mount, and the disposable file is gone.

Recipe hygiene