@geminilight/mindos 0.6.39 → 0.6.41

package/app/components/shared/ProviderSelect.tsx

@@ -0,0 +1,134 @@
+'use client';
+
+import { useState } from 'react';
+import { CheckCircle2, ChevronDown, SkipForward } from 'lucide-react';
+import { type ProviderId, PROVIDER_PRESETS, groupedProviders } from '@/lib/agent/providers';
+import { useLocale } from '@/lib/stores/locale-store';
+
+interface ProviderSelectProps {
+  value: ProviderId | 'skip';
+  onChange: (id: ProviderId | 'skip') => void;
+  showSkip?: boolean;
+  compact?: boolean;
+  configuredProviders?: Set<ProviderId>;
+}
+
+export default function ProviderSelect({
+  value, onChange, showSkip = false, compact = false, configuredProviders,
+}: ProviderSelectProps) {
+  const { locale } = useLocale();
+  const [showMore, setShowMore] = useState(false);
+  const groups = groupedProviders();
+
+  const renderItem = (id: ProviderId) => {
+    const preset = PROVIDER_PRESETS[id];
+    const displayName = locale === 'zh' ? preset.nameZh : preset.name;
+    const isSelected = value === id;
+    const isConfigured = configuredProviders?.has(id);
+
+    if (compact) {
+      return (
+        <button
+          key={id}
+          type="button"
+          onClick={() => onChange(id)}
+          className={`flex items-center gap-2 px-3 py-2 rounded-lg border text-left transition-all text-sm ${
+            isSelected
+              ? 'border-[var(--amber)] bg-[var(--amber-subtle)] shadow-sm'
+              : 'border-border/50 hover:border-border hover:bg-muted/30'
+          }`}
+        >
+          <span className={`font-medium ${isSelected ? 'text-foreground' : 'text-muted-foreground'}`}>
+            {displayName}
+          </span>
+          {isConfigured && !isSelected && (
+            <CheckCircle2 size={12} className="text-success ml-auto shrink-0" />
+          )}
+          {isSelected && (
+            <CheckCircle2 size={14} className="ml-auto shrink-0" style={{ color: 'var(--amber)' }} />
+          )}
+        </button>
+      );
+    }
+
+    return (
+      <button
+        key={id}
+        type="button"
+        onClick={() => onChange(id)}
+        className="flex items-start gap-3 p-4 rounded-xl border text-left transition-all duration-150"
+        style={{
+          background: isSelected ? 'var(--amber-dim)' : 'var(--card)',
+          borderColor: isSelected ? 'var(--amber)' : 'var(--border)',
+        }}
+      >
+        <div className="flex-1 min-w-0">
+          <p className="text-sm font-medium" style={{ color: 'var(--foreground)' }}>{displayName}</p>
+          <p className="text-xs mt-0.5" style={{ color: 'var(--muted-foreground)' }}>
+            {preset.defaultModel}
+          </p>
+        </div>
+        {isConfigured && !isSelected && (
+          <CheckCircle2 size={14} className="text-success shrink-0 mt-0.5" />
+        )}
+        {isSelected && (
+          <CheckCircle2 size={16} className="shrink-0 mt-0.5" style={{ color: 'var(--amber)' }} />
+        )}
+      </button>
+    );
+  };
+
+  const { primary: primaryItems, more: moreItems } = groups;
+
+  return (
+    <div className="space-y-2">
+      {/* Primary providers — always visible */}
+      <div className={compact ? 'flex flex-wrap gap-2' : 'grid grid-cols-1 gap-2'}>
+        {primaryItems.map(renderItem)}
+      </div>
+
+      {/* Show more toggle */}
+      {moreItems.length > 0 && (
+        <>
+          <button
+            type="button"
+            onClick={() => setShowMore(!showMore)}
+            className="flex items-center gap-1 text-xs text-muted-foreground hover:text-foreground transition-colors py-1"
+          >
+            <ChevronDown size={12} className={`transition-transform ${showMore ? 'rotate-180' : ''}`} />
+            {showMore
+              ? (locale === 'zh' ? '收起' : 'Show less')
+              : (locale === 'zh' ? `更多 (${moreItems.length})` : `More providers (${moreItems.length})`)}
+          </button>
+
+          {showMore && (
+            <div className={compact ? 'flex flex-wrap gap-2' : 'grid grid-cols-1 gap-2'}>
+              {moreItems.map(renderItem)}
+            </div>
+          )}
+        </>
+      )}
+
+      {/* Skip option — only in onboarding */}
+      {showSkip && (
+        <button
+          type="button"
+          onClick={() => onChange('skip')}
+          className="flex items-center gap-2 px-3 py-2 rounded-lg border text-left transition-all text-sm w-full mt-1"
+          style={{
+            background: value === 'skip' ? 'var(--amber-dim)' : 'var(--card)',
+            borderColor: value === 'skip' ? 'var(--amber)' : 'var(--border)',
+          }}
+        >
+          <SkipForward size={14} className="shrink-0" style={{ color: value === 'skip' ? 'var(--amber)' : 'var(--muted-foreground)' }} />
+          <span className={`font-medium ${value === 'skip' ? 'text-foreground' : 'text-muted-foreground'}`}>
+            {locale === 'zh' ? '暂时跳过' : 'Skip for now'}
+          </span>
+          {value === 'skip' && (
+            <CheckCircle2 size={14} className="ml-auto shrink-0" style={{ color: 'var(--amber)' }} />
+          )}
+        </button>
+      )}
+    </div>
+  );
+}

package/app/components/walkthrough/WalkthroughOverlay.tsx

@@ -1,8 +1,8 @@
 'use client';
 
 import { useState, useEffect, useCallback, useId } from 'react';
-import { useLocale } from '@/lib/LocaleContext';
-import { useWalkthrough } from './WalkthroughProvider';
+import { useLocale } from '@/lib/stores/locale-store';
+import { useWalkthrough } from '@/lib/stores/walkthrough-store';
 import { walkthroughSteps } from './steps';
 import WalkthroughTooltip from './WalkthroughTooltip';
 

package/app/components/walkthrough/WalkthroughTooltip.tsx

@@ -1,8 +1,8 @@
 'use client';
 
 import { useState, useEffect } from 'react';
-import { useLocale } from '@/lib/LocaleContext';
-import { useWalkthrough } from './WalkthroughProvider';
+import { useLocale } from '@/lib/stores/locale-store';
+import { useWalkthrough } from '@/lib/stores/walkthrough-store';
 
 interface WalkthroughTooltipProps {
   stepIndex: number;

package/app/components/walkthrough/index.ts

@@ -1,3 +1,3 @@
-export { default as WalkthroughProvider, useWalkthrough } from './WalkthroughProvider';
+export { useWalkthrough } from '@/lib/stores/walkthrough-store';
 export { walkthroughSteps } from './steps';
 export type { WalkthroughAnchor } from './steps';

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

@@ -15,152 +15,152 @@ description: >
 
 # MindOS Skill
 
-<!-- version: 1.3.2 -->
+<!-- version: 3.0.0 — CLI-first, MCP optional -->
+
+## CLI commands
+
+Use `mindos file <subcommand>` for all knowledge base operations. Add `--json` for structured output.
+
+| Operation | Command |
+|-----------|---------|
+| List files | `mindos file list` |
+| Read file | `mindos file read <path>` |
+| Write/overwrite | `mindos file write <path> --content "..."` |
+| Create new file | `mindos file create <path> --content "..."` |
+| Append to file | `mindos file append <path> --content "..."` |
+| Edit section | `mindos file edit-section <path> -H "## Heading" --content "..."` |
+| Insert after heading | `mindos file insert-heading <path> -H "## Heading" --content "..."` |
+| Append CSV row | `mindos file append-csv <path> --row "col1,col2,col3"` |
+| Delete file | `mindos file delete <path>` |
+| Rename/move | `mindos file rename <old> <new>` |
+| Search | `mindos search "query"` |
+| Backlinks | `mindos file backlinks <path>` |
+| Recent files | `mindos file recent --limit 10` |
+| Git history | `mindos file history <path>` |
+| List spaces | `mindos space list` |
+| Create space | `mindos space create "name"` |
+
+> **MCP users:** If you only have MCP tools (`mindos_*`), use them directly — they are self-describing via their schemas. Prefer CLI when available (lower token cost).
+
+### CLI setup
+
+```bash
+npm install -g @geminilight/mindos
+# Remote mode: mindos config set url http://<IP>:<PORT> && mindos config set authToken <token>
+```
+
+---
 
-**Before every task, internalize these 5 rules:**
+## 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.
+1. **Bootstrap first** — list the KB tree to understand structure before searching or writing.
+2. **Default to read-only.** Only write 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 → `.mindos/user-preferences.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.
+6. **Read before write.** Always read a file before overwriting it. Never write based on assumptions.
 
 ---
 
 ## 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.
+- **NEVER write to the KB root** unless explicitly told. Root is for governance files only. New content goes under the most fitting subdirectory.
+- **NEVER assume directory names.** Infer from the actual bootstrap tree — the KB may use Chinese names or flat layout.
+- **NEVER use full-file overwrite for a small edit.** Use `mindos file edit-section` or `mindos file insert-heading` for targeted changes. Full rewrites destroy git diffs.
+- **NEVER search with a single keyword.** Fire 2-4 parallel searches (synonyms, abbreviations, Chinese/English variants).
+- **NEVER modify `INSTRUCTION.md` or `README.md` without confirmation.** Governance docs — treat as high-sensitivity.
+- **NEVER create a file without checking siblings.** Read 1-2 files in the target directory to learn local style.
+- **NEVER leave orphan references.** After rename/move, check backlinks and update every referring file.
+- **NEVER skip routing confirmation for multi-file writes.** 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.
+- **Instruction** — A rules file (`INSTRUCTION.md`) all connected agents obey.
+- **Skill** — Teaches agents how to read, write, and organize the KB.
 
-**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.
+Notes can embody both Instruction and Skill — they're just Markdown files in the tree.
 
 ---
 
-## 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
+## Decision tree
 
 ```
 User request
   │
-  ├─ Only asks to look up / summarize / quote?
-  │   └─ YES → [Read-only path]: search + read + cite sources. No writes. Skip hooks.
+  ├─ Lookup / summarize / quote?
+  │   └─ [Read-only]: search → read → answer with citations. No writes.
   │
-  ├─ Asks to save / record / update / organize specific content?
-  │   ├─ Single file target? → [Single-file edit]
-  │   └─ Multiple files or unclear target? → [Multi-file routing]
+  ├─ Save / record / update / organize specific content?
+  │   ├─ Single file → [Single-file edit]
+  │   └─ Multiple files or unclear → [Multi-file routing] — plan first
   │
   ├─ Structural change (rename / move / delete / reorganize)?
-  │   └─ [Structural path]
+  │   └─ [Structural path] — check backlinks before and after
   │
   ├─ Procedural / repeatable task?
-  │   └─ [SOP path]
+  │   └─ [SOP path] — find and follow existing SOP, or create one
   │
   ├─ Retrospective / distill / handoff?
   │   └─ [Retrospective path]
   │
-  └─ Ambiguous or too broad?
-      └─ ASK for clarification. Propose 2-3 specific options based on KB state. Do NOT start editing.
+  └─ Ambiguous?
+      └─ ASK. Propose 2-3 specific options based on KB state.
 ```
 
-**For any write/SOP/structural path above → the write supplement is already loaded in context (see `## Write & Workflow Supplement` section below or in the next context block).**
-
----
-
-## 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 |
-
-Write, structural, and history tools → see Write & Workflow Supplement (loaded below or in next context block).
-
-### Fallbacks
-
-- `mindos_bootstrap` unavailable → manual reads of root `INSTRUCTION.md` + `README.md`.
-- 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
-
-| Pattern | When | Key steps |
-|---------|------|-----------|
-| **Read-only Q&A** | Lookup / summarize / quote | Tree reasoning → search → read → answer with citations → state gaps |
-
-For write, SOP, structural, and handoff patterns → see Write & Workflow Supplement (loaded below or in next context block).
-
 ---
 
 ## Judgment heuristics
 
-**Save intent — read vs. write boundary**
-- "帮我记下来" / "记录一下" / "保存这个" = write
-- "搜一下有没有关于 X 的笔记" / "总结上周的工作" = read-only
-- Ambiguous boundary ("整理一下这些内容") → ask first: display only, or write back to KB?
+**Save intent boundary:**
+- "帮我记下来" / "保存" = write
+- "搜一下" / "总结" = read-only
+- "整理一下" → ask: display only, or write back?
 
-**File location uncertainty**
-- 扫目录树 5 秒内定不下来 → don't invent a new directory; use the nearest semantically-fit existing one and inform the user
-- User says "just put it somewhere" → place in inbox or top-level general directory, propose classification after (triggers Structure classification hook)
+**File location uncertainty:**
+- Can't decide in 5 seconds → use nearest existing directory, inform user
+- "Just put it somewhere" → inbox, propose classification after
 
-**Scope creep signals**
-- Single input routes to >5 files → pause, confirm scope; users rarely intend bulk rewrites
-- "Update all of these" + content spans multiple topics → split into batches, confirm each, don't execute all at once
+**Scope creep:**
+- Input routes to >5 files → pause, confirm scope
+- "Update all of these" spanning multiple topics → split into batches
 
-**Citation discipline**
-- KB-cited facts must include the file path so the user can verify
+**Citation:** KB-cited facts must include the file path.
 
 ---
 
 ## Post-task hooks
 
-After **write tasks** (not simple single-file edits or read-only), scan this table. If a condition matches, make a one-line proposal. At most 1 proposal; pick highest priority. Check `user-skill-rules.md` suppression section first. Skip all if user asked for quiet mode.
+After write tasks (not simple reads), scan this table. At most 1 proposal; highest priority wins. Check `.mindos/user-preferences.md` suppression first.
 
 | Hook | Priority | Condition |
 |------|----------|-----------|
-| Experience capture | high | Debugging, troubleshooting, or took multiple rounds |
-| Consistency sync | high | Edited file A which has backlinks (check `get_backlinks`) |
-| SOP drift | medium | Followed an SOP but execution diverged from its steps |
-| Linked update | medium | Changed a CSV/TODO status and related docs exist |
-| Structure classification | medium | Created a file in a temporary location or inbox |
-| Pattern extraction | low | 3+ structurally similar operations this session |
-| Conversation retrospective | low | Session >10 turns with decisions or trade-offs |
+| Experience capture | high | Debugging, troubleshooting, or multi-round work |
+| Consistency sync | high | Edited file with backlinks |
+| SOP drift | medium | Followed SOP but diverged |
+| Linked update | medium | Changed CSV/TODO status with related docs |
+| Structure classification | medium | Created file in inbox/temp location |
+| Pattern extraction | low | 3+ similar operations this session |
 
-If a hook triggers → read [references/post-task-hooks.md](./references/post-task-hooks.md) for the propose format and any user-defined hooks. If nothing matches, end quietly — do not read the file.
+If a hook triggers → read [references/post-task-hooks.md](./references/post-task-hooks.md).
 
 ## 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.
+When user expresses a standing preference → read [references/preference-capture.md](./references/preference-capture.md) and follow confirm-then-write flow.
 
 ## 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).
+When creating/rewriting an SOP → read [references/sop-template.md](./references/sop-template.md).
+
+---
+
+## Error handling (CLI)
+
+```bash
+"command not found: mindos"  → npm install -g @geminilight/mindos
+"Mind root not configured"   → mindos onboard
+"401 Unauthorized"           → Check AUTH_TOKEN: mindos token (on server)
+"ECONNREFUSED"               → Start server: mindos start
+```

package/app/data/skills/mindos/references/write-supplement.md

@@ -0,0 +1,119 @@
+# MindOS Write & Workflow Supplement
+
+<!-- Always injected alongside SKILL.md by route.ts for every request. -->
+<!-- For read-only lookups, Q&A, and summarization this context is also available. -->
+
+---
+
+## NEVER do (write-path specific)
+
+- **NEVER use `mindos_write_file` as your first move.** Writing without reading first means replacing content you haven't seen. Even when you "know" the file's content, read it — your assumption may be stale.
+- **NEVER create a Mind Space with `mindos_create_file`.** That only creates a plain directory — no README, no INSTRUCTION scaffolding. A Space missing its governance files is broken from birth. Use `mindos_create_space`.
+- **NEVER write immediately after bootstrap.** Bootstrap gives you the top-level structure; it does NOT tell you whether a local `INSTRUCTION.md` near your target overrides the root rules. Read local governance before touching anything.
+- **NEVER execute multi-file writes without first showing the routing table.** Even when destinations seem obvious — the user's mental model diverges from yours more often than intuition suggests. Show the table, wait for confirmation.
+- **NEVER use `mindos_append_to_file` on structured files.** Blind appending ignores section order. If the file has headings, required fields, or schema constraints, use `insert_after_heading` or `update_section` to land content in the right place.
+
+---
+
+## Write tool selection
+
+| Intent | Best tool | Avoid |
+|--------|-----------|-------|
+| 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 |
+
+**Fallback:** Line/section tools unavailable → read + constrained `mindos_write_file` (simulate minimal edit).
+
+---
+
+## Startup protocol
+
+Run this before executing any write path:
+
+1. **Bootstrap** — `mindos_bootstrap` (preferred) or manually read root `INSTRUCTION.md` + `README.md`.
+2. **Discover structure**
+   - Only need top-level zones? → `mindos_list_spaces` (lighter; includes README blurbs)
+   - Need a specific file path? → confirm zone with `mindos_list_spaces`, then `mindos_list_files` inside that zone
+   - Know keywords? → fire 2-4 parallel `mindos_search_notes` covering CN/EN variants and abbreviations
+   - **Never assume top-level directory names** — the user's KB may use Chinese, pinyin, or unconventional hierarchy
+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.
+
+---
+
+## Execution patterns
+
+| Pattern | When | Key steps |
+|---------|------|-----------|
+| **Single-file edit** | One clear target file | Startup → read target + local conventions → minimal edit → verify → summarize |
+| **Multi-file routing** | Unstructured input, multiple destinations | Parse into semantic units → routing table → confirm → edit → summarize |
+| **Conversation retrospective** | Distill / capture session | Confirm scope → extract decisions/pitfalls/actions → route → trace changes |
+| **SOP execution** | Repeatable procedure | Read SOP fully → execute stepwise → update stale sections → propose SOP update if diverged |
+| **Structural change** | Rename / move / delete | `get_backlinks` → impact report → confirm → execute → update refs → sync READMEs |
+| **CSV append** | Add row to a table | Read header → validate fields → `mindos_append_csv` |
+| **Cross-agent handoff** | Continue another agent's work | Read task state + decisions → continue without re-discovery → write back progress |
+| **Periodic review** | Summarize recent changes | `get_recent`/`get_history` → read changed files → structured summary |
+| **Handoff doc** | Create a briefing | Read sources → synthesize (background, decisions, status, open items) → place in project dir |
+
+---
+
+## Detailed execution steps
+
+### Single-file edit
+Search → read target + read 1-2 sibling files for local conventions → apply minimal edit (prefer `update_section` / `update_lines` / `insert_after_heading` over full rewrite) → verify heading/style match → summarize what changed.
+
+### Multi-file routing
+Parse unstructured input into discrete semantic units → for each unit: search 2-4 keyword variants to find best-fit file → **present routing table** (content snippet → target file → insertion point) → wait for user confirmation → execute edits one file at a time → summarize all changes with file paths.
+
+### Conversation retrospective
+Confirm scope (which session? which topics?) → extract: decisions made, rationale, pitfalls encountered, next actions → for each artifact, find the best existing file via search → route each to the right place → append a one-line change trace per file touched.
+
+### SOP execution
+Read the full SOP before starting (never skim) → execute step by step, checking off as you go → if a step is stale or diverges from current KB state, note it → after completion, propose a targeted SOP update for any diverged steps.
+**Creating a new SOP** → first read [references/sop-template.md](./references/sop-template.md) for required structure.
+
+### Structural changes
+`get_backlinks` on the path being changed → present impact report (N files will need updates) → wait for confirmation → execute rename/move/delete → update every backlink → sync affected `README.md` files.
+
+### Handoff / cross-agent continuation
+Read the handoff document or last agent's progress notes → identify: current state, decisions already made, open items → continue from that state without re-running discovery already done → write progress back to the same handoff doc when done.
+
+---
+
+## Post-task hooks
+
+After **write tasks** (not simple single-file edits or read-only), scan this table. If a condition matches, make a one-line proposal. At most 1 proposal; pick highest priority. Check `.mindos/user-preferences.md` suppression section first. Skip all if user asked for quiet mode.
+
+| Hook | Priority | Condition |
+|------|----------|-----------|
+| Experience capture | high | Debugging, troubleshooting, or took multiple rounds |
+| Consistency sync | high | Edited file A which has backlinks (check `get_backlinks`) |
+| SOP drift | medium | Followed an SOP but execution diverged from its steps |
+| Linked update | medium | Changed a CSV/TODO status and related docs exist |
+| Structure classification | medium | Created a file in a temporary location or inbox |
+| Pattern extraction | low | 3+ structurally similar operations this session |
+| Conversation retrospective | low | Session >10 turns with decisions or trade-offs |
+
+If a hook triggers → read [references/post-task-hooks.md](./references/post-task-hooks.md) for the propose format and any user-defined hooks. If nothing matches, end quietly — do not read the file.
+
+## 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 `.mindos/user-preferences.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).