@usesocial/cli 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,222 @@
 # @usesocial/cli
 
+## 0.9.0
+
+### Minor Changes
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`90cd296`](https://github.com/usesocial/monorepo/commit/90cd2967a18a271337c54414466c5d89e66649d2) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - `social account logs` auto-paginates and aggregates for spend audits.
+
+  - `--limit` above the server's 100-row page cap now follows `.meta.cursor`
+    across pages transparently and returns one merged envelope.
+  - `--sum-by <fields>` (comma-separated from `platform`, `path`, `method`,
+    `day`, `cacheStatus`) aggregates the selected window into
+    `{ …key, calls, credits, errors }` rows sorted by credits descending —
+    a one-command answer to "what did my agent spend this week, on what".
+  - `createdAt` is always an ISO string, and the declared contract stays
+    JSON-Schema-serializable (`social schema --leaves` works).
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`b8cddb4`](https://github.com/usesocial/monorepo/commit/b8cddb4d4c5c290a2add9498ce94c906427a12e5) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Error output and diagnostics are now debuggable end-to-end.
+
+  - API error JSON printed to stderr now includes a top-level `code` (stable
+    snake_case API error code) and `requestId` — quote the request id when
+    reporting a bug and we can trace the exact server-side call.
+  - Rate-limited commands surface `retryCount` and `retryBudgetExhausted` on the
+    error payload alongside the existing `retryAfterSeconds`.
+  - Diagnostic telemetry (opt-out unchanged: `DO_NOT_TRACK=1` /
+    `SOCIAL_DO_NOT_TRACK=1`) now records every command failure — not just API
+    5xx — with a privacy-safe fingerprint (error class + status + stable code)
+    instead of raw messages. The first-run privacy promise is unchanged: no
+    arguments, stdin, response bodies, handles, or content ever leave the
+    machine.
+  - Crashes, unhandled rejections, and Ctrl-C now flush diagnostics before
+    exiting (signals exit `130`/`143`); a closed stdout pipe (`head`, `jq -e`)
+    exits `0` quietly instead of crashing.
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`e3fb8a2`](https://github.com/usesocial/monorepo/commit/e3fb8a2d09301494d95115f8409862d392d78fcb) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Schema contracts now declare advisory hazards instead of confirmation gates:
+  `confirmation.{required,recommended}` is replaced by `hazard { kind:
+spends_credits | destructive | outbound_write, confirm: "advisory" }` on
+  mutating commands (billing portal and connect declare nothing). Non-TTY
+  `account login` and `account connect` become pollable state machines that
+  advance one step per call — `pending_approval { verificationURL, expiresAt }`
+  through `logged_in` / `connected` — with the in-flight device code persisted
+  between calls. New get-started skill reference walks agents through
+  login → connect → cost-estimated first sync.
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`84797f6`](https://github.com/usesocial/monorepo/commit/84797f67c496cef4f5e26b740550166dacba3876) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - `social linkedin message <target>` now accepts `--media <path>` (repeatable) to
+  attach files to a new or existing conversation. The caption (piped on stdin)
+  becomes optional when media is present, and the combined attachments must stay
+  under 20 MB. Media types are detected from file content (magic bytes) and render
+  natively.
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`f9c9916`](https://github.com/usesocial/monorepo/commit/f9c9916e67699ab1640b621205bb0ba498b061d5) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - `social linkedin post` now attaches media and supports quoting and posting as a
+  company. Pipe the caption on stdin as before, or omit it entirely when attaching
+  media or quoting.
+
+  - `--media <path>` (repeatable) attaches local files inline (base64). The media
+    type is detected from the file's content (magic bytes). LinkedIn allows
+    multiple images, OR a single non-image file (video, PDF, document).
+  - `--quote <post>` quotes/reposts an existing post — a LinkedIn post URL,
+    `post_id:<id>`, or URN. With caption text it's a quote post; with empty text
+    it's a bare repost.
+  - `--as <company>` publishes on behalf of a company you admin — a numeric
+    company id, or a company URL/vanity that is resolved to its id.
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`b89c2f9`](https://github.com/usesocial/monorepo/commit/b89c2f96d1acc4dfe21b796a9332732fa60681b4) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Own-data live reads now require a target; your own data is the local mirror.
+
+  `social x tweets`, `x followers`, `x following`, `x liked`, `x mentions`, and
+  `linkedin connections` invoked without a target no longer fall back to a
+  metered self-read. Each fails with a teaching error naming the free local
+  path instead — e.g. `social x sync tweets` then
+  `social x sql "SELECT text, like_count, impression_count FROM x_tweets ORDER BY created_at DESC LIMIT 25"`.
+  Live reads are for someone else's graph; `sync` + `sql` is the own-data
+  surface. A literal `@me`/`@self` target still resolves to that real X
+  username but emits a note pointing at the sync+sql path.
+
+  Bare `social x sync` / `social linkedin sync` listings now include
+  `totalRows` (current local table count) beside `objectCount` (last run's
+  fetched count), so a caught-up sync no longer reads as an empty mirror.
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`90cd296`](https://github.com/usesocial/monorepo/commit/90cd2967a18a271337c54414466c5d89e66649d2) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Cursor-based syncs are resumable after rate limits and aborts.
+
+  Sync progress (page cursor and phase, including LinkedIn messages' two-phase
+  conversations→messages walk) is persisted after every stored page. When a
+  sync dies mid-run — most commonly a LinkedIn `/chats` 429 — the rate-limit
+  JSON now reports `syncResume.cursorPersisted: true` with `behavior: "resume"`,
+  and re-running the printed `retryCommand` continues from the saved cursor
+  instead of restarting and re-billing already-fetched pages. Resume only
+  applies to the same collection, account, and `--since` window; `--reset`
+  clears saved cursors; a clean completion replaces them with the normal
+  checkpoint.
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`90cd296`](https://github.com/usesocial/monorepo/commit/90cd2967a18a271337c54414466c5d89e66649d2) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Successful writes now update the local SQL mirror immediately.
+
+  - `social x message` inserts the sent DM into `x_messages` using the send
+    response (and upserts the recipient profile, so `counterpart_username`
+    resolves even for conversations where the other side has never replied).
+  - `social linkedin requests cancel` / `accept` remove the pending row from
+    `li_requests`; `requests send` inserts the new sent row.
+  - `social x bookmark` / `unbookmark` add and remove `x_bookmarks` rows.
+  - `social linkedin message` inserts into `li_messages` once that collection
+    has been synced.
+
+  Your own write is queryable via `sql` the moment the command succeeds — no
+  re-sync, and no `--reset` (which re-bills a collection's full history) just
+  to verify a send. Write-through only applies to collections that have been
+  synced at least once, and a mirror write failure never breaks a successful
+  command: it degrades to a stderr warning.
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`4824400`](https://github.com/usesocial/monorepo/commit/4824400ebcabb56f27f616418b0e62bc382c8fae) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Posting now updates the local SQL mirror immediately, like messages and
+  bookmarks already do.
+
+  - `social x post` inserts the created post into `x_tweets` from the send
+    response; `social x delete` removes the row.
+  - `social linkedin post` inserts into `li_posts` when the response carries a
+    usable post id (`post_id` or `id`); without one the mirror write is skipped
+    silently.
+
+  Rows are sparse until the next sync enriches them from upstream (engagement
+  counters arrive then). Same semantics as the existing write-throughs: only
+  applies once the collection has been synced at least once, and a mirror
+  failure degrades to a stderr warning without breaking the command.
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`b89c2f9`](https://github.com/usesocial/monorepo/commit/b89c2f96d1acc4dfe21b796a9332732fa60681b4) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - `liked` and `mentions` are now syncable X collections with local mirror twins.
+
+  - `social x sync liked` populates `x_liked`; `social x sync mentions`
+    populates `x_mentions`. Both are tweet-shaped (text, url, created_at, all
+    public metrics, author columns) and query free via `social x sql`.
+  - `mentions` supports `--since <ISO date>` for cheap incremental pulls;
+    `liked` does not (the upstream API has no time filter — re-syncs walk from
+    the newest like to the local checkpoint).
+  - Sync requests carry the full live-read field presets, so mirror rows land
+    with `created_at` and metrics populated from the first pull.
+  - `social x like <post>` inserts the post into `x_liked` immediately on
+    success and `unlike` removes it — no re-sync needed to see your own action,
+    once the collection has been synced at least once.
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`a902314`](https://github.com/usesocial/monorepo/commit/a9023144ca92f9cc87dd753239b572e6d0f3bfda) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - `social x post` now attaches media and creates native polls. Pipe the caption
+  on stdin as before, or omit it entirely when attaching media — text is optional
+  once media is present.
+
+  - `--media <path>` (repeatable) uploads local image/gif/video files via X's
+    chunked upload, then attaches them. X combinatorics apply: up to 4 images, OR
+    1 gif, OR 1 video — no mixing.
+  - `--media-id <id>` (repeatable) attaches an already-uploaded media id, skipping
+    upload (useful for retries).
+  - `--poll-option <text>` (repeatable, 2–4) with `--poll-duration <minutes>`
+    (5–10080) creates a native poll. Mutually exclusive with media.
+  - `--reply-settings <following|mentionedUsers|subscribers|verified>` limits who
+    can reply.
+  - `--timeout <seconds>` sets the wait budget for video/gif processing
+    (default 300).
+  - `--reply-to <post>`, `--account <selector>`, and the `--body <JSON>` escape
+    hatch for long-tail post fields (media title/description, `tagged_user_ids`,
+    `quote_tweet_id`, `made_with_ai`, community, geo, nullcast) are restored for
+    `post`.
+
+  Uploading media is free; each finalized file costs a flat 15 credits at the
+  finalize step, independent of file size, on top of the normal post-create
+  credits.
+
+  Posting media requires the `media.write` OAuth scope. Existing connected X
+  accounts must run `social account reconnect x <account>` to gain it — OAuth
+  scope upgrades are not retroactive.
+
+### Patch Changes
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`90cd296`](https://github.com/usesocial/monorepo/commit/90cd2967a18a271337c54414466c5d89e66649d2) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - `social linkedin message <person>` starts new conversations again.
+
+  Person-target sends (profile URL, `@username`, `profile_id:<id>`, URN) were
+  rejected upstream after the provider's v2 migration. New chats now follow the
+  v2 inbox contract — the CLI resolves the person, discovers the LinkedIn
+  classic inbox, and starts the chat there. The command's contract models both
+  response shapes: `MessageSent` for existing-chat sends (`chat_id:<id>`),
+  `ChatStarted` (with the new `chat_id`) for first messages.
+
+- [#35](https://github.com/usesocial/monorepo/pull/35) [`0dacb7f`](https://github.com/usesocial/monorepo/commit/0dacb7fadb59067787e167e8a3ae84fcde673fe7) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Internal: the profile write-through primitives (`upsertProfiles`,
+  `lookupProfiles`, `ProfileRow`) moved from `@usesocial/api/proxy` to
+  `@usesocial/db/profiles`; the proxy re-exports them unchanged. No CLI-visible
+  behavior change.
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`5a2e56e`](https://github.com/usesocial/monorepo/commit/5a2e56e7fbd4b27edc11990192639aa9404f19b1) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Report local SQLite cache auto-migrations in JSON output instead of stderr banners.
+  Breaking: all `social x sync...` and `social linkedin sync...` outputs now return
+  `{ data, meta }`; previous bare sync arrays and summary/reset objects now live
+  under `.data`, and migration details appear under `.meta.cache.migration` only
+  when a cache migration runs.
+
+- [#34](https://github.com/usesocial/monorepo/pull/34) [`90cd296`](https://github.com/usesocial/monorepo/commit/90cd2967a18a271337c54414466c5d89e66649d2) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - X syncs request full field presets, and incremental message refreshes are
+  ~10x cheaper.
+
+  - `social x sync tweets` / `bookmarks` / `followers` / `following` now send
+    the same field presets as live reads, so mirror rows land with `created_at`
+    and `public_metrics` populated — previously the upstream returned minimal
+    objects and the documented own-content audit recipe (`like_count`,
+    `impression_count`, …) silently came back all-NULL. Mirrors synced before
+    this fix need one `--reset` re-pull to heal (metered).
+  - Sync summaries gain an additive `warnings[]`; a `fieldCompleteness` warning
+    fires if a page arrives missing expected fields, so silent starvation
+    cannot recur.
+  - Checkpointed `x sync messages` refreshes request small pages instead of
+    full 100-event pages, cutting a caught-up refresh from ~1,470 to ~150
+    credits. `stoppedReason: "checkpoint"` now carries a note explaining it
+    means "caught up: no new events since the last sync checkpoint".
+
+## 0.8.0
+
+### Minor Changes
+
+- [#33](https://github.com/usesocial/monorepo/pull/33) [`abb6401`](https://github.com/usesocial/monorepo/commit/abb64017354f4607a25d321f115d5063ad3d4117) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Remove `social account config cache mode`; configure live-read proxy caching with `social account config cache ttl` only.
+
+- [#33](https://github.com/usesocial/monorepo/pull/33) [`2c315ba`](https://github.com/usesocial/monorepo/commit/2c315ba6ba0f8279b9bad05928450d5666476627) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Add sync `--timeout` rate-limit wait budgets and resumable rate-limit abort guidance.
+
+- [#33](https://github.com/usesocial/monorepo/pull/33) [`76d03f2`](https://github.com/usesocial/monorepo/commit/76d03f21d6e2e2214f85338c8cb13c4eae2a96c3) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Rebuild the local SQL mirror as curated views and slim the schema surfaces.
+
+  - Every cache table is now a view over a `<name>_raw` physical table. Views drop `raw`/`synced_at` (a `SELECT *` row is ~5× smaller) and normalize names across platforms: `username`/`name`/`avatar_url` everywhere, `created_at` (was `timestamp`), `conversation_id` (was `chat_id`/`dm_conversation_id`), `last_message_at`, `is_mentioned`, `*_distance`. Upstream JSON stays queryable in the `_raw` twins via `json_extract(raw, '$.field')`. Existing caches migrate automatically.
+  - Promoted raw fields: `li_requests.message` (invitation note text) and `x_profiles.receives_your_dm`.
+  - `li_posts` is a curated ~29-column view; the quoted-post/permissions long tail lives in `li_posts_raw`.
+  - Bare `social <platform> sql` now prints compact schema metadata — column lists, row counts, `synced_at`, `query_ready`, indexed columns, join hints, and enum values — instead of raw `CREATE TABLE` statements (~35% smaller).
+  - `social schema` output is leaner: the redundant `params` field is gone (use `args`/`flags`/`inputSchema`), `schemaVersion` prints once at the root, and empty `subCommands` are omitted (`--leaves` is ~26% smaller).
+  - `sql` contract examples are projected queries on `x_followers`, `x_following`, and `li_connections`.
+
 ## 0.7.1
 
 ### Patch Changes

package/README.md

@@ -25,6 +25,12 @@ Published as `@usesocial/cli` on npm; the binary is `social`.
 curl -fsSL https://usesocial.dev/install.sh | bash
 ```
 
+Or with Homebrew:
+
+```sh
+brew install usesocial/tap/cli
+```
+
 ## Quickstart
 
 ```sh
@@ -56,7 +62,7 @@ marked **local** update local CLI state or the local mirror.
 
 ### Targets
 
-Targets accept handles, profile/post/conversation/company URLs, LinkedIn URNs,
+Targets accept usernames, profile/post/conversation/company URLs, LinkedIn URNs,
 or typed IDs such as `profile_id:<id>`, `post_id:<id>`, `chat_id:<id>`,
 `conversation_id:<id>`, `company_id:<id>`, and `request_id:<id>`. Bare IDs are
 not accepted.
@@ -69,25 +75,48 @@ freeform text from stdin. There is no text positional:
 ```sh
 echo "gm" | social x post
 social linkedin post < draft.md
-social linkedin requests send @handle < note.txt
+social linkedin requests send @username < note.txt
 ```
 
 Pipe a JSON object for advanced payload fields.
 
-## Your data is local
+### Pagination
+
+Live list reads take `--limit`. X lists and LinkedIn `posts`/`connections`
+continue with `--cursor` from `.meta.cursor`; LinkedIn `search`, `comments`,
+`reactions`, and `jobs` continue with `--offset`. `sql` does not paginate —
+use SQL `LIMIT` and `ORDER BY`.
+
+### Your data is local
 
 `sync` pulls your own data down; it is explicit and costs credits. `sql` queries
 that local mirror; it is free, instant, and read-only. Named read commands call
 the live network and cost credits; `x tweets <target>` and
 `linkedin posts <target>` require a target. Writes act.
 
+`sync` output is always `{ data, meta }`: bare `sync` lists collections under
+`.data[]`, while collection summaries and `--reset` results live under `.data`.
+`sync <collection> --since 2026-05-04` (ISO date or datetime) pulls only newer
+items where the bare `sync` listing shows `supportsSince: true` — cheaper than a
+full re-pull. `sync <collection> --reset` clears a collection's local rows and
+sync state so the next sync rebuilds it.
+`sync <collection> --timeout 900` opts into a wall-clock wait budget, in seconds,
+for rate-limit handling. LinkedIn sync may sleep and retry while the next wait
+fits the budget; X keeps its current no-new-retry behavior.
+
+Rate-limit JSON includes `retryAfterSeconds`, `resumeAt`, `retryCommand`,
+`hint`, and `syncResume`. When `syncResume.cursorPersisted` is true, already
+synced pages are saved and the listed `retryCommand` resumes from the saved
+cursor. For parent/child message syncs, the hint says when an exact cursor
+resume is not safe and the re-run may re-fetch unfinished pages.
+
 ```sh
 social x sync messages
-social x sql "SELECT sender_handle, text, datetime(created_at/1000,'unixepoch') AS at FROM x_messages ORDER BY created_at DESC LIMIT 20" \
+social x sql "SELECT sender_username, text, datetime(created_at/1000,'unixepoch') AS at FROM x_messages ORDER BY created_at DESC LIMIT 20" \
   | jq '.items[]'
 ```
 
-The X inbox query gets `sender_handle` from the `x_messages` view; no extra
+The X inbox query gets `sender_username` from the `x_messages` view; no extra
 profile lookup is needed.
 
 ### Top level
@@ -117,26 +146,25 @@ profile lookup is needed.
 | `billing portal` | Open the hosted billing portal and print its URL. | |
 | `usage` | Aggregate proxy calls and credits. | |
 | `logs` | Recent proxy calls. | |
-| `config cache mode` | Read or set the live-read proxy cache mode. | |
-| `config cache ttl` | Set a live-read proxy cache TTL in seconds. | |
+| `config cache ttl` | Read or set the live-read proxy cache TTL in seconds. | |
 
 ### `social linkedin`
 
 | Command | Description | |
 | --- | --- | --- |
 | `profile [target]` | Fetch a profile; omit target for your own account. | |
-| `posts <target>` | Live posts for a person or company; target required. Supports `--limit` and `--cursor` from `.meta.cursor`. | |
-| `comments <target>` | List a post's comments; supports `--limit` and `--offset`. | |
-| `reactions <target>` | List a post's reactions; supports `--limit` and `--offset`. | |
-| `connections [target]` | Live connection graph read; omit target for your own account. Supports `--limit` and `--cursor` from `.meta.cursor`. Costs credits. | |
+| `posts <target>` | Live posts for a person or company; target required. | |
+| `comments <target>` | List a post's comments. | |
+| `reactions <target>` | List a post's reactions. | |
+| `connections [target]` | Live connection graph read; omit target for your own account. Costs credits. | |
 | `company <target>` | Fetch a company profile. | |
-| `jobs <target>` | List a company's job postings; supports `--limit` and `--offset`. | |
-| `search people\|posts\|jobs\|companies <keywords>` | Search LinkedIn; live offset-paginated reads. | |
+| `jobs <target>` | List a company's job postings. | |
+| `search people\|posts\|jobs\|companies <keywords>` | Search LinkedIn. | |
 | `sync [collection]` | Pull your own `connections`, `posts`, `messages`, or `requests` into the local mirror; costs credits. | local |
-| `sql [query]` | Query your synced local mirror with read-only SQL - free; bare `sql` prints the schema. | |
+| `sql [query]` | Query your synced local mirror with read-only SQL - free; bare `sql` prints compact schema metadata. | |
 | `post` | Create a post (body from stdin). | write |
 | `comment <target>` | Comment on a post (body from stdin). | write |
-| `react <target>` | React to a post or comment; use `--type` for non-like reactions. | write |
+| `react <target>` | React to a post; use `--type` for non-like reactions. | write |
 | `requests send <target>` | Send a connection request (optional note from stdin). | write |
 | `requests accept request_id:<id>` | Accept a received connection request. | write |
 | `requests cancel request_id:<id>` | Cancel a sent request or refuse a received connection request. | write |
@@ -163,7 +191,7 @@ profile lookup is needed.
 | `likers <target>` | List users who liked a post. | |
 | `reposters <target>` | List users who reposted a post. | |
 | `sync [collection]` | Pull your own `tweets`, `followers`, `following`, `bookmarks`, or `messages` into the local mirror; costs credits. | local |
-| `sql [query]` | Query your synced local mirror with read-only SQL - free; bare `sql` prints the schema. | |
+| `sql [query]` | Query your synced local mirror with read-only SQL - free; bare `sql` prints compact schema metadata. | |
 | `post` | Create a post (body from stdin). | write |
 | `message <recipients>` | Send a DM (body from stdin). | write |
 | `like <target>` / `unlike <target>` | Like or unlike a post. | write |
@@ -176,15 +204,16 @@ profile lookup is needed.
 
 - Everything speaks JSON: success on stdout, structured errors on stderr.
 - Platform reads return one envelope: lists use `.items[]`, single resources use
-  `.data`, metadata lives under `.meta`. `social account` service commands return
-  bare JSON; `account logs` returns `{ items, meta: { cursor } }`.
+  `.data`, metadata lives under `.meta`. Sync commands use `{ data, meta }`.
+  `social account` service commands return bare JSON; `account logs` returns
+  `{ items, meta: { cursor } }`.
 - Schema-backed planning: `social schema --list` is the compact runnable index.
 - Local SQL is the free surface for your own synced data.
 
 ```sh
 # SQL insight: synced contacts you have never messaged.
 # Run `social linkedin sync connections` and `social linkedin sync messages` first.
-social linkedin sql "SELECT c.user_display_name, c.user_public_identifier, c.user_profile_url FROM li_connections c LEFT JOIN li_messages m ON m.sender_id = c.user_id WHERE m.id IS NULL ORDER BY c.created_at DESC LIMIT 100" \
+social linkedin sql "SELECT c.user_name, c.user_username, c.user_profile_url FROM li_connections c LEFT JOIN li_messages m ON m.sender_id = c.user_id WHERE m.id IS NULL ORDER BY c.created_at DESC LIMIT 100" \
   | jq '.items[]'
 
 # Live fan-out: review recent posts, fan out to reactions, rank warm contacts.
@@ -192,8 +221,8 @@ social linkedin posts profile_id:<profile-id> --limit 25 > /tmp/recent-posts.jso
 jq -r '.items[].id' /tmp/recent-posts.json \
   | xargs -I{} social linkedin reactions post_id:{} --limit 100 --offset 0 \
   | jq -s '[ .[] | .items[] ]
-            | group_by(.actor.id // .reactor.id // .profile_id)
-            | map({person: (.[0].actor // .[0].reactor), signals: length})
+            | group_by(.sender.id)
+            | map({person: .[0].sender, signals: length})
             | sort_by(-.signals) | .[0:15]'
 ```
 
@@ -206,7 +235,7 @@ jq -r '.items[].id' /tmp/recent-posts.json \
 | `3` | Not found | Check the resource ID or pick a different item. |
 | `4` | Auth or scope error | Run `social account login`, or log out and choose the needed scope. |
 | `5` | API, proxy, or unexpected error | Retry later or surface the server error. |
-| `7` | Rate limited | Back off, using `retryAfterSeconds` when present. |
+| `7` | Rate limited | Back off, using `retryAfterSeconds`, `resumeAt`, and `retryCommand` when present. |
 
 ## Auth
 
@@ -230,26 +259,22 @@ The proxy cache applies to live reads only. Cache hits are free; fresh upstream
 reads are metered. Configure the default:
 
 ```sh
-social account config cache mode
-social account config cache mode live
-social account config cache mode analytical
-social account config cache mode historical
 social account config cache ttl 3600
 ```
 
 Override one live read when the command lists `--header`:
 
 ```sh
-social linkedin profile @handle -H "Cache-Control: no-cache"
-social linkedin profile @handle -H "Cache-Control: no-store"
-social linkedin profile @handle -H "Cache-Control: max-age=60"
+social linkedin profile @username -H "Cache-Control: no-cache"
+social linkedin profile @username -H "Cache-Control: no-store"
+social linkedin profile @username -H "Cache-Control: max-age=60"
 ```
 
 The local mirror is separate: run `sync` when you want newer local data, then
-query it with `sql`. SQL reads show local freshness in `meta.cache.tables`:
+query it with `sql`. SQL reads show local freshness in `meta.cache.tables` and auto-upgrades in `meta.cache.migration` when a migration runs:
 
 ```sh
-social x sql "SELECT sender_handle, text FROM x_messages ORDER BY created_at DESC LIMIT 5" \
+social x sql "SELECT sender_username, text FROM x_messages ORDER BY created_at DESC LIMIT 5" \
   | jq '{cost: .meta.cost, cache: .meta.cache}'
 social x timeline --limit 20 | jq '{cost: .meta.cost, cursor: .meta.cursor, cache: .meta.cache}'
 ```
@@ -263,8 +288,8 @@ Agents should watch `.meta.cost` during high-fanout loops, use
 ```sh
 # LinkedIn local mirror.
 social linkedin sync messages
-social linkedin sql "SELECT sender_display_name, text, datetime(timestamp/1000,'unixepoch') AS at FROM li_messages ORDER BY timestamp DESC LIMIT 20"
-social linkedin sql "SELECT user_display_name, user_public_identifier FROM li_requests WHERE type='received' ORDER BY created_at DESC LIMIT 25"
+social linkedin sql "SELECT sender_name, text, datetime(created_at/1000,'unixepoch') AS at FROM li_messages ORDER BY created_at DESC LIMIT 20"
+social linkedin sql "SELECT user_name, user_username FROM li_requests WHERE type='received' ORDER BY created_at DESC LIMIT 25"
 
 # LinkedIn live reads.
 social linkedin profile
@@ -275,7 +300,7 @@ social linkedin reactions post_id:<post-id> --limit 100 --offset 0
 
 # X local mirror.
 social x sync messages
-social x sql "SELECT sender_handle, text FROM x_messages ORDER BY created_at DESC LIMIT 20"
+social x sql "SELECT sender_username, text FROM x_messages ORDER BY created_at DESC LIMIT 20"
 social x sql "SELECT text, url FROM x_bookmarks ORDER BY created_at DESC LIMIT 50"
 social x sql "SELECT username, name, followers_count FROM x_followers ORDER BY followers_count DESC LIMIT 100"