@anyslate/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,74 +1,284 @@
 # @anyslate/cli
 
-Thin lifecycle-hook + checkpoint client for the AnySlate AI Memory Layer.
+The bridge that lets your AI tools quietly tell AnySlate what you've been working on - without you having to remember to checkpoint anything.
 
-All hook subcommands submit to your **Activity feed** via the `activity_submit` MCP tool (Phase 14). Low-risk same-session items auto-promote into canonical memory after a 30-second quiet period; ambiguous items wait for you to approve them in the desktop **AI Memory → Activity** panel.
+## What this is
+
+A small command-line tool that runs on your machine. Your AI tools (Claude Code, git, CI) call it on your behalf as you work. It records what's happening into your AnySlate **Activity feed** - file edits, shell commands, commits - automatically and continuously.
+
+Think of it like a Fitbit, but for your AI work. You don't tell a Fitbit "I just took 47 steps." You wear it, walk around, the count updates. Same shape here. You install this once, paste a small config snippet into your AI tool's settings, and from that point on, capture happens in the background while you work.
+
+**You almost never run a CLI command yourself.** The tool exists to be invisible plumbing that other tools call. The setup below takes 5 minutes and ends with `anyslate doctor` telling you it works.
+
+## Where it fits in your workflow
+
+Most days you'll never type `anyslate` yourself. Here's what actually happens:
+
+| Trigger | Who calls the CLI | What lands |
+|---|---|---|
+| You open a Claude Code session | Claude Code's `SessionStart` hook | Session-start activity; the AnySlate session is created on first sight |
+| Claude edits `routes/auth.ts` | Claude Code's `PostToolUse` hook | "Edited routes/auth.ts" in the activity ledger (**awaits your approval** - see below) |
+| Claude runs `npm test` | Claude Code's `PostToolUse` hook | Command + output in the activity ledger |
+| You `git commit` | Git's `post-commit` hook | Commit metadata + diff stats captured |
+| Teammate merges your PR | GitHub webhook (no CLI needed) | PR-merged event captured |
+| You close the laptop | Claude Code's `Stop` hook | Session-end marker captured |
+| **You manually want to checkpoint a decision** | **You typing `anyslate checkpoint ...`** | **Captured immediately** |
+| **You want to upload a file as an artifact** | **You typing `anyslate upload-artifact ...`** | **File stored, returns `cloud://artifact/<id>`** |
+
+The first six rows are automatic - that's what the lifecycle hooks do. The bottom two are the rare moments where you'd actually type something yourself.
+
+### What hook captures actually write - read this before you form expectations
+
+Hook captures land in a dedicated **`## Activity Ledger`** section of your memory page: which files were touched, which commands ran, what exit status they returned. That is the whole contract. The ledger is capped (25 files / 15 commands per entry) and is built deterministically - no LLM runs in the hook path, so capture never bills against your AI quota.
+
+Hook captures **do not** write to the **Decisions** or **Open Tasks** sections. Those stay human- and LLM-authored, and are populated by `anyslate checkpoint`, by the in-host MCP flow (`/anyslate-new`, `/anyslate-continue`), or by you editing the page. A hook firing on `Bash` has no decision in it to extract, and the product no longer pretends otherwise.
+
+If you want a decision recorded, type it:
+
+```bash
+anyslate checkpoint --note "Decided: Redis for session cache, not memcached"
+```
+
+### Approval: file edits wait, shell commands don't
+
+The classifier treats `Edit` / `Write` / `MultiEdit` as **high-risk** - those rows stay pending in **AI Memory → Activity** until you approve them. `Bash` and session lifecycle events classify **low-risk** and auto-promote on their own.
+
+This is deliberate, and it means a Claude Code session that edits a lot of files produces a queue you have to work through. Budget a few seconds a day for it, or approve in bulk.
+
+## What you get back
+
+After the setup is in place:
+
+- **You stop forgetting to checkpoint.** Capture happens whether you remember or not.
+- **AnySlate sees what actually happened, not just what the AI claimed.** Git knows what files really changed. The hooks know what commands really ran.
+- **Your work follows you across tools.** Claude Code at home, Cursor at work, terminal in between - all feed the same memory. (Cursor and Windsurf feed it through the in-host MCP server, not this CLI - see the FAQ.)
 
 ## Install
 
 ```bash
 npm i -g @anyslate/cli
-# or
+# or run on demand without installing:
 npx @anyslate/cli --help
 ```
 
 Requires Node ≥ 20.
 
+> **macOS users hitting `EACCES` on global install:** don't use `sudo`. Configure a user-writable npm prefix instead:
+>
+> ```bash
+> mkdir -p ~/.npm-global
+> npm config set prefix '~/.npm-global'
+> echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
+> source ~/.zshrc
+> npm install -g @anyslate/cli
+> ```
+
 ## Authenticate
 
-Mint an MCP token in the desktop app at **Settings → AI Memory → Connect**, then:
+Mint an MCP token in the AnySlate app: **Avatar (top-right) → API Tokens → Tokens tab → Create Token**. This is the same dialog on the desktop app and on the cloud app at `https://cloud.anyslate.io`; the dialog is titled *MCP Tokens*. MCP token minting is **available on every plan** - Free, Pro and Unlimited - with no token quota.
+
+Copy the token (it starts with `as_mcp_`; you only see it once), then:
 
 ```bash
 anyslate login --token as_mcp_your_token_here
 ```
 
-Or set environment variables:
+`login` verifies the token against the server before writing anything. If the host is unreachable, the URL isn't an AnySlate MCP service, or the token is unrecognised/revoked/expired, it prints the reason, **writes nothing, and exits non-zero**. See [`anyslate login`](#anyslate-login) for the `--force` / `--no-verify` escapes.
+
+Then confirm the whole install:
+
+```bash
+anyslate doctor
+```
+
+### Environment variables
 
 ```bash
 export ANYSLATE_MCP_TOKEN=as_mcp_your_token_here
-export ANYSLATE_API_URL=https://mcp.anyslate.io   # optional
-export ANYSLATE_HANDLE=h_xxx                       # optional, scope to one handle
+export ANYSLATE_API_URL=https://mcp.anyslate.io   # optional; service ROOT, no /mcp
+export ANYSLATE_HANDLE=mh_xxxxxxxx                # optional, scope to one capability handle
+export ANYSLATE_DISABLE=1                         # optional, disables capture for this shell
+export ANYSLATE_HOME=/path/to/dir                 # optional, overrides ~/.anyslate
+export ANYSLATE_STDIN_TIMEOUT_MS=10000            # optional, stdin idle timeout (0 disables)
 ```
 
 Env vars override `~/.anyslate/cli.json`.
 
+`ANYSLATE_DISABLE=1` stops `hook` / `checkpoint` / `upload-artifact` from making any network call (they exit 0). `doctor` and `login` still run, so you can diagnose and set up while capture is off. Any value counts as "on" except empty, `0`, `false`, `no`, `off`.
+
+Capability handles are `mh_` + a 32-character id (e.g. `mh_V1StGXR8Z5jdHi6BmyT0aQx3nKpL7cWe`), minted alongside a scoped token in the **Handles** tab of the same dialog. **A handle id that isn't yours or doesn't exist is rejected server-side** - since 0.2.0 the CLI reports that as a failure instead of exiting 0 silently.
+
+**If your token was minted with a memory scope, it already carries that scope server-side and `ANYSLATE_HANDLE` / `--handle` is ignored.** Scoped tokens cannot be widened per-call by design. To capture workspace-wide, mint an unscoped token. `anyslate doctor` reports which case you're in.
+
+### The two URL conventions - the one thing people get wrong
+
+AnySlate ships two clients and they want **different** URLs. This trips up nearly everyone:
+
+| Client | Variable / flag | Wants | Example |
+|---|---|---|---|
+| **`@anyslate/mcp` bridge** (Claude Desktop, Cursor, Windsurf…) | `ANYSLATE_MCP_URL` | the **MCP endpoint** - *with* `/mcp` | `https://mcp.anyslate.io/mcp` |
+| **`@anyslate/cli`** (this package) | `--api-url` / `ANYSLATE_API_URL` | the **service root** - *without* `/mcp` | `https://mcp.anyslate.io` |
+
+The CLI appends `/mcp` itself. Pasting the bridge's URL into `--api-url` used to produce `…/mcp/mcp`, a permanent `404 {"error":"Not found"}` that masks every other diagnosis - because the 404 fires before authentication, so a wrong URL makes a valid token look invalid.
+
+**Since 0.2.0 the CLI accepts either form and normalizes**, stripping any trailing `/mcp` segments (`/mcp`, `/mcp/mcp`, `/MCP/`, trailing slashes). Normalization happens on every read, so a `cli.json` written by an older version self-heals without re-running `login`. When it rewrites a value it tells you:
+
+```
+anyslate: apiUrl "https://mcp.anyslate.io/mcp" ends in /mcp — the CLI wants the service ROOT and appends /mcp itself.
+anyslate: using "https://mcp.anyslate.io". Run `anyslate login --api-url https://mcp.anyslate.io` to persist.
+```
+
 ## Subcommands
 
 ```
-anyslate hook <session-start|post-tool-use|stop> [--strict]
-anyslate checkpoint --note "..." [--kind milestone] [--session <id>]
-anyslate upload-artifact --session <id> --kind <kind> [--file <path>]
-anyslate login --token <BEARER> [--handle <ID>] [--api-url <URL>]
+anyslate hook <session-start|post-tool-use|stop> [--strict] [--session <id>] [--note <text>] [--host <hint>]
+anyslate checkpoint --note "..." [--kind milestone] [--session <id>] [--host <hint>] [--source <source>]
+anyslate upload-artifact --session <id> --kind <kind> [--file <path>] [--language <lang>] [--path-hint <path>]
+anyslate login --token <BEARER> [--handle <ID>] [--api-url <URL>] [--force] [--no-verify]
+anyslate doctor [--deep]
 anyslate version | help
 ```
 
+### `anyslate doctor`
+
+The one command whose job is to fail loudly. Run it after setup and any time capture seems dead. It exits non-zero if any check FAILs.
+
+It checks, in order: which config layer won (env var vs `cli.json`) per key; that a token is present; that the token *looks* like a token; that the URL parses and has the right shape (**before** any token verdict, because a wrong URL 404s ahead of auth and would otherwise be misread as a bad token); that the host is reachable and healthy; that the token is valid (and, if not, whether it is unrecognised, revoked or expired); that the token carries `memory:write`; the effective handle scope; that `anyslate` is on the PATH a hook subprocess would get; and whether Claude Code's hooks are actually wired in `~/.claude/settings.json`.
+
+Reading the output:
+
+- **PASS** - checked and observed good.
+- **WARN** - works, but something is narrower or more fragile than you probably intend (e.g. a project-scoped token, or a config key coming from an env var you forgot you exported).
+- **FAIL** - this is why capture isn't working. Each FAIL prints the specific remedy.
+
+`doctor` is **not** side-effect-free: verifying the token updates its `last_used_at`, consumes rate-limit budget, and writes an audit-log row. `--deep` additionally submits a real `doctor_probe` activity, which is visible in your Activity feed - that's why it's opt-in.
+
 ### `anyslate hook ...`
 
-Reads JSON event payload from stdin (Claude Code lifecycle event format). Fails open by default — a network blip logs a warning to stderr and exits 0 so your Claude Code session continues. Pass `--strict` to opt into exit 1 on failure (useful in CI smoke tests).
+Reads a JSON event payload from stdin (Claude Code lifecycle event format). **Fails open by default** - a network blip, an invalid token or a server-side rejection logs to stderr and exits 0, so your Claude Code session is never broken. Pass `--strict` to exit 1 on failure instead (useful in CI smoke tests).
+
+Because fail-open means you won't see stderr in normal use, every run is recorded to `~/.anyslate/cli-last-run.json` and a capped ring log at `~/.anyslate/cli-runs.ndjson` (both mode 0600, token redacted). After repeated consecutive failures the `SessionStart` hook surfaces a message in Claude Code itself telling you to run `anyslate doctor`. One-off failures stay quiet.
+
+Kind mapping: `hook session-start` → `topic_shift`; `hook stop` → `conversation_end`; `hook post-tool-use` maps `Edit`/`Write`/`MultiEdit`/`Create` and `Bash`/`Shell`/`Run`/`GitCommit` → `task_completed`, everything else → `topic_shift`.
 
-`hook session-start` → `topic_shift`; `hook stop` → `conversation_end`; `hook post-tool-use` maps Edit/Write/MultiEdit → `artifact_produced`, Bash/Shell/Run → `task_completed`, everything else → `topic_shift`.
+Hooks never emit `artifact_produced`. That kind is a contract — "I stored an artifact, here is its id in `artifact_refs`" — and the server rejects it without one. A hook observes a file touch; it stores nothing. The touched path is carried in the `files_touched` ledger field instead, so edits auto-promote as activity entries rather than piling up an approval queue.
+
+**Session identity is handled for you.** Claude Code's `session_id` is a UUID from its own namespace; AnySlate session ids are a different format entirely. The server resolves the incoming UUID against `conversation_id_external`, and **creates the AnySlate session on first sight** if there's no match, titling it from the host and working directory. You do **not** need to pass `--session` in the Claude Code hook config, and re-running under the same Claude Code session reuses the same AnySlate session. `--session` remains available for git hooks and CI, where you want to pin captures to one specific memory.
+
+Fields read from the stdin payload: `session_id` (or `sessionId`), `tool_name` (or `toolName`), `tool_input` (or `toolInput`), `tool_response` (or `toolResponse`, JSON-stringified into `conversation_excerpt`), `transcript_path`, `client_checkpoint_id`. Anything else in the payload is ignored.
+
+**The activity ledger.** From `tool_input` and `tool_response` the hook derives three structured fields — `files_touched`, `commands_run` and `exit_status` — and sends them as first-class payload fields. They record what a tool call *did*, and they land in the activity/ledger section of the memory page. They are deliberately **not** folded into `notes`: `notes` is the prose the server mines for Decisions and Open Tasks, and turning shell commands into decisions would manufacture entries you never made. Fields with nothing to record are omitted rather than sent empty. No LLM runs anywhere on this path.
 
 ### `anyslate checkpoint`
 
-User-initiated, exits non-zero on failure. Defaults `--kind milestone`, `--source api`. Allowed kinds: `topic_shift | decision_committed | task_completed | task_added | artifact_produced | milestone | conversation_end`.
+User-initiated, exits non-zero on failure - including on server-side rejections, not just network errors. Defaults `--kind milestone`, `--source api`. Allowed kinds: `topic_shift | decision_committed | task_completed | task_added | artifact_produced | milestone | conversation_end`.
+
+`--host <hint>` sets the advisory `host_hint`; `--source <source>` overrides the activity source.
+
+Low-risk items reach your memory page after a **30-second quiet period plus the next once-a-minute promoter run** - so 30-90 seconds, not instantly.
 
 ### `anyslate upload-artifact`
 
-Reads file or stdin, calls the `upload_artifact` MCP tool. Returns `cloud://artifact/<id>` on stdout. Allowed kinds: `code_block | file_path | error_message | shell_command | config_snippet | url_reference | fenced_quote`. 5 MB content cap.
+Reads a file or stdin, calls the `upload_artifact` MCP tool. Prints `cloud://artifact/<id>` on stdout on success; on failure prints nothing to stdout, writes the reason to stderr and exits non-zero. Allowed kinds: `code_block | file_path | error_message | shell_command | config_snippet | url_reference | fenced_quote`. 5 MB content cap on both the `--file` and stdin paths.
+
+Content is read as UTF-8. Binary files are not supported and are refused rather than silently mangled.
 
 ### `anyslate login`
 
-Writes `~/.anyslate/cli.json` with mode `0600`. Idempotent — preserves the apiUrl/handle if you only update the token.
+Verifies, then writes `~/.anyslate/cli.json` with mode `0600`. Idempotent - preserves the apiUrl/handle if you only update the token (the preserved apiUrl is re-normalized and re-verified).
+
+Verification is a single request that proves reachability, URL shape, token existence, revocation, expiry and scopes in one round trip. **On failure it writes nothing and exits non-zero.** Two escapes:
+
+- `--force` - write anyway, with a warning. For when you know the server is temporarily down.
+- `--no-verify` - skip the probe entirely. For air-gapped or offline setup.
+
+A token missing the `memory:write` scope is a **warning**, not a block - but `anyslate hook` needs it, so heed it.
 
 ## Wiring into Claude Code
 
-See `docs/AI_MEMORY_LAYER/GUIDE.md` §6.5 for the full `~/.claude/settings.json` block.
+Claude Code is the only host today with a native lifecycle-hook surface. Edit `~/.claude/settings.json` (create it if missing) and **merge** this into any `hooks` block already there - don't replace the file:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [ { "type": "command", "command": "anyslate hook session-start" } ] }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|Bash",
+        "hooks": [ { "type": "command", "command": "anyslate hook post-tool-use" } ]
+      }
+    ],
+    "Stop": [
+      { "hooks": [ { "type": "command", "command": "anyslate hook stop" } ] }
+    ]
+  }
+}
+```
+
+Restart Claude Code, then run `anyslate doctor` - it parses this file and tells you whether the wiring took.
+
+**If `anyslate` isn't found when the hook fires**, Claude Code spawned it with a minimal `PATH`. Use the absolute path (`command -v anyslate` prints it) or `npx --yes @anyslate/cli hook session-start`. `anyslate doctor` checks this explicitly.
+
+## Git capture
+
+Requires a global install (the template ships in the package). The guard on the first line means a missing template stops the recipe *before* it touches your hook file - it can never leave you with an empty one:
+
+```bash
+# from the repo root
+src="$(npm root -g)/@anyslate/cli/templates/git/post-commit"
+[ -s "$src" ] && install -m 0755 "$src" .git/hooks/post-commit \
+  || echo "template not found - install @anyslate/cli globally first (npm i -g @anyslate/cli)"
+```
+
+Optional, exported before the next commit:
+
+```bash
+export ANYSLATE_SESSION=<anyslate_session_id>  # routes commits into a specific memory
+export ANYSLATE_HOST=git_post_commit           # host_hint advisory
+export ANYSLATE_QUIET=1                        # swallow CLI stderr
+```
+
+`ANYSLATE_SESSION` is read by **this git template only** (it passes `--session` through); the CLI itself does not read it. It has no effect on Claude Code hooks, which don't need it - see the session-identity note above.
+
+Commit metadata (`repo`, `branch`, `sha`, `subject`, `author`, `stats`) is JSON-encoded into the capture's `conversation_excerpt`. It is not a set of first-class queryable fields.
+
+## FAQ
+
+**Do I have to type `anyslate ...` regularly?**
+No. After setup, your AI tools call it automatically. The only commands you might type yourself are `checkpoint`, `upload-artifact`, and `doctor` when something looks wrong.
+
+**Will this slow down my AI tool?**
+Each hook invocation is three sequential HTTPS round trips (`initialize`, `notifications/initialized`, `tools/call`) sharing one 15-second timeout budget. Typically well under a second. It is fail-open, so a network blip logs to stderr and exits cleanly rather than blocking your session.
+
+**What if I want to disable capture for one session?**
+Set `ANYSLATE_DISABLE=1` in the shell where you're running the AI tool. The CLI makes no network call and captures nothing for that shell.
+
+Setting `ANYSLATE_MCP_TOKEN=` (empty) does **not** disable capture - an empty string falls through to the token in `~/.anyslate/cli.json`, so capture keeps running. Earlier versions of this README claimed otherwise; that claim was wrong. Use `ANYSLATE_DISABLE=1`.
+
+**Where does the data live?**
+In your AnySlate workspace. The CLI is a stateless client; it sends events to the AnySlate MCP service over HTTPS and stores nothing locally beyond your token in `~/.anyslate/cli.json` and the local run logs described under `anyslate hook` (all mode 0600).
+
+**Can I see what was captured?**
+Yes - **AI Memory → Activity** shows every captured row with its status (pending / merged / rejected / failed), and failures under the **Failed** tab carry the reason. High-risk items wait for approval; low-risk items promote on their own in 30-90 seconds.
+
+**How do I undo a bad capture?**
+Open the Activity panel, find the row, click **Reject**. Pre-promotion rejections never touch your memory pages. Post-promotion: open the memory and edit or delete the merged content.
+
+**Does this work with tools that aren't Claude Code?**
+Auto-firing lifecycle hooks are Claude Code only - it's the only host with a native hook surface. For Cursor / Windsurf / Cline / Claude Desktop / ChatGPT, capture happens **inside the host** via the AnySlate MCP server (`/anyslate-new`, `/anyslate-continue`). The CLI on the side handles git capture, CI capture, and manual checkpoints from anywhere a shell command can run.
+
+**What's the privacy story?**
+Bearer-token auth, optional capability handles that scope a token to one project or topic, HTTPS-only transport, payload caps. Tokens are revocable from the same dialog you minted them in. `notes` is clipped at **4,000 characters** and `conversation_excerpt` at **16,000 characters** - both are string lengths, not bytes, and clipping applies to the `hook` path only (`checkpoint --note` is sent as given).
+
+**What if I'm offline?**
+Hooks fail open - no error to your AI tool, just no capture for those events. There is no offline queue, so events missed while offline are not retroactively captured. The failure is recorded locally and surfaced by `anyslate doctor`.
 
 ## Tests
 
 ```bash
-npm test
-# 23 tests · node --test · no external deps
+npm test    # node --test, no external deps
 ```
 
 ## License

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anyslate/cli",
-  "version": "0.1.0",
-  "description": "AnySlate CLI — lifecycle hooks + checkpoint / upload-artifact for AI memory capture. All hook subcommands submit to the Activity feed via the activity_submit MCP tool (Phase 14).",
+  "version": "0.2.0",
+  "description": "AnySlate CLI - lifecycle hooks, git/CI capture, and manual checkpoints for AI memory. Validates its connection at login, diagnoses itself with `anyslate doctor`, and fails open without failing silent.",
   "type": "module",
   "bin": {
     "anyslate": "./bin/anyslate.mjs"
@@ -10,6 +10,7 @@
     "bin",
     "src/*.mjs",
     "src/commands",
+    "templates",
     "README.md"
   ],
   "scripts": {
@@ -32,9 +33,8 @@
     "cli"
   ],
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/AnySlate/anyslate.git",
-    "directory": "cli"
+  "homepage": "https://anyslate.io",
+  "bugs": {
+    "url": "https://anyslate.io/support"
   }
 }

package/src/commands/checkpoint.mjs

@@ -1,11 +1,21 @@
-// `anyslate checkpoint` — submit an explicit checkpoint to the Activity feed.
+// `anyslate checkpoint` - submit an explicit checkpoint to the Activity feed.
 //
 // Unlike `hook`, this is user-initiated, so we surface failures directly
 // (exit 1 on error). Use this in CI or one-off scripts where you actually
 // want to know if the submit failed.
+//
+// W2: "failure" now includes tool-level errors (HTTP 200 + result.isError).
+// Previously a handle denial printed `{"error":"handle_not_found","status":401}`
+// to STDOUT and exited 0 — documented as fail-closed, actually fail-open, and
+// on the stream a caller would pipe into the next command.
+//
+// stdout carries results only. Every error goes to stderr.
 
-import { loadConfig, requireToken } from '../config.mjs';
-import { callTool } from '../mcp-client.mjs';
+import { loadConfig, requireToken, apiUrlNormalizationNotice, DISABLED_NOTICE } from '../config.mjs';
+import { callTool, formatCallFailure } from '../mcp-client.mjs';
+import { recordRun } from '../runlog.mjs';
+import { VERSION } from '../version.mjs';
+import { makeIo } from '../io.mjs';
 
 const ALLOWED_KINDS = new Set([
   'topic_shift', 'decision_committed', 'task_completed', 'task_added',
@@ -14,25 +24,37 @@ const ALLOWED_KINDS = new Set([
 
 /**
  * @param {string[]} argv  arguments after `checkpoint`
+ * @param {{env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch}} [deps]
  * @returns {Promise<number>}
  */
-export async function runCheckpoint(argv) {
+export async function runCheckpoint(argv, deps = {}) {
+  const env = deps.env ?? process.env;
+  const { out, err } = makeIo(deps);
   const flags = parseFlags(argv);
   if (!flags.note) {
-    process.stderr.write('usage: anyslate checkpoint --note <text> [--kind <kind>] [--session <id>] [--host <hint>] [--source <source>]\n');
-    process.stderr.write(`  kinds: ${[...ALLOWED_KINDS].join(', ')}\n`);
+    err.write('usage: anyslate checkpoint --note <text> [--kind <kind>] [--session <id>] [--host <hint>] [--source <source>]\n');
+    err.write(`  kinds: ${[...ALLOWED_KINDS].join(', ')}\n`);
     return 2;
   }
   const kind = flags.kind || 'milestone';
   if (!ALLOWED_KINDS.has(kind)) {
-    process.stderr.write(`anyslate checkpoint: unsupported kind: ${kind}\n`);
+    err.write(`anyslate checkpoint: unsupported kind: ${kind}\n`);
     return 2;
   }
 
-  const cfg = loadConfig();
+  const cfg = loadConfig(env);
+  if (cfg.disabled) {
+    err.write(`${DISABLED_NOTICE}\n`);
+    return 0;
+  }
+
+  const notice = apiUrlNormalizationNotice(cfg);
+  if (notice) err.write(notice);
+
   const tokenCheck = requireToken(cfg);
   if (!tokenCheck.ok) {
-    process.stderr.write(`anyslate checkpoint: ${tokenCheck.error}\n`);
+    err.write(`anyslate checkpoint: ${tokenCheck.error}\n`);
+    recordRun({ command: 'checkpoint', ok: false, apiUrl: cfg.apiUrl, error: tokenCheck.error, version: VERSION, exitCode: 1 }, env);
     return 1;
   }
 
@@ -57,16 +79,34 @@ export async function runCheckpoint(argv) {
       token: cfg.mcpToken,
       toolName: 'activity_submit',
       args,
+      fetchImpl: deps.fetchImpl,
     });
     if (!res.ok) {
-      const msg = typeof res.data === 'string' ? res.data : JSON.stringify(res.data);
-      process.stderr.write(`anyslate checkpoint: server ${res.status} — ${msg}\n`);
+      const message = formatCallFailure('anyslate checkpoint', res);
+      err.write(message);
+      recordRun(
+        {
+          command: 'checkpoint',
+          ok: false,
+          apiUrl: cfg.apiUrl,
+          status: res.status,
+          isError: !!res.isError,
+          networkError: !!res.networkError,
+          error: message.trim(),
+          version: VERSION,
+          exitCode: 1,
+        },
+        env,
+      );
       return 1;
     }
-    process.stdout.write(`${JSON.stringify(res.data)}\n`);
+    recordRun({ command: 'checkpoint', ok: true, apiUrl: cfg.apiUrl, status: res.status, version: VERSION, exitCode: 0 }, env);
+    out.write(`${JSON.stringify(res.data)}\n`);
     return 0;
   } catch (e) {
-    process.stderr.write(`anyslate checkpoint: request failed (${e?.message ?? e})\n`);
+    const message = `anyslate checkpoint: request failed (${e?.message ?? e})\n`;
+    err.write(message);
+    recordRun({ command: 'checkpoint', ok: false, apiUrl: cfg.apiUrl, error: message.trim(), version: VERSION, exitCode: 1 }, env);
     return 1;
   }
 }