npm - groove-dev - Versions diffs - 0.27.183 → 0.27.185 - Mend

groove-dev 0.27.183 → 0.27.185

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (65) hide show

package/packages/gui/dist/index.html CHANGED Viewed

@@ -6,12 +6,12 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" type="image/png" href="/favicon.png" />
     <title>Groove GUI</title>
-    <script type="module" crossorigin src="/assets/index-DPjGBQ5X.js"></script>
+    <script type="module" crossorigin src="/assets/index-DEZwM4Hb.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/vendor-26L3JoZv.js">
     <link rel="modulepreload" crossorigin href="/assets/reactflow-DoBZjiHE.js">
     <link rel="modulepreload" crossorigin href="/assets/codemirror-BYKpdS2W.js">
     <link rel="modulepreload" crossorigin href="/assets/xterm--7_ns2zW.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-CiOy7wVS.css">
+    <link rel="stylesheet" crossorigin href="/assets/index-CU8L_r5f.css">
   </head>
   <body>
     <div id="root"></div>

package/packages/gui/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@groove-dev/gui",
-  "version": "0.27.183",
+  "version": "0.27.185",
   "description": "GROOVE GUI — visual agent control plane",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/packages/gui/src/app.css CHANGED Viewed

@@ -40,6 +40,7 @@
   --color-info: #7ab0df;
   --color-purple: #b07fd5;
   --color-orange: #c4956a;
+  --color-indigo: #7c86e0;  /* InnerChat — agent-to-agent traffic */
   /* Fonts */
   --font-sans: 'Inter Variable', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;

package/packages/gui/src/components/agents/agent-feed.jsx CHANGED Viewed

@@ -4,7 +4,7 @@ import {
   Loader2, MessageSquare, SendHorizontal, Pause,
   FileEdit, Search, Terminal, CheckCircle2, AlertCircle,
   RotateCw, Zap, Wrench, Eye, Code2, Bug,
-  ChevronDown, Paperclip, GripHorizontal,
+  ChevronDown, Paperclip, GripHorizontal, ArrowLeftRight,
   FileCode, X, File, Image as ImageIcon, Film, Upload,
 } from 'lucide-react';
 import { AnimatePresence, motion } from 'framer-motion';
@@ -16,6 +16,7 @@ import { ThinkingIndicator } from '../ui/thinking-indicator';
 import { TableTree } from '../ui/table-tree';
 const EMPTY = [];
+const EMPTY_MAP = {};
 const KEEPER_RE = /(\[(?:save|append|update|delete|view|doc|link|read|instruct)\]|#[\w/.-]+)/gi;
 const KEEPER_CMD_RE = /^\[(?:save|append|update|delete|view|doc|link|read|instruct)\]$/i;
 const KEEPER_TAG_RE = /^#[\w/.-]+$/;
@@ -339,7 +340,45 @@ function UserMessage({ msg }) {
   );
 }
-function AgentMessage({ msg, agent }) {
+// An agent-to-agent turn. Deliberately styled apart from the normal feed —
+// amber rail and an explicit "X → Y" header — so it reads as traffic between
+// agents rather than something addressed to the user.
+function InnerChatMessage({ msg, agent }) {
+  const [collapsed, setCollapsed] = useState(msg.text?.length > 400);
+  const isLong = msg.text?.length > 400;
+  const { peer, direction, kind } = msg.innerchat || {};
+  const outbound = direction === 'out';
+  const me = agent?.name || 'this agent';
+  return (
+    <div className="rounded-md bg-indigo/[0.04] border border-indigo/15 px-2.5 py-2">
+      <div className="flex items-center gap-1.5 mb-1">
+        <ArrowLeftRight size={10} className="text-indigo flex-shrink-0" />
+        <span className="text-2xs font-semibold text-indigo font-sans">InnerChat</span>
+        <span className="text-2xs text-text-3 font-sans truncate">
+          {outbound ? `${me} → ${peer?.name}` : `${peer?.name} → ${me}`}
+        </span>
+        <span className="text-2xs text-text-4 font-sans">
+          {kind === 'answer' ? 'answer' : outbound ? 'asked' : 'asks'}
+        </span>
+        <span className="text-[10px] text-text-4 font-sans ml-auto flex-shrink-0">{timeAgo(msg.timestamp)}</span>
+      </div>
+      <div className="border-l-2 border-indigo/40 pl-3">
+        <StructuredMessage text={collapsed ? msg.text.slice(0, 400) + '...' : msg.text} />
+      </div>
+      {isLong && (
+        <button
+          onClick={() => setCollapsed((c) => !c)}
+          className="mt-1 text-2xs text-text-4 hover:text-indigo font-sans cursor-pointer"
+        >
+          {collapsed ? 'Show more' : 'Show less'}
+        </button>
+      )}
+    </div>
+  );
+}
+function AgentMessage({ msg, agent, answeredTo }) {
   const [collapsed, setCollapsed] = useState(msg.text?.length > 600);
   const isLong = msg.text?.length > 600;
@@ -348,9 +387,16 @@ function AgentMessage({ msg, agent }) {
       <div className="flex items-center gap-2 mb-1">
         <span className="text-2xs font-semibold text-text-1 font-sans">{agent?.name || 'Agent'}</span>
         <span className="text-2xs text-text-4 font-sans">{agent?.role}</span>
+        {/* This reply went to another agent, not to the user */}
+        {answeredTo && (
+          <span className="flex items-center gap-1 px-1.5 py-px rounded bg-indigo/10 text-2xs font-medium text-indigo font-sans">
+            <ArrowLeftRight size={9} />
+            to {answeredTo.name}
+          </span>
+        )}
         <span className="text-[10px] text-text-4 font-sans ml-auto">{timeAgo(msg.timestamp)}</span>
       </div>
-      <div className="border-l border-accent pl-3.5 py-1">
+      <div className={cn('pl-3.5 py-1 border-l', answeredTo ? 'border-indigo/50' : 'border-accent')}>
         <StructuredMessage text={collapsed ? msg.text.slice(0, 600) + '...' : msg.text} />
       </div>
       {collapsed && (
@@ -606,6 +652,8 @@ export function AgentFeed({ agent, readOnly = false }) {
   const rawActivityLog = useGrooveStore((s) => s.activityLog[agent.id]) || EMPTY;
   const instructAgent = useGrooveStore((s) => s.instructAgent);
   const isThinking = useGrooveStore((s) => s.thinkingAgents?.has(agent.id));
+  // Replies this agent sent to other agents, keyed by text — see innerchatAnswers.
+  const answerPeers = useGrooveStore((s) => s.innerchatAnswers?.[agent.id]) || EMPTY_MAP;
   const cachedChatRef = useRef(EMPTY);
   const cachedActivityRef = useRef(EMPTY);
   const cachedAgentIdRef = useRef(agent.id);
@@ -886,7 +934,15 @@ export function AgentFeed({ agent, readOnly = false }) {
           }
           if (item.from === 'user') return <UserMessage key={`user-${item._chatIdx}`} msg={item} />;
           if (item.from === 'system') return <SystemMessage key={`sys-${item._chatIdx}`} msg={item} />;
-          return <AgentMessage key={`agent-${item._chatIdx}`} msg={item} agent={agent} />;
+          if (item.from === 'innerchat') return <InnerChatMessage key={`ic-${item._chatIdx}`} msg={item} agent={agent} />;
+          return (
+            <AgentMessage
+              key={`agent-${item._chatIdx}`}
+              msg={item}
+              agent={agent}
+              answeredTo={answerPeers[item.text?.trim()]?.peer}
+            />
+          );
         })}
         <AnimatePresence>
           {(sending || isThinking) && (

package/packages/gui/src/components/agents/agent-panel.jsx CHANGED Viewed

@@ -6,7 +6,6 @@ import { AgentFeed } from './agent-feed';
 import { AgentConfig } from './agent-config';
 import { AgentTelemetry } from './agent-telemetry';
 import { AgentMdFiles } from './agent-mdfiles';
-import { InnerChatRelay } from './innerchat-relay';
 import { MessageSquare, Settings, Activity, FileText, Pencil, Check, X } from 'lucide-react';
 import { fmtNum, fmtUptime } from '../../lib/format';
 import { cn } from '../../lib/cn';
@@ -86,8 +85,6 @@ export function AgentPanel() {
   const [activeTab, setActiveTab] = useState('command');
   const cachedAgentRef = useRef(null);
-  const [innerChatOpen, setInnerChatOpen] = useState(false);
   const agentId = detailPanel?.type === 'agent' ? detailPanel.agentId : null;
   const liveAgent = agentId ? agents.find((a) => a.id === agentId) : null;
   if (liveAgent) cachedAgentRef.current = liveAgent;
@@ -159,37 +156,12 @@ export function AgentPanel() {
               </button>
             );
           })}
-          <div className="flex-1" />
-          {activeTab === 'command' && (
-            <button
-              onClick={() => setInnerChatOpen((v) => !v)}
-              className={cn(
-                'flex items-center gap-1 px-2 py-1.5 text-2xs font-semibold font-sans rounded transition-colors cursor-pointer border-b-2 -mb-px',
-                innerChatOpen
-                  ? 'text-warning border-warning/60'
-                  : 'text-text-4 border-transparent hover:text-warning',
-              )}
-              title="InnerChat — relay message to another agent"
-            >
-              <MessageSquare size={11} />
-              Relay
-            </button>
-          )}
         </div>
       </div>
       {/* ── Tab Content ────────────────────────────────────── */}
       <div className="flex-1 min-h-0 flex flex-col overflow-hidden">
-        {activeTab === 'command' && (
-          <>
-            <div className="flex-1 min-h-0 overflow-hidden">
-              <AgentFeed agent={agent} />
-            </div>
-            {innerChatOpen && (
-              <InnerChatRelay fromAgent={agent} onClose={() => setInnerChatOpen(false)} />
-            )}
-          </>
-        )}
+        {activeTab === 'command' && <AgentFeed agent={agent} />}
         {activeTab === 'config' && <AgentConfig agent={agent} />}
         {activeTab === 'telemetry' && <AgentTelemetry agent={agent} />}
         {activeTab === 'mdfiles' && <AgentMdFiles agent={agent} />}

package/packages/gui/src/components/fleet/fleet-agent-row.jsx CHANGED Viewed

@@ -1,6 +1,6 @@
 // FSL-1.1-Apache-2.0 — see LICENSE
 import { useState, useCallback, useRef, useEffect } from 'react';
-import { X } from 'lucide-react';
+import { X, Pencil } from 'lucide-react';
 import { useGrooveStore } from '../../stores/groove';
 import { cn } from '../../lib/cn';
 import { api } from '../../lib/api';
@@ -26,6 +26,7 @@ export function FleetAgentRow({ agent }) {
   const fleetSelectAgent = useGrooveStore((s) => s.fleetSelectAgent);
   const fleetMarkRead = useGrooveStore((s) => s.fleetMarkRead);
   const killAgent = useGrooveStore((s) => s.killAgent);
+  const addToast = useGrooveStore((s) => s.addToast);
   const unreadTs = useGrooveStore((s) => s.fleetUnreadMap[agent.id]);
   const chatHistory = useGrooveStore((s) => s.chatHistory[agent.id]);
@@ -69,7 +70,10 @@ export function FleetAgentRow({ agent }) {
     if (!trimmed || trimmed === agent.name) return;
     try {
       await api.patch(`/agents/${agent.id}`, { name: trimmed });
-    } catch { /* toast handles */ }
+    } catch (err) {
+      // Renames can legitimately fail — duplicate name, illegal characters.
+      addToast('error', 'Rename failed', err.message);
+    }
   }
   function handleKeyDown(e) {
@@ -158,6 +162,18 @@ export function FleetAgentRow({ agent }) {
         <span className="group-hover:hidden w-1.5 h-1.5 rounded-full bg-accent flex-shrink-0" />
       )}
+      {/* Rename — an explicit affordance, since double-click competes with
+          the row's drag handler and click-to-select */}
+      {!editing && !confirmKill && (
+        <button
+          onClick={(e) => { e.stopPropagation(); setEditing(true); setEditName(agent.name); }}
+          className="hidden group-hover:flex items-center justify-center p-0.5 rounded text-text-4 hover:text-accent transition-colors cursor-pointer flex-shrink-0"
+          title="Rename agent"
+        >
+          <Pencil size={11} />
+        </button>
+      )}
       {/* Remove button (visible on hover) */}
       {!editing && (
         <button

package/packages/gui/src/components/fleet/fleet-pane.jsx CHANGED Viewed

@@ -1,11 +1,10 @@
 // FSL-1.1-Apache-2.0 — see LICENSE
 import { useEffect, useRef, useState } from 'react';
-import { X, PanelRight, MessageSquare } from 'lucide-react';
+import { X, PanelRight } from 'lucide-react';
 import { useGrooveStore } from '../../stores/groove';
 import { cn } from '../../lib/cn';
 import { Badge } from '../ui/badge';
 import { AgentFeed } from '../agents/agent-feed';
-import { InnerChatRelay } from '../agents/innerchat-relay';
 import { fmtNum } from '../../lib/format';
 const STATUS_VARIANT = {
@@ -40,7 +39,6 @@ export function FleetPane({ agentId, paneIndex, readOnly = false }) {
   const openDetail = useGrooveStore((s) => s.openDetail);
   const detailPanel = useGrooveStore((s) => s.detailPanel);
   const isPanelOpen = detailPanel?.type === 'agent' && detailPanel?.agentId === resolvedId;
-  const [relayOpen, setRelayOpen] = useState(false);
   const lastAgentRef = useRef(liveAgent);
   const [gone, setGone] = useState(false);
@@ -97,16 +95,6 @@ export function FleetPane({ agentId, paneIndex, readOnly = false }) {
         )}>
           {ctxPct}%
         </span>
-        <button
-          onClick={() => setRelayOpen((v) => !v)}
-          className={cn(
-            'p-1 rounded-md transition-colors cursor-pointer',
-            relayOpen ? 'text-warning' : 'text-text-3 hover:text-warning hover:bg-surface-3',
-          )}
-          title="Relay a message to another agent"
-        >
-          <MessageSquare size={14} />
-        </button>
         <button
           onClick={() => openDetail({ type: 'agent', agentId: resolvedId })}
           className={cn(
@@ -130,8 +118,6 @@ export function FleetPane({ agentId, paneIndex, readOnly = false }) {
       <div className="flex-1 min-h-0">
         <AgentFeed agent={agent} readOnly={readOnly} />
       </div>
-      {relayOpen && <InnerChatRelay fromAgent={agent} onClose={() => setRelayOpen(false)} />}
     </div>
   );
 }

package/packages/gui/src/components/fleet/fleet-sidebar.jsx CHANGED Viewed

@@ -5,6 +5,9 @@ import { useGrooveStore } from '../../stores/groove';
 import { cn } from '../../lib/cn';
 import { FleetAgentRow } from './fleet-agent-row';
+const AGENT_DRAG = 'application/x-fleet-agent';
+const TEAM_DRAG = 'application/x-fleet-team';
 function teamStatusDot(agents) {
   if (agents.some((a) => a.status === 'crashed')) return 'bg-danger';
   if (agents.some((a) => a.status === 'running' || a.status === 'starting')) return 'bg-accent';
@@ -27,6 +30,7 @@ export function FleetSidebar({ width }) {
   const addToast = useGrooveStore((s) => s.addToast);
   const moveAgentToTeam = useGrooveStore((s) => s.moveAgentToTeam);
+  const reorderTeams = useGrooveStore((s) => s.reorderTeams);
   const [dropTeamId, setDropTeamId] = useState(null);
   const [confirmDeleteTeam, setConfirmDeleteTeam] = useState(null);
@@ -128,20 +132,27 @@ export function FleetSidebar({ width }) {
     setRenamingTeamId(null);
   }
-  // Team headers accept agent rows dragged from any other team.
+  // A team block accepts two kinds of drop: an agent row (reassign its team)
+  // or another team header (reorder the list).
   function handleDragOver(e, teamId) {
-    if (!e.dataTransfer.types.includes('application/x-fleet-agent')) return;
+    const { types } = e.dataTransfer;
+    const isAgent = types.includes(AGENT_DRAG);
+    const isTeam = types.includes(TEAM_DRAG);
+    if (!isAgent && !isTeam) return;
     e.preventDefault();
-    e.dataTransfer.dropEffect = 'link';
+    e.dataTransfer.dropEffect = isAgent ? 'link' : 'move';
     if (dropTeamId !== teamId) setDropTeamId(teamId);
   }
   function handleDrop(e, teamId) {
-    const agentId = e.dataTransfer.getData('application/x-fleet-agent');
     setDropTeamId(null);
-    if (!agentId) return;
+    const agentId = e.dataTransfer.getData(AGENT_DRAG);
+    const draggedTeamId = e.dataTransfer.getData(TEAM_DRAG);
+    if (!agentId && !draggedTeamId) return;
     e.preventDefault();
-    moveAgentToTeam(agentId, teamId);
+    if (agentId) moveAgentToTeam(agentId, teamId);
+    else if (draggedTeamId !== teamId) reorderTeams(draggedTeamId, teamId);
   }
   function startRename(e, team) {
@@ -200,11 +211,18 @@ export function FleetSidebar({ width }) {
               }}
               onDrop={(e) => handleDrop(e, team.id)}
             >
-              {/* Team header */}
-              <div className={cn(
-                'w-full flex items-center gap-1 px-2 py-1.5 rounded-md hover:bg-surface-2 transition-colors group',
-                isConfirming && 'bg-danger/10 hover:bg-danger/20',
-              )}>
+              {/* Team header — draggable to reorder the sidebar list */}
+              <div
+                draggable={renamingTeamId !== team.id}
+                onDragStart={(e) => {
+                  e.dataTransfer.setData(TEAM_DRAG, team.id);
+                  e.dataTransfer.effectAllowed = 'move';
+                }}
+                className={cn(
+                  'w-full flex items-center gap-1 px-2 py-1.5 rounded-md hover:bg-surface-2 transition-colors group',
+                  isConfirming && 'bg-danger/10 hover:bg-danger/20',
+                )}
+              >
                 {renamingTeamId === team.id ? (
                   <div className="flex items-center gap-1.5 flex-1 min-w-0 pl-1">
                     <input

package/packages/gui/src/stores/groove.js CHANGED Viewed

@@ -372,36 +372,50 @@ export const useGrooveStore = create((set, get) => ({
         case 'innerchat:turn': {
           const { thread, turn } = msg.data;
           if (turn.status === 'failed') {
-            get().addToast('error', `Relay to ${turn.to.name} failed`, turn.error);
+            get().addToast('error', `InnerChat to ${turn.to.name} failed`, turn.error);
+            break;
           }
-          // The turn lands in the recipient's chat, badged with who sent it.
           set((s) => {
             const history = { ...s.chatHistory };
-            const arr = [...(history[turn.to.id] || [])];
-            arr.push({
+            const entry = (peer, direction) => ({
               from: 'innerchat',
               text: turn.text,
               timestamp: turn.timestamp,
               isQuery: false,
-              innerchat: {
-                turnId: turn.id,
-                threadId: thread.id,
-                kind: turn.kind,
-                fromAgent: turn.from,
-              },
+              innerchat: { turnId: turn.id, threadId: thread.id, kind: turn.kind, peer, direction },
             });
-            history[turn.to.id] = arr.slice(-100);
+            const push = (agentId, item) => {
+              history[agentId] = [...(history[agentId] || []), item].slice(-100);
+            };
+            if (turn.kind === 'ask') {
+              // Both sides see the question — the asker as outgoing, the
+              // target as incoming — so neither feed has an unexplained gap.
+              push(turn.from.id, entry(turn.to, 'out'));
+              push(turn.to.id, entry(turn.from, 'in'));
+            } else {
+              // The answer reaches the asker over HTTP, so only it needs a
+              // feed entry. The responder already shows this text as its own
+              // agent message; that one gets badged via innerchatAnswers
+              // rather than duplicated here.
+              push(turn.to.id, entry(turn.from, 'in'));
+            }
             persistJSON('groove:chatHistory', history);
+            const answers = { ...s.innerchatAnswers };
+            if (turn.kind === 'answer') {
+              answers[turn.from.id] = {
+                ...(answers[turn.from.id] || {}),
+                [turn.text.trim()]: { peer: turn.to, threadId: thread.id },
+              };
+            }
             const threads = { ...s.innerchatThreads, [thread.id]: thread };
             persistJSON('groove:innerchatThreads', threads);
-            return { chatHistory: history, innerchatThreads: threads };
+            return { chatHistory: history, innerchatThreads: threads, innerchatAnswers: answers };
           });
-          if (turn.kind === 'reply' && turn.status !== 'failed') {
-            get().addToast('info', `${turn.from.name} replied`, `Forwarded to ${turn.to.name}`);
-          }
           break;
         }
@@ -605,6 +619,12 @@ export const useGrooveStore = create((set, get) => ({
           get().fetchTeams();
           break;
+        // Reordering already applied optimistically on the client that did it;
+        // this keeps every other window in sync.
+        case 'teams:reordered':
+          if (msg.teams) set({ teams: msg.teams });
+          break;
         case 'approval:request':
           set((s) => ({ pendingApprovals: [...s.pendingApprovals, msg.data] }));
           break;

package/packages/gui/src/stores/slices/agents-slice.js CHANGED Viewed

@@ -123,6 +123,12 @@ export const createAgentsSlice = (set, get) => ({
   innerchatThreads: loadJSON('groove:innerchatThreads') || {},
+  // agentId -> { <answer text>: { peer, threadId } }. An agent's answer to
+  // another agent arrives as an ordinary result, indistinguishable in its own
+  // feed from a message meant for the user — this is what lets the feed badge
+  // it. Keyed by text so it works regardless of which event lands first.
+  innerchatAnswers: {},
   // Relay a message from one agent to another. Pass threadId to continue an
   // existing exchange rather than opening a new one.
   async sendInnerChat(fromId, toId, message, threadId = null) {

package/packages/gui/src/stores/slices/teams-slice.js CHANGED Viewed

@@ -173,6 +173,28 @@ export const createTeamsSlice = (set, get) => ({
     }
   },
+  // Move a team to a new index in the sidebar. Applied optimistically so the
+  // drop lands instantly, then reconciled with whatever the daemon persisted.
+  async reorderTeams(draggedId, targetId) {
+    const current = get().teams;
+    const from = current.findIndex((t) => t.id === draggedId);
+    const to = current.findIndex((t) => t.id === targetId);
+    if (from === -1 || to === -1 || from === to) return;
+    const next = [...current];
+    const [moved] = next.splice(from, 1);
+    next.splice(to, 0, moved);
+    set({ teams: next });
+    try {
+      const { teams } = await api.post('/teams/reorder', { orderedIds: next.map((t) => t.id) });
+      if (teams) set({ teams });
+    } catch (err) {
+      set({ teams: current });
+      get().addToast('error', 'Failed to reorder teams', err.message);
+    }
+  },
   async promoteTeam(id) {
     try {
       const team = await api.post(`/teams/${encodeURIComponent(id)}/promote`);

package/packages/gui/src/views/memory.jsx CHANGED Viewed

@@ -6,16 +6,19 @@ import { ScrollArea } from '../components/ui/scroll-area';
 import { Dialog, DialogContent } from '../components/ui/dialog';
 import { BookOpen, Plus, Search, Trash2, Pencil, ChevronRight, Hash, FolderOpen, Clock, Save, Link2, FileText, Sparkles, HelpCircle, GripVertical, CornerLeftUp } from 'lucide-react';
+// `cmd` is the bare word; the UI always renders it bracketed so the real
+// syntax — [cmd] #tag — is never ambiguous. `example` shows a full, copyable
+// line so a new user can see exactly what to type.
 const COMMANDS = [
-  { cmd: 'save',     args: '#tag',                desc: 'Save the message and send it to the agent' },
-  { cmd: 'append',   args: '#tag',                desc: 'Add to an existing memory and send to agent' },
-  { cmd: 'update',   args: '#tag',                desc: 'Open the editor to modify a memory in place' },
-  { cmd: 'delete',   args: '#tag',                desc: 'Remove a memory permanently' },
-  { cmd: 'view',     args: '#tag',                desc: 'Read a memory in the viewer' },
-  { cmd: 'read',     args: '#tag1 #tag2 ...',     desc: 'Send memory content to the agent — chat stays clean' },
-  { cmd: 'doc',      args: '#tag',                desc: 'AI synthesizes the full conversation into a document' },
-  { cmd: 'link',     args: '#tag path/to/doc',    desc: 'Link a memory to a NORTHSTAR or external document' },
-  { cmd: '[instruct]', args: '',                  desc: 'Show this command reference' },
+  { cmd: 'save',     example: '[save] #api-auth',           desc: 'Save the current message as a new memory under #api-auth' },
+  { cmd: 'append',   example: '[append] #api-auth',         desc: 'Add the current message to the existing #api-auth memory' },
+  { cmd: 'update',   example: '[update] #api-auth',         desc: 'Open the editor to change the #api-auth memory' },
+  { cmd: 'view',     example: '[view] #api-auth',           desc: 'Open a memory to read it, without sending it to the agent' },
+  { cmd: 'read',     example: '[read] #api-auth #db-schema', desc: 'Send one or more memories to the agent as context (chat stays clean)' },
+  { cmd: 'doc',      example: '[doc] #api-auth',            desc: 'Let the AI synthesize the conversation into a memory' },
+  { cmd: 'link',     example: '[link] #api-auth docs/spec.md', desc: 'Link a memory to a NORTHSTAR or external document' },
+  { cmd: 'delete',   example: '[delete] #api-auth',         desc: 'Delete a memory permanently' },
+  { cmd: 'instruct', example: '[instruct]',                 desc: 'Show this command reference' },
 ];
 function formatRelative(iso) {
@@ -219,36 +222,58 @@ function EditorModal({ open, onOpenChange, editing, onSave, onRename }) {
 function InstructModal({ open, onOpenChange }) {
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent title="Keeper Commands" description="Memory system command reference" className="max-w-lg">
+      <DialogContent title="Memory Commands" description="How to save and recall tagged memories" className="max-w-lg">
         <div className="p-5 space-y-4">
-          <p className="text-xs text-text-2 leading-relaxed">
-            Type these commands in any agent chat to manage your tagged memories. Commands are intercepted by the Keeper sidecar — the agent never sees them.
-          </p>
-          <div className="space-y-1.5">
+          {/* Format primer — the part new users miss */}
+          <div className="rounded-lg bg-surface-2 border border-border-subtle p-3 space-y-2">
+            <p className="text-xs text-text-2 leading-relaxed">
+              Type a command in any agent chat. The format is always the command in
+              <span className="font-mono text-accent"> [square brackets]</span>, then a
+              <span className="font-mono text-accent"> #tag</span>:
+            </p>
+            <div className="flex items-center gap-2 font-mono text-sm">
+              <span className="px-1.5 py-0.5 rounded bg-accent/15 text-accent font-semibold">[save]</span>
+              <span className="px-1.5 py-0.5 rounded bg-info/10 text-info font-semibold">#api-auth</span>
+              <span className="text-text-3 text-xs font-sans">your message here</span>
+            </div>
+            <p className="text-xs text-text-4 leading-relaxed">
+              These commands are handled by GROOVE — the agent never sees them.
+            </p>
+          </div>
+          <div className="space-y-1">
             {COMMANDS.map((c) => (
               <div key={c.cmd} className="flex items-start gap-3 py-1.5 border-b border-border-subtle last:border-0">
-                <div className="flex-shrink-0 flex items-center gap-1">
-                  <span className="px-1.5 py-0.5 rounded bg-accent/15 text-accent font-mono text-xs font-semibold">{c.cmd}</span>
-                  {c.args && <span className="text-xs text-text-3 font-mono">{c.args}</span>}
-                </div>
+                <code className="flex-shrink-0 w-44 text-xs font-mono text-text-1 pt-0.5">
+                  {c.example.split(/(\[[^\]]+\]|#[\w/-]+)/).map((part, i) => {
+                    if (/^\[.+\]$/.test(part)) return <span key={i} className="text-accent font-semibold">{part}</span>;
+                    if (/^#/.test(part)) return <span key={i} className="text-info">{part}</span>;
+                    return <span key={i} className="text-text-4">{part}</span>;
+                  })}
+                </code>
                 <span className="text-xs text-text-3 pt-0.5">{c.desc}</span>
               </div>
             ))}
           </div>
-          <div className="pt-2 space-y-2">
-            <h3 className="text-xs font-semibold text-text-1">Tag Hierarchy</h3>
-            <p className="text-xs text-text-3 leading-relaxed">
-              Use <span className="font-mono text-accent">/</span> to create nested tags: <span className="font-mono text-accent">#groove/memory-system</span> lives under <span className="font-mono text-accent">#groove</span>. Pull a parent tag to get all children.
-            </p>
-            <h3 className="text-xs font-semibold text-text-1">Memory Types</h3>
-            <p className="text-xs text-text-3 leading-relaxed">
-              <span className="font-semibold">Manual</span> — you write it via [save], [append], [update]. <span className="font-semibold">Doc</span> — AI writes it via [doc], synthesizing your conversation. Both are fully editable.
-            </p>
-            <h3 className="text-xs font-semibold text-text-1">Spawning with Context</h3>
-            <p className="text-xs text-text-3 leading-relaxed">
-              When spawning a new agent, use [pull] #tag to inject memories into their context. You can also link memories to NORTHSTAR docs with [link] for cross-referencing.
-            </p>
+          <div className="pt-1 space-y-2.5">
+            <div>
+              <h3 className="text-xs font-semibold text-text-1 mb-1">Nested tags</h3>
+              <p className="text-xs text-text-3 leading-relaxed">
+                Use <span className="font-mono text-accent">/</span> to nest:
+                <span className="font-mono text-info"> #groove/memory</span> lives under
+                <span className="font-mono text-info"> #groove</span>. Reading the parent tag pulls every memory beneath it.
+              </p>
+            </div>
+            <div>
+              <h3 className="text-xs font-semibold text-text-1 mb-1">Give a new agent context</h3>
+              <p className="text-xs text-text-3 leading-relaxed">
+                Use <span className="font-mono"><span className="text-accent">[read]</span> <span className="text-info">#tag</span></span> to
+                drop saved memories into an agent's chat as background — useful right after spawning one.
+              </p>
+            </div>
           </div>
           <div className="flex justify-end pt-1">
             <Button variant="ghost" size="sm" onClick={() => onOpenChange(false)}>Close</Button>
           </div>