clawck 0.4.3 → 0.5.4

package/docs/skills/clawck-setup.md

@@ -114,6 +114,25 @@ def clawck_stop(entry_id, status="completed", summary=""):
 
 Use HTTP Request nodes to call the REST API at `http://localhost:3456/api/start` and `/api/stop` at the beginning and end of each agent turn.
 
+## Verifying Hook Data Flow
+
+If tokens or cost show as 0 in your entries, verify that the platform is sending the data:
+
+```bash
+# See what data the hook receives (debug mode)
+LOG_LEVEL=debug clawck hook stop
+
+# Test with sample JSON
+echo '{"session_id":"test","total_input_tokens":5000,"total_output_tokens":2000,"total_cost_usd":0.50}' | LOG_LEVEL=debug clawck hook stop
+```
+
+The debug output shows `Stop context: tokens_in=... tokens_out=... cost_usd=... tool_calls=...` so you can confirm the adapter extracted values correctly.
+
+Each platform adapter recognizes multiple field names:
+- **Claude**: `tokens_in`/`total_input_tokens`, `tokens_out`/`total_output_tokens`, `cost_usd`/`total_cost_usd`, `tool_calls`/`num_tool_calls`
+- **Gemini/Cursor/Windsurf/Codex**: `tokens_in`/`input_tokens`, `tokens_out`/`output_tokens`, `cost_usd`/`total_cost_usd`
+- **Cline**: `tokens_in`/`input_tokens`/`tokensIn`, `tokens_out`/`output_tokens`/`tokensOut`, `cost_usd`/`totalCost`
+
 ## Quick Start CLI
 
 ```bash

package/docs/skills/clawck-usage.md

@@ -91,6 +91,12 @@ Report if your platform provides this data:
 - `tokens_out`: Output tokens generated this turn
 - `cost_usd`: Estimated cost in USD
 
+**Platform hooks** auto-extract tokens and cost from the stdin JSON that each platform sends on stop events. The adapter layer normalizes field names across platforms (e.g., `total_input_tokens`, `input_tokens`, `tokens_in` are all recognized).
+
+**MCP tool users** should pass `tokens_in`, `tokens_out`, and `cost_usd` explicitly when calling `clawck_stop_task`.
+
+**Verification**: Run `LOG_LEVEL=debug clawck hook stop` to see the extracted token/cost values in the debug output. You can also pipe test JSON: `echo '{"session_id":"test","total_input_tokens":5000}' | LOG_LEVEL=debug clawck hook stop`
+
 ## Edge Cases
 
 ### Errors / Failures

package/docs/versioning.md

@@ -0,0 +1,49 @@
+# Versioning Policy
+
+Clawck tracks three independent version numbers. Each serves a different purpose and follows its own release cadence.
+
+## App Version
+
+- **Constant:** `APP_VERSION` in `src/core/types.ts`, mirrored in `package.json` `"version"`
+- **Format:** Semantic versioning (`MAJOR.MINOR.PATCH`)
+- **Current:** `0.4.3`
+- **What it tracks:** The overall Clawck release — CLI, server, SDK, dashboard, reports
+- **When bumped:**
+  - MAJOR: Breaking API or config changes (not yet — still 0.x)
+  - MINOR: New features (e.g., patterns, approval workflow, HTML reports)
+  - PATCH: Bug fixes and small improvements
+- **Compatibility:** While in 0.x, minor versions may contain breaking changes. Upgrade notes are in `CHANGELOG.md`.
+
+## Spec Version
+
+- **Constant:** `SPEC_VERSION` in `src/core/types.ts`
+- **Format:** Semantic versioning (`MAJOR.MINOR.PATCH`)
+- **Current:** `0.2.0`
+- **What it tracks:** The ATP (Agent Time Protocol) wire format — the JSON envelope used for import/export and multi-agent sync
+- **When bumped:** When the ATP schema changes (new required fields, structural changes)
+- **Compatibility:** ATP envelopes include a `spec_version` field. Import accepts older spec versions. See `docs/atp-spec-v0.2.md` for the current spec.
+
+## Schema Version
+
+- **Constant:** `ClawckDB.SCHEMA_VERSION` in `src/core/database.ts`
+- **Format:** Integer, incrementing from 1
+- **Current:** `5`
+- **What it tracks:** The SQLite database schema — tables, columns, indexes
+- **When bumped:** Each time a migration is added to the `MIGRATIONS` array in `database.ts`
+- **Compatibility:** Migrations are **forward-only** and **auto-applied** — Clawck detects the current schema version on startup and runs any pending migrations in a transaction. There is no downgrade path. See `docs/migration-guide.md` for details.
+
+## Version Independence
+
+These three versions are independent. A single release may bump the app version without changing the spec or schema version. For example:
+
+| Release | App Version | Spec Version | Schema Version |
+|---------|-------------|--------------|----------------|
+| v0.1.0  | 0.1.0       | 0.1.0        | 1              |
+| v0.3.0  | 0.3.0       | 0.2.0        | 5              |
+| v0.4.1  | 0.4.1       | 0.2.0        | 5              |
+| v0.4.3  | 0.4.3       | 0.2.0        | 5              |
+
+## Known Limitations
+
+- **No API versioning prefix** — REST endpoints are served at `/api/*` with no version prefix (e.g., no `/api/v1/`). Breaking API changes will be communicated via changelog and app version bumps.
+- **No schema downgrade** — If you need to roll back Clawck to an older version, restore the database from a backup taken before the upgrade.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clawck",
-  "version": "0.4.3",
-  "description": "⏱️🦀 Time tracking for AI agents. Toggl for the agentic era.",
+  "version": "0.5.4",
+  "description": "⏱️🦀 System of record for AI agent work.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
@@ -10,7 +10,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx watch src/cli/index.ts",
-    "start": "node dist/cli/index.ts",
+    "start": "node dist/cli/index.js",
     "serve": "tsx src/cli/index.ts serve",
     "test": "vitest run",
     "lint": "eslint src/",
@@ -39,12 +39,13 @@
   "dependencies": {
     "better-sqlite3": "^12.6.2",
     "commander": "^12.0.0",
-    "pdfkit": "^0.15.0",
     "cors": "^2.8.5",
     "express": "^4.21.0",
+    "pdfkit": "^0.15.0",
     "uuid": "^10.0.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/better-sqlite3": "^7.6.13",
     "@types/cors": "^2.8.0",
     "@types/express": "^4.17.0",
@@ -52,9 +53,11 @@
     "@types/pdfkit": "^0.13.0",
     "@types/supertest": "^7.2.0",
     "@types/uuid": "^10.0.0",
+    "eslint": "^10.0.3",
     "supertest": "^7.2.2",
     "tsx": "^4.0.0",
     "typescript": "^5.6.0",
+    "typescript-eslint": "^8.56.1",
     "vitest": "^2.0.0"
   },
   "engines": {