npm - groove-dev - Versions diffs - 0.27.184 → 0.27.186 - Mend

groove-dev 0.27.184 → 0.27.186

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 (60) 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-BpOyN6Zf.js"></script>
+    <script type="module" crossorigin src="/assets/index-DOOaCFRS.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-DiXB7yry.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.184",
+  "version": "0.27.186",
   "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';
@@ -12,10 +12,12 @@ import { useGrooveStore } from '../../stores/groove';
 import { cn } from '../../lib/cn';
 import { timeAgo } from '../../lib/format';
 import { api } from '../../lib/api';
+import { extractLogPaths, logLabel } from '../../lib/logpaths';
 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 +341,75 @@ 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 info = msg.innerchat || {};
+  // `peer` is the current field; `fromAgent` is the pre-`tell` schema still
+  // sitting in persisted chatHistory. Fall back so old bubbles never render
+  // "undefined".
+  const peer = info.peer || info.fromAgent;
+  const peerName = peer?.name || 'another agent';
+  const outbound = info.direction === 'out';
+  const isAnswer = info.kind === 'answer' || info.kind === 'reply';
+  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} → ${peerName}` : `${peerName} → ${me}`}
+        </span>
+        <span className="text-2xs text-text-4 font-sans">
+          {isAnswer ? '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>
+  );
+}
+// One-click "tail" chips for any log paths the agent mentioned — saves asking
+// "what's the log file?" and hand-copying it into a terminal.
+function LogChips({ text }) {
+  const runInTerminal = useGrooveStore((s) => s.runInTerminal);
+  const paths = useMemo(() => extractLogPaths(text), [text]);
+  if (paths.length === 0) return null;
+  return (
+    <div className="ml-3.5 mt-1.5 flex flex-wrap gap-1.5">
+      {paths.map((path) => (
+        <button
+          key={path}
+          onClick={() => runInTerminal(`tail -f ${path}`)}
+          title={`tail -f ${path}`}
+          className="inline-flex items-center gap-1.5 px-2 py-0.5 rounded-md bg-accent/10 hover:bg-accent/20 text-accent text-[11px] font-medium font-sans cursor-pointer transition-colors max-w-full"
+        >
+          <Terminal size={11} className="flex-shrink-0" />
+          <span className="truncate">tail {logLabel(path)}</span>
+        </button>
+      ))}
+    </div>
+  );
+}
+function AgentMessage({ msg, agent, answeredTo }) {
   const [collapsed, setCollapsed] = useState(msg.text?.length > 600);
   const isLong = msg.text?.length > 600;
@@ -348,11 +418,19 @@ 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>
+      <LogChips text={msg.text} />
       {collapsed && (
         <button
           onClick={() => setCollapsed(false)}
@@ -606,6 +684,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 +966,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/editor/terminal.jsx CHANGED Viewed

@@ -31,6 +31,7 @@ function TerminalInstance({ tabId, visible, registerKill, onSelectionChange }) {
   const mountedRef = useRef(false);
   const visibleRef = useRef(visible);
   const lastSizeRef = useRef({ cols: 0, rows: 0 });
+  const outputReadyRef = useRef(false);
   useEffect(() => {
     registerKill?.(tabId, () => {
@@ -41,6 +42,28 @@ function TerminalInstance({ tabId, visible, registerKill, onSelectionChange }) {
     });
   }, [tabId, registerKill]);
+  // Run a command dropped into the store by another component (e.g. a "tail
+  // log" chip in chat). Only the visible tab handles it, and we poll until this
+  // instance's PTY is ready — a freshly opened terminal spawns asynchronously,
+  // and keystrokes sent before it's ready are dropped.
+  const pendingCommand = useGrooveStore((s) => s.terminalPendingCommand);
+  useEffect(() => {
+    if (!pendingCommand || !visible) return;
+    let tries = 0;
+    let timer = null;
+    const send = () => {
+      const ws = useGrooveStore.getState().ws;
+      if (ws?.readyState === WebSocket.OPEN && termIdRef.current && outputReadyRef.current) {
+        ws.send(JSON.stringify({ type: 'terminal:input', id: termIdRef.current, data: pendingCommand.command + '\r' }));
+        useGrooveStore.getState().clearTerminalPendingCommand();
+        return;
+      }
+      if (tries++ < 40) timer = setTimeout(send, 150); // ~6s max, covers spawn
+    };
+    send();
+    return () => clearTimeout(timer);
+  }, [pendingCommand, visible]);
   useEffect(() => {
     if (!containerRef.current || mountedRef.current) return;
     mountedRef.current = true;
@@ -111,6 +134,7 @@ function TerminalInstance({ tabId, visible, registerKill, onSelectionChange }) {
             // Wipe xterm so garbled output from wrong-sized PTY is never visible
             term.reset();
             outputReady = true;
+            outputReadyRef.current = true;
             // Ask the shell to clear screen and redraw its prompt
             const w2 = useGrooveStore.getState().ws;
             if (w2?.readyState === WebSocket.OPEN && termIdRef.current) {
@@ -121,6 +145,7 @@ function TerminalInstance({ tabId, visible, registerKill, onSelectionChange }) {
           if (outputReady) term.write(msg.data);
         } else if (msg.type === 'terminal:exit' && msg.id === termIdRef.current) {
           outputReady = true;
+          outputReadyRef.current = false; // no live shell to accept commands
           term.write('\r\n\x1b[90m[session ended]\x1b[0m\r\n');
           termIdRef.current = null;
         }

package/packages/gui/src/lib/logpaths.js ADDED Viewed

@@ -0,0 +1,45 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+// Pull tailable log targets out of an agent's message so the chat can offer a
+// one-click "tail" instead of the user asking "what's the log file?".
+//
+// Two signals, in priority order:
+//   1. An explicit `tail -f <path>` the agent already wrote — highest confidence.
+//   2. Any path-like token ending in .log.
+// Both are conservative: a bare word like "changelog" is not a path and won't
+// match, and results are de-duped by full path.
+const TAIL_RE = /tail\s+(?:-[a-zA-Z]+\s+)*([~/]?[\w./-]+)/g;
+const DOTLOG_RE = /(?:^|[\s'"`(=])([~/]?(?:[\w.-]+\/)*[\w.-]+\.log)\b/g;
+function clean(p) {
+  return p.replace(/^['"`]+/, '').replace(/['"`.,;:)]+$/, '');
+}
+export function extractLogPaths(text) {
+  if (!text || typeof text !== 'string') return [];
+  const out = [];
+  const seen = new Set();
+  const add = (raw) => {
+    const p = clean(raw);
+    // Require something path-shaped: a slash, a ~, or a .log extension. Guards
+    // against picking up plain words that followed "tail".
+    if (!p || p.length < 3) return;
+    if (!p.endsWith('.log') && !p.includes('/') && !p.startsWith('~')) return;
+    if (seen.has(p)) return;
+    seen.add(p);
+    out.push(p);
+  };
+  for (const m of text.matchAll(TAIL_RE)) add(m[1]);
+  for (const m of text.matchAll(DOTLOG_RE)) add(m[1]);
+  return out;
+}
+// A short label for the chip — the basename, which is what the user recognizes.
+export function logLabel(path) {
+  const base = path.replace(/\/+$/, '').split('/').pop() || path;
+  return base.length > 28 ? `…${base.slice(-27)}` : base;
+}

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;
         }

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/ui-slice.js CHANGED Viewed

@@ -106,6 +106,17 @@ export const createUiSlice = (set, get) => ({
     set(updates);
     localStorage.setItem('groove:terminalVisible', String(v));
   },
+  // Cross-component channel for running a command in the terminal panel. The
+  // terminal id lives inside the active TerminalInstance, so components can't
+  // send to it directly — they drop a command here, the visible instance picks
+  // it up (waiting for its PTY to be ready) and clears it.
+  terminalPendingCommand: null,
+  runInTerminal(command) {
+    get().setTerminalVisible(true);
+    set({ terminalPendingCommand: { command, ts: Date.now() } });
+  },
+  clearTerminalPendingCommand() { set({ terminalPendingCommand: null }); },
   setTerminalHeight(h) {
     set({ terminalHeight: h });
     localStorage.setItem('groove:terminalHeight', String(h));

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>