clockify-unofficial-cli 0.2.0__tar.gz → 1.0.0__tar.gz

clockify_unofficial_cli-1.0.0/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "clockify-cli-skills",
+  "description": "Clockify time-tracking and workspace skills for Claude Code",
+  "owner": {
+    "name": "G.A.JAGUAR",
+    "email": "dev@gajaguar.com"
+  },
+  "plugins": [
+    {
+      "name": "clockify-cli",
+      "source": "./",
+      "description": "Skills that teach an agent to drive the unofficial Clockify CLI"
+    }
+  ]
+}

clockify_unofficial_cli-1.0.0/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "clockify-cli",
+  "version": "1.0.0",
+  "description": "Clockify time-tracking and workspace skills for Claude Code",
+  "author": {
+    "name": "G.A.JAGUAR",
+    "email": "dev@gajaguar.com"
+  },
+  "license": "MIT",
+  "repository": "https://github.com/gajaguar/clockify-cli",
+  "keywords": [
+    "clockify",
+    "time-tracking",
+    "timesheet",
+    "cli",
+    "skill"
+  ]
+}

clockify_unofficial_cli-1.0.0/AGENTS.md

@@ -0,0 +1,117 @@
+# AGENTS.md
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
+interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+## Agent instructions
+
+- `AGENTS.md` is the only agent instructions file; put project rules here. The
+  repository MUST NOT contain a `CLAUDE.md` or any other tool-specific copy,
+  because a second copy drifts from this one.
+
+## Command surface
+
+- Run the `Makefile` targets (`make check`, `make fix`, `make test`, ...)
+  instead of the underlying tools, so the agent and CI use the same options.
+  `make help` lists them.
+- Give every new target a `##` help line; `make help` prints it.
+- `make test` skips the `live` tests, which call the real Clockify API; run
+  them only with `CLOCKIFY_TEST_API_KEY` set.
+
+## Gate
+
+- `make check` and `make test` MUST pass before any commit.
+- Run `make fix` first for findings it can repair, then edit by hand.
+
+## Commits and branches
+
+- Write commit messages as
+  [Conventional Commits](https://www.conventionalcommits.org/) and branch
+  names as [Conventional Branch](https://conventionalbranch.org/)
+  (`<type>/<description>`, e.g. `feat/add-login`). A pre-commit hook and
+  `make commits-check` enforce both; see
+  [`docs/conventions/commits-check.md`](docs/conventions/commits-check.md).
+- Name a documentation or dependency branch `chore/...`: a branch type is not
+  a commit type, and `docs/` is not one.
+
+## Pull requests
+
+Once a pull request is open, the agent MUST:
+
+1. Wait for CI; while it fails, fix the cause, push to the same branch and
+   wait again until it passes.
+2. Squash-merge a pull request with exactly one commit and use a regular merge
+   commit otherwise (`gh pr view --json commits` gives the count).
+3. Delete the branch on the remote and locally.
+4. Switch back to the base branch, pull it and run `git fetch --prune`.
+
+## Documentation
+
+- Write documentation as an OKF bundle of atomic notes under `docs/`: one
+  Markdown concept per file, with YAML frontmatter (`type`, `title`,
+  `description`).
+- Add a new note to its directory's `index.md` and, by file name, to
+  [`docs/log.md`](docs/log.md).
+- Write a note only when it explains something a reader cannot already get
+  from `make help`, a linter's own message, or the configuration it comes
+  from.
+
+## Dependencies
+
+- Add a new tool to the ecosystem manager that owns it; use `mise.toml` only
+  for a tool that bootstraps an ecosystem or has no manager in this
+  repository. See
+  [`docs/toolchain/layering-rule.md`](docs/toolchain/layering-rule.md).
+
+## Python
+
+- Write no docstrings on functions, methods or classes; add a comment only
+  where the *why* is not obvious from the code. `pylint-gajaguar`'s
+  `gajaguar-no-docstrings` fails `make check` on any docstring.
+- Enable the plugin with `enable = ["gajaguar"]` in `pyproject.toml`'s
+  `[tool.pylint."messages control"]`, not with a list of rules, so a rule
+  added by a `pylint-gajaguar` upgrade runs without a config change.
+- Keep `pyproject.toml` to settings that differ from the tool's default, and
+  keep a `lint.per-file-ignores` entry only while it matches a current
+  violation; see
+  [`docs/python/pyproject-defaults.md`](docs/python/pyproject-defaults.md).
+
+## Architecture
+
+- Read [Layering](docs/ARCHITECTURE.md#layering) before adding code:
+  dependencies point downward only, from `commands/` through `services/` and
+  `runtime/` to the SDK.
+- Read [Authentication](docs/ARCHITECTURE.md#authentication) before changing
+  `auth/`: Clockify offers header API keys only, no OAuth2.
+- Add a command by following
+  [Adding a command](docs/ARCHITECTURE.md#adding-a-command), which ends with
+  `make check`, `make test` and `make coverage-report`.
+
+## Clockify rules
+
+- Reach Clockify only through `clockify-unofficial-sdk`, never with `httpx`
+  or a hand-built URL, so retries, pagination and models stay in one place.
+  Add a missing capability to the SDK first and raise the SDK floor in
+  `pyproject.toml` once it is released; see
+  [Cross-repo workflow](docs/ROADMAP.md#cross-repo-workflow).
+- Expose each command module as `APP: Final = typer.Typer(...)`, decorate
+  every command with `@APP.command(help=...)` then `@handle_errors`, and
+  declare options inline as `Annotated[..., typer.Option(...)]`, because
+  Typer cannot resolve PEP 695 `type` aliases.
+- Put logic beyond a single SDK call in `services/`.
+- Render data only through `AppContext.render`, and write diagnostics to
+  stderr through `AppContext.notify` or `CliError`, so `-o json` output
+  stays parseable.
+- Report a new failure with an existing `ExitCode`
+  (`runtime/exit_codes.py`). Its values are a public contract: add a value,
+  never renumber one.
+- Read API keys from the credential stores only. A key MUST NOT be accepted
+  as a command-line argument or printed outside `auth token`, because shell
+  history and logs would keep it.
+- Replace a long argument list with a Parameter Object (a frozen,
+  `slots=True` dataclass), as the SDK does, instead of silencing
+  `too-many-arguments`; see
+  [Typer parameter objects](docs/python/typer-parameter-objects.md).
+- Update [`docs/coverage.md`](docs/coverage.md) with every endpoint change;
+  `make coverage-report` checks it against the OpenAPI document.

{clockify_unofficial_cli-0.2.0 → clockify_unofficial_cli-1.0.0}/Makefile

@@ -68,7 +68,7 @@ spell: ## Spell-check files with cspell — accepts FILES="..."
 
 commits-check: ## Validate the commit range and branch name against Conventional Commits/Branch — see docs/conventions/commits-check.md
 	@git log --no-merges --format='%B%x00' $(BASE)..HEAD | while IFS= read -r -d '' message; do \
-		message="$${message#$$'\n'}"; [ -z "$$message" ] && continue; \
+		message="$${message#$$'\n'}"; \
 		echo "$$message" | $(CONVENTIONAL_GIT) check commit || exit 1; \
 	done
 	@$(CONVENTIONAL_GIT) check branch --name "$(BRANCH)"

{clockify_unofficial_cli-0.2.0 → clockify_unofficial_cli-1.0.0}/PKG-INFO

@@ -1,18 +1,18 @@
 Metadata-Version: 2.5
 Name: clockify-unofficial-cli
-Version: 0.2.0
+Version: 1.0.0
 Summary: Unofficial command-line interface for Clockify, built on clockify-unofficial-sdk.
 Author-email: "G.A.JAGUAR" <dev@gajaguar.com>
 License-Expression: MIT
 License-File: LICENSE
 Keywords: cli,clockify,time-tracking
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.14
-Requires-Dist: clockify-unofficial-sdk<2,>=1.0
+Requires-Dist: clockify-unofficial-sdk<2,>=1.10
 Requires-Dist: keyring>=25.0
 Requires-Dist: platformdirs>=4.0
 Requires-Dist: pydantic>=2.9
@@ -42,6 +42,7 @@ Unofficial command-line interface for Clockify, built on
 - [Getting started](#getting-started)
   - [Prerequisites](#prerequisites)
   - [Installation](#installation)
+- [Agent skills](#agent-skills)
 - [Usage](#usage)
   - [Commands](#commands)
   - [Global options](#global-options)
@@ -62,8 +63,9 @@ handles profiles, credential storage, name-to-ID resolution, output formatting,
 and stable exit codes. The SDK owns HTTP, retries, pagination, typed models,
 and API error mapping.
 
-The CLI is being delivered in phases. The authoritative endpoint mapping is in
-[`docs/coverage.md`](docs/coverage.md), and the delivery plan is in
+`1.0.0` covers every Clockify operation that the SDK offers: 105 of the 166
+non-deprecated operations. The authoritative endpoint mapping is in
+[`docs/coverage.md`](docs/coverage.md), and what comes next is in
 [`docs/ROADMAP.md`](docs/ROADMAP.md).
 
 ## Key features
@@ -77,6 +79,8 @@ The CLI is being delivered in phases. The authoritative endpoint mapping is in
 - **Stable automation contract** - Keep data on stdout, diagnostics on stderr,
   and use documented exit codes.
 - **CI support** - Use `CLOCKIFY_API_KEY` without writing a credential to disk.
+- **Broad coverage** - Manage time entries, projects, reports, time off,
+  approvals, expenses, invoices and webhooks from the terminal.
 - **Typed API foundation** - Build on the SDK's typed models, retries, and
   pagination instead of making HTTP requests in the CLI.
 
@@ -135,6 +139,34 @@ make install
 `make install` installs the pinned toolchain, Python dependencies, Node-based
 documentation tools, and the pre-commit hook.
 
+## Agent skills
+
+The repository is also a Claude Code plugin. Pick one channel:
+
+```text
+# Claude Code
+/plugin marketplace add gajaguar/clockify-cli
+/plugin install clockify-cli@clockify-cli-skills
+```
+
+```bash
+# Any Agent Skills-compatible agent
+npx skills add gajaguar/clockify-cli
+
+# opencode
+npx skills add gajaguar/clockify-cli -a opencode -y
+```
+
+- `clockify-time-tracking` covers `start`, `stop`, `status`, `log` and `entry`.
+- `clockify-cli` covers authentication, profiles, workspaces and the
+  project, task, tag, client, group, custom-field, webhook, report, time-off,
+  approval, expense and invoice commands.
+
+The skills follow the [Agent Skills](https://agentskills.io/specification)
+format, so other agents can read `skills/` directly. They require the CLI to
+be installed and a user to have run `clockify auth login`. See
+[`docs/agents/`](docs/agents/index.md) for what each install channel does.
+
 ## Usage
 
 Log in interactively. The key is read from a hidden prompt, validated with
@@ -165,9 +197,21 @@ printf '%s' "$KEY" | clockify -p work auth login --with-token --region EU_CENTRA
 - `config list` lists configured profiles.
 - `config use NAME` sets the default profile.
 
-Resource commands arrive in phases. See the
-[roadmap](docs/ROADMAP.md) and [coverage matrix](docs/coverage.md) for their
-status.
+- `start`, `stop`, `status` and `log` track time.
+- `workspace`, `user`, `client`, `project`, `task`, `tag`, `group`,
+  `custom-field`, `entry` and `webhook` manage resources.
+- `report` and `shared-report` summarize tracked time.
+- `time-off` and `approval` handle leave and timesheet approvals.
+- `expense` and `invoice` handle expenses, receipts, invoices and payments.
+
+Run `clockify COMMAND --help` for the verbs of each group. Clockify operations
+that the SDK does not offer yet are listed as `planned` in the
+[coverage matrix](docs/coverage.md) and in the [roadmap](docs/ROADMAP.md).
+
+Commands that download a file (`expense receipt`, `invoice export`) write it to
+`--save PATH`, or to a pipe with `--save -`, and never through `-o`. Amounts are
+typed in major units (`120.50`) and shown in Clockify's minor units. Time off,
+approvals, expenses and invoices need a paid Clockify plan.
 
 ### Global options
 
@@ -238,28 +282,27 @@ Live tests are excluded from `make test`. They require
 
 - Headless Linux hosts may not provide a Secret Service keyring backend. Use
   `CLOCKIFY_API_KEY` or the explicit `--insecure-storage` fallback.
-- The SDK is a `uv` git dependency pinned to a tag, so installation requires
-  access to GitHub.
 - Python 3.14 is the minimum version required by the CLI and SDK.
 
 ## Roadmap
 
-- [x] Phase 0: foundation, authentication, profiles, renderers, and exit codes
-- [x] Phase 1: workspace, user, project, task, tag, group, and entry commands
-- [ ] Phase 2: core API completion
-- [ ] Phase 3: reports
-- [ ] Phase 4: time off, holidays, and approvals
-- [ ] Phase 5: expenses and invoices
-- [ ] Phase 6: scheduling, webhooks, and entity changes
-- [ ] Phase 7: release hardening for `1.0.0`
+- [x] `0.2.0`: foundation, workspaces, users, projects, tasks, tags, entries
+- [x] `0.3.0`: group membership and webhooks
+- [x] `0.4.0`: reports
+- [x] `0.5.0`: time off and approvals
+- [x] `0.6.0`: expenses and receipts
+- [x] `0.7.0`: invoices
+- [x] `1.0.0`: exit codes, JSON output and command grammar are a stable contract
+- [ ] `1.x`: the 61 operations the SDK does not offer yet, as it adds them
 
-See [`docs/ROADMAP.md`](docs/ROADMAP.md) for operation counts, dependencies,
-and completion criteria.
+See [`docs/ROADMAP.md`](docs/ROADMAP.md) for operation counts and what is
+frozen from `1.0.0`.
 
 ## Open items
 
 - Only the `GLOBAL` region host is verified against a live account.
-- Plan-gated endpoints need a paid workspace for live verification.
+- Time off, approvals, expenses and invoices are tested against mocked
+  responses; they have not been run against a paid workspace.
 - Clockify's per-plan rate limits are not fully documented upstream.
 
 ## Contributing

{clockify_unofficial_cli-0.2.0 → clockify_unofficial_cli-1.0.0}/README.md

@@ -19,6 +19,7 @@ Unofficial command-line interface for Clockify, built on
 - [Getting started](#getting-started)
   - [Prerequisites](#prerequisites)
   - [Installation](#installation)
+- [Agent skills](#agent-skills)
 - [Usage](#usage)
   - [Commands](#commands)
   - [Global options](#global-options)
@@ -39,8 +40,9 @@ handles profiles, credential storage, name-to-ID resolution, output formatting,
 and stable exit codes. The SDK owns HTTP, retries, pagination, typed models,
 and API error mapping.
 
-The CLI is being delivered in phases. The authoritative endpoint mapping is in
-[`docs/coverage.md`](docs/coverage.md), and the delivery plan is in
+`1.0.0` covers every Clockify operation that the SDK offers: 105 of the 166
+non-deprecated operations. The authoritative endpoint mapping is in
+[`docs/coverage.md`](docs/coverage.md), and what comes next is in
 [`docs/ROADMAP.md`](docs/ROADMAP.md).
 
 ## Key features
@@ -54,6 +56,8 @@ The CLI is being delivered in phases. The authoritative endpoint mapping is in
 - **Stable automation contract** - Keep data on stdout, diagnostics on stderr,
   and use documented exit codes.
 - **CI support** - Use `CLOCKIFY_API_KEY` without writing a credential to disk.
+- **Broad coverage** - Manage time entries, projects, reports, time off,
+  approvals, expenses, invoices and webhooks from the terminal.
 - **Typed API foundation** - Build on the SDK's typed models, retries, and
   pagination instead of making HTTP requests in the CLI.
 
@@ -112,6 +116,34 @@ make install
 `make install` installs the pinned toolchain, Python dependencies, Node-based
 documentation tools, and the pre-commit hook.
 
+## Agent skills
+
+The repository is also a Claude Code plugin. Pick one channel:
+
+```text
+# Claude Code
+/plugin marketplace add gajaguar/clockify-cli
+/plugin install clockify-cli@clockify-cli-skills
+```
+
+```bash
+# Any Agent Skills-compatible agent
+npx skills add gajaguar/clockify-cli
+
+# opencode
+npx skills add gajaguar/clockify-cli -a opencode -y
+```
+
+- `clockify-time-tracking` covers `start`, `stop`, `status`, `log` and `entry`.
+- `clockify-cli` covers authentication, profiles, workspaces and the
+  project, task, tag, client, group, custom-field, webhook, report, time-off,
+  approval, expense and invoice commands.
+
+The skills follow the [Agent Skills](https://agentskills.io/specification)
+format, so other agents can read `skills/` directly. They require the CLI to
+be installed and a user to have run `clockify auth login`. See
+[`docs/agents/`](docs/agents/index.md) for what each install channel does.
+
 ## Usage
 
 Log in interactively. The key is read from a hidden prompt, validated with
@@ -142,9 +174,21 @@ printf '%s' "$KEY" | clockify -p work auth login --with-token --region EU_CENTRA
 - `config list` lists configured profiles.
 - `config use NAME` sets the default profile.
 
-Resource commands arrive in phases. See the
-[roadmap](docs/ROADMAP.md) and [coverage matrix](docs/coverage.md) for their
-status.
+- `start`, `stop`, `status` and `log` track time.
+- `workspace`, `user`, `client`, `project`, `task`, `tag`, `group`,
+  `custom-field`, `entry` and `webhook` manage resources.
+- `report` and `shared-report` summarize tracked time.
+- `time-off` and `approval` handle leave and timesheet approvals.
+- `expense` and `invoice` handle expenses, receipts, invoices and payments.
+
+Run `clockify COMMAND --help` for the verbs of each group. Clockify operations
+that the SDK does not offer yet are listed as `planned` in the
+[coverage matrix](docs/coverage.md) and in the [roadmap](docs/ROADMAP.md).
+
+Commands that download a file (`expense receipt`, `invoice export`) write it to
+`--save PATH`, or to a pipe with `--save -`, and never through `-o`. Amounts are
+typed in major units (`120.50`) and shown in Clockify's minor units. Time off,
+approvals, expenses and invoices need a paid Clockify plan.
 
 ### Global options
 
@@ -215,28 +259,27 @@ Live tests are excluded from `make test`. They require
 
 - Headless Linux hosts may not provide a Secret Service keyring backend. Use
   `CLOCKIFY_API_KEY` or the explicit `--insecure-storage` fallback.
-- The SDK is a `uv` git dependency pinned to a tag, so installation requires
-  access to GitHub.
 - Python 3.14 is the minimum version required by the CLI and SDK.
 
 ## Roadmap
 
-- [x] Phase 0: foundation, authentication, profiles, renderers, and exit codes
-- [x] Phase 1: workspace, user, project, task, tag, group, and entry commands
-- [ ] Phase 2: core API completion
-- [ ] Phase 3: reports
-- [ ] Phase 4: time off, holidays, and approvals
-- [ ] Phase 5: expenses and invoices
-- [ ] Phase 6: scheduling, webhooks, and entity changes
-- [ ] Phase 7: release hardening for `1.0.0`
+- [x] `0.2.0`: foundation, workspaces, users, projects, tasks, tags, entries
+- [x] `0.3.0`: group membership and webhooks
+- [x] `0.4.0`: reports
+- [x] `0.5.0`: time off and approvals
+- [x] `0.6.0`: expenses and receipts
+- [x] `0.7.0`: invoices
+- [x] `1.0.0`: exit codes, JSON output and command grammar are a stable contract
+- [ ] `1.x`: the 61 operations the SDK does not offer yet, as it adds them
 
-See [`docs/ROADMAP.md`](docs/ROADMAP.md) for operation counts, dependencies,
-and completion criteria.
+See [`docs/ROADMAP.md`](docs/ROADMAP.md) for operation counts and what is
+frozen from `1.0.0`.
 
 ## Open items
 
 - Only the `GLOBAL` region host is verified against a live account.
-- Plan-gated endpoints need a paid workspace for live verification.
+- Time off, approvals, expenses and invoices are tested against mocked
+  responses; they have not been run against a paid workspace.
 - Clockify's per-plan rate limits are not fully documented upstream.
 
 ## Contributing

{clockify_unofficial_cli-0.2.0 → clockify_unofficial_cli-1.0.0}/docs/ARCHITECTURE.md

@@ -1,5 +1,5 @@
 ---
-type: spec
+type: reference
 title: Architecture and technical specification
 description: The stack, layering, design patterns, authentication and extension checklist of clockify-cli.
 tags: [architecture]
@@ -10,7 +10,7 @@ status: stable
 
 This document is the technical specification for `clockify-cli`: what it is,
 which stack and design patterns it uses and why, how authentication works,
-and how to extend it. The phased delivery plan lives in
+and how to extend it. The release history and what comes next live in
 [`ROADMAP.md`](ROADMAP.md); the per-endpoint status lives in
 [`coverage.md`](coverage.md).
 
@@ -26,6 +26,7 @@ and how to extend it. The phased delivery plan lives in
 - [Configuration](#configuration)
 - [Errors and exit codes](#errors-and-exit-codes)
 - [Testing strategy](#testing-strategy)
+- [Stability](#stability)
 - [Adding a command](#adding-a-command)
 - [Security considerations](#security-considerations)
 - [Open items](#open-items)
@@ -41,9 +42,9 @@ stable exit codes.
 
 Goals:
 
-- Expose **every non-deprecated Clockify API operation** (166 at the time of
-  writing) as a typed CLI command — tracked row by row in
-  [`coverage.md`](coverage.md).
+- Expose **every non-deprecated Clockify API operation that the SDK offers**
+  as a typed CLI command: 105 of the 166 at `1.0.0`, tracked row by row in
+  [`coverage.md`](coverage.md). The rest wait for the SDK.
 - Be pleasant interactively (tables, prompts, names instead of IDs) **and**
   predictable in scripts (JSON/CSV/ID output, stderr for diagnostics, stable
   exit codes).
@@ -214,7 +215,7 @@ clockify-cli/
 ├── Makefile, mk/*.mk         # check/fix/test surface; mk/clockify.mk
 ├── docs/
 │   ├── ARCHITECTURE.md       # this document
-│   ├── ROADMAP.md            # phases to 100% endpoint coverage
+│   ├── ROADMAP.md            # releases to 1.0.0 and what comes next
 │   └── coverage.md           # endpoint → SDK method → CLI command
 ├── scripts/
 │   └── coverage_report.py    # checks coverage.md against openapi.json
@@ -242,32 +243,32 @@ clockify-cli/
 │   │   ├── formats.py        # table/json/jsonl/csv/id renderers
 │   │   ├── registry.py       # OutputFormat → renderer factory
 │   │   └── columns.py        # per-resource column specs
-│   ├── services/             # Phase 1+: resolve, timer, parsing
-│   └── commands/
-│       ├── auth.py           # login/status/logout/token
-│       └── config.py         # path/list/use
+│   ├── services/             # resolve, parsing, listing, timer, reports, time_off,
+│   │                         # expenses, invoices, files, money
+│   └── commands/             # one module per Clockify area (auth, project, entry,
+│                             # report, time_off, expense, invoice, webhook, ...)
 └── tests/
     ├── conftest.py           # in-memory keyring, fake client, runner
     ├── unit/                 # mirrors src/ layout, offline
     └── live/                 # -m live, needs CLOCKIFY_TEST_API_KEY
 ```
 
-Planned additions follow the same shape:
+New areas follow the same shape: one `commands/<domain>.py` per row group in
+[`coverage.md`](coverage.md), with its logic in `services/`. Notable services:
 
-- `commands/<domain>.py` per row group in [`coverage.md`](coverage.md), for
-  example `project.py`, `entry.py`, `report.py`, `time_off.py`;
-- `services/resolve.py` (name-or-ID lookup);
-- `services/timer.py` (start/stop/continue);
-- `services/parsing.py` (durations like `1h30m` and relative dates like
-  `yesterday 09:00`).
+- `services/resolve.py` resolves a name or ID for every resource;
+- `services/parsing.py` reads durations like `1h30m` and instants like
+  `yesterday 09:00`;
+- `services/files.py` writes binary downloads (receipts, exported invoices);
+- `services/money.py` converts typed amounts to Clockify's minor units.
 
 ## Command surface
 
 - **Grammar.** `clockify [GLOBAL OPTIONS] <noun> <verb> [ARGS]`. The standard
   verbs are `list`, `get`, `create`, `update` and `delete`; domain verbs such
   as `archive`, `approve` or `export` are added where the API has them.
-  Time tracking also gets root shortcuts: `start`, `stop`, `status`, `log`
-  and `continue`.
+  Time tracking also gets root shortcuts: `start`, `stop`, `status` and
+  `log`.
 - **Global options** must come before the noun:
 
   | Option                 | Env var              | Default                                                      |
@@ -278,7 +279,7 @@ Planned additions follow the same shape:
   | `--version`            |                      |                                                              |
   | `--install-completion` |                      | Added by Typer                                               |
 
-- **Names or IDs.** From Phase 1, arguments such as `PROJECT` or `TAG`
+- **Names or IDs.** Arguments such as `PROJECT` or `TAG`
   accept either an ID or an exact, case-insensitive name. An ambiguous name
   is a usage error that lists the candidates.
 - **Output contract.**
@@ -286,7 +287,11 @@ Planned additions follow the same shape:
     to stderr.
   - `json` keeps Clockify's camelCase field names so it matches the API docs.
   - `id` prints one identifier per line for `xargs`.
-- **Destructive commands** (`delete`, bulk operations), from Phase 1: ask
+  - A command that downloads a file (`expense receipt`, `invoice export`)
+    writes the bytes to `--save PATH`, or to a pipe with `--save -`, and never
+    through `-o`.
+  - Report commands print a totals line to stderr, so stdout holds only rows.
+- **Destructive commands** (`delete`, bulk operations): ask
   for confirmation on a TTY and require `--yes` otherwise.
 
 ## Configuration
@@ -348,16 +353,34 @@ by `hint: <next step>`.
   `CLOCKIFY_TEST_API_KEY` is set. The default run excludes them.
 - **Gates.**
   - `make check`: ruff `ALL`, mypy strict, Pyright, pylint with
-    `pylint-plugin`, markdownlint and cspell.
+    `pylint-gajaguar`, markdownlint and cspell.
   - `make test`: 90% coverage floor.
   - `make coverage-report`: keeps `coverage.md` in sync with the upstream
     spec.
 
+## Stability
+
+From `1.0.0` the following are a public contract, and a breaking change to
+any of them needs a major version:
+
+- the exit codes in [Errors and exit codes](#errors-and-exit-codes);
+- the field names and types of `-o json` and `-o jsonl`, which keep Clockify's
+  camelCase names (adding a field is not breaking);
+- what goes to stdout (rendered data) and what goes to stderr (prompts, totals,
+  progress and errors);
+- the `clockify <noun> <verb>` grammar, the commands and options listed as
+  `done` in [`coverage.md`](coverage.md), the global options, the environment
+  variables and the keys of `config.toml`.
+
+Table layout and column headers, the wording of messages and `--help`, and the
+order of rows Clockify does not sort are not part of the contract. See
+[`ROADMAP.md`](ROADMAP.md#what-100-freezes) for how new operations arrive.
+
 ## Adding a command
 
 1. Confirm the SDK exposes the endpoint (check the SDK's `docs/coverage.md`).
-   If not, add it there first and release a tag. Then bump the tag in
-   `[tool.uv.sources]`.
+   If not, add it there first and publish a release. Then raise the SDK
+   floor in `pyproject.toml`.
 2. Add or extend `commands/<domain>.py`:
    - Declare options inline with `Annotated[..., typer.Option(...)]`. Typer
      can't resolve PEP 695 `type` aliases.
@@ -394,5 +417,7 @@ by `hint: <next step>`.
 - Clockify's per-plan rate limits aren't documented upstream. The CLI relies
   on the SDK's retry policy and exits with code 8 once retries are
   exhausted.
-- Several endpoints in Phases 4–6 (time off, invoices, scheduling) need paid
-  plans, so live verification depends on access to such a workspace.
+- Time off, approvals, expenses and invoices need paid plans. Their commands
+  are tested against mocked responses built from the OpenAPI schemas, and have
+  not been run against a real paid workspace.
+- Report totals are not part of `-o json`, because they go to stderr.