@arbidocs/cli 0.3.63 → 0.3.65

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## v0.3.65
+
+[compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.3.64...HEAD)
+
+### 🩹 Fixes
+
+- **tsc:** Zero typecheck errors across all four packages ([#752](https://github.com/arbicity/ARBI-frontend/pull/752))
+
+## v0.3.64
+
+[compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.3.63...HEAD)
+
+### 🚀 Enhancements
+
+- **cli:** Clean up arbi dm list output ([#739](https://github.com/arbicity/ARBI-frontend/pull/739))
+- **cli:** Make arbi friendlier for AI agents ([#740](https://github.com/arbicity/ARBI-frontend/pull/740))
+- **cli:** More agent ergonomics (workspaces --mine, notifications, watch --type, local --json) ([#741](https://github.com/arbicity/ARBI-frontend/pull/741))
+- **cli:** PR3 — simplification, gap-fills, help-text cleanup ([#742](https://github.com/arbicity/ARBI-frontend/pull/742))
+- **cli:** PR4 — auth namespace, doc similar, workspace flag-wrappers, help groups, SSO clarity ([#743](https://github.com/arbicity/ARBI-frontend/pull/743))
+- **cli:** Citation ergonomics — inline markers in arbi ask, --json/--raw/verify on arbi cite ([#744](https://github.com/arbicity/ARBI-frontend/pull/744))
+- **cli:** One canonical format for arbi cite (markdown blocks), drop --raw ([#745](https://github.com/arbicity/ARBI-frontend/pull/745))
+- **cli:** Drop --json from mutating commands, self-print help on errors ([#746](https://github.com/arbicity/ARBI-frontend/pull/746))
+- **cli:** --dry-run on every destructive command ([#747](https://github.com/arbicity/ARBI-frontend/pull/747))
+- **cli:** Rename 'arbi conversations' → 'arbi convo' ([#749](https://github.com/arbicity/ARBI-frontend/pull/749))
+
+### 🩹 Fixes
+
+- **mcp-connect:** Allow button does nothing in new OAuth browser tab ([#735](https://github.com/arbicity/ARBI-frontend/pull/735))
+- **test:** Add missing getApiClient and account deletion mocks to UserSettings test ([#736](https://github.com/arbicity/ARBI-frontend/pull/736))
+- Open all workspaces before creating MCP OAuth session ([3f20c956](https://github.com/arbicity/ARBI-frontend/commit/3f20c956))
+- **docker:** Chown html dir so nginx can write runtime config files ([30970f86](https://github.com/arbicity/ARBI-frontend/commit/30970f86))
+- **docker:** Add USER root before chown so it runs as root in DHI image ([caa7ebb2](https://github.com/arbicity/ARBI-frontend/commit/caa7ebb2))
+- **docker:** Use USER 0 instead of USER root in DHI hardened image ([7d8313b4](https://github.com/arbicity/ARBI-frontend/commit/7d8313b4))
+- **cli:** Upload --watch exit + conversation continuation + add 'conversations switch' ([#748](https://github.com/arbicity/ARBI-frontend/pull/748))
+- **cli:** Build CLI on-demand in local.test.ts so CI passes ([#750](https://github.com/arbicity/ARBI-frontend/pull/750))
+- **cli:** Integration tests stale from --json drops, dm send rename, broken pdf URL ([#751](https://github.com/arbicity/ARBI-frontend/pull/751))
+
 ## v0.3.63
 
 [compare changes](https://github.com/arbicity/ARBI-frontend/compare/v0.3.62...HEAD)

package/SKILL.md

@@ -32,7 +32,7 @@ Documents, conversations, and tags are scoped per workspace. An active workspace
 
 Common moves:
 
-- List: `arbi workspaces` (human) · `arbi workspaces --json` (script) · `arbi workspaces --ids`
+- List: `arbi workspaces` (human) · `arbi workspaces --json` (script) · `arbi workspaces --ids` · `arbi workspaces --mine` (hide deployment-wide "common" workspaces — useful when the deployment has dozens of shared scratch workspaces from earlier test runs that drown out the one you actually belong to)
 - Active workspace ID: `arbi workspace current` (prints the ID, empty string if none) · `arbi workspace current --json` for full details
 - Pick/switch: `arbi workspace select <id-or-name>` — accepts a workspace ID or a unique (case-insensitive) name; clears the chat session; uploaded docs in other workspaces are unaffected
 - Create: `arbi workspace create "My WS"` — does NOT auto-select. Use `--select` to create + select in one go, `--json` for scripts
@@ -61,22 +61,26 @@ Scripting notes:
 
 ## For Automations / AI Agents
 
-- **Structured output (`--json`)**: supported on `status`, `config show`, `health`, `models`, `workspaces`, `workspace users`, `docs`, `conversations` (or `conversations list`), `tags` (or `tags list`), `contacts` (or `contacts list`), `find`, `settings get`, `task list`, `ask -b`, `upload`, `watch`. Use it whenever parsing output. `docs` also supports `--csv`, `--ids`, and `--count`.
+- **Structured output (`--json`)**: supported on `status`, `config show`, `health`, `models`, `workspaces`, `workspace users`, `workspace current`, `docs`, `convo` (or `convo list`), `tags` (or `tags list`), `contacts` (or `contacts list`), `find`, `settings get`, `task list` / `task status` / `task result`, `agent list`, `session list`, `dm list`, `notifications list`, `local ls` / `local find` / `local cat` / `local tree`, `update --check`, `register --non-interactive`, `ask -b`, `upload`, `watch`. Use it whenever parsing output. `docs` also supports `--csv`, `--ids`, and `--count`. `arbi ask --json` without `-b` errors out — streaming mode is prose, not JSON; pass `-b` to get a background task ID, then `arbi task result --json`.
 - **Human table output is lossy**: table rows may contain status glyphs (`●`, `🟩`, etc.) and emoji, and column widths truncate content. Never parse tables — always pass `--json`.
 - **Exit codes**:
   - `0` success
   - `1` failure (bad args / auth / API / network / server error)
   - `2` `arbi health --json` when the server reports unhealthy (the JSON body is still printed so you can introspect)
+  - `3` recipient/target not found (`arbi dm send <unknown>`, `arbi workspace remove-user <unknown>`, `arbi doctags create <unknown-tag>` — distinguished so agents can branch "fix the reference" vs "server error")
+  - `124` `arbi watch -n N --timeout S` when fewer than N messages arrived before the timeout (GNU `timeout` convention; in `--json` mode a final `{"type":"timeout","received":…,"expected":…}` line is emitted before exit)
   - `130` user-cancelled interactive prompt (Ctrl+C in `quickstart`)
   - Always check `$?` — `arbi ask` while logged-out, typo commands, and network failures all return non-zero.
-- **Avoid interactive prompts** — pass everything as flags/env vars:
+- **Avoid interactive prompts** — pass everything as flags/env vars. The CLI refuses to open a prompt when stdin isn't a TTY (exit 1 with a recovery hint), so an agent that forgets a positional arg fails loudly rather than hanging.
   - `arbi login -e $ARBI_EMAIL -p $ARBI_PASSWORD -w <workspace-id>` (or set `ARBI_EMAIL`/`ARBI_PASSWORD`).
   - `arbi agent-create --email agent-<...> --workspace-name "<name>"` (requires `SUPPORT_API_KEY`).
   - `arbi workspace select <id>` (ID directly, no picker).
   - `arbi docs` auto-uses the selected workspace; pass `-w <id>` to override.
+  - `arbi dm send <recipient> "<msg>"` (refuses to prompt; pass both args).
+  - `arbi agent delete <id> -y` (skip the confirmation prompt; `-y` is required in non-TTY).
   - Do **not** run `arbi quickstart` in non-interactive contexts — it is interactive-only.
 - **Health probe**: `arbi health --json` returns the raw payload and exits `2` if the server is not healthy — useful for pre-flight checks.
-- **No color leakage**: chalk auto-disables ANSI codes when stdout is not a TTY, so `arbi docs --json | jq`, `arbi workspaces --json | jq`, etc. work cleanly. Status messages and spinners go to stderr; stdout is safe to pipe.
+- **No color leakage**: chalk auto-disables ANSI codes when stdout is not a TTY, so `arbi docs --json | jq`, `arbi workspaces --json | jq`, etc. work cleanly. Status messages, spinners, empty-state hints (`No tags found.`, `No tasks. …`), and the auto-update nag all go to stderr; stdout is safe to pipe. The update nag is also gated to once per day (`~/.arbi/last-update-hint.json`) and suppressed entirely when any argv mentions `--json`.
 - **Typo suggestions**: `arbi updat` → `error: unknown command 'updat' (Did you mean update?)` (exit 1). Works for top-level commands and nested subcommands.
 - **Completion**: `arbi completion install` (no `bash`/`zsh` arg — auto-detected from `$SHELL`).
 
@@ -101,8 +105,45 @@ All document list/search/meta commands support machine-readable output. Prefer `
 All list commands that summarize people or state support `--json`:
 `arbi contacts list --json`, `arbi dm list --json`, `arbi dm send <to> <msg> --json`, `arbi agent list --json`, `arbi session list --json`, `arbi task list --json`.
 
-- **Contacts are one-way**: `arbi contacts add <email>` only populates *your* contact list; the other party is NOT notified and does not see you in their contacts. Before replying to a DM from a new sender you must add them with `arbi contacts add`.
+- **Contacts auto-add on DM**: sending or receiving a DM now mirrors both parties into each other's contact lists (backend-side, idempotent). You no longer need `arbi contacts add` before replying to an inbound DM. `arbi contacts --json` strips inline base64 profile pictures by default and exposes `has_picture: true` instead — pass `--include-pictures` to get the bytes.
 - **DM E2E proof**: `arbi dm send … --json` and `arbi dm list --json` emit an `encrypted_in_transit: true` flag per message. The SDK seals every DM with the recipient's curve25519 public key before the network call — this flag makes that invariant visible without reading SDK code.
+- **DM inbox triage**: `arbi dm list` accepts `--unread`, `--from <email-or-extid>`, `--thread <peer>` (both directions with one peer), `--since <iso>`, and `-l/--limit <n>`. `arbi dm read --all` / `arbi dm delete --all` bulk-operate without the picker.
+- **Non-DM notifications**: `arbi notifications list` (alias: `arbi notifications`) shows workspace invites, contact accepts, batch completes, etc. — everything `arbi dm list` filters out because it's not a `user_message`. Supports `--unread`, `--type <comma-list>`, `--limit`, `--json`.
+- **Workspace watch firehose**: `arbi watch --type task_update,notification` filters the WebSocket stream by event type (unknown types are rejected up-front instead of silently swallowed). Known types: `task_update`, `batch_complete`, `presence_update`, `response_complete`, `notification`, `error`. `arbi watch -n N --timeout S` exits **124** with a `{type:"timeout", received, expected}` JSON terminator if N events never arrived.
+- **Local filesystem**: `arbi local ls/find/cat/tree --json` for agent-friendly browsing. `ls --all` includes dotfiles; `tree --depth N` controls recursion; `cat --head N` truncates by line count. Empty result sets emit `[]` on stdout, not human prose.
+- **Update probe**: `arbi update --check` exits 0 if up to date and 1 if an update is available (`git diff --exit-code` convention). `arbi update --json` (implies `--check`) emits `{current, latest, update_available}` and is the right way for an agent to gate behavior on the CLI version.
+- **Quick toggles instead of JSON patches**: `arbi doc share <ids>` / `arbi doc unshare <ids>` and `arbi tags share <id>` / `arbi tags unshare <id>` / `arbi tags rename <id> <name>` are named shortcuts for the most common `doc update` / `tags update` operations — no more hand-writing `{"shared":true}` JSON.
+- **Inbox housekeeping**: `arbi notifications mark-read --all` and `arbi notifications delete --all` drain the non-DM queue for long-running agents whose `--unread` filter would otherwise grow unbounded.
+- **Leave a workspace**: `arbi workspace leave [id-or-name]` self-removes from a workspace (defaults to the active one); requires `-y/--yes` in non-TTY shells. Symmetric to `arbi workspace add-user`.
+- **Projects**: `arbi project list` (and `create`, `refresh`) — projects are the tenancy unit above workspaces. Until this command existed the only way to discover a `projectExtId` was inside `arbi register`, blocking multi-project bootstrap from a fresh agent install.
+- **Files (Responses API attachments)**: `arbi files list/upload/get/delete/content` — ephemeral files for the OpenAI-compatible Responses path. Independent of the workspace document index; meant for short-lived attachments to single `arbi ask -b` requests.
+- **Usage probe**: `arbi usage today --json` is the cheapest pre-flight check before launching a long batch. Returns whatever quota the project surfaces (credits, storage, token caps) so agents can budget.
+- **Execution trace**: `arbi convo trace <message-id>` (alias of `arbi convo message`) returns the full decrypted reasoning + tool-call trail for one agent response. Post-mortem primitive for debugging failed steps.
+- **Switch conversations**: `arbi convo switch <conv-id>` points the chat session at a different conversation so the next `arbi ask` resumes there. CLI equivalent of clicking a conversation in the web UI sidebar.
+
+## Citation Flow (the agent-grade verification path)
+
+The most subtle agent-facing concern: when ARBI answers from documents, **how do citations reach you on a CLI?** Without a screen to click on, the streaming text has to carry the answer AND the proof. Here's how the pieces line up:
+
+1. **Inline markers during the stream.** `arbi ask` emits inline citation markers directly in the streamed answer. The backend uses `[claim text](#cite-N)` (a markdown anchor link) and the CLI transforms it into `claim text[N]` on the fly while writing tokens to stdout. Pass `--raw-citations` to keep the original markdown form (useful when piping to a markdown renderer that resolves the anchors itself).
+2. **Persisted metadata for `arbi cite`.** When the SSE stream ends, the full citation graph — `claim → chunk_ext_ids → chunk content → doc_title / page_number` — is written to `~/.arbi/last-metadata.json`. Per shell, per `ARBI_CONFIG_DIR`. Survives until the next `arbi ask`.
+3. **Browse.** `arbi cite` lists all citations with one-line summaries. `arbi cite <N>` shows the full passage for citation `N` with doc title + page number.
+4. **Parse.** `arbi cite --json` (or `arbi cite <N> --json`) emits a structured payload:
+   ```json
+   { "count": 2, "citations": [
+       { "num": "1", "statement": "...", "doc_title": "...", "page_number": 3,
+         "chunk_ext_ids": ["chk-..."], "doc_ext_ids": ["doc-..."],
+         "passages": ["..."], "passage_hashes": ["sha256..."] } ] }
+   ```
+   This is the right way to read citations programmatically. `passage_hashes` lets an agent assert "this chunk matches what I cited" without re-fetching the doc.
+5. **Pipe.** `arbi cite --raw` (or `arbi cite <N> --raw`) prints just the passage text — no chalk, no headers — so it pipes cleanly into `grep`, `diff`, `wc`, etc.
+6. **Verify.** `arbi cite verify <N> [--json]` is the explicit "is this citation real?" path. It re-walks the saved metadata, returns the cited `chunk_ext_id` + `doc_ext_id` + a SHA256 of the cited passage, and emits a follow-up hint:
+   > For independent re-verification, run `arbi doc get <doc_ext_id> --json` and confirm the passage hash matches the doc content.
+   So an agent that wants higher assurance can pull the source doc, compute the same SHA256 over the cited passage, and assert byte-equality without trusting the saved metadata alone.
+
+Footnote-style rendering at the end of the answer is currently not supported — the backend places markers inline. If your downstream consumer wants footnotes specifically, parse the `arbi cite --json` output and assemble them yourself (the `num` and `statement` fields are all you need).
+- **`arbi dm` defaults to `list`**, so `arbi dm | head` and `arbi dm --json` both work. Same for `arbi task`, `arbi agent`, `arbi session`. Typos on these (`arbi dm lst`) suggest the nearest subcommand instead of erroring with "too many arguments".
+- **Names-or-IDs**: `arbi workspace remove-user`, `arbi workspace copy <target>`, and `arbi doctags create <tag>` / `arbi doctags delete <tag>` all accept either an ID or an email/workspace-name/tag-name. Ambiguous names exit `3` with the matching IDs listed.
 - **Listen side-effects**: `arbi listen --agent claude` writes `~/.claude/commands/arbi/SKILL.md` and sets a `defaultAgent` in the CLI config. Run it only on a machine you control.
 - **Persistent agents**: `arbi agent create --name <n> -w <ws-id>` creates a child identity the parent can delegate to (printed email+password). Share workspace IDs via `-w` rather than the interactive picker when running non-interactively.
 - **Agent-create errors**: `agent-create` rejects non-`agent-*` emails with a clear message. If you see "No verification record found" the account probably already exists — use `arbi login` instead.