@sinoia/hubdoc-tools 1.8.3 → 1.10.0

package/docs/llm-usage.md

@@ -362,6 +362,109 @@ hubdoc permissions ls --on="$WS" --on-type=workspace --json \
     | jq '.[] | {actor: .actor.display_name, level}'
 ```
 
+### Projects / Sprints / Tickets / Tasks (corex#588)
+
+Manage projects (attached to a workspace or standalone), their sprints,
+tickets and sub-tasks — the same domain Synapse agents drive when they
+consume incoming emails, produce deliverables, or hand off work between
+themselves. All commands support `--json` for machine parsing.
+
+`hubdoc projects` (top-level: attached to a workspace or standalone) —
+`ls | show | create | update | delete | archive | publish`.
+`--workspace null` filters the standalone (unattached) projects.
+
+`hubdoc sprints --project=<pid>` — `ls | show | create | update | delete
+| start | complete`.
+
+`hubdoc tickets --project=<pid>` — `ls | show | create | update | delete
+| assign | status | move | activities | deliverable | dispatch |
+comment | comments`. Every verb requires `--project=<pid>`. `ls
+--backlog` (or `ls --sprint null`) lists the backlog. `assign --to null`
+unassigns. `status --to <state> [--column <col>]` uses the canonical
+statuses: `open | in_progress | done | blocked | awaiting_human |
+cancelled | failed` and optionally pins the kanban column at the same
+time. `comment <id> --body <text>` (or `--body-file <path>`) posts a
+message on the ticket's discussion thread (visible in Corex / Agoria,
+attributed to the token holder); `comments <id>` reads the thread
+oldest-first (paginated like `activities`).
+
+`hubdoc tasks --project=<pid> --ticket=<tid>` — `ls | show | create |
+update | delete | complete | reorder`. Sub-tasks live under a ticket;
+both parents are required on every call.
+
+**Pagination**: all `ls`-shaped verbs return `{ items, pagination:{ page,
+per_page, pages, count, has_more } }` in `--json`. The transport under
+the hood is a bare JSON array plus `X-Total-*` headers (Pagy), same
+convention as `/api/v1/documents`; the CLI normalises so agents don't
+need to touch headers.
+
+**Idempotence caveat**: `sprints start` / `sprints complete` follow the
+interactor semantics — re-triggering on a sprint already in the target
+state returns **422** (`unprocessable_entity` with an
+`already_active` / `already_completed` message), not 200.
+
+**Deliverables**: `tickets deliverable <id> --deliverable <did>`
+publishes an EXISTING deliverable already attached to the ticket (via
+web UI or a future create endpoint). The API does not yet support
+creating + publishing a deliverable in one CLI call — track corex#588
+follow-ups.
+
+**Dispatch**: `tickets dispatch <id>` fires the agent already configured
+on the ticket (`agent_config` is read from the ticket's persisted
+state). To change the agent config, set it on the ticket via the web UI
+or a future `update` extension — the CLI cannot pass it in the request
+body today.
+
+#### End-to-end example: agent turns an incoming email into a mission
+
+```bash
+# 0. The Synapse poller has already dropped the raw .eml + attachments
+#    into Hubdoc and passed us the email doc id.
+EMAIL_ID="doc-42"
+
+# 1. Detach attachments so the agent can classify them separately.
+hubdoc files detach "$EMAIL_ID" --ext pdf,docx --json
+
+# 2. Pick the standalone project used for triage (no workspace linkage).
+PID=$(hubdoc projects ls --workspace null --type-id "$TRIAGE_PT_ID" --json \
+        | jq -r '.items[0].id')
+
+# 3. Create a ticket in the current sprint, priority high, due next week.
+SID=$(hubdoc sprints ls --project "$PID" --status active --json \
+        | jq -r '.items[0].id')
+TID=$(hubdoc tickets create --project "$PID" \
+        --title "Client X – devis à produire" \
+        --sprint "$SID" --assignee "u-1" \
+        --priority high --due 2026-07-18 \
+        --labels "commercial,urgent" --json | jq -r '.data.id')
+
+# 4. Break it down into tasks the agent will chew through.
+hubdoc tasks create --project "$PID" --ticket "$TID" \
+    --title "Lire pièces jointes" --priority high --json
+hubdoc tasks create --project "$PID" --ticket "$TID" \
+    --title "Rédiger devis" --priority high --due 2026-07-16 --json
+
+# 5. Dispatch the agent already configured on the ticket.
+hubdoc tickets dispatch "$TID" --project "$PID" --json
+
+# 6. Later — post a follow-up on the ticket thread (visible to the human):
+hubdoc tickets comment "$TID" --project "$PID" \
+    --body "Point d’avancement : devis en cours de rédaction, ETA demain 10h." --json
+
+# 7. Publish an already-attached deliverable and close the ticket.
+hubdoc tickets deliverable "$TID" --project "$PID" \
+    --deliverable "$DELIVERABLE_ID" --json
+hubdoc tickets status "$TID" --project "$PID" \
+    --to done --column done --json
+```
+
+Common patterns:
+- **Move a ticket to the backlog**: `hubdoc tickets move <id> --project=<pid>
+  --backlog` (equivalent to `--sprint null`).
+- **Un-assign**: `hubdoc tickets assign <id> --project=<pid> --to null`.
+- **Reorder a ticket's tasks** (drag-and-drop from the UI equivalent):
+  `hubdoc tasks reorder --project=<pid> --ticket=<tid> --order=k3,k1,k2`.
+
 ## Out of scope (planned)
 
 - `hubdoc templates create|update|delete` — depends on corex#417 backend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sinoia/hubdoc-tools",
-  "version": "1.8.3",
+  "version": "1.10.0",
   "description": "Professional command-line tool for HubDoc document management and bulk import/export",
   "main": "cli.js",
   "bin": {