docs: add distribution strategy page with three doors

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `doc` are documented here.
 
 ## [Unreleased]
 
+### Added
+
+- Add `docs/DISTRIBUTION.md`: the three distribution doors (local single-player, gated
+  ByteFolk-hosted SaaS, guided self-hosting), their identity, cost, and compliance
+  boundaries, the authentication consistency principle across deployments, and the
+  guidance surfaces in `doc init`, README, and `doc doctor`.
+
 ### Fixed
 
 - Persist like identity per viewer using a server-side `PubDocLike` table and cookie-based

README.md

@@ -14,7 +14,8 @@
 保留稳定的 API 与可追溯修改边界。
 
 项目的北极星、边界与验收场景见 [GOAL.md](GOAL.md)，当前实现契约见
-[SPEC.md](SPEC.md)。
+[SPEC.md](SPEC.md)。分发形态与三扇门（本地单人 / ByteFolk 托管 SaaS / 引导式自部署）
+见 [docs/DISTRIBUTION.md](docs/DISTRIBUTION.md)。
 
 > [!WARNING]
 > `doc` 仍处于 experimental 阶段。接口、数据模型和部署方式可能变化，请勿把它

docs/DISTRIBUTION.md

@@ -0,0 +1,85 @@
+# doc distribution
+
+`doc` 与 `mem` 的核心价值只在"别人也够得着"时成立：人与人共享文档、跨 Agent 共享记忆，
+前提都是存在一个多人可达的部署。而默认状态下用户不会部署。因此产品显式提供三扇门，
+并由 CLI 与文档引导用户选择其一，而不是把"部署"当作文档角落里的前提条件。
+
+## The three doors
+
+| 门                         | 给谁                       | 身份与认证边界                                                                         | 成本与合规谁背                                               | 当前缺口                                                           |
+| -------------------------- | -------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------ |
+| 本地单人（现状默认）       | 个人写作 + 与 AI 协作      | 回环自验（本地开发邮箱），不构成真实身份                                               | 无人背                                                       | 文案诚实化：明确标注单人模式，不让用户误以为本地即共享             |
+| ByteFolk 托管 SaaS         | "登录就用"的用户           | ByteFolk 统一身份：GitHub 任意用户 + 邮箱 magic link；org 成员资格只 gating 我们自己人 | 我们：基础设施、运维、用户内容与个人信息保管、境内域名则备案 | 多租户隔离工程、隐私政策、最低付费基础设施；**门未开，见开启条件** |
+| 引导式自部署（现阶段主推） | 有服务器或有合规要求的团队 | 部署者自定边界：他的 GitHub org、他的 SMTP、未来的 OIDC                                | 部署者：自己的服务器、域名、发信通道与数据合规               | 部署向导、一键模板、`doctor` 门位报告                              |
+
+## Door 1: local single-player
+
+现状默认路径（`doc init` + `doc dev`）服务个人写作与 AI 协作。它必须被诚实标注为
+单人模式：本地邮件闭环（开发邮箱）只用于验证权限流程，不产生真实身份，也不产生
+人与人共享。任何界面与文档不得暗示本地运行即具备协作能力。
+
+## Door 2: ByteFolk-hosted SaaS (gated)
+
+SaaS 默认不开。开启条件是需求信号：若干个团队明确表达"让我登录就用、我愿意付钱"。
+原因不是工程，而是责任：开了 SaaS 我们就从工具方变成数据保管方，用户文档落在我们
+盘上，个人信息保护、隐私政策、数据驻留随之而来。
+
+开启前必须就绪：
+
+- 多租户隔离。当前实现是单租户部署形态，租户边界是工程前提而非配置项；
+- 隐私政策与数据驻留说明；
+- 最低付费基础设施。免费托管档（闲置休眠、限期数据库）只能承载试验，不能承载
+  真实用户数据；
+- 统一身份落地：GitHub 任意用户 + 邮箱 magic link，org 成员资格仅用于我们自己的
+  管理面。
+
+## Door 3: guided self-hosting (current main path)
+
+自部署就是产品定位本身：部署者控制数据库、对象存储、模型凭据和认证边界（见
+[GOAL.md](../GOAL.md)）。我们要做的是把这条路做顺：
+
+- 部署向导：生产拓扑（web + collaboration + PostgreSQL + HTTPS 反代）加 DNS、
+  发信、OAuth 逐项检查，把"还缺哪几样"变成机器可读的报告；
+- 一键模板：容器平台 blueprint、永久免费虚拟机 runbook 等各一份，覆盖零成本试验
+  到正式落点；
+- `doc doctor` 报告当前实例处于哪扇门、距离下一扇门还缺什么。
+
+参考组合（runbook 维护细节）：零成本试验用免费托管加免费数据库，接受休眠与限期；
+正式落点用整机虚拟机加自动 HTTPS 与免费域名解析，数据落在部署者自己盘上；升级
+路径为付费轻量服务器或 SaaS。
+
+## mem follows the same doors
+
+`mem` 与 `doc` 同构：单机是个人记忆库，部署了才是团队资产层。自部署与 SaaS 均以
+同一拓扑打包两者；`doc` 与 `mem` 之间保持显式 API 连接，不共享隐藏数据库状态
+（见 [GOAL.md](../GOAL.md)）。分发、身份与合规边界按本页同一套门执行。
+
+## Authentication consistency principle
+
+一致性不是一个中心账号，而是同一套认证协议走遍所有部署：
+
+- 用户可能连 ByteFolk SaaS，也可能连自己团队的自部署实例。客户端（roleweave）的
+  登录因此是**按部署的会话管理**，类比 git 客户端按主机记凭证：SaaS 只是一个预置
+  部署地址；
+- 一致的是身份映射与协议（GitHub OAuth、邮箱 magic link、未来的 OIDC），不是账号
+  库。三扇门共用一套认证代码，客户端不为每扇门重做登录；
+- 开放条目：roleweave 客户端的按部署登录需求尚未开单，登记后与本页互引。
+
+## Guidance surfaces
+
+- `doc init` 的第一个问题即路由：就你自己 / 你团队有自己的基础设施 / 想让我们托管；
+- README 与落地页三扇门并列呈现，自部署不埋进文档深处；
+- `doc doctor` 输出门位与缺口清单，作为升级与排障的统一入口。
+
+## Security boundaries for ByteFolk operators
+
+- 部署与注册只用个人账户与个人身份，不触碰任何雇主内部基础设施；
+- 服务器与任何内部网络之间零隧道；
+- 实例只存放 ByteFolk 或用户自己的内容，不存放第三方雇主的代码、文档与数据；
+- 免费档供给风险（配额缩水、限期资源）作为已知风险管理，兜底手段是下一条。
+
+## Upgrade and migration
+
+三扇门之间的移动是一次完整迁移，属于产品承诺（见 [GOAL.md](../GOAL.md) 北极星第
+5 条：完整迁移到另一套部署），不是运维人情。试验档到正式档、自部署到 SaaS 的路径
+均由导出与导入能力支撑。