# Workspaces

A workspace is a top-level container for everything else — notes, tasks, projects, and logs all live inside one. Think of it as a named environment: `personal`, `work`, `freelance`. You can have as many as you want and switch between them at any time.

## Storage

Each workspace is a folder on disk:

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

The workspace name is the folder name. `metadata.md` holds the workspace id, creation date, and an optional markdown body (description/details). The folder is also a git repository — all changes inside it are tracked automatically.

## Commands

### `workspaces create <name>`

Create a new workspace. Optionally add a description right away.

```
sunwaee workspaces create personal
sunwaee workspaces create work --body "Client work and consulting projects"
```

### `workspaces list`

List all workspaces. The default workspace is marked with `✓`.

```
sunwaee workspaces list
```

### `workspaces read <name>`

Show full detail of a workspace, including its body.

```
sunwaee workspaces read personal
```

### `workspaces update <name>`

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

```
sunwaee workspaces update work --body "Updated description"
sunwaee workspaces update personal --set-default
sunwaee workspaces update work --body "New description" --set-default
```

### `workspaces delete <name>`

Delete a workspace and everything inside it permanently. Requires `--confirm`.

```
sunwaee workspaces delete old-workspace --confirm
```

## Default workspace

The default workspace is used automatically by all other commands when `--workspace` is not specified. Set it with `workspaces update --set-default` or by setting the `SUNWAEE_WORKSPACE` environment variable.

## AI tool

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

```python
workspaces(action="create", name="work", body="Client projects")
workspaces(action="list")
workspaces(action="read", name="work")
workspaces(action="update", name="work", body="Updated details")
workspaces(action="update", name="work", set_default=True)
```
