monday-cli 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -3,10 +3,674 @@
 All notable changes to `monday-cli` are recorded here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning
 follows [SemVer](https://semver.org/spec/v2.0.0.html). The CLI's
-output envelope (`{ ok, data, meta, ... }`) and 27 stable error
+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 —
+v0.2's mutating core gains the Monday Dev convention layer (sprints /
+epics / releases / tasks), multi-profile auth, diagnostics
+(`monday status` / `monday usage`), cross-board search + favorites,
+per-item history, partial-success bulk updates, and outbound writes
+(webhooks + notifications). **No breaking changes vs `0.2.0` — every
+v0.3 surface is additive.** Built incrementally across M19–M28.
+
+### Breaking changes vs `0.2.0`
+
+**None.** Every command, error code, envelope key, and warning shape
+shipped in v0.2.0 is preserved byte-for-byte. v0.3 only adds.
+
+### Surface
+
+**~95 commands shipped (was ~75 in v0.2).** Four new noun-namespaces
+(`tag` reads under `account`, `auth`, `dev`, `webhook`,
+`notification`) plus two new top-level diagnostics verbs
+(`monday status` / `monday usage`).
+
+**Friendly-translator close-out (M19) — three new writable column
+types.** `tags`, `board_relation`, `dependency` graduate from the v0.2
+tentative row to first-class `--set` writers. The friendly tokens
+resolve through per-account / per-board directories with cache
+fallbacks. `WRITABLE_COLUMN_TYPES` reaches 13. M19 also ships
+`monday account tags` (the read verb that closes the
+`tag_not_found.details.hint` forward-reference from v0.2) and adds
+`tag_not_found` to the stable error-code registry.
+
+**Time-tracking placeholders (M20) — documentation-only.** `monday item
+time-track start <iid>` / `monday item time-track stop <iid>` are
+registered so agent scripts targeting these verbs are stable across
+the eventual swap when Monday ships API support. They reject every
+invocation today with `usage_error` carrying the empirical-probe
+context as the hint — an empirical probe (2026-05-10, API `2026-01`)
+confirmed Monday's public API does not currently support writing to
+`time_tracking` columns.
+
+**Multi-profile auth (M21).** `monday auth login --profile <name>` /
+`monday auth logout --profile <name>` implement the OAuth flow + the
+`~/.monday-cli/credentials` mode-`0600` cache; `~/.monday-cli/config.toml`
+ships per-profile metadata with the new `--profile <name>` global
+flag resolving through `cli/program.ts`'s preAction hook. `oauth_failed`
+joins the stable error-code registry. **OAuth login is deferred in
+v0.3.0** (see "Internals worth highlighting" → OAuth deferral); the
+`monday auth login` command surfaces a clear `usage_error` pointing
+agents at `MONDAY_API_TOKEN` until the canonical OAuth app is
+registered. The redaction runtime folds credentials-cache tokens into
+the secret-bag so the two-layer scrub covers them on every emission
+path.
+
+**Diagnostics cluster (M22).** `monday status` runs a seven-probe
+matrix (DNS / TCP / TLS / auth / cache writability / redaction
+self-test / env-var pickup) for "is everything working?" without
+touching account state; `--no-probe` skips the four network probes.
+`monday usage` reports the daily Monday API operation budget remaining
+from `platform_api.daily_limit` + `platform_api.daily_analytics`
+(operations-per-day on free tier; an empirical probe pivoted this
+away from `account.complexity`, which does not exist on the `Account`
+type at API `2026-01`).
+
+**Cross-board search + favorites (M23).** `monday item search` gains
+cross-board mode when `--board` is omitted: `--workspace <wid>` /
+`--favorites` / `--max-boards <n>` (default 25; hard cap 100) scope
+the fan-out. `monday board favorites` reads the current user's
+starred boards. Both fan-outs use single-call cross-board semantics
+(no resumable cross-board cursor in v0.3 — per-board cursor lifetime
+under cross-board aggregation is genuinely thorny; agents narrow with
+`--workspace` / `--favorites` or use the v0.1 `--board <bid>` path
+which carries its own resumable cursor). Four new load-bearing
+warnings: `inaccessible_boards`, `column_not_found_on_board`,
+`cross_board_truncated`, `board_favorites_stale`.
+
+**Per-item activity history (M24).** `monday item history <iid>`
+merges Monday's `boards.activity_logs(item_ids:)` with `items.updates`
+chronologically by `created_at` ascending (lexicographic `id` tie-
+break). Event taxonomy is a zod discriminated union over Monday's
+observed `event` slot (`update_column_value`, board-scoped variants,
+synthesized `update_posted` / `update_replied`); unrecognised events
+surface under `kind: 'unknown'` carrying raw `event` + `entity` slots,
+with one bounded `unknown_event_kind` warning per unique unrecognised
+event. Per-source pagination (`--activity-logs-page` /
+`--updates-page`; independent denominators) + `--since` / `--until`
+ISO8601 wall-clock filters + `--stream` NDJSON output reusing R52's
+`startNdjsonStream`. Eventual-consistency lag is empirically >30s on
+freshly-edited boards — the verb's `--help` text documents the
+caveat.
+
+**Partial-success bulk updates (M25).** `monday item update --where
+... --continue-on-error` attempts every matched item regardless of
+per-item failure and emits a partial-success envelope (cli-design
+§6.4): `ok: true` whenever dispatch ran, per-target outcomes in
+`data.results: [{ item_id, ok, error? }]`, with
+`data.summary.failed_count` joining the existing
+`matched_count`/`applied_count` invariant
+(`matched_count === applied_count + failed_count`). The flag is
+orthogonal to the `--yes` confirmation gate. ERROR_CODES registry
+stays at 29 — per-item failures route through existing codes
+(`column_archived`, `validation_failed`, `complexity_exceeded`, etc.).
+The pre-existing fail-fast bulk path is unchanged.
+
+**Monday Dev convention layer (M26).** Thirteen verbs land under the
+`monday dev` namespace — the workflow-namespace three-level carve-out
+(cli-design §5.2 carve-out 1; §5.9 mechanics). Three setup verbs at
+two-level depth: `dev discover [--apply]` (auto-detect Tasks /
+Sprints / Epics / Releases / Bugs boards by name), `dev configure
+--tasks-board <bid> [...]` (pin board IDs per profile), `dev doctor`
+(11-reason structured health-check enum surfaced via
+`monday schema dev.doctor`). Ten workflow verbs at three-level depth:
+`dev sprint current/list/items`, `dev epic list/items`, `dev release
+list`, `dev task list/start/done/block`. Every workflow verb
+translates to standard board / item CRUD against the per-profile
+configured board IDs — no new Monday GraphQL mutations introduced. Two
+new stable error codes activate (`dev_not_configured`,
+`dev_board_misconfigured`; reserved on the v0.1 registry, now live).
+
+**Outbound writes (M27).** Webhook lifecycle: `monday webhook list
+[--board <bid>]` / `webhook create --board <bid> --url <url> --event
+<type> [--config <json>]` (event-type validated against the 21-value
+`WEBHOOK_EVENT_TYPES` closed enum, probed against API `2026-01`) /
+`webhook delete <wid>` (destructive — `--yes` required;
+`enforceDestructiveGate` fires BEFORE the resolver per the M10
+invariant). Notifications: `monday notification send --user <uid>
+--target <id> --target-type item|board --text <body>` (single-
+recipient at v0.3). Webhooks are live-only — outside cli-design §8's
+cache scope. The CLI never receives — webhooks land on the user's own
+HTTPS endpoint (cli-design §1 permanent non-goal: hosting webhooks).
+ERROR_CODES registry unchanged.
+
+**Subitem multi-level creation — deferred out of v0.3 (M28).** Closed
+at M28 pre-flight on empirical grounds: an empirical probe
+(2026-05-13, API `2026-01`) confirmed Monday's `sub_items_board` does
+NOT carry a `subtasks` column at the pinned API version, so a depth-2
+subitem has structurally no place to live in the data model. Single-
+level subitems remain first-class via the existing M9 carve-in (`item
+create --parent <iid>`, `item subitems <iid>`, and every standard
+item verb operating uniformly on subitems). v0.3.x / v0.4 picks the
+feature up if Monday surfaces the capability.
+
+### Output contract additions
+
+**Two new stable error codes — registry grows from 27 to 29.**
+
+1. **`tag_not_found`** (M19) — `monday item set <iid> tags=<token>`
+   when the token doesn't resolve through the per-account tag
+   directory. `details.hint` points the agent at `monday account
+   tags` for discovery.
+2. **`oauth_failed`** (M21) — umbrella for OAuth-flow failures
+   (`monday auth login`). `details.reason` discriminates per failure
+   mode (`port_in_use`, `code_exchange_failed`, `state_mismatch`,
+   `redirect_invalid`, `oauth_unregistered` for the v0.3.0
+   placeholder-guard path, etc.) so agents key off the structured
+   reason rather than the umbrella code alone.
+
+The two `dev_*` codes reserved on the v0.1 registry
+(`dev_not_configured`, `dev_board_misconfigured`) activate at M26 —
+they were registry-stable but inactive in v0.1/v0.2.
+
+**Per-item history envelope shape** (M24). New under
+`docs/cli-design.md` §6 for the merged activity stream: event objects
+carry `created_at` (ISO), `actor_id`, `kind` (discriminator —
+`update_column_value` / `update_posted` / `update_replied` /
+board-scoped variants / `unknown`), `before`, `after` (typed where
+M24 ships the projector, raw JSON elsewhere — agents read `kind` and
+case on it).
+
+**Partial-success bulk envelope** (M25 — §6.4 sub-section).
+`data.summary.failed_count` joins the bulk-summary fields; per-item
+`data.results: [{ item_id, ok, error? }]`. The fail-fast bulk path
+(`details.applied_to` decoration on the error envelope) is unchanged
+— agents who haven't migrated to read `data.results[]` continue to
+receive the v0.1 envelope shape.
+
+**Cross-board search envelope** (M23 — additive on `item search`).
+The data shape is unchanged; the cross-board path adds per-board
+`state` breakdown inside `cross_board_truncated.details`
+(`exhausted` / `has_more` / `not_started`).
+
+**Four new warnings** (cross-board search + favorites):
+`inaccessible_boards`, `column_not_found_on_board`,
+`cross_board_truncated`, `board_favorites_stale`. Plus
+`unknown_event_kind` (item history). All warnings carry structured
+`details` agents can route on.
+
+### Upgrade notes
+
+- **`unsupported_column_type` `deferred_to: "v0.3"` resolves** for
+  the v0.2 tentative row (`tags`, `board_relation`, `dependency`
+  shipped at M19). The `--set-raw` escape hatch on these types
+  continues to work byte-identically; agents using the friendly form
+  pick it up automatically.
+- **Multi-level subitem creation slips to `deferred_to: "v0.4"`.**
+  M28 Decision 11 closure: Monday's `sub_items_board` carries no
+  `subtasks` column at API `2026-01`, so depth-2 subitems have no
+  data-model home. Agents that previously caught the v0.2.0
+  envelope's `deferred_to: "v0.3"` should update the comparison;
+  the `error.code: "usage_error"` + `details.hierarchy_type:
+  "multi_level"` keys are unchanged. Single-level subitems (`item
+  create --parent <iid>` against classic boards) continue to work
+  byte-identically.
+- **Cross-board `item move` value-overrides slip to v0.4.**
+  `--columns-mapping`'s string-to-string form is unchanged. The
+  richer `{id, value?}` form was originally v0.3-targeted at M11
+  close; no v0.3 milestone picked up the extension because
+  Monday's `ColumnMappingInput` carries no value slot. Agents
+  needing overrides continue to fire `monday item set <iid>
+  <target>=<value>` post-move.
+- **Stable error-code registry expanded from 27 to 29.** Existing
+  codes' shapes are unchanged.
+- **`--profile <name>` is a new global flag.** Resolved through
+  `cli/program.ts`'s preAction hook; profile precedence is documented
+  at `docs/cli-design.md` §7.4. Single-profile installs (the v0.2
+  shape) need no change — the implicit default profile preserves the
+  v0.2 behaviour.
+- **`monday auth login` placeholder-guard.** The verb is registered
+  but returns `usage_error.details.reason: oauth_unregistered`
+  pointing at `MONDAY_API_TOKEN` until the canonical Monday OAuth app
+  is registered. `monday auth logout` works against any locally
+  cached credentials. The deferral is documented at cli-design §7.3.
+
+### Internals worth highlighting
+
+- **OAuth deferral.** `OAUTH_CLIENT_ID` / `OAUTH_CLIENT_SECRET` ship
+  as `<UNREGISTERED_PENDING_OAUTH_APP>` placeholders in `src/api/oauth.ts`
+  at v0.3.0. The full M21 OAuth source + test infrastructure stays as
+  dormant infrastructure (the `__test_oauth_helper` seam keeps the
+  M21 round-trip tests green). Whether a canonical `monday-cli`
+  OAuth app gets registered at v0.3.x / v0.4 is a separate product
+  decision — the CLI works fully with API tokens today, which is the
+  shape every agent harness already consumes. If registration lands,
+  the swap is one-sided in `src/api/oauth.ts` and the placeholder
+  guard drops in one edit.
+
+- **R-class refactors shipped during v0.3.** R-NEW-1 (`isENOENT`
+  lift), R-NEW-4 (`statusOutputSchema` / `probeResultSchema`
+  import-from-api lift), R-NEW-5 (`introspectType()` probe helper),
+  R-NEW-6 (`.claude/templates/codex-pre-flight-review.md` template
+  lift after M21 + M22 + M23 converged on the same prompt shape),
+  R-NEW-7 (`formatMode` lift), R-NEW-14 / R-NEW-15 / R-NEW-16
+  (`errorMessage` / `asError` / `errorCode` consolidation across 17
+  inline duplicates), R-NEW-17 (W1 redactor-pattern audit folded
+  template-stable), R-NEW-19 (manual `safeParse → ApiError` sites
+  migrated to `unwrapOrThrow`), R-NEW-21 (`trialQuery()` /
+  `ProbeRawErrors` probe lift), R-NEW-25 (W1's "findings up front"
+  Codex-prompt directive), R-NEW-27 (`isPlainObject`
+  consolidation), R-NEW-29 (`executeItemMutation` lift —
+  three-consumer trigger across single-item + fail-fast bulk + M25
+  partial-success bulk), R-NEW-30 (`resolveActiveDevProfile` —
+  13-consumer trigger across M26a + M26b), R-NEW-35
+  (`requireDevBoard` slot-check helper), R-NEW-36 (seven dev-conventions
+  workflow helpers), R-NEW-37 (Codex template W2 audit-point for
+  GraphQL operationName parity — caught the M27 IMPL caller-
+  overridable operationName slot), R-NEW-38 (sprint date-range
+  helpers consolidation), R-NEW-42 (`parseJsonArg` argv-JSON-parse-
+  boundary helper). Full register with shipped commit SHAs lives in
+  [`docs/v0.3-plan.md`](./docs/v0.3-plan.md) §22.
+
+- **Empirical probes** ratified as always-run-for-novel-API-surface
+  pre-flight discipline. v0.3 fired the pattern across M21 OAuth /
+  M22 `platform_api.daily_*` reshape / M23 cross-board + favorites /
+  M24 history kinds / M26 dev-board discovery / M27 webhook
+  event-type enum / M28 multi-level subitems. Multiple milestones
+  pivoted contract surfaces at pre-flight on probe findings rather
+  than discovering API drift at IMPL.
+
+- **Two-AI review** (cli-design pre-flight + implementation review)
+  ran for every milestone M19–M27. Catches contract drift before
+  it reaches `main`; the cumulative finding count + per-milestone
+  Codex-round breakdown is in the per-milestone post-mortems in
+  [`docs/v0.3-plan.md`](./docs/v0.3-plan.md) §11–§20.
+
+### Tests + quality gates
+
+- **3249 unit/integration + E2E tests** at v0.3.0 (+1 skipped; was
+  2280+38 ≈ 2318 in v0.2.0). All green on Node 22 + 24.
+- **Coverage at 99.26 / 96.40 / 99.37 / 99.51** (statements /
+  branches / functions / lines) against the floor 95 / 95.45 / 95
+  / 95. The branches floor was raised at M22 (94% → 95.45%) and
+  held through M28; the M28 close-out shipped six branch-coverage
+  residual tests closing the three deferred file-level gaps
+  (`item/search.ts` 88.23% → 100% stmts; `errors.ts` 95.37% → 100%
+  lines; `dry-run.ts` 96.26% → 100% branches). Branches margin is
+  0.95pp at v0.3.0.
+- **Envelope-snapshot suite refreshed** for v0.3 surfaces — every
+  new v0.3 command + the partial-success / history / cross-board /
+  dev / webhook / notification envelopes are pinned for byte-shape
+  regressions.
+- **Five test layers** held: unit, integration (in-process
+  `FixtureTransport`), E2E (subprocess against fixture server),
+  envelope-shape snapshot suite, published-tarball E2E.
+
+### Documentation
+
+- **[`docs/v0.3-plan.md`](./docs/v0.3-plan.md)** new — the v0.3
+  active plan with M19–M28 milestones, decisions log, R-class
+  register (R-NEW-1 through R-NEW-43), per-milestone post-mortems
+  (§11–§21).
+- **[`docs/cli-design.md`](./docs/cli-design.md)** §4.3 grew ~25 new
+  verb entries; §6.4 added the M25 bulk partial-success sub-section;
+  §6.5 added two new error codes; §7.3 added the OAuth deferral
+  block; §7.4 added the multi-profile resolution surface; §11.5
+  added the seven-probe `monday status` matrix; §13 v0.3 entry
+  closed out.
+- **[`docs/output-shapes.md`](./docs/output-shapes.md)** — every
+  shipped v0.3 command has a per-section data shape entry, snapshot-
+  backed.
+- **README.md** quickstart expanded with v0.3 examples (`monday
+  status`, `monday dev sprint current`, `monday webhook list`).
+
+[0.3.0]: https://github.com/Firer/monday-cli/releases/tag/v0.3.0
+
 ## [0.2.0] - 2026-05-08 — Mutating core: agents can drive a backlog
 
 The "agents can drive a backlog" milestone — v0.1's read-only core
@@ -215,7 +879,7 @@ once and skip subsequent metadata lookups.
 
 [0.2.0]: https://github.com/Firer/monday-cli/releases/tag/v0.2.0
 
-## [0.1.0] — Initial release
+## [0.1.0] — Foundation milestone (git tag — npm publish slipped to 0.2.0)
 
 The "read-only core + safe mutations" milestone — an agent can read
 everything the CLI surfaces, make small scoped idempotent changes,
@@ -223,6 +887,15 @@ and post comments narrating its work. Built incrementally across
 M0–M7 (M5 split into M5a + M5b; M2.5 inserted post-M2 as a
 structural-debt cleanup pass).
 
+> **Publication note**: 0.1.0 shipped to `main` as a tagged git
+> release but was not published to npm. The first public npm
+> release of `monday-cli` is **0.2.0** (which contains the full
+> v0.1 surface as its foundation — nothing in 0.1.0 was lost or
+> rolled back). The `monday-cli` npm namespace had a brief
+> pre-history (`monday-cli@0.0.1`, published and unpublished
+> within hours on 2026-01-12) before being claimed for this
+> project at the v0.2.0 release.
+
 ### Surface
 
 **Five reader nouns + 35 commands shipped.**