deer-flow/docs/guide/projects.md

Projects

Projects group related conversations under a shared name, instructions, and document shelf.

A conversation joins a project at creation time (when a project is selected) or later through the move menu. Runs never modify membership: submitting a message cannot assign or reassign a conversation. Moving a conversation out of a project keeps it unassigned until it is explicitly moved again.

Moving a conversation refreshes its header affiliation as well as the project lists, including when an older metadata request is still in flight.

Projects require the current database tables and columns. A database stamped 0019_thread_incarnations from the older 0018-based rollout is rejected at startup if the project schema is missing. Follow the offline database recovery procedure before starting this build against that database.

Project instructions

Each project stores free-form instructions — background, conventions, and constraints that apply to every conversation in the project — editable on the project page's Instructions tab with a live byte counter. When a run starts on a member thread, the Gateway pins the project's current state once and renders the instructions as a bounded, request-scoped <project> block for that run only: the block never enters the system prompt or persisted history, and every new run sees the latest saved instructions. Instructions are capped at projects.instructions_max_bytes UTF-8 bytes (default 8192, range 256–262144); multi-byte characters count as their UTF-8 byte length. Oversized instructions are rejected with a 422 at write time and are never silently truncated.

Document shelf

Each project has a document shelf for files the whole project shares, managed from the project page's Documents section:

• Upload a file (button or drag-drop, one file per request). Shelf size limits reuse uploads.max_file_size (default 50 MiB); re-uploading identical content returns the existing entry instead of creating a duplicate. Oversized uploads return 413; deduplicated uploads return 200. Staging cleanup failures are logged without replacing these outcomes or a missing, foreign, or archived project's 404 response. Cancelling a shelf upload discards its partial file after any active disk operation finishes; waiting for further upload data remains cancellable.
• List entries with name, size, modified time, and provenance (uploaded vs. saved from a conversation), and preview or download any entry.
• Save to project from a thread file: the read-only conversation-files browser below the shelf lists member threads' uploads and outputs, each with a Save to project action.
• Attach to thread: copy a shelf file into a thread's uploads through the normal ingestion pipeline, so the conversation can work with it directly.

New shelf names, including explicit upload name and promotion shelf_name, follow ordinary upload filename validation. Names containing NUL, Windows reserved device names (such as CON.txt), or trailing dots are rejected with 400 before bytes are staged.

On native Windows, the document shelf uses extended-length filesystem paths so deep workspace directories and long filenames can be uploaded, downloaded, restored, and purged without enabling the system-wide long-path setting. Filesystem limits on individual path components still apply.

Runs on member threads also receive a bounded <documents> index rendered per run from the pinned snapshot (capped by projects.shelf_index_max_entries and projects.shelf_index_max_bytes), and the agent can page the shelf and read documents with the list_project_documents and read_project_document tools.

Document character counts use a bounded, thread-safe cache; concurrent reads do not serialize full file scans behind its cache lock.

Shelf conversion cleanup failures are logged without replacing the read result or its original error. Cancelled reads wait for their staging cleanup to finish; files that cannot be removed remain eligible for the existing retention sweep.

Archive read semantics

Archiving a project freezes writes but keeps reads. Threads in an archived project still run and still receive the project's instructions and shelf index, and the shelf remains fully readable: listing, preview/download, the conversation-files browser, and attach-to-thread all keep working. Uploads, save-to-project, and moving individual shelf files to trash require an active project, and a trashed document cannot be restored into an archived one. Deleting an archived project remains allowed and moves its whole shelf to trash.

Trash

Deleting a shelf document moves it to trash instead of erasing it: the entry keeps its bytes and a snapshot of its origin project for projects.trash_retention_days (default 30) before the retention sweep may purge it permanently. The /workspace/trash page — reachable from the project page's Documents section and the sidebar Projects header — lists trashed documents with their origin project and remaining retention, with per-entry Restore and Delete permanently actions plus an Empty trash action that permanently deletes every document in the trash — immediately, not after the retention window; the window only bounds how long an entry may sit there before the retention sweep reclaims it. Restore returns the document to its origin project, or to a project you pick when the origin is gone or archived; if the target already holds an identical active file, the entries merge. Deleting a project moves its entire shelf to trash in the same step.

If the retention configuration cannot be read, automatic cleanup is deferred and the trash listing remains available. Cleanup resumes with the current configured retention window once the configuration is readable again.

Permanently deleting read-only documents also works on Windows. A file that is already missing does not block deletion; other filesystem errors keep the entry in Trash for retry. Permissions on symlink targets are preserved.