SagaSmithAI · dajiaohuang · Aug 29, 2026 · Aug 29, 2026
diff --git a/README-en.md b/README-en.md
@@ -1,11 +1,24 @@
 # SagaSmith Core
 
-[中文](README.md) · [English](README-en.md) · [Website](https://sagasmithai.github.io) · [Platform overview](https://github.com/SagaSmithAI/.github/blob/main/profile/README.md) · [Hosted service](https://github.com/SagaSmithAI/SagaSmith-service) · [Content catalog](https://github.com/SagaSmithAI/SagaSmith-dnd-content-library)
+[中文](README.md) · [English](README-en.md) · [Website](https://sagasmithai.github.io) · [Platform overview](https://github.com/SagaSmithAI/.github/blob/main/profile/README.md) · [SagaSmith Web](https://github.com/SagaSmithAI/SagaSmith-Web) · [Content catalog](https://github.com/SagaSmithAI/SagaSmith-dnd-content-library)
 
 **The system-neutral runtime for an AI-native TTRPG platform.** `sagasmith-core` gives rules systems, MCP servers, and clients persistent campaigns, actor knowledge, branching timelines, content ingestion, rule packs, and retrieval. It contains no D&D or Call of Cthulhu rules.
 
 > World state should be verifiable, timelines should branch, and every actor should know only what they actually know.
 
+## Choose a path
+
+| Goal | Start here |
+|---|---|
+| Use Core from a system package | `pip install sagasmith-core`, then see the minimal service construction below |
+| Integrate a current rules system | [D&D](https://github.com/SagaSmithAI/sagasmith-dnd) · [CoC](https://github.com/SagaSmithAI/sagasmith-coc) · [Narrative](https://github.com/SagaSmithAI/sagasmith-narrative) |
+| Understand data and transaction boundaries | [Architecture](docs/ARCHITECTURE.md) · [Quickstart](docs/QUICKSTART.md) |
+| Build or import content packages | [Content Packages](docs/CONTENT_PACKAGES.md) |
+| Configure retrieval and caches | [Retrieval](docs/RETRIEVAL.md) |
+
+Python 3.11+ is required. Most end users should install a system MCP/Local Kit
+instead of accessing Core's database directly.
+
 ## What it provides
 
 - **Campaigns and characters** — system-neutral records, namespaced sheets, revisions, principals, and roles.
@@ -32,6 +45,13 @@ flowchart TB
 
 Core does not decide GM style, MCP exposure, or system-specific rules. Skills own operating guidance, system runtimes own rules, MCP servers own the capability/storage boundary, and Core owns consistent data semantics.
 
+SagaSmith Web never reads authoritative D&D, CoC, or Narrative tables directly.
+After a domain MCP commits successfully, a rebuildable revisioned projection or
+receipt boundary may feed Web read models; failed, rolled-back, and no-op writes
+must not fabricate cache invalidation. Core vector, page, and embedding caches are
+also rebuildable performance layers, never authorities for revisions, events,
+facts, actor knowledge, or snapshots.
+
 ## Current domain implementations
 
 | Domain | Current repository | Components versioned together |
@@ -55,6 +75,13 @@ requester whose campaign role is evaluated. Neither identity may impersonate the
 other, and audit receipts retain the original fields. Explicit legacy v1 keeps its
 single caller/authorization-subject interpretation.
 
+This does not make Core an MCP Host or server. Hosts mint delegation, domain MCPs
+revalidate campaign role, authority, revision, and idempotency on every call, and
+Core provides system-neutral parsing, persistence, and transactions. Stable tool
+catalogs, bounded Host projection, stdio/HTTP adaptation, and tool-call policy
+belong above Core; never store a connection-bound principal or campaign session
+here.
+
 ## Shareable content formats
 
 `sagasmith.content-package` v2 is the only public exchange format and uses the
@@ -177,6 +204,21 @@ pytest --cov
 ruff check .
 ```
 
+## Upgrade and rollback
+
+Before deployment, stop writers and take a consistent backup after the SQLite
+WAL settles, or use the external database's native consistent backup. Startup
+should run `Database.upgrade_schema()`/Alembic to the current head. Snapshot
+schema v8 full-document records have no in-place downgrade. A data rollback
+restores the backup, Core, the matching Domain/MCP components, and the upstream
+component lock as one compatible set. Rolling back only the MCP SDK or replacing
+only the database is not a supported recovery.
+
+Tests and fixtures must not use production campaigns, real credentials, or paid
+external services. Install document, OCR, vector, and embedding extras explicitly
+for the capability exercised by CI or deployment; a missing optional dependency
+is not data corruption.
+
 Further reading: [Architecture](docs/ARCHITECTURE.md) · [Quickstart](docs/QUICKSTART.md) · [Retrieval](docs/RETRIEVAL.md)
 
 ## License

diff --git a/README.md b/README.md
@@ -1,11 +1,24 @@
 # SagaSmith Core
 
-[中文](README.md) · [English](README-en.md) · [官网](https://sagasmithai.github.io) · [平台总览](https://github.com/SagaSmithAI/.github/blob/main/profile/README.md) · [托管服务](https://github.com/SagaSmithAI/SagaSmith-service) · [内容目录](https://github.com/SagaSmithAI/SagaSmith-dnd-content-library)
+[中文](README.md) · [English](README-en.md) · [官网](https://sagasmithai.github.io) · [平台总览](https://github.com/SagaSmithAI/.github/blob/main/profile/README.md) · [SagaSmith Web](https://github.com/SagaSmithAI/SagaSmith-Web) · [内容目录](https://github.com/SagaSmithAI/SagaSmith-dnd-content-library)
 
 **AI 原生 TTRPG 平台的系统无关运行时。** `sagasmith-core` 为规则系统、MCP 服务和 UI 提供持久化战役、角色知识、分支时间线、内容导入、规则包与检索能力；它本身不包含 D&D 或 CoC 规则。
 
 > 世界状态应当可验证，时间线应当可分支，每个角色只应知道自己真正知道的事。
 
+## 从这里开始
+
+| 目标 | 入口 |
+|---|---|
+| 在系统包中使用 Core | `pip install sagasmith-core`，再看下方最小服务构造 |
+| 接入当前规则系统 | [D&D](https://github.com/SagaSmithAI/sagasmith-dnd) · [CoC](https://github.com/SagaSmithAI/sagasmith-coc) · [Narrative](https://github.com/SagaSmithAI/sagasmith-narrative) |
+| 理解数据与事务边界 | [Architecture](docs/ARCHITECTURE.md) · [Quickstart](docs/QUICKSTART.md) |
+| 创建或导入内容包 | [Content Packages](docs/CONTENT_PACKAGES.md) |
+| 配置检索与 cache | [Retrieval](docs/RETRIEVAL.md) |
+
+需要 Python 3.11+。大多数最终用户应安装对应的系统 MCP/Local Kit，而不是直接操作
+Core 数据库。
+
 ## 它解决什么
 
 普通聊天记忆无法充当长期战役数据库：它不知道哪条时间线有效，也无法可靠区分 GM、玩家、PC 和 NPC 的视角。SagaSmith Core 把这些问题建模为显式服务：
@@ -34,6 +47,11 @@ flowchart TB
 
 Core 不负责主持风格、MCP 工具暴露或具体规则裁决。Agent Skills 负责工作流，系统运行时负责规则，MCP 服务负责能力与存储边界，Core 负责一致的数据语义。
 
+SagaSmith Web 不直接读取 D&D、CoC 或 Narrative 的权威表。领域 MCP 成功提交后可以通过
+可重建的 revisioned projection/receipt 边界为 Web 提供读取模型；failed、rolled-back 或
+no-op 写入不得伪造 cache 失效。Core 的向量、页面与 embedding cache 同样只是可重建性能层，
+不能替代 revision、事件、事实、角色知识或 Snapshot 权威。
+
 ## 当前领域实现
 
 | 领域 | 当前仓库 | 同仓版本化组件 |
@@ -58,6 +76,10 @@ requester。两者不得互相冒充，审计 receipt 会保留原始身份字
 campaign、requester role、authority、revision 与幂等性；Core 只提供系统无关的身份
 解析、持久化与事务保证。
 
+Core 不是 MCP Host、MCP server，也不管理 `tools/list`。稳定目录、Host 端小型工具投影、
+stdio/HTTP 协议适配与每次工具调用授权都属于各领域 MCP/Agent；不要在 Core 中引入连接级
+principal 或 campaign session。
+
 ## 可分享内容格式
 
 `sagasmith.content-package` v2 是唯一公开交换格式，文件扩展名为
@@ -176,6 +198,17 @@ pytest --cov
 ruff check .
 ```
 
+## 升级与回滚
+
+部署前先停止写入，并在 SQLite WAL 收敛后创建一致性数据库备份；外部数据库使用其原生
+一致性备份。应用启动应通过 `Database.upgrade_schema()`/Alembic 升级到当前 head。
+Snapshot schema v8 的完整文档记录没有原地 downgrade；需要数据回滚时，必须把备份、Core、
+领域 Domain/MCP 与上游 component lock 恢复为匹配的一组。只回滚 MCP SDK 或只替换数据库
+都不是受支持的恢复方式。
+
+测试与 fixture 不应使用生产战役、真实凭据或付费外部服务。文档、OCR、向量与 embedding
+extras 在 CI/部署中应按实际能力显式安装，不能把缺少可选依赖误报成数据损坏。
+
 更多资料：[Architecture](docs/ARCHITECTURE.md) · [Quickstart](docs/QUICKSTART.md) · [Retrieval](docs/RETRIEVAL.md)
 
 ## License