xevol 0.14.0 → 0.15.0

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
 
@@ -52,7 +52,10 @@ xevol workspace switch <workspace-id>
 - `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 brands ...` — Brands: list, get, create, update, sourced facts, pinned files (logo, font, picture, product), Knowledge links, motion kits and managers
+- `xevol files put <file> <path>` — upload a local file to a Workspace Files path (up to 20 MiB), e.g. a product photo to pin on a Brand
 - `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
@@ -61,6 +64,11 @@ xevol workspace switch <workspace-id>
 - `xevol career ...` — read-only source job browsing and detail, separate from personal Matches and Pursuits
 - `xevol deals ...` — list, get, create, update, and stage management
 - `xevol activities ...` — record timelines, counts, personal tasks, activity creation, and task completion
+- `xevol sites ...` — local-business sites: make one from a Google listing, draft, keep or discard, preview links, publish, domains, the client's approval, paid-until, word edits and the weekly report
+- `xevol motion ...` — a Brand's videos, pictures and voice-overs: plan, render, contact sheets, video sets (paid work uses the Workspace's credits)
+- `xevol social ...` — connected social accounts and publications: draft, edit, list, cancel, retry. Approving a post and connecting an account happen in Xevol's browser app
+- `xevol newsletter ...` — lists, subscribers, drip sequences, campaigns, reports and sending domains. Adding subscribers, test sends, activating sequences and approving campaigns happen in Xevol's browser app
+- `xevol workflows ...` — draft, check and start workflows; runs, tasks, ready-made jobs; complete an external task. Activating, pausing and cancelling happen in Xevol
 - `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:
@@ -87,6 +95,62 @@ 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
+also start paid generated batches (template or photo ads), follow them, keep or reject the
+results and save the zip. They do not run the operator importer, 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
+```
+
+Generated batches, end to end (a person's token; an agent may submit and read, while
+`batch-review`, `batch-export`, `brands pin` and the use class stay with a person):
+
+```bash
+xevol brands create --file brand.json --json
+xevol brands add-fact <brand-id> --input '{"kind":"PRODUCT","text":"...","sourceUrl":"https://..."}' --json
+xevol files put app.png /Brands/anglokit/app.png --json
+xevol brands pin <brand-id> --input '{"role":"PRODUCT","path":"/Brands/anglokit/app.png","rightsAttested":true,"product":{"name":"Anglokit","kind":"SCREEN","text":"..."}}' --json
+xevol ads batch-submit --file batch.json --json   # "photo":{"productAssetId":"<asset-id>"} for photo ads
+xevol ads batch-watch <set-id>
+xevol ads batch <set-id> --json                    # concepts, candidates, check verdicts and reasons
+xevol ads batch-review --input '{"setId":"<set-id>","creativeIds":["<id>"],"status":"Selected"}' --json
+xevol ads batch-export <set-id> --json             # makes missing formats (the photo 9:16 is paid once)
+xevol ads batch-download <set-id> anglokit.zip
+```
+
+`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,
@@ -169,22 +233,33 @@ Work and system commands return `xevol.cli/v1` envelopes in `--json` mode and ke
 - `xevol add --file source.pdf --lang en` — upload PDF, UTF-8 text, audio, or video
 - `xevol retry <id> --regenerate --lang en` — regenerate saved content on the same transcription
 
-Add, upload, status, and retry use the selected Work Workspace's Creator gateway. Retained authority still routes to Creator; exclusive Native authority uses canonical Work ingestion. Use `--operation-id <id>` on a single add/upload/retry to repeat an uncertain response without starting another import. Audio/video requires the Agent's optional ASR configuration.
+Add, upload, status, and retry use the selected Work Workspace's Creator gateway. Retained authority still routes to Creator; exclusive Native authority uses canonical Work ingestion. Use `--operation-id <id>` on a single add/upload/retry to repeat an uncertain response without starting another import. Audio/video is hashed locally and uploaded straight to the Cloudflare transcription gateway; Work only receives its name, size and SHA-256.
 - `xevol create [text]` — create from text/file/url/stdin/editor
 - `xevol list` — list transcriptions
 - `xevol view <id>` — view summary/content
 - `xevol delete <id>` — delete transcription
 - `xevol open <id>` — open item in browser
 
+### Direct transcription (Cloudflare gateway)
+- `xevol transcribe <file>` — transcribe a local audio/video file; the bytes go straight to the Cloudflare gateway, never through Work
+- `xevol transcribe <file> --no-wait --json` — submit and print the stable job id
+- `xevol transcribe --job <id> --stream --json` — resume events over SSE as NDJSON (`--after <cursor>` replays from a cursor)
+- `xevol transcribe --job <id> --format json|txt|srt|vtt --output <path>` — export with SHA-256 verification
+- `xevol transcribe --job <id> --cancel` — request cancellation (Ctrl-C only closes the stream)
+
 ### Analysis & prompts
 - `xevol analyze <id> --prompt <promptId>` — create/read spike output
 - `xevol stream <spikeId>` — SSE stream spike content
 - `xevol resume <transcriptionId>` — resume interrupted stream session
 - `xevol prompts ...` — prompt CRUD/list/get
 
+Every Work command runs with your rights in the Workspace you pick: FORBIDDEN when you lack the role (Brand manager, Workspace owner), PRECONDITION_FAILED when the Workspace's plan does not include the module, PAYMENT_REQUIRED when credits, the monthly cap or the subscription stop paid work. Commands marked "people only" are refused for agent tokens. Approving posts and campaigns, connecting accounts, adding subscribers and cancelling workflow runs need Xevol's browser app.
+
 ### 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 saved list|process|to-knowledge|copy-to|remove` — read and use what you saved
+- `xevol saved import <export-folder> [--apply] [--workspace-id <id>] [--json]` — bring a Telegram Desktop Saved Messages export (JSON, with media) into Saved. Without `--apply` it only reports counts, file sizes, what is left out and the credits needed; with it, one message at a time, skipping anything already imported, so the same command resumes. One credit per stored file; nothing is processed
 - `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