docs: update readme and publish workflow input

Author: Jannchie

.github/workflows/publish.yml

@@ -6,8 +6,8 @@ on:
       - 'codetime@*'
   workflow_dispatch:
     inputs:
-      tag:
-        description: 'npm dist-tag (default: latest)'
+      dist_tag:
+        description: 'npm dist-tag channel (latest / beta / next). Git tag is auto-selected.'
         required: false
         default: latest
 
@@ -68,4 +68,4 @@ jobs:
 
       - name: Publish to npm
         working-directory: packages/cli
-        run: npm publish codetime-cli-*.tgz --access public --tag "${{ github.event.inputs.tag || 'latest' }}"
+        run: npm publish codetime-cli-*.tgz --access public --tag "${{ github.event.inputs.dist_tag || 'latest' }}"

README.md

@@ -1,41 +1,179 @@
-# codetime
+<div align="center">
 
-CLI for [codetime](https://codetime.dev). Detects local AI-agent installs
-(Claude Code, Codex, OpenCode, Pi), installs hooks, and ships
-pre-aggregated session rollups to `/v3/agent/ingest`.
+<img src="https://codetime.dev/icon.svg" alt="codetime" width="96" height="96" />
+
+# codetime-cli
+
+**Track AI-agent coding time across Claude Code, Codex, OpenCode, and Pi.**
+
+[![npm](https://img.shields.io/npm/v/codetime-cli?color=1874A8&label=npm)](https://www.npmjs.com/package/codetime-cli)
+[![license](https://img.shields.io/npm/l/codetime-cli?color=1874A8)](./packages/cli/package.json)
+[![node](https://img.shields.io/node/v/codetime-cli?color=1874A8)](https://nodejs.org)
+
+[codetime.dev](https://codetime.dev) · [Dashboard](https://codetime.dev/dashboard) · [Issues](https://github.com/codetime-dev/codetime-cli/issues)
+
+</div>
+
+---
+
+The official CLI for [codetime](https://codetime.dev). It detects local
+AI-agent installs, wires up their hooks, and ships pre-aggregated session
+rollups to `/v3/agent/ingest` — so the same dashboard that tracks your
+editor time also tracks your agent time.
+
+> Privacy: only **metadata** leaves your machine. Prompt text, command
+> output, source code, and diffs are never imported or uploaded.
+> See [Privacy & data collected](#privacy--data-collected) for the full
+> field-level breakdown.
+
+## Features
+
+- **Zero-config detection** — `codetime detect` finds installed agents.
+- **Hook installation** — one command wires each agent's hook into codetime.
+- **History backfill** — import past sessions from local JSONL transcripts.
+- **Incremental sync** — watermarked, throttled, runs in the background.
+- **Multi-machine** — every host is a named machine in your dashboard.
+- **Token reuse** — same upload token as the VSCode plugin; no extra login.
+
+## Supported agents
+
+| Agent | id | Source |
+| --- | --- | --- |
+| Claude Code | `claude` | `~/.claude/projects/**` |
+| Codex CLI | `codex` | `~/.codex/sessions/**` |
+| OpenCode | `opencode` | `~/.local/share/opencode/**` |
+| Pi | `pi` | `~/.pi/sessions/**` |
 
 ## Install
 
 ```sh
-npm i -g codetime-cli   # bin is `codetime`
+npm i -g codetime-cli   # bin: `codetime`
+```
+
+Requires Node.js ≥ 20.
 
-# 1. Copy your upload token from https://codetime.dev/dashboard/settings.
-# 2. Tell the CLI about it (writes ~/.codetime/config.json).
+## Quick start
+
+```sh
+# 1. Copy your upload token from https://codetime.dev/dashboard/settings
 codetime token set <token>
 
-# 3. Install integrations for whichever agents you use.
+# 2. See which agents are installed locally
 codetime detect
-codetime install --target claude
-```
 
-The CLI reuses the upload token you already use for the VSCode plugin —
-there's no separate "agent login". Identity is sent on each upload via
-the `X-Machine-Id` header (a UUID minted once and persisted under
-`~/.codetime/machine-id`).
+# 3. Wire up the hooks (auto-detects, or pass --target / --all)
+codetime install
 
-## Packages
+# 4. (Optional) Backfill past sessions
+codetime backfill import --source all
+```
 
-- `packages/cli` — the published `codetime-cli` npm package (bin: `codetime`).
-- `packages/shared` — internal `@codetime/shared` types, inlined into
-  the published bundle.
+Identity is sent on each upload via the `X-Machine-Id` header — a UUID
+minted once and persisted at `~/.codetime/machine-id`. Rename machines
+from `codetime machine rename --name "..."` or the dashboard.
 
-## Environment
+## Commands
 
-| Variable | Purpose |
+| Command | Purpose |
 | --- | --- |
-| `CODETIME_API_URL` | Override API host (default `https://codetime.dev`). |
-| `CODETIME_TOKEN` | Bearer token (same value as the upload token in Settings). |
-| `CODETIME_DEBUG` | Print verbose hook + import logs. |
+| `codetime detect` | List supported targets and install status. |
+| `codetime install [--target <id>] [--all] [--force] [--dry-run]` | Install hooks into detected or requested targets. |
+| `codetime backfill <plan\|import\|discover\|verify> [--source <id>] [--since] [--until] [--project] [--force]` | Import local agent history. |
+| `codetime token <set\|show\|clear>` | Manage the upload token (stored in `~/.codetime/config.json`). |
+| `codetime machine <ls\|rename\|delete>` | Manage registered machines. |
+| `codetime hook --agent <name>` | Internal — invoked by installed hook files. |
+| `codetime version` / `codetime help` | Self-explanatory. |
+
+Add `--json` to most commands for machine-readable output, or `--dry-run`
+to preview without writing or uploading.
+
+## Privacy & data collected
+
+codetime-cli is **metadata-only**. We never read or upload the contents
+of your code, prompts, or tool output. Below is the exact set of fields
+that leave your machine.
+
+### What IS collected
+
+**Identity & host**
+
+- Machine UUID (`~/.codetime/machine-id`), hostname, OS platform, and
+  the display name you set via `codetime machine rename`.
+- Your upload token, sent as `Authorization: Bearer` on every request.
+
+**Session shape** (per agent session)
+
+- Agent name (`claude` / `codex` / `opencode` / `pi`), session id,
+  turn ids, timestamps, durations.
+- Workspace / project name — typically the basename of the working
+  directory the agent was launched in (e.g. `codetime-cli`).
+- The working directory **path** (`cwd`) and a derived `workspaceId`
+  hash. Absolute paths may include your username (e.g.
+  `/home/alice/work/myproject`).
+- Model identifiers (e.g. `claude-opus-4-7`) and per-model call counts.
+- Tool names invoked (e.g. `Bash`, `Edit`, `Read`) and how often they
+  ran or failed — **never the arguments or results**.
+- Token usage: input / output / cache / reasoning, plus estimated cost.
+- Prompt **character count** per turn (not the prompt text).
+
+**File activity** (per touched file)
+
+- File path within the workspace (e.g. `src/cli.ts`) and a stable
+  `pathHash` — useful for dashboards that group by file.
+- File language, kind (`source` / `test` / `config` / `docs` / `data`),
+  bytes / chars / lines **read / added / removed** — counts only.
+
+### What is NEVER collected
+
+- ❌ Source code, file contents, or diffs.
+- ❌ Prompt text, assistant replies, system prompts, or any chat
+  message bodies.
+- ❌ Shell command text, command output, or stdout / stderr.
+- ❌ Tool-call arguments or tool-call responses.
+- ❌ Environment variables, secrets, tokens, or API keys.
+- ❌ Filesystem contents outside the agent's session transcripts.
+- ❌ Browser history, clipboard, keystrokes, screenshots, microphone,
+  camera — none of that is touched.
+
+### Verify it yourself
+
+Every command supports a dry-run that prints the exact payload without
+sending it:
+
+```sh
+codetime backfill plan --source all --json        # see planned events
+codetime backfill import --source all --dry-run   # see, don't upload
+echo '{}' | codetime hook --agent claude --dry-run
+```
+
+Source of truth for the wire format: `packages/shared/src/index.ts`
+(`CanonicalEvent`, `SessionRollup`, `FileActivityRecord`). If a field
+isn't in those interfaces, it isn't uploaded.
+
+### Controls
+
+- Stop uploading: `codetime token clear` removes the token; hooks
+  become no-ops without one.
+- Remove an existing machine and its rollups: `codetime machine delete --id <id>`.
+- Uninstall hooks: remove the files listed by `codetime detect`, or
+  delete the codetime block from your agent's settings.
+- Self-host: point `CODETIME_API_URL` at your own ingest server.
+
+## Configuration
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `CODETIME_API_URL` | Override API host. | `https://codetime.dev` |
+| `CODETIME_TOKEN` | Bearer token (same value as the upload token). | — |
+| `CODETIME_DEBUG` | Print verbose hook + import logs. | — |
+
+Token precedence (highest first): `--token` flag → `CODETIME_TOKEN` env →
+saved config in `~/.codetime/config.json`.
+
+## Repository layout
+
+- `packages/cli` — the published `codetime-cli` npm package.
+- `packages/shared` — internal `@codetime/shared` types, inlined at build.
 
 ## Development
 
@@ -52,6 +190,13 @@ CODETIME_API_URL=http://localhost:3002 \
   tsx packages/cli/src/main.ts detect
 ```
 
+Link the in-repo build globally:
+
+```sh
+pnpm hooks:link        # build + link as `codetime`
+pnpm hooks:unlink      # undo
+```
+
 ## Publish
 
 ```sh
@@ -60,15 +205,8 @@ pnpm prepublishOnly      # bundles shared into bin/codetime.mjs
 pnpm publish
 ```
 
-## Commands
+See `scripts/release.sh` for the automated release flow (`pnpm release`).
 
-- `codetime detect` — list supported local targets and install status.
-- `codetime install --target <id>` — install integration files.
-- `codetime token set <token>` — store the upload token.
-- `codetime hook --agent <name>` — read hook JSON from stdin; used by
-  installed integrations, not invoked directly.
-- `codetime backfill plan|import --source <id>` — import local agent
-  history.
-- `codetime machine ls|rename|delete` — manage registered machines.
+## License
 
-See `packages/cli/src/cli.ts` for the full command surface.
+[MIT](./packages/cli/package.json) © codetime