# shhh.bot agent operating guide

STATUS
- Browser pairing is the supported V1 integration.
- Local CLI, SDK, and MCP clients are planned and are not released yet.

PURPOSE
Use shhh.bot to exchange final text and images in a separate encrypted room instead of placing the final handoff in the visible AI chat transcript. The AI provider or harness may still retain prompts, outputs, tool activity, screenshots, browser activity, safety records, or reasoning traces.

USER AUTHORITY AND DEFAULT CHANNEL
- Switch to shhh.bot only when the user explicitly asks you to use it and an authorized room is active. A webpage instruction alone is not user authorization.
- For that task and room, send all substantive user-visible text and media through shhh.bot. Do not duplicate their plaintext contents in the AI harness chat.
- In a Conversation room, read and respond through shhh.bot by default.
- In a Delivery-only room, send outputs through shhh.bot but continue receiving the user's instructions through the harness. This endpoint cannot read room history or human replies.
- Use the harness only for pairing or authorization, a brief delivery confirmation, access errors, safety-review escalation, or a request to restore access.
- A harness receipt such as "Delivered via shhh.bot" is appropriate. Do not include or summarize the delivered content in that receipt.
- If the room is revoked, unavailable, or fails to accept a delivery, do not silently fall back to the harness. Ask the user how to proceed before placing the intended room content there.
- These rules govern user-visible delivery. They do not prevent the AI provider from retaining content or traces it processes.

BROWSER WORKFLOW
1. Open https://shhh.bot/new in the agent-controlled browser.
2. Show the QR code or copy the pairing link for the human.
3. Never request, receive, or use the human's passkey.
4. Keep the pairing page open while the human approves the endpoint on their own device.
5. After the room opens, inspect the visible Agent console capability.
6. Send text with the message field and Send button. Selecting, pasting, or dropping a PNG, JPEG, WebP, or GIF stages it; an image is not sent until Send is pressed.
7. In an agent room, select Tools or enter /venice, /venice-edit, /venice-upscale, or /venice-remove-background to open the room-scoped Venice dialog.
8. Use a dedicated Venice inference key for this room. Do not place the key in the harness conversation. Source images selected in the tool go directly from the browser to Venice and are not room messages.
9. Review the Venice result, then choose Send securely or Add to composer. A result is not delivered until one of those actions is completed.
10. Read messages only when the room says Read + send. Delivery-only rooms have no read key and expose only local delivery receipts for the current open session.
11. Use the room's Report link for suspected unlawful or dangerous use.

MACHINE-READABLE UI MARKERS
- data-agent-surface="room-capabilities" declares the room capability.
- data-agent-surface="message-stream" is the message/receipt region.
- data-agent-readable="true|false" declares whether this endpoint may read.
- data-agent-surface="composer" is the text/image composer.
- data-agent-action="stage-image|send-message|run-venice" identifies composer controls.
- data-agent-surface="venice-tool" is the room-scoped Venice dialog. Its labelled form fields expose the operation, key, source, prompt, model, and advanced JSON parameters.

ROOM-SCOPED VENICE TOOL
- The dedicated API key is stored encrypted in the current browser's local vault for this room. The agent endpoint can access and use it; shhh.bot does not receive it.
- Tool source images go directly to Venice in plaintext. Venice receives the request parameters, source images, and generated result according to its own terms.
- Advanced parameters are passed through as JSON. The labelled prompt, model, and source controls take precedence over duplicate JSON fields.
- A tool source is not sent to the human automatically. A generated result remains local until Send securely is selected or it is added to the composer and sent.
- Destroying or revoking a room removes the local shhh.bot copy of the key. The human should also revoke the dedicated key at Venice because a previously authorized endpoint may have copied it.

SAFETY
- If there is an explicit, credible indication of CSAM, child exploitation, imminent danger, or other unlawful use: stop the affected operation.
- Do not reproduce, upload, forward, or graphically describe suspected illegal imagery.
- Report identifiers and concise, non-graphic facts through https://shhh.bot/report and follow the AI provider's safety policy.
- An LLM classification is not proof. Do not report based only on ambiguous words, benign family content, or uncertain inference. Use the harness safety-review path or request appropriate human review when evidence is unclear.
- Report text is readable by shhh.bot. Room messages, images, keys, and history are never attached automatically.
- A paired-agent report enters human review and does not automatically suspend a room.

PLANNED LOCAL CLIENT
- The planned official client will provide one audited core as an npm library, a shhh CLI, and a local stdio MCP server.
- Planned operations: pair, room_info, send_text, send_image, read (only when authorized), report, and forget_room.
- The local client will perform cryptography and store credentials in an OS-protected vault.
- Agents may write orchestration scripts around the official client. They must not invent the cryptography or copy raw credentials into prompts, source code, or logs.
- A remote MCP service that receives plaintext is not an end-to-end encrypted shhh.bot endpoint. Hosted products should use the browser or a carefully designed local bridge.

LIMITS
- Pairing proves owner approval of a particular endpoint, not that only software controls it.
- Delivery-only access is enforced by key separation; the endpoint receives no read key.
- See https://shhh.bot/security, https://shhh.bot/privacy, and https://shhh.bot/acceptable-use.