@7ots/cli 0.1.0 → 0.1.3

package/cli/lib/prompts.mjs

@@ -19,7 +19,7 @@ When the user says "install it here":
 2. Run \`npx -y @7ots/cli install\`. It detects the project:
    - plain HTML site → inserts the 7ots widget before </body> (between <!-- 7ots --> markers, idempotent);
    - other projects → prints the snippet: put it in the root layout/template, before </body>;
-   - \`--target self\` → prepares the identity for the user's own 7ots server (IDENTITY_FILE=… npx -p 7ots 7ots-server);
+   - \`--target self\` → prepares the identity for the user's own 7ots server (IDENTITY_FILE=… npx -y @7ots/cli server);
    - it also prints a 7ots.com link that hosts this same identity (no server needed).
 3. The widget needs an AI endpoint: a 7ots proxy (/api/agent) or the ot hosted on 7ots.com. Tell the user which.`,
 
@@ -55,18 +55,210 @@ export function promptText(topic = 'all') {
   return PROMPTS[topic];
 }
 
-/** https://7ots.com/llms.txt */
+/** https://7ots.com/llms.txt — everything a coding agent needs to set up 7ots without guessing. */
 export function llmsTxt(base = 'https://7ots.com') {
   return `# 7ots
 
 > Open-source embeddable web agent: it sees the page, speaks and acts for your visitor. One HTML tag, your server, your brand.
-> Every ot has an identity (face, personality, voice, meet avatar) reproducible from a short seed, and can also live on
-> your computer as a virtual pet and join apuchat meet video calls.
+> Every ot has an identity (face, personality, voice, meet avatar) reproducible from a short seed. The same ot can live
+> on a website (widget), on the user's computer (a virtual pet: desktop window, terminal or tmux), in apuchat meet
+> video calls, and answer email (apumail) and chat (apuchat). 7ots integrates those services; it does not host audio or mail.
 
-- Site: ${base}/
-- Create an identity in the browser: ${base}/#create
-- Hosted ots (dashboard): ${base}/app/
-- npm: https://www.npmjs.com/package/7ots (CLI: \`npx @7ots/cli help\`)
+- Site: ${base}/ · create an identity in the browser: ${base}/#create
+- Hosted ots (dashboard, no server needed): ${base}/app/
+- CLI: npm \`@7ots/cli\` (https://www.npmjs.com/package/@7ots/cli) → \`npx -y @7ots/cli help\`, \`npx -y @7ots/cli <cmd> --help\`
+- This file: ${base}/llms.txt (also \`npx -y @7ots/cli docs\`)
+
+# Read this first (for coding agents)
+
+1. Never invent identity fields or config files by hand: use the CLI, it validates everything.
+2. Ask the user only what you can't tell from the project. The usual question is WHERE the ot should live:
+   - a website in this repo → widget (section "Website");
+   - not a website (library, backend, CLI, data…) → the pet on their computer, a meet call, or hosting on ${base}/app/;
+   - "on my computer" / "a tamagotchi" → the pet (section "Pet").
+3. From an agent, commands must return: use \`--detach\` for the pet, run \`meet\` in the background, and ask the user to run
+   interactive commands themselves (\`setup\`, the terminal pet) — in Claude Code: \`! npx -y @7ots/cli setup\`.
+4. Language: \`--lang en|es|pt\` on \`new\` sets the ot's language, and from then on every CLI text follows it
+   (order: SEVENOTS_LANG > ~/.7ots/config.json "lang" > the ot's language > LANG > English).
+5. Secrets (API keys, tokens) never go in HTML, in identity.json or in your reply: they go in env vars / .env of a server,
+   in ~/.7ots/keys.json (written by \`setup\`, 0600) or in the ${base}/app/ dashboard.
+6. When done, tell the user: the ot's name and seed, where it lives, and how to see it (URL, \`7ots pet\`, …).
+
+# Typical flows
+
+- "Use 7ots" in a website repo:
+  \`npx -y @7ots/cli new --lang <en|es|pt>\` → \`npx -y @7ots/cli install\` → tell the user which AI endpoint the widget uses.
+- "Give me a pet":
+  \`npx -y @7ots/cli new\` (if there is no identity) → \`npx -y @7ots/cli pet --mode desktop --detach\` → \`npx -y @7ots/cli hooks install --claude\`.
+- "Put it in a call": \`npx -y @7ots/cli meet --new\` (in the background) and give the printed link only to the user.
+- "Host it, no server": create it at ${base}/app/ (or open the link \`install\` prints) and paste its one-line embed.
+
+# CLI reference (\`npx -y @7ots/cli <command>\`, or \`7ots <command>\` once installed globally)
+
+Every command accepts \`--help\` (prints usage, never launches anything) and \`--lang en|es|pt\`.
+
+| Command | What it does |
+|---|---|
+| \`new [--seed s] [--name n] [--lang en\\|es\\|pt] [--global] [--force] [--json]\` | Random identity → \`.7ots/identity.json\` (\`--global\`: \`~/.7ots/identity.json\`, shared by every project). Keeps an existing one unless \`--force\`. |
+| \`show [--json\\|--prompt]\` | The identity in use (the project's, else the global one). \`--prompt\`: as a system prompt. |
+| \`seed <text>\` | Normalizes a seed. Same seed = same ot everywhere. |
+| \`install [--target html\\|self\\|print] [file]\` | Puts the widget in the project (see "Website"). |
+| \`setup\` (alias \`wizard\`, \`init\`) | Interactive wizard: where the ot lives, brain, voice, pet mode, chattiness, hooks. Writes \`~/.7ots/config.json\` and \`keys.json\`. |
+| \`pet [--mode desktop\\|terminal\\|browser\\|auto] [--detach] [--opaque] [--tmux] [--compact]\` | Wakes the pet (see "Pet"). |
+| \`feed\` · \`play\` · \`sleep\` · \`wake\` · \`say <text>\` | Care for the pet (works even if it is not running: the state is saved). |
+| \`status [--line\\|--json]\` | Level, food, energy, fun. \`--line\`: one short line for status bars. |
+| \`stop\` | Stops the pet daemon (and its windows). |
+| \`hooks install\\|remove [--claude] [--shell] [--global]\` | Lets the pet react to your work (see "Hooks"). |
+| \`meet --new [--minutes n]\` · \`meet "<invite or link>"\` | The ot joins an apuchat meet video call. |
+| \`prompt [identity\\|install\\|pet\\|meet\\|all]\` | Short recipes for coding agents. |
+| \`docs\` | Prints this file. |
+| \`login orquesta\` | Connects a getorquesta.com account (brain "batuta", home "orquesta"). |
+| \`server\` | Runs the 7ots proxy (\`/api/agent\`) with the env vars below. |
+| \`version\` · \`help\` | |
+
+# Files
+
+| Path | Content |
+|---|---|
+| \`.7ots/identity.json\` (project) / \`~/.7ots/identity.json\` (global) | The identity. Public data only (name, role, look, voice, personality, contact). Commit it if you want. |
+| \`~/.7ots/config.json\` | Written by \`setup\`: \`lang\`, \`home\`, \`brain\`, \`voice\`, \`pet\` (below). |
+| \`~/.7ots/keys.json\` (0600) | Keys typed in \`setup\`, under their env-var names. Env vars always win. Never print it. |
+| \`~/.7ots/pet.json\` · \`pet.log\` · \`pet.token\` | Pet state, daemon log, local auth token. |
+| \`SEVENOTS_HOME\` | Moves \`~/.7ots\` elsewhere. \`SEVENOTS_PET_PORT\` (default 7717) moves the pet daemon. \`SEVENOTS_LANG\` forces the CLI language. |
+
+Identity fields: \`id, name, role, tagline, seed, bio, language, languages, personality{tone, traits, instructions}, look{color, …},
+voice{provider, id, lang}, contact{…}\`. Change them with \`new --force\`, the web editor (${base}/#create) or the backoffice, not by hand.
+
+## config.json
+
+\`\`\`
+home   { kind: 'local' }                                  only on this computer
+       { kind: '7ots', url: '${base}/api/o/<id>' }        hosted on 7ots.com
+       { kind: 'server', url: 'https://site/api/agent' }   the user's own 7ots server
+       { kind: 'orquesta', projectId, projectName }        a getorquesta.com project
+brain  { kind: 'lines' }                                  built-in phrases, no AI (default)
+       { kind: 'cli', cli: 'claude'|'codex'|'gemini'|'ollama'|'custom', model?, command? }   the user's own AI CLI
+       { kind: 'api', provider: 'anthropic'|'openai', model?, baseUrl? }                    a key in keys.json/env
+       { kind: '7ots' }                                   the home's /chat (7ots.com or own server)
+       { kind: 'batuta', model? }                         Orquesta's Batuta
+voice  { kind: 'none'|'browser'|'apuchat'|'elevenlabs'|'grok'|'fish'|'openai', voiceId? }
+pet    { mode: 'ask'|'desktop'|'terminal'|'browser', annoy: 0..3, opaque?: true }
+       annoy: 0 silent · 1 rarely · 2 normal · 3 chatty (+ terminal bell)
+\`\`\`
+Keys by name: ANTHROPIC_API_KEY, OPENAI_API_KEY, ORQUESTA_TOKEN, APUCHAT_VOICE_TOKEN, ELEVENLABS_API_KEY, XAI_API_KEY, FISH_API_KEY.
+
+# Pet
+
+- \`desktop\`: a small always-on-top window that walks along the bottom of the screen (Electron via npx, ~100 MB the first time).
+  Find it bottom-right; menu on right click or the tray icon (Show / Hide / Feed / Play / Sleep / Quit). Hide keeps it alive.
+- \`terminal\`: drawn in the current terminal, keys f feed · p play · s sleep/wake · q quit. Needs its own terminal: ask the user.
+- \`browser\`: a tab at http://127.0.0.1:7717/pet.
+- \`auto\`: desktop if there is a screen, else terminal.
+- \`--detach\`: return immediately (always from agents). The daemon keeps running until \`7ots stop\`.
+- tmux: \`7ots pet --tmux\` opens the terminal pet in a side pane (\`--compact\` for a narrow one); for the status bar add
+  \`set -g status-right "#(7ots status --line)"\` to ~/.tmux.conf.
+- Needs: food, energy and fun decay with time (time away counts at most 8 h); it gains XP and levels from passing
+  commands and finished agent turns.
+
+Troubleshooting:
+- A grey/black box behind the pet (Linux without a compositor, some GPUs): \`7ots pet --opaque\` (or \`"pet": {"opaque": true}\` in config.json).
+- Can't see it: look at the tray icon, or \`7ots stop && 7ots pet --mode desktop\` (it comes back bottom-right).
+- Electron can't start (no display, headless, WSL): it falls back to the browser tab; or use \`--mode terminal\`.
+- Port busy: \`SEVENOTS_PET_PORT=7720\`.
+
+# Hooks
+
+- \`hooks install --claude\`: Claude Code hooks in \`.claude/settings.local.json\` of this project (\`--global\`: ~/.claude/settings.json).
+  The pet hears tool calls, errors and finished turns (\`7ots event --from claude\`, reads the hook JSON on stdin; never fails).
+- \`hooks install --shell\`: bash/zsh hook in ~/.bashrc / ~/.zshrc: the pet hears commands and exit codes (secrets are redacted).
+- \`hooks remove\` undoes both. Without a running pet the events still change its state silently.
+
+# Website (widget)
+
+\`npx -y @7ots/cli install\` detects the project:
+- plain HTML (index.html in ., public/, src/, static/, www/, site/) → inserts the widget before </body> between
+  \`<!-- 7ots -->\` markers (idempotent: re-running replaces the block);
+- a framework (Next, Nuxt, Astro, SvelteKit, Remix, Gatsby, Vite, Django, Rails, Laravel, Hugo, Jekyll…) → prints the snippet and
+  which file to paste it in (root layout/template, before </body>);
+- not a website → says so and suggests the pet, meet or hosting;
+- \`--target print\` only prints the snippet; \`--target self\` prepares the identity for the user's own server.
+
+Snippet for an ot hosted on 7ots.com (simplest; allowed domains are set in the dashboard):
+\`\`\`html
+<script src="${base}/api/o/<id>/embed.js" defer></script>
+\`\`\`
+Snippet with your own proxy:
+\`\`\`html
+<script src="https://cdn.jsdelivr.net/npm/@7ots/cli/dist/7ots.iife.js" defer></script>
+<script>
+  addEventListener('DOMContentLoaded', () => SevenOts.init({ endpoint: '/api/agent', identity: true }));
+</script>
+\`\`\`
+Declarative: \`<ots-agent endpoint="/api/agent" site-key="pk_x" name="Ana"></ots-agent>\`. ES module: \`import { init } from '@7ots/cli'\`.
+
+\`SevenOts.init(options)\`:
+| Option | Meaning |
+|---|---|
+| \`endpoint\` | Proxy URL (\`/api/agent\`, \`${base}/api/o/<id>\`, …). Required. |
+| \`siteKey\` | Public site id the proxy may require (\`SITE_KEYS\`). |
+| \`identity\` | \`true\` (ask the endpoint), a URL, or an inline identity object (public fields only). |
+| \`agent\` | \`{ name, role, siteName, language, instructions, expressive }\`. |
+| \`avatar\` | \`{ url, body: 'F'\\|'M', mood, cameraView }\` (3D, needs an importmap for three) or \`false\`; default is the 2D character. |
+| \`voice\` | \`{ tts: 'proxy'\\|'browser'\\|false, stt: true, lang }\` or \`false\`. |
+| \`auth\` | \`{ token }\`, \`{ getToken, getUser }\` or \`{ credentials: 'include' }\`; \`exposeClaims\`. |
+| \`mcp\` | \`[{ url, name, requiresAuth, filter, confirm }]\` MCP servers (Streamable HTTP). |
+| \`actions\` | Custom tools \`[{ name, description, parameters, handler, confirm }]\`. |
+| \`templates\` | \`{ name: (data, { escape }) => html }\` for show_modal / open_sidebar. |
+| \`navigation\` | \`{ allowedOrigins, router }\` (\`router\` for SPAs). |
+| \`proactive\` | \`{ level: 'quiet'\\|'normal'\\|'bold', greetDelayMs, dwellMs, idleMs, cooldownMs, maxPerSession, … }\` or \`false\`. |
+| \`context\` | \`{ privateSelectors, ignoreSelectors, extra: () => ({...}) }\` — what it may read on the page. |
+| \`contact\` | \`{ apuchat: true, apumail: true \\| { categories } }\` or \`false\` — hand off to a human. |
+| \`builtins\` | \`{ exclude: ['click', …], confirmClicks: 'submit'\\|'all'\\|'none' }\`. |
+| \`pointer\` | \`{ speed, visible }\` or \`false\` — the virtual mouse/keyboard. |
+| \`pageTools\` | \`true\` (default): forms/buttons with \`data-ots-tool\` become tools. |
+| \`mode\` / \`companion\` | \`'panel'\` (default) or \`'companion'\` (the avatar walks the page); \`{ size, idleHomeMs, follow, wanderMs, watchCursor }\`. |
+| \`theme\` | \`{ primary, radius, position: 'right'\\|'left', font }\`. |
+
+HTML tools without JS: \`<form data-ots-tool="invite_member" data-ots-description="…" data-ots-confirm="Invite {email}?" data-ots-auth>\`
+(named fields become parameters). Runtime API: \`agent.ask(text)\`, \`say\`, \`notify\`, \`registerAction\`, \`registerMcp\`,
+\`setAuthToken\`, \`setIdentity\`, \`setProactivity\`, \`open/close/reset/destroy\`, \`on(event, fn)\`.
+
+# Own server (\`npx -y @7ots/cli server\`, or \`node server/server.mjs\` from the repo)
+
+Reads env vars / \`.env\`. Keys live only here. Admin UI at /backoffice/ (localhost only unless ADMIN_PASSWORD).
+- Core: PORT (8787), ALLOWED_ORIGINS (comma list), SITE_KEYS, RATE_LIMIT_PER_MIN (40), TRUST_PROXY, SERVER_INSTRUCTIONS, LOCALE (es|en|pt), LOG_LEVEL.
+- LLM: LLM_PROVIDER (anthropic | openai | mock), ANTHROPIC_API_KEY, OPENAI_API_KEY, LLM_MODEL, LLM_BASE_URL (OpenAI-compatible:
+  DeepSeek, Groq, Ollama, OpenRouter…), LLM_EFFORT (low…max), LLM_MAX_TOKENS, LLM_FALLBACKS (on|off).
+- Voice (TTS): TTS_PROVIDER (apuchat | elevenlabs | grok | fish | openai | none = browser voice; empty = first with a key);
+  APUCHAT_VOICE_URL, APUCHAT_VOICE_TOKEN, APUCHAT_VOICE_ID, APUCHAT_VOICE_PROVIDER; ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID,
+  ELEVENLABS_MODEL; XAI_API_KEY, XAI_TTS_VOICE; FISH_API_KEY, FISH_VOICE_ID, FISH_MODEL; OPENAI_TTS_MODEL, OPENAI_TTS_VOICE.
+- Email tickets (apumail): APUMAIL_API, APUMAIL_INBOX, APUMAIL_INBOX_TOKEN, APUMAIL_TO.
+- Human handoff (apuchat): APUCHAT_HUB, APUCHAT_NOTIFIER_IDENTITY_KEY, APUCHAT_OPERATOR_HANDLE, APUCHAT_TRANSCRIBE.
+- Backoffice: ADMIN_PASSWORD, CONFIG_FILE, SECRETS_FILE, IDENTITY_FILE (default data/identity.json).
+- The agent outside the web: AGENT_NAME, AGENT_ROLE, AGENT_SITE_URL, AGENT_INSTRUCTIONS, AGENT_LANG; own mailbox APUMAIL_AGENT_INBOX,
+  APUMAIL_AGENT_TOKEN, APUMAIL_AGENT_WEBHOOK_SECRET, APUMAIL_AGENT_DAILY; own apuchat/meet identity APUCHAT_AGENT_IDENTITY_KEY,
+  APUCHAT_AGENT_AVATAR, APUCHAT_AGENT_SCENE, APUCHAT_AGENT_ALLOW, AGENT_MAX_CALLS, AGENT_CALL_MAX_MINUTES, AGENT_CALL_MAX_TURNS.
+- Demo: DEMO, SERVE_STATIC, DEMO_JWT_SECRET.
+- Platform (multi-tenant, what ${base} runs): PLATFORM=true, PLATFORM_URL, PLATFORM_DB, PLATFORM_SECRET, PLATFORM_MAX_OTS,
+  PLATFORM_OTS_RATE_PER_MIN, PLATFORM_OTS_DAILY_LIMIT, PLATFORM_NEW_ACCOUNTS_PER_IP_DAY, PLATFORM_MAX_INFLIGHT,
+  PLATFORM_LLM_PROVIDER/API_KEY/BASE_URL/MODEL, PLATFORM_FREE_MESSAGES, PLATFORM_APUCHAT_VOICE_TOKEN, PLATFORM_FREE_TTS,
+  PLATFORM_MAIL_INBOX/TOKEN, NOTLOGIN_URL/CLIENT_ID/CLIENT_SECRET, PLATFORM_APUCHAT_IDENTITIES_PER_DAY (free apuchat
+  identities per account and day, default 5), ORQUESTA_URL (default https://getorquesta.com).
+Endpoints: POST /api/agent/chat, POST /api/agent/tts, GET /api/agent/identity, /api/agent/contact/*, /llms.txt.
+
+# Hosted on ${base} (no server)
+
+- Sign in at ${base}/app/, create an ot (\`7ots install\` also prints a link that opens this same identity there), set the allowed domains, copy the embed.
+- Each ot's public API: \`${base}/api/o/<id>/\` — embed.js, config, identity, identity.vcf, chat, tts, contact/apumail, contact/apuchat.
+  Point the CLI at it with \`setup\` → home "7ots" (brain "7ots" then uses its /chat).
+- Brain: the account's free monthly quota on the platform's AI, or the user's own key (BYOK) set in the ot's settings.
+  Same for voice. Keys are encrypted and never shown again. Per-ot daily and per-minute limits apply.
+- Settings per ot in /backoffice/?ots=<id>: instructions, LLM/voice keys, apumail/apuchat channels.
+- apuchat tab of an ot: a free @handle (expires after 24h without activity, e.g. while the ot is paused), made permanent
+  by paying once by card on apuchat; connect your apuchat account to keep paid identities under it, or paste an identity key you own.
+- Orquesta tab of an ot: connect Orquesta (OAuth or an oak_ key), pick a project, enable tasks. Then the ot can start Orquesta
+  tasks (run_task, task_status) only for its owner in the dashboard ("Ask your ot to do something") and for apuchat DMs /
+  apumail emails from senders on the ot's allowlist — never from the public chat (/api/o/<id>/chat). Daily cap per ot (default 20).
 
 # Recipes for coding agents
 

package/cli/lib/terminal.mjs

@@ -1,6 +1,8 @@
 /**
  * Terminal mode: the pet drawn with ANSI in the current terminal, fed by the daemon's SSE.
  * Keys: f feed · p play · s sleep/wake · q quit (the daemon keeps running if --detach started it).
+ * Only redraws when the frame changes, line by line (no full clears: no flicker, fine inside tmux).
+ * compact: a few narrow lines for a small tmux pane.
  */
 
 import { PET_PORT } from './paths.mjs';
@@ -46,7 +48,7 @@ function bar(v, width = 16) {
   return `${color}${'█'.repeat(n)}${DIM}${'░'.repeat(width - n)}${RESET} ${String(v).padStart(3)}`;
 }
 
-export async function runTerminal({ identity, lang, port = PET_PORT, bell = false }) {
+export async function runTerminal({ identity, lang, port = PET_PORT, bell = false, compact = false }) {
   const out = process.stdout;
   const color = identity.look.color;
   let state = null;
@@ -55,15 +57,26 @@ export async function runTerminal({ identity, lang, port = PET_PORT, bell = fals
   let thinking = false;
   let blink = false;
   let hop = 0;
+  let last = '';
 
-  const draw = () => {
-    if (!state) return;
+  const frame = () => {
     const [l, m, r] = FACES[state.mood] || FACES.neutral;
     const eyesL = blink && !state.asleep ? '-' : l;
     const eyesR = blink && !state.asleep ? '-' : r;
     const c = fg(color);
     const lines = [];
     const now = Date.now();
+    if (compact) {
+      const say = bubble && now < bubbleUntil ? bubble : thinking ? '…' : '';
+      const w = Math.max(16, (out.columns || 28) - 2);
+      lines.push(`${c}(${RESET}${BOLD}${eyesL}${RESET}${m}${BOLD}${eyesR}${RESET}${c})${RESET} ${BOLD}${identity.name}${RESET}${state.asleep ? `${DIM} zz${RESET}` : ''}`);
+      lines.push(`${t('pet.food', lang).slice(0, 3)} ${bar(state.food, 6)}`);
+      lines.push(`${t('pet.energy', lang).slice(0, 3)} ${bar(state.energy, 6)}`);
+      lines.push(`${t('pet.fun', lang).slice(0, 3)} ${bar(state.fun, 6)}`);
+      for (const x of wrap(say, w).slice(0, 4)) lines.push(`${DIM}${x}${RESET}`);
+      lines.push(`${DIM}f p s q${RESET}`);
+      return lines;
+    }
     if (bubble && now < bubbleUntil) {
       const w = wrap(bubble, 38);
       const width = Math.max(...w.map((x) => x.length));
@@ -85,7 +98,15 @@ export async function runTerminal({ identity, lang, port = PET_PORT, bell = fals
     lines.push(`  ${DIM}${t('pet.level', lang, { level: state.level, xp: state.xp, next: state.next })}${RESET}`);
     lines.push('');
     lines.push(`  ${DIM}${t('pet.keys', lang)}${RESET}`);
-    out.write('\x1b[H\x1b[2J' + lines.join('\n') + '\n');
+    return lines;
+  };
+
+  const draw = (force = false) => {
+    if (!state) return;
+    const f = frame().map((x) => x + '\x1b[K').join('\r\n');
+    if (f === last && !force) return;
+    last = f;
+    out.write('\x1b[H' + f + '\x1b[J');
   };
 
   out.write('\x1b[?1049h\x1b[?25l');
@@ -103,11 +124,11 @@ export async function runTerminal({ identity, lang, port = PET_PORT, bell = fals
       if (k === 's') postPet('/event', { type: state?.asleep ? 'wake' : 'sleep' }, port);
     });
   }
-  out.on('resize', draw);
+  out.on('resize', () => draw(true));
   setInterval(() => {
     blink = Math.random() < 0.08;
     if (hop) hop--;
-    draw();
+    draw(); // no-op unless something visible changed (blink, hop, bubble expiring)
   }, 500);
 
   // SSE over fetch (Node has no EventSource without flags).

package/cli/pet/electron/main.cjs

@@ -1,63 +1,113 @@
 /**
  * Desktop mode: the pet page in a transparent, frameless, always-on-top window that strolls
  * along the bottom of the screen. Launched by `7ots pet --mode desktop` with
- *   npx -y electron@<v> cli/pet/electron/main.cjs
- * and SEVENOTS_PET_URL / SEVENOTS_PET_TOKEN in the environment. Right click = menu.
+ *   ~/.7ots/electron/…/electron cli/pet/electron/main.cjs (installed once by the CLI)
+ * and SEVENOTS_PET_URL / SEVENOTS_PET_TOKEN in the environment.
+ * Menu: right click on the pet, or the tray icon (Show / Hide / care / Quit).
+ * SEVENOTS_PET_OPAQUE=1 paints a solid card instead of transparency (Linux setups without a compositor).
  */
 
-const { app, BrowserWindow, Menu, screen } = require('electron');
+const path = require('node:path');
+const { app, BrowserWindow, Menu, Tray, nativeImage, screen } = require('electron');
 
 const URL_ = process.env.SEVENOTS_PET_URL;
 const TOKEN = process.env.SEVENOTS_PET_TOKEN;
+const OPAQUE = process.env.SEVENOTS_PET_OPAQUE === '1';
+const VIEW3D = process.env.SEVENOTS_PET_3D === '1';
+const LANG = String(process.env.SEVENOTS_PET_LANG || 'en').slice(0, 2);
+const ICON = path.join(__dirname, '..', '..', '..', 'brand', 'icon-512.png');
 const W = 240;
 const H = 270;
+const linux = process.platform === 'linux';
+
+const L = {
+  en: { talk: '💬 Talk', show: 'Show pet', hide: 'Hide (keeps living)', feed: '🍎 Feed', play: '🎾 Play', sleep: '💤 Sleep', wake: '☀️ Wake up', still: 'Stay still', quit: 'Quit pet' },
+  es: { talk: '💬 Hablar', show: 'Mostrar mascota', hide: 'Ocultar (sigue viva)', feed: '🍎 Dar comida', play: '🎾 Jugar', sleep: '💤 Dormir', wake: '☀️ Despertar', still: 'Quedarse quieta', quit: 'Cerrar mascota' },
+  pt: { talk: '💬 Falar', show: 'Mostrar bichinho', hide: 'Esconder (segue vivo)', feed: '🍎 Dar comida', play: '🎾 Brincar', sleep: '💤 Dormir', wake: '☀️ Acordar', still: 'Ficar parado', quit: 'Fechar bichinho' },
+}[LANG] || {};
+const tr = (k) => L[k] || { show: 'Show pet', hide: 'Hide', talk: 'Talk', feed: 'Feed', play: 'Play', sleep: 'Sleep', wake: 'Wake up', still: 'Stay still', quit: 'Quit pet' }[k];
 
-app.commandLine.appendSwitch('enable-transparent-visuals'); // Linux compositors
 app.commandLine.appendSwitch('autoplay-policy', 'no-user-gesture-required'); // it talks without a click
+if (linux && !OPAQUE) {
+  // Transparent windows on Linux: these avoid the black/grey box on most X11 setups.
+  app.commandLine.appendSwitch('enable-transparent-visuals');
+  if (!VIEW3D) app.disableHardwareAcceleration(); // the 3D ot needs the GPU (WebGL)
+}
+
+const post = (p, body) =>
+  fetch(new URL(p, URL_), { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-7ots-Token': TOKEN }, body: JSON.stringify(body || {}) }).catch(() => {});
 
-const post = (path, body) =>
-  fetch(new URL(path, URL_), { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-7ots-Token': TOKEN }, body: JSON.stringify(body || {}) }).catch(() => {});
+app.whenReady().then(() => setTimeout(start, linux ? 400 : 0)); // Linux: the compositor needs a moment
 
-app.whenReady().then(() => {
+function start() {
   const area = screen.getPrimaryDisplay().workArea;
-  let x = area.x + Math.round(area.width * 0.7);
-  const y = area.y + area.height - H;
+  const home = () => [area.x + area.width - W - 24, area.y + area.height - H];
+  let [x, y] = home();
+
+  // Tray first: if there is one, the window can stay out of the taskbar; if not, it shows there so it can be found.
+  let tray = null;
+  try {
+    const img = nativeImage.createFromPath(ICON);
+    if (!img.isEmpty()) {
+      tray = new Tray(img.resize({ width: 22, height: 22 }));
+      tray.setToolTip('7ots pet');
+    }
+  } catch {}
+
   const win = new BrowserWindow({
     width: W,
     height: H,
     x,
     y,
-    transparent: true,
+    transparent: !OPAQUE,
     frame: false,
     resizable: false,
-    hasShadow: false,
+    hasShadow: OPAQUE,
     alwaysOnTop: true,
-    skipTaskbar: true,
-    backgroundColor: '#00000000',
+    skipTaskbar: !!tray,
+    title: '7ots pet',
+    icon: ICON,
+    backgroundColor: OPAQUE ? '#ffffff' : '#00000000',
     webPreferences: { contextIsolation: true, sandbox: true },
   });
   win.setAlwaysOnTop(true, 'floating');
   win.setVisibleOnAllWorkspaces?.(true);
-  win.loadURL(`${URL_}/pet?desktop=1&token=${encodeURIComponent(TOKEN)}`);
+  win.loadURL(`${URL_}/pet?desktop=1${OPAQUE ? '&opaque=1' : ''}${VIEW3D ? '&3d=1' : ''}&token=${encodeURIComponent(TOKEN)}`);
   win.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
   win.webContents.on('will-navigate', (e) => e.preventDefault());
 
-  const menu = Menu.buildFromTemplate([
-    { label: '🍎 Feed', click: () => post('/event', { type: 'feed' }) },
-    { label: '🎾 Play', click: () => post('/event', { type: 'play' }) },
-    { label: '💤 Sleep', click: () => post('/event', { type: 'sleep' }) },
-    { label: '☀️ Wake up', click: () => post('/event', { type: 'wake' }) },
-    { type: 'separator' },
-    { label: 'Stay still', type: 'checkbox', checked: false, click: (i) => (still = i.checked) },
-    { label: 'Hide (keeps running)', click: () => app.quit() },
-    { label: 'Quit pet', click: () => post('/quit').finally(() => app.quit()) },
-  ]);
-  win.webContents.on('context-menu', () => menu.popup({ window: win }));
+  let still = false;
+  const show = () => {
+    [x, y] = home();
+    win.setPosition(x, y);
+    win.showInactive();
+    win.moveTop();
+  };
+  const menu = () =>
+    Menu.buildFromTemplate([
+      win.isVisible() ? { label: tr('hide'), click: () => win.hide() } : { label: tr('show'), click: show },
+      { type: 'separator' },
+      { label: tr('talk'), click: () => { show(); win.focus(); win.webContents.executeJavaScript('postMessage({ talk: true })').catch(() => {}); } },
+      { label: tr('feed'), click: () => post('/event', { type: 'feed' }) },
+      { label: tr('play'), click: () => post('/event', { type: 'play' }) },
+      { label: tr('sleep'), click: () => post('/event', { type: 'sleep' }) },
+      { label: tr('wake'), click: () => post('/event', { type: 'wake' }) },
+      { type: 'separator' },
+      { label: tr('still'), type: 'checkbox', checked: still, click: (i) => (still = i.checked) },
+      { label: tr('quit'), click: () => post('/quit').finally(() => app.quit()) },
+    ]);
+  win.webContents.on('context-menu', () => menu().popup({ window: win }));
+  if (tray) {
+    const refresh = () => tray.setContextMenu(menu()); // Linux trays only show the context menu
+    refresh();
+    win.on('show', refresh);
+    win.on('hide', refresh);
+    tray.on('click', () => (win.isVisible() ? win.hide() : show()));
+  }
 
   // Walk: a few seconds walking, a few standing, turn at the edges.
   let dir = -1;
   let walking = false;
-  let still = false;
   let dragged = 0;
   let lastSet = x;
   win.on('moved', () => {
@@ -70,7 +120,7 @@ app.whenReady().then(() => {
     tell();
   }, 4000);
   setInterval(() => {
-    if (!walking || still || Date.now() - dragged < 8000 || win.isDestroyed()) return;
+    if (!walking || still || !win.isVisible() || Date.now() - dragged < 8000 || win.isDestroyed()) return;
     const [cx, cy] = win.getPosition();
     x = cx + dir * 2;
     if (x < area.x || x > area.x + area.width - W) {
@@ -81,6 +131,7 @@ app.whenReady().then(() => {
     lastSet = x;
     win.setPosition(x, cy);
   }, 40);
-});
+}
 
+// Hidden is not closed: the pet lives on in the tray until Quit.
 app.on('window-all-closed', () => app.quit());

package/cli/pet/pet.html

@@ -108,7 +108,11 @@
   .foot { display: flex; gap: 6px 12px; flex-wrap: wrap; justify-content: space-between; padding: 10px 18px 14px; color: var(--muted); font-size: 11.5px; border-top: 1px solid var(--line); background: var(--panel-2); }
   .foot b { color: var(--ink-2); font-weight: 600; }
 
+  .ask { display: flex; width: 100%; margin: 4px 0 2px; }
+  .ask input { flex: 1; min-width: 0; height: 36px; padding: 0 12px; border-radius: 12px; border: 1px solid var(--line); background: var(--panel-2); color: var(--ink); font: inherit; font-size: 13px; outline: none; }
+  .ask input:focus { border-color: var(--accent); }
   /* ── desktop: transparent frameless window walking along the bottom of the screen ── */
+  html:has(body.desktop:not(.opaque)) { background: transparent; } /* html also paints --bg: without this the window is a white box */
   body.desktop { background: transparent; padding: 0; place-items: end center; height: 100vh; overflow: hidden; -webkit-app-region: drag; user-select: none; }
   body.desktop .app { width: 100%; background: transparent; border: 0; box-shadow: none; border-radius: 0; overflow: visible; }
   body.desktop .top, body.desktop .who, body.desktop .level, body.desktop .stats, body.desktop .feed, body.desktop .foot { display: none; }
@@ -124,9 +128,13 @@
   body.desktop .act span { display: none; }
   body.desktop .act.primary { background: var(--accent); }
   body.desktop .badge { display: flex; }
+  body.desktop .ask { display: none; position: absolute; left: 6px; right: 6px; top: 6px; margin: 0; z-index: 4; -webkit-app-region: no-drag; }
+  body.desktop.talking .ask { display: flex; }
   .badge { display: none; position: absolute; z-index: 2; left: -6px; bottom: 18px; min-width: 22px; height: 22px; padding: 0 6px; border-radius: 99px; align-items: center; justify-content: center;
     background: var(--panel); border: 1px solid var(--line); box-shadow: var(--shadow); font: 750 11px/1 var(--font); color: var(--ink); }
   body.desktop .floor { bottom: 0; }
+  /* --opaque: a solid card instead of transparency (for Linux setups that paint a box behind the window) */
+  body.desktop.opaque { background: var(--panel); }
 
   @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation: none !important; transition: none !important; } }
 </style>
@@ -147,6 +155,7 @@
       <div class="floor" aria-hidden="true"></div>
       <span class="badge" id="badge"></span>
     </div>
+    <form class="ask" id="ask" autocomplete="off"><input id="askIn" maxlength="800" enterkeyhint="send"></form>
     <div class="who">
       <h1 id="name"></h1>
       <div class="sub"><span id="role"></span><span class="mood" id="mood"></span></div>
@@ -162,6 +171,7 @@
 
   <nav class="actions">
     <button class="act primary" data-act="feed"><svg viewBox="0 0 24 24"><path d="M12 7c-1.5-2.5-6-2.5-7 1.5S7 20 9.5 20c1.2 0 1.6-.6 2.5-.6s1.3.6 2.5.6C17 20 20 12.5 19 8.5S13.5 4.5 12 7z"/><path d="M12 7c0-2 1-3.5 3-4"/></svg><span data-t="feed"></span></button>
+    <button class="act" id="talkBtn" type="button"><svg viewBox="0 0 24 24"><path d="M5 6h14v9H9l-4 3z"/></svg><span data-t="talk"></span></button>
     <button class="act" data-act="play"><svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="8.5"/><path d="M5 8.5c3 1.5 11 1.5 14 0M5 15.5c3-1.5 11-1.5 14 0"/></svg><span data-t="play"></span></button>
     <button class="act" data-act="sleep" id="sleepBtn"><svg viewBox="0 0 24 24"><path d="M20 14.5A8 8 0 1 1 9.5 4a6.5 6.5 0 0 0 10.5 10.5z"/></svg><span data-t="sleep"></span></button>
   </nav>
@@ -177,17 +187,17 @@
 <script type="module">
   const BOOT = __BOOT__;
   const T = {
-    en: { feed: 'Feed', play: 'Play', sleep: 'Sleep', wake: 'Wake', food: 'Food', energy: 'Energy', fun: 'Fun', level: 'Level {l}', xp: '{x} / {n} xp', live: 'Live', off: 'Reconnecting…',
+    en: { talk: 'Talk', askPh: 'Remind me to check email in 10 min…', feed: 'Feed', play: 'Play', sleep: 'Sleep', wake: 'Wake', food: 'Food', energy: 'Energy', fun: 'Fun', level: 'Level {l}', xp: '{x} / {n} xp', live: 'Live', off: 'Reconnecting…',
       activity: 'Activity', empty: 'Nothing yet. Run a command or ask your coding agent something.', tally: '{ok} ok · {fail} failed · turns {turns}',
       brain: 'Brain: {b}', age: 'Born {d}', lines: 'built-in phrases', now: 'now', m: '{n}m', h: '{n}h',
       moods: { happy: 'Happy', neutral: 'Calm', sad: 'Sad', disgust: 'Bored', sleep: 'Asleep', thinking: 'Thinking' },
       kind: { tool: 'Tool', shell: 'Shell', prompt: 'You asked', stop: 'Turn finished', notify: 'Needs you', start: 'Session started' } },
-    es: { feed: 'Comida', play: 'Jugar', sleep: 'Dormir', wake: 'Despertar', food: 'Comida', energy: 'Energía', fun: 'Diversión', level: 'Nivel {l}', xp: '{x} / {n} xp', live: 'En vivo', off: 'Reconectando…',
+    es: { talk: 'Hablar', askPh: 'Recuérdame ver el correo en 10 min…', feed: 'Comida', play: 'Jugar', sleep: 'Dormir', wake: 'Despertar', food: 'Comida', energy: 'Energía', fun: 'Diversión', level: 'Nivel {l}', xp: '{x} / {n} xp', live: 'En vivo', off: 'Reconectando…',
       activity: 'Actividad', empty: 'Nada todavía. Ejecuta un comando o pregúntale algo a tu agente.', tally: '{ok} ok · {fail} fallos · turnos {turns}',
       brain: 'Cerebro: {b}', age: 'Nació {d}', lines: 'frases propias', now: 'ahora', m: '{n} min', h: '{n} h',
       moods: { happy: 'Feliz', neutral: 'Tranquilo', sad: 'Triste', disgust: 'Aburrido', sleep: 'Dormido', thinking: 'Pensando' },
       kind: { tool: 'Herramienta', shell: 'Terminal', prompt: 'Preguntaste', stop: 'Turno terminado', notify: 'Te necesita', start: 'Sesión iniciada' } },
-    pt: { feed: 'Comida', play: 'Brincar', sleep: 'Dormir', wake: 'Acordar', food: 'Comida', energy: 'Energia', fun: 'Diversão', level: 'Nível {l}', xp: '{x} / {n} xp', live: 'Ao vivo', off: 'Reconectando…',
+    pt: { talk: 'Falar', askPh: 'Me lembre de ver o e-mail em 10 min…', feed: 'Comida', play: 'Brincar', sleep: 'Dormir', wake: 'Acordar', food: 'Comida', energy: 'Energia', fun: 'Diversão', level: 'Nível {l}', xp: '{x} / {n} xp', live: 'Ao vivo', off: 'Reconectando…',
       activity: 'Atividade', empty: 'Nada ainda. Rode um comando ou pergunte algo ao seu agente.', tally: '{ok} ok · {fail} falhas · turnos {turns}',
       brain: 'Cérebro: {b}', age: 'Nasceu {d}', lines: 'frases próprias', now: 'agora', m: '{n} min', h: '{n} h',
       moods: { happy: 'Feliz', neutral: 'Tranquilo', sad: 'Triste', disgust: 'Entediado', sleep: 'Dormindo', thinking: 'Pensando' },
@@ -202,6 +212,7 @@
 
   document.documentElement.lang = lang;
   document.body.classList.toggle('desktop', desktop);
+  document.body.classList.toggle('opaque', desktop && new URLSearchParams(location.search).has('opaque'));
   document.title = `${id.name} · 7ots`;
   $('#name').textContent = id.name;
   $('#role').textContent = id.role || '';
@@ -217,8 +228,22 @@
   $('#brain').innerHTML = '';
   $('#brain').append(t('brain', { b: '' }), Object.assign(document.createElement('b'), { textContent: BOOT.brain === 'lines' ? t('lines') : BOOT.brain }));
 
-  const { createCharacter } = await import('/dist/7ots.esm.js');
-  const ch = createCharacter($('#face'), id.look?.character || {}, { locale: lang, title: id.name });
+  const { createCharacter, loadCharacter3D } = await import('/dist/7ots.esm.js');
+  const spec = id.look?.character || {};
+  let ch = null;
+  if (new URLSearchParams(location.search).has('3d')) {
+    // three comes from the CDN; without WebGL or network the 2D ot takes over
+    try {
+      const m = await loadCharacter3D();
+      ch = m.createCharacter3D($('#face'), spec, { material: 'plush', backdrop: !desktop, orbit: !desktop, stage: { key: 'pet', zIndex: 3, maxDpr: 2 } });
+      if (ch.fallback) console.warn('[7ots pet] no WebGL: 2D ot');
+    } catch (err) {
+      console.warn('[7ots pet] 3D ot unavailable, using 2D:', err?.message || err);
+      ch = null;
+    }
+  }
+  ch ||= createCharacter($('#face'), spec, { locale: lang, title: id.name });
+  const is3d = !!ch.character;
   addEventListener('pointermove', (e) => ch.lookAtPoint(e.clientX, e.clientY));
   $('#face').addEventListener('click', () => ch.gesture('bounce'));
 
@@ -395,9 +420,33 @@
   live.textContent = t('off');
   connect();
 
+  // ── talk: reminders, notes, open a site (POST /ask) ──
+  const ask = $('#ask');
+  const askIn = $('#askIn');
+  askIn.placeholder = t('askPh');
+  const talking = (on) => {
+    document.body.classList.toggle('talking', on);
+    if (on) askIn.focus();
+  };
+  $('#talkBtn').addEventListener('click', () => talking(!document.body.classList.contains('talking') || !desktop));
+  $('#face').addEventListener('dblclick', () => talking(true));
+  askIn.addEventListener('keydown', (e) => e.key === 'Escape' && talking(false));
+  ask.addEventListener('submit', async (e) => {
+    e.preventDefault();
+    const text = askIn.value.trim();
+    if (!text) return;
+    askIn.value = '';
+    if (desktop) talking(false);
+    const r = await post('/ask', { text }).then((x) => x.json()).catch(() => null);
+    if (!r) say('…');
+  });
+  addEventListener('message', (e) => e.data?.talk && talking(true));
+
   // The desktop shell tells us which way we walk.
   addEventListener('message', (e) => {
-    if (e.data?.walk != null) $('#stage').classList.toggle('flip', e.data.walk < 0);
+    if (e.data?.walk == null) return;
+    if (is3d) ch.character.yaw = e.data.walk ? -e.data.walk * 0.9 : 0; // turns toward where it walks
+    else $('#stage').classList.toggle('flip', e.data.walk < 0);
   });
 </script>
 </body>