From 860e20fe7045e361b8cf491d414852dbc036f22e Mon Sep 17 00:00:00 2001
From: BBQ <bbq@BBQdeMacBook-Air.local>
Date: Wed, 11 Feb 2026 22:13:27 +0800
Subject: [PATCH] docs(docs): add concepts and style guides for VitePress site

- Add concepts: identity-and-binding, index (en/zh)
- Add style: terminology (en/zh)
- Update index and zh/index
- Update .vitepress/config.ts
---
 docs/docs/.vitepress/config.ts                | 48 ++++++++++++++++++-
 docs/docs/concepts/identity-and-binding.md    | 41 ++++++++++++++++
 docs/docs/concepts/index.md                   | 21 ++++++++
 docs/docs/index.md                            | 23 ++++++++-
 docs/docs/style/terminology.md                | 40 ++++++++++++++++
 docs/docs/zh/concepts/identity-and-binding.md | 41 ++++++++++++++++
 docs/docs/zh/concepts/index.md                | 21 ++++++++
 docs/docs/zh/index.md                         | 23 ++++++++-
 docs/docs/zh/style/terminology.md             | 40 ++++++++++++++++
 9 files changed, 294 insertions(+), 4 deletions(-)
 create mode 100644 docs/docs/concepts/identity-and-binding.md
 create mode 100644 docs/docs/concepts/index.md
 create mode 100644 docs/docs/style/terminology.md
 create mode 100644 docs/docs/zh/concepts/identity-and-binding.md
 create mode 100644 docs/docs/zh/concepts/index.md
 create mode 100644 docs/docs/zh/style/terminology.md

diff --git a/docs/docs/.vitepress/config.ts b/docs/docs/.vitepress/config.ts
index 7a3152c2..ef051e48 100644
--- a/docs/docs/.vitepress/config.ts
+++ b/docs/docs/.vitepress/config.ts
@@ -27,19 +27,63 @@ export default defineConfig({
     sidebar: {
       '/': [
         {
-          text: 'Hello Memoh',
+          text: 'Overview',
           link: '/index.md'
         },
         {
           text: 'Getting Started',
           link: '/getting-started.md'
+        },
+        {
+          text: 'Core Concepts',
+          items: [
+            {
+              text: 'Concepts Overview',
+              link: '/concepts/index.md'
+            },
+            {
+              text: 'Accounts and Linking',
+              link: '/concepts/identity-and-binding.md'
+            }
+          ]
+        },
+        {
+          text: 'Documentation Style Guide',
+          items: [
+            {
+              text: 'Terminology Rules',
+              link: '/style/terminology.md'
+            }
+          ]
         }
       ],
       '/zh/': [
         {
-          text: 'Hello Memoh',
+          text: '文档总览',
           link: '/zh/index.md'
         },
+        {
+          text: '核心概念',
+          items: [
+            {
+              text: '概念总览',
+              link: '/zh/concepts/index.md'
+            },
+            {
+              text: '账号模型与绑定',
+              link: '/zh/concepts/identity-and-binding.md'
+            }
+          ]
+        },
+        {
+          text: '文档写作规范',
+          items: [
+            {
+              text: '术语规范',
+              link: '/zh/style/terminology.md'
+            }
+          ]
+        }
       ]
     },
 
diff --git a/docs/docs/concepts/identity-and-binding.md b/docs/docs/concepts/identity-and-binding.md
new file mode 100644
index 00000000..bb7982b6
--- /dev/null
+++ b/docs/docs/concepts/identity-and-binding.md
@@ -0,0 +1,41 @@
+# Accounts and Linking
+
+## Account Model
+
+Memoh treats platform accounts and system accounts as two different entities:
+
+- **Platform Account (`ChannelIdentity`)** is the user's account on an external access platform (for example, a TG account), not a Memoh internal account.
+- **System Account (`User`)** is an internal account in Memoh.
+
+A platform account can exist before linking.  
+`bind` is the mechanism that links these two account types.
+
+## Access Platform and Bot
+
+- **Access Platform (`channel`)** is where inbound messages come from.
+- **Bot** is an authorization and resource boundary inside Memoh.
+
+Bots are managed by system accounts, while inbound messages are produced by platform accounts.
+
+## Why Linking Is Account-Scoped
+
+Account linking exists to establish account ownership, not to grant bot resources directly:
+
+- It links platform accounts and system accounts independent of any single bot.
+- It avoids coupling account linking with member management semantics.
+- It keeps bot authorization and account linking decoupled.
+
+## Linking Flow (Current Consensus)
+
+1. A user requests a bind code under their own system account.
+2. The platform account sends the code from a supported access-platform conversation.
+3. Memoh validates the code and links platform account to system account.
+4. Bot membership and authorization are handled by their own flows.
+
+## Bot Type Semantics
+
+- **Public bot**: supports member-based collaboration.
+- **Personal bot**: conceptually single-owner, and should not rely on member semantics.
+
+> Note: The conceptual model is documented here as product semantics.  
+> Runtime behavior may still be in transition as implementations are tightened.
diff --git a/docs/docs/concepts/index.md b/docs/docs/concepts/index.md
new file mode 100644
index 00000000..e6d54718
--- /dev/null
+++ b/docs/docs/concepts/index.md
@@ -0,0 +1,21 @@
+# Core Concepts
+
+This section defines the core account and access concepts used by Memoh.
+
+## Concept Map
+
+- **System Account (`User`)**: an internal account in Memoh.
+- **Platform Account (`ChannelIdentity`)**: a user's account on an external access platform, not a Memoh account (for example, the user's Telegram (TG) account).
+- **Bot**: an access and resource boundary managed by a system account.
+- **Account Linking (`bind`)**: the process that links a platform account to a system account.
+
+## Why This Matters
+
+Memoh receives messages from external access platforms, but manages permissions and resources inside the system.
+To keep these concerns clear, the model separates platform accounts from system accounts, while keeping bot access control as an independent concern.
+
+Terminology note: "platform account" always means the user's account on that platform (such as TG), not an internal account created by this project.
+
+## In This Chapter
+
+- [Accounts and Linking](/concepts/identity-and-binding.md)
diff --git a/docs/docs/index.md b/docs/docs/index.md
index dbb041ff..076fe5a9 100644
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -1 +1,22 @@
-# Hello Memoh
+# Memoh Documentation
+
+Memoh is a multi-member, long-memory, containerized AI agent system.
+
+## Documentation Sections
+
+- [Getting Started](/getting-started.md)
+- [Core Concepts](/concepts/index.md)
+
+## For Contributors
+
+- [Terminology Rules](/style/terminology.md)
+
+## Current Focus
+
+The current documentation iteration focuses on account semantics:
+
+- Distinguishing system accounts and platform accounts
+- Explaining why account linking is account-scoped
+- Clarifying the relationship between account linking and bot access
+
+Note: "platform account" means the user's account on external platforms (for example, TG), not a Memoh account.
diff --git a/docs/docs/style/terminology.md b/docs/docs/style/terminology.md
new file mode 100644
index 00000000..a510d624
--- /dev/null
+++ b/docs/docs/style/terminology.md
@@ -0,0 +1,40 @@
+# Terminology Rules
+
+> Audience: documentation contributors and maintainers.
+> This page defines writing terms. It is not product user guidance.
+
+## Canonical Terms
+
+- **System Account (`User`)**: the account inside Memoh.
+- **Platform Account (`ChannelIdentity`)**: the user's account on an external access platform, not a Memoh account.
+- **Access Platform (`channel`)**: the external platform carrying inbound messages.
+- **Account Linking (`bind`)**: linking a Platform Account to a System Account.
+- **Bind Code**: one-time code used for account linking.
+- **Bot**: resource and authorization boundary managed by a System Account.
+
+## Preferred Wording
+
+- Write **"platform account"** instead of "actor" in user-facing docs.
+- Write **"access platform"** instead of "channel" when describing product behavior.
+- Keep code aliases in parentheses on first mention:
+  - `Platform Account (ChannelIdentity)`
+  - `System Account (User)`
+  - `Account Linking (bind)`
+
+## Disallowed or Discouraged Terms
+
+- Avoid plain **actor** in conceptual docs (except when quoting code symbols).
+- Avoid ambiguous **platform user** phrasing (it does not distinguish system vs platform account).
+- Avoid wording that implies Platform Account is created inside Memoh.
+
+## Example Sentences
+
+- Correct: "A platform account is the user's TG account, not a Memoh account."
+- Correct: "Account linking binds a platform account to a system account."
+- Incorrect: "Actor is a user in Memoh."
+
+## Contributor Checklist
+
+- Is every "account" term clearly scoped (system vs platform)?
+- Is "channel" replaced by "access platform" in prose?
+- Are code aliases kept only as parenthetical references?
diff --git a/docs/docs/zh/concepts/identity-and-binding.md b/docs/docs/zh/concepts/identity-and-binding.md
new file mode 100644
index 00000000..c7d275d3
--- /dev/null
+++ b/docs/docs/zh/concepts/identity-and-binding.md
@@ -0,0 +1,41 @@
+# 账号模型与绑定
+
+## 账号模型
+
+Memoh 将平台账号与系统账号视为两类不同实体：
+
+- **平台账号（`ChannelIdentity`）** 是用户在外部接入平台上的账号（例如飞书账号），不是 Memoh 内部账号。
+- **系统账号（`User`）** 是 Memoh 系统内账号。
+
+平台账号在初始阶段可以不绑定系统账号。  
+`bind` 的职责是完成这两类账号的关联。
+
+## 接入平台与 Bot
+
+- **接入平台（`channel`）** 是入站消息来源。
+- **Bot** 是系统内的授权与资源边界。
+
+Bot 由系统账号管理，入站消息由平台账号产生。
+
+## 为什么账号绑定是账号作用域
+
+账号绑定的目标是建立账号归属关系，而不是直接发放 bot 资源权限：
+
+- 它只负责平台账号与系统账号的绑定；
+- 不把账号绑定与成员管理语义耦合在一起；
+- 让 bot 访问控制保持独立、可演进。
+
+## 账号绑定流程（当前共识）
+
+1. 用户以自己的系统账号申请 bind code；
+2. 平台账号在支持的接入平台会话中发送 code；
+3. 系统校验 code，完成平台账号到系统账号的绑定；
+4. bot 成员与授权由独立流程处理。
+
+## Bot 类型语义
+
+- **Public bot**：支持成员协作语义。
+- **Personal bot**：语义上应为单 owner，不应依赖成员机制。
+
+> 注：本文档记录的是产品语义与共识方向。  
+> 部分运行时细节仍可能处于收敛阶段。
diff --git a/docs/docs/zh/concepts/index.md b/docs/docs/zh/concepts/index.md
new file mode 100644
index 00000000..fe931ca6
--- /dev/null
+++ b/docs/docs/zh/concepts/index.md
@@ -0,0 +1,21 @@
+# 核心概念
+
+本章节用于定义 Memoh 的核心账号与访问概念。
+
+## 概念图
+
+- **系统账号（`User`）**：Memoh 系统内账号。
+- **平台账号（`ChannelIdentity`）**：用户在外部接入平台上的账号，不是 Memoh 系统内账号（例如用户的飞书账号）。
+- **Bot**：由系统账号管理的资源与访问边界。
+- **账号绑定（`bind`）**：把平台账号关联到系统账号的过程。
+
+## 为什么重要
+
+Memoh 需要同时处理外部接入平台消息与系统内权限控制。  
+因此我们明确区分平台账号与系统账号，并将 bot 授权与账号绑定解耦。
+
+术语说明：文档中的“平台账号”统一指用户在对应平台上的真实账号（如飞书账号），不指本项目内部账号。
+
+## 本章内容
+
+- [账号模型与绑定](/zh/concepts/identity-and-binding.md)
diff --git a/docs/docs/zh/index.md b/docs/docs/zh/index.md
index dbb041ff..5a068f92 100644
--- a/docs/docs/zh/index.md
+++ b/docs/docs/zh/index.md
@@ -1 +1,22 @@
-# Hello Memoh
+# Memoh 文档
+
+Memoh 是一个多成员、长记忆、容器化的 AI Agent 系统。
+
+## 文档章节
+
+- [快速开始](/getting-started.md)
+- [核心概念](/zh/concepts/index.md)
+
+## 面向文档贡献者
+
+- [术语规范](/zh/style/terminology.md)
+
+## 当前维护范围
+
+当前文档先聚焦账号语义与访问控制：
+
+- 区分系统账号与平台账号
+- 解释为什么账号绑定是账号作用域
+- 说明账号绑定与 bot 访问控制之间的关系
+
+说明：“平台账号”指用户在外部平台上的真实账号（例如飞书账号），不是 Memoh 系统账号。
diff --git a/docs/docs/zh/style/terminology.md b/docs/docs/zh/style/terminology.md
new file mode 100644
index 00000000..5d76ec7c
--- /dev/null
+++ b/docs/docs/zh/style/terminology.md
@@ -0,0 +1,40 @@
+# 术语规范
+
+> 适用对象：文档编写者与维护者。
+> 本页用于统一写作语义，不是面向最终用户的功能说明。
+
+## 规范术语
+
+- **系统账号（`User`）**：Memoh 系统内账号。
+- **平台账号（`ChannelIdentity`）**：用户在外部接入平台上的账号，不是 Memoh 内账号。
+- **接入平台（`channel`）**：承载入站消息的外部平台。
+- **账号绑定（`bind`）**：把平台账号关联到系统账号的过程。
+- **绑定码（Bind Code）**：用于账号绑定的一次性代码。
+- **Bot**：由系统账号管理的资源与授权边界。
+
+## 推荐写法
+
+- 面向产品语义时，优先写 **“平台账号”**，不要直接写 actor。
+- 描述业务行为时，优先写 **“接入平台”**，不要直接写 channel。
+- 首次出现保留技术别名，后续可只用中文术语：
+  - 平台账号（`ChannelIdentity`）
+  - 系统账号（`User`）
+  - 账号绑定（`bind`）
+
+## 禁用或不推荐写法
+
+- 在概念文档中直接使用 **actor**（除非明确引用代码符号）。
+- 使用含糊表述如 **“平台用户”**（未区分系统账号与平台账号）。
+- 写出“平台账号是 Memoh 内部账号”这类错误语义。
+
+## 示例
+
+- 正确：**“平台账号是用户在飞书上的账号，不是 Memoh 系统账号。”**
+- 正确：**“账号绑定用于把平台账号关联到系统账号。”**
+- 错误：**“Actor 是 Memoh 里的用户。”**
+
+## 自检清单
+
+- 是否明确区分了系统账号与平台账号？
+- 叙述中是否将 channel 表述为接入平台？
+- 是否仅在首处保留技术别名？