@workscribe/cli 2.0.1 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workscribe/cli",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "Passive developer work journal — automatic terminal activity summaries",
   "homepage": "https://workscribe.co",
   "repository": {

package/skills/workscribe/SKILL.md

@@ -22,18 +22,23 @@ workscribe sessions --json
 
 Add `--date YYYY-MM-DD` for another day. For "this week", run it once per day (Monday to today) and save each day's sessions — but note `workscribe summary --week` keeps using Workscribe's own digest; saved summaries are per day. The output is one line of JSON; see [references/json-contract.md](references/json-contract.md) for the fields you'll use. An empty `sessions` list means nothing was captured — tell the user and stop.
 
+Each session is one project's **thread** inside a work block. When the developer worked across several repos at once, their threads share a block and overlap in time: `alongside` lists the keys of the others.
+
+If it reports that **Workscribe hasn't finished upgrading the data**, ask the developer before running `workscribe upgrade` — it backs up their database first and can take a while on a long history. Once it finishes, run `workscribe sessions --json` again.
+
 ## 2. Write one block per session
 
 Follow [references/summary-format.md](references/summary-format.md). In short:
 
 ```
-## <project> (<branch>) — <duration>
+## <project> (<branches>) — <duration>
 - <outcome>
 ```
 
 - Up to **7 bullets**, most important first: what was built, fixed, shipped or decided.
 - Build bullets from `commits` (cite the short hash, e.g. `(a1b2c3d)`), test and build results (`exitCode` 0 vs non-zero; `null` means unknown, never "failed"), `notes` (always include them), and `hint`s on unclassified events.
 - Describe outcomes, not commands or tools. Never name the AI tool used. Don't invent anything the data doesn't show.
+- Don't name the projects worked `alongside` — Workscribe adds that line under each saved summary itself. Never repeat their work.
 - Skip a session with nothing notable rather than padding it.
 
 ## 3. Save each block
@@ -58,4 +63,4 @@ Show the summaries, then say they were saved to Workscribe: `workscribe summary`
 
 ## Privacy
 
-Running this skill sends the JSON — categories, commit subjects, notes, short redacted hints for unclassified commands, and each session's repo path and working directory; never full commands or IDE file paths — to the model provider behind this agent, along with any files you read under `repoPath`. If the developer needs summaries that never leave their machine, point them to `workscribe summary`, whose template engine runs entirely offline.
+Running this skill sends the JSON — categories, commit subjects, notes, short redacted hints for unclassified commands, the ids of the agent conversations the work came from, and each session's repo path and working directory; never full commands or IDE file paths — to the model provider behind this agent, along with any files you read under `repoPath`. If the developer needs summaries that never leave their machine, point them to `workscribe summary`, whose template engine runs entirely offline.

package/skills/workscribe/references/json-contract.md

@@ -1,24 +1,39 @@
 # `workscribe sessions --json` — fields this skill uses
 
-The full contract is documented at workscribe.co/docs/commands#json-output-contract. Within `schemaVersion: 1`, fields are only ever added — ignore any you don't recognise.
+The full contract is documented at workscribe.co/docs/commands#json-output-contract. Within `schemaVersion: 2`, fields are only ever added — ignore any you don't recognise.
+
+Each session is one project's **thread**: that project's work inside a work block (a stretch between idle gaps). Working across several repos at once gives one block with a thread per repo, so sessions of one block overlap in time.
 
 ```json
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "date": "2026-10-25",
+  "blocks": [
+    {
+      "id": 1,
+      "startedAt": "2026-10-25T09:00:00.000Z",
+      "endedAt": "2026-10-25T10:30:00.000Z",
+      "activeMinutes": 85,
+      "threadKeys": ["api|2026-10-25T09:00:00.000Z", "web|2026-10-25T09:40:00.000Z"]
+    }
+  ],
   "sessions": [
     {
       "key": "api|2026-10-25T09:00:00.000Z",
       "project": "api",
       "repoPath": "/Users/dev/api",
       "branch": "feature/auth",
+      "branches": ["feature/auth", "main"],
       "startedAt": "2026-10-25T09:00:00.000Z",
       "endedAt": "2026-10-25T10:30:00.000Z",
-      "durationMinutes": 90,
+      "activeMinutes": 70,
+      "blockId": 1,
+      "alongside": ["web|2026-10-25T09:40:00.000Z"],
+      "tickets": ["API-412"],
       "notes": ["blocked on staging credentials"],
       "commits": [
-        { "hash": "a1b2c3d", "subject": "fix: token refresh race", "source": "git" },
-        { "hash": null, "subject": "wip: amended away", "source": "captured" }
+        { "hash": "a1b2c3d", "subject": "fix: token refresh race", "committedAt": "2026-10-25T10:12:00+01:00", "source": "git" },
+        { "hash": null, "subject": "wip: amended away", "committedAt": "2026-10-25T09:41:07.000Z", "source": "captured" }
       ],
       "events": [
         { "category": "testing", "exitCode": 1, "metadata": { "tool": "npm" } },
@@ -33,7 +48,10 @@ The full contract is documented at workscribe.co/docs/commands#json-output-contr
 | Field | Use it for |
 |---|---|
 | `key` | The `--key` when saving this session's summary. Copy it exactly. |
-| `project`, `branch`, `durationMinutes` | The block heading. `project` is the repo name, a `~/path` for work outside git, or `null` (write `unknown`). |
+| `project`, `branch`, `activeMinutes` | The block heading. `project` is the project's name, a `~/path` for work outside any project, or `null` (write `unknown`). `activeMinutes` is the time spent on this project; `startedAt`–`endedAt` can span other projects' work too. |
+| `branches` | Every branch the session touched, in the order first seen. `branch` is the latest of them, the one the session ended on. Each commit's `committedAt` says when it was made. |
+| `alongside` | The keys of the sessions worked in the same block. Don't mention those projects — Workscribe adds an `Alongside:` line under each summary itself — and leave their work to their own blocks. |
+| `tickets` | Ticket keys the session's branches and commits name. Mention one when the work is about it (e.g. "Fixed the token refresh race (API-412)"); don't list them for their own sake. May be empty even when a branch names one, right after an update. |
 | `repoPath` | Where to read files if a commit needs context. `null` outside a git repo. |
 | `notes` | The developer's own notes — always include them. |
 | `commits` | The main source of outcomes. `source: "git"` has a short `hash` to cite; `"captured"` commits have `hash: null` (amended or rebased). |

package/skills/workscribe/references/summary-format.md

@@ -5,12 +5,13 @@ One block per session, in exactly the shape Workscribe uses everywhere else, so
 ## Heading
 
 ```
-## <project> (<branch>) — <duration>
+## <project> (<branches>) — <duration>
 ```
 
-- Leave out ` (<branch>)` when `branch` is `null`.
+- `<branches>` is every branch in `branches`, in order, separated by `, ` — for example `## api (main, feature/auth) — 1h 30m`. With one branch it's just that branch.
+- Leave out the parentheses when `branches` is empty.
 - If `project` is `null` (no repo and no events), use `unknown`, as Workscribe does.
-- Duration from `durationMinutes`: under an hour as `45m`; otherwise `1h` or `1h 30m`.
+- Duration from `activeMinutes` — the time actually spent on that project; a session's start-to-end span can include work on other projects. Under an hour as `45m`; otherwise `1h` or `1h 30m`.
 
 ## Bullets