dsh-plugin-wiki-tools 0.6.0 → 0.8.0

package/index.js

@@ -16,6 +16,7 @@ import z from '@deepseek-ai/schemastery'
 import { Vault } from './lib/vault.js'
 import { quickView, searchVault } from './lib/search.js'
 import { lintVault } from './lib/lint.js'
+import { scaffoldVault, SCAFFOLD_MODES } from './lib/scaffold.js'
 
 export const name = 'wiki-tools'
 export const inject = ['tools']
@@ -38,8 +39,8 @@ export const Config = z.object({
   }).default({}),
 })
 
-const PAGE_TYPES = ['source', 'entity', 'concept', 'domain', 'question', 'comparison', 'meta']
-const STATUSES = ['seed', 'developing', 'solid']
+const PAGE_TYPES = ['source', 'entity', 'concept', 'domain', 'question', 'synthesis', 'comparison', 'decision', 'session', 'meta']
+const STATUSES = ['seed', 'developing', 'mature', 'evergreen']
 
 /**
  * Build the three wiki tool definitions over one vault. Exported for tests.
@@ -125,12 +126,22 @@ export function createTools(vault, options = {}) {
       status: {
         type: 'string',
         enum: STATUSES,
-        description: 'Frontmatter status; defaults to developing (kept on update).',
+        description: 'Frontmatter status (seed | developing | mature | evergreen); defaults to developing (kept on update).',
       },
       summary: {
         type: 'string',
         description: 'One-line master-index entry; defaults to the first content line.',
       },
+      extra_frontmatter: {
+        type: 'object',
+        additionalProperties: true,
+        description:
+          'Flat schema fields to merge into frontmatter, e.g. related, sources, question, answer_quality '
+          + '(question/synthesis), entity_type/role (entity), complexity/domain/aliases (concept), '
+          + 'source_type/author/url/key_claims (source), subjects/dimensions/verdict (comparison), '
+          + 'decision_date (decision). Values are scalars or scalar lists; nesting is forbidden; '
+          + 'managed fields (type/title/status/created/updated/tags) are rejected.',
+      },
       source_path: {
         type: 'string',
         description: 'Vault-relative .raw/ source this page derives from, for delta tracking.',
@@ -162,11 +173,90 @@ export function createTools(vault, options = {}) {
           return { alreadyIngested: true, hash: tracked.hash, title: args.title }
         }
       }
-      return await vault.writePage(args)
+      const { extra_frontmatter: extraFrontmatter, ...rest } = args
+      return await vault.writePage({ ...rest, extraFrontmatter })
     },
     presentCall: args => ({ card: 'generic', title: `Write wiki page: ${args.title}`, kind: 'other', rawInput: { title: args.title, type: args.type } }),
   })
 
+  const wikiRename = defineTool({
+    name: 'wiki_rename',
+    description:
+      'Rename one wiki page and rewrite every [[wikilink]] to it across the vault (aliases and heading '
+      + 'anchors preserved), move the file to the new title, retitle its frontmatter, swap its master-index '
+      + 'and folder _index entries, and log the rename. The append-only log and dated lint reports keep the '
+      + 'old name as history. Use this instead of manual file renames, which strand every inbound link.',
+    parameters: {
+      title: {
+        type: 'string',
+        required: true,
+        description: 'Exact current page title.',
+      },
+      new_title: {
+        type: 'string',
+        required: true,
+        description: 'New title; also the new filename and [[wikilink]] target. Title Case with spaces.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: typeof value === 'object' && value !== null && 'to' in value
+          ? `wiki_rename: [[${value.from}]] → [[${value.to}]]; rewrote links in ${value.linksRewritten} files; page at ${value.path}`
+          : 'wiki_rename: failed',
+      }],
+    },
+    async execute(args) {
+      return await vault.renamePage({ title: args.title, newTitle: args.new_title })
+    },
+    presentCall: args => ({ card: 'generic', title: `Rename wiki page: ${args.title} → ${args.new_title}`, kind: 'other', rawInput: { from: args.title, to: args.new_title } }),
+  })
+
+  const wikiScaffold = defineTool({
+    name: 'wiki_scaffold',
+    description:
+      'Scaffold a wiki vault in one call: the chosen mode\u2019s folder structure with per-folder _index.md, '
+      + 'the core files (wiki/index.md, log.md, hot.md, overview.md), the mode\u2019s key seed pages, a raw-source '
+      + 'manifest, and the vault AGENTS.md conventions file. Idempotent — existing files are kept. Modes: '
+      + 'generic (matches wiki_write routing), sitemap, repository, business, personal, research, book. '
+      + 'The result carries a suggested typeFolders config for non-generic modes to paste into the profile.',
+    parameters: {
+      mode: {
+        type: 'string',
+        required: true,
+        enum: Object.keys(SCAFFOLD_MODES),
+        description: 'Scaffold mode; pick by what the vault is for (generic for a general knowledge base).',
+      },
+      purpose: {
+        type: 'string',
+        description: 'One-line vault purpose, written into overview.md and AGENTS.md.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: typeof value === 'object' && value !== null && 'created' in value
+          ? `wiki_scaffold (${value.mode}): created ${value.created.length} files, skipped ${value.skipped.length} existing`
+            + (Object.keys(value.suggestedTypeFolders ?? {}).length > 0
+              ? `; suggested typeFolders: ${JSON.stringify(value.suggestedTypeFolders)}`
+              : '')
+          : 'wiki_scaffold: failed',
+      }],
+    },
+    async execute(args) {
+      return await scaffoldVault(vault.root, args)
+    },
+    presentCall: args => ({ card: 'generic', title: `Scaffold wiki vault (${args.mode})`, kind: 'other', rawInput: { mode: args.mode } }),
+  })
+
   const wikiLint = defineTool({
     name: 'wiki_lint',
     description:
@@ -190,7 +280,7 @@ export function createTools(vault, options = {}) {
     presentCall: () => ({ card: 'generic', title: 'Lint wiki vault', kind: 'other' }),
   })
 
-  return [wikiQuery, wikiWrite, wikiLint]
+  return [wikiQuery, wikiWrite, wikiRename, wikiScaffold, wikiLint]
 }
 
 /**

package/lib/scaffold.js

@@ -0,0 +1,235 @@
+/**
+ * Vault scaffolding: the mechanical half of the wiki skill's SCAFFOLD
+ * operation as one call. Creates the mode's folder structure, the core wiki
+ * files (index, log, hot cache, overview), per-folder sub-indexes, the mode's
+ * key seed pages, the vault AGENTS.md conventions file, and the raw-source
+ * manifest. Idempotent: existing files are kept and reported as skipped.
+ *
+ * @module dsh-plugin-wiki-tools/lib/scaffold
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { today } from './vault.js'
+
+/**
+ * Folder sets per scaffold mode. `generic` matches the wiki_write routing
+ * (TYPE_FOLDERS); the six named modes follow the wiki skill's modes reference.
+ * `stubFolder` holds the mode's overview page; `stubs` are the key pages the
+ * mode's reference lists, each seeded into the folder named alongside it.
+ */
+export const SCAFFOLD_MODES = {
+  generic: {
+    label: 'Generic knowledge base',
+    folders: ['wiki/sources', 'wiki/entities', 'wiki/concepts', 'wiki/domains', 'wiki/questions', 'wiki/comparisons', 'wiki/meta'],
+    stubs: [],
+    typeFolders: {},
+  },
+  sitemap: {
+    label: 'Website / sitemap',
+    folders: ['wiki/pages', 'wiki/structure', 'wiki/audits', 'wiki/keywords', 'wiki/entities'],
+    stubs: [
+      { title: 'Site Overview', folder: 'wiki/structure', type: 'page' },
+      { title: 'Navigation Structure', folder: 'wiki/structure', type: 'page' },
+      { title: 'Content Gaps', folder: 'wiki/audits', type: 'page' },
+      { title: 'Redirect Map', folder: 'wiki/audits', type: 'page' },
+      { title: 'Keyword Clusters', folder: 'wiki/keywords', type: 'page' },
+    ],
+    typeFolders: { source: 'wiki/pages', entity: 'wiki/entities' },
+  },
+  repository: {
+    label: 'GitHub / repository',
+    folders: ['wiki/modules', 'wiki/components', 'wiki/decisions', 'wiki/dependencies', 'wiki/flows'],
+    stubs: [
+      { title: 'Architecture Overview', folder: 'wiki/modules', type: 'module' },
+      { title: 'Data Flow', folder: 'wiki/flows', type: 'flow' },
+      { title: 'Tech Stack', folder: 'wiki/dependencies', type: 'dependency' },
+      { title: 'Dependency Graph', folder: 'wiki/dependencies', type: 'dependency' },
+      { title: 'Key Decisions', folder: 'wiki/decisions', type: 'decision' },
+    ],
+    typeFolders: { source: 'wiki/modules', comparison: 'wiki/decisions' },
+  },
+  business: {
+    label: 'Business / project',
+    folders: ['wiki/stakeholders', 'wiki/decisions', 'wiki/deliverables', 'wiki/intel', 'wiki/comms'],
+    stubs: [
+      { title: 'Project Overview', folder: 'wiki/deliverables', type: 'deliverable' },
+      { title: 'Stakeholder Map', folder: 'wiki/stakeholders', type: 'stakeholder' },
+      { title: 'Decision Log', folder: 'wiki/decisions', type: 'decision' },
+      { title: 'Competitor Landscape', folder: 'wiki/intel', type: 'competitor' },
+    ],
+    typeFolders: { entity: 'wiki/stakeholders', source: 'wiki/comms', decision: 'wiki/decisions' },
+  },
+  personal: {
+    label: 'Personal / second brain',
+    folders: ['wiki/goals', 'wiki/learning', 'wiki/people', 'wiki/areas', 'wiki/resources'],
+    stubs: [
+      { title: 'North Star', folder: 'wiki/goals', type: 'goal' },
+      { title: 'Annual Goals', folder: 'wiki/goals', type: 'goal' },
+    ],
+    typeFolders: { concept: 'wiki/learning', domain: 'wiki/areas', entity: 'wiki/people', source: 'wiki/resources' },
+  },
+  research: {
+    label: 'Research',
+    folders: ['wiki/papers', 'wiki/concepts', 'wiki/entities', 'wiki/thesis', 'wiki/gaps'],
+    stubs: [
+      { title: 'Research Overview', folder: 'wiki/thesis', type: 'thesis' },
+      { title: 'Open Questions', folder: 'wiki/gaps', type: 'gap' },
+    ],
+    typeFolders: { source: 'wiki/papers', question: 'wiki/gaps', concept: 'wiki/concepts' },
+  },
+  book: {
+    label: 'Book / course',
+    folders: ['wiki/characters', 'wiki/themes', 'wiki/concepts', 'wiki/timeline', 'wiki/synthesis'],
+    stubs: [
+      { title: 'Book Overview', folder: 'wiki/timeline', type: 'chapter' },
+      { title: 'My Takeaways', folder: 'wiki/synthesis', type: 'synthesis' },
+    ],
+    typeFolders: { concept: 'wiki/concepts', question: 'wiki/synthesis' },
+  },
+}
+
+/**
+ * Scaffold one vault for a mode. Every artifact is written only when absent,
+ * so re-running after a partial scaffold or over an existing vault is safe.
+ * @param {string} root - absolute vault root.
+ * @param {object} input - scaffold options.
+ * @param {keyof typeof SCAFFOLD_MODES} input.mode - scaffold mode.
+ * @param {string} [input.purpose] - one-line vault purpose for overview and AGENTS.md.
+ * @returns {Promise<{ mode: string, created: string[], skipped: string[], suggestedTypeFolders: Record<string, string> }>}
+ */
+export async function scaffoldVault(root, { mode, purpose }) {
+  const spec = SCAFFOLD_MODES[mode]
+  if (spec === undefined) {
+    throw new Error(`wiki-tools: unknown scaffold mode "${mode}"; choose one of ${Object.keys(SCAFFOLD_MODES).join(', ')}`)
+  }
+  const date = today()
+  const created = []
+  const skipped = []
+  const writeIfAbsent = async (relPath, content) => {
+    const path = join(root, relPath)
+    if (await readFile(path, 'utf8').then(() => true, () => false)) {
+      skipped.push(relPath)
+      return
+    }
+    await mkdir(join(path, '..'), { recursive: true })
+    await writeFile(path, content, 'utf8')
+    created.push(relPath)
+  }
+
+  await writeIfAbsent('.raw/.manifest.json', '{"sources":{}}\n')
+  for (const folder of spec.folders) {
+    await writeIfAbsent(`${folder}/_index.md`, [
+      '---',
+      'type: meta',
+      `title: "${folder.split('/').pop()} Index"`,
+      `updated: ${date}`,
+      '---',
+      '',
+      `# ${folder.split('/').pop()}`,
+      '',
+    ].join('\n'))
+  }
+
+  await writeIfAbsent('wiki/index.md', indexTemplate(date))
+  await writeIfAbsent('wiki/log.md', `# Wiki Log\n`)
+  await writeIfAbsent('wiki/hot.md', [
+    '---',
+    'type: meta',
+    'title: "Hot Cache"',
+    `updated: ${date}`,
+    '---',
+    '',
+    '# Recent Context',
+    '',
+    `Scaffolded ${date}. ${purpose ?? spec.label}.`,
+    '',
+  ].join('\n'))
+  await writeIfAbsent('wiki/overview.md', [
+    '---',
+    'type: overview',
+    `title: "Overview"`,
+    `updated: ${date}`,
+    '---',
+    '',
+    '# Overview',
+    '',
+    purpose ?? spec.label,
+    '',
+  ].join('\n'))
+
+  for (const stub of spec.stubs) {
+    await writeIfAbsent(`${stub.folder}/${stub.title}.md`, [
+      '---',
+      `type: ${stub.type}`,
+      `title: "${stub.title}"`,
+      'status: seed',
+      `created: ${date}`,
+      `updated: ${date}`,
+      'tags:',
+      `  - ${stub.type}`,
+      '---',
+      '',
+      `# ${stub.title}`,
+      '',
+      `Seed page from ${mode} scaffold. Fill in.`,
+      '',
+    ].join('\n'))
+  }
+
+  await writeIfAbsent('AGENTS.md', agentsTemplate(mode, spec.label, purpose, date))
+
+  return { mode, created, skipped, suggestedTypeFolders: spec.typeFolders }
+}
+
+/**
+ * Master-index template with one empty section per generic type, in catalog
+ * order; named-mode vaults keep the same sections for their mapped types.
+ * @param {string} date - scaffold date.
+ * @returns {string} the index file content.
+ */
+function indexTemplate(date) {
+  const sections = ['Entities', 'Concepts', 'Sources', 'Questions']
+  return [
+    '---',
+    'type: meta',
+    'title: "Wiki Index"',
+    `updated: ${date}`,
+    '---',
+    '',
+    '# Wiki Index',
+    '',
+    ...sections.flatMap(section => [`## ${section}`, '']),
+  ].join('\n')
+}
+
+/**
+ * Vault conventions file: the rules every contributing agent follows.
+ * @param {string} mode - scaffold mode id.
+ * @param {string} label - human-readable mode label.
+ * @param {string | undefined} purpose - one-line vault purpose.
+ * @param {string} date - scaffold date.
+ * @returns {string} the AGENTS.md content.
+ */
+function agentsTemplate(mode, label, purpose, date) {
+  return `# Wiki Vault Conventions
+
+Mode: ${mode} (${label})
+Purpose: ${purpose ?? '(fill in)'}
+Created: ${date}
+
+## Rules
+
+- Every page uses flat YAML frontmatter: type, title, status, created, updated, tags at minimum.
+- status is one of seed | developing | mature | evergreen.
+- Wikilinks use [[Note Name]]; filenames are unique across the vault, no paths needed.
+- .raw/ holds immutable sources; never modify them.
+- wiki/index.md is the master catalog; every page is listed in its section.
+- wiki/log.md is append-only; new entries go at the TOP; never edit past entries.
+- wiki/hot.md is a ~500-word cache of recent context; overwrite it completely each update.
+- Prefer the wiki tools (wiki_query, wiki_write, wiki_rename, wiki_lint) over raw file edits;
+  they keep frontmatter, the index, the folder _index.md files, and the log consistent.
+- Contradictions between pages get > [!contradiction] callouts on both pages, never silent edits.
+`
+}

package/lib/vault.js

@@ -12,8 +12,8 @@
  */
 
 import { createHash } from 'node:crypto'
-import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises'
-import { basename, isAbsolute, join, relative, sep } from 'node:path'
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 
 /** Page-type to vault folder routing (the suite's generic mode). */
@@ -24,6 +24,9 @@ export const TYPE_FOLDERS = {
   domain: 'wiki/domains',
   question: 'wiki/questions',
   comparison: 'wiki/comparisons',
+  synthesis: 'wiki/questions',
+  decision: 'wiki/meta',
+  session: 'wiki/meta',
   meta: 'wiki/meta',
 }
 
@@ -158,25 +161,29 @@ export class Vault {
 
   /**
    * Write one wiki page with complete bookkeeping: frontmatter completion,
-   * filename-uniqueness guard, master-index entry, and a log entry. Existing
-   * pages keep `created` and any unknown frontmatter fields; `updated` moves
-   * to today.
+   * filename-uniqueness guard, master-index entry, folder `_index.md` entry,
+   * and a log entry. Existing pages keep `created` and any unknown frontmatter
+   * fields; `updated` moves to today.
    * @param {object} input - the write request.
    * @param {string} input.type - page type (routed to a folder).
    * @param {string} input.title - page title; also the filename and wikilink target.
    * @param {string} input.content - markdown body after frontmatter.
    * @param {string[]} [input.tags] - frontmatter tags; defaults to `[type]`.
-   * @param {string} [input.status] - frontmatter status; defaults to `developing` on create.
+   * @param {string} [input.status] - frontmatter status; one of seed/developing/mature/evergreen.
    * @param {string} [input.summary] - one-line index entry; defaults to the first content line.
+   * @param {Record<string, unknown>} [input.extraFrontmatter] - flat schema fields to merge
+   *   (related, sources, question, answer_quality, entity_type, aliases, …); must stay flat and
+   *   cannot override the managed fields.
    * @returns {Promise<{ path: string, created: boolean, title: string }>}
    */
-  async writePage({ type, title, content, tags, status, summary }) {
+  async writePage({ type, title, content, tags, status, summary, extraFrontmatter }) {
     const path = this.pagePath(type, title)
     return await this.enqueue(path, async () => {
       await this.assertRoot()
       const cleanTitle = title.endsWith('.md') ? title.slice(0, -3) : title
       const existing = await this.readPage(path)
       await this.assertUniqueFilename(cleanTitle, path)
+      validateExtraFrontmatter(extraFrontmatter)
       const date = today()
       const fields = {
         ...(existing?.fields ?? {}),
@@ -186,11 +193,13 @@ export class Vault {
         created: existing?.fields?.created ?? date,
         updated: date,
         tags: tags ?? existing?.fields?.tags ?? [type],
+        ...(extraFrontmatter ?? {}),
       }
       const file = `---\n${stringifyYaml(fields).trimEnd()}\n---\n\n${content.replace(/^\s*\n/, '')}\n`
       await mkdir(join(path, '..'), { recursive: true })
       await writeFile(path, file, 'utf8')
       await this.updateIndex(type, cleanTitle, summary ?? firstContentLine(content))
+      await this.updateFolderIndex(type, cleanTitle, summary ?? firstContentLine(content))
       await this.prependLog(`## [${date}] ${existing === undefined ? 'create' : 'update'} | ${cleanTitle}`, [
         `- ${existing === undefined ? 'Created' : 'Updated'}: [[${cleanTitle}]]`,
       ])
@@ -198,6 +207,119 @@ export class Vault {
     })
   }
 
+  /**
+   * Add or refresh one entry in the owning folder's `_index.md` sub-index, the
+   * wiki-ingest contract's per-folder catalog. Missing files are created with
+   * a single `## <Type>` section; existing entries are replaced in place in
+   * the section's dominant separator style.
+   * @param {string} type - page type selecting folder and section label.
+   * @param {string} title - page title.
+   * @param {string} summary - one-line description.
+   */
+  async updateFolderIndex(type, title, summary) {
+    const folder = this.typeFolders[type]
+    const indexPath = join(this.root, folder, '_index.md')
+    const entryPattern = new RegExp(`^\\s*-?\\s*\\[\\[${escapeRegExp(title)}\\]\\]`)
+    let raw = await readFile(indexPath, 'utf8').catch(() => undefined)
+    if (raw === undefined) {
+      const heading = `## ${capitalize(type)}s`
+      const file = `---\ntype: meta\ntitle: "${capitalize(basename(folder))} Index"\nupdated: ${today()}\n---\n\n${heading}\n\n- [[${title}]]: ${summary.replace(/\n/g, ' ')}\n`
+      await writeFile(indexPath, file, 'utf8')
+      return
+    }
+    const lines = raw.split('\n')
+    const at = lines.findIndex(line => entryPattern.test(line))
+    const entry = `- [[${title}]]: ${summary.replace(/\n/g, ' ')}`
+    if (at >= 0) {
+      lines[at] = entry
+    } else {
+      let insert = lines.length
+      while (insert > 0 && lines[insert - 1].trim() === '') insert -= 1
+      lines.splice(insert, 0, entry)
+    }
+    const updatedLine = lines.findIndex(line => /^updated: /.test(line))
+    if (updatedLine >= 0) lines[updatedLine] = `updated: ${today()}`
+    await writeFile(indexPath, `${lines.join('\n')}\n`, 'utf8')
+  }
+
+  /**
+   * Rename one page and rewrite every wikilink to it across the vault:
+   * `[[Old]]` → `[[New]]`, preserving aliases (`[[Old|x]]` → `[[New|x]]`) and
+   * heading anchors. The append-only log and dated lint reports are historical
+   * records and keep the old name; frontmatter aliases keep resolving.
+   * @param {object} input - the rename request.
+   * @param {string} input.title - exact current page title.
+   * @param {string} input.newTitle - the new title and filename.
+   * @returns {Promise<{ from: string, to: string, path: string, linksRewritten: number, filesRewritten: string[] }>}
+   */
+  async renamePage({ title, newTitle }) {
+    return await this.enqueue(join(this.root, 'wiki'), async () => {
+      await this.assertRoot()
+      const cleanNew = newTitle.endsWith('.md') ? newTitle.slice(0, -3) : newTitle
+      if (!/^[^/\\]+(\.md)?$/.test(newTitle) || newTitle.includes('\n')) {
+        throw new Error(`wiki-tools: newTitle must be a plain filename without path separators (got ${JSON.stringify(newTitle)})`)
+      }
+      if (cleanNew === title) throw new Error('wiki-tools: newTitle equals the current title')
+      const pages = await collectMarkdown(join(this.root, 'wiki'))
+      const target = pages.find(page => page.name === title)
+      if (target === undefined) throw new Error(`wiki-tools: no page named "${title}" exists in the vault`)
+      if (pages.some(page => page.name !== title && page.name.toLowerCase() === cleanNew.toLowerCase())) {
+        throw new Error(`wiki-tools: filename "${cleanNew}.md" already exists; wikilinks need unique filenames`)
+      }
+      const type = typeof target.fields?.type === 'string' && target.fields.type in this.typeFolders
+        ? target.fields.type
+        : 'meta'
+
+      // 1. Rewrite links everywhere except immutable records.
+      const rewritten = []
+      for (const page of pages) {
+        if (page.name === title || page.name.toLowerCase() === 'log' || /^lint-report-/.test(page.name)) continue
+        const raw = await readFile(page.path, 'utf8').catch(() => undefined)
+        if (raw === undefined) continue
+        const pattern = new RegExp(`\\[\\[${escapeRegExp(title)}(\]\]|\||#)`, 'g')
+        const updated = raw.replace(pattern, `[[${cleanNew}$1`)
+        if (updated !== raw) {
+          await writeFile(page.path, updated, 'utf8')
+          rewritten.push(page.name)
+        }
+      }
+
+      // 2. Move the page and retitle its frontmatter.
+      const newPath = this.pagePath(type, cleanNew)
+      const oldRaw = await readFile(target.path, 'utf8')
+      const retitled = oldRaw.replace(/^(title:.*)$/m, `title: ${cleanNew}`)
+      await mkdir(dirname(newPath), { recursive: true })
+      await writeFile(newPath, retitled, 'utf8')
+      if (newPath !== target.path) await rm(target.path)
+
+      // 3. Swap index entries: drop the old lines, add the new.
+      await this.removeIndexEntries(title)
+      const summary = firstContentLine(splitFrontmatter(retitled, newPath).content)
+      await this.updateIndex(type, cleanNew, summary)
+      await this.updateFolderIndex(type, cleanNew, summary)
+      await this.prependLog(`## [${today()}] rename | ${title}`, [
+        `- Renamed: [[${title}]] → [[${cleanNew}]] (${rewritten.length} files' links rewritten)`,
+      ])
+      return { from: title, to: cleanNew, path: newPath, linksRewritten: rewritten.length, filesRewritten: rewritten }
+    })
+  }
+
+  /**
+   * Remove one page's entry lines from the master index and its folder
+   * `_index.md`, used when a rename replaces rather than refreshes.
+   * @param {string} title - page title whose entries are removed.
+   */
+  async removeIndexEntries(title) {
+    const pattern = new RegExp(`^\\s*-?\\s*\\[\\[${escapeRegExp(title)}\\]\\]`)
+    for (const indexPath of [join(this.root, 'wiki', 'index.md'), ...Object.values(this.typeFolders).map(folder => join(this.root, folder, '_index.md'))]) {
+      const raw = await readFile(indexPath, 'utf8').catch(() => undefined)
+      if (raw === undefined) continue
+      const lines = raw.split('\n')
+      const filtered = lines.filter(line => !pattern.test(line))
+      if (filtered.length !== lines.length) await writeFile(indexPath, `${filtered.join('\n')}\n`, 'utf8')
+    }
+  }
+
   /**
    * Reject a title whose filename already exists elsewhere in the tree:
    * wikilinks address pages by bare filename, so duplicates break resolution.
@@ -325,6 +447,33 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 
+/** Frontmatter fields writePage manages itself; extraFrontmatter cannot override them. */
+const MANAGED_FIELDS = new Set(['type', 'title', 'status', 'created', 'updated', 'tags'])
+
+/**
+ * Validate caller-supplied schema fields: flat mapping of primitives or lists
+ * of primitives (the vault schema forbids nesting for Obsidian's Properties UI).
+ * @param {Record<string, unknown> | undefined} extra - the extraFrontmatter input.
+ * @returns {void} throws on any violation.
+ */
+function validateExtraFrontmatter(extra) {
+  if (extra === undefined) return
+  if (typeof extra !== 'object' || extra === null || Array.isArray(extra)) {
+    throw new Error('wiki-tools: extraFrontmatter must be a flat object of schema fields')
+  }
+  for (const [key, value] of Object.entries(extra)) {
+    if (MANAGED_FIELDS.has(key)) {
+      throw new Error(`wiki-tools: extraFrontmatter cannot override managed field "${key}"`)
+    }
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      throw new Error(`wiki-tools: extraFrontmatter must stay flat; "${key}" is an object (the schema forbids nesting)`)
+    }
+    if (Array.isArray(value) && value.some(item => item !== null && typeof item === 'object')) {
+      throw new Error(`wiki-tools: extraFrontmatter list "${key}" may hold only scalars`)
+    }
+  }
+}
+
 /**
  * Pick the index separator for one entry: reuse the matched line's style, else
  * the section's dominant style (`: ` or ` — `), else the canonical colon.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wiki-tools",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Native DeepSeek Harness tools for an Obsidian wiki vault: wiki_query, wiki_write, and wiki_lint implement the mechanical core (path routing, delta tracking, index/log bookkeeping, health checks) of the wiki skill suite.",
   "license": "MIT",
   "type": "module",