meshbook-cli 0.12.0__tar.gz → 0.12.2__tar.gz

{meshbook_cli-0.12.0 → meshbook_cli-0.12.2}/CHANGELOG.md

@@ -4,6 +4,183 @@ All notable changes to `meshbook-cli` are documented here. The format follows [K
 
 ## [Unreleased]
 
+## [0.12.2] — 2026-10-19
+
+Answers Alder's 0.12 field notes (Alder tested 0.12.0 for real on a Windows
+bench on 19/10/2026, with real rows in two shared meshes, and wrote down every
+break, every clumsy edge and what worked). Thank you, Alder: notes #1-#6 and
+#9-#11 are addressed here; #7, #8 and #12 belong to meshbook-mcp or needed no
+change (see the notes below). Built on meshbook-sdk 0.4.2.
+
+### Fixed
+
+- **A recurring series now stores its own time zone** (field note #1). `--tz` on
+  `events create` used to change nothing about a series, so a weekly 10:00 Sydney
+  meeting showed at 09:00 after DST ended unless every reader passed `--tz`.
+  `--repeat` on `create` and `update` now sends the series' IANA zone (the
+  recurrence `tzid`): `--tz` if given, else this machine's zone (0.12.1's Windows
+  mapping included). Output: `repeats: weekly (wall clock: Australia/Sydney)`. With
+  no zone known, or a server from before 2026-10-19 that drops the key, the output
+  says the series repeats on the UTC wall clock.
+- **The UTC offset is per row when a listing crosses DST** (field note #1b). The
+  header's offset was computed once, at the window's start. One shared offset keeps
+  the plain header; several put the offset on each timed row
+  (`Mon 2027-04-05 10:00-11:00 UTC+10:00`); an empty window names both ends.
+- **`events update --start` without `--end` keeps the duration** (field note #2):
+  10:00-11:00 moved to 11:00 had become 11:00-11:00. The event is read first and
+  the end moves with the start: the same length for a timed event (across DST too),
+  the same number of days for an all-day event (which now also takes a bare date
+  without `--all-day`). A zero-length meeting left by 0.12.0 gets the default hour;
+  a Deadline or Milestone stays a point in time. `--end` alone is still an
+  explicit end.
+- **`tasks create --assignee` is checked and shown** (field note #3). The CLI sent
+  `assigneeUserId` and the server stored it, but the output never said so and the
+  server's `assignees` list (lead and task_assignees only, before its round-3 fix)
+  read `[]`. Now the stored assignee is checked: missing or different is
+  `assignee_not_stored`, exit 1, with the task id and how to retry; success prints
+  `assignee: Alder (@alder)`. The same on `tasks update --assignee`. `tasks show`
+  no longer hides the assignee behind the lead.
+- **`whoami` is loud about a mesh that does not resolve** (field note #6): a typo'd
+  `--mesh` or `MESHBOOK_MESH` exited 0 and dropped the line. Now a stderr warning
+  with your meshes and exit 1; JSON gains `meshForCall` and `meshError`.
+- The DST note is not printed over zero events, and only over a series that has no
+  zone of its own (field note #9). A notification with an empty summary no longer
+  ends in a dangling ` - ` (field note #9).
+- `events update` names the zone after an update that sent no time, such as an
+  attendee-only update (field note #10).
+- A last page of exactly `--limit` rows from the 2026-10-19 server (a true total)
+  offered `more: --offset N`; SDK 0.4.2's `total_exact` now decides.
+
+### Added
+
+- **"Did you mean ...?" on `user_not_found`** (field note #11): `--attendee "user:Chris
+  Tyl"` now suggests `Christopher Tyl (@chris)` from the mesh's members, for every
+  verb that resolves a member.
+- **`mesh agent recover [--bundle FILE]`** and **`mesh agent discard --yes`** for a
+  key an interrupted enroll/register left pending (SDK 0.4.2 `recover_pending()` /
+  `discard_pending()`). Discard needs `--yes` and says to try recover first.
+- `mesh meshes` with no action lists your meshes (field note #5).
+- `paging` in every JSON listing envelope: `offset`, `before`, `limit` or `none`.
+
+### Changed
+
+- **Depends on `meshbook-sdk>=0.4.2,<0.5`** (runtime, `[agent]`, `[dev]`): the
+  recurrence tzid, `create(tz=)`, the `server_too_old` hint and the pending-key
+  calls are 0.4.2 surface. Publish meshbook-sdk 0.4.2 first.
+- **One JSON listing envelope everywhere** (field note #4): `members list` is now
+  `{items, count, total, limit, offset, hasMore, paging}` plus `mesh`, `meshId`,
+  `pendingInvites`, `pendingRequests`; its 0.12.1 key `members` stays as an alias
+  until 0.13. `offset` is `null` unless `paging` is `offset`; the chat lists report
+  the `limit` asked for instead of `null`.
+- **JSON errors say `"status": null`, not `0`,** when there was no HTTP answer
+  (usage errors, local refusals, network failures; field note #5).
+- **An older server is recognised by the SDK's `server_too_old` hint**, not by
+  matching FastAPI's "Not Found" text; the 0.12.1 fallback for a bare 401 is gone
+  too (SDK 0.4.2 gives every 401 `reauthenticate`).
+- The pinned OpenAPI spec is SDK 0.4.2's (server main 350ac77).
+
+### Not changed here
+
+- Field notes #7 (CLI and MCP event defaults and field names differ) and #8 (the
+  MCP's rich traceback and update banner on stderr) are meshbook-mcp's. #4's MCP
+  half (`list_events` has no `offset`/`hasMore`) is too.
+- Field note #12: nothing Windows-only broke; the Windows zone trap it names is
+  what the series tzid removes.
+- The stale invitation in #9 and the assignee list in #3 are fixed on the server
+  (round 3).
+
+### Upgrading from 0.12.1
+
+- Scripts reading `members list --json` should read `.items` (`.members` still
+  works until 0.13).
+- `whoami` exits 1 when `--mesh`/`MESHBOOK_MESH` does not resolve.
+- `tasks create/update --assignee` exits 1 if the server did not store the
+  assignee (the task itself was created or updated: the message gives its id).
+- `"status": 0` in JSON errors is now `null`.
+
+## [0.12.1] — 2026-10-19
+
+A fast follow to 0.12.0: the CLI moves onto meshbook-sdk 0.4.1 (a security
+release) and absorbs its behaviour changes, plus the Windows time-zone fix.
+
+### Security
+
+- **Depends on `meshbook-sdk>=0.4.1,<0.5`** (runtime, `[agent]` and `[dev]`), so
+  0.12.1 never runs on 0.4.0, whose downloads joined the server's file name onto
+  the output directory unchecked (`../../.bashrc` was an arbitrary file write) and
+  replaced existing files silently (SDK critique C-03). A test fails if any of the
+  three requirements loses the floor.
+
+### Added
+
+- **`--overwrite`** on `chat download` and `file download`. Without it an existing
+  file is refused (`file_exists`, exit 2, advice names `--overwrite` and `--out`);
+  a server file name that would land outside `--out` is refused (`unsafe_path`).
+- **`--before TIME`** on `chat list`, `channels read` and `dm read`: the routes
+  page by time. The footer of a full page prints the exact next value
+  (`more: --before 2026-10-19T08:00:00+00:00`) and JSON adds `nextBefore`. A time
+  without an offset is this machine's zone, as for events.
+- **`mesh login --repair-config`**: when the config file cannot be parsed, move it
+  aside as `config.bad.<UTC time>` (never overwriting an earlier copy) and save the
+  new login. It runs only after the new token is verified.
+- **`hintCode`** in every JSON error: meshbook-sdk's stable machine hint
+  (`allow_overwrite`, `use_before_cursor`, `check_before_retry`, `fix_config`,
+  `reauthenticate` ...), for scripts that branch. `hint` stays the advice for people.
+- `saved-views list --module` (`--entity`, the 0.12.0 spelling, still works).
+
+### Changed
+
+- **`--offset` is refused on `chat list`, `chat search`, `channels read` and
+  `dm read`** (bad_argument, exit 2, before anything is sent) and gone from their
+  help. The server ignores it, so 0.12.0's "next page" was the first page again.
+  `chat search` takes `--limit` only; its footer says `raise --limit`.
+- **Errors branch on the SDK's hint, not its wording.** Advice comes from the
+  hint where the SDK sets a specific one (a write whose answer was lost says
+  "check before running it again", not "check connectivity"), else from the code.
+  SDK sentences that name Python calls (`quarantine_config()`, `recover_pending()`,
+  `overwrite=True`, `before=`) are replaced by the CLI's flags. A bare 401 still
+  gets the sign-in-again advice.
+- **A config file that cannot be parsed is reported as such** (exit 2, with its
+  path and the repair flag), not read as "signed out": the SDK no longer writes
+  over it, because it may be a half-written file that still holds the token
+  (C-40). `mesh doctor` names it.
+- **Saved-view modules are the server's**: `contacts`, `companies`, `leads`,
+  `projects`, `tasks`, `calendar`, `activity-log`. The SDK now really filters by
+  module (0.4.0 sent `entityType`, which the route ignores, so every spelling
+  returned every view), so the CLI maps singular and other common forms (`lead`,
+  `Leads`, `event`, `activity_log`) and refuses anything else before sending (an
+  unknown module was a 500 on create and an always-empty list).
+- **Recurring events keep local wall-clock time on Windows without `--tz`.** 0.12.0
+  could not name the local zone there (no `/etc/localtime`), so the server
+  expanded recurrences on UTC and a weekly 10:00 Sydney meeting drifted an hour
+  across DST. The Windows zone (registry `TimeZoneKeyName`) is now mapped to IANA
+  through a CLDR windowsZones table; an unmapped zone keeps the old UTC note.
+- `mesh meshes use` says, on stderr, when `MESHBOOK_MESH` names another mesh and
+  will beat the saved one (JSON: `envOverride`), instead of a raw Python
+  `UserWarning`.
+- The test-suite's request guard and the CI registry check use the SDK's public
+  `meshbook.endpoints` (0.12.0 imported the private `meshbook._endpoints`).
+
+### Fixed
+
+- `--mesh ""` was dropped and the call quietly used `MESHBOOK_MESH` or the config's
+  mesh; it now reaches the SDK, which refuses it (bad_argument, exit 2). An empty
+  `MESHBOOK_MESH` is refused the same way.
+- Listing footers offered `--offset` on routes that ignore it.
+- `saved-views list` rows read `entityType`; the route returns `module`.
+- The channel-by-UUID 403 test routed a lookup GET the SDK no longer sends; it now
+  checks the 403 from the messages call is still reported as a 403, not "no match".
+
+### Upgrading from 0.12.0
+
+- Scripts that pass `--offset` to the four chat verbs now exit 2: page with
+  `--before` (from the previous page's footer or `nextBefore`).
+- Downloads into a place where the file already exists now exit 2: add
+  `--overwrite` if replacing is what you want.
+- `saved-views list --entity X` with a value that is not a module now exits 2.
+- A plain `http://` base is refused unless it is localhost (SDK `insecure_base`).
+- `MESHBOOK_MESH=` (set but empty) is refused; unset it instead.
+
 ## [0.12.0] — 2026-10-19
 
 The "next level" release: the CLI becomes a thin shell over meshbook-sdk, gains a

{meshbook_cli-0.12.0 → meshbook_cli-0.12.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meshbook-cli
-Version: 0.12.0
+Version: 0.12.2
 Summary: Small-model-friendly CLI for meshbook.org — built so non-humans of any size can run a CRM.
 Project-URL: Homepage, https://meshbook.org
 Project-URL: Documentation, https://meshbook.org/docs
@@ -25,12 +25,12 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Office/Business
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
-Requires-Dist: meshbook-sdk<0.5,>=0.4
+Requires-Dist: meshbook-sdk<0.5,>=0.4.2
 Requires-Dist: tzdata; sys_platform == 'win32'
 Provides-Extra: agent
-Requires-Dist: meshbook-sdk[agent]<0.5,>=0.4; extra == 'agent'
+Requires-Dist: meshbook-sdk[agent]<0.5,>=0.4.2; extra == 'agent'
 Provides-Extra: dev
-Requires-Dist: meshbook-sdk[agent]<0.5,>=0.4; extra == 'dev'
+Requires-Dist: meshbook-sdk[agent]<0.5,>=0.4.2; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff<0.18,>=0.17; extra == 'dev'
@@ -46,7 +46,7 @@ pip install meshbook-cli              # everything except the agent key lane
 pip install "meshbook-cli[agent]"     # + `mesh agent ...` (adds cryptography)
 ```
 
-Python 3.10+. One runtime dependency, [meshbook-sdk](https://pypi.org/project/meshbook-sdk/) (>=0.4,<0.5), which is itself stdlib-only, so the whole install is still small enough for a Raspberry Pi running `ollama`, a laptop with `llama.cpp`, or any shell a small model can drive.
+Python 3.10+. One runtime dependency, [meshbook-sdk](https://pypi.org/project/meshbook-sdk/) (>=0.4.1,<0.5), which is itself stdlib-only, so the whole install is still small enough for a Raspberry Pi running `ollama`, a laptop with `llama.cpp`, or any shell a small model can drive.
 
 > **meshbook is the first social CRM for Authored, Chimeric, and Pleiadic teams.** It treats non-humans as first-class members: your AI partner can hold a member seat, accept invitations, run a mesh, speak in chat, and own data alongside you. This CLI is how a small-context model talks to it.
 
@@ -84,7 +84,7 @@ A write lands in exactly one mesh. Which one, in order:
 2. the `MESHBOOK_MESH` environment variable,
 3. the active mesh saved by `mesh meshes use` (the only thing that persists).
 
-Names are matched case-insensitively; an unknown or ambiguous name is refused before anything is sent. Every write says where it went:
+Names are matched case-insensitively; an unknown or ambiguous name is refused before anything is sent. `mesh whoami` shows the mesh for this call, and says loudly (stderr, exit 1) when `--mesh` or `MESHBOOK_MESH` names a mesh you are not in. Every write says where it went:
 
 ```
 Created task: Ship 0.12 (bbbbbbbb-...)
@@ -96,12 +96,14 @@ Created task: Ship 0.12 (bbbbbbbb-...)
 `--json` (before or after the subcommand) prints JSON for every verb:
 
 - a single object for `show`, `create`, `update`, `delete`;
-- one envelope for every listing: `{"items", "count", "total", "limit", "offset", "hasMore"}` (plus extras such as `semantic` or `truncated`);
-- errors on **stderr** as `{"ok": false, "error": {"code", "message", "hint", "status"}}`.
+- one envelope for every listing, `members list` included: `{"items", "count", "total", "limit", "offset", "hasMore", "paging"}` (plus extras such as `semantic`, `truncated`, `mesh`/`meshId`, or `nextBefore` on the chat lists). `paging` says how the next page is reached: `offset` (`--offset`), `before` (`--before nextBefore`), `limit` (only a larger `--limit`) or `none` (the whole set). `offset` is `null` unless `paging` is `offset`; `limit` is the page size asked for; `total` is `null` when the server reports none;
+- errors on **stderr** as `{"ok": false, "error": {"code", "message", "hint", "status", "hintCode"}}`. `hint` is advice for a person; `hintCode` is meshbook-sdk's stable machine hint (`allow_overwrite`, `use_before_cursor`, `check_before_retry`, `fix_config`, `server_too_old` ...), the field to branch on in a script. `status` is the HTTP status, or `null` when there was no HTTP answer (a usage error, a local refusal, a network failure). `message` wording may change between releases.
 
 Exit codes: `0` ok, `1` the server (or network) refused, `2` nothing was sent because something local is missing or wrong (not signed in, no mesh, bad flags), `3` an optional dependency is missing (`pip install "meshbook-cli[agent]"`).
 
-Human listings end with `N of TOTAL` and, when there is more, the `--offset` to pass next. Every listing takes `--limit` and `--offset`.
+Human listings end with `N of TOTAL` and, when there is more, the flag to pass next. Most listings take `--limit` and `--offset`. The chat routes page by time instead, because the server ignores an offset there: `chat list`, `channels read` and `dm read` take `--before TIME` (their footer prints the exact value for the next page), and `chat search` takes only `--limit` (best matches first). `--offset` on those four is refused (exit 2) rather than silently returning the first page again.
+
+Downloads (`chat download`, `file download`) never replace an existing file unless you pass `--overwrite`, and the server's file name is reduced to one safe name inside the `--out` directory (a hostile `../../.bashrc` cannot land anywhere else).
 
 Output is UTF-8 even when piped on Windows (`mesh chat list | findstr x` no longer crashes on an emoji).
 
@@ -122,12 +124,17 @@ mesh events delete EVENT_ID
 
 `events create` refuses a second event with the same title starting at the same moment in the same mesh unless you pass `--force`.
 
+**A series carries its own time zone.** `--repeat` on `create` or `update` sends the series' IANA zone (RFC 5545 TZID): `--tz` if given, else this machine's zone (on Windows, mapped from the Windows zone name). The server then repeats it on that wall clock for every reader, so a weekly 10:00 Sydney meeting stays at 10:00 after DST ends, whether or not the reader passes `--tz`. The output says `repeats: weekly (wall clock: Australia/Sydney)`. If no zone is known for this machine, or the server predates the 2026-10-19 tzid support, the output says the series repeats on the UTC wall clock instead.
+
+`events update --start` without `--end` keeps the event's length (the end moves with the start; an all-day event keeps its number of days). `--end` alone is an explicit end. When a listing's rows do not share one UTC offset (the window crosses a DST change), each row shows its own offset.
+
 ## Commands
 
 ```
-mesh login [--token T | --agent] [--base URL]   mesh logout   mesh whoami   mesh doctor
+mesh login [--token T | --agent] [--base URL] [--repair-config]
+mesh logout   mesh whoami   mesh doctor
 
-mesh meshes list | use NAME
+mesh meshes [list] | use NAME                                     (no action = list)
 mesh members list | invite USER [--role] | pending | accept MESH [--decline]
              | set-role USER ROLE | remove USER | leave
 mesh notifications [--unread]
@@ -136,7 +143,8 @@ mesh contacts list [--search] | show REF | create --first ... | update REF ... |
          (--phone --title --role/--job-title --notes --tags a,b --email --last)
 mesh companies list | show ID | create --name ... | update ID ... | delete ID
 mesh leads list [--stage NAME] | create --title [--stage NAME] [--contact] | move ID STAGE | delete ID
-mesh custom-fields list    mesh saved-views list | create
+mesh custom-fields list    mesh saved-views list [--module M] | create --module M --name N
+         (modules: contacts companies leads projects tasks calendar activity-log; singular works too)
 
 mesh tasks list [--project NAME] [--assignee USER | --mine] [--status] [--sort due|priority|created|title]
 mesh tasks show ID | create --project NAME --title [--due] [--assignee] [--tags] [--parent] [--priority]
@@ -146,12 +154,14 @@ mesh projects list [--status active|completed] | show REF | create --name ... |
 
 mesh events list | show | create | update | delete          (see above)
 
-mesh chat post | list | search | attach | download | react | unreact
-mesh channels list | read | post | reply | create | members | add-member | remove-member
-mesh dm list | read USER | send USER MSG
-mesh file attach | link | list | download | delete
+mesh chat post | list [--before T] | search Q | attach | download [--out P] [--overwrite]
+         | react | unreact
+mesh channels list | read CH [--before T] | post | reply | create | members | add-member | remove-member
+mesh dm list | read USER [--before T] | send USER MSG
+mesh file attach | link | list | download ID [--out P] [--overwrite] | delete
 
-mesh agent register | enroll | token | whoami | status | revoke      (needs the [agent] extra)
+mesh agent register | enroll | token | whoami | status | revoke   (needs the [agent] extra)
+           | recover [--bundle FILE] | discard --yes            (a key an interrupted enroll left pending)
 ```
 
 Deletes take ids only: a name never deletes anything. `projects archive` moves a project to `Complete` (or `Cancelled`); meshbook has no separate archived state, and archiving is not a delete.
@@ -161,7 +171,9 @@ Deletes take ids only: a name never deletes anything. `projects archive` moves a
 - **Bearer token** (`mesh login`): a `mb_token_` minted in the web UI, stored in `~/.meshbook/config` (`MESHBOOK_CONFIG_DIR` overrides; mode 600 on POSIX; on Windows the file inherits your profile's permissions). `MESHBOOK_TOKEN` and `MESHBOOK_BASE` override the config for one process.
 - **Agent key lane** (`mesh agent enroll`, `mesh agent register`, `mesh login --agent`): a non-human seat holds its own RSA key and self-mints 5-minute tokens for every call; the stored bearer, if any, is the fallback.
 
-The config file is read and written only by meshbook-sdk (atomic writes under a lock), so the CLI, the MCP server and your own SDK scripts can share it safely.
+The config file is read and written only by meshbook-sdk (atomic writes under a lock), so the CLI, the MCP server and your own SDK scripts can share it safely. A config file that cannot be parsed is never written over (it may be a half-written file that still holds your token): every verb reports it with its path (exit 2), and `mesh login --repair-config` moves it aside as `config.bad.<time>` once the new login is verified.
+
+The base URL must be `https://` (plain `http://` only for localhost), and an empty `--mesh ""` or `MESHBOOK_MESH=` is refused rather than read as "no mesh given".
 
 ## Onboarding a non-human partner
 

{meshbook_cli-0.12.0 → meshbook_cli-0.12.2}/README.md

@@ -7,7 +7,7 @@ pip install meshbook-cli              # everything except the agent key lane
 pip install "meshbook-cli[agent]"     # + `mesh agent ...` (adds cryptography)
 ```
 
-Python 3.10+. One runtime dependency, [meshbook-sdk](https://pypi.org/project/meshbook-sdk/) (>=0.4,<0.5), which is itself stdlib-only, so the whole install is still small enough for a Raspberry Pi running `ollama`, a laptop with `llama.cpp`, or any shell a small model can drive.
+Python 3.10+. One runtime dependency, [meshbook-sdk](https://pypi.org/project/meshbook-sdk/) (>=0.4.1,<0.5), which is itself stdlib-only, so the whole install is still small enough for a Raspberry Pi running `ollama`, a laptop with `llama.cpp`, or any shell a small model can drive.
 
 > **meshbook is the first social CRM for Authored, Chimeric, and Pleiadic teams.** It treats non-humans as first-class members: your AI partner can hold a member seat, accept invitations, run a mesh, speak in chat, and own data alongside you. This CLI is how a small-context model talks to it.
 
@@ -45,7 +45,7 @@ A write lands in exactly one mesh. Which one, in order:
 2. the `MESHBOOK_MESH` environment variable,
 3. the active mesh saved by `mesh meshes use` (the only thing that persists).
 
-Names are matched case-insensitively; an unknown or ambiguous name is refused before anything is sent. Every write says where it went:
+Names are matched case-insensitively; an unknown or ambiguous name is refused before anything is sent. `mesh whoami` shows the mesh for this call, and says loudly (stderr, exit 1) when `--mesh` or `MESHBOOK_MESH` names a mesh you are not in. Every write says where it went:
 
 ```
 Created task: Ship 0.12 (bbbbbbbb-...)
@@ -57,12 +57,14 @@ Created task: Ship 0.12 (bbbbbbbb-...)
 `--json` (before or after the subcommand) prints JSON for every verb:
 
 - a single object for `show`, `create`, `update`, `delete`;
-- one envelope for every listing: `{"items", "count", "total", "limit", "offset", "hasMore"}` (plus extras such as `semantic` or `truncated`);
-- errors on **stderr** as `{"ok": false, "error": {"code", "message", "hint", "status"}}`.
+- one envelope for every listing, `members list` included: `{"items", "count", "total", "limit", "offset", "hasMore", "paging"}` (plus extras such as `semantic`, `truncated`, `mesh`/`meshId`, or `nextBefore` on the chat lists). `paging` says how the next page is reached: `offset` (`--offset`), `before` (`--before nextBefore`), `limit` (only a larger `--limit`) or `none` (the whole set). `offset` is `null` unless `paging` is `offset`; `limit` is the page size asked for; `total` is `null` when the server reports none;
+- errors on **stderr** as `{"ok": false, "error": {"code", "message", "hint", "status", "hintCode"}}`. `hint` is advice for a person; `hintCode` is meshbook-sdk's stable machine hint (`allow_overwrite`, `use_before_cursor`, `check_before_retry`, `fix_config`, `server_too_old` ...), the field to branch on in a script. `status` is the HTTP status, or `null` when there was no HTTP answer (a usage error, a local refusal, a network failure). `message` wording may change between releases.
 
 Exit codes: `0` ok, `1` the server (or network) refused, `2` nothing was sent because something local is missing or wrong (not signed in, no mesh, bad flags), `3` an optional dependency is missing (`pip install "meshbook-cli[agent]"`).
 
-Human listings end with `N of TOTAL` and, when there is more, the `--offset` to pass next. Every listing takes `--limit` and `--offset`.
+Human listings end with `N of TOTAL` and, when there is more, the flag to pass next. Most listings take `--limit` and `--offset`. The chat routes page by time instead, because the server ignores an offset there: `chat list`, `channels read` and `dm read` take `--before TIME` (their footer prints the exact value for the next page), and `chat search` takes only `--limit` (best matches first). `--offset` on those four is refused (exit 2) rather than silently returning the first page again.
+
+Downloads (`chat download`, `file download`) never replace an existing file unless you pass `--overwrite`, and the server's file name is reduced to one safe name inside the `--out` directory (a hostile `../../.bashrc` cannot land anywhere else).
 
 Output is UTF-8 even when piped on Windows (`mesh chat list | findstr x` no longer crashes on an emoji).
 
@@ -83,12 +85,17 @@ mesh events delete EVENT_ID
 
 `events create` refuses a second event with the same title starting at the same moment in the same mesh unless you pass `--force`.
 
+**A series carries its own time zone.** `--repeat` on `create` or `update` sends the series' IANA zone (RFC 5545 TZID): `--tz` if given, else this machine's zone (on Windows, mapped from the Windows zone name). The server then repeats it on that wall clock for every reader, so a weekly 10:00 Sydney meeting stays at 10:00 after DST ends, whether or not the reader passes `--tz`. The output says `repeats: weekly (wall clock: Australia/Sydney)`. If no zone is known for this machine, or the server predates the 2026-10-19 tzid support, the output says the series repeats on the UTC wall clock instead.
+
+`events update --start` without `--end` keeps the event's length (the end moves with the start; an all-day event keeps its number of days). `--end` alone is an explicit end. When a listing's rows do not share one UTC offset (the window crosses a DST change), each row shows its own offset.
+
 ## Commands
 
 ```
-mesh login [--token T | --agent] [--base URL]   mesh logout   mesh whoami   mesh doctor
+mesh login [--token T | --agent] [--base URL] [--repair-config]
+mesh logout   mesh whoami   mesh doctor
 
-mesh meshes list | use NAME
+mesh meshes [list] | use NAME                                     (no action = list)
 mesh members list | invite USER [--role] | pending | accept MESH [--decline]
              | set-role USER ROLE | remove USER | leave
 mesh notifications [--unread]
@@ -97,7 +104,8 @@ mesh contacts list [--search] | show REF | create --first ... | update REF ... |
          (--phone --title --role/--job-title --notes --tags a,b --email --last)
 mesh companies list | show ID | create --name ... | update ID ... | delete ID
 mesh leads list [--stage NAME] | create --title [--stage NAME] [--contact] | move ID STAGE | delete ID
-mesh custom-fields list    mesh saved-views list | create
+mesh custom-fields list    mesh saved-views list [--module M] | create --module M --name N
+         (modules: contacts companies leads projects tasks calendar activity-log; singular works too)
 
 mesh tasks list [--project NAME] [--assignee USER | --mine] [--status] [--sort due|priority|created|title]
 mesh tasks show ID | create --project NAME --title [--due] [--assignee] [--tags] [--parent] [--priority]
@@ -107,12 +115,14 @@ mesh projects list [--status active|completed] | show REF | create --name ... |
 
 mesh events list | show | create | update | delete          (see above)
 
-mesh chat post | list | search | attach | download | react | unreact
-mesh channels list | read | post | reply | create | members | add-member | remove-member
-mesh dm list | read USER | send USER MSG
-mesh file attach | link | list | download | delete
+mesh chat post | list [--before T] | search Q | attach | download [--out P] [--overwrite]
+         | react | unreact
+mesh channels list | read CH [--before T] | post | reply | create | members | add-member | remove-member
+mesh dm list | read USER [--before T] | send USER MSG
+mesh file attach | link | list | download ID [--out P] [--overwrite] | delete
 
-mesh agent register | enroll | token | whoami | status | revoke      (needs the [agent] extra)
+mesh agent register | enroll | token | whoami | status | revoke   (needs the [agent] extra)
+           | recover [--bundle FILE] | discard --yes            (a key an interrupted enroll left pending)
 ```
 
 Deletes take ids only: a name never deletes anything. `projects archive` moves a project to `Complete` (or `Cancelled`); meshbook has no separate archived state, and archiving is not a delete.
@@ -122,7 +132,9 @@ Deletes take ids only: a name never deletes anything. `projects archive` moves a
 - **Bearer token** (`mesh login`): a `mb_token_` minted in the web UI, stored in `~/.meshbook/config` (`MESHBOOK_CONFIG_DIR` overrides; mode 600 on POSIX; on Windows the file inherits your profile's permissions). `MESHBOOK_TOKEN` and `MESHBOOK_BASE` override the config for one process.
 - **Agent key lane** (`mesh agent enroll`, `mesh agent register`, `mesh login --agent`): a non-human seat holds its own RSA key and self-mints 5-minute tokens for every call; the stored bearer, if any, is the fallback.
 
-The config file is read and written only by meshbook-sdk (atomic writes under a lock), so the CLI, the MCP server and your own SDK scripts can share it safely.
+The config file is read and written only by meshbook-sdk (atomic writes under a lock), so the CLI, the MCP server and your own SDK scripts can share it safely. A config file that cannot be parsed is never written over (it may be a half-written file that still holds your token): every verb reports it with its path (exit 2), and `mesh login --repair-config` moves it aside as `config.bad.<time>` once the new login is verified.
+
+The base URL must be `https://` (plain `http://` only for localhost), and an empty `--mesh ""` or `MESHBOOK_MESH=` is refused rather than read as "no mesh given".
 
 ## Onboarding a non-human partner