wake-bridge 0.9.0-preview.8

package/docs/operations/policies.md

@@ -0,0 +1,106 @@
+# Personal policy 文件与控制面
+
+状态：current local implementation（WB-MVP-002）。本页只描述 public policy v1；Core 中的迁移类型不扩大支持矩阵。
+
+## 1. 写一个完整 policy 文件
+
+policy 文件是一个 owner-authored snapshot，每个 id 在同一文件中只能出现一次，并必须有显式 default：
+
+```json
+{
+  "schema_version": 1,
+  "policies": [
+    {
+      "id": "ci-failures",
+      "version": 1,
+      "order": 100,
+      "match": {"source": "ci", "metadata.status": "failed"},
+      "delivery": {
+        "mode": "immediate",
+        "quiet_hours_policy": "bypass",
+        "foreground_presence_policy": "defer"
+      },
+      "batch": {"coalesce_by": "metadata.project", "max_events": 20, "window_ms": 5000},
+      "target": {"attention_channel": "engineering"},
+      "reason_code": "ci_failed"
+    },
+    {
+      "id": "default",
+      "version": 2,
+      "enabled": true,
+      "order": -1000000,
+      "match": {},
+      "delivery": {"mode": "suppress"}
+    }
+  ]
+}
+```
+
+内置 bootstrap rule 已占用 `default@1`，所以第一次安装 owner default 用 version 2。之后改变任何内容都必须同时升 version。
+同版本内容完全相同可安全重跑；同版本内容不同或安装低于现有最高版本会返回 conflict。
+
+当前 delivery mode 只有 `immediate`、`scheduled` 与 `suppress`。scheduled 使用本实例 timezone：
+
+```json
+{"mode":"scheduled","scheduled_local_time":"08:30"}
+```
+
+`debounce`、`digest`、`max_delay_ms`、`prefer_transport`、`busy_behavior` 当前会被拒绝。`resume_spread_ms` 与
+`default_action` 也不接受为 quiet-hours config。不要根据历史 DB row 推断它们已经受支持。
+
+## 2. 安装与查看
+
+```sh
+node dist/src/cli.js policy install \
+  --config /absolute/path/to/agent-space/wakebridge.config.json \
+  --file /absolute/path/to/policies.json
+
+node dist/src/cli.js policy list \
+  --config /absolute/path/to/agent-space/wakebridge.config.json
+```
+
+list 同时返回 append-only `policies` 历史、每个 id 的 `active` 最高版本和 `status`。`new_event_matching` 可能是
+`eligible | disabled | historical | legacy_unsupported`；最后一种表示升级前残留 row 只供历史解释，不会匹配新事件。
+要停用一个规则，安装更高且
+`"enabled": false` 的版本；系统不会回退到旧 enabled 版本。文件中没有出现的已有 id 不会被删除或自动停用。
+
+## 3. Test 与 preview
+
+下面的命令只读取当前安装规则：
+
+```sh
+EVENT='{"type":"job.completed","dedupe_key":"dry-run-1","resource":{"uri":"ci://build/1842"},"metadata":{"status":"failed","project":"demo"}}'
+
+node dist/src/cli.js policy test \
+  --config /absolute/path/to/agent-space/wakebridge.config.json \
+  --source ci --event "$EVENT"
+
+node dist/src/cli.js policy preview \
+  --config /absolute/path/to/agent-space/wakebridge.config.json \
+  --source ci --event "$EVENT"
+```
+
+加 `--file /path/to/candidate.json` 可在安装前评估 candidate。test 返回 matched rule；preview 还返回当前求值时间、是否
+suppress、Claim eligibility/expiry/channel、quiet/presence gate 与 batch key。两者都不登记 Event，不创建 Claim/Batch。
+
+## 4. Owner API
+
+所有 endpoint 都要求 owner token，不能把它交给 source producer：
+
+```sh
+curl --fail-with-body http://127.0.0.1:4311/v1/policies \
+  -H "Authorization: Bearer ${WAKEBRIDGE_ADMIN_TOKEN}"
+
+curl --fail-with-body -X POST http://127.0.0.1:4311/v1/policies/install \
+  -H "Authorization: Bearer ${WAKEBRIDGE_ADMIN_TOKEN}" \
+  -H "Content-Type: application/json" \
+  --data-binary @/absolute/path/to/policies.json
+
+curl --fail-with-body -X POST http://127.0.0.1:4311/v1/policies/preview \
+  -H "Authorization: Bearer ${WAKEBRIDGE_ADMIN_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"source":"ci","event":{"type":"job.completed","dedupe_key":"dry-run-api","resource":{"uri":"ci://build/1842"}}}'
+```
+
+若要 preview 未安装文件，把完整对象放在 request 的 `policy_file` 字段。source-scoped ingress、host bootstrap 与 endpoint
+lease credential 对这些 API 一律 unauthorized。

package/docs/operations/public-sdk.md

@@ -0,0 +1,87 @@
+# Public SDK boundary
+
+状态：introduced in `wake-bridge@0.9.0-preview.2`; current package `0.9.0-preview.8`。
+
+Wake Bridge 只把 event、source 与 transport 三条版本化 contract 作为第三方 package surface。Core、DB、daemon、owner
+control 与 release lifecycle 是 package 内部实现，不是可导入 subpath；历史具体产品 Host Adapter 实验也不进入当前 tarball。`exports` map 会拒绝
+`wake-bridge/core`、`wake-bridge/db`、`wake-bridge/daemon` 等路径。
+
+`wake-bridge/transport` 在 preview.4 增加 `LOCAL_HOST_PROTOCOL_VERSION=1`、`HostSessionClient` 与 delivery validator，使仓库外
+bridge service 可以通过固定 loopback wire contract 接入 stock daemon。Public client 只有 host-session lifecycle、foreground
+presence 与 activity capability，
+不暴露 Core、DB 或 owner control；内置 local HTTP transport 仍是 package private implementation。
+
+## Entrypoints
+
+```ts
+import {
+  EVENT_CONTRACT_VERSION,
+  SourcePushClient,
+  validateWakeEventInput,
+} from "wake-bridge/event";
+
+import {
+  SOURCE_ADAPTER_CONTRACT_VERSION,
+  validateSourceManifest,
+  type PullSourceAdapter,
+} from "wake-bridge/source";
+
+import {
+  HOST_ADAPTER_CONTRACT_VERSION,
+  LOCAL_HOST_PROTOCOL_VERSION,
+  HostSessionClient,
+  validateLocalHostDeliveryRequest,
+  validateHostAdapterManifest,
+  type HostAdapter,
+} from "wake-bridge/transport";
+```
+
+root `wake-bridge` 只聚合以上 contract 与 `RELEASE_VERSION`，不再导出 `WakeBridge`、DB、daemon、operator lifecycle 或
+内置 adapters。JSON event schema 通过 `wake-bridge/schema/event-v1` 提供；policy schema 继续通过
+`wake-bridge/schema/policy-v1` 提供。
+
+## Version negotiation
+
+- event payload 必须使用 `schema_version: 1`；省略时 SDK/daemon 规范化为 v1，其他版本 fail closed；
+- source manifest 必须同时声明 `contract_version: 1` 与 adapter 自己的 `version`，二者不能混用；
+- host manifest 必须声明 `contract_version: 1` 与 `adapter_version`；
+- 当前 preview 只支持 exact v1，不做猜测、向下转换或“尽力兼容”。未来扩展必须增加 supported-version set 与明确迁移。
+
+## Capability isolation
+
+Source adapter 只能返回 event page；generic push client 只能向配置时固定的 loopback `source` 路径提交 v1 event。Host adapter
+只收到 dispatch context 与 `{instance_id, daemon_origin}` lifecycle context，不会获得 Core、SQLite handle、owner token 或
+owner-control client。Transport route 可以包含该 adapter 完成投递所需的窄 route credential，但不能据此调用 owner/source API。
+
+`HostSessionClient.renewPresence()` 只接受当前 lease 与 host 自己观察到的真实用户 active edge；Core 校验 endpoint/generation 并
+生成短 TTL lease。它与 `observeActivity()` 分离，避免把 agent/model activity 或 Wake echo 冒充用户仍在前台。
+
+实际 tarball test 会在仓库外安装 package、用 TypeScript 编译 fake source + fake host、运行 validators，并逐一确认 private
+subpaths 返回 `ERR_PACKAGE_PATH_NOT_EXPORTED`。这是一条受支持 API boundary，不是对同机恶意代码的 OS sandbox；安装目录仍应
+由 operator 权限保护。
+
+## Generic push
+
+```ts
+const client = new SourcePushClient({
+  base_url: "http://127.0.0.1:4311",
+  source: "ci",
+  token: process.env.WAKEBRIDGE_SOURCE_CI_TOKEN!,
+});
+
+await client.emit({
+  schema_version: EVENT_CONTRACT_VERSION,
+  type: "job.completed",
+  dedupe_key: "build:1842",
+  resource: { uri: "ci://build/1842" },
+});
+```
+
+client 不接受公网 daemon origin，不把 `source` 写入 body，并验证返回 receipt 的 source 与 event contract。Credential 的创建、
+轮换与 daemon 配置见 [source ingress](source-ingress.md)；SDK 不提供 owner API。
+
+## Reference source
+
+`wake-bridge/source/group-chat` 提供只依赖公开 feed contract 的 `GroupChatSourceAdapter` 与 mapper。仓内 conformance fixture 已覆盖
+mention/reply mapping、opaque cursor、schema fencing 与 duplicate-page rejection。真实独立 Group Chat feed canary 仍是外部验收项；
+在取得实际 feed endpoint、principal credential 与 provider version 之前，不得把 fixture 结果写成 production support。

package/docs/operations/release-lifecycle.md

@@ -0,0 +1,154 @@
+# Release install, upgrade, backup, and rollback
+
+状态：engineering preview current runbook（2026-09-07）。Wake Bridge 发布包只支持 Host Adapter Contract；
+完成本页不等于任何具体 agent 产品获得兼容性或时延保证。
+
+## 支持矩阵
+
+| 项目 | 当前承诺 |
+| --- | --- |
+| package | `wake-bridge`，npm dist-tag `preview` |
+| license | Apache-2.0 |
+| OS | macOS / `darwin`；Linux profile 与验证明确延后 |
+| CPU | arm64、x64 |
+| Node.js | 20 或更高 |
+| SQLite CLI | 3.33.0 或更高，且必须支持 `-json` |
+| topology | 每个 Agent Space 一个本地 instance / SQLite DB |
+| schema | current 8；显式升级支持 6、7 → 8 |
+| host integration | out-of-process Host Adapter Contract v1；不内置具体 agent 产品支持 |
+
+当前 npm manifest 会在非 macOS 平台拒绝安装，避免把尚未做 systemd、OS matrix 和真实 canary 的 Linux 暗示为已支持。
+SQLite 是外部 runtime prerequisite，不由 npm 安装；3.33.0 是 CLI 加入 JSON output mode 的版本。
+
+## 从 tarball 干净安装
+
+发布前先生成并审计 tarball：
+
+```bash
+npm pack --json
+npm install --global ./wake-bridge-0.9.0-preview.8.tgz
+wakebridge release-preflight
+```
+
+正式发布到 preview channel 后，等价安装命令是：
+
+```bash
+npm install --global wake-bridge@preview
+```
+
+初始化一个私有 Agent Space：
+
+```bash
+wakebridge init \
+  --data-dir "$HOME/Library/Application Support/WakeBridge/default" \
+  --instance-id default \
+  --owner-id your-agent \
+  --timezone Asia/Shanghai
+
+wakebridge release-preflight \
+  --config "$HOME/Library/Application Support/WakeBridge/default/wakebridge.config.json"
+```
+
+`init` 生成 mode-600 config、owner credential 与 SQLite DB，不在 stdout 打印 token。它不会覆盖已有 config/DB。
+
+## macOS LaunchAgent
+
+安装真实 profile，但不替 operator 静默启动进程：
+
+```bash
+wakebridge service install \
+  --config "$HOME/Library/Application Support/WakeBridge/default/wakebridge.config.json" \
+  --port 4311
+```
+
+返回值包含精确 `plist_path`、`load_command` 和 `unload_command`。plist 只保存 Node、已安装 CLI、config path、loopback
+host/port 与日志位置，不复制 owner token。核对后执行返回的 `launchctl bootstrap ...`，再检查：
+
+同机多个 Agent Space 必须为每个 instance 选择不同 loopback port；profile 不会猜测或自动抢占已有端口。
+
+```bash
+curl --fail -H "Authorization: Bearer $WAKEBRIDGE_ADMIN_TOKEN" http://127.0.0.1:4311/health
+wakebridge doctor --config "$HOME/Library/Application Support/WakeBridge/default/wakebridge.config.json"
+```
+
+同一 instance 不允许覆盖已有 plist。升级 package 后 plist 的全局安装路径保持不变；若 npm 安装布局改变，先 bootout、
+`service uninstall`，再由新 bin 重装 profile。
+
+## 一致性备份
+
+daemon 可运行时执行 online SQLite snapshot：
+
+```bash
+wakebridge backup \
+  --config /absolute/path/wakebridge.config.json \
+  --output /absolute/path/backups/pre-upgrade-0.9.0-preview.8
+```
+
+输出目录必须事先不存在。命令使用 SQLite `VACUUM INTO` 生成一致性 DB，随后执行 `quick_check`，写入 mode-600
+`manifest.json` 与 SHA-256。备份只包含 durable DB 和无 secret manifest，不复制带 owner token 的 config；config 应由 operator
+另行放进加密 secret backup。不要用文件复制代替 online snapshot，也不要只复制 `-wal` 或 `-shm`。
+
+## 显式 upgrade
+
+普通 `daemon`、`inspect`、MCP 或其他 Core 打开路径看到旧 schema 时会 fail closed，并要求显式 upgrade；它们不会先改 DB
+再补备份。
+
+```bash
+# 先停止/bootout daemon，避免 migration 期间仍有业务写入。
+wakebridge upgrade \
+  --config /absolute/path/wakebridge.config.json \
+  --backup-output /absolute/path/backups/pre-schema-8 \
+  --confirm-offline
+```
+
+upgrade 顺序固定：`offline assertion → WAL checkpoint → quick_check → verified backup → migrate → schema 8 + quick_check`。任何 migration/验证失败都会用刚创建的
+backup 自动恢复原 DB。schema 8 再执行为 no-op；schema 6、7 是本 preview 的升级基线；更旧或更新的 schema 都拒绝。
+
+## 数据 rollback / restore
+
+restore 是 offline、instance-fenced 的破坏性操作：
+
+```bash
+# 1. 执行 service install 曾返回的 unload_command，并确认 daemon 已停止。
+# 2. 恢复备份；confirm 值必须与 config 中 instance_id 完全一致。
+wakebridge restore \
+  --config /absolute/path/wakebridge.config.json \
+  --backup /absolute/path/backups/pre-schema-8 \
+  --rollback-output /absolute/path/backups/pre-restore-current \
+  --confirm-instance-id default \
+  --confirm-offline
+```
+
+restore 先为当前 DB 再做一份 verified rollback snapshot，校验目标 manifest、checksum、schema 与 integrity，然后原子替换 DB；
+失败时自动把刚才的 current snapshot 放回。恢复旧 schema 后不要再用新 daemon 打开 DB：先安装与该 schema 配套的旧 tarball，
+或重新执行新版本显式 upgrade。
+
+代码 rollback 与数据 rollback 是两个独立动作：
+
+1. bootout 新 daemon；
+2. 保存 inspect/日志证据；
+3. 必要时用 `restore` 恢复 pre-upgrade DB；
+4. `npm install --global /absolute/path/old-release.tgz`；
+5. 用旧版本的 `release-preflight/doctor` 验证后再 bootstrap LaunchAgent。
+
+## Uninstall
+
+先执行 install 返回的 `unload_command`，再删除 profile：
+
+```bash
+wakebridge service uninstall --config /absolute/path/wakebridge.config.json
+npm uninstall --global wake-bridge
+```
+
+`service uninstall` 只删除该 instance 的 plist，明确保留 config、DB、backups 和 logs。数据删除不属于 uninstall；如确需删除，
+由 operator 在完成 verified backup 后另行处理明确目录。
+
+## Artifact 内容
+
+tarball 包含运行 CLI 所需的 compiled `dist/src`、event/policy schema、LICENSE、README，以及当前 install/policy/source/SDK/operator/local-host runbook。
+tests、具体产品 Host Adapter 实验实现与文档、历史私有运行环境 artifacts、私有现场记录、源码和开发依赖不进入发布包。`exports` 只公开 root contract aggregation、
+`event`、`source`、`transport`、Group Chat reference source 与 schemas；Core/DB/daemon/operator/local-HTTP modules 只供 package 自己的 CLI 使用。
+边界和仓库外 fixture 见 [public SDK](public-sdk.md)；运行态与 dead-letter recovery 见
+[operator control](operator-control.md)。
+[Out-of-process host integration](out-of-process-host-adapter.md) 使用同一个 public transport subpath，但具体 runtime adapter 不因进入
+artifact 而获得 supported tier。

package/docs/operations/source-connectors.md

@@ -0,0 +1,163 @@
+# Source Connector 安装与本地协议
+
+状态：current Source Connector contract。通用 runner 已通过隔离 fixture；是否可启用仍由 connector catalog、
+identity verify、from-now bootstrap 与该来源的真实 UAT 分别决定。本文不证明任何 Host Adapter 的兼容性。
+
+## 谁保管什么
+
+```text
+provider credential → Source Connector process
+connector-local bearer → Wake Bridge daemon environment
+event facts + resource refs + identity-fenced opaque cursor → Wake Bridge SQLite
+```
+
+外部 provider 不需要为 Wake Bridge 改 server、增加 scope 或签发专用 credential。Connector 是 owner 安装的适配进程，可以复用 provider 已有 OAuth、API key、MCP 登录、webhook 或本地 session。Wake Bridge 不获得这些上游 secret。
+
+隔离不会把 broad credential 变成 read-only。Connector 被攻破时仍可能继承上游权限；能用 provider 原生最小 scope 时应优先使用。Manifest 只是如实声明和验收依据，不是进程沙箱。
+
+## Connector protocol
+
+Connector 监听一个独占 loopback origin，并用独立 bearer 验证每个请求：
+
+```http
+GET /v1/manifest
+Authorization: Bearer <connector-local-token>
+```
+
+```json
+{
+  "id": "example-notifications",
+  "version": "1.0.0",
+  "subject_ref": "example:principal:owner-confirmed-id",
+  "binding_fingerprint": "sha256:<64-lowercase-hex>",
+  "read_side_effects": "none",
+  "credential_custody": "connector",
+  "upstream_credential_breadth": "broad",
+  "upstream_credential_scopes": ["provider.account"],
+  "connector_capabilities": ["notifications.read"]
+}
+```
+
+```http
+POST /v1/poll
+Authorization: Bearer <connector-local-token>
+Content-Type: application/json
+
+{"cursor": null, "limit": 100}
+```
+
+可选的首次安装接口：
+
+```http
+POST /v1/bootstrap
+Authorization: Bearer <connector-local-token>
+Content-Type: application/json
+
+{"mode": "from-now"}
+```
+
+它只返回当前水位 cursor，不返回或创建 event。Wake Bridge 只在 source 尚无 checkpoint 时接受一次 `from-now` bootstrap。Agent 必须把刚刚 verify 到的 `subject_ref` 与 `binding_fingerprint` 原样回传，Bridge 不替 agent 猜身份。
+
+```json
+{
+  "events": [
+    {
+      "type": "mention",
+      "occurred_at": "2026-08-29T05:00:00.000Z",
+      "dedupe_key": "notification:123",
+      "resource": {"uri": "example://notification/123", "cursor": 123},
+      "metadata": {"notification_id": 123}
+    }
+  ],
+  "next_cursor": {"high_watermark": 123},
+  "has_more": false
+}
+```
+
+Event 不得携带 provider credential、完整邮件/消息正文或任意模型指令。`resource.uri` 指回权威来源，agent 醒来后使用自己的授权工具读取。
+
+## Wake Bridge 配置
+
+配置文件不保存 token 值，只保存 token 环境变量名：
+
+```json
+{
+  "version": 1,
+  "sources": [
+    {
+      "id": "example-notifications",
+      "base_url": "http://127.0.0.1:4391",
+      "token_env": "WAKEBRIDGE_SOURCE_EXAMPLE_TOKEN",
+      "enabled": true,
+      "poll_interval_ms": 60000,
+      "max_backoff_ms": 900000,
+      "limit": 100,
+      "max_pages_per_cycle": 4
+    }
+  ]
+}
+```
+
+Daemon 用 `WAKEBRIDGE_SOURCE_CONNECTORS_FILE=/absolute/path/sources.json` 读取它。`base_url` 必须是无 path/query/credential 的 loopback HTTP origin。Connector token 只放在 daemon 的 mode-600 env 文件或等价 secret store，不放命令行、配置 JSON、数据库或日志。
+
+安装者只负责提供已安装 connector 槽位和本地运行能力。上游 MCP URL、OAuth 或 API key 由 owning agent 使用 connector/provider 自己的配置机制填写和保管；Wake Bridge 不扫描宿主、shell 或浏览器配置，也不复制、修改这些值。
+
+## 验证与运行
+
+```bash
+wakebridge source-validate --connectors /absolute/path/sources.json
+wakebridge source-bootstrap example-notifications \
+  --mode from-now \
+  --connectors /absolute/path/sources.json \
+  --expected-subject-ref example:principal:owner-confirmed-id \
+  --expected-binding-fingerprint sha256:<64-lowercase-hex>
+wakebridge source-once example-notifications \
+  --connectors /absolute/path/sources.json \
+  --db /private/tmp/wakebridge-source-probe.sqlite
+wakebridge daemon \
+  --config /absolute/path/to/agent-space/wakebridge.config.json \
+  --connectors /absolute/path/sources.json
+```
+
+`source-once` 会真实调用 connector，并把标准化 event/checkpoint 写入指定 DB；它不是“只打印、不落库”的假 dry-run。首次验收应显式使用隔离 DB。状态不是 `healthy` 时命令以非零退出。
+
+Agent 日常使用 MCP 自助完成：
+
+1. `attention_source_status` 查看已安装槽位；
+2. 启动自己配置好的 connector 后，调用 `attention_source_verify`；
+3. 首次接入用 `attention_source_bootstrap`，已有错误/旧身份 checkpoint 用 `attention_source_rebind`；两者都必须回传 verify 结果中的准确身份；
+4. 调用 `attention_source_enable` 开始轮询；需要停用时调用 `attention_source_disable`。enable/disable 会持久化并跨 daemon 重启保留。
+
+Source control MCP 只接受 source id、非敏感身份确认、checkpoint revision 与 rebind reason，不接受任何 provider URL 或 credential。Opaque cursor 也不会经 status/verify 暴露给 agent。
+
+对应的 authenticated loopback 管理 API：
+
+```text
+GET  /v1/sources
+POST /v1/sources/:source_id/poll
+POST /v1/sources/:source_id/verify
+POST /v1/sources/:source_id/bootstrap
+POST /v1/sources/:source_id/rebind
+POST /v1/sources/:source_id/enable
+POST /v1/sources/:source_id/disable
+```
+
+两者都走现有 admin token。Health 只公开 source、状态、时间、错误分类、连续失败数、下一次轮询、checkpoint revision 与上一轮计数，不回显 endpoint、token、manifest scopes 或 event body。
+
+## 失败语义
+
+- connector 暂时不可达、HTTP 5xx/429：`backoff`，指数退避到配置上限；
+- 缺 connector token、401/403、manifest/checkpoint identity 不符、读取有副作用、schema/cursor/event 错误：`needs_attention`，停止自动轮询；
+- 每次 poll 都核对 live `subject_ref` + `binding_fingerprint`；身份变化时禁止沿用旧 cursor，只能在 disabled 状态显式 rebind，并把旧 checkpoint 归档；
+- page 全部 event durable 后才 CAS 推进 checkpoint；
+- commit 前崩溃会重放同页，`(source, dedupe_key)` 吸收重复；
+- `has_more` 每轮最多读取 `max_pages_per_cycle` 页，避免一个高流量 source 饿死其他来源。
+
+## 首次生产接入 gate
+
+1. 在隔离环境对真实 connector 做 manifest、auth、read-side-effect 与 cursor conformance。
+2. 由 owner 明确选择 `from-now` 或受控 backfill；`from-now` 用显式 bootstrap 写入空 checkpoint，不手改 SQLite。
+3. 用隔离 DB 先验证 bootstrap + `source-once`，确认旧通知不生成 event、event 不含正文/secret 且 resource 可回读；不要先指向 production DB。Production bootstrap 时 source 配置必须保持 `enabled=false`，完成后再受控启用，避免 poll 与空 checkpoint 竞争。
+4. 备份 Wake Bridge DB、release、LaunchAgent/env；安装 connector 自己的 rollback。
+5. 先启单一 source，以一条专用无敏感通知做 canary。
+6. 验收 event → claim → wake → ack/consume receipts；不自动回复、不改 provider read state。

package/docs/operations/source-ingress.md

@@ -0,0 +1,108 @@
+# Source-scoped event ingress
+
+状态：current local implementation。该入口适合 loopback producer、webhook sidecar 或同机 job runner；它只授予固定 source 的
+event ingest authority，不授予 owner control。
+
+## 1. 初始化一个 Agent Space
+
+```sh
+node dist/src/cli.js init \
+  --data-dir /absolute/path/to/agent-space \
+  --instance-id agent-a \
+  --owner-id agent-a-owner \
+  --timezone Asia/Shanghai
+```
+
+命令创建私有 config 与 DB，不在 stdout 打印 owner token。先检查本地 readiness：
+
+```sh
+node dist/src/cli.js doctor \
+  --config /absolute/path/to/agent-space/wakebridge.config.json
+```
+
+不要把 `wakebridge.config.json` 提交到 git、复制给 source producer 或传给任何 agent host。
+
+## 2. 配置窄 source credential
+
+token 只放环境变量：
+
+```sh
+export WAKEBRIDGE_SOURCE_CI_TOKEN="<至少 32 字符的随机 token>"
+```
+
+reference file 只保存 env 名与固定 source：
+
+```json
+{
+  "version": 1,
+  "credentials": [
+    {
+      "id": "ci-primary",
+      "source": "ci",
+      "token_env": "WAKEBRIDGE_SOURCE_CI_TOKEN"
+    }
+  ]
+}
+```
+
+启动 daemon：
+
+```sh
+node dist/src/cli.js daemon \
+  --config /absolute/path/to/agent-space/wakebridge.config.json \
+  --source-credentials /absolute/path/to/source-credentials.json \
+  --host 127.0.0.1 \
+  --port 4311
+```
+
+## 3. Producer 登记 event
+
+```sh
+curl --fail-with-body \
+  -X POST http://127.0.0.1:4311/v1/ingress/ci/events \
+  -H "Authorization: Bearer ${WAKEBRIDGE_SOURCE_CI_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "schema_version": 1,
+    "type": "job.completed",
+    "dedupe_key": "build:1842",
+    "attention_channel_hint": "default",
+    "resource": {"uri": "ci://build/1842"},
+    "metadata": {"result": "success"}
+  }'
+```
+
+请求 body 不接受 `source`。Bridge 从已经验证的 token 与 URL path 注入 `source=ci`。同一个 token 不能访问
+`/v1/ingress/other/events`，也不能访问 `/v1/inspect`、`/v1/tick` 或其他 owner API。
+
+`POST /v1/events` 仍存在，但它是 owner-admin surface，用于本实例 owner 的手动与管理式操作；不要把 owner token 发给普通
+producer。
+
+## 4. 轮换与撤销
+
+source token 不进 DB。安全轮换流程：
+
+1. 为同一个 source 增加第二个 credential id 与新的 token env；
+2. 重启 daemon；
+3. producer 切换到新 token；
+4. 从 reference file/env 删除旧 token并再次重启。
+
+owner config-backed token 使用：
+
+```sh
+node dist/src/cli.js owner-token-rotate \
+  --config /absolute/path/to/agent-space/wakebridge.config.json
+```
+
+轮换后重启 daemon。命令不会打印新 token；若设置了 `WAKEBRIDGE_ADMIN_TOKEN`，必须先 unset。config-backed profile 不允许
+CLI/env 改写固定的 instance、owner、DB、timezone 或 admin token，避免同一 credential 被带到另一个 Agent Space。
+
+## Development escape hatch
+
+只有不带任何真实数据的本地 fixture 才可使用：
+
+```sh
+node dist/src/cli.js daemon --unsafe-no-auth --host 127.0.0.1
+```
+
+它不能绑定 `0.0.0.0` 或其他非 loopback 地址，也不能让 host session 或 scoped source endpoint 绕过各自 credential。

package/docs/operations/templates/botlingknows-connector.env.example

@@ -0,0 +1,5 @@
+# Copy to a mode-600 file outside git. Never put either value in argv.
+BOTLINGKNOWS_MCP_URL=<existing-full-streamable-http-mcp-url>
+# Non-secret label chosen and confirmed by this connector's owner.
+BOTLINGKNOWS_SUBJECT_REF=botlingknows:principal:<owner-confirmed-id>
+WAKEBRIDGE_CONNECTOR_TOKEN=<separate-local-connector-token>

package/docs/operations/templates/sources.json.example

@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "sources": [
+    {
+      "id": "botlingknows",
+      "base_url": "http://127.0.0.1:4391",
+      "token_env": "WAKEBRIDGE_SOURCE_BOTLING_TOKEN",
+      "enabled": false,
+      "poll_interval_ms": 60000,
+      "max_backoff_ms": 900000,
+      "limit": 50,
+      "max_pages_per_cycle": 4
+    }
+  ]
+}