@togglhq/cli 1.5.19

package/build/program.js

@@ -0,0 +1,2 @@
+import { t as createProgram } from "./program-BwnVUFVS.js";
+export { createProgram };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@togglhq/cli",
+  "version": "1.5.19",
+  "description": "Toggl CLI for Focus API operations.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toggl/toggl-mcp.git"
+  },
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "bin": {
+    "toggl": "./build/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js",
+      "default": "./build/index.js"
+    },
+    "./program": {
+      "types": "./build/program.d.ts",
+      "import": "./build/program.js",
+      "default": "./build/program.js"
+    }
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "skills/**",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "build:public": "tsdown",
+    "build:internal": "tsdown --config tsdown.config.internal.ts",
+    "build:watch": "tsdown --watch",
+    "typecheck": "tsgo -p tsconfig.json --noEmit",
+    "lint": "oxlint --deny-warnings src/**/*.ts tsdown.config.ts tsdown.config.internal.ts",
+    "lint:fix": "oxlint --deny-warnings --fix src/**/*.ts tsdown.config.ts tsdown.config.internal.ts",
+    "format": "oxfmt --write src skills package.json tsconfig.json tsdown.config.ts tsdown.config.internal.ts README.md",
+    "format:check": "oxfmt --check src skills package.json tsconfig.json tsdown.config.ts tsdown.config.internal.ts README.md",
+    "test": "vitest run",
+    "link:global": "pnpm link --global",
+    "unlink:global": "pnpm unlink --global"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "skills": "1.5.2"
+  },
+  "devDependencies": {
+    "@toggl/cli-core": "workspace:^",
+    "@toggl/operations": "workspace:^",
+    "@toggl/queries": "0.15.17",
+    "@types/node": "22.19.11",
+    "tsdown": "0.21.8",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
+  }
+}

package/skills/toggl-cli/INTERNAL.md

@@ -0,0 +1,51 @@
+# Internal Toggl CLI Workflows
+
+Install `@toggl/cli-internal` from **GitHub Packages** for internal builds that include staging and MS environment helpers (`toggl-internal` bin).
+
+## Environments
+
+Use production by default. Use these flags only when a Toggl engineer asks for staging or a named MS environment.
+
+Authenticate against staging:
+
+```bash
+toggl-internal auth --staging
+toggl-internal --json profile list
+toggl-internal --json workspace list
+```
+
+Authenticate against a named MS environment:
+
+```bash
+toggl-internal auth --ms <name>
+toggl-internal --json profile list
+toggl-internal --json workspace list
+```
+
+Generated non-production profiles keep the environment prefix, for example `staging-hazem-12345` or `ms-foo-hazem-12345`.
+
+## Environment Variables
+
+The internal build also recognizes shorthand environment variables:
+
+```bash
+ENV=staging toggl-internal auth
+MS=<name> toggl-internal auth
+```
+
+Explicit URL overrides still take precedence:
+
+```bash
+TOGGL_FOCUS_API_URL=<url> TOGGL_ACCOUNTS_API_URL=<url> toggl-internal auth
+```
+
+## Troubleshooting
+
+When data appears missing in an internal environment, verify profile and workspace before assuming the resource does not exist:
+
+```bash
+toggl-internal --json profile list
+toggl-internal --json profile current
+toggl-internal --json workspace list --refresh
+toggl-internal --json workspace switch <workspace-id>
+```

package/skills/toggl-cli/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: toggl-cli
+description: Use the Toggl CLI to work with Toggl Focus tasks, projects, time entries, time blocks, workspaces, authentication, and CLI maintenance from an agent-friendly terminal workflow. Trigger when the user asks to inspect or modify Focus data through the terminal, authenticate Toggl, switch workspaces, install or refresh the Toggl agent skill, update the CLI, or automate Focus workflows.
+---
+
+# Toggl CLI
+
+Use the `toggl` command when the user wants to inspect or modify Toggl Focus data from the terminal. The CLI is designed for agents: commands are non-interactive when flags are supplied, `--json` gives compact machine-readable responses, validation errors are explicit, and destructive operations require confirmation flags.
+
+## When to Use
+
+Use this skill when the task involves:
+
+- Listing, reading, creating, updating, or deleting Toggl Focus tasks, projects, time blocks, or time entries.
+- Managing saved views, custom fields (admin), and task/project attachments (including file upload and download).
+- Finding workspace metadata such as statuses, users, and workspace IDs.
+- Authenticating the Toggl CLI, switching saved profiles, or switching the active workspace.
+- Installing or refreshing the CLI's agent skill (`toggl skill setup`, or `toggl skill sync` after upgrading `@toggl/cli`).
+- Updating a globally installed `@toggl/cli`.
+- Automating a Focus workflow from shell commands.
+
+Do not use this skill for Toggl Track APIs, raw Focus API calls, or MCP server implementation work unless the user specifically asks to operate through the CLI.
+
+## Operating Rules
+
+- Prefer `toggl --json ...` for any command whose output you will parse.
+- Without `--json`, successful responses are formatted for human reading; do not parse that output in scripts.
+- Run list/get commands first when the target ID is unclear.
+- Use scalar flags for simple inputs: `--task-id`, `--project-id`, `--payload-status-id`.
+- Use `--data -` or `--data-file <path>` for nested payloads or fragile shell quoting.
+- Use `--dry-run` before mutations when you need to validate input.
+- On a TTY, mutations that omit `--data` / `--data-file` / complete scalar flags may open interactive prompts by default; optional reads only prompt when the operation allows it and you pass **`--interactive`**. The **`--interactive`** / **`--no-interactive`** flags exist only on commands where the catalog enables prompting (not on read-only commands that are `interactive: hidden`). Agents and scripts should pass explicit `--*-id` flags or `--data` instead of relying on prompts.
+- Never pass `--yes` unless the user explicitly requested a destructive delete.
+- Use `toggl profile current` / `toggl profile list` when the active account may be wrong.
+- Use `toggl profile switch [<profile>]` to change the default account (omit the name in a TTY to pick interactively), or `--profile <name>` / `--workspace-id <id>` for one command. Use `toggl profile remove [<profile>]` to delete a saved profile (omit the name in a TTY to pick interactively).
+- Use `toggl workspace switch [<id>]` to set the active workspace (omit the id in a TTY to pick interactively from cached workspaces; use `toggl workspace list --refresh` if the list is stale).
+- When changing a time entry’s start time or duration together, use `time-entries update` with required `type` (`activity` or `break`), not `partial-update`; details are in `reference/time-entries.md`.
+- Inspect command help when unsure: `toggl <group> … <command> --help`. Use **`--dry-run`** to print `{ dry_run, operation, input }` (operation id plus validated body) without calling the API.
+- Use the curated command groups: organization commands live under **`toggl organization …`** (not `toggl org …`), shared-data CLI routes sit under **`toggl shared …`**, search is `toggl search`, workspace settings are not nested under `users`, and advanced composite creation is under `projects create-advanced` / `tasks create-with-children`. Attachments nest under their parent: `toggl tasks attachments …` / `toggl projects attachments …`.
+- Attachment files use local paths: upload with `attachments create --file-path <path>` (mime inferred from extension, 20 MB cap), bulk-upload with `--data '{"file_paths":[…]}'`, download with `attachments view --save-to <path>` (refuses to replace an existing file unless `--overwrite true`).
+- custom-fields mutations need workspace admin and 403 otherwise.
+- After the user upgrades `@toggl/cli`, suggest `toggl skill sync` if they use `--copy` installs; symlink installs usually track the package without an extra step.
+
+## Read Next
+
+- Focus concepts, entity hierarchy, and resource relationships: `reference/focus-concepts.md`
+- Auth, profiles, and workspaces: `reference/auth-environments-workspaces.md`
+- Command shape, JSON input, output, dates, and safety flags: `reference/command-contract.md`
+- Tasks: `reference/tasks.md`
+- Projects: `reference/projects.md`
+- Time entries: `reference/time-entries.md`
+- Time blocks: `reference/time-blocks.md`
+- Rates and billables (Focus API vs Track): `reference/rates-and-billables.md`
+- Statuses and users: `reference/statuses-users.md`
+- Reports (`get-workload` vs `get-flexq-data`): `reference/reports.md`
+- Common multi-step flows: `workflows/common-workflows.md`
+- Errors and recovery: `reference/troubleshooting.md`
+
+## Quick Start
+
+```bash
+toggl auth
+toggl --json profile list
+toggl --json workspace list
+toggl --json tasks list --project-id <project-id>
+toggl tasks update --task-id <task-id> --payload-status-id <status-id> --dry-run
+toggl --json tasks update --task-id <task-id> --payload-status-id <status-id>
+```

package/skills/toggl-cli/reference/auth-environments-workspaces.md

@@ -0,0 +1,141 @@
+# Auth, Environments, and Workspaces
+
+## Authentication
+
+Authenticate before making API calls:
+
+```bash
+toggl auth
+```
+
+On a machine without a usable browser (SSH, VM, remote CI shell), use the manual flow. The printed login URL redirects to **`accounts.toggl.com/focus/cli/auth-code`** (not localhost) and shows a copyable authorization code:
+
+```bash
+toggl auth --manual
+```
+
+Non-interactive environments can pass the code directly (must be from the same shell session’s printed login link—PKCE requires matching verifier). Use **`--manual`** so token exchange uses the accounts callback redirect:
+
+```bash
+toggl auth --manual --code 'YOUR_CODE'
+toggl auth --code 'https://accounts.toggl.com/focus/cli/auth-code?code=YOUR_CODE'
+```
+
+The default `toggl auth` flow still uses `http://localhost:8716/callback` on the same machine and shows a branded success page in the browser tab.
+
+The same flags work for `npx @toggl/mcp auth` when running the MCP package entrypoint outside the MCP host.
+
+If the account has multiple workspaces, pass the workspace explicitly:
+
+```bash
+toggl auth --workspace-id <workspace-id>
+```
+
+When `--profile` is omitted, the CLI saves the account under an account-based profile name such as `hazem-12345` and makes it active. Use an explicit profile name only when the user asks for a specific name:
+
+```bash
+toggl auth --profile <name>
+toggl --profile <name> --json tasks list --project-id <project-id>
+```
+
+Credentials are stored in `~/.toggl/focus-tools.json`. Sessions refresh automatically; re-run `toggl auth` to switch workspaces or after long inactivity.
+
+## Profiles
+
+List saved profiles:
+
+```bash
+toggl --json profile list
+```
+
+Show the active profile:
+
+```bash
+toggl --json profile current
+```
+
+Switch the default account and environment:
+
+```bash
+toggl --json profile switch <profile>
+```
+
+Remove a saved profile. With `--json` or when stdin/stdout is not a TTY, pass the profile name; in an interactive terminal you can omit it to pick from the list.
+
+```bash
+toggl --json profile remove <profile>
+```
+
+## Workspaces
+
+List cached workspaces:
+
+```bash
+toggl --json workspace list
+```
+
+Refresh workspace metadata from the account:
+
+```bash
+toggl --json workspace list --refresh
+```
+
+Switch the active workspace for the current profile. With `--json` or when not a TTY, pass the workspace id; in an interactive terminal you can omit it to pick from cached workspaces (refresh with `toggl workspace list --refresh` if needed).
+
+```bash
+toggl --json workspace switch <workspace-id>
+```
+
+Override workspace for one call without changing the active profile:
+
+```bash
+toggl --workspace-id <workspace-id> --json tasks list --project-id <project-id>
+```
+
+When a command returns unexpected missing data, verify the active profile, environment, and workspace before assuming the resource does not exist.
+
+## Workspace settings
+
+`workspace-settings update` expects `--data` with a top-level `payload` object whose **only** mutable workspace fields live under **`payload.settings`** (not alongside `payload` at the root). Discover keys and value shapes from `workspace-settings list` on the same workspace before patching.
+
+```bash
+toggl workspace-settings update --dry-run --data '{"payload":{"settings":{}}}'
+```
+
+## Skill and CLI Maintenance
+
+Install or refresh the agent skill (delegates to the `skills` CLI installed with `@toggl/cli`):
+
+```bash
+toggl skill setup
+```
+
+After upgrading the CLI, run the same flow again so agents pick up skill changes:
+
+```bash
+toggl skill sync
+```
+
+Non-interactive setup can pass target agents and confirmations to the `skills` installer:
+
+```bash
+toggl skill setup --agent cursor --global --copy --yes
+toggl skill setup --agent cursor codex --copy --yes
+```
+
+Prefer the default symlink install over `--copy` so skill content stays aligned when you upgrade `@toggl/cli` without re-running setup.
+
+Update a globally installed CLI:
+
+```bash
+toggl update
+```
+
+Preview the update command without running it:
+
+```bash
+toggl update --dry-run
+toggl --json update --dry-run
+```
+
+`toggl update` updates the CLI package only. Run `toggl skill setup` again to refresh the installed agent skill after updating.

package/skills/toggl-cli/reference/command-contract.md

@@ -0,0 +1,159 @@
+# Command Contract
+
+## Shape
+
+Commands follow:
+
+```bash
+toggl [global flags] <group> … <subcommand> [flags]
+```
+
+Put global flags before the first group:
+
+```bash
+toggl --json tasks list --project-id 436195
+toggl --profile hazem-12345 projects list
+toggl --workspace-id 356965 tasks list --project-id 436195
+```
+
+**Organization and shared data** use multi-segment paths (no top-level `org` command):
+
+```bash
+toggl organization invitations list
+toggl organization workspaces list
+toggl shared status get
+toggl shared holidays list
+```
+
+Core resources and actions:
+
+| Resource       | Actions                                                                             |
+| -------------- | ----------------------------------------------------------------------------------- |
+| `tasks`        | `list`, `get`, `create`, `update`, `delete`, and **`bulk`** subcommands (see below) |
+| `projects`     | `list`, `get`, `create`, `update`, `delete`, and **`bulk`** subcommands             |
+| `time-blocks`  | `list`, `get`, `create`, `update`, `delete`, and **`bulk`** subcommands             |
+| `time-entries` | `list`, `start`, `stop`, and **`bulk`** subcommands                                 |
+| `statuses`     | `list`                                                                              |
+| `users`        | `list`                                                                              |
+
+Operations marked **`hidden: true`** in `@toggl/operations` (notably generated **calendar** and **scheduler** endpoints today) are skipped by `visibleOperations()` and do not register CLI/MCP commands.
+
+Bulk mutations use a nested command: **`toggl <resource> bulk <verb>`** (for example `toggl tasks bulk patch`). MCP entity tools still use hyphenated `action` values such as `bulk-patch` — only the CLI path uses the nested form.
+
+| Resource       | `toggl <resource> bulk …`                                                   |
+| -------------- | --------------------------------------------------------------------------- |
+| `tasks`        | `create`, `patch`, `delete`, `archive`, `restore`, `unarchive`, `duplicate` |
+| `projects`     | `patch`, `delete`, `archive`, `restore`, `unarchive`                        |
+| `time-blocks`  | `create`, `patch`, `delete`                                                 |
+| `time-entries` | `create`, `patch`, `delete`, `restore`                                      |
+
+`list` commands also have the `ls` alias.
+
+## Output
+
+Successful responses go to stdout as JSON. Use `--json` for compact single-line JSON that is easy to parse:
+
+```bash
+toggl --json tasks list --project-id 436195
+```
+
+Without `--json`, successful output is still JSON, but pretty-printed.
+
+Validation errors, API errors, install failures, and update failures go to stderr. The process exits with `0` on success and `1` on error.
+
+## Input
+
+Prefer scalar flags for simple calls. Input field names map to kebab-case flags:
+
+```bash
+toggl --json tasks get --task-id 12345
+toggl --json tasks list --project-id 436195 --status-id 243956
+toggl --json time-entries list --date-from 2026-04-01 --date-to 2026-04-07
+```
+
+For `update` commands, payload fields use `--payload-<field>`:
+
+```bash
+toggl --json tasks update --task-id 12345 --payload-name "New task name"
+toggl --json tasks update --task-id 12345 --payload-status-id 270002
+toggl --json projects update --project-id 436195 --payload-name "Renamed project"
+```
+
+Use `--data` for a full JSON body:
+
+```bash
+toggl --json tasks create --data '{"name":"Write release notes","project_id":436195}'
+toggl --json tasks update --data '{"task_id":12345,"payload":{"status_id":270002}}'
+```
+
+Use `--data -` when shell quoting is fragile:
+
+```bash
+printf '%s\n' '{"task_id":12345,"payload":{"name":"Renamed task"}}' | toggl --json tasks update --data -
+```
+
+Use `--data-file <path>` when a payload already lives in a file:
+
+```bash
+toggl --json tasks create --data-file ./new-task.json
+```
+
+Bulk endpoints expect JSON via `--data` or `--data-file` (arrays for patch-style bulk; objects with `ids` or `task_ids` for deletes/archives). Examples:
+
+```bash
+toggl --json tasks bulk patch --dry-run --data '[{"id":111,"status_id":270002},{"id":222,"status_id":270002}]'
+toggl --json projects bulk patch --data-file ./project-updates.json
+toggl --json time-blocks bulk create --data '{"time_blocks":[{"task_id":12345,"start":"2026-04-01T09:00:00Z","duration":60}]}'
+toggl --json time-entries bulk patch --data '[{"id":9001,"description":"Updated"}]'
+toggl --json tasks bulk delete --data '{"ids":[111,222]}' --yes
+```
+
+## Interactive prompting
+
+**`--interactive`** and **`--no-interactive`** are registered only when the operation’s catalog `cli.interactive` mode is not `hidden` (read-only operations default to `hidden`, so most lists do not expose the flag). On a TTY, **mutations** with `interactive: default` prompt for missing fields when you did not pass `--data`, `--data-file`, or scalar flags that satisfy the schema; **`--interactive`** opts into prompts for operations marked `interactive: available` (optional reads). Prompting is suppressed when you use `--json`, `--data`, or `--data-file`, when stdin/stdout is not a TTY, or when `CI` / `TOGGL_NON_INTERACTIVE` is set. **Bulk** commands whose payloads are arrays of objects (for example `tasks bulk create` with a `tasks` array, or `tasks bulk patch` whose body is an array of `{ id, … }`) walk **one object at a time**: you fill that entry’s fields (including optional details via the usual checkbox), then answer whether to add another—comma-separated text is not used for those structures (use `--data` / `--data-file` for batch JSON). Typed dates and colors show inline validation before the prompt accepts input; ISO calendar dates accept `YYYY-MM-DD` or slash-separated forms (normalized); datetimes must parse as ISO-like strings; hex colors accept `#RGB`, `#RRGGBB`, or bare hex digits. For many Focus ID fields (for example `project_id`, `task_id`, `client_id`, `tag_id`, `status_id`, `user_id`, `assignee_user_id`), interactive prompts use a searchable list backed by the Focus API (type to narrow results; optional IDs can often be skipped with "— Skip —"). Arrays of those IDs (for example `tag_ids`, `assignee_user_ids`, `org_user_ids`, `workspaces`, `roles`, `groups` on `users list`) load the first API page straight into a multi-select checklist; when the page may be truncated (or a filter is already active), an extra row offers **Filter list by name** to narrow results before selecting again. Required fields (or failed list calls) still fall back to comma-separated IDs; **optional** arrays auto-skip when the API returns nothing to pick—pass flags or `--data` if you need explicit IDs anyway. Workspace and role lists are filtered client-side when the org APIs do not accept a search string; groups use organization teams with server-side `filter` scoped to your active workspace when applicable. Comma-separated flags and `--data` still accept raw IDs for scripts and agents.
+
+## Safety Flags
+
+Use `--dry-run` to validate resolved input without making an API call:
+
+```bash
+toggl tasks update --task-id 12345 --payload-status-id 270002 --dry-run
+```
+
+Delete commands require `--yes`. Never add `--yes` unless the user clearly requested the destructive delete:
+
+```bash
+toggl --json tasks delete --task-id 12345 --yes
+toggl --json projects delete --project-id 436195 --yes
+toggl --json time-blocks delete --task-id 12345 --time-block-id 67890 --yes
+toggl --json tasks bulk delete --data '{"ids":[111,222]}' --yes
+toggl --json projects bulk delete --data '{"ids":[436195,436196]}' --yes
+toggl --json time-blocks bulk delete --data '{"ids":[101,102]}' --yes
+```
+
+## Dates
+
+Date range flags accept:
+
+- `YYYY-MM-DD`, expanded by the CLI to full UTC-day boundaries.
+- RFC 3339 datetimes, used as provided.
+
+Examples:
+
+```bash
+toggl --json time-entries list --date-from 2026-04-01 --date-to 2026-04-07
+toggl --json time-blocks list --date-from 2026-04-01T08:00:00+03:00 --date-to 2026-04-01T17:00:00+03:00
+```
+
+## Discovery
+
+When a command shape is unclear, open help on each segment:
+
+```bash
+toggl --help
+toggl tasks --help
+toggl tasks bulk --help
+toggl tasks update --help
+```
+
+Use **`--dry-run`** on a generated command to print `operation` (catalog id) and validated `input` without calling the API.

package/skills/toggl-cli/reference/focus-concepts.md

@@ -0,0 +1,81 @@
+# Focus Concepts
+
+Use this file to understand how Toggl Focus entities relate to each other before choosing CLI commands.
+
+## Mental Model
+
+Toggl Focus 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 Focus 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 Focus 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.

package/skills/toggl-cli/reference/projects.md

@@ -0,0 +1,51 @@
+# Projects
+
+Use project commands to list Focus projects, resolve project IDs, create projects, rename projects, and delete projects.
+
+## Commands
+
+List projects:
+
+```bash
+toggl --json projects list
+```
+
+Get one project:
+
+```bash
+toggl --json projects get --project-id <project-id>
+```
+
+Create a project:
+
+```bash
+toggl --json projects create --data '{"name":"Q3 Planning","workspace_id":356965}'
+```
+
+Rename a project:
+
+```bash
+toggl --json projects update --project-id <project-id> --payload-name "Q3 Planning"
+```
+
+Delete a project only after explicit user confirmation:
+
+```bash
+toggl --json projects delete --project-id <project-id> --yes
+```
+
+## Agent Workflow
+
+When the user provides a project name, list projects and resolve the project ID before acting:
+
+```bash
+toggl --json projects list
+```
+
+When creating tasks, pass the resolved project ID to `tasks create`:
+
+```bash
+toggl --json tasks create --data '{"name":"Task name","project_id":436195}'
+```
+
+Project deletion is destructive. Confirm the exact project ID and name before using `--yes`.

package/skills/toggl-cli/reference/rates-and-billables.md

@@ -0,0 +1,13 @@
+# Rates and billables
+
+There are **two different systems**. Pick the one that matches where the user is working.
+
+## Focus billable / labor rate schedules (this CLI)
+
+Workspace and project **billable rate schedules** live under `toggl rates billable …` (nested under `rates`; same endpoints as the former top-level `billable-rates` command). **Labor cost rate** schedules use `toggl rates labor …` when your generated catalog includes them. Typical verbs: upserts, ranged deletes, conflict checks, and reads for workspace/project and per-user overlays (`get-*`, `upsert-*`, `delete-*-range`, `check-*-conflicts`). Use these when the task is **Focus billing configuration** or **Focus API rate data**.
+
+## Track workspace assignment / Members UI
+
+**Track** exposes member and workspace defaults such as **`track_billable_rate`** (and related assignment flows in the **Members** area of the Track product). That path is **not** the Focus `rates billable` endpoints. If someone is changing rates **only in Track’s member/project assignment UI**, use Track’s APIs or the Track web app — do not assume the Focus CLI commands wrote the same field.
+
+**Rule of thumb:** Focus CLI `rates billable` (and `rates labor` when present) ↔ Focus billing schedules. Track member default rate ↔ Track/Members and Track APIs.

package/skills/toggl-cli/reference/reports.md

@@ -0,0 +1,18 @@
+# Reports (`reports`)
+
+## `get-workload` vs `get-flexq-data`
+
+- **`reports get-workload`** — built-in workload report. Use for utilization, capacity, or team workload views that match that report.
+- **`reports get-flexq-data`** — flexible FlexQ query. Use when you need custom attributes, aggregations, groupings, filters, sorts, or transforms.
+
+Both commands share the same JSON shape: a top-level `payload` whose body includes every required key (`aggregation_filters`, `aggregations`, `attributes`, `filters`, `groupings`, `limit`, `ordinations`, `pagination`, `period`, `transformations`). Arrays may be empty for a minimal valid body; real analysis needs a meaningful `period` and populated dimensions.
+
+## Minimal `--data` (validate with `--dry-run`)
+
+```bash
+toggl reports get-workload --dry-run --data '{"payload":{"aggregation_filters":[],"aggregations":[],"attributes":[],"filters":[],"groupings":[],"limit":100,"ordinations":[],"pagination":{"page":1,"per_page":50},"period":{"from":"","preset":"","to":""},"transformations":[]}}'
+```
+
+Use the same JSON for `reports get-flexq-data`, changing only the subcommand.
+
+Prefer `--data-file` or `--data -` when editing larger FlexQ bodies to avoid shell quoting mistakes.