> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usealmanac.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This handbook preview targets personal CLI 0.11.1. Check installed command help and the matching backend schema before using examples with another release. Examples with named people and placeholder IDs are fictional.

# Projects and coding work

> Distinguish personal work projects from desktop coding workspaces and the files inside them.

Almanac uses “project” for two related but different purposes. A **personal work project** is a hosted record about an outcome in the person's life or work. A **desktop Project** is a named workspace that groups coding conversations around folders and repositories. One does not automatically create the other.

A personal work project can explain a goal, its participants, history, decisions and current state. Its linked tasks hold individual outcomes and their continuing sessions. Someone can create one directly; Almanac can also create or revise one while organizing useful work, including during Dream's review of the person's history. The project record is not a directory, Git repository or second task checklist. Structured task links, rather than prose alone, place tasks in the project. [Tasks and continuing work](/almanac/tasks) explains when an outcome deserves a task, and [task operations](/work/tasks-and-projects) gives the current edit contracts.

A desktop Project groups sessions by a working folder or repository. The person can create one or open a folder as a project. When that folder already belongs to a project, the desktop enters it; otherwise the open-folder action can create a named project. The sidebar can also discover repositories from existing sessions and show an automatic project grouping without a separately authored project record. This is workspace organization, not an agent silently deciding that unrelated personal obligations form a new goal.

Where `project_create` and `project_switch` are exposed, the agent can intentionally create or enter a desktop Project. An optional folder path anchors the workspace, and the live session and sidebar follow a successful switch in the GUI. Running `cd` in a terminal changes that shell's directory; it does not make the same durable project selection. These controls depend on the available runtime and GUI session, so the agent should check its tools rather than assume every chat can rearrange the desktop.

Coding happens in the selected execution workspace: the agent can inspect and edit files, run commands, test changes and present artifacts using the tools available there. A repository checkout and uncommitted work are filesystem/Git state, not Almanac wiki pages. A remote gateway's path names a file on the gateway, even if the desktop can show it through its file bridge. Conversely, a personal work project can retain why the coding outcome matters, while a task tracks what remains to finish. Link those records when that context will help later; don't copy a code tree into the wiki to make the connection. [Where work happens](/almanac/where-work-happens) explains the storage and presentation boundaries.