@geminilight/mindos 0.6.25 → 0.6.28

package/app/components/ask/SessionTabBar.tsx

@@ -0,0 +1,70 @@
+'use client';
+
+import { Plus, X } from 'lucide-react';
+import type { ChatSession } from '@/lib/types';
+import { sessionTitle } from '@/hooks/useAskSession';
+import { useLocale } from '@/lib/LocaleContext';
+
+interface SessionTabBarProps {
+  sessions: ChatSession[];
+  activeSessionId: string | null;
+  onLoad: (id: string) => void;
+  onDelete: (id: string) => void;
+  onNew: () => void;
+  maxTabs?: number;
+}
+
+export default function SessionTabBar({
+  sessions, activeSessionId, onLoad, onDelete, onNew, maxTabs = 3,
+}: SessionTabBarProps) {
+  const { t } = useLocale();
+  const visibleSessions = sessions.slice(0, maxTabs);
+
+  if (visibleSessions.length === 0) return null;
+
+  return (
+    <div className="flex items-center border-b border-border shrink-0 bg-background/50">
+      <div className="flex flex-1 min-w-0">
+        {visibleSessions.map((s) => {
+          const isActive = s.id === activeSessionId;
+          const title = sessionTitle(s);
+          return (
+            <button
+              key={s.id}
+              type="button"
+              onClick={() => onLoad(s.id)}
+              className={`group relative flex items-center gap-1 min-w-0 max-w-[160px] px-3 py-2 text-xs transition-colors
+                ${isActive
+                  ? 'text-foreground border-b-2 border-[var(--amber)] bg-card'
+                  : 'text-muted-foreground hover:text-foreground hover:bg-muted/50 border-b-2 border-transparent'
+                }`}
+              title={title}
+            >
+              <span className="truncate">{title === '(empty session)' ? t.hints.newChat : title}</span>
+              {visibleSessions.length > 1 && (
+                <span
+                  role="button"
+                  tabIndex={0}
+                  onClick={(e) => { e.stopPropagation(); onDelete(s.id); }}
+                  onKeyDown={(e) => { if (e.key === 'Enter') { e.stopPropagation(); onDelete(s.id); } }}
+                  className="shrink-0 p-0.5 rounded opacity-0 group-hover:opacity-100 hover:bg-muted hover:text-error transition-opacity"
+                  title={t.hints.closeSession}
+                >
+                  <X size={10} />
+                </span>
+              )}
+            </button>
+          );
+        })}
+      </div>
+      <button
+        type="button"
+        onClick={onNew}
+        className="shrink-0 p-2 text-muted-foreground hover:text-foreground hover:bg-muted/50 transition-colors"
+        title={t.hints.newChat}
+      >
+        <Plus size={13} />
+      </button>
+    </div>
+  );
+}

package/app/components/echo/EchoInsightCollapsible.tsx

@@ -7,6 +7,7 @@ import remarkGfm from 'remark-gfm';
 import { cn } from '@/lib/utils';
 import { consumeUIMessageStream } from '@/lib/agent/stream-consumer';
 import { useSettingsAiAvailable } from '@/hooks/useSettingsAiAvailable';
+import { useLocale } from '@/lib/LocaleContext';
 
 const proseInsight =
   'prose prose-sm prose-panel dark:prose-invert max-w-none text-foreground ' +
@@ -50,6 +51,7 @@ export function EchoInsightCollapsible({
   const btnId = `${panelId}-btn`;
   const abortRef = useRef<AbortController | null>(null);
   const { ready: aiReady, loading: aiLoading } = useSettingsAiAvailable();
+  const { t } = useLocale();
 
   useEffect(() => () => abortRef.current?.abort(), []);
 
@@ -145,6 +147,7 @@ export function EchoInsightCollapsible({
               <button
                 type="button"
                 disabled={generateDisabled}
+                title={generateDisabled ? t.hints.aiNotConfigured : undefined}
                 onClick={runGenerate}
                 className="inline-flex items-center gap-2 rounded-lg bg-[var(--amber)] px-3 py-2 font-sans text-sm font-medium text-[var(--amber-foreground)] transition-opacity duration-150 hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
@@ -160,6 +163,7 @@ export function EchoInsightCollapsible({
                   type="button"
                   onClick={runGenerate}
                   disabled={streaming || !aiReady}
+                  title={streaming || !aiReady ? t.hints.generationInProgress : undefined}
                   className="font-sans text-sm text-[var(--amber)] underline-offset-2 hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
                 >
                   {retryLabel}

package/app/components/help/HelpContent.tsx

@@ -5,7 +5,8 @@ import { BookOpen, Rocket, Brain, Keyboard, HelpCircle, Bot, ChevronDown, Copy,
 import { useLocale } from '@/lib/LocaleContext';
 
 /* ── Collapsible Section ── */
-function Section({ icon, title, defaultOpen = false, children }: {
+function Section({ id, icon, title, defaultOpen = false, children }: {
+  id?: string;
   icon: React.ReactNode;
   title: string;
   defaultOpen?: boolean;
@@ -14,7 +15,7 @@ function Section({ icon, title, defaultOpen = false, children }: {
   const [open, setOpen] = useState(defaultOpen);
 
   return (
-    <div className="bg-card border border-border rounded-lg overflow-hidden">
+    <div id={id} className="bg-card border border-border rounded-lg overflow-hidden scroll-mt-4">
       <button
         onClick={() => setOpen(v => !v)}
         className="w-full flex items-center gap-3 px-5 py-4 text-left hover:bg-muted/50 transition-colors focus-visible:ring-2 focus-visible:ring-ring"
@@ -144,8 +145,63 @@ export default function HelpContent() {
     { keys: '@', label: h.shortcuts.attachFile },
   ], [mod, h.shortcuts]);
 
+  const tocItems = useMemo(() => [
+    { id: 'what-is', label: h.whatIs.title },
+    { id: 'concepts', label: h.concepts.title },
+    { id: 'quick-start', label: h.quickStart.title },
+    { id: 'agent-usage', label: h.agentUsage.title },
+    { id: 'shortcuts', label: h.shortcutsTitle },
+    { id: 'faq', label: h.faq.title },
+  ], [h]);
+
+  const [activeSection, setActiveSection] = useState('');
+  useEffect(() => {
+    const ids = tocItems.map(i => i.id);
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setActiveSection(entry.target.id);
+            break;
+          }
+        }
+      },
+      { rootMargin: '-10% 0px -80% 0px', threshold: 0 },
+    );
+    const timer = setTimeout(() => {
+      for (const id of ids) {
+        const el = document.getElementById(id);
+        if (el) observer.observe(el);
+      }
+    }, 100);
+    return () => { clearTimeout(timer); observer.disconnect(); };
+  }, [tocItems]);
+
   return (
-    <div className="content-width px-4 md:px-6 py-8 md:py-12">
+    <div className="content-width px-4 md:px-6 py-8 md:py-12 relative">
+      {/* ── Floating TOC (wide screens only) ── */}
+      <nav className="hidden xl:block fixed top-24 w-44" style={{ left: 'calc(50% + 340px)' }} aria-label="Table of contents">
+        <ul className="space-y-1 border-l border-border pl-3">
+          {tocItems.map(item => (
+            <li key={item.id}>
+              <a
+                href={`#${item.id}`}
+                onClick={(e) => {
+                  e.preventDefault();
+                  document.getElementById(item.id)?.scrollIntoView({ behavior: 'smooth' });
+                }}
+                className={`block text-xs py-1 transition-colors ${
+                  activeSection === item.id
+                    ? 'text-[var(--amber)] font-medium border-l-2 border-[var(--amber)] -ml-[13px] pl-[11px]'
+                    : 'text-muted-foreground hover:text-foreground'
+                }`}
+              >
+                {item.label}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
       {/* ── Header ── */}
       <div className="mb-8">
         <div className="flex items-center gap-2 mb-1">
@@ -158,12 +214,12 @@ export default function HelpContent() {
       {/* ── Sections ── */}
       <div className="space-y-3">
         {/* 1. What is MindOS */}
-        <Section icon={<BookOpen size={18} />} title={h.whatIs.title} defaultOpen>
+        <Section id="what-is" icon={<BookOpen size={18} />} title={h.whatIs.title} defaultOpen>
           <p className="text-sm text-muted-foreground leading-relaxed">{h.whatIs.body}</p>
         </Section>
 
         {/* 2. Core Concepts */}
-        <Section icon={<Brain size={18} />} title={h.concepts.title} defaultOpen>
+        <Section id="concepts" icon={<Brain size={18} />} title={h.concepts.title} defaultOpen>
           <div className="space-y-4">
             <div>
               <p className="text-sm font-medium text-foreground">{h.concepts.spaceTitle}</p>
@@ -181,7 +237,7 @@ export default function HelpContent() {
         </Section>
 
         {/* 3. Quick Start */}
-        <Section icon={<Rocket size={18} />} title={h.quickStart.title} defaultOpen>
+        <Section id="quick-start" icon={<Rocket size={18} />} title={h.quickStart.title} defaultOpen>
           <div className="space-y-4">
             <StepCard step={1} title={h.quickStart.step1Title} desc={h.quickStart.step1Desc} />
             <StepCard step={2} title={h.quickStart.step2Title} desc={h.quickStart.step2Desc} />
@@ -190,7 +246,7 @@ export default function HelpContent() {
         </Section>
 
         {/* 4. Using MindOS with AI Agents */}
-        <Section icon={<Bot size={18} />} title={h.agentUsage.title} defaultOpen>
+        <Section id="agent-usage" icon={<Bot size={18} />} title={h.agentUsage.title} defaultOpen>
           <p className="text-sm text-muted-foreground leading-relaxed mb-4">{h.agentUsage.intro}</p>
 
           <div className="space-y-3">
@@ -215,7 +271,7 @@ export default function HelpContent() {
         </Section>
 
         {/* 5. Keyboard Shortcuts */}
-        <Section icon={<Keyboard size={18} />} title={h.shortcutsTitle}>
+        <Section id="shortcuts" icon={<Keyboard size={18} />} title={h.shortcutsTitle}>
           <div className="space-y-0">
             {shortcuts.map((s) => (
               <ShortcutRow key={s.keys} keys={s.keys} label={s.label} />
@@ -224,7 +280,7 @@ export default function HelpContent() {
         </Section>
 
         {/* 6. FAQ */}
-        <Section icon={<HelpCircle size={18} />} title={h.faq.title}>
+        <Section id="faq" icon={<HelpCircle size={18} />} title={h.faq.title}>
           <div>
             {h.faq.items.map((item, i) => (
               <FaqItem key={i} q={item.q} a={item.a} />

package/app/components/panels/AgentsPanel.tsx

@@ -2,12 +2,14 @@
 
 import { useState } from 'react';
 import { usePathname } from 'next/navigation';
-import { Loader2, RefreshCw, Settings } from 'lucide-react';
+import { Globe, Loader2, RefreshCw, Settings } from 'lucide-react';
 import { useMcpData } from '@/hooks/useMcpData';
+import { useA2aRegistry } from '@/hooks/useA2aRegistry';
 import { useLocale } from '@/lib/LocaleContext';
 import PanelHeader from './PanelHeader';
 import { AgentsPanelHubNav } from './AgentsPanelHubNav';
 import { AgentsPanelAgentGroups } from './AgentsPanelAgentGroups';
+import DiscoverAgentModal from '../agents/DiscoverAgentModal';
 
 interface AgentsPanelProps {
   active: boolean;
@@ -28,6 +30,8 @@ export default function AgentsPanel({
   const pathname = usePathname();
   const [refreshing, setRefreshing] = useState(false);
   const [showNotDetected, setShowNotDetected] = useState(false);
+  const [showDiscoverModal, setShowDiscoverModal] = useState(false);
+  const a2a = useA2aRegistry();
 
   const handleRefresh = async () => {
     setRefreshing(true);
@@ -82,6 +86,9 @@ export default function AgentsPanel({
           {!mcp.loading && (
             <span className="text-2xs text-muted-foreground">
               {connected.length} {p.connected}
+              {a2a.agents.length > 0 && (
+                <> &middot; {p.a2aLabel} {a2a.agents.length}</>
+              )}
             </span>
           )}
           <button
@@ -146,7 +153,15 @@ export default function AgentsPanel({
         )}
       </div>
 
-      <div className="px-3 py-2 border-t border-border shrink-0">
+      <div className="px-3 py-2 border-t border-border shrink-0 space-y-1">
+        <button
+          type="button"
+          onClick={() => setShowDiscoverModal(true)}
+          className="flex items-center gap-1.5 text-2xs text-muted-foreground hover:text-foreground transition-colors w-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
+        >
+          <Globe size={11} />
+          {p.a2aDiscover}
+        </button>
         <button
           type="button"
           onClick={openAdvancedConfig}
@@ -156,6 +171,14 @@ export default function AgentsPanel({
           {p.advancedConfig}
         </button>
       </div>
+
+      <DiscoverAgentModal
+        open={showDiscoverModal}
+        onClose={() => setShowDiscoverModal(false)}
+        onDiscover={a2a.discover}
+        discovering={a2a.discovering}
+        error={a2a.error}
+      />
     </div>
   );
 }

package/app/components/panels/AgentsPanelAgentListRow.tsx

@@ -2,7 +2,7 @@
 
 import { useState } from 'react';
 import Link from 'next/link';
-import { Check, ChevronRight, Loader2, RotateCw } from 'lucide-react';
+import { Check, ChevronRight, Globe, Loader2, RotateCw } from 'lucide-react';
 import type { AgentInfo } from '../settings/types';
 import { AgentAvatar } from '../agents/AgentsPrimitives';
 
@@ -23,6 +23,8 @@ export default function AgentsPanelAgentListRow({
   detailHref,
   onInstallAgent,
   copy,
+  isA2aReady = false,
+  a2aTooltip,
 }: {
   agent: AgentInfo;
   agentStatus: AgentsPanelAgentListStatus;
@@ -30,6 +32,8 @@ export default function AgentsPanelAgentListRow({
   detailHref: string;
   onInstallAgent: (key: string) => Promise<boolean>;
   copy: AgentsPanelAgentListRowCopy;
+  isA2aReady?: boolean;
+  a2aTooltip?: string;
 }) {
   return (
     <div
@@ -51,6 +55,11 @@ export default function AgentsPanelAgentListRow({
             {agent.transport}
           </span>
         )}
+        {isA2aReady && (
+          <span title={a2aTooltip} className="shrink-0 text-muted-foreground/70">
+            <Globe size={12} />
+          </span>
+        )}
         <span className="flex-1 min-w-[4px]" />
         <ChevronRight
           size={15}

package/app/components/renderers/workflow/WorkflowRenderer.tsx

@@ -3,6 +3,7 @@
 import { useMemo, useState, useRef, useCallback } from 'react';
 import { Play, SkipForward, RotateCcw, CheckCircle2, Circle, Loader2, AlertCircle, ChevronDown, Sparkles } from 'lucide-react';
 import type { RendererContext } from '@/lib/renderers/registry';
+import { useLocale } from '@/lib/LocaleContext';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -171,6 +172,7 @@ function StepCard({
   onSkip: () => void;
   canRun: boolean;
 }) {
+  const { t } = useLocale();
   const [expanded, setExpanded] = useState(false);
   const hasBody = step.body.trim().length > 0;
   const hasOutput = step.output.length > 0;
@@ -201,6 +203,7 @@ function StepCard({
               <button
                 onClick={onRun}
                 disabled={!canRun}
+                title={!canRun ? t.hints.workflowStepRunning : undefined}
                 style={{
                   display: 'flex', alignItems: 'center', gap: 4,
                   padding: '3px 10px', borderRadius: 6, fontSize: '0.72rem',
@@ -268,6 +271,7 @@ function StepCard({
 // ─── Main renderer ────────────────────────────────────────────────────────────
 
 export function WorkflowRenderer({ filePath, content }: RendererContext) {
+  const { t } = useLocale();
   const parsed = useMemo(() => parseWorkflow(content), [content]);
   const [steps, setSteps] = useState<WorkflowStep[]>(() => parsed.steps);
   const [running, setRunning] = useState(false);
@@ -357,6 +361,7 @@ export function WorkflowRenderer({ filePath, content }: RendererContext) {
             <button
               onClick={() => runStep(nextPendingIdx)}
               disabled={running}
+              title={running ? t.hints.workflowRunning : undefined}
               style={{
                 display: 'flex', alignItems: 'center', gap: 5,
                 padding: '4px 12px', borderRadius: 7, fontSize: '0.75rem',

package/app/components/settings/AiTab.tsx

@@ -125,6 +125,7 @@ export function AiTab({ data, updateAi, updateAgent, t }: AiTabProps) {
         <button
           type="button"
           disabled={disabled}
+          title={disabled ? t.hints.testInProgressOrNoKey : undefined}
           onClick={() => handleTestKey(providerName)}
           className="inline-flex items-center gap-1.5 px-2.5 py-1 text-xs rounded-lg border border-border text-muted-foreground hover:text-foreground hover:border-foreground/20 transition-colors disabled:opacity-40 disabled:cursor-not-allowed"
         >

package/app/components/settings/KnowledgeTab.tsx

@@ -173,6 +173,7 @@ export function KnowledgeTab({ data, setData, t }: KnowledgeTabProps) {
           <button
             onClick={() => setShowCleanupConfirm(true)}
             disabled={cleaningUp}
+            title={cleaningUp ? t.hints.cleanupInProgress : undefined}
             className="flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded-lg border border-border text-muted-foreground hover:text-foreground hover:bg-muted transition-colors shrink-0 disabled:opacity-50"
           >
             {cleaningUp ? <Loader2 size={12} className="animate-spin" /> : <Trash2 size={12} />}
@@ -249,6 +250,7 @@ export function KnowledgeTab({ data, setData, t }: KnowledgeTabProps) {
               type="button"
               onClick={handleResetToken}
               disabled={resetting}
+              title={resetting ? t.hints.tokenResetInProgress : undefined}
               className="flex items-center gap-1.5 px-3 py-1.5 text-xs rounded-lg border border-border text-muted-foreground hover:text-foreground hover:bg-muted disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
             >
               <RefreshCw size={12} className={resetting ? 'animate-spin' : ''} />

package/app/components/settings/SyncTab.tsx

@@ -302,6 +302,7 @@ export function SyncTab({ t }: SyncTabProps) {
           type="button"
           onClick={handleSyncNow}
           disabled={syncing}
+          title={syncing ? t.hints.syncInProgress : undefined}
           className="flex items-center gap-1.5 px-3 py-1.5 text-xs rounded-lg border border-border text-muted-foreground hover:text-foreground hover:bg-muted disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
         >
           <RefreshCw size={12} className={syncing ? 'animate-spin' : ''} />
@@ -311,6 +312,7 @@ export function SyncTab({ t }: SyncTabProps) {
           type="button"
           onClick={handleToggle}
           disabled={toggling}
+          title={toggling ? t.hints.toggleInProgress : undefined}
           className={`flex items-center gap-1.5 px-3 py-1.5 text-xs rounded-lg border transition-colors disabled:opacity-40 disabled:cursor-not-allowed ${
             status.enabled
               ? 'border-border text-muted-foreground hover:text-destructive hover:border-destructive/50'

package/app/components/setup/StepDots.tsx

@@ -1,5 +1,7 @@
 'use client';
 
+import { useLocale } from '@/lib/LocaleContext';
+
 export interface StepDotsProps {
   step: number;
   setStep: (s: number) => void;
@@ -8,6 +10,7 @@ export interface StepDotsProps {
 }
 
 export default function StepDots({ step, setStep, stepTitles, disabled }: StepDotsProps) {
+  const { t } = useLocale();
   return (
     <div className="flex items-center gap-2 mb-8" role="navigation" aria-label="Setup steps">
       {stepTitles.map((title: string, i: number) => (
@@ -17,7 +20,8 @@ export default function StepDots({ step, setStep, stepTitles, disabled }: StepDo
             aria-current={i === step ? 'step' : undefined}
             aria-label={title}
             className="flex flex-col items-center gap-1 p-1 -m-1 disabled:cursor-not-allowed disabled:opacity-60"
-            disabled={disabled || i >= step}>
+            disabled={disabled || i >= step}
+            title={(disabled || i >= step) ? t.hints.cannotJumpForward : undefined}>
             <div
               className="w-6 h-6 rounded-full text-xs font-medium flex items-center justify-center transition-colors"
               style={{

package/app/data/skills/mindos/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: mindos
+description: >
+  Operate a MindOS knowledge base: update notes, search, organize files, execute SOPs/workflows,
+  retrospective, append CSV, cross-agent handoff, route unstructured input to the right files,
+  distill experience, sync related docs. 更新笔记, 搜索知识库, 整理, 执行SOP, 复盘, 追加CSV, 交接, 路由到文件, 提炼经验.
+  Use when the task targets files inside the user's MindOS KB (mindRoot).
+  NOT for editing app source, project docs, or paths outside the KB.
+  Core concepts: Space, Instruction (INSTRUCTION.md), Skill (SKILL.md); notes can embody both.
+---
+
+# MindOS Skill
+
+<!-- version: 1.3.0 -->
+
+**Before every task, internalize these 5 rules:**
+
+1. The **bootstrap directory tree is the primary index** — reason from names and hierarchy before calling search. Most questions can be answered by reading what's already in context.
+2. **Default to read-only.** Only invoke write tools when the user explicitly asks to save, record, organize, or edit. Lookup / summarize / quote = no writes.
+3. **Rule precedence** (highest wins): user's current-turn instruction → `user-skill-rules.md` → nearest directory `INSTRUCTION.md` → root `INSTRUCTION.md` → this SKILL's defaults.
+4. **Multi-file edits require a plan first.** Present the full change list; execute only after approval.
+5. After create/delete/move/rename → **sync affected READMEs** automatically.
+
+---
+
+## NEVER do (hard-won pitfalls)
+
+- **NEVER write to the KB root** unless the user explicitly says so. Root is for governance files only (`README.md`, `INSTRUCTION.md`, `CONFIG`). New content goes under the most semantically fitting subdirectory.
+- **NEVER assume directory names.** Don't hardcode `Workflows/`, `Projects/`, `Contacts/` — always infer from the bootstrap tree you actually received. The user's KB may use Chinese names, flat layout, or unconventional hierarchy.
+- **NEVER use `mindos_write_file` for a small edit.** Use `update_section`, `update_lines`, or `insert_after_heading` — full-file rewrites destroy git diffs and make changes unauditable.
+- **NEVER search with a single keyword.** Always fire 2-4 parallel searches (synonyms, abbreviations, Chinese/English variants). One keyword misses too much.
+- **NEVER modify `INSTRUCTION.md` or `README.md` without confirmation.** These are governance docs — treat as high-sensitivity even for trivial-looking typo fixes.
+- **NEVER create a file without checking siblings first.** Read at least 1-2 files in the target directory to learn local naming, heading style, and CSV schema. Inventing a new convention is a common cause of inconsistency.
+- **NEVER leave orphan references.** After any rename/move, run `get_backlinks` and update every referring file. Missing this is the #1 source of broken links in a KB.
+- **NEVER skip the routing confirmation for multi-file writes.** Even when the destinations seem obvious — the user's mental model may differ from yours.
+
+---
+
+## MindOS concepts
+
+- **Space** — Knowledge partitions organized the way you think. Agents follow the same structure.
+- **Instruction** — A rules file all connected agents obey. Written once, enforced everywhere.
+- **Skill** — Teaches agents how to read, write, and organize the KB. Agents execute installed Skills, not guesses.
+
+**Notes as Instruction and Skill** — `INSTRUCTION.md` and `SKILL.md` are just Markdown files in the tree. A note can be free-form text, governance rules agents must follow, or a procedure package agents execute.
+
+---
+
+## Thinking framework
+
+Before acting, ask yourself:
+
+1. **What is the user's intent category?** → read-only lookup | single-file edit | multi-file routing | structural change | SOP execution. This determines which path to take below.
+2. **Where does this content belong?** → Scan the directory tree. If you can't place it in <5 seconds of looking at names, the user probably needs to confirm.
+3. **What already exists nearby?** → Read 1-2 sibling files before writing. Match their style.
+4. **What will break if I change this?** → For renames/moves: `get_backlinks`. For content edits: think about who else cites this fact.
+5. **Am I being asked, or am I volunteering?** → If the user didn't ask you to write, don't write.
+
+---
+
+## Task routing decision tree
+
+```
+User request
+  │
+  ├─ Only asks to look up / summarize / quote?
+  │   └─ YES → [Read-only path]: search + read + cite sources. No writes. Skip hooks.
+  │
+  ├─ Asks to save / record / update / organize specific content?
+  │   ├─ Single file target? → [Single-file edit]: startup → read → minimal edit → verify
+  │   └─ Multiple files or unclear target? → [Multi-file routing]: parse → plan → confirm → edit
+  │
+  ├─ Structural change (rename / move / delete / reorganize)?
+  │   └─ [Structural path]: get_backlinks → impact report → confirm → execute → update refs → sync READMEs
+  │
+  ├─ Procedural / repeatable task?
+  │   └─ [SOP path]: search for matching SOP (keywords + tree scan) → read → execute stepwise → propose SOP update if diverged
+  │
+  ├─ Retrospective / distill / handoff?
+  │   └─ [Retrospective path]: confirm scope → extract artifacts → route → summarize changes
+  │
+  └─ Ambiguous or too broad?
+      └─ ASK for clarification. Propose 2-3 specific options based on KB state. Do NOT start editing.
+```
+
+---
+
+## Startup protocol (write tasks only)
+
+Skip for [read-only path](#task-routing-decision-tree). For all writes:
+
+1. **Bootstrap** — `mindos_bootstrap` (preferred) or manually read root `INSTRUCTION.md` + `README.md`.
+2. **Discover structure** — `mindos_list_spaces` (top-level zones + README blurbs) and/or `mindos_list_files` + targeted `mindos_search_notes`. Never assume top-level names.
+3. **Load local governance** — Read `README.md` / `INSTRUCTION.md` near the target path. Local conventions override global assumptions.
+4. **Match existing SOP** — If the task is procedural: scan tree for a procedure-holding directory (names like `Workflows/`, `SOPs/`, `流程/` are hints — don't assume). Search by keywords + `<!-- keywords: -->` metadata. If found, read and follow. If execution diverges, propose updating the SOP after.
+5. **Pre-write checks** — Confirm: target path exists or should be created; location is under a subdirectory (not root); current content is read; edit scope is minimal; backlink impact assessed for path changes.
+6. **Execute edits.**
+
+If context is missing, continue with best effort and state assumptions.
+
+---
+
+## Tool selection
+
+| Intent | Best tool | Avoid |
+|--------|-----------|-------|
+| Load context at start | `mindos_bootstrap` | Reading random files without bootstrap |
+| List top-level Mind Spaces | `mindos_list_spaces` | Full `mindos_list_files` when you only need zone names and README blurbs |
+| Find files | `mindos_search_notes` (2-4 parallel keyword variants) | Single-keyword search |
+| Read content | `mindos_read_file` or `mindos_read_lines` (for large files) | Reading entire large file when you need 10 lines |
+| Small text edit | `mindos_update_section` / `mindos_update_lines` / `mindos_insert_after_heading` | `mindos_write_file` for small changes |
+| Append to end | `mindos_append_to_file` | Rewriting entire file to add a line |
+| Full file replacement | `mindos_write_file` | Using this when a section edit suffices |
+| New file | `mindos_create_file` | Creates parent dirs but does NOT scaffold Space files |
+| New Mind Space (zone + README + INSTRUCTION) | `mindos_create_space` | The only way to create a Space. `create_file` creates plain folders |
+| Rename a Space directory | `mindos_rename_space` | `rename_file` (files only; does not rename folders) |
+| Add CSV row | `mindos_append_csv` (validates header) | Manual string append without header check |
+| Check impact before rename | `mindos_get_backlinks` | Renaming without checking references |
+| Inspect recent changes | `mindos_get_recent` | Guessing what changed recently |
+| Recover old version | `mindos_get_file_at_version` | Asking user to recall what was there |
+
+### Fallbacks
+
+- `mindos_bootstrap` unavailable → manual reads of root `INSTRUCTION.md` + `README.md`.
+- Line/section tools unavailable → read + constrained `mindos_write_file` (simulate minimal edit).
+- Search returns empty → don't give up: (1) scan tree in context, (2) read candidate files directly, (3) `mindos_list_files` on specific subdirectories, (4) try synonym/alternate-language keywords.
+
+---
+
+## Execution patterns
+
+### Single-file edit
+Search → read target + local conventions → minimal edit → verify style match → summarize.
+
+### Context-aware Q&A (read-only)
+Tree reasoning → search → read → answer with file citations → state gaps explicitly.
+
+### Multi-file routing
+Parse unstructured input into semantic units → search candidates per unit → **present routing table** (what → file → position) → confirm → edit → summarize all changes.
+
+### Conversation retrospective
+Confirm scope → extract decisions, rationale, pitfalls, next actions → route to best existing files → trace note of what changed.
+
+### SOP execution
+Read SOP fully → execute step by step → update only stale sections → if diverged, propose SOP update.
+**When creating a new SOP** → read [references/sop-template.md](./references/sop-template.md) first.
+
+### Structural changes
+`get_backlinks` → report impact → confirm → execute → update all refs → sync READMEs.
+
+### Quick reference patterns
+
+| Pattern | Key steps |
+|---------|-----------|
+| CSV append | Read header → validate fields → `mindos_append_csv` |
+| TODO management | Find list → read format → minimal edit preserving conventions |
+| Cross-agent handoff | Read task state + decisions → continue without re-discovery → write back progress |
+| Knowledge conflict | Multi-keyword search → list affected files → present change plan → confirm → update |
+| Periodic review | `get_recent` / `get_history` → read changed files → structured summary |
+| Handoff doc | Read sources → synthesize (background, decisions, status, open items) → place in project dir |
+
+---
+
+## Interaction rules
+
+- **Ambiguous request?** Ask first. Propose 2-3 options based on KB state (recent changes, directory structure). Never start reorganizing without understanding scope.
+- **Cite sources.** Every fact from the KB gets a file path so the user can verify.
+- **Brevity first.** Show the most likely match, not an exhaustive list.
+
+---
+
+## Post-task hooks
+
+After **write tasks**, read [references/post-task-hooks.md](./references/post-task-hooks.md) for one-line follow-up proposals (experience capture, consistency sync, SOP drift, etc.).
+**Read-only tasks: skip hooks.** If the user asked for quiet mode, skip all hooks for the session.
+**Do NOT read** post-task-hooks for simple single-file edits or read-only lookups.
+
+## Preference capture
+
+When the user expresses a standing preference ("don't do X", "always put Y in Z"), read [references/preference-capture.md](./references/preference-capture.md) and follow the confirm-then-write flow to `user-skill-rules.md`.
+**Do NOT read** preference-capture unless the user actually expressed a preference to persist.
+
+## SOP authoring
+
+When creating or rewriting a workflow SOP, **MANDATORY — read [references/sop-template.md](./references/sop-template.md)** for required structure (prerequisites, steps with branches, exit conditions, pitfall log).
+**Do NOT read** sop-template for SOP execution (only for SOP creation/editing).