xevol 0.13.0 → 0.14.1

package/README.md

@@ -2,7 +2,7 @@
 
 Terminal client for Xevol content execution.
 
-Use it to operate Xevol Work Offers, Leads, Contacts, Companies, Deals, Activities, tasks, and search; ingest content; run analysis; manage prompts; inspect usage; and work across Workspaces.
+Use it to manage Xevol Work Ads; operate Offers, Leads, Contacts, Companies, Deals, Activities, tasks, and search; ingest content; run analysis; manage prompts; inspect usage; and work across Workspaces.
 
 ## Install
 
@@ -47,11 +47,13 @@ xevol workspace switch <workspace-id>
 
 ### Auth
 - `xevol login` — device auth flow (or `--token` for headless/CI)
+- `xevol connect <codex|claude|pi|other> [--workspace <id>]` — connect an AI app to Xevol's MCP server in one step. You approve with a code in any browser, so it works over SSH; the app gets limited agent access (read and draft in one Workspace) and is listed under Settings → Connected AI agents. `other` prints the URL and header for any other MCP client.
 - `xevol login --agent --workspace <id>` — limited access for an AI agent (Claude Code, Codex): one Workspace, read and draft, never approve, send, publish or delete. Give agents this token, never the full one. Disconnect it in Settings.
 - `xevol logout` — revoke token + clear local config
 - `xevol whoami` — current authenticated account
 
-### Xevol Work CRM
+### Xevol Work
+- `xevol ads ...` — manage Ads projects, collections, creatives, formats, copy, links, status, archives, and history
 - `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 offers ...` — every Offers procedure used by Xevol Work Web, including profiles, status, snapshots, audiences, angles, artifacts, revisions, and reviewed generation
@@ -86,6 +88,45 @@ List commands also accept `--query`, `--page`, `--page-size`, `--sort`, and `--d
 
 Campaign execution commands keep the Work API's reviewed-policy and acknowledgement requirements. In particular, `campaign-execution-activate` can start sending and requires both `expectedEnrollmentCount` and `"acknowledgeSend": true`; the CLI supplies no bypass and the API rechecks current Workspace authority.
 
+### Ads manager
+
+Ads commands mirror the `ads.*` Work manager. They create and edit native records, upload
+formats, change status, archive and restore, and expose append-only change history. They
+do not run the operator importer, generate creative, publish, or manage ad-platform
+campaigns, targeting, budgets, spend, or attribution.
+
+```bash
+xevol ads projects --json
+xevol ads compare <left-creative-id> --right-id <right-creative-id> --json
+xevol ads project-create --name OwnScreen --json
+xevol ads create --project-id <project-id> --title "Shop-window film" --kind motion --language en --json
+xevol ads update <creative-id> --destination https://example.test --json
+xevol ads upload <creative-id> film.mp4 --name "4:5 film" --width 1080 --height 1350 --duration 15 --json
+xevol ads copy-add <creative-id> --content "Turn any TV into a sign" --json
+xevol ads status <creative-id> --status Live --note "AU+NZ" --json
+xevol ads archive <creative-id> --entity creative --json
+xevol ads restore <creative-id> --entity creative --json
+xevol ads history <creative-id> --json
+```
+
+`ads update` and `ads status` fetch the creative's current `updatedAt` when
+`--updated-at` is omitted. Other edits require the `updatedAt` read from the API, passed
+through `--updated-at` or JSON, so concurrent changes return `CONFLICT` instead of being
+overwritten. `ads upload` accepts PNG, JPEG, WebP, GIF and MP4 files up to 64 MiB; it
+handles the grant, byte upload, and direct-upload finalization as one command.
+
+Read commands remain available: `projects`, `list`, `get`, `documents`, `compare`, and
+`history`. `ads list` supports `--category`, `--kind image|motion|mixed`, `--label`,
+`--language`, `--creative-type`, `--medium`, and common paging/search flags. Its sort
+fields are `title`, `category`, `label`, `language`, and `creativeType`. The project
+filter uses the stable `sourceId` returned by `ads projects`; `ads documents` uses that
+project's record `id`.
+
+Editorial status and archive presence do not prove publication, performance, platform
+approval, or reuse rights. The selected Workspace and Ads module gate still apply.
+Workspace-bound agent access may create, edit, link and upload. It cannot run `status`,
+`archive`, or `restore`; those decisions require a full OWNER or MEMBER session.
+
 ### Imported source data
 
 Directory and Career source commands use the same Work API token, selected Workspace,
@@ -181,8 +222,9 @@ Add, upload, status, and retry use the selected Work Workspace's Creator gateway
 - `xevol resume <transcriptionId>` — resume interrupted stream session
 - `xevol prompts ...` — prompt CRUD/list/get
 
-### Usage, exports, locations
+### Usage, billing, exports, locations
 - `xevol usage` — plan + usage snapshot
+- `xevol billing [--workspace-id <id>] [--json]` — read the Workspace credit balance, monthly use, enforcement policy, and waiting-work count
 - `xevol export <id> --format json|markdown|text` — export content locally
 - `xevol coordinates current` — latest Xevol Coordinates context, with coordinates hidden unless `--exact`
 - `xevol coordinates current --json` — stable machine-readable current context for scripts/agents
@@ -200,7 +242,7 @@ Use `--agent-id` and `--agent-revision` together only when reading a legitimatel
 These commands require a Work API release that provides `agentSkills.discover` and `agentSkills.readRevision`. An older server returns `UNSUPPORTED_SERVER`; the CLI never falls back to the administrative skill-history surface.
 
 ### Interface
-- `xevol agent-help` — machine-oriented guide for agents/scripts using xevol-cli
+- `xevol agent-help` — guide for AI agents with agent access: what they can read and draft, and what only people decide
 - `xevol agent-help --json` — structured command/workflow guide for agents
 - `xevol tui` — interactive terminal UI