ente-cli 0.4.99 → 0.4.101

package/README.md

@@ -92,12 +92,46 @@ fallback. CLI pairing without `--agent`
 creates a named connection agent. MCP authorization creates a connection agent
 named for the client.
 
-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.
+Named profiles are optional when one global default is sufficient.
+Profile selection uses `--profile`, then `ENTE_PROFILE`, then the nearest bound
+ancestor of the current directory, then the global `config.toml` default.
+Folder bindings are machine-local in the Ente config directory's `bindings.json`;
+no repository file selects an identity. Paths resolve symlinks before matching.
+A selected missing profile fails instead of falling back to another identity.
+Complete `ENTE_API_URL` / `ENTE_API_KEY` overrides still replace file credentials;
+partial overrides fail closed. `auth status` reports credential source separately
+from `profileSource` and `boundDirectory`.
+
+```bash
+ente auth bind /absolute/operator/folder operator-name
+ente auth bindings --json
+ente auth status --profile operator-name --json
+ente auth unbind /absolute/operator/folder
+```
+
+Bind an existing authenticated profile. Nested bindings override their parents.
+Platform administration credentials stay separate and ignore folder bindings.
+Bindings are defaults, not a security boundary. Use a separate OS account or
+container when operators must not read each other's keys. Never commit a key
+or put it in a project `.env` file.
+
+Inspect the selected credential before work:
+
+```bash
+ente auth whoami --json
+ente agent permissions --json
+ente agent permissions --check "Work" --action write --json
+```
+
+`whoami` reports the selected profile and its resolution `source`, the agent ID,
+name, icon, mailbox, active state, home space, and live scopes. The permission
+list includes account-visible spaces denied to the key, with `access` of `none`,
+`read`, or `write`, and server-derived `canRead`/`canWrite` flags. Scopes and OAuth
+consent can restrict those flags independently. Account panel visibility is
+separate from operational access. `--check` accepts an exact space name or ID
+and `--action read|write`; denial exits nonzero and names the web app's
+**Agent actions** and Connections scope settings. These commands never grant
+rights, invoke a provider, or print keys.
 
 ## Usage
 
@@ -142,7 +176,7 @@ Every command supports `--json`. Run `ente --help` or `ente <group> --help`.
 
 | Group | Commands |
 |---|---|
-| `auth` | `pair`, `login`, `status`, `logout`, `profiles` |
+| `auth` | `pair`, `login`, `status`, `whoami`, `logout`, `profiles`, `bind`, `unbind`, `bindings` |
 | `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`, `transcript` (`--grep`, `--context`), `update`, `delete`, `restore`, `message add`, `attachment upload` |
 | `agenda` | `create-point`, `link-task` |
@@ -155,7 +189,7 @@ Every command supports `--json`. Run `ente --help` or `ente <group> --help`.
 | `canvas` | `boards`, `html list`, `html get`, `html create`, `html update`, `html delete` |
 | `files` | `list`, `upload` (local file at most 10 MiB, or an activity attachment), `link`, `create-folder` — the entity's Nextcloud folder via your own connection; personal agent key only (MCP: `entity_files_list`, `entity_file_upload`, `entity_folder_link`, `entity_folder_create`) |
 | `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` | `permissions`, `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` |
 
@@ -353,6 +387,17 @@ at most 20 address candidates with continuation. For example:
 ente agent user-mailbox --request '{"operation":"recipients","connectionId":"<permitted-private-connection>","query":"Alex Morgan"}'
 ```
 
+When asked to write a new email from the inbox with no message selected, open
+the draft first with one `editVisible` patch. Use an explicit address or a clear,
+explicitly requested contact already in the authorized captured context. Otherwise
+leave `draft.to` empty, including ambiguous, missing, incomplete or unavailable
+matches. Keep the requested subject and body; all fields may be empty for a blank
+email. Do not delay opening for lookup, history, provider research or clarification.
+Never pick an arbitrary candidate. Explain an unresolved name after preparing the
+draft. Later explicit recipient research retains the existing recency and access
+checks. Opening and autosaving a draft never authorizes sending.
+
+Outside inbox composition, use recipient resolution for missing requested names.
 For interactive name resolution, add `"resolve":true` (without `cursor`). The
 server discovers names and updates all candidate addresses in one recency pass.
 It uses a shared ceiling of 20 cached pages of at most 200 records (4000 reads
@@ -360,7 +405,8 @@ across both passes, with a separate byte bound per page), or 4 provider pages
 of at most 20 matching headers (80 fetched headers; native searches, metadata
 requests and retries are additional network operations). It returns terminal
 `resolutionComplete`, `discoveryComplete`, `recencyComplete` and budget metadata.
-If incomplete or truncated, ask for an explicit address or selection. Do not
+If incomplete or truncated, ask for an explicit address or selection before choosing
+a recipient; this does not block opening an inbox draft with an empty recipient. Do not
 claim uniqueness or latest contact, automatically restart resolution, or expand
 to provider research. Preserve all requested recipients. Provider source is for
 explicitly requested or necessary provider/older correspondence searches.
@@ -565,3 +611,16 @@ ente entity field remove <valueId>
 replaces that field's values; `"value":null` removes them. Entity `--attr` is
 retained only to report the moved-to-fields error. Activity/task/list attributes
 are unchanged. Entity reads expose field/value IDs, labels, types and text.
+
+### Experimental Ask availability
+
+Hosted `ente ask` is an opt-in beta for the existing private cohort, not a general
+AI chat or included-model execution API. Most accounts receive an explanation
+without model execution. Explicit own/instance Ask model slots retain their route.
+Use `ente search`, `ente entity get`, `ente activity search/list/get` and summarize
+records with your agent. Do not change provider/model settings to repair beta
+unavailability. Ask exits nonzero unless `synthesisStatus` is `answered`.
+
+Default/lexical `ente query` remains deterministic and available without AI.
+Hybrid/semantic query requires private beta enrollment and separate passage
+consent; unavailable responses point to ordinary commands and lexical query.

package/dist/SKILL.md

@@ -68,12 +68,43 @@ including cached JWT calls. There is no unrestricted user-key fallback. Create
 and manage keys from the agent’s Connections settings in `/agents`; several
 credentials can belong to the same agent.
 
-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.
+Named profiles are optional when one global default is sufficient.
+Resolve the profile in this order: `--profile`, `ENTE_PROFILE`, the nearest
+bound canonical ancestor of the current directory, then the global default.
+Machine-local `bindings.json` in the Ente config directory stores folder bindings;
+repositories carry no binding file. Symlinked folders resolve to their real path.
+A selected missing profile fails closed. Complete API URL/key environment overrides
+still replace stored credentials; check these separately from profile selection.
+`auth status --json` reports `profileSource` and `boundDirectory` separately from
+credential `source`. Bind only an existing authenticated profile:
+
+```bash
+ente auth bind /absolute/operator/folder operator-name
+ente auth bindings --json
+ente auth unbind /absolute/operator/folder
+```
+
+Bindings do not isolate secrets from other processes under the same OS user.
+Use separate OS accounts or containers for that isolation. Platform keys ignore
+folder bindings. Never store a key in a repository or project `.env` file.
+
+Inspect the selected credential before work:
+
+```bash
+ente auth whoami --json
+ente agent permissions --json
+ente agent permissions --check "Work" --action write --json
+```
+
+`whoami` reports the selected profile and its resolution `source`, the agent ID,
+name, icon, mailbox, active state, home space, and live scopes. The permission
+list includes account-visible spaces denied to the key, with `access` of `none`,
+`read`, or `write`, and server-derived `canRead`/`canWrite` flags. Scopes and OAuth
+consent can restrict those flags independently. Account panel visibility is
+separate from operational access. `--check` accepts an exact space name or ID
+and `--action read|write`; denial exits nonzero and names the web app's
+**Agent actions** and Connections scope settings. These commands never grant
+rights, invoke a provider, or print keys.
 
 Verify server access with `ente entity list --limit 1 --json`.
 
@@ -150,19 +181,24 @@ ente auth login --url <convex-site-url> --key-stdin
 ente auth status
 ente auth logout
 ente auth profiles
+ente auth bind <path> <profile>
+ente auth unbind <path>
+ente auth bindings [--json]
 
 # Search & ask
-# Ask keeps scoped evidence on synthesis failure; check synthesisStatus.
+# Ask is an experimental opt-in beta, not a general AI chat or included-model execution API.
+# Prefer ordinary search/entity/activity commands; unavailable beta is not a provider setup task.
+# Check the exit code and synthesisStatus; never present a failed/evidence-only result as an AI answer.
 # Optional sourceHash/sourceFingerprint/passage metadata binds citations to a source version.
 # query remains deterministic and never starts embedding/indexing. See guide ask-the-graph.
 ente search "Alice" [--type person] [--space <name>] [--limit 5] [--projection compact|full] [--json]
-ente ask "What's open with Erik?" [--space <name>] [--entity <name>] [--evidence] [--json]   # AI answer + citations
+ente ask "What's open with Erik?" [--space <name>] [--entity <name>] [--evidence] [--json]   # enrolled beta only: AI answer + citations
 ente query "QM system export" [--space <name>] [--entity <name>] [--since <epoch-ms>] [--until <epoch-ms>] [--limit 12] [--verbose] [--json]         # evidence only, no AI
 
 # Entities
 ente entity list [--query <text>] [--type person|org|project|topic|place|object] [--space <name>] [--limit <count>] [--projection compact|full] [--archived] [--json]
 ente entity create "Jane Doe" --type person [--pin "Acme Corp"] [--share-parents --parent-space-grant-fingerprint <token>] [--alias "JD"] [--field '{"label":"E-Mail","type":"email","value":"jane@acme.com"}'] [--tag vip] [--description "CTO at Acme"] [--json]
-ente entity create "Leistungsphase 1" --type topic --space "Studio" --parent "Building A" [--json]
+ente entity create "Leistungsphase 1" --type topic --space "Studio" --parent "Building A" [--parent-role "Mandant"] [--json]
 ente entity duplicate <name-or-id> --space <space> [--name "New project"] [--include-exclusive-children] [--json]
 ente entity get "Jane Doe" [--limit 20] [--hours-back <hours>] [--min-count 5] [--projection compact|full] [--json]
 ente entity update "Jane Doe" [--allow-non-exclusive-children | --disallow-non-exclusive-children] [--name "Jane A. Doe"] [--alias-add "Jane"] [--alias-remove "JD"] [--field '{"label":"Job title","type":"job-title","value":"CEO"}'] [--tag vip] [--description "…"] [--json]
@@ -216,7 +252,7 @@ ente canvas html delete <boardId> <elementId> [--json]
 # Entity files: the entity's linked Nextcloud folder, through YOUR own Nextcloud
 # connection. Works only with your personal agent's key; shared agents are refused.
 # MCP/REST: entity_files_list, entity_file_upload, entity_folder_link, entity_folder_create.
-ente files list <entityId> [--path "03 Unterlagen"] [--json]
+ente files list <entityId> [--path "03 Unterlagen"] [--json]   # --json: linkedFolderPath = the linked folder's path from your Nextcloud root; join it with an item path for the exact file
 ente files upload <entityId> <local-file> [--folder "03 Unterlagen"] [--name "Vertrag.pdf"] [--mime-type application/pdf] [--json]   # at most 10 MiB
 ente files upload <entityId> --activity <activityId> --storage-id <storageId> --name "Vertrag.pdf" [--folder …] [--json]   # copy an activity attachment
 ente files link <entityId> "Mandate/2026-017 Zebrafink" [--space <spaceId>] [--json]
@@ -396,7 +432,9 @@ not enter another browser's local undo stack.
 For entity files, `files list` returns a `status` (`ok`, `not_linked`, `not_connected`,
 `reconnect_required`, `no_access`, `folder_deleted`, `unreachable`, `unavailable`) instead of an
 empty list; tell the user to connect or reconnect Nextcloud in settings rather than retrying.
-Paths for `link`/`create-folder` are relative to the user's Nextcloud root; `--path`/`--folder`
+Paths for `link`/`create-folder` are relative to the user's Nextcloud root (where the space has a
+Nextcloud space folder they must lie inside it, e.g. `Kanzlei/Mandate/2026-017`; otherwise the
+reason is `outside_space_folder`); `--path`/`--folder`
 are relative to the entity's linked folder. Inline uploads are limited to 10 MiB; for an
 existing activity attachment pass `--activity` and `--storage-id` (from `activity get --json`).
 A taken file name gets a numbered suffix, nothing is overwritten. `--space` is needed only when
@@ -568,6 +606,17 @@ at most 20 address candidates with continuation. For example:
 ente agent user-mailbox --request '{"operation":"recipients","connectionId":"<permitted-private-connection>","query":"Alex Morgan"}'
 ```
 
+When asked to write a new email from the inbox with no message selected, open
+the draft first with one `editVisible` patch. Use an explicit address or a clear,
+explicitly requested contact already in the authorized captured context. Otherwise
+leave `draft.to` empty, including ambiguous, missing, incomplete or unavailable
+matches. Keep the requested subject and body; all fields may be empty for a blank
+email. Do not delay opening for lookup, history, provider research or clarification.
+Never pick an arbitrary candidate. Explain an unresolved name after preparing the
+draft. Later explicit recipient research retains the existing recency and access
+checks. Opening and autosaving a draft never authorizes sending.
+
+Outside inbox composition, use recipient resolution for missing requested names.
 For interactive name resolution, add `"resolve":true` (without `cursor`). The
 server discovers names and updates all candidate addresses in one recency pass.
 It uses a shared ceiling of 20 cached pages of at most 200 records (4000 reads
@@ -575,7 +624,8 @@ across both passes, with a separate byte bound per page), or 4 provider pages
 of at most 20 matching headers (80 fetched headers; native searches, metadata
 requests and retries are additional network operations). It returns terminal
 `resolutionComplete`, `discoveryComplete`, `recencyComplete` and budget metadata.
-If incomplete or truncated, ask for an explicit address or selection. Do not
+If incomplete or truncated, ask for an explicit address or selection before choosing
+a recipient; this does not block opening an inbox draft with an empty recipient. Do not
 claim uniqueness or latest contact, automatically restart resolution, or expand
 to provider research. Preserve all requested recipients. Provider source is for
 explicitly requested or necessary provider/older correspondence searches.
@@ -633,7 +683,7 @@ blocks. Use existing activity controls to correct thread space/owners.
 
 Entity duplication copies the type, name, description, email addresses, icon and enabled bottom-bar tabs in their configured order, database columns/filters/sorts, grouping rules and the calendar-sidebar list/Kanban preference into the selected source space. It never copies activities or existing parents. `--include-exclusive-children` is the compatibility name for recursively recreating branches whose selected parent is each child’s sole regular parent already in that space with exact child names, order and aggregation settings. Selected-child grouping rules refer only to copied aggregation-enabled direct children; excluded children are dropped from the rule. Classifier-parent branches and archived children are excluded. Extra classifier links are never copied. The operation fails atomically above 100 entities including the root. Use parent context or an ID to distinguish same-named phases across projects.
 
-`entity create --parent` atomically creates and attaches a child. Add `--exclusive-parent` to restrict it to that parent. The parent must already belong to the destination space; this path never shares it or its ancestors. Resolve same-named phases by parent context or ID. Do not combine `--parent` with `--pin`; `--pin` retains the older separate-link behavior.
+`entity create --parent` atomically creates and attaches a child. `--parent-role "Gegner"` sets the relationship role on that link in the same write (same rule as `entity pin --role`; requires `--parent`). Add `--exclusive-parent` to restrict it to that parent. The parent must already belong to the destination space; this path never shares it or its ancestors. Resolve same-named phases by parent context or ID. Do not combine `--parent` with `--pin`; `--pin` retains the older separate-link behavior.
 
 ## Reviewed space changes
 
@@ -736,8 +786,11 @@ task and relationship retrieval without provider calls. `--mode lexical` is the
 same default. Keep `ente search` for fuzzy entity lookup and `ente activity search`
 for ordinary title/body keyword search.
 
-Use `ente query "question" --mode hybrid --space Personal --json` only when semantic
-retrieval is wanted and consented. Hybrid retains typed deterministic structured
+Hybrid/semantic query is an experimental private opt-in beta. It is unavailable
+for most accounts; do not change model/provider settings or repeatedly retry to
+obtain enrollment. Use ordinary commands or lexical query instead.
+Use `ente query "question" --mode hybrid --space Personal --json` only when
+explicitly enrolled and semantic retrieval is wanted and consented. Hybrid retains typed deterministic structured
 results and combines lexical/vector activity passages. `--mode semantic` returns
 vector activity passages only, for inspection/comparison. Initial vectors cover
 only the caller's own Personal notes, conversations, meetings and calls. Related
@@ -780,3 +833,16 @@ conflicting children, including archived or inaccessible ones, without removing
 links. Legacy `--exclusive-parent` is accepted but inert after policy activation;
 it never sets the new parent setting. Existing Space confirmation and cycle
 rules still apply.
+
+### Ask beta availability
+
+Hosted `ente ask` is restricted to the existing private beta cohort. The local
+fictional equivalent is test@example.com on a loopback backend. This is separate
+from passage-index consent: enabling/disabling semantic retrieval does not enroll
+another account in hosted Ask. Explicitly configured own/instance Ask model slots
+retain their route and permissions. Ordinary paid plans do not enroll an account.
+If unavailable, use `ente search`, `ente entity get`, `ente activity search`,
+`ente activity list` and `ente activity get`, then summarize the returned records
+with your agent. Default/lexical `ente query` remains available without AI.
+`ask` returns a nonzero exit unless synthesisStatus is answered. Do not request
+a Bedrock key, provider access or model change to repair beta unavailability.