# Toggl 2.0 Concepts

Use this file to understand how Toggl 2.0 entities relate to each other before choosing CLI commands.

## Mental Model

Toggl 2.0 is organized around work that happens inside a workspace:

```text
Environment/Profile
  -> Workspace
    -> Projects
      -> Tasks
        -> Time blocks
        -> Time entries
    -> Statuses
    -> Users
```

The active auth profile, environment, and workspace determine which data every command can see. If a project, task, status, or user appears missing, verify the profile and workspace before assuming the resource does not exist.

## Entities

### Profile

A profile stores credentials and the selected workspace. Use profiles when the user needs separate accounts or workspace contexts.

### Workspace

A workspace is the top-level context for projects, tasks, statuses, users, time entries, and time blocks. Most IDs only make sense inside the active workspace.

Use workspace commands when the agent needs to list available workspaces, refresh workspace metadata, switch the default workspace, or override the workspace for one command.

### Project

A project groups related tasks. When a user mentions a project by name, list projects first to resolve the project ID before listing or creating tasks.

### Task

A task is the main work item. Tasks belong to projects and can move through statuses. Most agent workflows start by resolving a task ID from a project and task name.

Use task commands for creating work items, checking details, renaming tasks, changing status, and deleting tasks after explicit confirmation.

### Status

A status represents a task workflow state, such as todo, in progress, review, blocked, or done. Status IDs are workspace-specific.

When the user asks to move a task to a named status, list statuses first and use the matching status ID in the task update.

### User

A user is a workspace member. Use user commands to resolve member IDs when a workflow needs a person, assignee, owner, or reviewer.

Do not guess user IDs from names or emails. List users and confirm ambiguous matches.

### Time Entry

A time entry represents actual tracked time. Starting a time entry begins the running timer; stopping it ends the current timer.

Use time entries when the user wants to track work, start a break, stop tracking, or inspect actual logged time.

### Time Block

A time block represents scheduled or planned work. Time blocks usually belong to a task and have explicit start/end times.

Use time blocks when the user wants to schedule, plan, move, inspect, or delete calendar-like time blocks.

## Choosing the Right Command

If the user wants to:

- Find work: list projects, then list tasks for the project.
- Create work: resolve the project ID, then create a task.
- Move work through a workflow: resolve the task ID and status ID, then update the task.
- Track actual time: resolve the task ID, then start a time entry.
- Stop tracking: stop the current time entry.
- Schedule planned work: resolve the task ID, then create a time block.
- Find people: list users.
- Change workspace context: list or switch workspaces, or pass `--workspace-id`.

When intent is ambiguous, prefer lookup commands and ask before mutating.