dsh-grove 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wali@2026
+
+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

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# Grove（知林）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![Grove：让每次对话长成可追溯的知识资产](brand/exports/readme-header-1600x480.zh.png)
+
+Grove 是 DeepSeek Harness 的个人知识成长插件。用 Obsidian vault 保存灵感、问题、知识资产和研究证据。探索是常态，研究是选择，成果自然生长。
+
+## 安装 v0.1.1
+
+需要 Node.js 22 或更高版本、一个已有的 Obsidian vault，以及 DeepSeek Harness `>=0.2.2-rc.1 <0.3.0`。兼容范围由 `engines.dsh` 声明：它必须是范围而不是某一个精确版本，否则 dsh 会把整个 bundle 判为不兼容并跳过加载。
+
+### 装进现有的 Harness
+
+| 入口 | 做法 |
+| --- | --- |
+| Desktop | **Plugins → Add plugin**，选择本仓库目录；按目录安装会装成 `link:`，改完代码重启宿主即生效 |
+| 会话里 | 让 agent 调用 `plugin_manager` 的 `install_bundle`，`target` 传目录绝对路径 |
+| CLI | `dsh plugin --profile <profile> add <目录或 tgz>`。Desktop 的 profile 由 App 管理，命令行装进 `profiles/web` 不会出现在 Desktop |
+
+装完在 **Plugins** 页确认 Grove 这一条出现，并在新会话里让模型调用 `grove_role`——工具真的注册上才算装好。
+
+### 独立 profile 试用（不碰日常配置）
+
+```sh
+export GROVE_VAULT="/absolute/path/to/Obsidian vault"
+npx --yes @deepseek-ai/dsh@0.2.2-rc.3 plugin --profile grove add "$PWD"
+npx --yes @deepseek-ai/dsh@0.2.2-rc.3 --profile grove
+```
+
+独立配置只初始化一次；已有 `grove` 配置时直接安装或启动。用独立配置试用，确保宿主的 Bash、文件编辑、通用自动化和其他扩展无法访问 vault 或代你运行本地确认命令。Grove 自身的模型工具只有角色提示、草稿和白名单查询。普通 Harness 会话仍遵循宿主的模型路由、权限和历史保留设置。
+
+### 命令行工具
+
+`grove` 命令来自包里的 `bin`，要全局安装才有；把插件装进某个 profile **不会**把它加进 PATH：
+
+```sh
+npm pack --pack-destination /tmp
+npm install --global /tmp/dsh-grove-0.1.1.tgz
+```
+
+## 日常使用
+
+1. 终端执行 `grove capture --body '为什么组织扩大后协调成本会上升？'`。在 Obsidian 中打开 vault 的 `Grove` 文件夹可看到 Markdown 笔记。
+2. 在 Harness 中自由对话。可要求使用 `grove_role` 作为思想伙伴、知识助手、研究助手、批判性审查者或创造助手。想保留一段讨论时，请求 `grove_propose` 起草，并提供你愿意保存的会话引用。探索可以直接结束。
+3. 在自己的终端执行 `grove preview 草稿ID`。用 `grove accept 草稿ID` 查看并输入 `SAVE`，或执行 `grove discard 草稿ID`。确认时也可用 `--file` 提供你编辑过的正文。
+4. 用 `grove list` 查询资产，用 `grove show 资产ID --version 1` 回看具体版本。默认 Grove 不向模型提供资产正文。若希望分享指定笔记，启动宿主前将 `GROVE_READABLE_IDS` 设为逗号分隔的资产 ID。取消分享后重新启动宿主。已进入宿主会话的内容仍受宿主历史设置约束。
+
+## 基础研究
+
+```sh
+grove add question --body '团队规模如何影响决策效率？'
+grove add research --question QUESTION_ID --body '比较决策权限和协调成本'
+grove add evidence --body '粘贴可核对的摘录' --source 'https://example.org/report' --locator '第12页第2段'
+grove add claim --body '我目前的判断'
+grove update CLAIM_ID --version 1 --link EVIDENCE_ID --relation supports
+grove update RESEARCH_ID --version 1 --link CLAIM_ID --relation related
+grove update RESEARCH_ID --version 2 --stage analysis
+grove update RESEARCH_ID --version 3 --stage review --status closed
+```
+
+把示例 ID 替换成上一步返回的 ID。阶段可回退，问题和项目可暂停、重开或归档。证据关系可表达支持、反驳和限定，双链指向具体版本。重写观点正文时，旧证据关系留在原版本，用户可以为新版本重新采用证据。结束研究时，成果可选。
+
+## 数据和卸载
+
+`Grove/` 内的版本文件使用 YAML 属性、Markdown 正文和 Obsidian 双链。Grove 不读 vault 中其他笔记。复制整个 `Grove/` 文件夹即可备份或迁移，点号开头的草稿文件也会随整目录迁移。可在 Obsidian 阅读及编辑正文，保留文件名和 Grove 元数据。要保留更改前的版本，使用 `grove update`。本版证据使用用户填写的来源标识与定位，附件管理、自动会话定位和专用插件界面留待后续版本。
+
+用 `npx --yes @deepseek-ai/dsh@0.2.2-rc.3 plugin --profile grove remove dsh-grove` 卸载宿主插件。数据留在 vault，终端命令可通过 `npm uninstall --global dsh-grove` 单独卸载。
+
+## 品牌资产
+
+标志、锁定组合、色板、字体与导出图都在 [`brand/`](brand/README.md)，规范见 [`brand/VI.md`](brand/VI.md)（中文）与 [`brand/VI.en.md`](brand/VI.en.md)（English）。根目录的 `icon.svg` 与 `brand/mark.svg` 保持字节一致，由测试保证。
+
+## 参与开发
+
+规则只有一份：[`AGENTS.md`](AGENTS.md)（[English](AGENTS.en.md)）。Claude Code、Cursor、GitHub Copilot 分别读 `CLAUDE.md`、`.cursor/rules/project.mdc`、`.github/copilot-instructions.md`，三者都只指向 `AGENTS.md`。
+
+理念、任务分层、DoD 与评审清单在 [`docs/development/`](docs/development/README.md)；会话交接在 [`docs/journal/`](docs/journal/)。改动前先跑 `npm test` 与 `bash scripts/check-compat.sh`。
+
+## 从源代码验证
+
+```sh
+npm ci
+npm test
+npm pack
+```

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: grove
+      name: dsh-grove

package/docs/DETAIL.en.md

@@ -0,0 +1,37 @@
+# Grove
+
+Grove turns DeepSeek Harness conversations into versioned knowledge assets in an Obsidian vault: inspirations, questions, concepts, theories, judgements, methods, outputs, explorations and research projects. AI helps you think; **every saved asset is confirmed by you**.
+
+## What it provides
+
+Three model tools, registered inside the host:
+
+| Tool | Purpose | Boundary |
+| --- | --- | --- |
+| `grove_role` | Returns the collaboration guidance for a role you named explicitly (`thinking` / `knowledge` / `research` / `critical` / `creation`) | Read-only text; never touches the vault |
+| `grove_propose` | Drafts one proposal from your request and writes it as `.proposal.json` | Does not create an asset; only `grove accept` in your terminal saves it |
+| `grove_read` | Reads one asset you explicitly shared | Only IDs listed in `GROVE_READABLE_IDS` |
+
+There are ten asset types: inspiration, question, concept, theory, claim, evidence, method, output, exploration and research. Research projects and evidence are recorded through the terminal commands; the model may only draft the other types.
+
+## How to use it
+
+1. Configure the vault: the plugin config field `vault`, or the `GROVE_VAULT` environment variable. It must be an **absolute path to a real directory**; symlinks in the path are rejected.
+2. Talk to the agent; ask it to call `grove_role` when you want a different way of collaborating.
+3. To keep part of a discussion, ask it to call `grove_propose`, passing the conversation reference you want saved as `origin`.
+4. In your terminal, `grove preview <draft-id>` to review, `grove accept <draft-id>` and type `SAVE` to save, or `grove discard <draft-id>`.
+5. `grove list` / `grove show <asset-id> --version <N>` to look back; `grove update` writes a new version and leaves the old version's evidence links on it.
+
+## Where the data lives
+
+Everything is under `<vault>/Grove/`: one file per asset, `<id>.v<version>.md`, with YAML frontmatter, a Markdown body and Obsidian wikilinks; dot-prefixed `.proposal.json` files beside them are drafts. There is no database — copying the whole `Grove/` folder is the backup and the migration.
+
+## Known limitations
+
+- Evidence records only the source identifier and locator you type (`--source` / `--locator`). No attachment management, no automatic session locating.
+- No dedicated Web UI: the surface is the in-session tools plus the terminal CLI.
+- Saving must happen in an interactive terminal (`grove accept` asks you to type `SAVE`); the model cannot save on your behalf.
+- Asset bodies are not given to the model by default; sharing requires `GROVE_READABLE_IDS` in advance, and turning sharing off needs a host restart.
+- One note is capped at 1 MiB and a draft body at 128 KiB; `grove_read` refuses assets outside the sharing list and archived assets.
+- The `grove` command comes from the package's `bin` and needs a global install; installing the plugin into a profile does not put it on `PATH`.
+- Compatible with dsh `>=0.2.2-rc.1 <0.3.0`.

package/docs/DETAIL.zh.md

@@ -0,0 +1,37 @@
+# Grove（知林）
+
+Grove 把 DeepSeek Harness 里的对话，变成 Obsidian vault 里可版本化的知识资产：灵感、问题、概念、理论、判断、方法、成果、探索、研究。AI 协助思考，**保存始终由你确认**。
+
+## 提供什么
+
+三个模型工具，注册在宿主内：
+
+| 工具 | 作用 | 边界 |
+| --- | --- | --- |
+| `grove_role` | 返回你明确点名的协作角色指引（`thinking` / `knowledge` / `research` / `critical` / `creation`） | 只读文本，不碰 vault |
+| `grove_propose` | 按你的要求起草一条草稿，写成 `.proposal.json` | 不创建资产；要你在终端执行 `grove accept` 才落盘 |
+| `grove_read` | 读取一条你显式分享的资产 | 只认 `GROVE_READABLE_IDS` 白名单里的 ID |
+
+资产类型共十种：灵感、问题、概念、理论、判断、证据、方法、成果、探索、研究。研究与证据走终端命令，模型只能起草其余类型。
+
+## 怎么用
+
+1. 配置 vault：插件配置里的 `vault`，或环境变量 `GROVE_VAULT`。必须是**绝对路径的真实目录**；路径里的 symlink 会被拒绝。
+2. 在会话里对话，需要时让模型调用 `grove_role` 切换协作方式。
+3. 想留下讨论时，让模型调用 `grove_propose` 起草，并把你要保存的会话引用作为 `origin` 传入。
+4. 在终端 `grove preview <草稿ID>` 看内容，`grove accept <草稿ID>` 并输入 `SAVE` 落盘，或用 `grove discard` 丢弃。
+5. `grove list` / `grove show <资产ID> --version <N>` 回看；`grove update` 写入新版本，旧版本的证据关系留在旧版本上。
+
+## 数据放在哪
+
+全在 `<vault>/Grove/`：一条资产一个文件 `<id>.v<版本>.md`，YAML frontmatter + Markdown 正文 + Obsidian 双链；点号开头的 `.proposal.json` 是同目录的草稿。没有数据库，复制整个 `Grove/` 就是备份和迁移。
+
+## 已知限制
+
+- 证据只记录你填写的来源标识与定位（`--source` / `--locator`），没有附件管理，也不自动定位会话。
+- 没有专用 Web 界面：交互面是会话里的工具加终端 CLI。
+- 保存必须在交互式终端完成（`grove accept` 要手输 `SAVE`），模型不能代你落盘。
+- 默认不把资产正文交给模型；分享要预先设置 `GROVE_READABLE_IDS`，取消分享后需重启宿主。
+- 单条笔记上限 1 MiB，草稿正文上限 128 KiB；`grove_read` 拒绝白名单外和已归档的资产。
+- `grove` 命令来自 npm 全局安装的 `bin`；把插件装进某个 profile 不会把它加进 PATH。
+- 兼容 dsh `>=0.2.2-rc.1 <0.3.0`。

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36">
+  <g transform="translate(18 18) scale(1.12) translate(-18.6 -20.9)">
+    <path d="M16.9 30.4h2.2l-.65-12.3h-.9z" fill="#1B3A2E"/>
+    <path d="M18.4 19c2.2-6.5 8.3-9.4 10.5-8.15-1 5.3-4.9 8.45-10.5 8.15Z" fill="#2F7D5B"/>
+    <path d="M17.6 23c-2.2-5.1-6.5-7.3-8.5-6.3.7 4.1 4.3 6.3 8.5 6.3Z" fill="#5FA37E"/>
+    <path d="M15.4 31.5h5.2" stroke="#C98A3B" stroke-width="2.2" stroke-linecap="round" fill="none"/>
+  </g>
+</svg>

package/locale/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Grove",
+    "description": "Personal knowledge growth in an Obsidian vault: capture ideas, keep versioned notes, and run evidence-tracked research, with every saved asset confirmed by you.",
+    "detail": "docs/DETAIL.en.md"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Grove（知林）",
+    "description": "在 Obsidian vault 里做个人知识成长：捕捉灵感、沉淀可版本化的知识资产、带证据做研究，每条资产都由你确认后才落盘。",
+    "detail": "docs/DETAIL.zh.md"
+  }
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "dsh-grove",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Personal knowledge growth for DeepSeek Harness and Obsidian",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/plugin.js",
+  "exports": {
+    ".": "./src/plugin.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "icon": "icon.svg",
+  "bin": {
+    "grove": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "docs/DETAIL.en.md",
+    "docs/DETAIL.zh.md"
+  ],
+  "engines": {
+    "node": ">=22",
+    "dsh": ">=0.2.2-rc.1 <0.3.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-tools": ">=0.2.2-rc.1 <0.3.0",
+    "semver": "^7.7.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": ">=0.2.2-rc.1 <0.3.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util'
+import { createInterface } from 'node:readline/promises'
+import { readFile } from 'node:fs/promises'
+import { Vault, stages, types } from './vault.js'
+import { accept, discard, preview } from './proposals.js'
+
+const usage = `Grove v0.1 · set GROVE_VAULT to an absolute Obsidian vault path
+  grove capture --body 'idea'
+  grove add TYPE --body 'text' [--title 'title'] [--origin 'session or source']
+  grove add evidence --body 'excerpt' --source 'source URL or identifier' --locator 'p. 12'
+  grove add research --body 'scope' --question QUESTION_ID
+  grove list [--query 'term']
+  grove show ID [--version N]
+  grove update ID --version N [--body 'new text'] [--status open|paused|closed|archived]
+  grove update ID --version N --stage STAGE
+  grove update ID --version N --link TARGET_ID --relation supports|refutes|qualifies|related|derived
+  grove preview DRAFT_ID
+  grove discard DRAFT_ID
+  grove accept DRAFT_ID [--body 'edited text' | --file FILE]
+Types: ${types.join(', ')}
+Research stages: ${stages.join(', ')}
+Use --file instead of --body for multiline text.
+`
+
+function print(value) {
+  process.stdout.write(JSON.stringify(value, null, 2) + '\n')
+}
+
+async function main() {
+  const { positionals: [command, id, ...extra], values } = parseArgs({
+    allowPositionals: true,
+    options: Object.fromEntries(['body', 'file', 'title', 'origin', 'source', 'locator', 'question', 'query', 'version', 'status', 'stage', 'link', 'relation'].map(name => [name, { type: 'string' }])),
+  })
+  if (!command || command === 'help') return process.stdout.write(usage)
+  if (extra.length) throw new Error('Unexpected positional arguments')
+  if (values.body !== undefined && values.file !== undefined) throw new Error('Specify either --body or --file')
+  const vault = new Vault(process.env.GROVE_VAULT)
+  const body = values.file === undefined ? values.body : await readFile(values.file, 'utf8')
+  const version = values.version === undefined ? undefined : Number(values.version)
+  switch (command) {
+    case 'capture': return print(await vault.create({ ...values, body, type: 'inspiration' }))
+    case 'add': return print(await vault.create({ ...values, body, type: id }))
+    case 'list': return print((await vault.list(values.query)).map(({ meta }) => meta))
+    case 'show': return print(await vault.get(id, version))
+    case 'update': {
+      if (!Number.isSafeInteger(version) || version < 1) throw new Error('Provide the current --version')
+      if (!body && !values.status && !values.stage && !values.link) throw new Error('Provide a change')
+      const link = values.link ? { id: values.link, kind: values.relation } : undefined
+      return print(await vault.update(id, version, { ...values, body, link }))
+    }
+    case 'preview': return print(await preview(vault, id))
+    case 'discard': return discard(vault, id)
+    case 'accept': {
+      if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error('Acceptance requires an interactive terminal')
+      const proposal = await preview(vault, id)
+      if (body !== undefined) proposal.body = body
+      print(proposal)
+      const terminal = createInterface({ input: process.stdin, output: process.stdout })
+      try {
+        if ((await terminal.question('Type SAVE to create this asset: ')) !== 'SAVE') {
+          return process.stdout.write('Cancelled. No asset created.\n')
+        }
+        return print(await accept(vault, id, proposal))
+      } finally {
+        terminal.close()
+      }
+    }
+    default: throw new Error('Unknown command; run grove help')
+  }
+}
+main().catch(error => {
+  process.stderr.write(`${error.message}\n`)
+  process.exitCode = 1
+})

package/src/plugin.js

@@ -0,0 +1,55 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { Vault, types } from './vault.js'
+import { propose, roles } from './proposals.js'
+
+export const name = 'grove'
+export const inject = ['tools']
+
+const output = {
+  schema: { type: 'string' },
+  render: (_args, value) => [{ type: 'text', text: value }],
+}
+
+export function apply(ctx, config = {}) {
+  const path = config.vault ?? process.env.GROVE_VAULT
+  if (!path) return
+  const vault = new Vault(path)
+  const allowed = new Set(config.readableIds ?? (process.env.GROVE_READABLE_IDS ?? '').split(',').map(id => id.trim()).filter(Boolean))
+
+  ctx.tools.register(defineTool({
+    name: 'grove_role',
+    description: 'Get the Grove collaboration guidance for a role explicitly requested by the user.',
+    parameters: { role: { type: 'string', enum: Object.keys(roles), required: true } },
+    output,
+    execute: ({ role }) => roles[role],
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'grove_propose',
+    description: 'When asked, save a draft for local human review. This tool does not create a knowledge asset.',
+    parameters: {
+      type: { type: 'string', enum: types.filter(type => !['evidence', 'research'].includes(type)), required: true },
+      body: { type: 'string', required: true },
+      title: { type: 'string' },
+      origin: { type: 'string', description: 'User-approved session reference or source description' },
+    },
+    output,
+    async execute(args) {
+      const id = await propose(vault, args)
+      return `Draft ${id}. The user can review it with grove preview ${id} in their terminal.`
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'grove_read',
+    description: 'Read one explicitly shared Grove asset by ID.',
+    parameters: { id: { type: 'string', required: true } },
+    output,
+    async execute({ id }) {
+      if (!allowed.has(id)) return 'This asset is outside the configured Grove sharing scope.'
+      const { meta, body } = await vault.get(id)
+      if (meta.status === 'archived') return 'This asset is archived.'
+      return JSON.stringify({ id, version: meta.version, title: meta.title, type: meta.type, body, source: meta.source, locator: meta.locator })
+    },
+  }))
+}

package/src/proposals.js

@@ -0,0 +1,59 @@
+import { randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { open, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { types } from './vault.js'
+
+export const roles = {
+  thinking: 'Clarify the question, expose assumptions, and offer alternative explanations.',
+  knowledge: 'Explain concepts, compare examples, and distinguish the user’s understanding from references.',
+  research: 'Identify research questions, methods, evidence gaps, and traceable sources.',
+  critical: 'Seek counterexamples and alternative explanations. Separate evidence from speculation.',
+  creation: 'Help structure the user’s argument and preserve source references. Produce a draft only on request.',
+}
+
+async function draftFile(vault, id, write = false) {
+  if (typeof id !== 'string' || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(id)) throw new Error('Invalid proposal ID')
+  const directory = await vault.folder(write)
+  const flags = write ? constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL
+    : constants.O_RDONLY | constants.O_NONBLOCK
+  return open(join(directory, `.${id}.proposal.json`), flags | constants.O_NOFOLLOW, 0o600)
+}
+
+export async function propose(vault, input) {
+  const { type, title, body, origin } = input
+  if (!types.includes(type) || ['research', 'evidence'].includes(type)) throw new Error('Unsupported proposal type')
+  if (typeof body !== 'string' || !body.trim() || Buffer.byteLength(body) > 128 * 1024) throw new Error('Invalid proposal body')
+  if (title && (typeof title !== 'string' || title.length > 300)) throw new Error('Invalid proposal title')
+  if (origin && (typeof origin !== 'string' || origin.length > 2000)) throw new Error('Invalid proposal origin')
+  const id = randomUUID()
+  const handle = await draftFile(vault, id, true)
+  try {
+    await handle.writeFile(JSON.stringify({ type, title, body, origin }))
+  } finally {
+    await handle.close()
+  }
+  return id
+}
+
+export async function preview(vault, id) {
+  const handle = await draftFile(vault, id)
+  try {
+    const stat = await handle.stat()
+    if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error('Invalid proposal file')
+    return JSON.parse(await handle.readFile('utf8'))
+  } finally {
+    await handle.close()
+  }
+}
+
+export async function accept(vault, id, proposal) {
+  const note = await vault.create({ ...proposal, origin: proposal.origin ? `AI draft confirmed by user · ${proposal.origin}` : 'AI draft confirmed by user' }, id)
+  await discard(vault, id).catch(error => { if (error.code !== 'ENOENT') throw error })
+  return note
+}
+
+export async function discard(vault, id) {
+  await preview(vault, id)
+  await unlink(join(await vault.folder(), `.${id}.proposal.json`))
+}

package/src/vault.js

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, realpath, mkdir, open, link, unlink, readdir } from 'node:fs/promises'
+import { isAbsolute, join } from 'node:path'
+import { parse, stringify } from 'yaml'
+
+export const types = ['inspiration', 'question', 'concept', 'theory', 'claim', 'evidence', 'method', 'output', 'exploration', 'research']
+export const stages = ['question', 'framework', 'evidence', 'analysis', 'judgment', 'validation', 'expression', 'review']
+const relations = ['related', 'derived', 'supports', 'refutes', 'qualifies']
+const validId = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/
+const filename = /^([a-f0-9-]{36})\.v([1-9][0-9]*)\.md$/
+const maxBytes = 1024 * 1024
+
+function required(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${label} is required`)
+  return value.trim()
+}
+
+async function directory(path, create) {
+  if (create) await mkdir(path).catch(error => { if (error.code !== 'EEXIST') throw error })
+  const stat = await lstat(path)
+  if (!stat.isDirectory() || await realpath(path) !== path) throw new Error('Grove requires a real directory')
+  return path
+}
+
+function encode(meta, body) {
+  const links = [
+    ...(meta.question ? [`[[${meta.question}.v${meta.questionVersion ?? 1}]]`] : []),
+    ...(meta.links ?? []).map(item => `${item.kind} [[${item.id}.v${item.version}]]`),
+  ]
+  return `---\n${stringify(meta, { lineWidth: 0 })}---\n\n${body}\n${links.length ? `\n<!-- grove-links -->\n${links.join('\n')}\n` : ''}`
+}
+
+async function readNote(path, id, version) {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+  try {
+    const stat = await handle.stat()
+    if (!stat.isFile() || stat.size > maxBytes) throw new Error('Invalid Grove note file')
+    const raw = await handle.readFile('utf8')
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(raw)
+    if (!match) throw new Error('Invalid Grove Markdown frontmatter')
+    const meta = parse(match[1], { maxAliasCount: 0 })
+    if (!meta || meta.id !== id || meta.version !== version || !types.includes(meta.type)) {
+      throw new Error('Grove note metadata does not match its filename')
+    }
+    return { meta, body: match[2].split('\n<!-- grove-links -->\n')[0].trim() }
+  } finally {
+    await handle.close()
+  }
+}
+
+async function publish(path, target, content) {
+  if (Buffer.byteLength(content) > maxBytes) throw new Error('Grove note exceeds the size limit')
+  const temp = join(path, `.${randomUUID()}.tmp`)
+  const handle = await open(temp, 'wx', 0o600)
+  try {
+    try {
+      await handle.writeFile(content)
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+    await link(temp, target)
+  } finally {
+    await unlink(temp)
+  }
+}
+
+export class Vault {
+  constructor(path) {
+    if (typeof path !== 'string' || !isAbsolute(path)) throw new Error('Set GROVE_VAULT to an absolute vault path')
+    this.path = path
+  }
+
+  async folder(create = false) {
+    return directory(join(await realpath(this.path), 'Grove'), create)
+  }
+
+  async inventory() {
+    const path = await this.folder().catch(error => {
+      if (error.code === 'ENOENT') return null
+      throw error
+    })
+    const entries = new Map()
+    for (const name of path ? await readdir(path) : []) {
+      const match = filename.exec(name)
+      if (!match || !validId.test(match[1])) continue
+      const version = Number(match[2])
+      if (!Number.isSafeInteger(version)) continue
+      const versions = entries.get(match[1]) ?? []
+      versions.push(version)
+      entries.set(match[1], versions)
+    }
+    return entries
+  }
+
+  async get(id, version) {
+    if (typeof id !== 'string' || !validId.test(id)) throw new Error('Invalid Grove ID')
+    const selected = version ?? Math.max(...((await this.inventory()).get(id) ?? []))
+    if (!Number.isSafeInteger(selected) || selected < 1) throw new Error('Grove note not found')
+    return readNote(join(await this.folder(), `${id}.v${selected}.md`), id, selected)
+  }
+
+  async list(query = '') {
+    const entries = await this.inventory()
+    const notes = await Promise.all([...entries].map(([id, versions]) => this.get(id, Math.max(...versions))))
+    const needle = query.toLowerCase()
+    return notes.filter(({meta, body}) => `${meta.title}\n${meta.type}\n${body}`.toLowerCase().includes(needle))
+  }
+
+  async create(input, id = randomUUID()) {
+    if (!validId.test(id)) throw new Error('Invalid Grove ID')
+    const type = input.type
+    if (!types.includes(type)) throw new Error('Unknown asset type')
+    const body = required(input.body, 'body')
+    const meta = { grove: 1, id, version: 1, type, title: input.title?.trim() || body.split('\n')[0].slice(0, 100), created: new Date().toISOString() }
+    if (input.origin) meta.origin = required(input.origin, 'origin')
+    if (type === 'question' || type === 'research') meta.status = 'open'
+    if (type === 'research') {
+      const question = await this.get(input.question)
+      if (question.meta.type !== 'question') throw new Error('Research requires a question')
+      meta.question = question.meta.id
+      meta.questionVersion = question.meta.version
+      meta.stage = stages[0]
+    }
+    if (type === 'evidence') {
+      meta.source = required(input.source, 'source')
+      meta.locator = required(input.locator, 'locator')
+    }
+    const path = await this.folder(true)
+    await publish(path, join(path, `${id}.v1.md`), encode(meta, body))
+    return { meta, body }
+  }
+
+  async update(id, expected, change) {
+    const note = await this.get(id)
+    if (note.meta.version !== expected) throw new Error('Version conflict; read the latest note and retry')
+    const { meta } = note
+    let body = note.body
+    if (change.body !== undefined) {
+      body = required(change.body, 'body')
+      if (meta.type === 'claim' && body !== note.body) {
+        meta.links = (meta.links ?? []).filter(edge => !['supports', 'refutes', 'qualifies'].includes(edge.kind))
+      }
+    }
+    if (change.status !== undefined) {
+      const allowed = meta.type === 'question' || meta.type === 'research'
+        ? ['open', 'paused', 'closed', 'archived'] : ['active', 'archived']
+      if (!allowed.includes(change.status)) throw new Error('Invalid status for this asset')
+      meta.status = change.status
+    }
+    if (change.stage !== undefined) {
+      if (meta.type !== 'research' || !stages.includes(change.stage)) throw new Error('Invalid research stage')
+      meta.stage = change.stage
+    }
+    if (change.link) {
+      const { kind, id: targetId, version } = change.link
+      if (!relations.includes(kind)) throw new Error('Invalid relationship')
+      const target = await this.get(targetId, version)
+      if (targetId === id) throw new Error('An asset cannot link to itself')
+      if (['supports', 'refutes', 'qualifies'].includes(kind) && (meta.type !== 'claim' || target.meta.type !== 'evidence')) {
+        throw new Error('Evidence relations must run from a claim to evidence')
+      }
+      const edge = { kind, id: targetId, version: target.meta.version }
+      if (!(meta.links ?? []).some(link => link.kind === kind && link.id === targetId && link.version === edge.version)) {
+        meta.links = [...(meta.links ?? []), edge]
+      }
+    }
+    meta.version++
+    meta.modified = new Date().toISOString()
+    const path = await this.folder()
+    try {
+      await publish(path, join(path, `${id}.v${meta.version}.md`), encode(meta, body))
+    } catch (error) {
+      if (error.code === 'EEXIST') throw new Error('Version conflict; read the latest note and retry')
+      throw error
+    }
+    return { meta, body }
+  }
+}