docs: add Docket 3.1 workflow guide

README.md

@@ -44,6 +44,21 @@ this exact copy of docket and tells you it did — but the short form survives
 moving or reinstalling, and `npx` leaves nothing on `PATH`.
 </details>
 
+
+## What's new in 3.1
+
+Docket 3.1 adds **digests**: an agent can read the work you already have in GitHub, GitLab, Notion, git, mail, chat and other configured sources, verify the current state, and publish one snapshot to the dashboard.
+
+The useful loop is short:
+
+```text
+make a digest → see what changed → copy #7 → tell an agent "take 7" → task is claimed → close with a reason
+```
+
+Digests also add owners, deeper per-item analysis, seen-state, "what changed" between snapshots, issue support, configurable MCP/file sources, daily headless runs, and the same behavior in Local and Self-hosted modes.
+
+**Start here:** [Docket 3.1 workflow guide](docs/3.1.md) · [Full digest reference](docs/digests.md) · [3.1 changelog](CHANGELOG.md#310)
+
 ## Why
 
 A thought that shows up mid-session is worth capturing but not worth the

docs/3.1.md

@@ -0,0 +1,200 @@
+# Docket 3.1
+
+Docket 3.1 turns the shared agent todo list into a small work console.
+
+The core loop is still deliberately simple: capture work from any MCP-capable agent and keep it visible across projects. Digests add a layer above that list: an agent can read the tools where work already lives, publish one verified snapshot, and hand any item back to an agent by number.
+
+## The 3.1 workflow
+
+```text
+GitHub / GitLab / Notion / git / mail / chat / files
+                         │
+                         ▼
+                   docket:digest
+                         │
+                         ▼
+             Docket dashboard home page
+                         │
+          ┌──────────────┼──────────────┐
+          ▼              ▼              ▼
+      what changed    needs you       shipped
+          │
+          ▼
+        #7 / D-XXXXXX/7
+          │
+          ▼
+      "take 7"
+          │
+          ▼
+       digest_take
+          │
+          ▼
+   claimed Docket task
+          │
+          ▼
+ todo_complete(id, reason)
+```
+
+The important boundary is intentional: **Docket does not log in to GitHub, GitLab, Notion, Slack, Gmail, or another work system.** Your agent reads those sources with the tools and credentials it already has. Docket stores only the digest the agent publishes.
+
+## Try it
+
+Install or update:
+
+```sh
+npx -y @pasichdev/docket setup
+```
+
+If you already use Docket 3.0, 3.1 upgrades in place. There is no todo-store format migration in this release.
+
+Install the Docket skill for Claude Code:
+
+```text
+/plugin marketplace add pasichDev/docket
+/plugin install docket@docket
+```
+
+Then ask:
+
+```text
+make a digest
+```
+
+or, for example:
+
+```text
+make a digest for the last 7 days
+```
+
+The `docket:digest-setup` skill can detect available sources and write the local configuration in:
+
+```text
+~/.config/docket/digest.json
+```
+
+Open the dashboard:
+
+```text
+http://localhost:8787
+```
+
+The home page now shows the latest digest. The ordinary task list lives at `/tasks`.
+
+## Hand work to an agent
+
+Every published digest item receives a number.
+
+If the dashboard shows:
+
+```text
+#7  Fix failing release workflow
+```
+
+you can tell any connected agent:
+
+```text
+take 7
+```
+
+or copy the stable handle:
+
+```text
+D-7K2F9A/7
+```
+
+The agent calls `digest_take`, receives the full item brief, and gets a Docket task claimed in its name. If the digest item already corresponds to a Docket task, Docket reuses it instead of creating a duplicate.
+
+When the work is finished, the agent closes it with:
+
+```text
+todo_complete(id, reason)
+```
+
+The reason is kept with the task history, so a hand-off ends with an explanation rather than a disappearing checkbox.
+
+## What changed since the previous digest
+
+Docket compares two published digests by item identity and computes:
+
+- newly listed work;
+- status changes such as `open → merged`;
+- items no longer listed.
+
+This comparison is produced by Docket itself when the digest is stored. It is not based on the agent remembering what it wrote last time.
+
+That gives the dashboard a useful first question: **what actually moved?**
+
+## Owners and depth
+
+Digest items can carry an `owner`:
+
+- `you`;
+- `agent`;
+- a person from the configured `people` list.
+
+The dashboard can group the next actions by person.
+
+Routine items stay compact. Important blocked, failing, stale, or decision-heavy items can include a Markdown `detail` field with the deeper analysis.
+
+## Seen items
+
+Marking an item **seen** hides routine noise without losing state.
+
+A seen item stays out of later digests while its status remains unchanged. If that status moves, for example an open pull request merges, it becomes relevant again.
+
+Seen marks are stored and synchronized alongside digests.
+
+## Sources
+
+Built-in digest workflows cover work from:
+
+- GitHub pull requests and issues;
+- GitLab merge requests and issues;
+- Notion;
+- local git repositories;
+- Docket tasks;
+- Obsidian;
+- project files;
+- mail and chat through connected MCP tools.
+
+Additional read-only MCP sources can be configured for systems such as Jira, Linear, YouTrack, Sentry, Slack, or another server the agent can query.
+
+Source failures are part of the digest rather than silently ignored, so a snapshot can say that one area could not be checked.
+
+## Local and self-hosted
+
+Digests work in both deployment modes.
+
+### Local Mode
+
+Digests are stored in `digests.json.enc` and can sync between paired devices. They use their own cursor and sequence space, separate from todo synchronization.
+
+### Self-hosted Mode
+
+Clients publish and read digests through the Docket Server. All paired clients see the same digest state immediately through the server rather than waiting for peer synchronization.
+
+## Daily digests
+
+Digest configuration can define a daily schedule. The skill can offer a macOS LaunchAgent or Linux user timer for a headless run.
+
+The schedule is opt-in. Docket does not silently install background jobs.
+
+The Claude Code SessionStart hook can also show a one-line summary of the newest digest and suggest creating a fresh one when it is old.
+
+## Useful commands and tools
+
+| Action | Command / tool |
+|---|---|
+| Setup Docket | `npx -y @pasichdev/docket setup` |
+| Open dashboard | `docket web` |
+| Configure digest sources | `docket:digest-setup` skill |
+| Build a digest | `docket:digest` skill |
+| Publish from an agent | `digest_publish(...)` |
+| Read latest/recent digests | `digest_list`, `digest_get` |
+| Give item 7 to an agent | `digest_take("7")` |
+| Read seen-state | `digest_seen()` |
+| Finish handed-off work | `todo_complete(id, reason)` |
+
+For the full data shape, configuration options, storage and sync behavior, see [Digests](digests.md).
+
+For the complete release history, see the [changelog](../CHANGELOG.md).