@justyork/repo-mind 0.4.0 → 0.7.1

package/dist/index/slug.js

@@ -3,6 +3,21 @@ export const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 export function isValidSlug(slug) {
     return SLUG_PATTERN.test(slug);
 }
+/** Derives a kebab-case slug from a human title. */
+export function slugFromTitle(title) {
+    const normalized = title
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    if (isValidSlug(normalized)) {
+        return normalized;
+    }
+    const fallback = normalized ? `draft-${normalized}` : 'draft';
+    const trimmed = fallback.slice(0, 80).replace(/-+$/g, '');
+    return isValidSlug(trimmed) ? trimmed : 'draft';
+}
 /** Builds a stable slug from a path relative to the docs root. */
 export function slugFromRelativePath(relativePath) {
     const normalized = relativePath

package/dist/mcp/server.js

@@ -5,6 +5,7 @@ import { getPackageVersion } from '../package-version.js';
 import { DocIndex } from '../index/doc-index.js';
 import { DOC_TYPES, DOC_STATUSES, DOC_DOMAINS } from '../index/types.js';
 import { exploreGraph } from '../tools/explore-graph.js';
+import { createDraft } from '../tools/create-draft.js';
 import { getDoc } from '../tools/get-doc.js';
 import { getGlossaryTerm } from '../tools/get-glossary-term.js';
 import { listDocs } from '../tools/list-docs.js';
@@ -15,6 +16,7 @@ const TOOL_NAMES = [
     'get_doc',
     'get_glossary_term',
     'explore_graph',
+    'create_draft',
 ];
 function isToolName(name) {
     return TOOL_NAMES.includes(name);
@@ -85,6 +87,23 @@ export async function startMcpServer() {
                     required: ['slug'],
                 },
             },
+            {
+                name: 'create_draft',
+                description: 'Create a SQLite-backed draft for human review in repo-mind UI (gated on ab-demo kill-switch or REPOMIND_AGENT_WRITE=1).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        type: { type: 'string', enum: [...DOC_TYPES] },
+                        title: { type: 'string' },
+                        body: { type: 'string' },
+                        slug: { type: 'string' },
+                        related: { type: 'array', items: { type: 'string' } },
+                        tags: { type: 'array', items: { type: 'string' } },
+                        forked_from: { type: 'string' },
+                    },
+                    required: ['type', 'title', 'body'],
+                },
+            },
         ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -125,6 +144,21 @@ export async function startMcpServer() {
                     slug: typeof args.slug === 'string' ? args.slug : '',
                     depth: typeof args.depth === 'number' ? args.depth : undefined,
                 }));
+            case 'create_draft': {
+                const result = createDraft(index, {
+                    type: typeof args.type === 'string' ? args.type : '',
+                    title: typeof args.title === 'string' ? args.title : '',
+                    body: typeof args.body === 'string' ? args.body : '',
+                    slug: typeof args.slug === 'string' ? args.slug : undefined,
+                    related: Array.isArray(args.related) ? args.related : undefined,
+                    tags: Array.isArray(args.tags) ? args.tags : undefined,
+                    forked_from: typeof args.forked_from === 'string' ? args.forked_from : undefined,
+                });
+                if (!result.ok) {
+                    return toolError(result.error);
+                }
+                return toolResult(result.data);
+            }
             default: {
                 const unknownTool = toolName;
                 throw new Error(`Unknown tool: ${unknownTool}`);
@@ -153,3 +187,9 @@ function toolResult(payload) {
         content: [{ type: 'text', text: JSON.stringify(payload) }],
     };
 }
+function toolError(error) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ error }) }],
+        isError: true,
+    };
+}

package/dist/publish/batch-publish.d.ts

@@ -0,0 +1,29 @@
+import type { DocIndex } from '../index/doc-index.js';
+import type { DraftsDb } from '../ui/db/drafts-db.js';
+export interface PublishedDraft {
+    draftId: string;
+    slug: string;
+    title: string;
+    path: string;
+}
+export interface BatchPublishFailure {
+    draftId: string;
+    slug: string;
+    code: string;
+    message: string;
+}
+export interface BatchPublishResult {
+    published: PublishedDraft[];
+    failures: BatchPublishFailure[];
+}
+export interface BatchPublishOptions {
+    draftIds?: string[];
+    dryRun?: boolean;
+}
+export declare function batchPublishDrafts(index: DocIndex, db: DraftsDb, options?: BatchPublishOptions): BatchPublishResult;
+export declare function defaultCommitMessage(published: PublishedDraft[]): string;
+export declare function defaultPrTitle(published: PublishedDraft[]): string;
+export declare function defaultPrBody(published: PublishedDraft[]): string;
+export declare function buildPublishBranchName(published: PublishedDraft[]): string;
+export declare function resolveUniqueBranchName(repoRoot: string, preferred: string): string;
+export declare function relativeDocsPaths(repoRoot: string, absolutePaths: string[]): string[];

package/dist/publish/batch-publish.js

@@ -0,0 +1,106 @@
+import path from 'node:path';
+import { branchExists } from '../git/git-exec.js';
+import { publishDraft, resolvePublishTargetPath, validateDraftForPublish } from '../ui/publish.js';
+function selectDrafts(db, draftIds) {
+    const active = db.listActive();
+    if (!draftIds || draftIds.length === 0) {
+        return active;
+    }
+    const byId = new Map(active.map((draft) => [draft.id, draft]));
+    return draftIds.map((id) => byId.get(id) ?? null).filter((draft) => draft !== null);
+}
+export function batchPublishDrafts(index, db, options = {}) {
+    const drafts = selectDrafts(db, options.draftIds);
+    const failures = [];
+    const validated = [];
+    for (const draft of drafts) {
+        const validation = validateDraftForPublish(index, draft);
+        if (validation) {
+            failures.push({
+                draftId: draft.id,
+                slug: draft.slug,
+                code: validation.code,
+                message: validation.message,
+            });
+            continue;
+        }
+        validated.push(draft);
+    }
+    if (failures.length > 0) {
+        return { published: [], failures };
+    }
+    if (options.dryRun) {
+        return {
+            published: validated.map((draft) => ({
+                draftId: draft.id,
+                slug: draft.slug,
+                title: draft.title,
+                path: resolvePublishTargetPath(index, draft) ?? '(unresolved)',
+            })),
+            failures: [],
+        };
+    }
+    const published = [];
+    for (const draft of validated) {
+        const result = publishDraft(index, draft);
+        db.markPublished(draft.id, result.path);
+        published.push({
+            draftId: draft.id,
+            slug: draft.slug,
+            title: draft.title,
+            path: result.path,
+        });
+    }
+    return { published, failures: [] };
+}
+export function defaultCommitMessage(published) {
+    const lines = ['docs: publish via repo-mind', ''];
+    for (const item of published) {
+        lines.push(`- ${item.slug} (${item.title})`);
+    }
+    return lines.join('\n').trim();
+}
+export function defaultPrTitle(published) {
+    if (published.length === 1) {
+        return `docs: publish ${published[0].slug}`;
+    }
+    return `docs: publish ${published.length} pages via repo-mind`;
+}
+export function defaultPrBody(published) {
+    const lines = [
+        '## Summary',
+        '',
+        'Published knowledge pages from repo-mind drafts:',
+        '',
+    ];
+    for (const item of published) {
+        lines.push(`- \`${item.slug}\` — ${item.title}`);
+    }
+    lines.push('', '## Test plan', '', '- [ ] `repo-mind check` passes', '- [ ] Pages render in repo-mind UI');
+    return lines.join('\n');
+}
+export function buildPublishBranchName(published) {
+    const slugPart = published
+        .map((item) => item.slug)
+        .slice(0, 2)
+        .join('-')
+        .slice(0, 40);
+    const stamp = new Date().toISOString().replace(/[-:]/g, '').slice(0, 13);
+    const suffix = slugPart ? `${slugPart}-${stamp}` : stamp;
+    return `repo-mind/publish/${suffix}`;
+}
+export function resolveUniqueBranchName(repoRoot, preferred) {
+    if (!branchExists(repoRoot, preferred)) {
+        return preferred;
+    }
+    for (let index = 2; index <= 9; index += 1) {
+        const candidate = `${preferred}-${index}`;
+        if (!branchExists(repoRoot, candidate)) {
+            return candidate;
+        }
+    }
+    return `${preferred}-${Date.now().toString(36)}`;
+}
+export function relativeDocsPaths(repoRoot, absolutePaths) {
+    return absolutePaths.map((absolutePath) => path.relative(repoRoot, absolutePath).replace(/\\/g, '/'));
+}

package/dist/tools/create-draft.d.ts

@@ -0,0 +1,32 @@
+import type { DocIndex } from '../index/doc-index.js';
+export type CreateDraftErrorCode = 'AGENT_WRITE_DISABLED' | 'BAD_TYPE' | 'BAD_SLUG' | 'BAD_TITLE' | 'DRAFT_EXISTS' | 'DOC_NOT_FOUND' | 'NO_KNOWLEDGE_ROOT' | 'SLUG_CONFLICT' | 'WRITE_CONFLICT';
+export interface CreateDraftError {
+    code: CreateDraftErrorCode;
+    message: string;
+    hint?: string;
+}
+export interface CreateDraftSuccess {
+    draftId: string;
+    slug: string;
+    title: string;
+    type: string;
+    editUrl: string;
+    editHint: string;
+}
+export type CreateDraftResult = {
+    ok: true;
+    data: CreateDraftSuccess;
+} | {
+    ok: false;
+    error: CreateDraftError;
+};
+export interface CreateDraftInput {
+    type: string;
+    title: string;
+    body: string;
+    slug?: string;
+    related?: string[];
+    tags?: string[];
+    forked_from?: string;
+}
+export declare function createDraft(index: DocIndex, rawInput: CreateDraftInput, cwd?: string): CreateDraftResult;

package/dist/tools/create-draft.js

@@ -0,0 +1,163 @@
+import { isValidSlug, slugFromTitle } from '../index/slug.js';
+import { DOC_TYPES, isDocType } from '../index/types.js';
+import { getAgentWriteGate } from '../agent-write-gate.js';
+import { getDoc } from './get-doc.js';
+import { openDraftsDb } from '../ui/db/drafts-db.js';
+function stringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === 'string');
+}
+function normalizeInput(raw) {
+    return {
+        type: raw.type.trim(),
+        title: raw.title.trim(),
+        body: raw.body,
+        slug: typeof raw.slug === 'string' && raw.slug.trim() ? raw.slug.trim() : undefined,
+        related: stringArray(raw.related),
+        tags: stringArray(raw.tags),
+        forked_from: typeof raw.forked_from === 'string' && raw.forked_from.trim()
+            ? raw.forked_from.trim()
+            : undefined,
+    };
+}
+function fail(code, message, hint) {
+    return { ok: false, error: { code, message, hint } };
+}
+function success(draft) {
+    const editUrl = `/?draft=${encodeURIComponent(draft.id)}`;
+    return {
+        ok: true,
+        data: {
+            draftId: draft.id,
+            slug: draft.slug,
+            title: draft.title,
+            type: draft.type,
+            editUrl,
+            editHint: `Run \`repo-mind ui\` and open draft "${draft.title}" in the sidebar (${editUrl}).`,
+        },
+    };
+}
+function slugTaken(index, slug, allowExistingDoc) {
+    if (index.getDocBySlug(slug) && !allowExistingDoc) {
+        return true;
+    }
+    return false;
+}
+function resolveAvailableSlug(index, db, base, options) {
+    if (!isValidSlug(base)) {
+        return { code: 'BAD_SLUG', message: `invalid slug: ${base}` };
+    }
+    const isFree = (slug) => !db.getActiveBySlug(slug) && !slugTaken(index, slug, options.allowExistingDoc);
+    if (isFree(base)) {
+        return base;
+    }
+    if (!options.autoSuffix) {
+        if (db.getActiveBySlug(base)) {
+            return {
+                code: 'DRAFT_EXISTS',
+                message: `active draft already exists for slug: ${base}`,
+            };
+        }
+        return {
+            code: 'SLUG_CONFLICT',
+            message: `published document already exists for slug: ${base}`,
+            hint: 'Use forked_from to edit an existing page, or omit slug to auto-assign a suffix.',
+        };
+    }
+    for (let suffix = 2; suffix <= 9; suffix += 1) {
+        const candidate = `${base}-${suffix}`;
+        if (isValidSlug(candidate) && isFree(candidate)) {
+            return candidate;
+        }
+    }
+    return {
+        code: 'WRITE_CONFLICT',
+        message: `could not allocate slug for base: ${base}`,
+        hint: 'All slug suffixes -2 through -9 are taken.',
+    };
+}
+export function createDraft(index, rawInput, cwd = process.cwd()) {
+    const gate = getAgentWriteGate(cwd);
+    if (!gate.enabled) {
+        return fail('AGENT_WRITE_DISABLED', gate.reason, 'Set REPOMIND_AGENT_WRITE=1 for local override.');
+    }
+    const knowledgeRoot = index.getKnowledgeRoot();
+    if (!knowledgeRoot) {
+        return fail('NO_KNOWLEDGE_ROOT', 'no docs/ knowledge root found');
+    }
+    const input = normalizeInput(rawInput);
+    const db = openDraftsDb(knowledgeRoot);
+    try {
+        if (input.forked_from) {
+            if (!isValidSlug(input.forked_from)) {
+                return fail('BAD_SLUG', `invalid forked_from slug: ${input.forked_from}`);
+            }
+            const existing = db.getActiveBySlug(input.forked_from);
+            if (existing) {
+                return fail('DRAFT_EXISTS', `active draft already exists for slug: ${input.forked_from}`);
+            }
+            const doc = getDoc(index, input.forked_from);
+            if (!doc.found || !doc.slug || !doc.frontmatter) {
+                return fail('DOC_NOT_FOUND', `document not found: ${input.forked_from}`);
+            }
+            const docRecord = index.getDocBySlug(input.forked_from);
+            try {
+                const draft = db.create({
+                    slug: doc.slug,
+                    type: doc.frontmatter.type,
+                    title: input.title || doc.frontmatter.title || doc.slug,
+                    body: input.body || doc.body || '',
+                    tags: (input.tags ?? []).length > 0 ? input.tags ?? [] : (doc.frontmatter.tags ?? []),
+                    related: (input.related ?? []).length > 0 ? input.related ?? [] : (doc.frontmatter.related ?? []),
+                    forked_from: doc.slug,
+                    target_path: docRecord?.relativePath ?? null,
+                });
+                return success(draft);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (message.includes('already exists')) {
+                    return fail('DRAFT_EXISTS', message);
+                }
+                throw error;
+            }
+        }
+        if (!input.title) {
+            return fail('BAD_TITLE', 'title is required');
+        }
+        if (!isDocType(input.type)) {
+            return fail('BAD_TYPE', `invalid type — expected one of: ${DOC_TYPES.join(', ')}`);
+        }
+        const baseSlug = input.slug ?? slugFromTitle(input.title);
+        const resolved = resolveAvailableSlug(index, db, baseSlug, {
+            autoSuffix: !input.slug,
+            allowExistingDoc: false,
+        });
+        if (typeof resolved !== 'string') {
+            return { ok: false, error: resolved };
+        }
+        try {
+            const draft = db.create({
+                slug: resolved,
+                type: input.type,
+                title: input.title,
+                body: input.body,
+                tags: input.tags,
+                related: input.related,
+            });
+            return success(draft);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('already exists')) {
+                return fail('DRAFT_EXISTS', message);
+            }
+            throw error;
+        }
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/ui/draft-api.js

@@ -2,7 +2,7 @@ import { runExport } from '../commands/export.js';
 import { isValidSlug } from '../index/slug.js';
 import { DOC_TYPES, isDocStatus, isDocType } from '../index/types.js';
 import { writeCatalogEmoji } from './catalog-meta.js';
-import { createFolder, createPageFile, deleteFolder, deletePageFile, movePageFile, renamePageFile } from './fs-operations.js';
+import { createFolder, createPageFile, deleteFolder, deletePageFile, moveFolder, movePageFile, promotePageToFolder, renamePageFile } from './fs-operations.js';
 import { prepareDocFile, prepareAllDocs } from '../prepare/prepare-docs.js';
 import { syncAllDocLinks } from '../prepare/auto-links.js';
 import { getDoc } from '../tools/get-doc.js';
@@ -102,6 +102,7 @@ export function handleDraftApi(index, db, method, pathname, bodyRaw) {
                 body: doc.body ?? '',
                 tags,
                 related,
+                forked_from: page.slug,
                 target_path: page.relativePath,
             });
             return { status: 201, body: { page, draft } };
@@ -111,6 +112,21 @@ export function handleDraftApi(index, db, method, pathname, bodyRaw) {
             return jsonError(400, message);
         }
     }
+    if (pathname === '/api/fs/promote-page' && method === 'POST') {
+        const body = parseJsonBody(bodyRaw);
+        if (body === null) {
+            return jsonError(400, 'invalid JSON body');
+        }
+        const pagePath = typeof body.pagePath === 'string' ? body.pagePath : '';
+        try {
+            const result = promotePageToFolder(index, pagePath);
+            return { status: 200, body: { result } };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return jsonError(400, message);
+        }
+    }
     if (pathname === '/api/fs/move' && method === 'POST') {
         const body = parseJsonBody(bodyRaw);
         if (body === null) {
@@ -127,6 +143,22 @@ export function handleDraftApi(index, db, method, pathname, bodyRaw) {
             return jsonError(400, message);
         }
     }
+    if (pathname === '/api/fs/move-folder' && method === 'POST') {
+        const body = parseJsonBody(bodyRaw);
+        if (body === null) {
+            return jsonError(400, 'invalid JSON body');
+        }
+        const fromPath = typeof body.fromPath === 'string' ? body.fromPath : '';
+        const toParentDir = typeof body.toParentDir === 'string' ? body.toParentDir : '';
+        try {
+            const result = moveFolder(index, fromPath, toParentDir);
+            return { status: 200, body: { result } };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return jsonError(400, message);
+        }
+    }
     if (pathname === '/api/fs/rename' && method === 'POST') {
         const body = parseJsonBody(bodyRaw);
         if (body === null) {

package/dist/ui/fs-operations.d.ts

@@ -44,9 +44,22 @@ export interface CreatePageOptions {
     title?: string;
     templateId?: string;
 }
+export interface PromotePageResult extends FsPageMutationResult {
+    folderPath: string;
+}
 export declare function createFolder(index: DocIndex, parentPath: string, name: string): CreateFolderResult;
 export declare function createPageFile(index: DocIndex, parentPath: string, name: string, options?: CreatePageOptions): CreatePageResult;
+/** Creates sibling folder `{parent}/{basename}/` for a leaf page (Confluence-style); page file stays in place. */
+export declare function promotePageToFolder(index: DocIndex, pagePath: string): PromotePageResult;
 export declare function movePageFile(index: DocIndex, fromPath: string, toDir: string): FsPageMutationResult;
 export declare function renamePageFile(index: DocIndex, pagePath: string, newName: string): FsPageMutationResult;
+export interface FsMoveFolderResult {
+    relativePath: string;
+    previousPath: string;
+    siblingPagePath?: string;
+    cascadeUpdated: string[];
+}
+/** Moves a folder and its Confluence sibling page file when present. */
+export declare function moveFolder(index: DocIndex, fromPath: string, toParentDir: string): FsMoveFolderResult;
 export declare function deletePageFile(index: DocIndex, pagePath: string): FsDeletePageResult;
 export declare function deleteFolder(index: DocIndex, folderPath: string): FsDeleteFolderResult;

package/dist/ui/fs-operations.js

@@ -115,6 +115,58 @@ function rewritePageFrontmatter(absolutePath, newRelativePath) {
     fs.writeFileSync(absolutePath, matter.stringify(parsed.content, nextData), 'utf8');
     return { newSlug, newType };
 }
+/** Creates sibling folder `{parent}/{basename}/` for a leaf page (Confluence-style); page file stays in place. */
+export function promotePageToFolder(index, pagePath) {
+    const knowledgeRoot = index.getKnowledgeRoot();
+    if (!knowledgeRoot) {
+        throw new Error('no docs/ directory found');
+    }
+    const normalizedFrom = normalizeRelativePath(pagePath);
+    if (normalizedFrom === 'README.md') {
+        throw new Error('cannot promote docs root index');
+    }
+    const fileName = path.posix.basename(normalizedFrom);
+    if (fileName.toLowerCase() === 'readme.md') {
+        throw new Error('page is already inside a folder');
+    }
+    const sourceAbsolute = resolveRelativeMdPath(knowledgeRoot, normalizedFrom);
+    if (!sourceAbsolute || !fs.existsSync(sourceAbsolute)) {
+        throw new Error(`page not found: ${pagePath}`);
+    }
+    const parentPath = parentRelativePath(normalizedFrom);
+    const baseName = knowledgeFileDisplayName(fileName);
+    if (!isValidFsName(baseName)) {
+        throw new Error(`invalid page name: ${baseName}`);
+    }
+    const folderRelative = joinRelativePath(parentPath, baseName);
+    const folderAbsolute = resolveUnderKnowledgeRoot(knowledgeRoot, folderRelative);
+    if (!folderAbsolute) {
+        throw new Error('path escapes docs/');
+    }
+    if (fs.existsSync(folderAbsolute)) {
+        if (!fs.statSync(folderAbsolute).isDirectory()) {
+            throw new Error(`already exists: ${folderRelative}`);
+        }
+    }
+    else {
+        fs.mkdirSync(folderAbsolute, { recursive: true });
+    }
+    const previousSlug = readPageSlug(sourceAbsolute);
+    index.refresh();
+    return {
+        relativePath: normalizedFrom,
+        absolutePath: sourceAbsolute,
+        slug: previousSlug,
+        previousSlug,
+        slugChanged: false,
+        inboundWarnings: [],
+        cascadeUpdated: [],
+        folderPath: normalizeRelativePath(folderRelative),
+    };
+}
+function knowledgeFileDisplayName(fileName) {
+    return fileName.replace(/\.(md|ya?ml|json)$/i, '');
+}
 export function movePageFile(index, fromPath, toDir) {
     const knowledgeRoot = index.getKnowledgeRoot();
     if (!knowledgeRoot) {
@@ -244,6 +296,93 @@ function mergeInboundWarnings(lists) {
     }
     return merged;
 }
+function isDescendantOrEqual(ancestor, candidate) {
+    const a = normalizeRelativePath(ancestor);
+    const c = normalizeRelativePath(candidate);
+    if (!a) {
+        return true;
+    }
+    return c === a || c.startsWith(`${a}/`);
+}
+function absoluteToDocsRelative(knowledgeRoot, absolutePath) {
+    return normalizeRelativePath(path.relative(knowledgeRoot, absolutePath));
+}
+/** Moves a folder and its Confluence sibling page file when present. */
+export function moveFolder(index, fromPath, toParentDir) {
+    const knowledgeRoot = index.getKnowledgeRoot();
+    if (!knowledgeRoot) {
+        throw new Error('no docs/ directory found');
+    }
+    const normalizedFrom = normalizeRelativePath(fromPath);
+    if (!normalizedFrom) {
+        throw new Error('cannot move docs root');
+    }
+    const sourceAbsolute = resolveUnderKnowledgeRoot(knowledgeRoot, normalizedFrom);
+    if (!sourceAbsolute || !fs.existsSync(sourceAbsolute)) {
+        throw new Error(`folder not found: ${fromPath}`);
+    }
+    if (!fs.statSync(sourceAbsolute).isDirectory()) {
+        throw new Error(`not a folder: ${fromPath}`);
+    }
+    const destParent = normalizeRelativePath(toParentDir);
+    if (isDescendantOrEqual(normalizedFrom, destParent)) {
+        throw new Error('cannot move folder into itself');
+    }
+    const folderName = path.posix.basename(normalizedFrom);
+    const destRelative = joinRelativePath(destParent, folderName);
+    const destAbsolute = resolveUnderKnowledgeRoot(knowledgeRoot, destRelative);
+    if (!destAbsolute) {
+        throw new Error('path escapes docs/');
+    }
+    if (fs.existsSync(destAbsolute)) {
+        throw new Error(`already exists: ${destRelative}`);
+    }
+    const fromParent = parentRelativePath(normalizedFrom);
+    const siblingRelative = joinRelativePath(fromParent, `${folderName}.md`);
+    const siblingAbsolute = resolveRelativeMdPath(knowledgeRoot, siblingRelative);
+    let siblingDestRelative;
+    if (siblingAbsolute && fs.existsSync(siblingAbsolute)) {
+        siblingDestRelative = joinRelativePath(destParent, `${folderName}.md`);
+        const siblingDestAbsolute = resolveRelativeMdPath(knowledgeRoot, siblingDestRelative);
+        if (!siblingDestAbsolute) {
+            throw new Error('path escapes docs/');
+        }
+        if (fs.existsSync(siblingDestAbsolute)) {
+            throw new Error(`already exists: ${siblingDestRelative}`);
+        }
+        fs.renameSync(siblingAbsolute, siblingDestAbsolute);
+    }
+    fs.renameSync(sourceAbsolute, destAbsolute);
+    const movedMarkdownAbsolutes = [];
+    if (siblingDestRelative) {
+        const siblingDestAbsolute = resolveRelativeMdPath(knowledgeRoot, siblingDestRelative);
+        if (siblingDestAbsolute) {
+            movedMarkdownAbsolutes.push(siblingDestAbsolute);
+        }
+    }
+    movedMarkdownAbsolutes.push(...listMarkdownFilesRecursive(destAbsolute));
+    const cascadeUpdated = new Set();
+    for (const absolutePath of movedMarkdownAbsolutes) {
+        const relativePath = absoluteToDocsRelative(knowledgeRoot, absolutePath);
+        const previousSlug = readPageSlug(absolutePath);
+        const { newSlug } = rewritePageFrontmatter(absolutePath, relativePath);
+        if (newSlug === previousSlug) {
+            continue;
+        }
+        for (const updatedPath of cascadeSlugRename(knowledgeRoot, previousSlug, newSlug, {
+            excludeAbsolutePath: absolutePath,
+        })) {
+            cascadeUpdated.add(updatedPath);
+        }
+    }
+    index.refresh();
+    return {
+        relativePath: destRelative,
+        previousPath: normalizedFrom,
+        siblingPagePath: siblingDestRelative,
+        cascadeUpdated: toRelativePaths(knowledgeRoot, [...cascadeUpdated]),
+    };
+}
 export function deletePageFile(index, pagePath) {
     const knowledgeRoot = index.getKnowledgeRoot();
     if (!knowledgeRoot) {