For Agents • FILESYSTEM.md

Agent procedure

If context is tight, fetch and follow /for-agents/cheatsheet.md first.
Otherwise read this hub, then in order:
Treat /filesystem.md as the normative workspace contract.
Map abstract ops (read_file, grep, append_log) to your harness tools. Do not invent a second layout.
Prefer on-demand reads. Do not load the entire repo into context at bootstrap.

Recommended session start

1. read_file FILESYSTEM.md
2. read_file AGENTS.md          # if present
3. read_file SOUL.md / USER.md  # only if present and needed
4. read_file MEMORY/daily/<today>.md
5. list SKILLS/                 # index only; do not load full SKILL.md yet

Manual index

Doc	When to use
Cheatsheet	Minimal injectable card
Bootstrap	Session start / cold start
Operations	Orient → plan → execute → log
Memory	Daily / observations / learned
Skills	Loading reusable capabilities
Safety	Boundaries, secrets, append-only logs
Claude Code mapping	Map abstract ops to Claude Code–style tools + study guide

Human notes

This section is the agent-facing handbook for FILESYSTEM.md. Humans maintain the workspace; agents execute against it.

Put durable rules in FILESYSTEM.md + AGENTS.md, not in chat history.
Keep harness-specific files (CLAUDE.md, .cursor/rules/) as thin adapters.
For Claude Code internals and engineering patterns, see Claude Code mapping and the public study guide: jetsquirrel.github.io/claude-code-study.
To build runtimes (virtual FS, tools, sandbox, composite backends), see Build.
For Linux/FUSE/cloud mounts, see Infrastructure.

Out of scope

Bypassing sandboxes or secret stores
Reverse-engineering proprietary agent binaries or leaked source
Replacing MCP, vector indexes, or enterprise DMS permissions