@imenam/mcp-documentor 1.0.23

package/README.md

@@ -0,0 +1,74 @@
+# @imenam/mcp-documentor
+
+An MCP server to create, manage, and search project documentation — with staleness tracking and optional semantic search.
+
+Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI document, browse and verify your codebase docs without leaving the chat.
+
+## Features
+
+- **Create & update docs** — write markdown documentation entries linked to source files
+- **Staleness tracking** — automatically detects when tracked files have changed since the last doc update
+- **Semantic search** — find relevant docs by meaning (requires an OpenAI API key)
+- **Multi-project support** — organize docs into separate projects and switch between them
+- **GUI** — built-in web interface to browse and read documentation
+- **Proxy-aware** — integrates with the [proxy-setup](https://github.com/Imena/proxy-setup) for GUI exposure
+
+## Installation
+
+```bash
+npx -y @imenam/mcp-documentor
+```
+
+Or install globally:
+
+```bash
+npm install -g @imenam/mcp-documentor
+```
+
+## MCP Configuration
+
+Add to your MCP client config (e.g. Cursor `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "mcp-documentor": {
+      "command": "npx",
+      "args": ["-y", "@imenam/mcp-documentor"],
+      "env": {
+        "OPENAI_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `OPENAI_API_KEY` | No | Enables semantic search via OpenAI embeddings |
+| `PROXY_URL` | No | URL of the proxy server to register the GUI |
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `create_doc` | Create a new documentation entry linked to source files |
+| `get_doc` | Retrieve a documentation entry with full content |
+| `get_doc_metadata` | Get metadata and freshness status without loading content |
+| `list_docs` | List all docs in the current project with staleness indicators |
+| `update_doc` | Update an existing documentation entry |
+| `search_docs` | Search docs by keyword or semantic similarity |
+| `check_freshness` | Check if a doc is up-to-date relative to its tracked files |
+| `refresh_file_snapshot` | Mark files as up-to-date without editing the doc content |
+| `list_projects` | List all documentation projects |
+| `set_project` | Switch to a different project |
+
+## Data Storage
+
+Documentation is stored locally in a `data/` directory next to the server process. This directory is **not** included in the npm package — it is created at runtime in the working directory.
+
+## License
+
+ISC

package/dist/shared/schemas/doc.schema.d.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+export declare const TrackedFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    lastModifiedAt: z.ZodString;
+    contentHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TrackedFile = z.infer<typeof TrackedFileSchema>;
+export declare const DocSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    content: z.ZodString;
+    tracked_files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        lastModifiedAt: z.ZodString;
+        contentHash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    folder: z.ZodOptional<z.ZodString>;
+    related_docs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type DocEntry = z.infer<typeof DocSchema>;
+export interface DocSummary {
+    id: string;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    tags: string[];
+    isStale: boolean;
+    folder?: string;
+}
+export interface DocMatch {
+    id: string;
+    title: string;
+    score: number;
+    excerpt: string;
+    /** Set when the hit comes from a known project scope (e.g. multi-project search). */
+    project?: string;
+}
+export declare const FreshnessReportSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        up_to_date: "up_to_date";
+        stale: "stale";
+        no_tracking: "no_tracking";
+    }>;
+    modified: z.ZodArray<z.ZodString>;
+    missing: z.ZodArray<z.ZodString>;
+    unchanged: z.ZodArray<z.ZodString>;
+    total: z.ZodNumber;
+}, z.core.$strip>;
+export type FreshnessReport = z.infer<typeof FreshnessReportSchema>;
+export declare const CreateDocArgsSchema: z.ZodObject<{
+    title: z.ZodString;
+    content: z.ZodString;
+    tracked_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    folder: z.ZodOptional<z.ZodString>;
+    related_docs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const UpdateDocArgsSchema: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
+    tracked_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    related_docs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const GetDocArgsSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strip>;
+export declare const MoveDocArgsSchema: z.ZodObject<{
+    path: z.ZodString;
+    new_path: z.ZodString;
+}, z.core.$strip>;
+export declare const CheckFreshnessArgsSchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+    project: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SearchDocsArgsSchema: z.ZodObject<{
+    query: z.ZodString;
+    top_k: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export declare const RefreshFileSnapshotArgsSchema: z.ZodObject<{
+    paths: z.ZodArray<z.ZodString>;
+    file_paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const GetDocMetadataArgsSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strip>;
+export declare const PatchDocArgsSchema: z.ZodObject<{
+    path: z.ZodString;
+    search: z.ZodString;
+    replacement: z.ZodString;
+}, z.core.$strip>;
+export declare const CheckLinksArgsSchema: z.ZodObject<{
+    project: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const GitDiffDocArgsSchema: z.ZodObject<{
+    paths: z.ZodArray<z.ZodString>;
+    file_paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const SetProjectArgsSchema: z.ZodObject<{
+    project: z.ZodString;
+}, z.core.$strip>;
+export declare const IPCMessageSchema: z.ZodObject<{
+    type: z.ZodString;
+    correlationId: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodAny>;
+    error: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type IPCMessage = z.infer<typeof IPCMessageSchema>;

package/dist/shared/schemas/doc.schema.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+export const TrackedFileSchema = z.object({
+    path: z.string(),
+    lastModifiedAt: z.string(),
+    contentHash: z.string().optional(),
+});
+export const DocSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    content: z.string(),
+    tracked_files: z.array(TrackedFileSchema).default([]),
+    tags: z.array(z.string()).default([]),
+    folder: z.string().optional(),
+    related_docs: z.array(z.string()).default([]),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const FreshnessReportSchema = z.object({
+    status: z.enum(["up_to_date", "stale", "no_tracking"]),
+    modified: z.array(z.string()),
+    missing: z.array(z.string()),
+    unchanged: z.array(z.string()),
+    total: z.number(),
+});
+export const CreateDocArgsSchema = z.object({
+    title: z.string().describe("Title of the documentation entry"),
+    content: z.string().describe("Documentation content in markdown"),
+    tracked_files: z.array(z.string()).optional().describe("File paths to track for staleness detection"),
+    tags: z.array(z.string()).optional().describe("Tags for categorization"),
+    folder: z.string().optional().describe("Folder path for organization, e.g. 'frontend/components'"),
+    related_docs: z.array(z.string()).optional().describe("IDs of related documentation entries"),
+});
+export const UpdateDocArgsSchema = z.object({
+    path: z.string().describe("Path of the documentation entry to update, e.g. 'backend/auth/authentication' or 'authentication' for root docs"),
+    content: z.string().optional().describe("New content (replaces existing)"),
+    tracked_files: z.array(z.string()).optional().describe("New list of file paths (replaces existing)"),
+    tags: z.array(z.string()).optional().describe("New tags (replaces existing)"),
+    related_docs: z.array(z.string()).optional().describe("Paths of related documentation entries (replaces existing)"),
+});
+export const GetDocArgsSchema = z.object({
+    path: z.string().describe("Path of the documentation entry, e.g. 'backend/auth/authentication' or 'authentication' for root docs"),
+});
+export const MoveDocArgsSchema = z.object({
+    path: z.string().describe("Current path of the documentation entry, e.g. 'backend/auth/authentication'"),
+    new_path: z.string().describe("New path for the documentation entry, e.g. 'backend/v2/authentication'. Changes folder and/or name."),
+});
+export const CheckFreshnessArgsSchema = z.object({
+    path: z.string().optional().describe("Path of a single documentation entry to check, e.g. 'backend/auth/authentication'. If omitted, checks all docs in the project."),
+    project: z.string().optional().describe("Project to scan (defaults to current project). Only used when path is omitted."),
+});
+export const SearchDocsArgsSchema = z.object({
+    query: z.string().describe("Search query in natural language"),
+    top_k: z.number().optional().default(5).describe("Number of results to return"),
+});
+export const RefreshFileSnapshotArgsSchema = z.object({
+    paths: z.array(z.string()).min(1).describe("Paths of documentation entries to refresh, e.g. ['backend/auth/authentication', 'setup']"),
+    file_paths: z.array(z.string()).optional().describe("Specific tracked file paths to refresh (refreshes all tracked files if omitted)"),
+});
+export const GetDocMetadataArgsSchema = z.object({
+    path: z.string().describe("Path of the documentation entry, e.g. 'backend/auth/authentication'"),
+});
+export const PatchDocArgsSchema = z.object({
+    path: z.string().describe("Path of the documentation entry to patch, e.g. 'backend/auth/authentication'"),
+    search: z.string().describe("Exact text to find in the current content"),
+    replacement: z.string().describe("Text to replace it with"),
+});
+export const CheckLinksArgsSchema = z.object({
+    project: z.string().optional().describe("Project to check (defaults to current project)"),
+});
+export const GitDiffDocArgsSchema = z.object({
+    paths: z.array(z.string()).min(1).describe("Paths of documentation entries to diff, e.g. ['backend/auth/authentication']"),
+    file_paths: z.array(z.string()).optional().describe("Specific tracked file paths to diff (all tracked files if omitted)"),
+});
+export const SetProjectArgsSchema = z.object({
+    project: z.string().describe("Project name to switch to (created if it does not exist)"),
+});
+export const IPCMessageSchema = z.object({
+    type: z.string(),
+    correlationId: z.string().optional(),
+    data: z.any().optional(),
+    error: z.string().optional(),
+    timestamp: z.string(),
+});

package/dist/src/core/embedding-engine.d.ts

@@ -0,0 +1,23 @@
+import type { EmbeddingStore } from "./embedding-store.js";
+import type { DocMatch } from "../../shared/schemas/doc.schema.js";
+export declare class EmbeddingEngine {
+    private client;
+    private model;
+    private store;
+    constructor(store: EmbeddingStore);
+    isConfigured(): boolean;
+    private refreshClient;
+    generateEmbedding(text: string): Promise<number[] | null>;
+    cosineSimilarity(a: number[], b: number[]): number;
+    saveEmbedding(docId: string, embedding: number[], project: string): Promise<void>;
+    removeEmbedding(docId: string, project: string): Promise<void>;
+    moveEmbedding(oldDocId: string, newDocId: string, project: string): Promise<void>;
+    search(query: string, project: string, topK: number, getDocContent: (id: string) => Promise<{
+        title: string;
+        content: string;
+    } | null>): Promise<DocMatch[]>;
+    searchAcrossProjects(query: string, projects: string[], topK: number, getDocContent: (project: string, docId: string) => Promise<{
+        title: string;
+        content: string;
+    } | null>): Promise<DocMatch[]>;
+}

package/dist/src/core/embedding-engine.js

@@ -0,0 +1,119 @@
+import OpenAI from "openai";
+import { createLogger } from "@imenam/mcp-gui-interface";
+const logger = createLogger("EmbeddingEngine");
+export class EmbeddingEngine {
+    client = null;
+    model;
+    store;
+    constructor(store) {
+        this.store = store;
+        this.model = process.env.MCP_DOCUMENTOR_OPENAI_MODEL || "text-embedding-3-small";
+        const apiKey = process.env.MCP_DOCUMENTOR_OPENAI_API_KEY;
+        if (apiKey && apiKey.trim() !== "") {
+            this.client = new OpenAI({ apiKey });
+        }
+    }
+    isConfigured() {
+        return this.client !== null;
+    }
+    refreshClient() {
+        const apiKey = process.env.MCP_DOCUMENTOR_OPENAI_API_KEY;
+        this.model = process.env.MCP_DOCUMENTOR_OPENAI_MODEL || "text-embedding-3-small";
+        if (apiKey && apiKey.trim() !== "") {
+            this.client = new OpenAI({ apiKey });
+        }
+        else {
+            this.client = null;
+        }
+    }
+    async generateEmbedding(text) {
+        this.refreshClient();
+        if (!this.client)
+            return null;
+        try {
+            const response = await this.client.embeddings.create({
+                model: this.model,
+                input: text,
+            });
+            return response.data[0].embedding;
+        }
+        catch (err) {
+            logger.error(`Failed to generate embedding: ${err.message}`);
+            return null;
+        }
+    }
+    cosineSimilarity(a, b) {
+        if (a.length !== b.length)
+            return 0;
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+        if (denominator === 0)
+            return 0;
+        return dotProduct / denominator;
+    }
+    async saveEmbedding(docId, embedding, project) {
+        this.store.save(project, docId, embedding);
+        logger.debug(`Embedding saved for doc "${docId}" in project "${project}"`);
+    }
+    async removeEmbedding(docId, project) {
+        this.store.remove(project, docId);
+        logger.debug(`Embedding removed for doc "${docId}" in project "${project}"`);
+    }
+    async moveEmbedding(oldDocId, newDocId, project) {
+        this.store.move(project, oldDocId, newDocId);
+        logger.debug(`Embedding moved: "${oldDocId}" → "${newDocId}" in project "${project}"`);
+    }
+    async search(query, project, topK, getDocContent) {
+        return this.searchAcrossProjects(query, [project], topK, async (_proj, docId) => getDocContent(docId));
+    }
+    async searchAcrossProjects(query, projects, topK, getDocContent) {
+        this.refreshClient();
+        if (!this.client) {
+            throw new Error("OpenAI API key is not configured. Set MCP_DOCUMENTOR_OPENAI_API_KEY in your .env file to enable semantic search.");
+        }
+        const queryEmbedding = await this.generateEmbedding(query);
+        if (!queryEmbedding) {
+            throw new Error("Failed to generate embedding for search query.");
+        }
+        const allEntries = this.store.loadAllProjects(projects);
+        const seenKeys = new Set();
+        const scored = [];
+        for (const { project, docId, embedding } of allEntries) {
+            const dedupeKey = `${project}::${docId}`;
+            if (seenKeys.has(dedupeKey))
+                continue;
+            seenKeys.add(dedupeKey);
+            scored.push({
+                project,
+                id: docId,
+                score: this.cosineSimilarity(queryEmbedding, embedding),
+            });
+        }
+        if (scored.length === 0)
+            return [];
+        scored.sort((a, b) => b.score - a.score);
+        const topResults = scored.slice(0, topK);
+        const matches = [];
+        const multiProject = projects.length > 1;
+        for (const result of topResults) {
+            const doc = await getDocContent(result.project, result.id);
+            if (doc) {
+                matches.push({
+                    id: result.id,
+                    title: doc.title,
+                    score: Math.round(result.score * 100) / 100,
+                    excerpt: doc.content.substring(0, 200),
+                    ...(multiProject ? { project: result.project } : {}),
+                });
+            }
+        }
+        return matches;
+    }
+}

package/dist/src/core/embedding-store.d.ts

@@ -0,0 +1,15 @@
+export declare class EmbeddingStore {
+    private db;
+    init(dataDir: string, model: string): void;
+    private handleModelDrift;
+    private getDb;
+    save(project: string, docId: string, embedding: number[]): void;
+    remove(project: string, docId: string): void;
+    move(project: string, oldDocId: string, newDocId: string): void;
+    loadAll(project: string): Map<string, number[]>;
+    loadAllProjects(projects: string[]): Array<{
+        project: string;
+        docId: string;
+        embedding: number[];
+    }>;
+}

package/dist/src/core/embedding-store.js

@@ -0,0 +1,97 @@
+import { createRequire } from "module";
+import path from "path";
+import fs from "fs";
+import { createLogger } from "@imenam/mcp-gui-interface";
+const require = createRequire(import.meta.url);
+const Database = require("better-sqlite3");
+const logger = createLogger("EmbeddingStore");
+const DB_FILENAME = "embeddings.db";
+const META_MODEL_KEY = "embedding_model";
+function embeddingToBuffer(embedding) {
+    return Buffer.from(new Float32Array(embedding).buffer);
+}
+function bufferToEmbedding(buffer) {
+    return Array.from(new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4));
+}
+export class EmbeddingStore {
+    db = null;
+    init(dataDir, model) {
+        if (this.db)
+            return;
+        fs.mkdirSync(dataDir, { recursive: true });
+        this.db = new Database(path.join(dataDir, DB_FILENAME));
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma("synchronous = NORMAL");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS embeddings (
+        project   TEXT NOT NULL,
+        doc_id    TEXT NOT NULL,
+        embedding BLOB NOT NULL,
+        PRIMARY KEY (project, doc_id)
+      );
+
+      CREATE TABLE IF NOT EXISTS meta (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+    `);
+        this.handleModelDrift(model);
+        const { c } = this.db.prepare("SELECT COUNT(*) as c FROM embeddings").get();
+        logger.info(`EmbeddingStore initialized — ${c} embeddings in store`);
+    }
+    handleModelDrift(currentModel) {
+        const row = this.db.prepare("SELECT value FROM meta WHERE key = ?").get(META_MODEL_KEY);
+        if (row && row.value !== currentModel) {
+            logger.warn(`Embedding model changed from "${row.value}" to "${currentModel}" — clearing embedding store`);
+            this.db.prepare("DELETE FROM embeddings").run();
+        }
+        this.db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run(META_MODEL_KEY, currentModel);
+    }
+    getDb() {
+        if (!this.db)
+            throw new Error("EmbeddingStore not initialized. Call init() first.");
+        return this.db;
+    }
+    save(project, docId, embedding) {
+        const buf = embeddingToBuffer(embedding);
+        this.getDb()
+            .prepare("INSERT OR REPLACE INTO embeddings (project, doc_id, embedding) VALUES (?, ?, ?)")
+            .run(project, docId, buf);
+        logger.debug(`Embedding saved: [${project}] ${docId}`);
+    }
+    remove(project, docId) {
+        this.getDb()
+            .prepare("DELETE FROM embeddings WHERE project = ? AND doc_id = ?")
+            .run(project, docId);
+        logger.debug(`Embedding removed: [${project}] ${docId}`);
+    }
+    move(project, oldDocId, newDocId) {
+        this.getDb()
+            .prepare("UPDATE embeddings SET doc_id = ? WHERE project = ? AND doc_id = ?")
+            .run(newDocId, project, oldDocId);
+        logger.debug(`Embedding moved: [${project}] ${oldDocId} → ${newDocId}`);
+    }
+    loadAll(project) {
+        const rows = this.getDb()
+            .prepare("SELECT doc_id, embedding FROM embeddings WHERE project = ?")
+            .all(project);
+        const result = new Map();
+        for (const row of rows) {
+            result.set(row.doc_id, bufferToEmbedding(row.embedding));
+        }
+        return result;
+    }
+    loadAllProjects(projects) {
+        if (projects.length === 0)
+            return [];
+        const placeholders = projects.map(() => "?").join(", ");
+        const rows = this.getDb()
+            .prepare(`SELECT project, doc_id, embedding FROM embeddings WHERE project IN (${placeholders})`)
+            .all(...projects);
+        return rows.map((row) => ({
+            project: row.project,
+            docId: row.doc_id,
+            embedding: bufferToEmbedding(row.embedding),
+        }));
+    }
+}

package/dist/src/core/migrate-embeddings.d.ts

@@ -0,0 +1,3 @@
+import type { EmbeddingStore } from "./embedding-store.js";
+import type { StorageEngine } from "./storage-engine.js";
+export declare function migrateEmbeddings(embeddingStore: EmbeddingStore, storageEngine: StorageEngine): Promise<void>;

package/dist/src/core/migrate-embeddings.js

@@ -0,0 +1,30 @@
+import fs from "fs";
+import path from "path";
+import { createLogger } from "@imenam/mcp-gui-interface";
+const logger = createLogger("MigrateEmbeddings");
+export async function migrateEmbeddings(embeddingStore, storageEngine) {
+    const config = storageEngine.getConfig();
+    for (const project of config.projects) {
+        const projectDir = storageEngine.getProjectDir(project);
+        const jsonPath = path.join(projectDir, "embeddings.json");
+        if (!fs.existsSync(jsonPath))
+            continue;
+        try {
+            const raw = fs.readFileSync(jsonPath, "utf-8");
+            const store = JSON.parse(raw);
+            const entries = Object.entries(store);
+            if (entries.length === 0) {
+                fs.unlinkSync(jsonPath);
+                continue;
+            }
+            for (const [docId, embedding] of entries) {
+                embeddingStore.save(project, docId, embedding);
+            }
+            fs.unlinkSync(jsonPath);
+            logger.info(`Migrated ${entries.length} embeddings for project "${project}" from JSON to SQLite`);
+        }
+        catch (err) {
+            logger.warn(`Failed to migrate embeddings for project "${project}": ${err.message}`);
+        }
+    }
+}

package/dist/src/core/migrate-folders.d.ts

@@ -0,0 +1,2 @@
+import type { StorageEngine } from "./storage-engine.js";
+export declare function migrateFolders(storageEngine: StorageEngine): Promise<void>;

package/dist/src/core/migrate-folders.js

@@ -0,0 +1,45 @@
+import fs from "fs";
+import path from "path";
+import matter from "gray-matter";
+import { createLogger } from "@imenam/mcp-gui-interface";
+const logger = createLogger("MigrateFolders");
+export async function migrateFolders(storageEngine) {
+    const config = storageEngine.getConfig();
+    if (config.foldersMigrated) {
+        logger.debug("Folder migration already done, skipping.");
+        return;
+    }
+    logger.info("Starting folder migration (virtual frontmatter → real disk folders)...");
+    let totalMoved = 0;
+    for (const project of config.projects) {
+        const projectDir = storageEngine.getProjectDir(project);
+        if (!fs.existsSync(projectDir))
+            continue;
+        const flatMdFiles = fs
+            .readdirSync(projectDir, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith(".md"))
+            .map((e) => path.join(projectDir, e.name));
+        for (const filePath of flatMdFiles) {
+            try {
+                const raw = fs.readFileSync(filePath, "utf-8");
+                const { data } = matter(raw);
+                if (!data.folder)
+                    continue;
+                const targetDir = path.join(projectDir, ...String(data.folder).split("/"));
+                const targetPath = path.join(targetDir, path.basename(filePath));
+                if (targetPath === filePath)
+                    continue;
+                fs.mkdirSync(targetDir, { recursive: true });
+                fs.renameSync(filePath, targetPath);
+                logger.info(`Migrated: ${path.basename(filePath)} → ${data.folder}/`);
+                totalMoved++;
+            }
+            catch (err) {
+                logger.warn(`Failed to migrate ${filePath}: ${err.message}`);
+            }
+        }
+    }
+    config.foldersMigrated = true;
+    storageEngine.saveConfig(config);
+    logger.info(`Folder migration complete: ${totalMoved} file(s) moved.`);
+}

package/dist/src/core/storage-engine.d.ts

@@ -0,0 +1,29 @@
+import type { DocEntry, DocSummary } from "../../shared/schemas/doc.schema.js";
+interface GlobalConfig {
+    currentProject: string;
+    projects: string[];
+    foldersMigrated?: boolean;
+}
+export declare class StorageEngine {
+    private rootDir;
+    constructor(rootDir: string);
+    getDataDir(): string;
+    getProjectDir(project?: string): string;
+    private getConfigPath;
+    getConfig(): GlobalConfig;
+    saveConfig(config: GlobalConfig): void;
+    ensureProject(project: string): void;
+    private walkMdFiles;
+    private docIdToFilePath;
+    private cleanEmptyDirs;
+    saveDoc(doc: DocEntry, project?: string): Promise<void>;
+    getDoc(id: string, project?: string): Promise<DocEntry | null>;
+    listDocs(project?: string): Promise<DocSummary[]>;
+    resolveDoc(id: string): Promise<{
+        doc: DocEntry;
+        project: string;
+    } | null>;
+    deleteDoc(id: string, project?: string): Promise<boolean>;
+    moveDoc(oldId: string, newId: string, project?: string): Promise<boolean>;
+}
+export {};