# Projects

A project groups related notes and tasks together within a workspace. Use projects to separate distinct areas of work — a specific client, a product, a side venture — without needing a whole separate workspace.

## Storage

Projects live inside a workspace folder:

```
~/sunwaee/workspaces/
└── personal/
    └── projects/
        └── my-project/
            ├── metadata.md   ← id, timestamps, body
            ├── notes/
            └── tasks/
```

The project name is the folder name. `metadata.md` holds the project id, creation date, and an optional markdown body.

## Commands

### `projects create <name>`

Create a new project in the current (or specified) workspace. Optionally add a description.

```
sunwaee projects create my-project
sunwaee projects create my-project --workspace work
sunwaee projects create client-site --body "Website redesign for ACME Corp, due Q3"
```

### `projects list`

List all projects in a workspace. The default project is marked with `✓`.

```
sunwaee projects list
sunwaee projects list --workspace work
```

### `projects read <name>`

Show full detail of a project, including its body.

```
sunwaee projects read client-site
sunwaee projects read client-site --workspace work
```

### `projects update <name>`

Update a project's body or set it as the default for its workspace. At least one flag is required.

```
sunwaee projects update client-site --body "Scope updated: also includes mobile app"
sunwaee projects update client-site --set-default
sunwaee projects update client-site --body "..." --set-default --workspace work
```

### `projects delete <name>`

Delete a project and all its notes and tasks permanently. Requires `--confirm`.

```
sunwaee projects delete old-project --confirm
sunwaee projects delete old-project --confirm --workspace work
```

## Default project

The default project is used by notes and tasks commands when `--project` is not specified. Set it with `projects update --set-default` or via the `SUNWAEE_PROJECT` environment variable.

## AI tool

The `projects` tool is available to the Sun AI agent with the following actions: `create`, `list`, `read`, `update`. Deletion is not exposed to the agent.

```python
projects(action="create", name="client-site", workspace="work", body="ACME redesign")
projects(action="list", workspace="work")
projects(action="read", name="client-site", workspace="work")
projects(action="update", name="client-site", body="Updated scope")
projects(action="update", name="client-site", set_default=True)
```
