xevol 0.12.5 → 0.12.7

package/README.md

@@ -2,7 +2,7 @@
 
 Terminal client for Xevol content execution.
 
-Use it to ingest content, run analysis (spikes), manage prompts, inspect usage, and work across personal/team workspaces.
+Use it to operate Xevol Work CRM records, Deals, Activities, tasks, and search; ingest content; run analysis; manage prompts; inspect usage; and work across Workspaces.
 
 ## Install
 
@@ -41,7 +41,7 @@ xevol workspace list
 xevol workspace switch <workspace-id>
 ```
 
-When a workspace is selected, CLI sends `X-Workspace-Id` automatically for workspace-aware API routes.
+`workspace list` and `workspace switch` use the Xevol Work API. The selected Work `workspaceId` is injected into Work commands and cannot be replaced by JSON input. When Creator is enabled, switching also records its mapped Creator Workspace ID for legacy content routes.
 
 ## Command map
 
@@ -50,8 +50,37 @@ When a workspace is selected, CLI sends `X-Workspace-Id` automatically for works
 - `xevol logout` — revoke token + clear local config
 - `xevol whoami` — current authenticated account
 
+### Xevol Work CRM
+- `xevol companies ...` — all Companies reads and commands: list, get, options, create, update, remove, enrich, research, and primary Contact
+- `xevol contacts ...` — all Contacts reads and commands: list, get, create, update, and proposed-fact decisions
+- `xevol leads ...` — every Leads procedure used by Xevol Work Web, including campaigns, review, identity, packets, Deal handoff, outreach, learning, import, insights, and export
+- `xevol deals ...` — list, get, create, update, and stage management
+- `xevol activities ...` — record timelines, counts, personal tasks, activity creation, and task completion
+- `xevol search [query]` — search Companies, Contacts, and Deals across the selected Workspace
+
+Every grouped procedure is a first-class kebab-case subcommand; Search is a direct command. Use `xevol <group> --help` for the complete list. Common creation has direct flags:
+
+```bash
+xevol companies create --name Acme --domain acme.com --json
+xevol contacts create --first-name Ada --email ada@acme.com --company-id <company-id> --json
+xevol leads create --campaign-id <campaign-id> --source MANUAL --company Acme --domain acme.com --json
+xevol deals create --name "Acme renewal" --company-id <company-id> --owner-id <user-id> --amount-cents 125000 --currency USD --json
+xevol activities create --type TASK --subject "Follow up" --deal-id <deal-id> --due-at 2026-09-01T09:00:00Z --json
+xevol search Acme --json
+```
+
+Complex or less common inputs still accept exactly one of `--input`, `--file`, or stdin:
+
+```bash
+xevol leads packet-decide --input '{"packetId":"...","action":"QUALIFY"}' --json
+xevol leads packet-decide --file decision.json --json
+cat decision.json | xevol leads packet-decide --json
+```
+
+List commands also accept `--query`, `--page`, `--page-size`, `--sort`, and `--dir`. Deal lists add status, owner, stage, and closing-window facets. Activity commands provide direct timeline anchors, filters, task windows, and limits. `--workspace-id` overrides the selected Workspace for one command while still relying on server-side membership authorization.
+
 ### Ingestion & content
-- `xevol add <url>` — URL ingestion (YouTube + non-YouTube)
+- `xevol add [url]` — URL ingestion (YouTube + non-YouTube); omit URL when using `--batch`
 - `xevol create [text]` — create from text/file/url/stdin/editor
 - `xevol list` — list transcriptions
 - `xevol view <id>` — view summary/content
@@ -67,10 +96,14 @@ When a workspace is selected, CLI sends `X-Workspace-Id` automatically for works
 ### Usage, exports, locations
 - `xevol usage` — plan + usage snapshot
 - `xevol export <id> --format json|markdown|text` — export content locally
-- `xevol whereami` — latest Xevol Coordinates location
-- `xevol locations` — Xevol Coordinates history
+- `xevol coordinates current` — latest Xevol Coordinates context, with coordinates hidden unless `--exact`
+- `xevol coordinates current --json` — stable machine-readable current context for scripts/agents
+- `xevol coordinates locations` — Xevol Coordinates history
+- `xevol whereami` / `xevol locations` — legacy convenience aliases
 
 ### Interface
+- `xevol agent-help` — machine-oriented guide for agents/scripts using xevol-cli
+- `xevol agent-help --json` — structured command/workflow guide for agents
 - `xevol tui` — interactive terminal UI
 
 ## Common flags
@@ -101,7 +134,12 @@ CLI config is stored in:
 
 - `~/.xevol/config.json`
 
-Includes token, API URL, selected workspace, and defaults.
+Includes the CLI token, Creator API URL, Work API URL, selected Work and mapped Creator Workspace IDs, and defaults.
+
+- `XEVOL_API_URL` overrides the Creator API origin.
+- `XEVOL_WORK_API_URL` overrides the Xevol Work origin (default `https://xevol.com`).
+
+The same device-flow CLI token is introspected by Xevol Work and mapped through its imported Creator identity binding. Every request still passes normal active Workspace membership and module gates.
 
 ## Notes