@tensorix/metahub 0.5.7 → 0.6.0

package/README.md

@@ -1,35 +1,38 @@
 # metahub
 
-**Give your AI a local knowledge base.**
+**A local-first workspace you and your agents share.**
 
 English · [简体中文](./README.zh-CN.md)
 
-metahub is a local-first knowledge base CLI built on Bun + SQLite. It gives an AI agent a durable, syncable working memory: Notion-style **typed tables** for structured data, **Markdown documents** for long-form knowledge, and a `Read / Edit / Write`-style editing interface. Everything lives on your own machine under `~/.metahub/` — offline on one machine, and consistent across many.
+metahub brings **Markdown notes**, **typed tables**, and **simple agent-built sites** into one shared workspace. You work in the desktop app or browser; your agent reads and writes the same notes and tables through the CLI. Ask your agent to build a small site to collect feedback or show hub data, then bring that input into the work. Built on Bun + SQLite, everything starts on your own machine under `~/.metahub/`, with offline use and sync across your devices.
 
 <p align="center">
-  <img src="./docs/assets/webui.png" alt="metahub WebUI — block-level document editing" width="100%">
+  <img src="./website/public/assets/documents-v0.5.4-en.png" alt="metahub shared workspace — document editor" width="100%">
 </p>
 
-> Requires [Bun](https://bun.sh). Use `bunx`, a global `mh` install, or a standalone binary.
+[Download desktop](#install) · [Connect an agent](#connect-an-agent)
+
+> The CLI and library use [Bun](https://bun.sh). Desktop downloads and standalone binaries are also available.
 
 ## Why metahub
 
-- **Built for AI read/write** — `doc read` returns the body plus a version token; `doc edit --old/--new` does an anchored find-and-replace that sends only the delta. Refer to anything by id prefix or name — no pasting full ids.
-- **Structured and unstructured in one place** — typed tables (rows, columns, 9 property types, including `relation` and `doc` columns that link rows to other rows and to documents) for tasks, ledgers, contacts; Markdown documents for notes and specs.
-- **Local-first and syncable** — your data sits on your own disk and works offline; multiple machines merge cleanly, and edits to different paragraphs don't clobber each other.
-- **GUI and API included** — `mh --server` starts a browser WebUI (browse, inline-edit, full-text search), a `/api/*` REST interface, and auto-generated OpenAPI docs. Open views refresh **live** when the CLI writes, so you and your agent can work on the same hub at once.
-- **Auditable agent work** — every write an agent makes is tagged `ai`; `mh audit` is the whole-hub change feed, and `mh audit revert <txn>` undoes one logical change group without clobbering edits made since.
+- **Write a starting point** — a note, requirement, or task board gives you and your agent something concrete to work on. Markdown notes sit beside typed tables with 9 property types, including links between records and documents.
+- **See what AI changes** — agent writes land in the workspace you open in the app. Open views refresh when the CLI writes, so you can review the result and make the next decision.
+- **Revise, then continue** — change a priority or rewrite a requirement in the UI. Your agent explicitly re-reads the note or table to pick up your revision; `doc read` returns a version token and `doc edit --old/--new` sends an anchored, incremental edit.
+- **Keep the work yours** — notes and tables live on your own disk and work offline. Pair devices to sync both ways; concurrent edits to different paragraphs merge cleanly.
+- **Trace and undo agent work** — agent writes carry an `ai` tag. `mh audit` shows the whole-hub change feed; `mh audit revert <txn>` undoes a logical change group while preserving later edits.
 
 <p align="center">
-  <img src="./docs/assets/webui-table.png" alt="metahub WebUI — typed tables with select, multi-select, and checkbox columns" width="100%">
+  <img src="./website/public/assets/tables-v0.5.4-en.png" alt="metahub shared workspace — typed tables" width="100%">
 </p>
 
-> Want to see the UI? Install the [desktop app](#install) or run `mh --server` and open `http://localhost:7777/`.
+> Download the [desktop app](#install), or run `mh --server` and open `http://localhost:7777/`. [Connect an agent](#connect-an-agent) to read and write the same workspace.
 
 ## Quick start
 
 ```bash
-bunx @tensorix/metahub init                          # create ~/.metahub
+bun install -g @tensorix/metahub                    # install the mh command (requires Bun)
+mh init                                            # create ~/.metahub
 mh db create "Tasks"                                 # create a table → returns an id like db_tasks-k3f9c1
 mh use tasks                                         # set the "current db"; record/prop commands target it
 mh prop add Title  --type text
@@ -55,11 +58,13 @@ Output adapts to the audience: a terminal (human) gets tables / Markdown, a pipe
 
 | Form | Install | For |
 | --- | --- | --- |
-| **Desktop app** (GUI) | `brew install --cask tensorix/tap/metahub-app` | A graphical, Notion-like experience |
-| **CLI** | `brew install tensorix/tap/metahub-cli`, or `npm i -g @tensorix/metahub`, or `bunx @tensorix/metahub <cmd>` | AI agents and the command line |
+| **Desktop app** (GUI) | `brew install --cask tensorix/tap/metahub-app` | Write and manage your workspace on macOS |
+| **CLI** | `brew install tensorix/tap/metahub-cli`, or `bun install -g @tensorix/metahub`, or `bunx @tensorix/metahub <cmd>` | AI agents and the command line |
 | **Library** (Bun) | `bun add @tensorix/metahub` | Calling metahub from your own Bun program |
 | **Standalone binary** | download for your platform, `chmod +x`, run | No runtime to install |
 
+The package-based CLI and library require [Bun](https://bun.sh). The desktop app and standalone binaries bundle their runtime.
+
 ```ts
 // As a library: every core capability is exported from the package root
 import { openMetahub, createDatabase, createRecord, search } from "@tensorix/metahub";
@@ -67,6 +72,20 @@ import { openMetahub, createDatabase, createRecord, search } from "@tensorix/met
 
 Platforms: `darwin-arm64` / `darwin-x64` / `linux-x64` / `linux-arm64` / `windows-x64` / `windows-arm64`. Library API: see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
+## Connect an agent
+
+After installing the CLI, add the usage guide to the agent you work with:
+
+```bash
+mh init --codex   # install the $mh skill for Codex
+# or
+mh init --claude  # install the /mh skill for Claude Code
+```
+
+For other agents, provide [SKILL.md](./SKILL.md) and access to the CLI or API. MetaHub supplies the workspace; your external agent runs the model and decides when to read or write.
+
+Try: “Read my event plan, draft an invitation in the workspace, and tell me what you changed.” After revising the plan yourself, ask: “Re-read the latest plan and update the invitation.” Review the changes in the app or with `mh audit`.
+
 ## Sync across machines
 
 Run a server on one machine and sync from another. Documents merge at the paragraph level, so concurrent edits to different parts of the same document combine cleanly.
@@ -155,6 +174,8 @@ The WebUI is an installable PWA. Open **Settings → 离线副本** and this bro
 
 ## Documentation
 
+- [Brand and slogan](./assets/brand/README.md) — product narrative, bilingual copy, palette roles, and logo assets.
+- [Website design](./website/DESIGN.md) — interactive scenarios, App fidelity, localization, and motion rules.
 - [System design](./docs/system-design/) — architecture, data model, capabilities, usage flows.
 - [Contributing](./CONTRIBUTING.md) — local development, build, release, project layout, library API.
 - [Desktop app](./apps/desktop/README.md) — Electron shell + Bun sidecar.

package/README.zh-CN.md

@@ -1,28 +1,38 @@
 # metahub
 
-**给你的 AI 一个本地知识库。**
+**你和 Agent 共享的本地优先工作空间。**
 
 [English](./README.md) · 简体中文
 
-metahub 是基于 Bun + SQLite 的本地优先知识库 CLI，给 AI agent 一份持久、可同步的工作记忆：用 notion 风格的**类型化数据表**装结构化数据，用 **markdown 文档**装长文本知识，再配一套像 `Read / Edit / Write` 的编辑接口。数据全部存在你本机的 `~/.metahub/`，单机离线可用，多机之间保持一致。
+metahub 把 **Markdown 笔记**、**类型化数据表**与 **Agent 构建的简单站点**放进同一个共享工作空间。你用桌面 App 或浏览器界面，Agent 通过 CLI 读写同一份笔记与数据表。还可以让 Agent 搭建小站点，收集反馈或展示工作空间的数据，再把这些输入带回日常工作。基于 Bun + SQLite，数据从本机的 `~/.metahub/` 开始，离线可用，也能在你的设备之间同步。
 
-> 运行时依赖 [Bun](https://bun.sh)。用 `bunx`、全局安装后的 `mh`，或下载独立二进制都行。
+<p align="center">
+  <img src="./website/public/assets/documents-v0.5.4-en.png" alt="metahub 共享工作空间 — 文档编辑" width="100%">
+</p>
+
+[下载桌面版](#获取--安装) · [连接 Agent](#连接-agent)
+
+> CLI 与库依赖 [Bun](https://bun.sh)，也可下载桌面版或独立可执行文件。
 
 ## 为什么用它
 
-- **为 AI 读写而设计** —— `doc read` 先返回正文 + 版本号，`doc edit --old/--new` 做锚定查找替换、只传增量；引用一律支持 id 前缀 / 名字，不必粘完整 id。
-- **结构化 + 非结构化一处管** —— 类型化数据表（行 / 列，9 种属性类型，含把行关联到别的行的 `relation` 列和关联到文档的 `doc` 列）放任务、流水、联系人；markdown 文档放设计稿、笔记。
-- **本地优先、可同步** —— 数据在你自己的磁盘上，离线可用；多台机器干净合并，改不同段落互不覆盖。
-- **自带 GUI 与 API** —— `mh --server` 一条命令起浏览器 WebUI（浏览 / 行内编辑 / 全文搜索）+ `/api/*` REST 接口 + 自动生成的 OpenAPI 文档。CLI 一写，**打开着的界面自己就更新**，人和 agent 可以同时开着同一个库干活。
-- **Agent 的改动可追可撤** —— agent 驱动的每一次写入都带 `ai` 标记；`mh audit` 是全库变更流，`mh audit revert <txn>` 按逻辑变更组撤销，且不会顺手抹掉你之后做的修改。
+- **写下一个起点** —— 笔记、需求或任务看板，让你和 Agent 有具体的事情可做。Markdown 笔记与类型化数据表放在一起，支持 9 种属性类型，包括记录之间、记录与文档之间的关联。
+- **看见 AI 的改动** —— Agent 写入的进展落在你打开的同一个工作空间中。CLI 写入后，已打开的界面会刷新，方便你查看结果、做下一步判断。
+- **你来调整，接着往下做** —— 在界面里改优先级、重写需求。Agent 明确重新读取笔记或数据表，才能接上你的修改；`doc read` 返回版本号，`doc edit --old/--new` 做锚定增量编辑。
+- **工作始终属于你** —— 笔记和数据表在自己的磁盘上，离线照常用。配对设备后双向同步，不同段落的并发修改可以合并。
+- **Agent 的改动可追可撤** —— Agent 写入带有 `ai` 标记；`mh audit` 展示全库变更流，`mh audit revert <txn>` 按逻辑变更组撤销，并保留之后的编辑。
+
+<p align="center">
+  <img src="./website/public/assets/tables-v0.5.4-en.png" alt="metahub 共享工作空间 — 类型化数据表" width="100%">
+</p>
 
-<!-- TODO 截图：docs/assets/webui.png（WebUI）、docs/assets/desktop.png（桌面端） -->
-> 想看界面？装上[桌面 App](#获取--安装)，或运行 `mh --server` 后打开 `http://localhost:7777/`。
+> [下载桌面版](#获取--安装)，或运行 `mh --server` 后打开 `http://localhost:7777/`。[连接 Agent](#连接-agent)，一起读写同一个工作空间。
 
 ## 快速开始
 
 ```bash
-bunx @tensorix/metahub init                       # 创建 ~/.metahub
+bun install -g @tensorix/metahub                 # 安装 mh 命令（需要 Bun）
+mh init                                         # 创建 ~/.metahub
 mh db create "Tasks"                              # 建一张表 → 返回 id，如 db_tasks-k3f9c1
 mh use tasks                                      # 设为「当前库」，之后 record/prop 免带库参数
 mh prop add Title  --type text
@@ -48,11 +58,13 @@ mh doc append <ref> --body "追加段落"             # 也有 prepend
 
 | 形态 | 安装 | 适合 |
 | --- | --- | --- |
-| **桌面 App**（GUI） | `brew install --cask tensorix/tap/metahub-app` | 想要图形界面、像 notion 那样用 |
-| **CLI** | `brew install tensorix/tap/metahub-cli`，或 `npm i -g @tensorix/metahub`，或免安装 `bunx @tensorix/metahub <cmd>` | AI agent / 命令行 |
+| **桌面 App**（GUI） | `brew install --cask tensorix/tap/metahub-app` | 在 macOS 上编辑和管理工作区 |
+| **CLI** | `brew install tensorix/tap/metahub-cli`，或 `bun install -g @tensorix/metahub`，或免安装 `bunx @tensorix/metahub <cmd>` | AI agent / 命令行 |
 | **库**（Bun） | `bun add @tensorix/metahub` | 在自己的 Bun 程序里直接调用 |
 | **独立二进制** | 下载对应平台文件，`chmod +x` 后直接运行 | 无运行时环境 |
 
+通过包安装的 CLI 和库需要 [Bun](https://bun.sh)；桌面 App 和独立二进制已自带运行时。
+
 ```ts
 // 作为库使用：所有 core 能力从包根导出
 import { openMetahub, createDatabase, createRecord, search } from "@tensorix/metahub";
@@ -60,6 +72,20 @@ import { openMetahub, createDatabase, createRecord, search } from "@tensorix/met
 
 支持平台：`darwin-arm64` / `darwin-x64` / `linux-x64` / `linux-arm64` / `windows-x64` / `windows-arm64`。库 API 详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
 
+## 连接 Agent
+
+安装 CLI 后，把使用指南装到你正在用的 Agent 中：
+
+```bash
+mh init --codex   # 安装 Codex 的 $mh skill
+# 或者
+mh init --claude  # 安装 Claude Code 的 /mh skill
+```
+
+其他 Agent 可以读取 [SKILL.md](./SKILL.md)，通过 CLI 或 API 接入。MetaHub 提供工作区；模型运行和何时读写由外部 Agent 负责。
+
+可以先试：「读取我的活动计划，在工作区里起草邀请文案，并告诉我改了什么。」亲手修改计划后，再说：「重新读取最新计划，更新邀请。」在 App 或 `mh audit` 中检查改动。
+
 ## 多机同步
 
 在一台机器起服务端，另一台与它同步。文档按段落级合并，所以并发改同一篇文档的不同部分能干净合并。
@@ -140,6 +166,8 @@ mh sync http://a-host:7777
 
 ## 文档
 
+- [品牌与 slogan](./assets/brand/README.md) —— 产品叙事、中英文文案、配色分工与 Logo 资源。
+- [官网设计](./website/DESIGN.md) —— 交互场景、App 对齐、双语排版与动效规则。
 - [系统设计](./docs/system-design/) —— 架构、数据模型、能力清单、使用流程。
 - [贡献指南](./CONTRIBUTING.md) —— 本地开发、构建、发布、目录结构、库 API。
 - [桌面 App](./apps/desktop/README.md) —— Electron 壳 + Bun sidecar。