@geminilight/mindos 0.5.58 → 0.5.59

package/README.md

@@ -55,7 +55,7 @@ MindOS is where you think, and where your AI agents act — a local-first knowle
 
 **1. Global Sync — Breaking Memory Silos**
 
-Switch tools or start a new chat and you're re-transporting context, scattering knowledge. **With a built-in MCP server (20+ tools), MindOS connects all Agents to your core knowledge base with zero config. Record profile and project memory once to empower all AI tools.**
+Switch tools or start a new chat and you're re-transporting context, scattering knowledge. **With a built-in MCP server, MindOS connects all Agents to your core knowledge base with zero config. Record profile and project memory once to empower all AI tools.**
 
 **2. Transparent & Controllable — No Black Boxes**
 

package/README_zh.md

@@ -55,7 +55,7 @@ MindOS 是你思考的地方，也是 AI Agent 行动的起点——一个你和
 
 **1. 全局同步 — 打破记忆割裂**
 
-切换工具带来上下文割裂，个人深度背景散落各处，导致知识无法复用。**MindOS 内置 MCP Server (支持 20+ 工具)，所有 Agent 零配置直连核心知识库。项目记忆与 SOP 仅需一处记录，全局赋能所有 AI 工具。**
+切换工具带来上下文割裂，个人深度背景散落各处，导致知识无法复用。**MindOS 内置 MCP Server，所有 Agent 零配置直连核心知识库。项目记忆与 SOP 仅需一处记录，全局赋能所有 AI 工具。**
 
 **2. 透明可控 — 消除记忆黑箱**
 

package/app/app/api/ask/route.ts

@@ -182,7 +182,10 @@ export async function POST(req: NextRequest) {
   // 2. user-skill-rules.md — user's personalized rules from KB root (if exists)
   const isZh = serverSettings.disabledSkills?.includes('mindos') ?? false;
   const skillDirName = isZh ? 'mindos-zh' : 'mindos';
-  const skillPath = path.resolve(process.cwd(), `data/skills/${skillDirName}/SKILL.md`);
+  const appDir = process.env.MINDOS_PROJECT_ROOT
+    ? path.join(process.env.MINDOS_PROJECT_ROOT, 'app')
+    : process.cwd();
+  const skillPath = path.join(appDir, `data/skills/${skillDirName}/SKILL.md`);
   const skill = readAbsoluteFile(skillPath);
 
   const mindRoot = getMindRoot();

package/app/app/api/extract-pdf/route.ts

@@ -27,8 +27,10 @@ function extractPdf(buf: Buffer): { text: string; pages: number } {
   // Write PDF to a temp file so the child script can read it.
   const tmpDir = os.tmpdir();
   const tmpPdf = path.join(tmpDir, `pdf-extract-${Date.now()}.pdf`);
-  // Dynamic path construction to prevent Turbopack static analysis
-  const scriptPath = [process.cwd(), 'scripts', 'extract-pdf.cjs'].join(path.sep);
+  const appDir = process.env.MINDOS_PROJECT_ROOT
+    ? path.join(process.env.MINDOS_PROJECT_ROOT, 'app')
+    : process.cwd();
+  const scriptPath = path.join(appDir, 'scripts', 'extract-pdf.cjs');
 
   fs.writeFileSync(tmpPdf, buf);
   try {

package/app/app/api/file/route.ts

@@ -18,6 +18,7 @@ import {
   appendCsvRow,
   getMindRoot,
   invalidateCache,
+  listMindSpaces,
 } from '@/lib/fs';
 import { createSpaceFilesystem } from '@/lib/core/create-space';
 
@@ -25,10 +26,19 @@ function err(msg: string, status = 400) {
   return NextResponse.json({ error: msg }, { status });
 }
 
-// GET /api/file?path=foo.md&op=read_file|read_lines
+// GET /api/file?path=foo.md&op=read_file|read_lines | GET ?op=list_spaces (no path)
 export async function GET(req: NextRequest) {
   const filePath = req.nextUrl.searchParams.get('path');
   const op = req.nextUrl.searchParams.get('op') ?? 'read_file';
+
+  if (op === 'list_spaces') {
+    try {
+      return NextResponse.json({ spaces: listMindSpaces() });
+    } catch (e) {
+      return err((e as Error).message, 500);
+    }
+  }
+
   if (!filePath) return err('missing path');
 
   try {

package/app/app/api/health/route.ts

@@ -11,8 +11,10 @@ function readVersion(): string {
   // 1. Env var set by CLI (most reliable)
   if (process.env.npm_package_version) return process.env.npm_package_version;
 
-  // 2. Try known relative paths from Next.js app directory
+  // 2. Try known relative paths — MINDOS_PROJECT_ROOT is reliable in standalone mode
+  const projRoot = process.env.MINDOS_PROJECT_ROOT;
   const candidates = [
+    ...(projRoot ? [join(projRoot, 'package.json')] : []),
     join(process.cwd(), '..', 'package.json'),    // dev: app/ → root
     join(process.cwd(), 'package.json'),           // if cwd is root
     join(dirname(process.cwd()), 'package.json'),  // standalone edge case

package/app/app/api/mcp/install-skill/route.ts

@@ -36,9 +36,11 @@ const AGENT_NAME_MAP: Record<string, string> = {
 
 /** Fallback: find local skills directory for offline installs */
 function findLocalSkillsDir(): string | null {
+  const projRoot = process.env.MINDOS_PROJECT_ROOT || path.resolve(process.cwd(), '..');
   const candidates = [
-    path.resolve(process.cwd(), 'data/skills'),   // app/data/skills/
-    path.resolve(process.cwd(), '..', 'skills'),   // project-root/skills/
+    path.resolve(process.cwd(), 'data/skills'),       // app/data/skills/
+    path.join(projRoot, 'skills'),                     // project-root/skills/
+    path.join(projRoot, 'app', 'data', 'skills'),      // standalone fallback
   ];
   for (const dir of candidates) {
     if (fs.existsSync(dir)) return dir;

package/app/app/api/mcp/restart/route.ts

@@ -57,7 +57,7 @@ export async function POST() {
     await new Promise(r => setTimeout(r, 1000));
 
     // Step 3: Spawn new MCP server
-    const root = resolve(process.cwd(), '..');
+    const root = process.env.MINDOS_PROJECT_ROOT || resolve(process.cwd(), '..');
     const mcpDir = resolve(root, 'mcp');
 
     if (!existsSync(resolve(mcpDir, 'node_modules'))) {

package/app/app/api/restart/route.ts

@@ -5,7 +5,7 @@ import { resolve } from 'node:path';
 
 export async function POST() {
   try {
-    const cliPath = process.env.MINDOS_CLI_PATH || resolve(process.cwd(), '..', 'bin', 'cli.js');
+    const cliPath = process.env.MINDOS_CLI_PATH || resolve(process.env.MINDOS_PROJECT_ROOT || process.cwd(), '..', 'bin', 'cli.js');
     const nodeBin = process.env.MINDOS_NODE_BIN || process.execPath;
     // Use 'restart' (stop all → wait for ports free → start) instead of bare
     // 'start' which would fail assertPortFree because the current process and

package/app/app/api/skills/route.ts

@@ -5,7 +5,7 @@ import path from 'path';
 import os from 'os';
 import { readSettings, writeSettings } from '@/lib/settings';
 
-const PROJECT_ROOT = path.resolve(process.cwd(), '..');
+const PROJECT_ROOT = process.env.MINDOS_PROJECT_ROOT || path.resolve(process.cwd(), '..');
 
 function getMindRoot(): string {
   const s = readSettings();

package/app/app/api/sync/route.ts

@@ -37,9 +37,9 @@ function isGitRepo(dir: string) {
   return existsSync(join(dir, '.git'));
 }
 
-/** Resolve path to bin/cli.js — prefer env var set by CLI launcher, fall back to cwd. */
+/** Resolve path to bin/cli.js — prefer env var set by CLI launcher, fall back to project root. */
 function getCliPath() {
-  return process.env.MINDOS_CLI_PATH || resolve(process.cwd(), '..', 'bin', 'cli' + '.js');
+  return process.env.MINDOS_CLI_PATH || resolve(process.env.MINDOS_PROJECT_ROOT || process.cwd(), '..', 'bin', 'cli' + '.js');
 }
 
 /** Run CLI command via execFile — avoids shell injection by passing args as array */

package/app/app/api/update/route.ts

@@ -12,7 +12,7 @@ import { resolve } from 'node:path';
  */
 export async function POST() {
   try {
-    const cliPath = process.env.MINDOS_CLI_PATH || resolve(process.cwd(), '..', 'bin', 'cli.js');
+    const cliPath = process.env.MINDOS_CLI_PATH || resolve(process.env.MINDOS_PROJECT_ROOT || process.cwd(), '..', 'bin', 'cli.js');
     const nodeBin = process.env.MINDOS_NODE_BIN || process.execPath;
 
     // Strip MINDOS_* env vars so the child reads fresh config

package/app/app/api/update-check/route.ts

@@ -7,9 +7,17 @@ import { resolve } from 'path';
 // Read version from package.json (not process.env.npm_package_version — unavailable in daemon mode)
 let current = '0.0.0';
 try {
-  const pkgPath = resolve(process.cwd(), '..', 'package.json');
-  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-  current = pkg.version;
+  const projRoot = process.env.MINDOS_PROJECT_ROOT;
+  const candidates = [
+    ...(projRoot ? [resolve(projRoot, 'package.json')] : []),
+    resolve(process.cwd(), '..', 'package.json'),
+  ];
+  for (const p of candidates) {
+    try {
+      const pkg = JSON.parse(readFileSync(p, 'utf-8'));
+      if (pkg.version) { current = pkg.version; break; }
+    } catch { /* try next */ }
+  }
 } catch {}
 
 // npm registry sources: prefer China mirror, fallback to official

package/app/app/globals.css

@@ -422,3 +422,7 @@ a:focus-visible,
 .wysiwyg-wrapper:focus-within {
   outline: none;
 }
+
+/* macOS Electron: traffic-light safe zone. Actual CSS is injected by Electron
+   main process via webContents.insertCSS(); this is a no-op fallback. */
+.electron-mac-titlebar-pad { display: none; }

package/app/app/layout.tsx

@@ -88,6 +88,12 @@ export default async function RootLayout({
             __html: `(function(){if(typeof Node!=='undefined'){var o=Node.prototype.removeChild;Node.prototype.removeChild=function(c){if(c.parentNode!==this){try{return o.call(c.parentNode,c)}catch(e){return c}}return o.call(this,c)};var i=Node.prototype.insertBefore;Node.prototype.insertBefore=function(n,r){if(r&&r.parentNode!==this){try{return i.call(r.parentNode,n,r)}catch(e){return i.call(this,n,null)}}return i.call(this,n,r)}}})();`,
           }}
         />
+        {/* Electron macOS: set data-electron-mac before first paint so sidebar clears traffic lights */}
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `(function(){try{if(/electron/i.test(navigator.userAgent)&&/macintosh/i.test(navigator.userAgent)){document.documentElement.setAttribute('data-electron-mac','')}}catch(e){}})();`,
+          }}
+        />
         {/* Apply user appearance settings before first paint, preventing flash */}
         <script
           dangerouslySetInnerHTML={{

package/app/app/login/page.tsx

@@ -118,9 +118,20 @@ function LoginForm() {
   );
 }
 
+function LoginFallback() {
+  return (
+    <div className="min-h-screen bg-background flex items-center justify-center px-4">
+      <div className="flex flex-col items-center gap-3 text-muted-foreground">
+        <Loader2 className="h-8 w-8 animate-spin text-[var(--amber)]" aria-hidden />
+        <p className="text-sm">Loading…</p>
+      </div>
+    </div>
+  );
+}
+
 export default function LoginPage() {
   return (
-    <Suspense>
+    <Suspense fallback={<LoginFallback />}>
       <LoginForm />
     </Suspense>
   );

package/app/app/register-sw.tsx

@@ -4,6 +4,10 @@ import { useEffect } from 'react';
 
 export default function RegisterSW() {
   useEffect(() => {
+    // Electron embedded Chromium: SW can leave the UI blank or stall hydration; skip.
+    if (typeof navigator !== 'undefined' && /electron/i.test(navigator.userAgent)) {
+      return;
+    }
     if ('serviceWorker' in navigator) {
       navigator.serviceWorker.register('/sw.js').catch((err) => {
         console.warn('[SW] Registration failed:', err);

package/app/components/Sidebar.tsx

@@ -90,6 +90,7 @@ export default function Sidebar({ fileTree, collapsed = false, onCollapse, onExp
 
   const sidebarContent = (
     <div className="flex flex-col h-full">
+      <div className="shrink-0 electron-mac-titlebar-pad" />
       <div className="flex items-center justify-between px-4 py-4 border-b border-border shrink-0">
         <Link href="/" className="flex items-center gap-2 hover:opacity-80 transition-opacity">
           <Logo id="desktop" />

package/app/components/SidebarLayout.tsx

@@ -376,7 +376,7 @@ export default function SidebarLayout({ fileTree, children }: SidebarLayoutProps
           #main-content {
             padding-left: ${lp.panelOpen && lp.panelMaximized ? '100vw' : `${lp.panelOpen ? lp.railWidth + lp.effectivePanelWidth : lp.railWidth}px`} !important;
             padding-right: calc(var(--right-panel-width) + var(--right-agent-detail-width)) !important;
-            padding-top: 0 !important;
+            padding-top: 0;
           }
         }
       `}</style>

package/app/instrumentation.ts

@@ -11,7 +11,8 @@ export async function register() {
         // createRequire() calls. The only way to load a runtime-computed path
         // is to hide the require call inside a Function constructor, which is
         // opaque to bundler static analysis.
-        const syncModule = resolve(process.cwd(), '..', 'bin', 'lib', 'sync.js');
+        const projRoot = process.env.MINDOS_PROJECT_ROOT || resolve(process.cwd(), '..');
+        const syncModule = resolve(projRoot, 'bin', 'lib', 'sync.js');
         // eslint-disable-next-line @typescript-eslint/no-implied-eval
         const dynamicRequire = new Function('id', 'return require(id)') as (id: string) => any;
         const { startSyncDaemon } = dynamicRequire(syncModule);

package/app/lib/core/list-spaces.ts

@@ -0,0 +1,58 @@
+import path from 'path';
+import type { FileNode } from './types';
+import { readFile } from './fs-ops';
+
+/** One top-level Mind Space (aligned with home page Spaces grid). */
+export interface MindSpaceSummary {
+  /** Directory entry name as on disk (may include leading emoji). */
+  name: string;
+  /** Relative path to the space directory, forward slashes only. */
+  path: string;
+  /** Count of .md/.csv files under this space (recursive). */
+  fileCount: number;
+  /** First non-empty body line from README.md after the title, or empty. */
+  description: string;
+}
+
+function countFiles(node: FileNode): number {
+  if (node.type === 'file') return 1;
+  return (node.children ?? []).reduce((sum, c) => sum + countFiles(c), 0);
+}
+
+function toPosixRel(p: string): string {
+  return p.split(path.sep).join('/');
+}
+
+function extractDescription(mindRoot: string, dirRelPosix: string): string {
+  const readmeRel = `${dirRelPosix}/README.md`;
+  try {
+    const content = readFile(mindRoot, readmeRel);
+    const lines = content.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      return trimmed;
+    }
+  } catch {
+    /* no README */
+  }
+  return '';
+}
+
+/**
+ * Build summaries from the **app file tree** (same nodes as home Spaces).
+ * Caller passes `getFileTree()` so ignore rules match the UI cache.
+ */
+export function summarizeTopLevelSpaces(mindRoot: string, tree: FileNode[]): MindSpaceSummary[] {
+  return tree
+    .filter((n) => n.type === 'directory' && !n.name.startsWith('.'))
+    .map((n) => {
+      const posix = toPosixRel(n.path);
+      return {
+        name: n.name,
+        path: posix,
+        fileCount: countFiles(n),
+        description: extractDescription(mindRoot, posix),
+      };
+    });
+}

package/app/lib/project-root.ts

@@ -0,0 +1,13 @@
+import path from 'path';
+
+/**
+ * Resolve the MindOS project root directory.
+ *
+ * In standalone mode (`node .next/standalone/server.js`), `process.cwd()` points to
+ * `.next/standalone/` — NOT the app or project root. `MINDOS_PROJECT_ROOT` is injected
+ * by Desktop ProcessManager; for CLI launches it defaults to `cwd/..` which is correct
+ * when cwd is `app/`.
+ */
+export function getProjectRoot(): string {
+  return process.env.MINDOS_PROJECT_ROOT || path.resolve(process.cwd(), '..');
+}

package/app/lib/template.ts

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import path from 'path';
+import { getProjectRoot } from './project-root';
 
 /**
  * Recursively copy `src` to `dest`, skipping files that already exist in dest.
@@ -29,12 +30,18 @@ export function applyTemplate(template: string, destDir: string): void {
     throw new Error(`Invalid template: ${template}`);
   }
 
-  // templates/ is at the repo root (sibling of app/)
-  const repoRoot = path.resolve(process.cwd(), '..');
-  const templateDir = path.join(repoRoot, 'templates', template);
-
-  if (!fs.existsSync(templateDir)) {
-    throw new Error(`Template "${template}" not found at ${templateDir}`);
+  // templates/ lives at the repo/project root (sibling of app/).
+  // In standalone mode process.cwd() is .next/standalone/ — unreliable for relative paths.
+  // MINDOS_PROJECT_ROOT is set by Desktop ProcessManager and CLI startup.
+  const projectRoot = getProjectRoot();
+  const candidates = [
+    path.join(projectRoot, 'templates', template),
+    path.resolve(process.cwd(), '..', 'templates', template),
+    path.resolve(process.cwd(), 'templates', template),
+  ];
+  const templateDir = candidates.find((d) => fs.existsSync(d));
+  if (!templateDir) {
+    throw new Error(`Template "${template}" not found at ${candidates.join(', ')}`);
   }
 
   if (!fs.existsSync(destDir)) {

package/app/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/bin/lib/mcp-spawn.js

@@ -1,10 +1,46 @@
 import { execSync, spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { arch, platform } from 'node:os';
 import { ROOT, CONFIG_PATH } from './constants.js';
 import { bold, red, yellow } from './colors.js';
 import { npmInstall } from './utils.js';
 
+/**
+ * If mcp/node_modules was installed on a different platform (e.g. Linux CI → macOS user),
+ * native packages like esbuild will crash. Detect via stamp or @esbuild heuristics, then reinstall.
+ */
+function ensureMcpNativeDeps() {
+  const mcpDir = resolve(ROOT, 'mcp');
+  const nm = resolve(mcpDir, 'node_modules');
+  if (!existsSync(nm)) return;
+
+  const host = `${platform()}-${arch()}`;
+  const stamp = resolve(mcpDir, '.mindos-npm-ci-platform');
+  let needsReinstall = false;
+
+  if (existsSync(stamp)) {
+    try {
+      needsReinstall = readFileSync(stamp, 'utf-8').trim() !== host;
+    } catch { /* fall through */ }
+  } else {
+    const esbuildDir = resolve(nm, '@esbuild');
+    if (existsSync(esbuildDir)) {
+      try {
+        const names = readdirSync(esbuildDir);
+        if (names.length > 0 && !names.includes(host)) needsReinstall = true;
+      } catch { /* ignore */ }
+    }
+  }
+
+  if (!needsReinstall) return;
+
+  console.log(yellow('MCP dependencies were built for another platform — reinstalling...'));
+  rmSync(nm, { recursive: true, force: true });
+  npmInstall(mcpDir, '--no-workspaces');
+  try { writeFileSync(stamp, host, 'utf-8'); } catch { /* non-fatal */ }
+}
+
 export function spawnMcp(verbose = false) {
   const mcpPort = process.env.MINDOS_MCP_PORT || '8781';
   const webPort = process.env.MINDOS_WEB_PORT || '3456';
@@ -14,6 +50,7 @@ export function spawnMcp(verbose = false) {
     console.log(yellow('Installing MCP dependencies (first run)...\n'));
     npmInstall(resolve(ROOT, 'mcp'), '--no-workspaces');
   }
+  ensureMcpNativeDeps();
 
   // Read AUTH_TOKEN directly from config to avoid stale system env overriding
   // the user's configured token. Config is the source of truth for auth.

package/mcp/README.md

@@ -1,6 +1,6 @@
 # MindOS MCP Server
 
-Pure HTTP client wrapper that maps 22 MCP tools to the App REST API via `fetch`. Zero business logic — all operations are delegated to the App.
+Pure HTTP client wrapper that maps MCP tools to the App REST API via `fetch`. Zero business logic — all operations are delegated to the App.
 
 ## Architecture
 
@@ -41,11 +41,12 @@ MCP_TRANSPORT=stdio mindos mcp   # stdio mode
 | `MCP_PORT` | `8781` | HTTP listen port (configurable via `mindos onboard`) |
 | `MCP_ENDPOINT` | `/mcp` | HTTP endpoint path |
 
-## MCP Tools (22)
+## MCP Tools
 
 | Tool | App API | Description |
 |------|---------|-------------|
 | `mindos_list_files` | `GET /api/files` | List all files in the knowledge base |
+| `mindos_list_spaces` | `GET /api/file?op=list_spaces` | List top-level Mind Spaces (name, path, counts, README blurb) |
 | `mindos_read_file` | `GET /api/file?path=...` | Read file content (with offset/limit pagination) |
 | `mindos_write_file` | `POST /api/file` op=save_file | Overwrite file content |
 | `mindos_create_file` | `POST /api/file` op=create_file | Create a new .md or .csv file |

package/mcp/src/index.ts

@@ -114,6 +114,36 @@ server.registerTool("mindos_list_files", {
   } catch (e) { logOp("mindos_list_files", { response_format }, "error", String(e)); return error(String(e)); }
 });
 
+// ── mindos_list_spaces ──────────────────────────────────────────────────────
+
+server.registerTool("mindos_list_spaces", {
+  title: "List Mind Spaces",
+  description:
+    "List top-level Mind Spaces (same as home Spaces grid): name, path, file count, and README blurb. Only spaces that appear in the file tree (at least one .md/.csv under the folder) are included.",
+  inputSchema: z.object({
+    response_format: z.enum(["markdown", "json"]).default("json"),
+  }),
+  annotations: { readOnlyHint: true },
+}, async ({ response_format }) => {
+  try {
+    const json = await get("/api/file", { op: "list_spaces" });
+    const spaces = json.spaces as Array<{ name: string; path: string; fileCount: number; description: string }>;
+    if (response_format === "json") {
+      logOp("mindos_list_spaces", { response_format }, "ok", `${spaces?.length ?? 0} spaces`);
+      return ok(JSON.stringify({ spaces: spaces ?? [] }, null, 2));
+    }
+    const lines = (spaces ?? []).map(
+      (s) => `- **${s.name}** (\`${s.path}/\`) — ${s.fileCount} file(s)${s.description ? ` — ${s.description}` : ""}`,
+    );
+    const text = lines.length ? lines.join("\n") : "(no top-level spaces in tree)";
+    logOp("mindos_list_spaces", { response_format }, "ok", `${spaces?.length ?? 0} spaces`);
+    return ok(text);
+  } catch (e) {
+    logOp("mindos_list_spaces", { response_format }, "error", String(e));
+    return error(String(e));
+  }
+});
+
 // ── mindos_read_file ────────────────────────────────────────────────────────
 
 server.registerTool("mindos_read_file", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminilight/mindos",
-  "version": "0.5.58",
+  "version": "0.5.59",
   "description": "MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.",
   "keywords": [
     "mindos",

package/scripts/setup.js

@@ -598,7 +598,7 @@ function expandHomePath(p) {
   return p.startsWith('~/') ? resolve(homedir(), p.slice(2)) : p;
 }
 
-/** Parse JSONC (JSON with // and /* */ comments) — for VS Code-based editor configs */
+/** Parse JSONC: JSON plus line // comments and slash-star block comments (e.g. VS Code configs). */
 function parseJsonc(text) {
   let stripped = text.replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*$)/gm, (m, g) => g ? '' : m);
   stripped = stripped.replace(/\/\*[\s\S]*?\*\//g, '');

package/skills/mindos/SKILL.md

@@ -52,7 +52,7 @@ Run this sequence before substantive edits:
 - If unavailable, read root `INSTRUCTION.md` and root `README.md` directly.
 
 2. Discover current structure dynamically.
-- Use `mindos_list_files` and targeted `mindos_search_notes`.
+- Use `mindos_list_spaces` (top-level zones + README blurbs), `mindos_list_files`, and targeted `mindos_search_notes` as needed.
 - Do not assume fixed top-level directory names.
 
 3. Load local guidance around target paths.
@@ -96,6 +96,7 @@ Before any non-trivial write, confirm all checks:
 
 - `mindos_bootstrap`: Load startup context.
 - `mindos_list_files`: Inspect file tree.
+- `mindos_list_spaces`: Top-level Mind Spaces with README blurbs (lighter than full tree).
 - `mindos_search_notes`: Locate relevant files by keyword/scope/type/date. **When searching, always issue multiple parallel searches with different keywords upfront** — synonyms, abbreviations, English/Chinese variants, and broader/narrower terms. A single keyword is fragile; casting a wider net on the first try avoids wasted rounds.
 - `mindos_get_recent`: Inspect latest activity.
 - `mindos_get_backlinks`: Assess impact before rename/move/delete.

package/skills/mindos/references/README.md

@@ -0,0 +1,11 @@
+# MindOS skill — reference bundle
+
+Long-form supplements for `../SKILL.md`. Load a file only when the task needs it.
+
+| File | When to read |
+|------|----------------|
+| [sop-template.md](./sop-template.md) | Creating or rewriting a workflow SOP in the KB |
+| [post-task-hooks.md](./post-task-hooks.md) | After a write/multi-step task; proposing follow-ups |
+| [preference-capture.md](./preference-capture.md) | User expresses standing preferences to persist |
+
+Chinese mirror: `skills/mindos-zh/references/` (same filenames).

package/skills/mindos/references/post-task-hooks.md

@@ -0,0 +1,53 @@
+# Post-task hooks
+
+After completing a task, check the conditions below. If one matches, make a **one-line** proposal to the user. If none match, end quietly.
+
+## Discipline
+
+1. Do not propose after simple operations (rename, append one line, read-only queries).
+2. **At most 1 proposal per task** — pick the highest priority match.
+3. One sentence + specific target file/path. Only expand if the user says yes.
+4. Check `user-skill-rules.md` suppression section first — skip any suppressed hook.
+5. If the user asked for **no suggestions / quiet mode** for this turn or session, skip all hooks.
+
+## Default hooks
+
+### Experience capture (priority: high)
+- **Condition**: task involved debugging, troubleshooting, or took multiple rounds to resolve.
+- **Propose**: "Record this experience to {related experience file}?"
+- **Format**: problem → cause → solution → rule
+
+### Consistency sync (priority: high)
+- **Condition**: edited file A, and A is referenced by other files (check via `get_backlinks`).
+- **Propose**: "{B} references what you just changed — sync it?"
+
+### Linked update (priority: medium)
+- **Condition**: changed a CSV/TODO item status, and related docs exist.
+- **Propose**: "Sync the corresponding info in {related doc}?"
+
+### Structure classification (priority: medium)
+- **Condition**: created a new file in a temporary location or inbox.
+- **Propose**: "Move this to {recommended directory}?"
+
+### Pattern extraction (priority: low)
+- **Condition**: 3+ structurally similar operations in the current session.
+- **Propose**: "This operation repeated multiple times — create an SOP?"
+
+### SOP drift (priority: medium)
+- **Condition**: task was executed following an existing SOP, but actual steps diverged from documented steps.
+- **Propose**: "Execution diverged from {SOP file} — update the SOP?"
+- **Action**: update divergent steps, append new pitfalls, set `<!-- last-used: -->` to today.
+
+### Conversation retrospective (priority: low)
+- **Condition**: session >10 turns and involved decisions, trade-offs, or lessons.
+- **Propose**: "This conversation had some decisions worth capturing — do a retrospective?"
+
+## User-defined hooks
+
+Add your own below, same format:
+
+```markdown
+### Weekly report material (priority: medium)
+- Condition: updated a Project-related file.
+- Propose: "Record this change in the weekly report?"
+```