@geminilight/mindos 0.6.23 → 0.6.25

package/app/components/walkthrough/WalkthroughProvider.tsx

@@ -42,7 +42,7 @@ export default function WalkthroughProvider({ children }: WalkthroughProviderPro
           walkthroughDismissed: dismissed,
         },
       }),
-    }).catch(() => {});
+    }).catch((err) => { console.warn("[WalkthroughProvider] localStorage setItem failed:", err); });
   }, []);
 
   // Check for auto-start via ?welcome=1 or guideState
@@ -81,7 +81,7 @@ export default function WalkthroughProvider({ children }: WalkthroughProviderPro
           setCurrentStep(gs.walkthroughStep);
         }
       })
-      .catch(() => {});
+      .catch((err) => { console.warn("[WalkthroughProvider] guideState read failed:", err); });
   }, [totalSteps]);
 
   const start = useCallback(() => {

package/app/lib/a2a/agent-card.ts

@@ -0,0 +1,107 @@
+/**
+ * A2A Agent Card generator for MindOS.
+ * Builds the card dynamically from current settings and MCP tools.
+ */
+
+import type { AgentCard, AgentSkill } from './types';
+
+/** MindOS knowledge-base skills exposed via A2A */
+const KB_SKILLS: AgentSkill[] = [
+  {
+    id: 'kb-search',
+    name: 'Search Knowledge Base',
+    description: 'Full-text search across all notes, files, and spaces in the knowledge base.',
+    tags: ['search', 'knowledge', 'notes'],
+    examples: ['Search for notes about machine learning', 'Find files mentioning project deadlines'],
+    inputModes: ['text/plain'],
+    outputModes: ['text/plain', 'application/json'],
+  },
+  {
+    id: 'kb-read',
+    name: 'Read Note',
+    description: 'Read the full content of a specific file in the knowledge base.',
+    tags: ['read', 'file', 'content'],
+    examples: ['Read the file at Projects/roadmap.md'],
+    inputModes: ['text/plain'],
+    outputModes: ['text/plain'],
+  },
+  {
+    id: 'kb-write',
+    name: 'Write Note',
+    description: 'Create or update a note in the knowledge base. Supports .md and .csv files.',
+    tags: ['write', 'create', 'update'],
+    examples: ['Create a new meeting note at Work/meetings/2026-03-30.md'],
+    inputModes: ['text/plain'],
+    outputModes: ['text/plain'],
+  },
+  {
+    id: 'kb-list',
+    name: 'List Files',
+    description: 'List files and directory structure of the knowledge base.',
+    tags: ['list', 'tree', 'structure'],
+    examples: ['Show the file tree', 'List all spaces'],
+    inputModes: ['text/plain'],
+    outputModes: ['application/json'],
+  },
+  {
+    id: 'kb-organize',
+    name: 'Organize Files',
+    description: 'AI-powered file organization into appropriate spaces and directories.',
+    tags: ['organize', 'ai', 'structure'],
+    examples: ['Organize imported files into relevant spaces'],
+    inputModes: ['text/plain'],
+    outputModes: ['text/plain'],
+  },
+];
+
+/**
+ * Build the A2A Agent Card for this MindOS instance.
+ * @param baseUrl  The publicly reachable base URL (e.g. http://localhost:3456)
+ */
+export function buildAgentCard(baseUrl: string): AgentCard {
+  let version = process.env.npm_package_version || '0.0.0';
+
+  // Try reading version from package.json as fallback
+  if (version === '0.0.0') {
+    try {
+      const fs = require('fs');
+      const path = require('path');
+      const projRoot = process.env.MINDOS_PROJECT_ROOT || path.resolve(process.cwd(), '..');
+      const pkg = JSON.parse(fs.readFileSync(path.join(projRoot, 'package.json'), 'utf-8'));
+      if (pkg.version) version = pkg.version;
+    } catch { /* use default */ }
+  }
+
+  return {
+    name: 'MindOS',
+    description: 'Personal knowledge management system with AI-powered Spaces, Instructions, and Skills. Store, organize, and retrieve knowledge through natural language.',
+    version,
+    provider: {
+      organization: 'MindOS',
+      url: baseUrl,
+    },
+    supportedInterfaces: [
+      {
+        url: `${baseUrl}/api/a2a`,
+        protocolBinding: 'JSONRPC',
+        protocolVersion: '1.0',
+      },
+    ],
+    capabilities: {
+      streaming: false,  // Phase 1: no streaming
+      pushNotifications: false,
+      stateTransitionHistory: false,
+    },
+    defaultInputModes: ['text/plain'],
+    defaultOutputModes: ['text/plain', 'application/json'],
+    skills: KB_SKILLS,
+    securitySchemes: {
+      bearer: {
+        httpAuthSecurityScheme: {
+          scheme: 'Bearer',
+        },
+      },
+    },
+    securityRequirements: [{ bearer: [] }],
+  };
+}

package/app/lib/a2a/index.ts

@@ -0,0 +1,23 @@
+export { buildAgentCard } from './agent-card';
+export { handleSendMessage, handleGetTask, handleCancelTask } from './task-handler';
+export { A2A_ERRORS } from './types';
+export type {
+  AgentCard,
+  AgentInterface,
+  AgentCapabilities,
+  AgentSkill,
+  SecurityScheme,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcError,
+  TaskState,
+  MessageRole,
+  MessagePart,
+  A2AMessage,
+  TaskStatus,
+  TaskArtifact,
+  A2ATask,
+  SendMessageParams,
+  GetTaskParams,
+  CancelTaskParams,
+} from './types';

package/app/lib/a2a/task-handler.ts

@@ -0,0 +1,228 @@
+/**
+ * A2A Task handler for MindOS.
+ * Routes A2A SendMessage requests to internal MCP tools.
+ */
+
+import { randomUUID } from 'crypto';
+import type {
+  A2ATask,
+  A2AMessage,
+  SendMessageParams,
+  GetTaskParams,
+  CancelTaskParams,
+  TaskState,
+} from './types';
+
+/* ── In-memory Task Store (Phase 1) ───────────────────────────────────── */
+// NOTE: In-memory Map is lost on serverless cold starts / process restarts.
+// Acceptable for Phase 1. Phase 2 should use persistent storage if needed.
+
+const tasks = new Map<string, A2ATask>();
+const MAX_TASKS = 1000;
+
+function pruneOldTasks() {
+  if (tasks.size <= MAX_TASKS) return;
+  // Remove oldest completed tasks first
+  const entries = [...tasks.entries()].sort((a, b) =>
+    new Date(a[1].status.timestamp).getTime() - new Date(b[1].status.timestamp).getTime()
+  );
+  const toRemove = entries.slice(0, tasks.size - MAX_TASKS);
+  for (const [id] of toRemove) tasks.delete(id);
+}
+
+/* ── Skill Router ─────────────────────────────────────────────────────── */
+
+interface SkillRoute {
+  pattern: RegExp;
+  tool: string;
+  extractParams: (text: string) => Record<string, string>;
+}
+
+const SKILL_ROUTES: SkillRoute[] = [
+  {
+    pattern: /^(?:search|find|look\s*up|query)\b/i,
+    tool: 'search_notes',
+    extractParams: (text) => ({ q: text.replace(/^(?:search|find|look\s*up|query)\s+(?:for\s+)?/i, '').trim() }),
+  },
+  {
+    pattern: /^(?:read|get|show|open|view)\s+(?:the\s+)?(?:file\s+)?(?:at\s+)?(.+\.(?:md|csv))/i,
+    tool: 'read_file',
+    extractParams: (text) => {
+      const match = text.match(/(?:at\s+)?([^\s]+\.(?:md|csv))/i);
+      return { path: match?.[1] ?? '' };
+    },
+  },
+  {
+    pattern: /^(?:list|show|tree)\s+(?:files|spaces|structure)/i,
+    tool: 'list_files',
+    extractParams: () => ({}),
+  },
+  {
+    pattern: /^(?:list|show)\s+spaces/i,
+    tool: 'list_spaces',
+    extractParams: () => ({}),
+  },
+];
+
+function routeToTool(text: string): { tool: string; params: Record<string, string> } | null {
+  for (const route of SKILL_ROUTES) {
+    if (route.pattern.test(text)) {
+      return { tool: route.tool, params: route.extractParams(text) };
+    }
+  }
+  return null;
+}
+
+/* ── Execute via internal API ─────────────────────────────────────────── */
+
+const TOOL_TIMEOUT_MS = 10_000;
+
+async function fetchWithTimeout(url: string): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), TOOL_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    return res;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+/** Sanitize file path: reject traversal attempts */
+function sanitizePath(p: string): string {
+  if (!p || p.includes('..') || p.includes('\0')) throw new Error('Invalid path');
+  // Normalize double slashes and strip leading slashes
+  return p.replace(/\/\//g, '/').replace(/^\/+/, '');
+}
+
+async function executeTool(tool: string, params: Record<string, string>): Promise<string> {
+  const baseUrl = `http://localhost:${process.env.PORT || 3456}`;
+
+  switch (tool) {
+    case 'search_notes': {
+      const q = (params.q || '').slice(0, 500); // limit query length
+      const res = await fetchWithTimeout(`${baseUrl}/api/search?q=${encodeURIComponent(q)}`);
+      if (!res.ok) throw new Error(`Search failed: ${res.status}`);
+      const data = await res.json();
+      return JSON.stringify(data, null, 2);
+    }
+    case 'read_file': {
+      const safePath = sanitizePath(params.path || '');
+      const res = await fetchWithTimeout(`${baseUrl}/api/file?path=${encodeURIComponent(safePath)}`);
+      if (!res.ok) throw new Error(`Read failed: ${res.status}`);
+      const data = await res.json();
+      return typeof data.content === 'string' ? data.content : JSON.stringify(data);
+    }
+    case 'list_files': {
+      const res = await fetchWithTimeout(`${baseUrl}/api/files`);
+      if (!res.ok) throw new Error(`List failed: ${res.status}`);
+      const data = await res.json();
+      return JSON.stringify(data, null, 2);
+    }
+    case 'list_spaces': {
+      const res = await fetchWithTimeout(`${baseUrl}/api/files`);
+      if (!res.ok) throw new Error(`List failed: ${res.status}`);
+      const data = await res.json();
+      const spaces = (data.tree ?? data.files ?? []).filter((n: { isSpace?: boolean }) => n.isSpace);
+      return JSON.stringify(spaces, null, 2);
+    }
+    default:
+      throw new Error(`Unknown tool: ${tool}`);
+  }
+}
+
+/* ── Public API ────────────────────────────────────────────────────────── */
+
+export async function handleSendMessage(params: SendMessageParams): Promise<A2ATask> {
+  const taskId = randomUUID();
+  const now = new Date().toISOString();
+
+  // Extract text from message parts
+  const text = params.message.parts
+    .map(p => p.text ?? (p.data ? JSON.stringify(p.data) : ''))
+    .join(' ')
+    .trim();
+
+  if (!text) {
+    const failedTask = createTask(taskId, 'TASK_STATE_FAILED', 'Empty message — no text content found.', now);
+    tasks.set(taskId, failedTask);
+    return failedTask;
+  }
+
+  // Create task in WORKING state
+  const task = createTask(taskId, 'TASK_STATE_WORKING', undefined, now);
+  task.history = [params.message];
+  tasks.set(taskId, task);
+  pruneOldTasks();
+
+  // Route to tool
+  const route = routeToTool(text);
+
+  try {
+    let result: string;
+    if (route) {
+      result = await executeTool(route.tool, route.params);
+    } else {
+      // Fallback: treat as search query
+      result = await executeTool('search_notes', { q: text });
+    }
+
+    // Update task to completed
+    task.status = {
+      state: 'TASK_STATE_COMPLETED',
+      timestamp: new Date().toISOString(),
+    };
+    task.artifacts = [{
+      artifactId: randomUUID(),
+      name: 'result',
+      parts: [{ text: result, mediaType: 'text/plain' }],
+    }];
+    task.history.push({
+      role: 'ROLE_AGENT',
+      parts: [{ text: result }],
+    });
+
+    return task;
+  } catch (err) {
+    task.status = {
+      state: 'TASK_STATE_FAILED',
+      message: {
+        role: 'ROLE_AGENT',
+        parts: [{ text: `Error: ${(err as Error).message}` }],
+      },
+      timestamp: new Date().toISOString(),
+    };
+    return task;
+  }
+}
+
+export function handleGetTask(params: GetTaskParams): A2ATask | null {
+  return tasks.get(params.id) ?? null;
+}
+
+export function handleCancelTask(params: CancelTaskParams): A2ATask | null {
+  const task = tasks.get(params.id);
+  if (!task) return null;
+
+  const terminalStates: TaskState[] = ['TASK_STATE_COMPLETED', 'TASK_STATE_FAILED', 'TASK_STATE_CANCELED', 'TASK_STATE_REJECTED'];
+  if (terminalStates.includes(task.status.state)) return null; // not cancelable
+
+  task.status = {
+    state: 'TASK_STATE_CANCELED',
+    timestamp: new Date().toISOString(),
+  };
+  return task;
+}
+
+/* ── Helpers ───────────────────────────────────────────────────────────── */
+
+function createTask(id: string, state: TaskState, errorMessage: string | undefined, timestamp: string): A2ATask {
+  return {
+    id,
+    status: {
+      state,
+      timestamp,
+      ...(errorMessage ? { message: { role: 'ROLE_AGENT', parts: [{ text: errorMessage }] } } : {}),
+    },
+  };
+}

package/app/lib/a2a/types.ts

@@ -0,0 +1,158 @@
+/**
+ * A2A Protocol v1.0 — Core Types for MindOS Agent Card & Task handling.
+ * Subset of the full spec: only what's needed for Phase 1 (Server mode).
+ * Reference: https://a2a-protocol.org/latest/specification/
+ */
+
+/* ── Agent Card ────────────────────────────────────────────────────────── */
+
+export interface AgentCard {
+  name: string;
+  description: string;
+  version: string;
+  provider: {
+    organization: string;
+    url: string;
+  };
+  supportedInterfaces: AgentInterface[];
+  capabilities: AgentCapabilities;
+  defaultInputModes: string[];
+  defaultOutputModes: string[];
+  skills: AgentSkill[];
+  securitySchemes?: Record<string, SecurityScheme>;
+  securityRequirements?: Record<string, string[]>[];
+}
+
+export interface AgentInterface {
+  url: string;
+  protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP_JSON';
+  protocolVersion: string;
+}
+
+export interface AgentCapabilities {
+  streaming: boolean;
+  pushNotifications: boolean;
+  stateTransitionHistory: boolean;
+}
+
+export interface AgentSkill {
+  id: string;
+  name: string;
+  description: string;
+  tags?: string[];
+  examples?: string[];
+  inputModes?: string[];
+  outputModes?: string[];
+}
+
+export interface SecurityScheme {
+  httpAuthSecurityScheme?: {
+    scheme: string;
+    bearerFormat?: string;
+  };
+}
+
+/* ── JSON-RPC ──────────────────────────────────────────────────────────── */
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  result?: unknown;
+  error?: JsonRpcError;
+}
+
+export interface JsonRpcError {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+/* ── A2A Messages & Tasks ──────────────────────────────────────────────── */
+
+export type TaskState =
+  | 'TASK_STATE_SUBMITTED'
+  | 'TASK_STATE_WORKING'
+  | 'TASK_STATE_INPUT_REQUIRED'
+  | 'TASK_STATE_COMPLETED'
+  | 'TASK_STATE_FAILED'
+  | 'TASK_STATE_CANCELED'
+  | 'TASK_STATE_REJECTED';
+
+export type MessageRole = 'ROLE_USER' | 'ROLE_AGENT';
+
+export interface MessagePart {
+  text?: string;
+  data?: unknown;
+  mediaType?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface A2AMessage {
+  role: MessageRole;
+  parts: MessagePart[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface TaskStatus {
+  state: TaskState;
+  message?: A2AMessage;
+  timestamp: string;
+}
+
+export interface TaskArtifact {
+  artifactId: string;
+  name?: string;
+  description?: string;
+  parts: MessagePart[];
+}
+
+export interface A2ATask {
+  id: string;
+  contextId?: string;
+  status: TaskStatus;
+  artifacts?: TaskArtifact[];
+  history?: A2AMessage[];
+  metadata?: Record<string, unknown>;
+}
+
+/* ── A2A Method Params ─────────────────────────────────────────────────── */
+
+export interface SendMessageParams {
+  message: A2AMessage;
+  configuration?: {
+    acceptedOutputModes?: string[];
+    blocking?: boolean;
+    historyLength?: number;
+  };
+  metadata?: Record<string, unknown>;
+}
+
+export interface GetTaskParams {
+  id: string;
+  historyLength?: number;
+}
+
+export interface CancelTaskParams {
+  id: string;
+}
+
+/* ── Error Codes ───────────────────────────────────────────────────────── */
+
+export const A2A_ERRORS = {
+  TASK_NOT_FOUND: { code: -32001, message: 'Task not found' },
+  TASK_NOT_CANCELABLE: { code: -32002, message: 'Task not cancelable' },
+  UNSUPPORTED_OPERATION: { code: -32004, message: 'Unsupported operation' },
+  CONTENT_TYPE_NOT_SUPPORTED: { code: -32005, message: 'Content type not supported' },
+  PARSE_ERROR: { code: -32700, message: 'Parse error' },
+  INVALID_REQUEST: { code: -32600, message: 'Invalid request' },
+  METHOD_NOT_FOUND: { code: -32601, message: 'Method not found' },
+  INVALID_PARAMS: { code: -32602, message: 'Invalid params' },
+  INTERNAL_ERROR: { code: -32603, message: 'Internal error' },
+} as const;

package/bin/cli.js

@@ -67,6 +67,9 @@ import * as fileCmd from './commands/file.js';
 import * as spaceCmd from './commands/space.js';
 import * as askCmd from './commands/ask.js';
 import * as statusCmd from './commands/status.js';
+import * as apiCmd from './commands/api.js';
+import * as agentCmd from './commands/agent.js';
+import * as searchCmd from './commands/search.js';
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
@@ -1311,6 +1314,9 @@ ${bold('Examples:')}
   space:  async () => { const p = parseArgs(process.argv.slice(3)); await spaceCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
   ask:    async () => { const p = parseArgs(process.argv.slice(3)); await askCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
   status: async () => { const p = parseArgs(process.argv.slice(3)); await statusCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
+  api:    async () => { const p = parseArgs(process.argv.slice(3)); await apiCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
+  agent:  async () => { const p = parseArgs(process.argv.slice(3)); await agentCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
+  search: async () => { const p = parseArgs(process.argv.slice(3)); await searchCmd.run([p.command, ...p.args].filter(Boolean), p.flags); },
 };
 
 // ── Entry ─────────────────────────────────────────────────────────────────────
@@ -1337,7 +1343,10 @@ ${row('mindos open',                       'Open Web UI in browser')}
 ${bold('Knowledge:')}
 ${row('mindos file <sub>',                 'File operations (list/read/create/delete/search)')}
 ${row('mindos space <sub>',                'Space management (list/create/info)')}
+${row('mindos search "<query>"',           'Search knowledge base via API')}
 ${row('mindos ask "<question>"',           'Ask AI using your knowledge base')}
+${row('mindos agent <sub>',               'AI Agent management (list/info)')}
+${row('mindos api <METHOD> <path>',        'Raw API passthrough (for developers/agents)')}
 
 ${bold('MCP:')}
 ${row('mindos mcp',                        'Start MCP server only')}
@@ -1354,6 +1363,7 @@ ${bold('Config & Diagnostics:')}
 ${row('mindos config <sub>',               'View/update config (show/set/unset/validate)')}
 ${row('mindos doctor',                     'Health check')}
 ${row('mindos update',                     'Update to latest version')}
+${row('mindos uninstall',                  'Fully uninstall MindOS')}
 ${row('mindos logs',                       'Tail service logs')}
 
 ${bold('Global Flags:')}

package/bin/commands/agent.js

@@ -0,0 +1,18 @@
+import{bold,dim,cyan,green,red,yellow}from"../lib/colors.js";import{MCP_AGENTS,detectAgentPresence}from"../lib/mcp-agents.js";import{existsSync,readFileSync}from"node:fs";import{resolve}from"node:path";import{homedir}from"node:os";import{output,isJsonMode}from"../lib/command.js";function expandHome(p){return p.startsWith("~/")?resolve(homedir(),p.slice(2)):p}export const meta={name:"agent",group:"Knowledge",summary:"AI Agent management (list/info)",usage:"mindos agent <subcommand>"};export async function run(a,f){const s=a[0];if(!s||f.help||f.h){console.log(bold("mindos agent")+" — AI Agent management
+
+Subcommands:
+  list   List detected AI agents
+  info   Show agent details
+
+Agent Keys: "+Object.keys(MCP_AGENTS).join(", "));return}if(s==="list"||s==="ls")return agentList(f);if(s==="info")return agentInfo(a[1],f);console.error(red("Unknown: "+s));process.exit(1)}function hasMindosConfig(agent){const paths=[agent.global,agent.project].filter(Boolean).map(expandHome);for(const p of paths){try{if(!existsSync(p))continue;const raw=readFileSync(p,"utf-8").replace(///.*$/gm,"").replace(//*[\s\S]*?*//g,"");const data=JSON.parse(raw);const servers=data[agent.key]||{};if(Object.keys(servers).some(k=>k.toLowerCase().includes("mindos")))return true}catch{}}return false}function agentList(f){const agents=[];for(const[key,agent]of Object.entries(MCP_AGENTS)){if(!detectAgentPresence(key))continue;agents.push({key,name:agent.name,installed:true,mindosConnected:hasMindosConfig(agent)})}if(isJsonMode(f)){output({count:agents.length,agents},f);return}if(agents.length===0){console.log(dim("No AI agents detected."));return}console.log("
+"+bold("Detected Agents ("+agents.length+"):")+"
+");for(const a of agents){console.log("  "+a.name.padEnd(20)+" "+(a.mindosConnected?green("● connected"):dim("○ not connected")))}console.log("
+"+dim("Connect: mindos mcp install <agent-key>")+"
+")}function agentInfo(key,f){if(!key){console.error(red("Usage: mindos agent info <key>"));process.exit(1)}const agent=MCP_AGENTS[key];if(!agent){console.error(red("Unknown: "+key));process.exit(1)}const installed=detectAgentPresence(key);const connected=installed?hasMindosConfig(agent):false;const info={key,name:agent.name,installed,mindosConnected:connected,transport:agent.preferredTransport};if(isJsonMode(f)){output(info,f);return}console.log("
+"+bold(agent.name)+"
+  Key:       "+key+"
+  Installed: "+(installed?green("yes"):red("no"))+"
+  MindOS:    "+(connected?green("connected"):yellow("not connected"))+"
+  Transport: "+agent.preferredTransport+(agent.global?"
+  Config:    "+expandHome(agent.global):"")+"
+")}

package/bin/commands/api.js

@@ -0,0 +1,58 @@
+import { bold, dim, cyan, red } from '../lib/colors.js';
+import { loadConfig } from '../lib/config.js';
+
+export const meta = {
+  name: 'api',
+  group: 'Knowledge',
+  summary: 'Raw API passthrough (GET/POST/PUT/DELETE any endpoint)',
+  usage: 'mindos api <METHOD> <path>',
+};
+
+export async function run(args, flags) {
+  if (args.length < 2 || flags.help || flags.h) {
+    console.log(bold('mindos api') + ' — Raw API passthrough\n');
+    console.log('Usage: mindos api <METHOD> <path> [--body <json>]');
+    console.log('Methods: GET, POST, PUT, PATCH, DELETE\n');
+    console.log('Examples:');
+    console.log('  mindos api GET /api/health');
+    console.log('  mindos api GET /api/files');
+    console.log('  mindos api POST /api/ask --body \'{"question":"..."}\'');
+    return;
+  }
+
+  const method = args[0].toUpperCase();
+  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+    console.error(red('Invalid method: ' + args[0]));
+    process.exit(1);
+  }
+
+  let apiPath = args[1];
+  if (!apiPath.startsWith('/')) apiPath = '/' + apiPath;
+
+  loadConfig();
+  const port = flags.port || process.env.MINDOS_WEB_PORT || '3456';
+  const token = process.env.MINDOS_AUTH_TOKEN || '';
+  const headers = { 'Content-Type': 'application/json' };
+  if (token) headers['Authorization'] = 'Bearer ' + token;
+
+  const fetchOpts = { method, headers };
+  if (flags.body && method !== 'GET') fetchOpts.body = flags.body;
+
+  try {
+    const res = await fetch('http://localhost:' + port + apiPath, fetchOpts);
+    const ct = res.headers.get('content-type') || '';
+    if (ct.includes('json')) {
+      console.log(JSON.stringify(await res.json(), null, 2));
+    } else {
+      console.log(await res.text());
+    }
+    if (!res.ok) process.exit(1);
+  } catch (err) {
+    if (err.cause && err.cause.code === 'ECONNREFUSED') {
+      console.error(red('Connection refused. Start with: mindos start'));
+    } else {
+      console.error(red('Request failed: ' + err.message));
+    }
+    process.exit(1);
+  }
+}