@geminilight/mindos 0.5.57 → 0.5.59

package/app/lib/core/create-space.ts

@@ -0,0 +1,36 @@
+import { MindOSError, ErrorCodes } from '@/lib/errors';
+import { createFile } from './fs-ops';
+
+/**
+ * Create a Mind Space on disk: `{fullPath}/README.md` plus scaffold from {@link createFile} / scaffoldIfNewSpace.
+ * Caller must invalidate app file-tree cache (e.g. `invalidateCache()` in `lib/fs.ts`).
+ */
+export function createSpaceFilesystem(
+  mindRoot: string,
+  name: string,
+  description: string,
+  parentPath = '',
+): { path: string } {
+  const trimmed = name.trim();
+  if (!trimmed) {
+    throw new MindOSError(ErrorCodes.INVALID_REQUEST, 'Space name is required', { name });
+  }
+  if (trimmed.includes('/') || trimmed.includes('\\')) {
+    throw new MindOSError(ErrorCodes.INVALID_PATH, 'Space name must not contain path separators', { name: trimmed });
+  }
+
+  const cleanParent = parentPath.replace(/\/+$/, '').trim();
+  if (cleanParent.includes('..') || cleanParent.startsWith('/') || cleanParent.includes('\\')) {
+    throw new MindOSError(ErrorCodes.INVALID_PATH, 'Invalid parent path', { parentPath });
+  }
+
+  const prefix = cleanParent ? `${cleanParent}/` : '';
+  const fullPath = `${prefix}${trimmed}`;
+
+  const cleanName = trimmed.replace(/^[\p{Emoji_Presentation}\p{Extended_Pictographic}\s]+/u, '') || trimmed;
+  const desc = description.trim() || '(Describe the purpose and usage of this space.)';
+  const readmeContent = `# ${cleanName}\n\n${desc}\n\n## 📁 Structure\n\n\`\`\`bash\n${fullPath}/\n├── INSTRUCTION.md\n├── README.md\n└── (your files here)\n\`\`\`\n\n## 💡 Usage\n\n(Add usage guidelines for this space.)\n`;
+
+  createFile(mindRoot, `${fullPath}/README.md`, readmeContent);
+  return { path: fullPath };
+}

package/app/lib/core/fs-ops.ts

@@ -2,7 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { resolveSafe, assertWithinRoot } from './security';
 import { MindOSError, ErrorCodes } from '@/lib/errors';
-import { scaffoldIfNewSpace } from './space-scaffold';
+import { scaffoldIfNewSpace, cleanDirName, INSTRUCTION_TEMPLATE, README_TEMPLATE } from './space-scaffold';
 
 /**
  * Reads the content of a file given a relative path from mindRoot.
@@ -55,6 +55,48 @@ export function deleteFile(mindRoot: string, filePath: string): void {
   fs.unlinkSync(resolved);
 }
 
+/**
+ * Recursively deletes a directory and all its contents.
+ * Throws if the path does not exist, is outside mindRoot, or is not a directory.
+ */
+export function deleteDirectory(mindRoot: string, dirPath: string): void {
+  const resolved = resolveSafe(mindRoot, dirPath);
+  if (!fs.existsSync(resolved)) {
+    throw new MindOSError(ErrorCodes.FILE_NOT_FOUND, `Directory not found: ${dirPath}`, { dirPath });
+  }
+  if (!fs.statSync(resolved).isDirectory()) {
+    throw new MindOSError(ErrorCodes.INVALID_PATH, `Not a directory: ${dirPath}`, { dirPath });
+  }
+  fs.rmSync(resolved, { recursive: true, force: true });
+}
+
+/**
+ * Converts an existing directory into a Space by creating INSTRUCTION.md
+ * (and README.md if missing). Idempotent — skips files that already exist.
+ */
+export function convertToSpace(mindRoot: string, dirPath: string): void {
+  const resolved = resolveSafe(mindRoot, dirPath);
+  if (!fs.existsSync(resolved)) {
+    throw new MindOSError(ErrorCodes.FILE_NOT_FOUND, `Directory not found: ${dirPath}`, { dirPath });
+  }
+  if (!fs.statSync(resolved).isDirectory()) {
+    throw new MindOSError(ErrorCodes.INVALID_PATH, `Not a directory: ${dirPath}`, { dirPath });
+  }
+
+  const dirName = path.basename(resolved);
+  const name = cleanDirName(dirName);
+
+  const instructionPath = path.join(resolved, 'INSTRUCTION.md');
+  if (!fs.existsSync(instructionPath)) {
+    fs.writeFileSync(instructionPath, INSTRUCTION_TEMPLATE(name), 'utf-8');
+  }
+
+  const readmePath = path.join(resolved, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    fs.writeFileSync(readmePath, README_TEMPLATE(name), 'utf-8');
+  }
+}
+
 /**
  * Renames a file within its current directory.
  * newName must be a plain filename (no path separators).
@@ -79,6 +121,41 @@ export function renameFile(mindRoot: string, oldPath: string, newName: string):
   return path.relative(root, newResolved);
 }
 
+/**
+ * Renames a directory (Mind Space) under mindRoot. `newName` must be a single segment (no `/` or `\\`).
+ * Does not rewrite links inside markdown files.
+ */
+export function renameSpaceDirectory(mindRoot: string, spacePath: string, newName: string): string {
+  const trimmedName = newName.trim();
+  if (!trimmedName || trimmedName.includes('/') || trimmedName.includes('\\')) {
+    throw new MindOSError(ErrorCodes.INVALID_PATH, 'Invalid space name: must not contain path separators', { newName });
+  }
+  const normalized = spacePath.replace(/\/+$/g, '').trim();
+  if (!normalized) {
+    throw new MindOSError(ErrorCodes.INVALID_PATH, 'Space path is required', { spacePath });
+  }
+
+  const root = path.resolve(mindRoot);
+  const oldResolved = resolveSafe(mindRoot, normalized);
+  if (!fs.existsSync(oldResolved)) {
+    throw new MindOSError(ErrorCodes.FILE_NOT_FOUND, `Space not found: ${normalized}`, { spacePath: normalized });
+  }
+  if (!fs.statSync(oldResolved).isDirectory()) {
+    throw new MindOSError(ErrorCodes.INVALID_PATH, `Not a directory: ${normalized}`, { spacePath: normalized });
+  }
+
+  const parentDir = path.dirname(oldResolved);
+  const newResolved = path.join(parentDir, trimmedName);
+  assertWithinRoot(newResolved, root);
+
+  if (fs.existsSync(newResolved)) {
+    throw new MindOSError(ErrorCodes.FILE_ALREADY_EXISTS, 'A space with that name already exists', { newName: trimmedName });
+  }
+
+  fs.renameSync(oldResolved, newResolved);
+  return path.relative(root, newResolved);
+}
+
 /**
  * Moves a file from one path to another within mindRoot.
  * Returns the new path and a list of files that referenced the old path.

package/app/lib/core/index.ts

@@ -22,7 +22,10 @@ export {
   writeFile,
   createFile,
   deleteFile,
+  deleteDirectory,
+  convertToSpace,
   renameFile,
+  renameSpaceDirectory,
   moveFile,
   getRecentlyModified,
 } from './fs-ops';
@@ -56,3 +59,8 @@ export { findBacklinks } from './backlinks';
 
 // Git
 export { isGitRepo, gitLog, gitShowFile } from './git';
+
+// Mind Space
+export { createSpaceFilesystem } from './create-space';
+export { summarizeTopLevelSpaces } from './list-spaces';
+export type { MindSpaceSummary } from './list-spaces';

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/core/types.ts

@@ -1,3 +1,8 @@
+export interface SpacePreview {
+  instructionLines: string[];
+  readmeLines: string[];
+}
+
 export interface FileNode {
   name: string;
   path: string;
@@ -5,6 +10,8 @@ export interface FileNode {
   children?: FileNode[];
   extension?: string;
   mtime?: number;
+  isSpace?: boolean;
+  spacePreview?: SpacePreview;
 }
 
 export interface SearchResult {

package/app/lib/fs.ts

@@ -7,7 +7,10 @@ import {
   writeFile as coreWriteFile,
   createFile as coreCreateFile,
   deleteFile as coreDeleteFile,
+  deleteDirectory as coreDeleteDirectory,
+  convertToSpace as coreConvertToSpace,
   renameFile as coreRenameFile,
+  renameSpaceDirectory as coreRenameSpaceDirectory,
   moveFile as coreMoveFile,
   readLines as coreReadLines,
   insertLines as coreInsertLines,
@@ -21,8 +24,10 @@ import {
   gitLog as coreGitLog,
   gitShowFile as coreGitShowFile,
   invalidateSearchIndex,
+  summarizeTopLevelSpaces,
 } from './core';
-import { FileNode } from './core/types';
+import type { MindSpaceSummary } from './core';
+import { FileNode, SpacePreview } from './core/types';
 import { SearchMatch } from './types';
 import { effectiveSopRoot } from './settings';
 
@@ -77,8 +82,31 @@ function ensureCache(): FileTreeCache {
 
 // ─── Internal builders ────────────────────────────────────────────────────────
 
-function buildFileTree(dirPath: string): FileNode[] {
-  const root = getMindRoot();
+const SPACE_PREVIEW_MAX_LINES = 3;
+
+function extractBodyLines(filePath: string, maxLines: number): string[] {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const bodyLines: string[] = [];
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      bodyLines.push(trimmed);
+      if (bodyLines.length >= maxLines) break;
+    }
+    return bodyLines;
+  } catch { return []; }
+}
+
+function buildSpacePreview(dirAbsPath: string) {
+  return {
+    instructionLines: extractBodyLines(path.join(dirAbsPath, 'INSTRUCTION.md'), SPACE_PREVIEW_MAX_LINES),
+    readmeLines: extractBodyLines(path.join(dirAbsPath, 'README.md'), SPACE_PREVIEW_MAX_LINES),
+  };
+}
+
+function buildFileTree(dirPath: string, rootOverride?: string): FileNode[] {
+  const root = rootOverride ?? getMindRoot();
   let entries: fs.Dirent[];
   try {
     entries = fs.readdirSync(dirPath, { withFileTypes: true });
@@ -94,9 +122,15 @@ function buildFileTree(dirPath: string): FileNode[] {
 
     if (entry.isDirectory()) {
       if (IGNORED_DIRS.has(entry.name)) continue;
-      const children = buildFileTree(fullPath);
+      const children = buildFileTree(fullPath, root);
       if (children.length > 0) {
-        nodes.push({ name: entry.name, path: relativePath, type: 'directory', children });
+        const hasInstruction = children.some(c => c.type === 'file' && c.name === 'INSTRUCTION.md');
+        const node: FileNode = { name: entry.name, path: relativePath, type: 'directory', children };
+        if (hasInstruction) {
+          node.isSpace = true;
+          node.spacePreview = buildSpacePreview(fullPath);
+        }
+        nodes.push(node);
       }
     } else if (entry.isFile()) {
       const ext = path.extname(entry.name).toLowerCase();
@@ -114,6 +148,11 @@ function buildFileTree(dirPath: string): FileNode[] {
   return nodes;
 }
 
+/** Exposed for testing only — builds a file tree from an arbitrary root path. */
+export function buildFileTreeForTest(rootPath: string): FileNode[] {
+  return buildFileTree(rootPath, rootPath);
+}
+
 function buildAllFiles(dirPath: string): string[] {
   const root = getMindRoot();
   let entries: fs.Dirent[];
@@ -146,6 +185,20 @@ export function getFileTree(): FileNode[] {
   return ensureCache().tree;
 }
 
+/** Top-level Mind Spaces (same cached tree as home Spaces grid). */
+export function listMindSpaces(): MindSpaceSummary[] {
+  return summarizeTopLevelSpaces(getMindRoot(), ensureCache().tree);
+}
+
+/** Returns space preview (INSTRUCTION + README excerpts) for a directory, or null if not a space. */
+export function getSpacePreview(dirPath: string): SpacePreview | null {
+  const root = getMindRoot();
+  const abs = path.join(root, dirPath);
+  const instructionPath = path.join(abs, 'INSTRUCTION.md');
+  if (!fs.existsSync(instructionPath)) return null;
+  return buildSpacePreview(abs);
+}
+
 /** Returns cached list of all file paths (relative to MIND_ROOT). */
 export function collectAllFiles(): string[] {
   return ensureCache().allFiles;
@@ -251,6 +304,25 @@ export function renameFile(oldPath: string, newName: string): string {
   return result;
 }
 
+/** Renames a Space directory under MIND_ROOT. newName must be a single path segment. */
+export function renameSpace(spacePath: string, newName: string): string {
+  const result = coreRenameSpaceDirectory(getMindRoot(), spacePath, newName);
+  invalidateCache();
+  return result;
+}
+
+/** Recursively deletes a directory under MIND_ROOT. */
+export function deleteDirectory(dirPath: string): void {
+  coreDeleteDirectory(getMindRoot(), dirPath);
+  invalidateCache();
+}
+
+/** Converts a regular folder into a Space by adding INSTRUCTION.md + README.md. */
+export function convertToSpace(dirPath: string): void {
+  coreConvertToSpace(getMindRoot(), dirPath);
+  invalidateCache();
+}
+
 // ─── Public API: Line-level operations (delegated to @mindos/core) ───────────
 
 export function readLines(filePath: string): string[] {
@@ -471,6 +543,7 @@ export function gitShowFile(filePath: string, commit: string): string {
 
 import type { BacklinkEntry } from './core/types';
 export type { BacklinkEntry } from './core/types';
+export type { MindSpaceSummary } from './core';
 
 export function findBacklinks(targetPath: string): BacklinkEntry[] {
   return coreFindBacklinks(getMindRoot(), targetPath);

package/app/lib/i18n-en.ts

@@ -278,6 +278,16 @@ export const en = {
     enterFileName: 'Enter a file name',
     failed: 'Failed',
     confirmDelete: (name: string) => `Delete "${name}"? This cannot be undone.`,
+    rules: 'Rules',
+    about: 'About',
+    viewAll: 'View all',
+    editRules: 'Edit Rules',
+    renameSpace: 'Rename Space',
+    deleteSpace: 'Delete Space',
+    confirmDeleteSpace: (name: string) => `Delete space "${name}" and all its files? This cannot be undone.`,
+    convertToSpace: 'Convert to Space',
+    deleteFolder: 'Delete Folder',
+    confirmDeleteFolder: (name: string) => `Delete folder "${name}" and all its contents? This cannot be undone.`,
   },
   dirView: {
     gridView: 'Grid view',

package/app/lib/i18n-zh.ts

@@ -302,6 +302,16 @@ export const zh = {
     enterFileName: '请输入文件名',
     failed: '操作失败',
     confirmDelete: (name: string) => `确定删除「${name}」？此操作不可撤销。`,
+    rules: '规则',
+    about: '说明',
+    viewAll: '查看全部',
+    editRules: '编辑规则',
+    renameSpace: '重命名空间',
+    deleteSpace: '删除空间',
+    confirmDeleteSpace: (name: string) => `删除空间「${name}」及其所有文件？此操作不可撤销。`,
+    convertToSpace: '转为空间',
+    deleteFolder: '删除文件夹',
+    confirmDeleteFolder: (name: string) => `删除文件夹「${name}」及其所有内容？此操作不可撤销。`,
   },
   dirView: {
     gridView: '网格视图',

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 20 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,14 +41,17 @@ 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 (20)
+## 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 |
+| `mindos_create_space` | `POST /api/file` op=create_space | Create a Mind Space (README + INSTRUCTION scaffold) |
+| `mindos_rename_space` | `POST /api/file` op=rename_space | Rename a Space directory (folder only) |
 | `mindos_delete_file` | `POST /api/file` op=delete_file | Delete a file |
 | `mindos_rename_file` | `POST /api/file` op=rename_file | Rename a file (same directory) |
 | `mindos_move_file` | `POST /api/file` op=move_file | Move a file to a new path |

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", {
@@ -173,6 +203,56 @@ server.registerTool("mindos_create_file", {
   } catch (e) { logOp("mindos_create_file", { path }, "error", String(e)); return error(String(e)); }
 });
 
+// ── mindos_create_space ─────────────────────────────────────────────────────
+
+server.registerTool("mindos_create_space", {
+  title: "Create Mind Space",
+  description:
+    "Create a new Mind Space (top-level or under parent_path): directory + README.md + INSTRUCTION.md scaffold. Use this instead of create_file when adding a new cognitive zone to the knowledge base.",
+  inputSchema: z.object({
+    name: z.string().min(1).describe("Space directory name (no path separators)"),
+    description: z.string().default("").describe("Short purpose text stored in README.md"),
+    parent_path: z.string().default("").describe("Optional parent directory under MIND_ROOT (empty = top-level Space)"),
+  }),
+}, async ({ name, description, parent_path }) => {
+  try {
+    const json = await post("/api/file", {
+      op: "create_space",
+      path: "_",
+      name,
+      description,
+      parent_path,
+    });
+    const p = json.path as string;
+    logOp("mindos_create_space", { name, parent_path }, "ok", p);
+    return ok(`Created Mind Space at "${p}"`);
+  } catch (e) {
+    logOp("mindos_create_space", { name, parent_path }, "error", String(e));
+    return error(String(e));
+  }
+});
+
+// ── mindos_rename_space ─────────────────────────────────────────────────────
+
+server.registerTool("mindos_rename_space", {
+  title: "Rename Mind Space",
+  description:
+    "Rename a Space directory (relative path to the folder, e.g. Notes or Work/Notes). Only the final folder name changes; new_name must be a single segment. Does not rewrite links inside files.",
+  inputSchema: z.object({
+    path: z.string().min(1).describe("Relative path to the space directory to rename"),
+    new_name: z.string().min(1).describe("New folder name only (no slashes)"),
+  }),
+}, async ({ path: spacePath, new_name }) => {
+  try {
+    const json = await post("/api/file", { op: "rename_space", path: spacePath, new_name });
+    logOp("mindos_rename_space", { path: spacePath, new_name }, "ok", String(json.newPath));
+    return ok(`Renamed space "${spacePath}" → "${json.newPath}"`);
+  } catch (e) {
+    logOp("mindos_rename_space", { path: spacePath, new_name }, "error", String(e));
+    return error(String(e));
+  }
+});
+
 // ── mindos_delete_file ──────────────────────────────────────────────────────
 
 server.registerTool("mindos_delete_file", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminilight/mindos",
-  "version": "0.5.57",
+  "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, '');