dsh-plugin-wiki-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lion
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# dsh-plugin-wiki-tools
+
+English | [中文](#中文)
+
+Native [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) tools for an Obsidian wiki vault: `wiki_query`, `wiki_write`, and `wiki_lint` implement the mechanical core of the wiki skill suite — path routing, frontmatter completion, index/log bookkeeping, source delta tracking, and health checks — so the model spends its turns on synthesis instead of filesystem chores.
+
+Pair with **[dsh-plugin-wiki-skills](https://github.com/Lion-1209/dsh-plugin-wiki-skills)** for the prompt-level skills (`wiki`, `wiki-ingest`, `wiki-query`, `wiki-lint`, `save`).
+
+## Attribution
+
+The vault layout and operation contracts follow the LLM Wiki pattern (Andrej Karpathy) as embodied by [claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian) (MIT, © 2026 AgriciDaniel). This package is an independent plain-ESM implementation of the mechanical core; it contains no code or skill text from claude-obsidian.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `wiki_query` | Quick mode returns `hot.md` + `index.md` verbatim (the skill's read order); standard mode is full-text search over content pages with snippets and the inbound/outbound link graph |
+| `wiki_write` | Writes one page with complete bookkeeping: type→folder routing, frontmatter completion (keeps `created` and unknown fields on update), filename-uniqueness guard, master-index entry, log entry; with `source_path`, records the source hash and skips unchanged sources unless `force` |
+| `wiki_lint` | Health check: duplicate filenames, dead wikilinks, orphan pages, frontmatter gaps, empty sections, stale index entries, stale hot cache — report only, with suggestions, written to `wiki/meta/lint-report-<date>.md` |
+
+## Install and configure
+
+```sh
+dsh plugin --profile web add dsh-plugin-wiki-tools
+```
+
+`vaultPath` is **required**. The boot fails loud until you set it from your profile's `cordis.patch.yml`:
+
+```yaml
+- id: wiki-tools
+  config:
+    vaultPath: /absolute/path/to/vault
+```
+
+The vault is the directory holding `wiki/` and `.raw/` — scaffold it first with the `wiki` skill's SCAFFOLD operation. `maxQueryResults` (default 10) is optional.
+
+## Design notes
+
+- The vault is host-local user data outside any session workspace (cross-project referencing is the point), so the tools read and write through `node:fs` against the explicitly configured absolute root — not a dsh filesystem seam.
+- Writes serialize per target file in-process; filenames are guarded unique vault-wide because wikilinks resolve by bare name.
+- Registers on `ctx.tools` via `defineTool`; schemas stay stable regardless of vault contents.
+
+## Develop
+
+```sh
+npm install
+node --test
+```
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+# 中文
+
+Obsidian wiki vault 的 DeepSeek Harness 原生工具：`wiki_query`、`wiki_write`、`wiki_lint` 实现知识库技能套件的机械核心（路径路由、frontmatter 补全、索引/日志簿记、来源增量追踪、健康检查），让模型把轮次花在综合而非文件操作上。与 [dsh-plugin-wiki-skills](https://github.com/Lion-1209/dsh-plugin-wiki-skills) 配套使用。
+
+## 出处
+
+vault 布局与操作契约遵循 LLM Wiki 模式（Karpathy），形态来自 claude-obsidian（AgriciDaniel，MIT）。本包为独立的纯 ESM 实现，不含 claude-obsidian 的代码或技能文本。
+
+## 安装与配置
+
+```sh
+dsh plugin --profile web add dsh-plugin-wiki-tools
+```
+
+`vaultPath` 为必填项：在你的 profile `cordis.patch.yml` 里覆盖 `wiki-tools` 行的 config 指向 vault 根目录（含 `wiki/` 与 `.raw/`，先用 wiki 技能的 SCAFFOLD 操作搭建），否则启动时会明确报错并给出示例。

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# The dsh-plugin-wiki-tools bundle patch: one insert over the profile root.
+# vaultPath is REQUIRED: replace this row's config from your own profile
+# cordis.patch.yml, e.g.
+#
+#   - id: wiki-tools
+#     config:
+#       vaultPath: /absolute/path/to/vault
+#
+# A boot without vaultPath fails loud with these instructions.
+
+- insert:
+    - id: wiki-tools
+      name: 'dsh-plugin-wiki-tools'

package/index.js

@@ -0,0 +1,209 @@
+/**
+ * Wiki Tools — native DeepSeek Harness tools over an Obsidian wiki vault.
+ *
+ * Registers `wiki_query`, `wiki_write`, and `wiki_lint` on `ctx.tools`,
+ * implementing the mechanical core of the wiki skill suite (path routing,
+ * frontmatter completion, index/log bookkeeping, source delta tracking, and
+ * health checks) so the model spends its turns on synthesis instead of
+ * filesystem chores. Vault design follows the LLM Wiki pattern; see
+ * dsh-plugin-wiki-skills for the skill half.
+ *
+ * @module dsh-plugin-wiki-tools
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+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'
+
+export const name = 'wiki-tools'
+export const inject = ['tools']
+
+/** Tool-plugin configuration. */
+export const Config = z.object({
+  /** Absolute path to the vault root: the directory holding `wiki/` and `.raw/`. */
+  vaultPath: z.string().required(),
+  /** Maximum pages returned by one wiki_query standard-mode call. */
+  maxQueryResults: z.number().default(10),
+})
+
+const PAGE_TYPES = ['source', 'entity', 'concept', 'domain', 'question', 'comparison', 'meta']
+const STATUSES = ['seed', 'developing', 'solid']
+
+/**
+ * Build the three wiki tool definitions over one vault. Exported for tests.
+ * @param {Vault} vault - the configured vault.
+ * @param {{ maxQueryResults?: number }} [options] - tool options.
+ * @returns {import('@deepseek-ai/dsh-tools').ToolDefinition[]}
+ */
+export function createTools(vault, options = {}) {
+  const limit = options.maxQueryResults ?? 10
+
+  const wikiQuery = defineTool({
+    name: 'wiki_query',
+    description:
+      'Search the knowledge vault. Quick mode returns the hot cache and master index verbatim — '
+      + 'read those before opening any page. Standard mode runs full-text search over every wiki page '
+      + 'and returns ranked matches with snippets, inbound links, and outbound link counts. '
+      + 'Use standard mode when quick context is not enough.',
+    parameters: {
+      query: {
+        type: 'string',
+        required: true,
+        description: 'The search text or question topic.',
+      },
+      mode: {
+        type: 'string',
+        enum: ['quick', 'standard'],
+        description: 'quick returns hot.md + index.md only (~1500 tokens); standard searches all pages. Defaults to standard.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: typeof value === 'object' && value !== null && 'results' in value
+          ? `wiki_query: ${value.results.length} of ${value.totalMatches} matching pages`
+          : 'wiki_query: returned hot cache and master index',
+      }],
+    },
+    async execute(args) {
+      if (args.mode === 'quick') {
+        const view = await quickView(vault.root)
+        return { mode: 'quick', ...view }
+      }
+      const { results, totalMatches } = await searchVault(vault.root, { query: args.query, limit })
+      return { mode: 'standard', query: args.query, results, totalMatches }
+    },
+    presentCall: args => ({ card: 'generic', title: `Query wiki: ${args.query}`, kind: 'read', rawInput: args.query }),
+  })
+
+  const wikiWrite = defineTool({
+    name: 'wiki_write',
+    description:
+      'Write or update one wiki page with full bookkeeping: routes the page to its type folder, '
+      + 'completes YAML frontmatter (type, title, status, created, updated, tags), guards filename '
+      + 'uniqueness, updates the master index entry, and prepends a log entry. The content is the '
+      + 'markdown body only — frontmatter is managed. With source_path, records the source hash in '
+      + 'the ingest manifest and reports already_ingested for unchanged content unless force is set.',
+    parameters: {
+      title: {
+        type: 'string',
+        required: true,
+        description: 'Page title; also the filename and [[wikilink]] target. Title Case with spaces.',
+      },
+      type: {
+        type: 'string',
+        required: true,
+        enum: PAGE_TYPES,
+        description: 'Page type, which selects the folder: sources, entities, concepts, domains, questions, comparisons, or meta.',
+      },
+      content: {
+        type: 'string',
+        required: true,
+        description: 'The markdown body after frontmatter.',
+      },
+      tags: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Frontmatter tags; defaults to [type].',
+      },
+      status: {
+        type: 'string',
+        enum: STATUSES,
+        description: 'Frontmatter status; defaults to developing (kept on update).',
+      },
+      summary: {
+        type: 'string',
+        description: 'One-line master-index entry; defaults to the first content line.',
+      },
+      source_path: {
+        type: 'string',
+        description: 'Vault-relative .raw/ source this page derives from, for delta tracking.',
+      },
+      force: {
+        type: 'boolean',
+        description: 'Write even when the source hash is unchanged. Defaults to false.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+      },
+      render: (args, value) => [{
+        type: 'text',
+        text: typeof value === 'object' && value !== null && 'path' in value
+          ? `wiki_write: ${value.created ? 'created' : 'updated'} ${value.path}`
+          : `wiki_write: skipped ${args.title} (source unchanged)`,
+      }],
+    },
+    async execute(args) {
+      if (args.source_path !== undefined) {
+        const tracked = await vault.trackSource({
+          sourcePath: args.source_path,
+          pagesCreated: [args.title],
+        })
+        if (tracked.alreadyIngested && args.force !== true) {
+          return { alreadyIngested: true, hash: tracked.hash, title: args.title }
+        }
+      }
+      return await vault.writePage(args)
+    },
+    presentCall: args => ({ card: 'generic', title: `Write wiki page: ${args.title}`, kind: 'other', rawInput: { title: args.title, type: args.type } }),
+  })
+
+  const wikiLint = defineTool({
+    name: 'wiki_lint',
+    description:
+      'Health-check the knowledge vault: duplicate filenames, dead wikilinks, orphan pages, '
+      + 'frontmatter gaps, empty sections, stale index entries, and a stale hot cache. '
+      + 'Report only — every issue carries a suggestion. Writes the dated report to wiki/meta/.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: typeof value === 'object' && value !== null && 'summary' in value
+          ? `wiki_lint: ${value.summary.issues} issues across ${value.summary.pagesScanned} pages; report at ${value.reportPath ?? '(not written)'}`
+          : 'wiki_lint: failed',
+      }],
+    },
+    async execute() {
+      return await lintVault(vault.root)
+    },
+    presentCall: () => ({ card: 'generic', title: 'Lint wiki vault', kind: 'other' }),
+  })
+
+  return [wikiQuery, wikiWrite, wikiLint]
+}
+
+/**
+ * Validate the deployment config and register the three wiki tools.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - registrant context carrying the tool registry.
+ * @param {import('@deepseek-ai/schemastery').Extract<typeof Config>} config - deployment config with the vault root.
+ * @returns {Promise<void>}
+ */
+export async function apply(ctx, config) {
+  if (typeof config.vaultPath !== 'string' || config.vaultPath.length === 0) {
+    throw new Error(
+      'wiki-tools: config vaultPath is required. Set it on the wiki-tools row from your profile cordis.patch.yml, e.g.\n'
+      + '  - id: wiki-tools\n'
+      + '    config:\n'
+      + '      vaultPath: /absolute/path/to/vault\n'
+      + 'The vault is the directory holding wiki/ and .raw/ (scaffold it with the wiki skill first).',
+    )
+  }
+  const vault = new Vault(config.vaultPath)
+  await vault.assertRoot()
+  for (const tool of createTools(vault, config)) {
+    ctx.tools.register(tool)
+  }
+}

package/lib/lint.js

@@ -0,0 +1,254 @@
+/**
+ * Vault health checks: the mechanical half of the wiki-lint skill. Report
+ * only — auto-fixing is a human decision, so every issue carries a suggestion
+ * and the report lands in `wiki/meta/lint-report-YYYY-MM-DD.md`.
+ *
+ * @module dsh-plugin-wiki-tools/lib/lint
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { collectMarkdown, META_FILENAMES, splitFrontmatter, today } from './vault.js'
+
+/** Frontmatter fields every content page must carry. */
+const REQUIRED_FIELDS = ['type', 'status', 'created', 'updated', 'tags']
+
+/**
+ * Run every mechanical check over the vault.
+ * @param {string} root - absolute vault root.
+ * @returns {Promise<{ issues: Issue[], summary: { pagesScanned: number, issues: number, byCheck: Record<string, number> }, reportPath: string | undefined }>}
+ */
+export async function lintVault(root) {
+  const pages = await collectMarkdown(join(root, 'wiki'))
+  const issues = []
+  const add = (check, severity, page, detail, suggestion) => {
+    issues.push({ check, severity, page, detail, suggestion })
+  }
+
+  checkDuplicateFilenames(pages, add)
+  const indexed = await checkStaleIndexEntries(root, pages, add)
+  const inbound = checkDeadLinks(pages, add)
+  checkOrphans(pages, inbound, indexed, add)
+  checkFrontmatterGaps(pages, add)
+  checkEmptySections(pages, add)
+  await checkHotCacheStaleness(root, pages, add)
+
+  const byCheck = {}
+  for (const issue of issues) byCheck[issue.check] = (byCheck[issue.check] ?? 0) + 1
+  const reportPath = await writeReport(root, issues, pages.length)
+  return {
+    issues,
+    summary: { pagesScanned: pages.length, issues: issues.length, byCheck },
+    reportPath,
+  }
+}
+
+/** @typedef {'error'|'warn'|'info'} Severity */
+/** @typedef {{ check: string, severity: Severity, page: string, detail: string, suggestion: string }} Issue */
+/** @typedef {(check: string, severity: Severity, page: string, detail: string, suggestion: string) => void} Add */
+
+/**
+ * Filenames must be unique vault-wide: wikilinks resolve by bare name.
+ * @param {Pages} pages - collected pages.
+ * @param {Add} add - issue recorder.
+ */
+function checkDuplicateFilenames(pages, add) {
+  const seen = new Map()
+  for (const page of pages) {
+    const key = page.name.toLowerCase()
+    if (seen.has(key)) {
+      add('duplicate-filename', 'error', page.name,
+        `filename also exists at ${seen.get(key)}`,
+        'Rename one page; wikilinks cannot address two files with one name')
+    } else {
+      seen.set(key, page.path)
+    }
+  }
+}
+
+/**
+ * Index entries pointing at pages that do not exist.
+ * @param {string} root - absolute vault root.
+ * @param {Pages} pages - collected pages.
+ * @param {Add} add - issue recorder.
+ * @returns {Promise<Set<string>>} titles listed in the master index.
+ */
+async function checkStaleIndexEntries(root, pages, add) {
+  const listed = new Set()
+  const raw = await readFile(join(root, 'wiki', 'index.md'), 'utf8').catch(() => undefined)
+  if (raw === undefined) return listed
+  for (const match of raw.matchAll(/\[\[([^\]]+)\]\]/g)) {
+    listed.add(match[1].split('|')[0].split('#')[0].trim())
+  }
+  const names = new Set(pages.map(page => page.name))
+  for (const title of listed) {
+    if (!names.has(title)) {
+      add('stale-index-entry', 'warn', title,
+        'listed in wiki/index.md but no page exists',
+        'Remove the entry, or restore/rename the page to match')
+    }
+  }
+  return listed
+}
+
+/**
+ * Wikilinks targeting pages that do not exist.
+ * @param {Pages} pages - collected pages.
+ * @param {Add} add - issue recorder.
+ * @returns {Map<string, string[]>} inbound links per page title.
+ */
+function checkDeadLinks(pages, add) {
+  const names = new Set(pages.map(page => page.name))
+  const inbound = new Map(pages.map(page => [page.name, []]))
+  for (const page of pages) {
+    for (const target of page.links) {
+      if (names.has(target)) {
+        inbound.get(target)?.push(page.name)
+        continue
+      }
+      add('dead-link', 'error', page.name,
+        `links to [[${target}]] which does not exist`,
+        'Create a stub page or remove the link')
+    }
+  }
+  return inbound
+}
+
+/**
+ * Content pages with no inbound links and no index entry.
+ * @param {Pages} pages - collected pages.
+ * @param {Map<string, string[]>} inbound - inbound links per title.
+ * @param {Set<string>} indexed - titles listed in the master index.
+ * @param {Add} add - issue recorder.
+ */
+function checkOrphans(pages, inbound, indexed, add) {
+  for (const page of pages) {
+    const base = page.name.toLowerCase()
+    if (META_FILENAMES.has(base) || page.name.startsWith('_')) continue
+    const links = inbound.get(page.name) ?? []
+    const isIndexed = indexed.has(page.name)
+    if (links.length === 0 && !isIndexed) {
+      add('orphan-page', 'warn', page.name,
+        'no inbound wikilinks and not in the master index',
+        'Link it from a related page or the index, or delete it')
+    }
+  }
+}
+
+/**
+ * Missing required frontmatter fields on content pages.
+ * @param {Pages} pages - collected pages.
+ * @param {Add} add - issue recorder.
+ */
+function checkFrontmatterGaps(pages, add) {
+  for (const page of pages) {
+    const base = page.name.toLowerCase()
+    if (META_FILENAMES.has(base) || page.name.startsWith('_')) continue
+    const missing = REQUIRED_FIELDS.filter(field => page.fields?.[field] === undefined)
+    if (missing.length > 0) {
+      add('frontmatter-gap', 'warn', page.name,
+        `missing fields: ${missing.join(', ')}`,
+        'Complete the frontmatter (type, status, created, updated, tags)')
+    }
+  }
+}
+
+/**
+ * Headings with no content before the next heading.
+ * @param {Pages} pages - collected pages.
+ * @param {Add} add - issue recorder.
+ */
+function checkEmptySections(pages, add) {
+  for (const page of pages) {
+    if (META_FILENAMES.has(page.name.toLowerCase())) continue
+    const lines = [...page.content.split('\n'), '# __eof__']
+    let heading
+    let hasContent = false
+    for (const line of lines) {
+      if (/^#{1,6} /.test(line)) {
+        if (heading !== undefined && !hasContent) {
+          add('empty-section', 'info', page.name,
+            `section "${heading}" has no content`,
+            'Fill it, or remove the heading')
+        }
+        heading = line.replace(/^#+\s*/, '').replace('__eof__', '').trim()
+        hasContent = false
+      } else if (line.trim().length > 0) {
+        hasContent = true
+      }
+    }
+  }
+}
+
+/**
+ * The hot cache lagging behind every page's last update.
+ * @param {string} root - absolute vault root.
+ * @param {Pages} pages - collected pages.
+ * @param {Add} add - issue recorder.
+ */
+async function checkHotCacheStaleness(root, pages, add) {
+  const raw = await readFile(join(root, 'wiki', 'hot.md'), 'utf8').catch(() => undefined)
+  if (raw === undefined) return
+  const { fields } = splitFrontmatter(raw, 'wiki/hot.md')
+  const hotUpdated = typeof fields?.updated === 'string' ? fields.updated : undefined
+  if (hotUpdated === undefined) return
+  const newest = pages
+    .map(page => (typeof page.fields?.updated === 'string' ? page.fields.updated : ''))
+    .sort()
+    .at(-1)
+  if (newest !== undefined && newest > hotUpdated) {
+    add('stale-hot-cache', 'warn', 'hot.md',
+      `hot cache updated ${hotUpdated}, newest page update ${newest}`,
+      'Refresh wiki/hot.md to reflect recent changes')
+  }
+}
+
+/**
+ * Write the lint report page in the suite's canonical format.
+ * @param {string} root - absolute vault root.
+ * @param {Issue[]} issues - every found issue.
+ * @param {number} pagesScanned - pages covered by the run.
+ * @returns {Promise<string | undefined>} the report path, or undefined when writing failed.
+ */
+async function writeReport(root, issues, pagesScanned) {
+  const date = today()
+  const path = join(root, 'wiki', 'meta', `lint-report-${date}.md`)
+  const sections = new Map()
+  for (const issue of issues) {
+    if (!sections.has(issue.check)) sections.set(issue.check, [])
+    sections.get(issue.check).push(issue)
+  }
+  const lines = [
+    '---',
+    'type: meta',
+    `title: "Lint Report ${date}"`,
+    `created: ${date}`,
+    `updated: ${date}`,
+    'tags: [meta, lint]',
+    'status: developing',
+    '---',
+    '',
+    `# Lint Report: ${date}`,
+    '',
+    '## Summary',
+    `- Pages scanned: ${pagesScanned}`,
+    `- Issues found: ${issues.length}`,
+    '',
+  ]
+  for (const [check, grouped] of sections) {
+    lines.push(`## ${check.replace(/(^|-)(\w)/g, (_, prefix, char) => (prefix === '-' ? ' ' : '') + char.toUpperCase())}`)
+    for (const issue of grouped) {
+      lines.push(`- [[${issue.page}]] (${issue.severity}): ${issue.detail}. Suggest: ${issue.suggestion}.`)
+    }
+    lines.push('')
+  }
+  try {
+    await mkdir(join(root, 'wiki', 'meta'), { recursive: true })
+    await writeFile(path, `${lines.join('\n')}\n`, 'utf8')
+    return path
+  } catch {
+    return undefined
+  }
+}
+
+/** @typedef {{ name: string, path: string, rel: string, fields: Record<string, unknown> | undefined, content: string, links: string[] }[]} Pages */

package/lib/search.js

@@ -0,0 +1,111 @@
+/**
+ * Vault-aware search: the wiki-query skill's read order (hot cache, master
+ * index, then pages) as one tool-call, plus full-text search with the link
+ * graph that makes wiki retrieval different from grep.
+ *
+ * @module dsh-plugin-wiki-tools/lib/search
+ */
+
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { collectMarkdown, META_FILENAMES } from './vault.js'
+
+/**
+ * Answer the quick mode: the hot cache and master index verbatim. The caller
+ * (the model, following the wiki-query skill) reads these before any page.
+ * @param {string} root - absolute vault root.
+ * @returns {Promise<{ hot: string | undefined, index: string | undefined }>}
+ */
+export async function quickView(root) {
+  const [hot, index] = await Promise.all([
+    readFile(join(root, 'wiki', 'hot.md'), 'utf8').catch(() => undefined),
+    readFile(join(root, 'wiki', 'index.md'), 'utf8').catch(() => undefined),
+  ])
+  return { hot, index }
+}
+
+/**
+ * Full-text search over the wiki tree with link-graph context. Matches are
+ * case-insensitive substrings scored by where they hit: title 5, tags 4,
+ * headings 2, body 1 per occurrence.
+ * @param {string} root - absolute vault root.
+ * @param {object} options - search options.
+ * @param {string} options.query - the search text.
+ * @param {number} [options.limit=10] - maximum results.
+ * @returns {Promise<{ results: { name: string, path: string, score: number, snippets: string[], inbound: string[], outbound: number }[], totalMatches: number }>}
+ */
+export async function searchVault(root, { query, limit = 10 }) {
+  const needle = query.trim().toLowerCase()
+  if (needle.length === 0) throw new Error('wiki-tools: query must be a non-empty string')
+  const pages = await collectMarkdown(join(root, 'wiki'))
+  // The link graph covers every file, but results exclude vault machinery:
+  // the index matches nearly every term by construction and is already the
+  // quick-mode payload.
+  const searchable = pages.filter(page =>
+    !META_FILENAMES.has(page.name.toLowerCase()) && !page.name.startsWith('_'))
+  const inbound = new Map(pages.map(page => [page.name, []]))
+  for (const page of searchable) {
+    for (const target of page.links) {
+      inbound.get(target)?.push(page.name)
+    }
+  }
+  const results = []
+  let totalMatches = 0
+  for (const page of searchable) {
+    const titleHits = countOccurrences(page.name.toLowerCase(), needle) * 5
+    const tags = Array.isArray(page.fields?.tags) ? page.fields.tags.join(' ').toLowerCase() : ''
+    const tagHits = tags.includes(needle) ? 4 : 0
+    const headings = page.content.split('\n').filter(line => line.startsWith('#')).join('\n').toLowerCase()
+    const headingHits = countOccurrences(headings, needle) * 2
+    const body = page.content.toLowerCase()
+    const bodyHits = countOccurrences(body, needle)
+    const score = titleHits + tagHits + headingHits + bodyHits
+    if (score === 0) continue
+    totalMatches += 1
+    results.push({
+      name: page.name,
+      path: page.path,
+      score,
+      snippets: matchLines(page.content, needle).slice(0, 2),
+      inbound: inbound.get(page.name) ?? [],
+      outbound: page.links.length,
+    })
+  }
+  results.sort((left, right) => right.score - left.score || left.name.localeCompare(right.name))
+  return { results: results.slice(0, limit), totalMatches: results.length }
+}
+
+/**
+ * Case-insensitive matching lines, trimmed for a result snippet.
+ * @param {string} content - page body.
+ * @param {string} needle - lowercased search text.
+ * @returns {string[]} up to 4 matching lines trimmed to 160 characters.
+ */
+function matchLines(content, needle) {
+  const lines = []
+  for (const line of content.split('\n')) {
+    if (line.toLowerCase().includes(needle)) {
+      const trimmed = line.trim()
+      lines.push(trimmed.length > 160 ? `${trimmed.slice(0, 157)}...` : trimmed)
+      if (lines.length === 4) break
+    }
+  }
+  return lines
+}
+
+/**
+ * Count substring occurrences.
+ * @param {string} haystack - lowercased text.
+ * @param {string} needle - lowercased substring.
+ * @returns {number} occurrence count.
+ */
+function countOccurrences(haystack, needle) {
+  if (!haystack.includes(needle)) return 0
+  let count = 0
+  let index = haystack.indexOf(needle)
+  while (index >= 0) {
+    count += 1
+    index = haystack.indexOf(needle, index + needle.length)
+  }
+  return count
+}

package/lib/vault.js

@@ -0,0 +1,360 @@
+/**
+ * Vault bookkeeping: path routing, frontmatter completion, index/log updates,
+ * and source delta tracking for an Obsidian wiki vault following the LLM Wiki
+ * layout (`.raw/` sources, `wiki/` knowledge tree).
+ *
+ * The vault is host-local user data addressed by an explicitly configured
+ * absolute root; reads and writes go through node:fs directly, not a dsh
+ * filesystem seam, because the vault lives outside any session workspace by
+ * design (cross-project referencing is the point).
+ *
+ * @module dsh-plugin-wiki-tools/lib/vault
+ */
+
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises'
+import { 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). */
+export const TYPE_FOLDERS = {
+  source: 'wiki/sources',
+  entity: 'wiki/entities',
+  concept: 'wiki/concepts',
+  domain: 'wiki/domains',
+  question: 'wiki/questions',
+  comparison: 'wiki/comparisons',
+  meta: 'wiki/meta',
+}
+
+/** Master-index section heading per page type, in catalog order. */
+const INDEX_SECTIONS = {
+  domain: '## Domains',
+  entity: '## Entities',
+  concept: '## Concepts',
+  source: '## Sources',
+  question: '## Questions',
+  comparison: '## Comparisons',
+}
+
+/** Pages that are vault machinery, never linted as content (basenames, no extension). */
+export const META_FILENAMES = new Set(['index', '_index', 'log', 'hot', 'overview'])
+
+/**
+ * Split one Markdown file into frontmatter fields and body. A file without a
+ * frontmatter fence returns no fields; a broken fence throws.
+ * @param {string} raw - the complete file text.
+ * @param {string} source - path shown in error messages.
+ * @returns {{ fields: Record<string, unknown> | undefined, content: string }}
+ */
+export function splitFrontmatter(raw, source) {
+  if (!raw.startsWith('---\n') && !raw.startsWith('---\r\n')) return { fields: undefined, content: raw }
+  const firstLineEnd = raw.indexOf('\n')
+  const rest = raw.slice(firstLineEnd + 1)
+  const closing = rest.search(/^---(?:\r?\n|$)/m)
+  if (closing < 0) throw new Error(`${source}: frontmatter has no closing --- fence`)
+  const frontmatterText = rest.slice(0, closing)
+  const content = rest.slice(closing).replace(/^---\r?\n?/, '')
+  const fields = parseYaml(frontmatterText)
+  if (fields !== null && typeof fields !== 'object' && !Array.isArray(fields)) {
+    throw new Error(`${source}: frontmatter must be a YAML mapping`)
+  }
+  return { fields: fields === null ? undefined : fields, content }
+}
+
+/** Today as the vault's canonical YYYY-MM-DD stamp. */
+export function today() {
+  return new Date().toISOString().slice(0, 10)
+}
+
+/**
+ * One vault root. All bookkeeping mutations go through {@link Vault.writePage},
+ * which completes frontmatter, updates the master index, and prepends a log
+ * entry in one serialized write per file.
+ */
+export class Vault {
+  /** @param {string} root - absolute path to the vault root (the directory holding `wiki/` and `.raw/`). */
+  constructor(root) {
+    if (typeof root !== 'string' || root.length === 0 || !isAbsolute(root)) {
+      throw new Error(`wiki-tools: vaultPath must be an absolute directory path (got ${JSON.stringify(root)})`)
+    }
+    this.root = root
+    /** Per-file write chains so concurrent tool calls serialize per target. */
+    this.writeChains = new Map()
+  }
+
+  /** Absolute path of one routed page. @param {string} type - page type. @param {string} title - page title (also the filename). */
+  pagePath(type, title) {
+    const folder = TYPE_FOLDERS[type]
+    if (folder === undefined) throw new Error(`wiki-tools: unknown page type "${type}"`)
+    if (!/^[^/\\]+(\.md)?$/.test(title) || title.includes('\n')) {
+      throw new Error(`wiki-tools: title must be a plain filename without path separators (got ${JSON.stringify(title)})`)
+    }
+    const filename = title.endsWith('.md') ? title : `${title}.md`
+    return join(this.root, folder, filename)
+  }
+
+  /**
+   * Verify the vault root exists and is a directory.
+   * @returns {Promise<void>} rejects with a setup hint when the root is missing.
+   */
+  async assertRoot() {
+    const info = await stat(this.root).catch(error => {
+      if (error.code === 'ENOENT') {
+        throw new Error(`wiki-tools: vault root ${this.root} does not exist; scaffold it first (the wiki skill's SCAFFOLD operation), then point vaultPath at it`)
+      }
+      throw error
+    })
+    if (!info.isDirectory()) throw new Error(`wiki-tools: vault root ${this.root} is not a directory`)
+  }
+
+  /**
+   * Read one page's frontmatter and body.
+   * @param {string} path - absolute page path.
+   * @returns {Promise<{ fields: Record<string, unknown> | undefined, content: string } | undefined>} undefined when missing.
+   */
+  async readPage(path) {
+    let raw
+    try {
+      raw = await readFile(path, 'utf8')
+    } catch (error) {
+      if (error.code === 'ENOENT') return undefined
+      throw error
+    }
+    return splitFrontmatter(raw, path)
+  }
+
+  /**
+   * Serialize one mutating operation per target path.
+   * @param {string} path - absolute target path.
+   * @param {() => Promise<T>} operation - the mutation, run after the previous one settles.
+   * @returns {Promise<T>}
+   */
+  enqueue(path, operation) {
+    const previous = this.writeChains.get(path) ?? Promise.resolve()
+    const next = previous.then(operation, operation)
+    this.writeChains.set(path, next.then(() => {}, () => {}))
+    return next
+  }
+
+  /**
+   * 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.
+   * @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.summary] - one-line index entry; defaults to the first content line.
+   * @returns {Promise<{ path: string, created: boolean, title: string }>}
+   */
+  async writePage({ type, title, content, tags, status, summary }) {
+    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)
+      const date = today()
+      const fields = {
+        ...(existing?.fields ?? {}),
+        type,
+        title: cleanTitle,
+        status: status ?? existing?.fields?.status ?? 'developing',
+        created: existing?.fields?.created ?? date,
+        updated: date,
+        tags: tags ?? existing?.fields?.tags ?? [type],
+      }
+      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.prependLog(`## [${date}] ${existing === undefined ? 'create' : 'update'} | ${cleanTitle}`, [
+        `- ${existing === undefined ? 'Created' : 'Updated'}: [[${cleanTitle}]]`,
+      ])
+      return { path, created: existing === undefined, title: cleanTitle }
+    })
+  }
+
+  /**
+   * Reject a title whose filename already exists elsewhere in the tree:
+   * wikilinks address pages by bare filename, so duplicates break resolution.
+   * @param {string} title - page title being written.
+   * @param {string} path - the routed destination path.
+   */
+  async assertUniqueFilename(title, path) {
+    const pages = await collectMarkdown(join(this.root, 'wiki'))
+    for (const page of pages) {
+      if (page.name.toLowerCase() === title.toLowerCase() && page.path !== path) {
+        throw new Error(`wiki-tools: filename "${title}.md" already exists at ${page.path}; wikilinks need unique filenames`)
+      }
+    }
+  }
+
+  /**
+   * Add or refresh one `- [[Title]]: summary` entry in the master index.
+   * Missing sections and files are created on first use.
+   * @param {string} type - page type selecting the index section.
+   * @param {string} title - page title.
+   * @param {string} summary - one-line description.
+   */
+  async updateIndex(type, title, summary) {
+    const heading = INDEX_SECTIONS[type]
+    if (heading === undefined) return
+    const indexPath = join(this.root, 'wiki', 'index.md')
+    let raw = await readFile(indexPath, 'utf8').catch(() => undefined)
+    if (raw === undefined) {
+      raw = '# Wiki Index\n\n'
+      for (const section of Object.values(INDEX_SECTIONS)) raw += `${section}\n\n`
+      await mkdir(join(indexPath, '..'), { recursive: true })
+    }
+    const entry = `- [[${title}]]: ${summary.replace(/\n/g, ' ')}`
+    const lines = raw.split('\n')
+    let headingLine = lines.findIndex(line => line === heading)
+    if (headingLine < 0) {
+      lines.push('', heading, entry)
+      await writeFile(indexPath, lines.join('\n').replace(/\n{3,}/g, '\n\n'), 'utf8')
+      return
+    }
+    const linkPrefix = `- [[${title}]]`
+    let cursor = headingLine + 1
+    while (cursor < lines.length && lines[cursor] !== '' && !lines[cursor].startsWith('## ')) {
+      if (lines[cursor].startsWith(linkPrefix)) {
+        lines[cursor] = entry
+        await writeFile(indexPath, lines.join('\n'), 'utf8')
+        return
+      }
+      cursor += 1
+    }
+    lines.splice(cursor, 0, entry)
+    await writeFile(indexPath, lines.join('\n'), 'utf8')
+  }
+
+  /**
+   * Prepend one dated entry to the append-only operation log.
+   * @param {string} header - the `## [date] op | title` heading line.
+   * @param {string[]} bullets - detail lines under the heading.
+   */
+  async prependLog(header, bullets) {
+    const logPath = join(this.root, 'wiki', 'log.md')
+    const raw = await readFile(logPath, 'utf8').catch(() => '# Wiki Log\n')
+    const stripped = raw.replace(/^# Wiki Log\r?\n?/, '')
+    const entry = `${header}\n${bullets.join('\n')}\n\n`
+    await mkdir(join(logPath, '..'), { recursive: true })
+    await writeFile(logPath, `# Wiki Log\n\n${entry}${stripped.replace(/^\s*/, '')}`, 'utf8')
+  }
+
+  /**
+   * Delta-track one raw source: report whether its content hash is unchanged
+   * since the last ingest, then record the new hash and touched pages.
+   * @param {object} input - the tracking request.
+   * @param {string} input.sourcePath - vault-relative or absolute `.raw/` source path.
+   * @param {string[]} [input.pagesCreated] - pages this ingest created.
+   * @param {string[]} [input.pagesUpdated] - pages this ingest updated.
+   * @returns {Promise<{ hash: string, alreadyIngested: boolean }>}
+   */
+  async trackSource({ sourcePath, pagesCreated = [], pagesUpdated = [] }) {
+    const absolute = isAbsolute(sourcePath) ? sourcePath : join(this.root, sourcePath)
+    const rel = relative(this.root, absolute)
+    const raw = await readFile(absolute).catch(error => {
+      if (error.code === 'ENOENT') throw new Error(`wiki-tools: source ${sourcePath} not found under the vault`)
+      throw error
+    })
+    const hash = createHash('sha256').update(raw).digest('hex')
+    const manifestPath = join(this.root, '.raw', '.manifest.json')
+    const manifest = await readJson(manifestPath, { sources: {} })
+    const previous = manifest.sources[rel] ?? manifest.sources[sourcePath]
+    const alreadyIngested = previous !== undefined && previous.hash === hash
+    manifest.sources[rel] = {
+      hash,
+      ingested_at: today(),
+      pages_created: pagesCreated,
+      pages_updated: pagesUpdated,
+    }
+    await mkdir(join(manifestPath, '..'), { recursive: true })
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+    return { hash, alreadyIngested }
+  }
+}
+
+/**
+ * First non-heading, non-empty content line, for index summaries.
+ * @param {string} content - markdown body.
+ * @returns {string} up to 120 characters of the first prose line.
+ */
+function firstContentLine(content) {
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed.length > 0 && !trimmed.startsWith('#') && !trimmed.startsWith('---')) {
+      return trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed
+    }
+  }
+  return '(no summary)'
+}
+
+/**
+ * Read a JSON file, returning the fallback when absent.
+ * @param {string} path - absolute file path.
+ * @param {T} fallback - value when the file is missing.
+ * @returns {Promise<T>}
+ * @template T
+ */
+async function readJson(path, fallback) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'))
+  } catch (error) {
+    if (error.code === 'ENOENT') return fallback
+    throw error
+  }
+}
+
+/**
+ * Recursively collect every Markdown page under a directory with title and wikilinks.
+ * @param {string} directory - absolute directory to walk.
+ * @returns {Promise<{ name: string, path: string, rel: string, fields: Record<string, unknown> | undefined, content: string, links: string[] }[]>}
+ */
+export async function collectMarkdown(directory) {
+  const pages = []
+  let entries
+  try {
+    entries = await readdir(directory, { withFileTypes: true })
+  } catch (error) {
+    if (error.code === 'ENOENT') return pages
+    throw error
+  }
+  for (const entry of entries) {
+    const path = join(directory, entry.name)
+    if (entry.isDirectory()) {
+      pages.push(...await collectMarkdown(path))
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const { fields, content } = splitFrontmatter(await readFile(path, 'utf8'), path)
+      pages.push({
+        name: entry.name.slice(0, -3),
+        path,
+        rel: relative(directory, path).split(sep).join('/'),
+        fields,
+        content,
+        links: extractWikilinks(content),
+      })
+    }
+  }
+  return pages
+}
+
+/**
+ * Extract wikilink targets from markdown, dropping aliases and heading anchors.
+ * @param {string} content - markdown body.
+ * @returns {string[]} link targets in order of appearance.
+ */
+export function extractWikilinks(content) {
+  const links = []
+  const withoutFences = content.replace(/```[\s\S]*?```/g, '')
+  for (const match of withoutFences.matchAll(/\[\[([^\]]+)\]\]/g)) {
+    const target = match[1].split('|')[0].split('#')[0].trim()
+    if (target.length > 0) links.push(target)
+  }
+  return links
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "dsh-plugin-wiki-tools",
+  "version": "0.1.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",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./lib/vault.js": "./lib/vault.js",
+    "./lib/search.js": "./lib/search.js",
+    "./lib/lint.js": "./lib/lint.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "cordis.patch.yml"
+  ],
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "obsidian",
+    "knowledge-base",
+    "wiki"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lion-1209/dsh-plugin-wiki-tools.git"
+  },
+  "dependencies": {
+    "yaml": "^2.8.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-tools": "*",
+    "@deepseek-ai/schemastery": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}