> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects

> Group repositories, machine folders, and shared instructions for related Reason sessions.

Projects give related sessions one durable working context. A Project can contain any number of connected repositories and enrolled machine folders, including no resources while it is being prepared.

## Create a Project

From the session sidebar, select **New Project**. Give the Project a name, use the small **Team** switch beside the name when everyone on the team should see it, optionally use **Add machines** and **Add repositories** to choose additional resources Reason may use. The provided **Cloud machine** is enabled by default: a Project needs no repository, folder, or personal device to start working.

Under **Machines**, you can turn the Cloud machine off for new sessions and choose an enrolled personal machine instead. That choice is saved with the Project. **Add a computer** opens device setup; return to the Project and select **Refresh machines** to see newly enrolled folders.

Adding resources is optional. Reason can work across several repositories and machine folders in one session without asking you to classify them as primary, context, read-only, or writable. The first repository added becomes the main delivery repository; later repositories support it, and removing the main repository promotes the next one. The underlying connection still enforces its real permissions—for example, a machine folder enrolled without write permission remains protected.

## Add Project instructions

Reason writes the first `PROJECT.md` immediately when a Project is created. This initial version is generated from trusted Project metadata—the name, selected repositories, and selected machine folders—so creation does not depend on a model call. The short Project summary shown elsewhere is derived from `PROJECT.md`; it is not a separate description you have to maintain.

Saving a rename, repository change, machine-folder change, or cloud setting refreshes the generated resource section in the same transaction. Your shared instructions and learned entries are preserved. A new document revision is created only when its content changes; resource-only saves do not resubmit an older copy of your runbook.

Edit `PROJECT.md` to add architecture notes, repository relationships, commands, conventions, and other instructions that should be available whenever a session starts in the Project. Reason pins the document revision selected at session creation so an in-progress session does not silently change when the Project is edited later.

The agent can read `PROJECT.md` directly with its file-read tool, just like memory, without starting a machine. `project:/PROJECT.md` resolves to the same pinned document. To edit the shared runbook, it reads the latest Project and uses the revision-checked Project update tool; writing an unrelated file in a checkout does not change the shared document.

Select **View PROJECT.md** to open that pinned revision in the standard Files sidepanel. When you open it from Project settings instead of an existing session, Reason creates a settled session inside the Project first, so the document keeps the same Project and revision context as future work. Opening `MEMORY.md` from Memory settings uses the same read-only sidepanel and creates a settled session in **Recents**.

After a successful Project session, Reason can add a short entry under **What Ara learned**. These automatic entries preserve your instructions, are deduplicated and bounded, and become available to future sessions through a new immutable `PROJECT.md` revision. A session already in progress continues using the revision it started with.

## Let Reason maintain a Project

Ask Reason to rename the Project, change its repositories or machine folders, or update the shared runbook. Writable sessions expose `tools.projects.list()`, `tools.projects.get({})` for the current Project, and `tools.projects.update(...)`. These operations use your current Workspace membership and Project permissions. A read-only session can inspect Projects but cannot edit them.

For a runbook edit, Reason reads the latest document and sends `project_md: { content, expected_revision }`. If someone edited it in the meantime, the update returns a conflict so Reason can read and reconcile both changes. Resource updates replace the full list, using existing connected repository IDs and enrolled machine-folder IDs; they do not enroll a computer or grant new access. The short description is derived from the document.

Project updates apply to future session admission. An existing session keeps its pinned instructions and execution resources. Shared procedures and tutorials belong in `PROJECT.md`; personal preferences belong in personal memory.

## Start a session

The new-session composer starts with a Project picker. After you choose a Project, a repository picker appears. Selecting a repository then reveals its branch and checkout choices: use **New worktree** for isolated work or **No worktree** to work directly on the selected branch. If you select no repository, the branch and checkout controls stay hidden.

You do not need to toggle individual Project resources for each session. The selected repository is the main delivery repository, while the Project's other repositories and enrolled machine folders remain available as supporting context.

Projects are shared with other members when **Team** is on. Private Projects remain available only to their creator and team owners or administrators.

Hover over **Projects** or **Recents** to reveal their compact actions. Both three-dot controls open the same organizer for repositories, people, open changes, and visible session metadata; the adjacent plus or pencil starts a new Project or session.

Each Project row also has a compact menu for **Pin**, **Edit**, **Mark all as read**, **Archive chats**, and **Remove project**.