Reference

Files layout

Files hold nothing unstructured. Everything has its own place, and lib/files/layout.js is the only code that builds those places. A writer asks it for a folder and never spells a path by hand.

<files root>/
  Projects/<project record id>/
    files/                      the project's own files
    chat/<chat id>/             a chat's folder
    made/<chat id>/             what a chat made
  agents/<agent id>/
    instructions/
    context/
    memory/
    work/
  objects/<object>/<record id>/ a record's attachments
  templates/<template id>/
  flows/<flow id>/              only for a flow that keeps files
  space/                        the Space's own documents

Rules#

• A folder is named by an id that never changes. A rename changes the display name in the record and moves nothing.
• Projects keeps its capital letter and its record id. Every existing project, its access guard and its seal already use that folder, so it is the canonical one. The other roots are new.
• An object is named by its slug (lowercase letters, digits, hyphens). Every other segment is an id of letters, digits, _ and -, at most 64 characters. A segment with a slash, a dot at the start or a space is refused.
• whereIs(path) reads a path back into what it is (project, agent, record, template, flow, space) or answers null.

Old places#

Nothing moves. A writer that used a different place keeps reading it and writes new files to the canonical one. Today:

• The agent page keeps an agent's context under agents/<uid>/context and its instructions in agents/<uid>/CLAUDE.md. Reading CLAUDE.md stays; new instruction files go to agents/<uid>/instructions/.
• work.start-project writes the project's Drive folder with projectDir, the same path as before.