feat(hub): embed agent images via Feishu upload + release v0.0.36 (#14 )

feat(hub): embed agent images via Feishu upload + release v0.0.36 Merge pull request #14
feat(hub): embed agent images via Feishu upload + release v0.0.36
2026-07-20 18:42:38 +08:00 · 2026-07-20 10:40:03 +00:00 · 2026-07-20 17:21:14 +08:00 · 2026-07-20 09:07:26 +00:00 · 2026-07-19 20:16:09 +08:00 · 2026-07-19 20:08:44 +08:00
134 changed files with 5661 additions and 2327 deletions
@@ -1,12 +1,12 @@
 name: checker check

 # Builds and lints the Rust implementation crates under crates/ (the rule-based
-# checker that "stands in Lean's position" at product runtime).
+# lesson checker).
 #
-# Like spec-check, this is an INTERNAL gate on the implementation's own health
-# (does it build, pass its tests, satisfy clippy + rustfmt?). It is NOT a
-# spec-to-implementation conformance gate — implementations align to the Lean
-# contract by human review, not by CI. See the repo README.
+# This is an INTERNAL gate on the implementation's own health
+# (does it build, pass its tests, satisfy clippy + rustfmt?). There is no
+# decision-to-implementation conformance gate — implementations align to the
+# ADRs by human review, not by CI. See the repo README.

 on:
  push:
@@ -1,8 +1,8 @@
 name: hub check

 # Builds, type-checks, and tests the Hub TS package under hub/.
-# The Hub is the Feishu-group collaboration + agent runtime half
-# (spec/System implementation). This is an INTERNAL gate on the Hub's own
+# The Hub is the Feishu-group collaboration + agent runtime half.
+# This is an INTERNAL gate on the Hub's own
 # health, like checker-check is for the Rust half.

 on:
@@ -1,20 +0,0 @@
-name: spec check
-
-# Builds the Lean semantic master spec under spec/.
-# This is an INTERNAL well-formedness gate (does the contract type-check?),
-# NOT a spec-to-implementation conformance gate — implementations align to the
-# contract by human review, not by CI. See repo README.
-
-on:
-  push:
-  pull_request:
-  workflow_dispatch:
-
-jobs:
-  spec-check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-      - uses: leanprover/lean-action@v1
-        with:
-          lake-package-directory: spec
@@ -1,7 +1,3 @@
-# Lean / Lake build artifacts (spec/ has its own .gitignore too)
-.lake/
-**/.lake/
-
 # Rust / Cargo build artifacts (repo-wide cargo workspace at root)
 /target
 **/*.pdf
@@ -29,7 +29,7 @@ workload brakes.

 The full current-state inventory, accepted behavior, and release evidence are
 recorded in [Initial abuse and capacity controls](../assets/initial-abuse-capacity-controls.md),
-with the durable decision in ADR-0022 and `Spec.System.Capacity`. Numerical
+with the durable decision in ADR-0022. Numerical
 ceilings remain open until production-like calibration.

 The implementation frontier is:
@@ -7,6 +7,6 @@ Blocked by: 01, 02, 03, 04, 05, 06, 07, 09, 10, 11, 12, 13, 14, 15, 16, 17, 18,
 ## Question

 After the readiness investigations and resulting fixes are resolved, can one
-repeatable release procedure prove build/test/spec health, deploy a clean
+repeatable release procedure prove build/test health, deploy a clean
 production-like environment, exercise critical tenant and agent journeys,
 verify observability and recovery, and either roll forward or roll back safely?
@@ -8,7 +8,7 @@ Blocked by: 04

 Separate or unify run-bound audit entries, pre-run security/permission events,
 structured messages, and operational recovery events without weakening
-`Spec.System.Audit`'s pinned AuditEntry-to-run relation. Decide durability,
+the pinned AuditEntry-to-run relation. Decide durability,
 failure, retention, and query semantics; then enforce referential integrity and
 observable/recoverable writes instead of silently swallowing lost evidence.
 Do not merge these customer Project/Run records with ADR-0023's already-decided
@@ -40,9 +40,7 @@ an off-host recovery key, an incident and reason, and issues only an expiring
 Emergency Platform Grant.

 The complete accepted decision and implementation divergences are in
-[ADR-0023](../../../docs/adr/0023-platform-administrator-identity-and-audit.md).
-The pinned semantic invariants are in
-[`Spec.System.PlatformAdministration`](../../../spec/Spec/System/PlatformAdministration.lean),
+[ADR-0023](../../../docs/adr/0023-platform-administrator-identity-and-audit.md),
 and the canonical terms are in [`CONTEXT.md`](../../../CONTEXT.md).

 Exact numeric session/invitation/step-up limits and browser mechanics remain
@@ -1,29 +1,25 @@
 # AGENTS.md —— agent 操作手册(全 repo)

-本 repo 是 monorepo。先读根 `README.md` 的"宪法"5 条,那是一切工作的前提。本文件是给在这里干活的 coding agent 的纪律。
+本 repo 是 monorepo。先读根 `README.md` 的"宪法"4 条,那是一切工作的前提。本文件是给在这里干活的 coding agent 的纪律。

 ## 这个 repo 是什么

- `spec/` 是一份**人机共识的契约**(Lean 语义母本),是产品语义的上游参照。
- 其余部件(将来的 `spec/` 外文件夹)是**向 `spec/` 对齐的实现**。
+- `docs/adr/` 是系统级决策的唯一权威来源;`CONTEXT.md` 是平台语言词汇表;代码注释把关键不变量锚到 ADR 编号,可 grep。
 - `hub/` 的平台层按 SaaS 形态演进:`Organization` 是 tenant root;`Project`/`Team`
-  必须归属 org,TEAM→PROJECT 授权不得跨 org(见 ADR-0020 / `Spec.System.Organization`)。
+  必须归属 org,TEAM→PROJECT 授权不得跨 org(见 ADR-0020)。
 - org 后台 project explorer 里 `Folder` 是透明组织节点,不是权限资源;project 仍是权限边界。
-  普通老师可在飞书群自助建 project 但受 org policy 控制(见 ADR-0021 /
-  `Spec.System.ProjectWorkspace`)。
+  普通老师可在飞书群自助建 project 但受 org policy 控制(见 ADR-0021)。
 - 每个 org 自选 BYOK 或平台托管 model provider connection;平台托管也必须是该 org
-  独享的 key/base URL,不得让无关 org 共用 process-global provider key(见 ADR-0021 /
-  `Spec.System.Organization`)。
+  独享的 key/base URL,不得让无关 org 共用 process-global provider key(见 ADR-0021)。
 - Feishu/provider secret 使用本地版本化 master-key keyring 的信封加密;生产由 systemd
  credential 注入,运行时只允许显式 org/project scope 的 fail-closed resolver,不得回退
  process-global credential;Agent child 只接收 run-scoped loopback proxy capability,
-  不接收 org provider credential(见 ADR-0024 / `Spec.System.Organization`)。
+  不接收 org provider credential(见 ADR-0024)。
 - 生产容量按不可突破的 platform ceiling 与 org 可下调 policy 分层;有效限制取两者较低值。
-  Agent admission 必须持久、有界、跨 org 公平且显式背压(见 ADR-0022 /
-  `Spec.System.Capacity`)。
+  Agent admission 必须持久、有界、跨 org 公平且显式背压(见 ADR-0022)。
 - 平台管理员只通过独立的 platform-owned 飞书应用与可撤销 Platform Session 认证,不复用
  客户 `User`/org membership;平台写操作与 append-only audit 同事务,break-glass 只走
-  双因子的离线恢复流程(见 ADR-0023 / `Spec.System.PlatformAdministration`)。
+  双因子的离线恢复流程(见 ADR-0023)。
 - 受控 alpha 暂采用一 Organization 一具名 systemd Silo:独立 database role/database、
  service identity、workspace、keyring 与 Feishu/provider connection；进程必须由
  `HUB_SILO_ORGANIZATION_ID` fail-closed 绑定唯一 org，平台后台不开放。共享 SaaS
@@ -44,12 +40,12 @@

 ## 纪律

-1. **不得用预训练先验脑补本领域。** 这个领域很新,你没有相关先验。契约里 prose doc 注释是语义的唯一权威来源;契约没写的,就是没定的。
+1. **不得用预训练先验脑补本领域。** 这个领域很新,你没有相关先验。ADR 与 `CONTEXT.md` 是语义的唯一权威来源;没写的,就是没定的。

-2. **凡契约未写明者,不得假设。** 遇到标了 `OPEN` 的地方,或契约根本没覆盖的地方,**显式 surface 出来**让开发者决定,绝不擅自替它选一个解。
+2. **凡 ADR 未写明者,不得假设。** 遇到没覆盖的地方,**显式 surface 出来**让开发者决定,绝不擅自替它选一个解。

-3. **改 `spec/` 必须保持其 `lake build` 通过。** 在 `spec/` 目录下跑 `lake build`。新增声明必须带 `/-- … -/` doc 注释和恰当标签(`PINNED` / `OPEN` / `ADR-NNNN`)。规范见 `spec/README.md`。不准用 `sorry` 把 build 糊绿。
+3. **新语义决策进 ADR。** 跨部件的语义分歧点按编号顺延新增 `docs/adr/NNNN-*.md`;代码里的关键不变量用注释锚到 ADR 编号,保持可 grep。已有 ADR 正文不改写历史——推翻旧决策就写新 ADR 标记 supersede。

-4. **实现向契约对齐;偏离必须 surface。** 没有 CI gate 替你把关 spec↔实现的一致性(见宪法第 2 条)——这道对齐靠 review 和你巡逻 diff。发现实现与契约不一致时,报告它,不要默默让其中一边将就另一边。
+4. **实现向 ADR 对齐;偏离必须 surface。** 没有 CI gate 替你把关 ADR↔实现的一致性(见宪法第 2 条)——这道对齐靠 review 和你巡逻 diff。发现实现与决策不一致时,报告它,不要默默让其中一边将就另一边。

 5. **写操作谨慎。** 线上操作、git 写操作前与开发者确认(这是开发者的全局偏好)。
@@ -1,25 +1,23 @@
 # CLAUDE.md —— agent 操作手册(全 repo)

-本 repo 是 monorepo。先读根 `README.md` 的"宪法"5 条,那是一切工作的前提。本文件是给在这里干活的 coding agent 的纪律。
+本 repo 是 monorepo。先读根 `README.md` 的"宪法"4 条,那是一切工作的前提。本文件是给在这里干活的 coding agent 的纪律。

 ## 这个 repo 是什么

- `spec/` 是一份**人机共识的契约**(Lean 语义母本),是产品语义的上游参照。
- 其余部件(将来的 `spec/` 外文件夹)是**向 `spec/` 对齐的实现**。
+- `docs/adr/` 是系统级决策的唯一权威来源;`CONTEXT.md` 是平台语言词汇表;代码注释把关键不变量锚到 ADR 编号,可 grep。
 - `hub/` 的平台层按 SaaS 形态演进:`Organization` 是 tenant root;`Project`/`Team`
-  必须归属 org,TEAM→PROJECT 授权不得跨 org(见 ADR-0020 / `Spec.System.Organization`)。
+  必须归属 org,TEAM→PROJECT 授权不得跨 org(见 ADR-0020)。
 - org 后台 project explorer 里 `Folder` 是透明组织节点,不是权限资源;project 仍是权限边界。
-  普通老师可在飞书群自助建 project 但受 org policy 控制(见 ADR-0021 /
-  `Spec.System.ProjectWorkspace`)。
+  普通老师可在飞书群自助建 project 但受 org policy 控制(见 ADR-0021)。

 ## 纪律

-1. **不得用预训练先验脑补本领域。** 这个领域很新,你没有相关先验。契约里 prose doc 注释是语义的唯一权威来源;契约没写的,就是没定的。
+1. **不得用预训练先验脑补本领域。** 这个领域很新,你没有相关先验。ADR 与 `CONTEXT.md` 是语义的唯一权威来源;没写的,就是没定的。

-2. **凡契约未写明者,不得假设。** 遇到标了 `OPEN` 的地方,或契约根本没覆盖的地方,**显式 surface 出来**让开发者决定,绝不擅自替它选一个解。
+2. **凡 ADR 未写明者,不得假设。** 遇到没覆盖的地方,**显式 surface 出来**让开发者决定,绝不擅自替它选一个解。

-3. **改 `spec/` 必须保持其 `lake build` 通过。** 在 `spec/` 目录下跑 `lake build`。新增声明必须带 `/-- … -/` doc 注释和恰当标签(`PINNED` / `OPEN` / `ADR-NNNN`)。规范见 `spec/README.md`。不准用 `sorry` 把 build 糊绿。
+3. **新语义决策进 ADR。** 跨部件的语义分歧点按编号顺延新增 `docs/adr/NNNN-*.md`;代码里的关键不变量用注释锚到 ADR 编号,保持可 grep。已有 ADR 正文不改写历史——推翻旧决策就写新 ADR 标记 supersede。

-4. **实现向契约对齐;偏离必须 surface。** 没有 CI gate 替你把关 spec↔实现的一致性(见宪法第 2 条)——这道对齐靠 review 和你巡逻 diff。发现实现与契约不一致时,报告它,不要默默让其中一边将就另一边。
+4. **实现向 ADR 对齐;偏离必须 surface。** 没有 CI gate 替你把关 ADR↔实现的一致性(见宪法第 2 条)——这道对齐靠 review 和你巡逻 diff。发现实现与决策不一致时,报告它,不要默默让其中一边将就另一边。

 5. **写操作谨慎。** 线上操作、git 写操作前与开发者确认(这是开发者的全局偏好)。
@@ -2,7 +2,7 @@

 教研生产的数字化解决方案。核心思路:课程像 DAW / 剪辑软件那样有一个**结构化的工程文件**;coding agent 协助编辑它;一个 rule-based checker(类编译器)校验其合法性并给出 helpful fix hint。目标是把教研从一次性的文档,沉淀成**可累积、可校验、可复用的资产**。

-这是一个 **monorepo**。它的组织方式本身就表达了一条原则:**`spec/` 是上游的语义母本,其余部件是向它对齐的实现。**
+这是一个 **monorepo**。它的组织方式本身就表达了一条原则:**`docs/adr/` 是系统级决策的唯一权威来源,代码注释把关键不变量锚到 ADR 编号,可 grep。**

 ## 安装 `cph` 命令行

@@ -33,47 +33,40 @@ cph completions zsh > ~/.zfunc/_cph        # 或 bash/fish/powershell/elvish
 ```
 README.md          ← 本文件:总览 + 宪法(下面 5 条)
 CLAUDE.md          ← 全局 agent 操作手册(管整个 repo)
-docs/adr/          ← 系统级架构决策记录(跨部件,被 spec 契约引用)
-spec/              ← Lean 语义母本(自包含的 Lean 工程)。见 spec/README.md
+docs/adr/          ← 系统级架构决策记录(跨部件,决策的唯一权威来源)
+CONTEXT.md         ← 平台语言词汇表(术语与禁用说法)
 Cargo.toml         ← 仓库级 cargo workspace(实现部件共用,便于跨部件复用 crate)
-crates/            ← 实现:rule-based checker(向 spec 对齐)。见 crates/README.md
+crates/            ← 实现:rule-based checker(语义由 ADR 锚定)。见 crates/README.md
  cph-diag / cph-model / cph-schema / cph-typst   ← 可复用基础(模型/校验/typst 引擎)
  cph-check / cph-cli                             ← checker 本体 + `cph` 命令行
-render/            ← typst 渲染包 cph-render(母本的渲染后端之一,ADR-0005)
+render/            ← typst 渲染包 cph-render(checker 的渲染后端,ADR-0005)
 examples/          ← 样例工程文件(如 TH-141),流水线的真实输入
 hub/              ← SaaS Hub:飞书协作、org 管理、agent runtime 与生产部署
-(exporter/ …)     ← 将来的其他部件,平级于 spec/
+(exporter/ …)     ← 将来的其他部件,平级于 crates/
 ```

-`spec/` 与实现部件**物理分离、平级共存**:谁是上游、谁向谁对齐,一眼可见。
 实现部件共用一个仓库根的 cargo workspace,使基础 crate(模型、typst 引擎)能被
 未来部件(如 exporter)复用,而非各自重造。

 ## 宪法

-这 5 条是 `spec/` 这份语义母本的定位与约束,是本仓库一切工作的前提。
+这 4 条是本仓库的协作约定,是一切工作的前提。

-1. **角色 —— Lean 是研发侧的上游参照。**
-   `spec/` 用 Lean 编写,是开发者(领域专家)与 coding agent **共用**的 spec 工具,用来沉淀产品各部件的**语义**。它**不进入产品运行时**——产品里"站在 Lean 这个位置"的那个 checker 用什么技术实现,尚未决定;但那个东西的语义,先在 `spec/` 里固定下来。
+1. **角色 —— ADR 是决策真相。**
+   跨部件的语义决策只记录在 `docs/adr/`,一份决策一份 ADR,编号顺延、正文不改写历史。代码里的关键不变量用注释锚到 ADR 编号,保持可 grep。没有第二份权威文档。

-2. **对齐机制 —— Lean 只做上游参照。**
-   不做 extract / codegen,不派生 conformance test,CI 里**没有** spec→实现的 gate。实现对齐 spec,由"开发者 review + agent 巡逻 diff"这个人肉环节承载。
-   (CI 里的 `spec check` 只验 spec **自身**能否 type-check,即契约内部良构,不是 spec↔实现的对齐检查。)
+2. **对齐机制 —— 人肉承载,无机器兜底。**
+   CI 只验各部件自身良构(build / test / clippy),**没有**决策↔实现的一致性 gate。实现对齐 ADR,由"开发者 review + agent 巡逻 diff"这个人肉环节承载。发现漂移,报告它,不要默默让其中一边将就另一边。

-3. **资产性 —— 由 review 纪律承载,无机器兜底。**
-   这份仓库给你的是"精确、自洽、机器验内部良构的语义共识",**不是**"实现正确性保证"。spec 与实现之间那道缝,是我们自愿用人来守的——清醒地守,它就是资产;放任实现漂移而不回头同步,它就退化成最贵的过期文档。
+3. **形态 —— 自包含。**
+   凡 ADR 未明文规定的,开发者与 agent 双方都不该假设;遇到没覆盖的地方,**显式 surface** 出来让开发者决定。

-4. **形态 —— 它是人机共识的契约。**
-   契约必须**自包含**:凡契约未明文规定的,开发者与 agent 双方都不该假设。这比"文档"严格——type checker 会逼这份契约在结构上无洞。
-
-5. **深度判据 —— 只收录分歧点。**
-   一条语义该不该写进 Lean,取决于一句话:**"不写明,开发者与 agent 会不会各自做出不同假设?"** 会 → 进契约;显然的东西 / 纯 plumbing / 普通 CRUD 字段 → 不进(写进去只稀释信噪比、增加维护面)。
-   深度上限不是 Lean 的表达力,而是**你愿意在每次实现变更时手动回头同步的量**——写得比你能维护的更深,多出来的部分会率先过期、反过来误导实现。
+4. **深度判据 —— 只收录分歧点。**
+   一条语义该不该写进 ADR,取决于一句话:**"不写明,开发者与 agent 会不会各自做出不同假设?"** 会 → 进 ADR;显然的东西 / 纯 plumbing / 普通 CRUD 字段 → 不进(写进去只稀释信噪比、增加维护面)。
+   深度上限是**你愿意在每次实现变更时手动回头同步的量**——写得比你能维护的更深,多出来的部分会率先过期、反过来误导实现。

 ## CI

-`.gitea/workflows/spec-check.yml` 在每次 push / PR 时于 `spec/` 下跑 `lake build`,确保契约始终 type-check 通过(从第一天起就是"绿"的)。这是良构 gate,见宪法第 2 条。
-
 Rust checker 的本地与 CI 工具链由根 `rust-toolchain.toml` 固定;`.gitea/workflows/checker-check.yml`
 必须安装同一精确版本并执行 `cargo fmt --all --check`、Clippy `-D warnings` 与 workspace
 全测试。升级 Rust 时这两处必须在同一提交更新并通过完整 checker gate。
@@ -1,7 +1,8 @@
 # crates/

-These crates implement the rule-based lesson checker that aligns to the
-semantic master in `spec/`: it reads an engineering-file (one lesson, ADR-0005)
+These crates implement the rule-based lesson checker whose semantics are
+pinned by the ADRs in `docs/adr/`: it reads an engineering-file (one lesson,
+ADR-0005)
 laid out per ADR-0008 (declarative `manifest.toml` + per-element
 `element.toml`), validates structure and content, and emits diagnostics.
 `cph-diag` (the shared diagnostic vocabulary), `cph-model` (the ADR-0008 loader),
@@ -19,13 +19,11 @@ const DEFAULT_TARGET: &str = "student";

 /// Severity of the render-coverage ("element ignored under a target") diagnostic.
 ///
-/// **PINNED to `warning` by the contract.** Mirrors the Lean master's
-/// `Spec.Courseware.renderIgnoredSeverity : Severity := .warning`
-/// (`spec/Spec/Courseware/Check/Diagnostic.lean`), itself citing ADR-0005: when a
+/// **PINNED to `warning` by ADR-0005:** when a
 /// `(kind, target)` pair has no render rule the checker reports that the element
 /// is ignored under that target and **does not block the export**. Naming the
-/// severity as a const makes "it is a warning, not an error" a greppable,
-/// alignable fact rather than an inline literal.
+/// severity as a const makes "it is a warning, not an error" a greppable
+/// fact rather than an inline literal.
 const RENDER_IGNORED_SEVERITY: Severity = Severity::Warning;

 /// The result of running [`check`] (or the check phases of [`build`]).
@@ -57,12 +55,12 @@ impl CheckReport {

    /// Whether any collected diagnostic is `Error`-severity.
    ///
-    /// **Legality decision (spec alignment).** `!has_errors()` is the
-    /// implementation of `Spec.Courseware.Legal` (`spec/Spec/Courseware/Check/Diagnostic.lean`):
-    /// a lesson is *legal* iff its diagnostics contain no error-level diagnostic
-    /// (warnings are non-blocking — see `Severity` / ADR-0010). There is no CI
-    /// gate enforcing this alignment (repo constitution); it is kept greppable
-    /// here so a reviewer can tie the orchestrator's gate to the Lean master.
+    /// **Legality decision (ADR-0010).** `!has_errors()` decides lesson
+    /// legality: a lesson is *legal* iff its diagnostics contain no error-level
+    /// diagnostic (warnings are non-blocking — see `Severity`). There is no CI
+    /// gate enforcing ADR↔implementation alignment (repo constitution); it is
+    /// kept greppable here so a reviewer can tie the orchestrator's gate to
+    /// the ADR.
    pub fn has_errors(&self) -> bool {
        self.diagnostics
            .iter()
@@ -2,7 +2,7 @@
 //!
 //! Every other crate in the workspace depends on these types to report
 //! problems. The vocabulary is intentionally small and stable: a [`Severity`]
-//! (mirroring the Lean master), a closed set of machine-stable [`DiagCode`]s, an
+//! (two-valued, ADR-0010), a closed set of machine-stable [`DiagCode`]s, an
 //! optional [`SourceSpan`] pointing back at the offending source, and a
 //! [`Diagnostic`] tying them together with a human message and a fix hint.
 //!
@@ -17,32 +17,27 @@ use serde::Serialize;

 /// Severity of a diagnostic.
 ///
-/// **Mirrors `Spec.Courseware.Diagnostic.Severity`** in the Lean semantic
-/// master (`spec/Spec/Courseware/Check/Diagnostic.lean`), whose definition is
-/// exactly:
+/// **Pinned by ADR-0005 / ADR-0010: exactly two values.**
 ///
 /// ```text
-/// inductive Severity where
-///   | warning
-///   | error
+/// warning | error
 /// ```
 ///
-/// This two-valued shape is a **contract decision**, not an accident: the Lean
-/// module pins `Severity` to exactly `warning | error` and states the finer
-/// levels (`info` / `hint` / `note`) are deliberately undecided. We therefore
+/// This two-valued shape is a **contract decision**, not an accident: the
+/// finer levels (`info` / `hint` / `note`) are deliberately undecided, so we
 /// do **not** add an info/note level here. `error` blocks (the artifact is
 /// invalid); `warning` does not block (the artifact still exports, but with
 /// loss / an ignored element — e.g. ADR-0005's "missing render ⇒ warning").
 ///
-/// There is no CI gate enforcing this alignment (see the repo constitution);
-/// it is maintained by review, which is why this correspondence is documented
-/// here rather than only in the spec.
+/// There is no CI gate enforcing ADR↔implementation alignment (see the repo
+/// constitution); it is maintained by review, which is why the decision is
+/// documented here rather than only in the ADR.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
 pub enum Severity {
    /// Non-blocking: the artifact still exports, but is lossy / has an ignored
-    /// element. Mirrors Lean `Severity.warning`.
+    /// element. ADR-0010 `warning`.
    Warning,
-    /// Blocking: the artifact is invalid. Mirrors Lean `Severity.error`.
+    /// Blocking: the artifact is invalid. ADR-0010 `error`.
    Error,
 }

@@ -3,9 +3,7 @@
 //! This crate is the **loader**, not the full checker. It reads
 //! `<root>/manifest.toml` (project / info / ordered `[[parts]]` / declared
 //! `[targets.*]`) and each part's `<root>/<path>/element.toml`, and produces an
-//! ordered [`Lesson`] — mirroring the Lean master's `Lesson = List (Element P)`
-//! (`spec/Spec/Courseware/Model/Lesson.lean`), where the order of `parts` carries
-//! teaching semantics.
+//! ordered [`Lesson`], where the order of `parts` carries teaching semantics.
 //!
 //! Scope boundaries (deliberately staying in lane):
 //! - It validates **structure** only: manifest shape, element.toml shape, and
@@ -23,7 +21,7 @@ use serde::{Deserialize, Serialize};

 /// An ordered, in-memory lesson loaded from an engineering file.
 ///
-/// Mirrors the Lean master's `Lesson = List (Element P)`: `parts` is an ordered
+/// `parts` is an ordered
 /// `Vec`, and that order is the lesson's order (ADR-0008 §"the lesson manifest
 /// is declarative" — the `[[parts]]` array order is the single source of truth).
 #[derive(Debug, Clone, PartialEq, Serialize)]
@@ -86,9 +84,8 @@ pub struct TargetConfig {
    /// with template `exports/<name>.typ` when no `[[steps]]` are given.
    pub steps: Vec<Step>,
    /// The **render-coverage declaration**: which element kinds this target
-    /// renders. Realizes `Spec.Courseware.TargetSpec.covers : KindId → Prop`
-    /// (`spec/Spec/Courseware/Export/Render.lean`) and ADR-0011's "render
-    /// coverage is a declaration, not a payload": the contract keeps *which
+    /// renders. Realizes ADR-0011's "render
+    /// coverage is a declaration, not a payload": the declaration keeps *which
    /// kinds a target renders* (used by the `renderIgnored` seed diagnostic),
    /// while the rendering "how" lives in the template/steps.
    ///
@@ -102,13 +99,10 @@ pub struct TargetConfig {

 /// The artifact an export target produces (ADR-0009/0011).
 ///
-/// **Mirrors `Spec.Courseware.Artifact`** in the Lean semantic master
-/// (`spec/Spec/Courseware/Export/Artifact.lean`), whose definition is exactly:
+/// **Pinned by ADR-0011** as an ADT with fields:
 ///
 /// ```text
-/// inductive Artifact where
-///   | singleFile (filepath : String)
-///   | fileTree (root : String) (outputs : String)
+/// Artifact = singleFile (filepath) | fileTree (root, outputs)
 /// ```
 ///
 /// ADR-0011 pinned the artifact as an ADT **with fields**: "what the product
@@ -120,20 +114,20 @@ pub struct TargetConfig {
 /// `"single-file"` → [`Artifact::SingleFile`], `"file-tree"` →
 /// [`Artifact::FileTree`].
 ///
-/// As with `cph-diag`'s `Severity`, there is no CI gate enforcing this
-/// alignment (see the repo constitution) — it is maintained by review, which is
-/// why the correspondence is documented here.
+/// As with `cph-diag`'s `Severity`, there is no CI gate enforcing ADR↔
+/// implementation alignment (see the repo constitution) — it is maintained by
+/// review, which is why the decision is documented here.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 pub enum Artifact {
    /// One bundled document landing at `filepath` (relative to the engineering
-    /// root). Mirrors Lean `Artifact.singleFile`. The default artifact shape.
+    /// root). ADR-0011 `singleFile`. The default artifact shape.
    SingleFile {
        /// Where the single product is written (relative to the engineering
        /// root), e.g. `build/student.pdf`.
        filepath: PathBuf,
    },
-    /// A set of files under `root` matching the `outputs` glob. Mirrors Lean
-    /// `Artifact.fileTree`.
+    /// A set of files under `root` matching the `outputs` glob. ADR-0011
+    /// `fileTree`.
    FileTree {
        /// The output directory (relative to the engineering root).
        root: PathBuf,
@@ -156,14 +150,10 @@ impl Artifact {

 /// One typed build step (ADR-0011).
 ///
-/// **Mirrors `Spec.Courseware.Step`** in the Lean semantic master
-/// (`spec/Spec/Courseware/Export/Render.lean`), whose definition is exactly:
+/// **Pinned by ADR-0011** as an ADT:
 ///
 /// ```text
-/// inductive Step where
-///   | typstCompile (template : String)
-///   | shell (run : String)
-///   | assembleMarkdown (field : String)
+/// Step = typstCompile (template) | shell (run) | assembleMarkdown (field)
 /// ```
 ///
 /// A step is a *typed* operation (extensible): `TypstCompile` compiles a
@@ -183,20 +173,20 @@ impl Artifact {
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 pub enum Step {
    /// Compile a template file (relative to the engineering root) into the
-    /// artifact; the framework injects the manifest. Mirrors Lean
-    /// `Step.typstCompile`.
+    /// artifact; the framework injects the manifest. ADR-0011
+    /// `typstCompile`.
    TypstCompile {
        /// The template file to compile as main, e.g. `exports/student.typ`.
        template: PathBuf,
    },
-    /// Run a shell command — the escape hatch. Mirrors Lean `Step.shell`.
+    /// Run a shell command — the escape hatch. ADR-0011 `shell`.
    Shell {
        /// The command line to run.
        run: String,
    },
    /// Assemble a single-file markdown deliverable by concatenating each
-    /// element's `field` markdown content file in `[[parts]]` order. Mirrors
-    /// Lean `Step.assembleMarkdown` (ADR-0015). Not a typst build — the
+    /// element's `field` markdown content file in `[[parts]]` order. ADR-0011
+    /// `assembleMarkdown` (ADR-0015). Not a typst build — the
    /// framework owns the read/concatenate/write itself.
    AssembleMarkdown {
        /// The per-element markdown content field to assemble (e.g. `slides`,
@@ -226,12 +216,11 @@ pub struct Project {

 /// `[info]` table (passed through to render targets verbatim).
 ///
-/// **Mirrors `Spec.Courseware.Info`** in the Lean semantic master
-/// (`spec/Spec/Courseware/Model/Info.lean`): the *canonical* model whose
+/// The *canonical* model whose
 /// `authors` is always a list. The authoring-surface form (string-or-array
 /// `author`) is the separate [`RawInfo`] / [`RawAuthor`], normalized into this
-/// at the load boundary — mirroring the Lean `RawInfo` / `RawAuthor` split. No
-/// CI gate enforces this alignment (repo constitution); it is kept greppable.
+/// at the load boundary. No
+/// CI gate enforces ADR↔implementation alignment (repo constitution); it is kept greppable.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 pub struct Info {
    /// Lesson title.
@@ -240,7 +229,6 @@ pub struct Info {
    /// so this is a list, not a single name. Empty when `[info]` declares no
    /// `author`. The on-disk `author` accepts either a bare string (one author)
    /// or an array of strings (see [`RawAuthor`]); both load into this `Vec`.
-    /// Mirrors Lean `Info.authors : List String`.
    pub authors: Vec<String>,
 }

@@ -290,8 +278,7 @@ struct RawProject {
    name: String,
 }

-/// The authoring-surface `[info]` (mirrors Lean `RawInfo` in
-/// `spec/Spec/Courseware/Model/Info.lean`): the raw form that exists for
+/// The authoring-surface `[info]`: the raw form that exists for
 /// fill-in convenience, normalized into the canonical [`Info`] at the load
 /// boundary. Not the form the rest of the model traffics in.
 #[derive(Debug, Deserialize)]
@@ -301,7 +288,7 @@ struct RawInfo {
 }

 /// On-disk `author`: either a single name (`author = "…"`) or a list
-/// (`author = ["…", "…"]`). Mirrors Lean `RawAuthor`: a fill-in convenience whose
+/// (`author = ["…", "…"]`). A fill-in convenience whose
 /// string-or-array union lives **only** at the load boundary — [`RawAuthor::into_vec`]
 /// folds it into the canonical [`Info::authors`] `Vec`, after which it never appears.
 #[derive(Debug, Deserialize)]
@@ -312,7 +299,7 @@ enum RawAuthor {
 }

 impl RawAuthor {
-    /// Flatten to the ordered author list (Lean `RawAuthor.normalize`): a single
+    /// Flatten to the ordered author list: a single
    /// name becomes a one-element list; a list passes through verbatim.
    fn into_vec(self) -> Vec<String> {
        match self {
@@ -0,0 +1,146 @@
+# ADR 0026: Usage Fact Ledger
+
+## Status
+
+Accepted.
+
+## Context
+
+ADR-0022 pins the cost-attribution contract for the platform: token,
+provider-reported cost, run count, and duration are attributed by Organization,
+Project, Run, model, and Provider Connection; "missing provider cost remains
+unknown rather than zero." ADR-0021 scopes usage accounting as operational
+reporting, not payment collection (commercial billing stays deferred).
+
+The implementation today stores this as **one scalar per `AgentRun`**:
+`inputTokens`, `outputTokens`, `costUsd?`, `costSource?`, written once from the
+Claude Agent SDK's `result.total_cost_usd` when the run finishes. This is
+adequate for a single provider-reported model loop, but it cannot represent:
+
+- **External capability consumption** inside a run. PDF→Markdown bundle
+  conversion, audio/video transcription, OCR and similar media transforms are
+  not the main agent loop. They run as side effects of a run, may use a
+  different provider/model, may bill in non-token units (pages, seconds,
+  invocations), and may report cost through a different channel than the
+  OpenRouter gateway. Today there is no row to write that cost to — it would
+  either disappear or silently corrupt the run's single scalar.
+- **Multiple model calls within one run** (e.g. a sub-model invoked by a
+  tool, a gateway-side reroute). The scalar collapses them into one number.
+- **Pricebook derivation** after the fact. With only a final USD figure and no
+  `(provider, model, occurredAt, tokens)` fact, an operator cannot re-derive
+  cost from a price table when the provider did not report it.
+
+Treating each external call as a nested `AgentRun` was considered and
+rejected: `AgentRun` carries lock ownership (ADR-0002), session/provider/role
+binding (ADR-0017), admission/capacity semantics (ADR-0022), and the
+user-visible task boundary. External calls hold none of those. Making them
+`AgentRun`s would pollute run counts, admission, lock semantics, and session
+continuity, and would still not solve non-token metering.
+
+## Decision
+
+Introduce **`UsageFact`** as the single source of truth for billable
+consumption inside an `AgentRun`. An `AgentRun` owns zero or more
+append-only `UsageFact` rows; each row records one billable consumption event:
+
+- `kind` — `model_completion` (the main agent loop) | `external_capability`
+  | `tool_proxy`. The kind set is `OPEN`; new kinds must be surfaced, not
+  silently folded into an existing one.
+- `provider` — e.g. `openrouter`, `mineru`, `openai_whisper`.
+- `model?`, `inputTokens?`, `outputTokens?` — token metering, optional
+  because non-token capabilities have none.
+- `quantity?` + `unit?` — non-token metering (pages, audio_seconds,
+  invocations), coexisting with tokens rather than replacing them.
+- `costUsd?` + `costSource` — `provider_reported` | `pricebook_derived` |
+  `unknown`. `costUsd = null` means **unknown, not zero** (ADR-0022). When the
+  provider reported a cost, `costSource = provider_reported` and that value
+  wins. When only tokens are known, a later pricebook pass may derive
+  `costUsd` with `costSource = pricebook_derived`. When neither is possible,
+  `costSource = unknown` and `costUsd` stays null.
+- `occurredAt` — when the consumption happened; the pricebook derivation
+  depends on this, not on `AgentRun.finishedAt`, because an external
+  capability may complete before the run finishes.
+- `capabilityId?` — for `external_capability` facts, the registered capability
+  id (e.g. `pdf_to_md_bundle`, `audio_video_to_text`).
+- `correlationId?` — external request id for reconciliation / idempotency;
+  not part of the aggregation key.
+
+### Invariants
+
+1. **Append-only.** A `UsageFact` row is never updated or deleted. A cost
+   correction is a new row; the old row stays. `onDelete: Cascade` exists only
+   so a hard run delete (itself not a normal path) cleans up its facts.
+2. **Belongs to exactly one Run; never holds a lock.** A fact is a side-effect
+   ledger of one run, not a sub-run. External capability calls obey the same
+   boundary: their identity is `capabilityId + correlationId`, not `RunId`.
+3. **Missing cost ≠ zero.** Aggregation MUST NOT sum `null` `costUsd` as 0.
+   A run whose facts all have `costUsd = null` is "cost unknown" — reported as
+   `runsWithoutCost`, exactly as the pre-migration `costUsd = null` runs are
+   today. A run with at least one `costUsd`-bearing fact contributes its sum.
+
+### Rollup cache
+
+`AgentRun.costUsd / inputTokens / outputTokens / costSource` columns are kept
+as a **derived rollup cache**, not dropped:
+
+- Existing non-`/usage` readers (slash `/usage`, session detail, integration
+  tests asserting `run.costUsd`) continue to work without code changes for
+  historical runs.
+- On run finish, the writer writes the `UsageFact` row first and then mirrors
+  it onto `AgentRun` as two separate statements, not one transaction. The
+  fact is the truth, so it is written first; the cache is derived, so it is
+  written second. A crash between the two leaves the cache stale, but the
+  usage service re-reads `UsageFact` directly, so staleness is recoverable
+  (and the reverse order would lose the truth, which is not). Keeping the
+  fact insert and the run update in separate statements also avoids holding
+  the `AgentRun` row lock across the FK ShareLock taken by the insert, which
+  deadlocks against concurrent workspace teardown under the cascade path
+  `Organization → Project → AgentRun → UsageFact`.
+- The org/project usage service and the slash `/usage` command read from
+  `UsageFact` directly — they are the canonical aggregation path.
+
+### Migration
+
+A new `UsageFact` table is added. For every existing `AgentRun` with a
+non-null `costUsd` or non-null `inputTokens`/`outputTokens`, the migration
+inserts **one synthetic `model_completion` fact** carrying the run's
+provider, model, tokens, cost, and `costSource`. Its `correlationId` is the
+run id, so the row is identifiable as a backfill artefact. This keeps
+historical reporting correct under the new aggregation path. Pre-migration
+runs with no recorded cost remain `runsWithoutCost` by design, matching
+ADR-0022's "missing cost ≠ zero" rule and the existing migration
+`20260709143000_agent_run_cost_tracking`'s "no backfill" stance for the
+truly unrecorded.
+
+## Consequences
+
+- The billing model now supports external capabilities (PDF→MD, ASR, OCR, …)
+  without per-capability schema changes: a new capability is one new
+  `capabilityId` value and one or more `external_capability` facts.
+- `AgentRun.costUsd` is no longer the truth; it is a convenience cache.
+  Readers that need the truth (cost breakdown, per-capability attribution)
+  must read `UsageFact`. The cache MUST be kept consistent on the write path.
+- The capability registry, pricebook, and any commercial settlement remain
+  `OPEN` and out of pilot scope (ADR-0021). This ADR only pins the ledger
+  shape and invariants.
+- `usage.ts` and `/usage` now perform a join against `UsageFact` rather than a
+  single-table scan of `AgentRun`; the index on `(runId, occurredAt)` and
+  `(provider, model, occurredAt)` keeps the existing org/project/report
+  queries bounded.
+- Cost corrections (e.g. a provider rebills a run) produce a new fact row; the
+  rollup cache must be recomputed. The initial release writes facts once at
+  run finish and does not support post-hoc correction flows — that remains
+  `OPEN`.
+
+## Deferred
+
+- **Capability registry** as a first-class spec entity (`Spec.System.Capability`)
+  with org-scoped enable/disable, input/output contracts, metering schemas,
+  and org-exclusive credentials (ADR-0024 alignment). This ADR only reserves
+  the `capabilityId` field and the `external_capability` fact kind.
+- **Pricebook** — a versioned price table keyed by `(provider, model, unit)`
+  with time validity. Required to actually produce `pricebook_derived` costs;
+  until then, facts without provider-reported cost stay `unknown`.
+- **Post-hoc cost correction flow** — append-only today; correction UI and
+  rollup recompute are `OPEN`.
+- **Commercial billing, invoicing, settlement** — still deferred per ADR-0021.
@@ -0,0 +1,152 @@
+# ADR 0027: External Capability Registry
+
+## Status
+
+Accepted.
+
+## Context
+
+ADR-0026 introduced the `UsageFact` ledger with a `kind = external_capability`
+fact and a `capabilityId` field, but deferred the capability registry itself.
+Two concrete needs now force the issue:
+
+- **PDF→Markdown bundle** conversion (and, imminently, audio/video→text)
+  must run as a side effect of an `AgentRun`, bill in non-token units
+  (pages, seconds), use a different provider than the model loop, and report
+  cost through a different channel. It is not a sub-run (ADR-0026 rejected
+  that) and not a model-provider call (it does not speak the Anthropic/
+  OpenRouter protocol).
+- The Agent already has a Bash tool. Without a first-class capability seam,
+  the path of least resistance is for the agent to shell out to ad-hoc
+  scripts that embed API keys, write to arbitrary paths, and report nothing
+  to the ledger. That is exactly the unattributed, uncontained external
+  consumption ADR-0022/0026 exist to prevent.
+
+The model-provider connection (`OrganizationProviderConnection`, ADR-0024)
+is the wrong seam for these services:
+
+- Its payload schema (`baseUrl` + `authToken` + `anthropicApiKey`) and
+  readiness probe (`/v1/models?supported_parameters=tools`) are specific to
+  OpenRouter/Anthropic. MinerU, Whisper, and future OCR/ASR services have
+  different auth shapes (an API token, optionally a project id) and no
+  `/v1/models` endpoint.
+- Its uniqueness key is `(organizationId, providerId)` where `providerId`
+  is an OpenRouter-style model-routing id. A capability provider id
+  (`mineru`) names a *service*, not a model.
+- Coupling capability credentials into the model-provider table would force
+  every capability's auth shape through `ProviderSecretPayloadV1` and every
+  readiness probe through `probeOpenRouterCredential`.
+
+The Feishu Application Connection (`OrganizationFeishuApplicationConnection`)
+is the right structural precedent: it reuses the ADR-0024 envelope (KEK →
+DEK → AES-256-GCM, AAD-bound to purpose/org/connection/version) but has its
+own connection table, its own payload schema, its own readiness probe, and
+its own per-org uniqueness. Capability connections follow the same pattern.
+
+## Decision
+
+### External Capability
+
+An **External Capability** is a platform-registered, org-enabled document or
+media transform service invoked as a side effect of an `AgentRun`. It is
+identified by a stable `capabilityId` (e.g. `pdf_to_md_bundle`,
+`audio_video_to_text`). A capability:
+
+- Has an **input kind** (PDF, image, audio, video, …) and an **output
+  contract** (markdown bundle with extracted images, transcript text, …).
+- Bills in **non-token units** (pages, audio-seconds) recorded on a
+  `UsageFact` with `kind = external_capability`, or in tokens when the
+  backing service reports them.
+- Writes its output **into the invoking run's workspace** (ADR-0018
+  `AgentSurface` — no escapes).
+- Is invoked through a **capability adapter** in Hub, never by the Agent
+  shelling out with embedded credentials.
+
+### Capability Connection
+
+Credentials for a capability live in an **`OrganizationCapabilityConnection`**,
+structurally identical to the Feishu Application Connection:
+
+- Belongs to exactly one Organization.
+- Unique by `(organizationId, capabilityId)`.
+- `DRAFT` / `ACTIVE` / `DISABLED`; resolution accepts only `ACTIVE` with a
+  valid active secret version.
+- Secret material is an immutable, AAD-bound, KEK-wrapped envelope version
+  (`CapabilityCredentialVersion`), reusing the ADR-0024 encryption
+  machinery with `purpose = "capability"`.
+- Its payload schema is capability-specific (`CapabilitySecretPayloadV1`:
+  `baseUrl`, `apiToken`, optional `projectId`). New capability types extend
+  the payload, not the connection table.
+- A capability-specific **readiness probe** validates the credential before
+  activation (e.g. MinerU: a trivial authenticated GET). The probe is
+  injectable, matching the Feishu/provider pattern, so tests never hit the
+  network.
+
+### Capability Adapter
+
+The adapter is the seam between the Agent and the external service. It:
+
+- Resolves the org's active capability connection (fail-closed, no
+  process-global fallback — ADR-0024).
+- Accepts a workspace-relative input path and an output directory.
+- Calls the backing service (MinerU, Whisper, …) via an injectable
+  `Client` interface so the real HTTP client is swappable and mockable.
+- Writes the produced markdown + image assets into the run's workspace.
+- Writes one `UsageFact` (or more, if the service reports per-stage
+  consumption) with `kind = external_capability`, `capabilityId`,
+  `provider` (the service id), `quantity + unit` (pages / seconds), and
+  `costUsd + costSource = provider_reported` when the service reports cost.
+
+### Registry
+
+The platform maintains a **registry** of known capabilities: their id,
+input kind, output contract, metering unit, and adapter. This is
+code-level registration (like `ToolRegistry`), not a database table — a
+capability is available to an Organization only when (a) the platform
+knows the adapter and (b) the Organization has an `ACTIVE` connection for
+it. Both gates are required.
+
+### What is NOT in this ADR
+
+- The capability invocation is **not** a first-class persisted record
+  (`CapabilityInvocation` table) in this ADR. The `UsageFact` row with
+  `capabilityId` + `correlationId` is the durable trace. If we later need
+  a richer invocation log (retries, partial output, multi-stage status),
+  that is a follow-up; for now the fact is enough.
+- **Pricebook** remains deferred (ADR-0026). Capability facts use
+  `provider_reported` when the service returns cost; otherwise `unknown`.
+- **Org-scoped enable/disable policy** beyond connection status is
+  deferred. An org with an `ACTIVE` connection has the capability; one
+  without does not. A finer "enabled but no credential" toggle is not
+  needed yet.
+- **Agent-facing tool exposure** (how the Agent discovers and calls the
+  capability — MCP tool, Bash wrapper, or built-in) is an implementation
+  detail of the adapter wiring, not a contract concern. The contract pins
+  that the Agent never receives the capability credential.
+
+## Consequences
+
+- Adding a new external capability (e.g. `image_ocr`) is: register an
+  adapter, add a `capabilityId` constant, optionally extend the secret
+  payload — no schema change to `UsageFact` or `AgentRun`.
+- The model-provider connection table stays focused on model routing;
+  capability credentials do not pollute its payload or readiness probe.
+- Three connection types now share the ADR-0024 envelope: model-provider,
+  Feishu application, and capability. Each has its own table, payload
+  schema, and probe, but the same encryption, rotation, and resolver
+  boundary.
+- The Agent's Bash tool remains available, but the intended path for
+  document/media transforms is the capability adapter. Whether to narrow
+  Bash for capability-shaped tasks is an operational policy decision,
+  not a contract one.
+- Tests prove: workspace containment of capability output, fail-closed
+  credential resolution, `UsageFact` attribution with non-token metering,
+  and that the Agent process never receives the capability credential.
+
+## Deferred
+
+- `CapabilityInvocation` as a first-class durable record (status, retries,
+  partial output) — currently the `UsageFact` row is the only trace.
+- Pricebook derivation for capability costs (ADR-0026 deferred).
+- Org-scoped capability enable/disable policy finer than connection status.
+- Agent-facing tool discovery (MCP vs built-in) for capabilities.
@@ -32,7 +32,7 @@ App ID 通常以 `cli_` 开头，可以写入交付单。App Secret 必须通过
 | 接收群聊中 @ 机器人的消息 | `im:message.group_at_msg:readonly` |
 | 以应用身份发送消息 | `im:message:send_as_bot` |
 | 读取触发消息和线程上下文 | `im:message:readonly` |
-| 获取与上传图片或文件 | `im:resource` |
+| 获取消息中的图片/文件，并向飞书上传图片或文件（含 Agent 回答中的图片发送） | `im:resource` |
 | 添加、删除消息表情回复 | `im:message.reactions:write_only` |
 | 获取用户基本信息 | `contact:user.base:readonly` |
 | 获取用户基本资料 | `contact:user.basic_profile:readonly` |
@@ -66,6 +66,9 @@ Educraft 机器人以应用身份调用上述 API，因此这些 scope 全部放

 如果 API 调试台提示缺少更细粒度权限，请把错误提示和发生时间截图给部署人员。不要自行开通通讯录全量读取等超出本表的权限。

+说明：`im:resource` 既用于下载用户发来的图片/文件，也用于 Agent 回复时把本地或远程图片上传为飞书 `image_key` 后嵌入消息卡片。缺少该权限时，带图回答会发送失败或降级为无图文本。已开通该 scope 的存量应用一般无需新增权限，但若权限尚未随最新版本发布，请创建新版本并审核发布。
+
+
 ## 4. 配置事件与卡片回调

 进入“事件与回调”。
@@ -34,6 +34,10 @@ HUB_FEISHU_EVENTS_PER_MINUTE="120"
 # to this path and rejects any overlap before installing the unit.
 HUB_PROJECT_WORKSPACE_ROOT="/var/lib/cph-hub/workspaces"

+# Persistent root for the content-addressed agent skill store. Required at hub
+# startup unless XDG_STATE_HOME is set (then defaults to $XDG_STATE_HOME/skills).
+HUB_SKILL_STORE_ROOT="/var/lib/cph-hub/state/skills"
+
 # This process is pinned to exactly one Organization. Feishu credentials are
 # resolved from that Organization's encrypted ACTIVE connection.
 HUB_SILO_ORGANIZATION_ID=""
@@ -168,6 +168,16 @@ export interface FeishuApplicationConnection {
 	updatedAt: string;
 }

+export interface CapabilityConnection {
+	id: string;
+	capabilityId: string;
+	status: 'DRAFT' | 'ACTIVE' | 'DISABLED';
+	activeVersion: number | null;
+	keyId: string | null;
+	createdAt: string;
+	updatedAt: string;
+}
+
 export interface UsageTotals {
 	runCount: number;
 	runsWithCost: number;
@@ -183,13 +193,81 @@ export interface ProjectUsageRow extends UsageTotals {
 	folderId: string | null;
 }

+/** Ledger slice from UsageFact (ADR-0026): separates model tokens vs external meters. */
+export interface UsageBreakdownRow {
+	kind: string;
+	provider: string;
+	model: string | null;
+	capabilityId: string | null;
+	unit: string | null;
+	factCount: number;
+	factsWithCost: number;
+	factsWithoutCost: number;
+	inputTokens: number;
+	outputTokens: number;
+	quantity: number | null;
+	costUsd: number | null;
+}
+
 export interface UsageReport {
 	from: string | null;
 	to: string | null;
 	projects: ProjectUsageRow[];
 	totals: UsageTotals;
+	breakdown: UsageBreakdownRow[];
 }

+export interface ProjectUsageReport extends ProjectUsageRow {
+	from: string | null;
+	to: string | null;
+	breakdown: UsageBreakdownRow[];
+}
+
+export interface UsageFactRow {
+	id: string;
+	occurredAt: string;
+	kind: string;
+	provider: string;
+	model: string | null;
+	inputTokens: number | null;
+	outputTokens: number | null;
+	quantity: number | null;
+	unit: string | null;
+	costUsd: number | null;
+	costSource: string;
+	capabilityId: string | null;
+	correlationId: string | null;
+}
+
+export interface SessionRunRow {
+	id: string;
+	status: string;
+	model: string;
+	provider: string;
+	inputTokens: number | null;
+	outputTokens: number | null;
+	costUsd: number | null;
+	costSource: string | null;
+	startedAt: string;
+	finishedAt: string | null;
+	error: string | null;
+	usageFacts: UsageFactRow[];
+}
+
+export interface SessionDetail {
+	id: string;
+	provider: string;
+	roleId: string;
+	model: string;
+	title: string | null;
+	createdAt: string;
+	updatedAt: string;
+	archivedAt: string | null;
+	project: { id: string; name: string };
+	runs: SessionRunRow[];
+}
+
+
 export type CapacityDimension =
 	| 'requestRate'
 	| 'requestBodySize'
@@ -343,6 +421,8 @@ export const api = {
 		get(`${orgBase(slug)}/projects/${projectId}/sessions${limit !== undefined ? `?limit=${limit}` : ''}`) as Promise<{
 			sessions: SessionSummary[];
 		}>,
+	session: (slug: string, sessionId: string) =>
+		get(`${orgBase(slug)}/sessions/${encodeURIComponent(sessionId)}`) as Promise<SessionDetail>,
 	usage: (slug: string, params?: { from?: string; to?: string; folderId?: string }) => {
 		const q = new URLSearchParams();
 		if (params?.from) q.set('from', params.from);
@@ -351,6 +431,16 @@ export const api = {
 		const qs = q.toString();
 		return get(`${orgBase(slug)}/usage${qs ? `?${qs}` : ''}`) as Promise<UsageReport>;
 	},
+	projectUsage: (slug: string, projectId: string, params?: { from?: string; to?: string }) => {
+		const q = new URLSearchParams();
+		if (params?.from) q.set('from', params.from);
+		if (params?.to) q.set('to', params.to);
+		const qs = q.toString();
+		return get(
+			`${orgBase(slug)}/projects/${encodeURIComponent(projectId)}/usage${qs ? `?${qs}` : ''}`,
+		) as Promise<ProjectUsageReport>;
+	},
+

 	providerConnections: (slug: string) =>
 		get(`${orgBase(slug)}/provider-connections`) as Promise<{ connections: ProviderConnectionRow[] }>,
@@ -381,6 +471,21 @@ export const api = {
 	disableFeishuApplication: (slug: string) =>
 		del(`${orgBase(slug)}/feishu-application-connection`) as Promise<FeishuApplicationConnection>,

+	capabilityConnections: (slug: string) =>
+		get(`${orgBase(slug)}/capability-connections`) as Promise<{ connections: CapabilityConnection[] }>,
+	capabilityConnection: (slug: string, capabilityId: string) =>
+		get(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`) as Promise<{
+			connection: CapabilityConnection | null;
+		}>,
+	rotateCapabilityConnection: (
+		slug: string,
+		capabilityId: string,
+		body: { accessKeyId: string; accessKeySecret: string; endpoint: string },
+	) =>
+		put(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`, body) as Promise<CapabilityConnection>,
+	disableCapabilityConnection: (slug: string, capabilityId: string) =>
+		del(`${orgBase(slug)}/capability-connections/${encodeURIComponent(capabilityId)}`) as Promise<CapabilityConnection>,
+
 	capacityPolicy: (slug: string) => get(`${orgBase(slug)}/capacity-policy`) as Promise<CapacityPolicyView>,
 	setCapacityPolicy: (slug: string, body: { limits: Partial<Record<CapacityDimension, number | null>> }) =>
 		put(`${orgBase(slug)}/capacity-policy`, body) as Promise<CapacityPolicyView>,
@@ -8,6 +8,8 @@
 		folders,
 		projects,
 		slug,
+		onCreateFolder,
+		onCreateProject,
 	}: {
 		folder: ExplorerFolder;
 		folders: ExplorerFolder[];
@@ -19,30 +21,58 @@
 			binding: { chatId: string } | null;
 		}[];
 		slug: string;
+		onCreateFolder?: (parentId: string) => void;
+		onCreateProject?: (folderId: string) => void;
 	} = $props();

 	let open = $state(true);
 </script>

 <div>
-	<button
-		type="button"
-		class="flex w-full items-center gap-2.5 px-3 py-2.5 text-left text-sm transition hover:bg-surface-100"
-		onclick={() => (open = !open)}
-	>
-		<span class="w-3.5 text-center text-xs text-surface-600">{open ? '▾' : '▸'}</span>
-		<span class="flex h-7 w-7 items-center justify-center border border-warning-300 bg-warning-50 text-warning-800">
-			<Icon name="folder" class="h-4 w-4" />
-		</span>
-		<span class="min-w-0 flex-1 truncate font-medium text-surface-900">{folder.name}</span>
-		<span class="saas-badge-neutral">{folder.projectCount} 项目</span>
-		{#if folder.childFolderCount > 0}
-			<span class="saas-badge-neutral">{folder.childFolderCount} 子夹</span>
+	<div class="group flex w-full items-center gap-2.5 px-3 py-2.5 text-sm transition hover:bg-surface-100">
+		<button type="button" class="flex min-w-0 flex-1 items-center gap-2.5 text-left" onclick={() => (open = !open)}>
+			<span class="w-3.5 text-center text-xs text-surface-600">{open ? '▾' : '▸'}</span>
+			<span class="flex h-7 w-7 items-center justify-center border border-warning-300 bg-warning-50 text-warning-800">
+				<Icon name="folder" class="h-4 w-4" />
+			</span>
+			<span class="min-w-0 flex-1 truncate font-medium text-surface-900">{folder.name}</span>
+			<span class="saas-badge-neutral">{folder.projectCount} 项目</span>
+			{#if folder.childFolderCount > 0}
+				<span class="saas-badge-neutral">{folder.childFolderCount} 子夹</span>
+			{/if}
+		</button>
+		{#if onCreateFolder || onCreateProject}
+			<span
+				class="flex shrink-0 items-center gap-1 opacity-0 transition group-hover:opacity-100 focus-within:opacity-100"
+			>
+				{#if onCreateFolder}
+					<button
+						type="button"
+						class="flex h-6 w-6 items-center justify-center border border-surface-300 bg-surface-50 text-surface-600 transition hover:border-primary-400 hover:text-primary-700"
+						title="在此新建子文件夹"
+						aria-label="在 {folder.name} 内新建子文件夹"
+						onclick={() => onCreateFolder(folder.id)}
+					>
+						<Icon name="folder-plus" class="h-4 w-4" />
+					</button>
+				{/if}
+				{#if onCreateProject}
+					<button
+						type="button"
+						class="flex h-6 w-6 items-center justify-center border border-surface-300 bg-surface-50 text-surface-600 transition hover:border-primary-400 hover:text-primary-700"
+						title="在此新建项目"
+						aria-label="在 {folder.name} 内新建项目"
+						onclick={() => onCreateProject(folder.id)}
+					>
+						<Icon name="file-plus" class="h-4 w-4" />
+					</button>
+				{/if}
+			</span>
 		{/if}
-	</button>
+	</div>
 	{#if open}
 		<div class="ml-4 border-l border-surface-300 pl-2">
-			<FolderTree {folders} {projects} parentId={folder.id} {slug} />
+			<FolderTree {folders} {projects} parentId={folder.id} {slug} {onCreateFolder} {onCreateProject} />
 		</div>
 	{/if}
 </div>
@@ -9,6 +9,8 @@
 		projects,
 		parentId,
 		slug,
+		onCreateFolder,
+		onCreateProject,
 	}: {
 		folders: ExplorerFolder[];
 		projects: {
@@ -20,6 +22,8 @@
 		}[];
 		parentId: string | null;
 		slug: string;
+		onCreateFolder?: (parentId: string) => void;
+		onCreateProject?: (folderId: string) => void;
 	} = $props();

 	let childFolders = $derived(folders.filter((f) => f.parentId === parentId));
@@ -29,7 +33,7 @@
 <div class="space-y-0.5">
 	{#each childProjects as p (p.id)}
 		<a
-			href={`/admin/org/${slug}/projects/${p.id}`}
+			href={`/admin/projects/${p.id}`}
 			class="flex items-center gap-2.5 px-3 py-2.5 text-sm transition hover:bg-surface-100"
 		>
 			<span class="flex h-7 w-7 items-center justify-center border border-primary-200 bg-primary-50 text-primary-700">
@@ -44,6 +48,6 @@
 	{/each}

 	{#each childFolders as f (f.id)}
-		<FolderNode folder={f} {folders} {projects} {slug} />
+		<FolderNode folder={f} {folders} {projects} {slug} {onCreateFolder} {onCreateProject} />
 	{/each}
 </div>
@@ -18,6 +18,8 @@
 			| 'arrow-left'
 			| 'folder'
 			| 'file'
+			| 'folder-plus'
+			| 'file-plus'
 			| 'check'
 			| 'roles';
 		class?: string;
@@ -122,6 +124,22 @@
 			d="M19.5 14.25v-2.625a3.375 3.375 0 00-3.375-3.375h-1.5A1.125 1.125 0 0113.5 7.125v-1.5a3.375 3.375 0 00-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 00-9-9z"
 		/>
 	</svg>
+{:else if name === 'folder-plus'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M12 10.5v6m3-3H9m4.06-7.19l-2.12-2.12a1.5 1.5 0 00-1.061-.44H4.5A2.25 2.25 0 002.25 6v12a2.25 2.25 0 002.25 2.25h15A2.25 2.25 0 0021.75 18V9a2.25 2.25 0 00-2.25-2.25h-5.379a1.5 1.5 0 01-1.06-.44z"
+		/>
+	</svg>
+{:else if name === 'file-plus'}
+	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
+		<path
+			stroke-linecap="round"
+			stroke-linejoin="round"
+			d="M19.5 14.25v-2.625a3.375 3.375 0 00-3.375-3.375h-1.5A1.125 1.125 0 0113.5 7.125v-1.5a3.375 3.375 0 00-3.375-3.375H8.25m3.75 9v6m3-3H9m1.5-12H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 00-9-9z"
+		/>
+	</svg>
 {:else if name === 'check'}
 	<svg class={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75">
 		<path stroke-linecap="round" stroke-linejoin="round" d="M4.5 12.75l6 6 9-13.5" />
@@ -10,6 +10,8 @@ export const TOOL_OPTIONS: ToolOption[] = [
 	{ id: 'list_files', label: '列目录', group: '文件' },
 	{ id: 'search_files', label: '搜索', group: '文件' },
 	{ id: 'bash', label: 'Bash 命令', group: 'Shell' },
+	{ id: 'web_fetch', label: 'WebFetch', group: '网络' },
+	{ id: 'web_search', label: 'WebSearch', group: '网络' },
 	{ id: 'cph_check', label: 'cph check', group: 'CPH' },
 	{ id: 'cph_build', label: 'cph build', group: 'CPH' },
 	{ id: 'send_file', label: '发送文件（飞书）', group: '飞书' },
@@ -29,6 +29,52 @@ export function fmtNum(n: number): string {
 	return n.toLocaleString();
 }

+const USAGE_KIND_LABELS: Record<string, string> = {
+	model_completion: '模型完成',
+	external_capability: '外部能力',
+	tool_proxy: '工具代理',
+};
+
+const METER_UNIT_LABELS: Record<string, string> = {
+	pages: '页',
+	audio_seconds: '音频秒',
+	invocations: '次调用',
+};
+
+export function usageKindLabel(kind: string): string {
+	return USAGE_KIND_LABELS[kind] ?? kind;
+}
+
+export function meterUnitLabel(unit: string | null | undefined): string {
+	if (!unit) return '—';
+	return METER_UNIT_LABELS[unit] ?? unit;
+}
+
+export function fmtQuantity(quantity: number | null | undefined, unit: string | null | undefined): string {
+	if (quantity === null || quantity === undefined) return '—';
+	const u = meterUnitLabel(unit);
+	return u === '—' ? fmtNum(quantity) : `${fmtNum(quantity)} ${u}`;
+}
+
+export function fmtTokens(input: number | null | undefined, output: number | null | undefined): string {
+	const hasIn = input !== null && input !== undefined;
+	const hasOut = output !== null && output !== undefined;
+	if (!hasIn && !hasOut) return '—';
+	return `${fmtNum(input ?? 0)} / ${fmtNum(output ?? 0)}`;
+}
+
+export function runStatusLabel(status: string): string {
+	const key = status.toUpperCase();
+	if (key === 'COMPLETED') return '完成';
+	if (key === 'FAILED') return '失败';
+	if (key === 'CANCELED') return '取消';
+	if (key === 'TIMED_OUT') return '超时';
+	if (key === 'RUNNING') return '运行中';
+	if (key === 'QUEUED') return '排队';
+	return status;
+}
+
+
 export function orgRoleLabel(role: string): string {
 	const key = role.toUpperCase() as OrgRole;
 	return ORG_ROLE_LABELS[key] ?? role;
@@ -0,0 +1,40 @@
+import type { MeResponse, OrgMembership } from './api';
+
+/** Alpha Silo host prefix: <slug>.educraft[.dev].… */
+export function hostOrgSlug(hostname: string = typeof window !== 'undefined' ? window.location.hostname : ''): string | null {
+	const host = hostname.toLowerCase();
+	const m = host.match(/^([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.educraft(?:-dev)?\./);
+	return m?.[1] ?? null;
+}
+
+export function isOrgAdmin(org: OrgMembership | null | undefined): boolean {
+	if (!org) return false;
+	const role = String(org.role ?? '').toUpperCase();
+	return role === 'OWNER' || role === 'ADMIN';
+}
+
+/**
+ * Resolve the tenancy for this browser session.
+ * Prefers hostname slug (silo), then ?org=, then first admin membership, then first membership.
+ */
+export function resolveOrg(me: MeResponse | null | undefined, search: string = ''): OrgMembership | null {
+	if (!me || me.organizations.length === 0) return null;
+	const host = hostOrgSlug();
+	if (host) {
+		const byHost = me.organizations.find((o) => o.slug === host);
+		if (byHost) return byHost;
+	}
+	const q = new URLSearchParams(search).get('org')?.trim();
+	if (q) {
+		const byQuery = me.organizations.find((o) => o.slug === q);
+		if (byQuery) return byQuery;
+	}
+	const admin = me.organizations.find((o) => isOrgAdmin(o));
+	return admin ?? me.organizations[0] ?? null;
+}
+
+/** SPA paths no longer embed org slug (subdomain carries tenancy). */
+export function adminPath(rest: string = ''): string {
+	const cleaned = rest.replace(/^\/+/, '');
+	return cleaned === '' ? '/admin' : `/admin/${cleaned}`;
+}
@@ -35,12 +35,9 @@ export async function loadSession(): Promise<void> {
 /**
 * Resolve org slug for org-scoped Feishu OAuth (`GET /auth/feishu/:orgSlug`).
 * Unscoped `/auth/feishu` is disabled unless allowLegacyFeishuOAuth is on.
+ * Path no longer carries tenancy: prefer hostname silo slug, then ?org=.
 */
 export function resolveLoginOrgSlug(): string | null {
-	const path = window.location.pathname.split('/').filter(Boolean);
-	if (path[0] === 'admin' && path[1] === 'org' && path[2]) {
-		return decodeURIComponent(path[2]);
-	}
 	const q = new URLSearchParams(window.location.search).get('org');
 	if (q && q.trim() !== '') return q.trim();

@@ -48,6 +45,12 @@ export function resolveLoginOrgSlug(): string | null {
 	const host = window.location.hostname.toLowerCase();
 	const m = host.match(/^([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.educraft(?:-dev)?\./);
 	if (m?.[1]) return m[1];
+
+	// Legacy path while old bookmarks still land briefly before redirect.
+	const path = window.location.pathname.split('/').filter(Boolean);
+	if (path[0] === 'admin' && path[1] === 'org' && path[2]) {
+		return decodeURIComponent(path[2]);
+	}
 	return null;
 }

@@ -5,6 +5,7 @@
 	import { page } from '$app/state';
 	import { session, loadSession, logout, redirectToLogin } from '$lib/session';
 	import type { OrgMembership } from '$lib/api';
+	import { adminPath, isOrgAdmin, resolveOrg } from '$lib/org';
 	import { orgRoleLabel } from '$lib/format';
 	import Icon from '$lib/components/Icon.svelte';
 	import ToastHost from '$lib/components/ToastHost.svelte';
@@ -20,6 +21,7 @@

 	const navItems = [
 		{ key: 'overview', label: '概览', icon: 'overview' as const },
+		{ key: 'usage', label: '用量', icon: 'overview' as const },
 		{ key: 'members', label: '成员', icon: 'members' as const },
 		{ key: 'teams', label: '团队', icon: 'teams' as const },
 		{ key: 'projects', label: '项目', icon: 'projects' as const },
@@ -28,68 +30,52 @@
 		{ key: 'skills', label: '技能', icon: 'roles' as const },
 		{ key: 'roles', label: '角色', icon: 'roles' as const },
 		{ key: 'feishu', label: '飞书', icon: 'feishu' as const },
+		{ key: 'capabilities', label: '能力', icon: 'provider' as const },
 	];

-	function isAdmin(org: OrgMembership): boolean {
-		const role = String(org.role ?? '').toUpperCase();
-		return role === 'OWNER' || role === 'ADMIN';
-	}
-
-	function orgSlugFromPath(): string | null {
-		const parts = page.url.pathname.split('/').filter(Boolean);
-		if (parts[0] === 'admin' && parts[1] === 'org' && parts[2]) {
-			return decodeURIComponent(parts[2]);
-		}
-		return null;
-	}
-
-	function isOnProjectRoute(): boolean {
-		const parts = page.url.pathname.split('/').filter(Boolean);
-		return parts[0] === 'admin' && parts[1] === 'org' && parts[3] === 'projects';
-	}
-
 	function memberships(): OrgMembership[] {
 		return $session.me?.organizations ?? [];
 	}

 	function adminOrgs(): OrgMembership[] {
-		return memberships().filter(isAdmin);
+		return memberships().filter((o) => isOrgAdmin(o));
 	}

 	function currentOrg(): OrgMembership | null {
-		const slug = orgSlugFromPath();
-		if (!slug) return null;
-		return memberships().find((o) => o.slug === slug) ?? null;
+		return resolveOrg($session.me, page.url.search);
 	}

-	function pickHomeOrg(): OrgMembership | null {
-		const admin = adminOrgs()[0];
-		if (admin) return admin;
-		return memberships()[0] ?? null;
+	function isOnProjectRoute(): boolean {
+		const parts = page.url.pathname.split('/').filter(Boolean);
+		// /admin/projects or /admin/projects/:id
+		return parts[0] === 'admin' && parts[1] === 'projects';
 	}

 	function activeKey(): string {
 		const parts = page.url.pathname.split('/').filter(Boolean);
-		if (parts[0] !== 'admin' || parts[1] !== 'org' || !parts[2]) return '';
-		return parts[3] ?? 'overview';
+		if (parts[0] !== 'admin') return '';
+		// /admin → overview; /admin/usage → usage; /admin/projects/x → projects
+		return parts[1] ?? 'overview';
 	}

 	function navHref(key: string): string {
-		const slug = currentOrg()?.slug ?? pickHomeOrg()?.slug;
-		if (!slug) return '/';
-		if (key === 'overview') return `/admin/org/${slug}`;
-		return `/admin/org/${slug}/${key}`;
+		if (key === 'overview') return adminPath();
+		return adminPath(key);
 	}

 	function pageTitle(): string {
 		const key = activeKey();
 		if (key === 'overview' || key === '') return '概览';
+		if (key === 'sessions') return '会话详情';
 		return navItems.find((i) => i.key === key)?.label ?? '管理后台';
 	}

 	function switchOrg(nextSlug: string) {
 		if (!nextSlug || nextSlug === currentOrg()?.slug) return;
-		void goto(`/admin/org/${nextSlug}`);
+		// Path is tenancy-free; keep optional ?org= for local multi-membership debugging.
+		const url = new URL(page.url.href);
+		url.searchParams.set('org', nextSlug);
+		void goto(`${url.pathname}${url.search}`, { replaceState: true });
 	}

 	function handleLogout(e: Event) {
@@ -112,33 +98,23 @@
 	$effect(() => {
 		if ($session.loading || !$session.me) return;

-		const slug = orgSlugFromPath();
-		const matched = slug ? memberships().find((o) => o.slug === slug) : null;
+		const path = page.url.pathname;
+		// Legacy /admin/org/:slug… is handled by admin/org/[...path] page.

-		// Org admins: route to their first admin org if none matched as admin.
+		const org = currentOrg();
 		const admins = adminOrgs();
-		if (matched && isAdmin(matched)) {
+
+		if (org && isOrgAdmin(org)) {
 			redirecting = false;
 			return;
 		}
-		if (!matched && admins.length > 0) {
-			const target = `/admin/org/${admins[0].slug}`;
-			if (page.url.pathname !== target && !page.url.pathname.startsWith(`${target}/`)) {
-				redirecting = true;
-				void goto(target, { replaceState: true });
-			}
-			return;
-		}

-		// Members (non-admin): project pages are open to project MANAGE holders;
-		// the org overview and other admin-only surfaces are not for them.
-		if (matched && !isAdmin(matched)) {
+		// Member only: allow project routes; bounce admin-only surfaces to projects.
+		if (org && !isOrgAdmin(org)) {
 			redirecting = false;
-			const parts = page.url.pathname.split('/').filter(Boolean);
-			const onOverview = parts.length === 3; // /admin/org/:slug
-			if (onOverview) {
-				const target = `/admin/org/${matched.slug}/projects`;
-				if (page.url.pathname !== target) {
+			if (!isOnProjectRoute()) {
+				const target = adminPath('projects');
+				if (path !== target) {
 					redirecting = true;
 					void goto(target, { replaceState: true });
 				}
@@ -146,12 +122,11 @@
 			return;
 		}

-		// No matched org and no admin orgs: route a member to their first org's
-		// projects page so they can reach project MANAGE surfaces.
-		if (!matched && memberships().length > 0) {
-			const home = memberships()[0];
-			const target = `/admin/org/${home.slug}/projects`;
-			if (page.url.pathname !== target && !page.url.pathname.startsWith(`${target}/`)) {
+		// No org resolved but user has memberships → land on first org's projects/overview via resolveOrg next tick
+		if (!org && memberships().length > 0) {
+			const home = admins[0] ?? memberships()[0]!;
+			const target = isOrgAdmin(home) ? adminPath() : adminPath('projects');
+			if (path !== target && !path.startsWith(`${target}/`)) {
 				redirecting = true;
 				void goto(target, { replaceState: true });
 			}
@@ -172,14 +147,14 @@
 					d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
 				></path>
 			</svg>
-			<p class="text-sm">{redirecting ? '正在进入组织…' : '正在加载会话…'}</p>
+			<p class="text-sm">加载中…</p>
 		</div>
 	</div>
 {:else if $session.error}
 	<div class="saas-status-panel">
 		<div class="saas-status-card">
 			<div
-				class="mx-auto mb-4 flex h-12 w-12 items-center justify-center border border-error-300 bg-error-100 text-error-700 font-bold"
+				class="mx-auto mb-3 flex h-12 w-12 items-center justify-center border border-error-200 bg-error-50 text-error-700"
 			>
 				!
 			</div>
@@ -192,7 +167,7 @@
 	<div class="saas-status-panel">
 		<div class="saas-status-card">
 			<div
-				class="mx-auto mb-5 flex h-12 w-12 items-center justify-center border border-primary-700 bg-primary-600 text-white font-bold"
+				class="mx-auto mb-4 flex h-12 w-12 items-center justify-center border border-primary-700 bg-primary-600 text-sm font-bold text-white"
 			>
 				CPH
 			</div>
@@ -201,7 +176,7 @@
 			<button class="saas-btn-primary w-full" onclick={() => redirectToLogin()}>使用飞书登录</button>
 		</div>
 	</div>
-{:else if currentOrg() && isAdmin(currentOrg()!)}
+{:else if currentOrg() && isOrgAdmin(currentOrg()!)}
 	{@const org = currentOrg()!}
 	{@const me = $session.me!}
 	<div class="saas-shell">
@@ -226,17 +201,19 @@
 				</div>
 				<div class="min-w-0">
 					<div class="truncate text-sm font-semibold text-surface-900">组织后台</div>
-					<div class="truncate text-xs text-surface-600">Curriculum Hub</div>
+					<div class="truncate text-xs text-surface-600">{org.name}</div>
 				</div>
 			</div>

-			<div class="px-3 pb-3">
-				<div class="mb-1.5 flex items-center gap-1.5 text-xs font-medium text-surface-700">
-					<Icon name="org" class="h-3.5 w-3.5" />
-					组织
+			{#if me.organizations.length > 1}
+				<div class="px-3 pb-3">
+					<div class="mb-1.5 flex items-center gap-1.5 text-xs font-medium text-surface-700">
+						<Icon name="org" class="h-3.5 w-3.5" />
+						组织
+					</div>
+					<SelectField items={orgSelectItems(me.organizations)} value={org.slug} onchange={switchOrg} />
 				</div>
-				<SelectField items={orgSelectItems(me.organizations)} value={org.slug} onchange={switchOrg} />
-			</div>
+			{/if}

 			<nav class="flex-1 space-y-0.5 overflow-y-auto px-2 pb-3">
 				<p class="px-3 pb-1 pt-2 text-[11px] font-semibold uppercase tracking-wider text-surface-600">工作台</p>
@@ -306,13 +283,13 @@
 			</main>
 		</div>
 	</div>
-{:else if currentOrg() && !isAdmin(currentOrg()!) && isOnProjectRoute()}
+{:else if currentOrg() && !isOrgAdmin(currentOrg()!) && isOnProjectRoute()}
 	{@const org = currentOrg()!}
 	{@const me = $session.me!}
 	<div class="saas-shell">
 		<div class="saas-main">
 			<header class="saas-topbar">
-				<a href={`/admin/org/${org.slug}/projects`} class="saas-btn-ghost px-2!" aria-label="返回项目列表">
+				<a href={adminPath('projects')} class="saas-btn-ghost px-2!" aria-label="返回项目列表">
 					<Icon name="menu" class="h-5 w-5" />
 				</a>
 				<div class="min-w-0">
@@ -341,7 +318,7 @@
 			</main>
 		</div>
 	</div>
-{:else if currentOrg() && !isAdmin(currentOrg()!)}
+{:else if currentOrg() && !isOrgAdmin(currentOrg()!)}
 	{@const denied = currentOrg()!}
 	<div class="saas-status-panel">
 		<div class="saas-status-card">
@@ -350,7 +327,7 @@
 				组织 <strong>{denied.name}</strong>（/{denied.slug}）中你的角色是
 				<span class="saas-badge-neutral mx-1">{orgRoleLabel(denied.role)}</span>。普通成员仅可访问自己有授权的项目。
 			</p>
-			<a class="saas-btn-primary" href={`/admin/org/${denied.slug}/projects`}>查看我的项目</a>
+			<a class="saas-btn-primary" href={adminPath('projects')}>查看我的项目</a>
 			{#if memberships().length > 1}
 				<p class="saas-label text-left mb-1.5 mt-3">切换到其他组织</p>
 				<div class="mb-4">
@@ -361,14 +338,14 @@
 		</div>
 	</div>
 {:else if memberships().length > 0}
-	{@const denied = pickHomeOrg()!}
+	{@const denied = resolveOrg($session.me) ?? memberships()[0]!}
 	<div class="saas-status-panel">
 		<div class="saas-status-card">
 			<h2 class="mb-2 text-lg font-semibold">正在跳转…</h2>
 			<p class="mb-5 text-sm text-surface-700">
 				即将进入 <strong>{denied.name}</strong>（/{denied.slug}）的项目。
 			</p>
-			<a class="saas-btn-primary" href={`/admin/org/${denied.slug}/projects`}>立即进入</a>
+			<a class="saas-btn-primary" href={adminPath('projects')}>立即进入</a>
 			<button class="saas-btn-ghost mt-3" onclick={handleLogout}>退出登录</button>
 		</div>
 	</div>
@@ -11,7 +11,7 @@
 			return r === 'OWNER' || r === 'ADMIN';
 		});
 		const target = admin ?? me.organizations[0];
-		return target ? `/admin/org/${target.slug}` : null;
+		return target ? `/admin` : null;
 	}

 	onMount(() => {
@@ -2,6 +2,7 @@
 	import { page } from '$app/state';
 	import { api, type OrgMembership } from '$lib/api';
 	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
 	import { fmtCost, fmtNum, orgRoleLabel } from '$lib/format';
 	import PageHeader from '$lib/components/PageHeader.svelte';
 	import StatCard from '$lib/components/StatCard.svelte';
@@ -10,7 +11,8 @@
 	import SwitchControl from '$lib/components/SwitchControl.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';

-	let orgSlug = $derived(page.params.slug ?? '');
+	const orgFromSession = $derived(resolveOrg($session.me, page.url.search));
+	let orgSlug = $derived(orgFromSession?.slug ?? '');
 	let org = $derived($session.me?.organizations.find((o) => o.slug === orgSlug) as OrgMembership | undefined);

 	let settings = $state<{ membersCanCreateProjects: boolean } | null>(null);
@@ -94,19 +96,56 @@
 	<div class="mb-4 flex items-end justify-between gap-3">
 		<div>
 			<h2 class="saas-section-title">用量概览</h2>
-			<p class="saas-muted">全组织智能体运行汇总</p>
+			<p class="saas-muted">totals 含全部 UsageFact；分账明细见用量页。</p>
 		</div>
+		<a class="saas-btn-secondary py-1.5! text-sm" href={`/admin/usage`}>完整用量报告</a>
 	</div>

 	<div class="mb-6 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
 		<StatCard label="运行总数" value={fmtNum(usage.totals.runCount)} />
 		<StatCard label="有成本运行" value={fmtNum(usage.totals.runsWithCost)} />
-		<StatCard label="无成本运行" value={fmtNum(usage.totals.runsWithoutCost)} />
+		<StatCard label="无成本运行" value={fmtNum(usage.totals.runsWithoutCost)} hint="未知 ≠ $0" />
 		<StatCard label="输入 tokens" value={fmtNum(usage.totals.inputTokens)} />
 		<StatCard label="输出 tokens" value={fmtNum(usage.totals.outputTokens)} />
 		<StatCard label="成本 (USD)" value={fmtCost(usage.totals.costUsd)} />
 	</div>

+	{#if usage.breakdown.length > 0}
+		<div class="saas-card overflow-hidden mb-6">
+			<div class="border-b border-surface-200 px-5 py-3 flex items-center justify-between gap-3">
+				<div>
+					<h3 class="text-sm font-semibold text-surface-800">消费来源（Top）</h3>
+					<p class="saas-muted text-xs">模型完成 vs 外部能力，按成本降序前 5</p>
+				</div>
+				<a class="text-sm text-primary-700 hover:underline" href={`/admin/usage`}>查看全部分账</a>
+			</div>
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>类型</th>
+							<th>供应方</th>
+							<th>模型 / 能力</th>
+							<th>次数</th>
+							<th>成本</th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each [...usage.breakdown].sort((a, b) => (b.costUsd ?? -1) - (a.costUsd ?? -1)).slice(0, 5) as row}
+							<tr>
+								<td class="text-sm">{row.kind === 'external_capability' ? '外部能力' : row.kind === 'model_completion' ? '模型完成' : row.kind}</td>
+								<td class="font-mono text-xs">{row.provider}</td>
+								<td class="font-mono text-xs">{row.capabilityId ?? row.model ?? '—'}</td>
+								<td class="tabular-nums">{fmtNum(row.factCount)}</td>
+								<td class="tabular-nums">{fmtCost(row.costUsd)}</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		</div>
+	{/if}
+
 	<div class="saas-card overflow-hidden">
 		<div class="border-b border-surface-200 px-5 py-3">
 			<h3 class="text-sm font-semibold text-surface-800">按项目用量</h3>
@@ -129,7 +168,11 @@
 					<tbody>
 						{#each usage.projects as p}
 							<tr>
-								<td class="font-medium">{p.projectName}</td>
+								<td class="font-medium">
+									<a class="hover:text-primary-700 hover:underline" href={`/admin/projects/${p.projectId}`}>
+										{p.projectName}
+									</a>
+								</td>
 								<td class="tabular-nums">{fmtNum(p.runCount)}</td>
 								<td class="tabular-nums text-surface-600">{fmtNum(p.inputTokens)} / {fmtNum(p.outputTokens)}</td>
 								<td class="tabular-nums">{fmtCost(p.costUsd)}</td>
@@ -0,0 +1,205 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type CapabilityConnection } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import { fmtDate } from '$lib/format';
+	import { Label } from 'bits-ui';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import { toastError, toastSuccess } from '$lib/toast';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+
+	const KNOWN_CAPABILITIES = [
+		{ id: 'pdf_to_md_bundle', label: 'PDF → Markdown', description: '将 PDF 转换为带图片的 Markdown bundle（阿里云文档智能，含公式 LaTeX 识别）' },
+		{ id: 'audio_video_to_text', label: '音视频 → 文本', description: '将音频/视频转写为文本（阿里云文档智能，按秒计费）' },
+	] as const;
+
+	let connections = $state<Map<string, CapabilityConnection>>(new Map());
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+
+	let editingCap = $state<string | null>(null);
+	let accessKeyId = $state('');
+	let accessKeySecret = $state('');
+	let endpoint = $state('docmind-api.cn-hangzhou.aliyuncs.com');
+	let saving = $state(false);
+	let disabling = $state<string | null>(null);
+
+	async function load() {
+		loading = true;
+		error = null;
+		try {
+			const res = await api.capabilityConnections(slug);
+			connections = new Map(res.connections.map((c) => [c.capabilityId, c]));
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function startEdit(capId: string) {
+		editingCap = capId;
+		accessKeyId = '';
+		accessKeySecret = '';
+		endpoint = 'docmind-api.cn-hangzhou.aliyuncs.com';
+	}
+
+	function cancelEdit() {
+		editingCap = null;
+	}
+
+	async function save(capId: string) {
+		if (accessKeyId.trim() === '' || accessKeySecret.trim() === '' || endpoint.trim() === '') {
+			toastError('AccessKey ID、AccessKey Secret、Endpoint 均为必填');
+			return;
+		}
+		saving = true;
+		try {
+			const result = await api.rotateCapabilityConnection(slug, capId, {
+				accessKeyId: accessKeyId.trim(),
+				accessKeySecret: accessKeySecret.trim(),
+				endpoint: endpoint.trim(),
+			});
+			connections.set(capId, result);
+			connections = new Map(connections);
+			editingCap = null;
+			toastSuccess('能力凭据已保存');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			saving = false;
+		}
+	}
+
+	async function disable(capId: string) {
+		if (!confirm('停用后该能力将不可用，确定停用？')) return;
+		disabling = capId;
+		try {
+			const result = await api.disableCapabilityConnection(slug, capId);
+			connections.set(capId, result);
+			connections = new Map(connections);
+			toastSuccess('已停用能力连接');
+		} catch (err) {
+			toastError(err instanceof Error ? err.message : String(err));
+		} finally {
+			disabling = null;
+		}
+	}
+
+	function statusBadge(status: string): string {
+		if (status === 'ACTIVE') return 'saas-badge-primary';
+		if (status === 'DISABLED') return 'saas-badge-error';
+		return 'saas-badge-muted';
+	}
+
+	function statusLabel(status: string): string {
+		if (status === 'ACTIVE') return '已启用';
+		if (status === 'DISABLED') return '已停用';
+		return '草稿';
+	}
+
+	$effect(() => {
+		if (slug) load();
+	});
+</script>
+
+<PageHeader
+	title="外部能力"
+	description="管理文档/媒体转换服务的组织级凭据（ADR-0027）。凭据按组织隔离、版本化信封存储，缺失或校验失败即 fail-closed。"
+/>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else}
+	<div class="space-y-6">
+		{#each KNOWN_CAPABILITIES as cap}
+			{@const conn = connections.get(cap.id)}
+			<div class="saas-card-pad">
+				<div class="mb-3 flex items-start justify-between gap-3">
+					<div>
+						<div class="flex items-center gap-2">
+							<h3 class="saas-section-title">{cap.label}</h3>
+							{#if conn}
+								<span class={statusBadge(conn.status)}>{statusLabel(conn.status)}</span>
+							{:else}
+								<span class="saas-badge-muted">未配置</span>
+							{/if}
+						</div>
+						<p class="saas-muted mt-1 text-sm">{cap.description}</p>
+						<p class="mt-0.5 font-mono text-xs text-surface-500">{cap.id}</p>
+					</div>
+					<div class="flex items-center gap-2">
+						{#if conn?.status === 'ACTIVE'}
+							<button
+								class="saas-btn-ghost text-sm"
+								onclick={() => disable(cap.id)}
+								disabled={disabling === cap.id}
+							>
+								{disabling === cap.id ? '停用中…' : '停用'}
+							</button>
+						{/if}
+						<button
+							class="saas-btn-primary text-sm"
+							onclick={() => startEdit(cap.id)}
+							disabled={editingCap === cap.id}
+						>
+							{conn ? '轮换凭据' : '配置凭据'}
+						</button>
+					</div>
+				</div>
+
+				{#if conn}
+					<dl class="space-y-1.5 text-sm text-surface-700">
+						<div class="flex justify-between">
+							<dt class="text-surface-500">版本</dt>
+							<dd class="font-mono">{conn.activeVersion ?? '—'}</dd>
+						</div>
+						<div class="flex justify-between">
+							<dt class="text-surface-500">密钥 ID</dt>
+							<dd class="font-mono text-xs">{conn.keyId ?? '—'}</dd>
+						</div>
+						<div class="flex justify-between">
+							<dt class="text-surface-500">更新时间</dt>
+							<dd>{fmtDate(conn.updatedAt)}</dd>
+						</div>
+					</dl>
+				{/if}
+
+				{#if editingCap === cap.id}
+					<div class="mt-4 border-t border-surface-100 pt-4">
+						<p class="saas-muted mb-3 text-sm">
+							阿里云 RAM 用户的 AccessKey。密钥仅写入新版本，旧版本归档。
+						</p>
+						<div class="grid gap-4">
+							<div>
+								<Label.Root class="saas-label" for="ak-id-{cap.id}">AccessKey ID</Label.Root>
+								<input id="ak-id-{cap.id}" class="saas-input font-mono text-sm" bind:value={accessKeyId} />
+							</div>
+							<div>
+								<Label.Root class="saas-label" for="ak-secret-{cap.id}">AccessKey Secret</Label.Root>
+								<input id="ak-secret-{cap.id}" class="saas-input" type="password" bind:value={accessKeySecret} />
+							</div>
+							<div>
+								<Label.Root class="saas-label" for="endpoint-{cap.id}">Endpoint</Label.Root>
+								<input id="endpoint-{cap.id}" class="saas-input font-mono text-sm" bind:value={endpoint} />
+							</div>
+						</div>
+						<div class="mt-4 flex items-center justify-end gap-3">
+							<button class="saas-btn-ghost" onclick={cancelEdit} disabled={saving}>取消</button>
+							<button class="saas-btn-primary" onclick={() => save(cap.id)} disabled={saving}>
+								{saving ? '保存中…' : '保存'}
+							</button>
+						</div>
+					</div>
+				{/if}
+			</div>
+		{/each}
+	</div>
+{/if}
@@ -1,13 +1,16 @@
 <script lang="ts">
 	import { page } from '$app/state';
 	import { api, type CapacityDimension, type CapacityDimensionRow, type CapacityPolicyView } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
 	import PageHeader from '$lib/components/PageHeader.svelte';
 	import LoadingState from '$lib/components/LoadingState.svelte';
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
 	import EmptyState from '$lib/components/EmptyState.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';

-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');

 	// Friendlier, user-facing labels. No spec jargon (墙钟 → 运行时长, etc.).
 	const DIMENSION_LABELS: Record<CapacityDimension, string> = {
@@ -1,6 +1,8 @@
 <script lang="ts">
 	import { page } from '$app/state';
 	import { api, type FeishuApplicationConnection } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
 	import { fmtDate } from '$lib/format';
 	import { Label } from 'bits-ui';
 	import PageHeader from '$lib/components/PageHeader.svelte';
@@ -8,7 +10,8 @@
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';

-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');

 	let connection = $state<FeishuApplicationConnection | null>(null);
 	let loading = $state(true);
@@ -1,6 +1,8 @@
 <script lang="ts">
 	import { page } from '$app/state';
 	import { api, type OrgMember } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
 	import { fmtDate } from '$lib/format';
 	import { ORG_ROLES, ORG_ROLE_LABELS, PERMISSION_ROLE_LABELS } from '$lib/constants';
 	import PageHeader from '$lib/components/PageHeader.svelte';
@@ -10,7 +12,8 @@
 	import SelectField from '$lib/components/SelectField.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';

-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
 	const roleItems = ORG_ROLES.map((r) => ({ value: r, label: ORG_ROLE_LABELS[r] }));
 	const permHint = Object.values(PERMISSION_ROLE_LABELS).join(' / ');

@@ -0,0 +1,23 @@
+<script lang="ts">
+	/**
+	 * Legacy bookmarks: /admin/org/:slug[/...] → /admin[/...]
+	 * Tenancy lives on the silo host, not the path.
+	 */
+	import { onMount } from 'svelte';
+	import { goto } from '$app/navigation';
+	import { page } from '$app/state';
+
+	onMount(() => {
+		const raw = page.params.path ?? '';
+		const segments = raw.split('/').filter(Boolean);
+		// Drop the old org slug (first segment) when present.
+		const rest = segments.length > 0 ? segments.slice(1).join('/') : '';
+		const target = rest === '' ? '/admin' : `/admin/${rest}`;
+		const q = page.url.search;
+		void goto(`${target}${q}`, { replaceState: true });
+	});
+</script>
+
+<div class="saas-status-panel">
+	<p class="text-sm text-surface-600">正在重定向到新地址…</p>
+</div>
@@ -2,6 +2,7 @@
 	import { page } from '$app/state';
 	import { api, type ExplorerData, type ExplorerFolder, type ExplorerProject, type OrgMembership } from '$lib/api';
 	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
 	import FolderTree from '$lib/components/FolderTree.svelte';
 	import PageHeader from '$lib/components/PageHeader.svelte';
 	import LoadingState from '$lib/components/LoadingState.svelte';
@@ -13,10 +14,8 @@
 	import { fmtDate } from '$lib/format';
 	import { toastError, toastSuccess } from '$lib/toast';

-	const slug = $derived(page.params.slug ?? '');
-	const org = $derived(
-		($session.me?.organizations.find((o) => o.slug === slug) as OrgMembership | undefined) ?? null,
-	);
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
 	const isAdmin = $derived(!!org && (org.role === 'OWNER' || org.role === 'ADMIN'));

 	let data = $state<ExplorerData | null>(null);
@@ -32,6 +31,18 @@
 	let projectName = $state('');
 	let projectFolder = $state('');

+	function openFolderModal(parentId: string) {
+		folderName = '';
+		folderParent = parentId;
+		showFolderModal = true;
+	}
+
+	function openProjectModal(folderId: string) {
+		projectName = '';
+		projectFolder = folderId;
+		showProjectModal = true;
+	}
+
 	async function load() {
 		loading = true;
 		error = null;
@@ -77,7 +88,7 @@
 			projectName = '';
 			projectFolder = '';
 			showProjectModal = false;
-			window.location.href = `/admin/org/${slug}/projects/${res.id}`;
+			window.location.href = `/admin/projects/${res.id}`;
 		} catch (err) {
 			toastError(err instanceof Error ? err.message : String(err));
 		}
@@ -113,8 +124,8 @@
 {:else if isAdmin && data}
 	<PageHeader title="项目" description="文件夹是透明组织节点；项目是权限边界。">
 		{#snippet actions()}
-			<button class="saas-btn-secondary" onclick={() => (showFolderModal = true)}>新建文件夹</button>
-			<button class="saas-btn-primary" onclick={() => (showProjectModal = true)}>新建项目</button>
+			<button class="saas-btn-secondary" onclick={() => openFolderModal('')}>新建文件夹</button>
+			<button class="saas-btn-primary" onclick={() => openProjectModal('')}>新建项目</button>
 		{/snippet}
 	</PageHeader>

@@ -122,7 +133,14 @@
 		{#if data.projects.filter((p) => !p.folderId).length === 0 && data.folders.filter((f) => !f.parentId).length === 0}
 			<EmptyState title="暂无项目" description="新建文件夹或项目，开始组织你的教研资产。" />
 		{:else}
-			<FolderTree folders={data.folders} projects={data.projects} parentId={null} {slug} />
+			<FolderTree
+				folders={data.folders}
+				projects={data.projects}
+				parentId={null}
+				{slug}
+				onCreateFolder={openFolderModal}
+				onCreateProject={openProjectModal}
+			/>
 		{/if}
 	</div>

@@ -190,7 +208,7 @@
 				</thead>
 				<tbody>
 					{#each myProjects as p}
-						<tr class="cursor-pointer" onclick={() => (window.location.href = `/admin/org/${slug}/projects/${p.id}`)}>
+						<tr class="cursor-pointer" onclick={() => (window.location.href = `/admin/projects/${p.id}`)}>
 							<td class="font-medium">{p.name}</td>
 							<td class="font-mono text-xs">{p.binding ? `群 ${p.binding.chatId}` : '—'}</td>
 							<td class="text-surface-700">{fmtDate(p.createdAt)}</td>
@@ -7,8 +7,19 @@
 		type TeamRow,
 		type SessionSummary,
 		type ExplorerData,
+		type ProjectUsageReport,
 	} from '$lib/api';
-	import { fmtDate, permissionRoleLabel } from '$lib/format';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import {
+		fmtCost,
+		fmtDate,
+		fmtNum,
+		fmtQuantity,
+		fmtTokens,
+		permissionRoleLabel,
+		usageKindLabel,
+	} from '$lib/format';
 	import { PERMISSION_ROLES, PERMISSION_ROLE_LABELS } from '$lib/constants';
 	import PageHeader from '$lib/components/PageHeader.svelte';
 	import LoadingState from '$lib/components/LoadingState.svelte';
@@ -18,7 +29,8 @@
 	import Icon from '$lib/components/Icon.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';

-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
 	const projectId = $derived(page.params.projectId ?? '');
 	const roleItems = PERMISSION_ROLES.map((r) => ({ value: r, label: PERMISSION_ROLE_LABELS[r] }));
 	const roleChain = `${PERMISSION_ROLE_LABELS.READ} ⊂ ${PERMISSION_ROLE_LABELS.EDIT} ⊂ ${PERMISSION_ROLE_LABELS.MANAGE}`;
@@ -26,6 +38,7 @@
 	let proj = $state<ProjectDetail | null>(null);
 	let access = $state<TeamAccessEntry[]>([]);
 	let sessions = $state<SessionSummary[]>([]);
+	let projectUsage = $state<ProjectUsageReport | null>(null);
 	let teams = $state<TeamRow[]>([]);
 	let explorer = $state<ExplorerData | null>(null);
 	let loading = $state(true);
@@ -49,14 +62,18 @@
 			// Team list is needed for grant UI whenever the actor has project MANAGE
 			// (org admin or member). Sessions/explorer stay org-admin oversight only.
 			const needTeams = p.actorIsOrgAdmin === true || p.actorCanManageProject === true;
-			const [s, t, e] = await Promise.all([
+			const [s, t, e, u] = await Promise.all([
 				p.actorIsOrgAdmin ? api.sessions(slug, projectId) : Promise.resolve({ sessions: [] as SessionSummary[] }),
 				needTeams ? api.teams(slug) : Promise.resolve({ teams: [] as TeamRow[] }),
 				p.actorIsOrgAdmin ? api.explorer(slug) : Promise.resolve(null as ExplorerData | null),
+				p.actorIsOrgAdmin
+					? api.projectUsage(slug, projectId)
+					: Promise.resolve(null as ProjectUsageReport | null),
 			]);
 			sessions = s.sessions;
 			teams = t.teams;
 			explorer = e;
+			projectUsage = u;
 			if (p.actorIsOrgAdmin) {
 				moveFolder = p.folderId ?? '';
 			}
@@ -95,7 +112,7 @@
 		if (!confirm(`归档项目 ${proj?.name}?`)) return;
 		try {
 			await api.archiveProject(slug, projectId);
-			window.location.href = `/admin/org/${slug}/projects`;
+			window.location.href = `/admin/projects`;
 		} catch (err) {
 			toastError(err instanceof Error ? err.message : String(err));
 		}
@@ -156,7 +173,7 @@
 {:else if proj}
 	<div class="mb-2">
 		<a
-			href={`/admin/org/${slug}/projects`}
+			href={`/admin/projects`}
 			class="inline-flex items-center gap-1 text-sm text-surface-700 hover:text-primary-600"
 		>
 			<Icon name="arrow-left" class="h-4 w-4" />
@@ -269,9 +286,67 @@
 	</div>

 	{#if actorIsOrgAdmin}
+		{#if projectUsage}
+			<div class="saas-card overflow-hidden mb-6">
+				<div class="border-b border-surface-200 px-5 py-3 flex items-center justify-between gap-3">
+					<div>
+						<h3 class="text-sm font-semibold">项目用量分账</h3>
+						<p class="saas-muted mt-0.5 text-xs">
+							{fmtNum(projectUsage.runCount)} 次运行 · 成本 {fmtCost(projectUsage.costUsd)} · tokens
+							{fmtTokens(projectUsage.inputTokens, projectUsage.outputTokens)}
+						</p>
+					</div>
+					<a class="text-sm text-primary-700 hover:underline" href={`/admin/usage`}>组织报告</a>
+				</div>
+				{#if projectUsage.breakdown.length === 0}
+					<div class="px-5 py-4 text-sm text-surface-600">尚无 UsageFact。</div>
+				{:else}
+					<div class="overflow-x-auto">
+						<table class="data-table">
+							<thead>
+								<tr>
+									<th>类型</th>
+									<th>供应方</th>
+									<th>模型 / 能力</th>
+									<th>次数</th>
+									<th>计量</th>
+									<th>成本</th>
+								</tr>
+							</thead>
+							<tbody>
+								{#each projectUsage.breakdown as row}
+									<tr>
+										<td>
+											<span
+												class={row.kind === 'external_capability' ? 'saas-badge-primary' : 'saas-badge-success'}
+											>
+												{usageKindLabel(row.kind)}
+											</span>
+										</td>
+										<td class="font-mono text-xs">{row.provider}</td>
+										<td class="font-mono text-xs">{row.capabilityId ?? row.model ?? '—'}</td>
+										<td class="tabular-nums">{fmtNum(row.factCount)}</td>
+										<td class="tabular-nums text-xs">
+											{#if row.unit}
+												{fmtQuantity(row.quantity, row.unit)}
+											{:else}
+												{fmtTokens(row.inputTokens, row.outputTokens)}
+											{/if}
+										</td>
+										<td class="tabular-nums">{fmtCost(row.costUsd)}</td>
+									</tr>
+								{/each}
+							</tbody>
+						</table>
+					</div>
+				{/if}
+			</div>
+		{/if}
+
 		<div class="saas-card overflow-hidden">
 			<div class="border-b border-surface-200 px-5 py-3">
 				<h3 class="text-sm font-semibold">智能体会话</h3>
+				<p class="saas-muted mt-0.5 text-xs">点进会话可查看每次 run 的 UsageFact 分账（模型 / 外部能力）。</p>
 			</div>
 			{#if sessions.length === 0}
 				<EmptyState title="暂无会话" description="飞书侧触发智能体后会显示在此。" />
@@ -283,6 +358,7 @@
 							<th>模型</th>
 							<th>运行次数</th>
 							<th>更新</th>
+							<th></th>
 						</tr>
 					</thead>
 					<tbody>
@@ -292,6 +368,14 @@
 								<td class="font-mono text-xs">{s.model}</td>
 								<td class="tabular-nums">{s.runCount}</td>
 								<td class="text-surface-700">{fmtDate(s.updatedAt)}</td>
+								<td class="text-right">
+									<a
+										class="text-sm text-primary-700 hover:underline"
+										href={`/admin/sessions/${s.id}`}
+									>
+										详情
+									</a>
+								</td>
 							</tr>
 						{/each}
 					</tbody>
@@ -1,6 +1,8 @@
 <script lang="ts">
 	import { page } from '$app/state';
 	import { api, type ProviderConnectionRow } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
 	import { fmtDate, providerModeLabel } from '$lib/format';
 	import { Label } from 'bits-ui';
 	import PageHeader from '$lib/components/PageHeader.svelte';
@@ -8,7 +10,8 @@
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';

-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');

 	let connections = $state<ProviderConnectionRow[]>([]);
 	let loading = $state(true);
@@ -1,6 +1,8 @@
 <script lang="ts">
 	import { page } from '$app/state';
 	import { api, type AgentRoleRow, type AgentModelRow, type AgentSkillRow } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
 	import PageHeader from '$lib/components/PageHeader.svelte';
 	import LoadingState from '$lib/components/LoadingState.svelte';
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
@@ -8,7 +10,8 @@
 	import RoleCard from '$lib/components/RoleCard.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';

-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');

 	let roles = $state<AgentRoleRow[]>([]);
 	let models = $state<AgentModelRow[]>([]);
@@ -24,10 +27,15 @@
 		loading = true;
 		error = null;
 		try {
-			const [r, m, s] = await Promise.all([api.agentRoles(slug), api.agentModels(slug), api.agentSkills(slug)]);
+			const [r, s] = await Promise.all([api.agentRoles(slug), api.agentSkills(slug)]);
 			roles = r.roles;
-			models = m.models;
 			skills = s.skills;
+			// Model fetch hits the provider API and may fail or be slow; load it
+			// independently so roles remain editable even without a model list.
+			models = [];
+			api.agentModels(slug)
+				.then((m) => { models = m.models; })
+				.catch((err) => { toastError(`模型列表加载失败：${err instanceof Error ? err.message : String(err)}`); });
 		} catch (err) {
 			error = err instanceof Error ? err.message : String(err);
 		} finally {
@@ -0,0 +1,238 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type SessionDetail, type SessionRunRow, type UsageFactRow } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import {
+		fmtCost,
+		fmtDate,
+		fmtNum,
+		fmtQuantity,
+		fmtTokens,
+		runStatusLabel,
+		usageKindLabel,
+	} from '$lib/format';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+	import Icon from '$lib/components/Icon.svelte';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+	const sessionId = $derived(page.params.sessionId ?? '');
+
+	let detail = $state<SessionDetail | null>(null);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+	let expandedRunId = $state<string | null>(null);
+
+	async function load() {
+		if (!slug || !sessionId) return;
+		loading = true;
+		error = null;
+		try {
+			detail = await api.session(slug, sessionId);
+			if (detail.runs.length > 0) {
+				expandedRunId = detail.runs[0]!.id;
+			}
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function statusClass(status: string): string {
+		const key = status.toUpperCase();
+		if (key === 'COMPLETED') return 'saas-badge-success';
+		if (key === 'FAILED' || key === 'TIMED_OUT' || key === 'CANCELED') return 'saas-badge-error';
+		return 'saas-badge-primary';
+	}
+
+	function factMeter(f: UsageFactRow): string {
+		if (f.unit) return fmtQuantity(f.quantity, f.unit);
+		if (f.inputTokens !== null || f.outputTokens !== null) {
+			return fmtTokens(f.inputTokens, f.outputTokens);
+		}
+		return '—';
+	}
+
+	function factSource(f: UsageFactRow): string {
+		if (f.capabilityId) return f.capabilityId;
+		if (f.model) return f.model;
+		return '—';
+	}
+
+	function runCostHint(run: SessionRunRow): string {
+		const factCost = run.usageFacts.reduce<number | null>((acc, f) => {
+			if (f.costUsd === null) return acc;
+			return (acc ?? 0) + f.costUsd;
+		}, null);
+		const cache = run.costUsd;
+		if (factCost !== null && cache !== null && Math.abs(factCost - cache) > 1e-9) {
+			return `运行缓存 ${fmtCost(cache)}；事实合计 ${fmtCost(factCost)}（缓存可能未含外部能力）`;
+		}
+		if (factCost !== null) return `事实合计 ${fmtCost(factCost)}`;
+		if (cache !== null) return `运行缓存 ${fmtCost(cache)}`;
+		return '成本未知';
+	}
+
+	function toggleRun(id: string) {
+		expandedRunId = expandedRunId === id ? null : id;
+	}
+
+	$effect(() => {
+		if (slug && sessionId) void load();
+	});
+</script>
+
+{#if loading}
+	<LoadingState />
+{:else if error}
+	<ErrorBanner message={error} onretry={load} />
+{:else if detail}
+	<div class="mb-2">
+		<a
+			class="inline-flex items-center gap-1 text-sm text-surface-700 hover:text-primary-700"
+			href={`/admin/projects/${detail.project.id}`}
+		>
+			<Icon name="arrow-left" class="h-4 w-4" />
+			返回项目 {detail.project.name}
+		</a>
+	</div>
+
+	<PageHeader
+		title={detail.title?.trim() || '未命名会话'}
+		description={`${detail.provider} · ${detail.roleId} · ${detail.model}`}
+	/>
+
+	<div class="saas-card-pad mb-6">
+		<dl class="grid gap-x-8 gap-y-3 text-sm sm:grid-cols-2 lg:grid-cols-3">
+			<div>
+				<dt class="text-surface-600">会话 ID</dt>
+				<dd class="mt-0.5 break-all font-mono text-xs">{detail.id}</dd>
+			</div>
+			<div>
+				<dt class="text-surface-600">项目</dt>
+				<dd class="mt-0.5">
+					<a class="text-primary-700 hover:underline" href={`/admin/projects/${detail.project.id}`}>
+						{detail.project.name}
+					</a>
+				</dd>
+			</div>
+			<div>
+				<dt class="text-surface-600">创建 / 更新</dt>
+				<dd class="mt-0.5 text-surface-800">{fmtDate(detail.createdAt)} · {fmtDate(detail.updatedAt)}</dd>
+			</div>
+			{#if detail.archivedAt}
+				<div>
+					<dt class="text-surface-600">已归档</dt>
+					<dd class="mt-0.5">{fmtDate(detail.archivedAt)}</dd>
+				</div>
+			{/if}
+			<div>
+				<dt class="text-surface-600">运行数</dt>
+				<dd class="mt-0.5 tabular-nums">{fmtNum(detail.runs.length)}</dd>
+			</div>
+		</dl>
+	</div>
+
+	<div class="mb-3">
+		<h2 class="saas-section-title">运行与计费事实</h2>
+		<p class="saas-muted">每条 UsageFact 是一次可计费消费；外部能力与模型完成分开列出。</p>
+	</div>
+
+	{#if detail.runs.length === 0}
+		<div class="saas-card">
+			<EmptyState title="尚无运行" description="此会话还没有 Agent run。" />
+		</div>
+	{:else}
+		<div class="space-y-3">
+			{#each detail.runs as run (run.id)}
+				{@const open = expandedRunId === run.id}
+				<div class="saas-card overflow-hidden">
+					<button
+						type="button"
+						class="flex w-full items-start justify-between gap-3 px-5 py-4 text-left hover:bg-surface-50"
+						onclick={() => toggleRun(run.id)}
+					>
+						<div class="min-w-0 space-y-1">
+							<div class="flex flex-wrap items-center gap-2">
+								<span class={statusClass(run.status)}>{runStatusLabel(run.status)}</span>
+								<span class="font-mono text-xs text-surface-700">{run.provider} / {run.model}</span>
+								<span class="font-mono text-[11px] text-surface-500">{run.id}</span>
+							</div>
+							<div class="text-xs text-surface-700">
+								{fmtDate(run.startedAt)}
+								{#if run.finishedAt}
+									→ {fmtDate(run.finishedAt)}
+								{/if}
+							</div>
+							<div class="text-xs text-surface-600">{runCostHint(run)}</div>
+							{#if run.error}
+								<div class="text-xs text-error-700">{run.error}</div>
+							{/if}
+						</div>
+						<div class="shrink-0 text-right text-sm">
+							<div class="tabular-nums text-surface-800">{fmtTokens(run.inputTokens, run.outputTokens)}</div>
+							<div class="tabular-nums font-medium">{fmtCost(run.costUsd)}</div>
+							<div class="mt-1 text-[11px] text-surface-600">{open ? '收起事实' : `${run.usageFacts.length} 条事实`}</div>
+						</div>
+					</button>
+
+					{#if open}
+						<div class="border-t border-surface-200">
+							{#if run.usageFacts.length === 0}
+								<div class="px-5 py-4">
+									<p class="text-sm text-surface-600">此 run 没有 UsageFact（可能尚未结束或未记费）。</p>
+								</div>
+							{:else}
+								<div class="overflow-x-auto">
+									<table class="data-table">
+										<thead>
+											<tr>
+												<th>时间</th>
+												<th>类型</th>
+												<th>供应方</th>
+												<th>模型 / 能力</th>
+												<th>计量</th>
+												<th>成本</th>
+												<th>来源</th>
+												<th>关联 ID</th>
+											</tr>
+										</thead>
+										<tbody>
+											{#each run.usageFacts as fact}
+												<tr>
+													<td class="whitespace-nowrap text-xs text-surface-700">{fmtDate(fact.occurredAt)}</td>
+													<td>
+														<span
+															class={fact.kind === 'external_capability'
+																? 'saas-badge-primary'
+																: 'saas-badge-success'}
+														>
+															{usageKindLabel(fact.kind)}
+														</span>
+													</td>
+													<td class="font-mono text-xs">{fact.provider}</td>
+													<td class="font-mono text-xs">{factSource(fact)}</td>
+													<td class="tabular-nums text-xs">{factMeter(fact)}</td>
+													<td class="tabular-nums">{fmtCost(fact.costUsd)}</td>
+													<td class="font-mono text-[11px] text-surface-600">{fact.costSource}</td>
+													<td class="max-w-[10rem] truncate font-mono text-[11px] text-surface-500" title={fact.correlationId ?? ''}>
+														{fact.correlationId ?? '—'}
+													</td>
+												</tr>
+											{/each}
+										</tbody>
+									</table>
+								</div>
+							{/if}
+						</div>
+					{/if}
+				</div>
+			{/each}
+		</div>
+	{/if}
+{/if}
@@ -1,6 +1,8 @@
 <script lang="ts">
 	import { page } from '$app/state';
 	import { api, type AgentSkillRow, type SkillFileEntry } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
 	import PageHeader from '$lib/components/PageHeader.svelte';
 	import LoadingState from '$lib/components/LoadingState.svelte';
 	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
@@ -8,7 +10,8 @@
 	import SkillEditor from '$lib/components/SkillEditor.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';

-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');

 	let skills = $state<AgentSkillRow[]>([]);
 	let loading = $state(true);
@@ -2,6 +2,8 @@
 	import { Collapsible } from 'bits-ui';
 	import { page } from '$app/state';
 	import { api, type TeamRow, type TeamMemberRow } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
 	import { fmtDate } from '$lib/format';
 	import PageHeader from '$lib/components/PageHeader.svelte';
 	import LoadingState from '$lib/components/LoadingState.svelte';
@@ -9,7 +11,8 @@
 	import EmptyState from '$lib/components/EmptyState.svelte';
 	import { toastError, toastSuccess } from '$lib/toast';

-	const slug = $derived(page.params.slug ?? '');
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');

 	let teams = $state<TeamRow[]>([]);
 	let loading = $state(true);
@@ -0,0 +1,241 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { api, type UsageReport, type UsageBreakdownRow } from '$lib/api';
+	import { session } from '$lib/session';
+	import { resolveOrg } from '$lib/org';
+	import {
+		fmtCost,
+		fmtDateOnly,
+		fmtNum,
+		fmtQuantity,
+		fmtTokens,
+		usageKindLabel,
+	} from '$lib/format';
+	import PageHeader from '$lib/components/PageHeader.svelte';
+	import StatCard from '$lib/components/StatCard.svelte';
+	import LoadingState from '$lib/components/LoadingState.svelte';
+	import ErrorBanner from '$lib/components/ErrorBanner.svelte';
+	import EmptyState from '$lib/components/EmptyState.svelte';
+
+	const org = $derived(resolveOrg($session.me, page.url.search));
+	const slug = $derived(org?.slug ?? '');
+
+	let usage = $state<UsageReport | null>(null);
+	let loading = $state(true);
+	let error = $state<string | null>(null);
+	let from = $state('');
+	let to = $state('');
+
+	function toIsoStart(dateLocal: string): string | undefined {
+		if (!dateLocal) return undefined;
+		const d = new Date(`${dateLocal}T00:00:00`);
+		return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+	}
+
+	function toIsoEnd(dateLocal: string): string | undefined {
+		if (!dateLocal) return undefined;
+		const d = new Date(`${dateLocal}T23:59:59.999`);
+		return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+	}
+
+	async function load() {
+		if (!slug) return;
+		loading = true;
+		error = null;
+		try {
+			usage = await api.usage(slug, {
+				...(toIsoStart(from) !== undefined ? { from: toIsoStart(from) } : {}),
+				...(toIsoEnd(to) !== undefined ? { to: toIsoEnd(to) } : {}),
+			});
+		} catch (err) {
+			error = err instanceof Error ? err.message : String(err);
+		} finally {
+			loading = false;
+		}
+	}
+
+	function clearRange() {
+		from = '';
+		to = '';
+		void load();
+	}
+
+	function sourceLabel(row: UsageBreakdownRow): string {
+		if (row.capabilityId) return row.capabilityId;
+		if (row.model) return row.model;
+		return '—';
+	}
+
+	function meterCell(row: UsageBreakdownRow): string {
+		if (row.unit) return fmtQuantity(row.quantity, row.unit);
+		if (row.inputTokens > 0 || row.outputTokens > 0) return fmtTokens(row.inputTokens, row.outputTokens);
+		return '—';
+	}
+
+	function meterHint(row: UsageBreakdownRow): string {
+		if (row.unit) return '非 token 计量';
+		if (row.inputTokens > 0 || row.outputTokens > 0) return 'in / out tokens';
+		return '无计量';
+	}
+
+	$effect(() => {
+		if (slug) void load();
+	});
+</script>
+
+{#if loading && !usage}
+	<LoadingState />
+{:else if error && !usage}
+	<ErrorBanner message={error} onretry={load} />
+{:else if usage}
+	<PageHeader
+		title="用量报告"
+		description="按 UsageFact 分账：模型完成与外部能力（PDF→MD、ASR 等）分开汇总。缺失成本计为未知，不为 0。"
+	/>
+
+	<div class="saas-card-pad mb-6">
+		<div class="flex flex-wrap items-end gap-3">
+			<div>
+				<label class="saas-label" for="usage-from">从</label>
+				<input id="usage-from" class="saas-input" type="date" bind:value={from} />
+			</div>
+			<div>
+				<label class="saas-label" for="usage-to">到</label>
+				<input id="usage-to" class="saas-input" type="date" bind:value={to} />
+			</div>
+			<button class="saas-btn-primary py-1.5! text-sm" type="button" onclick={load} disabled={loading}>
+				{loading ? '加载中…' : '应用筛选'}
+			</button>
+			<button class="saas-btn-secondary py-1.5! text-sm" type="button" onclick={clearRange} disabled={loading}>
+				清除
+			</button>
+			{#if usage.from || usage.to}
+				<p class="saas-muted grow text-right text-xs">
+					窗口：
+					{usage.from ? fmtDateOnly(usage.from) : '—'}
+					→
+					{usage.to ? fmtDateOnly(usage.to) : '—'}
+				</p>
+			{/if}
+		</div>
+		{#if error}
+			<p class="mt-3 text-sm text-error-700">{error}</p>
+		{/if}
+	</div>
+
+	<div class="mb-6 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+		<StatCard label="运行总数" value={fmtNum(usage.totals.runCount)} />
+		<StatCard
+			label="有成本 / 无成本"
+			value={`${fmtNum(usage.totals.runsWithCost)} / ${fmtNum(usage.totals.runsWithoutCost)}`}
+			hint="无成本 = 成本未知，不是 $0"
+		/>
+		<StatCard label="成本 (USD)" value={fmtCost(usage.totals.costUsd)} hint="仅汇总已知 costUsd" />
+		<StatCard label="输入 tokens" value={fmtNum(usage.totals.inputTokens)} hint="主要来自模型完成" />
+		<StatCard label="输出 tokens" value={fmtNum(usage.totals.outputTokens)} hint="主要来自模型完成" />
+		<StatCard
+			label="分账条目"
+			value={fmtNum(usage.breakdown.reduce((n, b) => n + b.factCount, 0))}
+			hint={`${fmtNum(usage.breakdown.length)} 个分项`}
+		/>
+	</div>
+
+	<div class="saas-card overflow-hidden mb-6">
+		<div class="border-b border-surface-200 px-5 py-3">
+			<h3 class="text-sm font-semibold text-surface-800">按来源分账</h3>
+			<p class="saas-muted mt-0.5 text-xs">
+				kind × provider × model/capability。外部能力显示页数/秒等计量，不与 tokens 混排。
+			</p>
+		</div>
+		{#if usage.breakdown.length === 0}
+			<EmptyState title="暂无用量事实" description="跑过智能体后，模型与外部能力消费会出现在此。" />
+		{:else}
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>类型</th>
+							<th>供应方</th>
+							<th>模型 / 能力</th>
+							<th>次数</th>
+							<th>计量</th>
+							<th>有成本 / 未知</th>
+							<th>成本</th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each usage.breakdown as row}
+							<tr>
+								<td>
+									<span
+										class={row.kind === 'external_capability'
+											? 'saas-badge-primary'
+											: row.kind === 'model_completion'
+												? 'saas-badge-success'
+												: 'saas-badge-primary'}
+									>
+										{usageKindLabel(row.kind)}
+									</span>
+								</td>
+								<td class="font-mono text-xs">{row.provider}</td>
+								<td class="font-mono text-xs">{sourceLabel(row)}</td>
+								<td class="tabular-nums">{fmtNum(row.factCount)}</td>
+								<td class="tabular-nums">
+									<div>{meterCell(row)}</div>
+									<div class="text-[11px] text-surface-600">{meterHint(row)}</div>
+								</td>
+								<td class="tabular-nums text-surface-700">
+									{fmtNum(row.factsWithCost)} / {fmtNum(row.factsWithoutCost)}
+								</td>
+								<td class="tabular-nums font-medium">{fmtCost(row.costUsd)}</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		{/if}
+	</div>
+
+	<div class="saas-card overflow-hidden">
+		<div class="border-b border-surface-200 px-5 py-3">
+			<h3 class="text-sm font-semibold text-surface-800">按项目</h3>
+			<p class="saas-muted mt-0.5 text-xs">项目仍是权限边界；行内成本已含该项目全部 fact 类型。</p>
+		</div>
+		{#if usage.projects.length === 0}
+			<EmptyState title="暂无项目" description="创建项目并触发智能体后会出现用量。" />
+		{:else}
+			<div class="overflow-x-auto">
+				<table class="data-table">
+					<thead>
+						<tr>
+							<th>项目</th>
+							<th>运行</th>
+							<th>有成本 / 未知</th>
+							<th>in / out tokens</th>
+							<th>成本</th>
+							<th></th>
+						</tr>
+					</thead>
+					<tbody>
+						{#each usage.projects as p}
+							<tr>
+								<td class="font-medium">{p.projectName}</td>
+								<td class="tabular-nums">{fmtNum(p.runCount)}</td>
+								<td class="tabular-nums text-surface-700">
+									{fmtNum(p.runsWithCost)} / {fmtNum(p.runsWithoutCost)}
+								</td>
+								<td class="tabular-nums text-surface-600">{fmtTokens(p.inputTokens, p.outputTokens)}</td>
+								<td class="tabular-nums">{fmtCost(p.costUsd)}</td>
+								<td class="text-right">
+									<a class="text-sm text-primary-700 hover:underline" href={`/admin/projects/${p.projectId}`}>
+										查看项目
+									</a>
+								</td>
+							</tr>
+						{/each}
+					</tbody>
+				</table>
+			</div>
+		{/if}
+	</div>
+{/if}
@@ -95,7 +95,7 @@ flock /var/lock/cph-hub-release-publish bash -c '
    exit 0
  fi
  cd "$HUB_DIR"
-  npm ci
+  PUPPETEER_SKIP_DOWNLOAD=1 npm ci
  npm ci --prefix admin-web
  npm run audit:production
  npm run build
@@ -63,7 +63,7 @@ if [ "$release_ready" = false ]; then
  # 2. Install deps (hub + admin-web), audit hub prod, build tsc + SPA, mark complete.
  # `npm run build` → tsc then admin:build → admin-web/build for registerStaticSpa.
  ssh "${SSH_OPTS[@]}" "$DEPLOY_USER@$HOST" \
-    "cd '$HUB_DIR' && npm ci && npm ci --prefix admin-web && npm run audit:production && npm run build && touch '$RELEASE_DIR/.complete'"
+    "cd '$HUB_DIR' && PUPPETEER_SKIP_DOWNLOAD=1 npm ci && npm ci --prefix admin-web && npm run audit:production && npm run build && touch '$RELEASE_DIR/.complete'"
 fi

 # 3. Ensure the service is installed (idempotent), then restart.
@@ -1,13 +1,16 @@
 {
  "name": "@paradigm/hub",
-  "version": "0.0.29",
+  "version": "0.0.36",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@paradigm/hub",
-      "version": "0.0.29",
+      "version": "0.0.36",
      "dependencies": {
+        "@alicloud/credentials": "^2.4.5",
+        "@alicloud/docmind-api20220711": "^1.4.15",
+        "@alicloud/tea-util": "^1.4.11",
        "@anthropic-ai/claude-agent-sdk": "^0.3.202",
        "@fastify/cookie": "^11.0.2",
        "@larksuiteoapi/node-sdk": "^1.70.0",
@@ -74,6 +77,175 @@
        "zod": "^3.25.76 || ^4.1.8"
      }
    },
+    "node_modules/@alicloud/credentials": {
+      "version": "2.4.5",
+      "resolved": "https://registry.npmjs.org/@alicloud/credentials/-/credentials-2.4.5.tgz",
+      "integrity": "sha512-od1ufCxOO7cP2R4EVFliOB0kGo9lUXCibyj/mzmI6yLhxeqhqsegTzVsx5p2NJJsceKJnYcmye7FWKyLJAFBkw==",
+      "license": "MIT",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.8.0",
+        "httpx": "^2.3.3",
+        "ini": "^1.3.5",
+        "kitx": "^2.0.0"
+      }
+    },
+    "node_modules/@alicloud/darabonba-array": {
+      "version": "0.1.2",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-array/-/darabonba-array-0.1.2.tgz",
+      "integrity": "sha512-ZPuQ+bJyjrd8XVVm55kl+ypk7OQoi1ZH/DiToaAEQaGvgEjrTcvQkg71//vUX/6cvbLIF5piQDvhrLb+lUEIPQ==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.7.1"
+      }
+    },
+    "node_modules/@alicloud/darabonba-encode-util": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-encode-util/-/darabonba-encode-util-0.0.2.tgz",
+      "integrity": "sha512-mlsNctkeqmR0RtgE1Rngyeadi5snLOAHBCWEtYf68d7tyKskosXDTNeZ6VCD/UfrUu4N51ItO8zlpfXiOgeg3A==",
+      "license": "ISC",
+      "dependencies": {
+        "moment": "^2.29.1"
+      }
+    },
+    "node_modules/@alicloud/darabonba-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-map/-/darabonba-map-0.0.1.tgz",
+      "integrity": "sha512-2ep+G3YDvuI+dRYVlmER1LVUQDhf9kEItmVB/bbEu1pgKzelcocCwAc79XZQjTcQGFgjDycf3vH87WLDGLFMlw==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.7.1"
+      }
+    },
+    "node_modules/@alicloud/darabonba-signature-util": {
+      "version": "0.0.4",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-signature-util/-/darabonba-signature-util-0.0.4.tgz",
+      "integrity": "sha512-I1TtwtAnzLamgqnAaOkN0IGjwkiti//0a7/auyVThdqiC/3kyafSAn6znysWOmzub4mrzac2WiqblZKFcN5NWg==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/darabonba-encode-util": "^0.0.1"
+      }
+    },
+    "node_modules/@alicloud/darabonba-signature-util/node_modules/@alicloud/darabonba-encode-util": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-encode-util/-/darabonba-encode-util-0.0.1.tgz",
+      "integrity": "sha512-Sl5vCRVAYMqwmvXpJLM9hYoCHOMsQlGxaWSGhGWulpKk/NaUBArtoO1B0yHruJf1C5uHhEJIaylYcM48icFHgw==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.7.1",
+        "moment": "^2.29.1"
+      }
+    },
+    "node_modules/@alicloud/darabonba-string": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@alicloud/darabonba-string/-/darabonba-string-1.0.3.tgz",
+      "integrity": "sha512-NyWwrU8cAIesWk3uHL1Q7pTDTqLkCI/0PmJXC4/4A0MFNAZ9Ouq0iFBsRqvfyUujSSM+WhYLuTfakQXiVLkTMA==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.5.1"
+      }
+    },
+    "node_modules/@alicloud/docmind-api20220711": {
+      "version": "1.4.15",
+      "resolved": "https://registry.npmjs.org/@alicloud/docmind-api20220711/-/docmind-api20220711-1.4.15.tgz",
+      "integrity": "sha512-QmjSDPV52d2B5bd/Dk3Zeofu+cJFPKYS+MphIHqlulfYsOynLgOaDqTRMGTK/RhcmVCwG14CyZ/15GBF00GRFw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@alicloud/credentials": "^2.4.2",
+        "@alicloud/openapi-core": "^1.0.0",
+        "@darabonba/typescript": "^1.0.0"
+      }
+    },
+    "node_modules/@alicloud/endpoint-util": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/@alicloud/endpoint-util/-/endpoint-util-0.0.1.tgz",
+      "integrity": "sha512-+pH7/KEXup84cHzIL6UJAaPqETvln4yXlD9JzlrqioyCSaWxbug5FUobsiI6fuUOpw5WwoB3fWAtGbFnJ1K3Yg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.5.1",
+        "kitx": "^2.0.0"
+      }
+    },
+    "node_modules/@alicloud/gateway-pop": {
+      "version": "0.0.6",
+      "resolved": "https://registry.npmjs.org/@alicloud/gateway-pop/-/gateway-pop-0.0.6.tgz",
+      "integrity": "sha512-KF4I+JvfYuLKc3fWeWYIZ7lOVJ9jRW0sQXdXidZn1DKZ978ncfGf7i0LBfONGk4OxvNb/HD3/0yYhkgZgPbKtA==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/credentials": "^2",
+        "@alicloud/darabonba-array": "^0.1.0",
+        "@alicloud/darabonba-encode-util": "^0.0.2",
+        "@alicloud/darabonba-map": "^0.0.1",
+        "@alicloud/darabonba-signature-util": "^0.0.4",
+        "@alicloud/darabonba-string": "^1.0.2",
+        "@alicloud/endpoint-util": "^0.0.1",
+        "@alicloud/gateway-spi": "^0.0.8",
+        "@alicloud/openapi-util": "^0.3.2",
+        "@alicloud/tea-typescript": "^1.7.1",
+        "@alicloud/tea-util": "^1.4.8"
+      }
+    },
+    "node_modules/@alicloud/gateway-spi": {
+      "version": "0.0.8",
+      "resolved": "https://registry.npmjs.org/@alicloud/gateway-spi/-/gateway-spi-0.0.8.tgz",
+      "integrity": "sha512-KM7fu5asjxZPmrz9sJGHJeSU+cNQNOxW+SFmgmAIrITui5hXL2LB+KNRuzWmlwPjnuA2X3/keq9h6++S9jcV5g==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/credentials": "^2",
+        "@alicloud/tea-typescript": "^1.7.1"
+      }
+    },
+    "node_modules/@alicloud/openapi-core": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/@alicloud/openapi-core/-/openapi-core-1.0.8.tgz",
+      "integrity": "sha512-xs8LdgMDcEUqv13kZ4nl+Vd+Fc1mixTF0g1lm5QSrNWDaLUUD5vqpuMtvUZnKNnq9PITfUQ+8KunAvNQJpFo8g==",
+      "hasInstallScript": true,
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/credentials": "^2.4.2",
+        "@alicloud/gateway-pop": "0.0.6",
+        "@alicloud/gateway-spi": "^0.0.8",
+        "@darabonba/typescript": "^1.0.5"
+      }
+    },
+    "node_modules/@alicloud/openapi-util": {
+      "version": "0.3.3",
+      "resolved": "https://registry.npmjs.org/@alicloud/openapi-util/-/openapi-util-0.3.3.tgz",
+      "integrity": "sha512-vf0cQ/q8R2U7ZO88X5hDiu1yV3t/WexRj+YycWxRutkH/xVXfkmpRgps8lmNEk7Ar+0xnY8+daN2T+2OyB9F4A==",
+      "license": "ISC",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.7.1",
+        "@alicloud/tea-util": "^1.3.0",
+        "kitx": "^2.1.0",
+        "sm3": "^1.0.3"
+      }
+    },
+    "node_modules/@alicloud/tea-typescript": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@alicloud/tea-typescript/-/tea-typescript-1.8.0.tgz",
+      "integrity": "sha512-CWXWaquauJf0sW30mgJRVu9aaXyBth5uMBCUc+5vKTK1zlgf3hIqRUjJZbjlwHwQ5y9anwcu18r48nOZb7l2QQ==",
+      "license": "ISC",
+      "dependencies": {
+        "@types/node": "^12.0.2",
+        "httpx": "^2.2.6"
+      }
+    },
+    "node_modules/@alicloud/tea-typescript/node_modules/@types/node": {
+      "version": "12.20.55",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-12.20.55.tgz",
+      "integrity": "sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==",
+      "license": "MIT"
+    },
+    "node_modules/@alicloud/tea-util": {
+      "version": "1.4.11",
+      "resolved": "https://registry.npmjs.org/@alicloud/tea-util/-/tea-util-1.4.11.tgz",
+      "integrity": "sha512-HyPEEQ8F0WoZegiCp7sVdrdm6eBOB+GCvGl4182u69LDFktxfirGLcAx3WExUr1zFWkq2OSmBroTwKQ4w/+Yww==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.5.1",
+        "@darabonba/typescript": "^1.0.0",
+        "kitx": "^2.0.0"
+      }
+    },
    "node_modules/@anthropic-ai/claude-agent-sdk": {
      "version": "0.3.202",
      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.3.202.tgz",
@@ -234,6 +406,24 @@
        "node": ">=6.9.0"
      }
    },
+    "node_modules/@darabonba/typescript": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/@darabonba/typescript/-/typescript-1.0.5.tgz",
+      "integrity": "sha512-pfxHFVM8I3h8K2o8skpDQLMmR5iAeQ2eNpP1HrKDEm/9ZPF8aKwDKPwwEszT1NnIo0Y3++E7x1YsVkVpGjA/xw==",
+      "license": "Apache License 2.0",
+      "dependencies": {
+        "@alicloud/tea-typescript": "^1.5.1",
+        "http-proxy-agent": "^5.0.0",
+        "https-proxy-agent": "^5.0.1",
+        "httpx": "^2.3.2",
+        "lodash": "^4.17.21",
+        "moment": "^2.30.1",
+        "moment-timezone": "^0.5.45",
+        "socks-proxy-agent": "^6.2.1",
+        "ws": "^8.18.0",
+        "xml2js": "^0.6.2"
+      }
+    },
    "node_modules/@emnapi/core": {
      "version": "1.11.2",
      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.2.tgz",
@@ -1396,6 +1586,15 @@
      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
      "license": "MIT"
    },
+    "node_modules/@tootallnate/once": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@tootallnate/once/-/once-2.0.1.tgz",
+      "integrity": "sha512-HqmEUIGRJ5fSXchkVgR5F7qn48bDBzv0kWj/Kfu5e6uci4UlEeng4331LnBkWffb++Ei3FOVLxo8JJWMFBDMeQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 10"
+      }
+    },
    "node_modules/@tybys/wasm-util": {
      "version": "0.10.3",
      "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.3.tgz",
@@ -2830,6 +3029,20 @@
        "url": "https://opencollective.com/express"
      }
    },
+    "node_modules/http-proxy-agent": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-5.0.0.tgz",
+      "integrity": "sha512-n2hY8YdoRE1i7r6M0w9DIw5GgZN0G25P8zLCRQ8rjXtTU3vsNFBI/vWK/UIeE6g5MUUz6avwAPXmL6Fy9D/90w==",
+      "license": "MIT",
+      "dependencies": {
+        "@tootallnate/once": "2",
+        "agent-base": "6",
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
    "node_modules/https-proxy-agent": {
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz",
@@ -2843,6 +3056,25 @@
        "node": ">= 6"
      }
    },
+    "node_modules/httpx": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/httpx/-/httpx-2.3.3.tgz",
+      "integrity": "sha512-k1qv94u1b6e+XKCxVbLgYlOypVP9MPGpnN5G/vxFf6tDO4V3xpz3d6FUOY/s8NtPgaq5RBVVgSB+7IHpVxMYzw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "^20",
+        "debug": "^4.1.1"
+      }
+    },
+    "node_modules/httpx/node_modules/@types/node": {
+      "version": "20.19.43",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz",
+      "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
    "node_modules/iconv-lite": {
      "version": "0.7.3",
      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.3.tgz",
@@ -2867,12 +3099,17 @@
      "license": "ISC",
      "peer": true
    },
+    "node_modules/ini": {
+      "version": "1.3.8",
+      "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz",
+      "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==",
+      "license": "ISC"
+    },
    "node_modules/ip-address": {
      "version": "10.2.0",
      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
      "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
      "license": "MIT",
-      "peer": true,
      "engines": {
        "node": ">= 12"
      }
@@ -2972,6 +3209,15 @@
      "license": "BSD-2-Clause",
      "peer": true
    },
+    "node_modules/kitx": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/kitx/-/kitx-2.2.0.tgz",
+      "integrity": "sha512-tBMwe6AALTBQJb0woQDD40734NKzb0Kzi3k7wQj9ar3AbP9oqhoVrdXPh7rk2r00/glIgd0YbToIUJsnxWMiIg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "^22.5.4"
+      }
+    },
    "node_modules/light-my-request": {
      "version": "6.6.0",
      "resolved": "https://registry.npmjs.org/light-my-request/-/light-my-request-6.6.0.tgz",
@@ -3270,6 +3516,12 @@
        "url": "https://opencollective.com/parcel"
      }
    },
+    "node_modules/lodash": {
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
+      "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
+      "license": "MIT"
+    },
    "node_modules/lodash.identity": {
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/lodash.identity/-/lodash.identity-3.0.0.tgz",
@@ -3357,6 +3609,27 @@
        "node": ">= 0.6"
      }
    },
+    "node_modules/moment": {
+      "version": "2.30.1",
+      "resolved": "https://registry.npmjs.org/moment/-/moment-2.30.1.tgz",
+      "integrity": "sha512-uEmtNhbDOrWPFS+hdjFCBfy9f2YoyzRpwcl+DqpC6taX21FzsTLQVbMV/W7PzNSX6x/bhC1zA3c2UQ5NzH6how==",
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/moment-timezone": {
+      "version": "0.5.48",
+      "resolved": "https://registry.npmjs.org/moment-timezone/-/moment-timezone-0.5.48.tgz",
+      "integrity": "sha512-f22b8LV1gbTO2ms2j2z13MuPogNoh5UzxL3nzNAYKGraILnbGc9NEE6dyiiiLv46DGRb8A4kg8UKWLjPthxBHw==",
+      "license": "MIT",
+      "dependencies": {
+        "moment": "^2.29.4"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
    "node_modules/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -3976,6 +4249,15 @@
      "license": "MIT",
      "peer": true
    },
+    "node_modules/sax": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/sax/-/sax-1.6.0.tgz",
+      "integrity": "sha512-6R3J5M4AcbtLUdZmRv2SygeVaM7IhrLXu9BmnOGmmACak8fiUtOsYNWUS4uK7upbmHIBbLBeFeI//477BKLBzA==",
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": ">=11.0.0"
+      }
+    },
    "node_modules/secure-json-parse": {
      "version": "4.1.0",
      "resolved": "https://registry.npmjs.org/secure-json-parse/-/secure-json-parse-4.1.0.tgz",
@@ -4193,6 +4475,50 @@
      "dev": true,
      "license": "ISC"
    },
+    "node_modules/sm3": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/sm3/-/sm3-1.0.3.tgz",
+      "integrity": "sha512-KyFkIfr8QBlFG3uc3NaljaXdYcsbRy1KrSfc4tsQV8jW68jAktGeOcifu530Vx/5LC+PULHT0Rv8LiI8Gw+c1g==",
+      "license": "MIT"
+    },
+    "node_modules/smart-buffer": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz",
+      "integrity": "sha512-94hK0Hh8rPqQl2xXc3HsaBoOXKV20MToPkcXvwbISWLEs+64sBq5kFgn2kJDHb1Pry9yrP0dxrCI9RRci7RXKg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 6.0.0",
+        "npm": ">= 3.0.0"
+      }
+    },
+    "node_modules/socks": {
+      "version": "2.8.9",
+      "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.9.tgz",
+      "integrity": "sha512-LJhUYUvItdQ0LkJTmPeaEObWXAqFyfmP85x0tch/ez9cahmhlBBLbIqDFnvBnUJGagb0JbIQrkBs1wJ+yRYpEw==",
+      "license": "MIT",
+      "dependencies": {
+        "ip-address": "^10.1.1",
+        "smart-buffer": "^4.2.0"
+      },
+      "engines": {
+        "node": ">= 10.0.0",
+        "npm": ">= 3.0.0"
+      }
+    },
+    "node_modules/socks-proxy-agent": {
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/socks-proxy-agent/-/socks-proxy-agent-6.2.1.tgz",
+      "integrity": "sha512-a6KW9G+6B3nWZ1yB8G7pJwL3ggLy1uTzKAgCb7ttblwqdz9fMGJUuTy3uFzEP48FAs9FLILlmzDlE2JJhVQaXQ==",
+      "license": "MIT",
+      "dependencies": {
+        "agent-base": "^6.0.2",
+        "debug": "^4.3.3",
+        "socks": "^2.6.2"
+      },
+      "engines": {
+        "node": ">= 10"
+      }
+    },
    "node_modules/sonic-boom": {
      "version": "4.2.1",
      "resolved": "https://registry.npmjs.org/sonic-boom/-/sonic-boom-4.2.1.tgz",
@@ -4700,6 +5026,28 @@
        }
      }
    },
+    "node_modules/xml2js": {
+      "version": "0.6.2",
+      "resolved": "https://registry.npmjs.org/xml2js/-/xml2js-0.6.2.tgz",
+      "integrity": "sha512-T4rieHaC1EXcES0Kxxj4JWgaUQHDk+qwHcYOCFHfiwKz7tOVPLq7Hjq9dM1WCMhylqMEfP7hMcOIChvotiZegA==",
+      "license": "MIT",
+      "dependencies": {
+        "sax": ">=0.6.0",
+        "xmlbuilder": "~11.0.0"
+      },
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/xmlbuilder": {
+      "version": "11.0.1",
+      "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-11.0.1.tgz",
+      "integrity": "sha512-fDlsI/kFEx7gLvbecc0/ohLG50fugQp8ryHzMTuW9vSa1GJ0XYWKnhsUx7oie3G98+r56aTQIUB4kht42R3JvA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4.0"
+      }
+    },
    "node_modules/zod": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
@@ -1,12 +1,15 @@
 {
  "name": "@paradigm/hub",
-  "version": "0.0.29",
+  "version": "0.0.36",
  "private": true,
  "type": "module",
  "engines": {
    "node": ">=24"
  },
  "dependencies": {
+    "@alicloud/credentials": "^2.4.5",
+    "@alicloud/docmind-api20220711": "^1.4.15",
+    "@alicloud/tea-util": "^1.4.11",
    "@anthropic-ai/claude-agent-sdk": "^0.3.202",
    "@fastify/cookie": "^11.0.2",
    "@larksuiteoapi/node-sdk": "^1.70.0",
@@ -27,7 +30,7 @@
      "axios": "1.18.1"
    }
  },
-  "description": "Curriculum Project Hub — org-scoped Feishu collaboration and confined Agent runtime. Aligns to spec/System through ADR-0024.",
+  "description": "Curriculum Project Hub — org-scoped Feishu collaboration and confined Agent runtime. Semantics pinned by docs/adr/ (ADR-0001 through ADR-0027).",
  "scripts": {
    "dev": "npm run prisma:migrate && tsx watch src/server.ts",
    "build": "tsc -p tsconfig.json && npm run admin:build",
@@ -1,6 +1,6 @@
 -- ADR-0023 rejected the legacy `PlatformRoleAssignment` / `PlatformRole`{ADMIN,TEACHER}
 -- model: the platform administration control plane is a separate identity/session/
-- audit surface (see `Spec.System.PlatformAdministration`), intentionally not built
+-- audit surface, intentionally not built
 -- in alpha (ADR-0025, `hub/deploy/README.md`). The legacy table has no runtime
 -- reader — no guard, route, or service queries it for an authorization decision —
 -- and ADR-0023 requires it to be migrated/replaced before the platform panel ships.
@@ -0,0 +1,64 @@
+-- ADR-0026: append-only UsageFact ledger. AgentRun.costUsd/inputTokens/
+-- outputTokens become a derived rollup cache; the truth is in UsageFact.
+
+CREATE TABLE "UsageFact" (
+    "id"            TEXT                   NOT NULL,
+    "runId"         TEXT                   NOT NULL,
+    "occurredAt"    TIMESTAMP(3)           NOT NULL,
+    "kind"          TEXT                   NOT NULL,
+    "provider"      TEXT                   NOT NULL,
+    "model"         TEXT,
+    "inputTokens"   INTEGER,
+    "outputTokens"  INTEGER,
+    "quantity"      DECIMAL(18, 6),
+    "unit"          TEXT,
+    "costUsd"       DECIMAL(18, 8),
+    "costSource"    TEXT                   NOT NULL,
+    "capabilityId"  TEXT,
+    "correlationId" TEXT,
+    "metadata"      JSONB                  NOT NULL,
+    "createdAt"     TIMESTAMP(3)           NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT "UsageFact_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX "UsageFact_runId_occurredAt_idx" ON "UsageFact"("runId", "occurredAt");
+CREATE INDEX "UsageFact_runId_kind_idx"       ON "UsageFact"("runId", "kind");
+CREATE INDEX "UsageFact_provider_model_occurredAt_idx"
+  ON "UsageFact"("provider", "model", "occurredAt");
+CREATE INDEX "UsageFact_capabilityId_occurredAt_idx"
+  ON "UsageFact"("capabilityId", "occurredAt");
+
+ALTER TABLE "UsageFact"
+  ADD CONSTRAINT "UsageFact_runId_fkey"
+  FOREIGN KEY ("runId") REFERENCES "AgentRun"("id")
+  ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- Backfill: one synthetic model_completion fact per AgentRun that has any
+-- recorded usage (cost or tokens). correlationId = run id marks these as
+-- backfill artefacts (real facts use an external correlation id or null).
+-- Runs with no recorded usage stay fact-less and remain runsWithoutCost,
+-- matching ADR-0022's "missing cost ≠ zero" rule and the pre-existing
+-- migration 20260709143000_agent_run_cost_tracking's "no backfill for the
+-- truly unrecorded" stance.
+INSERT INTO "UsageFact" (
+  "id", "runId", "occurredAt", "kind", "provider", "model",
+  "inputTokens", "outputTokens", "costUsd", "costSource",
+  "correlationId", "metadata"
+)
+SELECT
+  'usagefact_backfill_' || "AgentRun"."id",
+  "AgentRun"."id",
+  COALESCE("AgentRun"."finishedAt", "AgentRun"."startedAt", CURRENT_TIMESTAMP),
+  'model_completion',
+  "AgentRun"."provider",
+  "AgentRun"."model",
+  "AgentRun"."inputTokens",
+  "AgentRun"."outputTokens",
+  "AgentRun"."costUsd",
+  COALESCE("AgentRun"."costSource", 'unknown'),
+  "AgentRun"."id",
+  '{}'::jsonb
+FROM "AgentRun"
+WHERE "AgentRun"."costUsd" IS NOT NULL
+   OR "AgentRun"."inputTokens" IS NOT NULL
+   OR "AgentRun"."outputTokens" IS NOT NULL;
@@ -0,0 +1,69 @@
+-- ADR-0027: org-scoped capability connections for external document/media
+-- transforms (PDF→MD, audio/video→text, …). Mirrors the Feishu Application
+-- Connection shape: reuses the ADR-0024 envelope machinery with its own
+-- payload schema and readiness probe, distinct from the model-provider
+-- connection.
+
+CREATE TABLE "OrganizationCapabilityConnection" (
+    "id"                    TEXT                   NOT NULL,
+    "organizationId"        TEXT                   NOT NULL,
+    "capabilityId"          TEXT                   NOT NULL,
+    "status"                "OrganizationConnectionStatus" NOT NULL DEFAULT 'DRAFT',
+    "activeSecretVersionId" TEXT,
+    "activatedAt"           TIMESTAMP(3),
+    "disabledAt"            TIMESTAMP(3),
+    "createdAt"             TIMESTAMP(3)           NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt"             TIMESTAMP(3)           NOT NULL,
+    CONSTRAINT "OrganizationCapabilityConnection_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "OrganizationCapabilityConnection_organizationId_capabilityId_key"
+  ON "OrganizationCapabilityConnection"("organizationId", "capabilityId");
+CREATE UNIQUE INDEX "OrganizationCapabilityConnection_activeSecretVersionId_key"
+  ON "OrganizationCapabilityConnection"("activeSecretVersionId");
+CREATE INDEX "OrganizationCapabilityConnection_organizationId_status_idx"
+  ON "OrganizationCapabilityConnection"("organizationId", "status");
+CREATE INDEX "OrganizationCapabilityConnection_capabilityId_status_idx"
+  ON "OrganizationCapabilityConnection"("capabilityId", "status");
+
+CREATE TABLE "CapabilityCredentialVersion" (
+    "id"              TEXT                   NOT NULL,
+    "connectionId"    TEXT                   NOT NULL,
+    "version"         INTEGER                NOT NULL,
+    "envelopeVersion" INTEGER                NOT NULL DEFAULT 1,
+    "keyId"           TEXT                   NOT NULL,
+    "envelope"        JSONB                  NOT NULL,
+    "createdByUserId" TEXT,
+    "createdAt"       TIMESTAMP(3)           NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "retiredAt"       TIMESTAMP(3),
+    CONSTRAINT "CapabilityCredentialVersion_pkey" PRIMARY KEY ("id")
+);
+
+CREATE UNIQUE INDEX "CapabilityCredentialVersion_connectionId_version_key"
+  ON "CapabilityCredentialVersion"("connectionId", "version");
+CREATE INDEX "CapabilityCredentialVersion_connectionId_retiredAt_idx"
+  ON "CapabilityCredentialVersion"("connectionId", "retiredAt");
+CREATE INDEX "CapabilityCredentialVersion_keyId_idx"
+  ON "CapabilityCredentialVersion"("keyId");
+CREATE INDEX "CapabilityCredentialVersion_createdByUserId_idx"
+  ON "CapabilityCredentialVersion"("createdByUserId");
+
+ALTER TABLE "OrganizationCapabilityConnection"
+  ADD CONSTRAINT "OrganizationCapabilityConnection_organizationId_fkey"
+  FOREIGN KEY ("organizationId") REFERENCES "Organization"("id")
+  ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "OrganizationCapabilityConnection"
+  ADD CONSTRAINT "OrganizationCapabilityConnection_activeSecretVersionId_fkey"
+  FOREIGN KEY ("activeSecretVersionId") REFERENCES "CapabilityCredentialVersion"("id")
+  ON DELETE RESTRICT ON UPDATE CASCADE;
+
+ALTER TABLE "CapabilityCredentialVersion"
+  ADD CONSTRAINT "CapabilityCredentialVersion_connectionId_fkey"
+  FOREIGN KEY ("connectionId") REFERENCES "OrganizationCapabilityConnection"("id")
+  ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "CapabilityCredentialVersion"
+  ADD CONSTRAINT "CapabilityCredentialVersion_createdByUserId_fkey"
+  FOREIGN KEY ("createdByUserId") REFERENCES "User"("id")
+  ON DELETE SET NULL ON UPDATE CASCADE;
@@ -1,6 +1,6 @@
 // Prisma schema for Curriculum Project Hub.
 //
-// Aligns to spec/System (ADR-0001..0004, 0017). Key divergences from the
+// Aligns to ADR-0001..0004, 0017. Key divergences from the
 // legacy teaching-material-host-service schema, each deliberate:
 //
 //  - AgentSession is provider/model-bound. Provider runtime cursors such as
@@ -11,8 +11,8 @@
 //  - ProjectGroupBinding is project→chat only (ADR-0001 1:1); legacy mixed
 //    user/chat targets into one binding table.
 //  - PermissionGrant + PermissionSettings land (ADR-0004), missing in legacy.
-//  - AgentRunStatus adds WAITING_FOR_USER + TIMED_OUT (spec RunState; enum
-//    completeness OPEN — add states without a schema migration war).
+//  - AgentRunStatus adds WAITING_FOR_USER + TIMED_OUT (the run-state set is
+//    open — add states without a schema migration war).

 generator client {
  provider = "prisma-client-js"
@@ -44,6 +44,7 @@ model Organization {
  externalDirectoryConnections ExternalDirectoryConnection[]
  providerConnections          OrganizationProviderConnection[]
  feishuApplicationConnection  OrganizationFeishuApplicationConnection?
+  capabilityConnections        OrganizationCapabilityConnection[]
  agentSkills                  OrganizationAgentSkill[]
  agentRoles                   OrganizationAgentRole[]
  projectGroupBindings         ProjectGroupBinding[]
@@ -60,7 +61,7 @@ enum OrganizationStatus {
 }

 /// Org-scoped membership role. Distinct from project PermissionRole and from
-/// the platform administrator surface (ADR-0023 / Spec.System.PlatformAdministration),
+/// the platform administrator surface (ADR-0023),
 /// which is a separate control plane not modeled in alpha (ADR-0025).
 model OrganizationMembership {
  id             String                 @id @default(cuid())
@@ -198,6 +199,7 @@ model User {
  auditEntries                 AuditEntry[]                         @relation("auditActor")
  providerCredentialVersions   ProviderCredentialVersion[]          @relation("providerCredentialVersionCreator")
  feishuCredentialVersions     FeishuApplicationCredentialVersion[] @relation("feishuCredentialVersionCreator")
+  capabilityCredentialVersions CapabilityCredentialVersion[]        @relation("capabilityCredentialVersionCreator")
  feishuIdentities             FeishuUserIdentity[]
 }

@@ -596,9 +598,13 @@ model AgentRun {
  summary           String?
  inputTokens       Int?
  outputTokens      Int?
-  /// Provider/gateway-reported cost in USD. Null means this run has no trusted cost fact.
+  /// ADR-0026: derived rollup cache of UsageFact rows for this run. The truth
+  /// is in UsageFact; this column is convenience for existing readers. Null
+  /// means this run has no trusted cost fact (ADR-0022: missing cost ≠ zero).
  costUsd           Decimal?        @db.Decimal(18, 8)
-  /// Semantic source of costUsd, e.g. provider_reported. Not a pricing-estimate fallback.
+  /// ADR-0026: semantic source of the rolled-up costUsd (provider_reported |
+  /// pricebook_derived | unknown). Mirrors the dominant CostSource of the
+  /// run's facts; not a pricing-estimate fallback.
  costSource        String?
  metadata          Json
  error             String?
@@ -612,6 +618,7 @@ model AgentRun {
  projectLock ProjectAgentLock?
  messages    AgentMessage[]    @relation("runMessages")
  fileChanges AgentFileChange[] @relation("runFileChanges")
+  usageFacts  UsageFact[]       @relation("runUsageFacts")

  @@index([projectId, status])
  @@index([projectId, finishedAt])
@@ -817,3 +824,102 @@ model AgentFileChange {
  @@index([projectId])
  @@index([path])
 }
+
+// --- Usage fact ledger (ADR-0026) ----------------------------------------
+
+/// ADR-0026: one billable consumption event inside an AgentRun. Append-only;
+/// the run's AgentRun.costUsd/inputTokens/outputTokens are a derived rollup
+/// of these rows, not the truth. kind=external_capability carries capabilityId
+/// for media transforms (PDF→MD, audio/video→text, …). costUsd=null means
+/// unknown, not zero (ADR-0022). The kind set is OPEN: new kinds must be
+/// surfaced, not silently folded in.
+model UsageFact {
+  id            String   @id @default(cuid())
+  runId         String
+  /// When the consumption happened. Pricebook derivation uses this, not
+  /// AgentRun.finishedAt, because an external capability may finish before
+  /// the run ends.
+  occurredAt    DateTime
+  /// model_completion | external_capability | tool_proxy. OPEN set.
+  kind          String
+  /// e.g. openrouter, mineru, openai_whisper.
+  provider      String
+  model         String?
+  inputTokens   Int?
+  outputTokens  Int?
+  /// Non-token meter (pages, audio_seconds, invocations). Coexists with tokens.
+  quantity      Decimal? @db.Decimal(18, 6)
+  unit          String?
+  /// USD. Null = unknown, NOT zero (ADR-0022). When null, costSource=unknown.
+  costUsd       Decimal? @db.Decimal(18, 8)
+  /// provider_reported | pricebook_derived | unknown. Required even when
+  /// costUsd is null, so a reader can distinguish "reported zero" from
+  /// "no report at all".
+  costSource    String
+  /// For kind=external_capability, the registered capability id
+  /// (e.g. pdf_to_md_bundle, audio_video_to_text). Null for model_completion.
+  capabilityId  String?
+  /// External request id for reconciliation / idempotency. Not an aggregation key.
+  correlationId String?
+  metadata      Json
+  createdAt     DateTime @default(now())
+
+  run AgentRun @relation("runUsageFacts", fields: [runId], references: [id], onDelete: Cascade)
+
+  @@index([runId, occurredAt])
+  @@index([runId, kind])
+  @@index([provider, model, occurredAt])
+  @@index([capabilityId, occurredAt])
+}
+
+// --- External capability connections (ADR-0027) -------------------------
+
+/// ADR-0027: org-scoped credential connection for an external capability
+/// (PDF→MD, audio/video→text, …). Structurally mirrors the Feishu Application
+/// Connection: reuses the ADR-0024 envelope (KEK→DEK→AES-256-GCM, AAD-bound)
+/// but has its own payload schema and readiness probe, distinct from the
+/// model-provider connection. Unique by (organizationId, capabilityId).
+model OrganizationCapabilityConnection {
+  id                    String                       @id @default(cuid())
+  organizationId        String
+  capabilityId          String
+  status                OrganizationConnectionStatus @default(DRAFT)
+  activeSecretVersionId String?                      @unique
+  activatedAt           DateTime?
+  disabledAt            DateTime?
+  createdAt             DateTime                     @default(now())
+  updatedAt             DateTime                     @updatedAt
+
+  organization        Organization                  @relation(fields: [organizationId], references: [id], onDelete: Cascade)
+  secretVersions      CapabilityCredentialVersion[] @relation("capabilityCredentialVersions")
+  activeSecretVersion CapabilityCredentialVersion?  @relation("activeCapabilityCredentialVersion", fields: [activeSecretVersionId], references: [id], onDelete: Restrict)
+
+  @@unique([organizationId, capabilityId])
+  @@index([organizationId, status])
+  @@index([capabilityId, status])
+}
+
+/// ADR-0024/0027: one immutable authenticated envelope per capability secret
+/// version. Same encryption machinery as Provider/Feishu credential versions;
+/// the payload inside is CapabilitySecretPayloadV1 (baseUrl, apiToken,
+/// optional projectId).
+model CapabilityCredentialVersion {
+  id              String    @id @default(cuid())
+  connectionId    String
+  version         Int
+  envelopeVersion Int       @default(1)
+  keyId           String
+  envelope        Json
+  createdByUserId String?
+  createdAt       DateTime  @default(now())
+  retiredAt       DateTime?
+
+  connection OrganizationCapabilityConnection  @relation("capabilityCredentialVersions", fields: [connectionId], references: [id], onDelete: Cascade)
+  activeFor  OrganizationCapabilityConnection? @relation("activeCapabilityCredentialVersion")
+  createdBy  User?                             @relation("capabilityCredentialVersionCreator", fields: [createdByUserId], references: [id], onDelete: SetNull)
+
+  @@unique([connectionId, version])
+  @@index([connectionId, retiredAt])
+  @@index([keyId])
+  @@index([createdByUserId])
+}
@@ -0,0 +1,89 @@
+/**
+ * Smoke test: real Aliyun docmind API call using createReadStream.
+ * Run: node --experimental-strip-types scripts/smoke-docmind.ts <pdf-path>
+ */
+import DocmindClient from "@alicloud/docmind-api20220711";
+import { RuntimeOptions } from "@alicloud/tea-util";
+import { createReadStream } from "node:fs";
+import { basename } from "node:path";
+
+const accessKeyId = process.env["ALIBABA_CLOUD_ACCESS_KEY_ID"];
+const accessKeySecret = process.env["ALIBABA_CLOUD_ACCESS_KEY_SECRET"];
+if (accessKeyId === undefined || accessKeySecret === undefined) {
+  console.error("Set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET env vars.");
+  process.exit(1);
+}
+
+const pdfPath = process.argv[2] ?? "../examples/trial/prime_sieve.pdf";
+console.log(`Parsing: ${pdfPath}`);
+
+const client = new DocmindClient.default({
+  endpoint: "docmind-api.cn-hangzhou.aliyuncs.com",
+  accessKeyId,
+  accessKeySecret,
+  type: "access_key",
+  regionId: "cn-hangzhou",
+} as never);
+
+const fileStream = createReadStream(pdfPath);
+const runtime = new RuntimeOptions({});
+
+console.log("Submitting job...");
+const submitResp = await client.submitDocParserJobAdvance(
+  new DocmindClient.SubmitDocParserJobAdvanceRequest({
+    fileUrlObject: fileStream,
+    fileName: basename(pdfPath),
+    outputFormat: ["markdown"],
+    formulaEnhancement: true,
+  }),
+  runtime,
+);
+const jobId = submitResp.body?.data?.id;
+console.log("Job ID:", jobId);
+
+if (jobId === undefined) {
+  console.error("No job id:", JSON.stringify(submitResp.body));
+  process.exit(1);
+}
+
+console.log("Polling...");
+const deadline = Date.now() + 5 * 60_000;
+let status = "";
+let markdownUrl = "";
+let pageCount = 0;
+while (Date.now() < deadline) {
+  await new Promise((r) => setTimeout(r, 10_000));
+  const resp = await client.queryDocParserStatus(
+    new DocmindClient.QueryDocParserStatusRequest({ id: jobId }),
+  );
+  const data = (resp.body as { data?: { status?: string; pageCountEstimate?: number; outputFormatResult?: Array<{ outputFileUrl?: string; outputType?: string }> } }).data;
+  status = data?.status ?? "";
+  console.log(`  status: ${status}`);
+  if (status === "success") {
+    const md = data?.outputFormatResult?.find((r) => r.outputType === "markdown");
+    markdownUrl = md?.outputFileUrl ?? "";
+    pageCount = data?.pageCountEstimate ?? 0;
+    break;
+  }
+  if (status === "fail") {
+    console.error("Job failed!");
+    process.exit(1);
+  }
+}
+
+if (status !== "success" || markdownUrl === "") {
+  console.error("Failed or timed out:", status);
+  process.exit(1);
+}
+
+console.log("Downloading markdown from OSS...");
+const mdResp = await fetch(markdownUrl);
+const markdown = await mdResp.text();
+
+console.log("--- Result ---");
+console.log("Pages:", pageCount);
+console.log("Cost (USD, est):", ((pageCount > 0 ? pageCount : 1) * 0.0056).toFixed(4));
+console.log("Job ID:", jobId);
+console.log("Markdown length:", markdown.length, "chars");
+console.log("--- Markdown (first 1000 chars) ---");
+console.log(markdown.slice(0, 1000));
@@ -0,0 +1,63 @@
+---
+name: pdf-to-md
+description: >
+  Convert PDF documents to Markdown bundles using the convert_pdf_to_md tool.
+  Handles PDFs from Feishu messages, local workspace files, and produces
+  high-quality Markdown with LaTeX formulas and extracted images.
+---
+
+# PDF to Markdown Conversion
+
+## When to use
+
+Use this skill when the user asks to convert a PDF to Markdown, extract text
+from a PDF, or turn a PDF document into an editable format.
+
+## How it works
+
+The `convert_pdf_to_md` tool (provided by the `cph_hub` MCP server) calls
+Alibaba Cloud Document Mind to parse the PDF. It:
+
+- Extracts text in reading order (handles multi-column, scanned, and
+  multi-language documents)
+- Converts mathematical formulas to **LaTeX** (`$...$` inline, `$$...$$` block)
+- Extracts tables as Markdown tables
+- Downloads embedded images into the output directory
+- Writes a single `document.md` file plus image files
+
+## Workflow
+
+### PDF from a Feishu message
+
+1. Use `feishu_read_context` to find the `file_key` of the PDF attachment.
+2. Use `feishu_download_resource` to download it into the workspace.
+3. Use `convert_pdf_to_md` with the downloaded file path and an output directory.
+
+### PDF already in the workspace
+
+1. Use `convert_pdf_to_md` directly with the file path and an output directory.
+
+## Important rules
+
+- **Always** use `convert_pdf_to_md` for PDF→Markdown. Do NOT attempt to parse
+  PDFs yourself with Read, Bash, Python, or any other method. The tool provides
+  accurate formula, table, and image extraction that manual methods cannot
+  match.
+- If `convert_pdf_to_md` fails because no capability connection is configured,
+  tell the user to ask their organization admin to configure the Aliyun
+  docmind credential in the admin web UI (组织后台 → 能力).
+- The output directory will be created if it does not exist.
+- After conversion, use `send_file` to send the generated markdown back to the
+  user if they requested it.
+
+## Output
+
+The tool returns a list of generated files:
+- `document.md` — the main markdown file
+- `*.jpg` / `*.png` — extracted images, referenced from the markdown
+
+## Cost
+
+The conversion is billed per page (0.04 CNY/page ≈ $0.0056/page for the
+enhanced formula mode). The cost is automatically recorded on the run's
+usage ledger.
@@ -1,10 +1,12 @@
 /**
 * Org-admin Agent configuration routes (ADR-0017 / ADR-0018).
 *
- * Surface for browsing and editing Organization-scoped Agent roles and skills.
- * Roles are org-owned data; the default-model picker is constrained to the
- * env-default model registry (ADR-0017: there is no org-scoped model list —
- * `OrganizationAgentRole.defaultModel` selects from the platform-enabled set).
+ * Surface for browsing and editing Organization-scoped Agent roles, the skills
+ * bound to them, and the model picker. The model list is **derived** from the
+ * org's ACTIVE provider connection via OpenRouter's /v1/models API — there is
+ * no separate model table to maintain. When no ACTIVE provider exists, the
+ * route falls back to the env-default model registry so the admin surface
+ * remains usable.
 *
 * Skill management (create, read, edit, disable) is performed in-band through
 * the deep module `OrganizationAgentConfiguration`, which writes to the same
@@ -17,7 +19,9 @@
 import type { PrismaClient } from "@prisma/client";
 import type { FastifyInstance } from "fastify";
 import { OrganizationAgentConfiguration } from "../../agent/configuration.js";
+import { ProviderModelCatalog } from "../../connections/providerModelCatalog.js";
 import { createDefaultModelRegistry } from "../../settings/runtime.js";
+import type { LocalSecretEnvelope } from "../../security/secretEnvelope.js";
 import { requireOrgRole, type GuardDeps } from "../auth/guards.js";
 import { handleRouteError } from "../errors.js";

@@ -25,6 +29,7 @@ export interface AgentConfigRouteConfig {
  readonly prisma: PrismaClient;
  readonly sessionSecret: string;
  readonly skillStoreRoot: string;
+  readonly secretEnvelope: LocalSecretEnvelope;
 }

 export async function registerAgentConfigRoutes(
@@ -33,6 +38,7 @@ export async function registerAgentConfigRoutes(
 ): Promise<void> {
  const guardDeps: GuardDeps = { prisma: config.prisma, sessionSecret: config.sessionSecret };
  const agentConfig = new OrganizationAgentConfiguration(config.prisma, config.skillStoreRoot);
+  const modelCatalog = new ProviderModelCatalog(config.prisma, config.secretEnvelope);

  app.get("/api/org/:orgSlug/agent-roles", async (request, reply) => {
    try {
@@ -226,8 +232,13 @@ export async function registerAgentConfigRoutes(
      const { orgSlug } = request.params as { orgSlug: string };
      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
      if (auth === null) return;
-      const registry = createDefaultModelRegistry(process.env);
-      return { models: registry.listModels() };
+      const providerModels = await modelCatalog.listModels(auth.organization.id);
+      // Fall back to env-default registry when the org has no ACTIVE provider
+      // (or the provider API is unreachable on first load).
+      const models = providerModels.length > 0
+        ? providerModels
+        : createDefaultModelRegistry(process.env).listModels();
+      return { models };
    } catch (err) {
      return handleRouteError(reply, err);
    }
@@ -432,16 +432,16 @@ async function resolvePostLoginRedirect(
      select: { organization: { select: { slug: true, name: true } } },
    });
    if (intended === null) return "/admin?error=not_an_active_org_member";
-    const orgRoot = `/admin/org/${intended.organization.slug}`;
+    const orgRoot = "/admin";
    // Default / missing returnTo sanitizes to "/admin". Always land in the org
    // admin SPA (not the legacy static "close this tab" complete page).
    if (returnTo === "/admin") {
      return orgRoot;
    }
-    return returnTo === orgRoot || returnTo.startsWith(`${orgRoot}/`) ? returnTo : orgRoot;
+    return normalizeAdminReturnTo(returnTo) ?? orgRoot;
  }
  if (returnTo !== "/admin" && returnTo.startsWith("/admin")) {
-    return returnTo;
+    return normalizeAdminReturnTo(returnTo) ?? "/admin";
  }
  const membership = await prisma.organizationMembership.findFirst({
    where: {
@@ -454,7 +454,7 @@ async function resolvePostLoginRedirect(
    orderBy: { createdAt: "asc" },
  });
  if (membership !== null) {
-    return `/admin/org/${membership.organization.slug}`;
+    return "/admin";
  }
  // Member-only or no org: still land on a shell page (SPA will explain).
  const any = await prisma.organizationMembership.findFirst({
@@ -463,7 +463,7 @@ async function resolvePostLoginRedirect(
    orderBy: { createdAt: "asc" },
  });
  if (any !== null) {
-    return `/admin/org/${any.organization.slug}`;
+    return "/admin/projects";
  }
  return "/admin/login?error=no_organization";
 }
@@ -489,7 +489,18 @@ export function sanitizeReturnTo(raw: string): string {
  if (!raw.startsWith("/admin")) {
    return "/admin";
  }
-  return raw;
+  return normalizeAdminReturnTo(raw) ?? "/admin";
+}
+
+/** Map legacy `/admin/org/:slug[...]` bookmarks onto slugless `/admin[...]` paths. */
+export function normalizeAdminReturnTo(path: string): string | null {
+  if (!path.startsWith("/admin")) return null;
+  const legacy = path.match(/^\/admin\/org\/[^/]+(\/.*)?$/);
+  if (legacy) {
+    const rest = legacy[1] ?? "";
+    return rest === "" ? "/admin" : `/admin${rest}`;
+  }
+  return path;
 }

 function trimTrailingSlash(url: string): string {
@@ -0,0 +1,131 @@
+/**
+ * ADR-0027: Admin routes for organization-scoped capability connections.
+ * GET    /api/org/:orgSlug/capability-connections           — list all
+ * GET    /api/org/:orgSlug/capability-connections/:capId    — read one
+ * PUT    /api/org/:orgSlug/capability-connections/:capId    — rotate/create
+ * DELETE /api/org/:orgSlug/capability-connections/:capId    — disable
+ */
+import type { PrismaClient } from "@prisma/client";
+import type { FastifyInstance } from "fastify";
+import { CapabilityConnectionService } from "../../capability/capabilityConnectionService.js";
+import { CapabilityReadinessError, type CapabilityReadinessProbe } from "../../capability/capabilityReadiness.js";
+import type { LocalSecretEnvelope } from "../../security/secretEnvelope.js";
+import { requireOrgRole, type GuardDeps } from "../auth/guards.js";
+import { handleRouteError } from "../errors.js";
+
+export interface CapabilityConnectionRouteConfig {
+  readonly prisma: PrismaClient;
+  readonly sessionSecret: string;
+  readonly secretEnvelope: LocalSecretEnvelope;
+  readonly readinessProbe?: CapabilityReadinessProbe;
+}
+
+export async function registerCapabilityConnectionRoutes(
+  app: FastifyInstance,
+  config: CapabilityConnectionRouteConfig,
+): Promise<void> {
+  const guardDeps: GuardDeps = { prisma: config.prisma, sessionSecret: config.sessionSecret };
+  const connections = new CapabilityConnectionService(
+    config.prisma,
+    config.secretEnvelope,
+    config.readinessProbe,
+  );
+
+  app.get("/api/org/:orgSlug/capability-connections", async (request, reply) => {
+    try {
+      const { orgSlug } = request.params as { orgSlug: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      return { connections: await connections.list(auth.organization.id) };
+    } catch (error) {
+      request.log.error({ requestId: request.id, operation: "capability_connection.list" }, "list failed");
+      return handleRouteError(reply, error);
+    }
+  });
+
+  app.get("/api/org/:orgSlug/capability-connections/:capabilityId", async (request, reply) => {
+    try {
+      const { orgSlug, capabilityId } = request.params as { orgSlug: string; capabilityId: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      return { connection: await connections.read(auth.organization.id, capabilityId) };
+    } catch (error) {
+      request.log.error({ requestId: request.id, operation: "capability_connection.read" }, "read failed");
+      return handleRouteError(reply, error);
+    }
+  });
+
+  app.put("/api/org/:orgSlug/capability-connections/:capabilityId", async (request, reply) => {
+    try {
+      const { orgSlug, capabilityId } = request.params as { orgSlug: string; capabilityId: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const body = parseBody(request.body);
+      const result = await connections.rotate({
+        organizationId: auth.organization.id,
+        capabilityId,
+        actorUserId: auth.user.id,
+        ...body,
+      });
+      request.log.info({
+        organizationId: auth.organization.id,
+        capabilityId,
+        connectionId: result.id,
+        status: result.status,
+        secretVersion: result.activeVersion,
+      }, result.created ? "Capability Connection created" : "Capability Connection rotated");
+      const { created, ...metadata } = result;
+      return reply.status(created ? 201 : 200).send(metadata);
+    } catch (error) {
+      const facts = error instanceof CapabilityReadinessError
+        ? {
+            errorCode: error.code,
+            failureCategory: error.category,
+            ...(error.upstreamStatus !== undefined ? { upstreamStatus: error.upstreamStatus } : {}),
+          }
+        : { errorCode: "capability_connection_write_failed" };
+      request.log.error({ requestId: request.id, operation: "capability_connection.rotate", ...facts }, "rotate failed");
+      return handleRouteError(reply, error);
+    }
+  });
+
+  app.delete("/api/org/:orgSlug/capability-connections/:capabilityId", async (request, reply) => {
+    try {
+      const { orgSlug, capabilityId } = request.params as { orgSlug: string; capabilityId: string };
+      const auth = await requireOrgRole(request, reply, guardDeps, { orgSlug });
+      if (auth === null) return;
+      const result = await connections.disable({
+        organizationId: auth.organization.id,
+        capabilityId,
+        actorUserId: auth.user.id,
+      });
+      request.log.info({
+        organizationId: auth.organization.id,
+        capabilityId,
+        connectionId: result.id,
+        status: result.status,
+      }, "Capability Connection disabled");
+      return reply.send(result);
+    } catch (error) {
+      request.log.error({ requestId: request.id, operation: "capability_connection.disable" }, "disable failed");
+      return handleRouteError(reply, error);
+    }
+  });
+}
+
+function parseBody(value: unknown): { readonly accessKeyId: string; readonly accessKeySecret: string; readonly endpoint: string } {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("invalid capability credential body");
+  }
+  const body = value as Record<string, unknown>;
+  for (const name of ["accessKeyId", "accessKeySecret", "endpoint"] as const) {
+    if (typeof body[name] !== "string" || (body[name] as string).trim() === "") {
+      throw new Error(`${name} is required`);
+    }
+  }
+  return {
+    accessKeyId: body["accessKeyId"] as string,
+    accessKeySecret: body["accessKeySecret"] as string,
+    endpoint: body["endpoint"] as string,
+  };
+}
@@ -22,6 +22,8 @@ import type { LocalSecretEnvelope } from "../../security/secretEnvelope.js";
 import type { ProviderReadinessProbe } from "../../connections/providerReadiness.js";
 import type { FeishuReadinessProbe } from "../../connections/feishuReadiness.js";
 import { registerFeishuApplicationConnectionRoutes } from "./feishuApplicationConnectionRoutes.js";
+import { registerCapabilityConnectionRoutes } from "./capabilityConnectionRoutes.js";
+import type { CapabilityReadinessProbe } from "../../capability/capabilityReadiness.js";

 export interface OrgRouteConfig {
  readonly prisma: PrismaClient;
@@ -30,6 +32,7 @@ export interface OrgRouteConfig {
  readonly secretEnvelope: LocalSecretEnvelope;
  readonly providerReadinessProbe?: ProviderReadinessProbe;
  readonly feishuConnectionReadinessProbe?: FeishuReadinessProbe;
+  readonly capabilityReadinessProbe?: CapabilityReadinessProbe;
 }

 export async function registerOrgRoutes(app: FastifyInstance, config: OrgRouteConfig): Promise<void> {
@@ -116,6 +119,7 @@ export async function registerOrgRoutes(app: FastifyInstance, config: OrgRouteCo
    prisma: config.prisma,
    sessionSecret: config.sessionSecret,
    skillStoreRoot: readSkillStoreRoot(),
+    secretEnvelope: config.secretEnvelope,
  });
  await registerSessionsAndUsageRoutes(app, {
    prisma: config.prisma,
@@ -137,4 +141,12 @@ export async function registerOrgRoutes(app: FastifyInstance, config: OrgRouteCo
      ? { readinessProbe: config.feishuConnectionReadinessProbe }
      : {}),
  });
+  await registerCapabilityConnectionRoutes(app, {
+    prisma: config.prisma,
+    sessionSecret: config.sessionSecret,
+    secretEnvelope: config.secretEnvelope,
+    ...(config.capabilityReadinessProbe !== undefined
+      ? { readinessProbe: config.capabilityReadinessProbe }
+      : {}),
+  });
 }
@@ -1,4 +1,12 @@
-export const DEFAULT_CLAUDE_BUILT_IN_TOOLS = ["Read", "Write", "Bash", "Glob", "Grep"] as const;
+export const DEFAULT_CLAUDE_BUILT_IN_TOOLS = [
+  "Read",
+  "Write",
+  "Bash",
+  "Glob",
+  "Grep",
+  "WebFetch",
+  "WebSearch",
+] as const;

 export const CPH_HUB_MCP_SERVER_NAME = "cph_hub";
 export const CPH_HUB_MCP_TOOL_IDS = [
@@ -6,6 +14,7 @@ export const CPH_HUB_MCP_TOOL_IDS = [
  "feishu_read_context",
  "feishu_download_resource",
  "request_approval",
+  "convert_pdf_to_md",
 ] as const;

 export type CphHubMcpToolId = (typeof CPH_HUB_MCP_TOOL_IDS)[number];
@@ -26,11 +35,15 @@ const ROLE_TOOL_TO_CLAUDE_BUILT_INS = new Map<string, readonly string[]>([
  // would need a separate command-policy layer.
  ["cph_check", ["Bash"]],
  ["cph_build", ["Bash"]],
+  ["web_fetch", ["WebFetch"]],
+  ["web_search", ["WebSearch"]],
  ["Read", ["Read"]],
  ["Write", ["Write"]],
  ["Bash", ["Bash"]],
  ["Glob", ["Glob"]],
  ["Grep", ["Grep"]],
+  ["WebFetch", ["WebFetch"]],
+  ["WebSearch", ["WebSearch"]],
 ]);

 const ROLE_TOOL_TO_CPH_HUB_MCP_TOOL = new Map<string, CphHubMcpToolId>([
@@ -38,10 +51,12 @@ const ROLE_TOOL_TO_CPH_HUB_MCP_TOOL = new Map<string, CphHubMcpToolId>([
  ["feishu_read_context", "feishu_read_context"],
  ["feishu_download_resource", "feishu_download_resource"],
  ["request_approval", "request_approval"],
+  ["convert_pdf_to_md", "convert_pdf_to_md"],
  ["mcp__cph_hub__send_file", "send_file"],
  ["mcp__cph_hub__feishu_read_context", "feishu_read_context"],
  ["mcp__cph_hub__feishu_download_resource", "feishu_download_resource"],
  ["mcp__cph_hub__request_approval", "request_approval"],
+  ["mcp__cph_hub__convert_pdf_to_md", "convert_pdf_to_md"],
 ]);

 const SUPPORTED_ROLE_TOOLS = new Set([
@@ -24,10 +24,10 @@
 * denied by default and re-opened only for the workspace plus named system
 * runtimes, and `failIfUnavailable` hard-fails if the sandbox can't start. The
 * subprocess gets a minimal environment and SDK credential protection removes
- * provider secrets from Bash. This upholds `AgentFileOp.Authorized`
- * (ADR-0018 / `Spec.System.AgentSurface`) without re-implementing the
+ * provider secrets from Bash. This upholds the workspace-bounded file-op
+ * invariant (ADR-0018) without re-implementing the
 * `workspace.ts` `confine()` path validator as a tool wrapper — the OS sandbox
- * is the mechanism, the contract pins the invariant.
+ * is the mechanism, the ADR pins the invariant.
 */
 import { query, type HookCallback, type McpServerConfig, type SDKMessage, type SDKAssistantMessage, type SDKUserMessage, type SDKResultMessage, type SDKPartialAssistantMessage, type SDKSystemMessage } from "@anthropic-ai/claude-agent-sdk";
 import type { PrismaClient } from "@prisma/client";
@@ -0,0 +1,266 @@
+/**
+ * ADR-0027: Organization-scoped capability connection service. Manages the
+ * lifecycle (rotate / read / disable) of capability credentials stored in
+ * ADR-0024 encrypted envelopes with purpose="capability".
+ *
+ * Mirrors FeishuApplicationConnectionService, but keyed by (organizationId,
+ * capabilityId) instead of 1:1 — an org may have multiple capabilities.
+ */
+import { randomUUID } from "node:crypto";
+import type { Prisma, PrismaClient } from "@prisma/client";
+import { lockActiveOrganization } from "../org/status.js";
+import { LocalSecretEnvelope } from "../security/secretEnvelope.js";
+import { probeDocmindCredential, type CapabilityReadinessProbe } from "./capabilityReadiness.js";
+import type { CapabilitySecretPayload } from "./types.js";
+
+const CAPABILITY_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const KNOWN_CAPABILITY_IDS = new Set(["pdf_to_md_bundle", "audio_video_to_text"]);
+
+export interface CapabilityCredentialInput {
+  readonly accessKeyId: string;
+  readonly accessKeySecret: string;
+  readonly endpoint: string;
+}
+
+export interface RotateCapabilityInput extends CapabilityCredentialInput {
+  readonly organizationId: string;
+  readonly capabilityId: string;
+  readonly actorUserId: string;
+}
+
+export interface CapabilityConnectionMetadata {
+  readonly id: string;
+  readonly capabilityId: string;
+  readonly status: "DRAFT" | "ACTIVE" | "DISABLED";
+  readonly activeVersion: number | null;
+  readonly keyId: string | null;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+
+export interface CapabilityConnectionWriteResult extends CapabilityConnectionMetadata {
+  readonly created: boolean;
+}
+
+export type CapabilitySecretPayloadV1 = CapabilitySecretPayload;
+
+export class CapabilityConnectionService {
+  constructor(
+    private readonly prisma: PrismaClient,
+    private readonly secrets: LocalSecretEnvelope,
+    private readonly readinessProbe: CapabilityReadinessProbe = probeDocmindCredential,
+  ) {}
+
+  async rotate(input: RotateCapabilityInput): Promise<CapabilityConnectionWriteResult> {
+    if (!CAPABILITY_ID_PATTERN.test(input.capabilityId)) {
+      throw new Error(`invalid capabilityId: ${input.capabilityId}`);
+    }
+    const payload = validateCredential(input);
+    await this.prisma.$transaction(async (tx) => {
+      await requireCapabilityAdmin(tx, input);
+    });
+    await this.readinessProbe({
+      endpoint: payload.endpoint,
+      accessKeyId: payload.accessKeyId,
+      accessKeySecret: payload.accessKeySecret,
+    });
+
+    return this.prisma.$transaction(async (tx) => {
+      await requireCapabilityAdmin(tx, input);
+      const connection = await tx.organizationCapabilityConnection.upsert({
+        where: {
+          organizationId_capabilityId: {
+            organizationId: input.organizationId,
+            capabilityId: input.capabilityId,
+          },
+        },
+        update: {},
+        create: {
+          id: randomUUID(),
+          organizationId: input.organizationId,
+          capabilityId: input.capabilityId,
+          status: "DRAFT",
+        },
+      });
+      await tx.$queryRaw`SELECT "id" FROM "OrganizationCapabilityConnection" WHERE "id" = ${connection.id} FOR UPDATE`;
+      const locked = await tx.organizationCapabilityConnection.findUniqueOrThrow({
+        where: { id: connection.id },
+        include: {
+          activeSecretVersion: true,
+          secretVersions: { orderBy: { version: "desc" }, take: 1, select: { version: true } },
+        },
+      });
+      if (locked.organizationId !== input.organizationId) {
+        throw new Error("Capability Connection scope changed during rotation");
+      }
+      const version = (locked.secretVersions[0]?.version ?? 0) + 1;
+      const secretVersionId = randomUUID();
+      const envelope = this.secrets.encryptJson(
+        {
+          purpose: "capability",
+          organizationId: input.organizationId,
+          connectionId: locked.id,
+          secretVersionId,
+        },
+        payload,
+      );
+      const now = new Date();
+      const secretVersion = await tx.capabilityCredentialVersion.create({
+        data: {
+          id: secretVersionId,
+          connectionId: locked.id,
+          version,
+          envelopeVersion: envelope.version,
+          keyId: envelope.keyId,
+          envelope: envelope as unknown as Prisma.InputJsonValue,
+          createdByUserId: input.actorUserId,
+        },
+      });
+      if (locked.activeSecretVersion !== null) {
+        await tx.capabilityCredentialVersion.update({
+          where: { id: locked.activeSecretVersion.id },
+          data: { retiredAt: now },
+        });
+      }
+      const activated = await tx.organizationCapabilityConnection.update({
+        where: { id: locked.id },
+        data: {
+          status: "ACTIVE",
+          activeSecretVersionId: secretVersion.id,
+          activatedAt: now,
+          disabledAt: null,
+        },
+      });
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          actorUserId: input.actorUserId,
+          action: version === 1 ? "capability.created" : "capability.rotated",
+          metadata: {
+            connectionId: locked.id,
+            capabilityId: input.capabilityId,
+            status: "ACTIVE",
+            secretVersion: version,
+            keyId: envelope.keyId,
+          },
+        },
+      });
+      return {
+        ...toMetadata(activated, { version, keyId: secretVersion.keyId }),
+        created: version === 1,
+      };
+    });
+  }
+
+  async list(organizationId: string): Promise<CapabilityConnectionMetadata[]> {
+    const connections = await this.prisma.organizationCapabilityConnection.findMany({
+      where: { organizationId },
+      include: { activeSecretVersion: { select: { version: true, keyId: true } } },
+      orderBy: { capabilityId: "asc" },
+    });
+    return connections.map((c) => toMetadata(c, c.activeSecretVersion));
+  }
+
+  async read(organizationId: string, capabilityId: string): Promise<CapabilityConnectionMetadata | null> {
+    const connection = await this.prisma.organizationCapabilityConnection.findFirst({
+      where: { organizationId, capabilityId },
+      include: { activeSecretVersion: { select: { version: true, keyId: true } } },
+    });
+    return connection === null ? null : toMetadata(connection, connection.activeSecretVersion);
+  }
+
+  async disable(input: {
+    readonly organizationId: string;
+    readonly capabilityId: string;
+    readonly actorUserId: string;
+  }): Promise<CapabilityConnectionMetadata> {
+    return this.prisma.$transaction(async (tx) => {
+      await requireCapabilityAdmin(tx, input);
+      const connection = await tx.organizationCapabilityConnection.findFirst({
+        where: { organizationId: input.organizationId, capabilityId: input.capabilityId },
+        select: { id: true },
+      });
+      if (connection === null) throw new Error("Capability Connection not found");
+      await tx.$queryRaw`SELECT "id" FROM "OrganizationCapabilityConnection" WHERE "id" = ${connection.id} FOR UPDATE`;
+      const locked = await tx.organizationCapabilityConnection.findUniqueOrThrow({
+        where: { id: connection.id },
+        include: { activeSecretVersion: { select: { version: true, keyId: true } } },
+      });
+      if (locked.status === "DISABLED") return toMetadata(locked, locked.activeSecretVersion);
+      const disabled = await tx.organizationCapabilityConnection.update({
+        where: { id: locked.id },
+        data: { status: "DISABLED", disabledAt: new Date() },
+      });
+      await tx.auditEntry.create({
+        data: {
+          organizationId: input.organizationId,
+          actorUserId: input.actorUserId,
+          action: "capability.disabled",
+          metadata: {
+            connectionId: locked.id,
+            capabilityId: input.capabilityId,
+            previousStatus: locked.status,
+            status: "DISABLED",
+          },
+        },
+      });
+      return toMetadata(disabled, locked.activeSecretVersion);
+    });
+  }
+}
+
+function validateCredential(input: RotateCapabilityInput): CapabilitySecretPayloadV1 {
+  if (!KNOWN_CAPABILITY_IDS.has(input.capabilityId)) {
+    throw new Error(`unsupported capabilityId: ${input.capabilityId}`);
+  }
+  const accessKeyId = nonEmpty(input.accessKeyId, "accessKeyId");
+  const accessKeySecret = nonEmpty(input.accessKeySecret, "accessKeySecret");
+  const endpoint = nonEmpty(input.endpoint, "endpoint");
+  return { schemaVersion: 1, accessKeyId, accessKeySecret, endpoint };
+}
+
+function toMetadata(
+  connection: {
+    readonly id: string;
+    readonly capabilityId: string;
+    readonly status: string;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+  },
+  secret: { readonly version: number; readonly keyId: string } | null,
+): CapabilityConnectionMetadata {
+  return {
+    id: connection.id,
+    capabilityId: connection.capabilityId,
+    status: connection.status as CapabilityConnectionMetadata["status"],
+    activeVersion: secret?.version ?? null,
+    keyId: secret?.keyId ?? null,
+    createdAt: connection.createdAt,
+    updatedAt: connection.updatedAt,
+  };
+}
+
+async function requireCapabilityAdmin(
+  tx: Prisma.TransactionClient,
+  input: { readonly organizationId: string; readonly actorUserId: string },
+): Promise<void> {
+  await lockActiveOrganization(tx, input.organizationId);
+  const membership = await tx.organizationMembership.findFirst({
+    where: {
+      organizationId: input.organizationId,
+      userId: input.actorUserId,
+      role: { in: ["OWNER", "ADMIN"] },
+      revokedAt: null,
+    },
+    select: { id: true },
+  });
+  if (membership === null) {
+    throw new Error("only Organization OWNER or ADMIN may manage capability connections");
+  }
+}
+
+function nonEmpty(value: string, label: string): string {
+  const trimmed = value.trim();
+  if (trimmed === "") throw new Error(`${label} must not be empty`);
+  return trimmed;
+}
@@ -0,0 +1,70 @@
+/**
+ * ADR-0027: org-scoped capability credential resolver. Reuses the ADR-0024
+ * envelope decryption machinery (LocalSecretEnvelope) with
+ * purpose="capability", distinct from the model-provider and Feishu
+ * application connections. Fail-closed: no process-global fallback.
+ *
+ * Mirrors the Feishu application connection resolver shape, minus the
+ * readiness probe (capability probes are per-capability and injected by the
+ * adapter wiring, not this resolver).
+ */
+import type { PrismaClient } from "@prisma/client";
+import { LocalSecretEnvelope, type SecretEnvelopeV1 } from "../security/secretEnvelope.js";
+import {
+  CapabilityConnectionUnavailable,
+  type CapabilitySecretPayload,
+  type CapabilityId,
+} from "./types.js";
+
+const CAPABILITY_PURPOSE = "capability";
+
+export interface ResolvedCapabilityCredential extends CapabilitySecretPayload {
+  readonly connectionId: string;
+  readonly organizationId: string;
+  readonly capabilityId: string;
+}
+
+/**
+ * Resolve the active capability credential for an organization. Throws
+ * CapabilityConnectionUnavailable when the org has no ACTIVE connection
+ * (fail-closed, ADR-0024). Decrypted plaintext exists only in the returned
+ * object for the duration of the capability call; it is never cached, logged,
+ * or passed to the Agent process.
+ */
+export async function resolveCapabilityCredential(
+  prisma: PrismaClient,
+  secrets: LocalSecretEnvelope,
+  input: { readonly organizationId: string; readonly capabilityId: CapabilityId },
+): Promise<ResolvedCapabilityCredential> {
+  const connection = await prisma.organizationCapabilityConnection.findFirst({
+    where: {
+      organizationId: input.organizationId,
+      capabilityId: input.capabilityId,
+      status: "ACTIVE",
+    },
+    include: { activeSecretVersion: true },
+  });
+  if (connection === null || connection.activeSecretVersion === null) {
+    throw new CapabilityConnectionUnavailable(input.capabilityId, input.organizationId);
+  }
+  const version = connection.activeSecretVersion;
+  const binding = {
+    purpose: CAPABILITY_PURPOSE,
+    organizationId: connection.organizationId,
+    connectionId: connection.id,
+    secretVersionId: version.id,
+  };
+  const payload = secrets.decryptJson<CapabilitySecretPayload>(binding, version.envelope as unknown as SecretEnvelopeV1);
+  if (payload.schemaVersion !== 1) {
+    throw new Error(`unsupported capability secret schemaVersion: ${payload.schemaVersion}`);
+  }
+  return {
+    connectionId: connection.id,
+    organizationId: connection.organizationId,
+    capabilityId: connection.capabilityId,
+    schemaVersion: 1,
+    accessKeyId: payload.accessKeyId,
+    accessKeySecret: payload.accessKeySecret,
+    endpoint: payload.endpoint,
+  };
+}
@@ -0,0 +1,69 @@
+/**
+ * ADR-0027: Capability readiness probe. Validates the Alibaba Cloud docmind
+ * credential by calling QueryDocParserStatus with a dummy id — a 400 (bad
+ * request) means the credential is valid (the API accepted auth but rejected
+ * the id); a 401/403 means the credential is bad.
+ */
+import { classifyNetworkFailure, type NetworkFailureCategory } from "../connections/networkFailure.js";
+
+export interface CapabilityReadinessInput {
+  readonly endpoint: string;
+  readonly accessKeyId: string;
+  readonly accessKeySecret: string;
+}
+
+export type CapabilityReadinessProbe = (input: CapabilityReadinessInput) => Promise<void>;
+
+export class CapabilityReadinessError extends Error {
+  constructor(
+    readonly code: "capability_readiness_unsupported" | "capability_readiness_unreachable" | "capability_readiness_rejected",
+    message: string,
+    readonly category: NetworkFailureCategory | "configuration" | "http",
+    readonly upstreamStatus?: number,
+  ) {
+    super(message);
+    this.name = "CapabilityReadinessError";
+  }
+}
+
+/**
+ * Probe the Alibaba Cloud docmind credential. We call QueryDocParserStatus
+ * with a dummy id. The API will return:
+ *   - 400 (InvalidParameter) → credential valid, just a bad id → probe passes
+ *   - 401/403 (InvalidAccessKey/Forbidden) → credential invalid → probe fails
+ *   - network error → unreachable
+ */
+export const probeDocmindCredential: CapabilityReadinessProbe = async (input) => {
+  const url = `https://${input.endpoint}/?Action=QueryDocParserStatus&Id=probe-test&Version=2022-07-11`;
+  const authHeader = makeBasicAuth(input.accessKeyId, input.accessKeySecret);
+
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "GET",
+      headers: { authorization: authHeader, accept: "application/json" },
+      redirect: "manual",
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch (error) {
+    throw new CapabilityReadinessError(
+      "capability_readiness_unreachable",
+      "docmind credential readiness check could not reach the API",
+      classifyNetworkFailure(error),
+    );
+  }
+  await response.body?.cancel();
+  if (response.status === 401 || response.status === 403) {
+    throw new CapabilityReadinessError(
+      "capability_readiness_rejected",
+      `docmind credential rejected: status ${response.status}`,
+      "http",
+      response.status,
+    );
+  }
+};
+
+function makeBasicAuth(accessKeyId: string, accessKeySecret: string): string {
+  const credentials = Buffer.from(`${accessKeyId}:${accessKeySecret}`).toString("base64");
+  return `Basic ${credentials}`;
+}
@@ -0,0 +1,231 @@
+/**
+ * ADR-0027: Alibaba Cloud Document Mind (docmind) client.
+ *
+ * Uses the official @alicloud/docmind-api20220711 SDK to call the document
+ * parsing (large model version) API. The API is asynchronous:
+ *   1. SubmitDocParserJobAdvance — upload local file as a stream, get job id
+ *   2. QueryDocParserStatus — poll until data.status === "success";
+ *      the markdown output URL is returned in outputFormatResult
+ *   3. Download markdown from OSS, extract and download referenced images
+ *
+ * Pricing (2025-07, aliyun docmind):
+ *   - 图文文档基础链路: 0.02元/页
+ *   - 图文文档增强链路 (含公式 LaTeX): 0.04元/页
+ *   - 视频: 0.002元/秒
+ *   - 音频: 0.00035元/秒
+ */
+import $DocmindClient, {
+  SubmitDocParserJobAdvanceRequest,
+  QueryDocParserStatusRequest,
+} from "@alicloud/docmind-api20220711";
+import { RuntimeOptions } from "@alicloud/tea-util";
+import { createReadStream } from "node:fs";
+import { basename } from "node:path";
+import type { CapabilitySecretPayload } from "./types.js";
+
+/** A single extracted image downloaded from the markdown's OSS image URLs. */
+export interface DocmindExtractedImage {
+  readonly filename: string;
+  readonly data: Uint8Array;
+}
+
+/** The structured result of parsing one document. */
+export interface DocmindParseResult {
+  readonly markdown: string;
+  readonly images: readonly DocmindExtractedImage[];
+  readonly pageCount: number;
+  readonly costUsd: number | null;
+  readonly requestId: string | null;
+}
+
+export interface DocmindParseOptions {
+  readonly inputFilePath: string;
+}
+
+export interface CapabilityProviderClient {
+  parse(credential: CapabilitySecretPayload, options: DocmindParseOptions): Promise<DocmindParseResult>;
+}
+
+export class DocmindClientError extends Error {
+  constructor(
+    message: string,
+    readonly code: "docmind_unreachable" | "docmind_rejected" | "docmind_invalid_response" | "docmind_no_output" | "docmind_timeout",
+    readonly upstreamStatus?: number,
+  ) {
+    super(message);
+    this.name = "DocmindClientError";
+  }
+}
+
+/** Cost per page in USD (0.04 CNY/page ≈ 0.0056 USD). */
+const COST_PER_PAGE_USD = 0.0056;
+const POLL_INTERVAL_MS = 10_000;
+const POLL_TIMEOUT_MS = 5 * 60_000;
+
+type DocmindConfig = ConstructorParameters<typeof $DocmindClient.default>[0];
+
+export class AliyunDocmindClient implements CapabilityProviderClient {
+  async parse(credential: CapabilitySecretPayload, options: DocmindParseOptions): Promise<DocmindParseResult> {
+    const config: DocmindConfig = {
+      endpoint: credential.endpoint,
+      accessKeyId: credential.accessKeyId,
+      accessKeySecret: credential.accessKeySecret,
+      type: "access_key",
+      regionId: "cn-hangzhou",
+    } as DocmindConfig;
+    const client = new $DocmindClient.default(config);
+
+    // 1. Submit job with local file as a ReadStream (not a Buffer — the SDK
+    //    serializes Buffers as JSON {type:"Buffer",data:[...]} which the API
+    //    can't read; a Stream is uploaded as multipart form data).
+    const fileName = basename(options.inputFilePath);
+    const fileStream = createReadStream(options.inputFilePath);
+    const advanceRequest = new SubmitDocParserJobAdvanceRequest({
+      fileUrlObject: fileStream,
+      fileName,
+      outputFormat: ["markdown"],
+      formulaEnhancement: true,
+    });
+    const runtime = new RuntimeOptions({});
+    let submitResponse;
+    try {
+      submitResponse = await client.submitDocParserJobAdvance(advanceRequest, runtime);
+    } catch (e) {
+      throw new DocmindClientError(
+        e instanceof Error ? e.message : String(e),
+        "docmind_unreachable",
+      );
+    }
+    const jobId = submitResponse.body?.data?.id;
+    if (jobId === undefined || jobId === null || jobId === "") {
+      throw new DocmindClientError("docmind submit returned no job id", "docmind_invalid_response");
+    }
+
+    // 2. Poll QueryDocParserStatus until data.status === "success" or "fail".
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    let status = "";
+    let markdownUrl: string | null = null;
+    let pageCount = 0;
+    while (Date.now() < deadline) {
+      await sleep(POLL_INTERVAL_MS);
+      const statusReq = new QueryDocParserStatusRequest({ id: jobId });
+      const statusResponse = await client.queryDocParserStatus(statusReq);
+      const body = statusResponse.body as {
+        data?: {
+          status?: string;
+          pageCountEstimate?: number;
+          outputFormatResult?: Array<{ outputFileUrl?: string; outputType?: string }>;
+        };
+      };
+      status = body.data?.status ?? "";
+      if (status === "success") {
+        const mdResult = body.data?.outputFormatResult?.find((r) => r.outputType === "markdown");
+        markdownUrl = mdResult?.outputFileUrl ?? null;
+        pageCount = body.data?.pageCountEstimate ?? 0;
+        break;
+      }
+      if (status === "fail") {
+        throw new DocmindClientError(`docmind job ${jobId} failed`, "docmind_rejected");
+      }
+    }
+    if (status !== "success") {
+      throw new DocmindClientError(`docmind job ${jobId} timed out (status: ${status})`, "docmind_timeout");
+    }
+    if (markdownUrl === null) {
+      throw new DocmindClientError("docmind returned no markdown output URL", "docmind_no_output");
+    }
+
+    // 3. Download the markdown file from OSS.
+    let markdown: string;
+    try {
+      const mdResp = await fetch(markdownUrl);
+      if (!mdResp.ok) {
+        throw new DocmindClientError(`failed to download markdown: HTTP ${mdResp.status}`, "docmind_unreachable");
+      }
+      markdown = await mdResp.text();
+    } catch (e) {
+      if (e instanceof DocmindClientError) throw e;
+      throw new DocmindClientError(
+        e instanceof Error ? e.message : String(e),
+        "docmind_unreachable",
+      );
+    }
+    if (markdown === "") {
+      throw new DocmindClientError("docmind returned empty markdown", "docmind_no_output");
+    }
+
+    // 4. Download images referenced in the markdown (OSS URLs).
+    //    Markdown contains ![filename](http://...oss.../image.png?...) entries.
+    //    We rewrite them to local relative paths and download the images.
+    const images: DocmindExtractedImage[] = [];
+    const imageRefRegex = /!\[([^\]]*)\]\((https?:\/\/[^)]+)\)/g;
+    const localMarkdown = markdown.replace(imageRefRegex, (match, altText: string, url: string) => {
+      const idx = images.findIndex((img) => img.filename === extractFilename(altText, url, images.length));
+      if (idx >= 0) {
+        const img = images[idx]!;
+        return `![${altText}](${img.filename})`;
+      }
+      return match;
+    });
+
+    // Collect all image URLs first, then download.
+    const imageUrls: Array<{ url: string; altText: string }> = [];
+    let match: RegExpExecArray | null;
+    const collectRegex = /!\[([^\]]*)\]\((https?:\/\/[^)]+)\)/g;
+    while ((match = collectRegex.exec(markdown)) !== null) {
+      imageUrls.push({ url: match[2]!, altText: match[1]! });
+    }
+
+    for (let i = 0; i < imageUrls.length; i++) {
+      const { url, altText } = imageUrls[i]!;
+      const filename = extractFilename(altText, url, i);
+      try {
+        const imgResp = await fetch(url);
+        if (!imgResp.ok) continue;
+        const data = new Uint8Array(await imgResp.arrayBuffer());
+        images.push({ filename, data });
+      } catch {
+        // Best-effort: skip images that fail to download.
+      }
+    }
+
+    // Rewrite markdown with local image paths.
+    let finalMarkdown = markdown;
+    let imageIdx = 0;
+    finalMarkdown = finalMarkdown.replace(imageRefRegex, (match, altText: string, _url: string) => {
+      if (imageIdx < images.length) {
+        const img = images[imageIdx]!;
+        imageIdx++;
+        return `![${altText}](${img.filename})`;
+      }
+      return match;
+    });
+
+    if (pageCount === 0) {
+      pageCount = Math.max(1, images.length);
+    }
+    const costUsd = (pageCount > 0 ? pageCount : 1) * COST_PER_PAGE_USD;
+
+    return { markdown: finalMarkdown, images, pageCount, costUsd, requestId: jobId };
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/** Derive a clean filename from the alt text or URL. */
+function extractFilename(altText: string, url: string, index: number): string {
+  // Try alt text first (docmind often puts the original filename).
+  if (altText !== "" && altText.length < 100) {
+    const cleaned = altText.replace(/[^a-zA-Z0-9._-]/g, "_");
+    if (cleaned.length > 0) return cleaned;
+  }
+  // Fall back to URL path.
+  const urlPath = new URL(url).pathname;
+  const base = basename(urlPath);
+  if (base !== "" && base !== "/") return base;
+  return `image_${index + 1}.png`;
+}
@@ -0,0 +1,152 @@
+/**
+ * ADR-0027: pdf_to_md_bundle capability adapter.
+ *
+ * Converts a PDF in the run's workspace into a Markdown bundle (md + extracted
+ * images) by calling the MinerU document parsing service, writing outputs into
+ * the workspace, and recording consumption on a UsageFact (ADR-0026).
+ *
+ * Invariants (ADR-0027):
+ *   1. Credential isolation — the capability credential is resolved in Hub and
+ *      never reaches the Agent process. The MineruClient receives it as a
+ *      call argument, not from the environment.
+ *   2. Workspace containment — input and output paths are confined to the
+ *      run's workspace dir (ADR-0018 AgentSurface). Escapes are rejected.
+ *   3. Mandatory fact — a successful invocation always writes ≥1 UsageFact
+ *      with kind=external_capability, even when costUsd is null (ADR-0022:
+ *      missing cost ≠ zero).
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve, relative, isAbsolute } from "node:path";
+import type { PrismaClient } from "@prisma/client";
+import { LocalSecretEnvelope } from "../security/secretEnvelope.js";
+import { resolveCapabilityCredential } from "./capabilityConnections.js";
+import { DocmindClientError, type CapabilityProviderClient } from "./docmindClient.js";
+import {
+  CAPABILITIES,
+  type CapabilityAdapter,
+  type CapabilityInvocationInput,
+  type CapabilityInvocationResult,
+  type CapabilityOutputArtifact,
+} from "./types.js";
+
+const CAPABILITY_ID = "pdf_to_md_bundle" as const;
+const PROVIDER_ID = "aliyun_docmind";
+
+/** Thrown when a requested path escapes the workspace root (ADR-0018). */
+export class CapabilityPathEscape extends Error {
+  constructor(readonly requested: string, readonly workspaceDir: string) {
+    super(`capability path escapes workspace: ${requested} (root ${workspaceDir})`);
+    this.name = "CapabilityPathEscape";
+  }
+}
+
+/** Resolve a workspace-relative path, rejecting escapes (ADR-0018 AgentSurface). */
+function confineToWorkspace(requestedPath: string, workspaceDir: string): string {
+  if (isAbsolute(requestedPath)) {
+    const rel = relative(workspaceDir, requestedPath);
+    if (rel.startsWith("..") || rel === "") {
+      throw new CapabilityPathEscape(requestedPath, workspaceDir);
+    }
+    return requestedPath;
+  }
+  const resolved = resolve(workspaceDir, requestedPath);
+  const rel = relative(workspaceDir, resolved);
+  if (rel.startsWith("..")) {
+    throw new CapabilityPathEscape(requestedPath, workspaceDir);
+  }
+  return resolved;
+}
+
+export interface PdfToMdBundleDeps {
+  readonly secrets: LocalSecretEnvelope;
+  readonly client: CapabilityProviderClient;
+  readonly prisma: PrismaClient;
+}
+
+/** Build the pdf_to_md_bundle adapter. The client is injectable for testing. */
+export function createPdfToMdBundleAdapter(deps: PdfToMdBundleDeps): CapabilityAdapter {
+  return {
+    capabilityId: CAPABILITY_ID,
+    async invoke(input: CapabilityInvocationInput): Promise<CapabilityInvocationResult> {
+      const descriptor = CAPABILITIES[CAPABILITY_ID];
+      // 1. Resolve org-scoped credential (fail-closed, ADR-0024/0027).
+      const credential = await resolveCapabilityCredential(deps.prisma, deps.secrets, {
+        organizationId: input.organizationId,
+        capabilityId: CAPABILITY_ID,
+      });
+
+      // 2. Confine input + output paths to the workspace (ADR-0018).
+      const absoluteInput = confineToWorkspace(input.inputPath, input.workspaceDir);
+      const absoluteOutputDir = confineToWorkspace(input.outputDir, input.workspaceDir);
+      await mkdir(absoluteOutputDir, { recursive: true });
+
+      // 3. Call the backing service.
+      let result;
+      try {
+        result = await deps.client.parse(credential, { inputFilePath: absoluteInput });
+      } catch (e) {
+        if (e instanceof DocmindClientError) throw e;
+        throw new DocmindClientError(
+          e instanceof Error ? e.message : String(e),
+          "docmind_unreachable",
+        );
+      }
+      if (result.markdown === "") {
+        throw new DocmindClientError("docmind returned empty markdown", "docmind_no_output");
+      }
+
+      // 4. Write outputs into the workspace.
+      const artifacts: CapabilityOutputArtifact[] = [];
+      const mdPath = join(absoluteOutputDir, "document.md");
+      await writeFile(mdPath, result.markdown, "utf8");
+      artifacts.push({ path: relative(input.workspaceDir, mdPath), kind: "markdown" });
+
+      for (const image of result.images) {
+        const imagePath = join(absoluteOutputDir, image.filename);
+        const rel = relative(absoluteOutputDir, imagePath);
+        if (rel.startsWith("..")) {
+          // Defensive: image filename must not escape the output dir.
+          throw new CapabilityPathEscape(image.filename, absoluteOutputDir);
+        }
+        await writeFile(imagePath, image.data);
+        artifacts.push({ path: relative(input.workspaceDir, imagePath), kind: "image" });
+      }
+
+      // 5. Write the UsageFact (ADR-0026/0027). Always written on success;
+      //    costUsd null means unknown, NOT zero (ADR-0022).
+      const occurredAt = new Date();
+      await deps.prisma.usageFact.create({
+        data: {
+          runId: input.runId,
+          occurredAt,
+          kind: "external_capability",
+          provider: PROVIDER_ID,
+          model: null,
+          inputTokens: null,
+          outputTokens: null,
+          quantity: result.pageCount,
+          unit: descriptor.meteringUnit,
+          costUsd: result.costUsd,
+          costSource: result.costUsd !== null ? "provider_reported" : "unknown",
+          capabilityId: CAPABILITY_ID,
+          correlationId: result.requestId,
+          metadata: {},
+        },
+      });
+
+      return {
+        artifacts,
+        consumption: {
+          provider: PROVIDER_ID,
+          model: null,
+          inputTokens: null,
+          outputTokens: null,
+          quantity: result.pageCount,
+          unit: descriptor.meteringUnit,
+          costUsd: result.costUsd,
+          correlationId: result.requestId,
+        },
+      };
+    },
+  };
+}
@@ -0,0 +1,101 @@
+/**
+ * ADR-0027: External capability types shared across the adapter layer.
+ *
+ * A capability is a platform-registered, org-enabled document/media transform
+ * invoked as a side effect of an AgentRun. The adapter resolves the org's
+ * active capability connection, calls the backing service via an injectable
+ * client, writes output into the run's workspace (AgentSurface, ADR-0018),
+ * and records consumption on a UsageFact (ADR-0026).
+ */
+import type { PrismaClient, Prisma } from "@prisma/client";
+
+/** Stable capability identifiers registered with the platform (ADR-0027). */
+export const CAPABILITY_IDS = [
+  "pdf_to_md_bundle",
+  "audio_video_to_text",
+] as const;
+
+export type CapabilityId = (typeof CAPABILITY_IDS)[number];
+
+/** Non-token metering unit for a capability (ADR-0026/0027). */
+export interface CapabilityDescriptor {
+  readonly id: CapabilityId;
+  readonly meteringUnit: string;
+}
+
+/** Known capabilities and their metering units. Code-level registry. */
+export const CAPABILITIES: Readonly<Record<CapabilityId, CapabilityDescriptor>> = {
+  pdf_to_md_bundle: { id: "pdf_to_md_bundle", meteringUnit: "pages" },
+  audio_video_to_text: { id: "audio_video_to_text", meteringUnit: "audio_seconds" },
+};
+
+/** Input passed to a capability adapter invocation. */
+export interface CapabilityInvocationInput {
+  readonly runId: string;
+  readonly organizationId: string;
+  readonly projectId: string;
+  /** Absolute workspace dir of the run's project (ADR-0018 surface root). */
+  readonly workspaceDir: string;
+  /** Workspace-relative path to the input file (PDF, audio, …). */
+  readonly inputPath: string;
+  /** Workspace-relative directory to write outputs into. Created if absent. */
+  readonly outputDir: string;
+  /** Prisma client for UsageFact writes. */
+  readonly prisma: PrismaClient;
+}
+
+/** A successfully produced output artifact (file written into workspace). */
+export interface CapabilityOutputArtifact {
+  /** Workspace-relative path of the written artifact. */
+  readonly path: string;
+  readonly kind: "markdown" | "image" | "metadata" | "other";
+}
+
+/** Consumption recorded for one invocation (written to UsageFact). */
+export interface CapabilityConsumption {
+  /** The backing service provider id (e.g. "mineru", "openai_whisper"). */
+  readonly provider: string;
+  /** Model id if the service reports one; null for non-model services. */
+  readonly model: string | null;
+  readonly inputTokens: number | null;
+  readonly outputTokens: number | null;
+  /** Non-token meter (page count, audio seconds). */
+  readonly quantity: number;
+  readonly unit: string;
+  /** USD cost if the service reported one; null = unknown (ADR-0022). */
+  readonly costUsd: number | null;
+  /** External request id for reconciliation. */
+  readonly correlationId: string | null;
+}
+
+/** Result of a successful capability invocation. */
+export interface CapabilityInvocationResult {
+  readonly artifacts: readonly CapabilityOutputArtifact[];
+  readonly consumption: CapabilityConsumption;
+}
+
+/** A capability adapter: resolves credentials, calls the service, writes output. */
+export interface CapabilityAdapter {
+  readonly capabilityId: CapabilityId;
+  invoke(input: CapabilityInvocationInput): Promise<CapabilityInvocationResult>;
+}
+
+/** Decrypted capability credential (CapabilitySecretPayloadV1, ADR-0027).
+ * Alibaba Cloud Document Mind (docmind) uses AccessKey ID + Secret + endpoint. */
+export interface CapabilitySecretPayload {
+  readonly schemaVersion: 1;
+  readonly accessKeyId: string;
+  readonly accessKeySecret: string;
+  readonly endpoint: string;
+}
+
+/** Thrown when an org has no ACTIVE capability connection (fail-closed, ADR-0024). */
+export class CapabilityConnectionUnavailable extends Error {
+  constructor(readonly capabilityId: string, readonly organizationId: string) {
+    super(`no ACTIVE capability connection for ${capabilityId} in org ${organizationId}`);
+    this.name = "CapabilityConnectionUnavailable";
+  }
+}
+
+/** Prisma transaction client type alias (for resolver signatures). */
+export type TxClient = Prisma.TransactionClient;
@@ -1,6 +1,6 @@
 /**
- * ADR-0022 capacity dimensions (spec `Spec.System.Capacity.CapacityDimension`).
- * The 23 PINNED dimensions; exact numeric ceilings are `OPEN` and calibrated by
+ * ADR-0022 capacity dimensions.
+ * The 23 pinned dimensions; exact numeric ceilings are open and calibrated by
 * capacity testing. This module is the single source of the dimension set shared
 * by the platform-ceiling config and the org capacity-policy service.
 */
@@ -0,0 +1,144 @@
+/**
+ * Provider model catalog: fetches the list of models available to an
+ * Organization from its ACTIVE provider connection (OpenRouter), with an
+ * in-memory TTL cache so the admin model picker stays responsive without
+ * hammering the upstream API on every page load.
+ *
+ * The model list is **derived** from the provider connection — there is no
+ * separate model table to maintain. When an org activates a provider, its
+ * models become selectable; when the provider is disabled, the list empties.
+ */
+import type { PrismaClient } from "@prisma/client";
+import type { LocalSecretEnvelope } from "../security/secretEnvelope.js";
+import { decryptStoredProviderCredential } from "./providerConnections.js";
+
+/** A model entry surfaced to the admin model picker. */
+export interface ProviderModelEntry {
+  readonly id: string;
+  readonly label: string;
+  readonly toolCapable: boolean;
+}
+
+/** A model entry as returned by OpenRouter's /v1/models endpoint. */
+interface OpenRouterModel {
+  readonly id: string;
+  readonly name: string;
+  readonly supported_parameters: readonly string[];
+}
+
+interface OpenRouterModelsResponse {
+  readonly data: readonly OpenRouterModel[];
+}
+
+/** Cache entry: models + expiry timestamp. */
+interface CacheEntry {
+  readonly models: readonly ProviderModelEntry[];
+  readonly expiresAt: number;
+}
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Per-organization model catalog cache. Keyed by organizationId so that
+ * multiple orgs in the same Silo don't cross-pollute. The cache is intentionally
+ * process-local: it survives for the lifetime of the Hub process and is
+ * invalidated by TTL, not by DB events. A cache miss re-fetches from the
+ * provider API.
+ */
+export class ProviderModelCatalog {
+  private readonly cache = new Map<string, CacheEntry>();
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(
+    private readonly prisma: PrismaClient,
+    private readonly secrets: LocalSecretEnvelope,
+    private readonly ttlMs: number = DEFAULT_TTL_MS,
+    fetchImpl: typeof fetch = fetch,
+  ) {
+    this.fetchImpl = fetchImpl;
+  }
+
+  /**
+   * List tool-capable models available to the organization's ACTIVE provider
+   * connection. Returns cached results when fresh; otherwise fetches from the
+   * provider API. Falls back to an empty list (not an error) when the org has
+   * no ACTIVE provider — the admin sees the env-default model from the
+   * separate env fallback in the route.
+   */
+  async listModels(organizationId: string): Promise<readonly ProviderModelEntry[]> {
+    const cached = this.cache.get(organizationId);
+    if (cached !== undefined && cached.expiresAt > Date.now()) {
+      return cached.models;
+    }
+
+    const credential = await this.resolveActiveProviderCredential(organizationId);
+    if (credential === null) return [];
+
+    const models = await this.fetchModelsFromProvider(credential);
+    this.cache.set(organizationId, {
+      models,
+      expiresAt: Date.now() + this.ttlMs,
+    });
+    return models;
+  }
+
+  /** Force a cache invalidation (e.g. after provider connection changes). */
+  invalidate(organizationId: string): void {
+    this.cache.delete(organizationId);
+  }
+
+  private async resolveActiveProviderCredential(
+    organizationId: string,
+  ): Promise<{ readonly baseUrl: string; readonly authToken: string; readonly anthropicApiKey: string } | null> {
+    const connection = await this.prisma.organizationProviderConnection.findFirst({
+      where: { organizationId, status: "ACTIVE" },
+      include: { activeSecretVersion: true },
+    });
+    const version = connection?.activeSecretVersion;
+    if (connection === null || version === null || version === undefined || version.retiredAt !== null) {
+      return null;
+    }
+    const payload = decryptStoredProviderCredential(this.secrets, {
+      organizationId,
+      connectionId: connection.id,
+      providerId: connection.providerId,
+      secretVersionId: version.id,
+      envelopeVersion: version.envelopeVersion,
+      keyId: version.keyId,
+      envelope: version.envelope,
+    });
+    return {
+      baseUrl: payload.baseUrl,
+      authToken: payload.authToken,
+      anthropicApiKey: payload.anthropicApiKey,
+    };
+  }
+
+  private async fetchModelsFromProvider(
+    credential: { readonly baseUrl: string; readonly authToken: string; readonly anthropicApiKey: string },
+  ): Promise<readonly ProviderModelEntry[]> {
+    const base = credential.baseUrl.endsWith("/") ? credential.baseUrl : `${credential.baseUrl}/`;
+    // Filter to models that support tool calling — the agent runner requires it.
+    const url = new URL("v1/models?supported_parameters=tools", base);
+    const headers: Record<string, string> = {
+      authorization: `Bearer ${credential.authToken}`,
+      accept: "application/json",
+    };
+    if (credential.anthropicApiKey !== "") headers["x-api-key"] = credential.anthropicApiKey;
+
+    const response = await this.fetchImpl(url, {
+      method: "GET",
+      headers,
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (!response.ok) {
+      throw new Error(`provider models request failed: status ${response.status}`);
+    }
+    const body = (await response.json()) as OpenRouterModelsResponse;
+    return body.data.map((m) => ({
+      id: m.id,
+      label: m.name,
+      toolCapable: m.supported_parameters.includes("tools"),
+    }));
+  }
+}
@@ -250,6 +250,7 @@ async function initializeSilo(
      data: {
        organizationId: input.organization.id,
        name: "Inbox",
+        kind: "SYSTEM_INBOX",
        sortKey: "000000",
      },
    });
@@ -12,6 +12,7 @@
 */

 import type { ToolUseTraceStep } from "./trace-store.js";
+import type { CardContentSegment } from "../outboundImages.js";

 // ---------------------------------------------------------------------------
 // Types
@@ -42,6 +43,8 @@ const TOOL_ICONS: Record<string, string> = {
  request_approval: "thumb-up-filled",
  feishu_read_context: "search-filled",
  feishu_download_resource: "download-filled",
+  webfetch: "link-copy-filled",
+  websearch: "search-filled",
 };

 function toolIcon(toolName: string): string {
@@ -56,6 +59,7 @@ function toolIcon(toolName: string): string {
 export function buildAgentCard(params: {
  phase: CardPhase;
  text: string;
+  contentSegments?: readonly CardContentSegment[] | undefined;
  reasoningText: string | undefined;
  toolUseSteps: ToolUseTraceStep[];
  toolUseElapsedMs: number | undefined;
@@ -63,19 +67,19 @@ export function buildAgentCard(params: {
  interrupted: boolean | undefined;
  runId: string | undefined;
 }): Record<string, unknown> {
-  const { phase, text, reasoningText, toolUseSteps, toolUseElapsedMs, isError, interrupted } = params;
+  const { phase, text, contentSegments, reasoningText, toolUseSteps, toolUseElapsedMs, isError, interrupted } = params;
  const elements: unknown[] = [];

  // Tool-use panel (always present if there are steps)
  if (toolUseSteps.length > 0) {
    elements.push(buildToolUsePanel(toolUseSteps, toolUseElapsedMs, phase !== "complete"));
-  } else if (phase === "thinking" || (phase === "streaming" && text === "")) {
+  } else if (phase === "thinking" || (phase === "streaming" && text === "" && (contentSegments === undefined || contentSegments.length === 0))) {
    elements.push(buildPendingToolUsePanel());
  }

  // Reasoning panel
  if (reasoningText !== undefined && reasoningText !== "") {
-    if (phase === "streaming" && text === "") {
+    if (phase === "streaming" && text === "" && (contentSegments === undefined || contentSegments.length === 0)) {
      // Still thinking: show reasoning inline
      elements.push({
        tag: "markdown",
@@ -88,12 +92,11 @@ export function buildAgentCard(params: {
    }
  }

-  // Main text content
-  if (text !== "") {
-    elements.push({
-      tag: "markdown",
-      content: truncateText(text, MAX_TEXT_LENGTH),
-    });
+  // Main answer: either materialized segments (markdown + Feishu-hosted images)
+  // or a single markdown block.
+  const answerElements = buildAnswerElements(text, contentSegments);
+  if (answerElements.length > 0) {
+    elements.push(...answerElements);
  } else if (phase === "thinking" && toolUseSteps.length === 0 && (reasoningText === undefined || reasoningText === "")) {
    elements.push({
      tag: "markdown",
@@ -399,6 +402,43 @@ function escapeMarkdown(value: string): string {
  return value.replace(/\\/g, "\\\\").replace(/([`*_{}[\]<>])/g, "\\$1");
 }

+function buildAnswerElements(
+  text: string,
+  contentSegments: readonly CardContentSegment[] | undefined,
+): unknown[] {
+  if (contentSegments !== undefined && contentSegments.length > 0) {
+    const elements: unknown[] = [];
+    let remaining = MAX_TEXT_LENGTH;
+    for (const segment of contentSegments) {
+      if (segment.type === "image") {
+        elements.push({
+          tag: "img",
+          img_key: segment.imgKey,
+          alt: { tag: "plain_text", content: segment.alt },
+          mode: "fit_horizontal",
+          preview: true,
+        });
+        continue;
+      }
+      if (segment.content === "" || remaining <= 0) continue;
+      const slice = segment.content.length <= remaining
+        ? segment.content
+        : truncateText(segment.content, remaining);
+      remaining -= slice.length;
+      elements.push({
+        tag: "markdown",
+        content: slice,
+      });
+    }
+    return elements;
+  }
+  if (text === "") return [];
+  return [{
+    tag: "markdown",
+    content: truncateText(text, MAX_TEXT_LENGTH),
+  }];
+}
+
 function truncateText(value: string, maxLength: number): string {
  return value.length <= maxLength ? value : `${value.slice(0, maxLength - 3)}...`;
 }
@@ -18,10 +18,13 @@
 *   4. onToolEnd(name, id, input, result?, error?) — complete a tool step
 *   5. finish(finalText)    — flush + transition to complete card
 *   6. fail(errorText)      — flush + transition to error card
+ *
+ * On finish, markdown image references (`![](url|path)`) are downloaded /
+ * read, uploaded to Feishu as message images, and embedded as native card
+ * `img` elements so external URLs never hit Feishu content-security checks.
 */
-
 import type { FeishuRuntime, SendMessageOptions } from "../client.js";
-import { sendCard, patchCard, sendText } from "../client.js";
+import { sendCard, patchCard, sendText, sendLongText } from "../client.js";
 import { DEFAULT_MAX_MESSAGE_LENGTH, splitAtBoundary } from "../textStream.js";
 import {
  startToolUseTraceRun,
@@ -31,6 +34,12 @@ import {
  getToolUseTraceSteps,
 } from "./trace-store.js";
 import { buildAgentCard, type CardPhase } from "./builder.js";
+import {
+  type CardContentSegment,
+  maskMarkdownImagesForStreaming,
+  materializeAnswerSegments,
+  sendImageMessage,
+} from "../outboundImages.js";

 export interface StreamingCardSink {
  readonly create: (card: Record<string, unknown>) => Promise<string | null>;
@@ -44,6 +53,11 @@ export interface StreamingCardOptions {
  readonly sendOptions?: SendMessageOptions | undefined;
  readonly patchIntervalMs: number | undefined;
  readonly maxMessageLength: number | undefined;
+  /** Project workspace root; required to resolve local image paths. */
+  readonly workspaceRoot?: string | undefined;
+  /** Project workspace directory; required to resolve local image paths. */
+  readonly workspaceDir?: string | undefined;
+  readonly maxImageBytes?: number | undefined;
 }

 const DEFAULT_PATCH_INTERVAL_MS = 400;
@@ -65,6 +79,9 @@ export class StreamingAgentCard {
  private readonly sendOptions: SendMessageOptions | undefined;
  private readonly patchIntervalMs: number;
  private readonly maxMessageLength: number;
+  private readonly workspaceRoot: string | undefined;
+  private readonly workspaceDir: string | undefined;
+  private readonly maxImageBytes: number | undefined;

  constructor(options: StreamingCardOptions) {
    this.runId = options.runId;
@@ -73,6 +90,9 @@ export class StreamingAgentCard {
    this.sendOptions = options.sendOptions;
    this.patchIntervalMs = options.patchIntervalMs ?? DEFAULT_PATCH_INTERVAL_MS;
    this.maxMessageLength = options.maxMessageLength ?? DEFAULT_MAX_MESSAGE_LENGTH;
+    this.workspaceRoot = options.workspaceRoot;
+    this.workspaceDir = options.workspaceDir;
+    this.maxImageBytes = options.maxImageBytes;
    startToolUseTraceRun(this.runId);
  }

@@ -106,23 +126,43 @@ export class StreamingAgentCard {
    recordToolUseEnd({ runId: this.runId, ...params });
    this.scheduleFlush();
  }
-  async finish(fallbackText: string, options: { readonly interrupted?: boolean; readonly footerText?: string | undefined } = {}): Promise<void> {
+
+  async finish(
+    fallbackText: string,
+    options: { readonly interrupted?: boolean; readonly footerText?: string | undefined } = {},
+  ): Promise<void> {
    await this.flushChain;
    this.interrupted = options.interrupted === true;
    const footerText = options.footerText ?? "";
    const fallbackWithFooter = appendFooter(fallbackText, footerText);
    try {
+      let answerText =
+        this.text.length > 0 ? appendFooter(this.text, footerText) : fallbackWithFooter;
+      this.text = answerText;
+
+      const { segments, unresolved } = await materializeAnswerSegments(answerText, {
+        rt: this.rt,
+        workspaceRoot: this.workspaceRoot,
+        workspaceDir: this.workspaceDir,
+        maxImageBytes: this.maxImageBytes,
+      });
+      if (unresolved.length > 0) {
+        this.rt.logger.warn(
+          { runId: this.runId, unresolvedCount: unresolved.length, unresolved: unresolved.slice(0, 5) },
+          "some answer images could not be uploaded to Feishu",
+        );
+      }
+
      let updated = true;
-      if (this.text.length > 0) {
-        this.text = appendFooter(this.text, footerText);
-        updated = await this.flushCard("complete", this.text);
-      } else if (this.currentMessageId === null && fallbackWithFooter.length > 0) {
-        // No streaming text was sent. If we never created a card, send one now.
-        this.text = fallbackWithFooter;
-        updated = await this.flushCard("complete", this.text);
+      if (answerText.length > 0 || segments.length > 0) {
+        updated = await this.flushCard("complete", answerText, false, segments);
      } else if (this.currentMessageId !== null) {
-        // Patch the existing card with the final text.
-        updated = await this.flushCard("complete", fallbackWithFooter);
+        updated = await this.flushCard("complete", "", false, []);
+      }
+
+      if (!updated) {
+        // Card path failed (e.g. residual content policy). Deliver text + standalone images.
+        updated = await this.deliverPlainFallback(segments, answerText);
      }
      if (!updated && this.interrupted) {
        await sendText(this.rt, this.chatId, "\u5DF2\u4E2D\u65AD\u5F53\u524D\u8FD0\u884C\u3002", this.sendOptions);
@@ -166,15 +206,30 @@ export class StreamingAgentCard {
    return this.flushCard(this.currentPhase(), this.text);
  }

-  private async flushCard(phase: CardPhase, text: string, isError = false): Promise<boolean> {
-    const chunks = splitAtBoundary(text, this.maxMessageLength);
-    const firstChunk = chunks[0];
-    if (firstChunk === undefined) return true;
+  private async flushCard(
+    phase: CardPhase,
+    text: string,
+    isError = false,
+    contentSegments?: readonly CardContentSegment[],
+  ): Promise<boolean> {
+    // During live streaming, strip image URLs so Feishu never fetches remote
+    // ranks mid-run. Materialized segments are only used on the complete pass.
+    const displayText =
+      phase === "complete" && contentSegments !== undefined
+        ? text
+        : maskMarkdownImagesForStreaming(text);

+    const chunks = splitAtBoundary(displayText, this.maxMessageLength);
+    const firstChunk = chunks[0] ?? "";
+    // When we have segments (complete+images), keep first-card complete content
+    // on segments only; overflow text (rare) falls back to plain chunked cards.
    const toolUseSteps = getToolUseTraceSteps(this.runId);
    const card = buildAgentCard({
      phase,
-      text: firstChunk,
+      text: contentSegments !== undefined && contentSegments.length > 0 ? "" : firstChunk,
+      contentSegments: contentSegments !== undefined && contentSegments.length > 0
+        ? contentSegments
+        : undefined,
      reasoningText: this.reasoningText || undefined,
      toolUseSteps,
      toolUseElapsedMs: this.toolUseElapsedMs,
@@ -186,43 +241,89 @@ export class StreamingAgentCard {
    if (this.currentMessageId === null) {
      this.currentMessageId = await sendCard(this.rt, this.chatId, card, this.sendOptions);
      let updated = this.currentMessageId !== null;
-      // Send overflow chunks as new messages (rare for agent output)
-      for (const chunk of chunks.slice(1)) {
-        const overflowCard = buildAgentCard({
-          phase,
-          text: chunk,
-          reasoningText: undefined,
-          toolUseSteps: [],
-          toolUseElapsedMs: undefined,
-          isError,
-          interrupted: this.interrupted,
-          runId: undefined,
-        });
-        const overflowMessageId = await sendCard(this.rt, this.chatId, overflowCard, this.sendOptions);
-        updated = updated && overflowMessageId !== null;
-        this.currentMessageId = overflowMessageId;
-      }
-      return updated;
-    } else {
-      let updated = await patchCard(this.rt, this.currentMessageId, card);
-      // For overflow, create new messages
-      for (const chunk of chunks.slice(1)) {
-        const overflowCard = buildAgentCard({
-          phase,
-          text: chunk,
-          reasoningText: undefined,
-          toolUseSteps: [],
-          toolUseElapsedMs: undefined,
-          isError,
-          interrupted: this.interrupted,
-          runId: undefined,
-        });
-        const overflowMessageId = await sendCard(this.rt, this.chatId, overflowCard, this.sendOptions);
-        updated = updated && overflowMessageId !== null;
-        this.currentMessageId = overflowMessageId;
+      // Send overflow chunks as new messages (rare for agent output). Segments
+      // already include the whole answer; only plain text overflows.
+      if (contentSegments === undefined || contentSegments.length === 0) {
+        for (const chunk of chunks.slice(1)) {
+          const overflowCard = buildAgentCard({
+            phase,
+            text: chunk,
+            reasoningText: undefined,
+            toolUseSteps: [],
+            toolUseElapsedMs: undefined,
+            isError,
+            interrupted: this.interrupted,
+            runId: undefined,
+          });
+          const overflowMessageId = await sendCard(this.rt, this.chatId, overflowCard, this.sendOptions);
+          updated = updated && overflowMessageId !== null;
+          this.currentMessageId = overflowMessageId;
+        }
      }
      return updated;
    }
+
+    let updated = await patchCard(this.rt, this.currentMessageId, card);
+    if (contentSegments === undefined || contentSegments.length === 0) {
+      for (const chunk of chunks.slice(1)) {
+        const overflowCard = buildAgentCard({
+          phase,
+          text: chunk,
+          reasoningText: undefined,
+          toolUseSteps: [],
+          toolUseElapsedMs: undefined,
+          isError,
+          interrupted: this.interrupted,
+          runId: undefined,
+        });
+        const overflowMessageId = await sendCard(this.rt, this.chatId, overflowCard, this.sendOptions);
+        updated = updated && overflowMessageId !== null;
+        this.currentMessageId = overflowMessageId;
+      }
+    }
+    return updated;
+  }
+
+  private async deliverPlainFallback(
+    segments: readonly CardContentSegment[],
+    answerText: string,
+  ): Promise<boolean> {
+    const textParts: string[] = [];
+    const imageKeys: string[] = [];
+    if (segments.length > 0) {
+      for (const segment of segments) {
+        if (segment.type === "markdown") {
+          if (segment.content.trim() !== "") textParts.push(segment.content);
+        } else {
+          imageKeys.push(segment.imgKey);
+        }
+      }
+    } else if (answerText.trim() !== "") {
+      textParts.push(maskMarkdownImagesForStreaming(answerText));
+    }
+
+    let any = false;
+    if (textParts.length > 0) {
+      const messageId = await sendLongText(
+        this.rt,
+        this.chatId,
+        textParts.join("\n\n"),
+        this.sendOptions,
+      );
+      any = messageId !== null;
+    }
+    for (const imageKey of imageKeys) {
+      try {
+        const messageId = await sendImageMessage(this.rt, this.chatId, imageKey, this.sendOptions);
+        any = any || messageId !== null;
+      } catch (error) {
+        this.rt.logger.warn(
+          { runId: this.runId, err: error instanceof Error ? error.message : String(error) },
+          "standalone image fallback failed",
+        );
+      }
+    }
+    return any;
  }

  private currentPhase(): CardPhase {
@@ -235,5 +336,5 @@ export class StreamingAgentCard {
 function appendFooter(text: string, footerText: string): string {
  if (footerText === "") return text;
  if (text === "") return footerText;
-  return `${text.trimEnd()}\n\n${footerText}`;
+  return `${text}\n\n${footerText}`;
 }
@@ -316,7 +316,8 @@ export async function sendCard(
      { msgType: "interactive", content: JSON.stringify(card) },
      options,
    );
-  } catch {
+  } catch (e) {
+    rt.logger.warn({ chatId, err: errorText(e) }, "sendCard failed");
    return null;
  }
 }
@@ -334,7 +335,7 @@ export async function patchCard(rt: FeishuRuntime, messageId: string, card: Reco
    });
    return true;
  } catch (e) {
-    rt.logger.warn({ messageId, err: e instanceof Error ? e.message : String(e) }, "patchCard failed");
+    rt.logger.warn({ messageId, err: errorText(e) }, "patchCard failed");
    return false;
  }
 }
@@ -7,11 +7,16 @@ import { readFeishuContext } from "./read.js";
 import type { ApprovalManager } from "./approval.js";
 import { CPH_HUB_MCP_TOOL_IDS, type CphHubMcpToolId } from "../agent/roleTools.js";
 import { WorkspaceFileBoundaryError } from "../security/workspaceFiles.js";
+import type { PrismaClient } from "@prisma/client";
+import type { LocalSecretEnvelope } from "../security/secretEnvelope.js";
+import { createPdfToMdBundleAdapter } from "../capability/pdfToMdBundle.js";
+import { AliyunDocmindClient } from "../capability/docmindClient.js";

 export interface FileDeliveryToolOptions {
  readonly rt: FeishuRuntime;
  readonly chatId: string;
  readonly projectId: string;
+  readonly organizationId: string;
  readonly runId: string;
  readonly workspaceRoot?: string | undefined;
  readonly workspaceDir: string;
@@ -20,6 +25,8 @@ export interface FileDeliveryToolOptions {
  readonly approvalManager: ApprovalManager;
  readonly onDelivered?: (path: string) => void;
  readonly tools?: readonly CphHubMcpToolId[] | undefined;
+  readonly prisma: PrismaClient;
+  readonly secretEnvelope: LocalSecretEnvelope;
 }

 export function createFileDeliveryMcpServer(options: FileDeliveryToolOptions): McpSdkServerConfigWithInstance {
@@ -182,18 +189,18 @@ export function createFileDeliveryMcpServer(options: FileDeliveryToolOptions): M
    tools.push(
      tool(
        "request_approval",
-        "Send an interactive Feishu approval/confirmation card to the current chat and wait for a button click.",
+        "Send an interactive Feishu approval/confirmation card in the current chat and wait for the user's button click.",
        {
          title: z.string().describe("Card title."),
          body: z.string().describe("Markdown card body explaining what needs approval or confirmation."),
          options: z
            .array(z.object({
              label: z.string().describe("Button label shown to the user."),
-              value: z.string().describe("Action value returned to the agent when this button is clicked."),
-              style: z.enum(["primary", "default", "danger"]).optional().describe("Optional Feishu button style."),
+              value: z.string().describe("Stable option value returned after the user clicks."),
+              style: z.enum(["default", "primary", "danger"]).optional(),
            }))
            .min(1)
-            .describe("Button choices for the approval card."),
+            .describe("One or more response options."),
        },
        async (args) => {
          const messageId = await sendApprovalCard(
@@ -230,6 +237,51 @@ export function createFileDeliveryMcpServer(options: FileDeliveryToolOptions): M
    );
  }

+  if (enabledTools.has("convert_pdf_to_md")) {
+    const adapter = createPdfToMdBundleAdapter({
+      secrets: options.secretEnvelope,
+      client: new AliyunDocmindClient(),
+      prisma: options.prisma,
+    });
+    tools.push(
+      tool(
+        "convert_pdf_to_md",
+        "Convert a PDF file in the workspace to a Markdown bundle (markdown + extracted images) using Alibaba Cloud Document Mind. The PDF must already be in the workspace (use feishu_download_resource first if it came from Feishu). Returns the path to the generated markdown file and the list of extracted image paths. Mathematical formulas are converted to LaTeX.",
+        {
+          input_path: z.string().describe("Relative path to the input PDF within the workspace."),
+          output_dir: z.string().describe("Relative directory within the workspace to write the markdown and images into. Will be created if it does not exist."),
+        },
+        async (args) => {
+          try {
+            const result = await adapter.invoke({
+              runId: options.runId,
+              organizationId: options.organizationId,
+              projectId: options.projectId,
+              workspaceDir: options.workspaceDir,
+              inputPath: args.input_path,
+              outputDir: args.output_dir,
+              prisma: options.prisma,
+            });
+            const lines = [`Converted PDF to markdown. ${result.artifacts.length} files written:`];
+            for (const artifact of result.artifacts) {
+              lines.push(`  - ${artifact.path} (${artifact.kind})`);
+            }
+            lines.push(`Pages: ${result.consumption.quantity}, Cost: $${(result.consumption.costUsd ?? 0).toFixed(4)}`);
+            return {
+              content: [{ type: "text", text: lines.join("\n") }],
+            };
+          } catch (e) {
+            return {
+              isError: true,
+              content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+            };
+          }
+        },
+        { alwaysLoad: true },
+      ),
+    );
+  }
+
  const instructions = mcpInstructions(enabledTools);
  return createSdkMcpServer({
    name: "cph_hub",
@@ -260,5 +312,12 @@ function mcpInstructions(enabledTools: ReadonlySet<CphHubMcpToolId>): string {
  if (enabledTools.has("request_approval")) {
    instructions.push("Use request_approval when explicit human approval or confirmation is required before continuing.");
  }
+  if (enabledTools.has("convert_pdf_to_md")) {
+    instructions.push(
+      "Use convert_pdf_to_md when the user asks to convert a PDF to Markdown.",
+      "If the PDF came from a Feishu message, first use feishu_download_resource to save it to the workspace, then call convert_pdf_to_md.",
+      "Do NOT attempt to parse PDFs yourself with Read or Bash — always use convert_pdf_to_md for accurate text, formula, and image extraction.",
+    );
+  }
  return instructions.join(" ");
 }
@@ -0,0 +1,389 @@
+/**
+ * Resolve markdown image references in agent answers into Feishu-hosted
+ * image_keys so cards can embed them without remote URLs (which trip Feishu
+ * content-security controls).
+ */
+import { isIP } from "node:net";
+import type { FeishuRuntime } from "./client.js";
+import { withRetry } from "./client.js";
+import {
+  WorkspaceFileBoundaryError,
+  readWorkspaceFileNoFollow,
+} from "../security/workspaceFiles.js";
+
+export const FEISHU_MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+export const DEFAULT_MAX_OUTBOUND_IMAGES = 10;
+
+const IMAGE_MARKDOWN_RE = /!\[([^\]\n]*)\]\(([^)\n]+)\)/g;
+const FENCED_CODE_RE = /```[\s\S]*?```/g;
+
+export type CardContentSegment =
+  | { readonly type: "markdown"; readonly content: string }
+  | { readonly type: "image"; readonly imgKey: string; readonly alt: string };
+
+export interface MarkdownImageRef {
+  readonly fullMatch: string;
+  readonly alt: string;
+  readonly src: string;
+  readonly index: number;
+  readonly length: number;
+}
+
+export interface OutboundImageContext {
+  readonly rt: FeishuRuntime;
+  readonly workspaceRoot?: string | undefined;
+  readonly workspaceDir?: string | undefined;
+  readonly maxImageBytes?: number | undefined;
+  readonly maxImages?: number | undefined;
+  readonly fetchImpl?: typeof fetch | undefined;
+}
+
+type ImageCreateResponse = {
+  image_key?: string;
+  data?: { image_key?: string };
+} | null;
+
+type MessageCreateResponse = {
+  message_id?: string;
+  data?: { message_id?: string };
+} | null;
+
+/** Streaming-safe view: drop markdown image URLs so partial cards do not hit Feishu URL checks. */
+export function maskMarkdownImagesForStreaming(text: string): string {
+  return rewriteMarkdownImagesOutsideCode(text, (ref) => {
+    const alt = ref.alt.trim();
+    return alt === "" ? "\u3010\u56fe\u7247\u3011" : alt;
+  });
+}
+
+export function findMarkdownImagesOutsideCode(text: string): MarkdownImageRef[] {
+  const blocked = blockedRanges(text);
+  const refs: MarkdownImageRef[] = [];
+  IMAGE_MARKDOWN_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = IMAGE_MARKDOWN_RE.exec(text)) !== null) {
+    const index = match.index;
+    if (blocked.some((range) => index >= range.start && index < range.end)) continue;
+    const fullMatch = match[0];
+    const alt = match[1] ?? "";
+    const rawSrc = (match[2] ?? "").trim();
+    const src = stripUrlTitle(rawSrc);
+    if (src === "") continue;
+    refs.push({ fullMatch, alt, src, index, length: fullMatch.length });
+  }
+  return refs;
+}
+
+/**
+ * Upload reachable markdown images and split the answer into card segments
+ * (markdown + Feishu img elements). Unresolved images become visible alt text.
+ */
+export async function materializeAnswerSegments(
+  text: string,
+  ctx: OutboundImageContext,
+): Promise<{ segments: CardContentSegment[]; unresolved: string[] }> {
+  const refs = findMarkdownImagesOutsideCode(text);
+  if (refs.length === 0) {
+    return {
+      segments: text === "" ? [] : [{ type: "markdown", content: text }],
+      unresolved: [],
+    };
+  }
+
+  const maxImages = ctx.maxImages ?? DEFAULT_MAX_OUTBOUND_IMAGES;
+  const maxBytes = ctx.maxImageBytes ?? FEISHU_MAX_IMAGE_BYTES;
+  const keyBySrc = new Map<string, string>();
+  const unresolved: string[] = [];
+  const uniqueSrcs: string[] = [];
+  for (const ref of refs) {
+    if (!uniqueSrcs.includes(ref.src)) uniqueSrcs.push(ref.src);
+  }
+
+  for (const src of uniqueSrcs.slice(0, maxImages)) {
+    try {
+      const bytes = await resolveOutboundImageBytes(src, ctx, maxBytes);
+      if (bytes === null) {
+        unresolved.push(src);
+        continue;
+      }
+      const imageKey = await uploadMessageImage(ctx.rt, bytes);
+      keyBySrc.set(src, imageKey);
+    } catch (error) {
+      ctx.rt.logger.warn(
+        { src, err: error instanceof Error ? error.message : String(error) },
+        "outbound image materialize failed",
+      );
+      unresolved.push(src);
+    }
+  }
+  for (const src of uniqueSrcs.slice(maxImages)) {
+    unresolved.push(src);
+  }
+
+  const segments: CardContentSegment[] = [];
+  let cursor = 0;
+  for (const ref of refs) {
+    if (ref.index > cursor) {
+      pushMarkdown(segments, text.slice(cursor, ref.index));
+    }
+    const imageKey = keyBySrc.get(ref.src);
+    if (imageKey !== undefined) {
+      segments.push({
+        type: "image",
+        imgKey: imageKey,
+        alt: ref.alt.trim() === "" ? "\u56fe\u7247" : ref.alt.trim(),
+      });
+    } else {
+      const alt = ref.alt.trim();
+      pushMarkdown(segments, alt === "" ? "\u3010\u56fe\u7247\u3011" : alt);
+    }
+    cursor = ref.index + ref.length;
+  }
+  if (cursor < text.length) {
+    pushMarkdown(segments, text.slice(cursor));
+  }
+  return { segments, unresolved };
+}
+
+export async function uploadMessageImage(rt: FeishuRuntime, image: Buffer): Promise<string> {
+  if (image.byteLength === 0) {
+    throw new Error("image is empty");
+  }
+  if (image.byteLength > FEISHU_MAX_IMAGE_BYTES) {
+    throw new Error(`image exceeds Feishu limit of ${FEISHU_MAX_IMAGE_BYTES} bytes`);
+  }
+  const client = rt.client as unknown as {
+    im: { v1: { image: { create: (p: unknown) => Promise<ImageCreateResponse> } } };
+  };
+  const res = await withRetry(async () =>
+    client.im.v1.image.create({
+      data: { image_type: "message", image },
+    }),
+  );
+  const imageKey = res?.image_key ?? res?.data?.image_key;
+  if (imageKey === undefined || imageKey === "") {
+    throw new Error("Feishu image upload response is missing image_key");
+  }
+  return imageKey;
+}
+
+/** Send a standalone image message (fallback if card embed is unavailable). */
+export async function sendImageMessage(
+  rt: FeishuRuntime,
+  chatId: string,
+  imageKey: string,
+  options?: { readonly replyToMessageId?: string | undefined },
+): Promise<string | null> {
+  const client = rt.client as unknown as {
+    im: {
+      v1: {
+        message: {
+          create: (p: unknown) => Promise<MessageCreateResponse>;
+          reply: (p: unknown) => Promise<MessageCreateResponse>;
+        };
+      };
+    };
+  };
+  const replyTo = options?.replyToMessageId;
+  if (replyTo !== undefined && replyTo !== "") {
+    const res = await client.im.v1.message.reply({
+      path: { message_id: replyTo },
+      data: { msg_type: "image", content: JSON.stringify({ image_key: imageKey }) },
+    });
+    return res?.data?.message_id ?? res?.message_id ?? null;
+  }
+  const res = await client.im.v1.message.create({
+    params: { receive_id_type: "chat_id" },
+    data: {
+      receive_id: chatId,
+      msg_type: "image",
+      content: JSON.stringify({ image_key: imageKey }),
+    },
+  });
+  return res?.data?.message_id ?? res?.message_id ?? null;
+}
+
+export async function resolveOutboundImageBytes(
+  src: string,
+  ctx: OutboundImageContext,
+  maxBytes: number,
+): Promise<Buffer | null> {
+  if (isRemoteUrl(src)) {
+    return fetchRemoteImage(src, ctx.fetchImpl ?? fetch, maxBytes);
+  }
+  const root = ctx.workspaceRoot?.trim();
+  const dir = ctx.workspaceDir?.trim();
+  if (root === undefined || root === "" || dir === undefined || dir === "") {
+    return null;
+  }
+  try {
+    const file = await readWorkspaceFileNoFollow(root, dir, src, maxBytes);
+    return file.data;
+  } catch (error) {
+    if (error instanceof WorkspaceFileBoundaryError && error.reason === "not_found") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function rewriteMarkdownImagesOutsideCode(
+  text: string,
+  replace: (ref: MarkdownImageRef) => string,
+): string {
+  const refs = findMarkdownImagesOutsideCode(text);
+  if (refs.length === 0) return text;
+  let out = "";
+  let cursor = 0;
+  for (const ref of refs) {
+    out += text.slice(cursor, ref.index);
+    out += replace(ref);
+    cursor = ref.index + ref.length;
+  }
+  out += text.slice(cursor);
+  return out;
+}
+
+function pushMarkdown(segments: CardContentSegment[], content: string): void {
+  if (content === "") return;
+  const last = segments[segments.length - 1];
+  if (last !== undefined && last.type === "markdown") {
+    segments[segments.length - 1] = { type: "markdown", content: last.content + content };
+    return;
+  }
+  segments.push({ type: "markdown", content });
+}
+
+function blockedRanges(text: string): Array<{ start: number; end: number }> {
+  const ranges: Array<{ start: number; end: number }> = [];
+  FENCED_CODE_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = FENCED_CODE_RE.exec(text)) !== null) {
+    ranges.push({ start: match.index, end: match.index + match[0].length });
+  }
+  return ranges;
+}
+
+function stripUrlTitle(raw: string): string {
+  const trimmed = raw.trim();
+  // Markdown optional title: url "title" or url 'title'
+  const titled = /^(\S+)\s+(".*"|'.*')$/.exec(trimmed);
+  return (titled?.[1] ?? trimmed).trim();
+}
+
+function isRemoteUrl(src: string): boolean {
+  try {
+    const url = new URL(src);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+async function fetchRemoteImage(
+  src: string,
+  fetchImpl: typeof fetch,
+  maxBytes: number,
+): Promise<Buffer | null> {
+  let url: URL;
+  try {
+    url = new URL(src);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+  if (!isPublicHttpHost(url.hostname)) return null;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 15_000);
+  try {
+    const response = await fetchImpl(url, {
+      method: "GET",
+      redirect: "manual",
+      signal: controller.signal,
+      headers: { accept: "image/*,*/*;q=0.8" },
+    });
+    // One safe redirect hop to another public http(s) host.
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location");
+      if (location === null || location === "") return null;
+      let redirected: URL;
+      try {
+        redirected = new URL(location, url);
+      } catch {
+        return null;
+      }
+      if (redirected.protocol !== "http:" && redirected.protocol !== "https:") return null;
+      if (!isPublicHttpHost(redirected.hostname)) return null;
+      const second = await fetchImpl(redirected, {
+        method: "GET",
+        redirect: "manual",
+        signal: controller.signal,
+        headers: { accept: "image/*,*/*;q=0.8" },
+      });
+      return readImageBody(second, maxBytes);
+    }
+    return readImageBody(response, maxBytes);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function readImageBody(response: Response, maxBytes: number): Promise<Buffer | null> {
+  if (!response.ok) return null;
+  const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+  if (
+    contentType !== "" &&
+    !contentType.startsWith("image/") &&
+    !contentType.includes("octet-stream") &&
+    (contentType.startsWith("text/") || contentType.includes("json") || contentType.includes("html"))
+  ) {
+    return null;
+  }
+  const contentLength = Number(response.headers.get("content-length") ?? "NaN");
+  if (Number.isFinite(contentLength) && contentLength > maxBytes) return null;
+  const buf = Buffer.from(await response.arrayBuffer());
+  if (buf.byteLength === 0 || buf.byteLength > maxBytes) return null;
+  return buf;
+}
+
+function isPublicHttpHost(hostname: string): boolean {
+  const host = hostname.trim().toLowerCase().replace(/\.$/, "");
+  if (host === "" || host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local")) {
+    return false;
+  }
+  if (host === "0.0.0.0" || host === "::" || host === "[::]" || host === "::1" || host === "[::1]") {
+    return false;
+  }
+  const unbracketed = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  const ipVersion = isIP(unbracketed);
+  if (ipVersion === 4) return !isPrivateIPv4(unbracketed);
+  if (ipVersion === 6) return !isPrivateIPv6(unbracketed);
+  return true;
+}
+
+function isPrivateIPv4(ip: string): boolean {
+  const parts = ip.split(".").map((part) => Number(part));
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    return true;
+  }
+  const a = parts[0]!;
+  const b = parts[1]!;
+  if (a === 10 || a === 127 || a === 0) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT
+  if (a >= 224) return true; // multicast / reserved
+  return false;
+}
+
+function isPrivateIPv6(ip: string): boolean {
+  const normalized = ip.toLowerCase();
+  if (normalized === "::1") return true;
+  if (normalized.startsWith("fc") || normalized.startsWith("fd")) return true; // unique local
+  if (normalized.startsWith("fe80:")) return true; // link-local
+  const mapped = /^:ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(normalized);
+  if (mapped?.[1] !== undefined) return isPrivateIPv4(mapped[1]);
+  return false;
+}
@@ -92,7 +92,18 @@ export function createSlashCommandRegistry(
          finishedAt: { not: null },
        },
        orderBy: { finishedAt: "asc" },
-        select: { model: true, provider: true, inputTokens: true, outputTokens: true, costUsd: true },
+        select: {
+          usageFacts: {
+            select: {
+              provider: true,
+              model: true,
+              inputTokens: true,
+              outputTokens: true,
+              costUsd: true,
+            },
+            orderBy: { occurredAt: "asc" },
+          },
+        },
      });
      await sendText(rt, chatId, formatUsageReport(runs, scope), sendOptions);
    },
@@ -118,18 +129,24 @@ async function currentRoleSessionIds(
  return sessions.map((session) => session.id);
 }

-interface UsageRun {
-  readonly model: string;
-  readonly provider: string;
-  readonly inputTokens: number | null;
-  readonly outputTokens: number | null;
-  readonly costUsd: unknown;
+interface UsageRunWithFacts {
+  readonly usageFacts: readonly {
+    readonly provider: string;
+    readonly model: string | null;
+    readonly inputTokens: number | null;
+    readonly outputTokens: number | null;
+    readonly costUsd: unknown;
+  }[];
 }

-function formatUsageReport(runs: readonly UsageRun[], scope: "current" | "project"): string {
+function formatUsageReport(runs: readonly UsageRunWithFacts[], scope: "current" | "project"): string {
  if (runs.length === 0) return `${scope === "current" ? "当前角色会话" : "当前项目"}还没有已结束的 Agent run。`;
+  // Bucket by (fact.provider, fact.model) — ADR-0026: external capabilities
+  // carry their own provider/model and contribute their own meter, so a run
+  // with a main loop + an external call lands in two buckets. A run with no
+  // cost-bearing fact is "unrecorded" (ADR-0022: missing cost ≠ zero).
  const buckets = new Map<string, {
-    provider: string; model: string; runs: number; inputTokens: number; outputTokens: number; costUsd: number;
+    provider: string; model: string; facts: number; inputTokens: number; outputTokens: number; costUsd: number;
  }>();
  let recordedRuns = 0;
  let unrecordedRuns = 0;
@@ -137,21 +154,34 @@ function formatUsageReport(runs: readonly UsageRun[], scope: "current" | "projec
  let totalOutputTokens = 0;
  let totalCostUsd = 0;
  for (const run of runs) {
-    const costUsd = decimalToNumberOrNull(run.costUsd);
-    if (costUsd === null) { unrecordedRuns++; continue; }
+    const facts = run.usageFacts;
+    if (facts.length === 0 || !facts.some((f) => f.costUsd !== null && f.costUsd !== undefined)) {
+      unrecordedRuns++;
+      // Tokens from unrecorded runs still count toward totals (matches pre-0026).
+      for (const f of facts) {
+        totalInputTokens += f.inputTokens ?? 0;
+        totalOutputTokens += f.outputTokens ?? 0;
+      }
+      continue;
+    }
    recordedRuns++;
-    const key = `${run.provider}\u0000${run.model}`;
-    const bucket = buckets.get(key) ?? {
-      provider: run.provider, model: run.model, runs: 0, inputTokens: 0, outputTokens: 0, costUsd: 0,
-    };
-    bucket.runs++;
-    bucket.inputTokens += run.inputTokens ?? 0;
-    bucket.outputTokens += run.outputTokens ?? 0;
-    bucket.costUsd += costUsd;
-    buckets.set(key, bucket);
-    totalInputTokens += run.inputTokens ?? 0;
-    totalOutputTokens += run.outputTokens ?? 0;
-    totalCostUsd += costUsd;
+    for (const f of facts) {
+      const costUsd = decimalToNumberOrNull(f.costUsd);
+      if (costUsd === null) continue;
+      const model = f.model ?? "(unknown model)";
+      const key = `${f.provider}\u0000${model}`;
+      const bucket = buckets.get(key) ?? {
+        provider: f.provider, model, facts: 0, inputTokens: 0, outputTokens: 0, costUsd: 0,
+      };
+      bucket.facts += 1;
+      bucket.inputTokens += f.inputTokens ?? 0;
+      bucket.outputTokens += f.outputTokens ?? 0;
+      bucket.costUsd += costUsd;
+      buckets.set(key, bucket);
+      totalInputTokens += f.inputTokens ?? 0;
+      totalOutputTokens += f.outputTokens ?? 0;
+      totalCostUsd += costUsd;
+    }
  }
  const lines = [
    `${scope === "current" ? "当前角色会话" : "当前项目"}用量`,
@@ -160,7 +190,7 @@ function formatUsageReport(runs: readonly UsageRun[], scope: "current" | "projec
  ];
  if (unrecordedRuns > 0) lines.push(`另有 ${formatInteger(unrecordedRuns)} 个 run 未记录成本。`);
  for (const bucket of buckets.values()) {
-    lines.push(`- ${bucket.provider} / ${bucket.model}: ${formatInteger(bucket.runs)} runs, ${formatUsd(bucket.costUsd)}`);
+    lines.push(`- ${bucket.provider} / ${bucket.model}: ${formatInteger(bucket.facts)} 次, ${formatUsd(bucket.costUsd)}`);
  }
  return lines.join("\n");
 }
@@ -14,6 +14,7 @@ import { join } from "node:path";
 import type { Prisma, PrismaClient } from "@prisma/client";
 import { z } from "zod";
 import type { FastifyBaseLogger } from "fastify";
+import type { LocalSecretEnvelope } from "../security/secretEnvelope.js";
 import {
  sendText,
  sendTextMessage,
@@ -93,6 +94,7 @@ interface TriggerDeps {
  readonly prisma: PrismaClient;
  readonly settings: RuntimeSettings;
  readonly logger: FastifyBaseLogger;
+  readonly secretEnvelope: LocalSecretEnvelope;
  readonly runAgent?: (req: RunRequest) => Promise<RunResult>;
  readonly authorizer?: PermissionAuthorizer | undefined;
  readonly messageBatcherOptions?: MessageBatcherOptions | undefined;
@@ -486,6 +488,7 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
    // Streaming agent card: single interactive card through the full run
    // lifecycle (thinking → tool calls → streaming text → complete).
    // Shows tool-use trace panel + reasoning panel + answer text.
+    const deliveredFiles: string[] = [];
    const card = new StreamingAgentCard({
      runId: run.id,
      rt,
@@ -493,12 +496,15 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
      sendOptions,
      patchIntervalMs: undefined,
      maxMessageLength: undefined,
+      workspaceRoot: projectWorkspaceRoot,
+      workspaceDir: project.workspaceDir,
+      maxImageBytes: deps.resourceLimits?.maxBytesPerFile,
    });
-    const deliveredFiles: string[] = [];
    const fileDeliveryMcpServer = createFileDeliveryMcpServer({
      rt,
      chatId,
      projectId,
+      organizationId: siloOrganizationId,
      runId: run.id,
      workspaceRoot: projectWorkspaceRoot,
      workspaceDir: project.workspaceDir,
@@ -506,6 +512,8 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
      sendOptions,
      approvalManager,
      tools: cphHubMcpToolsForRole(roleTools),
+      prisma: deps.prisma,
+      secretEnvelope: deps.secretEnvelope,
      onDelivered: (path) => {
        deliveredFiles.push(path);
      },
@@ -604,6 +612,32 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
            data: { metadata: mergeSessionMetadata(session.metadata, metadataPatch) },
          });
        }
+        // ADR-0026: the UsageFact ledger is the truth; AgentRun.costUsd /
+        // inputTokens / outputTokens are a derived rollup cache for existing
+        // readers. We write the fact first, then mirror it onto the run.
+        // They are separate statements (not one transaction) so the AgentRun
+        // row lock is held for the shortest possible window and concurrent
+        // workspace teardown cannot deadlock on the FK ShareLock. A crash
+        // between the two leaves the cache stale, but the cache is derived
+        // (the usage service re-reads facts), so staleness is recoverable;
+        // the reverse order would lose the truth and is unrecoverable.
+        const finishedAt = new Date();
+        const reportedCost = result.costUsd;
+        const costSource = reportedCost !== undefined ? "provider_reported" : "unknown";
+        await deps.prisma.usageFact.create({
+          data: {
+            runId: run.id,
+            occurredAt: finishedAt,
+            kind: "model_completion",
+            provider: providerId,
+            model,
+            inputTokens: result.usage.inputTokens,
+            outputTokens: result.usage.outputTokens,
+            costUsd: reportedCost ?? null,
+            costSource,
+            metadata: {},
+          },
+        });
        await deps.prisma.agentRun.update({
          where: { id: run.id },
          data: {
@@ -618,9 +652,10 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
                    : "FAILED",
            inputTokens: result.usage.inputTokens,
            outputTokens: result.usage.outputTokens,
-            ...(result.costUsd !== undefined ? { costUsd: result.costUsd, costSource: "provider_reported" } : {}),
+            costUsd: reportedCost ?? null,
+            costSource,
            error: result.error ?? null,
-            finishedAt: new Date(),
+            finishedAt,
          },
        });
        await writeAudit(deps.prisma, {
@@ -162,6 +162,7 @@ export async function startHub(): Promise<void> {
      prisma,
      settings: runtimeSettings,
      logger: app.log,
+      secretEnvelope,
      projectWorkspaceRoot,
      publicBaseUrl,
      siloOrganizationId: siloOrganization.id,
@@ -1,9 +1,9 @@
 /**
- * Org capacity policy service (ADR-0022 / spec `Spec.System.Capacity`).
+ * Org capacity policy service (ADR-0022).
 *
 * Stores per-Organization lower `organizationLimit` overrides per
- * `CapacityDimension`. Enforces `LayeredLimit.Valid`: a set limit must be ≤ the
- * platform ceiling for that dimension. `LayeredLimit.effective` (min of the two)
+ * `CapacityDimension`. Enforces the layered-limit invariant: a set limit must be ≤ the
+ * platform ceiling for that dimension. The effective limit (min of the two)
 * is the value capacity admission should use; dimensions with no org override
 * fall back to the platform ceiling.
 */
@@ -1,7 +1,7 @@
 /**
 * Organization membership management for org admin (ADR-0021).
 *
- * Role rules (product pin, not yet in Lean):
+ * Role rules (product pin, not yet recorded in an ADR):
 * 1. Actor must be OWNER or ADMIN (enforced at HTTP layer).
 * 2. Only OWNER can grant/revoke OWNER or modify another OWNER.
 * 3. Cannot revoke or demote the last remaining OWNER.
@@ -73,9 +73,28 @@ export async function getSessionDetail(
          inputTokens: true,
          outputTokens: true,
          costUsd: true,
+          costSource: true,
          startedAt: true,
          finishedAt: true,
          error: true,
+          usageFacts: {
+            select: {
+              id: true,
+              occurredAt: true,
+              kind: true,
+              provider: true,
+              model: true,
+              inputTokens: true,
+              outputTokens: true,
+              quantity: true,
+              unit: true,
+              costUsd: true,
+              costSource: true,
+              capabilityId: true,
+              correlationId: true,
+            },
+            orderBy: { occurredAt: "asc" },
+          },
        },
        orderBy: { startedAt: "desc" },
        take: 100,
@@ -106,9 +125,25 @@ export async function getSessionDetail(
      inputTokens: r.inputTokens,
      outputTokens: r.outputTokens,
      costUsd: r.costUsd === null ? null : Number(r.costUsd),
+      costSource: r.costSource,
      startedAt: r.startedAt.toISOString(),
      finishedAt: r.finishedAt?.toISOString() ?? null,
      error: r.error,
+      usageFacts: r.usageFacts.map((f) => ({
+        id: f.id,
+        occurredAt: f.occurredAt.toISOString(),
+        kind: f.kind,
+        provider: f.provider,
+        model: f.model,
+        inputTokens: f.inputTokens,
+        outputTokens: f.outputTokens,
+        quantity: f.quantity === null ? null : Number(f.quantity),
+        unit: f.unit,
+        costUsd: f.costUsd === null ? null : Number(f.costUsd),
+        costSource: f.costSource,
+        capabilityId: f.capabilityId,
+        correlationId: f.correlationId,
+      })),
    })),
  };
 }
@@ -1,15 +1,22 @@
 /**
- * Org / project usage rollups from AgentRun cost facts (ADR-0021).
+ * Org / project usage rollups from the UsageFact ledger (ADR-0021, ADR-0026).
 * Operational usage accounting, not payment collection. Organizations may use
 * either their own provider credentials or a distinct platform-managed
 * connection; commercial billing remains outside the pilot scope.
+ *
+ * The truth is in `UsageFact`; `AgentRun.costUsd / inputTokens / outputTokens`
+ * are a derived rollup cache. This service reads `UsageFact` directly so that
+ * external-capability consumption (PDF→MD, ASR, …) is attributed correctly,
+ * not just the main model loop. A run with no cost-bearing fact is
+ * `runsWithoutCost` — ADR-0022: missing cost ≠ zero.
+ *
+ * Breakdown buckets keep kind / provider / model / capability / unit, so the
+ * admin UI can separate model tokens from non-token external meters instead of
+ * collapsing everything into a single input/output token total.
 */
 import type { Prisma, PrismaClient } from "@prisma/client";

-export interface ProjectUsageRow {
-  readonly projectId: string;
-  readonly projectName: string;
-  readonly folderId: string | null;
+export interface UsageTotals {
  readonly runCount: number;
  readonly runsWithCost: number;
  readonly runsWithoutCost: number;
@@ -18,17 +25,264 @@ export interface ProjectUsageRow {
  readonly costUsd: number | null;
 }

+export interface ProjectUsageRow extends UsageTotals {
+  readonly projectId: string;
+  readonly projectName: string;
+  readonly folderId: string | null;
+}
+
+/** One ledger slice: kind + provider + model + capability + unit. */
+export interface UsageBreakdownRow {
+  readonly kind: string;
+  readonly provider: string;
+  readonly model: string | null;
+  readonly capabilityId: string | null;
+  readonly unit: string | null;
+  readonly factCount: number;
+  readonly factsWithCost: number;
+  readonly factsWithoutCost: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  /** Sum of quantity when unit is non-null; null when this bucket is token-only. */
+  readonly quantity: number | null;
+  readonly costUsd: number | null;
+}
+
 export interface UsageReport {
  readonly from: string | null;
  readonly to: string | null;
  readonly projects: readonly ProjectUsageRow[];
-  readonly totals: {
-    readonly runCount: number;
-    readonly runsWithCost: number;
-    readonly runsWithoutCost: number;
-    readonly inputTokens: number;
-    readonly outputTokens: number;
-    readonly costUsd: number | null;
+  readonly totals: UsageTotals;
+  readonly breakdown: readonly UsageBreakdownRow[];
+}
+
+export interface ProjectUsageReport extends ProjectUsageRow {
+  readonly from: string | null;
+  readonly to: string | null;
+  readonly breakdown: readonly UsageBreakdownRow[];
+}
+
+type FactRow = {
+  readonly kind: string;
+  readonly provider: string;
+  readonly model: string | null;
+  readonly capabilityId: string | null;
+  readonly unit: string | null;
+  readonly quantity: unknown;
+  readonly inputTokens: number | null;
+  readonly outputTokens: number | null;
+  readonly costUsd: unknown;
+};
+
+type RunWithFacts = {
+  readonly projectId: string;
+  readonly usageFacts: readonly FactRow[];
+};
+
+type MutableTotals = {
+  runCount: number;
+  runsWithCost: number;
+  runsWithoutCost: number;
+  inputTokens: number;
+  outputTokens: number;
+  costUsd: number | null;
+};
+
+type MutableBreakdown = {
+  kind: string;
+  provider: string;
+  model: string | null;
+  capabilityId: string | null;
+  unit: string | null;
+  factCount: number;
+  factsWithCost: number;
+  factsWithoutCost: number;
+  inputTokens: number;
+  outputTokens: number;
+  quantity: number | null;
+  costUsd: number | null;
+};
+
+type MutableProjectRow = MutableTotals & {
+  readonly projectId: string;
+  readonly projectName: string;
+  readonly folderId: string | null;
+};
+
+const FACT_SELECT = {
+  kind: true,
+  provider: true,
+  model: true,
+  capabilityId: true,
+  unit: true,
+  quantity: true,
+  inputTokens: true,
+  outputTokens: true,
+  costUsd: true,
+} as const;
+
+function factCostUsdToNumber(value: unknown): number | null {
+  if (value === null || value === undefined) return null;
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function factQuantityToNumber(value: unknown): number | null {
+  if (value === null || value === undefined) return null;
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function breakdownKey(f: FactRow): string {
+  return [
+    f.kind,
+    f.provider,
+    f.model ?? "",
+    f.capabilityId ?? "",
+    f.unit ?? "",
+  ].join("\u0000");
+}
+
+function emptyMutableTotals(): MutableTotals {
+  return {
+    runCount: 0,
+    runsWithCost: 0,
+    runsWithoutCost: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    costUsd: null,
+  };
+}
+
+function addCost(existing: number | null, add: number): number {
+  return (existing ?? 0) + add;
+}
+
+function rollupRunTokensAndCost(facts: readonly FactRow[]): {
+  readonly hasCost: boolean;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly costUsd: number | null;
+} {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let costUsd: number | null = null;
+  let hasCost = false;
+  for (const f of facts) {
+    inputTokens += f.inputTokens ?? 0;
+    outputTokens += f.outputTokens ?? 0;
+    const c = factCostUsdToNumber(f.costUsd);
+    if (c !== null) {
+      hasCost = true;
+      costUsd = addCost(costUsd, c);
+    }
+  }
+  return { hasCost, inputTokens, outputTokens, costUsd };
+}
+
+function accumulateBreakdown(
+  buckets: Map<string, MutableBreakdown>,
+  facts: readonly FactRow[],
+): void {
+  for (const f of facts) {
+    const key = breakdownKey(f);
+    let bucket = buckets.get(key);
+    if (bucket === undefined) {
+      bucket = {
+        kind: f.kind,
+        provider: f.provider,
+        model: f.model,
+        capabilityId: f.capabilityId,
+        unit: f.unit,
+        factCount: 0,
+        factsWithCost: 0,
+        factsWithoutCost: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        quantity: null,
+        costUsd: null,
+      };
+      buckets.set(key, bucket);
+    }
+    bucket.factCount += 1;
+    bucket.inputTokens += f.inputTokens ?? 0;
+    bucket.outputTokens += f.outputTokens ?? 0;
+    const qty = factQuantityToNumber(f.quantity);
+    if (qty !== null) {
+      bucket.quantity = (bucket.quantity ?? 0) + qty;
+    }
+    const c = factCostUsdToNumber(f.costUsd);
+    if (c !== null) {
+      bucket.factsWithCost += 1;
+      bucket.costUsd = addCost(bucket.costUsd, c);
+    } else {
+      bucket.factsWithoutCost += 1;
+    }
+  }
+}
+
+function freezeBreakdown(buckets: Map<string, MutableBreakdown>): UsageBreakdownRow[] {
+  return [...buckets.values()]
+    .map((b) => ({
+      kind: b.kind,
+      provider: b.provider,
+      model: b.model,
+      capabilityId: b.capabilityId,
+      unit: b.unit,
+      factCount: b.factCount,
+      factsWithCost: b.factsWithCost,
+      factsWithoutCost: b.factsWithoutCost,
+      inputTokens: b.inputTokens,
+      outputTokens: b.outputTokens,
+      quantity: b.quantity,
+      costUsd: b.costUsd,
+    }))
+    .sort((a, b) => {
+      const kindCmp = a.kind.localeCompare(b.kind);
+      if (kindCmp !== 0) return kindCmp;
+      const provCmp = a.provider.localeCompare(b.provider);
+      if (provCmp !== 0) return provCmp;
+      const capA = a.capabilityId ?? "";
+      const capB = b.capabilityId ?? "";
+      const capCmp = capA.localeCompare(capB);
+      if (capCmp !== 0) return capCmp;
+      const modelA = a.model ?? "";
+      const modelB = b.model ?? "";
+      return modelA.localeCompare(modelB);
+    });
+}
+
+function freezeTotals(t: MutableTotals): UsageTotals {
+  return {
+    runCount: t.runCount,
+    runsWithCost: t.runsWithCost,
+    runsWithoutCost: t.runsWithoutCost,
+    inputTokens: t.inputTokens,
+    outputTokens: t.outputTokens,
+    costUsd: t.costUsd,
+  };
+}
+
+function applyRunToTotals(totals: MutableTotals, facts: readonly FactRow[]): void {
+  const roll = rollupRunTokensAndCost(facts);
+  totals.runCount += 1;
+  if (roll.hasCost) {
+    totals.runsWithCost += 1;
+    totals.costUsd = addCost(totals.costUsd, roll.costUsd ?? 0);
+  } else {
+    totals.runsWithoutCost += 1;
+  }
+  totals.inputTokens += roll.inputTokens;
+  totals.outputTokens += roll.outputTokens;
+}
+
+function emptyReport(from?: Date, to?: Date): UsageReport {
+  return {
+    from: from?.toISOString() ?? null,
+    to: to?.toISOString() ?? null,
+    projects: [],
+    totals: freezeTotals(emptyMutableTotals()),
+    breakdown: [],
  };
 }

@@ -54,85 +308,66 @@ export async function getOrgUsage(
    return emptyReport(input.from, input.to);
  }

-  const runWhere: Prisma.AgentRunWhereInput = {
-    projectId: { in: projects.map((p) => p.id) },
-    ...(input.from !== undefined || input.to !== undefined
-      ? {
-          startedAt: {
-            ...(input.from !== undefined ? { gte: input.from } : {}),
-            ...(input.to !== undefined ? { lte: input.to } : {}),
-          },
-        }
-      : {}),
-  };
-
+  const projectIds = projects.map((p) => p.id);
+  // Date range filters by run.startedAt, matching the pre-ADR-0026 semantics:
+  // a run is in or out of the window based on when it started, and all of its
+  // facts come along. Filtering facts by occurredAt independently would let a
+  // run contribute partial cost to a window it doesn't belong to.
  const runs = await prisma.agentRun.findMany({
-    where: runWhere,
+    where: {
+      projectId: { in: projectIds },
+      ...(input.from !== undefined || input.to !== undefined
+        ? {
+            startedAt: {
+              ...(input.from !== undefined ? { gte: input.from } : {}),
+              ...(input.to !== undefined ? { lte: input.to } : {}),
+            },
+          }
+        : {}),
+    },
    select: {
      projectId: true,
-      inputTokens: true,
-      outputTokens: true,
-      costUsd: true,
+      usageFacts: {
+        select: FACT_SELECT,
+        orderBy: { occurredAt: "asc" },
+      },
    },
  });

-  type MutableRow = {
-    projectId: string;
-    projectName: string;
-    folderId: string | null;
-    runCount: number;
-    runsWithCost: number;
-    runsWithoutCost: number;
-    inputTokens: number;
-    outputTokens: number;
-    costUsd: number | null;
-  };
-
-  const byProject = new Map<string, MutableRow>();
+  const byProject = new Map<string, MutableProjectRow>();
  for (const p of projects) {
    byProject.set(p.id, {
      projectId: p.id,
      projectName: p.name,
      folderId: p.folderId,
-      runCount: 0,
-      runsWithCost: 0,
-      runsWithoutCost: 0,
-      inputTokens: 0,
-      outputTokens: 0,
-      costUsd: null,
+      ...emptyMutableTotals(),
    });
  }

-  for (const run of runs) {
+  const breakdownBuckets = new Map<string, MutableBreakdown>();
+  for (const run of runs as readonly RunWithFacts[]) {
    const row = byProject.get(run.projectId);
    if (row === undefined) continue;
-    row.runCount += 1;
-    row.inputTokens += run.inputTokens ?? 0;
-    row.outputTokens += run.outputTokens ?? 0;
-    if (run.costUsd === null) {
-      row.runsWithoutCost += 1;
-    } else {
-      row.runsWithCost += 1;
-      const cost = Number(run.costUsd);
-      row.costUsd = (row.costUsd ?? 0) + cost;
-    }
+    applyRunToTotals(row, run.usageFacts);
+    accumulateBreakdown(breakdownBuckets, run.usageFacts);
  }

-  const projectsOut: ProjectUsageRow[] = [...byProject.values()];
-  let runCount = 0;
-  let runsWithCost = 0;
-  let runsWithoutCost = 0;
-  let inputTokens = 0;
-  let outputTokens = 0;
-  let costUsd: number | null = null;
+  const projectsOut: ProjectUsageRow[] = [...byProject.values()].map((r) => ({
+    projectId: r.projectId,
+    projectName: r.projectName,
+    folderId: r.folderId,
+    ...freezeTotals(r),
+  }));
+
+  const totals = emptyMutableTotals();
  for (const row of projectsOut) {
-    runCount += row.runCount;
-    runsWithCost += row.runsWithCost;
-    runsWithoutCost += row.runsWithoutCost;
-    inputTokens += row.inputTokens;
-    outputTokens += row.outputTokens;
+    totals.runCount += row.runCount;
+    totals.runsWithCost += row.runsWithCost;
+    totals.runsWithoutCost += row.runsWithoutCost;
+    totals.inputTokens += row.inputTokens;
+    totals.outputTokens += row.outputTokens;
    if (row.costUsd !== null) {
-      costUsd = (costUsd ?? 0) + row.costUsd;
+      totals.costUsd = addCost(totals.costUsd, row.costUsd);
    }
  }

@@ -140,14 +375,8 @@ export async function getOrgUsage(
    from: input.from?.toISOString() ?? null,
    to: input.to?.toISOString() ?? null,
    projects: projectsOut,
-    totals: {
-      runCount,
-      runsWithCost,
-      runsWithoutCost,
-      inputTokens,
-      outputTokens,
-      costUsd,
-    },
+    totals: freezeTotals(totals),
+    breakdown: freezeBreakdown(breakdownBuckets),
  };
 }

@@ -159,7 +388,7 @@ export async function getProjectUsage(
    readonly from?: Date | undefined;
    readonly to?: Date | undefined;
  },
-): Promise<ProjectUsageRow> {
+): Promise<ProjectUsageReport> {
  const project = await prisma.project.findFirst({
    where: { id: input.projectId, organizationId: input.organizationId },
    select: { id: true, name: true, folderId: true },
@@ -167,39 +396,41 @@ export async function getProjectUsage(
  if (project === null) {
    throw new Error(`project not found: ${input.projectId}`);
  }
-  const report = await getOrgUsage(prisma, {
-    organizationId: input.organizationId,
-    from: input.from,
-    to: input.to,
-  });
-  const row = report.projects.find((p) => p.projectId === project.id);
-  return (
-    row ?? {
-      projectId: project.id,
-      projectName: project.name,
-      folderId: project.folderId,
-      runCount: 0,
-      runsWithCost: 0,
-      runsWithoutCost: 0,
-      inputTokens: 0,
-      outputTokens: 0,
-      costUsd: null,
-    }
-  );
-}

-function emptyReport(from?: Date, to?: Date): UsageReport {
-  return {
-    from: from?.toISOString() ?? null,
-    to: to?.toISOString() ?? null,
-    projects: [],
-    totals: {
-      runCount: 0,
-      runsWithCost: 0,
-      runsWithoutCost: 0,
-      inputTokens: 0,
-      outputTokens: 0,
-      costUsd: null,
+  const runs = await prisma.agentRun.findMany({
+    where: {
+      projectId: project.id,
+      ...(input.from !== undefined || input.to !== undefined
+        ? {
+            startedAt: {
+              ...(input.from !== undefined ? { gte: input.from } : {}),
+              ...(input.to !== undefined ? { lte: input.to } : {}),
+            },
+          }
+        : {}),
    },
+    select: {
+      usageFacts: {
+        select: FACT_SELECT,
+        orderBy: { occurredAt: "asc" },
+      },
+    },
+  });
+
+  const totals = emptyMutableTotals();
+  const breakdownBuckets = new Map<string, MutableBreakdown>();
+  for (const run of runs) {
+    applyRunToTotals(totals, run.usageFacts as readonly FactRow[]);
+    accumulateBreakdown(breakdownBuckets, run.usageFacts as readonly FactRow[]);
+  }
+
+  return {
+    projectId: project.id,
+    projectName: project.name,
+    folderId: project.folderId,
+    ...freezeTotals(totals),
+    from: input.from?.toISOString() ?? null,
+    to: input.to?.toISOString() ?? null,
+    breakdown: freezeBreakdown(breakdownBuckets),
  };
 }
@@ -558,6 +558,26 @@ async function ensureInboxFolder(prisma: Prisma.TransactionClient, organizationI
    select: { id: true },
  });
  if (existing !== null) return existing;
+
+  // Bootstrap once created a root "Inbox" without kind=SYSTEM_INBOX. Sibling-name
+  // uniqueness then makes a second create fail. Recover by promoting that row.
+  const legacyRootInbox = await prisma.folder.findFirst({
+    where: {
+      organizationId,
+      parentId: null,
+      name: "Inbox",
+      archivedAt: null,
+    },
+    select: { id: true },
+  });
+  if (legacyRootInbox !== null) {
+    return prisma.folder.update({
+      where: { id: legacyRootInbox.id },
+      data: { kind: "SYSTEM_INBOX" },
+      select: { id: true },
+    });
+  }
+
  return prisma.folder.create({
    data: { organizationId, name: "Inbox", kind: "SYSTEM_INBOX", sortKey: "000000" },
    select: { id: true },
@@ -182,12 +182,16 @@ export class DatabaseRuntimeSettings implements RuntimeSettings {
      throw new Error(`organization ${project.organization.id} must have exactly one active default Agent role`);
    }

+    // The model list is the env-based fallback used when a role has no
+    // explicit defaultModel. Role defaultModels are chosen from the provider
+    // model catalog (admin surface) and may not be in the env list — we don't
+    // validate against it at runtime; the admin already validated by selection.
    const defaults = await this.envSettings.modelRegistry(scope);
-    const enabledModels = new Set(defaults.listModels().map((model) => model.id));
+    const fallbackModels = defaults.listModels();
    const roles: RoleEntry[] = project.organization.agentRoles.map((role) => ({
      id: role.roleId,
      label: role.label,
-      defaultModel: validateRoleModel(role.roleId, role.defaultModel, enabledModels),
+      defaultModel: role.defaultModel ?? undefined,
      ...(role.systemPrompt !== null ? { systemPrompt: role.systemPrompt } : {}),
      ...(role.tools !== null ? { tools: roleToolsFromJson(role.roleId, role.tools) } : {}),
      skills: role.skillBindings.map((binding): RoleSkillEntry => {
@@ -210,7 +214,7 @@ export class DatabaseRuntimeSettings implements RuntimeSettings {
        };
      }),
    }));
-    return new InMemoryModelRegistry(defaults.listModels(), roles);
+    return new InMemoryModelRegistry(fallbackModels, roles);
  }

  runPolicy(input: RunPolicyInput): Promise<RunPolicy> {
@@ -225,15 +229,6 @@ function roleToolsFromJson(roleId: string, value: Prisma.JsonValue): readonly st
  return value as string[];
 }

-function validateRoleModel(
-  roleId: string,
-  model: string | null,
-  enabledModels: ReadonlySet<string>,
-): string | undefined {
-  if (model === null) return undefined;
-  if (!enabledModels.has(model)) throw new Error(`role ${roleId} selects unavailable model ${model}`);
-  return model;
-}

 async function loadActiveProviderSecret(
  tx: Prisma.TransactionClient,
@@ -170,7 +170,7 @@ describe("admin auth + org API guards", () => {
    try {
      const res = await app.inject({
        method: "GET",
-        url: "/auth/feishu?returnTo=/admin/org/test-default",
+        url: "/auth/feishu?returnTo=/admin",
      });
      expect(res.statusCode).toBe(302);
      const location = res.headers.location;
@@ -233,7 +233,7 @@ describe("admin auth + org API guards", () => {
    try {
      const nonce = "nonce-test-1";
      const state = signOAuthState(
-        { nonce, returnTo: "/admin/org/test-default" },
+        { nonce, returnTo: "/admin" },
        SESSION_SECRET,
      );
      const res = await app.inject({
@@ -242,7 +242,7 @@ describe("admin auth + org API guards", () => {
        headers: { cookie: `${OAUTH_STATE_COOKIE_NAME}=${nonce}` },
      });
      expect(res.statusCode).toBe(302);
-      expect(res.headers.location).toBe("/admin/org/test-default");
+      expect(res.headers.location).toBe("/admin");
      expect(JSON.stringify(res.headers["set-cookie"])).toContain("cph_session=");

      const user = await prisma.user.findUnique({ where: { feishuOpenId: "ou_new" } });
@@ -293,7 +293,7 @@ describe("admin auth + org API guards", () => {
    try {
      const start = await app.inject({
        method: "GET",
-        url: "/auth/feishu/test-default?returnTo=/admin/org/test-default/settings",
+        url: "/auth/feishu/test-default?returnTo=/admin/settings",
      });
      expect(start.statusCode).toBe(302);
      const authorize = new URL(String(start.headers.location));
@@ -308,7 +308,7 @@ describe("admin auth + org API guards", () => {
        headers: { cookie: nonceCookie },
      });
      expect(callback.statusCode).toBe(302);
-      expect(callback.headers.location).toBe("/admin/org/test-default/settings");
+      expect(callback.headers.location).toBe("/admin/settings");
      const sessionCookie = cookiePair(callback.headers["set-cookie"], "cph_session");
      const me = await app.inject({ method: "GET", url: "/api/me", headers: { cookie: sessionCookie } });
      expect(me.statusCode).toBe(200);
@@ -346,7 +346,7 @@ describe("admin auth + org API guards", () => {
        headers: { cookie: cookiePair(defaultStart.headers["set-cookie"], OAUTH_STATE_COOKIE_NAME) },
      });
      expect(defaultCallback.statusCode).toBe(302);
-      expect(defaultCallback.headers.location).toBe("/admin/org/test-default");
+      expect(defaultCallback.headers.location).toBe("/admin");

      await connections.disable({ organizationId: DEFAULT_ORG_ID, actorUserId: "scoped-owner" });
      const revoked = await app.inject({ method: "GET", url: "/api/me", headers: { cookie: sessionCookie } });
@@ -0,0 +1,285 @@
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { prisma, resetDb, seedTestOrganization, testSecretEnvelope, DEFAULT_ORG_ID } from "./helpers.js";
+import { createPdfToMdBundleAdapter, CapabilityPathEscape } from "../../src/capability/pdfToMdBundle.js";
+import { DocmindClientError, type CapabilityProviderClient, type DocmindParseResult } from "../../src/capability/docmindClient.js";
+import type { CapabilitySecretPayload } from "../../src/capability/types.js";
+
+const CAPABILITY_ID = "pdf_to_md_bundle";
+const PROVIDER_ID = "aliyun_docmind";
+
+/**
+ * ADR-0027: pdf_to_md_bundle adapter contract tests. Proves:
+ *   - workspace containment (input + output confined to run workspace)
+ *   - fail-closed credential resolution (no ACTIVE connection → error)
+ *   - UsageFact attribution with non-token meter (pages), costSource rules
+ *   - outputs (md + images) written into workspace
+ *   - docmind client errors propagate
+ * The client is mocked; the prisma + envelope + filesystem are real.
+ */
+describe("pdf_to_md_bundle capability adapter (ADR-0027)", () => {
+  let workspaceRoot: string;
+  let runId: string;
+
+  beforeEach(async () => {
+    await resetDb();
+    await seedTestOrganization();
+    workspaceRoot = await mkdtemp(join(tmpdir(), "cph-cap-"));
+    runId = "run-cap-test";
+    // AgentRun is required for the UsageFact FK.
+    await prisma.project.create({
+      data: {
+        id: "proj-cap",
+        organizationId: DEFAULT_ORG_ID,
+        name: "Cap Test",
+        workspaceDir: workspaceRoot,
+      },
+    });
+    await prisma.agentRun.create({
+      data: {
+        id: runId,
+        projectId: "proj-cap",
+        entrypoint: "FEISHU",
+        provider: "openrouter",
+        model: "mock-model",
+        status: "ACTIVE",
+        prompt: "convert this pdf",
+        metadata: {},
+      },
+    });
+  });
+
+  afterEach(async () => {
+    await rm(workspaceRoot, { recursive: true, force: true }).catch(() => {});
+  });
+
+  async function seedActiveCapabilityConnection(): Promise<void> {
+    const payload: CapabilitySecretPayload = {
+      schemaVersion: 1,
+      accessKeyId: "LTAI-test-key-id",
+      accessKeySecret: "test-secret-never-log",
+      endpoint: "docmind-api.cn-hangzhou.aliyuncs.com",
+    };
+    const connection = await prisma.organizationCapabilityConnection.create({
+      data: {
+        id: "cap-conn-1",
+        organizationId: DEFAULT_ORG_ID,
+        capabilityId: CAPABILITY_ID,
+        status: "ACTIVE",
+        activatedAt: new Date(),
+      },
+    });
+    const envelope = testSecretEnvelope.encryptJson(
+      {
+        purpose: "capability",
+        organizationId: DEFAULT_ORG_ID,
+        connectionId: connection.id,
+        secretVersionId: "cap-sv-1",
+      },
+      payload,
+    );
+    await prisma.capabilityCredentialVersion.create({
+      data: {
+        id: "cap-sv-1",
+        connectionId: connection.id,
+        version: 1,
+        envelope: envelope as object,
+        keyId: envelope.keyId,
+      },
+    });
+    await prisma.organizationCapabilityConnection.update({
+      where: { id: connection.id },
+      data: { activeSecretVersionId: "cap-sv-1" },
+    });
+  }
+
+  function mockDocmindClient(result: Partial<DocmindParseResult> = {}): CapabilityProviderClient {
+    const full: DocmindParseResult = {
+      markdown: "# Parsed Document\n\nHello world.\n\n![fig](page_1.jpg)\n",
+      images: [
+        { filename: "page_1.jpg", data: new Uint8Array([0xff, 0xd8, 0xff, 0xe0]) },
+      ],
+      pageCount: 3,
+      costUsd: 0.0168,
+      requestId: "docmind-job-abc",
+      ...result,
+    };
+    return {
+      parse: vi.fn(async (): Promise<DocmindParseResult> => full),
+    };
+  }
+
+  function makeAdapter(client: CapabilityProviderClient) {
+    return createPdfToMdBundleAdapter({
+      secrets: testSecretEnvelope,
+      client,
+      prisma,
+    });
+  }
+
+  async function seedInputPdf(name: string = "input.pdf"): Promise<string> {
+    const dir = join(workspaceRoot, "sources");
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, name);
+    await writeFile(path, "%PDF-1.4 fake pdf bytes");
+    return join("sources", name);
+  }
+
+  it("writes md + images into the workspace and records a UsageFact", async () => {
+    await seedActiveCapabilityConnection();
+    const inputPath = await seedInputPdf();
+    const client = mockDocmindClient();
+    const adapter = makeAdapter(client);
+
+    const result = await adapter.invoke({
+      runId,
+      organizationId: DEFAULT_ORG_ID,
+      projectId: "proj-cap",
+      workspaceDir: workspaceRoot,
+      inputPath,
+      outputDir: "output",
+      prisma,
+    });
+
+    // Outputs landed in workspace.
+    const md = await readFile(join(workspaceRoot, "output", "document.md"), "utf8");
+    expect(md).toContain("# Parsed Document");
+    expect(result.artifacts.some((a) => a.kind === "markdown" && a.path === "output/document.md")).toBe(true);
+    expect(result.artifacts.some((a) => a.kind === "image" && a.path === "output/page_1.jpg")).toBe(true);
+
+    // Client received the decrypted credential, not the env.
+    const call = (client.parse as ReturnType<typeof vi.fn>).mock.calls[0]?.[0] as CapabilitySecretPayload;
+    expect(call.accessKeyId).toBe("LTAI-test-key-id");
+    expect(call.endpoint).toBe("docmind-api.cn-hangzhou.aliyuncs.com");
+
+    // UsageFact written with non-token meter and provider_reported cost.
+    const facts = await prisma.usageFact.findMany({ where: { runId } });
+    expect(facts).toHaveLength(1);
+    const fact = facts[0]!;
+    expect(fact.kind).toBe("external_capability");
+    expect(fact.provider).toBe(PROVIDER_ID);
+    expect(fact.capabilityId).toBe(CAPABILITY_ID);
+    expect(Number(fact.quantity)).toBe(3);
+    expect(fact.unit).toBe("pages");
+    expect(Number(fact.costUsd!)).toBeCloseTo(0.0168, 8);
+    expect(fact.costSource).toBe("provider_reported");
+    expect(fact.correlationId).toBe("docmind-job-abc");
+  });
+
+  it("writes UsageFact with costSource=unknown when docmind reports no cost", async () => {
+    await seedActiveCapabilityConnection();
+    const inputPath = await seedInputPdf();
+    const client = mockDocmindClient({ costUsd: null, requestId: null });
+    const adapter = makeAdapter(client);
+
+    await adapter.invoke({
+      runId,
+      organizationId: DEFAULT_ORG_ID,
+      projectId: "proj-cap",
+      workspaceDir: workspaceRoot,
+      inputPath,
+      outputDir: "output",
+      prisma,
+    });
+
+    const fact = (await prisma.usageFact.findFirstOrThrow({ where: { runId } }));
+    expect(fact.costUsd).toBeNull();
+    expect(fact.costSource).toBe("unknown");
+    // quantity still recorded — missing cost ≠ zero consumption (ADR-0022).
+    expect(Number(fact.quantity)).toBe(3);
+  });
+
+  it("fails closed when the org has no ACTIVE capability connection", async () => {
+    // No connection seeded.
+    const inputPath = await seedInputPdf();
+    const adapter = makeAdapter(mockDocmindClient());
+
+    await expect(adapter.invoke({
+      runId,
+      organizationId: DEFAULT_ORG_ID,
+      projectId: "proj-cap",
+      workspaceDir: workspaceRoot,
+      inputPath,
+      outputDir: "output",
+      prisma,
+    })).rejects.toThrow(/no ACTIVE capability connection/);
+
+    // No UsageFact written for a failed resolution.
+    const facts = await prisma.usageFact.findMany({ where: { runId } });
+    expect(facts).toHaveLength(0);
+  });
+
+  it("rejects an input path that escapes the workspace", async () => {
+    await seedActiveCapabilityConnection();
+    const adapter = makeAdapter(mockDocmindClient());
+
+    await expect(adapter.invoke({
+      runId,
+      organizationId: DEFAULT_ORG_ID,
+      projectId: "proj-cap",
+      workspaceDir: workspaceRoot,
+      inputPath: "../../../etc/passwd",
+      outputDir: "output",
+      prisma,
+    })).rejects.toBeInstanceOf(CapabilityPathEscape);
+  });
+
+  it("rejects an output path that escapes the workspace", async () => {
+    await seedActiveCapabilityConnection();
+    const inputPath = await seedInputPdf();
+    const adapter = makeAdapter(mockDocmindClient());
+
+    await expect(adapter.invoke({
+      runId,
+      organizationId: DEFAULT_ORG_ID,
+      projectId: "proj-cap",
+      workspaceDir: workspaceRoot,
+      inputPath,
+      outputDir: "../../outside",
+      prisma,
+    })).rejects.toBeInstanceOf(CapabilityPathEscape);
+  });
+
+  it("propagates docmind client errors without writing a UsageFact", async () => {
+    await seedActiveCapabilityConnection();
+    const inputPath = await seedInputPdf();
+    const client: CapabilityProviderClient = {
+      parse: vi.fn(async (): Promise<DocmindParseResult> => {
+        throw new DocmindClientError("upstream 502", "docmind_rejected", 502);
+      }),
+    };
+    const adapter = makeAdapter(client);
+
+    await expect(adapter.invoke({
+      runId,
+      organizationId: DEFAULT_ORG_ID,
+      projectId: "proj-cap",
+      workspaceDir: workspaceRoot,
+      inputPath,
+      outputDir: "output",
+      prisma,
+    })).rejects.toThrow(/upstream 502/);
+
+    const facts = await prisma.usageFact.findMany({ where: { runId } });
+    expect(facts).toHaveLength(0);
+  });
+
+  it("rejects empty markdown output as a parse failure", async () => {
+    await seedActiveCapabilityConnection();
+    const inputPath = await seedInputPdf();
+    const client = mockDocmindClient({ markdown: "" });
+    const adapter = makeAdapter(client);
+
+    await expect(adapter.invoke({
+      runId,
+      organizationId: DEFAULT_ORG_ID,
+      projectId: "proj-cap",
+      workspaceDir: workspaceRoot,
+      inputPath,
+      outputDir: "output",
+      prisma,
+    })).rejects.toThrow(/empty markdown/);
+  });
+});
@@ -101,6 +101,43 @@ describe("ADR-0021 project onboarding", () => {
    ]));
  });

+  it("promotes a legacy root Inbox when Feishu chat creates a project", async () => {
+    await seedUser("u-member", "ou_member", "MEMBER");
+    // Production drift after bootstrap omitted kind=SYSTEM_INBOX. The protect
+    // trigger refuses demotion, so the test plants the legacy shape directly.
+    await prisma.$executeRawUnsafe(`ALTER TABLE "Folder" DISABLE TRIGGER cph_protect_system_inbox`);
+    try {
+      await prisma.folder.updateMany({
+        where: { organizationId: DEFAULT_ORG_ID, kind: "SYSTEM_INBOX", archivedAt: null },
+        data: { kind: "REGULAR" },
+      });
+    } finally {
+      await prisma.$executeRawUnsafe(`ALTER TABLE "Folder" ENABLE TRIGGER cph_protect_system_inbox`);
+    }
+    const legacy = await prisma.folder.findFirstOrThrow({
+      where: { organizationId: DEFAULT_ORG_ID, parentId: null, name: "Inbox", archivedAt: null },
+      select: { id: true, kind: true },
+    });
+    expect(legacy.kind).toBe("REGULAR");
+
+    const result = await createProjectFromFeishuChat(prisma, {
+      organizationId: DEFAULT_ORG_ID,
+      actorFeishuOpenId: "ou_member",
+      chatId: "chat-legacy-inbox",
+      name: "Recovered Inbox Project",
+      workspaceRoot: await tempWorkspaceRoot(),
+    });
+
+    expect(result.folderId).toBe(legacy.id);
+    await expect(prisma.folder.findUniqueOrThrow({
+      where: { id: legacy.id },
+      select: { kind: true },
+    })).resolves.toEqual({ kind: "SYSTEM_INBOX" });
+    expect(await prisma.folder.count({
+      where: { organizationId: DEFAULT_ORG_ID, name: "Inbox", archivedAt: null },
+    })).toBe(1);
+  });
+
  it("blocks ordinary Feishu project creation when the org setting is off", async () => {
    await seedUser("u-member", "ou_member", "MEMBER");
    await setMembersCanCreateProjects(prisma, {
@@ -62,6 +62,11 @@ describe("Alpha Silo bootstrap", () => {
      { roleId: "draft", label: "草稿", isDefault: true },
      { roleId: "review", label: "审校", isDefault: false },
    ]);
+    await expect(prisma.folder.findMany({
+      where: { organizationId: "org_alpha", archivedAt: null },
+      select: { name: true, kind: true, parentId: true },
+    })).resolves.toEqual([{ name: "Inbox", kind: "SYSTEM_INBOX", parentId: null }]);
+

    const persisted = JSON.stringify({
      feishu: await prisma.feishuApplicationCredentialVersion.findMany(),
@@ -0,0 +1,221 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { prisma, resetDb, seedTestOrganization, DEFAULT_ORG_ID } from "./helpers.js";
+import { getOrgUsage, getProjectUsage } from "../../src/org/usage.js";
+
+/**
+ * ADR-0026: org/project usage rolls up from the UsageFact ledger, not from the
+ * AgentRun scalar cache. These tests pin the fact-based aggregation contract:
+ *   - a run with a cost-bearing fact → runsWithCost, costUsd summed
+ *   - a run whose facts all have null costUsd → runsWithoutCost (≠ zero)
+ *   - non-token meter (quantity/unit) is stored but does not corrupt token sums
+ *   - multiple facts per run (main loop + external capability) are summed together
+ *   - the AgentRun rollup cache is NOT consulted by getOrgUsage
+ */
+describe("usage rollup from UsageFact (ADR-0026)", () => {
+  beforeEach(async () => {
+    await resetDb();
+    await seedTestOrganization();
+  });
+
+  async function seedRun(opts: {
+    readonly projectId: string;
+    readonly projectName: string;
+    readonly folderId?: string;
+    readonly facts: ReadonlyArray<{
+      readonly kind?: string;
+      readonly provider?: string;
+      readonly model?: string;
+      readonly inputTokens?: number;
+      readonly outputTokens?: number;
+      readonly costUsd?: number | null;
+      readonly costSource?: string;
+      readonly capabilityId?: string;
+      readonly quantity?: number | null;
+      readonly unit?: string | null;
+    }>;
+  }): Promise<void> {
+    const project = await prisma.project.create({
+      data: {
+        id: opts.projectId,
+        organizationId: DEFAULT_ORG_ID,
+        name: opts.projectName,
+        workspaceDir: `/tmp/test-${opts.projectId}`,
+        ...(opts.folderId !== undefined ? { folderId: opts.folderId } : {}),
+      },
+    });
+    const startedAt = new Date("2026-07-18T10:00:00Z");
+    const finishedAt = new Date("2026-07-18T10:05:00Z");
+    const run = await prisma.agentRun.create({
+      data: {
+        projectId: project.id,
+        entrypoint: "FEISHU",
+        provider: "openrouter",
+        model: "mock-model",
+        metadata: {},
+        status: "COMPLETED",
+        prompt: "test",
+        startedAt,
+        finishedAt,
+        // Deliberately set the rollup cache to values that differ from the
+        // facts, to prove getOrgUsage reads facts, not the cache.
+        inputTokens: 999,
+        outputTokens: 999,
+        costUsd: 999,
+        costSource: "provider_reported",
+      },
+    });
+    for (const [i, f] of opts.facts.entries()) {
+      await prisma.usageFact.create({
+        data: {
+          runId: run.id,
+          occurredAt: new Date(startedAt.getTime() + i * 1000),
+          kind: f.kind ?? "model_completion",
+          provider: f.provider ?? "openrouter",
+          model: f.model !== undefined ? f.model : "mock-model",
+          inputTokens: f.inputTokens ?? null,
+          outputTokens: f.outputTokens ?? null,
+          costUsd: f.costUsd ?? null,
+          costSource: f.costSource ?? (f.costUsd !== undefined && f.costUsd !== null ? "provider_reported" : "unknown"),
+          capabilityId: f.capabilityId ?? null,
+          quantity: f.quantity ?? null,
+          unit: f.unit ?? null,
+          metadata: {},
+        },
+      });
+    }
+  }
+
+  it("sums cost and tokens from facts, ignoring the AgentRun rollup cache", async () => {
+    await seedRun({
+      projectId: "proj-a",
+      projectName: "A",
+      facts: [{ inputTokens: 10, outputTokens: 5, costUsd: 0.0023 }],
+    });
+    await seedRun({
+      projectId: "proj-b",
+      projectName: "B",
+      facts: [{ inputTokens: 20, outputTokens: 10, costUsd: 0.01 }],
+    });
+
+    const report = await getOrgUsage(prisma, { organizationId: DEFAULT_ORG_ID });
+
+    expect(report.totals.runCount).toBe(2);
+    expect(report.totals.runsWithCost).toBe(2);
+    expect(report.totals.runsWithoutCost).toBe(0);
+    expect(report.totals.inputTokens).toBe(30);
+    expect(report.totals.outputTokens).toBe(15);
+    expect(report.totals.costUsd).toBeCloseTo(0.0123, 8);
+  });
+
+  it("treats a run with only null-cost facts as runsWithoutCost, never zero", async () => {
+    await seedRun({
+      projectId: "proj-unknown",
+      projectName: "Unknown",
+      facts: [{ inputTokens: 7, outputTokens: 3, costUsd: null, costSource: "unknown" }],
+    });
+    await seedRun({
+      projectId: "proj-known",
+      projectName: "Known",
+      facts: [{ inputTokens: 4, outputTokens: 2, costUsd: 0.05 }],
+    });
+
+    const report = await getOrgUsage(prisma, { organizationId: DEFAULT_ORG_ID });
+
+    expect(report.totals.runCount).toBe(2);
+    expect(report.totals.runsWithCost).toBe(1);
+    expect(report.totals.runsWithoutCost).toBe(1);
+    // The unknown-cost run still contributes its tokens.
+    expect(report.totals.inputTokens).toBe(11);
+    expect(report.totals.outputTokens).toBe(5);
+    // And its cost is NOT counted as zero — only the known cost is summed.
+    expect(report.totals.costUsd).toBeCloseTo(0.05, 8);
+  });
+
+  it("sums multiple facts per run (main loop + external capability)", async () => {
+    await seedRun({
+      projectId: "proj-multi",
+      projectName: "Multi",
+      facts: [
+        { kind: "model_completion", inputTokens: 100, outputTokens: 50, costUsd: 0.02 },
+        {
+          kind: "external_capability",
+          provider: "mineru",
+          model: null,
+          inputTokens: null,
+          outputTokens: null,
+          costUsd: 0.015,
+          costSource: "provider_reported",
+          capabilityId: "pdf_to_md_bundle",
+          quantity: 12,
+          unit: "pages",
+        },
+      ],
+    });
+
+    const report = await getOrgUsage(prisma, { organizationId: DEFAULT_ORG_ID });
+    expect(report.totals.runCount).toBe(1);
+    expect(report.totals.runsWithCost).toBe(1);
+    expect(report.totals.inputTokens).toBe(100);
+    expect(report.totals.outputTokens).toBe(50);
+    expect(report.totals.costUsd).toBeCloseTo(0.035, 8);
+    // ADR-0026 breakdown: model tokens vs external non-token meter must not collapse.
+    expect(report.breakdown).toHaveLength(2);
+    const modelBucket = report.breakdown.find((b) => b.kind === "model_completion");
+    const capBucket = report.breakdown.find((b) => b.kind === "external_capability");
+    expect(modelBucket).toMatchObject({
+      provider: "openrouter",
+      model: "mock-model",
+      capabilityId: null,
+      inputTokens: 100,
+      outputTokens: 50,
+      quantity: null,
+      costUsd: 0.02,
+      factCount: 1,
+    });
+    expect(capBucket).toMatchObject({
+      provider: "mineru",
+      model: null,
+      capabilityId: "pdf_to_md_bundle",
+      unit: "pages",
+      quantity: 12,
+      inputTokens: 0,
+      outputTokens: 0,
+      costUsd: 0.015,
+      factCount: 1,
+    });
+
+  });
+
+  it("a run with no facts at all is runsWithoutCost and contributes nothing", async () => {
+    await seedRun({ projectId: "proj-empty", projectName: "Empty", facts: [] });
+
+    const report = await getOrgUsage(prisma, { organizationId: DEFAULT_ORG_ID });
+    expect(report.totals.runCount).toBe(1);
+    expect(report.totals.runsWithCost).toBe(0);
+    expect(report.totals.runsWithoutCost).toBe(1);
+    expect(report.totals.inputTokens).toBe(0);
+    expect(report.totals.outputTokens).toBe(0);
+    expect(report.totals.costUsd).toBeNull();
+  });
+
+  it("getProjectUsage returns just that project's row", async () => {
+    await seedRun({ projectId: "proj-x", projectName: "X", facts: [{ costUsd: 0.1, inputTokens: 1, outputTokens: 1 }] });
+    await seedRun({ projectId: "proj-y", projectName: "Y", facts: [{ costUsd: 0.2, inputTokens: 2, outputTokens: 2 }] });
+
+    const row = await getProjectUsage(prisma, { organizationId: DEFAULT_ORG_ID, projectId: "proj-x" });
+    expect(row.projectId).toBe("proj-x");
+    expect(row.runCount).toBe(1);
+    expect(row.costUsd).toBeCloseTo(0.1, 8);
+    expect(row.breakdown).toHaveLength(1);
+    expect(row.breakdown[0]).toMatchObject({ kind: "model_completion", costUsd: 0.1, inputTokens: 1 });
+  });
+
+  it("returns an empty report for an org with no projects", async () => {
+    const report = await getOrgUsage(prisma, { organizationId: DEFAULT_ORG_ID });
+    expect(report.projects).toHaveLength(0);
+    expect(report.totals.runCount).toBe(0);
+    expect(report.totals.costUsd).toBeNull();
+    expect(report.breakdown).toEqual([]);
+
+  });
+});
@@ -0,0 +1,163 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { FeishuRuntime } from "../../src/feishu/client.js";
+import {
+  findMarkdownImagesOutsideCode,
+  maskMarkdownImagesForStreaming,
+  materializeAnswerSegments,
+  uploadMessageImage,
+} from "../../src/feishu/outboundImages.js";
+import { buildAgentCard } from "../../src/feishu/card/builder.js";
+
+const temps: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(temps.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+describe("outbound markdown image parsing", () => {
+  it("finds image refs outside fenced code blocks", () => {
+    const text = [
+      "See diagram:",
+      "![plot](https://cdn.example.com/a.png)",
+      "",
+      "```md",
+      "![not-this](https://cdn.example.com/b.png)",
+      "```",
+      "![local](assets/x.png \"title\")",
+    ].join("\n");
+
+    const refs = findMarkdownImagesOutsideCode(text);
+    expect(refs.map((ref) => ref.src)).toEqual([
+      "https://cdn.example.com/a.png",
+      "assets/x.png",
+    ]);
+  });
+
+  it("masks image urls for streaming cards", () => {
+    expect(maskMarkdownImagesForStreaming("before ![alt text](https://x/y.png) after")).toBe(
+      "before alt text after",
+    );
+    expect(maskMarkdownImagesForStreaming("![](https://x/y.png)")).toBe("【图片】");
+  });
+});
+
+describe("materializeAnswerSegments", () => {
+  it("uploads remote and workspace images and builds card segments", async () => {
+    const workspaceRoot = await mkdtemp(join(tmpdir(), "cph-img-root-"));
+    temps.push(workspaceRoot);
+    const workspaceDir = join(workspaceRoot, "project");
+    await mkdir(join(workspaceDir, "assets"), { recursive: true });
+    await writeFile(
+      join(workspaceDir, "assets", "local.png"),
+      Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    );
+
+    const imageCreate = vi
+      .fn()
+      .mockResolvedValueOnce({ image_key: "img_remote_1" })
+      .mockResolvedValueOnce({ image_key: "img_local_1" });
+    const rt = mockRuntime({ imageCreate });
+
+    const fetchImpl = vi.fn(async () =>
+      new Response(Buffer.from("remote-bytes"), {
+        status: 200,
+        headers: { "content-type": "image/png" },
+      }),
+    );
+
+    const text = "Intro\n\n![remote](https://cdn.example.com/r.png)\n\nAnd local ![local](assets/local.png)\nDone.";
+    const { segments, unresolved } = await materializeAnswerSegments(text, {
+      rt,
+      workspaceRoot,
+      workspaceDir,
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+
+    expect(unresolved).toEqual([]);
+    expect(imageCreate).toHaveBeenCalledTimes(2);
+    expect(segments).toEqual([
+      { type: "markdown", content: "Intro\n\n" },
+      { type: "image", imgKey: "img_remote_1", alt: "remote" },
+      { type: "markdown", content: "\n\nAnd local " },
+      { type: "image", imgKey: "img_local_1", alt: "local" },
+      { type: "markdown", content: "\nDone." },
+    ]);
+
+    const card = buildAgentCard({
+      phase: "complete",
+      text: "",
+      contentSegments: segments,
+      reasoningText: undefined,
+      toolUseSteps: [],
+      toolUseElapsedMs: undefined,
+      isError: false,
+      interrupted: false,
+      runId: undefined,
+    });
+    expect(card.elements).toEqual(expect.arrayContaining([
+      expect.objectContaining({ tag: "img", img_key: "img_remote_1" }),
+      expect.objectContaining({ tag: "img", img_key: "img_local_1" }),
+      expect.objectContaining({ tag: "markdown", content: "Intro\n\n" }),
+    ]));
+  });
+
+  it("rejects private remote hosts", async () => {
+    const imageCreate = vi.fn();
+    const rt = mockRuntime({ imageCreate });
+    const fetchImpl = vi.fn();
+    const { segments, unresolved } = await materializeAnswerSegments(
+      "![x](http://127.0.0.1/secret.png)",
+      { rt, fetchImpl: fetchImpl as unknown as typeof fetch },
+    );
+    expect(fetchImpl).not.toHaveBeenCalled();
+    expect(imageCreate).not.toHaveBeenCalled();
+    expect(unresolved).toEqual(["http://127.0.0.1/secret.png"]);
+    expect(segments).toEqual([{ type: "markdown", content: "x" }]);
+  });
+});
+
+describe("uploadMessageImage", () => {
+  it("returns image_key from Feishu upload", async () => {
+    const imageCreate = vi.fn(async () => ({ data: { image_key: "img_nested" } }));
+    const rt = mockRuntime({ imageCreate });
+    await expect(uploadMessageImage(rt, Buffer.from("png"))).resolves.toBe("img_nested");
+    expect(imageCreate).toHaveBeenCalledWith({
+      data: { image_type: "message", image: Buffer.from("png") },
+    });
+  });
+});
+
+function mockRuntime(options: {
+  readonly imageCreate?: (payload: unknown) => Promise<unknown>;
+}): FeishuRuntime {
+  return {
+    client: {
+      im: {
+        v1: {
+          image: {
+            create: options.imageCreate ?? vi.fn(),
+          },
+          message: {
+            create: vi.fn(),
+            reply: vi.fn(),
+            patch: vi.fn(),
+          },
+        },
+      },
+    } as unknown as FeishuRuntime["client"],
+    logger: {
+      warn: vi.fn(),
+      error: vi.fn(),
+      info: vi.fn(),
+      debug: vi.fn(),
+      child: vi.fn(),
+      fatal: vi.fn(),
+      trace: vi.fn(),
+      silent: vi.fn(),
+      level: "info",
+    } as unknown as FeishuRuntime["logger"],
+  };
+}
@@ -290,6 +290,9 @@ function mockPrisma(): PrismaClient {
      findUnique: vi.fn(async () => null),
      update: vi.fn(async () => ({ id: "run-1" })),
    },
+    usageFact: {
+      create: vi.fn(async () => ({ id: "fact-1" })),
+    },
    projectAgentLock: {
      findUnique: vi.fn(async () => (lock === null ? null : { runId: lock.runId })),
      create: vi.fn(async (args: { data: { projectId: string; runId: string } }) => {
@@ -0,0 +1,156 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { ProviderModelCatalog, type ProviderModelEntry } from "../../src/connections/providerModelCatalog.js";
+import { LocalSecretEnvelope } from "../../src/security/secretEnvelope.js";
+const TEST_KEY = Buffer.alloc(32, "k");
+const secrets = new LocalSecretEnvelope({
+  activeKeyId: "test-active",
+  keys: new Map([["test-active", TEST_KEY]]),
+});
+
+function makeEncryptedPayload(baseUrl: string, authToken: string, anthropicApiKey = "") {
+  const payload = { schemaVersion: 1, baseUrl, authToken, anthropicApiKey };
+  return secrets.encryptJson({ purpose: "provider-connection", organizationId: "org-1", connectionId: "conn-1", secretVersionId: "sv-1" }, payload);
+}
+
+function mockPrismaWithConnection(overrides: Partial<{
+  status: string;
+  retiredAt: Date | null;
+  providerId: string;
+}> = {}) {
+  const envelope = makeEncryptedPayload("https://openrouter.ai/api", "sk-test-key", "sk-ant-test");
+  return {
+    organizationProviderConnection: {
+      findFirst: vi.fn().mockResolvedValue({
+        id: "conn-1",
+        organizationId: "org-1",
+        providerId: overrides.providerId ?? "openrouter",
+        status: overrides.status ?? "ACTIVE",
+        activeSecretVersion: {
+          id: "sv-1",
+          connectionId: "conn-1",
+          envelopeVersion: 1,
+          keyId: "test-active",
+          envelope,
+          retiredAt: overrides.retiredAt ?? null,
+        },
+      }),
+    },
+  };
+}
+
+function mockFetchResponse(models: Array<{ id: string; name: string; supported_parameters: string[] }>) {
+  return vi.fn().mockResolvedValue({
+    ok: true,
+    status: 200,
+    json: () => Promise.resolve({ data: models }),
+  });
+}
+
+describe("ProviderModelCatalog", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it("fetches tool-capable models from the provider API", async () => {
+    const prisma = mockPrismaWithConnection();
+    const fetchImpl = mockFetchResponse([
+      { id: "anthropic/claude-sonnet-5", name: "Claude Sonnet 5", supported_parameters: ["tools", "temperature"] },
+      { id: "openai/gpt-4o", name: "GPT-4o", supported_parameters: ["tools", "temperature"] },
+      { id: "meta/llama-3", name: "Llama 3", supported_parameters: ["temperature"] },
+    ]);
+    const catalog = new ProviderModelCatalog(prisma as never, secrets, 60_000, fetchImpl as never);
+
+    const models = await catalog.listModels("org-1");
+
+    expect(models).toHaveLength(3);
+    expect(models.map((m: ProviderModelEntry) => m.id)).toEqual([
+      "anthropic/claude-sonnet-5",
+      "openai/gpt-4o",
+      "meta/llama-3",
+    ]);
+    expect(models[0]).toMatchObject({ label: "Claude Sonnet 5", toolCapable: true });
+    expect(models[2]).toMatchObject({ label: "Llama 3", toolCapable: false });
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    const calledUrl = String(fetchImpl.mock.calls[0][0]);
+    expect(calledUrl).toContain("supported_parameters=tools");
+  });
+
+  it("returns cached results on subsequent calls within TTL", async () => {
+    const prisma = mockPrismaWithConnection();
+    const fetchImpl = mockFetchResponse([
+      { id: "anthropic/claude-sonnet-5", name: "Claude Sonnet 5", supported_parameters: ["tools"] },
+    ]);
+    const catalog = new ProviderModelCatalog(prisma as never, secrets, 60_000, fetchImpl as never);
+
+    await catalog.listModels("org-1");
+    await catalog.listModels("org-1");
+
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-fetches after TTL expires", async () => {
+    const prisma = mockPrismaWithConnection();
+    const fetchImpl = mockFetchResponse([
+      { id: "anthropic/claude-sonnet-5", name: "Claude Sonnet 5", supported_parameters: ["tools"] },
+    ]);
+    const catalog = new ProviderModelCatalog(prisma as never, secrets, 60_000, fetchImpl as never);
+
+    await catalog.listModels("org-1");
+    vi.advanceTimersByTime(61_000);
+    await catalog.listModels("org-1");
+
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+  });
+
+  it("returns empty list when no ACTIVE provider connection exists", async () => {
+    const prisma = {
+      organizationProviderConnection: {
+        findFirst: vi.fn().mockResolvedValue(null),
+      },
+    };
+    const fetchImpl = mockFetchResponse([]);
+    const catalog = new ProviderModelCatalog(prisma as never, secrets, 60_000, fetchImpl as never);
+
+    const models = await catalog.listModels("org-1");
+
+    expect(models).toEqual([]);
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("invalidate forces a re-fetch on next call", async () => {
+    const prisma = mockPrismaWithConnection();
+    const fetchImpl = mockFetchResponse([
+      { id: "anthropic/claude-sonnet-5", name: "Claude Sonnet 5", supported_parameters: ["tools"] },
+    ]);
+    const catalog = new ProviderModelCatalog(prisma as never, secrets, 60_000, fetchImpl as never);
+
+    await catalog.listModels("org-1");
+    catalog.invalidate("org-1");
+    await catalog.listModels("org-1");
+
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+  });
+
+  it("sends auth token and anthropic API key in headers", async () => {
+    const prisma = mockPrismaWithConnection();
+    const fetchImpl = mockFetchResponse([
+      { id: "anthropic/claude-sonnet-5", name: "Claude Sonnet 5", supported_parameters: ["tools"] },
+    ]);
+    const catalog = new ProviderModelCatalog(prisma as never, secrets, 60_000, fetchImpl as never);
+
+    await catalog.listModels("org-1");
+
+    const init = fetchImpl.mock.calls[0][1] as RequestInit;
+    const headers = init.headers as Record<string, string>;
+    expect(headers.authorization).toBe("Bearer sk-test-key");
+    expect(headers["x-api-key"]).toBe("sk-ant-test");
+  });
+
+  it("throws on non-200 response", async () => {
+    const prisma = mockPrismaWithConnection();
+    const fetchImpl = vi.fn().mockResolvedValue({ ok: false, status: 401 });
+    const catalog = new ProviderModelCatalog(prisma as never, secrets, 60_000, fetchImpl as never);
+
+    await expect(catalog.listModels("org-1")).rejects.toThrow("provider models request failed: status 401");
+  });
+});
@@ -68,14 +68,14 @@ describe("session cookie signing", () => {
 describe("oauth state signing", () => {
  it("round-trips state with returnTo", () => {
    const token = signOAuthState(
-      { nonce: "abc", returnTo: "/admin/org/acme" },
+      { nonce: "abc", returnTo: "/admin" },
      SECRET,
      600,
      1_700_000_000,
    );
    expect(verifyOAuthState(token, SECRET, 1_700_000_100)).toEqual({
      nonce: "abc",
-      returnTo: "/admin/org/acme",
+      returnTo: "/admin",
      exp: 1_700_000_600,
    });
  });
@@ -83,13 +83,13 @@ describe("oauth state signing", () => {
  it("binds state to an Organization and connection as one inseparable scope", () => {
    const token = signOAuthState({
      nonce: "scoped",
-      returnTo: "/admin/org/acme",
+      returnTo: "/admin",
      organizationId: "org-acme",
      connectionId: "connection-acme",
    }, SECRET, 600, 1_700_000_000);
    expect(verifyOAuthState(token, SECRET, 1_700_000_100)).toEqual({
      nonce: "scoped",
-      returnTo: "/admin/org/acme",
+      returnTo: "/admin",
      organizationId: "org-acme",
      connectionId: "connection-acme",
      exp: 1_700_000_600,
@@ -98,8 +98,11 @@ describe("oauth state signing", () => {
 });

 describe("sanitizeReturnTo", () => {
-  it("allows admin paths", () => {
-    expect(sanitizeReturnTo("/admin/org/acme")).toBe("/admin/org/acme");
+  it("allows admin paths and rewrites legacy org slug prefixes", () => {
+    expect(sanitizeReturnTo("/admin")).toBe("/admin");
+    expect(sanitizeReturnTo("/admin/usage")).toBe("/admin/usage");
+    expect(sanitizeReturnTo("/admin/org/acme")).toBe("/admin");
+    expect(sanitizeReturnTo("/admin/org/acme/usage")).toBe("/admin/usage");
  });

  it("blocks open redirects", () => {
@@ -23,6 +23,7 @@ describe("isSiloHttpRateLimitExempt", () => {
    expect(isSiloHttpRateLimitExempt("/favicon.svg")).toBe(true);
    expect(isSiloHttpRateLimitExempt("/robots.txt")).toBe(true);
    expect(isSiloHttpRateLimitExempt("/admin")).toBe(true);
+    expect(isSiloHttpRateLimitExempt("/admin/members")).toBe(true);
    expect(isSiloHttpRateLimitExempt("/admin/org/para-26071100/members")).toBe(true);
  });

@@ -1 +0,0 @@
-/.lake
@@ -1,55 +0,0 @@
-# spec —— Lean 语义母本
-
-这是本 monorepo 的**契约**:产品各部件语义的上游参照,用 Lean 编写。它的定位与约束见仓库根 `README.md` 的"宪法"5 条——本文件只讲**怎么往这份契约里写东西**。
-
-## 现状
-
-刚初始化的 Lean 工程(`lake init`),目前只有占位内容(`Spec/Basic.lean`)。实质领域内容(System 平台层、Courseware 产品层)将逐个概念加入,每个都遵循下面的规范。
-
-## 构建
-
-```sh
-cd spec
-lake build
-```
-
-工具链锁定在 `lean-toolchain`(`leanprover/lean4:v4.31.0`)。无外部依赖——Mathlib / Batteries 等留待第一个真正需要它的定理出现时再引入(依赖碰到再加)。
-
-## 写作规范
-
-### 双半契约:prose + type
-
-每个 top-level 声明**必须**带 `/-- … -/` doc 注释,用自然语言陈述其语义意图。两半缺一不可:
-
- **prose 半**给人读——说清"这在领域里是什么、为什么"。
- **type 半**给机器读、给 type checker 把关——保证结构无洞。
-
-agent 不得用预训练先验脑补本领域(领域很新,无先验);prose 是 agent 理解语义的唯一权威来源。
-
-### 标签分类法
-
-在 doc 注释里用以下标签标注每条语义的状态:
-
- **`PINNED`** —— 已解决的分歧点,契约在此处权威,双方据此对齐。
- **`OPEN`** —— 故意未规定。双方均**不得假设**其解;实现遇到时必须 surface 出来讨论,而不是擅自决定。
- **`ADR-NNNN`** —— 链接到根 `docs/adr/` 下的对应决策记录(如 `ADR-0002`),交代该语义的决策出处。
-
-### 分歧点测试(写之前先过一遍)
-
-新增任何概念前,先问:**"不写明,开发者与 agent 会不会各自做出不同假设?"**
-
- 会 → 它是分歧点,入契约。
- 不会(显然的东西 / 纯 plumbing / 普通 CRUD 字段)→ 不入。
-
-详见根 README 宪法第 5 条。
-
-### 不用 `sorry`
-
-无法陈述清楚的东西,用 `OPEN` 在 prose 里标注,而**不是**用 `sorry` 留一个假装成立的定理。`sorry` 会让 `lake build` 仍然变绿,却在契约里埋一个谎——这与"契约自包含、无洞"直接冲突。
-
-### 命名
-
- **模块 / 命名空间**:PascalCase,对应分层,如 `Spec.System.Agent.Run`、`Spec.Courseware.Validity`。
- **类型**:PascalCase。
- **谓词 / `Prop`**:用意图清晰的命名,如 `Legal…`、`ValidTransition`、`Can…`。
- **文件粒度**:原则上"一个带独立不变式的概念一个文件"。
@@ -1,5 +0,0 @@
-- This module serves as the root of the `Spec` library.
-- Import modules here that should be built as part of the library.
-import Spec.Prelude
-import Spec.System
-import Spec.Courseware
@@ -1,21 +0,0 @@
-import Spec.Courseware.Model
-import Spec.Courseware.Export
-import Spec.Courseware.Check
-import Spec.Courseware.Open
-
-/-!
-# Courseware —— 产品层契约(课程工程文件)
-
-护城河:课程"工程文件"的语义母本与合法性规则。决策出处 ADR-0005..0016。按四组组织:
-
- **`Model`** —— 工程文件的内容模型:基元 `Primitives`、富内容 `RichContent`、原子
-  单位 `Element`、单节课 `Lesson`(element 的有序序列)。
- **`Export`** —— export target = artifact + 有序 typed steps:产物 ADT `Artifact`
-  (`singleFile` / `fileTree`),build 规格 `TargetSpec`(artifact + steps + 覆盖声明
-  `covers`)与 `RenderConfig`。
- **`Check`** —— checker 语义:`Severity` + 6 类诊断 + **合法 lesson = 无 error 级
-  诊断**(模型外设施诊断以抽象谓词 + `Oracle` 表示);检查管线的 5 阶段、序、compile
-  门控。
- **`Open`** —— OPEN 骨架(核心关系 OPEN,已 surface):题库 `QuestionBank`、
-  课程编排 `Course`。
-/
@@ -1,9 +0,0 @@
-import Spec.Courseware.Check.Diagnostic
-import Spec.Courseware.Check.Pipeline
-
-/-!
-# Courseware.Check —— checker 语义
-
-诊断分类与合法 lesson(`Diagnostic`)、检查管线的阶段与序(`Pipeline`)。决策出处
-ADR-0010。
-/
@@ -1,107 +0,0 @@
-import Spec.Courseware.Model.Lesson
-import Spec.Courseware.Export.Render
-
-/-!
-# Diagnostic —— checker 诊断:分类、严重级别、合法 lesson
-
-产品里"站在 Lean 位置"的 rule-based checker,语义在此沉淀(ADR-0010,经 ADR-0012
-修订)。它对 lesson 提诊断,每条有**分类**(`DiagKind`)与**严重级别**(`Severity`)。
-定级别类型(二分);定 7 类诊断各自的含义与级别,并把"**合法 lesson = 无
-error 级诊断**"建成判定(ADR-0005 deferred 的"完整合法判定"的回填);对**模型外设施**
-型诊断(typst 编过否、数据合 schema 否)用**抽象谓词 + `Oracle` 实现边界**表示——契约
-说"存在这条诊断、什么意思、什么级别",真值由实现提供,不在 Lean 内计算(不内嵌 typst
-编译器)。引用解析(`@ref`、相对 import)不另设诊断:它们都是 typst 编译期失败,归
-`typstCompile`(ADR-0012)。版本契约诊断 `cphVersionMismatch`(ADR-0016)是第 7 类。
-/
-
-namespace Spec.Courseware
-
-/-- 诊断严重级别(`PINNED` 二分, ADR-0005)。`error` 阻断(产物不合法),`warning` 不
-阻断(产物仍可导出,只是有损)。更细级别(info/hint)未决策,故只二分。 -/
-inductive Severity where
-  | warning
-  | error
-
-/-- 诊断**分类**(`PINNED` 7 类, ADR-0010,经 ADR-0012 修订为 6 类,经 ADR-0016 增至 7
-类)。按"谁来判定"分三层:**结构型**(模型自身可判):`partPathMissing`/`unknownKind`/
-`cphVersionMismatch`;**schema/外部设施型**(靠实现 oracle):
-`missingContentFile`/`schemaViolation`/`typstCompile`;**语义型**:`renderIgnored`。 -/
-inductive DiagKind where
-  /-- manifest 的 part 指向不存在的文件夹(或经 `..` 逃出根)。结构型。 -/
-  | partPathMissing
-  /-- part 声明了未知 kind(含 part 与 element.toml 的 kind 不一致)。结构型。 -/
-  | unknownKind
-  /-- kind schema 要求的某 `content` 字段缺对应 `<field>.typ`。结构/schema 型。 -/
-  | missingContentFile
-  /-- 实例数据不合其 kind 的 JSON Schema;亦作 manifest/element.toml 畸形的兜底。 -/
-  | schemaViolation
-  /-- 拼装出的 typst 源编译失败:语法错、未解析的交叉引用 `@ref`、越界或缺失的相对
-      `import`/`include`(后两者即旧 `danglingReference` 的两种情形——typst 在编译期
-      检出,故归此类,ADR-0012)。外部设施型。 -/
-  | typstCompile
-  /-- 某被用到的 kind 在某声明的 target 下无渲染规则,该 element 被忽略。语义型。 -/
-  | renderIgnored
-  /-- 工程文件的 `.cph-version` 与 CLI(cph)版本不相容(ADR-0016)。**结构型**(加载期
-      判)。工程文件根的 `.cph-version` 声明它所面向的 cph 版本;CLI 加载时按**兼容性判
-      定**比对自身版本(实现侧 `CARGO_PKG_VERSION`),不相容即产此类。**当前判定为版本
-      完全相等才相容**(MVP;后续可放宽为 semver 区间,判定逻辑可逐步修改而不动本分类)。
-      `error` 级——版本不相容的工程文件不应被该 CLI 处理。 -/
-  | cphVersionMismatch
-
-/-- 每类诊断的**严重级别**(`PINNED`, ADR-0010)。六类 `error`(阻断);**唯
-`renderIgnored` 为 `warning`**——ADR-0005 种子规则"缺渲染 ⇒ warning,不阻断导出"。
-全函数使"哪类阻断"成为可引用、可对齐的事实(实现侧 `DiagCode` 级别据此对齐)。 -/
-def DiagKind.severity : DiagKind → Severity
-  | .partPathMissing    => .error
-  | .unknownKind        => .error
-  | .missingContentFile => .error
-  | .schemaViolation    => .error
-  | .typstCompile       => .error
-  | .renderIgnored      => .warning
-  | .cphVersionMismatch => .error
-
-/-- 缺渲染诊断的级别 = **warning**(`PINNED`, ADR-0005/0010,**非 error**)。具名常量,
-使"它是 warning"可被实现侧 grep 对齐(实现里同名常量 `RENDER_IGNORED_SEVERITY` 引用
-本定义)。等价于 `DiagKind.renderIgnored.severity`。 -/
-def renderIgnoredSeverity : Severity := DiagKind.renderIgnored.severity
-
-variable (P : Primitives)
-
-/-- **缺渲染诊断**:lesson 在 target `t` 下存在无法渲染的 element(`PINNED`,
-ADR-0005/0009)。成立 ⟺ 存在某 element,其 kind 在 `t` 下 `covers` 为假。语义型诊断,
-级别 warning。 -/
-def renderIgnored (l : Lesson P) (c : RenderConfig P) (t : P.TargetId) : Prop :=
-  ∃ e ∈ l, ¬ c.covers e.kind t
-
-/-!
-## 模型外设施型诊断:抽象谓词 + 实现边界(ADR-0010)
-
-`typstCompile`/`schemaViolation`(的 schema-合规面)断言的是模型自身无法判定的事实——
-要跑 typst 编译器、schema 校验器。契约把它们建成**抽象谓词**,真值由实现提供的 oracle
-给出。下面用 `Oracle` 收口这些判定:它不是要在 Lean 里实现 checker,而是把"这些事实
-来自模型外"显式化、类型化。
-/
-
-/-- **实现侧判定 oracle**(`PINNED` 实现边界, ADR-0010)。每个字段是一个谓词,真值由
-实现(checker)提供。结构型诊断(part 路径、未知 kind)不入此 oracle——那些模型自身可判。 -/
-structure Oracle (l : Lesson P) (c : RenderConfig P) where
-  /-- target `t` 下拼装源可编译(否 ⇒ `typstCompile`)。**含引用解析**:源能编译即蕴含
-      其 `@ref`、相对 import 全部解析(ADR-0012 已把引用诊断并入 `typstCompile`)。 -/
-  compiles : P.TargetId → Prop
-  /-- 每个 element 数据合 schema(否 ⇒ `schemaViolation`)。 -/
-  dataConforms : Prop
-  /-- schema 要求的 content 文件齐备(否 ⇒ `missingContentFile`)。 -/
-  contentFilesPresent : Prop
-
-/-- **合法 lesson**(`PINNED`, ADR-0010;回填 ADR-0005 deferred 的"完整合法判定")。
-
-合法 ⟺ 检查管线产出**零条 error 级诊断**。展开为:模型外设施判定(经 `Oracle`)全为真,
-**且**每个声明的 target 都编译通过。结构型诊断由 `cph-model` 在加载期判定;能走到这步
-谈合法性意味着已加载成功,故此处聚焦 schema/外部设施层。引用解析不单列——已被
-`compiles` 蕴含(ADR-0012)。`renderIgnored` 是 warning,**不**进合取——ADR-0005 种子
-规则的体现。`targets` 用全称式表达以不绑定 `TargetId` 的可枚举性。 -/
-def Legal (l : Lesson P) (c : RenderConfig P) (o : Oracle P l c) : Prop :=
-  o.dataConforms ∧ o.contentFilesPresent ∧
-    (∀ t : P.TargetId, (c.spec t).isSome → o.compiles t)
-
-end Spec.Courseware
@@ -1,54 +0,0 @@
-import Spec.Courseware.Check.Diagnostic
-
-/-!
-# Pipeline —— checker 检查管线的阶段与序(ADR-0010)
-
-checker 的 `check` 按**固定顺序**跑五个阶段,逐阶段收集诊断;`compile` 阶段有**门控**。
-顺序与门控是契约——它决定用户看到哪些诊断(藏在缺文件背后的语法错,在文件补齐前不
-显示,这是有意的)。每阶段的**算法**不进 Lean(深度上限:只定**阶段、序、
-门控**)。阶段对应上游模块:`load`←`cph-model`;`structural`←part 路径/未知 kind;
-`schema`←`cph-schema`;`compile`←`cph-typst`(模型外设施);`coverage`←`renderIgnored`。
-/
-
-namespace Spec.Courseware
-
-/-- 检查管线的**阶段**(`PINNED` 5 阶段, ADR-0010)。
-
- `load` —— 解析 manifest + 各 element.toml。**含 `.cph-version` 兼容性判定**
-  (ADR-0016:工程根 `.cph-version` 与 CLI 版本不相容 ⇒ `cphVersionMismatch` error)。
-  硬失败(无法解析 lesson)则**停**整条管线。
- `structural` —— part 路径存在、无 `..`、kind 已知且一致。此处判缺的 part 后续跳过。
- `schema` —— 每个"存在且 kind 已知"的 part 按其 kind schema 校验。
- `compile` —— 模型外设施阶段(typst 编译)。**门控:仅当前序零 error 才跑**。
- `coverage` —— 语义型 warning(`renderIgnored`);**不**受门控,总跑。 -/
-inductive Phase where
-  | load
-  | structural
-  | schema
-  | compile
-  | coverage
-deriving DecidableEq
-
-/-- 管线阶段的**执行序**(`PINNED`, ADR-0010)。`order p` 越小越先跑。序是契约:
-`compile`(3)排在 `structural`(1)/`schema`(2)之后,正因前者门控于后者无 error。 -/
-def Phase.order : Phase → Nat
-  | .load       => 0
-  | .structural => 1
-  | .schema     => 2
-  | .compile    => 3
-  | .coverage   => 4
-
-/-- 某阶段是否**受"前序零 error"门控**(`PINNED`, ADR-0010)。唯 `compile` 受门控:藏在
-结构/schema 错背后的编译错,在前者修好前不显示——有意降噪。 -/
-def Phase.gated : Phase → Bool
-  | .compile => true
-  | _        => false
-
-/-- 管线在 `load` 硬失败时**停**(`PINNED`, ADR-0010)。`load` 拿不到可解析 lesson 时,
-无 lesson 可喂下游,整条管线终止——唯一会截断后续所有阶段的情形(区别于 `compile`
-门控只跳过自己)。 -/
-def Phase.haltsPipelineOnFailure : Phase → Bool
-  | .load => true
-  | _     => false
-
-end Spec.Courseware
@@ -1,8 +0,0 @@
-import Spec.Courseware.Export.Artifact
-import Spec.Courseware.Export.Render
-
-/-!
-# Courseware.Export —— export target = artifact + 有序 typed steps
-
-产物 ADT(`Artifact`)、build 规格与渲染覆盖(`Render`)。决策出处 ADR-0009 / 0011。
-/
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
hongjr03	73cb0e5b47	feat(hub): embed agent images via Feishu upload + release v0.0.36 (#14 ) feat(hub): embed agent images via Feishu upload + release v0.0.36 Merge pull request #14	2026-07-20 18:42:38 +08:00
hongjr03	e21096c642	feat(hub): embed agent images via Feishu upload + release v0.0.36 Materialize markdown image refs on agent finish: fetch/read bytes, upload im.v1.image, and render native card img elements so remote image URLs no longer trip Feishu content-security. Stream masks image URLs mid-run; card failure falls back to plain text plus standalone image messages. Docs: clarify im:resource covers outbound Agent image send.	2026-07-20 10:40:03 +00:00
hongjr03	dc2d1c2f9e	Merge pull request 'chore: remove Lean spec; ADRs are the single source of truth' (#13 ) from chore/remove-lean-spec into main Reviewed-on: EduCraft/curriculum-project-hub#13	2026-07-20 17:21:14 +08:00
hongjr03	3f9b60f692	chore: remove Lean spec; ADRs are the single source of truth The spec/ Lean semantic master had no conformance gate, no codegen, and no CI tie to implementations — alignment was carried entirely by human review, the same mechanism that carries the ADRs. In practice the ADRs plus greppable code comments were already the load-bearing artifacts, so spec/ was the most expensive kind of stale documentation. - delete spec/ and the spec-check CI workflow - README: constitution rewritten around ADRs as decision truth - AGENTS.md/CLAUDE.md: discipline re-anchored (new decisions -> new ADR, never rewrite ADR history; supersede instead) - code comments: re-anchor 'Mirrors Spec.X' invariants to ADR numbers (cph-diag, cph-check, cph-model, hub runner/capacity/org, prisma) - leave ADR bodies and .scratch audit snapshots untouched (history); fix live references in open readiness tickets	2026-07-20 09:07:26 +00:00
hongjr03	4234ba4c96	Merge pull request 'fix(hub): mark bootstrap Inbox as SYSTEM_INBOX' (#12 ) from fix/hub-bootstrap-system-inbox into main	2026-07-19 20:16:09 +08:00
hongjr03	15f9443d3d	fix(hub): mark bootstrap Inbox as SYSTEM_INBOX Alpha silo bootstrap created the root Inbox without kind=SYSTEM_INBOX, so Feishu card project creation tried to insert a second Inbox and hit the sibling-name unique index. Tag the bootstrap folder correctly and promote any legacy root Inbox on ensure.	2026-07-19 20:08:44 +08:00
hongjr03	7f09fb1f13	feat(hub): drop redundant /admin/org/:slug path + release v0.0.35 (#11 ) Silo hostname already carries tenancy. Admin SPA routes become /admin/..., legacy bookmarks redirect, login lands on /admin. Co-authored-by: Hong Jiarong <me@jrhim.com> Co-committed-by: Hong Jiarong <me@jrhim.com>	2026-07-19 01:36:10 +08:00
hongjr03	eb0be43eac	feat(hub): usage fact breakdown API + admin usage/session UI + release v0.0.34 (#10 ) Expose UsageFact kind/capability rollups on org and project usage reports, and add admin pages that separate model tokens from external-capability meters. Co-authored-by: Hong Jiarong <me@jrhim.com> Co-committed-by: Hong Jiarong <me@jrhim.com>	2026-07-19 01:19:59 +08:00
hongjr03	ce18740870	feat(hub): expose pdf_to_md_bundle as MCP tool to agent + skill (ADR-0027) (#9 ) Co-authored-by: Hong Jiarong <me@jrhim.com> Co-committed-by: Hong Jiarong <me@jrhim.com>	2026-07-18 21:43:00 +08:00
hongjr03	ef96f8d33d	feat(hub): capability connection admin API + UI + release v0.0.32 (#8 ) Co-authored-by: Hong Jiarong <me@jrhim.com> Co-committed-by: Hong Jiarong <me@jrhim.com>	2026-07-18 17:57:04 +08:00
hongjr03	5e10419fc8	fix(hub): docmind client stream upload + correct API response parsing (#7 ) Co-authored-by: Hong Jiarong <me@jrhim.com> Co-committed-by: Hong Jiarong <me@jrhim.com>	2026-07-18 17:26:11 +08:00
hongjr03	64b3d1fc64	feat(hub): switch capability provider to Aliyun Doc Mind (ADR-0027) (#6 ) Co-authored-by: Hong Jiarong <me@jrhim.com> Co-committed-by: Hong Jiarong <me@jrhim.com>	2026-07-18 16:42:42 +08:00
hongjr03	b673dd1fe9	feat(hub): external capability registry for PDF/ASR transforms (ADR-0027) (#5 ) Co-authored-by: Hong Jiarong <me@jrhim.com> Co-committed-by: Hong Jiarong <me@jrhim.com>	2026-07-18 15:55:02 +08:00
hongjr03	aaa098bb8b	feat(hub): usage fact ledger for run-scoped cost attribution (ADR-0026) (#4 ) Co-authored-by: Hong Jiarong <me@jrhim.com> Co-committed-by: Hong Jiarong <me@jrhim.com>	2026-07-18 14:46:41 +08:00
hongjr03	97f7972cc5	chore(hub): remove markdown_to_pdf tool (#3 ) Drop markdown_to_pdf MCP surface, implementation, tests, and md-to-pdf dependency. Roles that still list markdown_to_pdf must be cleaned before startup. Co-authored-by: Hong Jiarong <me@jrhim.com> Co-committed-by: Hong Jiarong <me@jrhim.com>	2026-07-18 13:57:27 +08:00
hongjr03	cc42e6a7c6	chore: release v0.0.31	2026-07-18 13:38:07 +08:00
hongjr03	4e01c18cac	feat(hub): add markdown_to_pdf tool and default web tools Teachers need ad-hoc Markdown → PDF. Ship an MCP tool powered by md-to-pdf (Marked + headless Chrome) so remote images/CSS work, with workspace-scoped basedir, front-matter stripped so untrusted markdown cannot override dest/basedir/launch options, and MathJax for $/$ math. Also include WebFetch and WebSearch in the unrestricted role tool surface by default. Deploy skips Puppeteer's browser download and expects a host Chrome/Chromium (PUPPETEER_EXECUTABLE_PATH / CHROME_PATH).	2026-07-18 13:38:07 +08:00
ChickenPige0n	a12984d174	feat(admin-web): add folder and project creation functionality in FolderNode and FolderTree components	2026-07-18 12:32:45 +08:00
hongjr03	b93acd8e8c	chore: release v0.0.30	2026-07-16 01:26:28 +08:00
hongjr03	35251986af	feat(hub): derive admin model picker from org provider connection via OpenRouter API The admin role model picker was hardcoded to the env-default model registry (createDefaultModelRegistry), which only ever returned a single Sonnet model. Roles could not select any other model regardless of what the org's provider connection supported. Replace the env-only model list with a ProviderModelCatalog that: - Resolves the org's ACTIVE provider connection credential (BYOK or platform-managed, encrypted via ADR-0024 envelope) - Calls OpenRouter GET /v1/models?supported_parameters=tools to list tool-capable models available to that org - Caches results in-memory with a 5-minute TTL per organization - Falls back to the env-default registry when no ACTIVE provider exists The runtime modelRegistry no longer validates role.defaultModel against the env model list — the admin already validated by selection from the provider catalog. The env list remains as the fallback for roles with null defaultModel. The admin roles page loads models independently (non-blocking) so roles remain editable even if the provider API is slow or unreachable.	2026-07-16 01:24:00 +08:00