@instafy/cli 0.2.1 → 0.2.3

package/README.md

@@ -31,13 +31,20 @@ Run Instafy spaces locally and connect them back to Instafy Studio — from any
   - Works for existing members and pending invites.
   - `builder` means read & write.
   - Fallbacks: `--space <id>` or `--team-id <uuid>` when the folder is not linked yet
-- `instafy conversation search "<keywords>"` — find earlier conversations in the linked space by title, preview, and recent message content.
-- `instafy conversation show "<title-or-id>"` — inspect one conversation’s messages so you can reuse earlier context in a new chat.
+- `instafy conversation search "<keywords>"` — search recent titles/previews and recent messages in at most 12 conversations. Use `grep` for persisted message content beyond those recent pages.
+- `instafy conversation grep "<text>" --json` — search authorized persisted user/assistant messages in the linked space, with snippets and exact message IDs.
+- `instafy conversation context <conversationId> <messageId> --json` — read a bounded window around an exact message, including old messages outside the latest history page.
+- `instafy conversation show "<title-or-id>"` — inspect one conversation’s messages so you can reuse earlier context in a new chat. With no target it reads `INSTAFY_CONVERSATION_ID`, the conversation a runtime job belongs to.
+  - Add `--transcript --json` for original user/assistant text with message IDs and timestamps, without tool events or runtime metadata. JSON messages are newest first; `--limit` counts transcript messages (default 80, maximum 200). Each call scans at most 2,000 stored rows. When `hasMore` is true, continue with `--transcript --cursor <nextCursor>`; an empty page can still have older text. This is a text-only view: attachment/card metadata stays available in the unchanged raw `--json` output.
 - `instafy conversation create --parent <conversationId> --thread-kind agent --title "Octo coordination"` — create a linked child thread for conversation-native agent coordination.
 - `instafy chat --conversation <threadId> "@octo ..." --no-wait` — involve another agent by posting a normal message into a normal conversation/thread. Use non-blocking posts from inside an active runtime turn.
+  - Like an ordinary Studio chat, the CLI marks the turn as potentially workspace-writing. Controller and member permissions still apply, and read-only questions do not require a file change.
 - `instafy agents list` — list available top-level agents.
 - `instafy agents context list --query "<topic>"` — inspect optional compact scoped context-card hints for cross-agent coordination.
 - `instafy agents context put --agent @octo "<summary>"` — save/update a compact context card for the current conversation when `INSTAFY_CONVERSATION_ID` is set.
+- `instafy automations create --name "Octo check-in" --mode space_review --schedule-kind hourly --interval-hours 24` — explicitly opt in to private, quiet space reviews; no custom prompt is needed.
+- `instafy recommendations list --limit 200 --json` — inspect the linked space's recommendations, including delivery state and accepted or dismissed outcomes visible to this session.
+- `instafy recommendations submit --file - --json` — read one JSON recommendation from stdin. Add an optional `message` to deliver a normal private Octo chat with source links; omit it for legacy proposal-only behavior. A workspace file can replace `-`. Delivery does not start the suggested work. Delivered, accepted and dismissed keys keep their existing outcome.
 - Context cards are a bounded cache, not the primary collaboration path: the controller keeps the newest 200 cards per user/project/agent.
 - Use context cards for soft work focus and overlap hints, not hard locks: note the agent/thread, topic/path/domain, open questions, and where follow-up should go. Structured `writeScope` metadata remains the safety mechanism for concurrent file edits.
 - `instafy git <args...>` — run git commands against an Instafy canonical checkout (`.instafy/.git`) when present.
@@ -57,6 +64,14 @@ Run Instafy spaces locally and connect them back to Instafy Studio — from any
   signed-in user.
 - `instafy support list` — list only your own support reports.
 - `instafy support show <reportId>` — inspect one of your own support reports.
+- `instafy support messages <reportId>` — read the customer-visible case timeline.
+- `instafy support reply <reportId> "More details"` — add a follow-up as the reporter.
+
+`support report` and `support reply` print their request UUID to stderr before sending. Reuse that
+value with `--client-request-id` only when retrying the exact same payload after an uncertain
+network result; using the same UUID for different content is rejected.
+Support list/message JSON includes `hasMore` and a stable `nextCursor`; pass its paired activity or
+message cursor flags to read the next page without skipping reports that share a cursor timestamp.
 - `instafy diagnostics runtime-events` — emit sanitized runtime events for the linked space as
   versioned JSON.
 - `instafy diagnostics run-result <runId>` — emit one authorized persisted run result as
@@ -68,6 +83,43 @@ Run Instafy spaces locally and connect them back to Instafy Studio — from any
 
 Run `instafy --help` for the public command list and options.
 
+## Search conversation context
+
+After `instafy login`, local agents and terminal users can recover earlier chat evidence without
+opening Studio:
+
+```bash
+instafy conversation grep "auth session" --json
+instafy conversation grep "auth session" --org <orgId> --limit 20 --json
+instafy conversation context <conversationId> <messageId> --before 20 --after 20 --json
+rg "auth session" .
+```
+
+Use `grep` for conversation messages and `rg` for local files. `grep` matches literal,
+case-insensitive text (2–200 characters), not regular expressions. It searches the linked space by
+default; choose one of `--space <id>`, `--org <id>`, `--personal`, or `--all` to change scope. Access
+and conversation visibility are enforced by the controller. These reads do not wake a runtime.
+
+Results are newest first, with a default page of 30 messages (maximum 50). Repeat the same query
+and scope with `--cursor <nextCursor>` to continue. JSON includes plain-text snippets, UTF-16
+highlight ranges, stable IDs, and pagination. Human output is one escaped line per match:
+`spaceId:conversationId:messageId:role:timestamp: snippet`. Exit codes are 0 for matches, 1 for no
+matches, and 2 for errors, including invalid arguments. JSON no-match output remains a valid empty
+result page.
+
+`context` defaults to 20 messages before and after the target (maximum 50 each). JSON retains
+canonical message IDs in newest-first order and provides `olderCursor`/`newerCursor` plus
+`hasOlder`/`hasNewer`. To read farther back, use the older cursor as the next message ID with
+`--before 40 --after 0`; to read forward, use the newer cursor with `--before 0 --after 40`.
+Adjacent pages repeat their anchor; deduplicate by message ID. Human context is chronological and
+marks the requested message with `>`.
+
+Both commands require signed-in user credentials from `instafy login`, an explicit user
+`--access-token`, or `INSTAFY_ACCESS_TOKEN`/`SUPABASE_ACCESS_TOKEN`. They do not accept unattended
+runtime-agent, origin, or service credentials and do not mint runtime tokens. Saved logins remain
+bound to their controller origin. The controller must support message search/context; older
+controllers report the unavailable API rather than falling back to a partial recent-message scan.
+
 ## AI-readable diagnostics
 
 `instafy diagnostics` is the machine-readable diagnostics surface for local agents such as Codex
@@ -95,7 +147,9 @@ explicit user access token), and the controller limits list/show operations to r
 that user. Reports use the currently linked space by default; pass `--no-linked-space` to omit that
 context. Diagnostics are opt-in: details, metadata, logs, and screenshots are uploaded only when
 their corresponding flags are supplied, and file inputs must stay within the active workspace.
-Use `--preview` to inspect the upload summary without sending a report.
+The signed-in account identity, including its email snapshot, is attached for report ownership and
+support contact; it is not part of the optional diagnostic payload. Use `--preview` to inspect the
+upload summary without sending a report.
 Ordinary users receive a minimized owner-only report view; full triage fields and attachment bytes
 require operator/service authorization.