ente-cli 0.4.68 → 0.4.70

package/README.md

@@ -401,3 +401,25 @@ Updating replaces agent assignees and preserves human assignees. Use
 `--clear-agent-assignees` to remove them. Only active agents with write access qualify.
 
 Scheduled runs also accept `runCondition: "new_chats"`: skip model execution unless this agent has new manual or recording chats since its previous scheduled check. Scheduled/reflection chats do not trigger it; explicit Run now bypasses the condition.
+
+## Bounded retrieval and machine failures
+
+Use `query --space <name-or-id> --entity <name-or-id> --since <epoch-ms>
+--until <epoch-ms> --limit 8 --json` for deterministic evidence without a model.
+Time filters apply to activity evidence. Resolve entity identity globally first.
+
+`activity list --entity <id> --compact --limit 10 --json` returns one compact
+history page. Follow `nextCursor` with `--cursor` and the same entity/time
+filters until `hasMore` is false. Compact pages retain the space/member envelope,
+record IDs, time/assignment metadata and continuation. Long bodies become
+240-character excerpts; attributes, derived data, attachments and content hashes
+are omitted. The `projection.fullDetail` references point to `activity get <id>`
+(CLI), `activities_get` (MCP), and `getActivity` (internal tools). Defaults stay
+unchanged. REST uses `compact=true`; MCP `activities_forEntity` and internal
+`listRecentActivities` use `compact: true`. These options apply to active
+entity-scoped pages, without client-side type/attribute/open/deadline filters.
+
+JSON failures use stdout `{ "error": { "message": "..." } }` with a nonzero
+exit. REST status and structured error fields survive. Check the exit before
+parsing; see [Retrieve bounded context](playbooks/retrieve-bounded-context.md).
+The unsupported `entity show` spelling gives a targeted `entity get` correction.

package/dist/SKILL.md

@@ -98,6 +98,47 @@ npm i -g ente-cli --registry https://registry.npmjs.org
 
 ---
 
+## Retrieve a bounded page
+
+Search entities globally first to resolve identity. Use the returned ID and an
+explicit space for evidence when the task specifies a space. Preserve `spaces`,
+record `spaceId`/`spaceIds`, scope, warnings and pagination when selecting fields;
+access to a record is not permission to copy it into another space.
+
+```bash
+# Deterministic evidence; no hosted model. Time filters constrain activities.
+if ente query "launch decisions" --space "Work" --entity "Apollo" --since 1791763200000 --until 1792368000000 --limit 8 --json > evidence.json; then
+  jq '{data: {scope: .data.scope, evidence: [.data.evidence[] | {id, title, activityId, entityId, spaceIds, spaceNames}], warnings: .data.warnings, truncated: .data.truncated}, spaces: .data.spaces}' evidence.json
+fi
+# One entity-history page with body excerpts and an explicit full-detail path.
+ente activity list --entity <entity-id> --after 1791763200000 --before 1792368000000 --min-count 0 --limit 10 --compact --json
+# Continue with identical entity/time filters; never replace the cursor with a timestamp.
+ente activity list --entity <entity-id> --after 1791763200000 --before 1792368000000 --min-count 0 --limit 10 --compact --cursor '<nextCursor>' --json
+ente activity get <activity-id> --json
+```
+
+`--compact` currently applies to active entity-scoped activity pages only. It
+keeps space names, scopes, member emails, record IDs and `hasMore`/`nextCursor`.
+It replaces long bodies with 240-character excerpts and omits attributes,
+derived payloads, attachments and content hashes. `projection.fullDetail` names
+the complete read on each interface. Omit `--compact` for the existing output.
+Do not combine compact/cursor pages with client-side `--type`, `--attr`,
+`--only-open` or deadline sorting. Those filters need full reads.
+
+`--json` failures return `{ "error": { "message": "..." } }` on stdout and a
+nonzero exit; REST failures also retain `statusCode` and structured error fields.
+Check the exit before parsing. Do not append a successful help command and treat
+its exit as the preceding command's result. `entity show` reports the supported
+`entity get` command and fails without making a request.
+
+For inbox coverage, page the unfiltered `agent mail threads` list to completion,
+then inspect thread messages, including updates to older threads. `--unread`
+and `--needs-reply` answer different questions; unread alone misses read but
+unanswered mail. Keep each view's cursor separate and retain workflow versions.
+An unfiltered list is not an atomic merged snapshot with internal agent chats.
+
+---
+
 ## Quick Reference
 
 ```bash
@@ -111,7 +152,7 @@ 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
+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 50] [--archived] [--json]
@@ -128,12 +169,12 @@ 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 list [--entity "Jane"] [--compact] [--cursor <nextCursor>] [--min-count 0] [--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 transcript <activityId> [--grep "Preis"] [--context 2] [--recording <id>] [--json]   # transcript of the recording behind it
-ente activity update <activityId> [--title "…"] [--content "…"] [--entity-add "Bob"] [--entity-remove "Carol"] [--agent-assignee <agentId> ... | --clear-agent-assignees] [--json]
+ente activity update <activityId> [--title "…"] [--content "…"] [--deadline "2026-05-26" | --clear-deadline] [--entity-add "Bob"] [--entity-remove "Carol"] [--agent-assignee <agentId> ... | --clear-agent-assignees] [--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]
@@ -162,7 +203,7 @@ 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 update 5 [--title "…"] [--content "…"] [--deadline "2026-05-26" | --clear-deadline] [--attr k=v] [--json]   # 5 = #N or activity ID
 ente task done 5 [--json]
 ente space members --space "Work" [--json]
 ente task assign 5 <userId-or-email> [--json]