monday-cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,357 @@ output envelope (`{ ok, data, meta, ... }`) and 29 stable error
 codes are part of the public contract — the SemVer rules in
 [`docs/cli-design.md`](./docs/cli-design.md) §6 govern bumps.
 
+## [0.4.0] - 2026-05-14 — Operational features: long-poll watch, parallel bulk, asset upload, workdocs reads, shell completion
+
+The "agents can drive long-running workflows + multipart wire +
+shell completion" milestone — v0.3's "drive a real backlog"
+foundation gains long-poll item activity streaming (NDJSON), bounded
+parallel bulk dispatch, the first multipart wire surface (asset
+uploads), Monday workdocs reads, and per-shell completion script
+generation. **No breaking changes vs `0.3.0` — every v0.4 surface
+is additive.** Built incrementally across M29–M33.
+
+### Breaking changes vs `0.3.0`
+
+**None.** Every command, error code, envelope key, and warning
+shape shipped in v0.3.0 is preserved byte-for-byte. v0.4 only adds.
+
+### Surface
+
+**~101 commands shipped (was ~95 in v0.3).** Six new verbs +
+one orthogonal flag extension on an existing verb. The new noun
+namespaces are `doc` (workdocs reads) and `completion` (CLI-
+internal, shell completion script generator).
+
+**Long-poll item activity streaming (M29) — `monday item watch
+<iid>`.** Long-polls Monday's `boards.activity_logs(item_ids:)`
+with a polling cadence floor of `MIN_WATCH_INTERVAL_MS` (1000ms)
+and emits one NDJSON event record per emitted activity-log row
+plus a trailing `{"_meta": {...}}` record carrying the seven
+M29-specific session counters flat under `_meta`:
+`events_emitted`, `polls_made`, `failed_polls`,
+`last_seen_event_id`, `circuit_broken_at`, `exit_reason`,
+`watch_duration_seconds` (plus the standard meta keys + a
+`warnings: [...]` slot accumulating `poll_failed` /
+`circuit_breaker_armed` warnings). Modes: `--once` drains backlog
+and exits without polling further; `--max-events <N>` /
+`--max-duration <duration>` ceilings exit cleanly with the matching
+`exit_reason`; `--since <event-id>` looks up the event's
+`created_at` once and starts the loop from there; `--include
+<kind>` filter narrows emitted events (v0.5+ may extend with
+comment polling via `--include update_posted` once Monday's
+`activity_logs` surfaces those). SIGINT drains gracefully + exits
+130. Circuit-breaker trips after 5 consecutive `complexity_exceeded`
+polls (emits an `exit_reason: circuit_broken` trailer + a §6.5
+failure envelope on stderr + exit code 2; a successful poll between
+failures resets the consecutive counter). Walker-side
+`entity === 'pulse'` filter drops board-scoped rows per Decision 2
+closure.
+
+**Parallel bulk dispatch (M30) — `monday item update --where ...
+--concurrency <N>`.** Extends the M25 partial-success bulk path
+with bounded parallel dispatch via a new `--concurrency <N>` flag
+(range 1..32; default 1). `--concurrency 1` routes through
+`dispatchSequential` (byte-equivalent to the M25 default);
+`--concurrency > 1` routes through `dispatchParallel` (semaphore-
+bounded worker pool). The envelope is byte-equivalent across both
+paths — `--concurrency` is a dispatch-mode flag, not a contract
+extension. **Input-order preservation**: `data.results[]` lists
+per-target outcomes in the original matched-item order regardless
+of completion order, so agents can correlate `results[i]` ↔
+`matched_items[i]` deterministically. `--concurrency` is mutually
+exclusive with the single-item shape (rejected with `usage_error`
+at `validateInputShape` before any network call) and requires
+`--continue-on-error` on the bulk shape (the fail-fast bulk path
+keeps its v0.1 envelope).
+
+**Asset uploads (M31) — `monday item upload` + `monday update
+upload`.** First multipart wire surface (`add_file_to_column` /
+`add_file_to_update`). Per-verb shapes:
+
+- `monday item upload <iid> --column <col> <file>` uploads the
+  local file as a Monday asset attached to the named column on
+  the item. Column type is validated against the writable-files
+  allowlist (`file` only at v0.4 — Monday's `add_file_to_column`
+  doesn't generalise to other types).
+- `monday update upload <update-id> <file>` uploads the local
+  file as an asset attached to a Monday "update" (comment).
+
+Both verbs do a JSON-leg pre-read (item-board lookup + board
+metadata for column resolution, or update lookup) followed by
+the multipart `add_file_to_*` mutation. The success envelope
+carries Monday's full `Asset` projection (`id`, `name`, `url`,
+`public_url`, `file_extension`, `file_size`, `uploaded_by`, etc.).
+Pre-checks: `file_not_readable` (ENOENT or directory), `file_empty`
+(zero-byte). `file_too_large` rewrap on Monday's
+`FILE_SIZE_LIMIT_EXCEEDED` (non-retryable; the underlying
+multipart wire is retryable, but the file-size error isn't —
+M31 IMPL round-1 P2-1 closure). MIME content-type sniffed via the
+new lifted `src/utils/mime.ts` (R-NEW-NEW shipped at M31 IMPL —
+2-consumer trigger ahead of v0.4-plan §22's typical 3-consumer
+threshold). `--dry-run` previews the planned change envelope
+without firing the multipart wire (file path + filename +
+file_size_bytes echoed; argv path preserved verbatim for relative
+inputs per the R-class round-2/round-3 closure). Uploads are
+**non-idempotent**: each successful call mints a fresh `Asset`
+ID — re-running uploads the file a second time. Agents needing
+register-once dedupe pre-read `Item.assets` / `Update.assets`
+(read-side `item assets` / `update assets` verbs deferred to
+v0.4.x per M31 Decision D6). Cache invalidation fires single-leg
+on item-upload success (the parent item's board metadata cache
+invalidates per §8); update-upload doesn't touch board metadata
+so there's no invalidation step.
+
+**Monday workdocs reads (M32) — `monday doc list [--workspace
+<wid>,...] [--order-by <created_at|used_at>] [--limit <n>]
+[--page <n>]` + `monday doc get <did>`.** First read-only access
+to Monday's workdocs surface (`Query.docs(...)`). `doc list` is
+paginated via page/limit (no cursor on Monday's workdocs surface);
+defaults to `--limit 25 --page 1`; range 1..100. `--workspace
+<wid>,...` accepts a comma-separated `WorkspaceId` list and maps
+to wire `workspace_ids: [ID]` — Monday silently drops inaccessible
+IDs (best-effort, no resolver warning). `--order-by <created_at|
+used_at>` is a closed 2-value enum; both sort `desc` server-side.
+`doc list` emits a wrapped record envelope: `data:
+{ documents: [...], page, limit, returned_count, has_more }`
+where `has_more === (returned_count === limit)` (Monday's wire
+has no `total_count` slot). `doc get <did>` emits the direct-
+unwrap `data: <Document with blocks>` shape; empty `docs: []` →
+`not_found` with `details.doc_id` per D8 closure (Monday returns
+empty when the doc doesn't exist OR is inaccessible — single
+error code per the closure). `DocId` joins the brand registry
+(`src/types/ids.ts`) as the 9th brand. **The full workdocs CRUD
+mutation surface (9 mutations: `create_doc` / `update_doc_name`
+/ `delete_doc` / `duplicate_doc` / `import_doc_from_html` /
+`add_content_to_doc_from_markdown` / `create_doc_block` /
+`update_doc_block` / `delete_doc_block`) is deferred to v0.5 per
+D8 closure** — each mutation has enough surface area to warrant
+its own milestone cluster.
+
+**Shell completion (M33) — `monday completion <bash|zsh|fish>`.**
+First raw-bytes-carve-out verb (cli-design §3.1 #2). The default
+mode emits the install-time script bytes on stdout regardless of
+TTY/pipe context — `monday completion bash >> ~/.bashrc` writes
+the bash script to bashrc as a sourceable file. The `--json` /
+`--output json` / `MONDAY_OUTPUT=json` paths opt INTO the §6
+envelope with `data: { shell, script }` + `meta.source: "none"`
+(CLI-internal verb — no Monday wire call, no cache, no auth
+requirement). `--table` / `--output table` / `--output text` /
+`--output ndjson` reject with `usage_error` at the parse boundary
+(only `--json` and `--table` are global shorthand flags per
+cli-design §4.4). Per-shell scripts are hand-rolled templates
+(commander 14.0.3 ships **no** built-in completion machinery,
+verified by empirical probe at M33 pre-flight) generated by
+walking the registered command tree at runtime so agents adding a
+new verb get completion for free. ERROR_CODES count stays at 29
+per D4 closure. No new runtime dependency added per cli-design §1
+"minimum deps".
+
+### Output contract additions
+
+**No new stable error codes — registry stays at 29.** Every v0.4
+milestone closed the new-error-code question NEGATIVE: M29 routes
+poll failures through the existing `complexity_exceeded` /
+`rate_limited` / `network_error` codes (the trailer's
+`exit_reason: circuit_broken` is an envelope-level discriminator,
+not a `error.code`); M30 routes per-item failures through the M25
+codes (`column_archived` / `validation_failed` / etc.); M31 routes
+file-IO pre-checks through `usage_error.details.reason` discriminator
+(`file_not_readable` / `file_empty` / `file_too_large`); M32
+routes empty-array `doc get` through the existing `not_found`; M33
+routes invalid shells through `usage_error` from the `parseArgv`
+boundary.
+
+**New NDJSON trailer shape** (M29 — `monday item watch`). NDJSON-
+streaming verbs emit a final `{"_meta": {...}}` record carrying the
+seven M29-specific session counters flat alongside the standard
+meta keys (per cli-design §6.3 trailer contract). Pinned by the
+envelope-snapshot suite + dedicated per-command suite.
+
+**New wrapped-paginated-record envelope** (M32 — `monday doc
+list`). `data: { documents, page, limit, returned_count, has_more
+}` carries the pagination wrapper alongside the projection list.
+Mirrors the M22 `monday usage` wrapped-record shape but on a
+read-paginated surface. R-NEW-74 watch-item tracks the
+`kind: 'record'` candidate for a future `emitSuccess` shape
+extension (`emit.ts` ships only `kind: 'single' | 'collection'`
+today; `'single'` does double-duty for wrapped records). JSON
+output works correctly today; the watch-item fires only on a
+table-UX complaint + 3rd consumer.
+
+**New raw-bytes-default verb** (M33 — `monday completion`). First
+verb whose default stdout payload is NOT a §6 envelope. The
+carve-out at cli-design §3.1 #2 enumerates the rule: raw-bytes
+mode is opt-out (`--json` / `--output json` / `MONDAY_OUTPUT=json`
+opts INTO the envelope). The §6 envelope shape on the opt-in path
+is byte-identical to other CLI-internal verbs:
+`data: { shell, script }` + `meta.source: "none"`.
+
+**New multipart-mutation planned-change envelope** (M31 —
+`item upload --dry-run` + `update upload --dry-run`). The
+`planned_changes[]` entry shape extends the standard dry-run
+envelope with multipart-specific slots: `operation:
+"add_file_to_column"` / `"add_file_to_update"`, `file_path`,
+`filename`, `file_size_bytes`, plus the standard `item_id` /
+`column_id` (or `update_id`) keys.
+
+### Upgrade notes
+
+- **`unsupported_column_type` `deferred_to: "v0.4"` slips to
+  `"v0.5"`** for the files-shaped category (`file` column type via
+  `--set` / `--set-raw`). v0.4-M31 shipped the verb-shaped path
+  (`monday item upload`) — that's the alternative path agents
+  should use today — but NOT the friendly `--set
+  <file-col>=<path>` / `--set-raw <file-col>=<json>` form (which
+  would need a separate dispatch from the translator boundary
+  into the multipart wire). Agents that previously caught the
+  v0.3.0 envelope's `deferred_to: "v0.4"` for the files-shaped
+  reject path should update their comparison to `"v0.5"`; the
+  `error.code: "unsupported_column_type"` + the hint pointing at
+  `monday item upload` are unchanged. **The hint is the load-
+  bearing routing surface — agents key off the hint, not the
+  `deferred_to` value.**
+- **Multi-level subitem creation slips from `"v0.4"` → `"v0.5"`.**
+  Originally slipped from v0.3 → v0.4 at v0.3-M28 audit. v0.4
+  didn't pick it up — Monday's `sub_items_board` carries no
+  `subtasks` column at API `2026-01`, so depth-2 subitems still
+  have no data-model home. Single-level subitems (`item create
+  --parent <iid>` against classic boards) continue to work
+  byte-identically. The `error.code: "usage_error"` +
+  `details.hierarchy_type: "multi_level"` keys are unchanged.
+- **Cross-board `item move` value-overrides slip from `"v0.4"` →
+  `"v0.5"`.** Originally v0.3-M11-targeted, slipped to v0.4 at
+  v0.3-M28 audit, slipped to v0.5 at v0.4 release-prep. Monday's
+  `ColumnMappingInput` still carries no value slot; supporting it
+  would need a non-atomic post-move `change_multiple_column_
+  values` with cross-leg partial-failure envelope shapes that
+  have no precedent at v0.4 close. Agents needing overrides
+  continue to fire `monday item set <iid> <target>=<value>`
+  post-move.
+- **Cross-board resumable cursor slips from `"v0.4"` → `"v0.5"`.**
+  The `cross_board_truncated` warning's `details.hint` continues
+  to recommend narrowing via `--workspace` / `--favorites` /
+  `--max-boards`; v0.5 may pick the resumable surface up if
+  per-board cursor-lifetime under aggregation gets a clean design.
+- **Stable error-code registry stays at 29.** Existing codes'
+  shapes are unchanged across v0.3 → v0.4.
+- **`--concurrency <N>` is a new global-ish flag on bulk
+  `item update`.** Default `1` preserves the M25 sequential
+  envelope byte-for-byte; agents only opt INTO parallel dispatch
+  by passing the flag.
+- **`monday auth login` placeholder-guard unchanged.** The verb
+  is still registered and still surfaces `usage_error.details.
+  reason: oauth_unregistered` pointing at `MONDAY_API_TOKEN`
+  (unchanged from v0.3.0). The OAuth deferral revisits in v0.4.x
+  / v0.5 contingent on user demand.
+
+### Internals worth highlighting
+
+- **First multipart wire surface (M31)** introduces a new
+  transport seam (`MultipartTransport`) alongside the JSON
+  `transport` slot in `ResolvedClient`. Test seam mirrors the
+  JSON path's pattern (`ctx.multipart` injection wins;
+  production builds fresh via `createMultipartTransport(...)`).
+  The `add_file_to_column` / `add_file_to_update` fetchers share
+  an inline `dispatchMultipartOnce` helper + an inline retry-
+  thunk rewrap pattern for the non-retryable file_too_large case
+  (the wrap-vs-thunk placement is invariant — round-1 P2-1
+  closure). Codex pre-pre-flight checklist R-v0.4-W2 ratified
+  for "new transport seam" milestones.
+
+- **R-class refactors shipped during v0.4.** R-NEW-41 (asymmetric
+  wire-vs-CLI semantics documentation pattern) shipped at M31
+  pre-flight as a new `docs/architecture.md` "Wire-vs-CLI
+  semantics documentation conventions" section enumerating the
+  three documented asymmetries (M27 webhook.config wire-typing
+  + M27 NotificationTargetType + M31 multipart-vs-JSON
+  transport). R-NEW-NEW `sniffContentType` lift to
+  `src/utils/mime.ts` (M31 IMPL — 2-consumer trigger ahead of
+  the typical 3-consumer threshold; coverage from integration
+  tests alone would have failed the branches floor). R-NEW-56
+  ratified for the 3rd consecutive IMPL milestone (cross-doc
+  grep at IMPL kickoff catches prose-drift surface ahead of
+  Codex review). R-NEW-58 ratified via positive case at M31
+  + negative case at M32. R-NEW-72 (cross-doc grep after every
+  contract-flipping Codex fix-up) graduated to a permanent
+  CLAUDE.md "Workflow rules" entry at M33 IMPL close. R-NEW-75
+  (5-dimension candidate-selection framework) graduated at the
+  post-M33 candidate-selection session that picked release-prep
+  over team writers. Full register with shipped commit SHAs +
+  consumer counts lives in [`docs/v0.4-plan.md`](./docs/v0.4-plan.md) §22.
+
+- **Empirical probes** ratified across every novel v0.4 surface:
+  M29 `activity_logs` polling shape, M31 multipart `add_file_to_*`
+  wire, M32 `Query.docs(...)` filter + ordering enum + pagination
+  shape, M33 commander capability check (returned ZERO hits,
+  flipping the cli-design §13 entry from "via commander" to
+  "hand-rolled templates" before any pre-flight contract claim
+  could drift). R-NEW-77 (CLI-internal milestone empirical-probe-
+  slot equivalent) filed at M33 pre-flight as a 1-consumer
+  watch-item.
+
+- **Two-AI review** (cli-design pre-flight + implementation
+  review) ran for every milestone M29–M33. M30 IMPL took 5
+  rounds to converge (the lesson driving R-NEW-56's pre-IMPL
+  cross-doc grep + R-NEW-72's post-fix-up grep). M31 took 7
+  pre-flight rounds (two distinct surface classes plus
+  substantive transport-seam gaps at rounds 6-7) + 3 IMPL rounds.
+  M32 / M33 each converged in 3 IMPL rounds. The cumulative
+  finding count + per-milestone Codex-round breakdown lives in
+  the per-milestone post-mortems in
+  [`docs/v0.4-plan.md`](./docs/v0.4-plan.md) §3 + §13–§15.
+
+### Tests + quality gates
+
+- **3634 unit/integration + E2E tests** at v0.4.0 (+1 skipped;
+  was 3249+1 ≈ 3250 in v0.3.0; ~385 new tests across M29–M33 +
+  the v0.4 release-prep envelope-snapshot refresh). All green on
+  Node 22 + 24.
+- **Coverage at 99.26 / 96.33 / 99.34 / 99.53** (statements /
+  branches / functions / lines) against the floor 95 / 95.45 / 95
+  / 95. Branches margin **0.88pp** at v0.4.0 (was 0.95pp at
+  v0.3.0; the v0.4 surface introduced novel branch-heavy areas
+  like M29's circuit-breaker progression + M30's parallel
+  dispatcher, both of which carry full integration-test coverage
+  but eat margin). Floor unchanged across v0.3.0 → v0.4.0.
+- **Envelope-snapshot suite refreshed** for v0.4 surfaces — adds
+  11 snapshots covering item watch (NDJSON trailer shape),
+  doc list (wrapped record), doc get (direct unwrap + D8
+  not_found), completion bash/zsh/fish --json (raw-bytes-carve-
+  out envelope opt-in), completion --table + invalid-shell
+  rejections. Item upload / update upload pinned by the per-
+  command suites (multipart transport scaffolding stays out
+  of the envelope-snapshot suite per the v0.3-M28 cross-board /
+  dev precedent). `--concurrency` envelope byte-equivalent to
+  the existing M25 sequential snapshot — pinned by the per-
+  command bulk suite.
+- **Five test layers held**: unit, integration (in-process
+  `FixtureTransport` + `MultipartFixtureTransport`), E2E
+  (subprocess against fixture server), envelope-shape snapshot
+  suite, published-tarball E2E.
+
+### Documentation
+
+- **[`docs/v0.4-plan.md`](./docs/v0.4-plan.md)** new — the v0.4
+  active plan with M29–M33 milestones, decisions log, R-class
+  register (R-NEW-44 through R-NEW-81), per-milestone post-
+  mortems (§3 + §13–§15 + §22).
+- **[`docs/cli-design.md`](./docs/cli-design.md)** §4.3 grew six
+  new verb entries; §3.1 #2 raw-bytes carve-out documented; §13
+  v0.4 entry closed out + the v0.5 frame pinned (team writers +
+  doc CRUD mutation surface deferred to v0.5).
+- **[`docs/architecture.md`](./docs/architecture.md)** gained
+  the "Wire-vs-CLI semantics documentation conventions" section
+  (R-NEW-41 shipped at M31 pre-flight).
+- **[`docs/output-shapes.md`](./docs/output-shapes.md)** — every
+  shipped v0.4 command has a per-section data shape entry,
+  snapshot-backed.
+- **README.md** quickstart expanded with v0.4 examples (`monday
+  completion`, `monday item watch`, `monday item upload`,
+  `--concurrency`, `monday doc list/get`).
+
+[0.4.0]: https://github.com/Firer/monday-cli/releases/tag/v0.4.0
+
 ## [0.3.0] - 2026-05-13 — Monday Dev + multi-profile + diagnostics + outbound writes
 
 The "agent can drive a real backlog with a real workflow" milestone —

package/README.md

@@ -49,41 +49,71 @@ Requires **Node.js ≥ 22**.
 #    Get one at https://<your-org>.monday.com/admin/integrations/api
 #
 #    OAuth login (`monday auth login`) is registered but deferred in
-#    v0.3.0 — the verb surfaces a clear `usage_error.details.reason:
+#    v0.4.0 — the verb surfaces a clear `usage_error.details.reason:
 #    oauth_unregistered` pointing here. Authenticate via the env var.
 export MONDAY_API_TOKEN="<your-token>"
 
 # 2. Smoke test — confirm the token works.
 monday account whoami --json
 
-# 3. Is everything wired up? (v0.3 diagnostics cluster)
-monday status --json                    # 7-probe DNS/TCP/TLS/auth/cache matrix
-monday usage --json                     # remaining daily Monday API operations
+# 3. Install shell completion (v0.4-M33 — bash / zsh / fish).
+#    The default mode emits raw script bytes on stdout (so the redirect
+#    works); `--json` opts INTO the §6 envelope.
+monday completion bash >> ~/.bashrc        # or .zshrc / config.fish
 
-# 4. List a board's items (replace 12345 with your board ID)
+# 4. Is everything wired up? (v0.3 diagnostics cluster)
+monday status --json                       # 7-probe DNS/TCP/TLS/auth/cache matrix
+monday usage --json                        # remaining daily Monday API operations
+
+# 5. List a board's items (replace 12345 with your board ID)
 monday item list --board 12345 --json
 
-# 5. File a new task (v0.2)
+# 6. File a new task (v0.2)
 monday item create --board 12345 --name "Refactor login" \
   --set status=Backlog --set 'Due date'=+1w --json
 
-# 6. Find-or-create with idempotent matching (v0.2)
-#    Re-running with the same args is safe — 0/1/2+ matches route to
-#    create / update / `ambiguous_match` (one of the 29 stable error codes).
+# 7. Long-poll for activity on an item (v0.4-M29 — NDJSON stream).
+#    Per-event NDJSON record + a `{"_meta": {...}}` trailer carrying
+#    the session counters. Use `--once` to drain backlog without
+#    polling further; SIGINT (Ctrl-C) drains gracefully and exits 130.
+monday item watch 67890 --once             # or --max-events 50 --max-duration 1h
+
+# 8. Upload a file to a column or update (v0.4-M31 — multipart wire).
+#    `add_file_to_column` for item columns; `add_file_to_update` for
+#    comment attachments. Both surface `--dry-run` for an envelope
+#    preview without the multipart round-trip.
+monday item upload 67890 --column 'Attachments' ./screenshot.png --json
+monday update upload <update-id> ./diagram.png --json
+
+# 9. Parallel partial-success bulk updates (v0.4-M30).
+#    `--concurrency <N>` (range 1..32) opts into parallel dispatch on
+#    the M25 partial-success path. Envelope is byte-equivalent to the
+#    sequential `--concurrency 1` default; input order is preserved
+#    in `data.results[]` regardless of completion order.
+monday item update --where status=Backlog --set status='Working on it' \
+  --board 12345 --yes --continue-on-error --concurrency 4 --json
+
+# 10. Browse the workdocs surface (v0.4-M32 — read-only at v0.4).
+monday doc list --workspace 5 --order-by used_at --limit 10 --json
+monday doc get 88001 --json                # full Document with blocks
+
+# 11. Find-or-create with idempotent matching (v0.2)
+#     Re-running with the same args is safe — 0/1/2+ matches route to
+#     create / update / `ambiguous_match` (one of the 29 stable error codes).
 monday item upsert --board 12345 --name "Refactor login" \
   --match-by name --set status='Working on it' --json
 
-# 7. Move a ticket forward, then comment on it
+# 12. Move a ticket forward, then comment on it
 monday item set 67890 status=Done --json
 monday update create 67890 --body "Shipped in PR #1234" --json
 
-# 8. Monday Dev convention layer (v0.3 — sprint/epic/release/task)
-#    First-time setup auto-detects boards by Monday's stock template names.
-monday dev discover --apply --json      # writes ~/.monday-cli/config.toml
-monday dev sprint current --json        # the active sprint
-monday dev task list --mine --json      # my open tasks
+# 13. Monday Dev convention layer (v0.3 — sprint/epic/release/task)
+#     First-time setup auto-detects boards by Monday's stock template names.
+monday dev discover --apply --json         # writes ~/.monday-cli/config.toml
+monday dev sprint current --json           # the active sprint
+monday dev task list --mine --json         # my open tasks
 
-# 9. Outbound writes (v0.3 — webhooks + notifications)
+# 14. Outbound writes (v0.3 — webhooks + notifications)
 monday webhook list 12345 --json
 monday notification send --user 7 --target 67890 \
   --target-type item --text "PTAL" --json
@@ -152,7 +182,7 @@ Every JSON response uses the same universal envelope:
   "meta": {
     "schema_version": "1",
     "api_version": "2026-01",
-    "cli_version": "0.3.0",
+    "cli_version": "0.4.0",
     "request_id": "0e6f1a7b-...",
     "source": "live",
     "cache_age_seconds": null,
@@ -252,7 +282,27 @@ See [`.env.example`](./.env.example) for all supported variables
 
 ## Scope
 
-**v0.3.0 (current — `monday-cli@0.3.0` on npm):**
+**v0.4.0 (current — `monday-cli@0.4.0` on npm):**
+the v0.3 surface PLUS long-poll item activity streaming
+(`monday item watch <iid>` — NDJSON), parallel bulk dispatch
+(`monday item update --where ... --concurrency <N>`), asset uploads
+(`monday item upload` / `monday update upload` — multipart wire),
+Monday workdocs reads (`monday doc list` / `monday doc get` — full
+workdocs CRUD mutation surface deferred to v0.5), and shell
+completion (`monday completion bash|zsh|fish`). **No breaking
+changes vs v0.3.0** — every v0.4 surface is additive. Built
+incrementally across M29–M33. See [CHANGELOG.md](./CHANGELOG.md)
+for the full per-milestone release notes.
+
+**OAuth deferral (unchanged from v0.3.0).** `monday auth login` is
+registered but the canonical Monday OAuth app is not registered in
+v0.4.0; the verb surfaces a clear `usage_error.details.reason:
+oauth_unregistered` pointing at `MONDAY_API_TOKEN`. Multi-profile
+config + per-profile credentials cache work fully against API
+tokens; OAuth registration revisits in v0.4.x / v0.5 contingent on
+user demand.
+
+**v0.3.0 (the previous release):**
 the v0.2 mutating core PLUS the Monday Dev convention layer
 (`monday dev` namespace — sprint / epic / release / task workflow
 shortcuts on top of standard board CRUD), multi-profile auth
@@ -266,17 +316,8 @@ outbound writes (`monday webhook list/create/delete` +
 (`tags`, `board_relation`, `dependency`) closing the v0.2
 tentative-row carryover. **No breaking changes vs v0.2.0** — every
 v0.3 surface is additive. Built incrementally across M19–M28.
-See [CHANGELOG.md](./CHANGELOG.md) for the full per-milestone
-release notes.
-
-**OAuth deferral.** `monday auth login` is registered but the
-canonical Monday OAuth app is not registered in v0.3.0; the verb
-surfaces a clear `usage_error.details.reason: oauth_unregistered`
-pointing at `MONDAY_API_TOKEN`. Multi-profile config + per-profile
-credentials cache work fully against API tokens; OAuth registration
-revisits in v0.3.x / v0.4 contingent on user demand.
 
-**v0.2.0 (the previous release):**
+**v0.2.0 (the prior release):**
 the v0.1 read-only core + safe-mutations surface PLUS the full
 mutation surface (item lifecycle, update mutations, workspace
 lifecycle, board lifecycle, board columns + groups). Built
@@ -461,15 +502,66 @@ row `tags`, `board_relation`, `dependency`.
   deferred out of v0.3 per Decision 11 (Monday's `sub_items_board`
   carries no `subtasks` column at API `2026-01`).
 
-**v0.4:** `monday item watch`, `--concurrency` bulk parallelism,
-asset uploads, multi-level subitems if Monday's data model
-surfaces them.
+**What v0.4 added (M29–M33; full per-milestone narrative in
+[CHANGELOG.md](./CHANGELOG.md)):**
+
+- **M29** — `monday item watch <iid>` long-polls `boards.activity_
+  logs(item_ids:)` for per-item event streaming. NDJSON output:
+  one event record per emitted activity-log row + a trailing
+  `{"_meta": {...}}` record carrying the seven session counters
+  (`events_emitted` / `polls_made` / `failed_polls` /
+  `last_seen_event_id` / `circuit_broken_at` / `exit_reason` /
+  `watch_duration_seconds`). `--once` drains backlog and exits
+  without polling further; `--max-events` / `--max-duration`
+  ceilings exit cleanly; SIGINT drains gracefully + exits 130.
+  Circuit-breaker trips after 5 consecutive `complexity_exceeded`
+  polls.
+- **M30** — `monday item update --where ... --concurrency <N>`
+  (range 1..32; default 1) opts into bounded parallel dispatch on
+  the M25 partial-success path. Envelope is byte-equivalent to the
+  sequential default; input order is preserved in `data.results[]`
+  regardless of completion order. `--concurrency 1` routes through
+  `dispatchSequential`; `> 1` routes through `dispatchParallel`.
+- **M31** — `monday item upload <iid> --column <col> <file>` +
+  `monday update upload <update-id> <file>` ship the first multipart
+  wire surface (`add_file_to_column` / `add_file_to_update`). Both
+  surface `--dry-run` for a planned-change envelope preview without
+  the multipart round-trip. Uploads are non-idempotent (each
+  successful call mints a fresh `Asset` ID); cache invalidation
+  fires single-leg on success. Read-side `item assets` / `update
+  assets` verbs deferred to v0.4.x per M31 Decision D6.
+- **M32** — `monday doc list [--workspace <wid>,...] [--order-by
+  <created_at|used_at>] [--limit <n>] [--page <n>]` + `monday doc
+  get <did>` ship read-only access to Monday's workdocs surface
+  (`Query.docs(...)`). Page/limit pagination (no cursor on this
+  Monday surface). The full workdocs CRUD mutation surface (9
+  mutations: `create_doc` / `update_doc_name` / `delete_doc` /
+  `duplicate_doc` / `import_doc_from_html` / `add_content_to_doc_
+  from_markdown` / `create_doc_block` / `update_doc_block` /
+  `delete_doc_block`) is deferred to v0.5.
+- **M33** — `monday completion <bash|zsh|fish>` ships shell
+  completion script generation. The default mode emits raw script
+  bytes on stdout regardless of TTY/pipe context (so `monday
+  completion bash >> ~/.bashrc` works as a sourceable file —
+  cli-design §3.1 #2 raw-bytes carve-out); `--json` opts INTO the
+  §6 envelope with `data: { shell, script }`. Hand-rolled per-shell
+  templates (commander 14.0.3 ships no built-in completion
+  machinery, verified by empirical probe at M33 pre-flight).
+
+**v0.5 (next):** `team` writers (deferred from v0.4-M34 at the
+post-v0.4-M33 candidate-selection session), Monday workdocs CRUD
+mutation surface (9 mutations deferred at v0.4-M32 D8 closure),
+multi-level subitems remain conditional on Monday's data model
+surfacing them, cross-board `item move` value-overrides (slipped
+from v0.4 at v0.4 release-prep — Monday's `ColumnMappingInput`
+carries no value slot), and resumable cross-board cursor pagination
+(slipped from v0.4 — per-board cursor-lifetime under aggregation
+needs design work).
 
 See [`docs/cli-design.md`](./docs/cli-design.md) §13 for the
-full roadmap, [`docs/v0.3-plan.md`](./docs/v0.3-plan.md) for the
-v0.3 milestone history, and
-[`docs/v0.2-plan.md`](./docs/v0.2-plan.md) for the v0.2 milestone
-history.
+full roadmap, [`docs/v0.4-plan.md`](./docs/v0.4-plan.md) for the
+v0.4 milestone history, [`docs/v0.3-plan.md`](./docs/v0.3-plan.md)
+for v0.3, and [`docs/v0.2-plan.md`](./docs/v0.2-plan.md) for v0.2.
 
 See [CHANGELOG.md](./CHANGELOG.md) for the per-release contract.
 
@@ -513,7 +605,9 @@ The full dev workflow + how to add a new command is in
 - **No `any`** (lint-enforced).
 - **Parse at every boundary** with zod.
 - **Mock at the network boundary, not internal modules.**
-- **Branch coverage 95%+ floor** (v0.3 ratcheted from 94% — see
+- **Branch coverage 95.45% floor** for branches; 95% floor for
+  statements / functions / lines (v0.3-M22 ratcheted branches
+  from 94% via an OAuth coverage-push session — see
   `vitest.config.ts`).
 - **Atomic commits, Conventional Commits.**