ente-cli 0.1.0 → 0.4.53

package/README.md

@@ -0,0 +1,274 @@
+# ente CLI
+
+Command-line interface for [ente](https://github.com/valentindoering/ente) — a
+relationship manager and knowledge graph (people, orgs, projects, topics and the
+notes/calls/tasks/conversations logged against them).
+
+TypeScript, built on [clipanion](https://clipanion.dev/), bundled with esbuild
+into a single self-contained file, published to npm and Ivo's Gitea npm registry. It talks
+to ente's external REST API (`/api/external/*`) with a static Bearer API key.
+
+## Install
+
+```bash
+npm i -g ente-cli
+# Ivo's registry remains available with the same package and version:
+npm i -g ente-cli --registry https://gitea.i.ivo-zilkenat.de/api/packages/ivo.zilkenat/npm
+```
+
+## Setup
+
+Connect a normal CLI profile with browser approval. Replace the site URL and
+email with your Ente deployment and account:
+
+```bash
+ente auth pair --url https://your-deployment.convex.site --email you@example.com
+```
+
+The CLI prints a review link and six-digit code. Open the link, sign in, inspect
+the requested profile, enter the code, and approve it. The CLI generates its
+key locally and sends its hash and short prefix to Ente. The full key stays
+local and never appears in the browser or terminal output. Keep the CLI running
+until it verifies the new profile.
+
+To connect an operator to one agent, use that agent's ID from `ente agent list`
+and name the local profile:
+
+```bash
+ente auth pair --url https://your-deployment.convex.site --email you@example.com \
+  --profile mail-operator --agent <agent-id> --access write
+```
+
+For up to ten operators, put the exact agent IDs and local profile names in a
+JSON file outside a repository:
+
+```json
+[
+  { "profile": "operator-a", "agentId": "<agent-id-a>", "access": "write" },
+  { "profile": "operator-b", "agentId": "<agent-id-b>", "access": "read" }
+]
+```
+
+```bash
+ente auth pair --url https://your-deployment.convex.site --email you@example.com \
+  --manifest /private/path/operators.json
+```
+
+One Ente approval page lists all profiles and scopes. Existing local profiles
+are never overwritten unless `--replace` is supplied. A stopped or expired CLI
+run must be started again. Pending requests expire after ten minutes.
+Both agent access modes can read and change Ente data and manage spaces.
+With `read`, the key can inspect the bound agent and inbox, mark inbox threads
+read/unread, and change their workflow state. `write` also permits agent
+changes and sending email. The CLI saves approved profiles before
+activating their keys, so a failed local save cannot leave active keys behind.
+
+For headless integrations or a legacy key, generate an API key in the web app
+and enter it directly in the terminal:
+
+```bash
+ente auth login --url https://your-deployment.convex.site --key-stdin
+```
+
+Credentials are stored at `~/.config/ente/config.toml` (`~/Library/Application
+Support/ente/config.toml` on macOS), `0600`. `ENTE_API_URL` and `ENTE_API_KEY`
+override the file only when both are set.
+
+An agent operator profile is bound to that agent's configuration, threads,
+scheduled runs, and inbox when enabled:
+
+```bash
+ENTE_PROFILE=mail-operator ente agent config show
+ENTE_PROFILE=mail-operator ente agent mail threads --unread
+```
+
+Operator keys use the CLI's scoped REST commands. They cannot be exchanged for
+the legacy full-account CLI session token, so the bound-agent restriction
+cannot be bypassed through direct Convex commands. Use a normal account key for
+legacy administrative CLI commands that require that session token.
+
+Named profiles are optional. Use one only when a person or process deliberately
+switches between several credentials. `--profile` overrides `ENTE_PROFILE`.
+Profiles do not activate from the current directory and are not a security
+boundary. Use a separate OS account or container when operators on the same
+machine must not read each other's keys. Never commit a key or put it in a
+project `.env` file.
+
+## Usage
+
+```bash
+ente search "Alice"
+ente entity list --type person
+ente entity rename "Lorey Georg" "Georg Lorey"
+ente task list --due today
+ente activity create --type note --title "Meeting notes" --entity "Alice" --space "Personal"
+ente activity get <activityId> --json # includes the body, nested agenda, messages/replies, entities, and attachments
+ente agenda create-point --meeting <meetingActivityId> --title "Decisions" --content="- Ship the smaller scope"
+ente agenda link-task --point <agendaPointId> --task "#12"
+ente activity message add <activityId> --content "Decision: ship the smaller scope first."
+ente activity content read <activityId> --json
+ente activity content edit <activityId> --expected-version 42 --operations-file edits.json --json
+ente canvas boards <entityId>
+ente canvas html create <boardId> --title "Prototype" --file ./prototype.html --operation-id prototype-v1
+ente notification send --subject "Weekly brief" --text "Your brief is ready." --html-file ./brief.html --attachment ./brief.pdf --inline-image chart=./chart.png
+ente agent config show
+ente agent threads
+ente agent mail threads --unread
+ente agent mail send --to person@example.net --subject "Update" --text "Plain fallback" --attachment ./handoff.md --html "<p><strong>Update</strong></p>" --idempotency-key agent-update-2026-09-01
+ente tasks
+ente guide              # concepts; `ente guide <topic>`: entities, tasks, activities, search, patterns, limits
+```
+
+Every command supports `--json`. Run `ente --help` or `ente <group> --help`.
+
+### Command groups
+
+| Group | Commands |
+|---|---|
+| `auth` | `pair`, `login`, `status`, `logout`, `profiles` |
+| `entity` | `list`, `create`, `get`, `update` (`--name`, `--tag`, `--description`), `rename`, `archive`, `restore` (`--share-parents` plus the returned grant fingerprint), `pin` (`--role`, optional confirmed parent grants), `unpin`, `add-to-space`, `remove-from-space` (`--remove-from-activities` optional) |
+| `activity` | `list`, `create`, `search`, `get`, `update`, `delete`, `restore`, `message add`, `attachment upload` |
+| `agenda` | `create-point`, `link-task` |
+| `task` | `list`, `get`, `create`, `update`, `done`, `assign`, `unassign`, `set-assignees`, `clear-assignees` |
+| `pins` | `list` |
+| `space` | `members` |
+| `recording` | `list`, `show`, `inspect`, `rerun` (admin only) |
+| `canvas` | `boards`, `html list`, `html get`, `html create`, `html update`, `html delete` |
+| `notification` | `send` (emails only your own Ente account address; optional HTML, file attachments, and CID inline images) |
+| `agent` | `list`, `threads`, `show`, `new`, `send`, `config show`, `config set-prompt`, `schedules configure` |
+| `agent mail` | `address`, `threads`, `show`, `send`, `reply`, `mark` |
+| top-level | `search`, `ask`, `query`, `tasks`, `guide` |
+
+### Agent operators and inboxes
+
+An agent operator key can read and change Ente data, manage spaces, and access
+one bound agent. Agent read includes Ente configuration such as the prompt,
+Ente thread history, scheduled-run configuration, inbox reads, and thread status
+updates when an inbox is active. Agent
+write additionally allows prompt changes, full scheduled-run replacement, and
+inbox send/reply. New write-capable keys also receive `agent:communicate`, which
+lets the bound external agent start, claim, and reply to external threads without
+calling an Ente-hosted model. Ente prompt and scheduled runs configure the Ente agent
+counterpart; they are not instructions or schedules for the external operator.
+The caller cannot select another agent, mailbox, or sender.
+The corresponding scopes are `agent:read`, `agent:write`, `mail:read`, and
+`mail:send`, and `agent:communicate`.
+
+The inbox owner must add each exact correspondent in Ente. Unlisted inbound
+mail stays owner-only and never appears in operator REST, MCP, WebMCP, or CLI
+reads. New sends and replies are rejected before persistence unless the final
+recipient is allowed. An administrator-granted unlimited-mail account may
+enable send-to-anyone or receive-from-anyone separately for each mailbox.
+
+```bash
+ente agent config show
+ente agent threads --include-archived --limit 20
+ente agent show <ente-thread-id>
+ente agent new "Can I publish this?" --title "Release note" --request text --idempotency-key release-question-1
+ente agent threads --attention agent
+ente agent send <ente-thread-id> "Published." --request ack --request-prompt "Release note published" --idempotency-key release-answer-1
+ente agent config set-prompt --text "Review finance updates."
+ente agent config set-prompt --file ./ente-agent-prompt.md
+ente agent schedules configure --file ./schedules.json
+ente agent mail address
+ente agent mail threads --unread --limit 20
+ente agent mail show <thread-id>
+ente agent mail send --to person@example.net --subject "Update" --text "Plain fallback" --html "<p>Rich update</p>" --attachment ./reference.pdf --idempotency-key update-2026-09-01
+ente agent mail reply <thread-id> --message <message-id> --text-file ./reply.txt --html-file ./reply.html --attachment ./handoff.docx --idempotency-key reply-2026-09-01
+ente agent mail mark <thread-id> --state-version 4 --handled
+```
+
+`schedules.json` is the complete replacement list. Omitted schedules are
+deleted:
+
+```json
+[
+  {
+    "enabled": true,
+    "prompt": "Review new finance mail and prepare follow-ups.",
+    "timeMinutes": 480,
+    "timezone": "Europe/Berlin"
+  }
+]
+```
+
+Send and reply support repeatable `--inline-image CONTENT_ID=PATH` alongside
+`--attachment PATH`. Supply HTML containing `<img src="cid:readiness">` and
+`--inline-image readiness=./readiness.png`. The CLI embeds local file bytes in
+the email; use CID images for private charts, never remote URLs or data URIs.
+Inline images must be PNG, JPEG, GIF, or WebP (verified by file signature).
+Content-IDs must be unique, case-sensitive, at most 128 characters, start with a
+letter or number, and contain only letters, numbers, `.`, `_`, `@`, or `-`.
+Every inline image must have a matching HTML CID reference, and every CID
+reference must have an image. Keep the complete report in the required plain-text
+fallback; HTML and images do not replace it.
+
+The combined limit is **four files** across ordinary attachments and inline
+images, **750,000 bytes per file** (3,000,000 decoded bytes total). Four Health
+charts fit only when no ordinary attachment is also sent. Five SaaS Spending
+charts exceed this limit and are rejected; inline images do not bypass it.
+For example:
+
+```bash
+ente agent mail send --to owner@example.net --subject "Readiness" --text-file ./report.txt --html-file ./report.html --inline-image readiness=./readiness.png --idempotency-key readiness-report-v1
+ente agent mail reply <thread-id> --message <message-id> --text-file ./report.txt --html-file ./report.html --inline-image readiness=./readiness.png --attachment ./notes.txt --idempotency-key readiness-reply-v1
+```
+
+Retries must keep filenames, MIME types, Content-IDs, file order, and exact file
+bytes unchanged, along with the recipient, text, HTML, and reply target. A changed
+image or CID with the same key is rejected. Reported `sent` means transport
+accepted the message; delivery feedback may later report delivered, delayed,
+bounced, or complained. An unknown delivery outcome must never be retried with a
+new key.
+
+`--text` and `--html` accept inline strings. Their `--text-file` and
+`--html-file` counterparts read UTF-8 files. After an ambiguous timeout, retry
+the exact same operation with the same `--idempotency-key`; changing the body,
+recipient, thread, or message requires a new key.
+
+### Operational recipes (playbooks)
+
+Copy-pasteable, task-oriented recipes live in [`playbooks/`](./playbooks/) — log a
+meeting, rename/merge an entity, work around cross-space linking, etc. Start there
+for "how do I do X".
+
+## Develop in-repo / build
+
+```bash
+pnpm setup:cli                     # from the repository root; once per checkout
+cd cli
+pnpm dev entity list                # run from source via tsx
+pnpm typecheck                      # the build-from-truth gate (tsc --noEmit)
+pnpm build                          # → dist/cli.mjs (+ dist/SKILL.md)
+```
+
+The CLI is not a workspace member. `pnpm setup:cli` installs its locked
+dependencies separately. The repository's `pnpm check` typechecks and tests the
+CLI without installing dependencies.
+
+Publishing is automatic: a push to `main` touching `cli/**` or the publish
+workflow selects a version above both registries, tests and packs once, then
+publishes identical bytes to npm and Gitea. npm uses GitHub OIDC; Gitea keeps
+the existing package token. See `.github/workflows/publish-cli.yml` and
+`docs/cli-architecture.md` for setup and retry instructions.
+
+## Architecture
+
+```
+core/    brand-neutral: transport (REST/fetch), config, output, errors, update, command base.
+ente/    branded: the /api/external client, types, resolve, deadline, formatters, commands/*.
+cli.ts   clipanion bootstrap: registers every command group.
+```
+
+The dependency direction is one-way — `ente/` imports `core/`, never the reverse.
+See [`CLAUDE.md`](./CLAUDE.md) for the layering rules and conventions.
+
+## Public installation and recovery guide
+
+This is the Ente private knowledge-graph / relationship-manager CLI at ente.fast,
+not Ente Photos. Follow https://ente.fast/cli.md for new installations, upgrades,
+PATH conflicts, configuration reuse, legacy API keys, and stale authentication.
+Keep working credentials. `ente auth status --json` reports local configuration
+without key material; verify server access with `ente entity list --limit 1 --json`.
+Use `auth login --key-stdin` for hidden local key entry as shown in the guide.
+Never put secrets in chat, repositories, project `.env` files, or logs.

package/dist/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: m:ente-cli
+description: "Cli: drives the ente CRM and knowledge graph over its Convex API as the signed-in user — entities (people, organisations, projects, topics), activities (notes, calls, meetings, tasks), relationships, spaces, full-text and AI-backed search, agent threads and mail, plus Excalidraw canvas prototypes. Use when context about a person, an organisation or a meeting has to be stored, looked up or updated from the shell. Not for splitting shared costs, which is schnorrer-cli."
+when_to_use: "Remembering what was said in a call or meeting; looking up open tasks, deadlines or follow-ups for a person or project; creating or renaming an entity and pinning it to a parent; linking an activity to several entities or moving it between spaces; asking a question over the whole graph and getting citations; reviewing the voice-recording prompt or debugging a failed recording; sending a notification mail or an agent-inbox reply; posting to the in-app feedback board; managing Excalidraw canvas HTML prototypes on an entity board."
+metadata:
+  short-description: Relationship memory through ente
+---
+
+# ente-cli - CRM & Relationship Manager CLI Skill
+
+ente is a CRM / relationship manager that tracks people, organisations, projects, and topics (entities), and logs notes, calls, tasks, and conversations (activities) against them. This skill wraps the `ente` CLI so an agent can manage entities, activities, tasks, pins, and search end-to-end.
+
+---
+
+## Prerequisites
+
+This is Ente’s private knowledge-graph / relationship-manager CLI at ente.fast,
+not Ente Photos. For installation, upgrades, PATH conflicts, and recovery, follow
+https://ente.fast/cli.md. Honor an explicit CLI request even if MCP works;
+otherwise MCP remains the default for ordinary remote access.
+
+Reuse an existing working configuration. Never generate another key merely
+because the CLI was upgraded. Check locally, then verify with a read-only call:
+
+```bash
+ente auth status --json
+ente entity list --limit 1 --json
+```
+
+Auth status reports local configuration, not server validity. Only the read
+verifies access. Upgrade older releases if --json prints text.
+If no valid profile exists, run `ente auth pair --url <convex-site-url> --email
+<account-email>`. Open the printed Ente review link for the user and ask them to
+compare and enter the printed six-digit code on that page. Keep the command
+running until it reports verification. The CLI creates the key locally and
+passes its hash and short prefix to Ente. The full key stays local.
+Never collect secrets in chat, repositories,
+project `.env` files, or logs. A legacy key can still be entered with
+`ente auth login --url <convex-site-url> --key-stdin`.
+
+The current CLI reuses the legacy config.toml in the platform user configuration
+directory (macOS: ~/Library/Application Support/ente; Linux: ~/.config/ente).
+The complete ENTE_API_URL / ENTE_API_KEY environment pair overrides that file.
+Partial overrides fail closed. Check the selected profile and stale environment
+overrides before replacing credentials. Never print their secret values.
+
+For an agent operator, pair a named profile with the exact agent ID and scope.
+For several operators, pass a JSON manifest with up to ten `{ profile, agentId,
+access }` entries. The Ente page shows the complete set for one approval:
+
+Both agent access modes can read and change Ente data and manage spaces. With
+`read`, the key can inspect the bound agent and inbox, mark inbox threads
+read/unread, and change their workflow state. `write` also permits agent
+changes and email sending.
+
+```bash
+ente auth pair --url <convex-site-url> --email <account-email> --profile operator-name --agent <agent-id> --access write
+ente auth pair --url <convex-site-url> --email <account-email> --manifest /private/path/operators.json
+ENTE_PROFILE=operator-name ente agent config show --json
+ENTE_PROFILE=operator-name ente agent mail threads --unread --json
+```
+
+Operator keys use scoped REST commands and cannot mint the legacy full-account
+CLI session token. This preserves the one-agent boundary. A normal account key
+is still required for legacy administrative commands that call Convex
+functions directly.
+
+Named profiles are optional and only needed to switch deliberately between
+credentials. `--profile` overrides `ENTE_PROFILE`. Profiles do not activate
+from the current directory and do not isolate secrets from other processes
+running as the same operating-system user. Use a separate OS account or
+container when that isolation matters. Never store a key in the repository or
+a project `.env` file.
+
+Verify server access with `ente entity list --limit 1 --json`.
+
+Install / upgrade the CLI from npm:
+```bash
+npm i -g ente-cli --registry https://registry.npmjs.org
+```
+
+---
+
+## Important Notes
+
+- **Install targets**: The CLI writes this skill to supported app paths when they exist: `~/.claude/skills/ente-cli/SKILL.md` and `~/.codex/skills/ente-cli/SKILL.md`.
+- **Proactive triggers**: meeting logs, inbox context capture, promise/follow-up tracking, and people/org/project memory updates.
+- **Entity resolution**: Entity names are resolved via fuzzy search. Pass a name or a Convex ID (long alphanumeric string, 20+ chars). If ambiguous, the CLI lists matches and asks for a specific ID.
+- **Space resolution**: Space names work the same way — exact match first, then substring. Use `--space` to target a workspace.
+- **--json flag**: Every command supports `--json`. Always use `--json` when parsing output programmatically.
+- **Deadlines**: stored as millisecond epochs; displayed as `DD.MM.YYYY` / `DD.MM.YYYY, HH:MM` in Europe/Berlin.
+- **Entity types**: `person`, `org`, `project`, `topic`
+- **Activity types**: `note`, `conversation`, `meeting`, `call`, `message`, `task`
+
+---
+
+## Quick Reference
+
+```bash
+# Auth
+ente auth pair --url <convex-site-url> --email <account-email> [--profile <name>] [--agent <agent-id> --access read|write] [--manifest <json-file>]
+ente auth login --url <convex-site-url> --key-stdin
+ente auth status
+ente auth logout
+ente auth profiles
+
+# Search & ask
+ente search "Alice" [--type person] [--json]
+ente ask "What's open with Erik?" [--space <name>] [--entity <name>] [--evidence] [--json]   # AI answer + citations
+ente query "QM system export" [--space <name>] [--entity <name>] [--verbose] [--json]         # evidence only, no AI
+
+# Entities
+ente entity list [--query <text>] [--type person|org|project|topic] [--space <name>] [--limit 50] [--archived] [--json]
+ente entity create "Jane Doe" --type person [--pin "Acme Corp"] [--share-parents --parent-space-grant-fingerprint <token>] [--alias "JD"] [--attr email=jane@acme.com] [--tag vip] [--description "CTO at Acme"] [--json]
+ente entity get "Jane Doe" [--json]
+ente entity update "Jane Doe" [--name "Jane A. Doe"] [--alias-add "Jane"] [--alias-remove "JD"] [--attr role=CEO] [--tag vip] [--description "…"] [--json]
+ente entity rename "Lorey Georg" "Georg Lorey"        # change display name
+ente entity pin "Jane Doe" "Acme Corp" [--role "student"] [--share-parents --parent-space-grant-fingerprint <token>] [--json]
+ente entity unpin "Jane Doe" "Acme Corp" [--json]
+ente entity add-to-space "Jane Doe" --space "Team" [--share-parents --parent-space-grant-fingerprint <token>] [--json]
+ente entity remove-from-space "Jane Doe" --space "Team" [--remove-from-activities] [--json]
+ente pins list "Jane Doe" [--json]                    # relationships whose endpoints are accessible
+ente entity archive "Old Project" [--json]
+ente entity restore <entity-id> [--share-parents --parent-space-grant-fingerprint <token>] [--json]
+
+# Activities
+ente activity list [--entity "Jane"] [--type note|conversation|meeting|call|message|task] [--attr k=v] [--only-open] [--hours 168] [--limit 20] [--sort deadline|created] [--json]
+ente activity create --type meeting --title "Call with Jane" --entity "Jane Doe" --entity "Acme Corp" --space "Work" [--content "…"] [--content-file ./notes.md] [--auto-link --entity-space-grant-fingerprint <token>] [--json]
+ente activity search "quarterly review" [--entity "Acme"] [--type meeting] [--limit 10] [--json]
+ente activity get <activityId> [--json]                # complete detail: body, full nested agenda, messages/replies, entities, attachments
+ente activity update <activityId> [--title "…"] [--content "…"] [--entity-add "Bob"] [--entity-remove "Carol"] [--json]
+ente activity content read <activityId> [--cursor <cursor> --expected-version <version>] [--max-blocks 20] [--max-characters 12000] [--json]
+ente activity content edit <activityId> --expected-version <version> --operations-file ./operations.json [--json]
+ente activity message add <activityId> (--content "…" | --content-file ./update.md) [--json]
+ente activity attachment upload <activityId> ./file.pdf [--name "Contract.pdf"] [--json]
+ente activity delete <activityId> [--json]
+ente activity restore <activityId> [--json]
+
+# Meeting agendas
+ente agenda create-point --meeting <meetingActivityId> --title "Decisions" [--content="…"] [--content-file ./decisions.md] [--parent <agendaPointId>] [--after <agendaPointId>] [--json]
+ente agenda link-task --point <agendaPointId> --task <activityId|#N> [--json]
+
+# Excalidraw Canvas HTML prototypes
+ente canvas boards <entityId> [--json]
+ente canvas html list <boardId> [--json]
+ente canvas html get <boardId> <elementId> [--json]
+ente canvas html create <boardId> --title "Prototype" --file <html-path|-> [--placement below_content|empty_region|manual] [--direction right|down|left|up] [--x N --y N] [--width N --height N] [--operation-id <stable-key>] [--json]
+ente canvas html update <boardId> <elementId> --file <html-path|-> [--title "Revised"] [--x N --y N] [--width N --height N] [--json]
+ente canvas html delete <boardId> <elementId> [--json]
+
+# Tasks (activities with type=task; short-ids #N, deadlines, assignees)
+ente tasks [--json]                                    # open tasks by deadline
+ente task list [--due today|overdue|all] [--entity "Jane"] [--json]
+ente task get 5 [--space "Work"] [--json]
+ente task create "Reply to Jane" --entity "Jane Doe" --space "Personal" [--deadline "2026-05-23 14:00"] [--content "…"] [--assignee <userId-or-email>] [--json]
+ente task update 5 [--title "…"] [--content "…"] [--deadline "2026-05-26"] [--attr k=v] [--json]
+ente task done 5 [--json]
+ente space members --space "Work" [--json]
+ente task assign 5 <userId-or-email> [--json]
+ente task unassign 5 <userId-or-email> [--json]
+ente task set-assignees 5 --assignee <userId-or-email> [--json]
+ente notification send --subject "Weekly brief" --text "Your brief is ready." [--html-file ./brief.html] [--attachment ./handoff.md] [--image ./attachment.png] [--inline-image chart=./chart.png] [--json]
+ente task clear-assignees 5 [--json]
+
+# Bound Ente agent (operator key)
+ente agent config show [--json]
+ente agent threads [--include-archived] [--limit 20] [--json]
+ente agent threads [--attention user|agent|none] [--json]
+ente agent show <ente-thread-id> [--json]
+ente agent new "Question" [--title "Title"] [--request none|ack|text] [--request-prompt "Prompt"] [--html-file ./message.html] [--idempotency-key <stable-key>] [--json]
+ente agent send <ente-thread-id> "Reply" [--request none|ack|text] [--request-prompt "Prompt"] [--html-file ./message.html] [--idempotency-key <stable-key>] [--json]
+ente agent config set-prompt (--text "New prompt" | --file ./prompt.md) [--json]
+ente agent schedules configure --file ./schedules.json [--json]
+
+# Agent inbox (available when the bound agent has an active inbox)
+# The owner must first add each exact correspondent in Ente inbox settings.
+# Unlisted inbound mail is owner-only and is absent from CLI reads. Sends and
+# replies fail unless the final recipient is allowlisted (or an admin-granted
+# unlimited account enabled send-to-anyone for this mailbox).
+ente agent mail address [--profile <name>] [--json]
+ente agent mail threads [--profile <name>] [--unread] [--needs-reply] [--limit 20] [--cursor <cursor>] [--json]
+ente agent mail show <thread-id> [--cursor <cursor>] [--json]
+ente agent mail send --to person@example.net --subject "Update" --text "Plain fallback" [--html "<p>Rich update</p>" | --html-file ./message.html] [--attachment ./reference.pdf] [--idempotency-key <stable-key>] [--json]
+ente agent mail reply <thread-id> --message <message-id> (--text "Reply" | --text-file ./reply.txt) [--html "<p>Reply</p>" | --html-file ./reply.html] [--attachment ./handoff.docx] [--idempotency-key <stable-key>] [--json]
+ente agent mail mark <thread-id> --state-version <version> (--handled | --open | --needs-reply | --read | --unread) [--json]
+```
+
+Agent operator credentials are bound server-side to one exact agent. Agent read
+adds `agent:read` and, while the inbox is active, `mail:read`. Agent write adds
+`agent:write`, `agent:communicate`, and, while the inbox is active, `mail:send`.
+Use `agent threads --attention agent`, then `agent send`; the CLI claims the current
+attention version before replying so concurrent cron workers cannot duplicate work.
+The prompt and
+scheduled runs are Ente configuration for the Ente agent counterpart. They are
+not work instructions or scheduler settings for the external operator. The key
+cannot select a different agent, mailbox, or sender. All authenticated commands
+accept optional `--profile <name>`; use `ENTE_PROFILE` only when a launcher must
+select one of several stored credentials.
+Send and reply support repeatable `--inline-image CONTENT_ID=PATH` alongside
+`--attachment PATH`. Supply HTML containing `<img src="cid:readiness">` and
+`--inline-image readiness=./readiness.png`. The CLI embeds local file bytes in
+the email; use CID images for private charts, never remote URLs or data URIs.
+Inline images must be PNG, JPEG, GIF, or WebP (verified by file signature).
+Content-IDs must be unique, case-sensitive, at most 128 characters, start with a
+letter or number, and contain only letters, numbers, `.`, `_`, `@`, or `-`.
+Every inline image must have a matching HTML CID reference, and every CID
+reference must have an image. Keep the complete report in the required plain-text
+fallback; HTML and images do not replace it.
+
+The combined limit is **four files** across ordinary attachments and inline
+images, **750,000 bytes per file** (3,000,000 decoded bytes total). Four Health
+charts fit only when no ordinary attachment is also sent. Five SaaS Spending
+charts exceed this limit and are rejected; inline images do not bypass it.
+For example:
+
+```bash
+ente agent mail send --to owner@example.net --subject "Readiness" --text-file ./report.txt --html-file ./report.html --inline-image readiness=./readiness.png --idempotency-key readiness-report-v1
+ente agent mail reply <thread-id> --message <message-id> --text-file ./report.txt --html-file ./report.html --inline-image readiness=./readiness.png --attachment ./notes.txt --idempotency-key readiness-reply-v1
+```
+
+Retries must keep filenames, MIME types, Content-IDs, file order, and exact file
+bytes unchanged, along with the recipient, text, HTML, and reply target. A changed
+image or CID with the same key is rejected. Reported `sent` means transport
+accepted the message; delivery feedback may later report delivered, delayed,
+bounced, or complained. An unknown delivery outcome must never be retried with a
+new key.
+
+`--text` and `--html` accept inline strings; use the
+corresponding `--*-file` option for UTF-8 files. If a send or reply returns an
+ambiguous timeout, retry the exact operation with the same
+`--idempotency-key`. Use a new key whenever any payload field changes.
+
+For a focused update to an existing long body, use `activity content read`, select the returned
+version-scoped block targets, then call `activity content edit` with the exact `contentVersion`.
+The operations file is either a JSON array or `{ "operations": [...] }`; supported operation types
+are `replaceBlock`, `insertBefore`, `insertAfter`, `deleteBlock`, `replaceText`, and `append`.
+Use `replaceText` with a unique exact Markdown substring for file-patch-like changes inside a large
+block. Partial Markdown edits preserve existing rich blocks but do not create interactive HTML
+blocks; use the dedicated HTML block commands for those. If the version conflicts, reread and
+reconsider the edit; never overwrite newer content.
+Keep `activity update --content-file` for deliberate whole-document imports or rewrites, and use
+`activity message add` for chronological progress that belongs outside the main body.
+
+For a Canvas prototype, resolve the entity ID, call `canvas boards`, and insert the source with a
+stable `--operation-id`. Prefer `below_content` for a predictable append or `empty_region` when the
+board is already dense. The create result includes `reviewPath`. Update and delete perform a fresh
+read and fail on a concurrent human edit. These remote scene changes sync into open boards, but do
+not enter another browser's local undo stack.
+
+### Recording (voice) pipeline
+
+```bash
+ente recording-pipeline show [--json]                          # prompt + dictionary
+ente recording-pipeline set-prompt "<text>" | --file <path|-> | --edit
+ente recording-pipeline reset-prompt                           # clear → starter regenerated next run
+ente recording-pipeline set-dictionary "<text>" | --file <path|-> | --edit
+```
+
+- Edits **your own** user's voice-pipeline settings (same functions as web Settings → Voice pipeline).
+- `set-prompt`/`set-dictionary` are full replacements; exactly one source (`<value>` | `--file` | `--edit`).
+
+### Own models (own-models plan only)
+
+Users on the hidden €0 own-models plan bring OpenAI-compatible endpoints (e.g. LiteLLM). Ente then sends their content only to those endpoints; a feature stays disabled until its slot has a model.
+
+```bash
+ente models status                                         # slots, connections, web search
+printf %s "$KEY" | ente models connection add LiteLLM --base-url https://llm.example.eu/v1 --api-key-stdin
+ente models set agent LiteLLM claude-sonnet                # slots: agent ask recording transcription summary small
+ente models test [slot]                                    # real request; agent/ask/recording must call a tool
+ente models web-search on|off                              # Linkup web search for the agent (default off)
+ente users set-plan <email> own_models                     # admin: move a user onto the plan
+```
+
+### Recordings (admin — debug a failing recording)
+
+```bash
+ente recording list [--user <email|id>] [--status error] [--limit 20] [--json]
+ente recording show <recordingId> [--json]        # status, error, transcript size, activity count
+ente recording inspect <recordingId> [--json]     # audio container: brands, fragmented?, box counts
+ente recording rerun <recordingId> [--wait] [--timeout 900] [--json]
+```
+
+- Admin-only (`api.admin.recordings.*`); the ordinary `recordings.*` API is creator-scoped.
+- `rerun` never modifies or deletes the stored audio; `--wait` polls to `done`/`error` and exits non-zero on failure.
+- `--status` scans newest-first and says so when the sweep is capped.
+
+### Feedback board
+
+```bash
+ente feedback send "<summary>" [--category missing|confusing|wrong_data|workflow|bug|other] \
+  [--situation "…"] [--goal "…"] [--need-to-see "…"] [--need-to-do "…"] [--reason "…"] [--workaround "…"]
+ente feedback list [--status offen|todo|bearbeitung|klaerung|abgeschlossen|spaeter] [--text "…"] [--limit 50] [--json]
+ente feedback view <feedbackId> [--json]                 # full item + comment thread
+ente feedback comment <feedbackId> "<body>"              # reply on the thread
+ente feedback status <feedbackId> <status>               # move to a board column
+```
+
+- Same in-app feedback board as the web composer (`convex/feedback.ts` public functions) — no GitHub issue.
+- Every authenticated user may submit and manage the shared board. Screenshots/attachments are web-composer only.
+
+### Deadline formats
+
+| Input | Interpretation |
+|---|---|
+| `tomorrow` / `tomorrow 14:00` | Tomorrow 22:00 / 14:00 Berlin |
+| `today` / `today 14:00` | Today 22:00 / 14:00 Berlin |
+| `+3 days` / `+1 week` | Relative, 22:00 Berlin |
+| `2026-03-15` / `2026-03-15 14:00` | That date (22:00 default) Berlin |
+| `2026-03-15T14:00:00+01:00` | ISO 8601 with offset |
+
+---
+
+## Limits & boundaries
+
+- **Rename is supported**: `ente entity rename "<old>" "<new>"` (or `entity update <id> --name`).
+- **Relationships are spaceless**, but access propagates upward through the active graph. Every active parent and ancestor must belong to every active child space. A failed write returns the exact grant preview and `grantFingerprint`; retry with `--share-parents --parent-space-grant-fingerprint <token>` so concurrent graph changes cannot expand the approved grant set.
+- **Activity ownership stays inside its space.** An entity cannot leave a space while it owns activities there. Use `--remove-from-activities` to remove all affected ownership links when every activity has another owner.
+- **Cross-space linking is bounded**: an activity can only link entities already in its target space. A failed write returns the exact entity-space grant fingerprint. Retry with `--auto-link --entity-space-grant-fingerprint <token>` only after confirming that exact grant set; concurrent hierarchy changes fail closed.
+- **Merging duplicates and adding an entity to a shared space are web-UI only** — there is no API endpoint. Run `ente guide limits` for the full rundown.
+
+---
+
+## Workflow pattern
+
+1. **Check auth** — `ente auth status` before data commands.
+2. **Search first** — `ente search "name" --json` before creating entities (avoid duplicates).
+3. **Identify entities** — find the most specific existing owners; inspect direct children when a broad project or organization matches.
+4. **Determine space** — personal for private notes, shared for team-visible activities.
+5. **Operate** — entity/activity/task CRUD (prefer `--json` for parsing).
+6. **Link precisely** — link independently central entities, prefer specific children, and omit ancestors that are implied by hierarchy.
+7. **Confirm** — re-run the relevant list/get after writes to verify.
+
+---
+
+## Error handling
+
+- **"Not authenticated"**: run `ente auth login`.
+- **"Ambiguous match"**: multiple entities match — use the full Convex ID.
+- **"No entity found"**: check spelling, try `ente search`.
+- **"not in '<space>'" (cross-space)**: confirm the listed grants, then retry with `--auto-link --entity-space-grant-fingerprint <token>`, or add the entity to that space in the web UI.
+- **"Cannot remove all entities"**: an activity must keep at least one entity.
+
+Parent relationships are spaceless. Both entities must be accessible. Every active parent and ancestor must belong to every active child space. Commands that would expand parent access fail with a grant preview and fingerprint. Retry with both confirmation flags. A parent cannot be removed from a space while an active child remains there.